@ccmsg/protocol 0.3.1 → 0.4.0

package/package.json

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

package/src/common/topics.ts

@@ -45,25 +45,63 @@ export const Topic = Type.String({
   ].join(""),
 });
 
+/** How a subscriber folds a frame into what it already holds.
+ *
+ * Snapshot and delta share one payload type, which leaves one question the
+ * shape cannot answer: what a later frame does to the value before it. Stating
+ * it here means the daemon and the web UI fold the same way instead of each
+ * keeping its own table of which topic behaves how. */
+export const TOPIC_GRANULARITIES = [
+  /** The frame is the whole value; it replaces everything held. */
+  "whole",
+  /** The frame is the whole of what its `instance` knows; it replaces that
+   * instance's entries and leaves every other instance's alone. What the
+   * subscriber holds is the union across instances. */
+  "per_instance_whole",
+  /** The frame carries the elements that changed, keyed by their own id.
+   * Elements it does not mention are untouched, so a removal has to be a
+   * marked element rather than an absence. */
+  "element",
+  /** The frame carries what has been added since the last one; the subscriber
+   * appends and never rewrites what it already has. */
+  "append",
+  /** The frame is an occurrence, not a value. Nothing is held, so there is
+   * nothing to snapshot: subscribing yields the next occurrence, never a
+   * current state. */
+  "event",
+] as const;
+
+export type TopicGranularity = (typeof TOPIC_GRANULARITIES)[number];
+
 export interface TopicAttributes {
   readonly roles: readonly Role[];
   readonly capability?: Capability;
+  /** How a later frame relates to the value already held. Every topic but an
+   * `event` one opens with a `snapshot: true` frame. */
+  readonly granularity: TopicGranularity;
 }
 
-/** Who may subscribe to what. The same question the op table answers for ops:
- * a subscribe from a role outside the set answers `forbidden`, and one naming
- * a capability the instance lacks answers `capability_unavailable`. */
+/** Who may subscribe to what, and how the frames fold. The same question the
+ * op table answers for ops: a subscribe from a role outside the set answers
+ * `forbidden`, and one naming a capability the instance lacks answers
+ * `capability_unavailable`. */
 export const TOPIC_ATTRIBUTES = {
-  inbox: { roles: ["session", "user"] },
-  notify: { roles: ["session", "user"] },
-  peers: { roles: ["session", "user"] },
-  agents: { roles: ["user"] },
-  session_errors: { roles: ["user"] },
-  llm_requests: { roles: ["user"], capability: "llm_events" },
-  llm_status: { roles: ["user"], capability: "llm_status" },
-  session_status: { roles: ["user"] },
-  transcript: { roles: ["user"] },
-  kv: { roles: ["user"] },
+  inbox: { roles: ["session", "user"], granularity: "element" },
+  notify: { roles: ["session", "user"], granularity: "event" },
+  peers: { roles: ["session", "user"], granularity: "per_instance_whole" },
+  agents: { roles: ["user"], granularity: "per_instance_whole" },
+  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" },
+  // 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" },
+  transcript: { roles: ["user"], granularity: "append" },
+  kv: { roles: ["user"], granularity: "element" },
 } as const satisfies Record<
   PlainTopic | SessionScopedTopic | NamespaceScopedTopic,
   TopicAttributes
