@ccmsg/cli 0.4.3 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",
@@ -20,7 +20,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ccmsg/protocol": "1.12.0"
+    "@ccmsg/protocol": "1.13.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/instance/instance.ts

@@ -537,6 +537,9 @@ export class Instance {
     this.#topics.attach("inbox", this.#delivery);
     this.#topics.attach("notify", this.#notify);
     this.#topics.attach("transcript", this.#transcripts);
+    // One tail feeds both: the bytes as they are appended, and what those
+    // bytes were read as.
+    this.#topics.attach("transcript_items", this.#transcripts);
     this.#topics.attach("session_status", this.#status);
     this.#topics.attach("session_errors", this.#status);
     this.#topics.attach("llm_requests", this.#gateway.requests);

package/src/sessions/dump.ts

@@ -8,7 +8,15 @@ import type {
   SessionDumpWriteResult,
 } from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
-import { classify, type Item, ledger, select, selection } from "../transcript/items/index.ts";
+import {
+  bounded,
+  classify,
+  ledger,
+  located,
+  select,
+  selection,
+  within,
+} from "../transcript/items/index.ts";
 import type { TranscriptFiles } from "../transcript/index.ts";
 
 /** Where dumps land: one directory under this instance's own state, named
@@ -43,12 +51,7 @@ export interface DumpDeps {
  * 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");
-  }
-  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");
-  }
+  bounded(args);
   const preset = presetFor(args.preset, deps.presets);
   const file = deps.files.locate(
     args.sid,
@@ -72,7 +75,7 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
     },
     deps.presets,
   );
-  const { items, entries } = select(within(classify(text.split("\n")), args), keep);
+  const { items, entries } = select(within(classify(located(text)), 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
@@ -110,34 +113,3 @@ function presetFor(
   if (found === undefined) throw new OpError("invalid_args", `no preset is configured as ${name}`);
   return found;
 }
-
-/** 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. 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 (let at = 0; at < items.length; at += 1) {
-    const item = items[at];
-    if (item === undefined) continue;
-    if (!open) {
-      if (item.uuid !== args.since_uuid) continue;
-      open = true;
-    }
-    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;
-    }
-  }
-  return kept;
-}

package/src/sessions/handlers.ts

@@ -17,6 +17,8 @@ import {
   type SessionSearchArgs,
   type Sid,
   TITLE_MAX_CHARS,
+  type TranscriptItemsReadArgs,
+  type TranscriptItemsReadResult,
   type TranscriptReadArgs,
   type TranscriptReadResult,
 } from "@ccmsg/protocol";
@@ -25,6 +27,7 @@ import { sees, type Viewer } from "../files/index.ts";
 import { readSlice, type TranscriptFiles } from "../transcript/index.ts";
 import { dumpWrite } from "./dump.ts";
 import { forkOrigin } from "./fork.ts";
+import { itemsRead } from "./items.ts";
 import type { SessionProcesses } from "./processes.ts";
 import { search } from "./search.ts";
 
@@ -144,6 +147,19 @@ export function sessionHandlers(deps: SessionOpsDeps) {
       const file = deps.files.locate(args.sid, args);
       return readSlice(args.sid, file, args.before, args.max_bytes);
     },
+
+    /** The same transcript, as the items it was read into.
+     *
+     * The role narrows it the way it narrows the raw read: what a role may see
+     * is one rule whatever is being read, and a caller that cannot see a
+     * session cannot see it in either vocabulary. */
+    transcript_items_read: (input: HandlerInput): TranscriptItemsReadResult => {
+      const args = input.args as unknown as TranscriptItemsReadArgs;
+      if (!sees(args.sid, viewer(input))) {
+        throw new OpError("not_found", `no transcript is known for ${args.sid}`);
+      }
+      return itemsRead(args, { files: deps.files, presets: deps.presets });
+    },
   };
 }
 

package/src/sessions/items.ts

