@ccmsg/protocol 1.19.0 → 1.21.0

package/src/common/hello.ts

@@ -3,7 +3,7 @@ import { request, response } from "../envelope.ts";
 import { Capability, Endpoint, InstanceId, Role, Sid, Timestamp } from "../identifiers.ts";
 import { SessionMetaFields } from "../session-meta.ts";
 
-/** The mesh handshake's opening claim, carried by a `role: "instance"` hello.
+/** The mesh handshake's opening claim, carried by `hello.instance`.
  *
  * It is not signed and proves nothing on its own: it names the peer and says
  * where its one-off key can be fetched. The proof that binds this connection to
@@ -36,42 +36,39 @@ 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`.
+/** What every greeting carries, whichever of the three it is. */
+const GREETING_FIELDS = {
+  /** The generation the caller speaks. A hello announcing another generation
+   * is refused with `bad_request`; there is no path that serves it anyway. */
+  protocol_version: Type.Integer({ minimum: 1 }),
+  /** The client build, for display in diagnostics. Nothing gates on it. */
+  client_version: Type.Optional(Type.String()),
+};
+
+/** The greeting that settles what a connection is. There is one op per role,
+ * so what a greeting must carry is the schema's to state rather than a check
+ * the instance runs against a `role` field: a session names its `sid`, an
+ * instance its mesh claim, and a person neither.
  *
- * A field that belongs to another role is as much a refusal as a missing one:
+ * 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.
+ * is in — which is what the three ops keep apart: a greeting arrives under the
+ * name of the thing it settles, and there is no state in which the name and the
+ * fields disagree.
  *
  * A session's meta (`cwd`, `repo_root`, `transcript_path`, `title`, ...) is
  * taken field by field: a greeting that leaves a field out does not withdraw
  * it, and the instance keeps what it already knows for that `sid`. One session
  * reaches an instance as a run of short-lived processes (a session-start hook,
  * a `post`, a session-end hook), none of which knows every field. */
