@ccmsg/protocol 0.1.0

package/src/control/translate.ts

@@ -0,0 +1,33 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+
+/** Translates a batch of texts on the instance's host.
+ *
+ * The reply comes back when the whole batch is done, which can be seconds. An
+ * empty batch is not a probe for whether translation is available — that is the
+ * capability's job, and asking the question twice is what the capability set
+ * was introduced to end. */
+export const TranslateRunArgs = Type.Object({
+  texts: Type.Array(Type.String()),
+});
+export type TranslateRunArgs = Static<typeof TranslateRunArgs>;
+
+/** One text's outcome. A batch succeeds as a whole while individual texts may
+ * not, so the failure lives per item rather than failing the op. */
+export const TranslateResult = Type.Union(
+  [
+    Type.Object({ ok: Type.Literal(true), text: Type.String() }),
+    Type.Object({ ok: Type.Literal(false), error: Type.String() }),
+  ],
+  { $id: "TranslateResult" },
+);
+export type TranslateResult = Static<typeof TranslateResult>;
+
+export const TranslateRunResult = Type.Object({
+  /** One per requested text, in the order they were sent. */
+  results: Type.Array(TranslateResult),
+});
+export type TranslateRunResult = Static<typeof TranslateRunResult>;
+
+export const TranslateRunRequest = request("translate_run", TranslateRunArgs);
+export const TranslateRunResponse = response("translate_run", TranslateRunResult);

package/src/envelope.ts

@@ -0,0 +1,117 @@
+import { type Static, type TSchema, Type } from "@sinclair/typebox";
+import { ErrorBody } from "./errors.ts";
+import { InstanceId } from "./identifiers.ts";
+
+/** The generation of this wire contract. Within a generation, only optional
+ * fields and whole new ops may be added; a removal or a change of meaning
+ * raises it. Peers announcing another generation are refused, on client
+ * connections and on mesh links alike. */
+export const PROTOCOL_VERSION = 2;
+
+/** Fields a request carries in addition to its own arguments.
+ *
+ * `request_id` pairs a reply with its request so one connection can run its
+ * requests concurrently instead of in arrival order. Uniqueness only has to
+ * hold among one connection's in-flight requests.
+ *
+ * The three mesh fields are the whole of the mesh plane: an op forwarded to
+ * another instance is the same op in the same shape, wrapped in these. */
+export const RequestEnvelope = Type.Object(
+  {
+    request_id: Type.String({ minLength: 1 }),
+    /** Set when the caller wants this op run by a named instance rather than
+     * by the one it is connected to. */
+    to_instance: Type.Optional(InstanceId),
+    /** Stamped by the forwarding instance so the destination knows where the
+     * reply goes back to. */
+    from_instance: Type.Optional(InstanceId),
+    /** Instances this request has already passed through, in order. A request
+     * that would revisit an instance is dropped rather than looped. */
+    hops: Type.Optional(Type.Array(InstanceId)),
+  },
+  { $id: "RequestEnvelope" },
+);
+export type RequestEnvelope = Static<typeof RequestEnvelope>;
+
+/** Compose an op's own arguments with the request envelope. */
+export function request<T extends TSchema>(op: string, args: T) {
+  return Type.Intersect([Type.Object({ op: Type.Literal(op) }), args, RequestEnvelope], {
+    $id: `${op}:request`,
+  });
+}
+
+/** Compose an op's reply body with `ok: true` and the correlation id.
+ *
+ * `request_id` is required, unlike the generation that introduced it: a reply
+ * that cannot name its request settles no caller, and the only replies in that
+ * position are the reject-before-dispatch failures below. */
+export function response<T extends TSchema>(op: string, body: T) {
+  return Type.Intersect(
+    [Type.Object({ ok: Type.Literal(true), request_id: Type.String({ minLength: 1 }) }), body],
+    { $id: `${op}:response` },
+  );
+}
+
+/** A failed reply. `request_id` is absent only where the request could not be
+ * identified at all (unparseable JSON, missing `op`, missing `request_id`). */
+export const ErrorResponse = Type.Object(
+  {
+    ok: Type.Literal(false),
+    request_id: Type.Optional(Type.String({ minLength: 1 })),
+    error: ErrorBody,
+  },
+  { $id: "ErrorResponse" },
+);
+export type ErrorResponse = Static<typeof ErrorResponse>;
+
+/** A frame pushed on a topic the connection subscribed to.
+ *
+ * Snapshot and delta share one shape: the first frame after `topic_subscribe`
+ * carries `snapshot: true` and the whole current value, and later frames carry
+ * the same payload type as a change. `instance` names where the frame came
+ * from, which is what keeps whole-value topics from several instances out of
+ * each other's way. */
+export function topicFrame<T extends TSchema>(topic: string, data: T) {
+  return Type.Intersect(
+    [
+      Type.Object({
+        ev: Type.Literal("topic"),
+        topic: Type.String({ minLength: 1 }),
+        snapshot: Type.Optional(Type.Literal(true)),
+        instance: InstanceId,
+      }),
+      Type.Object({ data }),
+    ],
+    { $id: `topic:${topic}` },
+  );
+}
+
+/** The daemon is going down and will come back on the same socket. */
+export const RestartingEvent = Type.Object(
+  { ev: Type.Literal("restarting"), instance: InstanceId },
+  { $id: "RestartingEvent" },
+);
+export type RestartingEvent = Static<typeof RestartingEvent>;
+
+/** Another connection took over this session's subscription; this one will
+ * receive nothing further. About this connection alone, so it carries no
+ * originating instance. */
+export const SubscribeSupersededEvent = Type.Object(
+  { ev: Type.Literal("subscribe_superseded") },
+  { $id: "SubscribeSupersededEvent" },
+);
+export type SubscribeSupersededEvent = Static<typeof SubscribeSupersededEvent>;
+
+/** The instance's view of the host link changed. */
+export const NetOnlineEvent = Type.Object(
+  { ev: Type.Literal("net_online"), instance: InstanceId, online: Type.Boolean() },
+  { $id: "NetOnlineEvent" },
+);
+export type NetOnlineEvent = Static<typeof NetOnlineEvent>;
+
+/** Events about the connection itself rather than about a topic. */
+export const ConnectionEvent = Type.Union(
+  [RestartingEvent, SubscribeSupersededEvent, NetOnlineEvent],
+  { $id: "ConnectionEvent" },
+);
+export type ConnectionEvent = Static<typeof ConnectionEvent>;

