@provos/ironcurtain 0.9.1 → 0.11.0

package/dist/workflow/lint.js

@@ -0,0 +1,410 @@
+/**
+ * Workflow semantic linter. Receives a `WorkflowDefinition` that has
+ * already passed `validateDefinition()` and returns `Diagnostic`s for
+ * higher-level smells (cross-cutting or requiring external context)
+ * that structural validation deliberately leaves alone.
+ *
+ * See `docs/designs/workflow-semantic-linter-v2.md` for each check's
+ * rationale.
+ */
+import { resolve } from 'node:path';
+import { GLOBAL_PERSONA } from './types.js';
+import { findReachableStates, iterateSkillRefIssues, parseArtifactRef } from './validate.js';
+import { getWorkflowPackageDir } from './discovery.js';
+import { ACTIONABLE_DISCOVERY_REASONS, discoverSkillsWithErrors } from '../skills/discovery.js';
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * Runs all registered checks against `def`. Pure: same input => same
+ * output. Diagnostics come back in stable order (WF001 first, WF007 last).
+ */
+export function lintWorkflow(def, ctx) {
+    const reachable = findReachableStates(def.initial, def.states);
+    const reachableAgentOutputs = collectReachableAgentOutputs(def, reachable);
+    return [
+        ...checkUnreachableTerminal(def, reachable),
+        ...checkUnversionedArtifacts(def, reachableAgentOutputs),
+        ...checkTerminalOutputs(def, reachable, reachableAgentOutputs),
+        ...checkHumanGatePresent(def, reachable, reachableAgentOutputs),
+        ...checkMaxRoundsHasGuard(def),
+        ...checkPersonaExists(def, ctx),
+        ...checkVisitCapTransitionOrder(def),
+        ...checkSkillReferencesAndManifests(def, ctx),
+    ];
+}
+export function countBySeverity(diagnostics) {
+    let errors = 0;
+    let warnings = 0;
+    for (const d of diagnostics) {
+        if (d.severity === 'error')
+            errors++;
+        else
+            warnings++;
+    }
+    return { errors, warnings };
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/**
+ * Output artifacts produced by reachable agent states. Terminal
+ * `outputs:` are declarations of expected arrival state, not production
+ * (no runtime code writes them), so they don't count: WF002/WF003/WF004
+ * all ask "is this name actually produced?"
+ */
+function collectReachableAgentOutputs(def, reachable) {
+    const outputs = new Set();
+    for (const [stateId, state] of Object.entries(def.states)) {
+        if (!reachable.has(stateId))
+            continue;
+        if (state.type === 'agent') {
+            for (const o of state.outputs)
+                outputs.add(o);
+        }
+    }
+    return outputs;
+}
+function isAgentState(state) {
+    return state.type === 'agent';
+}
+// ---------------------------------------------------------------------------
+// WF001 — State can't reach any terminal
+// ---------------------------------------------------------------------------
+function checkUnreachableTerminal(def, reachable) {
+    const diagnostics = [];
+    for (const stateId of reachable) {
+        const state = def.states[stateId];
+        if (state.type === 'terminal')
+            continue;
+        const cone = findReachableStates(stateId, def.states);
+        let touchesTerminal = false;
+        for (const target of cone) {
+            if (def.states[target].type === 'terminal') {
+                touchesTerminal = true;
+                break;
+            }
+        }
+        if (!touchesTerminal) {
+            diagnostics.push({
+                code: 'WF001',
+                severity: 'error',
+                stateId,
+                message: `State "${stateId}" cannot reach any terminal state — the workflow will loop forever if it enters this state.`,
+                hint: 'Add a transition (guarded or unconditional) whose forward graph eventually reaches a terminal state.',
+            });
+        }
+    }
+    return diagnostics;
+}
+// ---------------------------------------------------------------------------
+// WF002 — unversionedArtifacts entry not produced by any state
+// ---------------------------------------------------------------------------
+function checkUnversionedArtifacts(def, produced) {
+    const entries = def.settings?.unversionedArtifacts ?? [];
+    if (entries.length === 0)
+        return [];
+    const diagnostics = [];
+    for (const name of entries) {
+        if (!produced.has(name)) {
+            diagnostics.push({
+                code: 'WF002',
+                severity: 'warning',
+                message: `settings.unversionedArtifacts entry "${name}" is not produced by any state — it will be silently versioned.`,
+                hint: "Remove the entry, or add the artifact to some agent state's outputs list.",
+            });
+        }
+    }
+    return diagnostics;
+}
+// ---------------------------------------------------------------------------
+// WF003 — terminal.outputs entry not produced by any reachable state
+// ---------------------------------------------------------------------------
+function checkTerminalOutputs(def, reachable, produced) {
+    const diagnostics = [];
+    for (const [stateId, state] of Object.entries(def.states)) {
+        if (state.type !== 'terminal')
+            continue;
+        if (!reachable.has(stateId))
+            continue;
+        for (const name of state.outputs ?? []) {
+            if (!produced.has(name)) {
+                diagnostics.push({
+                    code: 'WF003',
+                    severity: 'warning',
+                    stateId,
+                    message: `Terminal "${stateId}" lists output "${name}" which is not produced by any reachable state.`,
+                    hint: 'Remove the output from the terminal, or ensure a reachable agent state produces it.',
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+// ---------------------------------------------------------------------------
+// WF004 — human_gate present entry not produced by any reachable state
+// ---------------------------------------------------------------------------
+function checkHumanGatePresent(def, reachable, produced) {
+    const diagnostics = [];
+    for (const [stateId, state] of Object.entries(def.states)) {
+        if (state.type !== 'human_gate')
+            continue;
+        if (!reachable.has(stateId))
+            continue;
+        for (const entry of state.present ?? []) {
+            const { name } = parseArtifactRef(entry);
+            if (!produced.has(name)) {
+                diagnostics.push({
+                    code: 'WF004',
+                    severity: 'error',
+                    stateId,
+                    message: `Human gate "${stateId}" presents artifact "${name}" which is not produced by any reachable state — the human will approve without seeing it.`,
+                    hint: 'Fix the artifact name, or ensure a reachable agent state produces it.',
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+// ---------------------------------------------------------------------------
+// WF006 — maxRounds set without any isRoundLimitReached guard
+// ---------------------------------------------------------------------------
+const ROUND_LIMIT_GUARD = 'isRoundLimitReached';
+function checkMaxRoundsHasGuard(def) {
+    if (def.settings?.maxRounds === undefined)
+        return [];
+    for (const state of Object.values(def.states)) {
+        if (state.type !== 'agent' && state.type !== 'deterministic')
+            continue;
+        for (const t of state.transitions) {
+            if (t.guard === ROUND_LIMIT_GUARD)
+                return [];
+        }
+    }
+    return [
+        {
+            code: 'WF006',
+            severity: 'warning',
+            message: `settings.maxRounds=${def.settings.maxRounds} is set but no transition uses the "isRoundLimitReached" guard — the limit is silently ignored.`,
+            hint: 'Add a transition with guard: isRoundLimitReached to an iterative state, or remove maxRounds.',
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// WF007 — agent persona not installed
+// ---------------------------------------------------------------------------
+/**
+ * Flags any agent state whose `persona` is neither the reserved
+ * `GLOBAL_PERSONA` alias nor an installed persona directory.
+ *
+ * Emitted as a warning (not error) because personas are user-local state:
+ * a workflow author may legitimately ship a definition that depends on
+ * a persona the user hasn't installed yet. `--strict-lint` promotes this
+ * to a failure.
+ */
+function checkPersonaExists(def, ctx) {
+    const diagnostics = [];
+    for (const [stateId, state] of Object.entries(def.states)) {
+        if (!isAgentState(state))
+            continue;
+        const persona = state.persona;
+        if (persona === GLOBAL_PERSONA)
+            continue;
+        if (ctx.personaExists(persona))
+            continue;
+        diagnostics.push({
+            code: 'WF007',
+            severity: 'warning',
+            stateId,
+            message: `Agent state "${stateId}" references persona "${persona}" which is not installed locally — session creation will fail at runtime.`,
+            hint: `Install the persona with: ironcurtain persona create ${persona}, or change the state's persona to "${GLOBAL_PERSONA}".`,
+        });
+    }
+    return diagnostics;
+}
+// ---------------------------------------------------------------------------
+// WF008 — visit-cap guard must precede loop-continuing transitions
+// ---------------------------------------------------------------------------
+/**
+ * Verdict values that indicate an approval-style exit from a bounded loop.
+ * Transitions taken on these verdicts represent the success path out of the
+ * loop, so a visit-cap guard is legitimately ordered AFTER them (on the cap
+ * visit, if the agent still emits `approved`, we take the approval exit
+ * rather than escalating).
+ *
+ * Any other `when` verdict (rejected, rejected_build, blocked, or any
+ * workflow-specific loop-continuation verdict) must NOT precede the cap
+ * guard: if it did, the cap would never fire and the loop is effectively
+ * unbounded except for the workflow-wide `maxRounds`.
+ */
+const VISIT_CAP_GUARD = 'isStateVisitLimitReached';
+const APPROVAL_EXIT_VERDICTS = new Set(['approved', 'complete', 'done', 'success', 'passed']);
+/**
+ * Returns true if `t.when` represents an approval-style exit. Approval
+ * exits are allowed to precede the visit-cap guard. Everything else is
+ * considered loop-continuing for the purposes of WF008 — including:
+ *   - no `when` clause at all (always matches)
+ *   - empty `when: {}` (always matches; flagged separately by validation)
+ *   - a verdict not in the approval allowlist
+ *   - a `when` clause that sets fields other than `verdict` (future-
+ *     proofing: those match something other than the approval verdict)
+ */
+function isApprovalExitTransition(t) {
+    if (!t.when)
+        return false;
+    const keys = Object.keys(t.when);
+    if (keys.length === 0)
+        return false;
+    if (keys.length !== 1 || keys[0] !== 'verdict')
+        return false;
+    const verdict = t.when.verdict;
+    return typeof verdict === 'string' && APPROVAL_EXIT_VERDICTS.has(verdict);
+}
+function checkVisitCapTransitionOrder(def) {
+    const diagnostics = [];
+    for (const [stateId, state] of Object.entries(def.states)) {
+        if (!isAgentState(state))
+            continue;
+        if (state.maxVisits === undefined)
+            continue;
+        const transitions = state.transitions;
+        const capIndex = transitions.findIndex((t) => t.guard === VISIT_CAP_GUARD);
+        if (capIndex === -1)
+            continue;
+        // Find the first loop-continuing transition that precedes the cap.
+        for (let i = 0; i < capIndex; i++) {
+            const t = transitions[i];
+            if (isApprovalExitTransition(t))
+                continue;
+            // `t` is either unconditional, a non-approval `when`, or a different
+            // guard — all of which can match before the cap guard is evaluated.
+            const descriptor = describeTransition(t);
+            diagnostics.push({
+                code: 'WF008',
+                severity: 'error',
+                stateId,
+                message: `State "${stateId}" has maxVisits=${state.maxVisits} with an "${VISIT_CAP_GUARD}" ` +
+                    `transition at position ${capIndex + 1}, but a loop-continuing transition (${descriptor}) ` +
+                    `at position ${i + 1} will match first on every iteration, so the visit cap is never ` +
+                    `reached and the loop is effectively unbounded except by settings.maxRounds.`,
+                hint: `Move the "${VISIT_CAP_GUARD}" transition above any non-approval "when" clause ` +
+                    `(only ${Array.from(APPROVAL_EXIT_VERDICTS).join('/')} verdicts may precede the cap).`,
+            });
+            // One diagnostic per state is sufficient; multiple preceding loop-
+            // continuing transitions all share the same fix.
+            break;
+        }
+    }
+    return diagnostics;
+}
+function describeTransition(t) {
+    if (t.guard)
+        return `guard: ${t.guard} -> ${t.to}`;
+    if (t.when) {
+        const parts = Object.entries(t.when).map(([k, v]) => `${k}: ${JSON.stringify(v)}`);
+        return `when { ${parts.join(', ')} } -> ${t.to}`;
+    }
+    return `unconditional -> ${t.to}`;
+}
+// ---------------------------------------------------------------------------
+// WF010 — skill references and skill-manifest integrity
+// ---------------------------------------------------------------------------
+/**
+ * Entry point for WF010. Skips cleanly when `ctx.workflowFilePath` is
+ * absent (in-memory definitions have no package dir to scan).
+ * `checkSkillManifests` runs independently of any state reference so
+ * a typo'd frontmatter — which would silently disappear from
+ * discovery — still surfaces.
+ */
+function checkSkillReferencesAndManifests(def, ctx) {
+    if (!ctx.workflowFilePath)
+        return [];
+    const skillsRoot = resolve(getWorkflowPackageDir(ctx.workflowFilePath), 'skills');
+    const { skills, errors } = discoverSkillsWithErrors(skillsRoot, 'workflow');
+    return [...checkSkillManifests(errors), ...checkSkillReferences(def, skills, skillsRoot)];
+}
+function checkSkillManifests(errors) {
+    const diagnostics = [];
+    for (const err of errors) {
+        if (!ACTIONABLE_DISCOVERY_REASONS.has(err.reason))
+            continue;
+        diagnostics.push({
+            code: 'WF010',
+            severity: 'error',
+            ...buildSkillManifestDiagnostic(err),
+        });
+    }
+    return diagnostics;
+}
+function buildSkillManifestDiagnostic(err) {
+    const detail = err.detail ?? err.reason;
+    // Switch is exhaustive over `SkillDiscoveryErrorReason`. No `default`:
+    // a new union member must add a case here or TypeScript will flag the
+    // missing return-type coverage at compile time.
+    switch (err.reason) {
+        case 'malformed-frontmatter':
+            return {
+                message: `Malformed SKILL.md frontmatter at ${err.skillDir}: ${detail}.`,
+                hint: 'Fix the YAML frontmatter (the block fenced by `---` lines at the top of SKILL.md).',
+            };
+        case 'missing-required-fields':
+            return {
+                message: `SKILL.md at ${err.skillDir} is missing required frontmatter fields: ${detail}.`,
+                hint: 'SKILL.md frontmatter must declare both `name:` and `description:` as strings.',
+            };
+        case 'unreadable':
+            return {
+                message: `Unreadable SKILL.md at ${err.skillDir}: ${detail}.`,
+                hint: 'Check filesystem permissions or whether the path is a directory.',
+            };
+        case 'missing-manifest':
+            return {
+                message: `Missing SKILL.md at ${err.skillDir}: ${detail}.`,
+                hint: 'Create a SKILL.md file with a `---`-fenced YAML frontmatter declaring `name:` and `description:`.',
+            };
+        case 'duplicate-name':
+            return {
+                message: `Duplicate skill at ${err.skillDir}: ${detail}.`,
+                hint: 'Two skill directories under the same skills root cannot share the same frontmatter `name:`. Rename one in its SKILL.md frontmatter.',
+            };
+    }
+}
+/**
+ * Walks every agent state's `skills?: string[]` and emits one
+ * diagnostic per offending entry — either an invalid name (rejected by
+ * `validateSkillName`) or a name that does not match any discovered
+ * skill's frontmatter `name:` under `<packageDir>/skills/`. The
+ * frontmatter name is the user-facing identifier (matched by
+ * `workflowSkillFilter` in `src/skills/discovery.ts`), not the
+ * directory name. The orchestrator's `validateWorkflowSkillReferences`
+ * throws for the same conditions at start; surfacing them at lint time
+ * gives authors fast feedback before they hit runtime.
+ */
+function checkSkillReferences(def, discovered, skillsRoot) {
+    const discoveredNames = new Set(discovered.map((s) => s.name));
+    const available = [...discoveredNames].sort();
+    const availableHint = available.length > 0 ? available.join(', ') : '(none)';
+    const diagnostics = [];
+    for (const issue of iterateSkillRefIssues(def, discoveredNames)) {
+        if (issue.kind === 'invalid-name') {
+            diagnostics.push({
+                code: 'WF010',
+                severity: 'error',
+                stateId: issue.stateId,
+                message: `Invalid skill name "${issue.name}" in state "${issue.stateId}": ${issue.detail}.`,
+                hint: 'Skill names must be a single non-empty path segment with no separators or "."/"..".',
+            });
+        }
+        else {
+            diagnostics.push({
+                code: 'WF010',
+                severity: 'error',
+                stateId: issue.stateId,
+                message: `State "${issue.stateId}" references skill "${issue.name}" but no skill with that frontmatter name was found under ${skillsRoot}. Available: ${availableHint}.`,
+                hint: `Add a SKILL.md under <workflow-pkg>/skills/ whose frontmatter \`name:\` is "${issue.name}", or remove "${issue.name}" from the state's skills list.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=lint.js.map

package/dist/workflow/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/workflow/lint.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,90 @@
+import { type AnyStateMachine } from 'xstate';
+import type { WorkflowDefinition, WorkflowContext, AgentStateDefinition, AgentOutput } from './types.js';
+import type { AgentConversationId } from '../session/types.js';
+/** 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;
+}
+/** Result from a deterministic (test/lint) state. */
+export interface DeterministicInvokeResult {
+    readonly passed: boolean;
+    readonly testCount?: number;
+    readonly errors?: string;
+}
+export interface BuildMachineResult {
+    /** The XState machine (with placeholder actors). */
+    readonly machine: 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'>;
+/**
+ * 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): BuildMachineResult;