lua-cli 3.34.0 → 3.36.0

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.34.0
+# lua-cli v3.36.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.34.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.36.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 

package/docs/api/LuaWorkflow.md

@@ -2,7 +2,7 @@
 
 The workflow primitive: a **durable, multi-step program** you author in TypeScript, compile with `lua compile`, and push with `lua push workflow`. The engine executes the compiled graph server-side — steps survive restarts, waits hold no compute, and approvals/signals park the run until a person or a webhook answers.
 
-> **Execution model — read this first.** _`execute` re-runs from the top after resume; execution is at-least-once — dedupe on `occurrenceId`._ `occurrenceId` is `${lineageId}:${stepId}` — the same key on retry, resume, `retry-step` and a repair run; an effect that must be unique across independent runs needs your own business key (`refund:${ticketId}`). Wrap external effects in `ctx.once(key, fn)`.
+> **Execution model — read this first.** _`execute` re-runs from the top after resume; execution is at-least-once — dedupe on `occurrenceId`._ `occurrenceId` is `${lineageId}:${stepId}` — the same key on retry, resume and `retry-step` (no repair run exists — a terminal run is never re-run from its ledger); an effect that must be unique across independent runs needs your own business key (`refund:${ticketId}`). Wrap external effects in `ctx.once(key, fn)`.
 
 ## Import
 

package/docs/api/Workflows.md

@@ -15,7 +15,7 @@ Inside a sandbox (tools, jobs, webhooks, workflow code steps) `Workflows` is als
 - `start` **never awaits execution** — it returns `{ runId, status }` immediately. `waitSeconds` (≤ 55) asks the server to hold the response for early terminal state; it changes the response, never the execution model.
 - Runs are idempotent on `idempotencyKey` — re-sending the same key returns the existing run instead of a duplicate.
 - A workflow with `concurrencyPolicy: 'forbid'` refuses a second start while one is in flight with a thrown `WorkflowApiError { code: 'RUNS_IN_FLIGHT', blockingRunId }` — never a 429, never a gate.
-- `status: 'gated'` means the run is parked (quota, billing or consent) and holds no slot. Consent gates are cleared from the desktop or with `lua workflows approve`.
+- `status: 'gated'` means the run is parked (quota, billing or consent) and holds no slot. A **consent** gate is cleared by a person resolving its approval — from the desktop, or through the approvals API / inbox. `lua workflows approve` cannot clear one: it requires an `--approval wfa_…` id, which belongs to a workflow `approval` node, and a consent gate has no such id. `lua workflows status <runId>` reports a gated run, and exits 6 under `--strict`.
 - `nameOrId` resolves the workflow **name on the calling agent first**, then a workflow id.
 - `get` / `list` honour output visibility: a restricted run comes back with `restricted: true` and no `output` — never an error.
 - From a workflow code step, `Workflows.start` creates a **detached** run (no parent link). Use the `.workflow(...)` builder node when the parent should wait.

package/docs/workflows/migrating-runs.md

@@ -2,7 +2,7 @@
 
 _Source of truth: workflows-spec (Cluster D R46/R47, D7-r2). This page is the developer summary; the spec is normative._
 
-`lua workflows migrate-runs <workflowId> --from <ver> --to <ver>` re-pins runs to a new version where compatible (`isResumeCompatible` — same seeding math as repair runs); `cancel-by-version` recalls a bad version's fleet.
+`lua workflows migrate-runs <workflowId> --from <ver> --to <ver>` re-pins runs to a new version where compatible (`isResumeCompatible` — the same seeding math as `lua test workflow --from-run`); `cancel-by-version` recalls a bad version's fleet.
 
 ## Edited inputs
 

package/docs/workflows/recovery.md

@@ -19,13 +19,13 @@ A parked step waits for exactly one of:
 
 `onError:'continue'` never parks: the step is `failed` on the ledger, the run goes on, and every successor sees the step's **continued-failure value** `{ __lua_workflow:'continued_failure', failed:true, error:{code,message}, text:'' }` under `stepResults.<id>` (the default input, `${stepResults.<id>.text}` → `''`, `getStepResult(id)`, a `conditional` on `stepResults.<id>.failed`, and the parallel / foreach join entry). A `retry-step` on such a row while the run is still running re-arms it, but a successor that already consumed the value is not re-run.
 
