@ccmsg/protocol 1.22.1 → 2.0.0

package/package.json

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

@@ -8,10 +8,10 @@ import type { Capability, Role } from "./identifiers.ts";
  * different op. */
 export type Plane = "common" | "messaging" | "control" | "mesh";
 
-/** `instance-local` ops answer for one instance's processes, paths and
+/** `owner_instance` ops answer for one instance's processes, paths and
  * handles, so they are forwarded to the instance that owns the subject.
- * `cluster` ops are answerable by whichever instance is asked. */
-export type Locality = "instance-local" | "cluster";
+ * `any_instance` ops are answerable by whichever instance is asked. */
+export type Locality = "owner_instance" | "any_instance";
 
 export interface OpAttributes {
   readonly plane: Plane;
@@ -65,47 +65,47 @@ export const OP_ATTRIBUTES = {
   //
   // The greetings 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.
+  // is why they are `any_instance` despite answering about one instance.
   "hello.session": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "hello.user": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "hello.instance": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "instance.ping": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "instance.shutdown": {
     plane: "common",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "session.stopping": {
     plane: "common",
     roles: SESSION_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   // Open to every role, with which role may have which topic left to the topic
@@ -115,20 +115,20 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["topic_unknown"],
   },
   "topic.unsubscribe": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["topic_unknown"],
   },
 
   // The four ops that authenticate a person are open to every role for the
   // same reason the greetings are: they run before there is an identity to
-  // check, and what they answer is what settles one. They are `cluster` because whichever
+  // check, and what they answer is what settles one. They are `any_instance` because whichever
   // instance is reached answers — behind a load balancer that is not a choice
   // the caller makes — and each asks the issuing instance itself for the parts
   // only it holds.
@@ -136,7 +136,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: [],
   },
@@ -144,7 +144,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
@@ -152,7 +152,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
@@ -160,7 +160,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
@@ -170,24 +170,24 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["auth_invalid", "auth_expired"],
   },
-  // Between instances: what an issuer alone can answer. Instance-local by the
+  // Between instances: what an issuer alone can answer. `owner_instance` by the
   // usual rule — the subject belongs to one instance, and it is reached by
   // `to_instance` being that instance's id.
   "auth.resolve": {
     plane: "common",
     roles: INSTANCE_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["auth_invalid", "auth_expired"],
   },
   "auth.rotate": {
     plane: "common",
     roles: INSTANCE_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["auth_invalid", "auth_expired"],
   },
 
@@ -196,29 +196,29 @@ export const OP_ATTRIBUTES = {
     plane: "messaging",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "cluster",
-    errors: ["session_not_found"],
+    locality: "any_instance",
+    errors: ["session_not_found", "session_duplicated"],
   },
   "say.post": {
     plane: "messaging",
     roles: SESSION_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["rate_limited"],
   },
   "say.unread.clear": {
     plane: "messaging",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "notify.send": {
     plane: "messaging",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "cluster",
-    errors: ["rate_limited"],
+    locality: "any_instance",
+    errors: ["rate_limited", "session_duplicated"],
   },
 
   // --- control: session observation and operation (10) ---
@@ -226,50 +226,50 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: ["session_not_found"],
+    locality: "owner_instance",
+    errors: ["session_not_found", "ambiguous_run"],
   },
   "session.rename": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     capability: "terminal",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["session_not_found"],
   },
   "session.env.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["session_not_found"],
   },
   "session.search": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "session.dump.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: ["not_found"],
+    locality: "owner_instance",
+    errors: ["not_found", "session_duplicated"],
   },
   "dump.presets.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "transcript.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
     errors: ["not_found"],
   },
@@ -277,7 +277,7 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
     errors: ["not_found"],
   },
@@ -286,14 +286,14 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "fork",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["not_found"],
   },
   "session.forget": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
 
@@ -302,66 +302,66 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
-    errors: ["path_forbidden", "not_found"],
+    errors: ["path_forbidden", "not_found", "session_duplicated"],
   },
   "file.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