@@ -0,0 +1,105 @@
+import { readFileSync } from "node:fs";
+import type {
+  DumpPreset,
+  TranscriptItemsReadArgs,
+  TranscriptItemsReadResult,
+} from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+import type { TranscriptFiles } from "../transcript/index.ts";
+import {
+  bounded,
+  classify,
+  type Item,
+  ledger,
+  located,
+  select,
+  selection,
+  within,
+} from "../transcript/items/index.ts";
+import { READ_LIMIT } from "../transcript/read.ts";
+
+/** How many items one read may carry.
+ *
+ * The count a client draws in one go rather than a bound on the payload: an
+ * item is a sentence or a whole brief, so the size of a page is not something
+ * a count can state. The bytes below are what actually bounds it, and this is
+ * what keeps a page a page. */
+export const ITEMS_LIMIT = 500;
+
+/** The selector that asks for the ledger.
+ *
+ * The ledger is not an item type — an id says how to point at something, not
+ * what a line is — so asking for it is asking for a section rather than
+ * selecting a family. It is written in the same list because that is where a
+ * caller says what it wants out of a transcript. */
+const IDS = "ids";
+
+export interface ItemsReadDeps {
+  readonly files: TranscriptFiles;
+  /** The named selections this instance is configured with, which is what an
+   * `@name` inside a selection is resolved against. */
+  readonly presets: readonly DumpPreset[];
+}
+
+/** A slice of a transcript as the items it was read into.
+ *
+ * The raw read answers with the harness's own lines, which leaves the caller
+ * holding a private format; this answers with what those lines were classified
+ * as. Both stay: a client works in items and fetches the record behind one by
+ * the `source` that item carries.
+ *
+ * The whole file is classified before the range is applied, the way a dump's
+ * is. That is what makes a link answerable: a result inside the range whose
+ * call fell before it still names the call, and the caller can ask for the
+ * call by the id it was given. */
+export function itemsRead(
+  args: TranscriptItemsReadArgs,
+  deps: ItemsReadDeps,
+): TranscriptItemsReadResult {
+  bounded(args);
+  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 keep = selection(args.types === undefined ? {} : { types: args.types }, deps.presets);
+  const { items } = select(within(classify(located(text)), args), keep);
+  const page = paged(items, args.limit);
+  return {
+    items: page.items,
+    ...(page.next === undefined ? {} : { next: page.next }),
+    ...(keep.keeps(IDS) ? { ids: ledger(page.items) } : {}),
+  };
+}
+
+/** As much of the range as one answer carries, and where the next one starts.
+ *
+ * Two bounds, because either alone leaves a case unanswered: a count cannot
+ * keep a page of long briefs inside what a connection should carry, and bytes
+ * alone would answer with a number of items that varied with what was said in
+ * them. Whichever is reached first ends the page, and the first item left out
+ * is named so the caller resumes exactly where this stopped. */
+function paged(
+  items: readonly Item[],
+  limit: number | undefined,
+): { items: Item[]; next?: string } {
+  const most = Math.min(limit ?? ITEMS_LIMIT, ITEMS_LIMIT);
+  const kept: Item[] = [];
+  let held = 0;
+  for (const item of items) {
+    // A first item larger than the whole budget is still answered: a page of
+    // nothing would leave the caller resuming at the item it just failed to
+    // get, forever.
+    if (kept.length > 0 && (kept.length >= most || held >= READ_LIMIT)) {
+      return { items: kept, next: item.id };
+    }
+    kept.push(item);
+    held += JSON.stringify(item).length;
+  }
+  return { items: kept };
+}

package/src/transcript/items/classify.ts

@@ -1,5 +1,18 @@
 import type { Item } from "./item.ts";
-import { count, instant, isRow, list, optional, type Row, row, str, tagged } from "./record.ts";
+import {
+  count,
+  instant,
+  isRow,
+  list,
+  type Located,
+  located,
+  optional,
+  type Row,
+  row,
+  span,
+  str,
+  tagged,
+} from "./record.ts";
 import { genericResult, resultFields, useFields } from "./tools.ts";
 
 /** Turning a harness's transcript into the items the contract names.
@@ -48,10 +61,21 @@ const NOT_ITEMS = new Set([
  * what comes back is also an answer. */
 const SPAWNS = new Set(["Agent", "Task"]);
 
