@provos/ironcurtain 0.10.0 → 0.11.0

package/dist/workflow/orchestrator.d.ts

@@ -0,0 +1,450 @@
+import type { WorkflowId, WorkflowDefinition, WorkflowStatus, TransitionRecord, HumanGateRequest, HumanGateEvent } from './types.js';
+import type { ResolvedUserConfig } from '../config/user-config.js';
+import type { BundleId, Session, SessionId, SessionOptions } from '../session/types.js';
+import { type AgentId } from '../docker/agent-adapter.js';
+import { type DockerInfrastructure } from '../docker/docker-infrastructure.js';
+import type { CheckpointStore } from './checkpoint.js';
+import type { ResolvedSkill } from '../skills/types.js';
+/**
+ * Stages the workflow package's `skills/` tree into the run directory
+ * so the workflow becomes self-contained at start time. After this call
+ * the per-run path (`<runMetaDir>/workflow-skills/`) is the canonical
+ * source of workflow-bundled skills for both initial-set staging and
+ * per-state restage; the original package path under
+ * `getWorkflowPackageDir(definitionPath)` is no longer consulted at
+ * runtime.
+ *
+ * Returns the absolute path to the staged copy when source `skills/`
+ * exists and was copied, `undefined` when the source has no `skills/`
+ * directory (the workflow simply ships none — not an error). Throws
+ * only on copy I/O failure, since a half-copied tree would be worse
+ * than a missing one.
+ *
+ * Why copy at start (not symlink): the package directory may be
+ * deleted, moved, or rebuilt between start and resume — symlink chases
+ * lead to "skills silently empty on resume" without diagnostic. A
+ * shallow-recursive copy decouples the run from its source-of-record
+ * location.
+ */
+export declare function stageWorkflowSkillsAtStart(packageDir: string, runMetaDir: string): string | undefined;
+/** Handle for writing to a workflow tab in the mux. */
+export interface WorkflowTabHandle {
+    write(text: string): void;
+    setLabel(label: string): void;
+    close(): void;
+}
+/**
+ * Inputs for creating a workflow-scoped Docker infrastructure bundle.
+ * Supplied by the orchestrator when `settings.sharedContainer === true`
+ * and the workflow uses a Docker agent. One input produces one bundle;
+ * bifurcated workflows invoke the factory once per distinct
+ * `containerScope` their agent states declare.
+ */
+export interface CreateWorkflowInfrastructureInput {
+    readonly workflowId: WorkflowId;
+    /**
+     * Stable key for this bundle. Minted by the orchestrator via
+     * `createBundleId()` before the factory is invoked so both the
+     * coordinator's control-socket path and the bundle's on-disk
+     * directory share the same identifier. Each unique `scope` under a
+     * workflow gets its own fresh `BundleId`.
+     */
+    readonly bundleId: BundleId;
+    readonly agentId: AgentId;
+    /**
+     * Path to the bundle's coordinator control socket. The orchestrator
+     * starts the coordinator's HTTP control server at this path after the
+     * bundle is created (see `startWorkflowControlServer` dep). The path
+     * is included here so the factory may optionally pre-create the
+     * containing directory or use it for labelling.
+     */
+    readonly controlSocketPath: string;
+    /**
+     * Workspace directory for this workflow run. Used as the allowed
+     * directory for the filesystem MCP server and all sessions that run
+     * in the shared container. Either a user-supplied `--workspace <path>`
+     * or the default `<baseDir>/<workflowId>/workspace/`.
+     *
+     * All sessions in a workflow mount the workflow's workspace directory;
+     * no session-scoped sandbox is ever used under shared-container mode.
+     * Scoped bundles share this workspace — isolation happens at the
+     * coordinator/policy level, not the filesystem.
+     */
+    readonly workspacePath: string;
+    /**
+     * Scope label this bundle was minted for. Emitted directly as the
+     * `ironcurtain.scope=<scope>` Docker label on the container and its
+     * sidecar. The orchestrator resolves
+     * `stateConfig.containerScope ?? DEFAULT_CONTAINER_SCOPE` before calling
+     * the factory, so this is always a concrete string.
+     *
+     * See `docs/designs/workflow-session-identity.md` §2.5.
+     */
+    readonly scope: string;
+    /** Union of MCP server names required across every agent state in this scope. */
+    readonly requiredServers: ReadonlySet<string>;
+    /**
+     * Initial skills staged at bundle creation (user + workflow only).
+     * Persona skills are layered in per-state via `bundle.restageSkills`.
+     */
+    readonly resolvedSkills?: readonly ResolvedSkill[];
+}
+/** Inputs for starting the coordinator's HTTP control server on a workflow bundle. */
+export interface StartWorkflowControlServerInput {
+    readonly infra: DockerInfrastructure;
+    readonly socketPath: string;
+}
+/** Inputs for the `loadPolicy` RPC dispatched at each agent state entry. */
+export interface LoadPolicyRpcInput {
+    readonly socketPath: string;
+    readonly persona: string;
+    readonly policyDir: string;
+    /** Hard timeout in milliseconds; the call aborts if the coordinator does not ack in time. */
+    readonly timeoutMs?: number;
+}
+/** Dependencies injected into the orchestrator. */
+export interface WorkflowOrchestratorDeps {
+    /** Factory for creating agent sessions. */
+    readonly createSession: (options: SessionOptions) => Promise<Session>;
+    /** Factory for creating read-only workflow tabs in the mux. */
+    readonly createWorkflowTab: (label: string, workflowId: WorkflowId) => WorkflowTabHandle;
+    /** Callback to raise a human gate in the mux UI. */
+    readonly raiseGate: (gate: HumanGateRequest) => void;
+    /** Callback to dismiss a human gate from the mux UI. */
+    readonly dismissGate: (workflowId: WorkflowId, gateId: string) => void;
+    /** Base directory for workflow artifacts and checkpoints. */
+    readonly baseDir: string;
+    /** Persistent checkpoint store for workflow resume. */
+    readonly checkpointStore: CheckpointStore;
+    /**
+     * Resolved user config. Consulted by `getRequiredServersForScope` to
+     * decide whether to mint the memory relay for a shared-container
+     * bundle (memory is opt-in per persona; see
+     * docs/designs/per-persona-memory-optin.md).
+     */
+    readonly userConfig: ResolvedUserConfig;
+    /**
+     * Factory for creating a workflow-scoped Docker infrastructure bundle.
+     * Called at workflow start when `settings.sharedContainer === true`
+     * and the workflow uses a Docker agent. When omitted, the orchestrator
+     * loads the default implementation lazily from `src/docker/docker-infrastructure.ts`.
+     * Tests override this to avoid spinning up real Docker resources.
+     */
+    readonly createWorkflowInfrastructure?: (input: CreateWorkflowInfrastructureInput) => Promise<DockerInfrastructure>;
+    /**
+     * Teardown counterpart for `createWorkflowInfrastructure`. Called on
+     * workflow terminal states, abort, and shutdownAll. When omitted, the
+     * orchestrator loads the default implementation lazily from
+     * `src/docker/docker-infrastructure.ts`. Tests override this to avoid
+     * touching real Docker resources.
+     */
+    readonly destroyWorkflowInfrastructure?: (infra: DockerInfrastructure) => Promise<void>;
+    /**
+     * Attaches the coordinator's HTTP control server to the workflow
+     * bundle. Called once at workflow start (after the bundle is created)
+     * whenever `settings.sharedContainer === true`. The default
+     * implementation reaches through `infra.proxy.getPolicySwapTarget()` and
+     * calls `startControlServer({ socketPath })`. Tests override this to
+     * intercept the control-server wiring entirely.
+     */
+    readonly startWorkflowControlServer?: (input: StartWorkflowControlServerInput) => Promise<void>;
+    /**
+     * Dispatches a `POST /__ironcurtain/policy/load` request to the
+     * workflow's coordinator control socket. Called before each agent
+     * state invocation to rotate the audit stream and swap the active
+     * policy. The default implementation speaks HTTP/1.1 over a Unix
+     * domain socket (no extra dependency). Tests inject a fake handler
+     * to assert on the RPC shape without standing up a real socket.
+     */
+    readonly loadPolicyRpc?: (input: LoadPolicyRpcInput) => Promise<void>;
+}
+/** Lifecycle events emitted by the orchestrator. */
+export type WorkflowLifecycleEvent = {
+    readonly kind: 'started';
+    readonly workflowId: WorkflowId;
+    readonly name: string;
+    readonly taskDescription: string;
+} | {
+    readonly kind: 'state_entered';
+    readonly workflowId: WorkflowId;
+    readonly state: string;
+} | {
+    readonly kind: 'completed';
+    readonly workflowId: WorkflowId;
+} | {
+    readonly kind: 'failed';
+    readonly workflowId: WorkflowId;
+    readonly error: string;
+} | {
+    readonly kind: 'gate_raised';
+    readonly workflowId: WorkflowId;
+    readonly gate: HumanGateRequest;
+} | {
+    readonly kind: 'gate_dismissed';
+    readonly workflowId: WorkflowId;
+    readonly gateId: string;
+} | {
+    readonly kind: 'agent_started';
+    readonly workflowId: WorkflowId;
+    readonly state: string;
+    readonly persona: string;
+    /**
+     * Session ID of the agent session. Consumers (e.g. the daemon's
+     * token-stream bridge wiring) use this to register the session
+     * so token events produced by this agent are routable to
+     * `observe --all` subscribers.
+     */
+    readonly sessionId: SessionId;
+} | {
+    readonly kind: 'agent_completed';
+    readonly workflowId: WorkflowId;
+    readonly state: string;
+    readonly persona: string;
+    readonly verdict: string;
+}
+/**
+ * Emitted unconditionally in the `executeAgentState` finally block --
+ * both on success (after `agent_completed`) and on failure (when the
+ * agent state threw or the verdict retry failed). Pairs 1:1 with
+ * `agent_started` and signals that the session has been closed.
+ *
+ * Consumers that registered per-agent resources (e.g. token-stream
+ * bridge entries) must clean up in response to this event so no
+ * state leaks across rapid state transitions.
+ */
+ | {
+    readonly kind: 'agent_session_ended';
+    readonly workflowId: WorkflowId;
+    readonly state: string;
+    readonly sessionId: SessionId;
+};
+/** Extended workflow detail for the web UI. */
+export interface WorkflowDetail {
+    readonly definition: WorkflowDefinition;
+    readonly transitionHistory: readonly TransitionRecord[];
+    readonly workspacePath: string;
+    readonly context: {
+        readonly taskDescription: string;
+        readonly round: number;
+        readonly maxRounds: number;
+        readonly totalTokens: number;
+        readonly visitCounts: Record<string, number>;
+    };
+}
+/** The narrow controller interface exposed to the mux. */
+export interface WorkflowController {
+    start(definitionPath: string, taskDescription: string, workspacePath?: string): Promise<WorkflowId>;
+    resume(workflowId: WorkflowId): Promise<void>;
+    listResumable(): WorkflowId[];
+    getStatus(id: WorkflowId): WorkflowStatus | undefined;
+    getDetail(id: WorkflowId): WorkflowDetail | undefined;
+    listActive(): readonly WorkflowId[];
+    resolveGate(id: WorkflowId, event: HumanGateEvent): void;
+    abort(id: WorkflowId): Promise<void>;
+    onEvent(callback: (event: WorkflowLifecycleEvent) => void): void;
+    shutdownAll(): Promise<void>;
+}
+export declare class WorkflowOrchestrator implements WorkflowController {
+    private readonly deps;
+    private readonly workflows;
+    private readonly lifecycleCallbacks;
+    constructor(deps: WorkflowOrchestratorDeps);
+    /** Build a partial log entry with shared fields for the given workflow instance. */
+    private logBase;
+    /**
+     * Validates that all non-"global" personas referenced in the workflow
+     * definition actually exist on disk. Fails fast with a clear error
+     * listing all missing personas.
+     *
+     * Only checks for persona.json existence -- does NOT verify compiled
+     * policy (that happens at session creation time via resolvePersona).
+     */
+    private validatePersonas;
+    /**
+     * Determines whether a workflow should run in shared-container mode.
+     * Requires both an explicit opt-in via `settings.sharedContainer` and
+     * a Docker-backed agent. Builtin workflows ignore the flag entirely.
+     */
+    private shouldUseSharedContainer;
+    /**
+     * Returns the bundle for `scope`, minting a new one on first use.
+     *
+     * Each unique `containerScope` used across the workflow's states gets
+     * exactly one bundle: the first `executeAgentState` call under a given
+     * scope creates the bundle, attaches its coordinator control server,
+     * and inserts the result into `instance.bundlesByScope`. Later states
+     * with the same scope borrow the existing entry (no factory call).
+     *
+     * Replaces the pre-Step-6 eager workflow-start mint. Only invoked when
+     * `shouldUseSharedContainer(definition)` returns true; callers must
+     * gate on that check.
+     *
+     * On control-server attach failure, the just-created bundle is torn
+     * down before the error propagates so we do not leak Docker resources
+     * on partial initialization. The map is **not** populated in that case
+     * — the scope entry remains absent so a later state can retry.
+     *
+     * Concurrency: relies on serial XState invocations — there is no
+     * parallel agent-state fan-out today. If that ever lands, add an
+     * in-flight-promise guard to prevent concurrent lazy-mint races for
+     * the same scope.
+     *
+     * Abort race: if `destroyWorkflowInfrastructure` begins while a mint
+     * is suspended at either `await factory(...)` or `await startServer(...)`,
+     * the mint completes but must not publish into `bundlesByScope` —
+     * destroy already snapshot-cleared the map and would miss the late
+     * insertion. `instance.aborted` is the barrier, consulted at both
+     * `await` points; on observed abort we tear down the just-built
+     * bundle and throw without updating the map.
+     */
+    private ensureBundleForScope;
+    /**
+     * Returns the cached policyDir for `persona`, canonicalizing on first
+     * lookup so required-server derivation and the coordinator's
+     * `loadPolicy` RPC operate on the same realpath-resolved file (any
+     * symlink under the persona dir is collapsed once, here, instead of
+     * re-resolved by every reader).
+     */
+    private getPolicyDir;
+    /**
+     * Computes the union of MCP server names required by every agent state
+     * sharing `scope`. Threaded into the workflow infrastructure factory so
+     * the bundle only spawns proxies the policies actually reference.
+     */
+    private getRequiredServersForScope;
+    /**
+     * Reloads the coordinator's policy for the given persona on the given
+     * bundle. Called once per agent state invocation (including re-entries)
+     * in shared-container mode. The coordinator stamps `persona` onto every
+     * subsequent audit entry, so consumers can reconstruct per-persona /
+     * per-re-entry slices from the bundle's `audit.jsonl` file.
+     *
+     * Each scope owns its own bundle, coordinator, and control socket, so
+     * the bundle is passed explicitly — cycle the scope the state is
+     * about to enter, not some other scope's bundle.
+     *
+     * On failure (control socket unreachable, coordinator reports a load
+     * error) this throws — the workflow must not proceed under the
+     * previous persona's policy.
+     */
+    private cyclePolicy;
+    /**
+     * Tears down every bundle this workflow owns. Walks
+     * `instance.bundlesByScope.values()` in parallel via `Promise.allSettled`
+     * so failures in one bundle's teardown do not block the others. The
+     * map is drained before the awaits so a second concurrent caller (e.g.
+     * `shutdownAll` racing the fire-and-forget destroy in
+     * `handleWorkflowComplete`) sees an empty map and returns without
+     * re-entering `destroy`.
+     *
+     * Callers in recovery paths rely on **expected** failure modes being
+     * swallowed so abort/shutdown flows can complete:
+     *   - Failures in `destroy(infra)` are logged to stderr and swallowed.
+     *   - Failures in socket unlinks are logged and swallowed.
+     *
+     * **One exception — intentional throw on internal invariant violation.**
+     * After teardown the helper asserts `bundlesByScope.size === 0`. A
+     * non-empty map at that point is a bug: something added an entry back
+     * while teardown was in flight. The invariant is enforced by the
+     * abort-guard in `ensureBundleForScope` (post-`factory` flag check);
+     * reaching this throw means the guard has a hole and we want it to
+     * surface loudly rather than silently strand a bundle. Callers are
+     * `abort()`, `shutdownAll()`, and the fire-and-forget `.catch()` in
+     * `handleWorkflowComplete` — in the expected invariant-holds case
+     * none of them see an exception. A thrown leak assertion in
+     * `abort()` / `shutdownAll()` will propagate to their own caller (the
+     * test or CLI layer), which is the intended signal.
+     */
+    private destroyWorkflowInfrastructure;
+    /**
+     * Lazy-loads the default `createDockerInfrastructure` wrapper. The real
+     * helper requires Docker dependencies and the session config, so we
+     * construct them here rather than eagerly at orchestrator construction
+     * time (which would pay the import cost for every workflow run,
+     * including builtin ones that don't need Docker).
+     */
+    private loadDefaultInfrastructureFactory;
+    /** Lazy-loads the default `destroyDockerInfrastructure` helper. */
+    private loadDefaultInfrastructureTeardown;
+    /**
+     * Subscribes the workflow to the global token-stream bus. Accumulates
+     * `message_end.outputTokens` into `instance.tokens.outputTokens` for any
+     * event whose session ID is in `instance.tokens.sessionIds`. The set is managed
+     * by `executeAgentState` (added before `agent_started`, removed in the
+     * `finally` block after `agent_session_ended`).
+     *
+     * Installed synchronously so the subscription is live before any agent
+     * state runs — no window where bus events go unobserved.
+     */
+    private setupTokenSubscription;
+    /**
+     * Tears down the token-stream bus subscription. Idempotent: safe to
+     * call from both normal completion and abort paths.
+     */
+    private teardownTokenSubscription;
+    start(definitionPath: string, taskDescription: string, workspacePath?: string): Promise<WorkflowId>;
+    resume(workflowId: WorkflowId): Promise<void>;
+    /**
+     * Manually executes the invoke service for a state that was restored from
+     * a checkpoint. XState does not re-trigger invocations when an actor is
+     * started from a persisted snapshot, so we run the service ourselves and
+     * send the result event to the actor.
+     */
+    private replayInvokeForRestoredState;
+    listResumable(): WorkflowId[];
+    getStatus(id: WorkflowId): WorkflowStatus | undefined;
+    getDetail(id: WorkflowId): WorkflowDetail | undefined;
+    listActive(): readonly WorkflowId[];
+    resolveGate(id: WorkflowId, event: HumanGateEvent): void;
+    abort(id: WorkflowId): Promise<void>;
+    onEvent(callback: (event: WorkflowLifecycleEvent) => void): void;
+    shutdownAll(): Promise<void>;
+    /** Injects concrete agent/deterministic service implementations into the machine. */
+    private provideActors;
+    /** Subscribes to actor snapshot changes for lifecycle events, gates, and checkpointing. */
+    private subscribeToActor;
+    /**
+     * Returns true if `stateValue` names a terminal state in the workflow
+     * definition. Used to skip checkpointing on the final transition so the
+     * last on-disk checkpoint points at the last non-terminal state (important
+     * for resume-after-abort, which would otherwise reload an `aborted`
+     * snapshot and immediately re-terminate).
+     */
+    private isTerminalStateValue;
+    private buildCheckpoint;
+    private saveCheckpoint;
+    private executeAgentState;
+    private executeDeterministicState;
+    private handleGateEntry;
+    private buildGateRequest;
+    private handleWorkflowComplete;
+    private findMissingArtifacts;
+    private emitLifecycleEvent;
+}
+/**
+ * Default `loadPolicyRpc`: speaks HTTP/1.1 over the supplied UDS using
+ * Node's built-in client. Resolves on a 2xx response; rejects on any
+ * non-2xx status, request timeout, or socket error. The coordinator's
+ * reply body is read only on the error path (to surface the error
+ * text) — 2xx bodies are discarded with `res.resume()`.
+ *
+ * Exported so integration tests can drive the wire format without
+ * standing up a full `WorkflowOrchestrator`. Keeping the HTTP request
+ * construction in one place guarantees tests exercise the same bytes
+ * production emits.
+ */
+export declare function defaultLoadPolicyRpc(input: LoadPolicyRpcInput): Promise<void>;
+/**
+ * Computes a SHA-256 hash of output artifacts or workspace root file metadata.
+ *
+ * Hashes file metadata (path + size + mtime) — never contents. This bounds cost
+ * regardless of artifact size (fuzz logs, captured stderr, etc. can be many GiB
+ * and would otherwise trip Node's 2 GiB `readFile` ceiling). Any agent rewrite
+ * via fs ops bumps mtime, and same-mtime-same-size collisions in a single ms
+ * window are not a concern for workflow change detection.
+ */
+export declare function computeOutputHash(outputNames: readonly string[], artifactDir: string, workspacePath: string): string;
+/**
+ * Collects artifact paths: maps output name -> directory path.
+ */
+export declare function collectArtifactPaths(outputNames: readonly string[], artifactDir: string): Record<string, string>;