@openscout/protocol 0.2.64 → 0.2.83

package/src/observed-status.ts

@@ -0,0 +1,90 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export type ObservedStatusPhase =
+  | "unconfigured"
+  | "registered"
+  | "starting"
+  | "connecting"
+  | "running"
+  | "stopping"
+  | "stopped"
+  | "closed"
+  | "error"
+  | "unknown";
+
+export type ObservedActivity =
+  | "idle"
+  | "queued"
+  | "waking"
+  | "thinking"
+  | "executing"
+  | "working"
+  | "waiting_for_input"
+  | "waiting_on_actor"
+  | "blocked"
+  | "review"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "stalled"
+  | "offline"
+  | "unknown";
+
+export type ObservedStatusSubjectKind =
+  | "agent"
+  | "endpoint"
+  | "flight"
+  | "run"
+  | "question"
+  | "work_item"
+  | "pairing_runtime"
+  | "tail_session";
+
+export type ObservedStatusProvenanceSource =
+  | "broker_record"
+  | "endpoint"
+  | "flight"
+  | "agent_run"
+  | "collaboration_record"
+  | "session_trace"
+  | "pairing_runtime"
+  | "tail_event"
+  | "process"
+  | "tmux"
+  | "staleness_inference";
+
+export interface ObservedStatusDetail {
+  title?: string;
+  summary?: string;
+  toolName?: string;
+  waitingOn?: unknown;
+  sourceCursor?: string;
+  metadata?: MetadataMap;
+}
+
+export interface StatusProjectionProvenance {
+  source: ObservedStatusProvenanceSource;
+  refId: ScoutId;
+  observedAt: number;
+  confidence: number;
+}
+
+export interface ObservedStatusProjection {
+  subjectKind: ObservedStatusSubjectKind;
+  subjectId: ScoutId;
+  agentId?: ScoutId;
+  phase: ObservedStatusPhase;
+  activity: ObservedActivity;
+  detail?: ObservedStatusDetail;
+  provenance: StatusProjectionProvenance[];
+  confidence: number;
+  updatedAt: number;
+  staleAt?: number;
+}
+
+export function observedStatusDisplay(status: Pick<ObservedStatusProjection, "phase" | "activity">): string {
+  if (status.phase === "running" && status.activity && status.activity !== "unknown") {
+    return status.activity;
+  }
+  return status.phase;
+}

package/src/orchestrator-prompt.ts

@@ -0,0 +1,47 @@
+/**
+ * Soft-mode prompt fragment for agents with an active orchestrator assignment.
+ * Inject into the agent system/tool preamble when assignment is present.
+ */
+
+import {
+  SCOUT_MISSION_LOG_LIMITS,
+  SCOUT_ORCHESTRATOR_ROLE,
+  type ScoutRoleAssignment,
+} from "./assigned-roles.js";
+
+export function orchestratorSoftPrompt(opts: {
+  assignment: ScoutRoleAssignment;
+  missionId?: string;
+}): string {
+  const missionLine =
+    opts.assignment.scope.kind === "mission"
+      ? `Mission (work id): ${opts.assignment.scope.missionId}`
+      : opts.missionId
+        ? `Active mission context: ${opts.missionId} (standing orchestrator assignment)`
+        : "Standing orchestrator: prefer mission-scoped assignment when a campaign exists.";
+
+  return [
+    `# Orchestrator role (assigned)`,
+    "",
+    `You are assigned the **${SCOUT_ORCHESTRATOR_ROLE.label}** role.`,
+    SCOUT_ORCHESTRATOR_ROLE.summary,
+    missionLine,
+    "",
+    "## Duties",
+    "- Own the mission spine: keep child work/asks linked under the campaign root.",
+    "- On mission moments (turn end, delegation, waiting, finish), append a short mission log entry.",
+    "- When blocked, set who holds the next move.",
+    "- Do not spam: only mission-level moments, not every tool call.",
+    "",
+    "## Mission log fields",
+    `- intent: stable goal (≤ ${SCOUT_MISSION_LOG_LIMITS.intentMaxWords} words)`,
+    `- status: current action (≤ ${SCOUT_MISSION_LOG_LIMITS.statusMaxWords} words)`,
+    `- kind: heartbeat | progress | delegation | waiting | decision | risk | integration | done | failed`,
+    `- note: optional, ≤ ${SCOUT_MISSION_LOG_LIMITS.noteMaxChars} chars`,
+    "",
+    "## How to write",
+    "- CLI: `scout role log-append <missionId> --actor <you> --kind progress --intent \"...\" --status \"...\"`",
+    "- HTTP: `POST /api/missions/<missionId>/log` with actorId, kind, intent, status",
+    "- Verbose chat stays in DMs; mission log is the cheap reconstruction stream.",
+  ].join("\n");
+}

package/src/permission-policy.ts

