@ccmsg/protocol 1.13.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.13.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

@@ -61,8 +61,15 @@ export const TranscriptReadResponse = response("transcript_read", TranscriptRead
  * `source` that item carries.
  *
  * The range is cut the way a dump's is — an instant or a record on either side
- * — and `since_id` resumes a read that stopped at a limit. The role decides how
- * much is visible, as it does for the raw read. */
+ * — 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;
+ * 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,
   /** Read one agent below the session instead of the session itself. */
@@ -78,11 +85,16 @@ export const TranscriptItemsReadArgs = Type.Object({
   since_id: Type.Optional(TranscriptItemId),
   until_at: Type.Optional(Timestamp),
   until_uuid: Type.Optional(Type.String()),
+  /** Exclusive upper bound as an item id, the one a previous reply named as
+   * `prev`. Finer than `until_uuid`, which would stop at a record whose earlier
+   * items were already read. */
+  until_id: Type.Optional(TranscriptItemId),
   /** Which item types to keep, applied left to right. Absent keeps everything
    * but the attachments, as a dump's absent selection does. */
   types: Type.Optional(Type.Array(TranscriptItemSelector)),
-  /** How many items to answer with; the instance narrows this to its own
-   * limit. */
+  /** How many items to answer with, taken from the range's start when a lower
+   * 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>;
@@ -90,9 +102,13 @@ export type TranscriptItemsReadArgs = Static<typeof TranscriptItemsReadArgs>;
 export const TranscriptItemsReadResult = Type.Object({
   /** Oldest first, as the transcript had them. */
   items: Type.Array(TranscriptItem),
-  /** The first item left out, when a limit cut the answer short. Absent means
-   * the range was answered whole. */
+  /** The first item left out after the ones answered, when a limit cut a
+   * forward read short. Absent means nothing follows within the range. */
   next: Type.Optional(TranscriptItemId),
+  /** The first item answered, when a limit left older ones inside the range
+   * unread. Pass it back as `until_id` to read what came before. Absent means
+   * the range reaches back to its start. */
+  prev: Type.Optional(TranscriptItemId),
   /** The ids the answered items carried, gathered as a dump gathers them.
    * Absent when the caller did not ask the instance to collect them. */
   ids: Type.Optional(DumpIds),

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",
@@ -336,6 +337,23 @@ export const TRANSCRIPT_ITEMS_READ_RESPONSE: Static<typeof TranscriptItemsReadRe
   ids: [{ kind: "agent", id: "a471372f2", label: "dump-kinds-design", status: "running" }],
 };
 
+/** A client drawing the newest items first asks with an upper bound alone, and
+ * walks back by handing the `prev` it was given to the next call. */
+export const TRANSCRIPT_ITEMS_READ_BACKWARD_REQUEST: Static<typeof TranscriptItemsReadRequest> = {
+  request_id,
+  op: "transcript_items_read",
+  sid,
+  until_id: "18d6f2c9:0",
+  limit: 2,
+};
+
+export const TRANSCRIPT_ITEMS_READ_BACKWARD_RESPONSE: Static<typeof TranscriptItemsReadResponse> = {
+  ok: true,
+  request_id,
+  items: TRANSCRIPT_ITEMS.slice(1, 3),
+  prev: "f10b6d43:0",
+};
+
 export const SESSION_FORK_ORIGIN_REQUEST: Static<typeof SessionForkOriginRequest> = {
   request_id,
   op: "session_fork_origin",