> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared types

> The contract types that cross module boundaries inside the Engine.

When two modules need to talk, they talk through a typed contract. This
page lists the contract types that matter — the ones that, if changed,
ripple across the codebase. The authoritative source for these types is
the engine repo itself; this page summarizes the shape and links to the
canonical locations.

If you're about to add a new public surface that crosses a module
boundary, define the type **here first**, then implement against it. The
project's CLAUDE.md mandates this — types in a central place, modules
import from there.

## Content blocks

The fundamental unit of LLM communication. A message is a list of
content blocks; a model response is a list of content blocks.

**Source:** `src/herald/engine_contracts/__init__.py` (re-exports from
`src/herald/types.py`).

| Type              | Purpose                                             |
| ----------------- | --------------------------------------------------- |
| `TextBlock`       | Plain text. Streamed as `text_delta`.               |
| `ThinkingBlock`   | Internal reasoning. Streamed as `thinking_delta`.   |
| `ToolUseBlock`    | A tool call request from the model.                 |
| `ToolResultBlock` | The result fed back into context after a tool call. |
| `ImageBlock`      | An image input or output.                           |

```python theme={null}
class TextBlock:
    type: Literal["text"]
    text: str

class ToolUseBlock:
    type: Literal["tool_use"]
    id: str
    name: str
    input: dict
```

## Messages

A turn or part of a turn.

| Type          | Purpose                                                            |
| ------------- | ------------------------------------------------------------------ |
| `Message`     | One conversation message. Has a role and a list of content blocks. |
| `LLMResponse` | The non-streaming response shape from herald.                      |
| `StreamEvent` | One chunk in a streaming response from herald.                     |

## Tool definitions

How a tool is declared and how a call is invoked.

**Source:** `src/utility_directory/`, `src/herald/engine_contracts/`.

| Type       | Purpose                                             |
| ---------- | --------------------------------------------------- |
| `ToolDef`  | A tool's metadata: name, description, input schema. |
| `ToolCall` | An invocation of a tool: name, input, optional id.  |
| `Utility`  | The wrapper around a tool's executable behavior.    |

`ToolDef` is the schema the model sees in its system prompt. `ToolCall`
is what the model issues. `Utility` is what the Engine actually invokes.

## Events

The vocabulary of the SSE stream and the in-process event bus.

**Source:** `src/engine_core/events.py`.

There are 32+ event types. The major families:

* **Lifecycle** — `ThreadLifecycle`, `TaskLifecycle`.
* **Content** — `TextDelta`, `ThinkingDelta`, `ContentBlockStart`,
  `ContentBlockStop`.
* **Tools** — `ToolCall`, `ToolResult`, `ToolError`.
* **HITL** — `HitlRequest`, `HitlResolved`, `PermissionPrompt`.
* **Memory** — `WorkingMemoryUpdate`, `MemoryRetrieval`.
* **Compaction** — `CompactionEvent`.
* **Diagnostics** — `Heartbeat`, `Usage`, `Error`, `CacheHitRatioAlert`.

Every event has a `timestamp`, a `task_id`, and a `type`. Concrete
fields vary by type.

## Errors

Stable error codes used across the Engine.

**Source:** `src/errors.py`.

```python theme={null}
class ErrorCode(str, Enum):
    INVALID_KEY = "INVALID_KEY"
    KEY_ROTATION_PENDING = "KEY_ROTATION_PENDING"
    TASK_NOT_FOUND = "TASK_NOT_FOUND"
    HITL_REQUIRED = "HITL_REQUIRED"
    LLM_PROVIDER_ERROR = "LLM_PROVIDER_ERROR"
    LLM_RATE_LIMITED = "LLM_RATE_LIMITED"
    CONTEXT_OVERFLOW = "CONTEXT_OVERFLOW"
    PERMISSION_DENIED = "PERMISSION_DENIED"
    MCP_CONNECTION_FAILED = "MCP_CONNECTION_FAILED"
    MCP_TOKEN_EXPIRED = "MCP_TOKEN_EXPIRED"
    MIGRATION_REQUIRED = "MIGRATION_REQUIRED"
    # …

class EngineError(Exception):
    code: ErrorCode
    message: str
    details: dict | None
```

The error codes are part of the public API. **Don't rename them.**
Add new ones; don't reshuffle existing ones.

## Memory primitives

The records persisted in the brain.

**Source:** `src/memory/`.

| Type                       | Where                             | Purpose                                                                   |
| -------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
| `Episode`                  | `episodic_memory.py`              | An event with a description, value, tier, and embedding.                  |
| `KnowledgeFact`            | `knowledge_store.py`              | A typed assertion (fact / rule / heuristic) with confidence and validity. |
| `SocialNode`, `SocialEdge` | `social_graph.py`                 | People and their relationships.                                           |
| `LogEntry`, `EntryType`    | `working_memory.py`               | A single working-memory entry.                                            |
| `Soul`                     | `soul.py` (or via `MemorySystem`) | The user's core identity.                                                 |

## Channel state

Execution checkpoint.

**Source:** `src/engine_core/channel_state.py`.

```python theme={null}
class ChannelStateSnapshot:
    task_id: str
    snapshot_json: dict   # serialized loop state
    expires_at: datetime
```

## Asset Directory

MCP connection and registry types.

**Source:** `src/asset_directory/states.py`, `src/asset_directory/__init__.py`.

| Type                  | Purpose                                                            |
| --------------------- | ------------------------------------------------------------------ |
| `ServerConfigPayload` | Public-facing server registry entry.                               |
| `Connection`          | An active connection to an MCP server with credentials.            |
| `ConnectionStatus`    | `connected`, `pending_oauth`, `expired`, `failed`, `disconnected`. |
| `ActionDef`           | An MCP action's metadata and input schema.                         |

## Rules

* **Never inline a contract type.** If a type crosses a module boundary,
  it lives where the producing module exports it (or in a shared
  `engine_contracts` module).
* **Never break a public contract silently.** Renaming or reshaping
  `ToolUseBlock`, `ErrorCode`, or any event field is a breaking change
  and needs a migration guide.
* **Document new contract types deliberately.** If you're inventing a
  new kind of block or a new error code, write down why and where it's
  used so the next reader doesn't have to reverse-engineer the
  decision.

## See also

* [Components](./components) — which module owns which types.
* [Data flow](./data-flow) — how the types move through the system.