@ccmsg/protocol 0.1.0

package/src/control/session-errors.ts

@@ -0,0 +1,27 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { topicFrame } from "../envelope.ts";
+import { InstanceId, Sid } from "../identifiers.ts";
+import { SessionApiError } from "./session-status.ts";
+
+/** Which session is stopped, and on what. */
+export const SessionErrorEntry = Type.Intersect(
+  [Type.Object({ sid: Sid, instance: InstanceId }), SessionApiError],
+  { $id: "SessionErrorEntry" },
+);
+export type SessionErrorEntry = Static<typeof SessionErrorEntry>;
+
+/** The `session_errors` topic: every connected session currently stopped on a
+ * harness error.
+ *
+ * Not per session, unlike `session_status`. A client showing a list of sessions
+ * has to mark the stopped ones, and subscribing to a whole status fold for each
+ * visible session is the cost this exists to avoid: the instance folds the one
+ * error pattern over every connected session instead.
+ *
+ * Whole-value per instance. A session that recovers drops out of the list
+ * rather than appearing with an empty error, so a client that missed a frame
+ * still converges on the next one. */
+export const SessionErrorsFrame = topicFrame(
+  "session_errors",
+  Type.Object({ errors: Type.Array(SessionErrorEntry) }),
+);

package/src/control/session-status.ts

