@ccmsg/protocol 1.20.0 → 1.22.0

package/src/common/hello.ts

@@ -3,7 +3,7 @@ import { request, response } from "../envelope.ts";
 import { Capability, Endpoint, InstanceId, Role, Sid, Timestamp } from "../identifiers.ts";
 import { SessionMetaFields } from "../session-meta.ts";
 
-/** The mesh handshake's opening claim, carried by a `role: "instance"` hello.
+/** The mesh handshake's opening claim, carried by `hello.instance`.
  *
  * It is not signed and proves nothing on its own: it names the peer and says
  * where its one-off key can be fetched. The proof that binds this connection to
@@ -36,42 +36,39 @@ export const MeshHello = Type.Object(
 );
 export type MeshHello = Static<typeof MeshHello>;
 
-/** The greeting that settles what a connection is.
- *
- * Which of the fields below are required is decided by `role`, which no single
- * object schema can state — so the instance checks it, and a greeting that
- * breaks one of these is refused with `invalid_args`:
- *
- * - `role: "session"` carries `sid`.
- * - `role: "user"` carries no `sid`: a person speaks for no one session, and a
- *   greeting that names one is refused rather than quietly ignored.
- * - `role: "instance"` carries `mesh`.
+/** What every greeting carries, whichever of the three it is. */
+const GREETING_FIELDS = {
+  /** The generation the caller speaks. A hello announcing another generation
+   * is refused with `bad_request`; there is no path that serves it anyway. */
+  protocol_version: Type.Integer({ minimum: 1 }),
+  /** The client build, for display in diagnostics. Nothing gates on it. */
+  client_version: Type.Optional(Type.String()),
+};
+
+/** The greeting that settles what a connection is. There is one op per role,
+ * so what a greeting must carry is the schema's to state rather than a check
+ * the instance runs against a `role` field: a session names its `sid`, an
+ * instance its mesh claim, and a person neither.
  *
- * A field that belongs to another role is as much a refusal as a missing one:
+ * A field that belongs to another role is as much a refusal as a missing one —
  * `mesh` on a session greeting says the caller has confused which handshake it
- * is in, and accepting it would leave the connection settled as something
- * neither side meant.
+ * is in — which is what the three ops keep apart: a greeting arrives under the
+ * name of the thing it settles, and there is no state in which the name and the
+ * fields disagree.
  *
  * A session's meta (`cwd`, `repo_root`, `transcript_path`, `title`, ...) is
  * taken field by field: a greeting that leaves a field out does not withdraw
  * it, and the instance keeps what it already knows for that `sid`. One session
  * reaches an instance as a run of short-lived processes (a session-start hook,
  * a `post`, a session-end hook), none of which knows every field. */