@@ -77,6 +115,14 @@ export function topicKind(topic: string): TopicKind | undefined {
   return head in TOPIC_ATTRIBUTES ? head : 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.
+ * `undefined` for a name this generation does not define. */
+export function topicGranularity(topic: string): TopicGranularity | undefined {
+  const kind = topicKind(topic);
+  return kind === undefined ? undefined : TOPIC_ATTRIBUTES[kind].granularity;
+}
+
 export const TopicSubscribeArgs = Type.Object({ topic: Topic });
 export type TopicSubscribeArgs = Static<typeof TopicSubscribeArgs>;
 

package/src/control/llm.ts

@@ -249,8 +249,21 @@ export const LlmRequestInfo = Type.Object(
      * sessions, which is the other half of why the pair is the key. */
     prefix: Type.Optional(Type.String()),
     /** True for the series the session's own turns keep warm, as opposed to a
-     * subagent's. The instance decides it so that every client agrees on which
-     * window is the session's. */
+     * subagent's. The instance decides it, by the rule below, so that every
+     * client agrees on which window is the session's rather than each reading
+     * the same events into a different verdict.
+     *
+     * 1. `origin` decides it whenever the gateway states one. It watched the
+     *    request go out and nothing here knows better.
+     * 2. Otherwise a `prefix` seen under two or more sessions is a subagent's:
+     *    a series the session's own turns keep warm is not shared, so sharing
+     *    is the evidence. Among the series left, the one that session used
+     *    first wins — a session's own conversation starts before anything it
+     *    spawns.
+     * 3. If every series of a session is shared, none of them is that session's
+     *    own, so the newest is marked instead. It is the window a countdown
+     *    would be about, and marking nothing would leave the session with no
+     *    window at all. */
     main: Type.Boolean(),
     /** Whose turn issued the request, as the gateway read it. An open set; this
      * is one of the inputs to `main`, and `main` is the verdict clients read. */

package/src/control/peers.ts

@@ -72,6 +72,11 @@ export const PeerInfo = Type.Object(
     transcript_path: Type.Optional(SessionMetaFields.transcript_path),
     repo_root: Type.Optional(SessionMetaFields.repo_root),
     branch: Type.Optional(SessionMetaFields.branch),
+    /** The session's own title, as it named it. Also what resolves a display
+     * name for this session elsewhere — a message's `from_label`, a
+     * notification's `sid_label` — so the material for those is on the row that
+     * every client already holds. */
+    title: Type.Optional(SessionMetaFields.title),
     /** How this session stands. One of `waiting`, `live` or `live_unmanaged`:
      * a session in this list is connected, so it is by definition not gone.
      * Absent from an instance that states no classification, and a client then
@@ -91,6 +96,19 @@ export const PeerInfo = Type.Object(
      * while none has been found; a client orders such a session after every
      * session that has one rather than treating it as long ago. */
     last_user_input_at: Type.Optional(Timestamp),
+    /** When inference last ran for this session, as the gateway saw it.
+     *
+     * How busy a session is, carried as an attribute of the row rather than
+     * folded into `state`: a session is busy while it stands in any of the
+     * connected classifications, so the two answer different questions and
+     * collapsing them would lose one. It is an instant rather than a flag
+     * because there is no moment a request stops being in flight that anything
+     * observes — a client reads recency and decides its own threshold.
+     *
+     * Absent from an instance with no gateway configured, where nothing
+     * observes inference at all. That is not "idle": a client shows such a
+     * session without the mark rather than as quiet. */
+    gateway_active_at: Type.Optional(Timestamp),
     /** Whether the asking session can reach this one with the harness's own
      * cross-session messaging, which does not cross config homes. Computed
      * against the asker, so it never appears on the asker's own entry nor for a

package/src/errors.ts

@@ -11,6 +11,13 @@ export const ERROR_CODES = [
   "unknown_op",
   /** An op with `needs_hello` arrived before `hello` settled the identity. */
   "hello_required",
+  /** The op's implementation failed for a reason that is not the caller's: the
+   * arguments were right and the call was allowed. It belongs beside the other
+   * connection-level codes because no op owns it — any op can fail this way, and
+   * naming it apart from `bad_request` is what keeps a caller from re-reading
+   * arguments that were never the problem. Whether retrying helps is not stated;
+   * `msg` is the only thing that says more. */
+  "internal_error",
   // --- 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/identifiers.ts

@@ -8,6 +8,22 @@ export const Sid = Type.String({
 });
 export type Sid = Static<typeof Sid>;
 
+/** Who sent a message: a session, or the person at the web UI.
+ *
+ * A person has no sid — the `user` role greets without one — so the sender of a
+ * message cannot be a `Sid` alone. The literal is spelled out rather than left
+ * as an absent field, because a reader has to tell "a person sent this" from "a
+ * session sent this and the id was lost". Every session id remains a valid
+ * sender, so a reader that only knew sids keeps working.
+ *
+ * There is one person per instance to a session's eye, so the literal carries
+ * no id of its own; which browser it was is not a thing this contract names. */
+export const Sender = Type.Union([Sid, Type.Literal("user")], { $id: "Sender" });
+export type Sender = Static<typeof Sender>;
+
+/** The sender that is the person rather than a session. */
+export const USER_SENDER = "user" as const;
+
 /** An instance id: the endpoint URL other instances dial, compared as a whole
  * string including its path (mesh-peer-auth §4.2 — one origin may host several
  * instances, so origin-level comparison would confuse them). The display name

package/src/messaging/direct-delivery.ts

@@ -1,5 +1,5 @@
 import type { InboxMessage } from "./message.ts";
-import type { Mid, Sid } from "../identifiers.ts";
+import { type Mid, type Sender, USER_SENDER } from "../identifiers.ts";
 
 /** How an `InboxMessage` is worded when it is handed to a session through the
  * harness's own messaging socket rather than over this protocol.
@@ -39,15 +39,22 @@ export const DIRECT_DELIVERY_FROM_MODE = "prompting";
  * the frame being answered — so nothing has to be looked up to use it. A `mid`
  * does not name its sender, and the alternative to spelling the sid out here
  * would be an op that resolves one, which means a sent-message index the
- * daemon does not otherwise need. */
-export function directDeliveryReplyLine(mid: Mid, from: Sid): string {
-  return `Reply with: ccmsg reply ${mid} --to ${from} <text>`;
+ * daemon does not otherwise need.
+ *
+ * A message from a person carries no addressee: `user` is not a sid and
+ * addressing it would be a send that fails. The line drops `--to` instead, and
+ * what an answer to a person becomes is the instance's to decide — it reaches
+ * them as a notification, which is a route the recipient does not have to know
+ * about to run this line. */
+export function directDeliveryReplyLine(mid: Mid, from: Sender): string {
+  const to = from === USER_SENDER ? "" : ` --to ${from}`;
+  return `Reply with: ccmsg reply ${mid}${to} <text>`;
 }
 
 /** An `InboxMessage` as it reaches a session through the messaging socket. */
 export interface DirectDelivery {
   mid: Mid;
-  from: Sid;
+  from: Sender;
   from_label: string;
   reply_to?: Mid;
   /** The sender's text, exactly as it was sent. */

package/src/messaging/message.ts

@@ -1,6 +1,6 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response, topicFrame } from "../envelope.ts";
-import { InstanceId, Mid, Sid, Timestamp } from "../identifiers.ts";
+import { InstanceId, Mid, Sender, Sid, Timestamp } from "../identifiers.ts";
 
 /** Why a message was not handed to its recipient right away.
  *
@@ -70,14 +70,20 @@ export const MessageSendResponse = response("message_send", MessageSendResult);
 
 /** A message as the recipient receives it, on topic `inbox`.
  *
- * To answer it, send to `from`. The route is the sender's id and nothing else,
- * so no reply instructions travel on the wire: the wording a session sees
- * belongs to whoever renders it — see `direct-delivery.ts` for the one route
- * whose recipient reads text instead of this frame. */
+ * To answer it, send to `from`. The route is the sender and nothing else, so no
+ * reply instructions travel on the wire: the wording a session sees belongs to
+ * whoever renders it — see `direct-delivery.ts` for the one route whose
+ * recipient reads text instead of this frame.
+ *
+ * A `from` of `user` is the exception: `message_send` addresses a sid, so there
+ * is no such thing as sending back to the person. An answer to one reaches them
+ * as a notification instead, which is the instance's to arrange — this contract
+ * only states that the sender can be a person, so a client stops treating one
+ * as a malformed message. */
 export const InboxMessage = Type.Object(
   {
     mid: Mid,
-    from: Sid,
+    from: Sender,
     /** How the sender should be shown, resolved by the issuing instance. */
     from_label: Type.String(),
     text: Type.String(),