@openscout/protocol 0.2.63 → 0.2.82

package/src/events.ts

@@ -4,16 +4,26 @@ import type { ConversationBinding, ConversationDefinition } from "./conversation
 import type { DeliveryAttempt, DeliveryIntent } from "./deliveries.js";
 import type { FlightRecord, InvocationRequest } from "./invocations.js";
 import type { MessageRecord } from "./messages.js";
+import type { ConversationReadCursor } from "./read-receipts.js";
 import type { AgentDefinition, AgentEndpoint, ActorIdentity } from "./actors.js";
 import type { CollaborationEvent, CollaborationRecord } from "./collaboration.js";
 import type { ScoutDispatchRecord } from "./scout-dispatch.js";
 
+export const OPENSCOUT_CONTROL_EVENT_VERSION = 1 as const;
+
 export interface ControlEventBase<K extends string, P> {
   id: ScoutId;
   kind: K;
   ts: number;
   actorId: ScoutId;
   nodeId?: ScoutId;
+  /**
+   * Schema version of the control-event envelope. Optional by design: legacy
+   * persisted events pre-date the version field and carry no `v`, yet must
+   * still satisfy this type so they can be replayed. After
+   * {@link normalizeControlEvent}, `v` is always present.
+   */
+  readonly v?: typeof OPENSCOUT_CONTROL_EVENT_VERSION;
   payload: P;
 }
 
@@ -49,6 +59,10 @@ export type MessagePostedEvent = ControlEventBase<"message.posted", {
   message: MessageRecord;
 }>;
 
+export type ConversationReadCursorUpdatedEvent = ControlEventBase<"conversation.read_cursor.updated", {
+  cursor: ConversationReadCursor;
+}>;
+
 export type InvocationRequestedEvent = ControlEventBase<"invocation.requested", {
   invocation: InvocationRequest;
 }>;
@@ -91,6 +105,7 @@ export type ControlEvent =
   | ConversationUpsertedEvent
   | BindingUpsertedEvent
   | MessagePostedEvent
+  | ConversationReadCursorUpdatedEvent
   | InvocationRequestedEvent
   | FlightUpdatedEvent
   | DeliveryPlannedEvent
@@ -99,3 +114,19 @@ export type ControlEvent =
   | CollaborationUpsertedEvent
   | CollaborationEventAppendedEvent
   | ScoutDispatchedEvent;
+
+/**
+ * Stamp the current envelope version onto a control event when it is missing.
+ *
+ * The `v` field is optional on {@link ControlEventBase} so that legacy events
+ * persisted before versioning existed still satisfy the type (the package
+ * deliberately preserves legacy shapes for replay). This helper is the bridge:
+ * use it on the stamp-on-write path so newly produced events carry `v`, and on
+ * the normalize-on-read path so replayed legacy events are upgraded to the
+ * current version. It is a pure function — the input is never mutated.
+ */
+export function normalizeControlEvent<E extends ControlEvent>(
+  event: E,
+): E & { v: typeof OPENSCOUT_CONTROL_EVENT_VERSION } {
+  return { ...event, v: event.v ?? OPENSCOUT_CONTROL_EVENT_VERSION };
+}

package/src/harness-feature-support.ts

