@workflow-manager/runner 0.7.0 → 0.9.0

package/dist/index.js

@@ -14,7 +14,9 @@ import { parseWorkflowFile, validateWorkflow } from "./parser.js";
 import { MAN_PAGE_SOURCE } from "./manPage.js";
 import { promptForApprovalDecision, runWorkflow } from "./engine.js";
 import { cmdAuth, cmdPublish, cmdPull, cmdRemoteInfo, cmdSearch } from "./remote/commands.js";
+import { readSessionFile, writeSessionFile } from "./sessionFile.js";
 import { emitRunTelemetryBestEffort } from "./remote/telemetry.js";
+import { BUNDLED_SKILLS } from "./generated/bundledSkills.js";
 import { adapterImplementationStatuses, adapterMockFallbackWarnings, runtimeDoctorChecks, validateRuntimeRequirements, } from "./runtimePreflight.js";
 function resolveVersion() {
     if (typeof WFM_VERSION === "string" && WFM_VERSION) {
@@ -53,15 +55,20 @@ function usage() {
         `Usage: ${cli} <command> [options]`,
         "",
         "Author and run workflows",
-        row("scaffold [path]", "Write a starter workflow file"),
+        row("scaffold [path]", "Write a starter workflow file (--template agent-validated for validator example)"),
         row("validate <file>", "Check a workflow for errors"),
         row("doctor [file]", "Check host setup; with a file, preflight it"),
         row("run <file>", "Run a workflow with live progress (--ui for full-screen)"),
         "",
-        "Control a running workflow",
+        "Control or observe a running workflow",
         row("approve", "Approve a step waiting for review"),
         row("resume", "Resume a step waiting on external input"),
         row("cancel", "Cancel a waiting step"),
+        row("status [--step <key>]", "Print the run (or step) snapshot as JSON"),
+        row("logs [--step <key>]", "Print buffered agent logs as JSON"),
+        row("events [--since <seq>]", "Print run events as JSON (one-shot poll)"),
+        "  Connect with --url/--token, --session-file <path> (written by run --session-file),",
+        "  or WFM_RUNNER_URL/WFM_RUNNER_TOKEN.",
         "",
         "Share workflows (remote registry)",
         row("auth <login|whoami|logout>", "Sign in, check, or sign out"),
@@ -314,6 +321,159 @@ steps:
 
 Edit frontmatter to configure orchestration behavior.
 `;
+const WORKFLOW_SCAFFOLD_AGENT_VALIDATED_JSON = {
+    key: "agent-validated-pipeline",
+    title: "Agent-Validated Pipeline",
+    description: "Repeatable task pipeline where a second agent checks the implementation against explicit criteria",
+    objectives: ["ship a change that meets the stated acceptance criteria"],
+    defaultRetryPolicy: { maxAttempts: 2 },
+    steps: [
+        {
+            key: "implement",
+            kind: "task",
+            objective: "Implement the requested change",
+            dependsOn: [],
+            retryPolicy: { maxAttempts: 2 },
+            validation: {
+                mode: "agent",
+                required: true,
+                autoConfirm: false,
+                agent: {
+                    criteria: "The change satisfies the workflow objective, builds cleanly, and includes tests for new behavior.",
+                    init: {
+                        model: "openrouter/anthropic/claude-sonnet-4",
+                        systemPrompts: ["Check the diff against the criteria; be specific about any gaps found"],
+                    },
+                },
+            },
+            taskSpec: {
+                init: {
+                    context: { repo: "example/repo" },
+                    skills: ["coding", "testing"],
+                    systemPrompts: ["Implement the change described in the workflow objective"],
+                },
+                payload: { mockResult: "success" },
+            },
+        },
+        {
+            key: "review-gate",
+            kind: "approval",
+            objective: "Human sign-off before finalizing",
+            dependsOn: ["implement"],
+            validation: { mode: "human", required: true, autoConfirm: false },
+            approvalSpec: {
+                autoApprove: false,
+                validation: { mode: "human", required: true, autoConfirm: false },
+            },
+        },
+        {
+            key: "finalize",
+            kind: "task",
+            objective: "Finalize the change (for example, open a PR)",
+            dependsOn: ["review-gate"],
+            validation: { mode: "none", required: false, autoConfirm: true },
+            taskSpec: {
+                init: {
+                    systemPrompts: ["Open a PR summarizing the change and its validation history"],
+                },
+                payload: { mockResult: "success" },
+            },
+        },
+    ],
+};
+const WORKFLOW_SCAFFOLD_AGENT_VALIDATED_MARKDOWN = `---
+key: agent-validated-pipeline
+title: Agent-Validated Pipeline
+description: Repeatable task pipeline where a second agent checks the implementation against explicit criteria
+objectives:
+  - ship a change that meets the stated acceptance criteria
+defaultRetryPolicy:
+  maxAttempts: 2
+steps:
+  # "implement" omits taskSpec.adapterKey, so it runs on the default pi-agent adapter.
+  - key: implement
+    kind: task
+    objective: Implement the requested change
+    dependsOn: []
+    retryPolicy:
+      maxAttempts: 2
+    validation:
+      # mode: agent routes this step through a second, independent agent call after
+      # implement finishes. That validator agent reads validation.agent.criteria,
+      # returns a verdict (SUCCESS/QA_REJECTED/...), and the engine maps it to a QA
+      # action: PROCEED keeps going, RETRY_CURRENT reruns this step, ROLLBACK_PREVIOUS
+      # reruns an earlier step, RESTART_ALL restarts the run. Sharpen criteria to
+      # control what the validator accepts.
+      mode: agent
+      required: true
+      autoConfirm: false
+      agent:
+        criteria: >-
+          The change satisfies the workflow objective, builds cleanly, and
+          includes tests for new behavior.
+        init:
+          model: openrouter/anthropic/claude-sonnet-4
+          systemPrompts:
+            - Check the diff against the criteria; be specific about any gaps found
+    taskSpec:
+      init:
+        context:
+          repo: example/repo
+        skills: [coding, testing]
+        systemPrompts: [Implement the change described in the workflow objective]
+      payload:
+        # mockResult drives the mock adapter for local dry runs; real adapters ignore it.
+        mockResult: success
+  - key: review-gate
+    kind: approval
+    objective: Human sign-off before finalizing
+    dependsOn: [implement]
+    # Top-level validation must match approvalSpec.validation: without it, the
+    # parser's default (autoConfirm: true) wins and the gate auto-approves.
+    validation:
+      mode: human
+      required: true
+      autoConfirm: false
+    approvalSpec:
+      autoApprove: false
+      validation:
+        mode: human
+        required: true
+        autoConfirm: false
+  - key: finalize
+    kind: task
+    objective: "Finalize the change (for example, open a PR)"
+    dependsOn: [review-gate]
+    validation:
+      mode: none
+      required: false
+      autoConfirm: true
+    taskSpec:
+      init:
+        systemPrompts: [Open a PR summarizing the change and its validation history]
+      payload:
+        mockResult: success
+---
+
+# Agent-Validated Pipeline
+
+This workflow shows first-class agent validation: instead of (or in addition to) a
+human or external check, a step's own output can be graded by a second agent call.
+
+- \`implement\` runs, then its \`validation.agent\` config sends the result to a
+  validator agent along with \`criteria\` — plain-language acceptance criteria the
+  validator checks the work against.
+- The validator's verdict becomes a QA action: \`PROCEED\` lets the run continue,
+  \`RETRY_CURRENT\` re-runs \`implement\` with the validator's feedback,
+  \`ROLLBACK_PREVIOUS\` re-runs an earlier step, and \`RESTART_ALL\` restarts the run.
+  Retries are bounded by \`retryPolicy.maxAttempts\`.
+- \`review-gate\` is a human approval step — agent validation cannot be used on
+  approval steps, so high-stakes changes still get a human in the loop before
+  \`finalize\` runs.
+
+Tighten \`validation.agent.criteria\` to describe exactly what "done" means for this
+step; the validator only knows what criteria tells it.
+`;
 function resolveScaffoldFormat(targetPath, explicitFormat) {
     if (explicitFormat === "markdown" || explicitFormat === "json") {
         return explicitFormat;
@@ -323,6 +483,7 @@ function resolveScaffoldFormat(targetPath, explicitFormat) {
 function parseScaffoldArgs(args) {
     let targetPath;
     let format;
+    let template;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--format") {
@@ -330,11 +491,16 @@ function parseScaffoldArgs(args) {
             i += 1;
             continue;
         }
+        if (arg === "--template") {
+            template = args[i + 1];
+            i += 1;
+            continue;
+        }
         if (!arg.startsWith("-") && !targetPath) {
             targetPath = arg;
         }
     }
-    return { targetPath, format };
+    return { targetPath, format, template };
 }
 const DEFAULT_INSTALL_SKILL = "workflow-manager-cli";
 const SKILL_INSTALL_TARGETS = {
@@ -347,11 +513,22 @@ const SKILL_INSTALL_TARGETS = {
         globalDir: path.join(os.homedir(), ".config", "opencode", "skill"),
     },
 };
-function packagedSkillsDir() {
+export function packagedSkillsDir() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
 }
-function listPackagedSkills() {
-    const root = packagedSkillsDir();
+export function parseSkillDescription(skillMarkdown) {
+    try {
+        const parsed = matter(skillMarkdown);
+        if (typeof parsed.data.description === "string") {
+            return parsed.data.description.replace(/\s+/g, " ").trim();
+        }
+    }
+    catch {
+        // skills without parseable frontmatter are still installable
+    }
+    return "";
+}
+export function listPackagedSkillsFromDisk(root) {
     if (!fs.existsSync(root)) {
         return [];
     }
@@ -363,20 +540,44 @@ function listPackagedSkills() {
         const skillFile = path.join(dir, "SKILL.md");
         if (!fs.existsSync(skillFile))
             continue;
-        let description = "";
-        try {
-            const parsed = matter(fs.readFileSync(skillFile, "utf-8"));
-            if (typeof parsed.data.description === "string") {
-                description = parsed.data.description.replace(/\s+/g, " ").trim();
-            }
-        }
-        catch {
-            // skills without parseable frontmatter are still installable
-        }
-        skills.push({ name: entry.name, dir, description });
+        const description = parseSkillDescription(fs.readFileSync(skillFile, "utf-8"));
+        skills.push({ name: entry.name, description, source: { kind: "disk", dir } });
+    }
+    return skills;
+}
+export function listPackagedSkillsFromBundle(bundle = BUNDLED_SKILLS) {
+    const skills = [];
+    for (const name of Object.keys(bundle).sort()) {
+        const files = bundle[name];
+        const skillFile = files.find((file) => file.name === "SKILL.md");
+        if (!skillFile)
+            continue;
+        skills.push({ name, description: parseSkillDescription(skillFile.content), source: { kind: "bundled", files } });
     }
     return skills;
 }
+export function listPackagedSkills(root = packagedSkillsDir()) {
+    const onDisk = listPackagedSkillsFromDisk(root);
+    if (onDisk.length > 0) {
+        return onDisk;
+    }
+    return listPackagedSkillsFromBundle();
+}
+export function materializeSkillFiles(skill, destDir) {
+    if (skill.source.kind === "disk") {
+        for (const entry of fs.readdirSync(skill.source.dir, { withFileTypes: true })) {
+            if (!entry.isFile() || entry.name === "README.md")
+                continue;
+            fs.copyFileSync(path.join(skill.source.dir, entry.name), path.join(destDir, entry.name));
+        }
+        return;
+    }
+    for (const file of skill.source.files) {
+        if (file.name === "README.md")
+            continue;
+        fs.writeFileSync(path.join(destDir, file.name), file.content, "utf-8");
+    }
+}
 function cmdSkillList() {
     const skills = listPackagedSkills();
     if (skills.length === 0) {
@@ -461,16 +662,12 @@ function cmdSkillInstall(args) {
             return 1;
         }
         fs.mkdirSync(destDir, { recursive: true });
-        for (const entry of fs.readdirSync(skill.dir, { withFileTypes: true })) {
-            if (!entry.isFile() || entry.name === "README.md")
-                continue;
-            fs.copyFileSync(path.join(skill.dir, entry.name), path.join(destDir, entry.name));
-        }
+        materializeSkillFiles(skill, destDir);
         console.log(`Installed skill ${name} -> ${destDir}`);
     }
     return 0;
 }
-function cmdScaffold(targetPath, format) {
+function cmdScaffold(targetPath, format, template) {
     const resolvedPath = targetPath ? path.resolve(targetPath) : path.resolve("./example-workflow.md");
     const normalizedFormat = format?.toLowerCase();
     const resolvedFormat = resolveScaffoldFormat(resolvedPath, normalizedFormat);
@@ -478,10 +675,19 @@ function cmdScaffold(targetPath, format) {
         console.error(`Invalid --format value: ${format}. Use markdown or json.`);
         return 1;
     }
-    const template = resolvedFormat === "json"
-        ? `${JSON.stringify(WORKFLOW_SCAFFOLD_JSON, null, 2)}\n`
-        : WORKFLOW_SCAFFOLD_MARKDOWN;
-    fs.writeFileSync(resolvedPath, template, "utf-8");
+    const normalizedTemplate = template?.toLowerCase() ?? "default";
+    if (normalizedTemplate !== "default" && normalizedTemplate !== "agent-validated") {
+        console.error(`Invalid --template value: ${template}. Use default or agent-validated.`);
+        return 1;
+    }
+    const content = normalizedTemplate === "agent-validated"
+        ? resolvedFormat === "json"
+            ? `${JSON.stringify(WORKFLOW_SCAFFOLD_AGENT_VALIDATED_JSON, null, 2)}\n`
+            : WORKFLOW_SCAFFOLD_AGENT_VALIDATED_MARKDOWN
+        : resolvedFormat === "json"
+            ? `${JSON.stringify(WORKFLOW_SCAFFOLD_JSON, null, 2)}\n`
+            : WORKFLOW_SCAFFOLD_MARKDOWN;
+    fs.writeFileSync(resolvedPath, content, "utf-8");
     console.log(`Scaffolded ${resolvedFormat} workflow: ${resolvedPath}`);
     return 0;
 }
@@ -624,40 +830,66 @@ function cmdDoctor(args) {
     }
     return exitCode;
 }
-async function runnerControlRequest(action, args) {
-    const baseUrl = getFlagFromArgs(args, "--url") ?? process.env.WFM_RUNNER_URL;
-    const token = getFlagFromArgs(args, "--token") ?? process.env.WFM_RUNNER_TOKEN;
-    const stepKey = getFlagFromArgs(args, "--step");
-    const actor = getFlagFromArgs(args, "--actor");
-    const note = getFlagFromArgs(args, "--note");
-    const source = getFlagFromArgs(args, "--source") ?? "cli";
+function resolveRunnerConnection(args) {
+    let baseUrl = getFlagFromArgs(args, "--url");
+    let token = getFlagFromArgs(args, "--token");
+    let runId = getFlagFromArgs(args, "--run-id");
+    const sessionFilePath = getFlagFromArgs(args, "--session-file");
+    if (sessionFilePath && (!baseUrl || !token || !runId)) {
+        const session = readSessionFile(sessionFilePath);
+        if (typeof session === "string") {
+            return session;
+        }
+        baseUrl = baseUrl ?? session.baseUrl;
+        token = token ?? session.attachToken;
+        runId = runId ?? session.runId;
+    }
+    baseUrl = baseUrl ?? process.env.WFM_RUNNER_URL;
+    token = token ?? process.env.WFM_RUNNER_TOKEN;
     if (!baseUrl) {
-        console.error(`Missing --url. You can also set WFM_RUNNER_URL.`);
-        return 1;
+        return `Missing --url. You can also pass --session-file or set WFM_RUNNER_URL.`;
     }
     if (!token) {
-        console.error(`Missing --token. You can also set WFM_RUNNER_TOKEN.`);
+        return `Missing --token. You can also pass --session-file or set WFM_RUNNER_TOKEN.`;
+    }
+    return { baseUrl, token, runId };
+}
+async function resolveRunnerRunId(connection, headers) {
+    if (connection.runId) {
+        return { runId: connection.runId };
+    }
+    const sessionResponse = await fetch(`${connection.baseUrl}/session`, { headers });
+    if (!sessionResponse.ok) {
+        const message = await sessionResponse.text();
+        return { error: `Failed to discover run id: ${message}` };
+    }
+    const session = (await sessionResponse.json());
+    const runId = session.run?.runId;
+    if (!runId) {
+        return { error: "Could not determine run id. Pass --run-id explicitly." };
+    }
+    return { runId };
+}
+async function runnerControlRequest(action, args) {
+    const connection = resolveRunnerConnection(args);
+    if (typeof connection === "string") {
+        console.error(connection);
         return 1;
     }
+    const stepKey = getFlagFromArgs(args, "--step");
+    const actor = getFlagFromArgs(args, "--actor");
+    const note = getFlagFromArgs(args, "--note");
+    const source = getFlagFromArgs(args, "--source") ?? "cli";
     const headers = {
-        Authorization: `Bearer ${token}`,
+        Authorization: `Bearer ${connection.token}`,
     };
-    let runId = getFlagFromArgs(args, "--run-id");
-    if (!runId) {
-        const sessionResponse = await fetch(`${baseUrl}/session`, { headers });
-        if (!sessionResponse.ok) {
-            const message = await sessionResponse.text();
-            console.error(`Failed to discover run id: ${message}`);
-            return 1;
-        }
-        const session = (await sessionResponse.json());
-        runId = session.run?.runId;
-    }
-    if (!runId) {
-        console.error("Could not determine run id. Pass --run-id explicitly.");
+    const resolved = await resolveRunnerRunId(connection, headers);
+    if (resolved.error || !resolved.runId) {
+        console.error(resolved.error ?? "Could not determine run id. Pass --run-id explicitly.");
         return 1;
     }
-    const response = await fetch(`${baseUrl}/runs/${runId}/${action}`, {
+    const runId = resolved.runId;
+    const response = await fetch(`${connection.baseUrl}/runs/${runId}/${action}`, {
         method: "POST",
         headers: {
             ...headers,
@@ -682,9 +914,79 @@ async function runnerControlRequest(action, args) {
     console.log(`${decision} ${resolvedStep}`);
     return 0;
 }
+async function runnerReadRequest(command, args) {
+    const connection = resolveRunnerConnection(args);
+    if (typeof connection === "string") {
+        console.error(connection);
+        return 1;
+    }
+    const headers = {
+        Authorization: `Bearer ${connection.token}`,
+    };
+    try {
+        const resolved = await resolveRunnerRunId(connection, headers);
+        if (resolved.error || !resolved.runId) {
+            console.error(resolved.error ?? "Could not determine run id. Pass --run-id explicitly.");
+            return 1;
+        }
+        const runId = encodeURIComponent(resolved.runId);
+        let requestPath;
+        if (command === "status") {
+            const stepKey = getFlagFromArgs(args, "--step");
+            requestPath = stepKey ? `/runs/${runId}/steps/${encodeURIComponent(stepKey)}` : `/runs/${runId}`;
+        }
+        else if (command === "logs") {
+            const query = new URLSearchParams();
+            const stepKey = getFlagFromArgs(args, "--step");
+            const limit = getFlagFromArgs(args, "--limit");
+            const cursor = getFlagFromArgs(args, "--cursor");
+            if (stepKey)
+                query.set("stepKey", stepKey);
+            if (limit)
+                query.set("limit", limit);
+            if (cursor)
+                query.set("cursor", cursor);
+            const queryString = query.toString();
+            requestPath = `/runs/${runId}/logs${queryString ? `?${queryString}` : ""}`;
+        }
+        else {
+            const query = new URLSearchParams();
+            const since = getFlagFromArgs(args, "--since");
+            if (since)
+                query.set("sinceSequence", since);
+            query.set("includeLogs", args.includes("--include-logs") ? "true" : "false");
+            requestPath = `/runs/${runId}/events/list?${query.toString()}`;
+        }
+        const response = await fetch(`${connection.baseUrl}${requestPath}`, { headers });
+        const payloadText = await response.text();
+        if (!response.ok) {
+            let message = `Request failed with status ${response.status}`;
+            try {
+                const payload = JSON.parse(payloadText);
+                if (typeof payload.message === "string") {
+                    message = payload.message;
+                }
+            }
+            catch {
+                // keep the fallback message
+            }
+            console.error(`${command} failed: ${message}`);
+            return 1;
+        }
+        console.log(payloadText);
+        return 0;
+    }
+    catch (error) {
+        console.error(`${command} failed: ${error.message}`);
+        return 1;
+    }
+}
 async function cmdRun(filePath) {
     const resolvedPath = path.resolve(filePath);
     const startedAt = Date.now();
+    const sessionFilePath = getFlag("--session-file");
+    let sessionFileState;
+    let finalRunStatus;
     let workflow;
     let runnerServer;
     let sessionStore;
@@ -750,6 +1052,16 @@ async function cmdRun(filePath) {
         }
         runnerServer = await startRunnerApiServer(sessionStore, requestedPort);
         const session = sessionStore.sessionInfo();
+        if (sessionFilePath) {
+            sessionFileState = {
+                baseUrl: session.baseUrl,
+                attachToken: session.attachToken,
+                runId,
+                pid: process.pid,
+                startedAt: session.startedAt,
+            };
+            writeSessionFile(sessionFilePath, sessionFileState);
+        }
         if (!useTui) {
             process.stderr.write(`Attach API: ${session.baseUrl} (token ${session.attachToken})\n`);
         }
@@ -803,6 +1115,7 @@ async function cmdRun(filePath) {
         });
         tuiRenderer?.stop();
         liveRenderer?.close();
+        finalRunStatus = result.status;
         if (hasFlag("--json")) {
             console.log(JSON.stringify({ session: sessionStore.sessionInfo(), ...result }, null, 2));
         }
@@ -846,6 +1159,18 @@ async function cmdRun(filePath) {
     finally {
         tuiRenderer?.stop();
         liveRenderer?.close();
+        if (sessionFilePath && sessionFileState) {
+            try {
+                writeSessionFile(sessionFilePath, {
+                    ...sessionFileState,
+                    endedAt: new Date().toISOString(),
+                    status: finalRunStatus ?? "failed",
+                });
+            }
+            catch {
+                // session-file finalization is best effort; the run result is authoritative
+            }
+        }
         await runnerServer?.close().catch(() => undefined);
     }
 }
@@ -874,8 +1199,8 @@ async function main() {
         process.exit(1);
     }
     if (cmd === "scaffold") {
-        const { targetPath, format } = parseScaffoldArgs(process.argv.slice(3));
-        process.exit(cmdScaffold(targetPath, format));
+        const { targetPath, format, template } = parseScaffoldArgs(process.argv.slice(3));
+        process.exit(cmdScaffold(targetPath, format, template));
     }
     if (cmd === "man") {
         process.exit(cmdMan());
@@ -899,6 +1224,9 @@ async function main() {
     if (cmd === "approve" || cmd === "resume" || cmd === "cancel") {
         process.exit(await runnerControlRequest(cmd, process.argv.slice(3)));
     }
+    if (cmd === "status" || cmd === "logs" || cmd === "events") {
+        process.exit(await runnerReadRequest(cmd, process.argv.slice(3)));
+    }
     if (cmd === "auth") {
         process.exit(await cmdAuth(process.argv.slice(3)));
     }
@@ -932,4 +1260,30 @@ async function main() {
     usage();
     process.exit(1);
 }
-void main();
+// Run main() only when this module is the process entrypoint (direct `bun
+// run`/`node` invocation, an npm-installed symlinked bin, or a `bun build
+// --compile` standalone binary) — never when imported as a module, e.g. by
+// tests exercising the exported skill-catalog helpers below.
+function isEntryModule() {
+    if (!process.argv[1]) {
+        return false;
+    }
+    const self = fileURLToPath(import.meta.url);
+    let invoked = process.argv[1];
+    try {
+        invoked = fs.realpathSync(invoked);
+    }
+    catch {
+        // compiled/virtual filesystem paths (e.g. bun's $bunfs) can't be
+        // realpath'd; fall back to the raw invoked path.
+    }
+    try {
+        return path.resolve(invoked) === self;
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryModule()) {
+    void main();
+}

package/dist/manPage.d.ts

@@ -1 +1 @@
-export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B skill list\nList the agent skills bundled with the npm package.\n.TP\n.B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]\nInstall bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json.\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json] [--ui]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.TP\n.B --version, -v, version\nPrint the installed wfm version and exit.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\n.B --ui\nFull-screen terminal UI (requires a TTY; falls back to standard output).\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, or cancel commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, or cancel commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nInstall the bundled CLI skill for Claude Code:\n.B wfm skill install\n.TP\nInstall every bundled skill globally:\n.B wfm skill install --all --global\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";
+export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B skill list\nList the agent skills bundled with the npm package.\n.TP\n.B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]\nInstall bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json] [--template default|agent-validated]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json. Template defaults to default (the general multi-step example);\nagent-validated scaffolds a compact pipeline demonstrating first-class agent\nvalidation (validation.mode: agent with a validator agent and criteria).\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--session-file path] [--verbose] [--json] [--ui]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B status [--url value] [--token value] [--session-file path] [--run-id value] [--step key]\nPrint the current run snapshot (or one step detail with --step) as JSON on stdout.\n.TP\n.B logs [--url value] [--token value] [--session-file path] [--run-id value] [--step key] [--limit number] [--cursor value]\nPrint buffered agent stdout/stderr chunks as JSON on stdout.\n.TP\n.B events [--url value] [--token value] [--session-file path] [--run-id value] [--since sequence] [--include-logs]\nPrint run events as JSON on stdout in a single poll (no streaming). Log events are excluded unless --include-logs is passed.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.TP\n.B --version, -v, version\nPrint the installed wfm version and exit.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --session-file <path>\nWrite attach connection details (base URL, bearer token, run id, pid, timestamps) to a JSON file with mode 0600 when the run starts, and rewrite it with endedAt and the final status when the run finishes. Attach commands (approve, resume, cancel, status, logs, events) accept the same flag to read those details back.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\n.B --ui\nFull-screen terminal UI (requires a TTY; falls back to standard output).\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, cancel, status, logs, or events commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, cancel, status, logs, or events commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step, or when scoping status and logs output.\n.TP\n.B --limit <number>\nMaximum number of log chunks returned by the logs command. Defaults to 200.\n.TP\n.B --cursor <value>\nPagination cursor for the logs command, taken from a previous nextCursor value.\n.TP\n.B --since <sequence>\nOnly return events with a sequence greater than this value in the events command.\n.TP\n.B --include-logs\nInclude agent.stdout and agent.stderr events in the events command output.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nScaffold an agent-validated pipeline example:\n.B wfm scaffold ./agent-validated.md --template agent-validated\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nRun with a session file for attach clients:\n.B wfm run ./example-workflow.json --session-file ./run-session.json\n.TP\nObserve and control the run through the session file:\n.B wfm status --session-file ./run-session.json && wfm approve --session-file ./run-session.json --step qa_gate\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nInstall the bundled CLI skill for Claude Code:\n.B wfm skill install\n.TP\nInstall every bundled skill globally:\n.B wfm skill install --all --global\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";