-`fail` (or cancelling the run) applies the step's failure as-is. From the CLI: `lua workflows status <runId>` shows the park and names the verbs; `lua workflows retry-step <runId> --step <id>` re-runs, `lua workflows resolve-step <runId> --step <id> --outcome skip|complete|fail [--output <json|@file>] [--note …]` decides (R37 — `complete` needs `--output`, validated against the step's `outputSchema`; a second decision on the same park is a 200 no-op that names who decided). The desktop inbox carries the same three, plus a repair run.
+`fail` (or cancelling the run) applies the step's failure as-is. From the CLI: `lua workflows status <runId>` shows the park and names the verbs; `lua workflows retry-step <runId> --step <id>` re-runs, `lua workflows resolve-step <runId> --step <id> --outcome skip|complete|fail [--output <json|@file>] [--note …]` decides (R37 — `complete` needs `--output`, validated against the step's `outputSchema`; a second decision on the same park is a 200 no-op that names who decided). The desktop run page carries the same decisions.
 
-## Repair runs
+## No repair run
 
-When a whole run is beyond per-step repair, a **repair run** re-drives the graph seeded from the ledger (the §05 §5.5.4.1 seeding math — the same `seedLedgerFromRun` the CLI's `--from-run` uses): every `completed` step keeps its outputs, attempts and settled effects, and the frontier restarts at the first non-completed step. Because `occurrenceId` is stable across retry, resume, `retry-step` **and** a repair run, an external effect executes at most once per occurrence.
+Nothing re-runs a run from its ledger today (LUA-709 retired the verb; BAC-601): there is no "repair run" in the CLI, the API, the chat tools or the desktop, and a **terminal run cannot be re-run**. `retry-step` and `resolve-step` are the ways past a park; a new run (`lua workflows start`) is the way past a terminal one — offline, `lua test workflow <name> --from-run <runId>` can seed every `completed` step from the old ledger for a rehearsal. Because `occurrenceId` is stable across retry, resume and `retry-step`, an external effect executes at most once per occurrence within a run.
 
-> **The rule to remember:** _execution is at-least-once — dedupe on `occurrenceId`_; an effect that must be unique across **independent** runs needs your own business key (`refund:${ticketId}`).
+> **The rule to remember:** _execution is at-least-once — dedupe on `occurrenceId`_; an effect that must be unique across **independent** runs (a new run, seeded or not, is one) needs your own business key (`refund:${ticketId}`).
 
 ## Rehearsing offline
 

package/docs/workflows/testing-offline.md

@@ -15,7 +15,7 @@ _Source of truth: workflows-spec 03 §3.9 (WF-204/WF-225/WF-332). This page is t
 | `--approve <id>[=@payload]` · `--deny <id>[=@reason]` | Pre-answer approvals — the node completes with the engine's own envelope, `WorkflowApprovalOutput` (`{ approved, decision, text, note?, editedPayload?, editRevision?, decidedBy? }`, see [Approvals](./approvals.md)); an edited payload is the FULL payload, judged like the server's inline edit (`changedPointers` against the payload the approval showed + `matchesEditablePath`, then `editedPayloadSchema`); `onDeny` defaults to `'continue'` as on the engine (LUA-751). `editable: true` with no `editablePaths` is whole-root rights (any member may change), as on the server. Because the change set is judged against the payload the approval actually showed, a change outside `editablePaths` fails exit 2 `edit-path-not-allowed` **when the approval's turn comes — after the steps before it have run** — not before the run starts; `editedPayloadSchema` is still checked up-front |
 | `--signal <name>=@file\|<json>` (rep.)                | Pre-supply `waitForSignal` payloads in order of arrival                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `--fixtures <dir>` / `--record <dir>`                 | Replay / record agent+tool outputs (`<stepId>.<attempt>.json`); a missing fixture is exit **5** `FIXTURE_MISSING`, never a silent fake; `--step-output` wins over a fixture. An agent fixture's `output` is either the `{ text, object? }` reply envelope `--record` writes (the `object` wins, else the text is parsed under the `outputSchema`) or the structured value itself, taken as-is (LUA-751) — a value that is exactly `{ text }` reads as a text reply; record it as `{ object: { text } }`                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `--from-run <runId>`                                  | Seed every `completed` step from a real run (same math as repair runs); graph drift asks for `--force`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--from-run <runId>`                                  | Seed every `completed` step from a real run (the ledger seeding `migrate-runs` also uses); graph drift asks for `--force`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `--park <id>` (rep.)                                  | Simulate a platform-fault park of a `sideEffects:'external'` step — then `retry / skip / complete / fail`, the production verbs (see [When a step parks](./recovery.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `--fast-retries`                                      | Collapse retry backoff waits to 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `--real-time`                                         | Actually wait on `sleep`/backoff instead of fast-forwarding the virtual clock                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.34.0",
+  "version": "3.36.0",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -113,11 +113,11 @@
     "stripe": "^19.2.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
-    "@lua/shared-types": "0.0.1",
-    "@lua/shared-source-sync": "0.0.1",
-    "@lua/workflow-graph": "0.0.1",
     "@lua/sandbox-runtime": "0.0.1",
-    "@lua/shared-sandbox": "0.0.1"
+    "@lua/shared-sandbox": "0.0.1",
+    "@lua/shared-source-sync": "0.0.1",
+    "@lua/shared-types": "0.0.1",
+    "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",
@@ -128,6 +128,7 @@
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "test": "node ../../scripts/test-gate.mjs jest",
     "test:watch": "jest --watch",
-    "test:coverage": "node ../../scripts/test-gate.mjs jest --coverage"
+    "test:coverage": "node ../../scripts/test-gate.mjs jest --coverage",
+    "test:compat-matrix": "node scripts/compat-matrix-previous-cli.mjs"
   }
 }