package/src/errors.ts

@@ -0,0 +1,63 @@
+import { type Static, Type } from "@sinclair/typebox";
+
+/** Every code an error response may carry. The union is closed: a code outside
+ * this list is a contract violation, not an extension point. */
+export const ERROR_CODES = [
+  // --- connection level (no single op owns these) ---
+  /** The request could not be dispatched at all: unparseable JSON, no `op`, no
+   * `request_id`, or a `hello` announcing another protocol generation. */
+  "bad_request",
+  /** The op name is not in the op attribute table. */
+  "unknown_op",
+  /** An op with `needs_hello` arrived before `hello` settled the identity. */
+  "hello_required",
+  // --- rule-derived (op attribute table §0) ---
+  /** The connection's role is outside the op's `roles`. Argument problems stay
+   * on `invalid_args` / `bad_request`. */
+  "forbidden",
+  /** The op's arguments failed the op's schema. */
+  "invalid_args",
+  /** The op declares a `capability` this instance does not have. */
+  "capability_unavailable",
+  /** An `instance-local` op could not be forwarded to the instance that owns
+   * the subject. */
+  "instance_unreachable",
+  // --- subscription ---
+  /** The topic name is not one this protocol generation defines. */
+  "topic_unknown",
+  // --- subject lookup ---
+  /** The `sid` names no session anywhere in the cluster. */
+  "session_not_found",
+  /** The path, transcript, or record named by the arguments does not exist. */
+  "not_found",
+  // --- file access ---
+  "path_forbidden",
+  "path_not_writable",
+  "file_exists",
+  /** The file changed between the read the edit was based on and the write. */
+  "file_conflict",
+  /** The on-disk content sniffed as binary, so a text edit would not be
+   * faithful to what the caller saw. */
+  "not_a_text_file",
+  // --- translate ---
+  /** The helper process is present but failed on this call. (Its absence is
+   * `capability_unavailable` instead.) */
+  "translate_helper_failed",
+] as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+export const ErrorCodeSchema = Type.Union(
+  ERROR_CODES.map((code) => Type.Literal(code)),
+  { $id: "ErrorCode" },
+);
+
+export const ErrorBody = Type.Object(
+  {
+    code: ErrorCodeSchema,
+    /** Human-readable detail. Clients branch on `code`, never on this. */
+    msg: Type.String(),
+  },
+  { $id: "ErrorBody" },
+);
+export type ErrorBody = Static<typeof ErrorBody>;