@@ -0,0 +1,311 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { topicFrame } from "../envelope.ts";
+import { Sid, Timestamp } from "../identifiers.ts";
+
+/** One task on the session's list. */
+export const SessionTodo = Type.Object(
+  {
+    id: Type.String(),
+    subject: Type.String(),
+    /** Pending, in progress, done — an open set the harness may grow. */
+    status: Type.String(),
+    owner: Type.Optional(Type.String()),
+    /** Tasks this one waits on, and tasks that wait on it. Both are read out of
+     * the session's own transcript, and both are empty when nothing was
+     * declared. */
+    blocked_by: Type.Array(Type.String()),
+    blocks: Type.Array(Type.String()),
+  },
+  { $id: "SessionTodo" },
+);
+export type SessionTodo = Static<typeof SessionTodo>;
+
+/** One phase of a workflow, with how much of it is finished. */
+export const WorkflowPhaseStatus = Type.Object(
+  { title: Type.String(), done: Type.Integer({ minimum: 0 }), total: Type.Integer({ minimum: 0 }) },
+  { $id: "WorkflowPhaseStatus" },
+);
+export type WorkflowPhaseStatus = Static<typeof WorkflowPhaseStatus>;
+
+/** One agent belonging to a workflow.
+ *
+ * Nearly everything is optional because a finished agent and a running one are
+ * observed from different places: a finished one is described by the record the
+ * workflow wrote, a running one only by the fact that it started and has not
+ * reported back. */
+export const WorkflowAgentStatus = Type.Object(
+  {
+    /** The handle a transcript read accepts for this agent. */
+    agent_id: Type.String(),
+    label: Type.Optional(Type.String()),
+    model: Type.Optional(Type.String()),
+    agent_type: Type.Optional(Type.String()),
+    /** How it is getting on. An open set: most values come from the workflow's
+     * own record, and "still running" is inferred from a start with no result. */
+    state: Type.String(),
+    tokens: Type.Optional(Type.Integer({ minimum: 0 })),
+    tool_calls: Type.Optional(Type.Integer({ minimum: 0 })),
+    phase_index: Type.Optional(Type.Integer({ minimum: 0 })),
+    phase_title: Type.Optional(Type.String()),
+    last_tool: Type.Optional(Type.String()),
+    result_preview: Type.Optional(Type.String()),
+    error: Type.Optional(Type.String()),
+    started_at: Type.Optional(Timestamp),
+    duration_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+  },
+  { $id: "WorkflowAgentStatus" },
+);
+export type WorkflowAgentStatus = Static<typeof WorkflowAgentStatus>;
+
+export const SessionWorkflowStatus = Type.Object(
+  {
+    /** Correlates the workflow with the notification announcing its result. */
+    task_id: Type.String(),
+    name: Type.String(),
+    summary: Type.Optional(Type.String()),
+    /** Running, or one of the ways it can end. An open set. */
+    status: Type.String(),
+    started_at: Timestamp,
+    ended_at: Type.Optional(Timestamp),
+    /** Names this run, and is what a transcript read asks for to reach the
+     * agents belonging to it. */
+    run_id: Type.Optional(Type.String()),
+    /** The declared phases. Empty while the run is still going, since a
+     * workflow declares them in the record it writes when it finishes. */
+    phases: Type.Array(WorkflowPhaseStatus),
+    /** From that record once it exists, and from the run's journal before then.
+     * Empty when neither could be read. */
+    agents: Type.Array(WorkflowAgentStatus),
+  },
+  { $id: "SessionWorkflowStatus" },
+);
+export type SessionWorkflowStatus = Static<typeof SessionWorkflowStatus>;
+
+export const SessionBackgroundStatus = Type.Object(
+  {
+    task_id: Type.String(),
+    kind: Type.Union([Type.Literal("monitor"), Type.Literal("bash"), Type.Literal("agent")]),
+    description: Type.String(),
+    /** Running, or one of the ways it can end. An open set. */
+    status: Type.String(),
+    started_at: Timestamp,
+    ended_at: Type.Optional(Timestamp),
+    /** Which kind of agent was spawned. Only for `agent`. */
+    agent_type: Type.Optional(Type.String()),
+  },
+  { $id: "SessionBackgroundStatus" },
+);
+export type SessionBackgroundStatus = Static<typeof SessionBackgroundStatus>;
+
+/** How much context the session's own turns are carrying.
+ *
+ * The raw counts travel and the ceiling is left to the reader: what a model's
+ * limit is can be overridden where the session runs, and the transcript does
+ * not record that, so a limit computed here would be wrong exactly where it
+ * mattered. */
+export const SessionContextUsage = Type.Object(
+  {
+    /** Everything the last turn had to read. */
+    tokens: Type.Integer({ minimum: 0 }),
+    /** As the transcript spells it. */
+    model: Type.String(),
+    /** Absent from transcripts written before the harness recorded it. */
+    effort: Type.Optional(Type.String()),
+    /** The turn this reading was taken from. */
+    observed_at: Timestamp,
+  },
+  { $id: "SessionContextUsage" },
+);
+export type SessionContextUsage = Static<typeof SessionContextUsage>;
+
+/** A teammate of the session, as its transcript shows it. The teammate's own
+ * sense of whether it is busy is not reachable, so the state is an estimate. */
+export const SessionTeammate = Type.Object(
+  {
+    name: Type.String(),
+    /** Whether the spawn was seen to succeed. */
+    spawned: Type.Boolean(),
+    agent_type: Type.Optional(Type.String()),
+    color: Type.Optional(Type.String()),
+    spawned_at: Type.Optional(Timestamp),
+    last_sent_at: Type.Optional(Timestamp),
+    last_received_at: Type.Optional(Timestamp),
+    /** An open set, taken from the latest thing observed. */
+    state: Type.String(),
+    /** Fixed when it was spawned, in the raw spelling. */
+    model: Type.Optional(Type.String()),
+  },
+  { $id: "SessionTeammate" },
+);
+export type SessionTeammate = Static<typeof SessionTeammate>;
+
+/** One agent below the session.
+ *
+ * A node whose parent cannot be located — the parent's transcript has rotated,
+ * or was never seen — is surfaced at the top rather than dropped, so it stays
+ * reachable instead of quietly disappearing. */
+export const AgentTreeNode = Type.Recursive(
+  (self) =>
+    Type.Object({
+      /** Stable across reads, and what a transcript read asks for. */
+      agent_id: Type.String(),
+      /** Present for a teammate: the name it is addressed by, which is its
+       * observable identity even though it resolves to the same transcript. */
+      teammate_name: Type.Optional(Type.String()),
+      /** The role it was spawned as. Absent only when its record is malformed. */
+      agent_type: Type.Optional(Type.String()),
+      /** The spawn's description, verbatim. */
+      description: Type.Optional(Type.String()),
+      color: Type.Optional(Type.String()),
+      model: Type.Optional(Type.String()),
+      team_name: Type.Optional(Type.String()),
+      /** How far below the session it sits; a direct child is zero. */
+      spawn_depth: Type.Integer({ minimum: 0 }),
+      /** Where the node came from: a long-lived teammate, a one-off spawn, or a
+       * member of a workflow run. */
+      kind: Type.Union([
+        Type.Literal("teammate"),
+        Type.Literal("subagent"),
+        Type.Literal("workflow_member"),
+      ]),
+      /** The run it belongs to. Only for a workflow member. */
+      workflow_id: Type.Optional(Type.String()),
+      /** An estimate, and an open set. Direct children reuse what the session's
+       * own fold observed; deeper ones fall back to how recently their
+       * transcript was touched. */
+      state: Type.String(),
+      /** When its transcript was last written to. */
+      last_activity_at: Type.Optional(Timestamp),
+      children: Type.Array(self),
+    }),
+  { $id: "AgentTreeNode" },
+);
+export type AgentTreeNode = Static<typeof AgentTreeNode>;
+
+/** One phase of a workflow run, with the members assigned to it. */
+export const AgentTreeWorkflowPhase = Type.Object(
+  {
+    /** Counting from one, as the workflow declares its phases. */
+    index: Type.Integer({ minimum: 1 }),
+    title: Type.String(),
+    done: Type.Integer({ minimum: 0 }),
+    total: Type.Integer({ minimum: 0 }),
+    members: Type.Array(AgentTreeNode),
+  },
+  { $id: "AgentTreeWorkflowPhase" },
+);
+export type AgentTreeWorkflowPhase = Static<typeof AgentTreeWorkflowPhase>;
+
+/** One workflow run's members, grouped by phase. */
+export const AgentTreeWorkflowGroup = Type.Object(
+  {
+    workflow_id: Type.String(),
+    /** The whole run's progress, across every phase. */
+    done: Type.Integer({ minimum: 0 }),
+    total: Type.Integer({ minimum: 0 }),
+    /** Empty while the run has not declared its phases yet, in which case every
+     * member is unassigned. */
+    phases: Type.Array(AgentTreeWorkflowPhase),
+    /** Members no phase could be found for. Normally empty. */
+    unassigned: Type.Array(AgentTreeNode),
+    /** The newest activity anywhere in the run, for ordering runs against each
+     * other. */
+    last_activity_at: Type.Optional(Timestamp),
+  },
+  { $id: "AgentTreeWorkflowGroup" },
+);
+export type AgentTreeWorkflowGroup = Static<typeof AgentTreeWorkflowGroup>;
+
+/** Everything running below the session, in the three kinds it distinguishes.
+ * A kind with nothing in it is an empty list rather than an absent one. */
+export const AgentTreeGroups = Type.Object(
+  {
+    /** Long-lived members of the session's team, all directly below it. */
+    teammates: Type.Array(AgentTreeNode),
+    /** One-off spawns, nested where one spawned another. */
+    agents: Type.Array(AgentTreeNode),
+    /** One group per workflow run. */
+    workflows: Type.Array(AgentTreeWorkflowGroup),
+  },
+  { $id: "AgentTreeGroups" },
+);
+export type AgentTreeGroups = Static<typeof AgentTreeGroups>;
+
+/** Which kind of transcript record named a file outside the session's root.
+ * Grouping is all this decides; both origins grant the same single-file read. */
+export const ExternalFile = Type.Object(
+  {
+    path: Type.String(),
+    /** A file tool touched it, or it arrived as an attachment. A path named
+     * both ways is reported as whichever came first. */
+    origin: Type.Union([Type.Literal("tool"), Type.Literal("attachment")]),
+  },
+  { $id: "ExternalFile" },
+);
+export type ExternalFile = Static<typeof ExternalFile>;
+
+/** One folder the session's editor workspace names.
+ *
+ * The path is the allowlist key a `workspace` read is checked against; the name
+ * is for display, and falls back to the folder's own basename. Duplicates are
+ * removed, so a folder named twice appears once. */
+export const WorkspaceFolder = Type.Object(
+  {
+    name: Type.String({ minLength: 1 }),
+    /** Absolute, fully resolved, and without a trailing separator. */
+    path: Type.String({ minLength: 1 }),
+  },
+  { $id: "WorkspaceFolder" },
+);
+export type WorkspaceFolder = Static<typeof WorkspaceFolder>;
+
+/** An error the harness wrote in the session's own voice, seen as the last
+ * thing its main context did.
+ *
+ * The harness phrases these as though the agent were speaking — that a prompt
+ * is too long, that a login is needed — but they are the harness reporting a
+ * turn that stopped, and the session sits idle until a person intervenes.
+ *
+ * Only the latest turn counts: a real turn after one of these clears it, so a
+ * session that hit a passing failure and carried on is not flagged. An error
+ * inside a subagent never sets it, since a failed subagent does not stop the
+ * session. */
+export const SessionApiError = Type.Object(
+  {
+    /** The error as written, so a reader can see why the session stopped. May
+     * run to several lines. */
+    text: Type.String(),
+    occurred_at: Timestamp,
+  },
+  { $id: "SessionApiError" },
+);
+export type SessionApiError = Static<typeof SessionApiError>;
+
+/** Everything the instance can fold out of one session's transcript. */
+export const SessionStatusSnapshot = Type.Object(
+  {
+    todos: Type.Array(SessionTodo),
+    workflows: Type.Array(SessionWorkflowStatus),
+    background: Type.Array(SessionBackgroundStatus),
+    teammates: Type.Array(SessionTeammate),
+    agent_tree: AgentTreeGroups,
+    /** Absolute paths outside the session's root that its transcript names.
+     * This is exactly the allowlist an `external` read is checked against — one
+     * list, so nothing can honour one origin and forget another. */
+    external_files: Type.Array(ExternalFile),
+    workspace_folders: Type.Array(WorkspaceFolder),
+    /** Absent when the transcript's last turn carried no reading. */
+    context: Type.Optional(SessionContextUsage),
+    /** Present only while the session is stopped on one. */
+    api_error: Type.Optional(SessionApiError),
+  },
+  { $id: "SessionStatusSnapshot" },
+);
+export type SessionStatusSnapshot = Static<typeof SessionStatusSnapshot>;
+
+/** The `session_status:<sid>` topic. Whole-value: the fold is recomputed and
+ * sent entire whenever something in the transcript changes it. */
+export const SessionStatusFrame = topicFrame(
+  "session_status",
+  Type.Intersect([Type.Object({ sid: Sid }), SessionStatusSnapshot]),
+);

