@openscout/protocol 0.2.109 → 0.3.0

package/src/runtime-execution.ts

@@ -7,6 +7,8 @@ import {
   type ScoutOwnedRuntimeCatalog,
   type ScoutOwnedRuntimeHarness,
   type ScoutReasoningEffort,
+  type ScoutRuntimeHarnessPresentation,
+  type ScoutRuntimeModelPresentation,
 } from "./runtime-catalog-contract.js";
 export * from "./runtime-catalog-contract.js";
 
@@ -46,6 +48,15 @@ export function isScoutRuntimeHarnessListed(
   return entry?.enabled === true && entry.listed !== false;
 }
 
+/** A harness accepts a model dimension iff the owned catalog lists at least one enabled model for it. */
+export function isModelSelectableHarness(
+  harness: string,
+  catalog: ScoutOwnedRuntimeCatalog = SCOUT_RUNTIME_CATALOG,
+): boolean {
+  const entry = scoutRuntimeHarness(harness, catalog);
+  return entry?.enabled === true && entry.models.some((model) => model.enabled);
+}
+
 export function scoutRuntimeDefaultHarness(
   catalog: ScoutOwnedRuntimeCatalog = SCOUT_RUNTIME_CATALOG,
 ): ScoutLaunchableHarness | null {
@@ -147,6 +158,24 @@ export interface ScoutRuntimeDimensionResolution {
   drift: ScoutRuntimeDriftState;
 }
 
+/**
+ * Which Codex app-server executed the session: one Scout spawned for itself,
+ * or an already-running server Scout attached to over its control socket.
+ * Harness-owned evidence from `initialize` and `codex app-server daemon version`.
+ */
+export interface ScoutCodexAppServerIdentity {
+  connection: "spawned" | "attached";
+  socketPath: string | null;
+  pid: number | null;
+  userAgent: string | null;
+  appServerVersion: string | null;
+  codexHome: string | null;
+  platformOs?: string | null;
+  /** Scout features that do not apply to this server (e.g. scout_mcp_injection). */
+  capabilityGaps: string[];
+  connectedAt: number;
+}
+
 /**
  * Durable execution truth for one concrete session. `requested` is caller
  * intent, `resolved` is the spawn value after the launch ladder, and
@@ -160,6 +189,8 @@ export interface ScoutExecutionResolution {
   sessionId?: string;
   resolvedAt?: number;
   observedAt?: number;
+  /** Present for Codex sessions once the app-server has been reached. */
+  codexAppServer?: ScoutCodexAppServerIdentity;
 }
 
 export interface ScoutRuntimeModelOption {
@@ -170,6 +201,9 @@ export interface ScoutRuntimeModelOption {
   source: "catalog" | "observed" | "configured" | "default";
   family?: string;
   version?: string;
+  /** True when the owned catalog marks this model as its harness's default. */
+  isDefault?: boolean;
+  presentation?: ScoutRuntimeModelPresentation;
 }
 
 export interface ScoutRuntimeEffortOption {
@@ -195,6 +229,7 @@ export interface ScoutRuntimeHarnessOption {
   state?: "ready" | "configured" | "installed" | "missing" | null;
   ready?: boolean | null;
   detail?: string | null;
+  presentation?: ScoutRuntimeHarnessPresentation;
 }
 
 export interface ScoutRuntimeCapabilityCatalog {
@@ -238,6 +273,8 @@ export function scoutRuntimeModelCatalog(
         source: "default",
         ...(model.family ? { family: model.family } : {}),
         ...(model.version ? { version: model.version } : {}),
+        ...(model.default === true ? { isDefault: true } : {}),
+        ...(model.presentation ? { presentation: model.presentation } : {}),
       });
     }
   }
@@ -310,6 +347,28 @@ export type ScoutRuntimeModelNormalization =
   | { ok: true; requested: string; resolved: string }
   | { ok: false; requested: string; error: string; candidates?: string[] };
 
