@ccmsg/protocol 1.16.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
   "license": "MIT",
   "author": "kawaz",

package/src/control/dump.ts

@@ -24,7 +24,17 @@ import { Sid, Timestamp } from "../identifiers.ts";
  * 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
  * 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.
+ *
+ * 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
+ * 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_.-]+)*$",
   $id: "TranscriptItemType",
@@ -38,8 +48,12 @@ export type TranscriptItemType = Static<typeof TranscriptItemType>;
 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",
   "thinking",
@@ -156,12 +170,97 @@ const Text = Type.String();
 
 /** The subject is a session by default, or one agent below it when the dump
  * names an agent, and `in` / `out` are read from wherever the subject stands.
- * A dump of an agent therefore reads `message:user:in` as the brief its parent
- * gave it, on the same type names a dump of the session uses — which is what
- * lets one preset be carried down a chain of agents. */
+ * What moves when the subject moves is who the counterpart is, not the names:
+ * the same preset reads a session's talk with a person and an agent's talk with
+ * whoever started it, which is what lets one be carried down a chain of agents.
+ *
+ * The counterpart is named by the kind of party it is — a person, the one above,
+ * the throwaway agents below, a teammate that stays, another session — because a
+ * dump is read to find out who was talking, and a subject's own position is the
+ * one thing it cannot ask about itself. Hence `parent` rather than `user` for
+ * 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
+ * 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 });
 
+/** 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:
+ * 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"), {
+  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
+   * the case for the brief an agent opens with. */
+  harness_name: Type.Optional(Type.String()),
+  msg_id: Type.Optional(Type.String()),
+});
+
+/** 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"), {
+  ...USE_FIELDS,
+  text: Text,
+  /** The harness's own name for the parent, as the subject addressed it. */
+  harness_name: Type.Optional(Type.String()),
+  summary: Type.Optional(Type.String()),
+});
+
+/** Answered to the parent as prose — the agent's reply, final or interim. */
+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:
+ * a reply comes back as its own message, addressed and arriving whenever it is
+ * 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
+ * messages, and only the start of a teammate has a result to pair with. */
+const MessageTeamOut = item(Type.Literal("message:team:out"), {
+  ...USE_FIELDS,
+  text: Text,
+  /** The teammate addressed, by the name it stands under. */
+  harness_name: Type.Optional(Type.String()),
+  summary: Type.Optional(Type.String()),
+  agent_id: Type.Optional(Type.String()),
+  /** Present on the call that started the teammate, absent on the ones that
+   * write to it afterwards. */
+  subagent_type: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+});
+
+/** A teammate writing to the subject, arriving under its own name whenever it
+ * was written. */
+const MessageTeamInSaid = item(Type.Literal("message:team:in"), {
+  text: Text,
+  /** The name the teammate stands under. */
+  harness_name: Type.Optional(Type.String()),
+  msg_id: Type.Optional(Type.String()),
+});
+
+/** A teammate's run ending, which answers the call that started it. */
+const MessageTeamInDone = item(Type.Literal("message:team:in"), {
+  ...RESULT_FIELDS,
+  text: Text,
+  harness_name: Type.Optional(Type.String()),
+  agent_id: Type.Optional(Type.String()),
+  status: Type.Optional(Type.String()),
+  duration_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+});
+
 const MessageSubOut = item(Type.Literal("message:sub:out"), {
   ...USE_FIELDS,
   prompt: Text,
@@ -373,8 +472,14 @@ export const TranscriptItem = Type.Union(
   [
     MessageUserIn,
     MessageUserOut,
+    MessageParentIn,
+    MessageParentOutSent,
+    MessageParentOutSaid,
     MessageSubOut,
     MessageSubIn,
+    MessageTeamOut,
+    MessageTeamInSaid,
+    MessageTeamInDone,
     MessageSessionOut,
     MessageSessionIn,
     Thinking,

package/src/fixtures/control.ts

@@ -213,7 +213,9 @@ export const DUMP_PRESETS_READ_RESPONSE: Static<typeof DumpPresetsReadResponse>
     {
       name: "howto",
       description: "how the work was done: what was thought, run, read and written",
-      opts: { types: ["thinking", "message:user", "message:sub", "tool:Bash", "@file"] },
+      opts: {
+        types: ["thinking", "message:user", "message:parent", "message:sub", "tool:Bash", "@file"],
+      },
     },
   ],
 };
@@ -298,6 +300,80 @@ export const TRANSCRIPT_ITEMS: Static<typeof TranscriptItem>[] = [
     at: FIXTURE_NOW - 3_100_000,
     attachment: { type: "queued_command", command: "/pre-clear" },
   },
+  {
+    id: "c8a2f371:0",
+    uuid: "c8a2f371",
+    source: { offset: 182_800, bytes: 520 },
+    type: "message:team:out",
+    at: FIXTURE_NOW - 3_000_000,
+    role: "use",
+    result_item: "d4c1a0b2:0",
+    tool_use_id: "toolu_01Tm5XYp",
+    text: "契約に message:parent と message:team を足して",
+    harness_name: "contract-dump-items",
+    agent_id: "b83e0f114",
+    subagent_type: "opus5-worker-high",
+  },
+  {
+    id: "e5b70c93:0",
+    uuid: "e5b70c93",
+    source: { offset: 183_320, bytes: 300 },
+    type: "message:team:in",
+    at: FIXTURE_NOW - 2_900_000,
+    text: "fixtures まで通ったので ci を回す",
+    harness_name: "contract-dump-items",
+  },
+  {
+    id: "d4c1a0b2:0",
+    uuid: "d4c1a0b2",
+    source: { offset: 183_620, bytes: 410 },
+    type: "message:team:in",
+    at: FIXTURE_NOW - 2_800_000,
+    role: "result",
+    parent_item: "c8a2f371:0",
+    parent_tool_use_id: "toolu_01Tm5XYp",
+    text: "4 型を足して 1.17.0 を切った",
+    agent_id: "b83e0f114",
+    status: "ok",
+    duration_ms: 240_000,
+  },
+];
+
+/** The same vocabulary read with an agent as the subject.
+ *
+ * Nothing here is a new type: the brief an agent opens with and the answer it
+ * closes with are what `message:parent` names from wherever it is read, and the
+ * answer comes as prose with no call behind it. */
+export const TRANSCRIPT_ITEMS_AGENT_SUBJECT: Static<typeof TranscriptItem>[] = [
+  {
+    id: "a9f30d15:0",
+    uuid: "a9f30d15",
+    source: { offset: 0, bytes: 1_240 },
+    type: "message:parent:in",
+    at: FIXTURE_NOW - 3_290_000,
+    turn: 1,
+    text: "docs/design/dump-kinds.md を書き直す",
+  },
+  {
+    id: "b0e41c26:0",
+    uuid: "b0e41c26",
+    source: { offset: 1_240, bytes: 380 },
+    type: "message:parent:out",
+    at: FIXTURE_NOW - 3_260_000,
+    role: "use",
+    tool_use_id: "toolu_01Qz8Vbn",
+    text: "型一覧は 4 群に分けた。preset の例まで直してよいか",
+    harness_name: "main",
+    summary: "型一覧の分け方を確認",
+  },
+  {
+    id: "c1f52d37:0",
+    uuid: "c1f52d37",
+    source: { offset: 1_620, bytes: 690 },
+    type: "message:parent:out",
+    at: FIXTURE_NOW - 3_200_000,
+    text: "型一覧を 4 群に整理し、preset の例も揃えた",
+  },
 ];
 
 export const TRANSCRIPT_READ_REQUEST: Static<typeof TranscriptReadRequest> = {