@openscout/protocol 0.2.64 → 0.2.83

package/src/rendezvous.ts

@@ -0,0 +1,154 @@
+import type { ScoutId } from "./common.js";
+
+export const SCOUT_RENDEZVOUS_GENERATED_CODENAME_LENGTH = 6;
+export const SCOUT_RENDEZVOUS_CODENAME_MAX_LENGTH = 32;
+// Rooms stay joinable for hours so a human can relay the codename to the
+// second session at their own pace; per-call long-polls stay short.
+export const SCOUT_RENDEZVOUS_INVITE_TTL_MS = 4 * 60 * 60_000;
+export const SCOUT_RENDEZVOUS_MAX_WAIT_MS = 10 * 60_000;
+
+export type ScoutRendezvousCreateRequest = {
+  action: "create";
+  codename?: string;
+  projectRoot: string;
+  participantId: ScoutId;
+};
+
+export type ScoutRendezvousJoinRequest = {
+  action: "join";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  waitMs?: number;
+};
+
+export type ScoutRendezvousRequest =
+  | ScoutRendezvousCreateRequest
+  | ScoutRendezvousJoinRequest;
+
+export type ScoutRendezvousCreatedResponse = {
+  status: "created";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  createdAt: number;
+  expiresAt: number;
+};
+
+export type ScoutRendezvousWaitingResponse = {
+  status: "waiting";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  joinedAt: number;
+  expiresAt: number;
+};
+
+export type ScoutRendezvousMatchedResponse = {
+  status: "matched";
+  matchId: ScoutId;
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  participantIds: [ScoutId, ScoutId];
+  peerParticipantIds: ScoutId[];
+  createdAt: number;
+  expiresAt: number;
+};
+
+export type ScoutRendezvousCodenameBusyResponse = {
+  status: "codename_busy";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  participantCount: number;
+  expiresAt: number;
+  suggestion: "choose_another_codename";
+};
+
+export type ScoutRendezvousNotFoundResponse = {
+  status: "not_found";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  suggestion: "check_codename_or_create";
+};
+
+export type ScoutRendezvousExpiredResponse = {
+  status: "expired";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  expiresAt: number;
+  suggestion: "choose_another_codename";
+};
+
+export type ScoutRendezvousConsumedResponse = {
+  status: "consumed";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  expiresAt: number;
+  suggestion: "choose_another_codename";
+};
+
+export type ScoutRendezvousProjectMismatchResponse = {
+  status: "project_mismatch";
+  codename: string;
+  projectRoot: string;
+  participantId: ScoutId;
+  suggestion: "run_in_invitation_project";
+};
+
+export type ScoutRendezvousResponse =
+  | ScoutRendezvousCreatedResponse
+  | ScoutRendezvousWaitingResponse
+  | ScoutRendezvousMatchedResponse
+  | ScoutRendezvousCodenameBusyResponse
+  | ScoutRendezvousNotFoundResponse
+  | ScoutRendezvousExpiredResponse
+  | ScoutRendezvousConsumedResponse
+  | ScoutRendezvousProjectMismatchResponse;
+
+export type ScoutRendezvousFailureResponse = Extract<
+  ScoutRendezvousResponse,
+  { status: "codename_busy" | "not_found" | "expired" | "consumed" | "project_mismatch" }
+>;
+
+export function isScoutRendezvousFailureResponse(
+  response: ScoutRendezvousResponse,
+): response is ScoutRendezvousFailureResponse {
+  return response.status === "codename_busy"
+    || response.status === "not_found"
+    || response.status === "expired"
+    || response.status === "consumed"
+    || response.status === "project_mismatch";
+}
+
+export function normalizeScoutRendezvousCodename(codename: string): string {
+  return codename.normalize("NFKC").trim().toLocaleUpperCase("en-US");
+}
+
+/**
+ * Validates a human-chosen codename while retaining its display capitalization.
+ * Case folding is only for broker lookup keys.
+ */
+export function validateScoutRendezvousCodename(codename: unknown): string {
+  if (typeof codename !== "string") {
+    throw new Error("codename must be a string");
+  }
+  const displayCodename = codename.normalize("NFKC").trim();
+  if (!displayCodename) {
+    throw new Error("codename must not be blank");
+  }
+  const normalized = normalizeScoutRendezvousCodename(displayCodename);
+  if (
+    normalized.length > SCOUT_RENDEZVOUS_CODENAME_MAX_LENGTH
+    || !/^[A-Z0-9]+$/u.test(normalized)
+  ) {
+    throw new Error(
+      `codename must be 1 to ${SCOUT_RENDEZVOUS_CODENAME_MAX_LENGTH} ASCII letters or digits`,
+    );
+  }
+  return displayCodename;
+}

