@openscout/protocol 0.2.64 → 0.2.83

package/src/session-display-state.ts

@@ -0,0 +1,202 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export type ScoutSessionDisplayPhase =
+  | "idle"
+  | "running"
+  | "waiting"
+  | "failed"
+  | "completed";
+
+export interface ScoutDisplayMessage {
+  id: ScoutId;
+  role: "user" | "assistant" | "system";
+  text?: string;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface ScoutDisplayTool {
+  id: ScoutId;
+  name: string;
+  status: "running" | "completed" | "failed";
+  summary?: string;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface ScoutDisplayAttentionItem {
+  id: ScoutId;
+  kind: "question" | "approval" | "permission" | "waiting";
+  title: string;
+  summary?: string;
+  sourceRef?: string;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface ScoutDisplaySubagent {
+  id: ScoutId;
+  agentType?: string;
+  title: string;
+  status: "running" | "completed" | "failed";
+  summary?: string;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface ScoutDisplayTask {
+  id: ScoutId;
+  title: string;
+  status: "pending" | "in_progress" | "completed";
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface ScoutDisplayUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  source?: "provider_exact" | "tokenizer_estimate" | "char_heuristic" | "manual_estimate";
+}
+
+export interface ScoutDisplayTurn {
+  id: ScoutId;
+  status: "streaming" | "completed" | "interrupted" | "error";
+  startedAt: number;
+  endedAt?: number;
+  blockCount: number;
+  messageCount: number;
+  toolCount: number;
+  attentionCount: number;
+  summary?: string;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export interface ScoutSessionDisplayState {
+  sessionId: ScoutId;
+  phase: ScoutSessionDisplayPhase;
+  currentMessage: ScoutDisplayMessage | null;
+  activeTools: Record<ScoutId, ScoutDisplayTool>;
+  attention: Record<ScoutId, ScoutDisplayAttentionItem>;
+  activeSubagents: Record<ScoutId, ScoutDisplaySubagent>;
+  turns: ScoutDisplayTurn[];
+  tasks: ScoutDisplayTask[];
+  usage?: ScoutDisplayUsage;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}
+
+export type ScoutSessionDisplayEvent =
+  | { type: "phase_changed"; phase: ScoutSessionDisplayPhase; at: number }
+  | { type: "message_updated"; message: ScoutDisplayMessage; at?: number }
+  | { type: "tool_started"; tool: ScoutDisplayTool; at?: number }
+  | { type: "tool_finished"; toolId: ScoutId; failed?: boolean; summary?: string; at: number }
+  | { type: "attention_opened"; item: ScoutDisplayAttentionItem; at?: number }
+  | { type: "attention_closed"; itemId: ScoutId; at: number }
+  | { type: "subagent_started"; subagent: ScoutDisplaySubagent; at?: number }
+  | { type: "subagent_finished"; subagentId: ScoutId; failed?: boolean; summary?: string; at: number }
+  | { type: "turns_snapshot"; turns: ScoutDisplayTurn[]; at: number }
+  | { type: "tasks_snapshot"; tasks: ScoutDisplayTask[]; at: number }
+  | { type: "usage_updated"; usage: ScoutDisplayUsage; at: number }
+  | { type: "reset_thread"; at: number };
+
+export function createScoutSessionDisplayState(input: {
+  sessionId: ScoutId;
+  now?: number;
+}): ScoutSessionDisplayState {
+  return {
+    sessionId: input.sessionId,
+    phase: "idle",
+    currentMessage: null,
+    activeTools: {},
+    attention: {},
+    activeSubagents: {},
+    turns: [],
+    tasks: [],
+    updatedAt: input.now ?? 0,
+  };
+}
+
+export function reduceScoutSessionDisplayState(
+  state: ScoutSessionDisplayState,
+  event: ScoutSessionDisplayEvent,
+): ScoutSessionDisplayState {
+  switch (event.type) {
+    case "phase_changed":
+      return { ...state, phase: event.phase, updatedAt: event.at };
+    case "message_updated":
+      return { ...state, currentMessage: event.message, updatedAt: event.at ?? event.message.updatedAt };
+    case "tool_started":
+      return {
+        ...state,
+        activeTools: { ...state.activeTools, [event.tool.id]: event.tool },
+        updatedAt: event.at ?? event.tool.updatedAt,
+      };
+    case "tool_finished": {
+      const current = state.activeTools[event.toolId];
+      if (!current) return { ...state, updatedAt: event.at };
+      return {
+        ...state,
+        activeTools: {
+          ...state.activeTools,
+          [event.toolId]: {
+            ...current,
+            status: event.failed ? "failed" : "completed",
+            summary: event.summary ?? current.summary,
+            updatedAt: event.at,
+          },
+        },
+        updatedAt: event.at,
+      };
+    }
+    case "attention_opened":
+      return {
+        ...state,
+        phase: state.phase === "idle" ? "waiting" : state.phase,
+        attention: { ...state.attention, [event.item.id]: event.item },
+        updatedAt: event.at ?? event.item.updatedAt,
+      };
+    case "attention_closed": {
+      const next = { ...state.attention };
+      delete next[event.itemId];
+      return {
+        ...state,
+        attention: next,
+        phase: state.phase === "waiting" && Object.keys(next).length === 0 ? "idle" : state.phase,
+        updatedAt: event.at,
+      };
+    }
+    case "subagent_started":
+      return {
+        ...state,
+        activeSubagents: { ...state.activeSubagents, [event.subagent.id]: event.subagent },
+        updatedAt: event.at ?? event.subagent.updatedAt,
+      };
+    case "subagent_finished": {
+      const current = state.activeSubagents[event.subagentId];
+      if (!current) return { ...state, updatedAt: event.at };
+      return {
+        ...state,
+        activeSubagents: {
+          ...state.activeSubagents,
+          [event.subagentId]: {
+            ...current,
+            status: event.failed ? "failed" : "completed",
+            summary: event.summary ?? current.summary,
+            updatedAt: event.at,
+          },
+        },
+        updatedAt: event.at,
+      };
+    }
+    case "turns_snapshot":
+      return { ...state, turns: [...event.turns], updatedAt: event.at };
+    case "tasks_snapshot":
+      return { ...state, tasks: [...event.tasks], updatedAt: event.at };
+    case "usage_updated":
+      return { ...state, usage: event.usage, updatedAt: event.at };
+    case "reset_thread":
+      return createScoutSessionDisplayState({ sessionId: state.sessionId, now: event.at });
+  }
+}

package/src/terminal-host-topology.ts

@@ -0,0 +1,132 @@
+/**
+ * Herdr session topology, projected for Scout clients.
+ *
+ * Herdr owns the real thing: workspaces, tabs, panes, layouts, and the agent
+ * records inside them. This type is a READ-ONLY PROJECTION of that topology —
+ * what Scout's terminals view needs to represent a herdr session faithfully
+ * without becoming a second layout manager. Layout coordinates and split
+ * ratios are included read-only so a client can render the arrangement
+ * faithfully; there are deliberately no mutation verbs here: if a client wants
+ * to change the topology, the handoff is the herdr client itself (`herdr
+ * session attach`, `herdr agent focus`), not a Scout control.
+ *
+ * The server builds this from `herdr --session <n> workspace list`,
+ * `tab list`, and `pane list` JSON, plus the per-tab layout geometry from
+ * `herdr --session <n> api snapshot`. A session whose server is stopped
+ * projects as `{ running: false, workspaces: [] }` — an ordinary state, not
+ * an error.
+ */
+
+/** Agent state as herdr reports it, never as Scout infers it. */
+export type HerdrAgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+
+/**
+ * The harness-native session reference herdr reports for a pane (e.g. a Claude
+ * session id). Opaque to Scout: carried so clients can correlate, never parsed.
+ */
+export type HerdrAgentSessionRef = {
+  agent: string;
+  kind: string;
+  source: string;
+  value: string;
+};
+
+export type HerdrPaneProjection = {
+  paneId: string;
+  /** Herdr's stable terminal id; `herdr agent <verb>` accepts it as a target. */
+  terminalId: string | null;
+  tabId: string;
+  workspaceId: string;
+  label: string | null;
+  /** Detected/reported agent label, e.g. "claude". Null for plain shells. */
+  agent: string | null;
+  agentStatus: HerdrAgentStatus;
+  agentSession: HerdrAgentSessionRef | null;
+  cwd: string | null;
+  foregroundCwd: string | null;
+  focused: boolean;
+  /**
+   * Scrollback position as herdr reports it. `maxOffsetFromBottom` is the
+   * pane's backlog depth — the cheapest activity signal the projection has.
+   * Null when the host does not report scroll state (older herdr).
+   */
+  scroll: HerdrPaneScroll | null;
+};
+
+export type HerdrPaneScroll = {
+  maxOffsetFromBottom: number;
+  offsetFromBottom: number;
+  viewportRows: number;
+};
+
+/**
+ * Layout geometry for one tab, read from `herdr api snapshot`. Rects are
+ * absolute terminal cell coordinates as herdr reports them (the area includes
+ * herdr's chrome offset); clients normalize against `area` to render a
+ * proportional replica.
+ */
+export type HerdrLayoutRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type HerdrLayoutPane = {
+  paneId: string;
+  focused: boolean;
+  rect: HerdrLayoutRect;
+};
+
+export type HerdrLayoutSplit = {
+  id: string | null;
+  direction: "right" | "down" | null;
+  ratio: number | null;
+  rect: HerdrLayoutRect | null;
+};
+
+export type HerdrTabLayout = {
+  tabId: string;
+  workspaceId: string;
+  area: HerdrLayoutRect;
+  focusedPaneId: string | null;
+  zoomed: boolean;
+  panes: HerdrLayoutPane[];
+  splits: HerdrLayoutSplit[];
+};
+
+export type HerdrTabProjection = {
+  tabId: string;
+  workspaceId: string;
+  label: string | null;
+  number: number | null;
+  focused: boolean;
+  agentStatus: HerdrAgentStatus;
+  panes: HerdrPaneProjection[];
+  /** Per-tab pane geometry; null when the snapshot did not cover this tab. */
+  layout: HerdrTabLayout | null;
+};
+
+export type HerdrWorkspaceProjection = {
+  workspaceId: string;
+  label: string | null;
+  number: number | null;
+  focused: boolean;
+  activeTabId: string | null;
+  agentStatus: HerdrAgentStatus;
+  tabs: HerdrTabProjection[];
+};
+
+export type HerdrSessionTopology = {
+  /** Herdr session name, e.g. "openscout". */
+  session: string;
+  /** Whether the session's herdr server answered. */
+  running: boolean;
+  workspaces: HerdrWorkspaceProjection[];
+  /** Server wall-clock when the projection was observed. */
+  observedAt: number;
+};
+
+export function emptyHerdrSessionTopology(session: string, running: boolean): HerdrSessionTopology {
+  return { session, running, workspaces: [], observedAt: Date.now() };
+}

package/src/terminal-sessions.ts

@@ -0,0 +1,187 @@
+/**
+ * Terminal session registry.
+ *
+ * The durable noun is a HARNESS SESSION — a stable agent session identified by
+ * its harness-native source id and resumable via a resume command. A harness
+ * session is *materialized* through one or more disposable TERMINAL SURFACES
+ * (tmux, zellij, future ssh/host-control). Backends are interchangeable: the
+ * source session id is the stable key; the surface is the throwaway shell.
+ *
+ * This module defines the shared contract used by `scout session intake`
+ * (which writes the record), the runtime store (which persists it), the
+ * web/runtime APIs (which list it + materialize surfaces), and the app
+ * terminal UI (which reads it to attach/observe/take over).
+ *
+ * Terminal scrollback is never imported as Scout messages — a surface is a
+ * relay target, not a message source.
+ */
+
+import { formatTerminalSurfaceId, parseTerminalSurfaceId } from "./terminal-surface-id.js";
+import type { TerminalHostId, TerminalSurfaceId } from "./terminal-surface-id.js";
+
+/** Lifecycle of a single materialized surface. */
+export type TerminalSurfaceState = "live" | "detached" | "exited";
+
+/**
+ * Relay descriptor for one surface.
+ *
+ * The per-backend optional fields are legacy: they are what a relay built
+ * before host adapters expects to find, and they are only populated for the
+ * hosts that predate the registry. A new host adds an adapter, not a field —
+ * `backend` plus `sessionName` is the whole contract.
+ */
+export type TerminalSurfaceRelay = {
+  backend: TerminalHostId;
+  sessionName: string;
+  tmuxSession?: string;
+  zellijSession?: string;
+  zellijPaneId?: string;
+};
+
+/** One disposable terminal surface a harness session has been materialized through. */
+export type TerminalSurface = {
+  /**
+   * Opaque durable handle for this surface. Absent on records written before
+   * surface ids existed; derive one with `terminalSurfaceIdForSurface`.
+   */
+  surfaceId?: TerminalSurfaceId;
+  /** Host that owns the surface. Registered adapters may add hosts the union does not name. */
+  backend: TerminalHostId;
+  /** Backend session name (e.g. tmux target, zellij session). Secondary metadata. */
+  sessionName: string;
+  paneId: string | null;
+  attachCommand: string[];
+  observeCommand: string[] | null;
+  relay: TerminalSurfaceRelay;
+  /** Lifecycle state; absent means unknown / not yet observed. */
+  state?: TerminalSurfaceState;
+  /**
+   * Zellij requires a short socket dir on macOS (the default $TMPDIR exceeds the
+   * Unix socket-path length limit). Any relay attaching to a Scout-created zellij
+   * surface must preserve this, or it lands in a different server namespace.
+   */
+  socketDir?: string;
+};
+
+/**
+ * Durable registry record: a stable harness session plus the disposable
+ * terminal surfaces it owns. Re-materializing in another backend appends a
+ * surface; it never changes the record identity.
+ */
+export type TerminalSessionRecord = {
+  /** Stable Scout record id (derived from harness + sourceSessionId by default). */
+  id: string;
+  harness: string;
+  /** Harness-native session id — the stable identity across backends. */
+  sourceSessionId: string;
+  cwd: string;
+  resumeCommand: string;
+  /**
+   * Where the record came from. `registry` records are Scout-owned harness
+   * sessions with a real harness and resume command; `discovered` records are
+   * live multiplexer sessions observed on the host, for which both are unknown
+   * and must be left empty rather than filled with the backend and attach argv.
+   * Absent means `registry`.
+   */
+  origin?: "registry" | "discovered";
+  surfaces: TerminalSurface[];
+  createdAt: number;
+  updatedAt: number;
+  metadata?: Record<string, unknown>;
+};
+
+/** Upsert input for a registry record. Timestamps + id are assigned by the store. */
+export type TerminalSessionRecordInput = {
+  /** Optional explicit id; defaults to a deterministic id from harness + sourceSessionId. */
+  id?: string;
+  harness: string;
+  sourceSessionId: string;
+  cwd: string;
+  resumeCommand: string;
+  surfaces?: TerminalSurface[];
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * The durable handle for a surface. Prefers the stored id and derives the same
+ * value from the surface's address otherwise, so a record written before
+ * surface ids existed resolves to the id it would be issued today.
+ */
+export function terminalSurfaceIdForSurface(
+  surface: Pick<TerminalSurface, "surfaceId" | "backend" | "sessionName" | "paneId">,
+  options: { nodeId?: string | null } = {},
+): TerminalSurfaceId {
+  if (surface.surfaceId) return surface.surfaceId;
+  return formatTerminalSurfaceId({
+    backend: surface.backend,
+    hostSession: surface.sessionName,
+    paneId: surface.paneId,
+    nodeId: options.nodeId ?? null,
+  });
+}
+
+/** Where a match is being evaluated, for the parts of matching that are node-scoped. */
+export type TerminalSurfaceMatchScope = {
+  /**
+   * This host's own Scout node id, when the caller knows it. A surface observed
+   * with no node in its id was observed HERE, so this is the only node whose
+   * handles may claim it.
+   */
+  localNodeId?: string | null;
+};
+
+/**
+ * Whether a handle scoped to `handleNodeId` may address a surface scoped to
+ * `surfaceNodeId`.
+ *
+ * Three cases, and the third is the one a review reproduced:
+ *
+ * - Both sides name a node: they must name the same one. Without this a handle
+ *   for one node matched an identically named session on another.
+ * - The handle names none: it is a legacy key, which names no machine and must
+ *   keep matching whatever it finds.
+ * - The handle names a node and the OBSERVATION does not. A node-less
+ *   observation is by definition local — it is a session this host just listed
+ *   — so only the local node's handle can be the one it belongs to. Letting any
+ *   node-scoped handle match it meant handles for `node-a` and `node-b` both
+ *   bound to one discovered local session, and both workspaces reported it
+ *   Running: one session proving two machines live. A foreign handle never
+ *   matches, and when this host does not know its own node id it cannot prove
+ *   the handle is local either, so it does not claim it.
+ */
+export function terminalSurfaceNodeScopeMatches(input: {
+  handleNodeId: string | null;
+  surfaceNodeId: string | null;
+  localNodeId?: string | null;
+}): boolean {
+  if (input.handleNodeId === null) return true;
+  if (input.surfaceNodeId !== null) return input.handleNodeId === input.surfaceNodeId;
+  const localNodeId = input.localNodeId?.trim() || null;
+  return localNodeId !== null && input.handleNodeId === localNodeId;
+}
+
+/** The node a surface belongs to, which lives inside its own opaque id. */
+export function terminalSurfaceNodeId(
+  surface: Pick<TerminalSurface, "surfaceId">,
+): string | null {
+  return parseTerminalSurfaceId(surface.surfaceId)?.nodeId ?? null;
+}
+
+/** True when a handle addresses this surface, in either the opaque or legacy form. */
+export function terminalSurfaceMatchesId(
+  surface: Pick<TerminalSurface, "surfaceId" | "backend" | "sessionName" | "paneId">,
+  handle: string | null | undefined,
+  scope: TerminalSurfaceMatchScope = {},
+): boolean {
+  const address = parseTerminalSurfaceId(handle);
+  if (!address) return false;
+  if (address.backend !== surface.backend || address.hostSession !== surface.sessionName) return false;
+  // A legacy key carries no pane, so it matches any pane on the session; an
+  // opaque id that names a pane must match it exactly.
+  if (address.paneId !== null && address.paneId !== (surface.paneId ?? null)) return false;
+  return terminalSurfaceNodeScopeMatches({
+    handleNodeId: address.nodeId ?? null,
+    surfaceNodeId: terminalSurfaceNodeId(surface),
+    localNodeId: scope.localNodeId,
+  });
+}