reference data models

Data models

The core data shapes that Prime Agent persists and streams: the session transcript format, the web wire contract, the agent message union, the model registry, and the daemon protocol version constants.

Session JSONL transcript

Sessions persist as newline-delimited JSON files at ~/.prime/agent/sessions/<session-id>.jsonl. Each line is a JSON object with a type field. The format is documented in packages/coding-agent/docs/session-format.md and implemented by packages/coding-agent/src/core/session-manager.ts.

The first line is a SessionHeader with metadata only (no id/parentId):

{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}

Forked sessions add a parentSession field pointing at the source file. The version field is 3 today: version 1 was a linear sequence, version 2 introduced the id/parentId tree, and version 3 renamed the hookMessage role to custom. Existing sessions auto-migrate on load.

All entries except the header extend SessionEntryBase:

interface SessionEntryBase {
  type: string;
  id: string;           // 8-char hex ID
  parentId: string | null;  // parent entry, null for the first entry
  timestamp: string;    // ISO timestamp
}

Entry kinds include:

• message, a conversation message wrapping an AgentMessage (user, assistant, or tool result).
• model_change, thinking_level_change, service_tier_change, mid-session switches.
• compaction, stores a summary of earlier messages, with firstKeptEntryId and tokensBefore.
• branch_summary, LLM-generated summary of the abandoned path when switching branches.
• custom, extension state persistence; not included in LLM context.
• custom_message, extension-injected messages that do enter LLM context.
• label, user bookmark on an entry.
• session_info, session metadata such as a display name.
• session_state, daemon-managed lifecycle state (active, archived, legacy crash).
• agent_status, the latest short agent status for the agents view.
• git_state, append-only repository state snapshots.
• child_usage_attributed, daemon bookkeeping folding RLM child usage into a parent assistant message.

Entries form a tree via id/parentId; buildSessionContext() walks from the leaf to the root to produce the LLM message list, emitting compaction summaries first and skipping bookkeeping entries.

ChatStreamEvent

The web wire contract lives in web/protocol/src/chat-protocol.ts (ChatStreamEvent) with zod schemas in web/protocol/src/chat-protocol.zod.ts. A chat turn (POST /api/chat) emits an NDJSON frame stream. Each frame is a discriminated union on type:

• start, begins a turn (id, runId, sessionId, optional sessionFile/sessionReset/diagnostics).
• delta, streamed assistant text.
• tool, a tool call part.
• thinking, reasoning text.
• plan, plan-mode progress (mode, executing, completed, total, todos).
• state, lifecycle events (agent_start, agent_end, agent_settled, turn_start, turn_end, message_start, message_end).
• queue, steering and follow-up queue contents.
• compaction, start/end phases with reason and retry info.
• retry, retry lifecycle (start/end, attempt, delay).
• done, turn completion with the final ChatMessage.
• error, turn failure.

ChatPiSettings

ChatPiSettings (web/protocol/src/chat-protocol.ts) is the browser-facing projection of the settings manager. It mirrors the subset of packages/coding-agent/src/core/settings-manager.ts settings the web UI needs: compaction budgets, default model/provider/thinking level, skill and resource lists (packages, extensions, skills, prompts, themes), retry policy, delivery modes (steeringMode, followUpMode), and transport. ChatSettingsUpdateRequest/ChatSettingsResponse carry partial updates and report which changes need a new session or a resource reload.

AgentMessage

AgentMessage is the extensible message union defined in packages/agent/src/types.ts:

export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];

It composes the base LLM Message types from packages/ai/src/types.ts (UserMessage, AssistantMessage, ToolResultMessage) with app-defined custom messages that apps extend via declaration merging on the CustomAgentMessages interface. The coding agent adds coding-specific roles (bashExecution, custom, branchSummary, compactionSummary) in packages/coding-agent/src/core/messages.ts.

Content is carried as typed blocks (TextContent, ImageContent, ThinkingContent, ToolCall). AssistantMessage records provider, model, usage (token and cost accounting), stopReason, and an optional errorMessage.

Model

The model registry type is defined in packages/ai/src/models.ts and packages/ai/src/types.ts. Model<TApi extends Api> describes a single model: provider, id, the API family it uses, per-token cost, input support, context window, whether it reasons, and its thinking-level mapping. The concrete registry is generated data in packages/ai/src/models.generated.ts (never edited by hand; regenerate via packages/ai/scripts/generate-models.ts). getModel, getModels, and getProviders in packages/ai/src/models.ts expose the registry; getSupportedThinkingLevels and clampThinkingLevel derive the reasoning levels a model actually supports.

Daemon protocol

The daemon wire protocol is defined in packages/coding-agent/src/modes/daemon/daemon-protocol.ts. It is a JSONL protocol over a Unix socket separating the agent runtime from interactive and web clients. The version constants are:

• DAEMON_PROTOCOL_NAME, prime-agent.daemon.
• DAEMON_PROTOCOL_VERSION, 8.
• DAEMON_COMMAND_ENVELOPE_MIN_PROTOCOL_VERSION, 7.
• DAEMON_SCHEMA_REVISION, 15.
• DAEMON_SCHEMA_ID, protocol-8-schema-15-d28eaade1789.

Commands and events carry an explicit compatibility contract (DAEMON_COMMAND_COMPATIBILITY, DAEMON_OUTBOUND_COMPATIBILITY): each entry declares a minimum protocol version, an optional minimum schema revision, and an optional server capability gate. Optional features are negotiated as server capabilities, and clients must check the capability before sending a command or depending on an event. Bump DAEMON_PROTOCOL_VERSION only for incompatible changes or new startup requirements; otherwise advance DAEMON_SCHEMA_REVISION.