package/src/control/session.ts

@@ -0,0 +1,251 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
+
+/** Ends the OS process behind a session.
+ *
+ * The request names a session, never a pid: the instance resolves sid to pid
+ * itself at the moment it signals, and a pid the caller asserted would be a
+ * weaker basis for killing something than that. */
+export const SessionKillArgs = Type.Object({
+  sid: Sid,
+  /** Escalate to an unconditional kill. The instance never chooses this on its
+   * own, because it forfeits the session's chance to flush its transcript; a
+   * caller asks for it after watching a graceful attempt go unconfirmed. */
+  force: Type.Optional(Type.Boolean()),
+});
+export type SessionKillArgs = Static<typeof SessionKillArgs>;
+
+export const SessionKillResult = Type.Object({
+  /** The process was seen to be gone before the grace period ran out. False is
+   * not a failure: the signal was delivered and the process was still there,
+   * which is what a caller needs to know to decide whether to force. */
+  terminated: Type.Boolean(),
+});
+export type SessionKillResult = Static<typeof SessionKillResult>;
+
+export const SessionKillRequest = request("session_kill", SessionKillArgs);
+export const SessionKillResponse = response("session_kill", SessionKillResult);
+
+/** Retitles a running session by typing its own rename command into the
+ * terminal it lives in.
+ *
+ * Nothing can set a session's title from outside, so this drives the terminal
+ * multiplexer the session runs under. Success means the keystrokes reached the
+ * terminal, not that the session took them — the instance cannot see the TUI's
+ * reaction, and the title it settles on arrives later on the `agents` topic. A
+ * session whose terminal is unknown is refused rather than guessed at. */
+export const SessionRenameArgs = Type.Object({
+  sid: Sid,
+  /** The new title. Surrounding whitespace is trimmed and control characters
+   * are refused: the value is typed, so a newline in it would submit a
+   * half-written command. */
+  title: Type.String({ minLength: 1 }),
+});
+export type SessionRenameArgs = Static<typeof SessionRenameArgs>;
+
+export const SessionRenameResult = Type.Object({
+  /** The terminal handle the keystrokes went to. A host-local handle, so it
+   * travels with the instance that owns it. */
+  terminal_id: Type.String(),
+  instance: InstanceId,
+  /** The trimmed title actually typed, which is what a caller should report
+   * rather than the draft it sent. */
+  title: Type.String(),
+});
+export type SessionRenameResult = Static<typeof SessionRenameResult>;
+
+export const SessionRenameRequest = request("session_rename", SessionRenameArgs);
+export const SessionRenameResponse = response("session_rename", SessionRenameResult);
+
+/** Reads the environment of a session's own process.
+ *
+ * The environment comes from the resolved pid, not from the connection the
+ * session speaks on: the helper that holds that connection carries a different
+ * environment than the session itself. */
+export const SessionEnvReadArgs = Type.Object({ sid: Sid });
+export type SessionEnvReadArgs = Static<typeof SessionEnvReadArgs>;
+
+export const SessionEnvReadResult = Type.Object({
+  /** The pid actually read, after the same reuse check a kill applies. */
+  pid: Type.Integer({ minimum: 1 }),
+  instance: InstanceId,
+  /** Values verbatim, secrets included. Redaction is the caller's decision, so
+   * the contract does not make it for them. */
+  env: Type.Record(Type.String(), Type.String()),
+});
+export type SessionEnvReadResult = Static<typeof SessionEnvReadResult>;
+
+export const SessionEnvReadRequest = request("session_env_read", SessionEnvReadArgs);
+export const SessionEnvReadResponse = response("session_env_read", SessionEnvReadResult);
+
+/** Searches the transcripts of sessions that have run on this instance,
+ * including ones long finished. */
+export const SessionSearchArgs = Type.Object({
+  /** Newline-separated clauses, ORed. Within a clause, whitespace-separated
+   * terms are ANDed across the session's messages. */
+  query: Type.Optional(Type.String()),
+  case_sensitive: Type.Optional(Type.Boolean()),
+  /** Read each clause as a regular expression instead of as literal terms. */
+  regex: Type.Optional(Type.Boolean()),
+  /** Include what people said. Defaults to true. */
+  target_user: Type.Optional(Type.Boolean()),
+  /** Include what sessions said. Defaults to true. */
+  target_agent: Type.Optional(Type.Boolean()),
+  /** Space-separated words matched against the session's working directory. */
+  cwd: Type.Optional(Type.String()),
+  /** Substring of the session id. */
+  sid: Type.Optional(Type.String()),
+  /** Restricts the search to these config homes; ones the instance does not
+   * know are ignored. */
+  config_dirs: Type.Optional(Type.Array(Type.String())),
+  /** Only search transcripts touched within this window. */
+  modified_within_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+});
+export type SessionSearchArgs = Static<typeof SessionSearchArgs>;
+
+export const SessionSearchMatch = Type.Object(
+  {
+    role: Type.Union([Type.Literal("user"), Type.Literal("agent")]),
+    text: Type.String(),
+    said_at: Type.Optional(Timestamp),
+  },
+  { $id: "SessionSearchMatch" },
+);
+export type SessionSearchMatch = Static<typeof SessionSearchMatch>;
+
+/** One session the search matched. Paths and the config home are host values,
+ * so the hit names the instance they belong to — a search answered by several
+ * instances would otherwise mix two hosts' paths in one list. */
+export const SessionSearchHit = Type.Object(
+  {
+    sid: Sid,
+    instance: InstanceId,
+    config_dir: Type.String(),
+    /** Absolute path of the transcript, on the answering instance's host. */
+    file: Type.String(),
+    /** Absent when the transcript never established one. */
+    cwd: Type.Optional(Type.String()),
+    /** `owner/repo`, when the working directory follows the repo layout. */
+    repo: Type.Optional(Type.String()),
+    /** Workspace path within the repository. */
+    ws: Type.Optional(Type.String()),
+    /** The session's own title, when it set one early enough to be read here.
+     * Absent means none was found, never that the session is untitled. */
+    title: Type.Optional(Type.String()),
+    created_at: Timestamp,
+    updated_at: Timestamp,
+    size: Type.Integer({ minimum: 0 }),
+    matches: Type.Array(SessionSearchMatch),
+    /** What the session's last turn ran as, in the transcript's own spelling.
+     * Resuming it should default to these rather than to anything else, so
+     * they are reported unmapped. Independently absent. */
+    model: Type.Optional(Type.String()),
+    effort: Type.Optional(Type.String()),
+  },
+  { $id: "SessionSearchHit" },
+);
+export type SessionSearchHit = Static<typeof SessionSearchHit>;
+
+export const SessionSearchResult = Type.Object({
+  hits: Type.Array(SessionSearchHit),
+  /** The walk stopped at its budget, so the hits are not every match. */
+  truncated: Type.Boolean(),
+});
+export type SessionSearchResult = Static<typeof SessionSearchResult>;
+
+export const SessionSearchRequest = request("session_search", SessionSearchArgs);
+export const SessionSearchResponse = response("session_search", SessionSearchResult);
+
+/** Writes a session's dump to a file on the instance's host and answers with
+ * its path.
+ *
+ * What it adds over reading the transcript is a durable artifact whose path can
+ * be handed to a successor session, instead of a payload that would travel out
+ * through a client and back in again. The caller never supplies a path — the
+ * destination is the instance's own data directory. */
+export const SessionDumpWriteArgs = Type.Object({
+  sid: Sid,
+  /** Inclusive lower bound in time. */
+  since_at: Type.Optional(Timestamp),
+  /** Inclusive lower bound as a transcript record id, which cuts at that
+   * record's position rather than at its clock — records sharing an instant
+   * stay on their own side of the cut. Give one bound or the other, not both. */
+  since_uuid: Type.Optional(Type.String()),
+  until_at: Type.Optional(Timestamp),
+  until_uuid: Type.Optional(Type.String()),
+  /** Leave out the assistant's thinking blocks. */
+  no_thinking: Type.Optional(Type.Boolean()),
+  /** Leave out the machinery of in-process agents. */
+  no_agent: Type.Optional(Type.Boolean()),
+});
+export type SessionDumpWriteArgs = Static<typeof SessionDumpWriteArgs>;
+
+export const SessionDumpWriteResult = Type.Object({
+  /** Absolute path on the writing instance's host. */
+  path: Type.String(),
+  instance: InstanceId,
+  entries: Type.Integer({ minimum: 0 }),
+  bytes: Type.Integer({ minimum: 0 }),
+});
+export type SessionDumpWriteResult = Static<typeof SessionDumpWriteResult>;
+
+export const SessionDumpWriteRequest = request("session_dump_write", SessionDumpWriteArgs);
+export const SessionDumpWriteResponse = response("session_dump_write", SessionDumpWriteResult);
+
+/** Asks where a forked session stopped being a copy of its ancestor.
+ *
+ * Forking duplicates the ancestor's records keeping each record id, so nothing
+ * inside the file marks the seam; finding it means comparing against the
+ * sibling transcripts the instance can already enumerate. */
+export const SessionForkOriginArgs = Type.Object({ sid: Sid });
+export type SessionForkOriginArgs = Static<typeof SessionForkOriginArgs>;
+
+export const ForkOrigin = Type.Object(
+  {
+    /** The session the copied records came from. */
+    sid: Sid,
+    /** Id of the last copied record; the seam sits just after it. */
+    boundary_uuid: Type.String(),
+    /** How many records were copied. */
+    copied: Type.Integer({ minimum: 0 }),
+  },
+  { $id: "ForkOrigin" },
+);
+export type ForkOrigin = Static<typeof ForkOrigin>;
+
+export const SessionForkOriginResult = Type.Object({
+  /** Absent both when the session is no fork and when it is one whose ancestor
+   * file is gone. Nothing left on disk tells those two apart, and neither has a
+   * seam to place. */
+  origin: Type.Optional(ForkOrigin),
+});
+export type SessionForkOriginResult = Static<typeof SessionForkOriginResult>;
+
+export const SessionForkOriginRequest = request("session_fork_origin", SessionForkOriginArgs);
+export const SessionForkOriginResponse = response("session_fork_origin", SessionForkOriginResult);
+
+/** Drops one entry from the list of sessions that were running when the
+ * instance last saw them.
+ *
+ * The removal touches that list alone: the session stays resumable by every
+ * other route, and an instance that later sees it connected records it again.
+ * An unknown session is not an error — two clients pressing the same button is
+ * the ordinary case, and the caller's goal holds either way. */
+export const SessionLastLiveRemoveArgs = Type.Object({ sid: Sid });
+export type SessionLastLiveRemoveArgs = Static<typeof SessionLastLiveRemoveArgs>;
+
+export const SessionLastLiveRemoveResult = Type.Object({
+  /** Whether the entry was there to remove. */
+  removed: Type.Boolean(),
+});
+export type SessionLastLiveRemoveResult = Static<typeof SessionLastLiveRemoveResult>;
+
+export const SessionLastLiveRemoveRequest = request(
+  "session_last_live_remove",
+  SessionLastLiveRemoveArgs,
+);
+export const SessionLastLiveRemoveResponse = response(
+  "session_last_live_remove",
+  SessionLastLiveRemoveResult,
+);