-export const HelloArgs = Type.Object({
-  role: Role,
-  /** The generation the caller speaks. A hello announcing another generation
-   * is refused with `bad_request`; there is no path that serves it anyway. */
-  protocol_version: Type.Integer({ minimum: 1 }),
-  /** Required for `role: "session"`: the session the connection speaks for. */
-  sid: Type.Optional(Sid),
-  /** Required for `role: "instance"`: the mesh handshake claim. */
-  mesh: Type.Optional(MeshHello),
-  /** The client build, for display in diagnostics. Nothing gates on it. */
-  client_version: Type.Optional(Type.String()),
-  /** What a `role: "session"` connection says about itself. All optional: a
-   * session states what it knows, and the instance derives or leaves unknown
-   * what it is not told. The instance repeats these on the `peers` topic, so
-   * they are the same fields under the same names there. */
+export const HelloSessionArgs = Type.Object({
+  ...GREETING_FIELDS,
+  /** The session the connection speaks for. */
+  sid: Sid,
+  /** What the session says about itself. All optional: a session states what it
+   * knows, and the instance derives or leaves unknown what it is not told. The
+   * instance repeats these on the `peers` topic, so they are the same fields
+   * under the same names there. */
   repo: Type.Optional(SessionMetaFields.repo),
   ws: Type.Optional(SessionMetaFields.ws),
   cwd: Type.Optional(SessionMetaFields.cwd),
@@ -82,9 +79,22 @@ export const HelloArgs = Type.Object({
   model: Type.Optional(SessionMetaFields.model),
   effort: Type.Optional(SessionMetaFields.effort),
 });
-export type HelloArgs = Static<typeof HelloArgs>;
+export type HelloSessionArgs = Static<typeof HelloSessionArgs>;
+
+/** A person greeting. It names no session: a person speaks for none of them,
+ * and the sessions they may act on are decided by the op table rather than by
+ * anything settled here. */
+export const HelloUserArgs = Type.Object(GREETING_FIELDS);
+export type HelloUserArgs = Static<typeof HelloUserArgs>;
+
+/** A peer instance greeting, which opens the mesh handshake. */
+export const HelloInstanceArgs = Type.Object({
+  ...GREETING_FIELDS,
+  mesh: MeshHello,
+});
+export type HelloInstanceArgs = Static<typeof HelloInstanceArgs>;
 
-/** One instance as seen from the instance answering `hello`. */
+/** One instance as seen from the instance answering a greeting. */
 export const InstanceInfo = Type.Object(
   {
     /** Absent until the handshake with it has settled: an endpoint an operator
@@ -148,10 +158,38 @@ export const HelloResult = Type.Object({
    * closes it. Present on a connection an access token opened; absent where
    * reaching the instance is itself the permission (the Unix socket) or where
    * the connection is a mesh link. The person's client renews before this
-   * instant with `auth_refresh` rather than reconnecting. */
+   * instant with `auth.extend` rather than reconnecting. */
   auth_expires_at: Type.Optional(Timestamp),
 });
 export type HelloResult = Static<typeof HelloResult>;
 
-export const HelloRequest = request("hello", HelloArgs);
-export const HelloResponse = response("hello", HelloResult);
+export const HelloSessionRequest = request("hello.session", HelloSessionArgs);
+export const HelloSessionResponse = response("hello.session", HelloResult);
+
+export const HelloUserRequest = request("hello.user", HelloUserArgs);
+export const HelloUserResponse = response("hello.user", HelloResult);
+
+export const HelloInstanceRequest = request("hello.instance", HelloInstanceArgs);
+export const HelloInstanceResponse = response("hello.instance", HelloResult);
+
+/** The role a greeting settles, read from the op that carried it.
+ *
+ * The role itself stays — the op table and the topic table are written against
+ * it, and a forwarded request names it in `caller` — and what a greeting no
+ * longer carries is a second place to say it. */
+export const HELLO_OPS = {
+  "hello.session": "session",
+  "hello.user": "user",
+  "hello.instance": "instance",
+} as const satisfies Record<string, Role>;
+
+export type HelloOp = keyof typeof HELLO_OPS;
+
+export function isHelloOp(op: string): op is HelloOp {
+  return op in HELLO_OPS;
+}
+
+/** The role a connection speaks once `op` has been answered. */
+export function helloRole(op: HelloOp): Role {
+  return HELLO_OPS[op];
+}

package/src/common/ping.ts

@@ -33,5 +33,5 @@ export const InstancePingResult = Type.Object({
 });
 export type InstancePingResult = Static<typeof InstancePingResult>;
 
-export const InstancePingRequest = request("instance_ping", InstancePingArgs);
-export const InstancePingResponse = response("instance_ping", InstancePingResult);
+export const InstancePingRequest = request("instance.ping", InstancePingArgs);
+export const InstancePingResponse = response("instance.ping", InstancePingResult);

package/src/common/shutdown.ts

@@ -11,8 +11,8 @@ export type InstanceShutdownArgs = Static<typeof InstanceShutdownArgs>;
 export const InstanceShutdownResult = Type.Object({});
 export type InstanceShutdownResult = Static<typeof InstanceShutdownResult>;
 
-export const InstanceShutdownRequest = request("instance_shutdown", InstanceShutdownArgs);
-export const InstanceShutdownResponse = response("instance_shutdown", InstanceShutdownResult);
+export const InstanceShutdownRequest = request("instance.shutdown", InstanceShutdownArgs);
+export const InstanceShutdownResponse = response("instance.shutdown", InstanceShutdownResult);
 
 /** A session saying it is about to go, so that its disconnection reads as a
  * pause rather than a loss.
@@ -44,5 +44,5 @@ export const SessionStoppingResult = Type.Object({
 });
 export type SessionStoppingResult = Static<typeof SessionStoppingResult>;
 
-export const SessionStoppingRequest = request("session_stopping", SessionStoppingArgs);
-export const SessionStoppingResponse = response("session_stopping", SessionStoppingResult);
+export const SessionStoppingRequest = request("session.stopping", SessionStoppingArgs);
+export const SessionStoppingResponse = response("session.stopping", SessionStoppingResult);

package/src/common/topics.ts

@@ -9,14 +9,14 @@ export const PLAIN_TOPICS = [
   "peers",
   "instances",
   "agents",
-  "session_errors",
-  "llm_requests",
-  "llm_status",
-  "auth_records",
+  "session.errors",
+  "llm.requests",
+  "llm.status",
+  "auth.records",
 ] as const;
 
 /** Topics naming one session, written `<topic>:<sid>`. */
-export const SESSION_SCOPED_TOPICS = ["session_status", "transcript", "transcript_items"] as const;
+export const SESSION_SCOPED_TOPICS = ["session.status", "transcript", "transcript.items"] as const;
 
 /** Topics naming one namespace, written `<topic>:<ns>`. The parameter is a name
  * its users choose rather than an identifier this contract issues, so it is
@@ -36,13 +36,18 @@ export type TopicName =
   | `${SessionScopedTopic}:${string}`
   | `${NamespaceScopedTopic}:${string}`;
 
+/** A topic name is a `.`-separated hierarchy, so its dots are literal here
+ * rather than the regexp's any-character. */
+const alternation = (topics: readonly string[]): string =>
+  topics.map((topic) => topic.replace(/\./g, "\\.")).join("|");
+
 export const Topic = Type.String({
   $id: "Topic",
   pattern: [
     "^(?:",
-    PLAIN_TOPICS.join("|"),
-    `|(?:${SESSION_SCOPED_TOPICS.join("|")}):[0-9a-f-]{36}`,
-    `|(?:${NAMESPACE_SCOPED_TOPICS.join("|")}):${NAMESPACE_PATTERN}`,
+    alternation(PLAIN_TOPICS),
+    `|(?:${alternation(SESSION_SCOPED_TOPICS)}):[0-9a-f-]{36}`,
+    `|(?:${alternation(NAMESPACE_SCOPED_TOPICS)}):${NAMESPACE_PATTERN}`,
     ")$",
   ].join(""),
 });
@@ -101,27 +106,27 @@ export const TOPIC_ATTRIBUTES = {
   // A set the instance derives whole, by folding one error pattern over its
   // sessions: it learns which sessions are stopped, not that one of them
   // changed, so each frame is that reading entire.
-  session_errors: { roles: ["user"], granularity: "per_instance_whole" },
-  llm_requests: {
+  "session.errors": { roles: ["user"], granularity: "per_instance_whole" },
+  "llm.requests": {
     roles: ["user"],
     capability: "llm_events",
     granularity: "per_instance_whole",
   },
-  llm_status: { roles: ["user"], capability: "llm_status", granularity: "per_instance_whole" },
+  "llm.status": { roles: ["user"], capability: "llm_status", granularity: "per_instance_whole" },
   // One session lives on one instance, so its status has no other instance's
   // half to leave alone: the frame is simply the whole of it.
-  session_status: { roles: ["user"], granularity: "whole" },
+  "session.status": { roles: ["user"], granularity: "whole" },
   transcript: { roles: ["user"], granularity: "append" },
   // The same appending, in items rather than in bytes. Both are offered because
   // they answer different needs: one draws the conversation, the other shows a
   // record as it was written.
-  transcript_items: { roles: ["user"], granularity: "append" },
+  "transcript.items": { roles: ["user"], granularity: "append" },
   kv: { roles: ["user"], granularity: "element" },
   // The only topic no person may subscribe to: its elements are the secrets
   // that authenticate them. A relay carries it as the instance it is, not on a
   // caller's behalf, so there is no path by which a person's subscription
   // reaches it.
-  auth_records: { roles: ["instance"], granularity: "element" },
+  "auth.records": { roles: ["instance"], granularity: "element" },
 } as const satisfies Record<
   PlainTopic | SessionScopedTopic | NamespaceScopedTopic,
   TopicAttributes
@@ -136,7 +141,7 @@ export function topicKind(topic: string): TopicKind | undefined {
 }
 
 /** How the frames of a topic name fold, taken from the name a subscriber
- * actually uses — `session_status:<sid>` rather than the kind behind it.
+ * actually uses — `session.status:<sid>` rather than the kind behind it.
  * `undefined` for a name this generation does not define. */
 export function topicGranularity(topic: string): TopicGranularity | undefined {
   const kind = topicKind(topic);
@@ -152,8 +157,8 @@ export type TopicSubscribeArgs = Static<typeof TopicSubscribeArgs>;
 export const TopicSubscribeResult = Type.Object({ topic: Topic });
 export type TopicSubscribeResult = Static<typeof TopicSubscribeResult>;
 
-export const TopicSubscribeRequest = request("topic_subscribe", TopicSubscribeArgs);
-export const TopicSubscribeResponse = response("topic_subscribe", TopicSubscribeResult);
+export const TopicSubscribeRequest = request("topic.subscribe", TopicSubscribeArgs);
+export const TopicSubscribeResponse = response("topic.subscribe", TopicSubscribeResult);
 
 export const TopicUnsubscribeArgs = Type.Object({ topic: Topic });
 export type TopicUnsubscribeArgs = Static<typeof TopicUnsubscribeArgs>;
@@ -161,5 +166,5 @@ export type TopicUnsubscribeArgs = Static<typeof TopicUnsubscribeArgs>;
 export const TopicUnsubscribeResult = Type.Object({ topic: Topic });
 export type TopicUnsubscribeResult = Static<typeof TopicUnsubscribeResult>;
 
-export const TopicUnsubscribeRequest = request("topic_unsubscribe", TopicUnsubscribeArgs);
-export const TopicUnsubscribeResponse = response("topic_unsubscribe", TopicUnsubscribeResult);
+export const TopicUnsubscribeRequest = request("topic.unsubscribe", TopicUnsubscribeArgs);
+export const TopicUnsubscribeResponse = response("topic.unsubscribe", TopicUnsubscribeResult);

package/src/control/dump.ts

@@ -13,8 +13,8 @@ import { Sid, Timestamp } from "../identifiers.ts";
  * down here. That split is what lets a harness change its file, or a second
  * harness be read at all, without the contract moving.
  *
- * A type name is `:`-separated and read left to right, so a prefix names
- * everything below it: `tool` is every tool, `message:user` is both directions
+ * A type name is `.`-separated and read left to right, so a prefix names
+ * everything below it: `tool` is every tool, `message.user` is both directions
  * of what a person and a session said. Three families stay open, because their
  * last segment is a name someone else coins — a tool, an attachment kind, a
  * hook event — and closing them would turn every newcomer into `unknown`. */
@@ -22,49 +22,56 @@ import { Sid, Timestamp } from "../identifiers.ts";
 /** A type name as written on the wire and in a selection.
  *
  * Segments after the first carry the spelling of whatever named them, which is
- * why they are not held to snake_case: `tool:Bash` and `hook:PreToolUse` are
+ * why they are not held to snake_case: `tool.Bash` and `hook.PreToolUse` are
  * the harness's words, and rewriting them would leave the reader unable to
- * match what it sees against what it ran.
+ * match what it sees against what it ran. That segment carries no `.` of its
+ * own — a harness name holding one is written with `_` by whoever coins the
+ * type — so a reader may split any type name on `.` and get the hierarchy.
+ *
+ * `tool.unknown` is the reserved name for a call whose tool the reader could
+ * not name. It is a coined segment like any other, so a harness tool actually
+ * called `unknown` lands on it; what is lost is that distinction and nothing
+ * else, where dropping the item would lose the call.
  *
  * Under `message`, the second segment is **a relation read from the subject**:
  * `parent` is whoever started this agent, `sub` a throwaway agent it started,
  * `team` a named counterpart that goes on standing, `session` another session
  * over ccmsg. The one exception is `user` — a person is not a relation to
  * anyone, but the user, standing alone. A harness's own name for a party is
- * never a type: `message:main` would read as the main session's traffic being
+ * never a type: `message.main` would read as the main session's traffic being
  * overheard wherever it happens, when what is meant is the party this subject
  * answers to — which is what `parent` says. The literal names (`main`, a
  * lead's, a teammate's) are kept in `harness_name` on the item. */
 export const TranscriptItemType = Type.String({
-  pattern: "^[a-z]+(?::[A-Za-z0-9_.-]+)*$",
+  pattern: "^[a-z][a-z0-9_]*(?:\\.[A-Za-z0-9_-]+)*$",
   $id: "TranscriptItemType",
 });
 export type TranscriptItemType = Static<typeof TranscriptItemType>;
 
 /** The type names that are fully spelled out here. The three open families
- * (`tool:<Name>`, `system:attachment:<kind>`, `hook:<Event>`) are not in the
+ * (`tool.<Name>`, `system.attachment.<kind>`, `hook.<Event>`) are not in the
  * list: their last segment is coined elsewhere, and a name absent from this
  * list is a newcomer rather than an error. */
 export const TRANSCRIPT_ITEM_TYPES = [
-  "message:user:in",
-  "message:user:out",
-  "message:parent:in",
-  "message:parent:out",
-  "message:sub:in",
-  "message:sub:out",
-  "message:team:in",
-  "message:team:out",
-  "message:session:in",
-  "message:session:out",
+  "message.user.in",
+  "message.user.out",
+  "message.parent.in",
+  "message.parent.out",
+  "message.sub.in",
+  "message.sub.out",
+  "message.team.in",
+  "message.team.out",
+  "message.session.in",
+  "message.session.out",
   "thinking",
-  "notice:slash",
-  "notice:interrupt",
-  "system:compact",
-  "system:api-error",
-  "system:task",
-  "system:caveat",
-  "system:resume",
-  "system:unknown",
+  "notice.slash",
+  "notice.interrupt",
+  "system.compact",
+  "system.api.error",
+  "system.task",
+  "system.caveat",
+  "system.resume",
+  "system.unknown",
 ] as const;
 export type KnownTranscriptItemType = (typeof TRANSCRIPT_ITEM_TYPES)[number];
 
@@ -74,7 +81,7 @@ export type KnownTranscriptItemType = (typeof TRANSCRIPT_ITEM_TYPES)[number];
  * Elements apply left to right, so an exclusion reaches whatever a prefix or an
  * expansion before it brought in. */
 export const TranscriptItemSelector = Type.String({
-  pattern: "^-?(?:@[A-Za-z0-9][A-Za-z0-9_-]*|[a-z]+(?::[A-Za-z0-9_.-]+)*)$",
+  pattern: "^-?(?:@[A-Za-z0-9][A-Za-z0-9_-]*|[a-z][a-z0-9_]*(?:\\.[A-Za-z0-9_-]+)*)$",
   $id: "TranscriptItemSelector",
 });
 export type TranscriptItemSelector = Static<typeof TranscriptItemSelector>;
@@ -84,7 +91,7 @@ export type TranscriptItemSelector = Static<typeof TranscriptItemSelector>;
  * started to answer once — and `team` a teammate's, an agent that was named and
  * goes on standing.
  *
- * It is what the relations are read from. `message:parent:in` under a `sub` is
+ * It is what the relations are read from. `message.parent.in` under a `sub` is
  * an errand's brief and under a `team` is what its lead wrote, and an item that
  * does not say which of the two it stood in can only be placed by whoever
  * remembers the request that fetched it. Carrying it on the item is what lets
@@ -105,7 +112,7 @@ export type TranscriptSubject = Static<typeof TranscriptSubject>;
  *
  * An item is what a reader made of a record, and a reader is fallible: the one
  * question it cannot answer is what the record actually said. These two numbers
- * are that answer's address — `transcript_read` bounded to end at `offset +
+ * are that answer's address — `transcript.read` bounded to end at `offset +
  * bytes` and to carry `bytes` returns the record itself — which is what lets a
  * client show items and still let a person open the line behind one. Several
  * items read out of a single record share the address, so what comes back is
@@ -208,24 +215,24 @@ const Text = Type.String();
  * the one above: an agent's parent is a session or another agent, and calling it
  * `user` would have a reader take a machine for a person.
  *
- * `message:user` is a person and nobody else. Both directions occur under a
+ * `message.user` is a person and nobody else. Both directions occur under a
  * session and under a teammate, which someone can type at directly; under a
  * throwaway agent neither does. A combination a subject is not expected to show
  * — `team` below an agent, say — is not refused: an unexpected line is still a
  * line, and it is emitted under the name it fits. */
-const MessageUserIn = item(Type.Literal("message:user:in"), { text: Text });
-const MessageUserOut = item(Type.Literal("message:user:out"), { text: Text });
+const MessageUserIn = item(Type.Literal("message.user.in"), { text: Text });
+const MessageUserOut = item(Type.Literal("message.user.out"), { text: Text });
 
 /** What the one above said, and what was said back to it.
  *
  * An agent's first line is the brief it was started with, and its last is the
  * answer that brief is discharged by; in between it may hand its parent
  * something mid-flight. The answer is plain prose the harness collects, with no
- * call behind it, so `parent:out` is prose-or-call and not a call alone:
+ * call behind it, so `parent.out` is prose-or-call and not a call alone:
  * addressed to the parent is what the two forms have in common, and requiring a
  * `tool_use_id` would leave the one message an agent is certain to send
  * unnameable. */
-const MessageParentIn = item(Type.Literal("message:parent:in"), {
+const MessageParentIn = item(Type.Literal("message.parent.in"), {
   text: Text,
   /** The harness's own name for the parent — `main`, a lead's name, the agent
    * above. Left out when the record says only that it came from above, which is
@@ -236,7 +243,7 @@ const MessageParentIn = item(Type.Literal("message:parent:in"), {
 
 /** Sent to the parent through a call, which the parent's own transcript has the
  * other half of. */
-const MessageParentOutSent = item(Type.Literal("message:parent:out"), {
+const MessageParentOutSent = item(Type.Literal("message.parent.out"), {
   ...USE_FIELDS,
   text: Text,
   /** The harness's own name for the parent, as the subject addressed it. */
@@ -245,7 +252,7 @@ const MessageParentOutSent = item(Type.Literal("message:parent:out"), {
 });
 
 /** Answered to the parent as prose — the agent's reply, final or interim. */
-const MessageParentOutSaid = item(Type.Literal("message:parent:out"), { text: Text });
+const MessageParentOutSaid = item(Type.Literal("message.parent.out"), { text: Text });
 
 /** A teammate is an agent that was given a name and goes on standing, so what
  * passes between the subject and one is a correspondence rather than an errand:
@@ -253,10 +260,10 @@ const MessageParentOutSaid = item(Type.Literal("message:parent:out"), { text: Te
  * written, and not as the answer to the call that sent it.
  *
  * That is the whole of what separates `team` from `sub`. A throwaway agent is
- * started, answers once and is done, which is why `sub:in` is the result of the
- * `sub:out` that started it. Here the two halves of a round trip are two
+ * started, answers once and is done, which is why `sub.in` is the result of the
+ * `sub.out` that started it. Here the two halves of a round trip are two
  * messages, and only the start of a teammate has a result to pair with. */
-const MessageTeamOut = item(Type.Literal("message:team:out"), {
+const MessageTeamOut = item(Type.Literal("message.team.out"), {
   ...USE_FIELDS,
   text: Text,
   /** The teammate addressed, by the name it stands under. */
@@ -271,7 +278,7 @@ const MessageTeamOut = item(Type.Literal("message:team:out"), {
 
 /** A teammate writing to the subject, arriving under its own name whenever it
  * was written. */
-const MessageTeamInSaid = item(Type.Literal("message:team:in"), {
+const MessageTeamInSaid = item(Type.Literal("message.team.in"), {
   text: Text,
   /** The name the teammate stands under. */
   harness_name: Type.Optional(Type.String()),
@@ -279,7 +286,7 @@ const MessageTeamInSaid = item(Type.Literal("message:team:in"), {
 });
 
 /** A teammate's run ending, which answers the call that started it. */
-const MessageTeamInDone = item(Type.Literal("message:team:in"), {
+const MessageTeamInDone = item(Type.Literal("message.team.in"), {
   ...RESULT_FIELDS,
   text: Text,
   harness_name: Type.Optional(Type.String()),
@@ -288,7 +295,7 @@ const MessageTeamInDone = item(Type.Literal("message:team:in"), {
   duration_ms: Type.Optional(Type.Integer({ minimum: 0 })),
 });
 
-const MessageSubOut = item(Type.Literal("message:sub:out"), {
+const MessageSubOut = item(Type.Literal("message.sub.out"), {
   ...USE_FIELDS,
   prompt: Text,
   agent_id: Type.Optional(Type.String()),
@@ -298,7 +305,7 @@ const MessageSubOut = item(Type.Literal("message:sub:out"), {
   description: Type.Optional(Type.String()),
 });
 
-const MessageSubIn = item(Type.Literal("message:sub:in"), {
+const MessageSubIn = item(Type.Literal("message.sub.in"), {
   ...RESULT_FIELDS,
   text: Text,
   agent_id: Type.Optional(Type.String()),
@@ -306,7 +313,7 @@ const MessageSubIn = item(Type.Literal("message:sub:in"), {
   duration_ms: Type.Optional(Type.Integer({ minimum: 0 })),
 });
 
-const MessageSessionOut = item(Type.Literal("message:session:out"), {
+const MessageSessionOut = item(Type.Literal("message.session.out"), {
   text: Text,
   /** The addressee as the subject wrote it: a sid, or a name that was resolved
    * to one. Kept unresolved when that is all the transcript says. */
@@ -315,7 +322,7 @@ const MessageSessionOut = item(Type.Literal("message:session:out"), {
   reply_to: Type.Optional(Type.String()),
 });
 
-const MessageSessionIn = item(Type.Literal("message:session:in"), {
+const MessageSessionIn = item(Type.Literal("message.session.in"), {
   text: Text,
   from: Type.Optional(Type.String()),
   msg_id: Type.Optional(Type.String()),
@@ -325,52 +332,52 @@ const Thinking = item(Type.Literal("thinking"), { text: Text });
 
 // --- notice: a person operated the harness ---
 
-/** Kept apart from `system:*` because these explain a break in the
+/** Kept apart from `system.*` because these explain a break in the
  * conversation: someone typed a command or stopped a turn. A reader skimming
  * for why the thread jumps needs them, and can skip what the harness injected
  * for its own reasons. */
-const NoticeSlash = item(Type.Literal("notice:slash"), {
+const NoticeSlash = item(Type.Literal("notice.slash"), {
   command: Type.String(),
   args: Type.Optional(Type.String()),
   stdout: Type.Optional(Type.String()),
 });
-const NoticeInterrupt = item(Type.Literal("notice:interrupt"), {
+const NoticeInterrupt = item(Type.Literal("notice.interrupt"), {
   text: Type.Optional(Text),
 });
 
 // --- system: the harness talking in someone else's voice ---
 
-const SystemCompact = item(Type.Literal("system:compact"), { text: Text });
-const SystemApiError = item(Type.Literal("system:api-error"), { text: Text });
-const SystemTask = item(Type.Literal("system:task"), {
+const SystemCompact = item(Type.Literal("system.compact"), { text: Text });
+const SystemApiError = item(Type.Literal("system.api.error"), { text: Text });
+const SystemTask = item(Type.Literal("system.task"), {
   text: Text,
   /** The background task or monitor the event came from. */
   task_id: Type.Optional(Type.String()),
   event: Type.Optional(Type.String()),
 });
-const SystemCaveat = item(Type.Literal("system:caveat"), { text: Text });
-const SystemResume = item(Type.Literal("system:resume"), { text: Text });
+const SystemCaveat = item(Type.Literal("system.caveat"), { text: Text });
+const SystemResume = item(Type.Literal("system.resume"), { text: Text });
 
-/** `system:attachment:<kind>` — the kind is the harness's own word for what it
+/** `system.attachment.<kind>` — the kind is the harness's own word for what it
  * attached, taken through unchanged so an attachment nobody has seen before
  * still arrives under its own name instead of collapsing into `unknown`. */
-const SystemAttachment = item(Type.String({ pattern: "^system:attachment:[A-Za-z0-9_.-]+$" }), {
+const SystemAttachment = item(Type.String({ pattern: "^system\\.attachment\\.[A-Za-z0-9_-]+$" }), {
   attachment: Type.Record(Type.String(), Type.Unknown()),
 });
 
 /** What the reader could not place. It is still an item: a line that vanishes
  * silently is the one failure a dump cannot be read around. */
-const SystemUnknown = item(Type.Literal("system:unknown"), {
+const SystemUnknown = item(Type.Literal("system.unknown"), {
   record: Type.Record(Type.String(), Type.Unknown()),
 });
 
 // --- hook: code the operator installed ---
 
-/** `hook:<Event>` — the event alone, never the matcher. The name a hook runs
+/** `hook.<Event>` — the event alone, never the matcher. The name a hook runs
  * under is `PreToolUse:Bash`, whose `:` would read as a level of the hierarchy
- * and make `hook:PreToolUse` select nothing; the full name is a field instead,
+ * and make `hook.PreToolUse` select nothing; the full name is a field instead,
  * and prefix selection keeps meaning what it says. */
-const Hook = item(Type.String({ pattern: "^hook:[A-Za-z0-9_.-]+$" }), {
+const Hook = item(Type.String({ pattern: "^hook\\.[A-Za-z0-9_-]+$" }), {
   /** The hook's full name, matcher included. */
   hook_name: Type.String(),
   outcome: Type.Union([
@@ -387,19 +394,19 @@ const Hook = item(Type.String({ pattern: "^hook:[A-Za-z0-9_.-]+$" }), {
   tool_use_id: Type.Optional(Type.String()),
 });
 
-// --- tool: `tool:<Name>`, one item for the call and one for the result ---
+// --- tool: `tool.<Name>`, one item for the call and one for the result ---
 
-const ToolType = Type.String({ pattern: "^tool:[A-Za-z0-9_.-]+$" });
+const ToolType = Type.String({ pattern: "^tool\\.[A-Za-z0-9_-]+$" });
 
 function toolUse<N extends string, F extends Record<string, TSchema>>(name: N, fields: F) {
-  return item(Type.Literal(`tool:${name}` as const), {
+  return item(Type.Literal(`tool.${name}` as const), {
     ...USE_FIELDS,
     ...fields,
   });
 }
 
 function toolResult<N extends string, F extends Record<string, TSchema>>(name: N, fields: F) {
-  return item(Type.Literal(`tool:${name}` as const), {
+  return item(Type.Literal(`tool.${name}` as const), {
     ...RESULT_FIELDS,
     ...fields,
   });
@@ -453,7 +460,7 @@ const TOOL_ITEMS = [
   toolResult("WebFetch", { text: OptText }),
   toolUse("WebSearch", { query: Type.String() }),
   toolResult("WebSearch", { results: OptCount }),
-  /** The same exchange `message:sub:*` carries, seen from the calling side:
+  /** The same exchange `message.sub.*` carries, seen from the calling side:
    * this pair states that an agent was started and how it ended, and what it
    * answered stays with the message. */
   toolUse("Agent", {
@@ -493,7 +500,7 @@ const TOOL_ITEMS = [
  * Items are finer than lines: one assistant record becomes the thinking, the
  * text and each tool call it held. A reader that does not recognise a record
  * still emits one — as a tool it has no fields for, an attachment under its own
- * kind, or `system:unknown` — so nothing in the file goes missing without
+ * kind, or `system.unknown` — so nothing in the file goes missing without
  * saying so. */
 export const TranscriptItem = Type.Union(
   [
@@ -628,5 +635,5 @@ export const DumpPresetsReadResult = Type.Object({
 });
 export type DumpPresetsReadResult = Static<typeof DumpPresetsReadResult>;
 
-export const DumpPresetsReadRequest = request("dump_presets_read", DumpPresetsReadArgs);
-export const DumpPresetsReadResponse = response("dump_presets_read", DumpPresetsReadResult);
+export const DumpPresetsReadRequest = request("dump.presets.read", DumpPresetsReadArgs);
+export const DumpPresetsReadResponse = response("dump.presets.read", DumpPresetsReadResult);