+/** How many calls awaiting an answer one reading holds. Reached only by calls
+ * that are never answered, since an answered one is let go where it is
+ * answered. */
+const OUTSTANDING_CALLS = 4096;
+
 /** 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 };
+type Draft = Record<string, unknown> & {
+  id: string;
+  uuid: string;
+  source: { offset: number; bytes: number };
+  type: string;
+  at: number;
+};
 
 /** A whole transcript read as items, in the order the file holds them.
  *
@@ -60,23 +84,19 @@ type Draft = Record<string, unknown> & { uuid: string; type: string; at: number
  * 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[] {
+export function classify(records: Iterable<Located>): 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;
+  return state.readAll(records);
 }
 
-class Classification {
-  readonly items: Draft[] = [];
+/** A transcript read as items while it is still being written.
+ *
+ * The same reading as `classify`, kept open: a tail hands it what has just
+ * been appended and takes back the items those bytes were, with the calls made
+ * before them still known — which is what lets a result arriving now name the
+ * call it answers. */
+export class Classification {
+  #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
@@ -86,15 +106,54 @@ class Classification {
   /** The last slash command invoked, which is what its output belongs to. */
   #slash: string | undefined;
 
-  read(record: Row): void {
+  /** The records of one chunk as the items they were read as, oldest first.
+   *
+   * What comes back is this chunk's items alone. A call the chunk before it
+   * held is still known and can still be pointed at, but it has already been
+   * handed over and is not handed over twice: whoever is reading a transcript
+   * as it grows holds a list it only appends to. */
+  readAll(records: Iterable<Located>): Item[] {
+    for (const { line, offset } of records) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (isRow(parsed)) this.read(parsed, { offset, bytes: span(line) });
+    }
+    const made = this.#items;
+    this.#items = [];
+    return made as unknown as Item[];
+  }
+
+  /** A whole chunk of text as items, where the chunk begins at `start`. */
+  readChunk(chunk: string, start = 0): Item[] {
+    return this.readAll(located(chunk, start));
+  }
+
+  read(record: Row, source: { offset: number; bytes: number }): 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"]);
+    // Where in its record an item stood. One record becomes the thinking, the
+    // words and each call of a turn, and a link that named only the record
+    // would name all of them at once.
+    let index = 0;
     const make = (kind: string, fields: Record<string, unknown> = {}): Draft => {
-      const draft: Draft = { uuid, type: kind, at, turn: this.#turn, ...fields };
-      this.items.push(draft);
+      const draft: Draft = {
+        id: `${uuid}:${String(index)}`,
+        uuid,
+        source,
+        type: kind,
+        at,
+        turn: this.#turn,
+        ...fields,
+      };
+      index += 1;
+      this.#items.push(draft);
       return draft;
     };
     if (type === "attachment") return this.#attachment(record, make);
@@ -205,12 +264,26 @@ class Classification {
         ...(addressed(to) ? {} : { role: "use" }),
         ...(addressed(to)
           ? { text: text(input["message"]) ?? "", to }
-          : { prompt: text(input["message"]) ?? "", name: to }),
+          : // Writing to an agent is one direction of a correspondence, not a
+            // call that returns: what the agent says back arrives as its own
+            // message whenever it chooses to send one, under nothing that
+            // names this. So the brief says it is waiting for nothing, and a
+            // reader is not left watching for an answer that has no way in.
+            { prompt: text(input["message"]) ?? "", name: to, one_way: true }),
       });
     } 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) });
+    if (id === "") return;
+    // A call is dropped from the pairing once it has been answered, so what is
+    // held here is the calls still outstanding. The bound is for the one that
+    // never will be — a transcript ends mid-call, an agent is killed — which
+    // otherwise accumulates for as long as the file is followed.
+    if (this.#calls.size >= OUTSTANDING_CALLS) {
+      const oldest = this.#calls.keys().next();
+      if (oldest.done !== true) this.#calls.delete(oldest.value);
+    }
+    this.#calls.set(id, { tool, name, ...optional("message", message) });
   }
 
   #user(record: Row, make: Make): void {
