@workflow-manager/runner 0.7.0 → 0.9.0

package/dist/manPage.js

@@ -21,25 +21,36 @@ List the agent skills bundled with the npm package.
 .B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]
 Install 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.
 .TP
-.B scaffold [path] [--format markdown|json]
+.B scaffold [path] [--format markdown|json] [--template default|agent-validated]
 Create a starter workflow file. Format defaults to markdown unless the output
-path ends in .json.
+path ends in .json. Template defaults to default (the general multi-step example);
+agent-validated scaffolds a compact pipeline demonstrating first-class agent
+validation (validation.mode: agent with a validator agent and criteria).
 .TP
 .B validate <workflow.md|workflow.json>
 Validate workflow structure and report schema errors.
 .TP
-.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json] [--ui]
+.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--session-file path] [--verbose] [--json] [--ui]
 Run the workflow with live CLI progress and optional JSON output.
 .TP
-.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B approve [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Approve the current waiting runner step through the local attach API.
 .TP
-.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B resume [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Alias for approve, intended for external resume flows.
 .TP
-.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B cancel [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Cancel the current waiting runner step through the local attach API.
 .TP
+.B status [--url value] [--token value] [--session-file path] [--run-id value] [--step key]
+Print the current run snapshot (or one step detail with --step) as JSON on stdout.
+.TP
+.B logs [--url value] [--token value] [--session-file path] [--run-id value] [--step key] [--limit number] [--cursor value]
+Print buffered agent stdout/stderr chunks as JSON on stdout.
+.TP
+.B events [--url value] [--token value] [--session-file path] [--run-id value] [--since sequence] [--include-logs]
+Print run events as JSON on stdout in a single poll (no streaming). Log events are excluded unless --include-logs is passed.
+.TP
 .B auth <login|whoami|logout> [--token value]
 Manage remote registry authentication for CLI publish and pull flows.
 .TP
@@ -77,6 +88,9 @@ Bypass confirmation gating for all steps.
 .B --port <number>
 Bind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.
 .TP
+.B --session-file <path>
+Write 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.
+.TP
 .B --verbose
 Stream per-step agent output and execution updates to stderr while the workflow runs.
 .TP
@@ -89,16 +103,28 @@ Full-screen terminal UI (requires a TTY; falls back to standard output).
 Human approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.
 .TP
 .B --url <value>
-Runner attach API base URL for approve, resume, or cancel commands.
+Runner attach API base URL for approve, resume, cancel, status, logs, or events commands.
 .TP
 .B --token <value>
-Runner attach API bearer token for approve, resume, or cancel commands.
+Runner attach API bearer token for approve, resume, cancel, status, logs, or events commands.
 .TP
 .B --run-id <value>
 Runner id to control. If omitted, the CLI reads it from /session.
 .TP
 .B --step <value>
-Optional step key when controlling a specific waiting step.
+Optional step key when controlling a specific waiting step, or when scoping status and logs output.
+.TP
+.B --limit <number>
+Maximum number of log chunks returned by the logs command. Defaults to 200.
+.TP
+.B --cursor <value>
+Pagination cursor for the logs command, taken from a previous nextCursor value.
+.TP
+.B --since <sequence>
+Only return events with a sequence greater than this value in the events command.
+.TP
+.B --include-logs
+Include agent.stdout and agent.stderr events in the events command output.
 .TP
 .B --actor <value>
 Actor name recorded in approval audit events.
@@ -116,6 +142,9 @@ Validate json workflow:
 Scaffold json workflow file:
 .B wfm scaffold ./new-workflow.json --format json
 .TP
+Scaffold an agent-validated pipeline example:
+.B wfm scaffold ./agent-validated.md --template agent-validated
+.TP
 Authenticate with a CLI token:
 .B wfm auth login --token wm_exampletoken
 .TP
@@ -131,6 +160,12 @@ Search the remote registry:
 Run with explicit confirmations:
 .B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human
 .TP
+Run with a session file for attach clients:
+.B wfm run ./example-workflow.json --session-file ./run-session.json
+.TP
+Observe and control the run through the session file:
+.B wfm status --session-file ./run-session.json && wfm approve --session-file ./run-session.json --step qa_gate
+.TP
 Inspect host setup:
 .B wfm doctor
 .TP

package/dist/parser.js

@@ -185,9 +185,18 @@ export function validateWorkflow(def) {
             errors.push(`Unsupported adapter for ${step.key}: ${adapter}`);
         }
         const mode = step.validation?.mode ?? step.approvalSpec?.validation?.mode;
-        if (mode && !["none", "human", "external"].includes(mode)) {
+        if (mode && !["none", "human", "external", "agent"].includes(mode)) {
             errors.push(`Invalid validation mode for ${step.key}: ${mode}`);
         }
+        if (step.approvalSpec?.validation?.mode === "agent") {
+            errors.push(`Approval step ${step.key} cannot use agent validation`);
+        }
+        if (step.validation?.mode === "agent" && step.validation.agent?.adapterKey) {
+            const validatorAdapter = step.validation.agent.adapterKey;
+            if (!SUPPORTED_ADAPTERS.includes(validatorAdapter)) {
+                errors.push(`Unsupported validator adapter for ${step.key}: ${validatorAdapter}`);
+            }
+        }
     }
     const cycle = findDependencyCycle(def);
     if (cycle) {

package/dist/runnerApi.js

@@ -136,6 +136,20 @@ export async function startRunnerApiServer(store, requestedPort) {
                 });
                 return;
             }
+            const eventsListMatch = pathname.match(/^\/runs\/([^/]+)\/events\/list$/);
+            if (method === "GET" && eventsListMatch) {
+                const runId = decodeURIComponent(eventsListMatch[1] ?? "");
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                const sinceSequence = Number.parseInt(url.searchParams.get("sinceSequence") ?? "0", 10) || undefined;
+                const includeLogs = parseBoolean(url.searchParams.get("includeLogs"), true);
+                const items = store.events(sinceSequence, includeLogs);
+                const nextSequence = items.reduce((max, event) => Math.max(max, event.sequence), sinceSequence ?? 0);
+                jsonResponse(res, 200, { items, nextSequence });
+                return;
+            }
             const eventsMatch = pathname.match(/^\/runs\/([^/]+)\/events$/);
             if (method === "GET" && eventsMatch) {
                 const runId = decodeURIComponent(eventsMatch[1] ?? "");

package/dist/runtimePreflight.js

@@ -178,6 +178,7 @@ export function runtimeDoctorChecks(env = process.env) {
     return [
         commandCheck("pi-agent", "Pi command", piAgentCommand(piAgentStep, env), true, env),
         acpCheck,
+        commandCheck("codex-acp", "Codex ACP bridge", "codex-acp", false, env),
         commandCheck("opencode", "OpenCode command (legacy)", "opencode", false, env),
         commandCheck("claude", "Claude Code command (legacy)", "claude", false, env),
         envCheck("openrouter-key", "OpenRouter API key", "OPENROUTER_API_KEY", env),
@@ -220,7 +221,7 @@ export function adapterMockFallbackReason(step) {
         // command) but useRealAdapter is off, so the step still mocks.
         return `adapterKey '${adapter}' is set, but useRealAdapter is not enabled, so the step runs as a mock. Set taskSpec.payload.useRealAdapter: true to run it through ACP.`;
     }
-    // Bare acp/codex with no agent configured is treated as an intentional mock.
+    // Bare acp with no agent configured is treated as an intentional mock.
     return null;
 }
 export function adapterMockFallbackWarnings(definition) {
@@ -258,7 +259,7 @@ export function adapterImplementationStatuses() {
         {
             adapter: "codex",
             status: "partial",
-            detail: "routed through ACP when useRealAdapter and an acpCommand/acpAgent are set; otherwise mock",
+            detail: "routed through ACP via the codex-acp bridge when useRealAdapter is true; otherwise mock",
         },
         {
             adapter: "claude-code",

package/dist/sessionFile.d.ts

@@ -0,0 +1,11 @@
+export interface RunnerSessionFile {
+    baseUrl: string;
+    attachToken: string;
+    runId: string;
+    pid: number;
+    startedAt: string;
+    endedAt?: string;
+    status?: string;
+}
+export declare function writeSessionFile(filePath: string, session: RunnerSessionFile): void;
+export declare function readSessionFile(filePath: string): RunnerSessionFile | string;

package/dist/sessionFile.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+export function writeSessionFile(filePath, session) {
+    const resolvedPath = path.resolve(filePath);
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    fs.writeFileSync(resolvedPath, `${JSON.stringify(session, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    // writeFileSync only applies the mode on creation; enforce it on rewrites too.
+    fs.chmodSync(resolvedPath, 0o600);
+}
+export function readSessionFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    let raw;
+    try {
+        raw = fs.readFileSync(resolvedPath, "utf-8");
+    }
+    catch (error) {
+        return `Could not read session file ${resolvedPath}: ${error.message}`;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return `Session file ${resolvedPath} is not valid JSON`;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return `Session file ${resolvedPath} must contain a JSON object`;
+    }
+    const record = parsed;
+    for (const field of ["baseUrl", "attachToken", "runId", "startedAt"]) {
+        if (typeof record[field] !== "string" || record[field] === "") {
+            return `Session file ${resolvedPath} is missing required field: ${field}`;
+        }
+    }
+    if (typeof record.pid !== "number" || !Number.isInteger(record.pid)) {
+        return `Session file ${resolvedPath} is missing required field: pid`;
+    }
+    if (record.endedAt !== undefined && typeof record.endedAt !== "string") {
+        return `Session file ${resolvedPath} has an invalid endedAt field`;
+    }
+    if (record.status !== undefined && typeof record.status !== "string") {
+        return `Session file ${resolvedPath} has an invalid status field`;
+    }
+    const session = {
+        baseUrl: record.baseUrl,
+        attachToken: record.attachToken,
+        runId: record.runId,
+        pid: record.pid,
+        startedAt: record.startedAt,
+    };
+    if (typeof record.endedAt === "string") {
+        session.endedAt = record.endedAt;
+    }
+    if (typeof record.status === "string") {
+        session.status = record.status;
+    }
+    return session;
+}

package/dist/tui/tuiRunRenderer.js

@@ -38,6 +38,17 @@ function buildEventMetaText(event) {
         const feedbackReason = readString(payload, "feedbackReason");
         return `execution finished: ${status}${action ? ` action=${action}` : ""}${feedbackReason ? ` reason=${feedbackReason}` : ""}`;
     }
+    if (event.type === "step.validation_started") {
+        const adapter = readString(payload, "adapter");
+        const criteria = readString(payload, "criteria");
+        return `agent validation started${adapter ? ` (${adapter})` : ""}${criteria ? ` criteria=${criteria}` : ""}`;
+    }
+    if (event.type === "step.validation_finished") {
+        const status = readString(payload, "status") ?? "unknown";
+        const action = readString(payload, "action");
+        const feedbackReason = readString(payload, "feedbackReason");
+        return `agent validation: ${status}${action ? ` action=${action}` : ""}${feedbackReason ? ` reason=${feedbackReason}` : ""}`;
+    }
     if (event.type === "step.retried") {
         const attempt = typeof payload.attempt === "number" ? payload.attempt : undefined;
         return attempt !== undefined ? `retry scheduled (attempt ${attempt})` : "retry scheduled";

package/dist/types.d.ts

@@ -4,17 +4,11 @@ export type StepKind = "task" | "approval" | "system";
 export type NodeType = "AGENT" | "HUMAN" | "SYSTEM";
 export type ExecutionStatus = "SUCCESS" | "QA_REJECTED" | "YIELD_EXTERNAL" | "FAILED";
 export type QaAction = "PROCEED" | "RETRY_CURRENT" | "ROLLBACK_PREVIOUS" | "RESTART_ALL";
-export type ValidationMode = "none" | "human" | "external";
+export type ValidationMode = "none" | "human" | "external" | "agent";
 export type AdapterKey = "pi-agent" | "mock" | "opencode" | "codex" | "claude-code" | "acp";
 export interface RetryPolicy {
     maxAttempts?: number;
 }
-export interface ValidationSpec {
-    mode?: ValidationMode;
-    required?: boolean;
-    autoConfirm?: boolean;
-    confirmerPolicy?: string;
-}
 export interface TaskInitConfig {
     context?: Record<string, unknown> | string;
     skills?: string[];
@@ -22,6 +16,19 @@ export interface TaskInitConfig {
     systemPrompts?: string[];
     model?: string;
 }
+export interface AgentValidationSpec {
+    adapterKey?: AdapterKey;
+    init?: TaskInitConfig;
+    criteria?: string;
+    payload?: Record<string, unknown>;
+}
+export interface ValidationSpec {
+    mode?: ValidationMode;
+    required?: boolean;
+    autoConfirm?: boolean;
+    confirmerPolicy?: string;
+    agent?: AgentValidationSpec;
+}
 export interface StepDefinition {
     key: string;
     kind: StepKind;
@@ -260,7 +267,7 @@ export interface RunEvent {
     id: string;
     runId: string;
     stepRunId?: string;
-    type: "run.created" | "run.started" | "run.waiting_for_approval" | "step.runnable" | "step.claimed" | "step.execution_started" | "step.execution_finished" | "step.waiting_for_approval" | "approval.resolved" | "step.retried" | "step.confirmed" | "agent.started" | "agent.stdout" | "agent.stderr" | "agent.finished" | "run.completed" | "run.failed" | "run.cancelled";
+    type: "run.created" | "run.started" | "run.waiting_for_approval" | "step.runnable" | "step.claimed" | "step.execution_started" | "step.execution_finished" | "step.validation_started" | "step.validation_finished" | "step.waiting_for_approval" | "approval.resolved" | "step.retried" | "step.confirmed" | "agent.started" | "agent.stdout" | "agent.stderr" | "agent.finished" | "run.completed" | "run.failed" | "run.cancelled";
     sequenceNumber: number;
     occurredAt: string;
     actor: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-manager/runner",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "CLI runner for in-memory and markdown workflow orchestration using ATEP-like envelopes",
   "repository": {
     "type": "git",
@@ -23,6 +23,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "generate:skills": "node ./scripts/generate-bundled-skills.mjs",
     "build:bin": "node ./scripts/build-binary.mjs --outfile ./dist/wfm",
     "build:bin:macos": "node ./scripts/build-binary.mjs --target bun-darwin-arm64 --outfile ./dist/wfm-macos-arm64",
     "build:bin:linux": "node ./scripts/build-binary.mjs --target bun-linux-x64 --outfile ./dist/wfm-linux-x64",
@@ -72,7 +73,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@zed-industries/agent-client-protocol": "^0.4.5",
+    "@agentclientprotocol/sdk": "^1.2.1",
     "gray-matter": "^4.0.3",
     "picocolors": "^1.1.1"
   },

package/skills/workflow-author/README.md

@@ -0,0 +1,18 @@
+# workflow-author skill
+
+Teaches a host coding agent (Claude Code, opencode, pi) how to turn a natural-language
+task description into a repeatable `wfm` workflow, validate it, run it, and narrate
+progress — including approval gates — back to the user.
+
+This skill ships inside the root `@workflow-manager/runner` npm package alongside
+`workflow-manager-cli`. Install it into an agent's skill directory with:
+
+```bash
+wfm skill install workflow-author                    # -> ./.claude/skills/
+wfm skill install workflow-author --agent opencode    # -> ./.opencode/skill/
+wfm skill install workflow-author --global            # -> ~/.claude/skills/
+```
+
+See `SKILL.md` for the full operating manual, and `doc/guide/workflow-schema.md` /
+`doc/guide/runner-api.md` for the underlying schema and attach-API contract this
+skill is built on.