package/src/reserved-vocabulary.ts

@@ -0,0 +1,135 @@
+import {
+  BUILT_IN_AGENT_DEFINITION_IDS,
+  OPENSCOUT_COORDINATOR_AGENT_ID,
+  SCOUT_DISPATCHER_AGENT_ID,
+  normalizeAgentSelectorSegment,
+} from "./agent-identity.js";
+import {
+  SCOUT_LAUNCHABLE_HARNESSES,
+  SCOUT_REASONING_EFFORTS,
+} from "./runtime-execution.js";
+import { SCOUT_RESERVED_RUNTIME_PROFILE_IDS } from "./runtime-profiles.js";
+
+export const SCOUT_RESERVED_ROUTE_WORDS = [
+  "scout",
+  "openscout",
+  "scoutbot",
+  "operator",
+  "shared",
+  "broadcast",
+  "agent",
+  "alias",
+  "target",
+  "session",
+  "ref",
+  "id",
+  "project",
+  "channel",
+] as const;
+
+export const SCOUT_RESERVED_DIMENSION_WORDS = [
+  "harness",
+  "model",
+  "profile",
+  "node",
+  "workspace",
+  "effort",
+] as const;
+
+export type ScoutReservedVocabularyKind =
+  | "harness"
+  | "profile"
+  | "effort"
+  | "route"
+  | "dimension"
+  | "product"
+  | "built_in";
+
+const PRODUCT_IDENTITIES = new Set([
+  SCOUT_DISPATCHER_AGENT_ID,
+  OPENSCOUT_COORDINATOR_AGENT_ID,
+  "scoutbot",
+]);
+
+const RESERVED_BY_KIND: ReadonlyArray<readonly [ScoutReservedVocabularyKind, ReadonlySet<string>]> = [
+  ["profile", new Set(SCOUT_RESERVED_RUNTIME_PROFILE_IDS)],
+  ["harness", new Set(SCOUT_LAUNCHABLE_HARNESSES)],
+  ["effort", new Set(SCOUT_REASONING_EFFORTS)],
+  ["dimension", new Set(SCOUT_RESERVED_DIMENSION_WORDS)],
+  ["product", PRODUCT_IDENTITIES],
+  ["built_in", BUILT_IN_AGENT_DEFINITION_IDS],
+  ["route", new Set(SCOUT_RESERVED_ROUTE_WORDS)],
+];
+
+export const SCOUT_RESERVED_AGENT_NAMES: ReadonlySet<string> = new Set(
+  RESERVED_BY_KIND.flatMap(([, values]) => [...values]),
+);
+
+export const SCOUT_AGENT_NAME_PATTERN = /^[a-z][a-z0-9-]{0,62}$/;
+export const SCOUT_SESSION_HANDLE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/+\-]{0,127}$/;
+
+export function scoutReservedVocabularyKind(
+  value: string | null | undefined,
+): ScoutReservedVocabularyKind | null {
+  const normalized = normalizeAgentSelectorSegment(value ?? "");
+  if (!normalized) return null;
+  return RESERVED_BY_KIND.find(([, values]) => values.has(normalized))?.[0] ?? null;
+}
+
+export function isScoutReservedAgentName(value: string | null | undefined): boolean {
+  return scoutReservedVocabularyKind(value) !== null;
+}
+
+export type ScoutNameValidation =
+  | { ok: true; value: string }
+  | { ok: false; code: "invalid_name" | "reserved_name"; message: string };
+
+export function validateScoutAgentNameForWrite(value: string): ScoutNameValidation {
+  const raw = value.trim().replace(/^@+/, "");
+  if (!SCOUT_AGENT_NAME_PATTERN.test(raw)) {
+    return {
+      ok: false,
+      code: "invalid_name",
+      message: `invalid_name: agent name "${value}" must match ^[a-z][a-z0-9-]{0,62}$; names are not silently rewritten`,
+    };
+  }
+  const kind = scoutReservedVocabularyKind(raw);
+  if (kind) {
+    const teaching = kind === "harness" || kind === "profile"
+      ? ` To target a runtime, use --harness ${raw} or ${raw}/<model>/<effort>.`
+      : " Pick a non-runtime word to name an agent.";
+    return {
+      ok: false,
+      code: "reserved_name",
+      message: `reserved_name: name "${raw}" is reserved — it names a ${kind}.${teaching}`,
+    };
+  }
+  return { ok: true, value: raw };
+}
+
+export function assertScoutAgentNameForWrite(value: string): string {
+  const result = validateScoutAgentNameForWrite(value);
+  if (!result.ok) throw new Error(result.message);
+  return result.value;
+}
+
+/** Session handles are opaque but still cannot claim bare runtime grammar. */
+export function validateScoutSessionHandleForWrite(value: string): ScoutNameValidation {
+  const raw = value.trim().replace(/^@+/, "");
+  if (!SCOUT_SESSION_HANDLE_PATTERN.test(raw)) {
+    return {
+      ok: false,
+      code: "invalid_name",
+      message: `invalid_name: session handle "${value}" contains unsupported characters`,
+    };
+  }
+  const kind = scoutReservedVocabularyKind(raw);
+  if (kind) {
+    return {
+      ok: false,
+      code: "reserved_name",
+      message: `reserved_name: session handle "${raw}" is reserved — it names a ${kind}`,
+    };
+  }
+  return { ok: true, value: raw };
+}

