@alexkroman1/aai-cli 9.2.0 → 10.0.0

package/dist/cli.mjs

@@ -259,7 +259,7 @@ const secret = defineCommand({
 			},
 			cwd: "any",
 			async run({ args, mode, cwd }) {
-				const { executeSecretPut, NO_INPUT, readStdin } = await import("./secret-CwgDLpSy.mjs");
+				const { executeSecretPut, NO_INPUT, readStdin } = await import("./secret-B-3T5tvr.mjs");
 				const value = mode === "json" ? await readStdin() : void 0;
 				if (mode === "json" && !value) throw new CliError(...NO_INPUT);
 				return executeSecretPut(cwd, args.name, value, args.server);
@@ -281,7 +281,7 @@ const secret = defineCommand({
 			},
 			cwd: "any",
 			async run({ args, cwd }) {
-				const { executeSecretDelete } = await import("./secret-CwgDLpSy.mjs");
+				const { executeSecretDelete } = await import("./secret-B-3T5tvr.mjs");
 				return executeSecretDelete(cwd, args.name, args.server);
 			}
 		}),
@@ -296,7 +296,7 @@ const secret = defineCommand({
 			},
 			cwd: "any",
 			async run({ args, cwd }) {
-				const { executeSecretList } = await import("./secret-CwgDLpSy.mjs");
+				const { executeSecretList } = await import("./secret-B-3T5tvr.mjs");
 				return executeSecretList(cwd, args.server);
 			}
 		})
