@ccmsg/cli 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.5.1",
+  "version": "0.6.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.14.0"
+    "@ccmsg/protocol": "1.15.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/messaging/notify.ts

@@ -105,7 +105,7 @@ export class Notify implements UpstreamResource {
     // raise another (§6.4).
     if (this.deps.publish(NOTIFY, notification, this.deps.self) === "rate_limited") {
       throw new OpError(
-        "internal_error",
+        "rate_limited",
         "a watcher is behind on this topic; the notification was not taken",
       );
     }

package/src/sessions/items.ts

@@ -80,21 +80,18 @@ export function itemsRead(
 
 /** Whether the range's end is the part to answer with.
  *
- * A caller that named where to start is reading forward from there; one that
- * named only where to stop is looking at the newest of what it asked for, and
- * answering with the oldest of that range would hand it the far side of a
- * transcript it is walking back through. With neither bound the range is the
- * whole transcript, which is read from its beginning. */
+ * A caller that named where to start is reading forward from there; anyone
+ * else is looking at the newest of what it asked for, and answering with the
+ * oldest of that range would hand it the far side of a transcript it is
+ * walking back through. Naming no bound at all is the ordinary first read and
+ * answers the tail the same way; a caller that wants the transcript from its
+ * beginning says so with `since_at: 0`. */
 function backwards(bounds: TranscriptItemsReadArgs): boolean {
   const lower =
     bounds.since_at !== undefined ||
     bounds.since_uuid !== undefined ||
     bounds.since_id !== undefined;
-  const upper =
-    bounds.until_at !== undefined ||
-    bounds.until_uuid !== undefined ||
-    bounds.until_id !== undefined;
-  return upper && !lower;
+  return !lower;
 }
 
 /** As much of the range as one answer carries, and where the next one starts.

package/src/transcript/index.ts

@@ -13,4 +13,4 @@ export {
 } from "./fold.ts";
 export { READ_LIMIT, readSlice } from "./read.ts";
 export { type Appended, FOLD_TAIL_BYTES, TranscriptTail } from "./tail.ts";
-export { Transcripts, type TranscriptsDeps } from "./transcripts.ts";
+export { ITEMS_SNAPSHOT, Transcripts, type TranscriptsDeps } from "./transcripts.ts";

package/src/transcript/items/classify.ts

@@ -58,9 +58,21 @@ const NOT_ITEMS = new Set([
 
 /** 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. */
+ * what comes back is also an answer.
+ *
+ * They arrive under one type. Two names for one thing would put the same item
+ * in the vocabulary twice, and a selection asking for the tool that starts an
+ * agent would have to know which spelling this transcript happened to use. The
+ * spelling the harness wrote stays on the item as `harness_name`, for a reader
+ * matching what it sees against what it ran. */
 const SPAWNS = new Set(["Agent", "Task"]);
 
+/** The name an item is typed under, which is the harness's own except where
+ * two of its names are one thing. */
+function typedAs(name: string): string {
+  return SPAWNS.has(name) ? "Agent" : name;
+}
+
 /** 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. */
@@ -135,8 +147,12 @@ export class Classification {
   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;
+    // A record the harness wrote without an id of its own still happened, and
+    // an item is pointed at by the record it came from — so where the record
+    // stands in the file stands in for the id it lacks. The `@` says which of
+    // the two it is, since a reader that groups by record must not take an
+    // address for something the harness will write again.
+    const uuid = str(record["uuid"]) ?? `@${String(source.offset)}`;
     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
@@ -242,15 +258,18 @@ export class Classification {
     const id = str(block["id"]) ?? "";
     const input = row(block["input"]) ?? {};
     const fields = useFields(name, input);
-    const tool = make(`tool:${segment(name)}`, {
+    const called = typedAs(name);
+    const item = make(`tool:${segment(called)}`, {
       role: "use",
       tool_use_id: id,
+      ...(called === name ? {} : { harness_name: name }),
       ...(fields ?? { input }),
     });
     let message: Draft | undefined;
     if (SPAWNS.has(name)) {
       message = make("message:sub:out", {
         role: "use",
+        tool_use_id: id,
         prompt: str(input["prompt"]) ?? "",
         ...optional("subagent_type", str(input["subagent_type"])),
         ...optional("name", str(input["name"])),
@@ -261,7 +280,7 @@ export class Classification {
       // 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) ? {} : { role: "use", tool_use_id: id }),
         ...(addressed(to)
           ? { text: text(input["message"]) ?? "", to }
           : // Writing to an agent is one direction of a correspondence, not a
@@ -283,7 +302,7 @@ export class Classification {
       const oldest = this.#calls.keys().next();
       if (oldest.done !== true) this.#calls.delete(oldest.value);
     }
-    this.#calls.set(id, { tool, name, ...optional("message", message) });
+    this.#calls.set(id, { tool: item, name: called, ...optional("message", message) });
   }
 
   #user(record: Row, make: Make): void {
@@ -313,12 +332,18 @@ export class Classification {
     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 });
+      // An answer to a call this reading never saw, which is what a reading
+      // that starts part-way down a file meets. The record says which call it
+      // answers and never which tool was called, so the type is the reserved
+      // name for a result whose tool this instance does not know rather than a
+      // name guessed from what came back. What ties it to the call is the key
+      // the harness paired them by, which a reader joins against the calls it
+      // holds.
+      make("tool:unknown", {
+        role: "result",
+        parent_tool_use_id: id,
+        result: genericResult(record["toolUseResult"]),
+      });
       return;
     }
     const failed = block["is_error"] === true;
@@ -327,7 +352,7 @@ export class Classification {
     const item = make(`tool:${segment(call.name)}`, {
       role: "result",
       parent_item: call.tool.id,
-      tool_use_id: id,
+      parent_tool_use_id: id,
       ...(fields ?? { result: genericResult(answer) }),
     });
     call.tool["result_item"] = item.id;
@@ -353,6 +378,7 @@ export class Classification {
     const reply = make("message:sub:in", {
       role: "result",
       parent_item: call.message.id,
+      parent_tool_use_id: id,
       text: said,
       ...optional("agent_id", agent),
       ...optional("status", str(result["status"])),
@@ -448,6 +474,7 @@ export class Classification {
       const item = make("message:sub:in", {
         role: "result",
         parent_item: asked.id,
+        parent_tool_use_id: key,
         text: answer,
         ...optional("agent_id", str(asked["agent_id"]) ?? tagged(said, "task-id")),
         ...optional("status", tagged(said, "status")),

package/src/transcript/items/document.ts

@@ -44,7 +44,15 @@ export function document(file: SessionDumpFile, view: DumpView = {}): string {
     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(
+      ...draw(
+        item,
+        child === undefined ? undefined : (items[child] as Item),
+        view,
+        paired.parent.get(at),
+      ),
+      "",
+    );
   }
   lines.push(...ledger(file.ids));
   return `${lines.join("\n").trimEnd()}\n`;
@@ -72,12 +80,12 @@ function heading(file: SessionDumpFile, view: DumpView): string[] {
  * 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[] {
+function draw(item: Item, child: Item | undefined, view: DumpView, parent?: string): 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("←", fields(item)["parent_item"])
+    ? arrow("←", parent)
     : (arrow("→", fields(item)["result_item"]) ?? waiting(item));
   const head = isResult(item)
     ? words(prefix(item), link, own.head, clock(item))
@@ -185,27 +193,49 @@ 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.
+/** Which answer belongs to which call, which call each answer points back at,
+ * and which of those pairs are drawn together.
  *
  * 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. */
+ * carry. An answer read where its call was not says instead which key the
+ * harness paired them by, and the call that names that key is the one it
+ * belongs to. */
 function pair(items: readonly Item[]): {
   child: Map<number, number>;
   folded: Set<number>;
+  parent: Map<number, string>;
 } {
   const child = new Map<number, number>();
   const folded = new Set<number>();
+  const parent = new Map<number, string>();
   const where = new Map<string, number>();
-  for (let at = 0; at < items.length; at += 1) where.set((items[at] as Item).id, at);
+  const called = new Map<string, string>();
+  for (let at = 0; at < items.length; at += 1) {
+    const item = items[at] as Item;
+    where.set(item.id, at);
+    const key = fields(item)["tool_use_id"];
+    if (fields(item)["role"] === "use" && typeof key === "string" && key !== "") {
+      called.set(joined(item, key), item.id);
+    }
+  }
   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.
     if (fields(item)["role"] !== "result") continue;
-    const parent = fields(item)["parent_item"];
-    const call = typeof parent === "string" ? where.get(parent) : undefined;
+    const named = fields(item)["parent_item"];
+    const key = fields(item)["parent_tool_use_id"];
+    const to =
+      typeof named === "string"
+        ? named
+        : typeof key === "string"
+          ? called.get(joined(item, key))
+          : undefined;
+    if (to === undefined) continue;
+    parent.set(at, to);
+    const call = where.get(to);
     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
@@ -214,5 +244,14 @@ function pair(items: readonly Item[]): {
     child.set(call, at);
     folded.add(at);
   }
-  return { child, folded };
+  return { child, folded, parent };
+}
+
+/** The key an exchange is joined on. One call the harness gave a key to is two
+ * items where it started an agent — the call and the brief beside it — so the
+ * side of the exchange goes into the key: a tool's answer belongs to the call
+ * and an agent's to the brief, and the harness's key alone would not say
+ * which. */
+function joined(item: Item, key: string): string {
+  return `${item.type.startsWith("message:sub") ? "sub" : "tool"}\n${key}`;
 }

package/src/transcript/tail.ts

@@ -1,4 +1,4 @@
-import { type FSWatcher, statSync, watch } from "node:fs";
+import { closeSync, type FSWatcher, openSync, readSync, statSync, watch } from "node:fs";
 import { open, stat } from "node:fs/promises";
 import { CONFIRM_POLL_MS } from "../sessions/harness.ts";
 
@@ -86,11 +86,16 @@ export class TranscriptTail {
   }
 
   /** Begin following, seeding the fold from the end of what is already there.
-   * Resolves once the seed has been read, so a snapshot taken after it states
-   * a size the fold has caught up with. */
+   *
+   * The seed is read before this returns rather than awaited, for the reason
+   * the size is read in the constructor: a subscription's snapshot is answered
+   * in the same turn the tail is started, and what the seed settles — the
+   * fold's values, and the items a subscriber opens on — would otherwise be
+   * stated as empty and the whole existing end of the file would arrive later
+   * as though it had just been appended. */
   async start(): Promise<void> {
     if (this.running) return;
-    await this.#seed();
+    this.#seed();
     try {
       this.#watcher = watch(this.path, () => void this.refresh());
     } catch {
@@ -116,11 +121,11 @@ export class TranscriptTail {
     return this.#reading;
   }
 
-  async #seed(): Promise<void> {
+  #seed(): void {
     const size = this.#size;
     if (size === 0) return;
     const from = Math.max(0, size - FOLD_TAIL_BYTES);
-    const complete = whole(await this.#slice(from, size));
+    const complete = whole(this.#sliceSync(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 is read are whole records or nothing.
@@ -164,6 +169,26 @@ export class TranscriptTail {
    * 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. */
+  /** The same range, read without yielding, which is what the seed is read
+   * through: the turn that starts a tail is the turn that answers a
+   * subscription, and it has to hold the end of the file by then. Bounded by
+   * `FOLD_TAIL_BYTES` however large the transcript is. */
+  #sliceSync(from: number, to: number): Buffer {
+    if (to <= from) return Buffer.alloc(0);
+    let handle: number;
+    try {
+      handle = openSync(this.path, "r");
+    } catch {
+      return Buffer.alloc(0);
+    }
+    try {
+      const buffer = Buffer.alloc(to - from);
+      return buffer.subarray(0, readSync(handle, buffer, 0, buffer.length, from));
+    } finally {
+      closeSync(handle);
+    }
+  }
+
   async #slice(from: number, to: number): Promise<Buffer> {
     if (to <= from) return Buffer.alloc(0);
     const handle = await open(this.path, "r").catch(() => undefined);