@@ -239,22 +312,37 @@ class Classification {
   #answer(record: Row, block: Row, make: Make): void {
     const id = str(block["tool_use_id"]) ?? "";
     const call = this.#calls.get(id);
+    if (call === undefined) {
+      // An answer to a call this reading never saw. A result item names the
+      // call it answers and there is no id to name, so what is stated is the
+      // record itself rather than a pointer to something that does not exist.
+      // It happens where a reading starts part-way down a file: the whole file
+      // is read before a dump's range is applied, so the call is there.
+      make("system:unknown", { record });
+      return;
+    }
     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")}`, {
+    const fields = resultFields(call.name, answer, failed);
+    const item = make(`tool:${segment(call.name)}`, {
       role: "result",
-      parent_item: call?.tool.uuid ?? id,
+      parent_item: call.tool.id,
       tool_use_id: id,
       ...(fields ?? { result: genericResult(answer) }),
     });
-    if (call === undefined) return;
-    call.tool["result_item"] = item.uuid;
+    call.tool["result_item"] = item.id;
     // 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 = str(result["agentId"]) ?? str(result["agent_id"]);
-    if (call.message === undefined) return;
+    if (call.message === undefined) {
+      // The exchange is closed: nothing else in the file points back at this
+      // call, so what was held for the pairing is let go. A transcript
+      // followed while it grows is read by one long-lived reading, and a call
+      // kept after it was answered would be kept for the session's life.
+      this.#calls.delete(id);
+      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
@@ -264,13 +352,14 @@ class Classification {
     if (said === undefined) return;
     const reply = make("message:sub:in", {
       role: "result",
-      parent_item: call.message.uuid,
+      parent_item: call.message.id,
       text: said,
       ...optional("agent_id", agent),
       ...optional("status", str(result["status"])),
       ...optional("duration_ms", count(result["totalDurationMs"])),
     });
-    call.message["result_item"] = reply.uuid;
+    call.message["result_item"] = reply.id;
+    this.#calls.delete(id);
   }
 
   /** A `type: "user"` line whose content is words rather than a tool's answer.
@@ -352,18 +441,20 @@ class Classification {
    * 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") ?? "");
+    const key = tagged(said, "tool-use-id") ?? "";
+    const call = this.#calls.get(key);
     if (answer !== undefined && call !== undefined) {
       const asked = call.message ?? call.tool;
       const item = make("message:sub:in", {
         role: "result",
-        parent_item: asked.uuid,
+        parent_item: asked.id,
         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;
+      if (call.message !== undefined) call.message["result_item"] = item.id;
+      this.#calls.delete(key);
       return;
     }
     make("system:task", {

package/src/transcript/items/document.ts

@@ -1,5 +1,5 @@
 import type { DumpIdEntry, SessionDumpFile } from "@ccmsg/protocol";
-import type { Item } from "./item.ts";
+import { fields, type Item } from "./item.ts";
 import { elapsed, fragment, words } from "./render.ts";
 
 /** A whole dump as one document.
@@ -77,8 +77,8 @@ function draw(item: Item, child: Item | undefined, view: DumpView): string[] {
   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));
+    ? arrow("←", fields(item)["parent_item"])
+    : (arrow("→", fields(item)["result_item"]) ?? waiting(item));
   const head = isResult(item)
     ? words(prefix(item), link, own.head, clock(item))
     : words(
@@ -102,10 +102,28 @@ function draw(item: Item, child: Item | undefined, view: DumpView): string[] {
   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. */
+/** `[id] type`, which is how an item is pointed at: the id is what the links
+ * name, and the type is what the item was read as. The record's id is shown at
+ * the length a person compares by eye, with the place in the record kept whole
+ * — an item is one of several a record became, and a heading that dropped
+ * which one would not answer the arrow pointing at it. */
 function prefix(item: Item): string {
-  return `[${item.uuid.slice(0, 8)}] ${item.type}`;
+  return `[${short(item.id)}] ${item.type}`;
+}
+
+function short(id: string): string {
+  const cut = id.lastIndexOf(":");
+  return cut < 0 ? id.slice(0, 8) : `${id.slice(0, Math.min(8, cut))}${id.slice(cut)}`;
+}
+
+/** A call with nothing pointing back at it. Waiting and having nothing to wait
+ * for read differently: an agent answers the brief that started it, and a
+ * message written to one is answered wherever that agent chooses, under
+ * nothing that names this. */
+function waiting(item: Item): string | undefined {
+  const own = fields(item);
+  if (own["role"] !== "use") return undefined;
+  return own["one_way"] === true ? "(片道)" : "(未着)";
 }
 
 function clock(item: Item): string {
@@ -119,11 +137,11 @@ function two(value: number): string {
 }
 
 function arrow(mark: string, id: unknown): string | undefined {
-  return typeof id === "string" && id !== "" ? `${mark} ${id.slice(0, 8)}` : undefined;
+  return typeof id === "string" && id !== "" ? `${mark} ${short(id)}` : undefined;
 }
 
 function isResult(item: Item): boolean {
-  return item["role"] === "result";
+  return fields(item)["role"] === "result";
 }
 
 /** The lines under a heading, cut only where a reader asked for a cut. */
@@ -169,31 +187,25 @@ function cell(text: string): string {
 
 /** 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. */
+ * An answer names the call it answers, so the matching is a lookup: no two
+ * calls in one record are confused for one another, and a tool and an agent
+ * are paired by the same rule rather than by the ids each of them happens to
+ * carry. */
 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[]>();
+  const where = new Map<string, number>();
+  for (let at = 0; at < items.length; at += 1) where.set((items[at] as Item).id, at);
   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 (fields(item)["role"] !== "result") continue;
+    const parent = fields(item)["parent_item"];
+    const call = typeof parent === "string" ? where.get(parent) : undefined;
     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
@@ -204,11 +216,3 @@ function pair(items: readonly Item[]): {
   }
   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,6 +1,15 @@
-export { classify } from "./classify.ts";
+export { classify, Classification } from "./classify.ts";
 export { document, type DumpView } from "./document.ts";
-export type { Item } from "./item.ts";
+export { fields, type Item } from "./item.ts";
 export { ledger } from "./ids.ts";
+export { type Located, located, positioned } from "./record.ts";
 export { type Fragment, fragment } from "./render.ts";
-export { type Ask, type Selection, select, selection } from "./select.ts";
+export {
+  type Ask,
+  bounded,
+  type Bounds,
+  type Selection,
+  select,
+  selection,
+  within,
+} from "./select.ts";

package/src/transcript/items/item.ts

@@ -1,23 +1,20 @@
-/** One classified item, at the shape the daemon holds it in.
+import type { TranscriptItem } from "@ccmsg/protocol";
+
+/** One classified item, at the shape the contract states.
  *
- * The contract states the same shape as a schema, which is what a dump is
- * checked against; what it does not give is a type to write code with — a
- * union of that many object schemas erases to nothing usable — so the three
- * fields every item has are named here and the rest are the type's own. The
- * schema stays the authority: the tests validate what this produces against
- * it, so a field that drifts from the contract fails there rather than
- * travelling. */
-export interface Item {
-  /** The record's id in the transcript, which is what makes an item
-   * addressable and what the links between items point with. Every item one
-   * record became carries it, so a bound by record keeps a turn whole. */
-  readonly uuid: string;
-  readonly type: string;
-  /** The item's own instant. A call and its result each keep their own. */
-  readonly at: number;
-  /** Which turn of the session it fell in, counted from where a person spoke.
-   * Renumbered whenever the file is read again, so it is an attribute to show
-   * and never a way to cut a range. */
-  readonly turn?: number;
-  readonly [field: string]: unknown;
+ * The contract is the authority on what an item is, and its schema carries a
+ * type, so there is nothing to restate here: what the daemon holds and what
+ * travels are the same value, and a field that drifted would fail to compile
+ * rather than to validate. */
+export type Item = TranscriptItem;
+
+/** An item's fields read by name.
+ *
+ * The type is a union of one object per item type, which is what makes it
+ * precise when an item is built and useless when one is read: a drawing asks
+ * every item for `role` or `agent_id` and only some types have either. This is
+ * the one place that gap is crossed, so a reader names a field once instead of
+ * narrowing a union of fifty members it has no discriminant for. */
+export function fields(item: Item): Record<string, unknown> {
+  return item as unknown as Record<string, unknown>;
 }

package/src/transcript/items/record.ts

@@ -8,6 +8,45 @@
 
 export type Row = Record<string, unknown>;
 
+/** One record of a transcript and where it begins in the file.
+ *
+ * Classification carries the position through to the items, because an item is
+ * what a reader made of a record and a reader is fallible: the position is how
+ * whoever holds the item asks the transcript what the record actually said. */
+export interface Located {
+  readonly line: string;
+  readonly offset: number;
+}
+
+/** A chunk of a transcript as its records, each with its position, where
+ * `start` is the offset the chunk itself begins at.
+ *
+ * A record's span runs to the start of the next one — the newline that ends it
+ * included — so a read bounded to `offset + bytes` carrying `bytes` returns the
+ * record whole rather than everything but its terminator. Every record a
+ * transcript hands out is one the writer finished and terminated; a trailing
+ * fragment is not a record and is not offered here. */
+export function located(chunk: string, start = 0): Located[] {
+  return positioned(chunk.split("\n"), start);
+}
+
+/** Records already split out of a chunk, placed from where the chunk begins.
+ * The one a tail hands over, which has done the splitting on the bytes. */
+export function positioned(lines: readonly string[], start: number): Located[] {
+  const found: Located[] = [];
+  let offset = start;
+  for (const line of lines) {
+    if (line !== "") found.push({ line, offset });
+    offset += span(line);
+  }
+  return found;
+}
+
+/** How far a record runs from where it begins, its terminator included. */
+export function span(line: string): number {
+  return Buffer.byteLength(line, "utf8") + 1;
+}
+
 export function isRow(raw: unknown): raw is Row {
   return typeof raw === "object" && raw !== null && !Array.isArray(raw);
 }

package/src/transcript/items/render.ts

@@ -1,4 +1,4 @@
-import type { Item } from "./item.ts";
+import { fields, type Item } from "./item.ts";
 
 /** One item as the words a person reads.
  *
@@ -40,17 +40,18 @@ export function fragment(item: Item): Fragment {
     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"]) };
+    return { head: "", body: summary(fields(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"]) };
+  if (type.startsWith("system:attachment:"))
+    return { head: "", body: summary(fields(item)["attachment"]) };
   return { head: "", body: summary(own(item)) };
 }
 
 function isResult(item: Item): boolean {
-  return item["role"] === "result";
+  return fields(item)["role"] === "result";
 }
 
 // --- message, thinking and the harness's own voice ---
@@ -117,7 +118,7 @@ const ITEMS: Record<string, Draw> = {
     ),
     body: EMPTY,
   }),
-  "system:unknown": (item) => ({ head: "", body: summary(item["record"]) }),
+  "system:unknown": (item) => ({ head: "", body: summary(fields(item)["record"]) }),
 };
 
 function said(item: Item): Fragment {
@@ -192,14 +193,14 @@ const USES: Record<string, Draw> = {
   Monitor: (item) => ({
     head: words(
       str(item, "description"),
-      item["persistent"] === true ? "persistent" : undefined,
+      fields(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 todos = list(fields(item)["todos"]);
     const width = Math.max(0, ...todos.map((todo) => todo.status.length));
     return {
       head: `${String(todos.length)} items`,
@@ -220,7 +221,7 @@ const USES: Record<string, Draw> = {
  * read is a body. */
 const RESULTS: Record<string, Draw> = {
   Bash: (item) => ({
-    head: item["interrupted"] === true ? "中断" : "",
+    head: fields(item)["interrupted"] === true ? "中断" : "",
     body: [...stream("stdout", str(item, "stdout")), ...stream("stderr", str(item, "stderr"))],
   }),
   Read: (item) => ({
@@ -248,7 +249,7 @@ const RESULTS: Record<string, Draw> = {
   Skill: (item) => ({
     head: words(
       field(item, "agent_id", "agent="),
-      item["background"] === true ? "background" : undefined,
+      fields(item)["background"] === true ? "background" : undefined,
       field(item, "status", "status="),
     ),
     body: EMPTY,
@@ -268,7 +269,7 @@ function pattern(item: Item): Fragment {
 /** 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 };
+  return { head: fields(item)["ok"] === false ? "失敗" : "", body: EMPTY };
 }
 
 function hits(item: Item): Fragment {
@@ -315,12 +316,12 @@ function until(ms: number | undefined): string | undefined {
 // --- the pieces every drawing is made of ---
 
 function str(item: Item, name: string): string | undefined {
-  const value = item[name];
+  const value = fields(item)[name];
   return typeof value === "string" && value !== "" ? value : undefined;
 }
 
 function num(item: Item, name: string): number | undefined {
-  const value = item[name];
+  const value = fields(item)[name];
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
@@ -377,10 +378,20 @@ function list(value: unknown): Todo[] {
 
 /** 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"]);
+const BASE = new Set([
+  "id",
+  "uuid",
+  "source",
+  "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)));
+  return Object.fromEntries(Object.entries(fields(item)).filter(([name]) => !BASE.has(name)));
 }
 
 /** How deep a value nobody wrote a drawing for is laid out. Two levels is what

package/src/transcript/items/select.ts

@@ -1,4 +1,5 @@
 import type { DumpPreset } from "@ccmsg/protocol";
+import { OpError } from "../../dispatch/index.ts";
 import type { Item } from "./item.ts";
 
 /** Which of a transcript's items a dump keeps.
@@ -142,3 +143,69 @@ export function select(
   }
   return { items: kept, entries };
 }
+
+/** Where a range of a transcript begins and ends.
+ *
+ * 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 there are two kinds. An item bound is finer than either: it
+ * resumes inside a record whose earlier items were already answered for. */
+export interface Bounds {
+  readonly since_at?: number;
+  readonly since_uuid?: string;
+  readonly since_id?: string;
+  readonly until_at?: number;
+  readonly until_uuid?: string;
+}
+
+/** The bounds as stated, refused where they say two things at once.
+ *
+ * A range with two lower bounds has no reading that is not a guess at which
+ * one was meant, and a guess that answers the wrong slice is worse than a
+ * refusal the caller can act on. */
+export function bounded(bounds: Bounds): void {
+  const lower = [bounds.since_at, bounds.since_uuid, bounds.since_id].filter(
+    (one) => one !== undefined,
+  ).length;
+  if (lower > 1) {
+    throw new OpError("invalid_args", "a lower bound is a time, a record or an item, not several");
+  }
+  if (bounds.until_at !== undefined && bounds.until_uuid !== undefined) {
+    throw new OpError("invalid_args", "an upper bound is a time or a record, not both");
+  }
+}
+
+/** The items within the bounds, in the order the transcript holds them.
+ *
+ * Every item a record became carries that record's id, so a bound by record
+ * keeps a turn's thinking, words and calls together, while a bound by item
+ * cuts inside one. */
+export function within(items: readonly Item[], bounds: Bounds): Item[] {
+  const kept: Item[] = [];
+  // A lower bound by record or by item starts closed: it opens at what it
+  // names, which is included.
+  let open = bounds.since_uuid === undefined && bounds.since_id === undefined;
+  for (let at = 0; at < items.length; at += 1) {
+    const item = items[at];
+    if (item === undefined) continue;
+    if (!open) {
+      if (
+        bounds.since_id !== undefined
+          ? item.id !== bounds.since_id
+          : item.uuid !== bounds.since_uuid
+      ) {
+        continue;
+      }
+      open = true;
+    }
+    if (bounds.since_at !== undefined && item.at < bounds.since_at) continue;
+    if (bounds.until_at !== undefined && item.at > bounds.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 (bounds.until_uuid !== undefined && item.uuid === bounds.until_uuid) {
+      if (items[at + 1]?.uuid !== item.uuid) break;
+    }
+  }
+  return kept;
+}

package/src/transcript/tail.ts

@@ -32,9 +32,10 @@ export interface Appended {
 export interface TailDeps {
   /** Complete lines only; a record still being written waits for its end. */
   readonly onAppended: (appended: Appended) => void;
-  /** The end of the file as it stood when the tail opened, oldest first. The
-   * seed of the fold, not something a subscriber is sent. */
-  readonly onSeed: (lines: readonly string[]) => void;
+  /** The end of the file as it stood when the tail opened, oldest first, with
+   * the offsets that place it. The seed of what is folded and of what is
+   * classified, not something a subscriber is sent. */
+  readonly onSeed: (seeded: Appended) => void;
   /** The file is not the one the tail was reading: it shrank, so what was
    * folded out of the old contents no longer describes it. */
   readonly onTruncated: () => void;
@@ -119,14 +120,12 @@ export class TranscriptTail {
     const size = this.#size;
     if (size === 0) return;
     const from = Math.max(0, size - FOLD_TAIL_BYTES);
-    const text = await this.#slice(from, size);
-    const complete = whole(text);
-    this.#offset = from + byteLength(complete);
-    const lines = split(complete);
+    const complete = whole(await this.#slice(from, size));
+    this.#offset = from + complete.byteLength;
     // The first line is half a record whenever the read began mid-file, so it
-    // is dropped: what the fold reads are whole records or nothing.
-    if (from > 0) lines.shift();
-    this.deps.onSeed(lines);
+    // is dropped: what is read are whole records or nothing.
+    const at = from === 0 ? 0 : complete.indexOf(NEWLINE) + 1;
+    this.deps.onSeed({ lines: split(complete, at), start: from + at, end: this.#offset, size });
   }
 
   async #read(): Promise<void> {
@@ -141,11 +140,11 @@ export class TranscriptTail {
     this.#size = size;
     if (size === this.#offset) return;
     const complete = whole(await this.#slice(this.#offset, size));
-    if (complete.length === 0) return;
+    if (complete.byteLength === 0) return;
     const start = this.#offset;
-    const end = start + byteLength(complete);
+    const end = start + complete.byteLength;
     this.#offset = end;
-    this.deps.onAppended({ lines: split(complete), start, end, size });
+    this.deps.onAppended({ lines: split(complete, 0), start, end, size });
   }
 
   async #stat(): Promise<number> {
@@ -157,35 +156,47 @@ export class TranscriptTail {
     }
   }
 
-  /** The bytes in a range, as text. A range that reads short — the file was
-   * truncated between the stat and the read — yields what was actually there. */
-  async #slice(from: number, to: number): Promise<string> {
+  /** The bytes in a range. A range that reads short — the file was truncated
+   * between the stat and the read — yields what was actually there.
+   *
+   * Bytes rather than text, because the offsets that place what is read are
+   * found in them: a slice that begins part-way into a file lands wherever the
+   * arithmetic puts it, inside a character as readily as before one, and
+   * decoding first would turn those bytes into a replacement character of a
+   * different length and move every offset derived from it. */
+  async #slice(from: number, to: number): Promise<Buffer> {
+    if (to <= from) return Buffer.alloc(0);
     const handle = await open(this.path, "r").catch(() => undefined);
-    if (handle === undefined) return "";
+    if (handle === undefined) return Buffer.alloc(0);
     try {
       const buffer = Buffer.alloc(to - from);
       const { bytesRead } = await handle.read(buffer, 0, buffer.length, from);
-      return buffer.subarray(0, bytesRead).toString("utf8");
+      return buffer.subarray(0, bytesRead);
     } finally {
       await handle.close();
     }
   }
 }
 
+const NEWLINE = 0x0a;
+
 /** What of a read is whole records: everything up to and including the last
  * newline. A transcript ends every record with one, so what follows the last
  * is a record the writer has not finished. */
-function whole(text: string): string {
-  const last = text.lastIndexOf("\n");
-  return last < 0 ? "" : text.slice(0, last + 1);
-}
-
-function split(complete: string): string[] {
-  return complete.split("\n").slice(0, -1);
+function whole(bytes: Buffer): Buffer {
+  const last = bytes.lastIndexOf(NEWLINE);
+  return last < 0 ? Buffer.alloc(0) : bytes.subarray(0, last + 1);
 }
 
-function byteLength(text: string): number {
-  return Buffer.byteLength(text, "utf8");
+/** The records in what was read, from a byte that begins one. */
+function split(complete: Buffer, at: number): string[] {
+  const lines: string[] = [];
+  for (let from = at; from < complete.byteLength;) {
+    const newline = complete.indexOf(NEWLINE, from);
+    lines.push(complete.toString("utf8", from, newline));
+    from = newline + 1;
+  }
+  return lines;
 }
 
 /** How large the file is right now, or zero for one that is not there yet.

package/src/transcript/transcripts.ts

@@ -1,8 +1,25 @@
 import type { InstanceId, Sid } from "@ccmsg/protocol";
 import { topicParam, type TopicValue, type UpstreamResource } from "../topics/index.ts";
 import { NO_FACTS, type TranscriptFacts, TranscriptFold } from "./fold.ts";
+import { Classification, type Item, positioned } from "./items/index.ts";
 import { type Appended, TranscriptTail } from "./tail.ts";
 
+/** How many items a subscription to `transcript_items:<sid>` opens with.
+ *
+ * The tail of the same megabyte the fold is seeded from, bounded by a count
+ * because that read is bounded by bytes: a file of many small records would
+ * otherwise make the opening frame as large as the read that produced it. Two
+ * hundred items is several turns at the sizes the harness writes, which is
+ * more than a live view shows at once — and a client that wants further back
+ * asks for it by range rather than waiting for a snapshot to grow. */
+export const ITEMS_SNAPSHOT = 200;
+
+/** Which of the two topics a name is. Both are fed by one tail, so the
+ * resource is entered by either name and answers each in its own vocabulary. */
+function isItems(topic: string): boolean {
+  return topic.startsWith("transcript_items:");
+}
+
 export interface TranscriptsDeps {
   readonly self: InstanceId;
   /** Where a session's transcript is: what it announced when it greeted
@@ -58,7 +75,12 @@ export class Transcripts implements UpstreamResource {
     const sid = topicParam(topic);
     const followed = sid === undefined ? undefined : this.#followed.get(sid);
     if (sid === undefined || followed === undefined) return [];
-    return [{ instance: this.deps.self, data: { sid, size: followed.tail.size } }];
+    // The items topic holds a list that is only appended to, so its snapshot
+    // is the end of that list rather than a place to start from.
+    const data = isItems(topic)
+      ? { sid, items: [...followed.recent] }
+      : { sid, size: followed.tail.size };
+    return [{ instance: this.deps.self, data }];
   }
 
   /** What the fold currently says about a session. Empty for one not being
@@ -117,15 +139,20 @@ export class Transcripts implements UpstreamResource {
     const followed: Followed = {
       holds: 1,
       fold,
+      reading: new Classification(),
+      recent: [],
       tail: new TranscriptTail(path, {
-        onSeed: (lines) => {
+        onSeed: (seeded) => {
           // The end of the file as it already stood: it settles what the fold
-          // says, and it is not an append, so nothing is published for it.
-          if (foldAll(fold, lines)) this.deps.onFacts(sid);
+          // says and opens the reading that classifies what comes next, and it
+          // is not an append, so nothing is published for it.
+          this.#keep(sid, seeded);
+          if (foldAll(fold, seeded.lines)) this.deps.onFacts(sid);
         },
         onAppended: (appended) => this.#appended(sid, fold, appended),
         onTruncated: () => {
           fold.reset();
+          this.#reset(sid);
           this.deps.onFacts(sid);
         },
         ...(this.deps.pollMs === undefined ? {} : { pollMs: this.deps.pollMs }),
@@ -134,8 +161,15 @@ export class Transcripts implements UpstreamResource {
     return followed;
   }
 
-  /** The one pass over what was appended: the lines go to the fold and to the
-   * topic, in that order, and are not read a second time for either (M5). */
+  /** The one pass over what was appended: the lines go to the fold, to the
+   * classification and to the two topics, and are not read again for any of
+   * them (M5).
+   *
+   * Both topics are fed whether or not either is subscribed to, because the
+   * classification is a reading of the whole file kept open: a call answered
+   * now was made in bytes that went past long ago, and a reading started when
+   * somebody subscribed would not know it. What the memory holds is bounded —
+   * the calls still outstanding, and the items of the opening frame. */
   #appended(sid: Sid, fold: TranscriptFold, appended: Appended): void {
     const changed = foldAll(fold, appended.lines);
     this.deps.publish(`transcript:${sid}`, {
@@ -145,13 +179,46 @@ export class Transcripts implements UpstreamResource {
       end: appended.end,
       size: appended.size,
     });
+    const items = this.#keep(sid, appended);
+    // A record still being written was not read, so there is nothing to say
+    // about it yet; a chunk whose records were all the interface's own
+    // bookkeeping says nothing either.
+    if (items.length > 0) this.deps.publish(`transcript_items:${sid}`, { sid, items });
     if (changed) this.deps.onFacts(sid);
   }
+
+  /** What a chunk was read as, with the end of it held for the next
+   * subscription to open on. A result that fills in a call already handed over
+   * is not sent again: the call named nothing to wait for and the result names
+   * the call, so a reader ties the two together from what it already has. */
+  #keep(sid: Sid, chunk: Appended): readonly Item[] {
+    const followed = this.#followed.get(sid);
+    if (followed === undefined) return [];
+    const items = followed.reading.readAll(positioned(chunk.lines, chunk.start));
+    followed.recent.push(...items);
+    if (followed.recent.length > ITEMS_SNAPSHOT) {
+      followed.recent.splice(0, followed.recent.length - ITEMS_SNAPSHOT);
+    }
+    return items;
+  }
+
+  /** The file is not the one that was being read, so neither the reading nor
+   * what it produced describes it. */
+  #reset(sid: Sid): void {
+    const followed = this.#followed.get(sid);
+    if (followed === undefined) return;
+    followed.reading = new Classification();
+    followed.recent.length = 0;
+  }
 }
 
 interface Followed {
   holds: number;
   readonly fold: TranscriptFold;
+  /** The transcript read as items, kept open while the tail runs. */
+  reading: Classification;
+  /** The end of what has been read, which is what a subscription opens on. */
+  readonly recent: Item[];
   readonly tail: TranscriptTail;
 }