@ccmsg/cli 0.3.5 → 0.4.2

package/src/sessions/dump.ts

@@ -1,25 +1,47 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import type { InstanceId, SessionDumpWriteArgs, SessionDumpWriteResult } from "@ccmsg/protocol";
+import type {
+  DumpPreset,
+  InstanceId,
+  SessionDumpFile,
+  SessionDumpWriteArgs,
+  SessionDumpWriteResult,
+} from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
-import { readRecord, type TranscriptFiles, type TranscriptRecord } from "../transcript/index.ts";
+import { classify, type Item, ledger, select, selection } from "../transcript/items/index.ts";
+import type { TranscriptFiles } from "../transcript/index.ts";
 
 /** Where dumps land: one directory under this instance's own state, named
  * after the config home it answers for like every other per-instance path
  * (§8.1). The caller never supplies a path, so there is none to contain. */
 export const DUMPS = "dumps";
 
+/** What a dump file is called. Two extensions rather than one so that a reader
+ * knows both that it is JSON and that it is JSON of a shape the contract
+ * states — the file travels by its path, outliving the request that made it,
+ * and is opened by whoever was handed that path. */
+export const DUMP_SUFFIX = ".dump.json";
+
 export interface DumpDeps {
   readonly self: InstanceId;
   readonly stateDir: string;
   readonly files: TranscriptFiles;
+  /** The selections this instance is configured with, which is what a `preset`
+   * name and an `@name` inside a selection are resolved against. */
+  readonly presets: readonly DumpPreset[];
 }
 
 /** Write a session's dump and answer with where it went.
  *
  * What this adds over reading the transcript is a durable artifact whose path
  * can be handed to a successor session, rather than a payload that would
- * travel out through a client and back in again. */
+ * travel out through a client and back in again.
+ *
+ * The subject is the session, or one agent below it when the request names
+ * one. Every item type is read from wherever the subject stands — an agent's
+ * `message:user:in` is the brief its parent gave it — so one selection carries
+ * unchanged down a chain of agents, which is what makes the ledger's agent ids
+ * a way to descend rather than just a list. */
 export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDumpWriteResult {
   if (args.since_at !== undefined && args.since_uuid !== undefined) {
     throw new OpError("invalid_args", "a lower bound is a time or a record, not both");
@@ -27,79 +49,95 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
   if (args.until_at !== undefined && args.until_uuid !== undefined) {
     throw new OpError("invalid_args", "an upper bound is a time or a record, not both");
   }
-  const file = deps.files.session(args.sid);
+  const preset = presetFor(args.preset, deps.presets);
+  const file = deps.files.locate(
+    args.sid,
+    args.agent_id === undefined ? {} : { agent_id: args.agent_id },
+  );
   let text: string;
   try {
     text = readFileSync(file, "utf8");
   } catch {
     throw new OpError("not_found", `the transcript of ${args.sid} could not be read`);
   }
-  const entries = collect(text, args);
-  const document = {
+  // The whole file is classified before the range is applied, so a result
+  // inside the range still names the call that fell before it. Cutting first
+  // would leave `parent_item` pointing at something the reader never saw.
+  const keep = selection(
+    {
+      ...(args.types === undefined ? {} : { types: args.types }),
+      ...(preset === undefined ? {} : { preset }),
+      ...(args.no_thinking === undefined ? {} : { no_thinking: args.no_thinking }),
+      ...(args.no_agent === undefined ? {} : { no_agent: args.no_agent }),
+    },
+    deps.presets,
+  );
+  const { items, entries } = select(within(classify(text.split("\n")), args), keep);
+  const ids = ledger(items);
+  const written_at = Date.now();
+  // The file repeats what it was asked for. A dump outlives the request that
+  // made it and is read by whoever was handed the path, so it has to say on
+  // its own what it is a dump of and what was left out — which is why the
+  // selection is written as applied, with the presets already expanded.
+  const document: SessionDumpFile = {
     sid: args.sid,
-    instance: deps.self,
-    source: file,
-    generated_at: Date.now(),
-    entries,
+    ...(args.agent_id === undefined ? {} : { agent_id: args.agent_id }),
+    written_at,
+    types: [...keep.elements],
+    items,
+    ids,
   };
   const dir = join(deps.stateDir, DUMPS);
   mkdirSync(dir, { recursive: true });
-  const path = join(dir, `${args.sid}-${document.generated_at}.json`);
+  const named = args.agent_id === undefined ? args.sid : `${args.sid}-agent-${args.agent_id}`;
+  const path = join(dir, `${named}-${written_at}${DUMP_SUFFIX}`);
   const body = `${JSON.stringify(document, undefined, 2)}\n`;
   writeFileSync(path, body);
-  return {
-    path,
-    instance: deps.self,
-    entries: entries.length,
-    bytes: Buffer.byteLength(body),
-  };
+  return { path, instance: deps.self, entries, ids, bytes: Buffer.byteLength(body) };
 }
 
-/** One record of a dump: what was said, by whom, when.
+/** The named selection a request asked for.
  *
- * The fields are the record's own, taken from the type that reads a transcript
- * line rather than restated here — a dump reports what was read, and a second
- * spelling of those fields would be a second interpretation of the file. */
-type DumpEntry = Pick<TranscriptRecord, "uuid" | "said_at" | "said_by" | "text" | "thinking">;
+ * A name this instance does not have is refused rather than ignored: a dump
+ * silently wider than what was asked for is the failure a selection exists to
+ * prevent. */
+function presetFor(
+  name: string | undefined,
+  presets: readonly DumpPreset[],
+): DumpPreset | undefined {
+  if (name === undefined) return undefined;
+  const found = presets.find((one) => one.name === name);
+  if (found === undefined) throw new OpError("invalid_args", `no preset is configured as ${name}`);
+  return found;
+}
 
-/** The records within the bounds, in the order the transcript holds them.
+/** The items within the bounds, in the order the transcript holds them.
  *
  * A record bound cuts at that record's position rather than at its clock, so
  * records sharing an instant stay on their own side of the cut — which is the
- * whole reason the contract offers both kinds of bound. */
-function collect(text: string, args: SessionDumpWriteArgs): DumpEntry[] {
-  const entries: DumpEntry[] = [];
-  // A lower bound by record starts the dump closed: it opens at the record it
-  // names, which is included.
+ * whole reason the contract offers both kinds of bound. Every item a record
+ * became carries that record's id, so a bound by record keeps a turn's
+ * thinking, words and calls together. */
+function within(items: readonly Item[], args: SessionDumpWriteArgs): Item[] {
+  const kept: Item[] = [];
+  // A lower bound by record starts closed: it opens at the record it names,
+  // which is included.
   let open = args.since_uuid === undefined;
-  for (const line of text.split("\n")) {
-    if (line === "") continue;
-    const record = readRecord(line);
-    if (record === undefined) continue;
+  for (let at = 0; at < items.length; at += 1) {
+    const item = items[at];
+    if (item === undefined) continue;
     if (!open) {
-      if (record.uuid !== args.since_uuid) continue;
+      if (item.uuid !== args.since_uuid) continue;
       open = true;
     }
-    if (args.since_at !== undefined && (record.said_at ?? 0) < args.since_at) continue;
-    if (args.until_at !== undefined && (record.said_at ?? 0) > args.until_at) break;
-    // The machinery of in-process agents: their turns interleave into the
-    // session's own file, and a successor resuming the session is resuming the
-    // session rather than them.
-    if (args.no_agent === true && record.sidechain) {
-      if (record.uuid !== undefined && record.uuid === args.until_uuid) break;
-      continue;
+    if (args.since_at !== undefined && item.at < args.since_at) continue;
+    if (args.until_at !== undefined && item.at > args.until_at) break;
+    kept.push(item);
+    // An upper bound by record is inclusive and cuts after the last item that
+    // record became, so the rest of the same record is still let through.
+    if (args.until_uuid !== undefined && item.uuid === args.until_uuid) {
+      if (items[at + 1]?.uuid !== item.uuid) break;
     }
-    entries.push({
-      ...(record.uuid === undefined ? {} : { uuid: record.uuid }),
-      ...(record.said_at === undefined ? {} : { said_at: record.said_at }),
-      ...(record.said_by === undefined ? {} : { said_by: record.said_by }),
-      ...(record.text === undefined ? {} : { text: record.text }),
-      ...(args.no_thinking === true || record.thinking === undefined
-        ? {}
-        : { thinking: record.thinking }),
-    });
-    // An upper bound by record is inclusive, so the cut is after it.
-    if (record.uuid !== undefined && record.uuid === args.until_uuid) break;
   }
-  return entries;
+  return kept;
 }

package/src/sessions/handlers.ts

@@ -1,5 +1,7 @@
 import {
   type Capability,
+  type DumpPreset,
+  type DumpPresetsReadResult,
   type InstanceId,
   type SessionDumpWriteArgs,
   type SessionEnvReadArgs,
@@ -57,9 +59,11 @@ export interface SessionOpsDeps {
    * instance last saw them. The sessions domain owns the list; this op only
    * asks it to forget a row. */
   readonly forget: (sid: Sid) => boolean;
+  /** The named selections this instance is configured with (§3.6). */
+  readonly presets: readonly DumpPreset[];
 }
 
-/** The eight ops that observe and operate on sessions.
+/** The ops that observe and operate on sessions.
  *
  * None of them decides who may call it: dispatch has settled that from the
  * attribute table. The one that narrows by role is `transcript_read`, and it
@@ -104,8 +108,17 @@ export function sessionHandlers(deps: SessionOpsDeps) {
         self: deps.self,
         stateDir: deps.stateDir,
         files: deps.files,
+        presets: deps.presets,
       }),
 
+    /** Which selections a dump may be asked for by name.
+     *
+     * Nothing else states them, so a client without this 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, happen where the config is read. */
+    dump_presets_read: (): DumpPresetsReadResult => ({ presets: [...deps.presets] }),
+
     session_fork_origin: (input: HandlerInput): SessionForkOriginResult => {
       const args = input.args as unknown as SessionForkOriginArgs;
       const origin = forkOrigin(args.sid, deps.files);

package/src/sessions/index.ts

@@ -1,5 +1,5 @@
 export * from "./classify.ts";
-export { DUMPS, dumpWrite } from "./dump.ts";
+export { DUMP_SUFFIX, DUMPS, dumpWrite } from "./dump.ts";
 export { forkOrigin } from "./fork.ts";
 export * from "./harness.ts";
 export { sessionCapabilities, sessionHandlers, type SessionOpsDeps } from "./handlers.ts";

package/src/transcript/items/classify.ts

@@ -0,0 +1,400 @@
+import type { Item } from "./item.ts";
+import { count, instant, isRow, list, optional, type Row, row, str, tagged } from "./record.ts";
+import { genericResult, resultFields, useFields } from "./tools.ts";
+
+/** Turning a harness's transcript into the items the contract names.
+ *
+ * The contract writes down the type names and what an item of each type
+ * carries, and says nothing about the file: the file is the harness's own, it
+ * changes without asking, and reading it is this instance's work (§3.8). So
+ * everything that knows what a line looks like is here, and what leaves is
+ * only ever an item.
+ *
+ * Items are finer than lines. One assistant record holds the thinking, the
+ * words and each tool call of a turn, and each of those is its own item — the
+ * unit a reader selects and draws by is the thing that happened, not the line
+ * the harness happened to write it on.
+ *
+ * Nothing is dropped for being unrecognised. A tool nobody wrote fields for
+ * arrives with what it was called with, an attachment arrives under its own
+ * kind, and a record that fits nothing arrives as `system:unknown`. The one
+ * failure a dump cannot be read around is a line that vanished quietly. */
+
+/** Record types that are the interface and the session's own bookkeeping
+ * rather than anything that was said or done: the current mode, the title as
+ * it was retitled, the queue, the file-history snapshots the editor keeps.
+ *
+ * They are the bulk of a transcript — more than a third of the lines in the
+ * sessions this was measured against — and none of them is an event a reader
+ * of a dump is looking for. */
+const NOT_ITEMS = new Set([
+  "mode",
+  "permission-mode",
+  "atis-latch",
+  "ai-title",
+  "custom-title",
+  "last-prompt",
+  "queue-operation",
+  "cost-state",
+  "file-history-snapshot",
+  "file-history-delta",
+  "bridge-session",
+  "progress",
+  "summary",
+]);
+
+/** What an item is under construction: the contract's shape, before it is
+ * settled. A call learns the id of what answered it only when the answer
+ * arrives, which is why these are written to after they are made. */
+type Draft = Record<string, unknown> & { uuid: string; type: string; at: number };
+
+/** A whole transcript read as items, in the order the file holds them.
+ *
+ * The file is read through once and the links are filled in as the answers
+ * arrive, so a call and its result point at each other however many turns
+ * apart the harness wrote them. Reading the whole file before any range is
+ * applied is what makes `parent_item` answerable: a result inside the range
+ * whose call fell before it still names the call. */
+export function classify(lines: Iterable<string>): Item[] {
+  const state = new Classification();
+  for (const line of lines) {
+    if (line === "") continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (isRow(parsed)) state.read(parsed);
+  }
+  return state.items;
+}
+
+class Classification {
+  readonly items: Draft[] = [];
+  /** The call each tool result belongs to, by the id the harness pairs them
+   * with. Holds the `tool:*` item and, for an `Agent` call, the
+   * `message:sub:out` beside it — the same exchange seen from the two sides
+   * the contract names it from. */
+  readonly #calls = new Map<string, { tool: Draft; message?: Draft; name: string }>();
+  #turn = 0;
+  /** The last slash command invoked, which is what its output belongs to. */
+  #slash: string | undefined;
+
+  read(record: Row): void {
+    const type = str(record["type"]);
+    if (type === undefined || NOT_ITEMS.has(type)) return;
+    const uuid = str(record["uuid"]) ?? "";
+    if (uuid === "") return;
+    const at = instant(record["timestamp"]);
+    const make = (kind: string, fields: Record<string, unknown> = {}): Draft => {
+      const draft: Draft = { uuid, type: kind, at, turn: this.#turn, ...fields };
+      this.items.push(draft);
+      return draft;
+    };
+    if (type === "attachment") return this.#attachment(record, make);
+    if (type === "system") return this.#system(record, make);
+    if (type === "assistant") return this.#assistant(record, make);
+    if (type === "user") return this.#user(record, make);
+    make("system:unknown", { record });
+  }
+
+  /** An attachment is either the operator's own code speaking or the harness
+   * attaching something to a turn, and the two are kept apart because a reader
+   * cares about them for opposite reasons. */
+  #attachment(record: Row, make: Make): void {
+    const attachment = row(record["attachment"]) ?? {};
+    const kind = str(attachment["type"]);
+    if (kind === "hook_additional_context" || kind === "hook_success") {
+      const name = str(attachment["hookName"]) ?? "";
+      // The event alone is the type. A hook runs under `PreToolUse:Bash`,
+      // whose `:` would read as another level of the hierarchy and leave
+      // `hook:PreToolUse` selecting nothing.
+      const event = str(attachment["hookEvent"]) ?? name.split(":")[0] ?? "";
+      make(`hook:${segment(event)}`, {
+        hook_name: name,
+        outcome: kind === "hook_success" ? "output" : "additionalContext",
+        ...optional("content", text(attachment["content"])),
+        ...optional("command", str(attachment["command"])),
+        ...optional("exit_code", count(attachment["exitCode"])),
+        ...optional("stderr", str(attachment["stderr"])),
+        ...optional("duration_ms", count(attachment["durationMs"])),
+        ...optional("tool_use_id", str(attachment["toolUseID"])),
+      });
+      return;
+    }
+    make(`system:attachment:${segment(kind ?? "unknown")}`, { attachment });
+  }
+
+  /** The harness files a slash command's output as a line of its own, which
+   * says what came out and not what was run. The command it belongs to is the
+   * one that was just invoked — the harness writes the two together — so the
+   * output is reported under that name rather than under none. */
+  #system(record: Row, make: Make): void {
+    if (str(record["subtype"]) === "local_command") {
+      const content = str(record["content"]) ?? "";
+      make("notice:slash", {
+        command: this.#slash ?? "",
+        ...optional("stdout", tagged(content, "local-command-stdout") ?? content),
+      });
+      return;
+    }
+    make("system:unknown", { record });
+  }
+
+  #assistant(record: Row, make: Make): void {
+    const message = row(record["message"]) ?? {};
+    if (record["isApiErrorMessage"] === true) {
+      make("system:api-error", { text: text(message["content"]) ?? "" });
+      return;
+    }
+    for (const block of list(message["content"])) {
+      const fields = row(block);
+      if (fields === undefined) continue;
+      const kind = str(fields["type"]);
+      if (kind === "thinking") {
+        const thought = str(fields["thinking"])?.trim();
+        if (thought !== undefined && thought !== "") make("thinking", { text: thought });
+        continue;
+      }
+      if (kind === "text") {
+        const said = str(fields["text"])?.trim();
+        if (said !== undefined && said !== "") make("message:user:out", { text: said });
+        continue;
+      }
+      if (kind === "tool_use") this.#call(fields, make);
+    }
+  }
+
+  /** One tool call, and — where the call is one session addressing another
+   * mind — the message it also is.
+   *
+   * `Agent` is always both: the pair states that an agent was started and how
+   * it ended, and the brief it was given and what it answered are the message
+   * beside it. `SendMessage` and a `ccmsg` command are one or the other by
+   * whom they are addressed to. */
+  #call(block: Row, make: Make): void {
+    const name = str(block["name"]) ?? "";
+    const id = str(block["id"]) ?? "";
+    const input = row(block["input"]) ?? {};
+    const fields = useFields(name, input);
+    const tool = make(`tool:${segment(name)}`, {
+      role: "use",
+      tool_use_id: id,
+      ...(fields ?? { input }),
+    });
+    let message: Draft | undefined;
+    if (name === "Agent") {
+      message = make("message:sub:out", {
+        role: "use",
+        prompt: str(input["prompt"]) ?? "",
+        ...optional("subagent_type", str(input["subagent_type"])),
+        ...optional("name", str(input["name"])),
+        ...optional("description", str(input["description"])),
+      });
+    } else if (name === "SendMessage") {
+      const to = str(input["to"]) ?? "";
+      // A sid is the harness's own uuid; anything else is a name, and a name
+      // is how an agent below this session is addressed.
+      make(addressed(to) ? "message:session:out" : "message:sub:out", {
+        ...(addressed(to) ? {} : { role: "use" }),
+        ...(addressed(to)
+          ? { text: text(input["message"]) ?? "", to }
+          : { prompt: text(input["message"]) ?? "", name: to }),
+      });
+    } else if (name === "Bash" && isCcmsgSend(str(input["command"]))) {
+      make("message:session:out", { text: str(input["command"]) ?? "" });
+    }
+    if (id !== "") this.#calls.set(id, { tool, name, ...optional("message", message) });
+  }
+
+  #user(record: Row, make: Make): void {
+    const message = row(record["message"]) ?? {};
+    const content = message["content"];
+    if (Array.isArray(content)) {
+      let said = "";
+      for (const block of list(content)) {
+        const fields = row(block);
+        if (fields === undefined) continue;
+        if (str(fields["type"]) === "tool_result") {
+          this.#answer(record, fields, make);
+          continue;
+        }
+        const part = str(fields["text"]);
+        if (part !== undefined) said += said === "" ? part : `\n${part}`;
+      }
+      if (said !== "") this.#said(record, said, make);
+      return;
+    }
+    const said = str(content);
+    if (said !== undefined) this.#said(record, said, make);
+  }
+
+  /** What came back from a tool call, linked to the call in both directions. */
+  #answer(record: Row, block: Row, make: Make): void {
+    const id = str(block["tool_use_id"]) ?? "";
+    const call = this.#calls.get(id);
+    const failed = block["is_error"] === true;
+    const answer = record["toolUseResult"];
+    const fields = resultFields(call?.name, answer, failed);
+    const item = make(`tool:${segment(call?.name ?? "unknown")}`, {
+      role: "result",
+      parent_item: call?.tool.uuid ?? id,
+      tool_use_id: id,
+      ...(fields ?? { result: genericResult(answer) }),
+    });
+    if (call === undefined) return;
+    call.tool["result_item"] = item.uuid;
+    // An agent's id is known only once it has started, so the message that
+    // asked for it learns its own id from the answer.
+    const result = row(answer);
+    const agent =
+      result === undefined ? undefined : (str(result["agentId"]) ?? str(result["agent_id"]));
+    if (call.message !== undefined && agent !== undefined) call.message["agent_id"] = agent;
+  }
+
+  /** A `type: "user"` line whose content is words rather than a tool's answer.
+   *
+   * Most of what wears this shape was not said by a person: the harness
+   * reports background tasks, compaction and its own caveats in the same
+   * place, and another session's message arrives inside an envelope. The
+   * person's own turn is what is left when none of those match — read last,
+   * so nothing the harness injected is mistaken for someone speaking. */
+  #said(record: Row, said: string, make: Make): void {
+    if (record["isCompactSummary"] === true) {
+      make("system:compact", { text: said });
+      return;
+    }
+    if (said.startsWith("<local-command-caveat>")) {
+      make("system:caveat", { text: said });
+      return;
+    }
+    const command = tagged(said, "command-name");
+    if (command !== undefined) {
+      this.#slash = command;
+      make("notice:slash", {
+        command,
+        ...optional("args", tagged(said, "command-args") ?? tagged(said, "command-message")),
+        ...optional("stdout", tagged(said, "local-command-stdout")),
+      });
+      return;
+    }
+    if (said.startsWith("[Request interrupted")) {
+      make("notice:interrupt", { text: said });
+      return;
+    }
+    if (said.startsWith("Resume the paused workflow by calling: Workflow({")) {
+      make("system:resume", { text: said });
+      return;
+    }
+    if (said.startsWith("<task-notification>")) {
+      this.#notification(said, make);
+      return;
+    }
+    // The record nothing else in the file is a reply to is the brief this
+    // transcript was opened with, whoever the subject is: a person's first
+    // words to a session, or the parent's instructions to an agent. An agent
+    // is briefed inside the same envelope another session's message arrives
+    // in, so this is read before that envelope is — from where the subject
+    // stands, being told what to do is not the same as being written to.
+    if (record["parentUuid"] === null) {
+      this.#turn += 1;
+      make("message:user:in", { text: said });
+      return;
+    }
+    if (said.includes("<cross-session-message") || said.includes("<teammate-message")) {
+      make("message:session:in", {
+        text: said,
+        ...optional("from", attribute(said, "from") ?? attribute(said, "teammate_id")),
+        ...optional("msg_id", attribute(said, "mid")),
+      });
+      return;
+    }
+    if (record["isMeta"] === true) {
+      make("system:unknown", { record });
+      return;
+    }
+    // A turn begins where a person speaks, which is the only place a dump can
+    // count turns from — the harness numbers nothing.
+    this.#turn += 1;
+    make("message:user:in", { text: said });
+  }
+
+  /** A background task reporting, or an agent handing back its answer.
+   *
+   * The two arrive in the same envelope and are told apart by what it holds: a
+   * `<result>` is an agent that finished, and everything else is an event from
+   * a monitor or a background command.
+   *
+   * What the answer belongs to is whichever call started the agent. An `Agent`
+   * call has a brief, so the answer is the other half of that message; a
+   * `Skill` run in the background has none, and the answer hangs off the call
+   * itself. Either way it is an agent answering and reads as one. */
+  #notification(said: string, make: Make): void {
+    const answer = tagged(said, "result");
+    const call = this.#calls.get(tagged(said, "tool-use-id") ?? "");
+    if (answer !== undefined && call !== undefined) {
+      const asked = call.message ?? call.tool;
+      const item = make("message:sub:in", {
+        role: "result",
+        parent_item: asked.uuid,
+        text: answer,
+        ...optional("agent_id", str(asked["agent_id"]) ?? tagged(said, "task-id")),
+        ...optional("status", tagged(said, "status")),
+        ...optional("duration_ms", count(Number(tagged(said, "duration_ms")))),
+      });
+      if (call.message !== undefined) call.message["result_item"] = item.uuid;
+      return;
+    }
+    make("system:task", {
+      text: said,
+      ...optional("task_id", tagged(said, "task-id")),
+      ...optional("event", tagged(said, "event") ?? tagged(said, "summary")),
+    });
+  }
+}
+
+type Make = (kind: string, fields?: Record<string, unknown>) => Draft;
+
+/** A session id as the harness writes one. What `SendMessage` addresses is
+ * either this — another session — or a name, which is an agent below this
+ * one. */
+const SID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function addressed(to: string): boolean {
+  return SID.test(to);
+}
+
+/** Whether a shell command is this session speaking to another one. */
+function isCcmsgSend(command: string | undefined): boolean {
+  if (command === undefined) return false;
+  return /\bccmsg\s+(post|reply)\b/.test(command);
+}
+
+/** One segment of a type name. The harness's own spellings pass through — they
+ * are what a reader matches against what it ran — and a character the name
+ * could not carry is replaced rather than the segment being refused, so a
+ * newcomer still arrives under something close to its own name. */
+function segment(name: string): string {
+  const cleaned = name.replace(/[^A-Za-z0-9_.-]/g, "-");
+  return cleaned === "" ? "unknown" : cleaned;
+}
+
+/** An attribute of one of the harness's envelope tags. */
+function attribute(said: string, name: string): string | undefined {
+  return new RegExp(`${name}="([^"]*)"`).exec(said)?.[1] || undefined;
+}
+
+/** A content field that is sometimes a string and sometimes the blocks of
+ * one. */
+function text(raw: unknown): string | undefined {
+  const found = str(raw);
+  if (found !== undefined) return found;
+  if (!Array.isArray(raw)) return undefined;
+  const parts = raw.flatMap((block) => {
+    const fields = row(block);
+    const part = fields === undefined ? str(block) : str(fields["text"]);
+    return part === undefined ? [] : [part];
+  });
+  return parts.length === 0 ? undefined : parts.join("\n");
+}