+const CLAUDE_FAMILY_ALIASES: Record<string, string> = {
+  fable: "Fable",
+  opus: "Opus",
+  sonnet: "Sonnet",
+  haiku: "Haiku",
+};
+
+/**
+ * The newest enabled model in a catalog family: the harness default when it is
+ * in the family, otherwise the first in catalog order (newest first). A family
+ * alias like `opus` follows the catalog instead of pinning a release.
+ */
+export function scoutRuntimeLatestModelInFamily(
+  harness: string,
+  family: string,
+  catalog: ScoutOwnedRuntimeCatalog = SCOUT_RUNTIME_CATALOG,
+): string | undefined {
+  const models = (scoutRuntimeHarness(harness, catalog)?.models ?? [])
+    .filter((model) => model.enabled && model.family === family);
+  return (models.find((model) => model.default) ?? models[0])?.id;
+}
+
 /** Canonical model aliases shared by every request boundary and spawn path. */
 export function normalizeScoutRuntimeModel(
   harness: string,
@@ -334,13 +393,9 @@ export function normalizeScoutRuntimeModel(
     return { ok: true, requested, resolved: requested };
   }
   if (normalizedHarness === "claude") {
-    const aliases: Record<string, string> = {
-      fable: "claude-fable-5",
-      opus: "claude-opus-5",
-      sonnet: "claude-sonnet-4-6",
-      haiku: "claude-haiku-4-5",
-    };
-    return { ok: true, requested, resolved: aliases[lower] ?? requested };
+    const family = CLAUDE_FAMILY_ALIASES[lower];
+    const resolved = family ? scoutRuntimeLatestModelInFamily("claude", family) : undefined;
+    return { ok: true, requested, resolved: resolved ?? requested };
   }
   return { ok: true, requested, resolved: requested };
 }
