Shared types

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.

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.

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.

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.

​Content blocks

​Messages

​Tool definitions

​Events

​Errors

​Memory primitives

​Channel state

​Asset Directory

​Rules

​See also