@ccmsg/protocol 1.14.0 → 1.15.0

package/package.json

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

package/src/attributes.ts

@@ -179,7 +179,7 @@ export const OP_ATTRIBUTES = {
     roles: SESSION_ONLY,
     needs_hello: true,
     locality: "cluster",
-    errors: [],
+    errors: ["rate_limited"],
   },
   say_mark_read: {
     plane: "messaging",
@@ -193,7 +193,7 @@ export const OP_ATTRIBUTES = {
     roles: AGENT_AND_USER,
     needs_hello: true,
     locality: "cluster",
-    errors: [],
+    errors: ["rate_limited"],
   },
 
   // --- control: session observation and operation (10) ---

package/src/control/dump.ts

@@ -129,12 +129,21 @@ const USE_FIELDS = {
   role: Type.Literal("use"),
   /** The result's id, once there is one. */
   result_item: Type.Optional(TranscriptItemId),
+  /** The harness's own key for this call, which the result names back. */
+  tool_use_id: Type.String(),
 };
 
 const RESULT_FIELDS = {
   role: Type.Literal("result"),
-  /** The call this answers. Always known: a result exists because a call did. */
-  parent_item: TranscriptItemId,
+  /** The call this answers, when the reader saw it. A read that begins in the
+   * middle of a file — a topic's seed, a transcript resumed from another file —
+   * meets results whose call is behind where it started, and an id it never
+   * read is one it cannot name. */
+  parent_item: Type.Optional(TranscriptItemId),
+  /** The harness's key for the call this answers, which the record carries
+   * whether or not the call was read. A reader that has no `parent_item` joins
+   * on this against the `tool_use_id` of the calls it holds. */
+  parent_tool_use_id: Type.String(),
 };
 
 function item<T extends TSchema, F extends Record<string, TSchema>>(type: T, fields: F) {
@@ -259,7 +268,6 @@ 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), {
     ...USE_FIELDS,
-    tool_use_id: Type.String(),
     ...fields,
   });
 }
@@ -267,7 +275,6 @@ function toolUse<N extends string, F extends Record<string, TSchema>>(name: N, f
 function toolResult<N extends string, F extends Record<string, TSchema>>(name: N, fields: F) {
   return item(Type.Literal(`tool:${name}` as const), {
     ...RESULT_FIELDS,
-    tool_use_id: Type.String(),
     ...fields,
   });
 }
@@ -280,12 +287,10 @@ const OptCount = Type.Optional(Type.Integer({ minimum: 0 }));
  * to decide whether it is kept. */
 const ToolUseGeneric = item(ToolType, {
   ...USE_FIELDS,
-  tool_use_id: Type.String(),
   input: Type.Record(Type.String(), Type.Unknown()),
 });
 const ToolResultGeneric = item(ToolType, {
   ...RESULT_FIELDS,
-  tool_use_id: Type.String(),
   result: Type.Record(Type.String(), Type.Unknown()),
 });
 

package/src/control/transcript.ts

@@ -62,10 +62,13 @@ export const TranscriptReadResponse = response("transcript_read", TranscriptRead
  *
  * The range is cut the way a dump's is — an instant or a record on either side
  * — and which end of it a limit keeps follows from which bound was given. A
- * lower bound reads forward from it and `next` names the continuation; an upper
- * bound alone reads the range's last items and `prev` names the continuation
- * backwards, which is how a client that draws the newest items first walks back
- * through a transcript it never has to read whole. The role decides how much is
+ * lower bound reads forward from it and `next` names the continuation;
+ * otherwise the read answers the range's last items and `prev` names the
+ * continuation backwards, which is how a client that draws the newest items
+ * first walks back through a transcript it never has to read whole. Asking
+ * with no bound at all is the ordinary first read, and it answers the tail, as
+ * the raw read with no `before` does; a client that wants the transcript from
+ * its beginning says so with `since_at: 0`. The role decides how much is
  * visible, as it does for the raw read. */
 export const TranscriptItemsReadArgs = Type.Object({
   sid: Sid,
@@ -90,8 +93,8 @@ export const TranscriptItemsReadArgs = Type.Object({
    * but the attachments, as a dump's absent selection does. */
   types: Type.Optional(Type.Array(TranscriptItemSelector)),
   /** How many items to answer with, taken from the range's start when a lower
-   * bound was given and from its end when only an upper one was; the instance
-   * narrows this to its own limit. */
+   * bound was given and from its end otherwise; the instance narrows this to
+   * its own limit. */
   limit: Type.Optional(Type.Integer({ minimum: 1 })),
 });
 export type TranscriptItemsReadArgs = Static<typeof TranscriptItemsReadArgs>;

package/src/errors.ts

@@ -18,6 +18,15 @@ export const ERROR_CODES = [
    * arguments that were never the problem. Whether retrying helps is not stated;
    * `msg` is the only thing that says more. */
   "internal_error",
+  // --- backpressure ---
+  /** The call was well-formed and allowed, and the instance is not taking it
+   * just now: what it would be queued behind has reached the limit the sender
+   * keeps to. Apart from `internal_error` because nothing failed and the
+   * arguments are not what to re-read — the same call sent again once the
+   * reader has caught up is the one that goes through. Which ops answer it is
+   * in their `errors`, since only an op that queues for a reader has a queue to
+   * fill. */
+  "rate_limited",
   // --- rule-derived (op attribute table §0) ---
   /** The connection's role is outside the op's `roles`. Argument problems stay
    * on `invalid_args` / `bad_request`. */

package/src/fixtures/control.ts

@@ -261,8 +261,8 @@ export const TRANSCRIPT_ITEMS: Static<typeof TranscriptItem>[] = [
     type: "tool:Bash",
     at: FIXTURE_NOW - 3_399_000,
     role: "result",
-    tool_use_id: "toolu_01Ne9BDS",
     parent_item: "f10b6d43:1",
+    parent_tool_use_id: "toolu_01Ne9BDS",
     stdout: "1174 assistant\n753 user\n",
     interrupted: false,
   },
@@ -274,6 +274,7 @@ export const TRANSCRIPT_ITEMS: Static<typeof TranscriptItem>[] = [
     at: FIXTURE_NOW - 3_300_000,
     role: "use",
     result_item: "c2d80f16:0",
+    tool_use_id: "toolu_01Rk4WQm",
     prompt: "docs/design/dump-kinds.md を書き直す",
     agent_id: "a471372f2",
     subagent_type: "opus5-worker-high",