package/src/identifiers.ts

@@ -0,0 +1,62 @@
+import { type Static, Type } from "@sinclair/typebox";
+
+/** A session id: the uuid Claude Code gives its own session. Globally unique,
+ * so it names a session across the whole cluster without an instance prefix. */
+export const Sid = Type.String({
+  $id: "Sid",
+  pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+});
+export type Sid = Static<typeof Sid>;
+
+/** An instance id: the endpoint URL other instances dial, compared as a whole
+ * string including its path (mesh-peer-auth §4.2 — one origin may host several
+ * instances, so origin-level comparison would confuse them). The display name
+ * lives in config, never on the wire. */
+export const InstanceId = Type.String({
+  $id: "InstanceId",
+  pattern: "^wss?://[^\\s?#]+$",
+});
+export type InstanceId = Static<typeof InstanceId>;
+
+/** A delivery-frame id: `<instance>/<counter>`, numbered by the instance that
+ * issued the frame. It exists so `reply_to` can point at one frame; it is not
+ * a cursor and carries no ordering across instances. */
+export const Mid = Type.String({
+  $id: "Mid",
+  pattern: "^wss?://[^\\s?#]+/\\d+$",
+});
+export type Mid = Static<typeof Mid>;
+
+/** Who a connection speaks as. Set once by `hello` and fixed for the
+ * connection's life; the op attribute table's `roles` is checked against it. */
+export const Role = Type.Union(
+  [Type.Literal("session"), Type.Literal("user"), Type.Literal("instance")],
+  { $id: "Role" },
+);
+export type Role = Static<typeof Role>;
+
+/** A capability name. `hello` returns the set this instance has, and an op
+ * whose `capability` is outside that set answers `capability_unavailable`. */
+export const Capability = Type.Union(
+  [
+    Type.Literal("fork"),
+    Type.Literal("launcher"),
+    /** A gateway webhook source is configured, so request activity arrives to
+     * be pushed on the `llm_requests` topic. */
+    Type.Literal("llm_events"),
+    Type.Literal("llm_stats"),
+    Type.Literal("llm_status"),
+    Type.Literal("llm_usage"),
+    Type.Literal("sandbox"),
+    Type.Literal("terminal"),
+    Type.Literal("translate"),
+  ],
+  { $id: "Capability" },
+);
+export type Capability = Static<typeof Capability>;
+
+/** A Unix-milliseconds timestamp. Every wire field naming a point in time is
+ * this type and ends in `_at`; durations carry their unit instead (`*_ms` /
+ * `*_secs`). */
+export const Timestamp = Type.Integer({ $id: "Timestamp", minimum: 0 });
+export type Timestamp = Static<typeof Timestamp>;

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from "./attributes.ts";
+export * from "./common/hello.ts";
+export * from "./common/ping.ts";
+export * from "./common/shutdown.ts";
+export * from "./common/topics.ts";
+export * from "./control/agents.ts";
+export * from "./control/files.ts";
+export * from "./control/kv.ts";
+export * from "./control/launcher.ts";
+export * from "./control/llm.ts";
+export * from "./control/peers.ts";
+export * from "./control/sandbox.ts";
+export * from "./control/session-errors.ts";
+export * from "./control/session-status.ts";
+export * from "./control/session.ts";
+export * from "./control/transcript.ts";
+export * from "./control/translate.ts";
+export * from "./envelope.ts";
+export * from "./errors.ts";
+export * from "./identifiers.ts";
+export * from "./messaging/message.ts";
+export * from "./messaging/notify.ts";
+export * from "./messaging/say.ts";
+export * from "./schemas.ts";
+export * from "./upstream.ts";