@@ -0,0 +1,116 @@
+export type HarnessSupportLevel = "yes" | "partial" | "no" | "unknown";
+
+export type HarnessFeatureDowngrade =
+  | "native"
+  | "embedded"
+  | "reference_text"
+  | "prompt_only"
+  | "debug_only"
+  | "unsupported";
+
+export interface HarnessFeatureEvidence {
+  kind: "adapter_spec" | "catalog" | "runtime_check" | "manual" | "upstream";
+  ref: string;
+}
+
+export interface HarnessFeatureSupport {
+  level: HarnessSupportLevel;
+  reason?: string;
+  evidence?: HarnessFeatureEvidence[];
+  downgrade?: HarnessFeatureDowngrade;
+}
+
+export interface HarnessFeatureSupportMap {
+  prompts?: {
+    systemPrompt?: HarnessFeatureSupport;
+    agentInstructions?: HarnessFeatureSupport;
+    promptFiles?: HarnessFeatureSupport;
+    images?: HarnessFeatureSupport;
+  };
+  session?: {
+    start?: HarnessFeatureSupport;
+    resume?: HarnessFeatureSupport;
+    interrupt?: HarnessFeatureSupport;
+    shutdown?: HarnessFeatureSupport;
+    concurrentTurns?: HarnessFeatureSupport;
+    traceObserve?: HarnessFeatureSupport;
+    fork?: HarnessFeatureSupport;
+    nativeThreadClone?: HarnessFeatureSupport;
+    steer?: HarnessFeatureSupport;
+    followUps?: HarnessFeatureSupport;
+  };
+  interaction?: {
+    questions?: HarnessFeatureSupport;
+    approvals?: HarnessFeatureSupport;
+    serverRequests?: HarnessFeatureSupport;
+    toolSuspensions?: HarnessFeatureSupport;
+    planApproval?: HarnessFeatureSupport;
+  };
+  tools?: {
+    command?: HarnessFeatureSupport;
+    fileChange?: HarnessFeatureSupport;
+    subagent?: HarnessFeatureSupport;
+    taskProjection?: HarnessFeatureSupport;
+    mcpStdio?: HarnessFeatureSupport;
+    mcpSse?: HarnessFeatureSupport;
+    mcpStreamableHttp?: HarnessFeatureSupport;
+  };
+  events?: {
+    rawStream?: HarnessFeatureSupport;
+    normalizedStream?: HarnessFeatureSupport;
+    displayState?: HarnessFeatureSupport;
+    subagentEvents?: HarnessFeatureSupport;
+    taskEvents?: HarnessFeatureSupport;
+    usageEvents?: HarnessFeatureSupport;
+  };
+  limits?: {
+    maxTurns?: HarnessFeatureSupport;
+    maxModelCalls?: HarnessFeatureSupport;
+    maxDuration?: HarnessFeatureSupport;
+  };
+  auth?: {
+    apiKey?: HarnessFeatureSupport;
+    authFile?: HarnessFeatureSupport;
+    oauthToken?: HarnessFeatureSupport;
+    localLogin?: HarnessFeatureSupport;
+  };
+  debug?: {
+    tmuxAttach?: HarnessFeatureSupport;
+    logs?: HarnessFeatureSupport;
+    rawTranscript?: HarnessFeatureSupport;
+  };
+}
+
+export function normalizeHarnessSupportLevel(value: string | null | undefined): HarnessSupportLevel {
+  switch (value?.trim().toLowerCase()) {
+    case "yes":
+    case "supported":
+    case "true":
+      return "yes";
+    case "partial":
+    case "degraded":
+      return "partial";
+    case "no":
+    case "unsupported":
+    case "false":
+      return "no";
+    case "unknown":
+    default:
+      return "unknown";
+  }
+}
+
+export function isHarnessFeatureUsable(
+  feature: Pick<HarnessFeatureSupport, "level"> | null | undefined,
+): boolean {
+  return feature?.level === "yes" || feature?.level === "partial";
+}
+
+export function unsupportedHarnessFeature(reason: string, evidence: HarnessFeatureEvidence[] = []): HarnessFeatureSupport {
+  return {
+    level: "no",
+    reason,
+    evidence,
+    downgrade: "unsupported",
+  };
+}

package/src/host-integrations.ts

