@alexkroman1/aai-cli 6.10.1 → 7.0.0

package/dist/templates/travel-concierge/shared.ts

@@ -35,7 +35,15 @@
  * agent that can rebook a flight and one that can rebook a flight *by mistake*.
  */
 
-import { type DeepReadonly, pushCapped, sessionSlot, type ToolFailure } from "@alexkroman1/aai";
+import {
+  type DeepReadonly,
+  type DialogSpec,
+  dialog,
+  pushCapped,
+  sessionSlot,
+  type ToolContext,
+  type ToolFailure,
+} from "@alexkroman1/aai";
 
 // ─── The booking world ───────────────────────────────────────────────────────
 // Their notebook downloads a sqlite database of a real airline's schedule and
@@ -341,6 +349,51 @@ export function note(state: TripState, entry: string): void {
 
 // ─── The confirmation gate ───────────────────────────────────────────────────
 
+/**
+ * The gate as a STATE MAP — their `interrupt_before`, which is a graph construct.
+ *
+ * This port had to hand-roll it: a voice session had no graph, so "halt before a
+ * sensitive tool and resume on approval" became "every sensitive tool STAGES and
+ * `confirm_action` is the only thing that applies one". That half is unchanged
+ * and is still the mechanism — see {@link stageAction}. What the machine adds is
+ * the PRECONDITION on the other side of the halt: `confirm_action` and
+ * `cancel_action` are legal only while something is actually waiting, which was
+ * a null check inside each of them and is now `when`.
+ *
+ * **The staging tools are deliberately NOT gated on `browsing`.**
+ * {@link stageAction}'s refusal NAMES the sentence already waiting, which is what
+ * lets the model settle that one first and restage the rest; a state gate can
+ * only say "you are in awaitingConfirmation", since a state's instruction is
+ * static. So the specific refusal stays where it is and the flow follows it.
+ */
+const gateSpec = {
+  initial: "browsing",
+  states: {
+    browsing: {
+      instruction:
+        "Nothing is waiting for the caller's yes. Stage a change with a booking tool first.",
+      on: { STAGED: "awaitingConfirmation" },
+    },
+    awaitingConfirmation: {
+      instruction:
+        "Read the staged change back and hear a clear yes or no, then use confirm_action or cancel_action.",
+      on: { SETTLED: "browsing" },
+    },
+  },
+} as const satisfies DialogSpec;
+
+/**
+ * Whether a change is waiting on the caller's word.
+ *
+ * Its own slot, beside {@link tripSlot}: the flow holds the POSITION and the
+ * trip holds the staged action itself, because an inspectable
+ * {@link PendingAction} is what `confirm_action` re-derives the effect from. One
+ * tool call always moves both — {@link stageAction} sends `STAGED` in the same
+ * synchronous window it writes `pending` in, and the two settling tools send
+ * `SETTLED` only on success.
+ */
+export const gateFlow = dialog("gate", gateSpec);
+
 /**
  * Describe a staged action in one sentence, in the second person — this is
  * read aloud, so it is a question's worth of text and not a receipt.
@@ -396,6 +449,7 @@ export function describeAction(action: DeepReadonly<PendingAction>): string | To
  * model ask about that one first and restage the rest afterwards.
  */
 export function stageAction(
+  ctx: ToolContext,
   state: TripState,
   action: PendingAction,
 ):
@@ -413,6 +467,11 @@ export function stageAction(
     };
   }
   state.pending = action;
+  // The flow moves in the SAME synchronous window `pending` is written in, so
+  // the position and the payload cannot be observed disagreeing. `gateFlow` is
+  // a different slot from `tripSlot`, so this is not a nested write to the draft
+  // being held — the open-draft guard is per slot.
+  gateFlow.send(ctx, { type: "STAGED" });
   note(state, `Awaiting confirmation: ${described}`);
   return {
     awaitingConfirmation: true,
@@ -421,13 +480,21 @@ export function stageAction(
   };
 }
 
