@ccmsg/cli 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",

package/src/cli.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env bun
-import { type MessageSendArgs, type NotifySendArgs, PROTOCOL_VERSION } from "@ccmsg/protocol";
+import {
+  type MessageSendArgs,
+  type NotifySendArgs,
+  PROTOCOL_VERSION,
+  type SessionDumpFile,
+  type SessionDumpWriteArgs,
+  type SessionDumpWriteResult,
+} from "@ccmsg/protocol";
 import {
   add as addToConfig,
   ask,
@@ -24,8 +31,10 @@ import {
   type Target,
   targetFor,
 } from "./daemon/index.ts";
+import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { document } from "./transcript/items/index.ts";
 import { currentSession, DEFAULT_HARNESS, HARNESS, HARNESSES, isHarness } from "./harness/index.ts";
 
 /** The variables a session is named by, for the help and for the message a
@@ -357,6 +366,40 @@ const ROOT: Command = {
       ],
       run: (args) => agents(args),
     },
+    {
+      name: "dump",
+      summary: "セッション (か配下の worker 1 体) の transcript を型ごとの表示で書き出す",
+      usage: "ccmsg dump <sid>[/agent-<id>] [--preset <名前>] [--types <選択>]",
+      options: [
+        ["--preset <名前>", "instance が持つ選択 (ccmsg dump presets で一覧)"],
+        ["--types <選択>", "型をカンマ区切りで。prefix 可、-で除外、@名前で preset 展開"],
+        ["--since <at|uuid>", "下限。時刻 (ISO か epoch ミリ秒) か record の uuid"],
+        ["--until <at|uuid>", "上限。同上"],
+        ["--max-chars <n>", "1 アイテムの本文をこの文字数で切る (既定は切らない)"],
+        ["--json", "markdown ではなく dump file の中身をそのまま出す"],
+        ["--out <path>", "標準出力ではなくこの path に書く"],
+      ],
+      notes: [
+        {
+          title: "別のセッションのやり方を読む:",
+          docs: [
+            ["1", "ccmsg dump <sid> --preset howto で親を読む"],
+            ["2", "末尾の ids 台帳から良さそうな worker の agent id を選ぶ"],
+            ["3", "ccmsg dump <sid>/agent-<id> --preset howto で主語を移して掘る"],
+          ],
+        },
+      ],
+      children: [
+        {
+          name: "presets",
+          summary: "この instance が持つ preset の名前と中身を並べる",
+          usage: "ccmsg dump presets",
+          bare: true,
+          run: () => instanceAsk({ op: "dump_presets_read" }),
+        },
+      ],
+      run: (args) => dump(args),
+    },
     {
       name: "post",
       summary: "別のセッションへメッセージを送る",
@@ -857,6 +900,115 @@ async function topic(
   }
 }
 
+/** `ccmsg dump <sid>[/agent-<id>]`: read how a session worked.
+ *
+ * The instance writes the file — it is the one that can read a transcript, and
+ * a path that outlives the request is the point of the op — and this reads it
+ * back and draws it. Which means the two halves stay where they belong: what
+ * an item is settled by whoever read the file, and how an item reads is
+ * settled here, where somebody is looking at it.
+ *
+ * `--json` hands over the file as it stands, for a reader that is a program. */
+async function dump(args: readonly string[]): Promise<unknown> {
+  const parsed = options(args, ["preset", "types", "since", "until", "out", "max-chars"], ["json"]);
+  const subject = parsed.rest[0];
+  if (subject === undefined) {
+    throw new CommandError(
+      "invalid_args",
+      "使い方: ccmsg dump <sid>[/agent-<id>] [--preset <名前>] [--types <選択>]",
+    );
+  }
+  const written = (await instanceAsk({
+    op: "session_dump_write",
+    ...dumpArgs(subject, parsed.named),
+  })) as unknown as SessionDumpWriteResult;
+  const body = readFileSync(written.path, "utf8");
+  const since = parsed.named.get("since");
+  const until = parsed.named.get("until");
+  const limit = parsed.named.get("max-chars");
+  const text = parsed.flags.has("json")
+    ? body
+    : document(JSON.parse(body) as SessionDumpFile, {
+        instance: written.instance,
+        ...(since === undefined ? {} : { since }),
+        ...(until === undefined ? {} : { until }),
+        ...(limit === undefined ? {} : { max_chars: chars(limit) }),
+      });
+  const out = parsed.named.get("out");
+  if (out === undefined) {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+    return undefined;
+  }
+  writeFileSync(out, text);
+  return {
+    path: out,
+    bytes: Buffer.byteLength(text),
+    dump: written.path,
+    instance: written.instance,
+    entries: written.entries,
+    ids: written.ids,
+  };
+}
+
+/** What a person typed, as the op's arguments.
+ *
+ * `<sid>/agent-<id>` is split here and nowhere else: the contract keeps the
+ * two apart so that a sid stays a validated sid, and the joined spelling is
+ * the CLI's own convenience — it is how the file the agent's records live in
+ * is named, which is what makes the two halves tellable apart by eye. */
+export function dumpArgs(
+  subject: string,
+  named: ReadonlyMap<string, string> = new Map(),
+): SessionDumpWriteArgs {
+  const at = subject.indexOf(AGENT_MARK);
+  const sid = at === -1 ? subject : subject.slice(0, at);
+  const agent = at === -1 ? undefined : subject.slice(at + AGENT_MARK.length);
+  const types = named.get("types");
+  const preset = named.get("preset");
+  return {
+    sid,
+    ...(agent === undefined || agent === "" ? {} : { agent_id: agent }),
+    ...(preset === undefined ? {} : { preset }),
+    ...(types === undefined
+      ? {}
+      : {
+          types: types
+            .split(",")
+            .map((one) => one.trim())
+            .filter((one) => one !== ""),
+        }),
+    ...bound("since", named.get("since")),
+    ...bound("until", named.get("until")),
+  };
+}
+
+const AGENT_MARK = "/agent-";
+
+/** One bound, as whichever of the two kinds it was written in.
+ *
+ * A time and a record id cannot be confused for one another — one parses as a
+ * moment and the other does not — so the caller writes what they have rather
+ * than saying which it is. */
+function bound(kind: "since" | "until", value: string | undefined): Record<string, unknown> {
+  if (value === undefined || value === "") return {};
+  const at = moment(value);
+  return at === undefined ? { [`${kind}_uuid`]: value } : { [`${kind}_at`]: at };
+}
+
+function moment(value: string): number | undefined {
+  if (/^\d+$/.test(value)) return Number(value);
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+function chars(value: string): number {
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new CommandError("invalid_args", "--max-chars は 1 以上の整数です");
+  }
+  return limit;
+}
+
 /** `ccmsg post <sid> <text>`: start a conversation with another session. */
 function post(args: readonly string[]): Promise<unknown> {
   const parsed = options(args, ["sid"]);
@@ -1106,6 +1258,26 @@ async function call(
       `自分のセッション ID が分かりません (--sid か ${SESSION_ENV.join(" / ")})`,
     );
   }
+  return await exchange(
+    { op: "hello", role: "session", sid, protocol_version: PROTOCOL_VERSION, ...meta },
+    request,
+  );
+}
+
+/** One op, spoken as the person at the keyboard.
+ *
+ * Which is who is asking: reading a transcript is not something a session is a
+ * party to, and the ops that do it are open to a person and to nobody else. */
+function instanceAsk(request: Record<string, unknown>): Promise<unknown> {
+  return exchange({ op: "hello", role: "user", protocol_version: PROTOCOL_VERSION }, request);
+}
+
+/** Greet this config home's instance, ask it one thing, and answer with what
+ * it said. */
+async function exchange(
+  greeting: Record<string, unknown>,
+  request: Record<string, unknown>,
+): Promise<unknown> {
   const paths = resolvePaths();
   const conn = await connect(paths.socket);
   if (conn === undefined) {
@@ -1115,15 +1287,9 @@ async function call(
     );
   }
   try {
-    const greeting = await conn.ask({
-      op: "hello",
-      role: "session",
-      sid,
-      protocol_version: PROTOCOL_VERSION,
-      ...meta,
-    });
-    if (greeting["ok"] !== true) {
-      throw new CommandError("forbidden", `hello が拒否されました: ${JSON.stringify(greeting)}`);
+    const greeted = await conn.ask(greeting);
+    if (greeted["ok"] !== true) {
+      throw new CommandError("forbidden", `hello が拒否されました: ${JSON.stringify(greeted)}`);
     }
     const answer = await conn.ask(request);
     if (answer["ok"] !== true) {

package/src/plugin/skill.ts

@@ -63,6 +63,16 @@ ccmsg peers --all      他ホストの instance が知っている分も含め
 根拠をこちらで要約し直しても情報は増えず、時間とコンテキストだけが減る。人に言うのは
 自セッション目線の事実 (何を頼んだ・何が返り・その結果こちらが何をしたか) だけ。
 
+## 別のセッションのやり方を読む
+
+\`\`\`
+ccmsg dump <sid> --preset howto        親セッションが何を考えて何を叩いたか
+ccmsg dump <sid>/agent-<id> --preset howto   その worker 自身のやり口
+\`\`\`
+
+出力の末尾に ids 台帳があり、そこに出た \`agent\` の id が 2 行目の \`<id>\` になる。
+preset の一覧は \`ccmsg dump presets\`。
+
 ## 見ている人へ知らせる
 
 \`\`\`

package/src/transcript/items/classify.ts

@@ -43,6 +43,11 @@ const NOT_ITEMS = new Set([
   "summary",
 ]);
 
+/** The tools that start an agent, in the spellings the harness has used for
+ * the one thing. Both are read the same way: the call is also a brief, and
+ * what comes back is also an answer. */
+const SPAWNS = new Set(["Agent", "Task"]);
+
 /** 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. */
@@ -184,7 +189,7 @@ class Classification {
       ...(fields ?? { input }),
     });
     let message: Draft | undefined;
-    if (name === "Agent") {
+    if (SPAWNS.has(name)) {
       message = make("message:sub:out", {
         role: "use",
         prompt: str(input["prompt"]) ?? "",
@@ -247,10 +252,25 @@ class Classification {
     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;
+    const result = row(answer) ?? {};
+    const agent = str(result["agentId"]) ?? str(result["agent_id"]);
+    if (call.message === undefined) return;
+    if (agent !== undefined) call.message["agent_id"] = agent;
+    // An agent that was waited on answers here, in the call's own result. One
+    // started in the background answers much later in a notification of its
+    // own, and this result then says only that it was launched — so what
+    // decides is whether an answer came back, not which tool was called.
+    const said = answered(result["content"]);
+    if (said === undefined) return;
+    const reply = make("message:sub:in", {
+      role: "result",
+      parent_item: call.message.uuid,
+      text: said,
+      ...optional("agent_id", agent),
+      ...optional("status", str(result["status"])),
+      ...optional("duration_ms", count(result["totalDurationMs"])),
+    });
+    call.message["result_item"] = reply.uuid;
   }
 
   /** A `type: "user"` line whose content is words rather than a tool's answer.
@@ -385,6 +405,15 @@ function attribute(said: string, name: string): string | undefined {
   return new RegExp(`${name}="([^"]*)"`).exec(said)?.[1] || undefined;
 }
 
+/** What an agent handed back, which the harness writes as the blocks of a
+ * message. Nothing back is not an answer of no words: a launch says only that
+ * the agent started, and reading that as an empty answer would claim it had
+ * finished. */
+function answered(raw: unknown): string | undefined {
+  const said = text(raw)?.trim();
+  return said === undefined || said === "" ? undefined : said;
+}
+
 /** A content field that is sometimes a string and sometimes the blocks of
  * one. */
 function text(raw: unknown): string | undefined {

package/src/transcript/items/document.ts

@@ -0,0 +1,214 @@
+import type { DumpIdEntry, SessionDumpFile } from "@ccmsg/protocol";
+import type { Item } from "./item.ts";
+import { elapsed, fragment, words } from "./render.ts";
+
+/** A whole dump as one document.
+ *
+ * What the file holds is items in the order the transcript had them, and what
+ * a person reads is that same order with the pairs put back together: a call
+ * and the answer that came straight back read as one thing, and an answer that
+ * arrived twenty turns later reads where it arrived, saying which call it
+ * belongs to. Folding is decided here rather than in the classification,
+ * because it is a fact about how far apart two items ended up in this
+ * particular selection and not about what either of them is.
+ *
+ * An agent is the exception: its answer is drawn under the brief that asked
+ * for it however many turns apart they are. The pair is a conversation with
+ * somebody else, and a conversation split across the page is one nobody can
+ * follow. */
+
+/** What the file cannot say about itself: which instance wrote it, and the
+ * bounds the request was made with. The file states the selection because the
+ * selection decides what is inside it; a bound decides only where it stops,
+ * and a reader who wants it is told here. */
+export interface DumpView {
+  readonly instance?: string;
+  readonly since?: string;
+  readonly until?: string;
+  /** How much of one item's body is drawn before the rest is reported by its
+   * length. Nothing is cut when nobody says: a dump is read to find out what
+   * was actually written, and the reader who wants less is the one who knows
+   * how much less. */
+  readonly max_chars?: number;
+}
+
+const INDENT = "  ";
+
+export function document(file: SessionDumpFile, view: DumpView = {}): string {
+  const items = file.items as unknown as Item[];
+  const paired = pair(items);
+  const lines: string[] = [...heading(file, view)];
+  lines.push("## items", "");
+  if (items.length === 0) lines.push("(なし)", "");
+  for (let at = 0; at < items.length; at += 1) {
+    if (paired.folded.has(at)) continue;
+    const item = items[at] as Item;
+    const child = paired.child.get(at);
+    lines.push(...draw(item, child === undefined ? undefined : (items[child] as Item), view), "");
+  }
+  lines.push(...ledger(file.ids));
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+/** What this is a dump of, before anything that happened in it. */
+function heading(file: SessionDumpFile, view: DumpView): string[] {
+  const subject = file.agent_id === undefined ? file.sid : `${file.sid}/agent-${file.agent_id}`;
+  const lines = [`# dump ${subject}`, ""];
+  lines.push(`- 対象: \`${subject}\``);
+  if (view.instance !== undefined) lines.push(`- instance: \`${view.instance}\``);
+  lines.push(`- 書き出し: ${new Date(file.written_at).toISOString()}`);
+  lines.push(`- types: ${file.types.map((one) => `\`${one}\``).join(" ") || "(既定)"}`);
+  const bounds = words(
+    view.since === undefined ? undefined : `since=${view.since}`,
+    view.until === undefined ? undefined : `until=${view.until}`,
+  );
+  if (bounds !== "") lines.push(`- 範囲: ${bounds}`);
+  lines.push(`- items: ${String(file.items.length)}`, "");
+  return lines;
+}
+
+/** One item, with whatever was folded into it.
+ *
+ * A call keeps its own heading and the answer's words are put at the end of
+ * it, so `→` reads as "and this came back". An answer drawn where it arrived
+ * points the other way, at a call the reader has already gone past. */
+function draw(item: Item, child: Item | undefined, view: DumpView): string[] {
+  const own = fragment(item);
+  const answer = child === undefined ? undefined : fragment(child);
+  const nested = child !== undefined && child.type.startsWith("message:sub");
+  const link = isResult(item)
+    ? arrow("←", item["parent_item"])
+    : (arrow("→", item["result_item"]) ?? (item["role"] === "use" ? "(未着)" : undefined));
+  const head = isResult(item)
+    ? words(prefix(item), link, own.head, clock(item))
+    : words(
+        prefix(item),
+        own.head,
+        link,
+        nested || answer === undefined ? undefined : answer.head,
+        clock(item),
+      );
+  const under = [
+    ...body(own.body, view),
+    ...(answer === undefined || nested ? [] : body(answer.body, view)),
+  ];
+  const lines = [head, ...under.map((line) => `${INDENT}${line}`)];
+  if (!nested || child === undefined || answer === undefined) return lines;
+  // The agent's answer, under the brief that asked for it. It keeps a heading
+  // of its own — it has its own instant, and often a status the brief could
+  // not have known — and is indented to say whose answer it is.
+  lines.push(`${INDENT}${words(prefix(child), answer.head, clock(child))}`);
+  for (const line of body(answer.body, view)) lines.push(`${INDENT}${INDENT}${line}`);
+  return lines;
+}
+
+/** `[uuid8] type`, which is how an item is pointed at: the id is what a reader
+ * goes back to the transcript with, and the type is what it was read as. */
+function prefix(item: Item): string {
+  return `[${item.uuid.slice(0, 8)}] ${item.type}`;
+}
+
+function clock(item: Item): string {
+  const at = new Date(item.at);
+  const time = `${two(at.getHours())}:${two(at.getMinutes())}:${two(at.getSeconds())}`;
+  return item.turn === undefined ? time : `${time} turn ${String(item.turn)}`;
+}
+
+function two(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+function arrow(mark: string, id: unknown): string | undefined {
+  return typeof id === "string" && id !== "" ? `${mark} ${id.slice(0, 8)}` : undefined;
+}
+
+function isResult(item: Item): boolean {
+  return item["role"] === "result";
+}
+
+/** The lines under a heading, cut only where a reader asked for a cut. */
+function body(source: readonly string[], view: DumpView): string[] {
+  const limit = view.max_chars;
+  if (limit === undefined || limit <= 0) return [...source];
+  const kept: string[] = [];
+  let held = 0;
+  for (const line of source) {
+    if (held + line.length <= limit) {
+      kept.push(line);
+      held += line.length + 1;
+      continue;
+    }
+    const room = Math.max(0, limit - held);
+    const rest = source.join("\n").length - held - room;
+    if (room > 0) kept.push(line.slice(0, room));
+    kept.push(`… (残り ${String(Math.max(rest, 0))} 文字)`);
+    break;
+  }
+  return kept;
+}
+
+/** The ids the items carried, which is what a reader descends by: the agent
+ * that did the thing worth copying is named here, and dumping it is the same
+ * request with that id as its subject. */
+function ledger(ids: readonly DumpIdEntry[]): string[] {
+  const lines = ["## ids", ""];
+  if (ids.length === 0) return [...lines, "(なし)"];
+  lines.push("| kind | id | label | status |", "|---|---|---|---|");
+  for (const entry of ids) {
+    const status = words(entry.status, elapsed(entry.duration_ms));
+    lines.push(
+      `| ${cell(entry.kind)} | \`${cell(entry.id)}\` | ${cell(entry.label ?? "")} | ${cell(status)} |`,
+    );
+  }
+  return lines;
+}
+
+function cell(text: string): string {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+
+/** Which answer belongs to which call, and which of those are drawn together.
+ *
+ * A tool's two halves are matched on the id the harness pairs them with, so
+ * two calls in the same record are never confused for one another. An agent's
+ * are matched on the record the brief was written in and the agent that
+ * answered, which is what the classification filled in once the agent had
+ * started. */
+function pair(items: readonly Item[]): {
+  child: Map<number, number>;
+  folded: Set<number>;
+} {
+  const child = new Map<number, number>();
+  const folded = new Set<number>();
+  const waiting = new Map<string, number[]>();
+  for (let at = 0; at < items.length; at += 1) {
+    const item = items[at] as Item;
+    // Which half of an exchange this is, which the contract calls an item's
+    // role and nothing here confuses with who is allowed to ask for one.
+    const half = item["role"];
+    if (half === "use") {
+      const queue = waiting.get(key(item, false));
+      if (queue === undefined) waiting.set(key(item, false), [at]);
+      else queue.push(at);
+      continue;
+    }
+    if (half !== "result") continue;
+    const call = waiting.get(key(item, true))?.shift();
+    if (call === undefined) continue;
+    // A pair the reader would have to scroll between is left where each half
+    // happened, unless it is an agent's: what an agent was asked and what it
+    // answered are one exchange whatever fell between them.
+    if (!item.type.startsWith("message:sub") && call !== at - 1) continue;
+    child.set(call, at);
+    folded.add(at);
+  }
+  return { child, folded };
+}
+
+function key(item: Item, result: boolean): string {
+  const call = item["tool_use_id"];
+  if (typeof call === "string" && call !== "") return `${item.type}${call}`;
+  const record = result ? item["parent_item"] : item.uuid;
+  const agent = item["agent_id"];
+  return `sub${String(record)}${typeof agent === "string" ? agent : ""}`;
+}

package/src/transcript/items/index.ts

@@ -1,4 +1,6 @@
 export { classify } from "./classify.ts";
+export { document, type DumpView } from "./document.ts";
 export type { Item } from "./item.ts";
 export { ledger } from "./ids.ts";
+export { type Fragment, fragment } from "./render.ts";
 export { type Ask, type Selection, select, selection } from "./select.ts";

package/src/transcript/items/render.ts

@@ -0,0 +1,421 @@
+import type { Item } from "./item.ts";
+
+/** One item as the words a person reads.
+ *
+ * A type is drawn by one function, the way the same type is drawn by one
+ * component where the destination is a screen instead of text. What the two
+ * share is the classification; how a `tool:Bash` reads is the drawing's own
+ * business, and neither side carries the other's.
+ *
+ * A type nobody wrote a drawing for is still drawn. The generic shape says the
+ * type name and lays out whatever fields the item carried, so a tool that
+ * arrived after this file was written reads worse than a known one and is
+ * never missing — a line that vanishes quietly is the failure a dump cannot be
+ * read around. */
+
+/** What one item says about itself: the words that belong on its heading, and
+ * the lines that go under it.
+ *
+ * Split because a call and its answer are two items that often read as one:
+ * folding them puts the answer's heading words at the end of the call's
+ * heading and its lines under the call's, and neither piece has to know
+ * whether that happened. */
+export interface Fragment {
+  readonly head: string;
+  readonly body: readonly string[];
+}
+
+/** How a type is drawn. */
+type Draw = (item: Item) => Fragment;
+
+const EMPTY: readonly string[] = [];
+
+/** The drawing for one item, whatever its type. */
+export function fragment(item: Item): Fragment {
+  const type = item.type;
+  if (type.startsWith("tool:")) {
+    const name = type.slice("tool:".length);
+    const result = isResult(item);
+    const draw = (result ? RESULTS : USES)[name];
+    if (draw !== undefined) return draw(item);
+    // A tool nothing knows the shape of arrives carrying what it was called
+    // with and what it answered, which is what the generic shape lays out.
+    return { head: "", body: summary(item[result ? "result" : "input"]) };
+  }
+  const draw = ITEMS[type];
+  if (draw !== undefined) return draw(item);
+  if (type.startsWith("hook:")) return hook(item);
+  if (type.startsWith("system:attachment:")) return { head: "", body: summary(item["attachment"]) };
+  return { head: "", body: summary(own(item)) };
+}
+
+function isResult(item: Item): boolean {
+  return item["role"] === "result";
+}
+
+// --- message, thinking and the harness's own voice ---
+
+/** The types whose whole content is what was said. Their body is the words,
+ * kept as they were written: a dump is read to find out what somebody actually
+ * wrote, and a reader who wants less asks for less. */
+const SAID: readonly string[] = [
+  "message:user:in",
+  "message:user:out",
+  "thinking",
+  "system:compact",
+];
+
+const ITEMS: Record<string, Draw> = {
+  ...Object.fromEntries(SAID.map((type) => [type, said])),
+
+  "message:sub:out": (item) => ({
+    head: words(
+      field(item, "agent_id", "agent="),
+      field(item, "subagent_type", "type="),
+      field(item, "name", "name="),
+      str(item, "description"),
+    ),
+    body: lines(str(item, "prompt")),
+  }),
+
+  "message:sub:in": (item) => ({
+    head: words(
+      field(item, "agent_id", "agent="),
+      field(item, "status", "status="),
+      elapsed(num(item, "duration_ms")),
+    ),
+    body: lines(str(item, "text")),
+  }),
+
+  "message:session:out": (item) => ({
+    head: words(field(item, "to", "to="), field(item, "reply_to", "reply_to="), mid(item)),
+    body: lines(str(item, "text")),
+  }),
+
+  "message:session:in": (item) => ({
+    head: words(field(item, "from", "from="), mid(item)),
+    body: lines(str(item, "text")),
+  }),
+
+  // A person operated the harness, or the harness spoke in someone else's
+  // voice. Both are why a conversation jumps rather than part of it, so they
+  // are a line each and the line names what happened. Everything the record
+  // held is in the JSON dump beside this one, addressable by the id shown.
+  "notice:slash": (item) => ({
+    head: words(`/${str(item, "command") ?? ""}`, str(item, "args"), first(str(item, "stdout"))),
+    body: EMPTY,
+  }),
+  "notice:interrupt": (item) => ({ head: first(str(item, "text")) ?? "", body: EMPTY }),
+  "system:api-error": (item) => ({ head: first(str(item, "text")) ?? "", body: EMPTY }),
+  "system:caveat": (item) => ({ head: first(str(item, "text")) ?? "", body: EMPTY }),
+  "system:resume": (item) => ({ head: first(str(item, "text")) ?? "", body: EMPTY }),
+  "system:task": (item) => ({
+    head: words(
+      field(item, "task_id", "task="),
+      field(item, "event", "event="),
+      first(str(item, "text")),
+    ),
+    body: EMPTY,
+  }),
+  "system:unknown": (item) => ({ head: "", body: summary(item["record"]) }),
+};
+
+function said(item: Item): Fragment {
+  return { head: "", body: lines(str(item, "text")) };
+}
+
+function mid(item: Item): string | undefined {
+  return field(item, "msg_id", "mid=");
+}
+
+/** The operator's own code, and what it did with its turn. */
+function hook(item: Item): Fragment {
+  return {
+    head: words(
+      str(item, "hook_name"),
+      str(item, "outcome"),
+      field(item, "tool_use_id", "tool="),
+      exit(num(item, "exit_code")),
+      elapsed(num(item, "duration_ms")),
+      field(item, "stderr", "stderr="),
+    ),
+    body: lines(str(item, "content")),
+  };
+}
+
+function exit(code: number | undefined): string | undefined {
+  return code === undefined ? undefined : `exit=${String(code)}`;
+}
+
+// --- tools ---
+
+/** What each call says on its heading and under it.
+ *
+ * The command, the path, the pattern: the one thing that says which call this
+ * was goes on the heading, and a body is for what a reader has to look at line
+ * by line rather than recognise at a glance. */
+const USES: Record<string, Draw> = {
+  Bash: (item) => ({
+    head: str(item, "description") ?? "",
+    body: lines(str(item, "command")).map((line) => `$ ${line}`),
+  }),
+  Read: (item) => ({
+    head: words(str(item, "file_path"), at(item)),
+    body: EMPTY,
+  }),
+  Write: (item) => ({
+    head: words(str(item, "file_path"), rows(num(item, "lines"))),
+    body: EMPTY,
+  }),
+  Edit: (item) => ({
+    head: words(str(item, "file_path"), edited(item)),
+    body: EMPTY,
+  }),
+  Grep: pattern,
+  Glob: pattern,
+  WebFetch: (item) => ({ head: words(str(item, "url"), str(item, "prompt")), body: EMPTY }),
+  WebSearch: (item) => ({ head: field(item, "query", "query=") ?? "", body: EMPTY }),
+  // The brief itself is the `message:sub:out` beside this call, so the call
+  // says which agent was started and leaves the words to the message.
+  Agent: (item) => ({
+    head: words(
+      field(item, "subagent_type", "type="),
+      field(item, "name", "name="),
+      str(item, "description"),
+    ),
+    body: EMPTY,
+  }),
+  SendMessage: (item) => ({
+    head: words(field(item, "to", "to="), str(item, "summary")),
+    body: EMPTY,
+  }),
+  Monitor: (item) => ({
+    head: words(
+      str(item, "description"),
+      item["persistent"] === true ? "persistent" : undefined,
+      until(num(item, "timeout_ms")),
+    ),
+    body: lines(str(item, "command")).map((line) => `$ ${line}`),
+  }),
+  Skill: (item) => ({ head: words(str(item, "skill"), str(item, "args")), body: EMPTY }),
+  TodoWrite: (item) => {
+    const todos = list(item["todos"]);
+    const width = Math.max(0, ...todos.map((todo) => todo.status.length));
+    return {
+      head: `${String(todos.length)} items`,
+      body: todos.map((todo) => `${todo.status.padEnd(width)}  ${todo.content}`),
+    };
+  },
+  TaskStop: (item) => ({ head: field(item, "task_id", "task=") ?? "", body: EMPTY }),
+  CronCreate: (item) => ({
+    head: str(item, "cron") ?? "",
+    body: lines(str(item, "prompt")),
+  }),
+};
+
+/** What each answer says, on the heading it is folded into or on its own.
+ *
+ * An answer that is a fact about the call — how many lines, which id — is
+ * heading words, so a folded pair reads as one line. An answer somebody has to
+ * read is a body. */
+const RESULTS: Record<string, Draw> = {
+  Bash: (item) => ({
+    head: item["interrupted"] === true ? "中断" : "",
+    body: [...stream("stdout", str(item, "stdout")), ...stream("stderr", str(item, "stderr"))],
+  }),
+  Read: (item) => ({
+    head: words(rows(num(item, "lines")), bytes(num(item, "bytes"))),
+    body: EMPTY,
+  }),
+  Write: ok,
+  Edit: ok,
+  Grep: hits,
+  Glob: hits,
+  WebFetch: (item) => ({ head: "", body: lines(str(item, "text")) }),
+  WebSearch: (item) => {
+    const found = num(item, "results");
+    return { head: found === undefined ? "" : `${String(found)} results`, body: EMPTY };
+  },
+  Agent: (item) => ({
+    head: words(field(item, "agent_id", "agent="), field(item, "status", "status=")),
+    body: EMPTY,
+  }),
+  SendMessage: (item) => ({
+    head: words(mid(item), field(item, "routing", "routing=")),
+    body: EMPTY,
+  }),
+  Monitor: (item) => ({ head: field(item, "task_id", "task=") ?? "", body: EMPTY }),
+  Skill: (item) => ({
+    head: words(
+      field(item, "agent_id", "agent="),
+      item["background"] === true ? "background" : undefined,
+      field(item, "status", "status="),
+    ),
+    body: EMPTY,
+  }),
+  TodoWrite: ok,
+  TaskStop: ok,
+  CronCreate: (item) => ({ head: field(item, "cron_id", "cron=") ?? "", body: EMPTY }),
+};
+
+function pattern(item: Item): Fragment {
+  return {
+    head: words(field(item, "pattern", "pattern="), field(item, "path", "path=")),
+    body: EMPTY,
+  };
+}
+
+/** A tool that says nothing but whether it worked. Success is the silent case:
+ * a heading crowded with `ok` is a heading nobody reads. */
+function ok(item: Item): Fragment {
+  return { head: item["ok"] === false ? "失敗" : "", body: EMPTY };
+}
+
+function hits(item: Item): Fragment {
+  const found = num(item, "matches");
+  return { head: found === undefined ? "" : `${String(found)} hits`, body: EMPTY };
+}
+
+/** One of a shell call's two streams, kept whole. A single line sits beside
+ * its name; more than one goes under it, because a stream that needs reading
+ * needs its own left edge. */
+function stream(name: string, text: string | undefined): string[] {
+  const rows = lines(text);
+  if (rows.length === 0) return [];
+  if (rows.length === 1) return [`${name}  ${rows[0] as string}`];
+  return [name, ...rows.map((line) => `  ${line}`)];
+}
+
+function at(item: Item): string | undefined {
+  const offset = num(item, "offset");
+  const limit = num(item, "limit");
+  if (offset === undefined && limit === undefined) return undefined;
+  return `${String(offset ?? 0)}+${limit === undefined ? "" : String(limit)}`;
+}
+
+function edited(item: Item): string | undefined {
+  const old = num(item, "old_lines");
+  const fresh = num(item, "new_lines");
+  if (old === undefined && fresh === undefined) return undefined;
+  return `-${String(old ?? 0)} +${String(fresh ?? 0)}`;
+}
+
+function rows(count: number | undefined): string | undefined {
+  return count === undefined ? undefined : `${String(count)} 行`;
+}
+
+function bytes(count: number | undefined): string | undefined {
+  return count === undefined ? undefined : `${String(count)} B`;
+}
+
+function until(ms: number | undefined): string | undefined {
+  return ms === undefined ? undefined : `timeout=${elapsed(ms) ?? ""}`;
+}
+
+// --- the pieces every drawing is made of ---
+
+function str(item: Item, name: string): string | undefined {
+  const value = item[name];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+function num(item: Item, name: string): number | undefined {
+  const value = item[name];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function field(item: Item, name: string, label: string): string | undefined {
+  const value = str(item, name);
+  return value === undefined ? undefined : `${label}${value}`;
+}
+
+/** Heading words, separated by the two spaces that keep them apart without
+ * inventing a syntax to parse. */
+export function words(...parts: (string | undefined)[]): string {
+  return parts.filter((part) => part !== undefined && part !== "").join("  ");
+}
+
+function lines(text: string | undefined): string[] {
+  if (text === undefined) return [];
+  const body = text.replace(/\s+$/, "");
+  return body === "" ? [] : body.split("\n");
+}
+
+/** The first line of something that is drawn as one line, saying that there is
+ * more where the rest was left in the file beside this one. */
+function first(text: string | undefined): string | undefined {
+  const rows = lines(text);
+  const head = rows[0];
+  if (head === undefined) return undefined;
+  return rows.length === 1 ? head : `${head} …`;
+}
+
+/** A duration in the units a person compares them in. */
+export function elapsed(ms: number | undefined): string | undefined {
+  if (ms === undefined) return undefined;
+  if (ms < 1_000) return `${String(Math.round(ms))}ms`;
+  const seconds = Math.round(ms / 1_000);
+  if (seconds < 60) return `${String(seconds)}s`;
+  return `${String(Math.floor(seconds / 60))}m${String(seconds % 60).padStart(2, "0")}s`;
+}
+
+interface Todo {
+  readonly content: string;
+  readonly status: string;
+}
+
+function list(value: unknown): Todo[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null) return [];
+    const each = entry as Record<string, unknown>;
+    const content = each["content"];
+    const status = each["status"];
+    return typeof content === "string" && typeof status === "string" ? [{ content, status }] : [];
+  });
+}
+
+/** The base fields every item has, which the heading already said. What is
+ * left is the type's own, and that is what a generic drawing lays out. */
+const BASE = new Set(["uuid", "type", "at", "turn", "role", "result_item", "parent_item"]);
+
+function own(item: Item): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(item).filter(([name]) => !BASE.has(name)));
+}
+
+/** How deep a value nobody wrote a drawing for is laid out. Two levels is what
+ * shows a record's shape — its fields, and what each of them is — without the
+ * drawing becoming the file. */
+const DEPTH = 2;
+
+/** How long a value is quoted before it is reported by its length instead. */
+const VALUE = 200;
+
+/** Whatever it was, as lines under a heading.
+ *
+ * Not JSON: the reader of a dump is looking for what happened, and a nested
+ * object's punctuation is in the way of that. One field per line, flattened by
+ * the path it sits at, with what is deeper than the layout goes said by its
+ * shape rather than shown. */
+function summary(value: unknown, depth = DEPTH, path = ""): string[] {
+  if (value === undefined) return [];
+  if (typeof value !== "object" || value === null)
+    return [`${path}${path === "" ? "" : "  "}${scalar(value)}`];
+  if (Array.isArray(value)) {
+    if (depth <= 0) return [`${path}  [${String(value.length)} 件]`];
+    return value.flatMap((entry, index) => summary(entry, depth - 1, `${path}[${String(index)}]`));
+  }
+  const fields = Object.entries(value as Record<string, unknown>);
+  if (depth <= 0) return [`${path}  {${fields.map(([name]) => name).join(", ")}}`];
+  return fields.flatMap(([name, each]) =>
+    summary(each, depth - 1, path === "" ? name : `${path}.${name}`),
+  );
+}
+
+function scalar(value: unknown): string {
+  if (typeof value !== "string") return String(value);
+  const single = value.replace(/\s+/g, " ").trim();
+  return single.length <= VALUE
+    ? single
+    : `${single.slice(0, VALUE)}… (${String(single.length)} 文字)`;
+}

package/src/transcript/items/tools.ts

@@ -196,6 +196,12 @@ const RESULT: Record<string, (result: unknown, failed: boolean) => Record<string
   },
 };
 
+/** `Task` is the harness's older name for the tool that starts an agent. The
+ * type keeps whichever name the record used — a reader matches what it sees
+ * against what it ran — and both are read the same way. */
+USE["Task"] = USE["Agent"] as Reader;
+RESULT["Task"] = RESULT["Agent"] as (result: unknown, failed: boolean) => Record<string, unknown>;
+
 function matches(result: unknown): Record<string, unknown> {
   const fields = row(result);
   if (fields === undefined) return {};