@@ -327,7 +327,7 @@ const logs = defineExec({
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeLogs } = await import("./logs-D2Yhqe2w.mjs");
+		const { executeLogs } = await import("./logs-hWnJ66Bl.mjs");
 		return executeLogs(resolveDirArg(cwd, args.dir), {
 			server: args.server,
 			follow: args.follow
@@ -358,7 +358,7 @@ const list = defineExec({
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeList } = await import("./studio-D3-HWIfk.mjs");
+		const { executeList } = await import("./studio-wVWNLREn.mjs");
 		return executeList({
 			cwd,
 			server: args.server
@@ -391,7 +391,7 @@ const pull = defineExec({
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executePull } = await import("./studio-D3-HWIfk.mjs");
+		const { executePull } = await import("./studio-wVWNLREn.mjs");
 		return executePull({
 			cwd,
 			project: args.project,
@@ -413,7 +413,7 @@ const push = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePush } = await import("./studio-D3-HWIfk.mjs");
+		const { executePush } = await import("./studio-wVWNLREn.mjs");
 		return executePush({
 			cwd,
 			server: args.server,
@@ -437,7 +437,7 @@ const publish = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePublish } = await import("./studio-D3-HWIfk.mjs");
+		const { executePublish } = await import("./studio-wVWNLREn.mjs");
 		return executePublish({
 			cwd,
 			server: args.server,
@@ -468,6 +468,25 @@ const workflowToken = {
 	type: "string",
 	description: "Bearer for an agent that sets AAI_WORKFLOW_API_TOKEN"
 };
+/**
+* `--agent <url>` — target a server the caller is running THEMSELVES.
+*
+* The workflow API is the one agent surface that is fully live under `aai dev`,
+* and until this flag existed there was no way to say so: every verb resolved a
+* platform origin plus a PUBLISHED slug, so an undeployed project was told to
+* `aai publish` while the runs it asked about were answering on localhost. A
+* dev server also has no slug segment at all (`createServer` mounts the API on
+* the origin), so a different `--server` could not express it either.
+*
+* Separate from `--server` rather than a mode of it, because the two carry
+* different credentials: `--server` is paired with the user's platform API key
+* and is trust-checked for that reason, where this reaches a bare agent and
+* sends nothing but `--token`. See `workflow.ts`.
+*/
+const workflowAgent = {
+	type: "string",
+	description: "Base URL of a server you are running (e.g. `aai dev` on http://localhost:3000)"
+};
 /** The positional every run-scoped verb takes. */
 const runIdArg = {
 	type: "positional",
@@ -482,7 +501,8 @@ const runIdArg = {
 const workflowArgs = {
 	server: sharedArgs.server,
 	json: sharedArgs.json,
-	token: workflowToken
+	token: workflowToken,
+	agent: workflowAgent
 };
 /**
 * Every verb here reads `.aai/project.json` for the origin and the published
@@ -504,10 +524,11 @@ const workflow = defineCommand({
 			args: workflowArgs,
 			cwd: WORKFLOW_CWD,
 			async run({ args, cwd }) {
-				const { executeWorkflowList } = await import("./workflow-BflATMmU.mjs");
+				const { executeWorkflowList } = await import("./workflow-BBu5oEDw.mjs");
 				return executeWorkflowList(cwd, {
 					server: args.server,
-					token: args.token
+					token: args.token,
+					agent: args.agent
 				});
 			}
 		}),
@@ -530,12 +551,13 @@ const workflow = defineCommand({
 			},
 			cwd: WORKFLOW_CWD,
 			async run({ args, cwd }) {
-				const { executeWorkflowRuns } = await import("./workflow-BflATMmU.mjs");
+				const { executeWorkflowRuns } = await import("./workflow-BBu5oEDw.mjs");
 				const limit = args.limit === void 0 ? void 0 : Number(args.limit);
 				if (limit !== void 0 && !Number.isFinite(limit)) throw new CliError("bad_limit", "--limit must be a number");
 				return executeWorkflowRuns(cwd, args.workflow, {
 					server: args.server,
 					token: args.token,
+					agent: args.agent,
 					limit
 				});
 			}
@@ -551,10 +573,11 @@ const workflow = defineCommand({
 			},
 			cwd: WORKFLOW_CWD,
 			async run({ args, cwd }) {
-				const { executeWorkflowShow } = await import("./workflow-BflATMmU.mjs");
+				const { executeWorkflowShow } = await import("./workflow-BBu5oEDw.mjs");
 				return executeWorkflowShow(cwd, args.runId, {
 					server: args.server,
-					token: args.token
+					token: args.token,
+					agent: args.agent
 				});
 			}
 		}),
@@ -569,10 +592,11 @@ const workflow = defineCommand({
 			},
 			cwd: WORKFLOW_CWD,
 			async run({ args, cwd }) {
-				const { executeWorkflowCancel } = await import("./workflow-BflATMmU.mjs");
+				const { executeWorkflowCancel } = await import("./workflow-BBu5oEDw.mjs");
 				return executeWorkflowCancel(cwd, args.runId, {
 					server: args.server,
-					token: args.token
+					token: args.token,
+					agent: args.agent
 				});
 			}
 		})
@@ -647,7 +671,7 @@ const mainCommand = defineCommand({
 			},
 			cwd: "none",
 			async run({ args, mode }) {
-				const { executeInit } = await import("./init-DK7GpIF9.mjs");
+				const { executeInit } = await import("./init-BRfoc2EK.mjs");
 				return executeInit({
 					dir: args.dir,
 					force: args.force,
@@ -678,7 +702,7 @@ const mainCommand = defineCommand({
 			},
 			cwd: "agent",
 			async run({ args, cwd }) {
-				const { executeDev } = await import("./dev-dFzdvwa7.mjs");
+				const { executeDev } = await import("./dev-BfVl1uBA.mjs");
 				return executeDev({
 					cwd,
 					port: args.port,
@@ -728,7 +752,7 @@ const mainCommand = defineCommand({
 			},
 			cwd: "agent",
 			async run({ args, cwd }) {
-				const { executeBuild } = await import("./build-DvDdSwAS.mjs");
+				const { executeBuild } = await import("./build-DKC2e9o_.mjs");
 				return executeBuild({
 					cwd,
 					skipTests: args.skipTests,
@@ -760,7 +784,7 @@ const mainCommand = defineCommand({
 			},
 			cwd: "agent",
 			async run({ args, cwd }) {
-				const { executeDeploy } = await import("./deploy-CjU3e-3P.mjs");
+				const { executeDeploy } = await import("./deploy-CchW5pmw.mjs");
 				return executeDeploy({
 					cwd,
 					server: args.server,
@@ -780,7 +804,7 @@ const mainCommand = defineCommand({
 			},
 			cwd: "any",
 			async run({ args, cwd }) {
-				const { executeDelete } = await import("./delete-8pjH8n8n.mjs");
+				const { executeDelete } = await import("./delete-X_CRgCf6.mjs");
 				return executeDelete({
 					cwd,
 					server: args.server
@@ -813,7 +837,7 @@ const mainCommand = defineCommand({
 			args: { json: sharedArgs.json },
 			cwd: "none",
 			async run({ mode }) {
-				const { listTemplates } = await import("./_templates-4WcKOjS5.mjs");
+				const { listTemplates } = await import("./_templates-0Zr2z6yA.mjs");
 				const names = await listTemplates();
 				if (mode === "human") {
 					for (const name of names) log.message(name);

package/dist/{delete-8pjH8n8n.mjs → delete-X_CRgCf6.mjs}

@@ -3,7 +3,7 @@ import { a as ok } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
 import { l as writeProjectConfig } from "./_config-CmJOFsAP.mjs";
 import { a as resolveDeployTarget, i as requireDeployedSlug } from "./_agent-BTwZJu4P.mjs";
-import { d as apiTestSeam, l as HINT_NOT_DEPLOYED, s as studioProjectApiUrl, u as apiRequest } from "./_studio-CKrsixd0.mjs";
+import { d as apiTestSeam, l as HINT_NOT_DEPLOYED, s as studioProjectApiUrl, u as apiRequest } from "./_studio-B1waXMuR.mjs";
 import { omitUndefined } from "@alexkroman1/aai/utils";
 //#region delete.ts
 async function runDelete(opts) {

package/dist/{deploy-CjU3e-3P.mjs → deploy-CchW5pmw.mjs}

@@ -3,11 +3,11 @@ import { a as ok } from "./_output-CKkmWs7i.mjs";
 import { n as log, r as notify, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
 import { o as errorMessage$1 } from "./_utils-B8QmtFhK.mjs";
 import { s as updateProjectConfig } from "./_config-CmJOFsAP.mjs";
-import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-CDuYl5Gb.mjs";
+import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-B31MqYaD.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
 import { a as resolveDeployTarget } from "./_agent-BTwZJu4P.mjs";
 import { assertTypechecks } from "./_typecheck-gate-BXvUNnfs.mjs";
-import { d as apiTestSeam, f as checkedResponse, i as projectNameFromDir, u as apiRequest } from "./_studio-CKrsixd0.mjs";
+import { d as apiTestSeam, f as checkedResponse, i as projectNameFromDir, u as apiRequest } from "./_studio-B1waXMuR.mjs";
 import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { gzipSync } from "node:zlib";
 //#region _deploy.ts

package/dist/{dev-dFzdvwa7.mjs → dev-BfVl1uBA.mjs}

@@ -12,7 +12,7 @@ import { styleText } from "node:util";
 async function executeDev(opts) {
 	const port = parsePort(opts.port);
 	const agentName = path.basename(path.resolve(opts.cwd));
-	const { startDevServer } = await import("./_dev-server-BAR8Ya43.mjs");
+	const { startDevServer } = await import("./_dev-server-Bo5dSBzQ.mjs");
 	let cleanup;
 	let shuttingDown = false;
 	const onSignal = () => {

package/dist/{init-DK7GpIF9.mjs → init-BRfoc2EK.mjs}

@@ -106,7 +106,7 @@ function collectWarnings() {
 }
 /** Publish after init and return deploy metadata if successful. */
 async function tryPublish(cwd, server, warn) {
-	const { executePublish } = await import("./studio-D3-HWIfk.mjs");
+	const { executePublish } = await import("./studio-wVWNLREn.mjs");
 	try {
 		const result = await executePublish({
 			cwd,
@@ -127,7 +127,7 @@ async function tryPublish(cwd, server, warn) {
 }
 /** Scaffold the project, optionally showing a spinner. */
 async function scaffoldProject(dir, cwd, template, silent) {
-	const { runInit } = await import("./_init-BNotRgV1.mjs");
+	const { runInit } = await import("./_init-BURbdHNM.mjs");
 	await withSpinner(silent, {
 		start: `Creating ${dir}`,
 		done: "Project created",

package/dist/{logs-D2Yhqe2w.mjs → logs-hWnJ66Bl.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { a as ok } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
-import { f as checkedResponse } from "./_studio-CKrsixd0.mjs";
-import { n as slugRequest } from "./_slug-api--ZBmIGH-.mjs";
+import { f as checkedResponse } from "./_studio-B1waXMuR.mjs";
+import { n as slugRequest } from "./_slug-api-CfGQq1Tt.mjs";
 import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { sleep } from "@alexkroman1/aai/internal";
 function isLogsPage(value) {

package/dist/scaffold/CLAUDE.md

@@ -25,7 +25,7 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
 
    **A spec that needs the agent as DEPLOYED imports one module:**
 
-   ```ts no-check
+   ```ts
    import agentDef from "virtual:aai/agent";
    ```
 
@@ -405,58 +405,174 @@ everything in flight is lost when that process goes away. That is the honest
 tradeoff, and it is what
 lets you build a workflow app before provisioning anything.
 
-One thing does need a database whatever the run does: a workflow **upload**. An
-upload's record is a row, so `api.upload` and the file-taking form hooks refuse
-by name without a `DATABASE_URL`. (`ctx.db` was the other; there is no `ctx.db`
-— see "Persisting data" below.)
+**A workflow UPLOAD is durable with no setup either**, and this paragraph used
+to say the opposite. An upload's record is a platform row and its bytes are
+platform storage, so `api.upload`, `<FileField>` and the file-taking form
+hooks outlive the sandbox exactly as the runs reading them do — a deployed app
+needs no database of its own for either half. Under `aai dev` they are as
+temporary as the runs above: the bytes go to a per-process temporary directory
+that a restart abandons. There is no `ctx.db` at all — see "Persisting data"
+below.
 
 ### Workflow bodies live in `workflows/`
 
-The build transforms that directory and nothing else. A `"use workflow"` body
-written in `agent.ts` is never transformed — it runs inline once, with no
-durability and nothing saying so.
+A body is an ordinary exported async function of its input and a `WorkflowCtx`.
+There is no directive and no compile step of its own — the agent bundle compiles
+`workflows/` like any other source file — and durability is a method call:
 
 ```ts
-import { sleep } from "workflow";
+import type { WorkflowCtx } from "@alexkroman1/aai";
 
-export async function digestFlow(input: { url: string }) {
-  "use workflow";
+export async function digestFlow(input: { url: string }, ctx: WorkflowCtx) {
+  const digest = await ctx.step("summarize", () => summarize(input.url));
 
-  const digest = await summarize(input.url);
   // Suspended, not blocked: the container is free to exit here and the run
-  // resumes when it comes due. `"6 hours"` works the same as `"10 seconds"`.
-  await sleep("10 seconds");
-  return { ...digest, filedAt: await file(digest) };
+  // resumes when it comes due. Six hours works the same as ten seconds.
+  await ctx.sleep(10_000);
+
+  const filedAt = await ctx.step("file", () => file(digest));
+  return { ...digest, filedAt };
 }
 
 async function summarize(url: string) {
-  "use step";
   // The whole Node runtime is available in a step: fetch, a model call, a
   // database. Not in the body.
   return { url, headline: `What ${new URL(url).hostname} says`, points: [] };
 }
 
-async function file(digest: { url: string }) {
-  "use step";
+async function file(_digest: { url: string }) {
   return new Date().toISOString();
 }
 ```
 
-Three rules. The second and third fail silently if broken; the first is
-warned about by `aai build` and `aai dev`, naming the file and the call:
+`ctx.step(name, fn)` runs `fn` once, journals what it returned, and on every
+later replay returns the journaled value without running it again. The step
+functions themselves are ordinary functions — which is also what lets a spec call
+one directly, with no engine in the path.
+
+Three rules, and all three fail silently if broken — nothing scans a body for
+them:
 
 - **The body replays from the top on every resume**, so it holds no live handle
   and makes no undurable decision — no `Date.now()`, no `Math.random()`, no
-  `crypto.randomUUID()`, no `fetch`. Those belong in a step, whose result is
-  journaled and returned unchanged on replay. (The warning reads the built
-  workflow bundle, where step bodies have already been removed, so a step doing
-  any of this is not flagged — that is what a step is FOR.)
+  `crypto.randomUUID()`, no `fetch`. Those go inside a `ctx.step`, whose result
+  is journaled and returned unchanged on replay.
 - **A step's arguments and return value cross a queue**, so they must be
   JSON-shaped and small. Put bytes in storage and pass the key.
-- **A step gets no tool context.** It is bundled and dispatched separately from
-  the agent, so there is no `ctx` in one — see below for how it reaches the
-  agent's env and a model anyway. A step reaches a database the same way a tool
-  does now — its own client, its own credential from `requireStepEnv`.
+- **A step gets no tool context.** There is no `ctx.db` and no `ctx.generate`
+  inside one — see below for how it reaches the agent's env and a model anyway.
+  A step reaches a database the way a tool does: its own client, its own
+  credential from `requireStepEnv`.
+
+**A step's NAME is its identity in the journal**, so write a string literal and
+keep it stable: renaming one makes an in-flight run re-run that step. A single
+call site inside a loop or a `mapConcurrent` fan-out is exactly what the scheme
+is for — each reach gets its own entry — but two DIFFERENT call sites should not
+share a name: the journal keys an entry by `(name, occurrence)`, so two sites
+alias onto one counter and read each other's journaled results. Nothing detects
+it.
+
+**Per-step retries are an argument, not a property.** Pass
+`{ maxAttempts }` where a step deserves more patience than the default three:
+
+```ts no-check
+const digest = await ctx.step("summarize", () => summarize(input.url), {
+  maxAttempts: 6,
+});
+```
+
+### Waiting: `ctx.sleep` and `ctx.waitFor`
+
+Both SUSPEND the run — the body stops, the container is free, and the engine
+brings the run back — so a long wait costs nothing while it runs.
+
+**How long a wait really survives is a property of the run STORE.** On the
+platform it is durable with no setup, and a self-hosted deployment with a
+`DATABASE_URL` is durable too — the wait outlives the body, the worker and the
+process. Under `aai dev` without a `DATABASE_URL` the store is memory, so a wait
+lives only as long as the dev server. The boot line reports which one is in play.
+
+```ts no-check
+// A duration in milliseconds, or an absolute Date.
+await ctx.sleep(6 * 60 * 60 * 1000, { correlationId: "review-window" });
+
+// Until somebody outside the run answers, via `ctx.workflows.signal(token, …)`
+// from a tool, or by a delivery to `publicWebhookUrl` — both hops reach the
+// same waitpoint.
+const approval = await ctx.waitFor<{ approved: boolean }>(approvalToken(input.id), {
+  timeoutMs: 120_000,
+});
+if (approval === undefined) return { published: false, reason: "nobody approved" };
+```
+
+Four things worth knowing:
+
+- **A hook's token must be DERIVED, not random.** Whoever signals is usually a
+  tool, and a tool cannot see the body's local variables — so export one function
+  that computes the token from the run's own input and import it in both places.
+  Derive it from something that identifies the RUN rather than the caller: a
+  token is held for the life of its run, so two runs deriving the same one is the
+  second one failing.
+- **`timeoutMs` resolves `undefined` when the window closes unanswered.** A
+  closing window is an outcome to branch on, not a failure, and the engine closes
+  the hook as it shuts so a late answer cannot change what already happened.
+- **Do NOT race the two.** `Promise.race([ctx.waitFor(t), ctx.sleep(ms)])` does
+  not work: both suspend, and a suspend unwinds the stack, so the race stops the
+  body before the other side has been reached. That is why the deadline is a
+  parameter.
+- **`ctx.workflows.wakeUp(runId, { correlationIds: [id] })`** ends a sleep early,
+  which is how a "send it now" tool cuts a scheduled wait short. Naming no ids
+  wakes every outstanding SLEEP and deliberately not a `waitFor` deadline, so
+  cutting a schedule short cannot also close an approval window.
+
+#### A third-party callback is an OPTIMIZATION over a reconciling read
+
+The webhook route is how a payment provider, a transcription service or an
+approval mailer resumes a run, and `recap-workflow` is the worked example — it
+hands AssemblyAI a `webhook_url` and parks on the delivery instead of polling
+for twenty minutes. Five things about that shape, and every one of them is a
+trap somebody has already paid for:
+
+- **Mint it with `stepWebhookUrl(token)`, from inside the step that hands it
+  over.** That is the step-side half of `ctx.workflows.publicWebhookUrl` — the
+  tool-side one needs a `ToolContext`, and a workflow body and its steps are
+  handed none, so a workflow app with no tools has only this one. It THROWS when
+  the deployment cannot mint one, which a step should catch and treat as "no
+  callback": a run must not fail over a missing optimization. And note
+  `requireStepEnv("AAI_PUBLIC_BASE_URL")` is NOT a substitute — the public base
+  URL is a boot parameter of the deployment, not one of the agent's own secrets,
+  so that read is `undefined` in production precisely where the value exists.
+- **Return the callback FACT from the step, and branch on that.** Whether a
+  callback was registered decides whether the body parks, and a body may only
+  branch on values that came out of the journal. Mint inside the step's function
+  — it runs once, on first execution, never on a replay — and answer
+  `{ id, callback }`. A body that re-minted on every walk could flip the branch
+  under a redeploy and then look for a `waitFor` the journal never recorded.
+- **Keep the poll as the TIMEOUT arm.** A webhook is one HTTP POST from a third
+  party with no delivery guarantee you control: the sender gives up after its own
+  retry budget, a deployment may not know its public URL, and a delivery that
+  lands before your body reaches its wait is answered `404` and dropped. So read
+  the state before you park and again after, give the wait a `timeoutMs`, and let
+  an unanswered window fall through to the read. A run that hangs forever on a
+  dropped delivery is strictly worse than one that polls.
+- **Wait for the EDGE, not the answer.** Treat the payload as "something
+  happened, go look" and get the fact from the far side's own API under your own
+  credential. That is what makes an unauthenticated callback route safe: a forged
+  delivery on a guessed token costs one extra read and changes no outcome. It
+  holds by construction, where a shared secret holds only until somebody has to
+  rotate it — and the route authorizes on the TOKEN and reads no other header, so
+  a sender's own auth-header option would be sent and ignored.
+- **One token, ONE `waitFor` per run.** A token is claimed for the life of its
+  run and given back when the run goes terminal, so a second `ctx.waitFor` on the
+  same token — a wait written inside a loop — THROWS. A throw is not a suspend,
+  so a body with a `catch` will treat it as a failed run and start compensating.
+  Park once, outside the loop.
+- **You cannot test it under `aai dev` without a tunnel.** `publicUrl` there is
+  `http://localhost:<backend port>`, which no third party can reach — so the
+  delivery never arrives, the run silently takes the fallback, and the webhook
+  half of your code is exercised by nothing. `PUBLIC_URL=https://<your tunnel>
+  pnpm dev` is what makes it reachable. Until you set it, treat local runs as
+  coverage of the backstop only.
 
 ### A step's env, and calling a model from one
 
@@ -465,13 +581,11 @@ A step has no `ctx`, so the two things tool code takes for granted come from
 `@alexkroman1/aai` — a `workflows/*.ts` module is bundled separately, and the
 root barrel would drag the whole SDK into that bundle.
 
-```ts no-check
+```ts
 import { stepEnv } from "@alexkroman1/aai/step";
 import { stepGenerateClassified } from "@alexkroman1/aai/step-errors";
 
 async function summarize(text: string) {
-  "use step";
-
   // The agent's env by name — the same values a tool reads from `ctx.env`.
   // `requireStepEnv` fails naming the key; `stepEnv` returns undefined.
   const style = stepEnv("DIGEST_STYLE") ?? "plain";
@@ -494,8 +608,8 @@ deploy. Use `stepGenerateJsonClassified` with a Zod `schema` if you need a shape
 ### From a step, reach for the `Classified` call
 
 `@alexkroman1/aai/step-errors` publishes a wrapper for every `/step` call that
-can fail against a remote service, and **inside a `"use step"` body the wrapper
-is the one to use**:
+can fail against a remote service, and **inside a step the wrapper is the one to
+use**:
 
 | Raw, on `@alexkroman1/aai/step` | Use this instead, on `@alexkroman1/aai/step-errors` |
 | --- | --- |
@@ -512,9 +626,9 @@ while this also turns a NON-2XX RESPONSE into a throw — `stepFetch` resolves
 with a `404` rather than raising it. Two changes, so two names.
 
 The whole of what a wrapper adds is `throwStepError`, and that is worth having
-because the DevKit's retry policy is decided by WHICH error a step throws. Raw,
+because the engine's retry policy is decided by WHICH error a step throws. Raw,
 every failure looks the same to it: a bad API key is retried until the attempts
-run out, and a rate limit backs off for the DevKit's default one second while
+run out, and a rate limit backs off for the engine's default one second while
 the delay the gateway itself named sits unread on the error. Classified, a
 terminal failure raises `FatalError` and stops, and a transient one raises
 `RetryableError` carrying the far side's own `Retry-After`. That matters most
@@ -529,11 +643,11 @@ or `throwFfmpegStepError(err)` for a media failure, whose default runs the other
 way (only a `timeout` or an `aborted` is worth another attempt).
 
 **Why the split exists, since the wrapper is what you usually want:** this is
-the one authoring module allowed to import the DevKit's `workflow` package, and
-`/step` is not written only for a step — `mapConcurrent` bounds a rate-limited
-call anywhere, `stepFetch` is an ordinary HTTP client, and your specs drive
-exported steps directly. Putting `workflow` in `/step`'s graph would put it in
-every one of those bundles. A step pays nothing for the extra import line.
+importing from here is the OPT-IN, and `/step` is not written only for a step —
+`mapConcurrent` bounds a rate-limited call anywhere, `stepFetch` is an ordinary
+HTTP client, and your specs drive exported steps directly. None of those callers
+has a retry budget to burn, so none should meet a vocabulary whose whole subject
+is one. A step pays nothing for the extra import line.
 
 ### Media, big files, and transcription from a step
 
@@ -564,8 +678,6 @@ import { throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
 import { readUploadToFile, withTempDir } from "@alexkroman1/aai/step-files";
 
 export async function measure(uploadId: string) {
-  "use step";
-
   return await withTempDir(async (dir) => {
     const path = `${dir}/input`;
     // Read the upload ONCE. A five-step version reads it five times, and on a
@@ -591,8 +703,6 @@ import { requireStepEnv } from "@alexkroman1/aai/step";
 import { sendToChannelClassified } from "@alexkroman1/aai/step-errors";
 
 export async function announce(headline: string, points: string[]) {
-  "use step";
-
   const message: ChannelMessage = {
     text: headline,
     sections: points.map((point) => ({ text: point })),
@@ -619,8 +729,6 @@ call to make from a step, for a reason nothing at the call site shows:
 import { multipartBody, stepFetch, StepTransportError } from "@alexkroman1/aai/step";
 
 async function transcribeChunk(key: string, bytes: Uint8Array, index: number) {
-  "use step";
-
   // Multipart as BYTES. Never a `FormData` — see below.
   const part = multipartBody({
     name: "audio",
@@ -654,7 +762,7 @@ and pathological for `mapConcurrent` over large bodies. Measured on 8 concurrent
 HTTP/2 a capacity limit arrives as a *stream reset* — `NGHTTP2_ENHANCE_YOUR_CALM`
 — and a stream error carries no HTTP status, so `isTransientStatus` and
 `retryAfter` cannot see it. Every sibling in the batch then retries in lockstep
-into the same reset, exhausts `maxRetries`, and fails the run with
+into the same reset, exhausts the step's attempts, and fails the run with
 `TypeError: fetch failed`, whose real cause is two `cause` hops down where
 nothing prints it. Over HTTP/1.1 the identical limit arrives as `503` with
 `retry-after`, which your retry policy already reads.
@@ -686,12 +794,10 @@ generated PDF — needs two things a first draft reaches for and does not find.
 Both are on `@alexkroman1/aai/step`, and `spoken-summary` is the template that
 shows the whole round trip.
 
-```ts no-check
+```ts
 import { stepSpeak, writeUpload } from "@alexkroman1/aai/step";
 
 export async function narrate(script: string) {
-  "use step";
-
   const spoken = await stepSpeak(script, { voice: "jane" });
   const stored = await writeUpload(spoken.audio, { name: "summary.wav", type: "audio/wav" });
   return { audio: stored.id, durationMs: spoken.durationMs };
@@ -1205,7 +1311,7 @@ fixing one call site at a time.
 **A `sessionSlot` is the only way to keep state across a session's tool calls**,
 and it is one declaration in a shared module:
 
-```ts no-check
+```ts
 // shared.ts — the one place the shape is written down.
 import { sessionSlot } from "@alexkroman1/aai";
 
@@ -1300,7 +1406,7 @@ collect an address before taking payment is a suggestion; a dialog is a rule.
 that leave it. It is a slot underneath, so the position is persisted with the
 rest of the session and survives a reconnect.
 
-```ts no-check
+```ts
 import { dialog } from "@alexkroman1/aai";
 
 export const checkout = dialog("checkout", {
@@ -1507,7 +1613,7 @@ export default tool({
 });
 ```
 
-```ts no-check
+```ts
 // agent.ts — nothing about tools appears here
 import { agent } from "@alexkroman1/aai";
 
@@ -1655,8 +1761,10 @@ HTTP API, a provider SDK or a hosted KV works the same way.
   nothing else.
 - **Durable workflow runs** — a run survives the sandbox recycling, every
   redeploy, and a multi-day `sleep()`.
+- **Workflow uploads** — a file a form submitted, record and bytes both, so a
+  resumed run reads the same recording the browser sent.
 
-Those two cover almost everything an agent wants. A database is for data that
+Those three cover almost everything an agent wants. A database is for data that
 must outlive a session AND be queryable: a ledger, filed records, cross-session
 saves.
 

package/dist/scaffold/package.json

@@ -14,19 +14,17 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^9.2.0",
-    "@alexkroman1/aai-runtime": "^9.2.0",
-    "@alexkroman1/aai-ui": "^9.2.0",
-    "@workflow/world-postgres": "4.3.3",
+    "@alexkroman1/aai": "^10.0.0",
+    "@alexkroman1/aai-runtime": "^10.0.0",
+    "@alexkroman1/aai-ui": "^10.0.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
-    "workflow": "4.8.2",
     "xstate": "^5.32.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^9.2.0",
+    "@alexkroman1/aai-cli": "^10.0.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",