@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/workflow/machine-builder.d.ts

@@ -0,0 +1,178 @@
+import { type AnyStateMachine } from 'xstate';
+import type { WorkflowDefinition, WorkflowContext, AgentStateDefinition, DeterministicStateDefinition, AgentOutput } from './types.js';
+import type { AgentConversationId } from '../session/types.js';
+type ExecutableStateDefinition = AgentStateDefinition | DeterministicStateDefinition;
+/** Input provided to each invoked agent service. */
+export interface AgentInvokeInput {
+    readonly stateId: string;
+    readonly stateConfig: AgentStateDefinition;
+    readonly context: WorkflowContext;
+}
+/** Result returned by an agent service promise. */
+export interface AgentInvokeResult {
+    readonly output: AgentOutput;
+    /**
+     * Agent CLI conversation id used for this invocation. Minted or reused
+     * by the orchestrator before session construction (see
+     * `executeAgentState` and `docs/designs/workflow-session-identity.md`
+     * §3). Threaded through the result only so the
+     * `updateContextFromAgentResult` XState action can write it into
+     * `agentConversationsByState[stateId]`; not a read-back from the
+     * session.
+     */
+    readonly agentConversationId: AgentConversationId;
+    readonly artifacts: Record<string, string>;
+    /** SHA-256 of output artifacts, computed by the orchestrator. */
+    readonly outputHash: string;
+    /** Raw response text from session.sendMessage(). */
+    readonly responseText: string;
+    /**
+     * Cumulative workflow-level output-token count at the moment this
+     * agent finished. Copied onto `ctx.totalTokens` by the XState
+     * `updateContextFromAgentResult` assign action. Sourced from the
+     * orchestrator's token-stream bus subscription, which sums every
+     * `message_end.outputTokens` seen for sessions belonging to this
+     * workflow run.
+     */
+    readonly totalTokens: number;
+}
+/** Input provided to each invoked deterministic service. */
+export interface DeterministicInvokeInput {
+    readonly stateId: string;
+    readonly commands: readonly (readonly string[])[];
+    readonly context: WorkflowContext;
+    readonly container?: boolean;
+    readonly containerScope?: string;
+    readonly timeoutMs?: number;
+    readonly resultFile?: string;
+}
+/** Result from a deterministic (test/lint) state. */
+export interface DeterministicInvokeResult {
+    readonly passed: boolean;
+    readonly testCount?: number;
+    readonly errors?: string;
+    readonly verdict?: string;
+    readonly payload?: Record<string, unknown>;
+}
+/**
+ * Input provided to a parent fan-out state invoke. `stateConfig` carries the
+ * `fanOut`/`segment` markers the orchestrator reads to resolve the worker
+ * count and the round sub-chain; `context` is the parent's context at fan-out
+ * time, cloned into each lane's child actor.
+ */
+export interface FanOutInvokeInput {
+    readonly stateId: string;
+    readonly stateConfig: ExecutableStateDefinition;
+    readonly context: WorkflowContext;
+}
+/**
+ * The three synthetic terminal states every child round machine carries are
+ * `recorded`/`blocked`/`errored` (see `buildRoundChildDefinition`). `drained`
+ * is not a child terminal; it is the parent-side outcome synthesized for a
+ * peer actor stopped by drain-on-escalation after another child blocked or
+ * errored. Typed as a closed union so the join's branches are
+ * exhaustive-checkable.
+ */
+export type RoundChildStatus = 'recorded' | 'blocked' | 'errored' | 'drained';
+/**
+ * The fully-resolved result of joining one child round actor: the terminal
+ * it reached plus the context it carried there. `context` is read by the
+ * parent to thread per-lane updates (e.g. the `evaluator_blocked` reason on
+ * `previousAgentOutput`) back onto the parent FSM after the barrier.
+ */
+export interface RoundChildOutcome {
+    readonly index: number;
+    readonly status: RoundChildStatus;
+    readonly context: WorkflowContext;
+    readonly drainedBy?: {
+        readonly index: number;
+        readonly status: 'blocked' | 'errored';
+        readonly reason: string;
+    };
+}
+/**
+ * Per-lane summary surfaced on the fan-out result for observability. When a lane
+ * was `drained` (stopped because a peer blocked/errored), `drainedBy` names the
+ * triggering peer and carries its reason, so the join log records WHICH lane's
+ * escalation stopped this one — signal the bare `drained` status alone lacks.
+ */
+export interface RoundChildSummary {
+    readonly index: number;
+    readonly status: RoundChildStatus;
+    readonly drainedBy?: {
+        readonly index: number;
+        readonly status: 'blocked' | 'errored';
+        readonly reason: string;
+    };
+}
+/**
+ * Result returned by the fan-out pump after all children have joined. Shaped
+ * as a `DeterministicInvokeResult` so the parent `workers` state's transitions
+ * match on `verdict` exactly like a normal deterministic state. The verdict
+ * space is `recorded` (batch advanced) | `escalate` (at least one lane blocked;
+ * route to human review) | `result_file_error` (errored-only lane / segment
+ * misconfiguration). `context` is the joined context promoted onto the parent
+ * FSM; `children` is the per-lane status summary, for observability only.
+ */
+export interface FanOutInvokeResult extends DeterministicInvokeResult {
+    readonly context: WorkflowContext;
+    readonly children?: readonly RoundChildSummary[];
+}
+export interface BuildMachineResult {
+    /** The XState machine (with placeholder actors). */
+    readonly machine: AnyStateMachine;
+    /** Child round machines keyed by the parent fan-out state that invokes them. */
+    readonly roundMachinesByState: ReadonlyMap<string, AnyStateMachine>;
+    /** Set of state names that are human gates (for snapshot.matches()). */
+    readonly gateStateNames: ReadonlySet<string>;
+    /** Set of state names that are terminal (for completion detection). */
+    readonly terminalStateNames: ReadonlySet<string>;
+}
+/**
+ * Sanitizes agent response text for reuse in subsequent prompts: escapes any
+ * literal NUL bytes and truncates to stay within the 32KB limit.
+ *
+ * NUL escaping is load-bearing, not cosmetic. Agent output flows back into
+ * later prompts via `previousAgentOutput` / `previousAgentNotes`, which the
+ * Docker adapter passes as an argv element to `child_process.spawn`. Node
+ * refuses argv strings containing `\0` (`ERR_INVALID_ARG_VALUE`) and throws
+ * synchronously before the container even starts — aborting the workflow. A
+ * security-research agent describing a binary file format ("APP1 'Exif\\0\\0'")
+ * is the natural way this happens. We escape rather than strip so the textual
+ * description survives intact for downstream readers.
+ *
+ * Exported for testing.
+ */
+export declare function truncateAgentOutput(text: string): string;
+/**
+ * Creates the initial WorkflowContext for a given definition.
+ * Exported for testing.
+ */
+export declare function createInitialContext(definition: WorkflowDefinition): Omit<WorkflowContext, 'taskDescription'>;
+interface BuildWorkflowMachineOptions {
+    readonly contextFromInput?: boolean;
+    readonly buildRoundMachines?: boolean;
+    /**
+     * When set, every executable state's `onError` routes here instead of the
+     * `findErrorTarget` heuristic. Used by the child round-machine build: a
+     * child definition has no gate / `failed` / `aborted` terminal, so
+     * `findErrorTarget` would fall through to the first synthetic terminal
+     * (`recorded`) and silently treat a crashed lane as a recorded round.
+     * Forcing `onErrorTarget: 'errored'` makes a service rejection land in the
+     * `errored` lane-verdict terminal, where the barrier maps it to a fail.
+     */
+    readonly onErrorTarget?: string;
+}
+/**
+ * Builds an XState v5 machine from a validated WorkflowDefinition.
+ *
+ * The returned machine has placeholder actors (`agentService`,
+ * `deterministicService`) that throw if invoked directly. Callers
+ * must call `.provide({ actors: { ... } })` to inject real
+ * implementations before passing to `createActor()`.
+ *
+ * Guards are registered with concrete implementations from the guards
+ * module. Actions for context updates are defined inline via `assign`.
+ */
+export declare function buildWorkflowMachine(definition: WorkflowDefinition, taskDescription: string, options?: BuildWorkflowMachineOptions): BuildMachineResult;
+export {};