@ccmsg/protocol 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
   "license": "MIT",
   "author": "kawaz",

package/src/common/hello.ts

@@ -1,6 +1,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response } from "../envelope.ts";
 import { Capability, 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.
  *
@@ -36,6 +37,19 @@ export const HelloArgs = Type.Object({
   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. */
+  repo: Type.Optional(SessionMetaFields.repo),
+  ws: Type.Optional(SessionMetaFields.ws),
+  cwd: Type.Optional(SessionMetaFields.cwd),
+  transcript_path: Type.Optional(SessionMetaFields.transcript_path),
+  repo_root: Type.Optional(SessionMetaFields.repo_root),
+  branch: Type.Optional(SessionMetaFields.branch),
+  title: Type.Optional(SessionMetaFields.title),
+  model: Type.Optional(SessionMetaFields.model),
+  effort: Type.Optional(SessionMetaFields.effort),
 });
 export type HelloArgs = Static<typeof HelloArgs>;
 

package/src/control/peers.ts

@@ -1,6 +1,40 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { topicFrame } from "../envelope.ts";
 import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
+import { SessionMetaFields } from "../session-meta.ts";
+
+/** How a session stands, as the instance holding it derives it.
+ *
+ * The instance states the classification rather than the raw inputs it read,
+ * so every client shows the same session the same way. The first three appear
+ * on connected sessions, the last two on sessions the instance has lost; a
+ * client that groups its list groups on this field alone.
+ *
+ * Being pinned is not one of these: a person pins a session, and the mark
+ * travels beside the classification rather than replacing it. */
+export const SessionState = Type.Union(
+  [
+    /** Stopped at something a person has to answer: a dialog it opened, or a
+     * turn that ended in an upstream error. */
+    Type.Literal("waiting"),
+    Type.Literal("live"),
+    /** Alive, but reachable through neither a client connection nor a
+     * terminal, so nothing here can act on it. */
+    Type.Literal("live_unmanaged"),
+    /** Gone, having said it was stopping. */
+    Type.Literal("paused"),
+    /** Gone without saying so. */
+    Type.Literal("disappeared"),
+  ],
+  { $id: "SessionState" },
+);
+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
+ * 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;
 
 /** A client of one session whose greeting was refused.
  *
@@ -31,17 +65,20 @@ export const PeerInfo = Type.Object(
   {
     sid: Sid,
     instance: InstanceId,
-    repo: Type.String(),
-    ws: Type.String(),
-    cwd: Type.String(),
-    /** Present when the session announced a transcript the instance accepted,
-     * which is what decides whether its transcript can be read at all. */
-    transcript_path: Type.Optional(Type.String()),
-    /** Present when the session announced a repository container the instance
-     * accepted. File browsing is rooted here rather than at the working
-     * directory, so sibling workspaces are reachable. */
-    repo_root: Type.Optional(Type.String()),
-    branch: Type.Optional(Type.String()),
+    repo: SessionMetaFields.repo,
+    ws: SessionMetaFields.ws,
+    cwd: SessionMetaFields.cwd,
+    /** Present when the session announced one the instance accepted. */
+    transcript_path: Type.Optional(SessionMetaFields.transcript_path),
+    repo_root: Type.Optional(SessionMetaFields.repo_root),
+    branch: Type.Optional(SessionMetaFields.branch),
+    /** 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. */
+    state: Type.Optional(SessionState),
+    /** Set while a person has pinned this session. Absent means not pinned. */
+    pinned: Type.Optional(Type.Boolean()),
     /** When this session first registered with the instance. Stable across its
      * reconnections, and reset when the instance restarts. */
     connected_at: Type.Optional(Timestamp),
@@ -88,23 +125,31 @@ export const LastLiveSession = Type.Object(
   {
     sid: Sid,
     instance: InstanceId,
-    repo: Type.String(),
-    ws: Type.String(),
-    cwd: Type.String(),
+    repo: SessionMetaFields.repo,
+    ws: SessionMetaFields.ws,
+    cwd: SessionMetaFields.cwd,
     /** Also where the model and effort below were read from. */
-    transcript_path: Type.Optional(Type.String()),
-    repo_root: Type.Optional(Type.String()),
-    branch: Type.Optional(Type.String()),
-    /** The session's own title as of the snapshot, when one was known. Absent
-     * means not known, never untitled. */
-    title: Type.Optional(Type.String()),
+    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(Type.String()),
-    effort: Type.Optional(Type.String()),
+    model: Type.Optional(SessionMetaFields.model),
+    effort: Type.Optional(SessionMetaFields.effort),
   },
   { $id: "LastLiveSession" },
 );

package/src/index.ts

@@ -18,8 +18,10 @@ export * from "./control/translate.ts";
 export * from "./envelope.ts";
 export * from "./errors.ts";
 export * from "./identifiers.ts";
+export * from "./messaging/direct-delivery.ts";
 export * from "./messaging/message.ts";
 export * from "./messaging/notify.ts";
 export * from "./messaging/say.ts";
 export * from "./schemas.ts";
+export * from "./session-meta.ts";
 export * from "./upstream.ts";

package/src/messaging/direct-delivery.ts

@@ -0,0 +1,136 @@
+import type { InboxMessage } from "./message.ts";
+import type { Mid, Sid } 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.
+ *
+ * On that route the recipient is the model, not a client: it reads one block of
+ * text and has no frame to look at. So `mid` and `from` have to be in the text
+ * or the recipient cannot answer — it would know a message arrived and not what
+ * to answer or how. That is what this module puts there, and nothing more: the
+ * wording is the delivery's, not the sender's, and `text` is carried through
+ * untouched.
+ *
+ * The shape is the harness's own sender convention, `<cross-session-message>`
+ * embedded in the message body. Sitting on it means the receiving harness reads
+ * the origin it already knows how to read, and a session that has seen a peer
+ * message sees the same envelope here. */
+
+/** The element senders wrap a peer message in. */
+export const DIRECT_DELIVERY_TAG = "cross-session-message";
+
+/** What the recipient's harness is told to answer to.
+ *
+ * Not the sender's session and not a `uds:` path. Those are the addresses the
+ * harness itself dials, and dialing one that has gone ends the recipient's turn
+ * in failure; the sender here is a daemon that offers no such socket anyway.
+ * A name asks for no answer, so there is nothing to dangle — the way back is
+ * the reply line, which the recipient runs rather than the harness. */
+export const DIRECT_DELIVERY_FROM = "ccmsg";
+
+/** What the recipient is told the sender is doing. `prompting` is what a peer
+ * mid-turn sends as, which is what a relayed message is. */
+export const DIRECT_DELIVERY_FROM_MODE = "prompting";
+
+/** How the recipient answers: the one line of instruction in the body.
+ *
+ * A command and not a description of one, because the recipient acts on it
+ * directly. `reply` names the thing being done and takes the frame it answers,
+ * so nothing has to be looked up to use it. */
+export function directDeliveryReplyLine(mid: Mid): string {
+  return `Reply with: ccmsg reply ${mid} <text>`;
+}
+
+/** An `InboxMessage` as it reaches a session through the messaging socket. */
+export interface DirectDelivery {
+  mid: Mid;
+  from: Sid;
+  from_label: string;
+  reply_to?: Mid;
+  /** The sender's text, exactly as it was sent. */
+  text: string;
+}
+
+/** Attribute values are quoted, so a label the sender chose cannot be trusted
+ * to stay inside its quotes. The identifiers cannot contain any of these, but
+ * they go through the same escape so one rule covers every attribute. */
+function escapeAttribute(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function unescapeAttribute(value: string): string {
+  return value
+    .replaceAll("&quot;", '"')
+    .replaceAll("&gt;", ">")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&amp;", "&");
+}
+
+/** Word a message for the messaging socket.
+ *
+ * `from` / `from-name` / `from-mode` are the harness's attributes, so the
+ * receiving harness reads the origin it expects. The `ccmsg-` ones are this
+ * protocol's: the harness has no use for them and a reader that does not know
+ * them sees an envelope it can still read, while a recipient that wants to
+ * answer has the `mid` and the sid without parsing prose.
+ *
+ * The body is not escaped. What the model reads is these characters, so
+ * entity-escaping them would hand the recipient a corrupted message to answer;
+ * a `</cross-session-message>` inside the text is left where the sender put it
+ * and the closing tag is found from the end (see `parseDirectDelivery`).
+ * Refusing such a message instead would lose it for a substring. */
+export function renderDirectDelivery(message: InboxMessage): string {
+  const attributes = [
+    `from="${DIRECT_DELIVERY_FROM}"`,
+    `from-name="${escapeAttribute(message.from_label)}"`,
+    `from-mode="${DIRECT_DELIVERY_FROM_MODE}"`,
+    `ccmsg-mid="${escapeAttribute(message.mid)}"`,
+    `ccmsg-from="${escapeAttribute(message.from)}"`,
+  ];
+  if (message.reply_to !== undefined) {
+    attributes.push(`ccmsg-reply-to="${escapeAttribute(message.reply_to)}"`);
+  }
+  const body = `${message.text}\n\n${directDeliveryReplyLine(message.mid)}`;
+  return `<${DIRECT_DELIVERY_TAG} ${attributes.join(" ")}>\n${body}\n</${DIRECT_DELIVERY_TAG}>`;
+}
+
+const OPENING = new RegExp(`^<${DIRECT_DELIVERY_TAG}((?:\\s+[a-z-]+="[^"]*")*)\\s*>\\n`);
+const ATTRIBUTE = /([a-z-]+)="([^"]*)"/g;
+
+/** Read back what `renderDirectDelivery` wrote.
+ *
+ * For the recipient side: a session or client holding the delivered text can
+ * recover the frame it answers without the sender's help. Returns `undefined`
+ * for anything that is not one of these envelopes — a plain message, or one
+ * missing the identity that makes it answerable.
+ *
+ * The closing tag is taken from the end so a body containing one round-trips,
+ * and the reply line this delivery added is removed, leaving the sender's own
+ * text. */
+export function parseDirectDelivery(delivered: string): DirectDelivery | undefined {
+  const opening = OPENING.exec(delivered);
+  if (!opening) return undefined;
+  const closing = `\n</${DIRECT_DELIVERY_TAG}>`;
+  const end = delivered.lastIndexOf(closing);
+  if (end < opening[0].length - 1) return undefined;
+
+  const attributes = new Map<string, string>();
+  for (const [, key, value] of (opening[1] ?? "").matchAll(ATTRIBUTE)) {
+    if (key !== undefined && value !== undefined) attributes.set(key, unescapeAttribute(value));
+  }
+  const mid = attributes.get("ccmsg-mid");
+  const from = attributes.get("ccmsg-from");
+  const from_label = attributes.get("from-name");
+  if (mid === undefined || from === undefined || from_label === undefined) return undefined;
+
+  let text = delivered.slice(opening[0].length, end);
+  const suffix = `\n\n${directDeliveryReplyLine(mid)}`;
+  if (text.endsWith(suffix)) text = text.slice(0, -suffix.length);
+
+  const reply_to = attributes.get("ccmsg-reply-to");
+  return { mid, from, from_label, ...(reply_to !== undefined ? { reply_to } : {}), text };
+}

