primitives

Primitives

This lens documents the foundational domain objects that recur across three or more systems in Prime Agent. A primitive here is a shared type or contract that crosses a system boundary: it is produced in one package, transformed in another, and consumed by a third, so it must stay stable and its lifecycle must be understood end to end.

The repo is a TypeScript ESM monorepo. The agent runtime lives under packages/ as npm workspaces (ai, agent, coding-agent, tui), and the Qredence web UI lives under web/ as a pnpm workspace (protocol, design, server, app). Browser code talks HTTP (NDJSON and SSE) only and never imports @earendil-works/* directly, so every value that travels from the agent core to the UI crosses a serialization boundary at web/server.

Pages

• Agent message - the message model: AgentMessage is a union of LLM messages and app-extended custom types; it crosses packages/agent, packages/coding-agent, and the web/server event mapper.
• Chat stream event - the wire event: a discriminated union of NDJSON frames emitted per chat turn, validated by zod in web/protocol and consumed by the web reducer and renderers.

Related shared types

Other types appear across systems but are documented in their owning package pages rather than here:

• SessionView - the session structure surfaced to the UI, covered in Session runtime.
• ReplacedClientContext - a client-visible session replacement snapshot, covered in the session runtime page.
• QueueState - the steering/follow-up queue payload carried in queue chat frames (web/protocol/src/chat-protocol.ts), documented with the web protocol page.
• ChatPlanState - the structured plan execution state in plan frames (web/protocol/src/chat-protocol.ts), documented with the web protocol page.

For cross-references on LLM message shapes and streaming see ai package, and for glossary terms see Glossary.