@netnodeag/kraftwerk 0.2.0

package/dist/yaml.js

@@ -0,0 +1,324 @@
+import { mkdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { Ajv } from "ajv";
+import { parse } from "yaml";
+import { envelopeContract } from "./envelope.js";
+import { containsText, fileNonEmpty, slotsFilled } from "./gates.js";
+import { Run } from "./run.js";
+import { summaryTable } from "./stats.js";
+import { runStamp } from "./workflow.js";
+/**
+ * YAML-configured workflows (v1: a linear sequence of gated agent steps).
+ * Vocabulary borrows from GitHub Actions: `steps`, `runs-on` (the harness),
+ * `${{ request }}` / `${{ agent }}` interpolation.
+ *
+ * Canonical form is a FOLDER:
+ *
+ *   src/workflows/tagline/
+ *     workflow.yml        # agents inline + steps; validated against
+ *     prompts/            # schema/workflow.schema.json
+ *       analysieren.md    # referenced from a step: `prompt: prompts/analysieren.md`
+ *
+ * In folder mode, single-line `prompt:`, `persona:`, and `workspace:` values
+ * are treated as file references inside the folder; multiline values stay
+ * inline. A single `.yml` file (everything inline) is still supported.
+ *
+ * Steps come in two kinds: agent steps (`agent` + `prompt`) and deterministic
+ * script steps (`run`: a bash script, single-line value = file reference).
+ *
+ * MCP servers live alongside the workflow: a top-level `mcp:` map (stdio
+ * command/args/env or remote url), agents opt in via `mcp: [names]` —
+ * governance like tools. Relative server files (e.g. mcp/multiply-server.ts)
+ * are resolved inside the folder.
+ *
+ * CLIs work the same way: a top-level `clis:` map (command prefix -> one-line
+ * usage hint), agents opt in via `clis: [names]`. The hint is injected into
+ * the agent's persona once — step prompts never repeat it.
+ *
+ * Validation: structural pass against the JSON Schema (ajv) first, then
+ * semantic checks (agent references, duplicate step names, variables,
+ * referenced files). The engine appends the envelope contract to every step
+ * prompt itself. Not in v1 (roadmap): approval loops,
+ * AGENTS.md-style context files, skills.
+ */
+const GATE_HINT = "Gates: file_non_empty: <file> | slots_filled: <file> | contains: {file, text, label?}";
+const VARIABLES = ["request", "agent"];
+let compiledSchema;
+async function schemaValidator() {
+    if (!compiledSchema) {
+        const schema = JSON.parse(await readFile(new URL("../schema/workflow.schema.json", import.meta.url), "utf8"));
+        compiledSchema = new Ajv({ allErrors: true }).compile(schema);
+    }
+    return compiledSchema;
+}
+const STEP_HINT = "Step: agent step {name, agent, prompt, gates?} OR script step {name, run, gates?}";
+const MCP_HINT = "MCP servers: {command, args?, env?} (stdio) OR {url} (remote streamable HTTP)";
+const CLI_HINT = "CLIs: <command prefix>: <one-line usage hint> — name e.g. git, ddev, npm run (no special characters)";
+function formatAjvErrors(errors, file) {
+    // oneOf mismatches (gates, steps, mcp) explode into per-branch errors; keep it readable.
+    const relevant = errors.filter((e) => e.keyword !== "oneOf" || !/\/gates\/|\/steps\/\d+$|^\/mcp\//.test(e.instancePath));
+    const lines = relevant.slice(0, 4).map((e) => {
+        const where = e.instancePath || "/";
+        if (e.keyword === "additionalProperties") {
+            return `${where}: unknown key "${e.params.additionalProperty}"`;
+        }
+        if (e.keyword === "enum") {
+            return `${where}: allowed values are ${e.params.allowedValues?.join(", ")}`;
+        }
+        return `${where}: ${e.message}`;
+    });
+    const gateHint = errors.some((e) => e.instancePath.includes("/gates/")) ? `\n${GATE_HINT}` : "";
+    const stepHint = errors.some((e) => e.keyword === "oneOf" && /\/steps\/\d+$/.test(e.instancePath))
+        ? `\n${STEP_HINT}`
+        : "";
+    const mcpHint = errors.some((e) => e.instancePath.startsWith("/mcp/")) ? `\n${MCP_HINT}` : "";
+    const cliHint = errors.some((e) => e.instancePath.startsWith("/clis")) ? `\n${CLI_HINT}` : "";
+    return `${file}: schema validation failed\n${lines.map((l) => `  - ${l}`).join("\n")}${gateHint}${stepHint}${mcpHint}${cliHint}`;
+}
+/** Names from `requires:` that are missing/empty in the current environment. */
+export const missingEnv = (requires) => requires.filter((name) => !process.env[name]);
+/**
+ * Load a workflow from a folder (`<dir>/workflow.yml` + referenced files)
+ * or from a single `.yml`/`.yaml` file (everything inline).
+ */
+export async function loadWorkflow(givenPath) {
+    const stats = await stat(givenPath).catch(() => null);
+    if (!stats)
+        throw new Error(`${givenPath}: not found`);
+    let yamlPath = givenPath;
+    let baseDir;
+    if (stats.isDirectory()) {
+        baseDir = givenPath;
+        const candidates = ["workflow.yml", "workflow.yaml"];
+        const found = [];
+        for (const c of candidates) {
+            if (await stat(path.join(givenPath, c)).catch(() => null))
+                found.push(c);
+        }
+        if (found.length === 0) {
+            throw new Error(`${path.basename(givenPath)}/: contains no workflow.yml`);
+        }
+        yamlPath = path.join(givenPath, found[0]);
+    }
+    const file = baseDir
+        ? `${path.basename(baseDir)}/${path.basename(yamlPath)}`
+        : path.basename(yamlPath);
+    const fail = (message) => {
+        throw new Error(`${file}: ${message}`);
+    };
+    let raw;
+    try {
+        raw = parse(await readFile(yamlPath, "utf8"));
+    }
+    catch (err) {
+        return fail(`unreadable YAML: ${err.message}`);
+    }
+    // 1) Structural validation against the JSON Schema.
+    const validate = await schemaValidator();
+    if (!validate(raw)) {
+        throw new Error(formatAjvErrors(validate.errors ?? [], file));
+    }
+    // Single-line values in folder mode reference files inside the folder.
+    const resolveText = async (value, field) => {
+        const line = value.trim();
+        if (!baseDir || line.includes("\n"))
+            return value.trim();
+        const candidate = path.resolve(baseDir, line);
+        if (!candidate.startsWith(path.resolve(baseDir) + path.sep)) {
+            return fail(`${field}: "${line}" is outside the workflow folder`);
+        }
+        const content = await readFile(candidate, "utf8").catch(() => null);
+        if (content !== null)
+            return content.trim();
+        if (line.includes("/") || /\.(md|txt|sh)$/.test(line)) {
+            return fail(`${field}: referenced file "${line}" not found`);
+        }
+        return value.trim();
+    };
+    // 2) Semantic checks + resolution.
+    const workspace = raw.workspace ? await resolveText(raw.workspace, "workspace") : "";
+    // MCP servers stored alongside the workflow. Stdio args that resolve to a
+    // file relative to the folder become absolute (the server process is later
+    // spawned from the run directory); absolute paths and URLs pass through —
+    // that's the external-MCP case.
+    const mcpBase = baseDir ?? path.dirname(yamlPath);
+    const mcpDefs = new Map();
+    for (const [name, cfg] of Object.entries(raw.mcp ?? {})) {
+        if ("url" in cfg) {
+            mcpDefs.set(name, { url: cfg.url });
+            continue;
+        }
+        const resolvedArgs = [];
+        for (const arg of (cfg.args ?? [])) {
+            if (path.isAbsolute(arg)) {
+                resolvedArgs.push(arg);
+                continue;
+            }
+            const candidate = path.resolve(mcpBase, arg);
+            if (await stat(candidate).catch(() => null)) {
+                resolvedArgs.push(candidate);
+            }
+            else if (/\.(ts|mts|cts|js|mjs|cjs|py|sh)$/.test(arg)) {
+                fail(`mcp.${name}: server file "${arg}" not found`);
+            }
+            else {
+                resolvedArgs.push(arg); // flags like -y, package names like tsx
+            }
+        }
+        mcpDefs.set(name, {
+            command: cfg.command,
+            ...(resolvedArgs.length > 0 ? { args: resolvedArgs } : {}),
+            ...(cfg.env ? { env: cfg.env } : {}),
+        });
+    }
+    // CLIs available to agents: command prefix -> one-line usage hint (may be
+    // empty). Purely declarative; agents opt in below.
+    const cliDefs = new Map(Object.entries(raw.clis ?? {}).map(([name, hint]) => [name, String(hint ?? "")]));
+    const agents = new Map();
+    for (const [id, a] of Object.entries(raw.agents ?? {})) {
+        const mcp = {};
+        for (const serverName of (a.mcp ?? [])) {
+            const def = mcpDefs.get(serverName);
+            if (!def) {
+                fail(`agents.${id}.mcp: server "${serverName}" is not defined under mcp` +
+                    ` (available: ${[...mcpDefs.keys()].join(", ") || "—"})`);
+            }
+            mcp[serverName] = def;
+        }
+        if (Object.keys(mcp).length > 0 && a["runs-on"] === "pi") {
+            fail(`agents.${id}: runs-on "pi" does not support MCP — use claude or codex`);
+        }
+        const clis = {};
+        for (const cliName of (a.clis ?? [])) {
+            if (!cliDefs.has(cliName)) {
+                fail(`agents.${id}.clis: CLI "${cliName}" is not defined under clis` +
+                    ` (available: ${[...cliDefs.keys()].join(", ") || "—"})`);
+            }
+            clis[cliName] = cliDefs.get(cliName);
+        }
+        agents.set(id, {
+            id,
+            name: a.name ?? id,
+            model: a.model,
+            effort: a.effort,
+            tools: a.tools,
+            persona: await resolveText(a.persona, `agents.${id}.persona`),
+            harness: a["runs-on"],
+            ...(Object.keys(clis).length > 0 ? { clis } : {}),
+            ...(Object.keys(mcp).length > 0 ? { mcp } : {}),
+        });
+    }
+    const seen = new Set();
+    const steps = [];
+    for (const [i, s] of raw.steps.entries()) {
+        const at = (message) => fail(`steps[${i}]: ${message}`);
+        if (seen.has(s.name))
+            at(`step name "${s.name}" is a duplicate`);
+        seen.add(s.name);
+        const gates = (s.gates ?? []).map((g, j) => buildGate(g, (message) => fail(`steps[${i}].gates[${j}]: ${message}`)));
+        if (s.run !== undefined) {
+            const script = await resolveText(s.run, `steps[${i}].run`);
+            for (const match of script.matchAll(/\$\{\{\s*(\w+)\s*\}\}/g)) {
+                if (match[1] !== "request") {
+                    at(`unknown variable \${{ ${match[1]} }} — run steps only support \${{ request }} (plus env: REQUEST, RUN_DIR, PHASE, WORKFLOW_DIR)`);
+                }
+            }
+            steps.push({ kind: "script", name: s.name, script, gates });
+            continue;
+        }
+        const agent = agents.get(s.agent);
+        if (!agent) {
+            at(`agent "${s.agent}" is not defined under agents (available: ${[...agents.keys()].join(", ")})`);
+        }
+        const prompt = await resolveText(s.prompt, `steps[${i}].prompt`);
+        for (const match of prompt.matchAll(/\$\{\{\s*(\w+)\s*\}\}/g)) {
+            if (!VARIABLES.includes(match[1])) {
+                at(`unknown variable \${{ ${match[1]} }} — available: ${VARIABLES.join(", ")}`);
+            }
+        }
+        steps.push({ kind: "agent", name: s.name, agent: agent, prompt, gates });
+    }
+    const requires = raw.requires ?? [];
+    return {
+        name: raw.name,
+        description: raw.description,
+        meta: {
+            agents: [...agents.values()],
+            steps: steps.map((s) => s.name),
+            requires,
+        },
+        async run({ request, verbose }) {
+            const missing = missingEnv(requires);
+            if (missing.length > 0) {
+                throw new Error(`Workflow "${raw.name}" needs environment variables that are missing: ${missing.join(", ")}` +
+                    ` (declared under requires: in ${file})`);
+            }
+            // KRAFTWERK_RUN_DIR lets an outer runner (sandbox, web trigger) pick
+            // the run directory upfront so it can mount/watch it by name.
+            const runDir = process.env.KRAFTWERK_RUN_DIR
+                ? path.resolve(process.env.KRAFTWERK_RUN_DIR)
+                : path.resolve("output", `run-${runStamp()}`);
+            await mkdir(runDir, { recursive: true });
+            const run = new Run({
+                runDir,
+                verbose,
+                workspaceContext: [
+                    `Working directory (read and create all files here): ${runDir}`,
+                    workspace,
+                ]
+                    .filter(Boolean)
+                    .join("\n\n"),
+            });
+            await run.trace("run_start", {
+                workflow: raw.name,
+                description: raw.description,
+                request,
+                steps: steps.map((s) => s.kind === "script"
+                    ? { name: s.name, kind: "script" }
+                    : { name: s.name, kind: "agent", agent: s.agent.id, model: s.agent.model }),
+            });
+            for (const step of steps) {
+                if (step.kind === "script") {
+                    await run.scriptPhase({
+                        name: step.name,
+                        script: step.script.replace(/\$\{\{\s*request\s*\}\}/g, request),
+                        gates: step.gates,
+                        env: {
+                            REQUEST: request,
+                            ...(baseDir ? { WORKFLOW_DIR: path.resolve(baseDir) } : {}),
+                        },
+                    });
+                    continue;
+                }
+                const prompt = step.prompt
+                    .replace(/\$\{\{\s*request\s*\}\}/g, request)
+                    .replace(/\$\{\{\s*agent\s*\}\}/g, step.agent.id);
+                await run.agentPhase({
+                    name: step.name,
+                    agent: step.agent,
+                    prompt: `${prompt}\n\n${envelopeContract(step.name)}`,
+                    gates: step.gates,
+                });
+            }
+            await run.printSummary();
+            console.log(`\nArtifacts: ${runDir}`);
+            return { runDir, phases: run.stats, total: summaryTable(run.stats).total };
+        },
+    };
+}
+/** Back-compat alias for the single-file entry point. */
+export const loadWorkflowYaml = loadWorkflow;
+/** One YAML gate entry (single-key mapping, schema-checked) -> a Gate. */
+function buildGate(g, at) {
+    const [gateName, value] = Object.entries(g)[0];
+    switch (gateName) {
+        case "file_non_empty":
+            return fileNonEmpty(value);
+        case "slots_filled":
+            return slotsFilled(value);
+        case "contains":
+            return containsText(value.file, value.text, value.label ?? value.text);
+        default:
+            return at(`unknown gate "${gateName}" — ${GATE_HINT}`);
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@netnodeag/kraftwerk",
+  "version": "0.2.0",
+  "description": "Deterministic workflow-as-code framework: agents (persona + model + tools + harness) run in bounded phases on headless CLI harnesses (claude -p, codex exec, pi); code owns the control flow, envelopes + gates judge the results",
+  "keywords": ["agents", "workflow", "orchestration", "llm", "claude", "codex", "automation", "cli"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NETNODEAG/kraftwerk.git",
+    "directory": "kraftwerk"
+  },
+  "homepage": "https://github.com/NETNODEAG/kraftwerk#readme",
+  "bugs": { "url": "https://github.com/NETNODEAG/kraftwerk/issues" },
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "files": [
+    "bin",
+    "dist",
+    "runner",
+    "schema"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "validate": "tsx src/validate.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "ajv": "^8.20.0",
+    "chalk": "^6.0.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^15.0.0",
+    "ora": "^9.4.1",
+    "yaml": "^2.9.0"
+  },
+  "bin": {
+    "kraftwerk": "bin/kraftwerk.js"
+  }
+}

package/runner/Dockerfile

@@ -0,0 +1,43 @@
+# kraftwerk-runner — sandbox image for isolated workflow runs.
+#
+# Build (from the framework directory):
+#   kraftwerk runner build          # or:
+#   docker build -t kraftwerk-runner -f runner/Dockerfile .
+#
+# One container per run: the runner mounts the workflow folder read-only,
+# bind-mounts the host run directory, injects env vars, and executes
+# `kraftwerk run` inside. See src/runner/docker.ts.
+
+# node >= 24: workflows may ship TypeScript MCP servers that node runs
+# directly (native type stripping).
+FROM node:24-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      bash python3 curl ca-certificates openssh-client git procps jq \
+    && rm -rf /var/lib/apt/lists/*
+
+# Agent harness CLIs used by workflows (headless: claude -p, codex exec).
+RUN npm install -g @anthropic-ai/claude-code @openai/codex
+
+# The framework itself, installed from the build context. Ships the
+# compiled dist/ (tsx is a devDependency and not installed here) — run
+# `npm run build` before building the image from a dev checkout.
+WORKDIR /opt/kraftwerk
+COPY package.json ./
+RUN npm install --omit=dev
+COPY bin ./bin
+COPY schema ./schema
+COPY dist ./dist
+RUN ln -s /opt/kraftwerk/bin/kraftwerk.js /usr/local/bin/kraftwerk \
+    && chmod +x /opt/kraftwerk/bin/kraftwerk.js
+
+# Consumer project skeleton: the runner mounts the workflow folder into
+# src/workflows/<name> and the run dir into output/<run-id>. The MCP SDK +
+# zod are preinstalled so workflow-local MCP servers (mcp/*.ts) resolve
+# their imports, mirroring the consumer's node_modules.
+WORKDIR /work
+RUN mkdir -p src/workflows output \
+    && printf '{"name":"kraftwerk-sandbox","private":true}\n' > package.json \
+    && npm install --no-fund --no-audit @modelcontextprotocol/sdk zod
+
+ENV HOME=/root

package/schema/workflow.schema.json

@@ -0,0 +1,244 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json",
+  "title": "kraftwerk workflow",
+  "description": "A linear workflow of gated agent steps. Folder form: <name>/workflow.yml, where single-line prompt/persona/workspace values may reference files inside the folder (e.g. prompts/step.md).",
+  "type": "object",
+  "required": ["name", "description", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Workflow id used on the CLI: npm start -- <name> \"<request>\""
+    },
+    "description": {
+      "type": "string",
+      "description": "One-liner shown in the CLI workflow listing"
+    },
+    "workspace": {
+      "type": "string",
+      "description": "Workspace context appended to every agent's system prompt (file layout etc.). Single-line value = path to a file inside the workflow folder."
+    },
+    "requires": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "description": "Environment variables the workflow needs (API tokens etc.). Checked before the run starts; missing variables abort with a clear error instead of failing mid-run."
+    },
+    "mcp": {
+      "type": "object",
+      "description": "MCP servers stored alongside the workflow, keyed by server name. Agents opt in via their mcp: [names] list.",
+      "propertyNames": { "pattern": "^[A-Za-z0-9_-]+$" },
+      "additionalProperties": { "$ref": "#/definitions/mcpServer" }
+    },
+    "clis": {
+      "type": "object",
+      "description": "CLIs agents may call via Bash, keyed by command prefix (e.g. git, ddev, npm run) with a one-line usage hint (may be empty). Agents opt in via their clis: [names] list; the hint is injected into the agent's persona once — never repeat it in step prompts. claude scopes its Bash allowlist to Bash(<name>:*); codex runs commands in its sandbox anyway; pi gets the plain bash tool (no scoping).",
+      "propertyNames": { "pattern": "^[A-Za-z0-9@_.][A-Za-z0-9@_. /-]*$" },
+      "additionalProperties": {
+        "type": ["string", "null"],
+        "description": "One-line usage hint injected into the granting agent's persona; empty/null = name only"
+      }
+    },
+    "agents": {
+      "type": "object",
+      "minProperties": 1,
+      "description": "Agent roster: id -> definition",
+      "additionalProperties": { "$ref": "#/definitions/agent" }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Linear sequence of gated steps: agent steps (agent + prompt) or deterministic script steps (run)",
+      "items": { "$ref": "#/definitions/step" }
+    }
+  },
+  "definitions": {
+    "agent": {
+      "type": "object",
+      "required": ["model", "tools", "persona"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Display name, defaults to the agent id"
+        },
+        "description": {
+          "type": "string",
+          "description": "Informational only"
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Model id in the harness's naming, e.g. haiku, claude-opus-5, gpt-5.6-sol, deepseek/deepseek-chat"
+        },
+        "effort": {
+          "enum": ["low", "medium", "high", "xhigh", "max"],
+          "description": "Reasoning effort; omit for the model default"
+        },
+        "runs-on": {
+          "enum": ["claude", "codex", "pi"],
+          "description": "Harness that executes this agent (default: claude)"
+        },
+        "tools": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Governance: the only tools the agent may use, e.g. [Read, Write, Edit, WebFetch]"
+        },
+        "persona": {
+          "type": "string",
+          "minLength": 1,
+          "description": "System prompt: role, voice, rules. Single-line value = path to a file inside the workflow folder."
+        },
+        "mcp": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "MCP servers this agent may use (names from the top-level mcp map). Governance like tools. Not supported on runs-on: pi."
+        },
+        "clis": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "CLIs this agent may use (names from the top-level clis map). Their usage hints are injected into the persona; claude additionally scopes the Bash allowlist to these commands."
+        }
+      }
+    },
+    "mcpServer": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["command"],
+          "additionalProperties": false,
+          "properties": {
+            "command": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Executable that starts the stdio MCP server, e.g. node or npx"
+            },
+            "args": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Arguments; an arg that resolves to a file inside the workflow folder is made absolute (e.g. mcp/multiply-server.ts)"
+            },
+            "env": {
+              "type": "object",
+              "additionalProperties": { "type": "string" },
+              "description": "Extra environment variables for the server process"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["url"],
+          "additionalProperties": false,
+          "properties": {
+            "url": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Remote streamable-HTTP MCP server, e.g. https://mcp.linear.app/mcp"
+            }
+          }
+        }
+      ]
+    },
+    "step": {
+      "oneOf": [
+        { "$ref": "#/definitions/agentStep" },
+        { "$ref": "#/definitions/scriptStep" }
+      ]
+    },
+    "agentStep": {
+      "type": "object",
+      "required": ["name", "agent", "prompt"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Step/phase name; also the envelope phase the agent must report"
+        },
+        "agent": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Id of an agent defined under agents"
+        },
+        "prompt": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Task prompt. Single-line value = path to a file inside the workflow folder. Variables: ${{ request }}, ${{ agent }}. The envelope contract is appended automatically."
+        },
+        "gates": {
+          "type": "array",
+          "description": "Post-execution file checks; failures trigger an in-session correction",
+          "items": { "$ref": "#/definitions/gate" }
+        }
+      }
+    },
+    "scriptStep": {
+      "type": "object",
+      "required": ["name", "run"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Step/phase name; also the envelope phase of the script step"
+        },
+        "run": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Deterministic step: bash script executed in the run directory (no agent, no LLM). Single-line value = script file inside the workflow folder (e.g. scripts/check.sh). Env vars: REQUEST, RUN_DIR, PHASE; ${{ request }} is interpolated. Non-zero exit fails the run. Optionally end stdout with the same fenced ```json envelope agents emit; otherwise the engine synthesizes one (status ok, summary = last stdout line)."
+        },
+        "gates": {
+          "type": "array",
+          "description": "Post-execution file checks; script steps have no correction loop — a failing gate fails the run (fix the script)",
+          "items": { "$ref": "#/definitions/gate" }
+        }
+      }
+    },
+    "gate": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["file_non_empty"],
+          "additionalProperties": false,
+          "properties": {
+            "file_non_empty": {
+              "type": "string",
+              "minLength": 1,
+              "description": "File (relative to the run directory) that must exist and be non-empty"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["slots_filled"],
+          "additionalProperties": false,
+          "properties": {
+            "slots_filled": {
+              "type": "string",
+              "minLength": 1,
+              "description": "File that must not contain unfilled {{...}} template slots"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["contains"],
+          "additionalProperties": false,
+          "properties": {
+            "contains": {
+              "type": "object",
+              "required": ["file", "text"],
+              "additionalProperties": false,
+              "properties": {
+                "file": { "type": "string", "minLength": 1 },
+                "text": { "type": "string", "minLength": 1 },
+                "label": { "type": "string", "description": "Short label used in the gate name; defaults to text" }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}