@alexkroman1/aai-cli 8.2.0 → 9.0.0

package/dist/scaffold/CLAUDE.md

@@ -7,8 +7,12 @@ You are helping build a voice agent using the **aai** framework.
 The fast loop: edit → `pnpm dev` (browser, talk to it) →
 `pnpm test` (logic) → `pnpm build` (validate bundle).
 
-1. **Iterate in `pnpm dev`** — hot reload + browser UI. Speak to the
-   agent to verify behavior end-to-end. This is the primary feedback loop.
+1. **Iterate in `pnpm dev`** — browser UI, and `pnpm dev -- --watch` to
+   rebuild and restart on every save. Speak to the agent to verify behavior
+   end-to-end. This is the primary feedback loop. Watching is OPT-IN because a
+   restart ends in-flight voice sessions, which is right while you are editing
+   and wrong while something is driving the agent for twenty minutes;
+   `AAI_DEV_WATCH=1` is the same switch for a process supervisor.
 2. **Run `pnpm test` after logic changes** — vitest. Co-locate tests as
    `agent.test.ts` (see `pipeline-simple` template for a reference).
    **When the project has an `agent.test.ts` (the default `simple`
@@ -18,6 +22,20 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
    agent that no longer exists. When a test fails after your change, decide
    which side is stale: updating the test to match the new agent is a normal
    fix, not a workaround. Do not delete a test to make it pass.
+
+   **A spec that needs the agent as DEPLOYED imports one module:**
+
+   ```ts no-check
+   import agentDef from "virtual:aai/agent";
+   ```
+
+   That is `agent.ts` with its `tools/` directory discovered and its
+   `system-prompt.md` applied — the same lowering `aai build` does, so a spec
+   measures the agent that ships rather than the raw default export (which has
+   no tools and the framework's default prompt). `vitest.config.ts` registers
+   the plugin that serves it; a scaffolded project already has it. For a runner
+   that is not vitest, `deployedAgent` on `@alexkroman1/aai/testing` is the same
+   thing written out.
 3. **Run `pnpm eval` when you change what the agent DOES** — a test asserts
    the agent's shape; an eval drives a real session and asserts what it did.
    Cases live in `agent.eval.test.ts` (the `simple` template ships one):
@@ -163,8 +181,8 @@ import { agent } from "@alexkroman1/aai";
 export default agent({
   name: string;                              // required — display name
   systemPrompt?: string;                     // usually ABSENT — write system-prompt.md
-                                             // instead; declare it only to COMPOSE
-                                             // one (`system` is an accepted alias)
+                                             // instead; declare it only to COMPOSE one.
+                                             // There is no `system` alias — one name.
   greeting?: string;                         // default: "Hey there..."
   voice?: string;                            // TTS voice for the default pipeline, e.g. "michael"
                                              // (shorthand for tts: assemblyAITts({ voice });
@@ -180,6 +198,10 @@ export default agent({
                                              // (there is no `tools` field — a tool is a FILE;
                                              //  see "A file in tools/ IS a tool")
   maxSteps?: number;                         // default: 10 — max tool calls per turn
+  temperature?: number;                      // sampling temperature for the agent's OWN model calls
+                                             // (pipeline and text). Unset = the model's default; some
+                                             // models ignore it and warn. S2S REFUSES it — the model
+                                             // runs in the provider's service and never sees this.
   toolChoice?: ToolChoice;                   // "auto" (default) | "required" | "none"
                                              // | { type: "tool", toolName }
   idleTimeoutMs?: number;                    // disconnect after inactivity (ms)
@@ -192,6 +214,18 @@ export default agent({
   preemptiveGeneration?: boolean;            // pipeline only — start the reply from a high-confidence interim (default false; true opts in)
   syncState?: StateProjection;               // show a slot to the client: slot.projection(view)
                                              // (read it with useAgentState; see UI hooks)
+  minTurnSilenceMs?: number;                 // pipeline only — pause (ms) that ENDS a user turn once the
+                                             // text reads complete (default 560)
+  maxTurnSilenceMs?: number;                 // pipeline only — pause (ms) that ends a turn REGARDLESS of
+                                             // content (default 1600). The endpointing knob to reach for:
+                                             // it bounds the utterances that never read as finished.
+                                             // Both are shorthand for the same options on the default
+                                             // assemblyAIStt() stage — invalid with an explicit `stt`.
+  requiredEnv?: string[];                    // env vars this agent reads. A deploy CHECKS them, so a
+                                             // missing key fails at `aai push` instead of mid-call.
+                                             // Declare every key any tool or step reads.
+  text?: true;                               // text-only agent: no STT, no TTS, `llm` is the one stage
+  events?: SessionEventHandlers;             // observe the session (see "Watching the session")
 });
 ```
 
@@ -361,17 +395,20 @@ callback. Reach for `agent()` when someone is on the line — a voice agent can
 also START a workflow from a tool (`ctx.workflows.start(def, input)`) and
 answer the turn, which is the other shape.
 
-**Storage is OPTIONAL, and what it buys is DURABILITY.** With a database
-(`aai storage enable`, Settings → Database in the studio, or `DATABASE_URL`
-under `aai dev`) runs live in it and survive a restart, a redeploy and an idle
-sandbox. Without one they live in the process that started them — you can
-submit the form, watch the run and read its result, and everything in flight is
-lost when that process goes away. That is the honest tradeoff, and it is what
+**Runs are DURABLE on the platform with no setup.** A deployed app's runs live
+on the platform's own database, so they survive a restart, a redeploy and an
+idle sandbox. There is nothing to enable.
+
+Under `aai dev` without a `DATABASE_URL` they live in the process that started
+them — you can submit the form, watch the run and read its result, and
+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.
 
-Two things do need the database whatever the run does: `ctx.db`, and a workflow
-**upload** — an upload's record is a row, so `api.upload` and the file-taking
-form hooks refuse by name until storage is on (see "Database API" below).
+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.)
 
 ### Workflow bodies live in `workflows/`
 
@@ -418,7 +455,8 @@ warned about by `aai build` and `aai dev`, naming the file and the call:
   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. `ctx.db` has no step-side equivalent yet.
+  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's env, and calling a model from one
 
@@ -468,6 +506,11 @@ is the one to use**:
 | `stepTranscribeUpload` / `Submit` / `Poll` | the matching `*Classified` |
 | `sendToChannel` (`/channels`) | `sendToChannelClassified` |
 
+`stepFetchOk` is the one that is not spelled `*Classified`, and the name is the
+difference: the others turn an already-thrown failure into a classified one,
+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,
 every failure looks the same to it: a bad API key is retried until the attempts
@@ -497,11 +540,13 @@ every one of those bundles. A step pays nothing for the extra import line.
 Three more subpaths a `workflows/*.ts` module can reach, all with the same
 bundling rule as `/step` — import them there, never through the root barrel:
 
-- **`@alexkroman1/aai/transcribe`** — `stepTranscribeSync(bytes)` for a short
+- **`@alexkroman1/aai/step`** — `stepTranscribeSync(bytes)` for a short
   recording, or `stepTranscribeUpload` → `stepTranscribeSubmit` →
   `stepTranscribePoll` for a long one, plus `Transcript`, `TranscribeError` and
-  the `TRANSCRIBE_*` limits. Use the `Classified` wrappers above: a provider
-  refusal — a container it will not read, a recording with no speech — arrives
+  the `TRANSCRIBE_*` limits. (There is no `/transcribe` subpath; transcription
+  lives on `/step` with the other step primitives.) Use the `Classified`
+  wrappers above: a provider refusal — a container it will not read, a
+  recording with no speech — arrives
   with `retryable: false`, and unclassified a step re-uploads the same bytes
   until its attempts run out.
 - **`@alexkroman1/aai/ffmpeg`** — `transcodeToWav(bytes, { sampleRate })`,
@@ -705,7 +750,7 @@ rather than fail the turn:
 import { webSearch } from "@alexkroman1/aai/tools";
 import { isToolFailure } from "@alexkroman1/aai/utils";
 
-const found = await webSearch<{ results?: { url?: string }[] }>({ query, max_results: 4 });
+const found = await webSearch<{ results?: { url?: string }[] }>({ query, maxResults: 4 });
 // NOT `(found.results ?? [])` — a REFUSED search would then read as an empty web.
 if (isToolFailure(found)) return `That search failed: ${found.error}`;
 return (found.results ?? []).map((one) => one.url);
@@ -862,8 +907,39 @@ export default agent({
 Tools, the database, `ctx`, and the UI all behave identically across modes.
 Only the audio + LLM transport differs.
 
-**There is no text-only agent mode.** An agent is a voice conversation —
-every pipeline agent must declare a real TTS provider.
+**Four front doors, each one field on `agent()`.** Omit them all for PIPELINE
+(voice, cascaded STT → LLM → TTS) — the default, and the mode this guide
+assumes. `s2s:` selects speech-to-speech. **`text: true` selects a text-only
+agent**: no STT, no TTS, `llm` is the one stage, and the host runs it with
+`createTextAgent` from `@alexkroman1/aai-runtime`. `workflowApp()` (see
+"Workflow apps") builds a form with no session at all. Setting a field from the
+wrong arm is a compile error naming the rule, so the modes cannot be mixed by
+accident. Every pipeline agent must declare a real TTS provider — that is a
+statement about pipeline mode, not about the SDK.
+
+### Answering a phone call
+
+A deployed voice agent already serves carrier media streams — there is nothing
+to switch on. `createServer` mounts `WS /phone` whenever the agent is a voice
+agent (`telephony` defaults to `true`, and to `false` for a `page: "static"`
+workflow app, which has no stages to put on a call). Point the carrier at it
+with a `carrier` query parameter naming who is dialling:
+
+```text
+wss://<your-agent-url>/phone?carrier=twilio
+wss://<your-agent-url>/phone?carrier=telnyx
+```
+
+Twilio and Telnyx are the two carriers this build decodes (`CARRIER_CODECS`);
+an unknown `carrier` is declined at the upgrade. Both speak 8 kHz mu-law, which
+the bridge transcodes in both directions, so the agent, its tools and its slots
+behave exactly as they do in the browser — a phone call is a transport, not a
+mode. Nothing about `agent.ts` changes to support one.
+
+Turn the route off with `telephony: false` on `createServer`. If you are
+embedding the runtime yourself rather than deploying, the pieces are
+`createTelephonyBridge`, `startTelephonySession`, `TELEPHONY_PATH` and
+`carrierByName`, all on `@alexkroman1/aai-runtime`.
 
 **Silence nudge (pipeline only):** set `silenceTimeoutMs` to make the
 assistant proactively take a turn after that much user silence (e.g.
@@ -1062,10 +1138,14 @@ same way in `aai dev` and deployed.
 ### `ctx` (ToolContext)
 
 ```ts no-check
-ctx.env: Readonly<Record<string, string>>     // secrets from .env / aai secret put
+ctx.env: Readonly<Partial<Record<string, string>>> // secrets from .env / aai secret put.
+                                               // Partial: every read is `string | undefined`.
+                                               // Use requireEnv(ctx, "KEY") to fail by NAME
+                                               // instead of throwing a TypeError at the model.
+ctx.workflows: WorkflowClient                  // start / signal / wake / find / stream a durable run
+                                               // from a tool (see "Workflows")
 ctx.slots: SlotStore                           // where sessionSlot() keeps this session's state —
                                                // reach for the slot, never this (see "Session state")
-ctx.db: Db                                     // SQL database, needs storage enabled (see Database section)
 ctx.messages: readonly Message[]               // conversation history [{role, content}]
 ctx.sessionId: string                          // unique session ID
 ctx.send(event: string, data: unknown): void   // push custom event to browser client (silently dropped over 64 KB JSON)
@@ -1181,9 +1261,10 @@ Four rules, and each is an error rather than advice if you get it wrong:
 - **Hold plain data.** Objects, arrays, strings, numbers, booleans and null. A
   `Map`, a `Set`, a `Date` or a class instance is refused with the field named,
   because none of them survives being stored.
-- **State is STORED when your app has a database** (`aai storage enable`, or a
-  `DATABASE_URL` in `.env`), so a crash or a redeploy no longer loses it. Without
-  one it lives in memory for the life of the process. You write the same code
+- **State is STORED on the platform**, so a crash or a redeploy no longer loses
+  it — the platform keeps a session's slots on its own database and there is
+  nothing to enable. Under `aai dev` it lives in memory for the life of the
+  process unless you set a `DATABASE_URL` in `.env`. You write the same code
   either way; that is the reason for the rules above.
 
 There is nothing to declare on `agent()` — the slot owns its own default. Use
@@ -1267,8 +1348,8 @@ an SDK dependency. `support-line` is the worked example.
 
 `ctx.generate` is ONE prompt. When answering takes an unknown number of tool
 calls whose intermediate results the conversation has no reason to carry,
-delegate to a **subagent** instead: a second tool loop with its own
-instructions, model, tools and — the whole point — its own context window.
+delegate to a **subagent** instead: a second tool loop with its own system
+prompt, model, tools and — the whole point — its own context window.
 
 ```ts
 import { subagent, tool } from "@alexkroman1/aai";
@@ -1276,7 +1357,9 @@ import { z } from "zod";
 
 const researcher = subagent({
   name: "researcher",
-  instructions:
+  // `systemPrompt`, the same field name `agent()` uses — a subagent is a
+  // field-for-field smaller agent, so nothing about it is spelled differently.
+  systemPrompt:
     "Research the task with the tools you have. IMPORTANT: your final message " +
     "is the only thing the caller sees — end with a self-contained summary.",
   builtinTools: ["web_search", "visit_webpage"],
@@ -1470,7 +1553,7 @@ something it has to notice and switch off.
 
 | Tool | Description | Params |
 | --- | --- | --- |
-| `web_search` | Search the web (DuckDuckGo) — no API key required | `query`, `max_results?` (default 5) |
+| `web_search` | Search the web (DuckDuckGo) — no API key required | `query`, `maxResults?` (default 5) |
 | `visit_webpage` | Fetch URL to plain text | `url` |
 | `get_page_design` | Fetch URL's raw HTML + CSS (style blocks and linked stylesheets) to study/mimic a site's design | `url` |
 | `fetch_json` | HTTP GET a JSON API | `url`, `headers?` |
@@ -1533,75 +1616,49 @@ that case — `slot.update`'s window is synchronous — so reach for the lock wh
 the thing being mutated is outside the session. `withLock` takes an optional
 acquire deadline and throws `KeyedLockTimeoutError` when it runs out.
 
-## Database API — `ctx.db`
+## Persisting data — bring your own client
 
-Persistent SQL storage scoped per app, backed by the app's own Postgres
-schema. Access via `ctx.db`:
+**There is no `ctx.db`.** It was a SQL handle on the tool context, backed first
+by a Postgres the platform provisioned per app and later by a `DATABASE_URL` an
+author set. The platform provisions no database, and no longer hands tool code
+one either.
 
-```ts no-check
-ctx.db.query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
-```
+So a tool that needs to persist anything uses a client of its own:
 
-One parameterized statement per call, `$1, $2…` placeholders — never
-interpolate values into the SQL string. The rows come back as plain objects;
-`jsonb` columns are returned already parsed (no `JSON.parse` needed).
-A query returning more than 1000 rows throws — always bound reads with
-`LIMIT` (paginate with `LIMIT`/`OFFSET`).
-
-**The database must be enabled** or accessing `ctx.db` throws:
-
-- CLI: `aai storage enable`
-- Studio: Settings pane → Database → Enable database (covers both the
-  preview and published agents, each with its own schema)
-- `aai dev`: set `DATABASE_URL` in the project `.env`
+```ts no-check
+// tools/save_note.ts — a driver you added, a credential you set.
+import { tool } from "@alexkroman1/aai";
+import postgres from "postgres";
+import { z } from "zod";
 
-**A workflow UPLOAD needs one more thing locally: somewhere to put the bytes.**
-A deployed agent gets it from the platform; under `aai dev` the bytes go to a
-bucket you point it at, and the Supabase CLI prints the two values
-(`supabase start`, then `supabase status -o env`):
+// Module scope, so one pool serves every call in this sandbox.
+const sql = postgres(process.env.DATABASE_URL ?? "");
 
-```sh
-DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
-AAI_UPLOAD_STORAGE_URL=http://127.0.0.1:54321
-AAI_UPLOAD_STORAGE_KEY=<SERVICE_ROLE_KEY>
-AAI_UPLOAD_STORAGE_BUCKET=blobs
+export default tool({
+  description: "Save a note.",
+  inputSchema: z.object({ body: z.string() }),
+  execute: async ({ body }) => {
+    await sql`insert into notes (body) values (${body})`;
+    return "saved";
+  },
+});
 ```
 
-`blobs`, not `uploads`: that is the one bucket the local stack declares
-(`supabase/config.toml`, applied by `supabase start`), and uploads land under an
-`uploads/` PREFIX inside it — the same layout production uses beside its
-`blobs/<sha256>` deploy artifacts. Nothing creates a bucket for you.
-
-`.env.example` in a scaffolded project carries this block commented out.
+Add the driver to your project's `package.json` and the URL with `aai secret put
+DATABASE_URL …` (or in `.env` under `aai dev`). Nothing here is privileged — an
+HTTP API, a provider SDK or a hosted KV works the same way.
 
-Without both halves `api.upload(file)` fails naming the one that is missing —
-never quietly into a directory, which is what it used to do and then lose by the
-time a resumed run read it.
+**What the platform DOES persist for you**, with no setup:
 
-Create tables lazily from tool code and upsert with `on conflict`:
-
-```ts no-check
-await ctx.db.query(`create table if not exists app_state (
-  key text primary key,
-  value jsonb not null,
-  updated_at timestamptz not null default now()
-)`);
-await ctx.db.query(
-  "insert into app_state (key, value, updated_at) values ($1, $2::jsonb, now()) " +
-    "on conflict (key) do update set value = excluded.value, updated_at = now()",
-  ["user:123", JSON.stringify({ name: "Alex" })],
-);
-const rows = await ctx.db.query<{ value: { name: string } }>(
-  "select value from app_state where key = $1",
-  ["user:123"],
-);
-```
+- **`sessionSlot`** — this session's state, durable across a crash or a
+  redeploy. Reach for it before reaching for a database; most agents need
+  nothing else.
+- **Durable workflow runs** — a run survives the sandbox recycling, every
+  redeploy, and a multi-day `sleep()`.
 
-Use `ctx.db` for data that must outlive the session (saves, filed records,
-user profiles). For scratch that only the current session needs, prefer
-a `sessionSlot` (per-session state, stored when the app has a database); the
-`remember`/`recall` builtins likewise remain for session-scoped notes the
-LLM manages itself.
+Those two 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.
 
 ## Custom UI — `client()`
 
@@ -1947,15 +2004,13 @@ Common mistakes when working in aai projects:
   platform's Modal/Deno sandbox; the self-hosted `aai dev` server has no
   sandbox, so there `run_code` refuses with an error result. Deploy to test
   it end-to-end, or use the `calculate` builtin for simple arithmetic in dev.
-- **`ctx.db` throws until the database is enabled.** Enable it with
-  `aai storage enable` (CLI), Settings → Database (studio), or
-  `DATABASE_URL` in `.env` (`aai dev`) before shipping tools that persist
-  data. A deployed agent reads its connection string when its sandbox is
-  built, so enabling rebuilds it — the change reaches a running agent
-  without a redeploy.
-- **The database is per-app.** Rows are shared by every session of one
-  deployment — key them yourself if sessions must not see each other's data
-  (or keep session-scoped data in a `sessionSlot`).
+- **There is no `ctx.db`.** The platform provisions no database and hands tool
+  code none, so a tool that persists brings its own client — see "Persisting
+  data". Two consequences worth knowing before you do: a deployed agent reads a
+  secret when its sandbox is BUILT, so a newly set `DATABASE_URL` reaches it on
+  the next deploy rather than immediately; and a database you bring is shared by
+  every session of the deployment, so key rows yourself if sessions must not see
+  each other's data (or keep session-scoped data in a `sessionSlot`).
 - **Rime language codes are ISO 639-3** (3-letter, e.g. `"eng"`), not
   ISO 639-1 (`"en"`).
 

package/dist/scaffold/global.d.ts

@@ -1 +1,13 @@
 /// <reference types="vite/client" />
+
+/**
+ * `virtual:aai/agent` — the agent as `aai build` lowers it: `agent.ts` with its
+ * `tools/` directory discovered and its `system-prompt.md` applied.
+ *
+ * Served by `aaiAgentPlugin()` in `vitest.config.ts`, which resolves it against
+ * the importing spec's own directory. See `@alexkroman1/aai/testing/vite`.
+ */
+declare module "virtual:aai/agent" {
+  const agentDef: import("@alexkroman1/aai").AgentDef;
+  export default agentDef;
+}

package/dist/scaffold/package.json

@@ -14,9 +14,9 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^8.2.0",
-    "@alexkroman1/aai-runtime": "^8.2.0",
-    "@alexkroman1/aai-ui": "^8.2.0",
+    "@alexkroman1/aai": "^9.0.0",
+    "@alexkroman1/aai-runtime": "^9.0.0",
+    "@alexkroman1/aai-ui": "^9.0.0",
     "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -26,7 +26,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^8.2.0",
+    "@alexkroman1/aai-cli": "^9.0.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

package/dist/scaffold/server.mjs

@@ -17,7 +17,11 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parseEnv } from "node:util";
-import { createAgentServer, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
+import {
+  createAgentServer,
+  ensureSessionStateSchema,
+  withHostCredentialFallback,
+} from "@alexkroman1/aai-runtime";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
 
 const root = path.dirname(fileURLToPath(import.meta.url));
@@ -54,7 +58,22 @@ if (!existsSync(workerPath)) {
 }
 // A file: URL rather than a relative specifier, so the path is correct on
 // Windows, where a bare POSIX-looking path is not a valid module specifier.
-const { default: agent } = await import(pathToFileURL(workerPath).href);
+const worker = await import(pathToFileURL(workerPath).href);
+const agent = worker.default;
+
+/**
+ * The compiled workflow surface, carried on the bundle as two string exports.
+ *
+ * A `"use workflow"` body has to go through the DevKit's compiler, which happens
+ * at BUILD time — a deployed agent is handed one ESM string and has no bundler —
+ * so `aai build` leaves the result here as data. Passing them is what makes
+ * durable workflows actually run: without them the server accepts a run and no
+ * world is ever started to execute it, so it sits `pending` with no error
+ * anywhere. Both are absent for a project with no `workflows/` directory.
+ */
+const workflowCode =
+  typeof worker.__aaiWorkflowCode === "string" ? worker.__aaiWorkflowCode : undefined;
+const stepCode = typeof worker.__aaiStepCode === "string" ? worker.__aaiStepCode : undefined;
 
 /**
  * Parse a dotenv-syntax file into a record; `{}` when it does not exist.
@@ -132,6 +151,24 @@ const env = await resolveAgentEnv();
  */
 const publicUrl = process.env.PUBLIC_URL?.trim();
 
+/**
+ * Create the session-state tables, when this agent has a database.
+ *
+ * A `DATABASE_URL` puts session state in Postgres, and those tables come with
+ * whoever OWNS the database — which for a self-hosted agent is you, with no
+ * migration step anywhere to hang them off. Without this the server starts,
+ * reports `sessionState: postgres, durable: true`, and then every session dies
+ * at start with a fatal error the browser shows as "Session failed to start",
+ * the real reason (`relation "aai_session_events" does not exist`) appearing
+ * only in this process's log.
+ *
+ * Best-effort: if a real migration already created them and this role may not
+ * CREATE, it warns and the server starts anyway.
+ */
+if (env.DATABASE_URL) {
+  await ensureSessionStateSchema({ url: env.DATABASE_URL, logger: console });
+}
+
 const server = createAgentServer({
   agent,
   env,
@@ -141,6 +178,16 @@ const server = createAgentServer({
   providerEnv: withHostCredentialFallback(env),
   clientDir: resolveClientDir(),
   ...(publicUrl ? { publicUrl } : {}),
+  // Durable workflows. A `DATABASE_URL` in `env` puts the runs in Postgres and
+  // they survive a restart; without one they live in a per-process directory and
+  // do not, which is the same trade `aai dev` makes.
+  //
+  // Passed straight through rather than conditionally spread: both fields accept
+  // `undefined` explicitly, so a project with no `workflows/` directory needs no
+  // guard here — and a truthiness-guarded spread is what `guard-invariants`
+  // rule 22 counts.
+  workflowCode,
+  stepCode,
 });
 
 // Loopback by default: this server has no request authentication of its own,

package/dist/scaffold/tsconfig.json

@@ -4,6 +4,7 @@
     "module": "ESNext",
     "moduleResolution": "bundler",
     "strict": true,
+    "noUncheckedIndexedAccess": true,
     "useUnknownInCatchVariables": false,
     "verbatimModuleSyntax": true,
     "allowImportingTsExtensions": true,

package/dist/scaffold/vitest.config.ts

@@ -1,3 +1,4 @@
+import { aaiAgentPlugin } from "@alexkroman1/aai/testing/vite";
 import { defineConfig } from "vitest/config";
 
 /**
@@ -16,9 +17,32 @@ import { defineConfig } from "vitest/config";
  * explicit `import { test } from "vitest"`. Both spellings are common, both
  * are correct, and tsconfig's `types: ["vitest/globals"]` already promises
  * the un-imported one — this makes the runtime match the types.
+ *
+ * `reporters` is PINNED, and left unset it is not merely a default — it is a
+ * different reporter depending on who is running. Vitest 4 resolves an unset
+ * value to `std-env`'s `isAgent ? "agent" : "default"`, and the agent reporter
+ * prints a passing file's captured console output nowhere. So `aai test` run by
+ * a coding agent — this project's own studio agent, or a CLI agent in your
+ * terminal — swallowed every `console.log` from a test that passed, which is
+ * exactly where you put one while working out what an agent said or which tool
+ * it reached for. Measured on a scaffolded project, vitest 4.1.10: with the
+ * agent markers in the environment a module-scope `console.warn` printed
+ * nothing; with them stripped it printed; pinning this restored it either way.
+ *
+ * That reporter exists to keep an agent's output small, so this is a real
+ * trade — it is pinned because a debugging line you cannot see costs more than
+ * the tokens it saves, and because a test run that behaves differently
+ * depending on who typed the command is the harder thing to reason about. Drop
+ * the line if you would rather have the terser output.
+ *
+ * `aaiAgentPlugin` serves `virtual:aai/agent` — the agent lowered the way
+ * `aai build` lowers it, so a spec imports one module instead of rebuilding it
+ * out of a glob, a `?raw` read and `deployedAgent`.
  */
 export default defineConfig({
+  plugins: [aaiAgentPlugin()],
   test: {
     globals: true,
+    reporters: ["default"],
   },
 });

package/dist/{secret-Ct34kdgU.mjs → secret-CwgDLpSy.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-u7T4YooX.mjs";
-import { f as checkedResponse, p as isStringArray } from "./_studio-DR5yzZ1T.mjs";
-import { t as secretRequest } from "./_slug-api-z-USxPtL.mjs";
+import { f as checkedResponse, p as isStringArray } from "./_studio-CKrsixd0.mjs";
+import { t as secretRequest } from "./_slug-api--ZBmIGH-.mjs";
 import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 import { text } from "node:stream/consumers";

package/dist/{studio-CzTzPqe1.mjs → studio-D3-HWIfk.mjs}

@@ -5,9 +5,10 @@ import { s as updateProjectConfig } from "./_config-CmJOFsAP.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
 import { a as resolveDeployTarget } from "./_agent-BTwZJu4P.mjs";
 import { layerScaffold } from "./_templates-4WcKOjS5.mjs";
-import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-DR5yzZ1T.mjs";
+import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-CKrsixd0.mjs";
+import { existsSync } from "node:fs";
 import path from "node:path";
-import { isRecord } from "@alexkroman1/aai/utils";
+import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 //#region studio.ts
 /**
@@ -74,7 +75,7 @@ async function executePull(opts) {
 		serverUrl,
 		studioProject: opts.project,
 		studioSourceHash: remote.sourceHash,
-		...remote.deployedSlug ? { slug: remote.deployedSlug } : {}
+		...omitUndefined({ slug: remote.deployedSlug })
 	});
 	const count = Object.keys(remote.files).length;
 	log.success(`Pulled ${opts.project} (${count} files) into ${target}`);
@@ -95,6 +96,7 @@ async function pushProject(opts) {
 	const { files, warnings } = await collectSourceFiles(opts.cwd);
 	for (const warning of warnings) log.warn(warning);
 	if (Object.keys(files).length === 0) throw new Error("Nothing to push — this directory has no project files.");
+	if (!files["agent.ts"] && existsSync(path.join(opts.cwd, "agent.ts"))) throw new CliError("entry_not_synced", warnings.find((w) => w.startsWith("agent.ts ")) ?? "agent.ts exists locally but was not synced.", "The entry file must sync to deploy — reduce its size or fix its encoding.");
 	let project = config?.studioProject;
 	let baseHash = config?.studioSourceHash;
 	let slug = config?.slug;
@@ -114,7 +116,7 @@ async function pushProject(opts) {
 		serverUrl,
 		studioProject: project,
 		studioSourceHash: result.sourceHash,
-		...slug ? { slug } : {}
+		...omitUndefined({ slug })
 	});
 	return {
 		project,
@@ -166,7 +168,7 @@ async function executePublish(opts) {
 	const hadSlug = pushed.slug !== void 0;
 	if (pushed.slug) await syncEnvSecrets(opts.cwd, serverUrl, apiKey, project);
 	log.step(`Publishing ${project} (builds in the project's sandbox)…`);
-	const result = checkedResponse(await publishStudioProject(serverUrl, apiKey, project), (value) => isRecord(value) && typeof value.slug === "string" && typeof value.output === "string", `the publish route at ${serverUrl}`);
+	const result = checkedResponse(await publishStudioProject(serverUrl, apiKey, project, { skipTypecheck: opts.skipTypecheck }), (value) => isRecord(value) && typeof value.slug === "string" && typeof value.output === "string", `the publish route at ${serverUrl}`);
 	if (result.output.trim()) log.message(result.output.trim());
 	await updateProjectConfig(opts.cwd, {
 		serverUrl,