package/src/route-aliases.ts

@@ -0,0 +1,130 @@
+import type { AgentHarness } from "./actors.js";
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export interface RouteAliasScope {
+  projectKey?: string;
+  projectRoot?: string;
+  nodeId?: ScoutId;
+}
+
+export type RouteAliasTarget =
+  | { kind: "agent"; agentId: ScoutId; nodeId: ScoutId }
+  | {
+      kind: "session";
+      sessionId: ScoutId;
+      agentId: ScoutId;
+      endpointId: ScoutId;
+      nodeId: ScoutId;
+      harness: AgentHarness;
+    };
+
+export type RouteAliasState = "active" | "unset" | "expired";
+
+export interface RouteAliasBinding {
+  id: ScoutId;
+  alias: string;
+  displayAlias?: string;
+  ownerRealmId: ScoutId;
+  scopeProjectKey: string;
+  scopeProjectRoot?: string;
+  scopeNodeId: ScoutId;
+  target: RouteAliasTarget;
+  targetSnapshot: MetadataMap;
+  state: RouteAliasState;
+  revision: number;
+  createdByActorId: ScoutId;
+  updatedByActorId: ScoutId;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt?: number;
+  revokedAt?: number;
+  metadata?: MetadataMap;
+}
+
+export type RouteAliasRevisionOperation = "set" | "repoint" | "unset" | "expire" | "repair";
+
+export interface RouteAliasRevision {
+  id: ScoutId;
+  bindingId: ScoutId;
+  revision: number;
+  operation: RouteAliasRevisionOperation;
+  oldTarget?: RouteAliasTarget;
+  newTarget?: RouteAliasTarget;
+  oldTargetSnapshot?: MetadataMap;
+  newTargetSnapshot?: MetadataMap;
+  actorId: ScoutId;
+  authorityNodeId: ScoutId;
+  createdAt: number;
+  reason?: string;
+  requestId?: ScoutId;
+}
+
+export interface RouteAliasResolutionProof {
+  bindingId: ScoutId;
+  revision: number;
+  requestedAlias: string;
+  scope: Required<Pick<RouteAliasScope, "projectKey" | "nodeId">> & Pick<RouteAliasScope, "projectRoot">;
+  target: RouteAliasTarget;
+  resolvedAt: number;
+}
+
+export type RouteAliasDiagnosticCode =
+  | "invalid_alias"
+  | "alias_exists"
+  | "unknown_alias"
+  | "ambiguous_alias_scope"
+  | "alias_inactive"
+  | "alias_shadowed"
+  | "alias_target_unavailable"
+  | "alias_session_not_reachable"
+  | "alias_session_terminal"
+  | "not_authorized"
+  | "revision_conflict";
+
+export interface RouteAliasSetRequest {
+  alias: string;
+  scope?: RouteAliasScope;
+  target?: import("./scout-dispatch.js").ScoutRouteTarget;
+  self?: "session" | "agent";
+  replace?: boolean;
+  expectedRevision?: number;
+  expiresAt?: number;
+  caller?: import("./scout-dispatch.js").ScoutCallerContext;
+  metadata?: MetadataMap;
+}
+
+export interface RouteAliasListRequest {
+  scope?: RouteAliasScope;
+  targetAgentId?: ScoutId;
+  targetSessionId?: ScoutId;
+  includeInactive?: boolean;
+  limit?: number;
+  caller?: import("./scout-dispatch.js").ScoutCallerContext;
+}
+
+export interface RouteAliasResolveRequest {
+  alias?: string;
+  bindingId?: ScoutId;
+  scope?: RouteAliasScope;
+  caller?: import("./scout-dispatch.js").ScoutCallerContext;
+}
+
+export interface RouteAliasResolveResult {
+  resolved: boolean;
+  available: boolean;
+  binding?: RouteAliasBinding;
+  proof?: RouteAliasResolutionProof;
+  status?: "active" | "shadowed" | "unreachable" | "terminal" | "expired" | "unset";
+  diagnostic?: { code: RouteAliasDiagnosticCode; detail: string };
+  fullyQualifiedSelector?: string;
+}
+
+export interface RouteAliasMutationRequest {
+  target?: import("./scout-dispatch.js").ScoutRouteTarget;
+  /** Included by front doors so a non-authoritative broker can forward the mutation. */
+  scope?: RouteAliasScope;
+  expectedRevision?: number;
+  expiresAt?: number | null;
+  caller?: import("./scout-dispatch.js").ScoutCallerContext;
+  reason?: string;
+}