package/scripts/compat-matrix-previous-cli.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * [WMC-E7] The CLI compatibility matrix's real leg (plan §6.9, "Older CLIs keep working").
+ *
+ * Installs the PREVIOUS MINOR RELEASE of this CLI from npm into a temporary directory and drives it, as a
+ * child process, against the mock API in `tests/helpers/workflow-compat-server.mjs`. It runs the matrix
+ * twice: once against a server serving definitions and runs WITHOUT any of the per-step model-selection
+ * fields, and once WITH all of them, including the run-event types the older CLI has never heard of.
+ *
+ * The verbs exercised are the three §6.9 names: **push**, **view** and **watch**.
+ *
+ * ── Safety ────────────────────────────────────────────────────────────────
+ * Nothing here touches a real account or a real agent. The child CLI is pointed at `127.0.0.1` through
+ * `LUA_API_URL` and given a throwaway `LUA_API_KEY`, so there is no `lua auth`, no production host and no
+ * production verb against anything that exists. The temp directory is removed on the way out.
+ *
+ * ── Why it is gated ───────────────────────────────────────────────────────
+ * It needs the npm registry. Every property it proves is also asserted offline in
+ * `tests/__tests__/workflows.compat-matrix.test.ts`, which runs on every PR; this leg is the end-to-end
+ * confirmation and belongs in the nightly job and on demand:
+ *
+ *     pnpm --filter lua-cli test:compat-matrix
+ *     LUA_COMPAT_MATRIX_VERSION=3.33.0 pnpm --filter lua-cli test:compat-matrix
+ *
+ * Exit 0 = the previous release coped with both halves. Non-zero names the leg that failed.
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_ID, RUN_ID, WORKFLOW_ID, startCompatServer } from '../tests/helpers/workflow-compat-server.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(fs.readFileSync(path.join(HERE, '..', 'package.json'), 'utf8'));
+
+/** The previous MINOR of the version in package.json — 3.34.x ⇒ 3.33.0 — unless one is named. */
+function previousMinor(current) {
+  const [major, minor] = current.split('.').map(Number);
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) throw new Error(`cannot read a version from "${current}"`);
+  if (minor === 0) throw new Error(`no previous minor for ${current} — name one with LUA_COMPAT_MATRIX_VERSION`);
+  return `${major}.${minor - 1}.0`;
+}
+
+const TARGET = process.env.LUA_COMPAT_MATRIX_VERSION || previousMinor(PKG.version);
+
+function say(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+/**
+ * Run the installed previous CLI with the mock API as its whole world.
+ *
+ * ASYNC on purpose. `spawnSync` blocks this process's event loop, and the mock API runs in this process —
+ * so a synchronous spawn freezes the server and every request the child makes hangs until the child is
+ * killed on its timeout. That failure looks exactly like a compatibility failure (empty output, no requests
+ * recorded) and is not one, which is why the harness records the signal as well as the exit code below.
+ */
+function runOldCli(cliEntry, cwd, baseUrl, args, { timeoutMs = 60_000 } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [cliEntry, ...args], {
+      cwd,
+      // stdin CLOSED, not inherited: an open pipe leaves any interactive prompt waiting for ever.
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        LUA_API_URL: baseUrl,
+        LUA_AUTH_URL: baseUrl,
+        LUA_API_KEY: 'compat-matrix-not-a-real-key',
+        // Keep the child from phoning home for an update check or writing analytics during the matrix.
+        LUA_DISABLE_ANALYTICS: '1',
+        LUA_SKIP_UPDATE_CHECK: '1',
+        CI: '1',
+        NO_COLOR: '1',
+      },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (c) => (stdout += c));
+    child.stderr.on('data', (c) => (stderr += c));
+    const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolve({ status: null, signal: null, stdout, stderr, error });
+    });
+    child.on('close', (status, signal) => {
+      clearTimeout(timer);
+      resolve({ status, signal, stdout, stderr });
+    });
+  });
+}
+
+/** One half of the matrix: a server serving old-only or new-bearing shapes, and the three verbs against it. */
+async function runLeg({ withNewFields, cliEntry, projectDir }) {
+  const label = withNewFields ? 'WITH the new fields' : 'WITHOUT the new fields';
+  const server = await startCompatServer({ withNewFields });
+  const failures = [];
+  try {
+    const checks = [
+      { verb: 'view', args: ['workflows', 'view', 'compat', '--json'] },
+      { verb: 'list', args: ['workflows', 'list', '--json'] },
+      { verb: 'status', args: ['workflows', 'status', RUN_ID, '--steps', '--json'] },
+      // `watch` must reach the terminal frame and exit 0 even with event types it does not know.
+      { verb: 'watch', args: ['workflows', 'watch', RUN_ID, '--timeout', '20'] },
+      // The push half of §6.9: the old client compiles its own source and sends a body with none of the new
+      // members. `compile` is part of it on purpose — a push body an older CLI cannot even BUILD is the same
+      // failure as one the server rejects.
+      { verb: 'compile', args: ['compile', '--ci'] },
+      { verb: 'push', args: ['push', 'workflow', '--force'] },
+    ];
+    for (const { verb, args } of checks) {
+      const out = await runOldCli(cliEntry, projectDir, server.baseUrl, args);
+      const ok = out.status === 0;
+      say(
+        `  ${ok ? '✓' : '✗'} ${TARGET} · ${verb} · ${label}${ok ? '' : ` (${out.status === null ? `signal ${out.signal}` : `exit ${out.status}`})`}`
+      );
+      if (!ok) {
+        // `status: null` means the child never exited on its own — name the signal and the spawn error, or the
+        // failure is indistinguishable from a real incompatibility.
+        const how = out.status === null ? `killed by ${out.signal ?? 'an unknown signal'}` : `exit ${out.status}`;
+        failures.push(`${verb} (${label}) ${how}`);
+        if (out.error) say(`      spawn error: ${out.error.message}`);
+        say(`      stdout: ${(out.stdout || '').trim().slice(0, 2500)}`);
+        say(`      stderr: ${(out.stderr || '').trim().slice(0, 2500)}`);
+        say(`      routes: ${server.requests.join(' | ')}`);
+      }
+    }
+    // A leg that asked the server for nothing proves nothing — the "No tests found" failure mode.
+    if (server.requests.length === 0) failures.push(`${label}: the old CLI made no requests at all`);
+
+    // The push must have actually reached the version route, and what it sent is the thing under test:
+    // a body an older CLI builds carries NONE of the new members and leaves the envelope marker at 1.
+    if (server.pushed.length === 0) {
+      failures.push(`${label}: the old CLI never sent a version body`);
+    } else {
+      for (const body of server.pushed) {
+        const marker = body?.graph?.luaWorkflow;
+        if (marker !== 1) failures.push(`${label}: the old CLI sent luaWorkflow ${marker}, expected 1`);
+        const nodes = body?.graph?.definition?.graph ?? [];
+        const leaked = JSON.stringify(nodes).match(/"(taskClass|requires|modelReason|effort)"/g);
+        if (leaked) failures.push(`${label}: the old CLI's body carried ${[...new Set(leaked)].join(', ')}`);
+        say(`  ✓ ${TARGET} · push body · ${label} · luaWorkflow ${marker}, no new members`);
+      }
+    }
+  } finally {
+    await server.close();
+  }
+  return failures;
+}
+
+async function main() {
+  say(`\n🧭 CLI compatibility matrix — driving lua-cli@${TARGET} against the current shapes\n`);
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lua-compat-'));
+  const failures = [];
+  try {
+    // 1. Install the previous release into a scratch directory of its own.
+    say(`  … installing lua-cli@${TARGET} into ${tmp}`);
+    fs.writeFileSync(path.join(tmp, 'package.json'), JSON.stringify({ name: 'compat-host', private: true }), 'utf8');
+    execFileSync('npm', ['install', '--no-audit', '--no-fund', '--silent', `lua-cli@${TARGET}`], {
+      cwd: tmp,
+      stdio: 'inherit',
+      timeout: 300_000,
+    });
+    const cliEntry = path.join(tmp, 'node_modules', 'lua-cli', 'dist', 'index.js');
+    if (!fs.existsSync(cliEntry)) throw new Error(`installed lua-cli@${TARGET} has no dist/index.js at ${cliEntry}`);
+
+    // 2. A project directory the old CLI recognises. No credential file: the key rides the environment.
+    const projectDir = path.join(tmp, 'project');
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, 'lua.skill.yaml'),
+      [
+        'agent:',
+        `  agentId: ${AGENT_ID}`,
+        '  orgId: org_compat',
+        '  name: compat',
+        'workflows:',
+        '  - name: compat',
+        `    workflowId: ${WORKFLOW_ID}`,
+        '    version: 1.0.0',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+    // A project the OLD CLI can compile: nothing in it uses anything this change added, which is the point.
+    fs.mkdirSync(path.join(projectDir, 'src', 'workflows'), { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, 'package.json'),
+      JSON.stringify({ name: 'compat', private: true, type: 'module', dependencies: { 'lua-cli': TARGET } }, null, 2),
+      'utf8'
+    );
+    fs.symlinkSync(path.join(tmp, 'node_modules'), path.join(projectDir, 'node_modules'), 'dir');
+    fs.writeFileSync(
+      path.join(projectDir, 'tsconfig.json'),
+      JSON.stringify(
+        {
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'bundler',
+            strict: true,
+            skipLibCheck: true,
+            esModuleInterop: true,
+            outDir: 'dist',
+          },
+          include: ['src/**/*'],
+        },
+        null,
+        2
+      ),
+      'utf8'
+    );
+    fs.writeFileSync(
+      path.join(projectDir, 'src', 'workflows', 'compat.ts'),
+      [
+        "import { createWorkflow } from 'lua-cli';",
+        "import { z } from 'zod';",
+        '',
+        'export const compat = createWorkflow({',
+        "  name: 'compat',",
+        "  description: 'compatibility matrix fixture',",
+        '  inputSchema: z.object({}),',
+        '  outputSchema: z.object({ text: z.string() }),',
+        '})',
+        "  .agentStep('summarise', { agentId: '$self', toolScope: {}, prompt: 'hi' })",
+        '  .commit();',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+    fs.writeFileSync(
+      path.join(projectDir, 'src', 'index.ts'),
+      [
+        "import { LuaAgent } from 'lua-cli';",
+        "import { compat } from './workflows/compat';",
+        '',
+        'export default new LuaAgent({',
+        "  name: 'compat',",
+        "  persona: 'compatibility matrix fixture',",
+        '  workflows: [compat],',
+        '});',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+
+    // 3. Both halves.
+    for (const withNewFields of [false, true]) {
+      failures.push(...(await runLeg({ withNewFields, cliEntry, projectDir })));
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+
+  if (failures.length) {
+    say(`\n✗ compatibility matrix: ${failures.length} failure(s)`);
+    for (const f of failures) say(`   • ${f}`);
+    process.exit(1);
+  }
+  say(`\n✓ compatibility matrix: lua-cli@${TARGET} pushes, views and watches against the current shapes.\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`compatibility matrix failed to run: ${err?.stack || err}\n`);
+  process.exit(1);
+});

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.34.0",
+    "lua-cli": "^3.36.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"