-/** Apply the staged action. The ONE place any of them takes effect. */
+/**
+ * Apply the staged action. The ONE place any of them takes effect.
+ *
+ * The "nothing is waiting" guard is gone: `confirm_action` is gated on
+ * `awaitingConfirmation`, so reaching here means something IS staged. The
+ * remaining `!action` arm is the flow and the payload disagreeing, which one
+ * synchronous window per transition is what rules out — it reports rather than
+ * throwing, because a live call is the wrong place to find out.
+ */
 export function applyPending(
   state: TripState,
 ): { applied: string; reference?: string } | ToolFailure {
   const action = state.pending;
   if (!action) {
-    return { error: "Nothing is waiting for confirmation. Use the booking tool first." };
+    return { error: "Nothing is staged after all — ask the caller again what they want." };
   }
   const described = describeAction(action);
   if (typeof described !== "string") return described;

package/dist/templates/travel-concierge/tools/book_car_rental.ts

@@ -10,8 +10,8 @@ export default tripSlot.updateTool({
     carId: z.string().max(20).describe("The car id from search_car_rentals, e.g. 'C2'"),
     days: z.number().int().min(1).max(60).describe("How many days"),
   }),
-  execute(args, trip) {
-    return stageAction(trip, {
+  execute(args, trip, ctx) {
+    return stageAction(ctx, trip, {
       kind: "book_car",
       carId: args.carId.toUpperCase(),
       days: args.days,

package/dist/templates/travel-concierge/tools/book_excursion.ts

@@ -9,8 +9,8 @@ export default tripSlot.updateTool({
   inputSchema: z.object({
     excursionId: z.string().max(20).describe("The excursion id from search_excursions, e.g. 'E2'"),
   }),
-  execute(args, trip) {
-    return stageAction(trip, {
+  execute(args, trip, ctx) {
+    return stageAction(ctx, trip, {
       kind: "book_excursion",
       excursionId: args.excursionId.toUpperCase(),
     });

package/dist/templates/travel-concierge/tools/book_hotel.ts

@@ -10,8 +10,8 @@ export default tripSlot.updateTool({
     hotelId: z.string().max(20).describe("The hotel id from search_hotels, e.g. 'H1'"),
     nights: z.number().int().min(1).max(30).describe("How many nights"),
   }),
-  execute(args, trip) {
-    return stageAction(trip, {
+  execute(args, trip, ctx) {
+    return stageAction(ctx, trip, {
       kind: "book_hotel",
       hotelId: args.hotelId.toUpperCase(),
       nights: args.nights,

package/dist/templates/travel-concierge/tools/cancel_ticket.ts

@@ -9,8 +9,8 @@ export default tripSlot.updateTool({
   description:
     "Cancel the caller's ticket outright. This does NOT cancel anything yet — " +
     "it stages the cancellation so you can read it back and hear a yes.",
-  execute(_args, trip) {
+  execute(_args, trip, ctx) {
     if (!trip.ticket) return { error: "There is no ticket to cancel." };
-    return stageAction(trip, { kind: "cancel_ticket" });
+    return stageAction(ctx, trip, { kind: "cancel_ticket" });
   },
 });

package/dist/templates/travel-concierge/tools/update_ticket.ts

@@ -13,10 +13,10 @@ export default tripSlot.updateTool({
   inputSchema: z.object({
     flightId: z.string().max(20).describe("The flight to move to, e.g. 'LX52'"),
   }),
-  execute(args, trip) {
+  execute(args, trip, ctx) {
     if (!trip.ticket) {
       return { error: "This caller has no ticket to move — it was cancelled on this call." };
     }
-    return stageAction(trip, { kind: "update_ticket", flightId: args.flightId.toUpperCase() });
+    return stageAction(ctx, trip, { kind: "update_ticket", flightId: args.flightId.toUpperCase() });
   },
 });

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.10.1",
+  "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.10.1",
-    "@alexkroman1/aai-ui": "6.10.1"
+    "@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"