package/src/messaging/message.ts

@@ -0,0 +1,92 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response, topicFrame } from "../envelope.ts";
+import { InstanceId, Mid, Sid, Timestamp } from "../identifiers.ts";
+
+/** Why a message was not handed to its recipient right away.
+ *
+ * These are not errors: the op succeeded and the message is held in the
+ * recipient's inbox. They tell the sender what to do next — wait, resend to
+ * another session, or give up. The op itself fails only when `to` names no
+ * session anywhere in the cluster (`session_not_found`). */
+export const UndeliveredReason = Type.Union(
+  [
+    /** Alive, but not yet listening. The daemon delivers when it starts. */
+    Type.Literal("preparing"),
+    Type.Literal("paused"),
+    /** The session is gone. */
+    Type.Literal("disappeared"),
+    /** The instance holding the session cannot be reached over the mesh. */
+    Type.Literal("instance_unreachable"),
+    /** The recipient declined it for now — too much arriving at once, a full
+     * queue, or a message it has already been handed. It stays in the inbox and
+     * is offered again, so the sender waits rather than resending. */
+    Type.Literal("throttled"),
+    /** The recipient's inbox is at its limit; the oldest message was dropped
+     * to make room for this one. */
+    Type.Literal("inbox_full"),
+  ],
+  { $id: "UndeliveredReason" },
+);
+export type UndeliveredReason = Static<typeof UndeliveredReason>;
+
+/** A session the sender could send to instead, offered when the addressee is
+ * paused or gone: a session live now in the same repository. The workspace
+ * name is there because several worktrees of one repository qualify and the
+ * sender has to tell them apart. */
+export const CandidateSession = Type.Object(
+  {
+    sid: Sid,
+    /** Workspace name, when the session runs in a named workspace. */
+    ws: Type.Optional(Type.String()),
+    instance: InstanceId,
+  },
+  { $id: "CandidateSession" },
+);
+export type CandidateSession = Static<typeof CandidateSession>;
+
+export const MessageSendArgs = Type.Object({
+  /** The recipient session. There is no room to address: a message goes to one
+   * session. */
+  to: Sid,
+  text: Type.String({ minLength: 1 }),
+  /** The `mid` of the frame this message answers, when it answers one. */
+  reply_to: Type.Optional(Mid),
+});
+export type MessageSendArgs = Static<typeof MessageSendArgs>;
+
+export const MessageSendResult = Type.Object({
+  /** True when the recipient received it now; false when it went to the inbox
+   * to be delivered once the recipient can take it. */
+  delivered: Type.Boolean(),
+  /** Present when `delivered` is false. */
+  reason: Type.Optional(UndeliveredReason),
+  /** Present when the addressee is paused or gone. */
+  candidates: Type.Optional(Type.Array(CandidateSession)),
+});
+export type MessageSendResult = Static<typeof MessageSendResult>;
+
+export const MessageSendRequest = request("message_send", MessageSendArgs);
+export const MessageSendResponse = response("message_send", MessageSendResult);
+
+/** A message as the recipient receives it, on topic `inbox`.
+ *
+ * To answer it, send to `from`. The route is the sender's id and nothing else,
+ * so no reply instructions travel on the wire: the wording a session sees
+ * belongs to whichever client renders it. */
+export const InboxMessage = Type.Object(
+  {
+    mid: Mid,
+    from: Sid,
+    /** How the sender should be shown, resolved by the issuing instance. */
+    from_label: Type.String(),
+    text: Type.String(),
+    reply_to: Type.Optional(Mid),
+    sent_at: Timestamp,
+  },
+  { $id: "InboxMessage" },
+);
+export type InboxMessage = Static<typeof InboxMessage>;
+
+/** The `inbox` topic. Its snapshot is whatever is still undelivered for this
+ * session; each later frame is one newly arrived message. */
+export const InboxFrame = topicFrame("inbox", Type.Array(InboxMessage));

package/src/messaging/notify.ts