package/src/messaging/message.ts

@@ -72,7 +72,8 @@ export const MessageSendResponse = response("message_send", MessageSendResult);
  *
  * 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 whichever client renders it. */
+ * belongs to whoever renders it — see `direct-delivery.ts` for the one route
+ * whose recipient reads text instead of this frame. */
 export const InboxMessage = Type.Object(
   {
     mid: Mid,
@@ -87,6 +88,18 @@ export const InboxMessage = Type.Object(
 );
 export type InboxMessage = Static<typeof InboxMessage>;
 
+/** How long an undelivered message is kept for its recipient. The same window
+ * a lost session stays listed for: a message outliving the session it was
+ * addressed to would be offered to no one, and a session outliving what was
+ * said to it would come back to an empty inbox. */
+export const INBOX_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** How many undelivered messages one session's inbox holds. Beyond it the
+ * oldest is dropped for the newest and the sender is told `inbox_full`. Matched
+ * to what the harness itself will hold for a session, so a message the inbox
+ * accepts is one the recipient can still be handed. */
+export const INBOX_MAX_PER_SID = 256;
+
 /** The `inbox` topic. Its snapshot is whatever is still undelivered for this
  * session; each later frame is one newly arrived message. */
 export const InboxFrame = topicFrame("inbox", Type.Array(InboxMessage));

package/src/session-meta.ts

@@ -0,0 +1,33 @@
+import { Type } from "@sinclair/typebox";
+
+/** The fields that describe where a session lives and what it runs as.
+ *
+ * Stated once and referenced wherever a session is described: the session names
+ * them itself in `hello`, and the instance repeats them on the `peers` topic
+ * for connected and last-known sessions alike. Which of them are required
+ * differs by place — a greeting may leave any of them unsaid — so each place
+ * wraps what it needs in `Type.Optional`, but the name and the type of a field
+ * never differ between them. */
+export const SessionMetaFields = {
+  /** The repository the session works in, as a display name. */
+  repo: Type.String(),
+  /** The workspace (worktree) name within that repository. */
+  ws: Type.String(),
+  /** The session's working directory. */
+  cwd: Type.String(),
+  /** The transcript file, which is what decides whether the session's
+   * transcript can be read at all. */
+  transcript_path: Type.String(),
+  /** The repository container. File browsing is rooted here rather than at the
+   * working directory, so sibling workspaces are reachable. An instance that is
+   * not told one derives it from `cwd`. */
+  repo_root: Type.String(),
+  /** The branch checked out in that workspace. */
+  branch: Type.String(),
+  /** The session's own title. Absent means not known, never untitled. */
+  title: Type.String(),
+  /** The model the session runs as, in its own spelling. */
+  model: Type.String(),
+  /** The reasoning effort the session runs at, in its own spelling. */
+  effort: Type.String(),
+};