-    errors: ["path_forbidden", "not_found"],
+    errors: ["path_forbidden", "not_found", "session_duplicated"],
   },
   "file.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: ["path_not_writable", "file_exists"],
+    locality: "owner_instance",
+    errors: ["path_not_writable", "file_exists", "session_duplicated"],
   },
   "file.create": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: ["file_exists", "path_forbidden"],
+    locality: "owner_instance",
+    errors: ["file_exists", "path_forbidden", "session_duplicated"],
   },
   "file.edit": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: ["file_conflict", "not_a_text_file"],
+    locality: "owner_instance",
+    errors: ["file_conflict", "not_a_text_file", "session_duplicated"],
   },
   "file.delete": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: ["path_forbidden", "not_found"],
+    locality: "owner_instance",
+    errors: ["path_forbidden", "not_found", "session_duplicated"],
   },
   "file.find": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: ["path_forbidden"],
+    locality: "owner_instance",
+    errors: ["path_forbidden", "session_duplicated"],
   },
   "file.stat": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
-    errors: [],
+    locality: "owner_instance",
+    errors: ["session_duplicated"],
   },
   "dir.tree": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     capability: "launcher",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
 
@@ -371,7 +371,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "launcher",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "launcher.run": {
@@ -379,7 +379,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "launcher",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "sandbox.grant": {
@@ -387,7 +387,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "sandbox",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["path_forbidden"],
   },
   "sandbox.revoke": {
@@ -395,7 +395,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "sandbox",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "translate.run": {
@@ -403,7 +403,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "translate",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["translate_helper_failed"],
   },
   "llm.usage.read": {
@@ -411,7 +411,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "llm_usage",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "llm.stats.read": {
@@ -419,32 +419,32 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "llm_stats",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
 
   // --- control: the shared key-value store (3) ---
-  // The only control ops that are not instance-local: a value is held by every
+  // The only control ops not answered by an owning instance: a value is held by every
   // instance rather than by one, so whichever is asked can answer.
   "kv.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["not_found"],
   },
   "kv.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "kv.delete": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
 } as const satisfies Record<string, OpAttributes>;
@@ -466,7 +466,7 @@ export function opErrors(op: OpName): ErrorCode[] {
   if (attrs.needs_hello) codes.add("hello_required");
   if (attrs.roles.length < ALL_ROLES.length) codes.add("forbidden");
   if (attrs.capability !== undefined) codes.add("capability_unavailable");
-  if (attrs.locality === "instance-local") codes.add("instance_unreachable");
+  if (attrs.locality === "owner_instance") codes.add("instance_unreachable");
   return [...codes];
 }
 

package/src/common/auth.ts

@@ -30,7 +30,7 @@ export const REGISTER_TTL_MS = 10 * 60 * 1000;
  * retention would otherwise carry the removed credential back as news. */
 export const FAMILY_TOMBSTONE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 
-/** Who a person is to this cluster. Issued when the registration URL is made
+/** Who a person is to this mesh. Issued when the registration URL is made
  * (`<unit>-<counter>` by default) and carried by every record they own. */
 export const Subject = Type.String({ $id: "Subject", minLength: 1, maxLength: 128 });
 export type Subject = Static<typeof Subject>;
@@ -337,11 +337,11 @@ export const AuthRotateResponse = response("auth.rotate", AuthRotateResult);
 
 // --- the replicated records ------------------------------------------------
 
-/** A registered passkey, as every instance in the cluster holds it.
+/** A registered passkey, as every instance in the mesh holds it.
  *
  * Complete once it is written: the instance that registered it is not asked
  * about it again, which is what lets a person authenticate anywhere in the
- * cluster while the instance they registered at is down. */
+ * mesh while the instance they registered at is down. */
 export const CredentialRecord = Type.Object(
   {
     kind: Type.Literal("credential"),
@@ -503,7 +503,7 @@ export type AuthTombstone = Static<typeof AuthTombstone>;
 /** One entry of the replicated set, under the key it is matched by. */
 export const AuthRecord = Type.Object(
   {
-    /** What this entry is, cluster-wide. Two instances writing one key hold the
+    /** What this entry is, mesh-wide. Two instances writing one key hold the
      * same thing, and the later `updated_at` is what stands. */
     key: Type.String({ minLength: 1, maxLength: 256 }),
     updated_at: Timestamp,

package/src/common/hello.ts

@@ -66,6 +66,16 @@ export const HelloSessionArgs = Type.Object({
   ...GREETING_FIELDS,
   /** The session the connection speaks for. */
   sid: Sid,
+  /** The harness process running this session. Where the greeting is carried by
+   * something standing in for the session — a hook, the CLI — it is the parent
+   * harness process's pid and not the helper's: what this names is the run, and
+   * the helper is not one.
+   *
+   * It is what ties this session to a process a launcher started before the
+   * harness had written anything of its own, and what lets two runs of one
+   * session be told apart. Optional: a session that cannot read it is greeted
+   * anyway, and the instance then knows the run by its connection alone. */
+  pid: Type.Optional(Type.Integer({ minimum: 1 })),
   /** 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
@@ -141,11 +151,11 @@ export const HelloResult = Type.Object({
   version: Type.String(),
   started_at: Timestamp,
   /** Where a person opens the terminal a session runs in: the base URL of the
-   * gateway that fronts this instance's terminals. A session's terminal names
-   * itself in `terminal_id` on the `agents` topic, and the gateway's URL for it
-   * is `<terminal_gateway>/sessions/<terminal_id>` — so the base URL carries no
-   * trailing slash, the path below it being the gateway's spelling and not this
-   * contract's.
+   * gateway that fronts this instance's terminals. A run's terminal names
+   * itself in `terminal_id`, and `terminalUrl` below composes the URL from the
+   * two — only for a handle under the `hyoui` scheme, this gateway serving no
+   * other. The base URL carries no trailing slash, the path below it being the
+   * gateway's spelling and not this contract's.
    *
    * Stated by the instance because only it knows which gateway stands in front
    * of the machine its sessions run on; a client has no way to derive one from
@@ -164,6 +174,29 @@ export const HelloResult = Type.Object({
 });
 export type HelloResult = Static<typeof HelloResult>;
 
+/** The terminal scheme the gateway in `terminal_gateway` serves. */
+export const HYOUI_TERMINAL_SCHEME = "hyoui";
+
+/** Where a person opens a run's terminal, or nothing.
+ *
+ * Nothing when the gateway is absent, and nothing when the handle is under
+ * another scheme: a handle names whose terminal it is, and composing this URL
+ * for one the gateway does not serve would hand a person a link to a page that
+ * is not there. A client holding such a handle opens it the way that system
+ * does, or leaves it unopened.
+ *
+ * Composed here rather than once per client, so the one place that knows both
+ * the scheme and the gateway's path is this contract. */
+export function terminalUrl(
+  gateway: string | undefined,
+  terminalId: string | undefined,
+): string | undefined {
+  if (gateway === undefined || terminalId === undefined) return undefined;
+  const prefix = `${HYOUI_TERMINAL_SCHEME}:`;
+  if (!terminalId.startsWith(prefix)) return undefined;
+  return `${gateway}/sessions/${terminalId.slice(prefix.length)}`;
+}
+
 export const HelloSessionRequest = request("hello.session", HelloSessionArgs);
 export const HelloSessionResponse = response("hello.session", HelloResult);
 

package/src/common/ping.ts

@@ -7,8 +7,8 @@ export type InstancePingArgs = Static<typeof InstancePingArgs>;
 
 /** How the answering daemon process is running.
  *
- * This is about one process, which is why the op is instance-local: the health
- * of the cluster is `hello`'s `instances[]`, not a ping fanned out. */
+ * This is about one process, which is why the op is `owner_instance`: the health
+ * of the mesh is `hello`'s `instances[]`, not a ping fanned out. */
 export const InstancePingResult = Type.Object({
   instance: InstanceId,
   version: Type.String(),

package/src/common/topics.ts

@@ -93,6 +93,12 @@ export interface TopicAttributes {
  * `forbidden`, and one naming a capability the instance lacks answers
  * `capability_unavailable`. */
 export const TOPIC_ATTRIBUTES = {
+  // The one topic where the same subscription means two things: a session is
+  // handed what was addressed to it, so what it reads leaves its inbox, while a
+  // person is looking at somebody else's mail and reading it moves nothing.
+  // Stated on the frame rather than as an attribute here — it is not a fold and
+  // not an authorization, and a subscriber does the same thing with the frames
+  // whichever it is.
   inbox: { roles: ["session", "user"], granularity: "element" },
   notify: { roles: ["session", "user"], granularity: "event" },
   // A row here changes on its own — one session becomes busy while the rest

package/src/control/agents.ts

@@ -1,19 +1,26 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { topicFrame } from "../envelope.ts";
-import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
+import { InstanceId, Sid, TerminalId, Timestamp } from "../identifiers.ts";
 import { upstream } from "../upstream.ts";
 
-/** One session as the harness itself reports it, noted with which config home
- * it was found under.
+/** One run of a session — one process — as the harness itself reports it, noted
+ * with which config home it was found under.
  *
  * This is the harness's view rather than the instance's: it covers sessions
  * that never connected here, and it carries what only the process knows — its
  * pid, its terminal, the title the session gave itself. The instance renames
  * the fields as it copies them in; the words inside them stay the harness's,
- * which is why the status-like fields are open sets. */
+ * which is why the status-like fields are open sets.
+ *
+ * A row is one process and is matched by `instance` and `pid`, never by `sid`:
+ * two processes may be running one session, and a launcher's process is here
+ * before it has a session at all. */
 export const AgentInfo = Type.Object(
   {
-    sid: Sid,
+    /** The session this process is running. Absent on a process a launcher
+     * started that the harness has not yet named a session for — it has a
+     * terminal and a start, and nothing to attach them to yet. */
+    sid: Type.Optional(Sid),
     /** The instance that polled it, and whose host the pid belongs to. */
     instance: InstanceId,
     pid: Type.Integer({ minimum: 1 }),
@@ -39,7 +46,7 @@ export const AgentInfo = Type.Object(
      * into. Absent when the process does not name one or its environment could
      * not be read. Read from the running process rather than remembered from
      * when it started, since resuming a session gives it a new process. */
-    terminal_id: Type.Optional(Type.String()),
+    terminal_id: Type.Optional(TerminalId),
     /** Which namespace that terminal lives in. Absent means the process set
      * none, which the multiplexer treats as its default — not the instance's
      * own namespace, which can differ. Typing into the wrong namespace reports a
@@ -50,13 +57,15 @@ export const AgentInfo = Type.Object(
 );
 export type AgentInfo = Static<typeof AgentInfo>;
 
-/** 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. */
+/** A row that is gone: the process ended, or the instance that polled it
+ * stopped. Marked rather than absent, since a frame carries only what changed.
+ *
+ * It names the pid and not the session: the session may well still be there,
+ * with another process running it. */
 export const AgentRemoved = Type.Object(
   {
-    sid: Sid,
     instance: InstanceId,
+    pid: Type.Integer({ minimum: 1 }),
     removed: Type.Literal(true),
   },
   { $id: "AgentRemoved" },
@@ -67,7 +76,7 @@ export const AgentElement = Type.Union([AgentInfo, AgentRemoved], { $id: "AgentE
 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`.
+ * last frame, matched by their `instance` and `pid`.
  *
  * The instance polls the harness only while somebody is listening here, so the
  * list is as fresh as the subscription is old — and a poll that finds one