@provos/ironcurtain 0.9.1 → 0.11.0

package/dist/workflow/types.d.ts

@@ -0,0 +1,498 @@
+import type { AgentConversationId } from '../session/types.js';
+/**
+ * Directory name for workflow artifacts inside the agent workspace.
+ * All artifact subdirectories (plan/, code/, reviews/, etc.) live under this.
+ */
+export declare const WORKFLOW_ARTIFACT_DIR = ".workflow";
+/**
+ * Reserved persona alias meaning "use the global policy".
+ * When a workflow state specifies this as its persona, the session
+ * factory strips the persona field (same as undefined), so the
+ * session uses the default global compiled policy and memory.
+ *
+ * Any other persona value is passed through to `createSession()`,
+ * which resolves it to a per-persona policy, memory, and prompt.
+ */
+export declare const GLOBAL_PERSONA = "global";
+/**
+ * Sentinel value for an agent state's `skills:` field meaning "no skills
+ * of any kind". Strictly stronger than `[]` (which still loads
+ * user-global + persona skills); this disables every layer.
+ */
+export declare const SKILLS_NONE = "none";
+/**
+ * Translate an agent state's `skills:` field into the subset of
+ * `WorkflowBorrowOptions` that controls skill resolution. `disableAllSkills`
+ * is mutually exclusive with `skillsDir` / `skillFilter`: when the sentinel
+ * is present, only `disableAllSkills: true` is set; otherwise `skillsDir`
+ * and `skillFilter` may co-occur. Used by both the orchestrator and the
+ * run-state CLI so the invariant lives in one place.
+ */
+export declare function resolveWorkflowSkillsOptions(skills: readonly string[] | typeof SKILLS_NONE | undefined, skillsDir: string | undefined): {
+    skillsDir?: string;
+    skillFilter?: ReadonlySet<string>;
+    disableAllSkills?: true;
+};
+/**
+ * Default `containerScope` value assigned to agent states that do not
+ * declare one explicitly. Every such state shares the workflow's primary
+ * bundle. The orchestrator's scope-lookup path resolves
+ * `stateConfig.containerScope ?? DEFAULT_CONTAINER_SCOPE` before dispatch.
+ *
+ * Scope strings are opaque Map lookup keys — they are never embedded in
+ * filesystem paths (bundle directory names use the UUID `bundleId`).
+ *
+ * See `docs/designs/workflow-session-identity.md` §2.4 / §6.
+ */
+export declare const DEFAULT_CONTAINER_SCOPE = "primary";
+/**
+ * Unique identifier for a workflow instance. Branded to prevent accidental
+ * mixing with other string identifiers.
+ */
+export type WorkflowId = string & {
+    readonly __brand: 'WorkflowId';
+};
+/** Creates a new unique WorkflowId. */
+export declare function createWorkflowId(): WorkflowId;
+export interface WorkflowDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly initial: string;
+    readonly states: Record<string, WorkflowStateDefinition>;
+    readonly settings?: WorkflowSettings;
+}
+export interface WorkflowSettings {
+    /** Session mode. Default: 'docker'. */
+    readonly mode?: 'docker' | 'builtin';
+    /** Agent ID for Docker mode. Default: 'claude-code'. */
+    readonly dockerAgent?: string;
+    /** Default max rounds for iterative loops. Default: 4. */
+    readonly maxRounds?: number;
+    /** Git repository path for worktree management. */
+    readonly gitRepoPath?: string;
+    /** Max parallel agent sessions. Default: 3. */
+    readonly maxParallelism?: number;
+    /**
+     * Optional system prompt text appended to the base system prompt
+     * for ALL agent states in this workflow. Use for workspace
+     * conventions, project-level context, or shared instructions.
+     * Sent via --append-system-prompt.
+     */
+    readonly systemPrompt?: string;
+    /**
+     * Per-turn wall-clock timeout in seconds for agent sessions.
+     * Overrides the global resourceBudget.maxSessionSeconds for this workflow.
+     * Default: uses the global setting (1800s / 30 minutes).
+     */
+    readonly maxSessionSeconds?: number;
+    /** Output artifact names excluded from versioning (e.g., append-only journals). */
+    readonly unversionedArtifacts?: readonly string[];
+    /**
+     * Default model ID for all agent states in this workflow.
+     * Format: "provider:model-name" (e.g., "anthropic:claude-sonnet-4-6").
+     * Can be overridden per state via `states.<name>.model`.
+     * Takes precedence over `agentModelId` from user config but is
+     * overridden by the `--model` CLI flag.
+     */
+    readonly model?: string;
+    /**
+     * When true, the workflow runs in shared-container mode: the engine
+     * creates one DockerInfrastructure bundle at workflow start and
+     * reuses it across all states. When false (default), each state
+     * gets a fresh container (today's behavior).
+     *
+     * Shared-container mode is the prerequisite for policy hot-swap at
+     * state transitions. See docs/designs/workflow-container-lifecycle.md.
+     *
+     * Ignored for builtin workflows (no Docker infrastructure to share).
+     */
+    readonly sharedContainer?: boolean;
+}
+/**
+ * State definition. Discriminated on `type`.
+ */
+export type WorkflowStateDefinition = AgentStateDefinition | HumanGateStateDefinition | DeterministicStateDefinition | TerminalStateDefinition;
+export interface AgentStateDefinition {
+    readonly type: 'agent';
+    readonly description: string;
+    readonly persona: string;
+    /**
+     * Role instructions for the agent. Embedded in the full prompt assembled
+     * by the orchestrator; see `buildFirstVisitPrompt` / `buildReVisitPrompt`
+     * in prompt-builder.ts for the section layout. The role prompt is
+     * positioned for recency bias on first visit; re-invocations reuse the
+     * conversation history via `--continue`.
+     */
+    readonly prompt: string;
+    /**
+     * Input artifact names assembled into the agent's command.
+     * Trailing `?` marks optional inputs (no error if absent).
+     */
+    readonly inputs: readonly string[];
+    /** Output artifact names the agent is expected to produce. */
+    readonly outputs: readonly string[];
+    /** Transitions evaluated in order; first match wins. */
+    readonly transitions: readonly AgentTransitionDefinition[];
+    /** When true, each parallel instance gets a dedicated git worktree. */
+    readonly worktree?: boolean;
+    /**
+     * When false, re-invocations of this state resume the previous agent
+     * session via --continue, receiving an abbreviated re-visit prompt.
+     * Use this for iterative refinement loops where the agent benefits
+     * from retaining its prior reasoning (e.g., harness design/build after
+     * critique feedback).
+     *
+     * Default: true (each invocation starts a fresh session, bootstrapping
+     * from artifacts on disk).
+     */
+    readonly freshSession?: boolean;
+    /**
+     * Per-state model override. Format: "provider:model-name".
+     * Takes precedence over `settings.model` at the workflow level.
+     * Overridden only by the `--model` CLI flag.
+     */
+    readonly model?: string;
+    /**
+     * Per-state visit cap. When set, the `isStateVisitLimitReached` guard
+     * returns true once `context.visitCounts[stateId] >= maxVisits`. Use
+     * this to bound an iterative loop (e.g., harness_design_review) and
+     * route to a human gate once the cap is reached. Independent of the
+     * workflow-level `maxRounds` setting.
+     *
+     * Because visit counts are incremented on state entry (before
+     * `invoke`), the guard fires on the onDone transitions of the Nth
+     * visit — i.e., after the Nth invocation completes.
+     */
+    readonly maxVisits?: number;
+    /**
+     * Container scope label. States sharing a scope share a bundle (one
+     * container, one coordinator, one audit log, one control socket);
+     * states with different scopes live in different bundles. When unset,
+     * defaults to `"primary"`, so every state lands on the workflow's
+     * primary bundle by default.
+     *
+     * Meaningful only under `sharedContainer: true`. Under
+     * `sharedContainer: false` (legacy default, one container per state)
+     * declaring a `containerScope` is a validation error — silent no-ops
+     * are footguns; we reject at validate.ts.
+     *
+     * Charset: `/^[a-zA-Z0-9_-]+$/`. Scope strings are opaque Map lookup
+     * keys — they are NEVER embedded in filesystem paths; the on-disk
+     * bundle directory name is the UUID `bundleId`, not the scope.
+     *
+     * See `docs/designs/workflow-session-identity.md` §2.4.
+     */
+    readonly containerScope?: string;
+    /**
+     * Per-state filter on workflow-package skills (`<workflow-pkg>/skills/`).
+     * When omitted (default), the state receives every workflow-package
+     * skill. When set to an array, only the named entries from the
+     * workflow package are layered in — referenced names that do not
+     * exist as `<workflow-pkg>/skills/<name>/SKILL.md` fail validation at
+     * workflow load. User-global skills always apply regardless of this
+     * field. The literal sentinel `'none'` is a true off-switch: no skills
+     * of any kind (workflow-package, user-global, or persona) are loaded
+     * for the state.
+     */
+    readonly skills?: readonly string[] | typeof SKILLS_NONE;
+}
+export interface HumanGateStateDefinition {
+    readonly type: 'human_gate';
+    readonly description: string;
+    /** Event types this gate accepts. Each maps to a HUMAN_* WorkflowEvent. */
+    readonly acceptedEvents: readonly HumanGateEventType[];
+    /** Artifact names to present to the human for review. */
+    readonly present?: readonly string[];
+    /**
+     * Transitions keyed by accepted event type.
+     * Each transition specifies which event triggers it and where to go.
+     */
+    readonly transitions: readonly HumanGateTransitionDefinition[];
+}
+export interface DeterministicStateDefinition {
+    readonly type: 'deterministic';
+    readonly description: string;
+    /**
+     * Commands to execute. Each command is an array of [binary, ...args].
+     * Never a shell string -- per CLAUDE.md safe coding rules.
+     */
+    readonly run: readonly (readonly string[])[];
+    readonly transitions: readonly AgentTransitionDefinition[];
+}
+export interface TerminalStateDefinition {
+    readonly type: 'terminal';
+    readonly description: string;
+    readonly outputs?: readonly string[];
+    readonly cleanup?: readonly (readonly string[])[];
+}
+/** Allowed value types in a `when` clause. Matches AgentOutput field types. */
+export type WhenValue = string | number | boolean | null;
+/**
+ * Per-key typed shape for `when` clauses. Using a mapped type here
+ * enforces compile-time validation of both key names (must be in
+ * AgentOutput) and value types (must match the field's type, e.g.
+ * `completed` must be boolean, `verdict` must be a valid union member).
+ *
+ * Prefer this type over `Readonly<Record<string, WhenValue>>` when
+ * writing workflow definitions in TypeScript.
+ */
+export type WhenClause = {
+    readonly [K in keyof AgentOutput]?: AgentOutput[K];
+};
+/**
+ * Action executed on a transition, in addition to the default context
+ * update actions (updateContextFromAgentResult / ...). Discriminated on
+ * `type`. Implementations live in `machine-builder.ts` — this is a
+ * closed set, not an open extension point.
+ *
+ * Today there is only a single variant, but the discriminated-union
+ * shape is retained so new action types can be added without changing
+ * the surrounding shape of transition definitions.
+ */
+export type WorkflowTransitionAction = {
+    readonly type: 'resetVisitCounts';
+    readonly stateIds: readonly string[];
+};
+export interface AgentTransitionDefinition {
+    readonly to: string;
+    /**
+     * Guard name matching a registered XState guard. No translation
+     * layer -- use names directly: isRoundLimitReached, isStalled, isPassed,
+     * isStateVisitLimitReached. For verdict-based routing, prefer `when`
+     * clauses instead. Mutually exclusive with `when`.
+     */
+    readonly guard?: string;
+    /**
+     * Declarative field-match condition on AgentOutput.
+     * Keys must be valid AgentOutput field names and values must match
+     * the field's type (enforced at compile time via the mapped type).
+     * All entries must match (AND semantics).
+     * Mutually exclusive with `guard`.
+     */
+    readonly when?: WhenClause;
+    /**
+     * Optional ordered list of actions to run on this transition, in
+     * addition to the default context-update action. Actions execute
+     * in the order listed.
+     */
+    readonly actions?: readonly WorkflowTransitionAction[];
+}
+export interface HumanGateTransitionDefinition {
+    readonly to: string;
+    /** The accepted event type that triggers this transition. */
+    readonly event: HumanGateEventType;
+    /**
+     * Optional ordered list of actions to run on this transition, in
+     * addition to the default gate context-update actions (storeHumanPrompt,
+     * clearError). Actions execute in the order listed.
+     */
+    readonly actions?: readonly WorkflowTransitionAction[];
+}
+export type HumanGateEventType = 'APPROVE' | 'FORCE_REVISION' | 'REPLAN' | 'ABORT';
+export declare const CONFIDENCE_VALUES: readonly ["high", "medium", "low"];
+export type Confidence = (typeof CONFIDENCE_VALUES)[number];
+/** Structured output parsed from the agent's response text. */
+export interface AgentOutput {
+    /**
+     * @deprecated Maintained for backward compatibility. Defaults to `true`
+     * at parse time. Workflows should use free-form `verdict` strings for
+     * routing decisions instead of relying on this boolean.
+     */
+    readonly completed: boolean;
+    /** Free-form verdict string. Well-known values: approved, rejected, blocked, spec_flaw. Workflows may define custom verdicts for direct routing. */
+    readonly verdict: string;
+    /**
+     * @deprecated Maintained for backward compatibility. Defaults to `'high'`
+     * at parse time. Should not be relied upon for routing decisions; use
+     * `verdict` and `notes` instead.
+     */
+    readonly confidence: Confidence;
+    /**
+     * @deprecated Maintained for backward compatibility. Defaults to `null`
+     * at parse time. Use `notes` for inter-agent context instead.
+     */
+    readonly escalation: string | null;
+    /**
+     * @deprecated Maintained for backward compatibility. Defaults to `null`
+     * at parse time. Should not be relied upon for routing decisions.
+     */
+    readonly testCount: number | null;
+    readonly notes: string | null;
+}
+/** Valid keys for `when` clauses. Must match AgentOutput field names. */
+export declare const AGENT_OUTPUT_FIELDS: readonly ["completed", "verdict", "confidence", "escalation", "testCount", "notes"];
+export type WorkflowEvent = {
+    readonly type: 'AGENT_COMPLETED';
+    readonly output: AgentOutput;
+} | {
+    readonly type: 'VALIDATION_PASSED';
+    readonly testCount: number;
+} | {
+    readonly type: 'VALIDATION_FAILED';
+    readonly errors: string;
+} | {
+    readonly type: 'HUMAN_APPROVE';
+    readonly prompt?: string;
+} | {
+    readonly type: 'HUMAN_FORCE_REVISION';
+    readonly prompt?: string;
+} | {
+    readonly type: 'HUMAN_REPLAN';
+    readonly prompt?: string;
+} | {
+    readonly type: 'HUMAN_ABORT';
+} | {
+    readonly type: 'PARALLEL_ALL_COMPLETED';
+    readonly results: readonly ParallelSlotResult[];
+} | {
+    readonly type: 'PARALLEL_SLOT_FAILED';
+    readonly key: string;
+    readonly error: string;
+} | {
+    readonly type: 'MERGE_SUCCEEDED';
+} | {
+    readonly type: 'MERGE_CONFLICT';
+    readonly conflictDetails: string;
+};
+export interface WorkflowContext {
+    readonly taskDescription: string;
+    readonly artifacts: Record<string, string>;
+    readonly round: number;
+    readonly maxRounds: number;
+    /** Per-role output hash for stall detection. */
+    readonly previousOutputHashes: Record<string, string>;
+    readonly previousTestCount: number | null;
+    readonly humanPrompt: string | null;
+    readonly reviewHistory: readonly string[];
+    readonly parallelResults: Record<string, ParallelSlotResult>;
+    readonly worktreeBranches: readonly string[];
+    readonly totalTokens: number;
+    readonly lastError: string | null;
+    /**
+     * Maps a stateId to the agent-CLI conversation id assigned on the last
+     * successful invocation of that state. Consumed by `freshSession: false`
+     * re-entries so the CLI can `--resume` the prior conversation.
+     *
+     * See `docs/designs/workflow-session-identity.md` §2.4.
+     */
+    readonly agentConversationsByState: Record<string, AgentConversationId>;
+    /**
+     * Response text from the last completed agent state, with the trailing
+     * `agent_status` YAML block stripped. Truncated at 32KB. Used as the
+     * "body" portion of the "Scoping from the previous agent" section in the
+     * next agent's prompt — carries the full directive, not just the summary.
+     */
+    readonly previousAgentOutput: string | null;
+    /**
+     * The `notes` field from the last agent's `agent_status` block. Rendered
+     * as the "Notes" sub-section under "Scoping from the previous agent".
+     * When the orchestrator writes a bare status block with no directive, this
+     * is often the only surviving scoping signal.
+     */
+    readonly previousAgentNotes: string | null;
+    /**
+     * The state name that produced `previousAgentOutput`. Used to
+     * label the output in the next agent's prompt.
+     */
+    readonly previousStateName: string | null;
+    /**
+     * Per-state visit counter. Maps state ID to the number of times
+     * that state has been entered. Used for first-visit vs re-visit
+     * prompt selection and per-state round limit checking.
+     */
+    readonly visitCounts: Readonly<Record<string, number>>;
+}
+export type WorkflowStatus = {
+    readonly phase: 'running';
+    readonly currentState: string;
+    readonly activeAgents: readonly AgentSlot[];
+} | {
+    readonly phase: 'waiting_human';
+    readonly gate: HumanGateRequest;
+} | {
+    readonly phase: 'completed';
+    readonly result: WorkflowResult;
+} | {
+    readonly phase: 'failed';
+    readonly error: string;
+    readonly lastState: string;
+} | {
+    readonly phase: 'aborted';
+    readonly reason: string;
+};
+export interface AgentSlot {
+    readonly stateId: string;
+    readonly persona: string;
+}
+export interface WorkflowResult {
+    readonly finalArtifacts: Record<string, string>;
+}
+export interface ParallelSlotResult {
+    readonly key: string;
+    readonly status: 'success' | 'failed';
+    readonly error?: string;
+    readonly worktreeBranch?: string;
+}
+export interface HumanGateRequest {
+    readonly gateId: string;
+    readonly workflowId: string;
+    readonly stateName: string;
+    readonly acceptedEvents: readonly HumanGateEventType[];
+    readonly presentedArtifacts: ReadonlyMap<string, string>;
+    readonly summary: string;
+}
+/**
+ * JSON-serializable view of HumanGateRequest. The domain type's
+ * `presentedArtifacts` is a `ReadonlyMap` which doesn't JSON-encode;
+ * the DTO replaces it with the artifact names as a plain array.
+ */
+export interface HumanGateRequestDto {
+    readonly gateId: string;
+    readonly workflowId: string;
+    readonly stateName: string;
+    readonly acceptedEvents: readonly string[];
+    /** Artifact names only (not content). */
+    readonly presentedArtifacts: readonly string[];
+    readonly summary: string;
+}
+export declare function toHumanGateRequestDto(gate: HumanGateRequest): HumanGateRequestDto;
+export interface HumanGateEvent {
+    readonly type: HumanGateEventType;
+    readonly prompt?: string;
+}
+export interface WorkflowCheckpoint {
+    /** Serialized XState snapshot.value (string or nested object). */
+    readonly machineState: unknown;
+    readonly context: WorkflowContext;
+    readonly timestamp: string;
+    readonly transitionHistory: readonly TransitionRecord[];
+    readonly definitionPath: string;
+    /** Workspace root directory. Used on resume to reconstruct artifactDir. */
+    readonly workspacePath?: string;
+    /**
+     * Per-run staged copy of the workflow package's `skills/` tree (when
+     * the package shipped one). The orchestrator copies this at start
+     * under `<baseDir>/<workflowId>/workflow-skills/` so the run is
+     * self-contained: resume reads from the staged copy regardless of
+     * whether the original package path is still on disk. Absent when
+     * the workflow ships no skills, and absent on legacy checkpoints
+     * written before this field existed (resume falls back to re-staging
+     * from `definitionPath`'s package dir).
+     */
+    readonly workflowSkillsDir?: string;
+    /**
+     * Terminal-phase status, populated only when the workflow has reached a terminal
+     * phase (completed / aborted / failed / waiting_human). Absent for mid-run
+     * checkpoints and for legacy retained checkpoints written before this field existed.
+     */
+    readonly finalStatus?: WorkflowStatus;
+}
+export interface TransitionRecord {
+    readonly from: string;
+    readonly to: string;
+    readonly event: string;
+    readonly timestamp: string;
+    readonly duration_ms: number;
+    /** Summary of the agent's output that produced this transition (if any). */
+    readonly agentMessage?: string;
+}