package/src/control/transcript.ts

@@ -0,0 +1,80 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response, topicFrame } from "../envelope.ts";
+import { Sid } from "../identifiers.ts";
+
+/** Reads a slice of a session's transcript.
+ *
+ * The caller never supplies a path — the file is the one the session announced,
+ * or the one an id below it resolves to — so there is no traversal to defend
+ * against. Paging is by byte offset aligned to line boundaries, which is what
+ * lets a transcript of any size be read from its end backwards without ever
+ * scanning it whole or building an index: read the tail, then ask again for
+ * what began before the slice just read.
+ *
+ * The role decides how much is visible rather than whether the call is allowed:
+ * a session reads its own transcript, a person reads any. */
+export const TranscriptReadArgs = Type.Object({
+  sid: Sid,
+  /** Read lines ending at or before this offset. Absent starts at the end. */
+  before: Type.Optional(Type.Integer({ minimum: 0 })),
+  /** How much to return; the instance narrows this to its own limit. */
+  max_bytes: Type.Optional(Type.Integer({ minimum: 1 })),
+  /** Read an agent's transcript instead of the session's own. Validated
+   * strictly, since it names a file. Not to be combined with `teammate`. */
+  agent_id: Type.Optional(Type.String()),
+  /** The workflow run that owns `agent_id`. Absent means the agent hangs
+   * directly below the session. Meaningless on its own. */
+  run_id: Type.Optional(Type.String()),
+  /** Read a teammate's transcript, found by the name it is addressed by — the
+   * name it carries in conversation cannot be used as a filename, so it is
+   * resolved rather than substituted. Not to be combined with `agent_id`. */
+  teammate: Type.Optional(Type.String()),
+});
+export type TranscriptReadArgs = Static<typeof TranscriptReadArgs>;
+
+export const TranscriptReadResult = Type.Object({
+  sid: Sid,
+  /** Whole records as written, oldest first. The reader parses each. */
+  lines: Type.Array(Type.String()),
+  /** Offset of the first line returned. Pass it back as `before` to page
+   * further back; zero means the beginning is included. */
+  start: Type.Integer({ minimum: 0 }),
+  /** Offset just past the last line returned. */
+  end: Type.Integer({ minimum: 0 }),
+  /** The transcript's size now. It grows while the session runs, so this is
+   * also where a later read of what has since been appended starts. */
+  size: Type.Integer({ minimum: 0 }),
+});
+export type TranscriptReadResult = Static<typeof TranscriptReadResult>;
+
+export const TranscriptReadRequest = request("transcript_read", TranscriptReadArgs);
+export const TranscriptReadResponse = response("transcript_read", TranscriptReadResult);
+
+/** The `transcript:<sid>` topic.
+ *
+ * The one topic whose frames are not a whole value: a transcript is appended
+ * to, and sending it entire on every line would be sending the whole file over
+ * and over. The snapshot therefore states only where the file currently ends,
+ * and each frame after it carries what was appended, with the offsets that
+ * place it. Those offsets are the same ones a read pages by, so a client can
+ * stitch what arrives live onto what it read without reading anything twice.
+ *
+ * Only complete lines are sent; a line still being written waits for its end. */
+export const TranscriptFrame = topicFrame(
+  "transcript",
+  Type.Union([
+    Type.Object({
+      sid: Sid,
+      /** Where the transcript ends as the subscription begins. What follows
+       * starts here. */
+      size: Type.Integer({ minimum: 0 }),
+    }),
+    Type.Object({
+      sid: Sid,
+      lines: Type.Array(Type.String()),
+      start: Type.Integer({ minimum: 0 }),
+      end: Type.Integer({ minimum: 0 }),
+      size: Type.Integer({ minimum: 0 }),
+    }),
+  ]),
+);