@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/workflow-bundler.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Workflow bundling — turning a project's `workflows/` directory into the two
+ * small artifacts a guest needs to run durable workflows.
+ *
+ * Public (no `_` prefix) for the same reason as `worker-bundler.ts`: the studio
+ * builds its workspaces through this too, so a workflow published from the
+ * browser comes out of the same pass as one from `aai build`.
+ *
+ * @internal — build hook for aai-server/the studio; not a supported public API
+ * and not covered by semver.
+ *
+ * ## Why this exists at all
+ *
+ * The Workflow Development Kit's own integrations (Next, Nitro, SvelteKit) build
+ * workflow routes while building the SERVER, by scanning `workflows/` and
+ * emitting handler files. That model does not fit this platform: the guest image
+ * is baked once and then serves MANY tenants' agents, each arriving over
+ * `bundle/load` at runtime. There is no `workflows/` directory in existence when
+ * the harness is built. So the transform has to happen per tenant at deploy
+ * time — here — and the guest receives the result as data.
+ *
+ * ## The two artifacts, and why they are small
+ *
+ * A default `workflow build` emits a 3.7 MB flow bundle and a 12 MB step bundle,
+ * because each one inlines the whole WDK runtime. Neither could ride the guest's
+ * single-ESM-string delivery. Two settings fix that, and both are load-bearing:
+ *
+ * - **`externalPackages: ["workflow", …]`** — the WDK is resolved from the
+ *   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.
+ *
+ * So `workflowCode` is passed to `workflowEntrypoint()` in the guest and
+ * `stepCode` is evaluated there to register its step functions.
+ *
+ * ## The THIRD transform, which is the agent bundle's
+ *
+ * Those two are what the queue runs. The agent bundle needs a third —
+ * `applySwcTransform(…, "client")`, wired in as {@link workflowClientPlugin} —
+ * and without it the whole mechanism is inert: `ctx.workflows.start` reads the
+ * `workflowId` the compiler attaches to a directive body, and Vite bundling
+ * `workflows/research.ts` the ordinary way attaches nothing. The symptom is
+ * `MISSING_WORKFLOW_ID_MESSAGE` at the first `start()` — an agent that builds,
+ * deploys, boots and answers the phone, and cannot start a run.
+ *
+ * The plugin transforms EXACTLY the files the builder scanned (`inputFiles`),
+ * not "every file with a directive". Same list, same `moduleSpecifierRoot`,
+ * therefore the same ids by construction — a body outside `workflows/` cannot
+ * acquire an id that no flow bundle registered, which would trade a clear
+ * failure at `start()` for a run that enqueues and then fails at replay.
+ *
+ * ## Config details that are not optional
+ *
+ * Each of these cost real time to find, and none fails in a way that names
+ * itself:
+ *
+ * - `dirs` must carry the `./` prefix. A bare `"workflows"` crashes inside
+ *   enhanced-resolve with `Cannot read properties of undefined (reading
+ *   'length')` from `join(undefined, …)`, nowhere near the cause.
+ * - Every bundle path must be ABSOLUTE, for the same reason.
+ * - `projectRoot` and `moduleSpecifierRoot` must be set explicitly; they do not
+ *   default to `workingDir` on the path this takes.
+ * - `keepInterimBundleContext` must stay off — it leaves an esbuild watch context
+ *   alive, so a one-shot build never exits.
+ */
+import type { Plugin } from "vite";
+/**
+ * The directory a project's `"use workflow"` bodies live in.
+ *
+ * The WDK builder's convention, not ours, and it is why a workflow body cannot
+ * live in `agent.ts`: only files under here are transformed. A body outside it
+ * runs inline, once, with no durability and nothing reporting that.
+ */
+export declare const WORKFLOWS_DIR = "workflows";
+/** What a guest needs to serve workflows for one agent. */
+export type WorkflowBundleOutput = {
+    /**
+     * The workflow-mode transform of every `"use workflow"` body, as code.
+     *
+     * Passed to `workflowEntrypoint(code)` in the guest — which is why it is a
+     * STRING rather than a file: the guest never sees this project's filesystem.
+     */
+    workflowCode: string;
+    /**
+     * The step-mode transform, as code. Evaluated in the guest so its
+     * `registerStepFunction` calls run; nothing imports anything from it.
+     */
+    stepCode: string;
+    /**
+     * The builder's manifest — `workflowId` per exported workflow, plus the step
+     * graph. The ids are what `ctx.workflows.start` needs, and the SDK reads them
+     * off each body's own `workflowId` property, so nothing consumes this at
+     * runtime; it is the builder's own output, kept for inspection and asserted
+     * by this package's spec.
+     *
+     * It is deliberately NOT emitted into the worker bundle. It was, as a
+     * double-encoded `__aaiWorkflowManifest` string literal, on the stated
+     * grounds that "the studio's workflows card renders it" — which was never
+     * true (the card calls `GET /workflows`). Nothing anywhere read the export,
+     * so it was bytes in every deploy artifact, re-fetched and hash-verified on
+     * every cold guest boot, for no reader.
+     */
+    manifest: unknown;
+    /**
+     * The absolute paths the builder scanned — the agent bundle's client
+     * transform runs over exactly these. See the module doc's third-transform
+     * section for why it is this list and not a content sniff.
+     */
+    inputFiles: readonly string[];
+};
+/**
+ * Attach the compiler's `workflowId`/`stepId` to the agent bundle's copy of
+ * each directive body — the third transform, see the module doc.
+ *
+ * `enforce: "pre"` so it sees the file before Vite's own TypeScript pass: the
+ * swc transform reads types itself (it is given the filename to infer syntax),
+ * and its output is plain JS that the later pass leaves alone.
+ *
+ * @internal
+ */
+export declare function workflowClientPlugin(cwd: string, inputFiles: readonly string[]): Plugin;
+/**
+ * Build a project's workflows, or resolve `undefined` when it declares none.
+ *
+ * `undefined` rather than empty strings, because "this project has no workflows"
+ * is the common case — every voice agent that never reaches for one — and the
+ * guest must be able to tell it apart from "the build produced nothing", which
+ * would be a bug.
+ *
+ * @internal
+ */
+export declare function buildWorkflows(cwd: string): Promise<WorkflowBundleOutput | undefined>;