@@ -0,0 +1,21 @@
+export const SCOUT_PERMISSION_PROFILES = [
+  "observe",
+  "review",
+  "workspace_write",
+  "sandboxed_write",
+  "trusted_local",
+  "external_sandbox",
+] as const;
+
+export type ScoutPermissionProfile = typeof SCOUT_PERMISSION_PROFILES[number];
+
+export function normalizeScoutPermissionProfile(
+  value: string | null | undefined,
+): ScoutPermissionProfile | undefined {
+  const normalized = value?.trim().replaceAll("-", "_");
+  return SCOUT_PERMISSION_PROFILES.find((profile) => profile === normalized);
+}
+
+export function formatScoutPermissionProfiles(): string {
+  return SCOUT_PERMISSION_PROFILES.join("|");
+}

package/src/provisional-agent-names.ts

@@ -0,0 +1,272 @@
+import { normalizeAgentSelectorSegment, parseAgentIdentity } from "./agent-identity.js";
+
+/**
+ * Curated rotation pool for provisional agent identities.
+ *
+ * Names are short, human-addressable, and collision-resistant across a local
+ * fleet. Categories include scientists, composers, philosophers, and a few
+ * literary figures — chosen for memorability, not biographical endorsement.
+ */
+export const PROVISIONAL_AGENT_NAMES = [
+  // Scientists & inventors
+  "archimedes",
+  "avogadro",
+  "bohr",
+  "boyle",
+  "copernicus",
+  "curie",
+  "dalton",
+  "darwin",
+  "dirac",
+  "einstein",
+  "euler",
+  "faraday",
+  "feynman",
+  "fermi",
+  "fourier",
+  "galileo",
+  "gauss",
+  "hawking",
+  "heisenberg",
+  "hooke",
+  "hopper",
+  "hypatia",
+  "kepler",
+  "lavoisier",
+  "lovelace",
+  "maxwell",
+  "mendel",
+  "newton",
+  "noether",
+  "oppenheimer",
+  "pasteur",
+  "pauli",
+  "planck",
+  "pythagoras",
+  "rutherford",
+  "sagan",
+  "turing",
+  "volterra",
+  // Composers
+  "bach",
+  "bartok",
+  "beethoven",
+  "brahms",
+  "chopin",
+  "debussy",
+  "dvorak",
+  "grieg",
+  "handel",
+  "haydn",
+  "liszt",
+  "mahler",
+  "monteverdi",
+  "mozart",
+  "prokofiev",
+  "purcell",
+  "ravel",
+  "satie",
+  "schubert",
+  "schumann",
+  "stravinsky",
+  "tchaikovsky",
+  "vivaldi",
+  "wagner",
+  // Philosophers & thinkers
+  "aquinas",
+  "aristotle",
+  "confucius",
+  "descartes",
+  "epicurus",
+  "hegel",
+  "hume",
+  "kant",
+  "kierkegaard",
+  "locke",
+  "machiavelli",
+  "nietzsche",
+  "plato",
+  "popper",
+  "rousseau",
+  "russell",
+  "seneca",
+  "socrates",
+  "spinoza",
+  "voltaire",
+  "wittgenstein",
+  "zeno",
+  // Writers (classic, globally recognizable)
+  "austen",
+  "borges",
+  "dickens",
+  "dostoevsky",
+  "homer",
+  "kafka",
+  "orwell",
+  "shakespeare",
+  "tolstoy",
+  "virgil",
+  "woolf",
+  // House vocabulary (design-studies / product fixtures)
+  "atlas",
+  "cobalt",
+  "drover",
+  "hudson",
+  "pike",
+  "quill",
+] as const;
+
+export type ProvisionalAgentName = (typeof PROVISIONAL_AGENT_NAMES)[number];
+
+export function normalizeProvisionalAgentNameCandidates(
+  candidates: Iterable<string>,
+): string[] {
+  const seen = new Set<string>();
+  const normalizedNames: string[] = [];
+  for (const raw of candidates) {
+    const withoutComment = raw.split("#")[0]?.trim() ?? "";
+    const withoutSigil = withoutComment.replace(/^@+/, "").trim();
+    const normalized = normalizeAgentSelectorSegment(withoutSigil);
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    normalizedNames.push(normalized);
+  }
+  return normalizedNames;
+}
+
+export function parseProvisionalAgentNamesText(content: string): string[] {
+  return normalizeProvisionalAgentNameCandidates(content.split(/\r?\n/u));
+}
+
+export function parseProvisionalAgentNamesJson(content: string): string[] {
+  const parsed = JSON.parse(content) as unknown;
+  if (Array.isArray(parsed)) {
+    return normalizeProvisionalAgentNameCandidates(
+      parsed.filter((entry): entry is string => typeof entry === "string"),
+    );
+  }
+  if (
+    parsed
+    && typeof parsed === "object"
+    && Array.isArray((parsed as { names?: unknown }).names)
+  ) {
+    return normalizeProvisionalAgentNameCandidates(
+      (parsed as { names: unknown[] }).names.filter(
+        (entry): entry is string => typeof entry === "string",
+      ),
+    );
+  }
+  throw new Error(
+    "provisional agent names JSON must be a string array or { \"names\": [...] }",
+  );
+}
+
+export function isProvisionalAgentName(
+  value: string,
+  pool: readonly string[] = PROVISIONAL_AGENT_NAMES,
+): boolean {
+  const normalized = normalizeAgentSelectorSegment(value);
+  return normalized.length > 0 && pool.includes(normalized);
+}
+
+/** Extract the base definition id from an agent id, handle, or @label. */
+export function definitionIdFromOccupancyKey(value: string): string | null {
+  const trimmed = value.trim().replace(/^@+/, "");
+  if (!trimmed) {
+    return null;
+  }
+
+  const parsed = parseAgentIdentity(trimmed.startsWith("@") ? trimmed : `@${trimmed}`);
+  if (parsed?.definitionId) {
+    return normalizeAgentSelectorSegment(parsed.definitionId);
+  }
+
+  const head = trimmed.split(".")[0]?.trim() ?? "";
+  const normalized = normalizeAgentSelectorSegment(head);
+  return normalized || null;
+}
+
+export function collectOccupiedDefinitionIds(references: Iterable<string>): Set<string> {
+  const occupied = new Set<string>();
+  for (const reference of references) {
+    const definitionId = definitionIdFromOccupancyKey(reference);
+    if (definitionId) {
+      occupied.add(definitionId);
+    }
+  }
+  return occupied;
+}
+
+export type AllocateProvisionalAgentNameOptions = {
+  /** When set, allocation starts scanning from this pool index (wraps). */
+  startIndex?: number;
+  /** Override the built-in pool (for example operator-configured names). */
+  pool?: readonly string[];
+};
+
+export type ProvisionalAgentNameSeedPart = string | number | boolean | null | undefined;
+
+function updateFnv1a32(hash: number, value: string): number {
+  let next = hash >>> 0;
+  for (let index = 0; index < value.length; index += 1) {
+    next ^= value.charCodeAt(index);
+    next = Math.imul(next, 0x01000193) >>> 0;
+  }
+  return next;
+}
+
+export function provisionalAgentNameStartIndexForSeed(
+  seedParts: Iterable<ProvisionalAgentNameSeedPart>,
+  pool: readonly string[] = PROVISIONAL_AGENT_NAMES,
+): number {
+  if (pool.length === 0) {
+    return 0;
+  }
+
+  let hash = 0x811c9dc5;
+  let fieldIndex = 0;
+  for (const part of seedParts) {
+    const value = part == null ? "" : String(part);
+    hash = updateFnv1a32(hash, `${fieldIndex}:${value.length}:`);
+    hash = updateFnv1a32(hash, value);
+    hash = updateFnv1a32(hash, "|");
+    fieldIndex += 1;
+  }
+  hash = updateFnv1a32(hash, `fields:${fieldIndex}`);
+  return hash % pool.length;
+}
+
+/**
+ * Pick the next free name from the pool.
+ * Falls back to `{poolName}-{n}` only when the entire pool is occupied.
+ */
+export function allocateProvisionalAgentName(
+  occupied: ReadonlySet<string> | Iterable<string>,
+  options: AllocateProvisionalAgentNameOptions = {},
+): string {
+  const pool = options.pool?.length ? options.pool : PROVISIONAL_AGENT_NAMES;
+  if (pool.length === 0) {
+    throw new Error("provisional agent name pool is empty");
+  }
+
+  const taken = occupied instanceof Set
+    ? occupied
+    : collectOccupiedDefinitionIds(occupied);
+
+  const start = Math.abs(options.startIndex ?? 0) % pool.length;
+  for (let offset = 0; offset < pool.length; offset += 1) {
+    const candidate = pool[(start + offset) % pool.length]!;
+    if (!taken.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  const anchor = pool[start]!;
+  let suffix = 2;
+  while (taken.has(`${anchor}-${suffix}`)) {
+    suffix += 1;
+  }
+  return `${anchor}-${suffix}`;
+}

package/src/read-receipts.ts

@@ -0,0 +1,12 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+
+export interface ConversationReadCursor {
+  conversationId: ScoutId;
+  actorId: ScoutId;
+  readerNodeId?: ScoutId;
+  lastReadMessageId?: ScoutId;
+  lastReadSeq?: number;
+  lastReadAt: number;
+  updatedAt: number;
+  metadata?: MetadataMap;
+}

package/src/relay-agent-card.ts

@@ -2,73 +2,83 @@ import type { AgentEndpoint, AgentHarness } from "./actors.js";
 import type { MetadataMap, ScoutId } from "./common.js";
 
 export interface RelayReturnAddress {
-    actorId: ScoutId;
-    handle: string;
-    displayName?: string;
-    selector?: string;
-    defaultSelector?: string;
-    conversationId?: ScoutId;
-    replyToMessageId?: ScoutId;
-    nodeId?: ScoutId;
-    projectRoot?: string;
-    sessionId?: string;
-    metadata?: MetadataMap;
+  actorId: ScoutId;
+  handle: string;
+  displayName?: string;
+  selector?: string;
+  defaultSelector?: string;
+  conversationId?: ScoutId;
+  replyToMessageId?: ScoutId;
+  nodeId?: ScoutId;
+  projectRoot?: string;
+  sessionId?: string;
+  metadata?: MetadataMap;
+}
+
+export interface RelayAgentCardLifecycle {
+  kind: "persistent" | "one_time";
+  createdAt?: number;
+  createdById?: ScoutId;
+  expiresAt?: number;
+  maxUses?: number;
+  inboxConversationId?: ScoutId;
 }
 
 export interface RelayAgentCard {
-    id: ScoutId;
-    agentId: ScoutId;
-    definitionId: ScoutId;
-    displayName: string;
-    handle: string;
-    selector?: string;
-    defaultSelector?: string;
-    projectName?: string;
-    projectRoot: string;
-    currentDirectory: string;
-    harness: AgentHarness;
-    transport: AgentEndpoint["transport"];
-    sessionId?: string;
-    branch?: string;
-    createdAt: number;
-    createdById?: ScoutId;
-    brokerRegistered: boolean;
-    inboxConversationId?: ScoutId;
-    returnAddress: RelayReturnAddress;
-    metadata?: MetadataMap;
+  id: ScoutId;
+  agentId: ScoutId;
+  definitionId: ScoutId;
+  displayName: string;
+  handle: string;
+  selector?: string;
+  defaultSelector?: string;
+  projectName?: string;
+  projectRoot: string;
+  currentDirectory: string;
+  harness: AgentHarness;
+  transport: AgentEndpoint["transport"];
+  sessionId?: string;
+  branch?: string;
+  createdAt: number;
+  createdById?: ScoutId;
+  brokerRegistered: boolean;
+  inboxConversationId?: ScoutId;
+  lifecycle?: RelayAgentCardLifecycle;
+  returnAddress: RelayReturnAddress;
+  metadata?: MetadataMap;
 }
 
 export function buildRelayReturnAddress(input: RelayReturnAddress): RelayReturnAddress {
-    const next: RelayReturnAddress = {
-        actorId: input.actorId,
-        handle: input.handle.trim(),
-    };
-    if (input.displayName?.trim()) {
-        next.displayName = input.displayName.trim();
-    }
-    if (input.selector?.trim()) {
-        next.selector = input.selector.trim();
-    }
-    if (input.defaultSelector?.trim()) {
-        next.defaultSelector = input.defaultSelector.trim();
-    }
-    if (input.conversationId?.trim()) {
-        next.conversationId = input.conversationId.trim();
-    }
-    if (input.replyToMessageId?.trim()) {
-        next.replyToMessageId = input.replyToMessageId.trim();
-    }
-    if (input.nodeId?.trim()) {
-        next.nodeId = input.nodeId.trim();
-    }
-    if (input.projectRoot?.trim()) {
-        next.projectRoot = input.projectRoot.trim();
-    }
-    if (input.sessionId?.trim()) {
-        next.sessionId = input.sessionId.trim();
-    }
-    if (input.metadata && Object.keys(input.metadata).length > 0) {
-        next.metadata = input.metadata;
-    }
-    return next;
+  const next: RelayReturnAddress = {
+    actorId: input.actorId,
+    handle: input.handle.trim(),
+  };
+  if (input.displayName?.trim()) {
+    next.displayName = input.displayName.trim();
+  }
+  if (input.selector?.trim()) {
+    next.selector = input.selector.trim();
+  }
+  if (input.defaultSelector?.trim()) {
+    next.defaultSelector = input.defaultSelector.trim();
+  }
+  if (input.conversationId?.trim()) {
+    next.conversationId = input.conversationId.trim();
+  }
+  if (input.replyToMessageId?.trim()) {
+    next.replyToMessageId = input.replyToMessageId.trim();
+  }
+  if (input.nodeId?.trim()) {
+    next.nodeId = input.nodeId.trim();
+  }
+  if (input.projectRoot?.trim()) {
+    next.projectRoot = input.projectRoot.trim();
+  }
+  if (input.sessionId?.trim()) {
+    next.sessionId = input.sessionId.trim();
+  }
+  if (input.metadata && Object.keys(input.metadata).length > 0) {
+    next.metadata = input.metadata;
+  }
+  return next;
 }