@ccmsg/protocol 0.3.1 → 0.5.0

package/package.json

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

@@ -2,7 +2,8 @@ import type { ErrorCode } from "./errors.ts";
 import type { Capability, Role } from "./identifiers.ts";
 
 /** Which face of the contract an op belongs to. `common` is the transport
- * level (connect / subscribe), which every face uses. `mesh` holds no ops: an
+ * level (connect, declare the end of a connection, subscribe), which every
+ * face uses. `mesh` holds no ops: an
  * op crosses instances by carrying the envelope's mesh fields, not by being a
  * different op. */
 export type Plane = "common" | "messaging" | "control" | "mesh";
@@ -39,7 +40,7 @@ const SESSION_ONLY = ["session"] as const;
  * facts live: authorization, capability gating and forwarding all read it
  * rather than each carrying their own copy. */
 export const OP_ATTRIBUTES = {
-  // --- common: connect and subscribe (5) ---
+  // --- common: connect, declare the end, and subscribe (6) ---
   // `hello` and `instance_ping` address the instance the caller reached, so
   // there is nothing to forward and no unreachable instance to report — which
   // is why they are `cluster` despite answering about one instance.
@@ -64,6 +65,13 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: [],
   },
+  session_stopping: {
+    plane: "common",
+    roles: SESSION_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: [],
+  },
   topic_subscribe: {
     plane: "common",
     roles: AGENT_AND_USER,

package/src/common/hello.ts

@@ -26,6 +26,21 @@ 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`.
+ *
+ * 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. */
 export const HelloArgs = Type.Object({
   role: Role,
   /** The generation the caller speaks. A hello announcing another generation

package/src/common/shutdown.ts

@@ -1,5 +1,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response } from "../envelope.ts";
+import { Timestamp } from "../identifiers.ts";
+import { upstream } from "../upstream.ts";
 
 export const InstanceShutdownArgs = Type.Object({});
 export type InstanceShutdownArgs = Static<typeof InstanceShutdownArgs>;
@@ -11,3 +13,36 @@ export type InstanceShutdownResult = Static<typeof 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.
+ *
+ * The calling session is recorded as `paused` — carrying the `stopped_at`
+ * below — once the connection closes; a session that vanishes without this
+ * call is `disappeared`. The instance holds the declaration until the
+ * disconnection arrives, so the two are one event in that order however long
+ * the session takes to actually exit, and a session that carries on regardless
+ * stays connected and unchanged. */
+export const SessionStoppingArgs = Type.Object({
+  /** Why it is stopping, for display. An open set: this is normally called
+   * from the harness's own end-of-session hook, which passes its reason
+   * through, and nothing here gates on the word. */
+  reason: Type.Optional(
+    Type.String({
+      minLength: 1,
+      ...upstream("claude", "the session-end reason, in the harness's spelling"),
+    }),
+  ),
+});
+export type SessionStoppingArgs = Static<typeof SessionStoppingArgs>;
+
+export const SessionStoppingResult = Type.Object({
+  /** The instant the instance recorded, and the one that will appear on the
+   * session's `last_live` entry. Stated rather than left to the caller so the
+   * pause is stamped by the clock the entry is read against. */
+  stopped_at: Timestamp,
+});
+export type SessionStoppingResult = Static<typeof SessionStoppingResult>;
+
+export const SessionStoppingRequest = request("session_stopping", SessionStoppingArgs);
+export const SessionStoppingResponse = response("session_stopping", SessionStoppingResult);

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

@@ -68,10 +68,18 @@ export const PeerInfo = Type.Object(
     repo: SessionMetaFields.repo,
     ws: SessionMetaFields.ws,
     cwd: SessionMetaFields.cwd,
-    /** Present when the session announced one the instance accepted. */
+    /** Present when the session announced one the instance accepted. What an
+     * instance accepts is its own rule — the reference one takes a path under
+     * the `projects/` tree of its own config home, so that a session cannot
+     * turn a transcript read into a read of any file it names. */
     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 +99,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
@@ -28,7 +44,11 @@ export const Mid = Type.String({
 export type Mid = Static<typeof Mid>;
 
 /** Who a connection speaks as. Set once by `hello` and fixed for the
- * connection's life; the op attribute table's `roles` is checked against it. */
+ * connection's life; the op attribute table's `roles` is checked against it.
+ *
+ * Once by `hello` means once: a second `hello` on a connection whose identity
+ * is already settled is refused with `bad_request`, whether it repeats the
+ * role or names another. */
 export const Role = Type.Union(
   [Type.Literal("session"), Type.Literal("user"), Type.Literal("instance")],
   { $id: "Role" },

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(),

package/src/schemas.ts

@@ -3,7 +3,12 @@ import { TypeCompiler, type TypeCheck } from "@sinclair/typebox/compiler";
 import type { OpName } from "./attributes.ts";
 import { HelloRequest, HelloResponse } from "./common/hello.ts";
 import { InstancePingRequest, InstancePingResponse } from "./common/ping.ts";
-import { InstanceShutdownRequest, InstanceShutdownResponse } from "./common/shutdown.ts";
+import {
+  InstanceShutdownRequest,
+  InstanceShutdownResponse,
+  SessionStoppingRequest,
+  SessionStoppingResponse,
+} from "./common/shutdown.ts";
 import {
   TopicSubscribeRequest,
   TopicSubscribeResponse,
@@ -108,6 +113,7 @@ export const OP_SCHEMAS: Record<OpName, OpSchemas> = {
   hello: { request: HelloRequest, response: HelloResponse },
   instance_ping: { request: InstancePingRequest, response: InstancePingResponse },
   instance_shutdown: { request: InstanceShutdownRequest, response: InstanceShutdownResponse },
+  session_stopping: { request: SessionStoppingRequest, response: SessionStoppingResponse },
   topic_subscribe: { request: TopicSubscribeRequest, response: TopicSubscribeResponse },
   topic_unsubscribe: { request: TopicUnsubscribeRequest, response: TopicUnsubscribeResponse },
   message_send: { request: MessageSendRequest, response: MessageSendResponse },