@lchase/yak 0.1.0 → 0.3.0

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="docs-site/static/img/yak-mascot.png" alt="yak mascot" width="320" />
+</p>
+
 # yak
 
 An agentic workflow engine. *It shaves the yak so you don't.*
@@ -6,77 +10,56 @@ Reads a YAML DAG, runs steps (shell commands, pure transforms, coding-agent
 invocations, human gates), and journals everything to disk so runs resume
 exactly where they stopped.
 
-Status: M0–M5 all done (spec.md §8). The `agent → agent → command →
-transform` reference shape runs deterministically against fixtures
-(`mock` adapter) and for real against an actual bug
-(`claude-code` adapter, `fixtures/todo-app/` — see the tutorial at
-`docs-site/docs/tutorial.md`, live at
-`https://lchase.github.io/yak/docs/tutorial`). `loop`, `map`, `gate`,
-and worktree isolation are all implemented and executable, not just IR
-types. See `spec.md` §8.
+## Install
+
+```bash
+npm install -g @lchase/yak
+```
+
+## Quickstart
+
+```bash
+yak run path/to/workflow.yaml
+```
 
-## Current capabilities (M0–M5)
+See `docs-site/docs/quickstart.md` (free, no API key, uses a mock adapter)
+and `docs-site/docs/tutorial.md` (a real run that finds and fixes an actual
+bug) for a guided walkthrough — also live at
+[lchase.github.io/yak/docs/tutorial](https://lchase.github.io/yak/docs/tutorial).
 
-M0 is zero-AI by design — a boring shell pipeline has to cache, resume, and
-journal correctly before nondeterministic steps go anywhere near it.
+## Capabilities
 
 - **Step kinds:** `command` (streamed shell exec, capture stdout/stderr/
   exitCode, optional `idleTimeoutMs` — SIGTERM then SIGKILL after a grace
-  period, `StepFailure.reason: 'timeout'`), `transform` (named pure
-  function from `.yak/transforms.ts`), `agent`
-  (prompt from `{ file }`/`{ inline }` with `{{placeholder}}` interpolation,
-  `context: 'fresh' | { inherit } | { session }`, Zod schema validation via
+  period), `transform` (named pure function from `.yak/transforms.ts`),
+  `agent` (prompt from `{ file }`/`{ inline }`, Zod schema validation via
   `.yak/schemas.ts`, schema repair loop with retries), `loop` (bounded by
-  `maxIterations`, plus a `noProgress` signal/rounds exhaustion check),
-  `map` (concurrency cap, per-item failure policy, optional
-  `isolation: 'worktree'` — each item forks its own worktree off the
-  run's `HEAD`, engine auto-commits before fan-out so items see prior
-  steps' output), and `gate` (human decision point, `schema`-validated
-  answer, optional `skipIf`).
+  `maxIterations`, plus a no-progress exhaustion check), `map`
+  (concurrency cap, per-item failure policy, optional
+  `isolation: 'worktree'`), and `gate` (human decision point,
+  schema-validated answer, optional `skipIf`).
 - **Suspend/resume:** a `gate` or an exhausted budget suspends the run
-  (`run.suspended`, reason `gate` | `budget`, `tripped: maxIterations |
-  maxTokens | noProgress`) rather than failing it. `yak pending` lists
-  every run across the repo awaiting a human answer; `yak resume
-  <run-id>` replays and continues; `--interactive` prompts through open
-  gates inline instead of exiting to resume later.
+  rather than failing it. `yak pending` lists every run across the repo
+  awaiting a human answer; `yak resume <run-id>` replays and continues;
+  `--interactive` prompts through open gates inline instead of exiting to
+  resume later.
 - **Worktree isolation:** `yak run --isolation worktree` runs the whole
-  workflow inside a fresh git worktree (`.yak/worktrees/<run-id>/`);
-  `map` steps can additionally isolate each item into its own sibling
-  worktree.
+  workflow inside a fresh git worktree; `map` steps can additionally
+  isolate each item into its own sibling worktree.
 - **Introspection:** `yak graph <workflow>` emits a workflow's DAG as
   Mermaid; `yak watch [<run-id>]` live-tails a run's step statuses in a
   terminal UI; `yak artifacts [<run-id>]` lists a `map` step's per-item
