@ccmsg/protocol 1.9.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.9.0",
+  "version": "1.11.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 (8) ---
+  // --- control: session observation and operation (9) ---
   session_kill: {
     plane: "control",
     roles: USER_ONLY,
@@ -233,6 +233,13 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: ["not_found"],
   },
+  dump_presets_read: {
+    plane: "control",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: [],
+  },
   transcript_read: {
     plane: "control",
     roles: AGENT_AND_USER,

package/src/common/hello.ts

@@ -129,6 +129,21 @@ export const HelloResult = Type.Object({
   /** The daemon build, for display. */
   version: Type.String(),
   started_at: Timestamp,
+  /** Where a person opens the terminal a session runs in: the base URL of the
+   * gateway that fronts this instance's terminals. A session's terminal names
+   * itself in `terminal_id` on the `agents` topic, and the gateway's URL for it
+   * is `<terminal_gateway>/sessions/<terminal_id>` — so the base URL carries no
+   * trailing slash, the path below it being the gateway's spelling and not this
+   * contract's.
+   *
+   * Stated by the instance because only it knows which gateway stands in front
+   * of the machine its sessions run on; a client has no way to derive one from
+   * the endpoint it reached. Absent where the instance cannot reach its
+   * sessions' terminals at all, which is the same condition that leaves the
+   * `terminal` capability out of the set above. */
+  terminal_gateway: Type.Optional(
+    Type.String({ pattern: "^https?://[^/?#\\s]+(/[^?#\\s]*[^/?#\\s])?$" }),
+  ),
   /** When this connection's authorization runs out, after which the instance
    * closes it. Present on a connection an access token opened; absent where
    * reaching the instance is itself the permission (the Unix socket) or where

package/src/control/dump.ts

@@ -0,0 +1,433 @@
+import { type Static, type TSchema, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+import { 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
+ * by.
+ *
+ * A transcript is a harness's own file format, appended to in whatever shape
+ * that harness settles on. What travels between us is not that file but the
+ * items it was read as, so the classifying — which line is which item — belongs
+ * to whoever reads the file, and only the names it classifies into are written
+ * down here. That split is what lets a harness change its file, or a second
+ * harness be read at all, without the contract moving.
+ *
+ * A type name is `:`-separated and read left to right, so a prefix names
+ * everything below it: `tool` is every tool, `message:user` is both directions
+ * of what a person and a session said. Three families stay open, because their
+ * last segment is a name someone else coins — a tool, an attachment kind, a
+ * hook event — and closing them would turn every newcomer into `unknown`. */
+
+/** A type name as written on the wire and in a selection.
+ *
+ * Segments after the first carry the spelling of whatever named them, which is
+ * why they are not held to snake_case: `tool:Bash` and `hook:PreToolUse` are
+ * the harness's words, and rewriting them would leave the reader unable to
+ * match what it sees against what it ran. */
+export const TranscriptItemType = Type.String({
+  pattern: "^[a-z]+(?::[A-Za-z0-9_.-]+)*$",
+  $id: "TranscriptItemType",
+});
+export type TranscriptItemType = Static<typeof TranscriptItemType>;
+
+/** The type names that are fully spelled out here. The three open families
+ * (`tool:<Name>`, `system:attachment:<kind>`, `hook:<Event>`) are not in the
+ * list: their last segment is coined elsewhere, and a name absent from this
+ * list is a newcomer rather than an error. */
+export const TRANSCRIPT_ITEM_TYPES = [
+  "message:user:in",
+  "message:user:out",
+  "message:sub:in",
+  "message:sub:out",
+  "message:session:in",
+  "message:session:out",
+  "thinking",
+  "notice:slash",
+  "notice:interrupt",
+  "system:compact",
+  "system:api-error",
+  "system:task",
+  "system:caveat",
+  "system:resume",
+  "system:unknown",
+] as const;
+export type KnownTranscriptItemType = (typeof TRANSCRIPT_ITEM_TYPES)[number];
+
+/** One element of a selection: a type name, a prefix of one, either of those
+ * negated with `-`, or `@name` standing for a preset expanded in place.
+ *
+ * Elements apply left to right, so an exclusion reaches whatever a prefix or an
+ * expansion before it brought in. */
+export const TranscriptItemSelector = Type.String({
+  pattern: "^-?(?:@[A-Za-z0-9][A-Za-z0-9_-]*|[a-z]+(?::[A-Za-z0-9_.-]+)*)$",
+  $id: "TranscriptItemSelector",
+});
+export type TranscriptItemSelector = Static<typeof TranscriptItemSelector>;
+
+/** 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. */
+const BASE_FIELDS = {
+  uuid: Type.String({ minLength: 1 }),
+  /** 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
+   * it. Derived from the file and renumbered whenever it is read again, so it
+   * is an attribute to show and never a way to cut a range. */
+  turn: Type.Optional(Type.Integer({ minimum: 0 })),
+};
+
+/** A call and what came back are two items, not one.
+ *
+ * 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. */
+const USE_FIELDS = {
+  role: Type.Literal("use"),
+  /** The result's uuid, once there is one. */
+  result_item: Type.Optional(Type.String({ minLength: 1 })),
+};
+
+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 }),
+};
+
+function item(type: TSchema, fields: Record<string, TSchema> = {}): TSchema {
+  return Type.Object({ ...BASE_FIELDS, type, ...fields });
+}
+
+const Text = Type.String();
+
+// --- message: who said what to whom, from the subject's side ---
+
+/** The subject is a session by default, or one agent below it when the dump
+ * names an agent, and `in` / `out` are read from wherever the subject stands.
+ * A dump of an agent therefore reads `message:user:in` as the brief its parent
+ * gave it, on the same type names a dump of the session uses — which is what
+ * lets one preset be carried down a chain of agents. */
+const MessageUserIn = item(Type.Literal("message:user:in"), { text: Text });
+const MessageUserOut = item(Type.Literal("message:user:out"), { text: Text });
+
+const MessageSubOut = item(Type.Literal("message:sub:out"), {
+  ...USE_FIELDS,
+  prompt: Text,
+  agent_id: Type.Optional(Type.String()),
+  /** The agent definition asked for, in the harness's spelling. */
+  subagent_type: Type.Optional(Type.String()),
+  name: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+});
+
+const MessageSubIn = item(Type.Literal("message:sub:in"), {
+  ...RESULT_FIELDS,
+  text: Text,
+  agent_id: Type.Optional(Type.String()),
+  status: Type.Optional(Type.String()),
+  duration_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+});
+
+const MessageSessionOut = item(Type.Literal("message:session:out"), {
+  text: Text,
+  /** The addressee as the subject wrote it: a sid, or a name that was resolved
+   * to one. Kept unresolved when that is all the transcript says. */
+  to: Type.Optional(Type.String()),
+  msg_id: Type.Optional(Type.String()),
+  reply_to: Type.Optional(Type.String()),
+});
+
+const MessageSessionIn = item(Type.Literal("message:session:in"), {
+  text: Text,
+  from: Type.Optional(Type.String()),
+  msg_id: Type.Optional(Type.String()),
+});
+
+const Thinking = item(Type.Literal("thinking"), { text: Text });
+
+// --- notice: a person operated the harness ---
+
+/** Kept apart from `system:*` because these explain a break in the
+ * conversation: someone typed a command or stopped a turn. A reader skimming
+ * for why the thread jumps needs them, and can skip what the harness injected
+ * for its own reasons. */
+const NoticeSlash = item(Type.Literal("notice:slash"), {
+  command: Type.String(),
+  args: Type.Optional(Type.String()),
+  stdout: Type.Optional(Type.String()),
+});
+const NoticeInterrupt = item(Type.Literal("notice:interrupt"), {
+  text: Type.Optional(Text),
+});
+
+// --- system: the harness talking in someone else's voice ---
+
+const SystemCompact = item(Type.Literal("system:compact"), { text: Text });
+const SystemApiError = item(Type.Literal("system:api-error"), { text: Text });
+const SystemTask = item(Type.Literal("system:task"), {
+  text: Text,
+  /** The background task or monitor the event came from. */
+  task_id: Type.Optional(Type.String()),
+  event: Type.Optional(Type.String()),
+});
+const SystemCaveat = item(Type.Literal("system:caveat"), { text: Text });
+const SystemResume = item(Type.Literal("system:resume"), { text: Text });
+
+/** `system:attachment:<kind>` — the kind is the harness's own word for what it
+ * attached, taken through unchanged so an attachment nobody has seen before
+ * still arrives under its own name instead of collapsing into `unknown`. */
+const SystemAttachment = item(Type.String({ pattern: "^system:attachment:[A-Za-z0-9_.-]+$" }), {
+  attachment: Type.Record(Type.String(), Type.Unknown()),
+});
+
+/** What the reader could not place. It is still an item: a line that vanishes
+ * silently is the one failure a dump cannot be read around. */
+const SystemUnknown = item(Type.Literal("system:unknown"), {
+  record: Type.Record(Type.String(), Type.Unknown()),
+});
+
+// --- hook: code the operator installed ---
+
+/** `hook:<Event>` — the event alone, never the matcher. The name a hook runs
+ * under is `PreToolUse:Bash`, whose `:` would read as a level of the hierarchy
+ * and make `hook:PreToolUse` select nothing; the full name is a field instead,
+ * and prefix selection keeps meaning what it says. */
+const Hook = item(Type.String({ pattern: "^hook:[A-Za-z0-9_.-]+$" }), {
+  /** The hook's full name, matcher included. */
+  hook_name: Type.String(),
+  outcome: Type.Union([
+    Type.Literal("additionalContext"),
+    Type.Literal("output"),
+    Type.Literal("block"),
+  ]),
+  content: Type.Optional(Text),
+  command: Type.Optional(Type.String()),
+  exit_code: Type.Optional(Type.Integer()),
+  stderr: Type.Optional(Type.String()),
+  duration_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+  /** The call the hook fired around, for the events that have one. */
+  tool_use_id: Type.Optional(Type.String()),
+});
+
+// --- tool: `tool:<Name>`, one item for the call and one for the result ---
+
+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}`), {
+    ...USE_FIELDS,
+    tool_use_id: Type.String(),
+    ...fields,
+  });
+}
+
+function toolResult(name: string, fields: Record<string, TSchema>): TSchema {
+  return item(Type.Literal(`tool:${name}`), {
+    ...RESULT_FIELDS,
+    tool_use_id: Type.String(),
+    ...fields,
+  });
+}
+
+const OptText = Type.Optional(Text);
+const OptCount = Type.Optional(Type.Integer({ minimum: 0 }));
+
+/** A tool nobody wrote fields for still arrives, carrying what it was called
+ * with and what it answered. Fields are added to sharpen how a tool reads, not
+ * to decide whether it is kept. */
+const ToolUseGeneric = item(ToolType, {
+  ...USE_FIELDS,
+  tool_use_id: Type.String(),
+  input: Type.Record(Type.String(), Type.Unknown()),
+});
+const ToolResultGeneric = item(ToolType, {
+  ...RESULT_FIELDS,
+  tool_use_id: Type.String(),
+  result: Type.Record(Type.String(), Type.Unknown()),
+});
+
+const TOOL_ITEMS: TSchema[] = [
+  /** 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 }),
+  toolResult("Bash", {
+    stdout: OptText,
+    stderr: OptText,
+    interrupted: Type.Optional(Type.Boolean()),
+  }),
+  toolUse("Read", {
+    file_path: Type.String(),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    limit: OptCount,
+  }),
+  toolResult("Read", { lines: OptCount, bytes: OptCount }),
+  toolUse("Write", { file_path: Type.String(), lines: OptCount }),
+  toolResult("Write", { ok: Type.Boolean() }),
+  /** The bodies are counted rather than carried: an edit's two sides are the
+   * file's content, and a dump that inlined them would be the file. */
+  toolUse("Edit", {
+    file_path: Type.String(),
+    old_lines: OptCount,
+    new_lines: OptCount,
+  }),
+  toolResult("Edit", { ok: Type.Boolean() }),
+  toolUse("Grep", { pattern: Type.String(), path: OptText }),
+  toolResult("Grep", { matches: OptCount }),
+  toolUse("Glob", { pattern: Type.String(), path: OptText }),
+  toolResult("Glob", { matches: OptCount }),
+  toolUse("WebFetch", { url: Type.String(), prompt: OptText }),
+  toolResult("WebFetch", { text: OptText }),
+  toolUse("WebSearch", { query: Type.String() }),
+  toolResult("WebSearch", { results: OptCount }),
+  /** The same exchange `message:sub:*` carries, seen from the calling side:
+   * this pair states that an agent was started and how it ended, and what it
+   * answered stays with the message. */
+  toolUse("Agent", {
+    prompt: Type.String(),
+    name: OptText,
+    subagent_type: OptText,
+    description: OptText,
+  }),
+  toolResult("Agent", { agent_id: OptText, status: OptText }),
+  toolUse("SendMessage", { to: Type.String(), summary: OptText }),
+  toolResult("SendMessage", { msg_id: OptText, routing: OptText }),
+  toolUse("Monitor", {
+    description: Type.String(),
+    command: OptText,
+    persistent: Type.Optional(Type.Boolean()),
+    timeout_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+  }),
+  toolResult("Monitor", { task_id: OptText }),
+  toolUse("Skill", { skill: Type.String(), args: OptText }),
+  toolResult("Skill", {
+    agent_id: OptText,
+    background: Type.Optional(Type.Boolean()),
+    status: OptText,
+  }),
+  toolUse("TodoWrite", {
+    todos: Type.Array(Type.Object({ content: Type.String(), status: Type.String() })),
+  }),
+  toolResult("TodoWrite", { ok: Type.Boolean() }),
+  toolUse("TaskStop", { task_id: Type.String() }),
+  toolResult("TaskStop", { ok: Type.Boolean() }),
+  toolUse("CronCreate", { cron: Type.String(), prompt: OptText }),
+  toolResult("CronCreate", { cron_id: OptText }),
+];
+
+/** One classified item.
+ *
+ * Items are finer than lines: one assistant record becomes the thinking, the
+ * text and each tool call it held. A reader that does not recognise a record
+ * still emits one — as a tool it has no fields for, an attachment under its own
+ * kind, or `system:unknown` — so nothing in the file goes missing without
+ * saying so. */
+export const TranscriptItem = Type.Union(
+  [
+    MessageUserIn,
+    MessageUserOut,
+    MessageSubOut,
+    MessageSubIn,
+    MessageSessionOut,
+    MessageSessionIn,
+    Thinking,
+    NoticeSlash,
+    NoticeInterrupt,
+    SystemCompact,
+    SystemApiError,
+    SystemTask,
+    SystemCaveat,
+    SystemResume,
+    SystemAttachment,
+    SystemUnknown,
+    Hook,
+    ...TOOL_ITEMS,
+    ToolUseGeneric,
+    ToolResultGeneric,
+  ],
+  { $id: "TranscriptItem" },
+);
+export type TranscriptItem = Static<typeof TranscriptItem>;
+
+/** What kind of thing an id names. An id says how to point at something, not
+ * what a line is, which is why these are gathered rather than made types of
+ * their own — the same agent would otherwise appear once as an item and again
+ * as an id. */
+export const DumpIdKind = Type.Union(
+  [
+    Type.Literal("agent"),
+    Type.Literal("task"),
+    Type.Literal("tool_use"),
+    Type.Literal("msg"),
+    Type.Literal("sid"),
+    Type.Literal("cron"),
+  ],
+  { $id: "DumpIdKind" },
+);
+export type DumpIdKind = Static<typeof DumpIdKind>;
+
+export const DumpIdEntry = Type.Object(
+  {
+    kind: DumpIdKind,
+    id: Type.String({ minLength: 1 }),
+    /** What the id was called where it appeared — an agent's name, a monitor's
+     * description, a peer's working directory. */
+    label: Type.Optional(Type.String()),
+    /** Where it stood when the dump was written, for the ids that end. */
+    status: Type.Optional(Type.String()),
+    duration_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+  },
+  { $id: "DumpIdEntry" },
+);
+export type DumpIdEntry = Static<typeof DumpIdEntry>;
+
+/** The ids the dumped items carried, gathered once.
+ *
+ * The ledger is what a reader descends by: an agent that did the thing worth
+ * copying is named here, and dumping it is the same request with that id as its
+ * subject. It is relative to the subject, so an agent's ledger lists the agents
+ * it started and not itself. */
+export const DumpIds = Type.Array(DumpIdEntry, { $id: "DumpIds" });
+export type DumpIds = Static<typeof DumpIds>;
+
+/** A selection an operator named and can ask for by name.
+ *
+ * Presets are configured on the instance rather than fixed here, because what
+ * they name is an interest — "how the work was done", "what to hand over" —
+ * and an interest is not a property of the wire. A type name stays one to one
+ * with what a record is, and the groupings people actually reach for are made
+ * by naming a set of them. */
+export const DumpPreset = Type.Object(
+  {
+    name: Type.String({ minLength: 1 }),
+    description: Type.Optional(Type.String()),
+    opts: Type.Object({ types: Type.Array(TranscriptItemSelector) }),
+  },
+  { $id: "DumpPreset" },
+);
+export type DumpPreset = Static<typeof DumpPreset>;
+
+/** Reads the presets an instance is configured with.
+ *
+ * Nothing else states which names a dump may be asked for, so a client with no
+ * way to list them could only offer a free-text field and let the instance
+ * refuse. A preset that references another is answered as written; the
+ * expansion, and the refusal of a cycle or of a name that is not configured,
+ * happen where the config is validated. */
+export const DumpPresetsReadArgs = Type.Object({});
+export type DumpPresetsReadArgs = Static<typeof DumpPresetsReadArgs>;
+
+export const DumpPresetsReadResult = Type.Object({
+  /** In configured order. */
+  presets: Type.Array(DumpPreset),
+});
+export type DumpPresetsReadResult = Static<typeof DumpPresetsReadResult>;
+
+export const DumpPresetsReadRequest = request("dump_presets_read", DumpPresetsReadArgs);
+export const DumpPresetsReadResponse = response("dump_presets_read", DumpPresetsReadResult);

package/src/control/session.ts

@@ -1,6 +1,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response } from "../envelope.ts";
 import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
+import { DumpIds, TranscriptItemSelector, TranscriptItemType } from "./dump.ts";
 
 /** Ends the OS process behind a session.
  *
@@ -173,6 +174,13 @@ export const SessionSearchResponse = response("session_search", SessionSearchRes
  * destination is the instance's own data directory. */
 export const SessionDumpWriteArgs = Type.Object({
   sid: Sid,
+  /** Dump one agent below the session instead of the session itself, naming it
+   * as the transcript's own file does. The subject decides what every item
+   * type points at, so the same selection reads an agent's work the way it
+   * reads the session's. Kept beside `sid` rather than spelled into it: `sid`
+   * is validated as a sid, and a single joined string would be neither
+   * validated nor parsed anywhere but in the instance. */
+  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
@@ -181,9 +189,19 @@ export const SessionDumpWriteArgs = Type.Object({
   since_uuid: Type.Optional(Type.String()),
   until_at: Type.Optional(Timestamp),
   until_uuid: Type.Optional(Type.String()),
-  /** Leave out the assistant's thinking blocks. */
+  /** Which item types to keep, applied left to right over the whole range.
+   * Absent keeps everything but the attachments. */
+  types: Type.Optional(Type.Array(TranscriptItemSelector)),
+  /** A preset configured on the instance, used as the ground `types` is then
+   * applied over. A name the instance does not have is refused rather than
+   * ignored, since a dump silently wider than asked for is the failure a
+   * selection exists to prevent. */
+  preset: Type.Optional(Type.String({ minLength: 1 })),
+  /** Leave out the assistant's thinking blocks. `["-thinking"]` says the same
+   * thing in the vocabulary the rest of the selection is written in. */
   no_thinking: Type.Optional(Type.Boolean()),
-  /** Leave out the machinery of in-process agents. */
+  /** Leave out the machinery of in-process agents, which
+   * `["-message:sub", "-tool:Agent"]` also says. */
   no_agent: Type.Optional(Type.Boolean()),
 });
 export type SessionDumpWriteArgs = Static<typeof SessionDumpWriteArgs>;
@@ -192,7 +210,13 @@ export const SessionDumpWriteResult = Type.Object({
   /** Absolute path on the writing instance's host. */
   path: Type.String(),
   instance: InstanceId,
-  entries: Type.Integer({ minimum: 0 }),
+  /** How many items of each type were written, keyed by type name. A single
+   * total leaves the caller unable to tell a dump that kept what it asked for
+   * from one whose selection matched almost nothing. */
+  entries: Type.Record(TranscriptItemType, Type.Integer({ minimum: 0 })),
+  /** The ids those items carried, so the next dump — of an agent named here —
+   * can be asked for without opening the file. */
+  ids: DumpIds,
   bytes: Type.Integer({ minimum: 0 }),
 });
 export type SessionDumpWriteResult = Static<typeof SessionDumpWriteResult>;

package/src/fixtures/common.ts

@@ -79,6 +79,7 @@ export const HELLO_RESPONSE: Static<typeof HelloResponse> = {
     { id: other_instance, endpoint: other_endpoint, host: "nuc", reachable: false },
   ],
   capabilities: ["fork", "launcher", "terminal"],
+  terminal_gateway: "https://mba.example.ts.net/hyoui",
   version: "0.1.0",
   started_at: FIXTURE_NOW - 3_600_000,
 };

package/src/fixtures/control.ts

@@ -45,6 +45,11 @@ import type {
   SandboxRevokeRequest,
   SandboxRevokeResponse,
 } from "../control/sandbox.ts";
+import type {
+  DumpPresetsReadRequest,
+  DumpPresetsReadResponse,
+  TranscriptItem,
+} from "../control/dump.ts";
 import type {
   SessionDumpWriteRequest,
   SessionDumpWriteResponse,
@@ -149,8 +154,10 @@ export const SESSION_DUMP_WRITE_REQUEST: Static<typeof SessionDumpWriteRequest>
   request_id,
   op: "session_dump_write",
   sid,
+  agent_id: "a471372f2",
   since_at: FIXTURE_NOW - 3_600_000,
-  no_thinking: true,
+  preset: "howto",
+  types: ["@file", "-tool:Grep", "thinking"],
 };
 
 export const SESSION_DUMP_WRITE_RESPONSE: Static<typeof SessionDumpWriteResponse> = {
@@ -158,10 +165,104 @@ export const SESSION_DUMP_WRITE_RESPONSE: Static<typeof SessionDumpWriteResponse
   request_id,
   path: "/transcripts/6f1a2b3c.dump.md",
   instance,
-  entries: 128,
+  entries: { thinking: 41, "tool:Bash": 62, "tool:Read": 25 },
+  ids: [
+    {
+      kind: "agent",
+      id: "a471372f2",
+      label: "dump-kinds-design",
+      status: "ok",
+      duration_ms: 252_000,
+    },
+    { kind: "task", id: "b6mmcr0ax", label: "just watch", status: "running" },
+    { kind: "sid", id: other_sid, label: "ccmsg-webui/main" },
+  ],
   bytes: 65_536,
 };
 
+export const DUMP_PRESETS_READ_REQUEST: Static<typeof DumpPresetsReadRequest> = {
+  request_id,
+  op: "dump_presets_read",
+};
+
+export const DUMP_PRESETS_READ_RESPONSE: Static<typeof DumpPresetsReadResponse> = {
+  ok: true,
+  request_id,
+  presets: [
+    {
+      name: "file",
+      description: "reading, writing and searching, as one interest",
+      opts: { types: ["tool:Read", "tool:Write", "tool:Edit", "tool:Glob", "tool:Grep"] },
+    },
+    {
+      name: "howto",
+      description: "how the work was done: what was thought, run, read and written",
+      opts: { types: ["thinking", "message:user", "message:sub", "tool:Bash", "@file"] },
+    },
+  ],
+};
+
+/** One item of several types, as a reader emits them.
+ *
+ * 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. */
+export const TRANSCRIPT_ITEMS: Static<typeof TranscriptItem>[] = [
+  {
+    uuid: "3f9a21c4",
+    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",
+    type: "tool:Bash",
+    at: FIXTURE_NOW - 3_400_000,
+    role: "use",
+    tool_use_id: "toolu_01Ne9BDS",
+    result_item: "18d6f2c9",
+    command: "jq -r '.type' session.jsonl | sort | uniq -c",
+    description: "count the record types",
+  },
+  {
+    uuid: "18d6f2c9",
+    type: "tool:Bash",
+    at: FIXTURE_NOW - 3_399_000,
+    role: "result",
+    tool_use_id: "toolu_01Ne9BDS",
+    parent_item: "07c5e1b8",
+    stdout: "1174 assistant\n753 user\n",
+    interrupted: false,
+  },
+  {
+    uuid: "b7e41d09",
+    type: "message:sub:out",
+    at: FIXTURE_NOW - 3_300_000,
+    role: "use",
+    result_item: "c2d80f16",
+    prompt: "docs/design/dump-kinds.md を書き直す",
+    agent_id: "a471372f2",
+    subagent_type: "opus5-worker-high",
+  },
+  {
+    uuid: "92e6d4f5",
+    type: "hook:PreToolUse",
+    at: FIXTURE_NOW - 3_200_000,
+    hook_name: "PreToolUse:Bash",
+    outcome: "additionalContext",
+    content: "read コマンドを使うこと",
+    tool_use_id: "toolu_01Ne9BDS",
+  },
+  {
+    uuid: "81d5c3e4",
+    type: "system:attachment:queued_command",
+    at: FIXTURE_NOW - 3_100_000,
+    attachment: { type: "queued_command", command: "/pre-clear" },
+  },
+];
+
 export const TRANSCRIPT_READ_REQUEST: Static<typeof TranscriptReadRequest> = {
   request_id,
   op: "transcript_read",

package/src/fixtures/index.ts

@@ -92,6 +92,10 @@ export const OP_FIXTURES = {
     request: control.SESSION_DUMP_WRITE_REQUEST,
     response: control.SESSION_DUMP_WRITE_RESPONSE,
   },
+  dump_presets_read: {
+    request: control.DUMP_PRESETS_READ_REQUEST,
+    response: control.DUMP_PRESETS_READ_RESPONSE,
+  },
   transcript_read: {
     request: control.TRANSCRIPT_READ_REQUEST,
     response: control.TRANSCRIPT_READ_RESPONSE,

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./common/ping.ts";
 export * from "./common/shutdown.ts";
 export * from "./common/topics.ts";
 export * from "./control/agents.ts";
+export * from "./control/dump.ts";
 export * from "./control/files.ts";
 export * from "./control/kv.ts";
 export * from "./control/launcher.ts";

package/src/schemas.ts

@@ -33,6 +33,7 @@ import {
   TopicUnsubscribeResponse,
 } from "./common/topics.ts";
 import { AgentsFrame } from "./control/agents.ts";
+import { DumpPresetsReadRequest, DumpPresetsReadResponse } from "./control/dump.ts";
 import {
   DirListRequest,
   DirListResponse,
@@ -150,6 +151,7 @@ export const OP_SCHEMAS: Record<OpName, OpSchemas> = {
   session_env_read: { request: SessionEnvReadRequest, response: SessionEnvReadResponse },
   session_search: { request: SessionSearchRequest, response: SessionSearchResponse },
   session_dump_write: { request: SessionDumpWriteRequest, response: SessionDumpWriteResponse },
+  dump_presets_read: { request: DumpPresetsReadRequest, response: DumpPresetsReadResponse },
   transcript_read: { request: TranscriptReadRequest, response: TranscriptReadResponse },
   session_fork_origin: { request: SessionForkOriginRequest, response: SessionForkOriginResponse },
   session_last_live_remove: {