@ccmsg/protocol 1.11.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
   "license": "MIT",
   "author": "kawaz",

package/src/attributes.ts

@@ -196,7 +196,7 @@ export const OP_ATTRIBUTES = {
     errors: [],
   },
 
-  // --- control: session observation and operation (9) ---
+  // --- control: session observation and operation (10) ---
   session_kill: {
     plane: "control",
     roles: USER_ONLY,
@@ -248,6 +248,14 @@ export const OP_ATTRIBUTES = {
     scope: "role",
     errors: ["not_found"],
   },
+  transcript_items_read: {
+    plane: "control",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "instance-local",
+    scope: "role",
+    errors: ["not_found"],
+  },
   session_fork_origin: {
     plane: "control",
     roles: USER_ONLY,

package/src/common/topics.ts

@@ -15,7 +15,7 @@ export const PLAIN_TOPICS = [
 ] as const;
 
 /** Topics naming one session, written `<topic>:<sid>`. */
-export const SESSION_SCOPED_TOPICS = ["session_status", "transcript"] as const;
+export const SESSION_SCOPED_TOPICS = ["session_status", "transcript", "transcript_items"] as const;
 
 /** Topics naming one namespace, written `<topic>:<ns>`. The parameter is a name
  * its users choose rather than an identifier this contract issues, so it is
@@ -102,6 +102,10 @@ export const TOPIC_ATTRIBUTES = {
   // half to leave alone: the frame is simply the whole of it.
   session_status: { roles: ["user"], granularity: "whole" },
   transcript: { roles: ["user"], granularity: "append" },
+  // The same appending, in items rather than in bytes. Both are offered because
+  // they answer different needs: one draws the conversation, the other shows a
+  // record as it was written.
+  transcript_items: { roles: ["user"], granularity: "append" },
   kv: { roles: ["user"], granularity: "element" },
   // The only topic no person may subscribe to: its elements are the secrets
   // that authenticate them. A relay carries it as the instance it is, not on a

package/src/control/dump.ts

@@ -1,6 +1,6 @@
 import { type Static, type TSchema, Type } from "@sinclair/typebox";
 import { request, response } from "../envelope.ts";
-import { Timestamp } from "../identifiers.ts";
+import { Sid, Timestamp } from "../identifiers.ts";
 
 /** The vocabulary a transcript is read in: item types, the shape one item
  * takes, the ledger of ids they carry, and the named selections a person dumps
@@ -65,14 +65,47 @@ export const TranscriptItemSelector = Type.String({
 });
 export type TranscriptItemSelector = Static<typeof TranscriptItemSelector>;
 
+/** Where in the transcript the record an item was read from begins, and how far
+ * it runs.
+ *
+ * An item is what a reader made of a record, and a reader is fallible: the one
+ * question it cannot answer is what the record actually said. These two numbers
+ * are that answer's address — `transcript_read` bounded to end at `offset +
+ * bytes` and to carry `bytes` returns the record itself — which is what lets a
+ * client show items and still let a person open the line behind one. Several
+ * items read out of a single record share the address, so what comes back is
+ * the record and not a slice of it. */
+export const TranscriptItemSource = Type.Object(
+  {
+    offset: Type.Integer({ minimum: 0 }),
+    bytes: Type.Integer({ minimum: 1 }),
+  },
+  { $id: "TranscriptItemSource" },
+);
+export type TranscriptItemSource = Static<typeof TranscriptItemSource>;
+
+/** An item's own identity, `<uuid>:<index>` — the record it was read from and
+ * where in that record it stood.
+ *
+ * The record's id alone does not identify an item: one assistant record becomes
+ * the thinking, the text and each call it held, and a link that pointed by
+ * `uuid` would name all of them at once. */
+export const TranscriptItemId = Type.String({
+  pattern: "^[^\\s:]+:(?:0|[1-9][0-9]*)$",
+  $id: "TranscriptItemId",
+});
+export type TranscriptItemId = Static<typeof TranscriptItemId>;
+
 /** What every item carries, whatever its type.
  *
- * `uuid` is the record's own id in the transcript, which is what makes an item
- * addressable: a reader that wants more than the dump kept can go back to the
- * file with it, and the links below point with it rather than with a position,
- * since a selection or a range decides which items exist in a given dump. */
+ * `id` is what the links below point with — never a position in the array,
+ * since a selection or a range decides which items exist in a given read — and
+ * `uuid` stays beside it as the record the item came out of, which is what a
+ * reader groups by when it wants the whole of one line. */
 const BASE_FIELDS = {
+  id: TranscriptItemId,
   uuid: Type.String({ minLength: 1 }),
+  source: TranscriptItemSource,
   /** The item's own instant. A call and its result each keep their own. */
   at: Timestamp,
   /** Which turn of the session the item fell in, when the reader could place
@@ -86,22 +119,25 @@ const BASE_FIELDS = {
  * Some results arrive many turns later — an agent runs, a monitor waits — with
  * other items in between, so folding them into a single item would make the
  * reader decide which of the two instants the fold happens at. Two items each
- * keep their own, linked by uuid, and folding is left to whoever draws them. A
- * `use` without a `result_item` is a call that has not come back, including one
- * whose result falls outside the range asked for. */
+ * keep their own, linked by id, and folding is left to whoever draws them.
+ *
+ * A link is written from the whole transcript and not from the slice it travels
+ * in, so a `result_item` naming an item outside the range asked for is the
+ * ordinary case rather than a broken pointer: the reader knows the id and can
+ * ask for it. A `use` without one is a call that has not come back. */
 const USE_FIELDS = {
   role: Type.Literal("use"),
-  /** The result's uuid, once there is one. */
-  result_item: Type.Optional(Type.String({ minLength: 1 })),
+  /** The result's id, once there is one. */
+  result_item: Type.Optional(TranscriptItemId),
 };
 
 const RESULT_FIELDS = {
   role: Type.Literal("result"),
   /** The call this answers. Always known: a result exists because a call did. */
-  parent_item: Type.String({ minLength: 1 }),
+  parent_item: TranscriptItemId,
 };
 
-function item(type: TSchema, fields: Record<string, TSchema> = {}): TSchema {
+function item<T extends TSchema, F extends Record<string, TSchema>>(type: T, fields: F) {
   return Type.Object({ ...BASE_FIELDS, type, ...fields });
 }
 
@@ -220,16 +256,16 @@ const Hook = item(Type.String({ pattern: "^hook:[A-Za-z0-9_.-]+$" }), {
 
 const ToolType = Type.String({ pattern: "^tool:[A-Za-z0-9_.-]+$" });
 
-function toolUse(name: string, fields: Record<string, TSchema>): TSchema {
-  return item(Type.Literal(`tool:${name}`), {
+function toolUse<N extends string, F extends Record<string, TSchema>>(name: N, fields: F) {
+  return item(Type.Literal(`tool:${name}` as const), {
     ...USE_FIELDS,
     tool_use_id: Type.String(),
     ...fields,
   });
 }
 
-function toolResult(name: string, fields: Record<string, TSchema>): TSchema {
-  return item(Type.Literal(`tool:${name}`), {
+function toolResult<N extends string, F extends Record<string, TSchema>>(name: N, fields: F) {
+  return item(Type.Literal(`tool:${name}` as const), {
     ...RESULT_FIELDS,
     tool_use_id: Type.String(),
     ...fields,
@@ -253,7 +289,7 @@ const ToolResultGeneric = item(ToolType, {
   result: Type.Record(Type.String(), Type.Unknown()),
 });
 
-const TOOL_ITEMS: TSchema[] = [
+const TOOL_ITEMS = [
   /** No exit code: what the harness records of a shell call is its output and
    * whether it was interrupted, so that is what a reader has to judge by. */
   toolUse("Bash", { command: Type.String(), description: OptText }),
@@ -396,6 +432,32 @@ export type DumpIdEntry = Static<typeof DumpIdEntry>;
 export const DumpIds = Type.Array(DumpIdEntry, { $id: "DumpIds" });
 export type DumpIds = Static<typeof DumpIds>;
 
+/** The file a dump is written to.
+ *
+ * The reply to a dump names a path rather than carrying the items, so the file
+ * is where they actually travel — which makes its shape as much a part of the
+ * contract as the reply is: a successor session handed the path, or a client
+ * that fetches it, would otherwise be reading a format nothing states. It
+ * repeats what it was asked for, because a file outlives the request that made
+ * it and has to say on its own what it is a dump of and what was left out. */
+export const SessionDumpFile = Type.Object(
+  {
+    sid: Sid,
+    /** The agent the dump is of, absent when it is of the session itself. */
+    agent_id: Type.Optional(Type.String()),
+    written_at: Timestamp,
+    /** The selection as applied: presets expanded and exclusions kept in
+     * place, so the file states what it holds without the instance's config
+     * having to be read beside it. */
+    types: Type.Array(TranscriptItemSelector),
+    /** Oldest first, as the transcript had them. */
+    items: Type.Array(TranscriptItem),
+    ids: DumpIds,
+  },
+  { $id: "SessionDumpFile" },
+);
+export type SessionDumpFile = Static<typeof SessionDumpFile>;
+
 /** A selection an operator named and can ask for by name.
  *
  * Presets are configured on the instance rather than fixed here, because what

package/src/control/transcript.ts

@@ -1,6 +1,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response, topicFrame } from "../envelope.ts";
-import { Sid } from "../identifiers.ts";
+import { Sid, Timestamp } from "../identifiers.ts";
+import { DumpIds, TranscriptItem, TranscriptItemId, TranscriptItemSelector } from "./dump.ts";
 
 /** Reads a slice of a session's transcript.
  *
@@ -50,6 +51,79 @@ export type TranscriptReadResult = Static<typeof TranscriptReadResult>;
 export const TranscriptReadRequest = request("transcript_read", TranscriptReadArgs);
 export const TranscriptReadResponse = response("transcript_read", TranscriptReadResult);
 
+/** Reads a slice of a transcript as the items it was read into.
+ *
+ * The read above answers with the file's own lines, which leaves whoever asked
+ * holding a harness's private format; this answers with what those lines were
+ * classified as, so a client draws items and never learns how a record is
+ * shaped. Both stay: the typed read is what a client works in, and the raw one
+ * is how it fetches the record behind an item it wants to see verbatim, by the
+ * `source` that item carries.
+ *
+ * The range is cut the way a dump's is — an instant or a record on either side
+ * — and `since_id` resumes a read that stopped at a limit. The role decides how
+ * much is visible, as it does for the raw read. */
+export const TranscriptItemsReadArgs = Type.Object({
+  sid: Sid,
+  /** Read one agent below the session instead of the session itself. */
+  agent_id: Type.Optional(Type.String()),
+  /** Inclusive lower bound in time. */
+  since_at: Type.Optional(Timestamp),
+  /** Inclusive lower bound as a transcript record id, which cuts at that
+   * record's position rather than at its clock. Give one lower bound only. */
+  since_uuid: Type.Optional(Type.String()),
+  /** Resume at this item, the one a previous reply named as `next`. Finer than
+   * `since_uuid`, which would start again at the first item of a record whose
+   * later items were already read. */
+  since_id: Type.Optional(TranscriptItemId),
+  until_at: Type.Optional(Timestamp),
+  until_uuid: Type.Optional(Type.String()),
+  /** Which item types to keep, applied left to right. Absent keeps everything
+   * but the attachments, as a dump's absent selection does. */
+  types: Type.Optional(Type.Array(TranscriptItemSelector)),
+  /** How many items to answer with; the instance narrows this to its own
+   * limit. */
+  limit: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+export type TranscriptItemsReadArgs = Static<typeof TranscriptItemsReadArgs>;
+
+export const TranscriptItemsReadResult = Type.Object({
+  /** Oldest first, as the transcript had them. */
+  items: Type.Array(TranscriptItem),
+  /** The first item left out, when a limit cut the answer short. Absent means
+   * the range was answered whole. */
+  next: Type.Optional(TranscriptItemId),
+  /** The ids the answered items carried, gathered as a dump gathers them.
+   * Absent when the caller did not ask the instance to collect them. */
+  ids: Type.Optional(DumpIds),
+});
+export type TranscriptItemsReadResult = Static<typeof TranscriptItemsReadResult>;
+
+export const TranscriptItemsReadRequest = request("transcript_items_read", TranscriptItemsReadArgs);
+export const TranscriptItemsReadResponse = response(
+  "transcript_items_read",
+  TranscriptItemsReadResult,
+);
+
+/** The `transcript_items:<sid>` topic.
+ *
+ * What `transcript:<sid>` carries as appended bytes, carried as the items those
+ * bytes were read as. A subscriber holds a list it only ever appends to, so the
+ * opening frame is the tail of it — the last items the instance kept, in a
+ * count it decides — and every frame after carries what has since been
+ * classified. A client that wants further back asks for it by range rather than
+ * waiting for a snapshot to grow.
+ *
+ * A record still being written is not classified until its line ends, which is
+ * the same rule the raw topic sends whole lines under. */
+export const TranscriptItemsFrame = topicFrame(
+  "transcript_items",
+  Type.Object({
+    sid: Sid,
+    items: Type.Array(TranscriptItem),
+  }),
+);
+
 /** The `transcript:<sid>` topic.
  *
  * The one topic whose frames are not a whole value: a transcript is appended

package/src/fixtures/control.ts

@@ -48,6 +48,7 @@ import type {
 import type {
   DumpPresetsReadRequest,
   DumpPresetsReadResponse,
+  SessionDumpFile,
   TranscriptItem,
 } from "../control/dump.ts";
 import type {
@@ -66,7 +67,12 @@ import type {
   SessionSearchRequest,
   SessionSearchResponse,
 } from "../control/session.ts";
-import type { TranscriptReadRequest, TranscriptReadResponse } from "../control/transcript.ts";
+import type {
+  TranscriptItemsReadRequest,
+  TranscriptItemsReadResponse,
+  TranscriptReadRequest,
+  TranscriptReadResponse,
+} from "../control/transcript.ts";
 import type { TranslateRunRequest, TranslateRunResponse } from "../control/translate.ts";
 import { FIXTURE_IDS, FIXTURE_NOW } from "./ids.ts";
 
@@ -163,7 +169,7 @@ export const SESSION_DUMP_WRITE_REQUEST: Static<typeof SessionDumpWriteRequest>
 export const SESSION_DUMP_WRITE_RESPONSE: Static<typeof SessionDumpWriteResponse> = {
   ok: true,
   request_id,
-  path: "/transcripts/6f1a2b3c.dump.md",
+  path: "/transcripts/6f1a2b3c.dump.json",
   instance,
   entries: { thinking: 41, "tool:Bash": 62, "tool:Read": 25 },
   ids: [
@@ -180,6 +186,16 @@ export const SESSION_DUMP_WRITE_RESPONSE: Static<typeof SessionDumpWriteResponse
   bytes: 65_536,
 };
 
+/** The file the reply above names, holding the items themselves. */
+export const SESSION_DUMP_FILE: Static<typeof SessionDumpFile> = {
+  sid,
+  agent_id: "a471372f2",
+  written_at: FIXTURE_NOW,
+  types: ["tool:Read", "tool:Write", "tool:Edit", "tool:Glob", "thinking"],
+  items: [],
+  ids: [{ kind: "agent", id: "a471372f2", label: "dump-kinds-design", status: "ok" }],
+};
+
 export const DUMP_PRESETS_READ_REQUEST: Static<typeof DumpPresetsReadRequest> = {
   request_id,
   op: "dump_presets_read",
@@ -206,48 +222,66 @@ export const DUMP_PRESETS_READ_RESPONSE: Static<typeof DumpPresetsReadResponse>
  *
  * A call and its result appear as the two items they are, linked both ways, so
  * an implementation can check that it draws the pair without assuming they are
- * adjacent. */
+ * adjacent. The thinking and the call after it were read out of one record and
+ * carry the one address it sits at, which is the case an id exists for. */
 export const TRANSCRIPT_ITEMS: Static<typeof TranscriptItem>[] = [
   {
+    id: "3f9a21c4:0",
     uuid: "3f9a21c4",
+    source: { offset: 180_000, bytes: 420 },
     type: "message:user:in",
     at: FIXTURE_NOW - 3_600_000,
     turn: 1,
     text: "dump のアイテム型を整理して",
   },
-  { uuid: "f10b6d43", type: "thinking", at: FIXTURE_NOW - 3_500_000, text: "台帳として分ける" },
   {
-    uuid: "07c5e1b8",
+    id: "f10b6d43:0",
+    uuid: "f10b6d43",
+    source: { offset: 180_420, bytes: 980 },
+    type: "thinking",
+    at: FIXTURE_NOW - 3_500_000,
+    text: "台帳として分ける",
+  },
+  {
+    id: "f10b6d43:1",
+    uuid: "f10b6d43",
+    source: { offset: 180_420, bytes: 980 },
     type: "tool:Bash",
     at: FIXTURE_NOW - 3_400_000,
     role: "use",
     tool_use_id: "toolu_01Ne9BDS",
-    result_item: "18d6f2c9",
+    result_item: "18d6f2c9:0",
     command: "jq -r '.type' session.jsonl | sort | uniq -c",
     description: "count the record types",
   },
   {
+    id: "18d6f2c9:0",
     uuid: "18d6f2c9",
+    source: { offset: 181_400, bytes: 260 },
     type: "tool:Bash",
     at: FIXTURE_NOW - 3_399_000,
     role: "result",
     tool_use_id: "toolu_01Ne9BDS",
-    parent_item: "07c5e1b8",
+    parent_item: "f10b6d43:1",
     stdout: "1174 assistant\n753 user\n",
     interrupted: false,
   },
   {
+    id: "b7e41d09:0",
     uuid: "b7e41d09",
+    source: { offset: 181_660, bytes: 640 },
     type: "message:sub:out",
     at: FIXTURE_NOW - 3_300_000,
     role: "use",
-    result_item: "c2d80f16",
+    result_item: "c2d80f16:0",
     prompt: "docs/design/dump-kinds.md を書き直す",
     agent_id: "a471372f2",
     subagent_type: "opus5-worker-high",
   },
   {
+    id: "92e6d4f5:0",
     uuid: "92e6d4f5",
+    source: { offset: 182_300, bytes: 310 },
     type: "hook:PreToolUse",
     at: FIXTURE_NOW - 3_200_000,
     hook_name: "PreToolUse:Bash",
@@ -256,7 +290,9 @@ export const TRANSCRIPT_ITEMS: Static<typeof TranscriptItem>[] = [
     tool_use_id: "toolu_01Ne9BDS",
   },
   {
+    id: "81d5c3e4:0",
     uuid: "81d5c3e4",
+    source: { offset: 182_610, bytes: 190 },
     type: "system:attachment:queued_command",
     at: FIXTURE_NOW - 3_100_000,
     attachment: { type: "queued_command", command: "/pre-clear" },
@@ -281,6 +317,25 @@ export const TRANSCRIPT_READ_RESPONSE: Static<typeof TranscriptReadResponse> = {
   size: 182_400,
 };
 
+export const TRANSCRIPT_ITEMS_READ_REQUEST: Static<typeof TranscriptItemsReadRequest> = {
+  request_id,
+  op: "transcript_items_read",
+  sid,
+  since_at: FIXTURE_NOW - 3_600_000,
+  types: ["message", "thinking", "tool:Bash"],
+  limit: 200,
+};
+
+/** The answer stops where the limit did and names what comes next, so the
+ * caller asks for the rest with `since_id` and reads nothing twice. */
+export const TRANSCRIPT_ITEMS_READ_RESPONSE: Static<typeof TranscriptItemsReadResponse> = {
+  ok: true,
+  request_id,
+  items: TRANSCRIPT_ITEMS,
+  next: "c2d80f16:0",
+  ids: [{ kind: "agent", id: "a471372f2", label: "dump-kinds-design", status: "running" }],
+};
+
 export const SESSION_FORK_ORIGIN_REQUEST: Static<typeof SessionForkOriginRequest> = {
   request_id,
   op: "session_fork_origin",

package/src/fixtures/index.ts

@@ -100,6 +100,10 @@ export const OP_FIXTURES = {
     request: control.TRANSCRIPT_READ_REQUEST,
     response: control.TRANSCRIPT_READ_RESPONSE,
   },
+  transcript_items_read: {
+    request: control.TRANSCRIPT_ITEMS_READ_REQUEST,
+    response: control.TRANSCRIPT_ITEMS_READ_RESPONSE,
+  },
   session_fork_origin: {
     request: control.SESSION_FORK_ORIGIN_REQUEST,
     response: control.SESSION_FORK_ORIGIN_RESPONSE,
@@ -162,6 +166,7 @@ export const TOPIC_FIXTURES = {
   agents: topics.AGENTS_FRAME,
   session_status: topics.SESSION_STATUS_FRAME,
   transcript: topics.TRANSCRIPT_FRAME,
+  transcript_items: topics.TRANSCRIPT_ITEMS_FRAME,
   session_errors: topics.SESSION_ERRORS_FRAME,
   llm_requests: topics.LLM_REQUESTS_FRAME,
   llm_status: topics.LLM_STATUS_FRAME,

package/src/fixtures/topics.ts

@@ -6,7 +6,8 @@ import type { LlmRequestsFrame, LlmStatusFrame } from "../control/llm.ts";
 import type { PeersFrame } from "../control/peers.ts";
 import type { SessionErrorsFrame } from "../control/session-errors.ts";
 import type { SessionStatusFrame } from "../control/session-status.ts";
-import type { TranscriptFrame } from "../control/transcript.ts";
+import type { TranscriptFrame, TranscriptItemsFrame } from "../control/transcript.ts";
+import { TRANSCRIPT_ITEMS } from "./control.ts";
 import type { InboxFrame } from "../messaging/message.ts";
 import type { NotifyFrame } from "../messaging/notify.ts";
 import { FIXTURE_IDS, FIXTURE_NOW } from "./ids.ts";
@@ -264,6 +265,24 @@ export const TRANSCRIPT_SIZE_FRAME = {
   data: { sid, size: 182_400 },
 } satisfies Static<typeof TranscriptFrame>;
 
+/** The typed topic, whose frames carry items rather than bytes. */
+export const TRANSCRIPT_ITEMS_FRAME = {
+  ev: "topic",
+  topic: `transcript_items:${sid}`,
+  instance,
+  data: { sid, items: TRANSCRIPT_ITEMS.slice(-2) },
+} satisfies Static<typeof TranscriptItemsFrame>;
+
+/** Its opening frame, which is the tail the instance kept — the same shape as
+ * every frame after it, so a subscriber appends both the same way. */
+export const TRANSCRIPT_ITEMS_SNAPSHOT_FRAME = {
+  ev: "topic",
+  topic: `transcript_items:${sid}`,
+  snapshot: true,
+  instance,
+  data: { sid, items: TRANSCRIPT_ITEMS },
+} satisfies Static<typeof TranscriptItemsFrame>;
+
 export const SESSION_ERRORS_FRAME: Static<typeof SessionErrorsFrame> = {
   ev: "topic",
   topic: "session_errors",

package/src/schemas.ts

@@ -104,6 +104,9 @@ import {
 } from "./control/session.ts";
 import {
   TranscriptFrame,
+  TranscriptItemsFrame,
+  TranscriptItemsReadRequest,
+  TranscriptItemsReadResponse,
   TranscriptReadRequest,
   TranscriptReadResponse,
 } from "./control/transcript.ts";
@@ -153,6 +156,10 @@ export const OP_SCHEMAS: Record<OpName, OpSchemas> = {
   session_dump_write: { request: SessionDumpWriteRequest, response: SessionDumpWriteResponse },
   dump_presets_read: { request: DumpPresetsReadRequest, response: DumpPresetsReadResponse },
   transcript_read: { request: TranscriptReadRequest, response: TranscriptReadResponse },
+  transcript_items_read: {
+    request: TranscriptItemsReadRequest,
+    response: TranscriptItemsReadResponse,
+  },
   session_fork_origin: { request: SessionForkOriginRequest, response: SessionForkOriginResponse },
   session_last_live_remove: {
     request: SessionLastLiveRemoveRequest,
@@ -197,6 +204,7 @@ export const TOPIC_SCHEMAS = {
   agents: AgentsFrame,
   session_status: SessionStatusFrame,
   transcript: TranscriptFrame,
+  transcript_items: TranscriptItemsFrame,
   session_errors: SessionErrorsFrame,
   llm_requests: LlmRequestsFrame,
   llm_status: LlmStatusFrame,