@@ -0,0 +1,35 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response, topicFrame } from "../envelope.ts";
+import { Sid, Timestamp } from "../identifiers.ts";
+
+/** A short line meant to reach a person watching, not the session's own turn.
+ * Delivery is best effort and unacknowledged; unlike `message_send`, nothing is
+ * held for later. */
+export const NotifySendArgs = Type.Object({
+  /** The session the notification is about. Omit to mean the caller. */
+  sid: Type.Optional(Sid),
+  text: Type.String({ minLength: 1 }),
+});
+export type NotifySendArgs = Static<typeof NotifySendArgs>;
+
+export const NotifySendResult = Type.Object({});
+export type NotifySendResult = Static<typeof NotifySendResult>;
+
+export const NotifySendRequest = request("notify_send", NotifySendArgs);
+export const NotifySendResponse = response("notify_send", NotifySendResult);
+
+export const Notification = Type.Object(
+  {
+    sid: Sid,
+    /** How the session should be shown, resolved by the issuing instance. */
+    sid_label: Type.String(),
+    text: Type.String(),
+    sent_at: Timestamp,
+  },
+  { $id: "Notification" },
+);
+export type Notification = Static<typeof Notification>;
+
+/** The `notify` topic. There is nothing to snapshot — a notification matters
+ * when it happens — so every frame is a new one. */
+export const NotifyFrame = topicFrame("notify", Notification);

package/src/messaging/say.ts

@@ -0,0 +1,35 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+import { Sid, Timestamp } from "../identifiers.ts";
+
+/** A session speaking to whoever is watching, rather than to one recipient.
+ *
+ * What was said is already in the calling session's transcript, since the call
+ * itself is a tool use there. So this op only pushes "this session just spoke"
+ * to the watchers; the instance keeps no log of its own. */
+export const SayPostArgs = Type.Object({
+  text: Type.String({ minLength: 1 }),
+});
+export type SayPostArgs = Static<typeof SayPostArgs>;
+
+export const SayPostResult = Type.Object({
+  posted_at: Timestamp,
+});
+export type SayPostResult = Static<typeof SayPostResult>;
+
+export const SayPostRequest = request("say_post", SayPostArgs);
+export const SayPostResponse = response("say_post", SayPostResult);
+
+/** Clears the unread mark a `say_post` raised. The mark is instance state that
+ * a restart may forget — nothing depends on it surviving. */
+export const SayMarkReadArgs = Type.Object({
+  /** The session whose unread mark is cleared. Omit to clear every one. */
+  sid: Type.Optional(Sid),
+});
+export type SayMarkReadArgs = Static<typeof SayMarkReadArgs>;
+
+export const SayMarkReadResult = Type.Object({});
+export type SayMarkReadResult = Static<typeof SayMarkReadResult>;
+
+export const SayMarkReadRequest = request("say_mark_read", SayMarkReadArgs);
+export const SayMarkReadResponse = response("say_mark_read", SayMarkReadResult);

package/src/schemas.ts

