@dougbots/avenor-core 0.9.0 → 0.10.1

package/README.md

@@ -50,7 +50,33 @@ const result = await spawnTool({
 // { run_id: '...', label: 'reverse-string', supervisor_id: '/path/to/socket' }
 ```
 
-Accepts `agent`, `prompt`, `promptFile`, `label`, `dir`, `timeout`, `model`, `backend`, `serverUrl`, `sessionId`, and `supervisorId` (to target a specific socket).
+Accepts `agent`, `prompt`, `promptFile`, `label`, `dir`, `timeout`, `model`, `thinking`, `backend`, `rosterFile`, `rosterEntry`, `serverUrl`, `sessionId`, and `supervisorId` (to target a specific socket).
+
+### Roster selection
+
+`rosterFile` is the path to a top-level JSON roster map and `rosterEntry` is the key selected from it. Each entry must contain `backend` and at least one of `agent` or `model`:
+
+```json
+{
+  "planner": {
+    "backend": "opencode-acp",
+    "model": "provider/planner"
+  }
+}
+```
+
+A direct roster spawn forwards both selectors and must not also provide `agent`, `model`, or `backend`. Direct mode without a roster allows each of those identity fields to be omitted independently, including a backend-only request; the selected runtime supplies defaults for omitted values. `thinking` is run-level, not a roster field, and is checked against the effective backend. The shared selector validation rejects missing selector pairs, mixed direct/roster fields, and unknown selector keys. Roster-file loading rejects deferred entry fields such as `system`; `thinking` remains a valid run-level option but is never read from a roster entry.
+
+```ts
+await spawnTool({
+  prompt: 'Analyze the repository',
+  dir: '/repo',
+  rosterFile: '/repo/roster.json',
+  rosterEntry: 'planner',
+})
+```
+
+Roster phase selection is resolved by Avenor's Go workflow runners. A roster entry may override backend/agent/model per phase. CLI workflow fallback and nested roster inheritance are CLI-only; stable nesting keeps its existing behavior. A resumed session must use the same effective backend as the original session.
 
 ### `statusTool`
 

package/dist/index.d.ts

@@ -1,6 +1,34 @@
 import { n as getVersion, r as installerBinaryPath, t as getInstallDir } from "./install-path-DagQIDKB.js";
 import * as net from "node:net";
 
+//#region src/thinking-policy.d.ts
+/**
+ * Portable thinking-policy contract.
+ *
+ * THINKING_LEVELS is the single TypeScript source for the canonical tuple and
+ * is exported for hosts (MCP, OpenCode, Pi) to derive their enums from. It is
+ * verified against schemas/thinking_policy.umpire.json and the Go tuple by
+ * introspection and conformance tests so all languages agree.
+ *
+ * The backend policy (which canonical values each backend supports, on start
+ * vs. explicit resume) is modelled directly in the Umpire schema's eitherOf
+ * branches with fairWhen rules and conditions (backend, resume). Both Go and
+ * TypeScript derive the policy from the schema, eliminating hand-written
+ * policy tables that could drift apart.
+ */
+declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+declare function isThinkingLevel(value: string): boolean;
+/** Accepts an empty value (backend default) or a canonical thinking level. */
+declare function validateThinking(value: unknown): void;
+type ThinkingOutcome = 'ok' | 'unsupportedCapability' | 'unsupportedValue' | 'startOnly';
+/** Evaluates the schema-derived backend policy for a (backend, value, resume) combination. */
+declare function evaluateThinkingPolicy(backend: string, value: string, resume?: boolean): ThinkingOutcome;
+/** Accepts a value iff it is valid under the static backend policy (start). */
+declare function validateThinkingForBackend(backend: string, value: unknown): void;
+/** Accepts a value iff it is valid on an explicit resume for the backend. */
+declare function validateThinkingForBackendResume(backend: string, value: unknown): void;
+//#endregion
 //#region src/client.d.ts
 interface Event {
   event: string;
@@ -24,7 +52,6 @@ interface HistoryResult<TEvent = Event> {
   events: TEvent[];
   latest_seq?: number;
 }
-type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 interface SpawnParams {
   agent?: string;
   prompt_file?: string;
@@ -36,13 +63,83 @@ interface SpawnParams {
   thinking?: ThinkingLevel;
   agent_profile?: string;
   backend?: string;
+  roster_file?: string;
+  roster_entry?: string;
   server_url?: string;
   session_id?: string;
   sentinel_file?: string;
+  workflow_id?: string;
+  node_id?: string;
+  activation_id?: string;
+  attempt_id?: string;
   on_event?: string;
   auto_approve?: boolean;
   [key: string]: unknown;
 }
+interface SpawnResult {
+  runtime_id?: string;
+  session_id?: string;
+  on_event?: string;
+  sentinel_file?: string;
+  broker_url?: string;
+  parent_token?: string;
+  agent?: string;
+  agent_profile?: string;
+  model?: string;
+  backend?: string;
+  roster_file?: string;
+  roster_entry?: string;
+  effective_agent?: string;
+  effective_model?: string;
+  effective_backend?: string;
+  [key: string]: unknown;
+}
+interface ExecutionIdentity {
+  supervisor_id?: string;
+  workflow_id?: string;
+  node_id?: string;
+  activation_id?: string;
+  attempt_id?: string;
+  run_id?: string;
+  runtime_id?: string;
+  session_id?: string;
+}
+type WorkflowGateOperation = 'satisfy' | 'reject' | 'waive' | 'external_result';
+interface WorkflowCompleteParams {
+  workflow_id: string;
+  node_id: string;
+  activation_id: string;
+  attempt_id: string;
+  lease_id: string;
+  owner_token: string;
+  outcome: string;
+  outputs?: unknown;
+  artifacts?: unknown;
+}
+interface WorkflowGateParams {
+  workflow_id: string;
+  node_id: string;
+  gate_id: string;
+  activation_id: string;
+  operation: WorkflowGateOperation;
+  actor?: string;
+  reason?: string;
+  outcome?: string;
+  subject?: unknown;
+  poll_id?: string;
+  source?: string;
+  result?: string;
+  response_hash?: string;
+  observed_at?: string;
+  evidence_ids?: string[];
+}
+interface WorkflowHeartbeatParams {
+  workflow_id: string;
+  node_id: string;
+  activation_id?: string;
+  lease_id: string;
+  owner_token: string;
+}
 declare class Client {
   private socket;
   private rl;
@@ -69,12 +166,34 @@ declare class Client {
   status(runtimeId?: string): Promise<Record<string, unknown>>;
   result(runtimeId?: string): Promise<Record<string, unknown>>;
   list(): Promise<Array<Record<string, unknown>>>;
-  spawn(params: SpawnParams): Promise<Record<string, unknown>>;
+  spawn(params: SpawnParams): Promise<SpawnResult>;
   shutdown(mode: string): Promise<void>;
   answerPermission(runtimeId: string, requestId: string, optionId: string, message?: string): Promise<void>;
   prompt(runtimeId: string, text: string): Promise<void>;
   interruptAndPrompt(runtimeId: string, text: string, keepQueue?: boolean): Promise<void>;
   cancel(runtimeId?: string): Promise<void>;
+  workflowStatus(workflowId: string): Promise<Record<string, unknown>>;
+  workflowWait(workflowId: string, timeoutMs?: number): Promise<Record<string, unknown>>;
+  workflowInspect(workflowId: string): Promise<Record<string, unknown>>;
+  workflowEvents(workflowId: string, opts?: {
+    afterSeq?: number;
+    limit?: number;
+  }): Promise<Record<string, unknown>>;
+  workflowCommand(workflowId: string, command: unknown): Promise<Record<string, unknown>>;
+  workflowComplete(params: WorkflowCompleteParams): Promise<Record<string, unknown>>;
+  workflowGate(params: WorkflowGateParams): Promise<Record<string, unknown>>;
+  workflowHeartbeat(params: WorkflowHeartbeatParams): Promise<Record<string, unknown>>;
+  brokerSend(fromRunId: string, toRunId: string, message: string, role?: string): Promise<void>;
+  brokerAsk(toRunId: string, message: string, role?: string): Promise<Record<string, unknown>>;
+  brokerPeers(): Promise<Array<Record<string, unknown>>>;
+  brokerCancel(messageId: string): Promise<void>;
+  brokerReceive(): Promise<Array<{
+    from_run_id: string;
+    message_id: string;
+    message: string;
+    role?: string;
+  }>>;
+  brokerReply(toRunId: string, replyTo: string, message: string): Promise<void>;
   isClosed(): boolean;
   close(): void;
 }
@@ -245,6 +364,11 @@ interface RunInfo {
   agentProfile?: string;
   backend?: string;
   model?: string;
+  effectiveAgent?: string;
+  effectiveModel?: string;
+  effectiveBackend?: string;
+  rosterFile?: string;
+  rosterEntry?: string;
   thinking?: ThinkingLevel;
   dir?: string;
   brokerUrl?: string;
@@ -255,6 +379,14 @@ interface SupervisorOptions {
   binaryPath?: string;
   callTimeoutMs?: number;
 }
+/** Metadata retained locally when a follow-up uses a resolved direct identity. */
+interface SpawnMetadata {
+  rosterFile?: string;
+  rosterEntry?: string;
+  effectiveAgent?: string;
+  effectiveModel?: string;
+  effectiveBackend?: string;
+}
 declare function findAvenorBinary(): string;
 declare class Supervisor {
   private static instance;
@@ -267,6 +399,7 @@ declare class Supervisor {
   private crashed;
   private crashCode;
   private runs;
+  private aliases;
   private binaryPath;
   private callTimeoutMs;
   private constructor();
@@ -277,7 +410,7 @@ declare class Supervisor {
   static isCurrentInstance(supervisorId: string): boolean;
   static currentInstance(): Supervisor | null;
   getClient(): Client;
-  spawn(params: SpawnParams, runId?: `${string}-${string}-${string}-${string}-${string}`): Promise<RunInfo>;
+  spawn(params: SpawnParams, runId?: `${string}-${string}-${string}-${string}-${string}`, metadata?: SpawnMetadata): Promise<RunInfo>;
   close(options?: {
     skipShutdown?: boolean;
   }): Promise<void>;
@@ -286,8 +419,16 @@ declare class Supervisor {
 //#region src/paths.d.ts
 declare function socketsRoot(): string;
 //#endregion
+//#region src/tools/get-supervisor-client.d.ts
+declare function getSupervisorClient(supervisorId: string): Promise<{
+  client: Client;
+  isSingleton: boolean;
+  sup: Supervisor | null;
+  supervisorId: string;
+}>;
+//#endregion
 //#region src/tools/spawn.d.ts
-declare function spawnTool(args: {
+interface SpawnToolArgs {
   agent?: string;
   prompt?: string;
   promptFile?: string;
@@ -298,18 +439,33 @@ declare function spawnTool(args: {
   thinking?: ThinkingLevel;
   agentProfile?: string;
   backend?: string;
+  rosterFile?: string;
+  rosterEntry?: string;
   serverUrl?: string;
   sessionId?: string;
   supervisorId?: string;
   parent_run_id?: string;
-}): Promise<{
+}
+interface SpawnToolResult {
   run_id: string;
   label: string;
   supervisor_id: string;
   runtime_id?: string;
   broker_url?: string;
   parent_token?: string;
-}>;
+}
+declare const spawnTool: (args: SpawnToolArgs) => Promise<SpawnToolResult>;
+//#endregion
+//#region src/spawn-selection.d.ts
+interface SpawnSelectionInput {
+  agent?: string;
+  model?: string;
+  backend?: string;
+  roster_file?: string;
+  roster_entry?: string;
+}
+/** Validate the direct-versus-roster selector contract. */
+declare function validateSpawnSelection(input: unknown, rosterConfigured?: boolean): void;
 //#endregion
 //#region src/tools/status.d.ts
 type StatusView = 'lifecycle' | 'full';
@@ -337,9 +493,15 @@ interface StatusResult {
   };
   session_id?: string;
   stop_reason?: string;
+  roster_file?: string;
+  roster_entry?: string;
   backend?: string;
   agent?: string;
   model?: string;
+  agent_profile?: string;
+  effective_backend?: string;
+  effective_agent?: string;
+  effective_model?: string;
   dir?: string;
   parent_id?: string;
   children?: string[];
@@ -436,6 +598,7 @@ interface FollowUpToolArgs {
 interface FollowUpToolResult {
   run_id: string;
   label: string;
+  runtime_id?: string;
 }
 declare const followUpTool: (args: FollowUpToolArgs) => Promise<FollowUpToolResult>;
 //#endregion
@@ -448,4 +611,128 @@ declare function shutdownTool(args: {
   cleaned_up: string[];
 }>;
 //#endregion
-export { type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type HistoryOptions, type HistoryResult, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type ResultResult, type ResultToolArgs, type RunChunkRole, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnParams, type StatusResult, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, type ThinkingLevel, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool };
+//#region src/tools/ask.d.ts
+interface AskToolArgs {
+  toRunId: string;
+  message: string;
+  supervisorId?: string;
+}
+interface AskResult {
+  reply: string;
+  from_run_id: string;
+}
+declare const askTool: (args: AskToolArgs) => Promise<AskResult>;
+//#endregion
+//#region src/tools/peers.d.ts
+interface PeersToolArgs {
+  supervisorId?: string;
+}
+interface PeerEntry {
+  run_id: string;
+  label?: string;
+  status?: string;
+  backend?: string;
+  model?: string;
+  dir?: string;
+}
+interface PeersResult {
+  peers: PeerEntry[];
+}
+declare const peersTool: (args: PeersToolArgs) => Promise<PeersResult>;
+//#endregion
+//#region src/tools/cancel.d.ts
+interface CancelToolArgs {
+  messageId: string;
+  supervisorId?: string;
+}
+interface CancelResult {
+  cancelled: boolean;
+}
+declare const cancelTool: (args: CancelToolArgs) => Promise<CancelResult>;
+//#endregion
+//#region src/tools/broker-receive.d.ts
+interface BrokerReceiveArgs {
+  supervisorId?: string;
+}
+interface InboundAsk {
+  from_run_id: string;
+  message_id: string;
+  message: string;
+  role?: string;
+}
+interface BrokerReceiveResult {
+  asks: InboundAsk[];
+}
+declare const brokerReceiveTool: (args: BrokerReceiveArgs) => Promise<BrokerReceiveResult>;
+//#endregion
+//#region src/tools/broker-reply.d.ts
+interface BrokerReplyArgs {
+  toRunId: string;
+  replyTo: string;
+  message: string;
+  supervisorId?: string;
+}
+interface BrokerReplyResult {
+  ok: true;
+}
+declare const brokerReplyTool: (args: BrokerReplyArgs) => Promise<BrokerReplyResult>;
+//#endregion
+//#region src/tools/workflow-client.d.ts
+type GetSupervisorClient = typeof getSupervisorClient;
+//#endregion
+//#region src/tools/workflow-status.d.ts
+interface WorkflowStatusToolArgs {
+  workflowId: string;
+  supervisorId?: string;
+}
+type WorkflowStatusResult = Record<string, unknown>;
+declare function createWorkflowStatusTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowStatusToolArgs) => Promise<WorkflowStatusResult>;
+declare const workflowStatusTool: (args: WorkflowStatusToolArgs) => Promise<WorkflowStatusResult>;
+//#endregion
+//#region src/tools/workflow-wait.d.ts
+interface WorkflowWaitToolArgs {
+  workflowId: string;
+  timeout?: string;
+  supervisorId?: string;
+}
+type WorkflowWaitResult = Record<string, unknown>;
+declare function createWorkflowWaitTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowWaitToolArgs) => Promise<WorkflowWaitResult>;
+declare const workflowWaitTool: (args: WorkflowWaitToolArgs) => Promise<WorkflowWaitResult>;
+//#endregion
+//#region src/tools/workflow-inspect.d.ts
+interface WorkflowInspectToolArgs {
+  workflowId: string;
+  supervisorId?: string;
+}
+type WorkflowInspectResult = Record<string, unknown>;
+declare function createWorkflowInspectTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowInspectToolArgs) => Promise<WorkflowInspectResult>;
+declare const workflowInspectTool: (args: WorkflowInspectToolArgs) => Promise<WorkflowInspectResult>;
+//#endregion
+//#region src/tools/workflow-events.d.ts
+interface WorkflowEventsToolArgs {
+  workflowId: string;
+  afterSeq?: number;
+  limit?: number;
+  supervisorId?: string;
+}
+type WorkflowEventsResult = Record<string, unknown>;
+declare function createWorkflowEventsTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowEventsToolArgs) => Promise<WorkflowEventsResult>;
+declare const workflowEventsTool: (args: WorkflowEventsToolArgs) => Promise<WorkflowEventsResult>;
+//#endregion
+//#region src/tools/workflow-complete.d.ts
+interface WorkflowCompleteToolArgs extends WorkflowCompleteParams {
+  supervisorId?: string;
+}
+type WorkflowCompleteResult = Record<string, unknown>;
+declare function createWorkflowCompleteTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowCompleteToolArgs) => Promise<WorkflowCompleteResult>;
+declare const workflowCompleteTool: (args: WorkflowCompleteToolArgs) => Promise<WorkflowCompleteResult>;
+//#endregion
+//#region src/tools/workflow-gate.d.ts
+interface WorkflowGateToolArgs extends WorkflowGateParams {
+  supervisorId?: string;
+}
+type WorkflowGateResult = Record<string, unknown>;
+declare function createWorkflowGateTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowGateToolArgs) => Promise<WorkflowGateResult>;
+declare const workflowGateTool: (args: WorkflowGateToolArgs) => Promise<WorkflowGateResult>;
+//#endregion
+export { type AskResult, type AskToolArgs, type BrokerReceiveArgs, type BrokerReceiveResult, type BrokerReplyArgs, type BrokerReplyResult, type CancelResult, type CancelToolArgs, type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type ExecutionIdentity, type FollowUpToolArgs, type FollowUpToolResult, type HistoryOptions, type HistoryResult, type InboundAsk, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type PeerEntry, type PeersResult, type ResultResult, type ResultToolArgs, type RunChunkRole, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnMetadata, type SpawnParams, type SpawnResult, type SpawnSelectionInput, type SpawnToolArgs, type SpawnToolResult, type StatusResult, type StatusToolArgs, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, THINKING_LEVELS, type ThinkingLevel, type ThinkingOutcome, type WorkflowCompleteParams, type WorkflowCompleteResult, type WorkflowCompleteToolArgs, type WorkflowEventsResult, type WorkflowEventsToolArgs, type WorkflowGateOperation, type WorkflowGateParams, type WorkflowGateResult, type WorkflowGateToolArgs, type WorkflowHeartbeatParams, type WorkflowInspectResult, type WorkflowInspectToolArgs, type WorkflowStatusResult, type WorkflowStatusToolArgs, type WorkflowWaitResult, type WorkflowWaitToolArgs, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, createRunSnapshot, createWorkflowCompleteTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, isThinkingLevel, normalizeRunEvent, observeRun, peersTool, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCompleteTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowStatusTool, workflowWaitTool };