@alexkroman1/aai-cli 6.11.0 → 7.0.0

package/dist/{worker-bundler-CGD4r8Kc.mjs → worker-bundler-COxnqstQ.mjs}

@@ -1,10 +1,226 @@
 #!/usr/bin/env node
 import { i as errorCode } from "./_utils-B8QmtFhK.mjs";
 import { n as withPreservedNodeEnv } from "./_vite-env-BNveawd1.mjs";
+import { builtinModules } from "node:module";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { build } from "vite";
 import { BaseBuilder, applySwcTransform, detectWorkflowPatterns, shouldTransformFile } from "@workflow/builders";
+//#region _workflow-scan.ts
+/**
+* What the BUILT flow bundle carries — the two scans that read it, and the
+* checks over them.
+*
+* Split out of `workflow-bundler.ts` when that file crossed the 500-line cap,
+* along the seam the two scans already share: both read the same artifact after
+* the builder has written it, both attribute a line to a module through
+* esbuild's `// <path>` headers, and neither has anything to do with
+* CONFIGURING the build. One of them fails the build (a `require` the workflow
+* VM cannot answer) and the other warns (a call that replays differently), which
+* is the only real difference between them.
+*
+* Internal: `workflow-bundler.ts` is the surface the studio and the CLI's own
+* build call, and it re-exports nothing from here that they need.
+*
+* @module _workflow-scan
+*/
+/**
+* Every Node builtin, in both spellings esbuild can emit for one.
+*
+* `node:child_process` and bare `child_process` are the same module and the
+* bundle may name it either way — a bare name only reaches the output when the
+* source imported it bare, which npm is still full of.
+*/
+const RUNTIME_MODULES = /* @__PURE__ */ new Set([...builtinModules, ...builtinModules.map((name) => `node:${name}`)]);
+/**
+* A `require(…)` CALL, excluding esbuild's own `__require` shim.
+*
+* The lookbehind is what separates the two: `__require` is the shim esbuild
+* writes for a bundled CJS module's dynamic requires, and the STEP bundle
+* defines a real `require` for it (see {@link STEP_REQUIRE_SHIM}). A bare
+* `require` in the FLOW bundle is the different thing this scan is for.
+*/
+const REQUIRE_CALL = /(?<![\w$.])require\(\s*"([^"]+)"\s*\)/g;
+/** esbuild's per-module header — `// node_modules/pkg/index.js`, and nothing else. */
+const MODULE_COMMENT = /^\/\/ (\S+\.[cm]?[jt]sx?)$/;
+/**
+* Find the Node builtins a flow bundle would `require` at load.
+*
+* The flow bundle is compiled in a `node:vm` `Script` whose context has
+* `module` and `exports` and **no `require`**, so one of these is a run that
+* dies at replay with `ReferenceError: require is not defined` — never a build
+* failure, and never a symptom before the first run. The WDK's own builder
+* bundles everything for exactly this reason and carries
+* `createNodeModuleErrorPlugin` to reject a builtin import at build time.
+*
+* That plugin has two blind spots this scan covers, and both are the DEPLOYED
+* shape rather than an exotic one:
+*
+* - It reports a violation only when it can point at the import LINE in a
+*   first-party file, matched with a single-line regex — so a multi-line
+*   `import {\n  x,\n} from "pkg"` finds nothing and the builtin is marked
+*   external in silence.
+* - It resolves that file against `process.cwd()`, which is not the project
+*   being built when the studio builds a workspace, so the read fails and the
+*   same silent path is taken.
+*
+* Both were reproduced. What reaches the VM either way is
+* `var import_node_child_process = require("node:child_process");` at the top
+* of the bundle, i.e. every run of every workflow in the project fails, and the
+* stack names a line of generated code inside a dependency.
+*
+* Restricted to builtin specifiers deliberately: those are the only ones this
+* builder leaves external (it marks nothing else so, precisely so nothing can
+* need a `require`), and a narrow set is what keeps the scan from reading the
+* text of a prompt as a violation.
+*
+* @internal
+*/
+function findVmRequires(workflowCode) {
+	const found = [];
+	const seen = /* @__PURE__ */ new Set();
+	let module;
+	for (const line of workflowCode.split("\n")) {
+		const header = MODULE_COMMENT.exec(line.trim());
+		if (header) {
+			module = header[1];
+			continue;
+		}
+		for (const [, specifier] of line.matchAll(REQUIRE_CALL)) {
+			if (specifier === void 0 || !RUNTIME_MODULES.has(specifier)) continue;
+			const key = `${specifier}\u0000${module ?? ""}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			found.push({
+				specifier,
+				module
+			});
+		}
+	}
+	return found;
+}
+/**
+* Calls whose answer differs between a run and its replays, and what to say
+* about each.
+*
+* **A workflow body REPLAYS from the top on every resume** — after a `sleep`,
+* after a redeploy, after the container was reclaimed — and only a step's
+* result is journaled. So a body that reads the clock gets a different time on
+* every pass, and a body that fetches performs the request again, both silently:
+* the run completes, and its output is built from values that disagree with the
+* ones the earlier passes saw. The scaffold guide has always carried this rule
+* with the words "all of which fail silently if broken", and nothing checked it.
+*/
+const REPLAY_UNSAFE = [
+	{
+		re: /(?<![\w$.])Date\.now\s*\(/g,
+		fix: "reads a different clock on every replay — take the time in a `\"use step\"` body, whose result is journaled"
+	},
+	{
+		re: /(?<![\w$.])new Date\s*\(\s*\)/g,
+		fix: "reads a different clock on every replay — take the time in a `\"use step\"` body, whose result is journaled"
+	},
+	{
+		re: /(?<![\w$.])Math\.random\s*\(/g,
+		fix: "draws a different number on every replay — draw it in a `\"use step\"` body"
+	},
+	{
+		re: /(?<![\w$.])crypto\.randomUUID\s*\(/g,
+		fix: "mints a different id on every replay — mint it in a `\"use step\"` body"
+	},
+	{
+		re: /(?<![\w$.])fetch\s*\(/g,
+		fix: "runs again on every replay, and the VM has no fetch to run it with — call `stepFetch` from a `\"use step\"` body"
+	}
+];
+/**
+* Replay-unsafe calls the flow bundle carries, attributed to the project's OWN
+* `workflows/` files.
+*
+* Attribution is the whole design. The bundle inlines every non-external
+* dependency a workflow module imports — zod, a markdown parser, whatever — and
+* third-party code is full of `Date.now()` on paths a workflow never reaches, so
+* a scan of the bundle's text reports a library and blocks a correct project.
+* esbuild writes a `// <path>` header per module (the same one
+* {@link findVmRequires} reads), so lines can be charged to the file they were
+* written in, and only the project's own workflow sources are read.
+*
+* Scanning the BUNDLE rather than the sources is what makes a `"use step"` body
+* exempt for free: the workflow-mode transform has already removed them, so
+* what is left is the part that really does replay.
+*
+* @internal
+*/
+function findReplayUnsafeCalls(workflowCode) {
+	const found = [];
+	const seen = /* @__PURE__ */ new Set();
+	let module;
+	for (const line of workflowCode.split("\n")) {
+		const header = MODULE_COMMENT.exec(line.trim());
+		if (header) {
+			module = header[1];
+			continue;
+		}
+		if (module === void 0 || !isProjectWorkflowModule(module)) continue;
+		for (const { re, fix } of REPLAY_UNSAFE) for (const [call] of line.matchAll(re)) {
+			const key = `${call}\u0000${module}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			found.push({
+				call,
+				fix,
+				module
+			});
+		}
+	}
+	return found;
+}
+/**
+* Is this bundled module one of the project's own `workflows/` files?
+*
+* A dependency's path runs through `node_modules/`, which is excluded first so
+* a package that happens to live in a directory called `workflows` cannot be
+* read as the project's.
+*/
+function isProjectWorkflowModule(module) {
+	const posix = module.split(path.sep).join("/");
+	return !posix.includes("node_modules/") && /(?:^|\/)workflows\//.test(posix);
+}
+/**
+* The warning `aai build` and `aai dev` print for a replay-unsafe call.
+*
+* A WARNING and not a build failure, deliberately. The attribution above makes
+* the scan accurate about which FILE a call is in, and it cannot know whether a
+* plain function in a `workflows/` module is reached from a body (where the
+* rule bites) or only from a step (where it does not) — so the one thing it
+* must not do is refuse a correct project. A silent build was the actual
+* problem; a line naming the file solves it without that risk.
+*/
+function replayWarnings(workflowCode) {
+	return findReplayUnsafeCalls(workflowCode).map(({ call, fix, module }) => `${module}: \`${call}…\` ${fix}.`);
+}
+/**
+* Fail the build when the flow bundle carries a `require` — see
+* {@link findVmRequires} for what that means and why nothing upstream catches it.
+*
+* The message has to name the MODULE as well as the specifier, because the
+* import that caused it is not in the file an author is looking at: only a
+* `"use step"` body is stripped from this bundle, so a value a `workflows/`
+* module holds at module scope — an exported helper, a constant — keeps its
+* import, and that import's whole graph rides into the VM.
+*/
+function assertNoVmRequires(workflowCode) {
+	const sites = findVmRequires(workflowCode);
+	if (sites.length === 0) return;
+	const lines = sites.map(({ specifier, module }) => `  ${specifier}${module === void 0 ? "" : ` — from ${module}`}`);
+	throw new Error([
+		`This project's workflows cannot run: the workflow bundle requires ${sites.length === 1 ? "a Node module" : "Node modules"} that the workflow VM has no \`require\` for.`,
+		...lines,
+		"",
+		"Only a `\"use step\"` body is removed from this bundle, so anything a `workflows/` module holds at MODULE scope keeps its import — including an exported helper that a step body is the only caller of. Move that use inside the step body, or into a module only a step body imports."
+	].join("\n"));
+}
+//#endregion
 //#region workflow-bundler.ts
 /**
 * Workflow bundling — turning a project's `workflows/` directory into the two
@@ -37,7 +253,7 @@ import { BaseBuilder, applySwcTransform, detectWorkflowPatterns, shouldTransform
 *   guest's BAKED image instead of being inlined. Step bundle: 12 MB → ~7 KB.
 * - **`bundleFinalOutput: false`** — skips wrapping the workflow-mode code in a
 *   runtime host, which is exactly what `workflowEntrypoint(code)` supplies
-*   itself at the other end. Flow bundle: 3.7 MB → ~69 KB.
+*   itself at the other end. Dialog bundle: 3.7 MB → ~69 KB.
 *
 * So `workflowCode` is passed to `workflowEntrypoint()` in the guest and
 * `stepCode` is evaluated there to register its step functions.
@@ -189,11 +405,13 @@ var AaiWorkflowBuilder = class extends BaseBuilder {
 			outfile: this.stepFile
 		});
 		const [workflowCode, stepCode] = await Promise.all([fs.readFile(this.flowFile, "utf-8"), fs.readFile(this.stepFile, "utf-8")]);
+		assertNoVmRequires(workflowCode);
 		this.output = {
 			workflowCode,
 			stepCode: STEP_REQUIRE_SHIM + stepCode,
 			manifest,
-			inputFiles
+			inputFiles,
+			warnings: replayWarnings(workflowCode)
 		};
 	}
 };
@@ -325,7 +543,7 @@ function wrapperEntrySource(runtime, workflows, toolFiles, systemPromptFile) {
 	const toolEntries = toolFiles.map((file, i) => `  ${JSON.stringify(`tools/${file}`)}: __aaiTool${i},`).join("\n");
 	return `import def from "../agent.ts";
 import { agentToolsToSchemas, toAgentConfig, toolRegistry, withSystemPrompt, withTools } from "@alexkroman1/aai/manifest";
-${runtime ? `import { createRuntime } from "@alexkroman1/aai/runtime";` : ""}
+${runtime ? `import { createRuntime } from "@alexkroman1/aai-runtime";` : ""}
 ${systemPromptFile ? `import __aaiSystemPrompt from "../${SYSTEM_PROMPT_FILE}?raw";` : ""}
 ${toolImports}
 // A tool's name is its file name. The map is built here rather than written in

package/dist/worker-bundler.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as buildWorker } from "./worker-bundler-CGD4r8Kc.mjs";
+import { t as buildWorker } from "./worker-bundler-COxnqstQ.mjs";
 export { buildWorker };

package/dist/{workflow-CFpxOFfQ.mjs → workflow-D2AQf2Pl.mjs}

@@ -1,10 +1,37 @@
 #!/usr/bin/env node
 import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
-import { n as getServerInfo } from "./_agent-DpH2pBJd.mjs";
+import { n as getServerInfo } from "./_agent-BTwZJu4P.mjs";
 import { errorMessage, omitUndefined } from "@alexkroman1/aai/utils";
 import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
 //#region workflow.ts
+/**
+* `aai workflow` — reading and steering a deployed agent's durable runs from a
+* terminal.
+*
+* A run outlives every surface that can show it: the studio's runs card is one
+* project's, and a page holds only the id it started. Without this the only way
+* to ask "what has this agent been doing" is to hand-build a `curl` against
+* `/:slug/workflows`, which needs the platform origin and the PUBLISHED slug —
+* neither of which is the project's name.
+*
+* **It talks to the platform's brokered route, unauthenticated by default**,
+* which is the same posture the page has: that surface carries no credential
+* unless the agent's operator set `AAI_WORKFLOW_API_TOKEN`, and `--token` is how
+* a caller passes it. So this is deliberately NOT an `apiRequest` — the caller's
+* API key is not what authorizes here, and sending it would put a platform
+* credential on a route that does not want one.
+*
+* Every request BROKERS, so the first one may boot the agent's sandbox. That is
+* the same trade the studio card makes and worth knowing before scripting a loop
+* around it.
+*
+* **The requests are the SDK's** (`createWorkflowApiClient`,
+* `@alexkroman1/aai/workflow-api`). What is left here is the two things that are
+* genuinely the CLI's: turning "this directory" into an origin plus a published
+* slug, and PRINTING — which is most of why the verbs exist separately from the
+* client's methods.
+*/
 /** Runs listed when the caller names no limit — a terminal is not a dashboard. */
 const DEFAULT_RUN_LIMIT = 20;
 /**

package/dist/workflow-bundler.d.ts

@@ -29,7 +29,7 @@
  *   guest's BAKED image instead of being inlined. Step bundle: 12 MB → ~7 KB.
  * - **`bundleFinalOutput: false`** — skips wrapping the workflow-mode code in a
  *   runtime host, which is exactly what `workflowEntrypoint(code)` supplies
- *   itself at the other end. Flow bundle: 3.7 MB → ~69 KB.
+ *   itself at the other end. Dialog bundle: 3.7 MB → ~69 KB.
  *
  * So `workflowCode` is passed to `workflowEntrypoint()` in the guest and
  * `stepCode` is evaluated there to register its step functions.
@@ -108,6 +108,11 @@ export type WorkflowBundleOutput = {
      * section for why it is this list and not a content sniff.
      */
     inputFiles: readonly string[];
+    /**
+     * Replay-safety findings, as lines to print. See {@link replayWarnings} for
+     * why they are warnings rather than a failed build.
+     */
+    warnings: readonly string[];
 };
 /**
  * Attach the compiler's `workflowId`/`stepId` to the agent bundle's copy of

package/dist/workflow.d.ts

@@ -25,7 +25,7 @@
  * slug, and PRINTING — which is most of why the verbs exist separately from the
  * client's methods.
  */
-import type { WorkflowRunSnapshot, WorkflowSummary } from "@alexkroman1/aai";
+import type { WorkflowRunSnapshot, WorkflowSummary } from "@alexkroman1/aai/workflow-api";
 import { type CommandResult } from "./_output.ts";
 /**
  * One run, as the API reports it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "6.11.0",
+  "version": "7.0.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -44,8 +44,9 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai": "6.11.0",
-    "@alexkroman1/aai-ui": "6.11.0"
+    "@alexkroman1/aai-ui": "7.0.0",
+    "@alexkroman1/aai": "7.0.0",
+    "@alexkroman1/aai-runtime": "7.0.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",
@@ -53,7 +54,7 @@
     "verdaccio": "^6.9.2",
     "vitest": "^4.1.10",
     "workflow": "4.8.2",
-    "aai-templates": "0.3.6"
+    "aai-templates": "0.3.7"
   },
   "peerDependencies": {
     "vitest": "^4.1.10"

package/dist/templates/call-audit/workflows/temp-media.ts

@@ -1,138 +0,0 @@
-// Copyright 2026 the AAI authors. MIT license.
-/**
- * Moving bytes between the upload store and a local file, which is what an
- * ffmpeg step spends most of its lines on.
- *
- * No directive, so it sits under `workflows/` untransformed and is called FROM
- * steps, inheriting their environment. It exists because both ffmpeg steps in
- * this template need the same three things and the third one is the one that is
- * easy to get wrong.
- *
- * ## Why a temp file at all
- *
- * `@alexkroman1/aai/ffmpeg` takes bytes as happily as a path, and for a short
- * clip bytes are the better call. This desk uses paths, for two reasons that are
- * both properties of real recordings rather than preferences:
- *
- * - **A pipe cannot seek.** An `.m4a` off a phone usually carries its `moov`
- *   index at the END of the file, so ffmpeg reading it from `pipe:0` fails with
- *   `moov atom not found`. That is the flagship input.
- * - **Piped output is capped**, at `DEFAULT_MAX_FFMPEG_OUTPUT_BYTES` (64 MiB),
- *   which is about half an hour of this desk's 16 kHz mono PCM. The desk exists
- *   for the two-hour call.
- *
- * ## A temp file may not outlive its step
- *
- * A step is journaled by its RETURN VALUE and may be dispatched into a different
- * process than its neighbours, so a path in a return value is a path that is
- * replayed after the file behind it is gone — and the failure mode is a resumed
- * run reading a directory that another run is using. {@link withTempDir} makes
- * the lifetime a lexical scope: the directory is created on entry, removed on
- * exit, and what crosses the step boundary is an upload id.
- */
-
-import { mkdtemp, open, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { readUpload } from "@alexkroman1/aai/utils";
-
-/**
- * Bytes moved per `readUpload`, and per write.
- *
- * Large enough that a two-hour recording is a few hundred round trips rather
- * than tens of thousands, and small enough that a step's resident set is a
- * constant rather than a function of the recording. The number this must NOT be
- * is "the whole file", which is the shape every first draft has.
- */
-export const WINDOW_BYTES = 8 * 1024 * 1024;
-
-/**
- * Run `work` with a private temp directory, and remove it afterwards.
- *
- * `join(tmpdir(), …)` rather than a `/tmp` literal, which is this repo's rule
- * (`guard-invariants` rule 11) and not merely portability theatre: on Windows a
- * literal `/tmp/x` is DRIVE-RELATIVE, so it resolves somewhere that does not
- * exist and every write fails with ENOENT. A step runs in a Linux guest when it
- * is deployed and on the developer's own machine under `aai dev`, which is the
- * half that makes it matter.
- *
- * The removal is in a `finally`, so it also runs on the failure paths — a guest's
- * disk is small, and a step that leaves a copy of every recording it touched
- * fills it. `force` so a run that never created its output does not fail HERE and
- * replace the real error with this one.
- */
-export async function withTempDir<T>(work: (dir: string) => Promise<T>): Promise<T> {
-  const dir = await mkdtemp(join(tmpdir(), "aai-call-audit-"));
-  try {
-    return await work(dir);
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-}
-
-/**
- * Write an upload to a local path, a window at a time.
- *
- * A `for` loop rather than a fan-out deliberately: the bytes land in one file at
- * one offset each, so concurrency buys nothing and costs exactly the memory the
- * windows are here to bound.
- *
- * `windowBytes` defaults to {@link WINDOW_BYTES}; see {@link fileChunks} for why
- * it is a parameter at all.
- */
-export async function materializeUpload(
-  uploadId: string,
-  size: number,
-  path: string,
-  windowBytes: number = WINDOW_BYTES,
-): Promise<void> {
-  const handle = await open(path, "w");
-  try {
-    for (let at = 0; at < size; at += windowBytes) {
-      const slice = await readUpload(uploadId, {
-        start: at,
-        end: Math.min(at + windowBytes, size),
-      });
-      await handle.write(slice.bytes);
-    }
-  } finally {
-    await handle.close();
-  }
-}
-
-/**
- * A local file as the stream `writeUpload` takes.
- *
- * A generator rather than `readFile`, for the same reason the windows above
- * exist: the normalized PCM is the largest thing this desk touches, and handing
- * the store an `AsyncIterable` is what keeps it off the heap.
- *
- * **The `.slice()` is load-bearing.** One buffer is reused across reads, so
- * yielding a view of it hands the consumer memory the next read overwrites — a
- * bug whose symptom is a stored file made of the LAST chunk repeated, and which
- * does not reproduce whenever the consumer happens to copy before the next
- * iteration.
- *
- * `windowBytes` is a parameter with a default for exactly that reason, and it is
- * the one testability seam in this template. The aliasing bug above only manifests
- * across MULTIPLE reads, so at the real 8 MiB window a spec would have to write a
- * 16 MB file to reach it — and a first draft of that spec used 200 KB, passed with
- * the `.slice()` deleted, and would have shipped a test proving nothing. A small
- * window makes the multi-chunk path a few kilobytes instead.
- */
-export async function* fileChunks(
-  path: string,
-  windowBytes: number = WINDOW_BYTES,
-): AsyncIterable<Uint8Array> {
-  const handle = await open(path, "r");
-  try {
-    const buffer = new Uint8Array(windowBytes);
-    for (;;) {
-      const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
-      if (bytesRead === 0) return;
-      yield buffer.subarray(0, bytesRead).slice();
-    }
-  } finally {
-    await handle.close();
-  }
-}