@@ -0,0 +1,195 @@
+import type { TSchema } from "@sinclair/typebox";
+import { TypeCompiler, type TypeCheck } from "@sinclair/typebox/compiler";
+import type { OpName } from "./attributes.ts";
+import { HelloRequest, HelloResponse } from "./common/hello.ts";
+import { InstancePingRequest, InstancePingResponse } from "./common/ping.ts";
+import { InstanceShutdownRequest, InstanceShutdownResponse } from "./common/shutdown.ts";
+import {
+  TopicSubscribeRequest,
+  TopicSubscribeResponse,
+  TopicUnsubscribeRequest,
+  TopicUnsubscribeResponse,
+} from "./common/topics.ts";
+import { AgentsFrame } from "./control/agents.ts";
+import {
+  DirListRequest,
+  DirListResponse,
+  DirTreeRequest,
+  DirTreeResponse,
+  FileCreateRequest,
+  FileCreateResponse,
+  FileDeleteRequest,
+  FileDeleteResponse,
+  FileEditRequest,
+  FileEditResponse,
+  FileFindRequest,
+  FileFindResponse,
+  FileReadRequest,
+  FileReadResponse,
+  FileStatBatchRequest,
+  FileStatBatchResponse,
+  FileWriteRequest,
+  FileWriteResponse,
+} from "./control/files.ts";
+import {
+  KvDeleteRequest,
+  KvDeleteResponse,
+  KvFrame,
+  KvReadRequest,
+  KvReadResponse,
+  KvWriteRequest,
+  KvWriteResponse,
+} from "./control/kv.ts";
+import {
+  LauncherConfigReadRequest,
+  LauncherConfigReadResponse,
+  LauncherRunRequest,
+  LauncherRunResponse,
+} from "./control/launcher.ts";
+import {
+  LlmRequestsFrame,
+  LlmStatsReadRequest,
+  LlmStatsReadResponse,
+  LlmStatusFrame,
+  LlmUsageReadRequest,
+  LlmUsageReadResponse,
+} from "./control/llm.ts";
+import { PeersFrame } from "./control/peers.ts";
+import {
+  SandboxGrantRequest,
+  SandboxGrantResponse,
+  SandboxRevokeRequest,
+  SandboxRevokeResponse,
+} from "./control/sandbox.ts";
+import { SessionErrorsFrame } from "./control/session-errors.ts";
+import { SessionStatusFrame } from "./control/session-status.ts";
+import {
+  SessionDumpWriteRequest,
+  SessionDumpWriteResponse,
+  SessionEnvReadRequest,
+  SessionEnvReadResponse,
+  SessionForkOriginRequest,
+  SessionForkOriginResponse,
+  SessionKillRequest,
+  SessionKillResponse,
+  SessionLastLiveRemoveRequest,
+  SessionLastLiveRemoveResponse,
+  SessionRenameRequest,
+  SessionRenameResponse,
+  SessionSearchRequest,
+  SessionSearchResponse,
+} from "./control/session.ts";
+import {
+  TranscriptFrame,
+  TranscriptReadRequest,
+  TranscriptReadResponse,
+} from "./control/transcript.ts";
+import { TranslateRunRequest, TranslateRunResponse } from "./control/translate.ts";
+import { InboxFrame, MessageSendRequest, MessageSendResponse } from "./messaging/message.ts";
+import { NotifyFrame, NotifySendRequest, NotifySendResponse } from "./messaging/notify.ts";
+import {
+  SayMarkReadRequest,
+  SayMarkReadResponse,
+  SayPostRequest,
+  SayPostResponse,
+} from "./messaging/say.ts";
+
+export interface OpSchemas {
+  readonly request: TSchema;
+  readonly response: TSchema;
+}
+
+/** The schema pair for every op.
+ *
+ * The op attribute table says who may call an op and where it runs; this says
+ * what it takes and what it answers. The two are checked against each other:
+ * an op in one and not the other is a hole in the contract, not a stage of it. */
+export const OP_SCHEMAS: Record<OpName, OpSchemas> = {
+  hello: { request: HelloRequest, response: HelloResponse },
+  instance_ping: { request: InstancePingRequest, response: InstancePingResponse },
+  instance_shutdown: { request: InstanceShutdownRequest, response: InstanceShutdownResponse },
+  topic_subscribe: { request: TopicSubscribeRequest, response: TopicSubscribeResponse },
+  topic_unsubscribe: { request: TopicUnsubscribeRequest, response: TopicUnsubscribeResponse },
+  message_send: { request: MessageSendRequest, response: MessageSendResponse },
+  say_post: { request: SayPostRequest, response: SayPostResponse },
+  say_mark_read: { request: SayMarkReadRequest, response: SayMarkReadResponse },
+  notify_send: { request: NotifySendRequest, response: NotifySendResponse },
+
+  session_kill: { request: SessionKillRequest, response: SessionKillResponse },
+  session_rename: { request: SessionRenameRequest, response: SessionRenameResponse },
+  session_env_read: { request: SessionEnvReadRequest, response: SessionEnvReadResponse },
+  session_search: { request: SessionSearchRequest, response: SessionSearchResponse },
+  session_dump_write: { request: SessionDumpWriteRequest, response: SessionDumpWriteResponse },
+  transcript_read: { request: TranscriptReadRequest, response: TranscriptReadResponse },
+  session_fork_origin: { request: SessionForkOriginRequest, response: SessionForkOriginResponse },
+  session_last_live_remove: {
+    request: SessionLastLiveRemoveRequest,
+    response: SessionLastLiveRemoveResponse,
+  },
+
+  dir_list: { request: DirListRequest, response: DirListResponse },
+  file_read: { request: FileReadRequest, response: FileReadResponse },
+  file_write: { request: FileWriteRequest, response: FileWriteResponse },
+  file_create: { request: FileCreateRequest, response: FileCreateResponse },
+  file_edit: { request: FileEditRequest, response: FileEditResponse },
+  file_delete: { request: FileDeleteRequest, response: FileDeleteResponse },
+  file_find: { request: FileFindRequest, response: FileFindResponse },
+  file_stat_batch: { request: FileStatBatchRequest, response: FileStatBatchResponse },
+  dir_tree: { request: DirTreeRequest, response: DirTreeResponse },
+
+  launcher_config_read: {
+    request: LauncherConfigReadRequest,
+    response: LauncherConfigReadResponse,
+  },
+  launcher_run: { request: LauncherRunRequest, response: LauncherRunResponse },
+  sandbox_grant: { request: SandboxGrantRequest, response: SandboxGrantResponse },
+  sandbox_revoke: { request: SandboxRevokeRequest, response: SandboxRevokeResponse },
+  translate_run: { request: TranslateRunRequest, response: TranslateRunResponse },
+  llm_usage_read: { request: LlmUsageReadRequest, response: LlmUsageReadResponse },
+  llm_stats_read: { request: LlmStatsReadRequest, response: LlmStatsReadResponse },
+
+  kv_read: { request: KvReadRequest, response: KvReadResponse },
+  kv_write: { request: KvWriteRequest, response: KvWriteResponse },
+  kv_delete: { request: KvDeleteRequest, response: KvDeleteResponse },
+};
+
+/** The frame schema for every topic.
+ *
+ * A topic's snapshot and its later frames share one schema, which is the point
+ * of the form: a subscriber has one way to read the current value and every
+ * change to it. */
+export const TOPIC_SCHEMAS = {
+  inbox: InboxFrame,
+  notify: NotifyFrame,
+  peers: PeersFrame,
+  agents: AgentsFrame,
+  session_status: SessionStatusFrame,
+  transcript: TranscriptFrame,
+  session_errors: SessionErrorsFrame,
+  llm_requests: LlmRequestsFrame,
+  llm_status: LlmStatusFrame,
+  kv: KvFrame,
+} as const;
+
+const compiled = new WeakMap<TSchema, TypeCheck<TSchema>>();
+
+/** A compiled validator for a schema, made once and reused. Validation is the
+ * contract's own job: both sides check against these rather than each writing
+ * their own field-by-field tests. */
+export function validator<T extends TSchema>(schema: T): TypeCheck<T> {
+  const hit = compiled.get(schema);
+  if (hit) return hit as TypeCheck<T>;
+  const made = TypeCompiler.Compile(schema);
+  compiled.set(schema, made as TypeCheck<TSchema>);
+  return made;
+}
+
+export function isValid<T extends TSchema>(schema: T, value: unknown): boolean {
+  return validator(schema).Check(value);
+}
+
+/** The reasons a value fails a schema, as `path: message` lines. Suitable for
+ * the `msg` of an `invalid_args` error. */
+export function validationErrors<T extends TSchema>(schema: T, value: unknown): string[] {
+  return [...validator(schema).Errors(value)].map((e) => `${e.path}: ${e.message}`);
+}

package/src/upstream.ts

@@ -0,0 +1,17 @@
+/** Systems other than ccmsg that own the meaning of a type.
+ *
+ * `claude` is the Claude Code CLI (`claude agents --json`, the session state
+ * files, transcript rows); `llm-gateway` is the proxy the daemon asks about
+ * quota, spend and upstream health. */
+export type UpstreamSource = "claude" | "llm-gateway";
+
+/** Marks a type whose vocabulary belongs to `source`, not to ccmsg.
+ *
+ * The mark says where an open set's future values come from, so a reader knows
+ * an unfamiliar `status` string is the upstream's to add rather than a bug. It
+ * does not exempt the type from this contract's spelling: the daemon renames
+ * and re-units every field as it copies the upstream document in, so what
+ * travels here is snake_case with Unix-ms instants like everything else. */
+export function upstream(source: UpstreamSource, note: string): { description: string } {
+  return { description: `upstream: ${source} — ${note}` };
+}