@alexkroman1/aai-cli 9.2.0 → 10.0.1

package/dist/templates/transcription-workflow/workflows/transcribe.ts

@@ -63,16 +63,19 @@
  *   `output` exists only when the last segment does.
  */
 
+import type { WorkflowCtx } from "@alexkroman1/aai";
 import {
   emit,
   encodeWav,
   mapConcurrent,
   readUpload,
   report,
+  requireCompleteUpload,
   uploadInfo,
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
 import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
+import { downsampleSegment, requestFormat } from "./downsample.ts";
 import { normalizeRecording } from "./normalize.ts";
 import { stitchTranscript, TRANSCRIPT_STREAM, type TranscriptChunk } from "./stitch.ts";
 import { elapsed, timed, transcribeWav } from "./sync-api.ts";
@@ -168,15 +171,18 @@ export const BYTES_IN_FLIGHT = 640 * 1024 * 1024;
  * The table above was measured under the old per-round barrier. Re-measuring it is
  * worth doing before this number moves again: the window makes a wide fan-out
  * cheaper at the tail, which if anything argues for a HIGHER knee. *
- * **What EXECUTES at this width is the world's call, not this number's.**
+ * **What EXECUTES at this width is the engine's call, not this number's.**
  * `mapConcurrent` bounds how many step calls the body has in flight; how many
- * run at once is the workflow world's worker concurrency, which on the
- * `DATABASE_URL` path defaults to three — so on a default deployment a width
- * above three is inert while still costing a queued job per item. That makes
- * this the FAR SIDE's knee and the width to use once an operator has raised
- * the ceiling, not a promise about a stock deployment. See "The WINDOW is not
- * the concurrency" in `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers
- * above were measured against the endpoint and say nothing about that layer.
+ * run at once is `DEFAULT_STEP_CONCURRENCY` (`aai-runtime`), which is **16** —
+ * measured against a real microVM at Modal's guaranteed reservation, where a
+ * concurrent segment of 48 kHz stereo costs 26.1 MB. So a width above 16 is
+ * inert on a stock deployment while still costing a queued job per item, and
+ * this number is the FAR SIDE's knee: the one to use once an operator has
+ * raised `AAI_WORKFLOW_STEP_CONCURRENCY` for a larger guest. It was three,
+ * inherited from graphile-worker and never measured, which made every number
+ * in the table above unreachable. See "The WINDOW is not the concurrency" in
+ * `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers above were measured
+ * against the endpoint and say nothing about that layer.
  */
 export const MAX_SEGMENT_CONCURRENCY = 32;
 
@@ -199,7 +205,13 @@ export const MAX_SEGMENT_CONCURRENCY = 32;
  * `stepFetch` pins.
  */
 export function segmentConcurrency(format: WavFormat): number {
-  const perSegment = bytesPerSecond(format) * (SEGMENT_SECONDS + SEGMENT_OVERLAP_SECONDS);
+  // The format that will be SENT, not the one that was cut. The budget is bytes
+  // UPLOADING and `transcribeSegment` normalizes each window first, so asking the
+  // source format would price a 48 kHz stereo segment at 17.66 MB when 2.94 MB
+  // goes on the wire — six times too cautious, and drifting the moment either
+  // side of that pair changes. Both derive it from `requestFormat`.
+  const perSegment =
+    bytesPerSecond(requestFormat(format)) * (SEGMENT_SECONDS + SEGMENT_OVERLAP_SECONDS);
   if (perSegment <= 0) return MAX_SEGMENT_CONCURRENCY;
   return Math.max(1, Math.min(MAX_SEGMENT_CONCURRENCY, Math.floor(BYTES_IN_FLIGHT / perSegment)));
 }
@@ -236,9 +248,7 @@ export type SegmentTranscript = {
  * The input is what `POST /workflows/runs` carries — see `agent.ts` for the
  * schema it is validated against before a run exists.
  */
-export async function transcribeFlow(input: { recording: string }) {
-  "use workflow";
-
+export async function transcribeFlow(input: { recording: string }, ctx: WorkflowCtx) {
   // Both at once: neither needs the other, and issued together they are one
   // round trip instead of two before any audio is read. The ORDER is still a
   // pure function of this line — the two calls go out synchronously, left to
@@ -247,12 +257,20 @@ export async function transcribeFlow(input: { recording: string }) {
   // The clock starts before the conversion rather than after it, because a
   // reader comparing the three flows over one file is comparing what the desk
   // COST them, and re-encoding an m4a is part of that.
-  const [startedAt, ready] = await Promise.all([startClock(), normalizeRecording(input.recording)]);
+  // `maxAttempts: 6` was `normalizeRecording.maxRetries = 5`. More than the
+  // default 3, and not because a conversion is flaky — a corrupt file fails
+  // identically forever, and `throwFfmpegStepError` is what stops the engine
+  // retrying that. It is the two I/O halves that are worth another attempt: this
+  // step reads a whole recording out of the store and writes a whole one back.
+  const [startedAt, ready] = await Promise.all([
+    ctx.step("startClock", () => startClock()),
+    ctx.step("normalizeRecording", () => normalizeRecording(input.recording), { maxAttempts: 6 }),
+  ]);
 
   // `ready.recording` from here on, not `input.recording`: a converted file is a
   // DIFFERENT upload, and cutting the original by offsets planned against the
   // converted one is a fan-out of garbage that still reports success.
-  const plan = await splitRecording(ready.recording);
+  const plan = await ctx.step("splitRecording", () => splitRecording(ready.recording));
 
   // One step per segment, bounded, in an order a replay reproduces exactly.
   // A failed segment fails the RUN, deliberately: every sibling that finished is
@@ -260,13 +278,20 @@ export async function transcribeFlow(input: { recording: string }) {
   // what is missing, where catching here to salvage a partial transcript would
   // return a recording with a silent hole in it and report success.
   const parts = await mapConcurrent(plan.segments, segmentConcurrency(plan.format), (segment) =>
-    transcribeSegment(ready.recording, plan.format, segment),
+    // `maxAttempts: 6` was `transcribeSegment.maxRetries = 5` — more than the
+    // default 3 because a rate limit is the expected failure here, and a segment
+    // that 429s is not a segment that is wrong.
+    ctx.step("transcribeSegment", () => transcribeSegment(ready.recording, plan.format, segment), {
+      maxAttempts: 6,
+    }),
   );
 
   // The ORIGINAL id, and only here: `mergeTranscript` uses it for the filename a
   // reader sees, and `standup.m4a` is the recording they uploaded — where the
   // converted copy is an artifact of how the desk works.
-  return await mergeTranscript(input.recording, plan.durationMs, parts, startedAt);
+  return await ctx.step("mergeTranscript", () =>
+    mergeTranscript(input.recording, plan.durationMs, parts, startedAt),
+  );
 }
 
 /**
@@ -283,10 +308,14 @@ export async function splitRecording(uploadId: string): Promise<{
   segments: Segment[];
   durationMs: number;
 }> {
-  "use step";
-
+  // The whole file, refused if it is still arriving. `info.size` is the readable
+  // PREFIX, and it is what the segment plan's width is derived from — so against a
+  // half-arrived recording this planned a fan-out over the first half and the run
+  // returned a transcript of it, reporting success. `stream.ts` is the flow for a
+  // recording that is still landing; this one wants all of it.
+  const stored = await requireCompleteUpload(uploadId);
   const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
-  const format = fatalOnUnsupported(() => parseWav(head.bytes, head.info.size));
+  const format = fatalOnUnsupported(() => parseWav(head.bytes, stored.size));
   const segments = fatalOnUnsupported(() => planSegments(format));
   const durationMs = segments.at(-1)?.endMs ?? 0;
 
@@ -308,8 +337,6 @@ export async function transcribeSegment(
   format: WavFormat,
   segment: Segment,
 ): Promise<SegmentTranscript> {
-  "use step";
-
   // One line per segment, which is what makes the fan-out legible to a page: the
   // status is `running` for the whole thing, so without this a sixty-segment
   // recording and a one-segment recording look identical while they run.
@@ -338,9 +365,29 @@ export async function transcribeSegment(
   // template's: a `WavFormat` is structurally a `PcmFormat`, and 22 lines of
   // `DataView` writes with a comment about which of the two declared lengths a
   // decoder trusts is not a thing worth a second copy of.
+  // Down to 16 kHz mono BEFORE the header goes on, because the endpoint's budget
+  // is 30 seconds of wall clock and that covers the upload. At 48 kHz stereo this
+  // window is 17.66 MB and the same audio is 2.94 MB normalized — six times the
+  // bytes against a fixed deadline, which is what turns a slow segment into a
+  // `504 request exceeded 30.0s` and then into a failed run. Inert on the classic
+  // flow, where `normalizeRecording` already converted the whole file; see
+  // `downsample.ts` for why the streaming flow cannot do the same.
+  //
+  // Through `fatalOnUnsupported` for the same reason `planStreamed` reads its
+  // header through it: `parseWav` admits any bit depth whose block align is
+  // positive, and `downsampleSegment` can serve only four of them — so a
+  // recording the desk could cut but cannot send raises
+  // `UnsupportedRecordingError` here, and a plain throw would spend all six
+  // attempts re-reading this window out of the upload store to arrive at the
+  // identical answer. BOTH flows can reach it, which is newer than it looks:
+  // the check used to hang off the resampler, so a 12-bit recording already at
+  // 16 kHz mono — light for both flows, and therefore converted by neither —
+  // sailed past it into an unclassified `RangeError` from `encodeWav`.
+  const light = fatalOnUnsupported(() => downsampleSegment(audio.bytes, format));
+
   const { value: text, ms } = await timed(() =>
     transcribeWav(
-      encodeWav(audio.bytes, format),
+      encodeWav(light.bytes, light.format),
       `segment-${segment.index}.wav`,
       `Segment ${segment.index} (${formatDuration(segment.startMs)})`,
     ),
@@ -364,12 +411,6 @@ export async function transcribeSegment(
   return { index: segment.index, text };
 }
 
-/**
- * Retries beyond the default 3, because a rate limit is the expected failure and
- * a segment that 429s is not a segment that is wrong.
- */
-transcribeSegment.maxRetries = 5;
-
 /**
  * Stitch the segments into one transcript.
  *
@@ -385,8 +426,6 @@ export async function mergeTranscript(
   parts: readonly SegmentTranscript[],
   startedAt: number,
 ): Promise<Transcript> {
-  "use step";
-
   await report(`Stitching ${parts.length} ${plural(parts.length, "segment")} together.`);
 
   // `mapConcurrent` resolves in ITEM order however the calls settled, so this is
@@ -427,8 +466,6 @@ export async function mergeTranscript(
  * which needs one number measured one way.
  */
 export async function startClock(): Promise<number> {
-  "use step";
-
   return Date.now();
 }
 

package/dist/templates/transcription-workflow/workflows/wav.ts

@@ -3,9 +3,9 @@
  * The pure half of the transcription desk: reading a WAV header, deciding where
  * to cut, and writing a header back over each cut.
  *
- * No directive in this file, and that is legal — the Workflow DevKit's builder
- * scans `workflows/` and transforms only what carries a `"use workflow"` /
- * `"use step"` body, so an ordinary module can sit beside them. It is a separate
+ * Nothing in this file is a step or a body, and that is legal — a body is
+ * whatever is handed a `ctx`, so an ordinary module can sit beside one. It is a
+ * separate
  * file because everything here is a pure function of a journaled value, which is
  * what makes it testable without a run at all: `transcribe.ts`'s spec drives
  * these directly.
@@ -43,7 +43,18 @@
  *   so they keep naming the `ffmpeg` line that fixes the file.
  */
 
-/** What the sync endpoint will accept in one request. */
+/**
+ * What the sync endpoint will accept in one request.
+ *
+ * **Measured against the live endpoint, the binding limit is a 30-second WALL
+ * CLOCK budget rather than this**, and that budget covers the upload as well as
+ * the transcription: a 92-second segment that is 17.66 MB comes back
+ * `504 — request exceeded 30.0s` well inside the documented cap. The constant is
+ * left alone because it is what the service DOCUMENTS and the discrepancy is
+ * unconfirmed; what closes the gap today is `downsample.ts`, which makes each
+ * request six times lighter so the deadline stops binding. Revisit both together
+ * once the real cap is settled — this number is what `planSegments` cuts to.
+ */
 export const MAX_SEGMENT_SECONDS = 120;
 
 /**

package/dist/worker-bundler.d.ts

@@ -1,5 +1,4 @@
 import { type PluginOption } from "vite";
-import { type WorkflowBundleOutput } from "./workflow-bundler.ts";
 /**
  * Options for worker bundling.
  *
@@ -25,19 +24,6 @@ export type BuildWorkerOptions = {
      * rebuild would turn the watch loop from sub-second into multi-second.
      */
     runtime?: boolean;
-    /**
-     * The project's compiled workflows, when it declares any.
-     *
-     * Embedded in the worker as two string exports rather than shipped as extra
-     * files, because the guest's `bundle/load` contract is ONE ESM string. See
-     * `wrapperEntrySource`.
-     *
-     * It also switches on the client transform (`workflowClientPlugin`), which is
-     * what puts a `workflowId` on the agent's own copy of each body. Passing the
-     * strings without it produces a bundle that serves every workflow route and
-     * cannot start a run.
-     */
-    workflows?: WorkflowBundleOutput | undefined;
 };
 /**
  * Bundle agent.ts into a single ESM string for the sandbox worker.

package/dist/worker-bundler.mjs

@@ -1,3 +1,151 @@
 #!/usr/bin/env node
-import { t as buildWorker } from "./worker-bundler-CCVEDjm1.mjs";
+import { i as errorCode } from "./_utils-B8QmtFhK.mjs";
+import { n as withPreservedNodeEnv } from "./_vite-env-BNveawd1.mjs";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { invariant } from "@alexkroman1/aai/internal";
+import { build } from "vite";
+//#region worker-bundler.ts
+/**
+* Generated wrapper entry, written under `.aai/` for the duration of the
+* build (the CLI's own scratch dir — dot-paths are ignored by the dev
+* watcher, and the studio's workspace materialization never writes there).
+*/
+const WRAPPER_ENTRY_REL = path.join(".aai", "worker-entry.ts");
+/** Extensions a tool module may be authored in (mirrors the SDK's registry). */
+const TOOL_MODULE_EXT_RE = /\.(?:m?ts|tsx)$/;
+/** A co-located spec is not a tool. */
+const TOOL_SPEC_RE = /\.(?:test|spec)\.[^.]+$/;
+/**
+* The project's `tools/` directory, as file names relative to it.
+*
+* **This is the whole of "discovery", and it happens HERE because the guest has
+* no filesystem.** A sandbox is handed one ESM string, so the only place a
+* directory can be turned into modules is where the bundle is assembled — the
+* same lowering eve does (`readdir` → static import list, which the bundler then
+* follows). The names are validated by `toolRegistry` at bundle-evaluation time
+* rather than here, so one implementation owns the rules.
+*
+* Sorted, so the emitted entry is byte-stable for a given directory: an entry
+* that reordered per readdir would change the bundle hash for no reason.
+*/
+async function discoverToolFiles(cwd) {
+	const root = path.join(cwd, "tools");
+	let entries;
+	try {
+		entries = await fs.readdir(root, {
+			withFileTypes: true,
+			recursive: true
+		});
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return [];
+		throw err;
+	}
+	return entries.filter((e) => e.isFile() && TOOL_MODULE_EXT_RE.test(e.name) && !TOOL_SPEC_RE.test(e.name)).map((e) => path.relative(root, path.join(e.parentPath, e.name)).split(path.sep).join("/")).sort();
+}
+/** The prose slot: one file, beside `agent.ts`, named by convention. */
+const SYSTEM_PROMPT_FILE = "system-prompt.md";
+/**
+* Whether the project keeps its system prompt in a file.
+*
+* The other half of "a file beside `agent.ts` can BE the thing", and it happens
+* here for the same reason `discoverToolFiles` does — the guest has no
+* filesystem, so the read belongs where the bundle is assembled. What the file
+* MEANS is `withSystemPrompt`'s to decide (the author may have imported and
+* composed it, in which case discovery must not apply it twice); this only
+* answers whether there is one.
+*/
+async function hasSystemPromptFile(cwd) {
+	const nested = path.join(cwd, "system-prompt");
+	if ((await fs.stat(nested).catch(() => void 0))?.isDirectory() === true) throw new Error(`${nested} is a directory. A system prompt is ONE file — rename it to ${SYSTEM_PROMPT_FILE}, or import the pieces yourself and compose them into \`systemPrompt\`. There is deliberately no concatenation order for a directory.`);
+	try {
+		return (await fs.stat(path.join(cwd, SYSTEM_PROMPT_FILE))).isFile();
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return false;
+		throw err;
+	}
+}
+function wrapperEntrySource(runtime, toolFiles, systemPromptFile) {
+	const toolImports = toolFiles.map((file, i) => `import * as __aaiTool${i} from "../tools/${file}";`).join("\n");
+	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";` : ""}
+${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
+// agent.ts, so a file that exists is a tool the model can call — there is no
+// registration step to forget.
+//
+// \`system-prompt.md\` arrives the same way, and the \`?raw\` lives HERE rather
+// than in the author's own \`agent.ts\`: it is a Vite convention, and the whole
+// point of generating this entry is that a bundler feature never has to appear
+// in user-authored space.
+const __aaiAgent = ${systemPromptFile ? "withSystemPrompt(" : ""}withTools(
+  def,
+  toolRegistry({
+${toolEntries}
+  }),
+)${systemPromptFile ? ", __aaiSystemPrompt)" : ""};
+export default __aaiAgent;
+export const __aaiConfig = {
+  ...toAgentConfig(__aaiAgent),
+  toolSchemas: agentToolsToSchemas(__aaiAgent.tools ?? {}),
+};
+${runtime ? `export const __aaiCreateRuntime = (opts: Record<string, unknown>) =>
+  createRuntime({ ...opts, agent: __aaiAgent });
+` : ""}`;
+}
+/**
+* Bundle agent.ts into a single ESM string for the sandbox worker.
+*
+* Zod is bundled in — zod 4's `Function()` usage is wrapped in try/catch
+* and gracefully degrades in restricted environments like Deno.
+*
+* @internal — build hook for aai-server/the studio; not a supported public
+* API and not covered by semver.
+*/
+async function buildWorker(cwd, opts = {}) {
+	const wrapperPath = path.join(cwd, WRAPPER_ENTRY_REL);
+	const [, toolFiles, systemPromptFile] = await Promise.all([
+		fs.mkdir(path.dirname(wrapperPath), { recursive: true }),
+		discoverToolFiles(cwd),
+		hasSystemPromptFile(cwd)
+	]);
+	await fs.writeFile(wrapperPath, wrapperEntrySource(opts.runtime !== false, toolFiles, systemPromptFile), "utf-8");
+	const plugins = opts.plugins ?? [];
+	let result;
+	try {
+		result = await withPreservedNodeEnv(() => build({
+			root: cwd,
+			logLevel: "silent",
+			...opts.configFile === false && { configFile: false },
+			...plugins.length > 0 && { plugins },
+			ssr: { noExternal: true },
+			build: {
+				ssr: true,
+				lib: {
+					entry: wrapperPath,
+					formats: ["es"],
+					fileName: "worker"
+				},
+				target: "node20",
+				minify: opts.minify ? "oxc" : false,
+				write: false,
+				rollupOptions: { output: {
+					entryFileNames: "[name].js",
+					codeSplitting: false
+				} }
+			}
+		}));
+	} finally {
+		await fs.rm(wrapperPath, { force: true }).catch(() => void 0);
+	}
+	const output = Array.isArray(result) ? result[0] : result;
+	invariant(output !== void 0, "bundle.worker.output");
+	const chunk = output.output.find((o) => o.type === "chunk" && o.isEntry);
+	invariant(chunk !== void 0, "bundle.worker.entry-chunk", () => ({ kinds: output.output.map((o) => o.type) }));
+	return chunk.code;
+}
+//#endregion
 export { buildWorker };

package/dist/{workflow-BflATMmU.mjs → workflow-BBu5oEDw.mjs}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
+import { a as ok, n as fail, t as CliError } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
+import { i as readProjectConfig } from "./_config-CmJOFsAP.mjs";
 import { n as getServerInfo } from "./_agent-BTwZJu4P.mjs";
 import { errorMessage, omitUndefined } from "@alexkroman1/aai/utils";
 import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
@@ -35,32 +36,105 @@ import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
 /** Runs listed when the caller names no limit — a terminal is not a dashboard. */
 const DEFAULT_RUN_LIMIT = 20;
 /**
+* The base URL {@link createWorkflowApiClient} is given for `--agent`.
+*
+* A dev server has no slug: `createServer` mounts the workflow API at
+* `WORKFLOW_API_PREFIX` on the ORIGIN, where the platform serves it under
+* `/:slug`. So targeting one is not a matter of a different origin — it is the
+* absence of the path segment, which nothing in this command could express.
+*
+* Validated rather than interpolated. This value is joined into a request path,
+* and the CLI's standing rule is that anything reaching a URL is checked at the
+* one point it becomes a target (`resolveDeployTarget`'s slug guard is the same
+* rule). It is also the only origin here that `resolveServerUrl` does not
+* produce, so stripping the trailing slash is this function's job — the join
+* site deliberately carries no copy of that.
+*
+* No trust check, deliberately, and the asymmetry with `--server` is the point:
+* `--server` pairs an origin with the user's PLATFORM API KEY, which is why a
+* repo-supplied loopback URL is refused there. Nothing credentialed goes to
+* `--agent` — the workflow API takes the agent's own bearer or none — so there
+* is nothing for a hostile origin to collect, and requiring `aai login` to read
+* runs off a server on your own laptop is the defect this flag exists for.
+*/
+function agentBaseUrl(raw) {
+	const url = URL.parse(raw);
+	if (url === null) throw new CliError("bad_agent_url", `--agent is not a URL: ${JSON.stringify(raw)}`, HINT_URL);
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new CliError("bad_agent_url", `--agent must be http or https, not ${url.protocol.replace(":", "")}`, HINT_URL);
+	return raw.replace(/\/+$/, "");
+}
+/**
 * A client for the agent's workflow API, plus the bearer when one was given.
 *
-* `getServerInfo` is what turns "this directory" into an origin and a published
-* slug, and it already refuses a project that has never been deployed with the
-* sentence naming `aai publish`. The client is handed the AGENT's base URL and
-* appends the route prefix itself, so the `/workflows` literal is not spelled
-* here — it is the same constant the server matches on.
+* Two ways in. `--agent <url>` names a server the caller is running themselves
+* — `aai dev`, or the scaffold's `npm start` — and takes that URL as the base:
+* no project config, no published slug, and no `ensureApiKey`, none of which
+* such a server has or wants. Otherwise `getServerInfo` turns "this directory"
+* into a platform origin and a published slug.
+*
+* The client is handed the AGENT's base URL and appends the route prefix itself,
+* so the `/workflows` literal is not spelled here — it is the same constant the
+* server matches on.
 *
 * `serverUrl` is joined as-is: `resolveServerUrl` is the single producer of
-* every origin that reaches here and strips trailing slashes once, at
+* every origin that reaches THAT branch and strips trailing slashes once, at
 * resolution time, precisely so join sites do not each carry a copy. The copy
 * this used to hold also DISAGREED with it — `/\/$/` takes one slash where the
 * upstream `/\/+$/` takes all — so the two would have differed on the only
 * input either was written for.
+*
+* **The no-deployment failure is raised HERE rather than by
+* `requireDeployedSlug`, and the ordering is why.** `getServerInfo` resolves the
+* API key BEFORE it looks for a slug, so in an undeployed project the first
+* thing a developer running `aai dev` saw was `not_logged_in` — pointing at
+* `aai login` for a command that never sends the key it was asking for, with
+* the real cause two errors away. Reading the project config first puts the
+* cause first and lets the sentence name every way out: publish it, or point at
+* the server already running.
 */
 async function target(cwd, opts) {
+	if (opts.agent !== void 0) {
+		const baseUrl = agentBaseUrl(opts.agent);
+		return {
+			api: createWorkflowApiClient({
+				baseUrl,
+				...omitUndefined({ token: opts.token })
+			}),
+			name: baseUrl
+		};
+	}
+	if (!(await readProjectConfig(cwd))?.slug) throw new CliError("no_deployment", NO_DEPLOYMENT, HINT_AGENT);
 	const { serverUrl, slug } = await getServerInfo(cwd, opts.server);
 	return {
 		api: createWorkflowApiClient({
 			baseUrl: `${serverUrl}/${slug}`,
 			...omitUndefined({ token: opts.token })
 		}),
-		slug
+		name: slug
 	};
 }
 /**
+* What a project with no deployment is told, and why it names two ways out.
+*
+* `requireDeployedSlug`'s sentence — "run `aai publish` first" — is right for
+* `aai secret` and `aai delete`, which have nothing to talk to until the agent
+* is on the platform. It is wrong here often enough to be a defect: a workflow
+* API is the one agent surface that is fully live under `aai dev`, so the
+* developer being told to publish frequently has the thing they asked about
+* answering on localhost already.
+*/
+const NO_DEPLOYMENT = "This project has no deployed agent, and no --agent URL was given — so there is nothing for `aai workflow` to ask.";
+/**
+* What a malformed `--agent` is told.
+*
+* Its own hint rather than {@link HINT_AGENT}: the caller already knows about
+* the flag — they typed it — so repeating "run `aai publish`" answers a
+* question they did not ask.
+*/
+const HINT_URL = "Pass a full origin, e.g. --agent http://localhost:3000";
+/** How to reach a server you are running yourself. Paired with {@link NO_DEPLOYMENT}. */
+const HINT_AGENT = "Run `aai publish` to deploy it, or pass --agent <url> to target a server you are already running — `--agent http://localhost:3000` for `aai dev`, which needs no login and no slug.";
+/**
 * Run one call, turning a rejection into this command's failure result.
 *
 * The client throws with the AGENT'S own sentence — an unknown workflow names
@@ -93,11 +167,11 @@ async function attempt(code, call) {
 }
 /** `aai workflow list` — what this agent declares. */
 async function executeWorkflowList(cwd, opts) {
-	const { api, slug } = await target(cwd, opts);
+	const { api, name } = await target(cwd, opts);
 	const res = await attempt("workflow_list_failed", () => api.list());
 	if (!res.ok) return res;
 	const workflows = res.value;
-	if (workflows.length === 0) log.info(`${slug} declares no workflows`);
+	if (workflows.length === 0) log.info(`${name} declares no workflows`);
 	else for (const w of workflows) log.info(`${w.name}${w.description ? ` — ${w.description}` : ""}`);
 	return ok({ workflows });
 }

package/dist/workflow.d.ts

@@ -39,6 +39,7 @@ type Run = WorkflowRunSnapshot;
 type WorkflowOptions = {
     server?: string | undefined;
     token?: string | undefined;
+    agent?: string | undefined;
 };
 /** `aai workflow list` — what this agent declares. */
 export declare function executeWorkflowList(cwd: string, opts: WorkflowOptions): Promise<CommandResult<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "9.2.0",
+  "version": "10.0.1",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -33,7 +33,6 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@workflow/builders": "4.1.7",
     "chokidar": "^5.0.0",
     "citty": "^0.2.2",
     "env-paths": "^4.0.0",
@@ -44,16 +43,15 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai": "9.2.0",
-    "@alexkroman1/aai-runtime": "9.2.0",
-    "@alexkroman1/aai-ui": "9.2.0"
+    "@alexkroman1/aai": "10.0.1",
+    "@alexkroman1/aai-runtime": "10.0.1",
+    "@alexkroman1/aai-ui": "10.0.1"
   },
   "devDependencies": {
     "playwright": "^1.62.1",
     "tsdown": "^0.22.14",
     "verdaccio": "^6.9.2",
     "vitest": "^4.1.10",
-    "workflow": "4.8.2",
     "aai-templates": "0.3.8"
   },
   "peerDependencies": {