@ccmsg/protocol 1.19.0 → 1.20.0

package/package.json

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

@@ -7,6 +7,7 @@ export const PLAIN_TOPICS = [
   "inbox",
   "notify",
   "peers",
+  "instances",
   "agents",
   "session_errors",
   "llm_requests",
@@ -89,8 +90,17 @@ export interface TopicAttributes {
 export const TOPIC_ATTRIBUTES = {
   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" },
+  // A row here changes on its own — one session becomes busy while the rest
+  // stand still — so a frame carries the rows that changed rather than every
+  // row the instance knows.
+  peers: { roles: ["session", "user"], granularity: "element" },
+  // One instance's whole reading of its links, taken together, which is why it
+  // is apart from the rows of `peers`.
+  instances: { roles: ["session", "user"], granularity: "per_instance_whole" },
+  agents: { roles: ["user"], granularity: "element" },
+  // A set the instance derives whole, by folding one error pattern over its
+  // sessions: it learns which sessions are stopped, not that one of them
+  // changed, so each frame is that reading entire.
   session_errors: { roles: ["user"], granularity: "per_instance_whole" },
   llm_requests: {
     roles: ["user"],

package/src/control/agents.ts

@@ -50,15 +50,34 @@ export const AgentInfo = Type.Object(
 );
 export type AgentInfo = Static<typeof AgentInfo>;
 
-/** The `agents` topic. Whole-value per instance, like `peers`.
+/** A row that is gone: the harness no longer reports this session, or the
+ * instance that polled it stopped. Marked rather than absent, since a frame
+ * carries only what changed. */
+export const AgentRemoved = Type.Object(
+  {
+    sid: Sid,
+    instance: InstanceId,
+    removed: Type.Literal(true),
+  },
+  { $id: "AgentRemoved" },
+);
+export type AgentRemoved = Static<typeof AgentRemoved>;
+
+export const AgentElement = Type.Union([AgentInfo, AgentRemoved], { $id: "AgentElement" });
+export type AgentElement = Static<typeof AgentElement>;
+
+/** The `agents` topic. Elements, like `peers`: the rows that changed since the
+ * last frame, matched by their `instance` and `sid`.
  *
  * The instance polls the harness only while somebody is listening here, so the
- * list is as fresh as the subscription is old. */
+ * list is as fresh as the subscription is old — and a poll that finds one
+ * session's status changed says that, rather than restating every row it read.
+ */
 export const AgentsFrame = topicFrame(
   "agents",
   Type.Object({
-    agents: Type.Array(AgentInfo),
-    /** When the poll behind this list ran. Absent before the first one. */
+    agents: Type.Array(AgentElement),
+    /** When the poll behind these rows ran. Absent before the first one. */
     polled_at: Type.Optional(Timestamp),
   }),
 );

package/src/control/instances.ts

@@ -0,0 +1,21 @@
+import { Type } from "@sinclair/typebox";
+import { InstanceInfo } from "../common/hello.ts";
+import { topicFrame } from "../envelope.ts";
+
+/** The `instances` topic: the mesh as one instance sees it, itself included,
+ * as `hello` answers it.
+ *
+ * Carried as a topic so that a link going down is something a subscriber
+ * learns where it is already listening, rather than by greeting again to find
+ * out.
+ *
+ * Whole-value per instance: `reachable` is one instance's reading of every
+ * link it has, taken together, and two instances may legitimately disagree
+ * about the same link — so a frame states one sender's whole view and leaves
+ * every other sender's alone. It is apart from `peers` for the same reason it
+ * is whole: a mesh view is one value, while a session row is a row, and an
+ * entry here may also stand before its instance has an id to be matched by. */
+export const InstancesFrame = topicFrame(
+  "instances",
+  Type.Object({ instances: Type.Array(InstanceInfo) }),
+);

package/src/control/peers.ts

@@ -1,5 +1,4 @@
 import { type Static, Type } from "@sinclair/typebox";
-import { InstanceInfo } from "../common/hello.ts";
 import { topicFrame } from "../envelope.ts";
 import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
 import { SessionMetaFields } from "../session-meta.ts";
@@ -31,8 +30,9 @@ export const SessionState = Type.Union(
 );
 export type SessionState = Static<typeof SessionState>;
 
-/** How long a session stays in `last_live` after it was last seen. The same
- * window the inbox keeps undelivered messages for: what a person comes back to
+/** How long a lost session's row is kept after it was last seen, before the
+ * instance forgets it and the row leaves as a removal. The same window the inbox
+ * keeps undelivered messages for: what a person comes back to
  * is one thing — the session and what was said to it — so the two cannot expire
  * at different times. */
 export const LAST_LIVE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
@@ -57,11 +57,20 @@ export const StaleClientInfo = Type.Object(
 );
 export type StaleClientInfo = Static<typeof StaleClientInfo>;
 
-/** One session an instance can call live (connected or not).
+/** One session an instance knows of, connected or lost.
  *
  * The paths are the host's, so the entry names the instance holding them:
  * `peers` carries every instance's sessions in one list, and two hosts' paths
- * would otherwise be indistinguishable. */
+ * would otherwise be indistinguishable. The pair `instance` and `sid` is also
+ * what a later row is matched against, since one session lives on one
+ * instance.
+ *
+ * Connected and lost sessions are one kind of row rather than two lists: a
+ * session registering or going quiet moves it between the two, and a row that
+ * changed lists while keeping its identity is an update of that row. Which it
+ * is now is the `state` below, and the fields that only a lost session has
+ * (`last_seen_at`, `stopped_at`, and what it must resume as) are stated
+ * alongside the connection fields it kept. */
 export const PeerInfo = Type.Object(
   {
     sid: Sid,
@@ -81,10 +90,10 @@ export const PeerInfo = Type.Object(
      * 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
-     * shows the session without grouping it rather than guessing one. */
+    /** How this session stands, which is also what separates a connected row
+     * from one its instance has lost. Absent from an instance that states no
+     * classification, and a client then shows the session without grouping it
+     * rather than guessing one. */
     state: Type.Optional(SessionState),
     /** Set while a person has pinned this session. Absent means not pinned. */
     pinned: Type.Optional(Type.Boolean()),
@@ -129,77 +138,52 @@ export const PeerInfo = Type.Object(
     protocol_version: Type.Optional(Type.Integer({ minimum: 1 })),
     /** Set while some client of this session is being refused. */
     stale_client: Type.Optional(StaleClientInfo),
+    /** The newest instant this session is known to have been alive. Stated on a
+     * row its instance has lost, where it is what the retention window above is
+     * measured from; a connected row is alive now and states none. */
+    last_seen_at: Type.Optional(Timestamp),
+    /** When the session said it was stopping. Its presence is what makes a lost
+     * session a pause rather than a disappearance: one that goes without a word
+     * leaves nothing to stamp here. */
+    stopped_at: Type.Optional(Timestamp),
+    /** What its last turn ran as, in the transcript's own spelling, read back
+     * from the transcript rather than copied from the connection: what a lost
+     * session must resume as is a property of where it actually stopped. A
+     * resume must not quietly switch the session to something else. */
+    model: Type.Optional(SessionMetaFields.model),
+    effort: Type.Optional(SessionMetaFields.effort),
   },
   { $id: "PeerInfo" },
 );
 export type PeerInfo = Static<typeof PeerInfo>;
 
-/** One session that was connected when its instance last saw it, and has not
- * come back.
+/** A row that is gone: the session has been forgotten by the instance that
+ * held it, whether its retention window ran out or a person dropped it.
  *
- * The connection fields are a frozen copy of what that session looked like at
- * the last snapshot, not a live reading — by definition it is not connected
- * while it appears here. The model and effort are the exception: they are read
- * back from the transcript's last turn, because what the session must resume as
- * is a property of where it actually stopped, not of when the snapshot was
- * written. An entry leaves this list the moment its session registers again, so
- * a fully recovered host shows none. */
-export const LastLiveSession = Type.Object(
+ * A removal has to be a marked element rather than an absence, since a frame
+ * carries only what changed and an absence in it says nothing. It names the
+ * same pair every row is matched by and nothing else — there is no row left to
+ * describe. */
+export const PeerRemoved = Type.Object(
   {
     sid: Sid,
     instance: InstanceId,
-    repo: SessionMetaFields.repo,
-    ws: SessionMetaFields.ws,
-    cwd: SessionMetaFields.cwd,
-    /** Also where the model and effort below were read from. */
-    transcript_path: Type.Optional(SessionMetaFields.transcript_path),
-    repo_root: Type.Optional(SessionMetaFields.repo_root),
-    branch: Type.Optional(SessionMetaFields.branch),
-    title: Type.Optional(SessionMetaFields.title),
-    /** How this session stands: `paused` or `disappeared`, which the
-     * `stopped_at` below is what separates. Absent from an instance that states
-     * no classification. */
-    state: Type.Optional(SessionState),
-    /** Set while a person has pinned this session. Absent means not pinned. */
-    pinned: Type.Optional(Type.Boolean()),
-    connected_at: Type.Optional(Timestamp),
-    /** The newest instant this session is known to have been alive. */
-    last_seen_at: Timestamp,
-    /** When the session said it was stopping. Its presence is what makes this a
-     * pause rather than a disappearance: a session that goes without a word
-     * leaves nothing to stamp here. */
-    stopped_at: Type.Optional(Timestamp),
-    /** What its last turn ran as, in the transcript's own spelling. A resume
-     * must not quietly switch the session to something else. */
-    model: Type.Optional(SessionMetaFields.model),
-    effort: Type.Optional(SessionMetaFields.effort),
+    removed: Type.Literal(true),
   },
-  { $id: "LastLiveSession" },
+  { $id: "PeerRemoved" },
 );
-export type LastLiveSession = Static<typeof LastLiveSession>;
+export type PeerRemoved = Static<typeof PeerRemoved>;
+
+export const PeerElement = Type.Union([PeerInfo, PeerRemoved], { $id: "PeerElement" });
+export type PeerElement = Static<typeof PeerElement>;
 
 /** The `peers` topic.
  *
- * Whole-value per instance: a frame replaces everything previously known from
- * the instance that sent it and leaves other instances' entries alone, which is
- * what lets several instances each state their whole list without colliding.
+ * Elements: each frame carries the rows that changed, matched by their
+ * `instance` and `sid`, and rows it does not name are left as they were. A row
+ * changes on its own — one session becoming busy, another going quiet — and
+ * restating every row an instance knows would send a list to report one field.
  *
- * Both lists travel together because a session registering is exactly what
- * moves it from one to the other. */
-export const PeersFrame = topicFrame(
-  "peers",
-  Type.Object({
-    peers: Type.Array(PeerInfo),
-    last_live: Type.Array(LastLiveSession),
-    /** The instances the sending one can see, itself included, as `hello`
-     * answers it. Carried here so that a link going down is something a
-     * subscriber learns from the topic it is already on, rather than by
-     * greeting again to find out. It is the sender's own view like the two
-     * lists above — `reachable` says whether that instance can reach the one it
-     * names, which two instances may legitimately disagree about.
-     *
-     * Absent from an instance that states no view; a client then keeps what it
-     * last knew rather than reading the omission as nothing being reachable. */
-    instances: Type.Optional(Type.Array(InstanceInfo)),
-  }),
-);
+ * The opening `snapshot: true` frame carries every row the instance holds,
+ * connected and lost alike. */
+export const PeersFrame = topicFrame("peers", Type.Object({ peers: Type.Array(PeerElement) }));

package/src/fixtures/index.ts

@@ -163,6 +163,7 @@ export const TOPIC_FIXTURES = {
   inbox: topics.INBOX_FRAME,
   notify: topics.NOTIFY_FRAME,
   peers: topics.PEERS_FRAME,
+  instances: topics.INSTANCES_FRAME,
   agents: topics.AGENTS_FRAME,
   session_status: topics.SESSION_STATUS_FRAME,
   transcript: topics.TRANSCRIPT_FRAME,

package/src/fixtures/topics.ts

@@ -1,6 +1,7 @@
 import type { Static } from "@sinclair/typebox";
 import type { AuthRecordsFrame } from "../common/auth.ts";
 import type { AgentsFrame } from "../control/agents.ts";
+import type { InstancesFrame } from "../control/instances.ts";
 import type { KvFrame } from "../control/kv.ts";
 import type { LlmRequestsFrame, LlmStatusFrame } from "../control/llm.ts";
 import type { PeersFrame } from "../control/peers.ts";
@@ -94,16 +95,6 @@ export const PEERS_FRAME: Static<typeof PeersFrame> = {
         repo: "ccmsg",
         ws: "daemon-v2",
         cwd: "/repos/kawaz/ccmsg/daemon-v2",
-        state: "live_unmanaged",
-      },
-    ],
-    last_live: [
-      {
-        sid: other_sid,
-        instance,
-        repo: "ccmsg",
-        ws: "daemon-v2",
-        cwd: "/repos/kawaz/ccmsg/daemon-v2",
         state: "paused",
         last_seen_at: FIXTURE_NOW - 1_200_000,
         stopped_at: FIXTURE_NOW - 1_000_000,
@@ -111,6 +102,28 @@ export const PEERS_FRAME: Static<typeof PeersFrame> = {
         effort: "high",
       },
     ],
+  },
+};
+
+/** A later frame: one row moved on, and one the instance forgot. */
+export const PEERS_CHANGE_FRAME: Static<typeof PeersFrame> = {
+  ev: "topic",
+  topic: "peers",
+  instance,
+  data: {
+    peers: [
+      { ...PEER, state: "live", gateway_active_at: FIXTURE_NOW + 1_000 },
+      { sid: "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", instance, removed: true },
+    ],
+  },
+};
+
+export const INSTANCES_FRAME: Static<typeof InstancesFrame> = {
+  ev: "topic",
+  topic: "instances",
+  snapshot: true,
+  instance,
+  data: {
     instances: [
       { id: instance, endpoint, host: "mba", reachable: true },
       { id: other_instance, endpoint: other_endpoint, host: "nuc", reachable: false },
@@ -144,6 +157,14 @@ export const AGENTS_FRAME: Static<typeof AgentsFrame> = {
   },
 };
 
+/** A later frame: the harness no longer reports one of the rows above. */
+export const AGENTS_CHANGE_FRAME: Static<typeof AgentsFrame> = {
+  ev: "topic",
+  topic: "agents",
+  instance,
+  data: { agents: [{ sid: other_sid, instance, removed: true }], polled_at: FIXTURE_NOW + 5_000 },
+};
+
 export const SESSION_STATUS_FRAME: Static<typeof SessionStatusFrame> = {
   ev: "topic",
   topic: `session_status:${sid}`,

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./common/topics.ts";
 export * from "./control/agents.ts";
 export * from "./control/dump.ts";
 export * from "./control/files.ts";
+export * from "./control/instances.ts";
 export * from "./control/kv.ts";
 export * from "./control/launcher.ts";
 export * from "./control/llm.ts";

package/src/schemas.ts

@@ -77,6 +77,7 @@ import {
   LlmUsageReadRequest,
   LlmUsageReadResponse,
 } from "./control/llm.ts";
+import { InstancesFrame } from "./control/instances.ts";
 import { PeersFrame } from "./control/peers.ts";
 import {
   SandboxGrantRequest,
@@ -201,6 +202,7 @@ export const TOPIC_SCHEMAS = {
   inbox: InboxFrame,
   notify: NotifyFrame,
   peers: PeersFrame,
+  instances: InstancesFrame,
   agents: AgentsFrame,
   session_status: SessionStatusFrame,
   transcript: TranscriptFrame,