-  artifact files.
-- **Scheduling:** topological sort, concurrent execution of independent
-  steps up to a concurrency cap, artifact-driven eligibility (`needs`/
-  `produces`).
-- **Validation:** rejects unknown step kinds, duplicate ids, `needs`
-  referencing an artifact nothing produces, cycles, and reading
-  `<step>.exitCode` downstream of a step with `failOn: 'exitCode'`.
-- **Caching:** two-tier content-addressed cache key (`semanticKey` over
-  step id + input artifact hashes, `definitionKey` over the step's own
-  definition). `cache: strict` (default) re-runs on any mismatch;
-  `cache: loose` reuses the artifact and marks the step `stale` when only
-  the definition moved.
-- **Journal:** append-only JSONL event log of every step's lifecycle.
-- **Resume:** `yak resume <run-id>` replays a run's journal to find what
-  already completed (a step left `step.started` with no matching
-  `step.completed`/`step.failed` is treated as interrupted), recomputes each
-  completed step's cache keys against the frozen workflow, reuses the
-  on-disk artifact on a match, and re-runs everything from the first
-  mismatch downward.
-- **Status:** `yak status [<run-id>]` replays a run's journal into per-step
-  state (`completed`/`cached`/`stale`/`failed`/`pending`), with no db or
-  extra durable state beyond the journal. Defaults to the most recent run
-  when `<run-id>` is omitted.
+  artifact files; `yak status [<run-id>]` reports per-step state
+  (`completed`/`cached`/`stale`/`failed`/`pending`).
+- **Caching:** content-addressed — re-runs only what a workflow or
+  artifact change actually invalidates, everything else is reused from a
+  prior run.
+- **Journal:** append-only event log of every step's lifecycle is the
+  only durable state — no database.
 - **Adapters:** `mock` (fixture-driven, deterministic, free) and
-  `claude-code` (real, wraps `@anthropic-ai/claude-agent-sdk`). Selected
-  with `yak run --adapter mock|claude-code` (default `claude-code`);
-  `yak resume` replays the run's original choice and rejects a conflicting
-  `--adapter` override. `claude-code.ts`'s own tests stub `query()` at the
-  module boundary — CI never calls a real model, per CLAUDE.md.
+  `claude-code` (real, wraps `@anthropic-ai/claude-agent-sdk`, also works
+  against any Anthropic-compatible local model server via
+  `ANTHROPIC_BASE_URL`). Selected with `yak run --adapter mock|claude-code`.
 
-Not yet implemented: eval-corpus export (`yak export --evals`,
-descoped from M4, spec.md §9 decision 10), an API/CLI/YAML reference
-beyond spec.md, and npm publish (`docs-site/`'s quickstart still targets
-a git-clone install for that reason).
+Full behavior reference: `spec.md`. Release process and commit
+conventions: `CONTRIBUTING.md`.

package/dist/index.js

