@lchase/yak 0.4.0 → 0.5.0

package/README.md

@@ -42,7 +42,9 @@ bug) for a guided walkthrough — also live at
   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.
+  resume later. `yak cancel <run-id>` terminates a live run's process tree
+  and journals a clean `failed`/`cancelled` terminal state, so any
+  out-of-process supervisor has a supported kill.
 - **Worktree isolation:** `yak run --isolation worktree` runs the whole
   workflow inside a fresh git worktree; `map` steps can additionally
   isolate each item into its own sibling worktree.

package/dist/index.js

@@ -488,6 +488,7 @@ async function validateWorkflow(workflow, cwd = process.cwd(), runIsolation = "n
   checkReservedArtifactNames(flatSteps);
   checkNeedsSatisfied(workflow.steps, producerOf);
   checkNoCycles(workflow.steps, producerOf);
+  checkExprArtifactIdentifiers(workflow.steps, producerOf);
   checkExitCodeReads(workflow.steps, producerOf);
   checkAgentToolNames(flatSteps);
   await checkAgentSchemaKeys(flatSteps, cwd);
@@ -605,22 +606,58 @@ function checkNeedsSatisfied(steps, producerOf) {
 function checkNoCycles(steps, producerOf) {
   const stepsById = new Map(steps.map((s) => [s.id, s]));
   const state = /* @__PURE__ */ new Map();
-  function visit(step, path21) {
+  function visit(step, path22) {
     const mark = state.get(step.id);
     if (mark === "done") return;
     if (mark === "visiting") {
-      const cycle = [...path21, step.id].join(" -> ");
+      const cycle = [...path22, step.id].join(" -> ");
       throw new WorkflowValidationError(`cycle detected: ${cycle}`);
     }
     state.set(step.id, "visiting");
     for (const depId of dependenciesOf(step, producerOf)) {
       const dep = stepsById.get(depId);
-      if (dep) visit(dep, [...path21, step.id]);
+      if (dep) visit(dep, [...path22, step.id]);
     }
     state.set(step.id, "done");
   }
   for (const step of steps) visit(step, []);
 }
+var JEXL_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function checkExprArtifactIdentifiers(steps, producerOf) {
+  for (const step of steps) {
+    if (step.skipIf !== void 0) checkExprRefs(step.id, "skipIf", step.skipIf, producerOf);
+    if (step.kind === "loop") {
+      const localProducerOf = new Map([...producerOf, ...buildProducerMap(step.body)]);
+      checkExprRefs(step.id, "until", step.until, localProducerOf);
+      if (step.budget.noProgress) {
+        checkExprRefs(step.id, "noProgress.signal", step.budget.noProgress.signal, localProducerOf);
+      }
+      checkExprArtifactIdentifiers(step.body, localProducerOf);
+    }
+    if (step.kind === "map") checkExprArtifactIdentifiers([step.step], producerOf);
+  }
+}
+function checkExprRefs(stepId, field, expr, producerOf) {
+  if (typeof expr !== "string") return;
+  for (const name of producerOf.keys()) {
+    if (JEXL_IDENTIFIER.test(name)) continue;
+    const bounded = new RegExp(`(?<![A-Za-z0-9_$])${escapeRegExp(name)}(?![A-Za-z0-9_$])`);
+    if (!bounded.test(expr)) continue;
+    throw new WorkflowValidationError(
+      `step "${stepId}": ${field} references artifact "${name}", but "${name}" is not a valid jexl identifier \u2014 jexl reads it as an expression ("a-b" parses as "a minus b"), not a name, so the artifact is invisible to ${field}. Rename it to an identifier (e.g. "${toIdentifier(name)}").`
+    );
+  }
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function toIdentifier(name) {
+  const camel = name.replace(
+    /[^A-Za-z0-9]+([A-Za-z0-9])?/g,
+    (_, c) => c ? c.toUpperCase() : ""
+  );
+  return JEXL_IDENTIFIER.test(camel) ? camel : `a${camel}`;
+}
 function checkExitCodeReads(steps, producerOf) {
   const stepsById = new Map(steps.map((s) => [s.id, s]));
   for (const step of steps) {
@@ -1615,11 +1652,28 @@ async function runLoopStep(step, ctx) {
     return "failed";
   }
   const resumeFrom = ctx.loopContinuation?.action === "continue" ? await buildResumeFrom(step, ctx) : void 0;
-  const status = await runLoopBody(step, ctx, resumeFrom);
-  if (status === "ok") {
-    await appendJournalEvent(ctx.runDir, ctx.runId, { t: "step.completed", stepId: step.id, cached: false });
+  const result = await runLoopBody(step, ctx, resumeFrom);
+  if (result.status === "ok") {
+    let artifact;
+    if (step.produces) {
+      const written = await writeArtifact(ctx.runDir, step.produces, result.untilContext, z6.unknown());
+      artifact = { name: step.produces, hash: written.hash };
+      ctx.outerArtifactHashes.set(step.produces, written.hash);
+      await appendJournalEvent(ctx.runDir, ctx.runId, {
+        t: "artifact.written",
+        name: step.produces,
+        hash: written.hash,
+        bytes: written.bytes
+      });
+    }
+    await appendJournalEvent(ctx.runDir, ctx.runId, {
+      t: "step.completed",
+      stepId: step.id,
+      ...artifact ? { artifact: artifact.name, artifactHash: artifact.hash } : {},
+      cached: false
+    });
   }
-  return status;
+  return result.status;
 }
 async function buildResumeFrom(step, ctx) {
   const events = await readJournal(ctx.runDir);
@@ -1682,12 +1736,12 @@ async function runLoopBody(step, ctx, resumeFrom) {
             recoverable: false
           }
         });
-        return "failed";
+        return { status: "failed" };
       }
       throw err;
     }
     const untilContext = Object.fromEntries(thisValues);
-    if (await evalExpr(step.until, untilContext, ctx.cwd)) return "ok";
+    if (await evalExpr(step.until, untilContext, ctx.cwd)) return { status: "ok", untilContext };
     let tripped;
     if (step.budget.noProgress) {
       lastSignal = await evalExpr(step.budget.noProgress.signal, untilContext, ctx.cwd);
@@ -1706,7 +1760,10 @@ async function runLoopBody(step, ctx, resumeFrom) {
       const tokensTotal = await sumBodyTokens(ctx.runDir, bodyStepIds);
       if (tokensTotal >= step.budget.maxTokens) tripped = "maxTokens";
     }
-    if (tripped) return await handleExhausted(step, ctx, iteration, tripped);
+    if (tripped) {
+      const outcome = await handleExhausted(step, ctx, iteration, tripped);
+      return outcome === "ok" ? { status: "ok", untilContext } : { status: outcome };
+    }
     priorValues = thisValues;
     priorHashes = thisHashes;
   }
@@ -2361,6 +2418,7 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
     inputHash: inputWritten?.hash ?? sha256(JSON.stringify(workflow)),
     adapter,
     isolation,
+    pid: process.pid,
     ...opts.tag !== void 0 ? { tag: opts.tag } : {}
   });
   if (inputWritten) {
@@ -2449,6 +2507,7 @@ async function resumeRun(runId, opts = {}) {
   const { runsDir, cwd, cacheDir } = resolveDirs(opts.runsDir, opts.cwd, opts.cacheDir);
   const runDir = path15.join(runsDir, runId);
   const workflow = await readRunWorkflow(runDir);
+  await appendJournalEvent(runDir, runId, { t: "run.resumed", pid: process.pid });
   let events = await readJournal(runDir);
   const loopContinuations = await resolveOpenRequests(runId, runDir, workflow, cwd, events);
   events = await readJournal(runDir);
@@ -2512,6 +2571,99 @@ async function artifactsCommand(runId, opts = {}) {
   return 0;
 }
 
+// src/engine/cancel.ts
+import path17 from "path";
+var SIGKILL_GRACE_MS = 5e3;
+var LIVENESS_POLL_MS = 100;
+var LIVENESS_POLLS = Math.ceil(SIGKILL_GRACE_MS / LIVENESS_POLL_MS);
+var realSignal = (pid, signal) => {
+  process.kill(pid, signal);
+};
+function livePidFromJournal(events) {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event?.t === "run.resumed") return event.pid;
+  }
+  const started = events.find((e) => e.t === "run.started");
+  return started?.t === "run.started" ? started.pid : void 0;
+}
+function isAlive(signal, pid) {
+  try {
+    signal(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+async function terminateProcessTree(signal, sleep, pid) {
+  if (!isAlive(signal, pid)) return "not-running";
+  try {
+    signal(-pid, "SIGTERM");
+  } catch {
+    try {
+      signal(pid, "SIGTERM");
+    } catch {
+      return "sigterm";
+    }
+  }
+  for (let poll = 0; poll < LIVENESS_POLLS; poll++) {
+    if (!isAlive(signal, pid)) return "sigterm";
+    await sleep(LIVENESS_POLL_MS);
+  }
+  if (!isAlive(signal, pid)) return "sigterm";
+  try {
+    signal(-pid, "SIGKILL");
+  } catch {
+    try {
+      signal(pid, "SIGKILL");
+    } catch {
+    }
+  }
+  return "sigkill";
+}
+async function cancelRun(runId, opts = {}) {
+  const runsDir = opts.runsDir ?? defaultRunsDir();
+  const signal = opts.signal ?? realSignal;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const runDir = path17.join(runsDir, runId);
+  const events = await readJournal(runDir);
+  if (!events.some((e) => e.t === "run.started")) return { status: "not-found", runId };
+  const last = events.at(-1);
+  if (last?.t === "run.finished") {
+    return { status: "already-terminal", runId, finishedStatus: last.status };
+  }
+  const pid = livePidFromJournal(events);
+  const signalled = pid === void 0 ? "no-pid" : await terminateProcessTree(signal, sleep, pid);
+  const settled = (await readJournal(runDir)).at(-1);
+  if (settled?.t === "run.finished") {
+    return { status: "already-terminal", runId, finishedStatus: settled.status };
+  }
+  await appendJournalEvent(runDir, runId, {
+    t: "run.finished",
+    status: "failed",
+    reason: "cancelled"
+  });
+  return { status: "cancelled", runId, signalled };
+}
+
+// src/cli/commands/cancel.ts
+async function cancelCommand(runId, opts = {}) {
+  const outcome = await cancelRun(runId, { runsDir: opts.runsDir });
+  switch (outcome.status) {
+    case "not-found":
+      console.error(`run ${runId} not found`);
+      return 1;
+    case "already-terminal":
+      console.log(`run ${runId} already finished: ${outcome.finishedStatus} \u2014 nothing to cancel`);
+      return 0;
+    case "cancelled": {
+      const note = outcome.signalled === "no-pid" ? " (no pid recorded \u2014 marked cancelled without signalling)" : outcome.signalled === "not-running" ? " (process already gone \u2014 marked cancelled)" : outcome.signalled === "sigkill" ? " (SIGKILL after grace period)" : "";
+      console.log(`run ${runId} cancelled${note}`);
+      return 0;
+    }
+  }
+}
+
 // src/cli/commands/graph.ts
 async function graphCommand(workflowPath) {
   const raw = await loadWorkflowYaml(workflowPath);
@@ -2522,13 +2674,13 @@ async function graphCommand(workflowPath) {
 
 // src/cli/commands/pending.ts
 import { readdir as readdir3 } from "fs/promises";
-import path17 from "path";
+import path18 from "path";
 async function pendingCommand(opts = {}) {
   const runsDir = opts.runsDir ?? defaultRunsDir();
   const runIds = (await readdir3(runsDir).catch(() => [])).sort();
   let anyPending = false;
   for (const runId of runIds) {
-    const runDir = path17.join(runsDir, runId);
+    const runDir = path18.join(runsDir, runId);
     const events = await readJournal(runDir);
     const last = events.at(-1);
     if (!last || last.t !== "run.finished" || last.status !== "suspended") continue;
@@ -2632,7 +2784,7 @@ async function resumeCommand(runId, adapter) {
 }
 
 // src/cli/commands/run.ts
-import path18 from "path";
+import path19 from "path";
 import { cancel, intro, log, outro } from "@clack/prompts";
 
 // src/cli/interactive.ts
@@ -2762,7 +2914,7 @@ ${text2}
 async function runCommand(workflowPath, opts = {}) {
   let result;
   try {
-    result = await executeWorkflowFile(path18.resolve(workflowPath), {
+    result = await executeWorkflowFile(path19.resolve(workflowPath), {
       adapter: opts.adapter,
       isolation: opts.isolation,
       input: opts.input,
@@ -2802,7 +2954,7 @@ async function runCommand(workflowPath, opts = {}) {
 }
 
 // src/cli/commands/status.ts
-import path19 from "path";
+import path20 from "path";
 async function statusCommand(runId, opts = {}) {
   const runsDir = opts.runsDir ?? defaultRunsDir();
   const resolvedRunId = runId ?? await findLatestRunId(runsDir);
@@ -2810,7 +2962,7 @@ async function statusCommand(runId, opts = {}) {
     console.error("no runs found");
     return 1;
   }
-  const runDir = path19.join(runsDir, resolvedRunId);
+  const runDir = path20.join(runsDir, resolvedRunId);
   const workflow = await readRunWorkflow(runDir).catch(() => void 0);
   if (!workflow) {
     console.error(`run ${resolvedRunId} not found`);
@@ -2836,7 +2988,7 @@ async function statusCommand(runId, opts = {}) {
 }
 
 // src/cli/commands/watch.ts
-import path20 from "path";
+import path21 from "path";
 import { render } from "ink";
 import React2 from "react";
 
@@ -2896,7 +3048,7 @@ async function watchCommand(runId, opts = {}) {
     console.error("no runs found");
     return 1;
   }
-  const runDir = path20.join(runsDir, resolvedRunId);
+  const runDir = path21.join(runsDir, resolvedRunId);
   const workflow = await readRunWorkflow(runDir).catch(() => void 0);
   if (!workflow) {
     console.error(`run ${resolvedRunId} not found`);
@@ -2973,6 +3125,9 @@ program.command("run").description("Run a workflow YAML file").argument("<workfl
 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);
 });
+program.command("cancel").description("Terminate a live run and journal a clean 'cancelled' terminal state").argument("<run-id>", "id of the run to cancel").action(async (runId) => {
+  process.exitCode = await cancelCommand(runId);
+});
 program.command("status").description("Report a run's per-step status").argument("[run-id]", "id of the run to report on (default: most recent)").action(async (runId) => {
   process.exitCode = await statusCommand(runId);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lchase/yak",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An agentic workflow engine",
   "license": "MIT",
   "type": "module",