package/src/runtime-catalog-contract.ts

@@ -0,0 +1,60 @@
+import type { AgentHarness } from "./actors.js";
+
+/** Harness ids Scout can select for a new execution session. */
+export const SCOUT_LAUNCHABLE_HARNESSES = [
+  "claude", "codex", "grok", "grok-acp", "kimi", "flue", "cursor", "opencode", "pi",
+] as const satisfies readonly AgentHarness[];
+
+export type ScoutLaunchableHarness = typeof SCOUT_LAUNCHABLE_HARNESSES[number];
+
+export const SCOUT_REASONING_EFFORTS = [
+  "none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra",
+] as const;
+
+export type ScoutReasoningEffort = typeof SCOUT_REASONING_EFFORTS[number];
+
+export const SCOUT_REASONING_EFFORT_LABELS: Readonly<Record<ScoutReasoningEffort, string>> = {
+  none: "None",
+  minimal: "Minimal",
+  low: "Light",
+  medium: "Medium",
+  high: "High",
+  xhigh: "Extra High",
+  max: "Max",
+  ultra: "Ultra",
+};
+
+export interface ScoutOwnedRuntimeModel {
+  id: string;
+  label: string;
+  enabled: boolean;
+  default?: boolean;
+  description?: string;
+  family?: string;
+  version?: string;
+  contextWindowTokens?: number;
+  reasoningEfforts?: readonly ScoutReasoningEffort[] | null;
+  defaultReasoningEffort?: ScoutReasoningEffort | null;
+}
+
+export interface ScoutOwnedRuntimeHarness {
+  id: ScoutLaunchableHarness;
+  label: string;
+  enabled: boolean;
+  /**
+   * Whether pickers offer this harness. Defaults to `true`; `false` keeps the
+   * harness launchable and resumable without presenting a duplicate transport
+   * as a separate operator choice.
+   */
+  listed?: boolean;
+  default?: boolean;
+  reasoningEfforts: readonly ScoutReasoningEffort[] | null;
+  defaultReasoningEffort?: ScoutReasoningEffort | null;
+  models: readonly ScoutOwnedRuntimeModel[];
+}
+
+export interface ScoutOwnedRuntimeCatalog {
+  schemaVersion: "openscout.runtime-catalog.v1";
+  revision: string;
+  harnesses: readonly ScoutOwnedRuntimeHarness[];
+}