@ccmsg/protocol 0.4.0 → 0.5.0

package/package.json

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

@@ -68,7 +68,10 @@ 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),

package/src/identifiers.ts

@@ -44,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/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 },