@@ -0,0 +1,104 @@
+import type { AgentHarness } from "./actors.js";
+
+export type ScoutHostIntegrationRole =
+  | "execution_harness"
+  | "agent_host"
+  | "mcp_host"
+  | "terminal_host"
+  | "agent_state_surface";
+
+export type ScoutHostIntegrationId =
+  | "claude-code"
+  | "codex"
+  | "cursor"
+  | "pi"
+  | "hermes"
+  | "herdr";
+
+export interface ScoutHostIntegration {
+  id: ScoutHostIntegrationId;
+  label: string;
+  roles: readonly ScoutHostIntegrationRole[];
+  /**
+   * Present only when this host is also a Scout execution harness. Hosts such
+   * as Hermes and Herdr are first-class integrations without being valid
+   * values for `execution.harness` or `--harness`.
+   */
+  harness?: AgentHarness;
+  homepage?: string;
+  repositoryUrl?: string;
+  installHint?: string;
+  summary: string;
+}
+
+export const SCOUT_HOST_INTEGRATIONS: readonly ScoutHostIntegration[] = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    roles: ["execution_harness", "agent_host", "mcp_host"],
+    harness: "claude",
+    homepage: "https://claude.ai/claude-code",
+    repositoryUrl: "https://github.com/arach/claude-scout",
+    installHint: "/plugin marketplace add arach/claude-scout",
+    summary: "Claude Code can run Scout-routed work as a harness and expose Scout through a host plugin.",
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    roles: ["execution_harness", "agent_host", "mcp_host"],
+    harness: "codex",
+    homepage: "https://github.com/openai/codex",
+    repositoryUrl: "https://github.com/arach/codex-scout",
+    installHint: "/plugin marketplace add arach/codex-scout",
+    summary: "Codex can run Scout-routed work as a harness and expose Scout through MCP/plugin surfaces.",
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    roles: ["execution_harness", "agent_host", "mcp_host"],
+    harness: "cursor",
+    repositoryUrl: "https://github.com/arach/cursor-scout",
+    installHint: "See https://github.com/arach/cursor-scout for the host-specific installer.",
+    summary: "Cursor is an agent host and execution target when routed through its supported CLI or MCP surfaces.",
+  },
+  {
+    id: "pi",
+    label: "pi",
+    roles: ["execution_harness", "agent_host"],
+    harness: "pi",
+    repositoryUrl: "https://github.com/arach/pi-scout",
+    installHint: "pi install git:github.com/arach/pi-scout",
+    summary: "pi can run Scout-routed work through its native extension model.",
+  },
+  {
+    id: "hermes",
+    label: "Hermes Agent",
+    roles: ["agent_host", "mcp_host"],
+    homepage: "https://hermes-agent.nousresearch.com/docs/",
+    repositoryUrl: "https://github.com/arach/hermes-scout",
+    installHint: "Install Hermes Scout as a Hermes plugin after Scout is healthy.",
+    summary: "Hermes hosts Scout tools through its plugin and MCP system; it is not a Scout harness.",
+  },
+  {
+    id: "herdr",
+    label: "Herdr",
+    roles: ["terminal_host", "agent_state_surface"],
+    homepage: "https://herdr.dev/docs/",
+    repositoryUrl: "https://github.com/ogulcancelik/herdr",
+    installHint: "Install the Herdr integrations for the agent hosts you use, such as Claude, Codex, Hermes, or Cursor.",
+    summary: "Herdr is a terminal host and agent-state surface for sessions Scout can observe or drive; it is not a Scout harness.",
+  },
+] as const;
+
+export function scoutHostIntegrationById(
+  id: string,
+): ScoutHostIntegration | undefined {
+  return SCOUT_HOST_INTEGRATIONS.find((host) => host.id === id);
+}
+
+export function scoutHostIntegrationHasRole(
+  host: ScoutHostIntegration,
+  role: ScoutHostIntegrationRole,
+): boolean {
+  return host.roles.includes(role);
+}

package/src/inbox.ts

