@ccmsg/protocol 0.1.0 → 0.2.0

package/package.json

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

@@ -22,4 +22,5 @@ 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/message.ts

@@ -87,6 +87,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(),
+};