@ccmsg/cli 0.8.2 → 0.9.1

package/src/sessions/registry.ts

@@ -3,8 +3,10 @@ import { basename, dirname, isAbsolute, join } from "node:path";
 import {
   type AgentInfo,
   type Capability,
-  type HelloArgs,
+  type HelloInstanceArgs,
   type HelloResult,
+  type HelloSessionArgs,
+  type HelloUserArgs,
   type Endpoint,
   type AgentElement,
   type InstanceId,
@@ -115,7 +117,7 @@ export interface MeshSource {
 }
 
 /** The mesh claim a peer greets with, as the contract states it. */
-type MeshClaim = NonNullable<HelloArgs["mesh"]>;
+type MeshClaim = HelloInstanceArgs["mesh"];
 
 /** The fold, as the sessions domain reads it: two values about one session,
  * asked for when a payload is built rather than copied here when they change
@@ -137,7 +139,7 @@ export interface GatewaySource {
  * are the same fields under the same names — nothing is renamed on the way
  * through, and nothing is invented for a field the session left unsaid. */
 type SessionMeta = Pick<
-  HelloArgs,
+  HelloSessionArgs,
   "repo" | "ws" | "cwd" | "transcript_path" | "repo_root" | "branch" | "title" | "model" | "effort"
 >;
 
@@ -208,7 +210,7 @@ export class Sessions implements UpstreamResource {
    * Held here rather than written to `last_live`, because the declaration
    * arrives while the session is still connected and `last_live` holds what is
    * gone: the entry is written when the connection closes, and this is what
-   * stamps it then (contract, `session_stopping`). A session that declares and
+   * stamps it then (contract, `session.stopping`). A session that declares and
    * then carries on stays connected and keeps its declaration, which is spent
    * whenever it does leave. */
   readonly #stopping = new Map<Sid, Timestamp>();
@@ -252,55 +254,62 @@ export class Sessions implements UpstreamResource {
     for (const sid of live.keys()) this.#lastLive.remove(sid);
   }
 
-  /** `hello`, which is where a session becomes something this instance can
-   * speak about, and where everything this instance knows about where that
-   * session lives comes from.
+  /** `hello.session`, which is where a session becomes something this instance
+   * can speak about, and where everything this instance knows about where that
+   * session lives comes from. The greeting names its sid because the op it
+   * arrived under is the one whose schema asks for one. */
+  helloSession = (input: HandlerInput): HelloResult => {
+    const args = input.args as unknown as HelloSessionArgs;
+    this.#greetable(input, args.protocol_version);
+    this.register(args.sid, args);
+    input.conn.onClose(() => this.release(args.sid));
+    return this.#greeted(input);
+  };
+
+  /** `hello.user`. A person speaks for no session, so there is nothing to
+   * register: the greeting settles a role and answers what the instance is. */
+  helloUser = (input: HandlerInput): HelloResult => {
+    const args = input.args as unknown as HelloUserArgs;
+    this.#greetable(input, args.protocol_version);
+    return this.#greeted(input);
+  };
+
+  /** `hello.instance`. A peer's greeting is answered only once the connection
+   * has been proven to be the endpoint it names. The verification rejects when
+   * it is not, and the connection stays anonymous because nothing settles an
+   * identity but a reply (mesh-peer-auth §5, daemon-v2 §3.2 step 7). This is
+   * the one greeting that has to wait for something, which is why it is the one
+   * that answers with a promise. */
+  helloInstance = (input: HandlerInput): Promise<HelloResult> => {
+    const args = input.args as unknown as HelloInstanceArgs;
+    this.#greetable(input, args.protocol_version);
+    const mesh = this.deps.mesh;
+    if (mesh === undefined) {
+      throw new OpError(
+        "capability_unavailable",
+        "this instance has no mesh, so no peer connection can be proven",
+      );
+    }
+    return mesh.greet(input.conn, args.mesh).then(() => this.#greeted(input));
+  };
+
+  /** What each of the three greetings checks before it settles anything.
    *
-   * What registers a session is the greeting naming a sid, not the role it
-   * claims: the sid is the session it speaks for, and reading the role here
-   * would put the contract's "a session names its sid" rule in a second place
-   * (M1). */
-  hello = (input: HandlerInput): HelloResult | Promise<HelloResult> => {
-    const args = input.args as unknown as HelloArgs;
-    // A role is set once and fixed for the connection's life (contract, `Role`),
-    // so a second greeting is not a re-identification: it is a request to be
-    // somebody else on a connection that already is somebody.
+   * A role is set once and fixed for the connection's life (contract, `Role`),
+   * so a second greeting is not a re-identification: it is a request to be
+   * somebody else on a connection that already is somebody. */
+  #greetable(input: HandlerInput, protocolVersion: number): void {
     if (input.conn.identity.state === "settled") {
       throw new OpError("bad_request", "a connection greets once, and this one already has");
     }
-    if (args.protocol_version !== PROTOCOL_VERSION) {
+    if (protocolVersion !== PROTOCOL_VERSION) {
       throw new OpError("bad_request", `this instance speaks protocol ${PROTOCOL_VERSION}`);
     }
-    if (args.role === "instance") {
-      // A peer's greeting is answered only once the connection has been proven
-      // to be the endpoint it names. The verification rejects when it is not,
-      // and the connection stays anonymous because nothing settles an identity
-      // but a reply (mesh-peer-auth §5, daemon-v2 §3.2 step 7). This is the one
-      // greeting that has to wait for something, which is why it is the one
-      // that answers with a promise.
-      if (args.mesh === undefined) {
-        throw new OpError("invalid_args", "an instance greets with its mesh claim");
-      }
-      const mesh = this.deps.mesh;
-      if (mesh === undefined) {
-        throw new OpError(
-          "capability_unavailable",
-          "this instance has no mesh, so no peer connection can be proven",
-        );
-      }
-      return mesh.greet(input.conn, args.mesh).then(() => this.#greeted(args, input));
-    }
-    return this.#greeted(args, input);
-  };
+  }
 
   /** What every greeting answers, once whatever had to be settled has been. */
-  #greeted(args: HelloArgs, input: HandlerInput): HelloResult {
+  #greeted(input: HandlerInput): HelloResult {
     const expiresAt = this.deps.authExpiresAt?.(input.conn);
-    const sid = requiredSid(args);
-    if (sid !== undefined) {
-      this.register(sid, args);
-      input.conn.onClose(() => this.release(sid));
-    }
     return {
       protocol_version: PROTOCOL_VERSION,
       instance: this.deps.self,
@@ -439,7 +448,7 @@ export class Sessions implements UpstreamResource {
   }
 
   /** Drop one entry from `last_live`, which is what
-   * `session_last_live_remove` asks for. The removal touches that list alone:
+   * `session.forget` asks for. The removal touches that list alone:
    * the session stays resumable by every other route. */
   forget(sid: Sid): boolean {
     const removed = this.#lastLive.remove(sid);
@@ -453,7 +462,7 @@ export class Sessions implements UpstreamResource {
     this.changed();
   }
 
-  /** `session_stopping`: a session saying it is about to go, which is what
+  /** `session.stopping`: a session saying it is about to go, which is what
    * makes it Paused rather than Disappeared once it is gone (§5.2).
    *
    * Nothing is recorded now and nothing is published: the session is still
@@ -600,7 +609,7 @@ export class Sessions implements UpstreamResource {
    * silence for a retraction would let each of them erase what the last one
    * knew, and the session would be described by whichever process spoke most
    * recently rather than by everything it has said. */
-  private register(sid: Sid, args: HelloArgs): void {
+  private register(sid: Sid, args: HelloSessionArgs): void {
     const now = Date.now();
     const held = this.#connected.get(sid);
     const meta = {
@@ -652,7 +661,7 @@ export class Sessions implements UpstreamResource {
     for (const [sid, entry] of this.#live) {
       if (live.has(sid)) continue;
       // The declaration came first and the departure has now arrived, which is
-      // the order the two are one event in (contract, `session_stopping`).
+      // the order the two are one event in (contract, `session.stopping`).
       const stoppedAt = this.#stopping.get(sid);
       this.#stopping.delete(sid);
       this.#lastLive.record({
@@ -769,11 +778,11 @@ export class Sessions implements UpstreamResource {
    * id, so what it reports is not by itself evidence about *this* instance's
    * sessions: a session id belonging to another config home would otherwise
    * classify as live here, put a row on this instance's `peers`, and make
-   * `message_send` accept a message for a session that has no inbox here and
+   * `message.send` accept a message for a session that has no inbox here and
    * never will. So the reading is narrowed to the sids this instance knows —
    * one that has greeted us, still connected or remembered in `last_live`, or
    * one the harness's own `sessions/` names. The events themselves are not
-   * dropped: `llm_requests` carries what the gateway saw whoever it was for,
+   * dropped: `llm.requests` carries what the gateway saw whoever it was for,
    * because that topic is a view of the gateway rather than of this instance's
    * sessions. */
   #gatewayActiveAt(sid: Sid, inHarness: boolean): Timestamp | undefined {
@@ -834,7 +843,7 @@ export class Sessions implements UpstreamResource {
  * that is simply absent from what `peers` says. */
 function metaOf(
   deps: Pick<SessionsDeps, "configHome" | "harness">,
-  args: HelloArgs,
+  args: HelloSessionArgs,
   refused: (reason: string) => void,
 ): SessionMeta {
   const meta: Record<string, string> = {};
@@ -924,29 +933,3 @@ function resolveAsFarAsItGoes(path: string): string | undefined {
     }
   }
 }
-
-/** What each role must and must not say when it greets.
- *
- * The sid is what registers a session, so which role is entitled to name one is
- * decided here rather than left to whoever reads the field: a `user` naming a
- * sid would be a person registering as the session, and a `session` without one
- * is a session this instance cannot speak about. */
-function requiredSid(args: HelloArgs): Sid | undefined {
-  switch (args.role) {
-    case "session":
-      if (args.sid === undefined) throw new OpError("invalid_args", "a session names its sid");
-      return args.sid;
-    case "user":
-      if (args.sid !== undefined) {
-        throw new OpError("invalid_args", "a sid is the greeting of a session, not of a person");
-      }
-      return undefined;
-    case "instance":
-      // A peer speaks for no session: what it is has already been settled by
-      // the handshake, and a sid here would be it registering as one.
-      if (args.sid !== undefined) {
-        throw new OpError("invalid_args", "a sid is the greeting of a session, not of an instance");
-      }
-      return undefined;
-  }
-}

package/src/sessions/search.ts

@@ -20,7 +20,7 @@ import { readRecord, type TranscriptFile, type TranscriptFiles } from "../transc
 const SCAN_BUDGET_BYTES = 64 * 1024 * 1024;
 const HITS = 50;
 /** What one hit shows of what it matched. Enough to recognise the passage;
- * the transcript itself is one `transcript_read` away. */
+ * the transcript itself is one `transcript.read` away. */
 const MATCHES_PER_HIT = 5;
 const MATCH_CHARS = 400;
 

package/src/sessions/status.ts

@@ -14,14 +14,14 @@ import { workspaceFolders } from "./workspace.ts";
 /** What the fold says stopped a session, read in one place.
  *
  * Three values rest on it: whether a live session is Waiting (§5.2), what
- * `session_errors` lists, and the `api_error` of `session_status:<sid>`. They
+ * `session.errors` lists, and the `api_error` of `session.status:<sid>`. They
  * ask this rather than each reading the fold's field, so the three cannot come
  * to different answers about the same session (§7.4, M5). */
 export function stoppedOn(facts: TranscriptFacts): SessionApiError | undefined {
   return facts.api_error;
 }
 
-/** The `session_status:<sid>` payload.
+/** The `session.status:<sid>` payload.
  *
  * Almost every field is the fold's, stated as the fold left it: one pass over
  * the transcript settles the error, the task list, the files it named and what
@@ -61,7 +61,7 @@ export function sessionStatusOf(
 }
 
 /** Where a session works, as it greeted (§5.1). The same two values the file
- * surfaces are decided against, asked for here so that what `session_status`
+ * surfaces are decided against, asked for here so that what `session.status`
  * says and what a read is admitted by come from one answer. */
 export interface SessionWhere {
   readonly root?: string;
@@ -88,7 +88,7 @@ export interface SessionStatusDeps {
 /** The two topics the fold's error state feeds, and the tails they keep
  * running (§6.3).
  *
- * `session_errors` is one list for the instance and `session_status:<sid>` is
+ * `session.errors` is one list for the instance and `session.status:<sid>` is
  * one session, so what they hold differs: the first wants every session's fold
  * and the second wants one. Both wants are the same mechanism — a subscription
  * arrives, the tails it needs are held, and the last subscription to go
@@ -170,7 +170,7 @@ export class SessionStatus implements UpstreamResource {
   /** What a topic of this owner currently says, for a snapshot and for a
    * change alike — built here and nowhere else, so the two cannot drift. */
   private value(topic: string): unknown {
-    if (topic === "session_errors") return this.errors();
+    if (topic === "session.errors") return this.errors();
     const sid = topicParam(topic);
     return sid === undefined
       ? undefined
@@ -196,11 +196,11 @@ export class SessionStatus implements UpstreamResource {
     const wanted = new Set<Sid>();
     // One list for the instance means every session's fold; the list is what
     // the subscriber asked for, and it cannot be built from a subset of it.
-    if (this.#wanted.has("session_errors")) {
+    if (this.#wanted.has("session.errors")) {
       for (const sid of this.deps.sessions()) wanted.add(sid);
     }
     for (const topic of this.#wanted) {
-      if (topic === "session_errors") continue;
+      if (topic === "session.errors") continue;
       const sid = topicParam(topic);
       if (sid !== undefined) wanted.add(sid);
     }

package/src/topics/handlers.ts

@@ -7,12 +7,12 @@ import type { SubscribeOutcome, Topics } from "./topics.ts";
  * it to `Topics`, and turns the outcome into the contract's own answer. */
 export function topicHandlers(topics: Topics) {
   return {
-    topic_subscribe: (input: HandlerInput): TopicSubscribeResult => {
+    "topic.subscribe": (input: HandlerInput): TopicSubscribeResult => {
       const topic = topicOf(input);
       answer(topics.subscribe(input.conn, topic), topic);
       return { topic };
     },
-    topic_unsubscribe: (input: HandlerInput): TopicSubscribeResult => {
+    "topic.unsubscribe": (input: HandlerInput): TopicSubscribeResult => {
       const topic = topicOf(input);
       answer(topics.unsubscribe(input.conn, topic), topic);
       return { topic };

package/src/transcript/items/classify.ts

@@ -31,7 +31,7 @@ import { genericResult, resultFields, useFields } from "./tools.ts";
  *
  * Nothing is dropped for being unrecognised. A tool nobody wrote fields for
  * arrives with what it was called with, an attachment arrives under its own
- * kind, and a record that fits nothing arrives as `system:unknown`. The one
+ * kind, and a record that fits nothing arrives as `system.unknown`. The one
  * failure a dump cannot be read around is a line that vanished quietly. */
 
 /** Record types that are the interface and the session's own bookkeeping
@@ -112,8 +112,8 @@ export function classify(records: Iterable<Located>, subject: TranscriptSubject
 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
+   * with. Holds the `tool.*` item and, for an `Agent` call, the
+   * `message.sub.out` beside it — the same exchange seen from the two sides
    * the contract names it from. */
   readonly #calls = new Map<string, { tool: Draft; message?: Draft; name: string }>();
   #turn = 0;
@@ -198,7 +198,7 @@ export class Classification {
     if (type === "system") return this.#system(record, make);
     if (type === "assistant") return this.#assistant(record, make);
     if (type === "user") return this.#user(record, make);
-    make("system:unknown", { record });
+    make("system.unknown", { record });
   }
 
   /** An attachment is either the operator's own code speaking or the harness
@@ -210,10 +210,10 @@ export class Classification {
     if (kind === "hook_additional_context" || kind === "hook_success") {
       const name = str(attachment["hookName"]) ?? "";
       // The event alone is the type. A hook runs under `PreToolUse:Bash`,
-      // whose `:` would read as another level of the hierarchy and leave
-      // `hook:PreToolUse` selecting nothing.
+      // whose matcher is no level of a hierarchy: carrying it would make
+      // `hook.PreToolUse` select nothing, so it is a field instead.
       const event = str(attachment["hookEvent"]) ?? name.split(":")[0] ?? "";
-      make(`hook:${segment(event)}`, {
+      make(`hook.${segment(event)}`, {
         hook_name: name,
         outcome: kind === "hook_success" ? "output" : "additionalContext",
         ...optional("content", text(attachment["content"])),
@@ -225,7 +225,7 @@ export class Classification {
       });
       return;
     }
-    make(`system:attachment:${segment(kind ?? "unknown")}`, { attachment });
+    make(`system.attachment.${segment(kind ?? "unknown")}`, { attachment });
   }
 
   /** The harness files a slash command's output as a line of its own, which
@@ -235,19 +235,19 @@ export class Classification {
   #system(record: Row, make: Make): void {
     if (str(record["subtype"]) === "local_command") {
       const content = str(record["content"]) ?? "";
-      make("notice:slash", {
+      make("notice.slash", {
         command: this.#slash ?? "",
         ...optional("stdout", tagged(content, "local-command-stdout") ?? content),
       });
       return;
     }
-    make("system:unknown", { record });
+    make("system.unknown", { record });
   }
 
   #assistant(record: Row, make: Make): void {
     const message = row(record["message"]) ?? {};
     if (record["isApiErrorMessage"] === true) {
-      make("system:api-error", { text: text(message["content"]) ?? "" });
+      make("system.api.error", { text: text(message["content"]) ?? "" });
       return;
     }
     for (const block of list(message["content"])) {
@@ -265,7 +265,7 @@ export class Classification {
         // them is the answer it was started for, and the ones before are what
         // it hands back mid-flight. No call carries them, which is why
         // `parent:out` is prose as well as a call.
-        const kind = this.#subject === "main" ? "message:user:out" : "message:parent:out";
+        const kind = this.#subject === "main" ? "message.user.out" : "message.parent.out";
         if (said !== undefined && said !== "") make(kind, { text: said });
         continue;
       }
@@ -286,7 +286,7 @@ export class Classification {
     const input = row(block["input"]) ?? {};
     const fields = useFields(name, input);
     const called = typedAs(name);
-    const item = make(`tool:${segment(called)}`, {
+    const item = make(`tool.${segment(called)}`, {
       role: "use",
       tool_use_id: id,
       ...(called === name ? {} : { harness_name: name }),
@@ -301,14 +301,14 @@ export class Classification {
       const named = str(input["name"]) ?? str(input["team_name"]);
       message =
         named === undefined
-          ? make("message:sub:out", {
+          ? make("message.sub.out", {
               role: "use",
               tool_use_id: id,
               prompt: str(input["prompt"]) ?? "",
               ...optional("subagent_type", str(input["subagent_type"])),
               ...optional("description", str(input["description"])),
             })
-          : make("message:team:out", {
+          : make("message.team.out", {
               role: "use",
               tool_use_id: id,
               text: str(input["prompt"]) ?? "",
@@ -323,14 +323,14 @@ export class Classification {
       // the names a harness gives a lead, and any other name is somebody
       // standing alongside.
       if (addressed(to)) {
-        make("message:session:out", { text: text(input["message"]) ?? "", to });
+        make("message.session.out", { text: text(input["message"]) ?? "", to });
       } else {
         // Writing to an agent is one direction of a correspondence, not a call
         // that returns: what it says back arrives as its own message whenever
         // it chooses to send one, under nothing that names this. So the
         // message says it is waiting for nothing, and a reader is not left
         // watching for an answer that has no way in.
-        make(LEADS.has(to) ? "message:parent:out" : "message:team:out", {
+        make(LEADS.has(to) ? "message.parent.out" : "message.team.out", {
           role: "use",
           tool_use_id: id,
           text: text(input["message"]) ?? "",
@@ -340,7 +340,7 @@ export class Classification {
         });
       }
     } else if (name === "Bash" && isCcmsgSend(str(input["command"]))) {
-      make("message:session:out", { text: str(input["command"]) ?? "" });
+      make("message.session.out", { text: str(input["command"]) ?? "" });
     }
     if (id === "") return;
     // A call is dropped from the pairing once it has been answered, so what is
@@ -388,7 +388,7 @@ export class Classification {
       // 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", {
+      make("tool.unknown", {
         role: "result",
         parent_tool_use_id: id,
         result: genericResult(record["toolUseResult"]),
@@ -398,7 +398,7 @@ export class Classification {
     const failed = block["is_error"] === true;
     const answer = record["toolUseResult"];
     const fields = resultFields(call.name, answer, failed);
-    const item = make(`tool:${segment(call.name)}`, {
+    const item = make(`tool.${segment(call.name)}`, {
       role: "result",
       parent_item: call.tool.id,
       parent_tool_use_id: id,
@@ -446,17 +446,17 @@ export class Classification {
    * so nothing the harness injected is mistaken for someone speaking. */
   #said(record: Row, said: string, make: Make): void {
     if (record["isCompactSummary"] === true) {
-      make("system:compact", { text: said });
+      make("system.compact", { text: said });
       return;
     }
     if (said.startsWith("<local-command-caveat>")) {
-      make("system:caveat", { text: said });
+      make("system.caveat", { text: said });
       return;
     }
     const command = tagged(said, "command-name");
     if (command !== undefined) {
       this.#slash = command;
-      make("notice:slash", {
+      make("notice.slash", {
         command,
         ...optional("args", tagged(said, "command-args") ?? tagged(said, "command-message")),
         ...optional("stdout", tagged(said, "local-command-stdout")),
@@ -464,11 +464,11 @@ export class Classification {
       return;
     }
     if (said.startsWith("[Request interrupted")) {
-      make("notice:interrupt", { text: said });
+      make("notice.interrupt", { text: said });
       return;
     }
     if (said.startsWith("Resume the paused workflow by calling: Workflow({")) {
-      make("system:resume", { text: said });
+      make("system.resume", { text: said });
       return;
     }
     if (said.startsWith("<task-notification>")) {
@@ -483,14 +483,14 @@ export class Classification {
     // stands, being told what to do is not the same as being written to.
     if (record["parentUuid"] === null) {
       this.#turn += 1;
-      make(this.#subject === "main" ? "message:user:in" : "message:parent:in", {
+      make(this.#subject === "main" ? "message.user.in" : "message.parent.in", {
         text: said,
         ...(this.#subject === "main" ? {} : envelope(said)),
       });
       return;
     }
     if (said.includes("<cross-session-message")) {
-      make("message:session:in", {
+      make("message.session.in", {
         text: said,
         ...optional("from", attribute(said, "from")),
         ...optional("msg_id", attribute(said, "mid")),
@@ -503,14 +503,14 @@ export class Classification {
       // name is somebody standing alongside, and what they send is a message
       // of its own rather than the answer to anything.
       const from = attribute(said, "teammate_id");
-      make(LEADS.has(from ?? "") ? "message:parent:in" : "message:team:in", {
+      make(LEADS.has(from ?? "") ? "message.parent.in" : "message.team.in", {
         text: said,
         ...envelope(said),
       });
       return;
     }
     if (record["isMeta"] === true) {
-      make("system:unknown", { record });
+      make("system.unknown", { record });
       return;
     }
     // What is left is somebody writing to the subject in their own words, and
@@ -522,7 +522,7 @@ export class Classification {
     // A turn begins where the subject is addressed, which is the only place a
     // dump can count turns from — the harness numbers nothing.
     this.#turn += 1;
-    make(this.#subject === "sub" ? "message:parent:in" : "message:user:in", { text: said });
+    make(this.#subject === "sub" ? "message.parent.in" : "message.user.in", { text: said });
   }
 
   /** A background task reporting, or an agent handing back its answer.
@@ -554,7 +554,7 @@ export class Classification {
       this.#calls.delete(key);
       return;
     }
-    make("system:task", {
+    make("system.task", {
       text: said,
       ...optional("task_id", tagged(said, "task-id")),
       ...optional("event", tagged(said, "event") ?? tagged(said, "summary")),
@@ -594,7 +594,7 @@ function envelope(said: string): Record<string, unknown> {
  * whatever asked for it: a teammate's run ending answers the call that started
  * it, an errand's answer is the errand's result. */
 function answers(asked: Draft): string {
-  return asked.type === "message:team:out" ? "message:team:in" : "message:sub:in";
+  return asked.type === "message.team.out" ? "message.team.in" : "message.sub.in";
 }
 
 /** Whether a shell command is this session speaking to another one. */
@@ -603,12 +603,17 @@ function isCcmsgSend(command: string | undefined): boolean {
   return /\bccmsg\s+(post|reply)\b/.test(command);
 }
 
-/** One segment of a type name. The harness's own spellings pass through — they
- * are what a reader matches against what it ran — and a character the name
- * could not carry is replaced rather than the segment being refused, so a
- * newcomer still arrives under something close to its own name. */
+/** The last segment of an open family's type name (`tool.<Name>`,
+ * `system.attachment.<kind>`, `hook.<Event>`). The harness's own spellings pass
+ * through — they are what a reader matches against what it ran — and a
+ * character the name could not carry is replaced rather than the segment being
+ * refused, so a newcomer still arrives under something close to its own name.
+ *
+ * A `.` in the harness's name is written `_`: the reader splits a type on `.`
+ * to walk its hierarchy, and a name carrying one of its own would read as a
+ * level this contract never coined (contract, `TranscriptItemType`). */
 function segment(name: string): string {
-  const cleaned = name.replace(/[^A-Za-z0-9_.-]/g, "-");
+  const cleaned = name.replace(/\./g, "_").replace(/[^A-Za-z0-9_-]/g, "-");
   return cleaned === "" ? "unknown" : cleaned;
 }
 

package/src/transcript/items/document.ts

@@ -253,7 +253,7 @@ function pair(items: readonly Item[]): {
  * the call and an agent's to the message, and the harness's key alone would
  * not say which. */
 function joined(item: Item, key: string): string {
-  return `${item.type.startsWith("message:") ? "message" : "tool"}\n${key}`;
+  return `${item.type.startsWith("message.") ? "message" : "tool"}\n${key}`;
 }
 
 /** Whether an item is the conversation half of starting an agent, as opposed
@@ -262,5 +262,5 @@ function joined(item: Item, key: string): string {
  * they ended up — a conversation split across the page is one nobody can
  * follow. */
 function spoken(type: string): boolean {
-  return type.startsWith("message:sub") || type.startsWith("message:team");
+  return type.startsWith("message.sub") || type.startsWith("message.team");
 }