package/dist/workflow.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `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.
+ */
+import type { WorkflowRunSnapshot, WorkflowSummary } from "@alexkroman1/aai";
+import { type CommandResult } from "./_output.ts";
+/**
+ * One run, as the API reports it.
+ *
+ * The SDK's own type, not a restatement: this command prints `status`, `key` and
+ * `error`, and a copy is how a field added to the snapshot silently stops being
+ * printed. `WorkflowRunSnapshot` is a discriminated union, so `error` is
+ * reachable only after narrowing — which is what {@link formatRun} does.
+ */
+type Run = WorkflowRunSnapshot;
+type WorkflowOptions = {
+    server?: string | undefined;
+    token?: string | undefined;
+};
+/** `aai workflow list` — what this agent declares. */
+export declare function executeWorkflowList(cwd: string, opts: WorkflowOptions): Promise<CommandResult<{
+    workflows: WorkflowSummary[];
+}>>;
+/**
+ * `aai workflow runs <name>` — recent runs, newest first.
+ *
+ * `recent` rather than `find`, so the query carries no `key`: a terminal has no
+ * correlation key to ask about, and most runs carry none.
+ */
+export declare function executeWorkflowRuns(cwd: string, workflow: string, opts: WorkflowOptions & {
+    limit?: number | undefined;
+}): Promise<CommandResult<{
+    runs: Run[];
+}>>;
+/** `aai workflow show <runId>` — one run in full, including its output. */
+export declare function executeWorkflowShow(cwd: string, runId: string, opts: WorkflowOptions): Promise<CommandResult<{
+    run: Run;
+}>>;
+/** `aai workflow cancel <runId>` — stop a live run. */
+export declare function executeWorkflowCancel(cwd: string, runId: string, opts: WorkflowOptions): Promise<CommandResult<{
+    runId: string;
+    cancelled: boolean;
+}>>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "5.14.0",
+  "version": "6.1.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -33,24 +33,26 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "@workflow/builders": "4.1.7",
     "chokidar": "^5.0.0",
     "citty": "^0.2.2",
     "env-paths": "^4.0.0",
-    "execa": "^10.0.0",
+    "execa": "^10.0.1",
     "get-port": "^7.2.0",
     "ofetch": "^1.5.1",
     "p-debounce": "^5.1.0",
     "p-timeout": "^7.0.1",
-    "vite": "^8.1.5",
+    "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai": "5.14.0",
-    "@alexkroman1/aai-ui": "5.14.0"
+    "@alexkroman1/aai": "6.1.0",
+    "@alexkroman1/aai-ui": "6.1.0"
   },
   "devDependencies": {
-    "playwright": "^1.61.1",
-    "tsdown": "^0.22.13",
-    "verdaccio": "^6.8.0",
+    "playwright": "^1.62.1",
+    "tsdown": "^0.22.14",
+    "verdaccio": "^6.9.2",
     "vitest": "^4.1.10",
+    "workflow": "4.8.2",
     "aai-templates": "0.3.4"
   },
   "peerDependencies": {
@@ -77,7 +79,9 @@
     "lint": "biome check .",
     "check:publint": "publint",
     "check:attw": "attw --pack --profile esm-only",
-    "test:e2e": "VITEST_PROFILE=e2e VITEST_INCLUDE=e2e*.test.ts vitest run -c ../../vitest.slow.config.ts",
+    "test:scenario": "VITEST_PROFILE=scenario VITEST_SETUP=./_test-setup.ts VITEST_INCLUDE=**/*.scenario.test.ts vitest run -c ../../vitest.slow.config.ts",
+    "check:scenario": "pnpm run test:scenario",
+    "test:e2e": "VITEST_PROFILE=e2e VITEST_SETUP=./_test-setup.ts VITEST_INCLUDE=e2e*.test.ts vitest run -c ../../vitest.slow.config.ts",
     "check:e2e": "pnpm run test:e2e"
   }
 }

package/dist/build-DQJ1ZSm9.mjs

@@ -1,39 +0,0 @@
-#!/usr/bin/env node
-import { a as ok, t as CliError } from "./_output-CC300DzW.mjs";
-import { n as log } from "./_ui-u7T4YooX.mjs";
-import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-BuIyDdvs.mjs";
-import { assertTypechecks } from "./_typecheck-gate-4v9UBZHh.mjs";
-import { classifyVitestError, runVitest } from "./test-2LWBcXvY.mjs";
-//#region build.ts
-/**
-* `aai build` — bundle the agent without deploying, behind the same gates
-* deploy runs (tests, then typecheck), so the command previews the deploy
-* artifact and its failures alike.
-*/
-/**
-* Map a {@link runVitest} failure to a CliError — distinguishing a real test
-* failure (test_failed) from the runner not spawning (spawn_failed) instead
-* of a generic command_failed.
-*/
-function testGateError(err) {
-	const { code, message } = classifyVitestError(err);
-	return new CliError(code, message, "Re-run with --skipTests to build without tests", { cause: err });
-}
-async function executeBuild(opts) {
-	const { cwd } = opts;
-	if (!opts.skipTests) try {
-		runVitest(cwd);
-	} catch (err) {
-		throw testGateError(err);
-	}
-	if (!opts.skipTypecheck) await assertTypechecks(cwd);
-	const bundle = await buildAgentBundle(cwd, { minify: true });
-	const agentDef = await evalWorkerBundle(bundle.worker);
-	log.success("Build complete");
-	return ok({
-		name: agentDef.name,
-		workerBytes: bundle.worker.length
-	});
-}
-//#endregion
-export { executeBuild };