@@ -485,6 +540,7 @@ export function createScoutExecutionResolution(input: {
 export function validateScoutRuntimeTuple(
   input: ScoutRuntimeTuple,
   catalog?: Pick<ScoutRuntimeCapabilityCatalog, "models" | "efforts">,
+  ownedCatalog: ScoutOwnedRuntimeCatalog = SCOUT_RUNTIME_CATALOG,
 ): ScoutRuntimeTupleIssue[] {
   const rawHarness = input.harness?.trim().toLowerCase();
   const harness = rawHarness === "oc" ? "opencode" : rawHarness;
@@ -492,11 +548,14 @@ export function validateScoutRuntimeTuple(
   const effortRaw = input.reasoningEffort?.trim();
   const issues: ScoutRuntimeTupleIssue[] = [];
 
-  if (harness && !isScoutLaunchableHarness(harness)) {
+  // Harness membership and model selectability come from the owned catalog —
+  // the live broker snapshot when one is supplied, the bundled default
+  // otherwise — never a hand-maintained list.
+  if (harness && !ownedCatalog.harnesses.some((entry) => entry.id === harness)) {
     issues.push({
       code: "unsupported_harness",
       dimension: "harness",
-      message: `unsupported harness "${input.harness}"; expected one of: ${SCOUT_LAUNCHABLE_HARNESSES.join(", ")}`,
+      message: `unsupported harness "${input.harness}"; expected one of: ${ownedCatalog.harnesses.map((entry) => entry.id).join(", ")}`,
     });
     return issues;
   }
@@ -512,7 +571,7 @@ export function validateScoutRuntimeTuple(
     const catalogEffort = catalog?.efforts.find((candidate) => candidate.id === effort);
     let supported = catalogEffort
       ? catalogEffort.harnesses.includes(harness as ScoutLaunchableHarness)
-      : (scoutRuntimeReasoningEfforts(harness, model) ?? []).includes(effort);
+      : (scoutRuntimeReasoningEfforts(harness, model, ownedCatalog) ?? []).includes(effort);
     if (supported && catalogEffort?.models?.length && model) {
       const harnessModels = new Set(
         catalog?.models
@@ -535,12 +594,7 @@ export function validateScoutRuntimeTuple(
     }
   }
 
-  const modelSelectableHarness = harness === "claude"
-    || harness === "codex"
-    || harness === "grok"
-    || harness === "grok-acp"
-    || harness === "opencode";
-  if (model && harness && !modelSelectableHarness) {
+  if (model && harness && !isModelSelectableHarness(harness, ownedCatalog)) {
     issues.push({
       code: "unsupported_model_dimension",
       dimension: "model",

package/src/scout-agent-card.ts

@@ -42,6 +42,8 @@ export interface ScoutReturnAddress {
   nodeId?: ScoutId;
   projectRoot?: string;
   sessionId?: string;
+  /** Copyable `sess.<token>@<host>` for the exact session replies should continue. */
+  sessionAddress?: string;
   metadata?: MetadataMap;
 }
 
@@ -125,6 +127,9 @@ export function buildScoutReturnAddress(input: ScoutReturnAddress): ScoutReturnA
   if (input.sessionId?.trim()) {
     next.sessionId = input.sessionId.trim();
   }
+  if (input.sessionAddress?.trim()) {
+    next.sessionAddress = input.sessionAddress.trim();
+  }
   if (input.metadata && Object.keys(input.metadata).length > 0) {
     next.metadata = input.metadata;
   }

package/src/scout-composer.ts

@@ -1,6 +1,7 @@
 import { parseAgentIdentity } from "./agent-identity.js";
 import { AGENT_HARNESSES, type AgentHarness } from "./actors.js";
 import type { ScoutRouteTarget } from "./scout-dispatch.js";
+import { parseScoutSessionHostAddress } from "./session-handle.js";
 
 export const SCOUT_COMPOSER_ROUTE_OPERATOR = ">>" as const;
 export const SCOUT_TARGET_HANDLE_SHORTHAND = "⌖" as const;
@@ -100,12 +101,30 @@ function parseRouteAliasTarget(rawValue: string): ScoutRouteTarget | null {
   return { kind: "route_alias", alias, value: `alias:${alias}` };
 }
 
+function parseSessionHostAddressTarget(value: string): ScoutRouteTarget | null {
+  const address = parseScoutSessionHostAddress(value);
+  if (!address) {
+    return null;
+  }
+  return {
+    kind: "session_id",
+    sessionId: address.handle,
+    host: address.host,
+    value: `session:${address.handle}@${address.host}`,
+  };
+}
+
 function parseSessionRouteTarget(rawValue: string): ScoutRouteTarget | null {
   const value = rawValue.replace(/^@+/, "");
   if (!isRouteValue(value)) {
     return null;
   }
 
+  const hostAddress = parseSessionHostAddressTarget(value);
+  if (hostAddress) {
+    return hostAddress;
+  }
+
   const harnessSeparator = value.indexOf(":");
   if (harnessSeparator > 0) {
     const maybeHarness = value.slice(0, harnessSeparator) as AgentHarness;
@@ -181,6 +200,13 @@ export function parseScoutComposerRouteTarget(value: string): ScoutRouteTarget |
     }
   }
 
+  // Bare `sess.<token>@<host>` — the copyable session address. Agent labels
+  // never contain `@`, so this cannot shadow an existing selector.
+  const hostAddress = parseSessionHostAddressTarget(token);
+  if (hostAddress) {
+    return hostAddress;
+  }
+
   return parseAgentLabelTarget(token);
 }
 

package/src/scout-delivery.ts

@@ -34,7 +34,7 @@ export type ScoutOperatorSignalKind = "notify" | "consult" | "need";
  *             do without it (`defaultAction`). Silence is a valid answer.
  *   need    — the agent cannot proceed. Silence is NOT an answer, so this is
  *             the only kind that is blocking, and the only one that raises the
- *             operator's needs-you surface.
+ *             operator's requests surface.
  *
  * `notify` and `consult` stay conversational side effects: they never create a
  * flight and never imply the agent is waiting. `need` is the exception on
@@ -142,6 +142,8 @@ export interface ScoutDeliveryReceipt {
   requesterNodeId: ScoutId;
   targetAgentId?: ScoutId;
   targetSessionId?: ScoutId;
+  /** Copyable `sess.<token>@<host>` for exact continuation of the target session. */
+  targetSessionAddress?: string;
   targetLabel?: string;
   /** Provisional routable pointer (e.g. project-chopin) when target is cardless. */
   sessionAlias?: string;

package/src/scout-dispatch.ts

@@ -48,6 +48,17 @@ export type ScoutRouteTarget =
       /** Canonical writes use a broker `sess.*` handle. Native ids are legacy resolver inputs only. */
       sessionId: ScoutId;
       harness?: AgentHarness;
+      /**
+       * Opt-in for native ids: if the session is live outside Scout (e.g. open
+       * in the operator's terminal), continue it as a new Scout-owned fork
+       * rather than refusing. The receipt's targetSessionId names the fork.
+       */
+      forkIfLive?: boolean;
+      /**
+       * Host part of a `sess.<token>@<host>` address: the broker authority that
+       * owns the session. Scopes resolution to that host; it never widens it.
+       */
+      host?: string;
       value?: string;
     }
   | { kind: "binding_ref"; ref: string; value?: string }
@@ -108,6 +119,8 @@ export interface ScoutDispatchEnvelope {
   dispatchedAt: number;
   dispatcherNodeId: ScoutId;
   diagnosticCode?: RouteAliasDiagnosticCode;
+  /** Exact-session wake refusal code (session_unknown, session_live_unbound, …). */
+  sessionWakeReason?: string;
   aliasResolution?: RouteAliasResolutionProof;
 }
 

package/src/session-handle.ts

@@ -35,3 +35,91 @@ export function parseScoutSessionAddress(
 export function formatScoutSessionAddress(handle: ScoutSessionHandle): string {
   return `${SCOUT_SESSION_ADDRESS_PREFIX}${handle}`;
 }
+
+/**
+ * Email-like session address: `sess.<token>@<host>`.
+ *
+ * The local part is the exact harness conversation (the opaque broker handle);
+ * the domain is the stable broker authority that owns it — a mesh node's
+ * stable qualifier, never a network address. It is derived for every known
+ * session, so first contact needs no agent card. Addressability says nothing
+ * about reachability: resolving an address may still report the session as
+ * offline, ended, or on a host this broker cannot reach.
+ *
+ * `session:sess.<token>@<host>` is the typed form; a bare `sess.<token>@<host>`
+ * is accepted wherever a route target is. Only canonical `sess.*` handles take
+ * a host; legacy native session ids keep their existing grammar untouched.
+ */
+export interface ScoutSessionHostAddress {
+  handle: ScoutSessionHandle;
+  host: string;
+}
+
+/** Normalized host label: lowercase DNS-ish label, no `.local`, no trailing dot. */
+export function normalizeScoutSessionHost(value: string | null | undefined): string {
+  if (typeof value !== "string") return "";
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/\.+$/, "")
+    .replace(/\.local$/, "")
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-.]+|[-.]+$/g, "");
+}
+
+const SCOUT_SESSION_HOST_PATTERN = /^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/;
+
+export function parseScoutSessionHostAddress(
+  value: string | null | undefined,
+): ScoutSessionHostAddress | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  const bare = trimmed.startsWith(SCOUT_SESSION_ADDRESS_PREFIX)
+    ? trimmed.slice(SCOUT_SESSION_ADDRESS_PREFIX.length)
+    : trimmed;
+  const at = bare.indexOf("@");
+  if (at <= 0 || at !== bare.lastIndexOf("@")) return null;
+  const handle = bare.slice(0, at);
+  const host = normalizeScoutSessionHost(bare.slice(at + 1));
+  if (!isScoutSessionHandle(handle) || !SCOUT_SESSION_HOST_PATTERN.test(host)) return null;
+  return { handle, host };
+}
+
+export function formatScoutSessionHostAddress(address: ScoutSessionHostAddress): string {
+  return `${address.handle}@${normalizeScoutSessionHost(address.host)}`;
+}
+
+/** The node facts a host label is derived from (a subset of NodeDefinition). */
+export interface ScoutSessionHostNode {
+  id: string;
+  meshId?: string;
+  name?: string;
+  hostName?: string;
+}
+
+/**
+ * Derive the stable host label for a mesh node. Node ids are minted as
+ * `<stable-qualifier>-<mesh>`, so stripping the mesh suffix yields the
+ * persisted machine qualifier; display names are a fallback only.
+ */
+export function scoutSessionHostForNode(node: ScoutSessionHostNode): string {
+  const id = normalizeScoutSessionHost(node.id);
+  const mesh = normalizeScoutSessionHost(node.meshId);
+  if (mesh && id.endsWith(`-${mesh}`) && id.length > mesh.length + 1) {
+    return id.slice(0, -(mesh.length + 1));
+  }
+  return normalizeScoutSessionHost(node.name) || normalizeScoutSessionHost(node.hostName) || id;
+}
+
+/** True when `host` names this node by its derived label, id, name, or host name. */
+export function scoutNodeMatchesSessionHost(node: ScoutSessionHostNode, host: string): boolean {
+  const wanted = normalizeScoutSessionHost(host);
+  if (!wanted) return false;
+  return [
+    scoutSessionHostForNode(node),
+    normalizeScoutSessionHost(node.id),
+    normalizeScoutSessionHost(node.name),
+    normalizeScoutSessionHost(node.hostName),
+  ].includes(wanted);
+}

package/src/terminal-host-topology.ts

@@ -11,7 +11,8 @@
  * 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
+ * `tab list`, and `pane list` JSON, with assigned names from `agent list`
+ * joined by terminal + pane id, plus the per-tab layout geometry from
  * `herdr --session <n> api snapshot`. A session whose server is stopped
  * projects from its persisted `session.json` instead — same shape, marked by
  * `running: false` and `savedAt`; geometry, terminal ids, and live agent
@@ -36,10 +37,12 @@ export type HerdrAgentSessionRef = {
 
 export type HerdrPaneProjection = {
   paneId: string;
-  /** Herdr's stable terminal id; `herdr agent <verb>` accepts it as a target. */
+  /** Herdr's terminal identity; CLI read commands use the separately carried pane id. */
   terminalId: string | null;
   tabId: string;
   workspaceId: string;
+  /** Operator-assigned Herdr name; distinct from the changing terminal title. */
+  name?: string | null;
   label: string | null;
   /** Detected/reported agent label, e.g. "claude". Null for plain shells. */
   agent: string | null;

package/src/transports.ts

@@ -112,6 +112,14 @@ export interface ChannelInviteRevokeCommand {
   revokedAt: number;
 }
 
+export interface ChannelMemberRemoveCommand {
+  kind: "channel.member.remove";
+  channelId: ScoutId;
+  actorId: ScoutId;
+  removedByActorId: ScoutId;
+  removedAt: number;
+}
+
 export interface ChannelInviteRedeemCommand {
   kind: "channel.invite.redeem";
   channelId: ScoutId;
@@ -134,6 +142,7 @@ export type ControlCommand =
   | ChannelInviteCreateCommand
   | ChannelInviteRevokeCommand
   | ChannelInviteRedeemCommand
+  | ChannelMemberRemoveCommand
   | PostMessageCommand
   | InvokeAgentCommand
   | EnsureAwakeCommand