package/dist/workflow/types.js

@@ -0,0 +1,83 @@
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Directory name for workflow artifacts inside the agent workspace.
+ * All artifact subdirectories (plan/, code/, reviews/, etc.) live under this.
+ */
+export const WORKFLOW_ARTIFACT_DIR = '.workflow';
+/**
+ * Reserved persona alias meaning "use the global policy".
+ * When a workflow state specifies this as its persona, the session
+ * factory strips the persona field (same as undefined), so the
+ * session uses the default global compiled policy and memory.
+ *
+ * Any other persona value is passed through to `createSession()`,
+ * which resolves it to a per-persona policy, memory, and prompt.
+ */
+export const GLOBAL_PERSONA = 'global';
+/**
+ * Sentinel value for an agent state's `skills:` field meaning "no skills
+ * of any kind". Strictly stronger than `[]` (which still loads
+ * user-global + persona skills); this disables every layer.
+ */
+export const SKILLS_NONE = 'none';
+/**
+ * Translate an agent state's `skills:` field into the subset of
+ * `WorkflowBorrowOptions` that controls skill resolution. `disableAllSkills`
+ * is mutually exclusive with `skillsDir` / `skillFilter`: when the sentinel
+ * is present, only `disableAllSkills: true` is set; otherwise `skillsDir`
+ * and `skillFilter` may co-occur. Used by both the orchestrator and the
+ * run-state CLI so the invariant lives in one place.
+ */
+export function resolveWorkflowSkillsOptions(skills, skillsDir) {
+    if (skills === SKILLS_NONE)
+        return { disableAllSkills: true };
+    const result = {};
+    if (skillsDir !== undefined)
+        result.skillsDir = skillsDir;
+    if (Array.isArray(skills))
+        result.skillFilter = new Set(skills);
+    return result;
+}
+/**
+ * Default `containerScope` value assigned to agent states that do not
+ * declare one explicitly. Every such state shares the workflow's primary
+ * bundle. The orchestrator's scope-lookup path resolves
+ * `stateConfig.containerScope ?? DEFAULT_CONTAINER_SCOPE` before dispatch.
+ *
+ * Scope strings are opaque Map lookup keys — they are never embedded in
+ * filesystem paths (bundle directory names use the UUID `bundleId`).
+ *
+ * See `docs/designs/workflow-session-identity.md` §2.4 / §6.
+ */
+export const DEFAULT_CONTAINER_SCOPE = 'primary';
+/** Creates a new unique WorkflowId. */
+export function createWorkflowId() {
+    return randomUUID();
+}
+// ---------------------------------------------------------------------------
+// Agent output
+// ---------------------------------------------------------------------------
+export const CONFIDENCE_VALUES = ['high', 'medium', 'low'];
+/** Valid keys for `when` clauses. Must match AgentOutput field names. */
+export const AGENT_OUTPUT_FIELDS = [
+    'completed',
+    'verdict',
+    'confidence',
+    'escalation',
+    'testCount',
+    'notes',
+];
+export function toHumanGateRequestDto(gate) {
+    return {
+        gateId: gate.gateId,
+        workflowId: gate.workflowId,
+        stateName: gate.stateName,
+        acceptedEvents: gate.acceptedEvents,
+        presentedArtifacts: Array.from(gate.presentedArtifacts.keys()),
+        summary: gate.summary,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/workflow/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA0D,EAC1D,SAA6B;IAM7B,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;IAC9D,MAAM,MAAM,GAA8D,EAAE,CAAC;IAC7E,IAAI,SAAS,KAAK,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAChE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAYjD,uCAAuC;AACvC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,EAAgB,CAAC;AACpC,CAAC;AAoQD,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAC;AAgCpE,yEAAyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,WAAW;IACX,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,OAAO;CAC0C,CAAC;AA+HpD,MAAM,UAAU,qBAAqB,CAAC,IAAsB;IAC1D,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,kBAAkB,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QAC9D,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC"}

package/dist/workflow/validate.d.ts

@@ -0,0 +1,58 @@
+import type { WorkflowDefinition, WorkflowStateDefinition } from './types.js';
+export declare class WorkflowValidationError extends Error {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+/**
+ * Parses a workflow input artifact reference. A trailing `?` marks the
+ * input as optional — the consumer may skip it if the artifact isn't
+ * produced.
+ */
+export declare function parseArtifactRef(ref: string): {
+    readonly name: string;
+    readonly isOptional: boolean;
+};
+export declare function collectOutputArtifacts(states: Record<string, WorkflowStateDefinition>): Set<string>;
+export declare function findReachableStates(initial: string, states: Record<string, WorkflowStateDefinition>): Set<string>;
+/**
+ * One issue produced by {@link iterateSkillRefIssues}. Surface code
+ * (validate vs lint) formats the user-facing wording.
+ */
+export type SkillRefIssue = {
+    kind: 'invalid-name';
+    stateId: string;
+    name: string;
+    detail: string;
+} | {
+    kind: 'unknown-name';
+    stateId: string;
+    name: string;
+};
+/**
+ * Walks every agent state's `skills[]` and yields a structured issue
+ * per offending entry, classifying shape failures (`invalid-name`)
+ * separately from membership failures (`unknown-name`). Shape-first:
+ * an entry that fails the shape check is yielded as such and not
+ * checked for membership, which would otherwise emit a confusing
+ * "skill not found" message for inputs that were never valid names.
+ */
+export declare function iterateSkillRefIssues(definition: WorkflowDefinition, discoveredNames: ReadonlySet<string>): Generator<SkillRefIssue>;
+/**
+ * Verifies every `skills[]` entry on an agent state matches a SKILL.md
+ * frontmatter `name:` under `<packageDir>/skills/`. Membership is
+ * keyed on the frontmatter name (also what `workflowSkillFilter` in
+ * `src/skills/discovery.ts` matches), not the directory name —
+ * `existsSync` on the dir would miss dir-vs-frontmatter mismatches.
+ * Called from orchestrator `start()` only.
+ *
+ * @throws {WorkflowValidationError} when any entry is invalid or unknown
+ */
+export declare function validateWorkflowSkillReferences(definition: WorkflowDefinition, packageDir: string): void;
+/**
+ * Validates a parsed object as a WorkflowDefinition.
+ * Performs structural parsing (Zod) then semantic checks.
+ * The input can come from JSON.parse() or YAML.parse().
+ *
+ * @throws {WorkflowValidationError} with structured list of issues
+ */
+export declare function validateDefinition(raw: unknown): WorkflowDefinition;