@@ -70,6 +70,7 @@ async function writeRejectedOutput(runDir, stepId, attempt, content) {
 import { randomBytes as randomBytes2 } from "crypto";
 import { mkdir as mkdir6, readdir as readdir2, readFile as readFile9, writeFile as writeFile4 } from "fs/promises";
 import path15 from "path";
+import { z as z9 } from "zod";
 
 // src/ir/graph.ts
 function buildProducerMap(steps) {
@@ -206,7 +207,7 @@ var rawStepSchema = z2.lazy(
 var rawWorkflowSchema = z2.object({
   name: z2.string(),
   version: z2.string(),
-  inputSchema: z2.string().optional(),
+  inputSchema: rawSchemaSpecSchema.optional(),
   steps: z2.array(rawStepSchema)
 });
 function normalizeStep(raw) {
@@ -318,6 +319,9 @@ function normalizeWorkflow(raw) {
   };
 }
 
+// src/ir/types.ts
+var INPUT_ARTIFACT = "input";
+
 // src/ir/validate.ts
 import { execFile } from "child_process";
 import { readFile as readFile3 } from "fs/promises";
@@ -481,6 +485,7 @@ async function validateWorkflow(workflow, cwd = process.cwd(), runIsolation = "n
   checkKnownKinds(flatSteps);
   checkDuplicateIds(flatSteps);
   const producerOf = buildProducerMap(workflow.steps);
+  checkReservedArtifactNames(flatSteps);
   checkNeedsSatisfied(workflow.steps, producerOf);
   checkNoCycles(workflow.steps, producerOf);
   checkExitCodeReads(workflow.steps, producerOf);
@@ -569,9 +574,19 @@ function checkDuplicateIds(steps) {
     seen.add(step.id);
   }
 }
+function checkReservedArtifactNames(steps) {
+  for (const step of steps) {
+    if (step.produces === INPUT_ARTIFACT) {
+      throw new WorkflowValidationError(
+        `step "${step.id}": "${INPUT_ARTIFACT}" is a reserved artifact name (the run input) \u2014 a step cannot produce it`
+      );
+    }
+  }
+}
 function checkNeedsSatisfied(steps, producerOf) {
   for (const step of steps) {
     for (const need of step.needs ?? []) {
+      if (need === INPUT_ARTIFACT) continue;
       if (!producerOf.has(need)) {
         throw new WorkflowValidationError(
           `step "${step.id}": needs artifact "${need}" but no step produces it`
@@ -681,9 +696,9 @@ function checkFlatAnswerSchema(step, schema) {
 async function checkGateRenderPlaceholders(steps, cwd) {
   for (const step of steps) {
     if (step.kind !== "gate") continue;
-    const text = "file" in step.render ? await readFile3(path3.resolve(cwd, step.render.file), "utf8") : step.render.inline;
+    const text2 = "file" in step.render ? await readFile3(path3.resolve(cwd, step.render.file), "utf8") : step.render.inline;
     const allowed = new Set(step.needs ?? []);
-    for (const root of extractTemplateRoots(text)) {
+    for (const root of extractTemplateRoots(text2)) {
       if (!allowed.has(root)) {
         throw new WorkflowValidationError(
           `step "${step.id}": render references "{{${root}}}" but "${root}" is not in needs`
@@ -695,9 +710,9 @@ async function checkGateRenderPlaceholders(steps, cwd) {
 async function checkAgentPromptPlaceholders(steps, cwd) {
   for (const step of steps) {
     if (step.kind !== "agent") continue;
-    const text = "file" in step.prompt ? await readFile3(path3.resolve(cwd, step.prompt.file), "utf8") : step.prompt.inline;
+    const text2 = "file" in step.prompt ? await readFile3(path3.resolve(cwd, step.prompt.file), "utf8") : step.prompt.inline;
     const allowed = new Set(agentInputNames(step));
-    for (const root of extractTemplateRoots(text)) {
+    for (const root of extractTemplateRoots(text2)) {
       if (!allowed.has(root)) {
         throw new WorkflowValidationError(
           `step "${step.id}": prompt references "{{${root}}}" but "${root}" is not in needs or context.inherit`
@@ -883,8 +898,8 @@ async function evalExpr(expr, context, cwd) {
 
 // src/steps/gate.ts
 async function renderGate(step, inputs, cwd) {
-  const text = "file" in step.render ? await readFile6(path7.resolve(cwd, step.render.file), "utf8") : step.render.inline;
-  return renderTemplate(text, inputs);
+  const text2 = "file" in step.render ? await readFile6(path7.resolve(cwd, step.render.file), "utf8") : step.render.inline;
+  return renderTemplate(text2, inputs);
 }
 async function completeGate(step, ctx, answer, opts) {
   let artifactName;
@@ -997,8 +1012,8 @@ import {
 import { readFile as readFile7 } from "fs/promises";
 import path8 from "path";
 async function buildPrompt(step, inputs, cwd) {
-  const text = "file" in step.prompt ? await readFile7(path8.resolve(cwd, step.prompt.file), "utf8") : step.prompt.inline;
-  return renderTemplate(text, inputs);
+  const text2 = "file" in step.prompt ? await readFile7(path8.resolve(cwd, step.prompt.file), "utf8") : step.prompt.inline;
+  return renderTemplate(text2, inputs);
 }
 async function callAgentOnce(step, inputs, ctx, promptSuffix) {
   const prompt = await buildPrompt(step, inputs, ctx.cwd) + (promptSuffix ?? "");
@@ -1248,11 +1263,20 @@ var ClaudeCodeAdapter = class {
       await mkdir4(path9.dirname(sessionLogPath), { recursive: true });
       const filesChanged = /* @__PURE__ */ new Set();
       let result;
-      for await (const message of query({ prompt: req.prompt, options })) {
-        await appendFile2(sessionLogPath, `${JSON.stringify(message)}
+      const stream = query({ prompt: req.prompt, options });
+      try {
+        for await (const message of stream) {
+          await appendFile2(sessionLogPath, `${JSON.stringify(message)}
 `, "utf8");
-        collectFilesChanged(message, filesChanged);
-        if (message.type === "result") result = message;
+          collectFilesChanged(message, filesChanged);
+          if (message.type === "result") result = message;
+        }
+      } catch (err) {
+        throw new AgentStepFailedError({
+          reason: "adapter-error",
+          detail: `claude-code adapter for step "${this.stepId}": query() stream errored: ${err.message}`,
+          recoverable: true
+        });
       }
       if (!result) {
         throw new AgentStepFailedError({
@@ -2063,7 +2087,7 @@ async function runEligibleSteps(workflow, ctx, resumeState) {
   const completed = /* @__PURE__ */ new Set();
   const failedSteps = /* @__PURE__ */ new Set();
   const inFlight = /* @__PURE__ */ new Map();
-  const artifactHashes = /* @__PURE__ */ new Map();
+  const artifactHashes = new Map(ctx.seedArtifactHashes ?? []);
   let failed = false;
   let suspended = false;
   if (resumeState) trustResumedSteps(remaining, producerOf, resumeState, completed, artifactHashes);
@@ -2259,6 +2283,31 @@ async function runStep(step, ctx, artifactHashes, workflowName, agentSessionIds)
 
 // src/engine/run.ts
 var DEFAULT_ADAPTER = "claude-code";
+var InputValidationError = class extends Error {
+  name = "InputValidationError";
+};
+async function resolveRunInput(workflow, rawInput, cwd) {
+  const stepNeedsInput = flattenSteps(workflow.steps).some((s) => (s.needs ?? []).includes(INPUT_ARTIFACT));
+  if (rawInput === void 0 && workflow.inputSchema === void 0 && !stepNeedsInput) {
+    return void 0;
+  }
+  const provided = rawInput ?? {};
+  if (workflow.inputSchema === void 0) return provided;
+  const schema = await resolveSchemaSpec(workflow.inputSchema, cwd);
+  const parsed = schema.safeParse(provided);
+  if (!parsed.success) {
+    throw new InputValidationError(
+      `--input does not satisfy the workflow's inputSchema:
+${parsed.errorSummary}`
+    );
+  }
+  return parsed.data;
+}
+async function seedInputHash(runDir) {
+  const value = await readArtifactRawOrUndefined(runDir, INPUT_ARTIFACT);
+  if (value === void 0) return void 0;
+  return /* @__PURE__ */ new Map([[INPUT_ARTIFACT, sha256(JSON.stringify(value, null, 2))]]);
+}
 function defaultRunsDir() {
   return path15.join(process.cwd(), ".runs");
 }
@@ -2287,18 +2336,33 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
   const raw = await loadWorkflowYaml(workflowPath);
   const workflow = normalizeWorkflow(raw);
   await validateWorkflow(workflow, cwd, isolation);
+  const inputValue = await resolveRunInput(workflow, opts.input, cwd);
   const runId = generateRunId();
   const runDir = path15.join(runsDir, runId);
   await mkdir6(runDir, { recursive: true });
   await writeFile4(path15.join(runDir, "workflow.json"), JSON.stringify(workflow, null, 2), "utf8");
+  let seedArtifactHashes;
+  let inputWritten;
+  if (inputValue !== void 0) {
+    inputWritten = await writeArtifact(runDir, INPUT_ARTIFACT, inputValue, z9.unknown());
+    seedArtifactHashes = /* @__PURE__ */ new Map([[INPUT_ARTIFACT, inputWritten.hash]]);
+  }
   await appendJournalEvent(runDir, runId, {
     t: "run.started",
     runId,
     workflow: workflow.name,
-    inputHash: sha256(JSON.stringify(workflow)),
+    inputHash: inputWritten?.hash ?? sha256(JSON.stringify(workflow)),
     adapter,
     isolation
   });
+  if (inputWritten) {
+    await appendJournalEvent(runDir, runId, {
+      t: "artifact.written",
+      name: inputWritten.name,
+      hash: inputWritten.hash,
+      bytes: inputWritten.bytes
+    });
+  }
   let stepCwd = cwd;
   if (isolation === "worktree") {
     const worktreePath = worktreePathFor(runsDir, runId);
@@ -2310,7 +2374,14 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
     }
     stepCwd = worktreePath;
   }
-  const status = await runEligibleSteps(workflow, { runId, runDir, cwd: stepCwd, cacheDir, adapter });
+  const status = await runEligibleSteps(workflow, {
+    runId,
+    runDir,
+    cwd: stepCwd,
+    cacheDir,
+    adapter,
+    seedArtifactHashes
+  });
   await appendJournalEvent(runDir, runId, { t: "run.finished", status });
   return { runId, runDir, status };
 }
@@ -2383,9 +2454,18 @@ async function resumeRun(runId, opts = {}) {
     );
   }
   const stepCwd = persistedIsolation === "worktree" ? worktreePathFor(runsDir, runId) : cwd;
+  const seedArtifactHashes = await seedInputHash(runDir);
   const status = await runEligibleSteps(
     workflow,
-    { runId, runDir, cwd: stepCwd, cacheDir, adapter: persistedAdapter, loopContinuations },
+    {
+      runId,
+      runDir,
+      cwd: stepCwd,
+      cacheDir,
+      adapter: persistedAdapter,
+      loopContinuations,
+      seedArtifactHashes
+    },
     resumeState
   );
   await appendJournalEvent(runDir, runId, { t: "run.finished", status });
@@ -2463,7 +2543,55 @@ async function pendingCommand(opts = {}) {
   return 0;
 }
 
+// src/engine/status.ts
+function stepStatusesFromJournal(steps, events) {
+  const stateByStep = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.t === "step.started") {
+      stateByStep.set(event.stepId, "pending");
+    } else if (event.t === "step.completed") {
+      stateByStep.set(event.stepId, event.stale ? "stale" : event.cached ? "cached" : "completed");
+    } else if (event.t === "step.failed") {
+      stateByStep.set(event.stepId, "failed");
+    }
+  }
+  return steps.map((step) => ({ stepId: step.id, status: stateByStep.get(step.id) ?? "pending" }));
+}
+function failedStepsFromJournal(events) {
+  return events.filter((e) => e.t === "step.failed").map((e) => ({ stepId: e.stepId, failure: e.failure }));
+}
+function formatStepFailure(failure) {
+  return `${failure.detail} (${failure.reason})`;
+}
+function loopStatusFromJournal(step, events) {
+  const bodyStepIds = new Set(step.body.map((s) => s.id));
+  let state = "pending";
+  for (const event of events) {
+    if (event.t === "step.started" && event.stepId === step.id) state = "running";
+    else if (event.t === "step.completed" && event.stepId === step.id) state = "completed";
+    else if (event.t === "step.failed" && event.stepId === step.id) state = "failed";
+    else if (event.t === "run.suspended" && event.loopStepId === step.id) state = "suspended";
+  }
+  const iteration = events.filter((e) => e.t === "step.started" && bodyStepIds.has(e.stepId)).reduce((max, e) => Math.max(max, e.iteration ?? 0), 0);
+  const consumedTokens = events.filter((e) => e.t === "budget.consumed" && bodyStepIds.has(e.stepId)).reduce((sum, e) => sum + e.tokens, 0);
+  const lastIterationEvent = [...events].reverse().find((e) => e.t === "loop.iteration" && e.stepId === step.id);
+  const noProgressSignal = lastIterationEvent?.t === "loop.iteration" ? lastIterationEvent.signal : void 0;
+  return {
+    stepId: step.id,
+    state,
+    iteration,
+    maxIterations: step.budget.maxIterations,
+    consumedTokens,
+    ...step.budget.maxTokens !== void 0 ? { maxTokens: step.budget.maxTokens } : {},
+    ...noProgressSignal !== void 0 ? { noProgressSignal } : {}
+  };
+}
+function formatLoopBudget(detail) {
+  return detail.maxTokens !== void 0 ? `iteration ${detail.iteration}/${detail.maxIterations}, tokens ${detail.consumedTokens}/${detail.maxTokens}` : `iteration ${detail.iteration}/${detail.maxIterations}, tokens ${detail.consumedTokens}`;
+}
+
 // src/cli/commands/resume.ts
+var EX_SUSPEND = 78;
 async function resumeCommand(runId, adapter) {
   let result;
   try {
@@ -2476,94 +2604,162 @@ async function resumeCommand(runId, adapter) {
     console.log(`run ${result.runId} finished: ok`);
     return 0;
   }
-  console.error(`run ${result.runId} finished: ${result.status}`);
+  if (result.status === "suspended") {
+    console.log(`run ${result.runId} suspended \u2014 resume with:
+  yak resume ${result.runId}`);
+    return EX_SUSPEND;
+  }
+  console.error(`run ${result.runId} failed:`);
+  const events = await readJournal(result.runDir);
+  for (const { stepId, failure } of failedStepsFromJournal(events)) {
+    console.error(`  ${stepId}: ${formatStepFailure(failure)}`);
+  }
   return 1;
 }
 
 // src/cli/commands/run.ts
 import path18 from "path";
+import { cancel, intro, log, outro } from "@clack/prompts";
 
 // src/cli/interactive.ts
 import { createInterface } from "readline";
-function terminalAsk(input, output) {
-  const rl = createInterface({ input, output });
-  const queued = [];
-  const waiters = [];
-  rl.on("line", (line) => {
-    const waiter = waiters.shift();
-    if (waiter) waiter(line);
-    else queued.push(line);
-  });
-  return (question) => {
-    output.write(question);
-    const queuedLine = queued.shift();
-    if (queuedLine !== void 0) return Promise.resolve(queuedLine);
-    return new Promise((resolve) => waiters.push(resolve));
-  };
-}
-async function promptForAnswer(request, ask, announce = () => {
+import { confirm, isCancel, select, text } from "@clack/prompts";
+var PromptCancelledError = class extends Error {
+  constructor() {
+    super("prompt cancelled");
+  }
+};
+async function promptForAnswer(request, promptField, announce = () => {
 }) {
   if (request.kind === "gate") {
-    announce(`
-${request.rendered}
-`);
+    announce(request.rendered);
   } else {
-    announce(`
-loop "${request.stepId}" exhausted (${request.tripped}) at iteration ${request.iteration}
-`);
+    announce(`loop "${request.stepId}" exhausted (${request.tripped}) at iteration ${request.iteration}`);
   }
   const schema = request.answerSchema;
   const required = new Set(schema.required ?? []);
   const answer = {};
   for (const [name, prop] of Object.entries(schema.properties ?? {})) {
-    const value = await promptField(ask, name, prop, required.has(name));
+    const value = await promptField({ name, prop, required: required.has(name) });
     if (value !== void 0) answer[name] = value;
   }
   return answer;
 }
-async function promptField(ask, name, prop, required) {
-  const label = required ? name : `${name} (optional, blank to skip)`;
-  for (; ; ) {
-    const raw = (await ask(prop.enum ? `${label} [${prop.enum.join("/")}]: ` : `${label}: `)).trim();
-    if (!raw) {
-      if (!required) return void 0;
-      continue;
+function clackFieldPrompt() {
+  return async ({ name, prop, required }) => {
+    if (prop.enum) {
+      const result = await select({
+        message: name,
+        options: prop.enum.map((value) => ({ value, label: value }))
+      });
+      if (isCancel(result)) throw new PromptCancelledError();
+      return result;
     }
-    if (prop.enum && !prop.enum.includes(raw)) continue;
-    if (prop.type === "number") {
-      const n = Number(raw);
-      if (Number.isNaN(n)) continue;
-      return n;
+    if (prop.type === "boolean") {
+      const result = await confirm({ message: name });
+      if (isCancel(result)) throw new PromptCancelledError();
+      return result;
     }
-    if (prop.type === "boolean") return /^y(es)?$/i.test(raw);
-    return raw;
-  }
+    const raw = await text({
+      message: required ? name : `${name} (optional)`,
+      placeholder: required ? void 0 : "blank to skip",
+      validate(value) {
+        if (!value) return required ? "required" : void 0;
+        if (prop.type === "number" && Number.isNaN(Number(value))) return "must be a number";
+        return void 0;
+      }
+    });
+    if (isCancel(raw)) throw new PromptCancelledError();
+    if (raw === "") return void 0;
+    return prop.type === "number" ? Number(raw) : raw;
+  };
+}
+function lineFieldPrompt(input, output) {
+  const rl = createInterface({ input, output });
+  const queued = [];
+  const waiters = [];
+  rl.on("line", (line) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter(line);
+    else queued.push(line);
+  });
+  const askLine = (question) => {
+    output.write(question);
+    const queuedLine = queued.shift();
+    if (queuedLine !== void 0) return Promise.resolve(queuedLine);
+    return new Promise((resolve) => waiters.push(resolve));
+  };
+  const promptField = async ({ name, prop, required }) => {
+    const label = required ? name : `${name} (optional, blank to skip)`;
+    for (; ; ) {
+      const raw = (await askLine(prop.enum ? `${label} [${prop.enum.join("/")}]: ` : `${label}: `)).trim();
+      if (!raw) {
+        if (!required) return void 0;
+        continue;
+      }
+      if (prop.enum && !prop.enum.includes(raw)) continue;
+      if (prop.type === "number") {
+        const n = Number(raw);
+        if (Number.isNaN(n)) continue;
+        return n;
+      }
+      if (prop.type === "boolean") return /^y(es)?$/i.test(raw);
+      return raw;
+    }
+  };
+  return { promptField, close: () => rl.close() };
 }
 
 // src/cli/commands/run.ts
-var EX_SUSPEND = 78;
+var EX_SUSPEND2 = 78;
 async function answerOpenRequestsInteractively(runId, runDir) {
   const events = await readJournal(runDir);
   const openIds = new Set(openRequestStepIds(events));
   if (openIds.size === 0) return;
   const workflow = await readRunWorkflow(runDir);
   const orderedIds = workflow.steps.map((s) => s.id).filter((id) => openIds.has(id));
-  const ask = terminalAsk(process.stdin, process.stdout);
-  for (const stepId of orderedIds) {
-    const request = await readPendingRequest(runDir, stepId);
-    if (!request) continue;
-    const answer = await promptForAnswer(request, ask, (text) => console.log(text));
-    await writeAnswer(runDir, stepId, answer);
+  const isRealTerminal = process.stdin.isTTY && process.stdout.isTTY;
+  const { promptField, close } = isRealTerminal ? { promptField: clackFieldPrompt(), close: () => {
+  } } : lineFieldPrompt(process.stdin, process.stdout);
+  const announce = isRealTerminal ? log.info : (text2) => console.log(`
+${text2}
+`);
+  if (isRealTerminal) intro("yak: answer pending gates");
+  try {
+    for (const stepId of orderedIds) {
+      const request = await readPendingRequest(runDir, stepId);
+      if (!request) continue;
+      try {
+        const answer = await promptForAnswer(request, promptField, announce);
+        await writeAnswer(runDir, stepId, answer);
+      } catch (err) {
+        if (err instanceof PromptCancelledError) {
+          cancel(`"${stepId}" left unanswered \u2014 run still suspended`);
+          throw new Error(`answering "${stepId}" was cancelled`);
+        }
+        throw err;
+      }
+    }
+  } finally {
+    close();
   }
+  if (isRealTerminal) outro("all gates answered");
 }
 async function runCommand(workflowPath, opts = {}) {
-  let result = await executeWorkflowFile(path18.resolve(workflowPath), {
-    adapter: opts.adapter,
-    isolation: opts.isolation
-  });
-  while (opts.interactive && result.status === "suspended") {
-    await answerOpenRequestsInteractively(result.runId, result.runDir);
-    result = await resumeRun(result.runId, { adapter: opts.adapter });
+  let result;
+  try {
+    result = await executeWorkflowFile(path18.resolve(workflowPath), {
+      adapter: opts.adapter,
+      isolation: opts.isolation,
+      input: opts.input
+    });
+    while (opts.interactive && result.status === "suspended") {
+      await answerOpenRequestsInteractively(result.runId, result.runDir);
+      result = await resumeRun(result.runId, { adapter: opts.adapter });
+    }
+  } catch (err) {
+    console.error(err.message);
+    return 1;
   }
   if (result.status === "ok") {
     console.log(`run ${result.runId} finished: ok`);
@@ -2572,57 +2768,18 @@ async function runCommand(workflowPath, opts = {}) {
   if (result.status === "suspended") {
     console.log(`run ${result.runId} suspended \u2014 resume with:
   yak resume ${result.runId}`);
-    return EX_SUSPEND;
+    return EX_SUSPEND2;
+  }
+  console.error(`run ${result.runId} failed:`);
+  const events = await readJournal(result.runDir);
+  for (const { stepId, failure } of failedStepsFromJournal(events)) {
+    console.error(`  ${stepId}: ${formatStepFailure(failure)}`);
   }
-  console.error(`run ${result.runId} finished: failed`);
   return 1;
 }
 
 // src/cli/commands/status.ts
 import path19 from "path";
-
-// src/engine/status.ts
-function stepStatusesFromJournal(steps, events) {
-  const stateByStep = /* @__PURE__ */ new Map();
-  for (const event of events) {
-    if (event.t === "step.started") {
-      stateByStep.set(event.stepId, "pending");
-    } else if (event.t === "step.completed") {
-      stateByStep.set(event.stepId, event.stale ? "stale" : event.cached ? "cached" : "completed");
-    } else if (event.t === "step.failed") {
-      stateByStep.set(event.stepId, "failed");
-    }
-  }
-  return steps.map((step) => ({ stepId: step.id, status: stateByStep.get(step.id) ?? "pending" }));
-}
-function loopStatusFromJournal(step, events) {
-  const bodyStepIds = new Set(step.body.map((s) => s.id));
-  let state = "pending";
-  for (const event of events) {
-    if (event.t === "step.started" && event.stepId === step.id) state = "running";
-    else if (event.t === "step.completed" && event.stepId === step.id) state = "completed";
-    else if (event.t === "step.failed" && event.stepId === step.id) state = "failed";
-    else if (event.t === "run.suspended" && event.loopStepId === step.id) state = "suspended";
-  }
-  const iteration = events.filter((e) => e.t === "step.started" && bodyStepIds.has(e.stepId)).reduce((max, e) => Math.max(max, e.iteration ?? 0), 0);
-  const consumedTokens = events.filter((e) => e.t === "budget.consumed" && bodyStepIds.has(e.stepId)).reduce((sum, e) => sum + e.tokens, 0);
-  const lastIterationEvent = [...events].reverse().find((e) => e.t === "loop.iteration" && e.stepId === step.id);
-  const noProgressSignal = lastIterationEvent?.t === "loop.iteration" ? lastIterationEvent.signal : void 0;
-  return {
-    stepId: step.id,
-    state,
-    iteration,
-    maxIterations: step.budget.maxIterations,
-    consumedTokens,
-    ...step.budget.maxTokens !== void 0 ? { maxTokens: step.budget.maxTokens } : {},
-    ...noProgressSignal !== void 0 ? { noProgressSignal } : {}
-  };
-}
-function formatLoopBudget(detail) {
-  return detail.maxTokens !== void 0 ? `iteration ${detail.iteration}/${detail.maxIterations}, tokens ${detail.consumedTokens}/${detail.maxTokens}` : `iteration ${detail.iteration}/${detail.maxIterations}, tokens ${detail.consumedTokens}`;
-}
-
-// src/cli/commands/status.ts
 async function statusCommand(runId, opts = {}) {
   const runsDir = opts.runsDir ?? defaultRunsDir();
   const resolvedRunId = runId ?? await findLatestRunId(runsDir);
@@ -2638,6 +2795,7 @@ async function statusCommand(runId, opts = {}) {
   }
   const events = await readJournal(runDir);
   const statuses = stepStatusesFromJournal(workflow.steps, events);
+  const failuresByStep = new Map(failedStepsFromJournal(events).map((f) => [f.stepId, f]));
   console.log(`run ${resolvedRunId}:`);
   for (const { stepId, status } of statuses) {
     console.log(`  ${stepId}: ${status}`);
@@ -2647,6 +2805,8 @@ async function statusCommand(runId, opts = {}) {
       const signal = detail.noProgressSignal !== void 0 ? `, noProgress signal ${detail.noProgressSignal}` : "";
       console.log(`    ${formatLoopBudget(detail)}${signal}`);
     }
+    const failed = failuresByStep.get(stepId);
+    if (failed) console.log(`    ${formatStepFailure(failed.failure)}`);
   }
   return 0;
 }
@@ -2728,6 +2888,22 @@ async function watchCommand(runId, opts = {}) {
   return 0;
 }
 
+// src/cli/parse-input.ts
+function parseInputPairs(pairs) {
+  if (pairs === void 0 || pairs.length === 0) return void 0;
+  const out = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`--input must be key=value, got "${pair}"`);
+    }
+    const key = pair.slice(0, eq);
+    if (key in out) throw new Error(`--input key "${key}" given more than once`);
+    out[key] = pair.slice(eq + 1);
+  }
+  return out;
+}
+
 // src/cli/index.ts
 function requireAdapterId(value) {
   if (value !== "mock" && value !== "claude-code") {
@@ -2743,13 +2919,19 @@ function requireIsolation(value) {
 }
 var program = new Command();
 program.name("yak").description("An agentic workflow engine").version("0.0.1");
-program.command("run").description("Run a workflow YAML file").argument("<workflow>", "path to the workflow YAML file").option("--adapter <adapter>", "agent adapter to use", "claude-code").option("--interactive", "prompt inline for gate answers instead of exiting to resume later", false).option("--isolation <mode>", 'run inside a fresh git worktree ("worktree") or the plain cwd ("none")', "none").action(async (workflow, options) => {
-  process.exitCode = await runCommand(workflow, {
-    adapter: requireAdapterId(options.adapter),
-    interactive: options.interactive,
-    isolation: requireIsolation(options.isolation)
-  });
-});
+program.command("run").description("Run a workflow YAML file").argument("<workflow>", "path to the workflow YAML file").option("--adapter <adapter>", "agent adapter to use", "claude-code").option("--interactive", "prompt inline for gate answers instead of exiting to resume later", false).option("--isolation <mode>", 'run inside a fresh git worktree ("worktree") or the plain cwd ("none")', "none").option(
+  "--input <pair...>",
+  "workflow input as key=value, repeatable \u2014 validated against the workflow inputSchema"
+).action(
+  async (workflow, options) => {
+    process.exitCode = await runCommand(workflow, {
+      adapter: requireAdapterId(options.adapter),
+      interactive: options.interactive,
+      isolation: requireIsolation(options.isolation),
+      input: parseInputPairs(options.input)
+    });
+  }
+);
 program.command("resume").description("Resume an interrupted run").argument("<run-id>", "id of the run to resume").option("--adapter <adapter>", "must match the adapter the run started with, if given").action(async (runId, options) => {
   process.exitCode = await resumeCommand(runId, options.adapter ? requireAdapterId(options.adapter) : void 0);
 });
@@ -2768,4 +2950,9 @@ program.command("watch").description("Live-tail a run's step statuses in a termi
 program.command("artifacts").description("List a map step's per-item artifact files for a run").argument("[run-id]", "id of the run to report on (default: most recent)").action(async (runId) => {
   process.exitCode = await artifactsCommand(runId);
 });
-program.parse();
+try {
+  await program.parseAsync();
+} catch (err) {
+  console.error(err.message);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lchase/yak",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "An agentic workflow engine",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.228",
     "@anthropic-ai/sdk": "^0.116.0",
+    "@clack/prompts": "^1.7.0",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "ink": "^7.1.1",