@@ -0,0 +1,68 @@
+import type { DeliveryIntent } from "./deliveries.js";
+import type { InvocationRequest } from "./invocations.js";
+import type { MessageRecord } from "./messages.js";
+import type { DeliveryReason, DeliveryStatus, MetadataMap, ScoutId } from "./common.js";
+
+export type InboxItemKind = "message" | "invocation";
+
+export const INBOX_CLAIMABLE_DELIVERY_STATUSES = [
+  "pending",
+  "accepted",
+  "deferred",
+] as const satisfies readonly DeliveryStatus[];
+
+export type InboxClaimableDeliveryStatus =
+  (typeof INBOX_CLAIMABLE_DELIVERY_STATUSES)[number];
+
+export function isInboxClaimableDeliveryStatus(
+  status: DeliveryStatus,
+): status is InboxClaimableDeliveryStatus {
+  return (INBOX_CLAIMABLE_DELIVERY_STATUSES as readonly DeliveryStatus[])
+    .includes(status);
+}
+
+export interface InboxItem {
+  id: ScoutId;
+  kind: InboxItemKind;
+  targetId: ScoutId;
+  targetNodeId?: ScoutId;
+  conversationId?: ScoutId;
+  messageId?: ScoutId;
+  invocationId?: ScoutId;
+  reason: DeliveryReason;
+  status: DeliveryStatus;
+  leaseOwner?: string;
+  leaseExpiresAt?: number;
+  delivery: DeliveryIntent;
+  message?: MessageRecord;
+  invocation?: InvocationRequest;
+  metadata?: MetadataMap;
+}
+
+export interface InboxClaimRequest {
+  targetId: ScoutId;
+  itemId?: ScoutId;
+  messageId?: ScoutId;
+  reasons?: DeliveryReason[];
+  leaseOwner?: string;
+  leaseMs?: number;
+}
+
+export interface InboxClaimResponse {
+  ok: true;
+  claimed: InboxItem | null;
+}
+
+export interface InboxAckRequest {
+  itemId: ScoutId;
+  leaseOwner?: string | null;
+  metadata?: MetadataMap;
+}
+
+export interface InboxNackRequest {
+  itemId: ScoutId;
+  leaseOwner?: string | null;
+  retryAfterMs?: number;
+  reason?: string;
+  metadata?: MetadataMap;
+}

package/src/index.ts

@@ -1,18 +1,51 @@
 export * from "./common.js";
+export * from "./time.js";
 export * from "./actors.js";
 export * from "./agent-identity.js";
-export * from "./agent-address.js";
-export * from "./agent-selectors.js";
+export * from "./provisional-agent-names.js";
+export * from "./a2a.js";
 export * from "./scout-agent-card.js";
 export * from "./relay-agent-card.js";
 export * from "./mesh.js";
 export * from "./conversations.js";
+export * from "./channel-identity.js";
 export * from "./collaboration.js";
+export * from "./assigned-roles.js";
+export * from "./orchestrator-prompt.js";
 export * from "./messages.js";
+export * from "./read-receipts.js";
 export * from "./invocations.js";
+export * from "./agent-runs.js";
+export * from "./budget.js";
+export * from "./agent-broker-feed.js";
+export * from "./durable-actions.js";
+export * from "./observed-status.js";
+export * from "./activity.js";
+export * from "./harness-feature-support.js";
+export * from "./host-integrations.js";
+export * from "./native-interactions.js";
+export * from "./session-display-state.js";
+export * from "./capability-matrix.js";
+export * from "./debug-attach.js";
 export * from "./scout-dispatch.js";
+export * from "./runtime-profiles.js";
+export * from "./runtime-execution.js";
+export * from "./runtime-catalog.js";
+export * from "./reserved-vocabulary.js";
+export * from "./route-aliases.js";
 export * from "./scout-delivery.js";
+export * from "./scout-reply-context.js";
+export * from "./scout-composer.js";
 export * from "./deliveries.js";
+export * from "./inbox.js";
 export * from "./transports.js";
 export * from "./events.js";
 export * from "./thread-events.js";
+export * from "./permission-policy.js";
+export * from "./cursor-transport.js";
+export * from "./terminal-surface-id.js";
+export * from "./terminal-sessions.js";
+export * from "./terminal-workspaces.js";
+export * from "./terminal-host-topology.js";
+export * from "./broker-routes.js";
+export * from "./rendezvous.js";