-export const HelloArgs = Type.Object({
-  role: Role,
-  /** The generation the caller speaks. A hello announcing another generation
-   * is refused with `bad_request`; there is no path that serves it anyway. */
-  protocol_version: Type.Integer({ minimum: 1 }),
-  /** Required for `role: "session"`: the session the connection speaks for. */
-  sid: Type.Optional(Sid),
-  /** Required for `role: "instance"`: the mesh handshake claim. */
-  mesh: Type.Optional(MeshHello),
-  /** The client build, for display in diagnostics. Nothing gates on it. */
-  client_version: Type.Optional(Type.String()),
-  /** What a `role: "session"` connection says about itself. All optional: a
-   * session states what it knows, and the instance derives or leaves unknown
-   * what it is not told. The instance repeats these on the `peers` topic, so
-   * they are the same fields under the same names there. */
+export const HelloSessionArgs = Type.Object({
+  ...GREETING_FIELDS,
+  /** The session the connection speaks for. */
+  sid: Sid,
+  /** What the session says about itself. All optional: a session states what it
+   * knows, and the instance derives or leaves unknown what it is not told. The
+   * instance repeats these on the `peers` topic, so they are the same fields
+   * under the same names there. */
   repo: Type.Optional(SessionMetaFields.repo),
   ws: Type.Optional(SessionMetaFields.ws),
   cwd: Type.Optional(SessionMetaFields.cwd),
@@ -82,9 +79,22 @@ export const HelloArgs = Type.Object({
   model: Type.Optional(SessionMetaFields.model),
   effort: Type.Optional(SessionMetaFields.effort),
 });
-export type HelloArgs = Static<typeof HelloArgs>;
+export type HelloSessionArgs = Static<typeof HelloSessionArgs>;
+
+/** A person greeting. It names no session: a person speaks for none of them,
+ * and the sessions they may act on are decided by the op table rather than by
+ * anything settled here. */
+export const HelloUserArgs = Type.Object(GREETING_FIELDS);
+export type HelloUserArgs = Static<typeof HelloUserArgs>;
+
+/** A peer instance greeting, which opens the mesh handshake. */
+export const HelloInstanceArgs = Type.Object({
+  ...GREETING_FIELDS,
+  mesh: MeshHello,
+});
+export type HelloInstanceArgs = Static<typeof HelloInstanceArgs>;
 
-/** One instance as seen from the instance answering `hello`. */
+/** One instance as seen from the instance answering a greeting. */
 export const InstanceInfo = Type.Object(
   {
     /** Absent until the handshake with it has settled: an endpoint an operator
@@ -148,10 +158,38 @@ export const HelloResult = Type.Object({
    * closes it. Present on a connection an access token opened; absent where
    * reaching the instance is itself the permission (the Unix socket) or where
    * the connection is a mesh link. The person's client renews before this
-   * instant with `auth_refresh` rather than reconnecting. */
+   * instant with `auth.extend` rather than reconnecting. */
   auth_expires_at: Type.Optional(Timestamp),
 });
 export type HelloResult = Static<typeof HelloResult>;
 
-export const HelloRequest = request("hello", HelloArgs);
-export const HelloResponse = response("hello", HelloResult);
+export const HelloSessionRequest = request("hello.session", HelloSessionArgs);
+export const HelloSessionResponse = response("hello.session", HelloResult);
+
+export const HelloUserRequest = request("hello.user", HelloUserArgs);
+export const HelloUserResponse = response("hello.user", HelloResult);
+
+export const HelloInstanceRequest = request("hello.instance", HelloInstanceArgs);
+export const HelloInstanceResponse = response("hello.instance", HelloResult);
+
+/** The role a greeting settles, read from the op that carried it.
+ *
+ * The role itself stays — the op table and the topic table are written against
+ * it, and a forwarded request names it in `caller` — and what a greeting no
+ * longer carries is a second place to say it. */
+export const HELLO_OPS = {
+  "hello.session": "session",
+  "hello.user": "user",
+  "hello.instance": "instance",
+} as const satisfies Record<string, Role>;
+
+export type HelloOp = keyof typeof HELLO_OPS;
+
+export function isHelloOp(op: string): op is HelloOp {
+  return op in HELLO_OPS;
+}
+
+/** The role a connection speaks once `op` has been answered. */
+export function helloRole(op: HelloOp): Role {
+  return HELLO_OPS[op];
+}

package/src/common/ping.ts

@@ -33,5 +33,5 @@ export const InstancePingResult = Type.Object({
 });
 export type InstancePingResult = Static<typeof InstancePingResult>;
 
-export const InstancePingRequest = request("instance_ping", InstancePingArgs);
-export const InstancePingResponse = response("instance_ping", InstancePingResult);
+export const InstancePingRequest = request("instance.ping", InstancePingArgs);
+export const InstancePingResponse = response("instance.ping", InstancePingResult);

package/src/common/shutdown.ts

@@ -11,8 +11,8 @@ export type InstanceShutdownArgs = Static<typeof InstanceShutdownArgs>;
 export const InstanceShutdownResult = Type.Object({});
 export type InstanceShutdownResult = Static<typeof InstanceShutdownResult>;
 
-export const InstanceShutdownRequest = request("instance_shutdown", InstanceShutdownArgs);
-export const InstanceShutdownResponse = response("instance_shutdown", 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.
@@ -44,5 +44,5 @@ export const SessionStoppingResult = Type.Object({
 });
 export type SessionStoppingResult = Static<typeof SessionStoppingResult>;
 
-export const SessionStoppingRequest = request("session_stopping", SessionStoppingArgs);
-export const SessionStoppingResponse = response("session_stopping", SessionStoppingResult);
+export const SessionStoppingRequest = request("session.stopping", SessionStoppingArgs);
+export const SessionStoppingResponse = response("session.stopping", SessionStoppingResult);

package/src/common/topics.ts

@@ -7,15 +7,16 @@ export const PLAIN_TOPICS = [
   "inbox",
   "notify",
   "peers",
+  "instances",
   "agents",
-  "session_errors",
-  "llm_requests",
-  "llm_status",
-  "auth_records",
+  "session.errors",
+  "llm.requests",
+  "llm.status",
+  "auth.records",
 ] as const;
 
 /** Topics naming one session, written `<topic>:<sid>`. */
-export const SESSION_SCOPED_TOPICS = ["session_status", "transcript", "transcript_items"] as const;
+export const SESSION_SCOPED_TOPICS = ["session.status", "transcript", "transcript.items"] as const;
 
 /** Topics naming one namespace, written `<topic>:<ns>`. The parameter is a name
  * its users choose rather than an identifier this contract issues, so it is
@@ -35,13 +36,18 @@ export type TopicName =
   | `${SessionScopedTopic}:${string}`
   | `${NamespaceScopedTopic}:${string}`;
 
+/** A topic name is a `.`-separated hierarchy, so its dots are literal here
+ * rather than the regexp's any-character. */
+const alternation = (topics: readonly string[]): string =>
+  topics.map((topic) => topic.replace(/\./g, "\\.")).join("|");
+
 export const Topic = Type.String({
   $id: "Topic",
   pattern: [
     "^(?:",
-    PLAIN_TOPICS.join("|"),
-    `|(?:${SESSION_SCOPED_TOPICS.join("|")}):[0-9a-f-]{36}`,
-    `|(?:${NAMESPACE_SCOPED_TOPICS.join("|")}):${NAMESPACE_PATTERN}`,
+    alternation(PLAIN_TOPICS),
+    `|(?:${alternation(SESSION_SCOPED_TOPICS)}):[0-9a-f-]{36}`,
+    `|(?:${alternation(NAMESPACE_SCOPED_TOPICS)}):${NAMESPACE_PATTERN}`,
     ")$",
   ].join(""),
 });
@@ -89,29 +95,38 @@ 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" },
-  session_errors: { roles: ["user"], granularity: "per_instance_whole" },
-  llm_requests: {
+  // 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"],
     capability: "llm_events",
     granularity: "per_instance_whole",
   },
-  llm_status: { roles: ["user"], capability: "llm_status", 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" },
+  "session.status": { roles: ["user"], granularity: "whole" },
   transcript: { roles: ["user"], granularity: "append" },
   // The same appending, in items rather than in bytes. Both are offered because
   // they answer different needs: one draws the conversation, the other shows a
   // record as it was written.
-  transcript_items: { roles: ["user"], granularity: "append" },
+  "transcript.items": { roles: ["user"], granularity: "append" },
   kv: { roles: ["user"], granularity: "element" },
   // The only topic no person may subscribe to: its elements are the secrets
   // that authenticate them. A relay carries it as the instance it is, not on a
   // caller's behalf, so there is no path by which a person's subscription
   // reaches it.
-  auth_records: { roles: ["instance"], granularity: "element" },
+  "auth.records": { roles: ["instance"], granularity: "element" },
 } as const satisfies Record<
   PlainTopic | SessionScopedTopic | NamespaceScopedTopic,
   TopicAttributes
@@ -126,7 +141,7 @@ export function topicKind(topic: string): TopicKind | 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.
+ * 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);
@@ -142,8 +157,8 @@ export type TopicSubscribeArgs = Static<typeof TopicSubscribeArgs>;
 export const TopicSubscribeResult = Type.Object({ topic: Topic });
 export type TopicSubscribeResult = Static<typeof TopicSubscribeResult>;
 
-export const TopicSubscribeRequest = request("topic_subscribe", TopicSubscribeArgs);
-export const TopicSubscribeResponse = response("topic_subscribe", TopicSubscribeResult);
+export const TopicSubscribeRequest = request("topic.subscribe", TopicSubscribeArgs);
+export const TopicSubscribeResponse = response("topic.subscribe", TopicSubscribeResult);
 
 export const TopicUnsubscribeArgs = Type.Object({ topic: Topic });
 export type TopicUnsubscribeArgs = Static<typeof TopicUnsubscribeArgs>;
@@ -151,5 +166,5 @@ export type TopicUnsubscribeArgs = Static<typeof TopicUnsubscribeArgs>;
 export const TopicUnsubscribeResult = Type.Object({ topic: Topic });
 export type TopicUnsubscribeResult = Static<typeof TopicUnsubscribeResult>;
 
-export const TopicUnsubscribeRequest = request("topic_unsubscribe", TopicUnsubscribeArgs);
-export const TopicUnsubscribeResponse = response("topic_unsubscribe", TopicUnsubscribeResult);
+export const TopicUnsubscribeRequest = request("topic.unsubscribe", TopicUnsubscribeArgs);
+export const TopicUnsubscribeResponse = response("topic.unsubscribe", TopicUnsubscribeResult);

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),
   }),
 );