@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/scaffold/package.json

@@ -6,28 +6,31 @@
   },
   "scripts": {
     "dev": "aai dev",
+    "prestart": "aai build --skip-tests",
     "start": "node server.mjs",
     "build": "aai build",
     "test": "aai test",
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^5.14.0",
-    "@alexkroman1/aai-ui": "^5.14.0",
+    "@alexkroman1/aai": "^6.1.0",
+    "@alexkroman1/aai-ui": "^6.1.0",
+    "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
+    "workflow": "4.8.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^5.14.0",
+    "@alexkroman1/aai-cli": "^6.1.0",
     "@tailwindcss/vite": "^4.3.3",
-    "@types/node": "^26.1.1",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.4",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
     "typescript": "^7.0.2",
-    "vite": "^8.1.5",
+    "vite": "^8.2.1",
     "vitest": "^4.1.10"
   }
 }

package/dist/scaffold/pnpm-workspace.yaml

@@ -7,9 +7,17 @@
 # build script without this entry. pnpm 10 reads `onlyBuiltDependencies`;
 # pnpm 11 renamed it to `allowBuilds` and ignores the old key, so both are
 # declared. This file also marks the project as its own pnpm workspace root.
+# `@swc/core` and `cbor-extract` arrive TRANSITIVELY, through the `workflow`
+# dependency the DevKit templates need. pnpm 11 makes an undeclared build script
+# a hard error (`ERR_PNPM_IGNORED_BUILDS`), so leaving them out fails the install
+# — which is the very first thing `aai init` does after writing these files.
 onlyBuiltDependencies:
+  - "@swc/core"
+  - cbor-extract
   - esbuild
 allowBuilds:
+  "@swc/core": true
+  cbor-extract: true
   esbuild: true
 
 # Exempt our own packages from pnpm's release-age quarantine, and ONLY ours.

package/dist/scaffold/server.mjs

@@ -1,22 +1,21 @@
 // Self-hosted entrypoint — this is what `npm start` runs.
 //
 // It serves the agent over HTTP + WebSocket from your own Node process: no
-// platform account, no CLI at run time, no bundler. `aai dev` is the
-// development counterpart (file watching, Vite, a browser that opens itself);
-// this file is the deployment.
+// platform account, no managed anything. `aai dev` is the development
+// counterpart (file watching, Vite, a browser that opens itself); this file is
+// the deployment.
 //
 //   npm start                          # http://127.0.0.1:3000
 //   PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container
 //
 // Anything that can run Node can host it: copy the project, install
-// dependencies, provide the secrets, run this file. Deleting it costs nothing
-// — `aai dev`, `aai publish` and the managed platform never read it.
+// dependencies, provide the secrets, run `npm start`. Deleting this file costs
+// nothing — `aai dev`, `aai publish` and the managed platform never read it.
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { registerHooks } from "node:module";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { parseEnv } from "node:util";
 import { createAgentServer, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
@@ -24,56 +23,38 @@ import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
 const root = path.dirname(fileURLToPath(import.meta.url));
 
 /**
- * Teach Node the two non-JavaScript import shapes the `aai` bundler supports,
- * so one `agent.ts` runs unchanged under `aai dev`, `aai publish`, and here.
+ * The built agent — `.aai/worker.mjs`, produced by `aai build`, which the
+ * `prestart` script runs for you. It is the SAME artifact `aai publish` uploads
+ * and the managed platform runs, so a self-hosted agent and a deployed one
+ * cannot behave differently.
  *
- * - `import prompt from "./system-prompt.md?raw"` — a Vite convention; Node
- *   would look for a file literally named `system-prompt.md?raw`.
- * - `import data from "./data.json"` with no import attribute — TypeScript's
- *   `resolveJsonModule` allows it; Node requires `with { type: "json" }` and
- *   otherwise fails with ERR_IMPORT_ATTRIBUTE_MISSING. An import that DOES
- *   carry the attribute is left to Node, whose own handling is correct.
+ * Loading the build rather than `agent.ts` directly is what makes `tools/`
+ * work. A tool is registered by EXISTING — its file name is the name the model
+ * calls, and nothing anywhere lists them — and the only place a directory can
+ * be turned into modules is where the bundle is assembled: a deployed agent is
+ * handed one ESM string and has no filesystem to scan. So the bundler
+ * enumerates `tools/` and emits the imports, and every loader that skips it
+ * would serve an agent with no tools at all.
  *
- * Nothing is transformed beyond that: `.ts` itself needs no help, because Node
- * strips the types natively (this project needs Node 24+). That is why there
- * is no build step here, and no second copy of the agent in JavaScript that
- * could drift from the one you deploy.
+ * It also settles two things the bundler already resolves, and this file used
+ * to re-implement with `node:module` hooks: `import prompt from
+ * "./system-prompt.md?raw"` (a Vite convention — Node looks for a file
+ * literally named `system-prompt.md?raw`) and `import data from "./data.json"`
+ * with no import attribute (TypeScript's `resolveJsonModule` allows it, Node
+ * requires `with { type: "json" }`). Both are inlined into the bundle, so
+ * there is nothing left to teach Node.
  */
-registerHooks({
-  resolve(specifier, context, nextResolve) {
-    if (specifier.startsWith(".") && specifier.endsWith("?raw")) {
-      // Resolved by hand rather than through nextResolve: the default
-      // resolver has no format for `.md` and the query would be lost anyway.
-      return {
-        url: new URL(specifier, context.parentURL).href,
-        format: "module",
-        shortCircuit: true,
-      };
-    }
-    return nextResolve(specifier, context);
-  },
-  load(url, context, nextLoad) {
-    const asRaw = url.endsWith("?raw");
-    const asBareJson = url.endsWith(".json") && context.importAttributes?.type !== "json";
-    if (!(asRaw || asBareJson)) return nextLoad(url, context);
-    const text = readFileSync(fileURLToPath(asRaw ? url.slice(0, -"?raw".length) : url), "utf-8");
-    return {
-      format: "module",
-      // `export default <literal>` for both: a JSON document is already a
-      // valid JS expression, and JSON.stringify makes any file safe to embed
-      // as a string. Emitting `format: "json"` instead would put the import
-      // back under the attribute check this exists to satisfy.
-      source: `export default ${asRaw ? JSON.stringify(text) : text};`,
-      shortCircuit: true,
-    };
-  },
-});
-
-// Imported dynamically, and this is load-bearing: static `import` statements
-// are hoisted and evaluated BEFORE any statement in this file, so an
-// `import agent from "./agent.ts"` at the top would load the agent — and every
-// `?raw` import inside it — before the hooks above were ever registered.
-const { default: agent } = await import("./agent.ts");
+const workerPath = path.join(root, ".aai", "worker.mjs");
+if (!existsSync(workerPath)) {
+  console.error(
+    `No built agent at ${path.relative(root, workerPath)}.\n` +
+      "Run `npm run build` (or `aai build`) first — `npm start` normally does it for you.",
+  );
+  process.exit(1);
+}
+// 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);
 
 /** Parse a dotenv-syntax file into a record; `{}` when it does not exist. */
 async function readEnvFile(file) {
@@ -116,8 +97,8 @@ async function resolveAgentEnv() {
 
 /**
  * Static assets served at `/`: this project's own UI once `client.tsx` has been
- * built (`npm run build` leaves it in `.aai/client`), otherwise the prebuilt
- * default client that ships inside @alexkroman1/aai-ui.
+ * built (the same `aai build` leaves it in `.aai/client`), otherwise the
+ * prebuilt default client that ships inside @alexkroman1/aai-ui.
  */
 function resolveClientDir() {
   const built = path.join(root, ".aai", "client");
@@ -130,6 +111,20 @@ function resolveClientDir() {
 
 const env = await resolveAgentEnv();
 
+/**
+ * Where THIS server is reachable from outside — `PUBLIC_URL`, e.g.
+ * `https://agent.example.com`. Set it whenever a durable workflow has to hand a
+ * URL to somebody else: `ctx.workflows.publicWebhookUrl(token)` is built from it,
+ * and without it that call throws rather than minting a `http://localhost:3000`
+ * URL that a payment provider will try, days later, and fail.
+ *
+ * Nothing else reads it, so it is not a startup requirement: an agent with no
+ * webhooks needs no value here. It is deliberately NOT derived from `PORT`/`HOST`
+ * — those describe the socket this process binds, which behind a reverse proxy is
+ * not what the outside world dials.
+ */
+const publicUrl = process.env.PUBLIC_URL?.trim();
+
 const server = createAgentServer({
   agent,
   env,
@@ -138,6 +133,7 @@ const server = createAgentServer({
   // ASSEMBLYAI_API_KEY to a container. Anything in `env` still wins.
   providerEnv: withHostCredentialFallback(env),
   clientDir: resolveClientDir(),
+  ...(publicUrl ? { publicUrl } : {}),
 });
 
 // Loopback by default: this server has no request authentication of its own,

package/dist/{secret-Ds9dvqAj.mjs → secret-DzSQx1Ds.mjs}

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-import { a as ok, n as fail } from "./_output-CC300DzW.mjs";
+import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-u7T4YooX.mjs";
-import { t as secretRequest } from "./_slug-api-D30zPmsn.mjs";
+import { a as isStringArray, i as checkedResponse } from "./_api-client-LgLksMhN.mjs";
+import { t as secretRequest } from "./_slug-api-D2heILuC.mjs";
+import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 import { text } from "node:stream/consumers";
 //#region secret.ts
@@ -46,7 +48,8 @@ async function executeSecretDelete(cwd, name, server) {
 	return ok({ name });
 }
 async function executeSecretList(cwd, server) {
-	const { data: { vars } } = await secretRequest(cwd, "", { action: "secret" }, server);
+	const { data, target } = await secretRequest(cwd, "", { action: "secret" }, server);
+	const { vars } = checkedResponse(data, (value) => isRecord(value) && isStringArray(value.vars), `the secret list for ${target}`);
 	if (vars.length === 0) log.info("No secrets set. Use `aai secret put <name>` to add one.");
 	else {
 		log.message(`${vars.length} secret${vars.length === 1 ? "" : "s"}:`);

package/dist/{storage-DbrQSHFk.mjs → storage-C-Do0mIA.mjs}

@@ -1,17 +1,29 @@
 #!/usr/bin/env node
-import { a as ok, n as fail } from "./_output-CC300DzW.mjs";
+import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
-import { n as slugRequest } from "./_slug-api-D30zPmsn.mjs";
+import { i as checkedResponse } from "./_api-client-LgLksMhN.mjs";
+import { n as slugRequest } from "./_slug-api-D2heILuC.mjs";
+import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 //#region storage.ts
+/**
+* The storage route's answer, CHECKED — every caller here reads `enabled` and
+* a body without it reported "Storage is disabled for <slug>" (and returned
+* `enabled: undefined` to a script) for a server that never said so. See
+* `checkedResponse`.
+*/
 async function storageRequest(cwd, init, server) {
-	return slugRequest(cwd, "/storage", {
+	const { data, slug } = await slugRequest(cwd, "/storage", {
 		...init,
 		action: "storage"
 	}, server);
+	return {
+		enabled: checkedResponse(data, (value) => isRecord(value) && typeof value.enabled === "boolean", `the storage route for ${slug}`).enabled,
+		slug
+	};
 }
 async function executeStorageStatus(cwd, server) {
-	const { data: { enabled }, slug } = await storageRequest(cwd, void 0, server);
+	const { enabled, slug } = await storageRequest(cwd, void 0, server);
 	if (enabled) log.info(`Storage is enabled for ${slug}`);
 	else log.info(`Storage is disabled for ${slug}. Use \`aai storage enable\` to turn it on.`);
 	return ok({
@@ -20,7 +32,7 @@ async function executeStorageStatus(cwd, server) {
 	});
 }
 async function executeStorageEnable(cwd, server) {
-	const { data: { enabled }, slug } = await storageRequest(cwd, { method: "POST" }, server);
+	const { enabled, slug } = await storageRequest(cwd, { method: "POST" }, server);
 	log.success(`Storage enabled for ${slug}`);
 	log.info("Tool code can now use ctx.db.query(sql, params).");
 	return ok({
@@ -43,7 +55,7 @@ async function executeStorageDisable(cwd, opts = {}) {
 			return fail("cancelled", "Disable cancelled");
 		}
 	}
-	const { data: { enabled }, slug } = await storageRequest(cwd, { method: "DELETE" }, opts.server);
+	const { enabled, slug } = await storageRequest(cwd, { method: "DELETE" }, opts.server);
 	log.success(`Storage disabled for ${slug} — database schema and data dropped`);
 	return ok({
 		slug,

package/dist/{studio-GSFd4s5O.mjs → studio-BGVmCA2G.mjs}

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-import { a as ok, t as CliError } from "./_output-CC300DzW.mjs";
+import { a as ok, t as CliError } from "./_output-CKkmWs7i.mjs";
 import { n as log, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
-import { s as updateProjectConfig } from "./_config-CzwAWOWr.mjs";
-import { t as resolveServerEnv } from "./_server-common-61fL__39.mjs";
-import { i as resolveDeployTarget } from "./_agent-C8Jk-ZcP.mjs";
-import { layerScaffold } from "./_templates-B1kt3BGt.mjs";
-import { n as apiRequest } from "./_api-client-BX8Qv51n.mjs";
-import { a as publishStudioProject, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectUrl, t as collectSourceFiles } from "./_studio-D2ciIhbi.mjs";
+import { s as updateProjectConfig } from "./_config-D_s09e7g.mjs";
+import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
+import { a as resolveDeployTarget } from "./_agent-vGW5SBnX.mjs";
+import { layerScaffold } from "./_templates-iDGjGiPf.mjs";
+import { i as checkedResponse, n as apiRequest } from "./_api-client-LgLksMhN.mjs";
+import { a as publishStudioProject, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectUrl, t as collectSourceFiles } from "./_studio-zAJycZ8j.mjs";
 import path from "node:path";
+import { isRecord } from "@alexkroman1/aai/utils";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 //#region studio.ts
 /**
@@ -158,7 +159,7 @@ async function syncEnvSecrets(cwd, serverUrl, apiKey, project) {
 }
 async function executePublish(opts) {
 	if (!opts.skipTypecheck) {
-		const { assertTypechecks } = await import("./_typecheck-gate-4v9UBZHh.mjs");
+		const { assertTypechecks } = await import("./_typecheck-gate-BXvUNnfs.mjs");
 		await assertTypechecks(opts.cwd);
 	}
 	const pushed = await pushProject(opts);
@@ -166,8 +167,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 = await publishStudioProject(serverUrl, apiKey, project);
-	if (typeof result?.slug !== "string" || typeof result?.output !== "string") throw new CliError("bad_publish_response", `Unexpected response from the publish route at ${serverUrl}.`, "Check that --server points at an aai platform server, then try again.");
+	const result = checkedResponse(await publishStudioProject(serverUrl, apiKey, project), (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,

package/dist/templates/code-interpreter/agent.ts

@@ -1,9 +1,7 @@
 import { agent } from "@alexkroman1/aai";
-import systemPrompt from "./system-prompt.md?raw";
 
 export default agent({
   name: "Coda",
-  systemPrompt,
   greeting:
     "Hey, I'm Coda. I solve problems by writing and running code. Try asking me something like, what's the 50th fibonacci number, or what day of the week was January 1st 2000.",
   builtinTools: ["run_code"],

package/dist/templates/dispatch-center/agent.test.ts

@@ -1,20 +1,18 @@
 import type { ToolContext } from "@alexkroman1/aai";
 import { createToolContext } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import { dispatchSlot, type StateSlot } from "./shared.ts";
-import { incidentCreate } from "./tools/incident_create.ts";
-import { incidentEscalate } from "./tools/incident_escalate.ts";
-import { incidentTriage } from "./tools/incident_triage.ts";
-import { incidentUpdateStatus } from "./tools/incident_update_status.ts";
-import { resourcesDispatch } from "./tools/resources_dispatch.ts";
-import { resourcesUpdateStatus } from "./tools/resources_update_status.ts";
-
-/** The dispatch board lives in ctx.state, one per session — and
- *  `createToolContext` gives each call its own session id, so two contexts are
- *  two boards by construction. */
-function makeCtx(): { ctx: ToolContext<StateSlot> } {
-  return { ctx: createToolContext<StateSlot>() };
-}
+import { dispatchSlot } from "./shared.ts";
+import incidentCreate from "./tools/incident_create.ts";
+import incidentEscalate from "./tools/incident_escalate.ts";
+import incidentTriage from "./tools/incident_triage.ts";
+import incidentUpdateStatus from "./tools/incident_update_status.ts";
+import resourcesDispatch from "./tools/resources_dispatch.ts";
+import resourcesUpdateStatus from "./tools/resources_update_status.ts";
+
+/** The dispatch board lives in a session slot, and `createToolContext` gives
+ *  each call its own slot store — so two contexts are two boards by
+ *  construction. */
+const makeCtx = (): ToolContext => createToolContext();
 
 async function createIncidentFor(
   ctx: ToolContext,
@@ -29,7 +27,7 @@ async function createIncidentFor(
 
 describe("dispatch-center template", () => {
   test("resolving an incident does not yank a reassigned unit off its new incident", async () => {
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
 
     const inc1 = await createIncidentFor(ctx);
     await resourcesDispatch.execute({ incidentId: inc1, callsigns: ["Medic-1"] }, ctx);
@@ -51,7 +49,7 @@ describe("dispatch-center template", () => {
   });
 
   test("callsigns: ['auto'] triggers auto-dispatch as the description promises", async () => {
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
     const incidentId = await createIncidentFor(ctx, "cardiac arrest, patient not breathing");
 
     const result = (await resourcesDispatch.execute({ incidentId, callsigns: ["auto"] }, ctx)) as {
@@ -64,7 +62,7 @@ describe("dispatch-center template", () => {
   });
 
   test("concurrent tool calls are serialized — no lost updates", async () => {
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
 
     // Parallel tool calls in one LLM turn run concurrently. The per-session
     // mutex in updateState makes each one run against the previous one's
@@ -102,7 +100,7 @@ describe("dispatch-center template", () => {
   });
 
   test("mutual-aid units get unique ids and callsigns across escalations", async () => {
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
     const incidentId = await createIncidentFor(ctx);
 
     await incidentEscalate.execute(
@@ -122,7 +120,7 @@ describe("dispatch-center template", () => {
   });
 
   test("resolved is terminal: no escalation, re-resolution, or dispatch", async () => {
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
     const incidentId = await createIncidentFor(ctx);
     await incidentUpdateStatus.execute({ incidentId, status: "resolved" }, ctx);
 

package/dist/templates/dispatch-center/agent.ts

@@ -1,21 +1,10 @@
 import { agent } from "@alexkroman1/aai";
 import { dashboardView, dispatchSlot } from "./shared.ts";
-import systemPrompt from "./system-prompt.md?raw";
-import { incidentAddNote } from "./tools/incident_add_note.ts";
-import { incidentCreate } from "./tools/incident_create.ts";
-import { incidentEscalate } from "./tools/incident_escalate.ts";
-import { incidentGet } from "./tools/incident_get.ts";
-import { incidentTriage } from "./tools/incident_triage.ts";
-import { incidentUpdateStatus } from "./tools/incident_update_status.ts";
-import { opsDashboard } from "./tools/ops_dashboard.ts";
-import { opsProtocols } from "./tools/ops_protocols.ts";
-import { opsRunScenario } from "./tools/ops_run_scenario.ts";
-import { resourcesDispatch } from "./tools/resources_dispatch.ts";
-import { resourcesGetAvailable } from "./tools/resources_get_available.ts";
-import { resourcesUpdateStatus } from "./tools/resources_update_status.ts";
 
 export default agent({
   name: "Dispatch Command Center",
+  // The board exists before the first tool call, so a resumed connection has
+  // something to project rather than an empty state object.
   // One projection replaces eleven `ctx.send("incidents", ...)` calls, and
   // is the single place that decides caller PII stays server-side.
   syncState: dispatchSlot.projection(dashboardView),
@@ -23,26 +12,10 @@ export default agent({
   // one message ("unit twelve … respond to"). The default pipeline's
   // `max_turn_silence` already tolerates that; reach for
   // `assemblyAIStt({ maxTurnSilenceMs })` only if your callers pause longer.
-  systemPrompt,
   greeting:
     "Dispatch Command Center online. Restoring operational state. I'm ready to take incoming calls, manage active incidents, or run dispatch operations. Say 'dashboard' for a full status report. What do we have.",
 
   // The system prompt instructs the model to use web_search and run_code, so
   // they must be enabled here — the default builtin set does not include them.
   builtinTools: ["think", "remember", "recall", "calculate", "web_search", "run_code"],
-
-  tools: {
-    incident_add_note: incidentAddNote,
-    incident_create: incidentCreate,
-    incident_escalate: incidentEscalate,
-    incident_get: incidentGet,
-    incident_triage: incidentTriage,
-    incident_update_status: incidentUpdateStatus,
-    ops_dashboard: opsDashboard,
-    ops_protocols: opsProtocols,
-    ops_run_scenario: opsRunScenario,
-    resources_dispatch: resourcesDispatch,
-    resources_get_available: resourcesGetAvailable,
-    resources_update_status: resourcesUpdateStatus,
-  },
 });

package/dist/templates/dispatch-center/client.tsx

@@ -1,6 +1,12 @@
 import "@alexkroman1/aai-ui/styles.css";
-import type { ChatMessage } from "@alexkroman1/aai-ui";
-import { AutoScroll, client, useAgentState, useSession } from "@alexkroman1/aai-ui";
+import type { AgentState, ChatMessage } from "@alexkroman1/aai-ui";
+import {
+  AutoScroll,
+  client,
+  useAgentState,
+  useSession,
+  useUserTranscript,
+} from "@alexkroman1/aai-ui";
 import type { DashboardView, DispatchState, IncidentSummary, Severity, Status } from "./shared.ts";
 import { dashboardView, dispatchSlot } from "./shared.ts";
 
@@ -55,17 +61,24 @@ const statusColors: Record<string, string> = {
 // new DashboardView field can't silently miss the pre-first-tool-call render.
 const EMPTY_DASH: DashboardView = dispatchSlot.projection(dashboardView)(undefined);
 
-function stateColor(state: string): string {
-  return state === "listening"
-    ? "#22c55e"
-    : state === "thinking"
-      ? "#eab308"
-      : state === "speaking"
-        ? "#3b82f6"
-        : state === "ready"
-          ? "#22c55e"
-          : "#6b7280";
-}
+// The dot's colour per session state, as an EXHAUSTIVE map rather than an
+// if-chain with a grey default.
+//
+// The palette is this template's own — every client here paints the same six
+// states in its own colours, so the SDK has nothing to share but the union. What
+// the SDK does own is `AgentState`, and `satisfies Record<AgentState, string>`
+// is what borrows it: a state added there stops compiling here, where the
+// `state === "…"` chain this replaced answered a new state with a silent grey
+// badge in three separate files and no way to notice.
+const STATE_COLORS = {
+  disconnected: "#6b7280",
+  connecting: "#6b7280",
+  ready: "#22c55e",
+  listening: "#22c55e",
+  thinking: "#eab308",
+  speaking: "#3b82f6",
+  error: "#6b7280",
+} satisfies Record<AgentState, string>;
 
 function Panel({ title, children }: { title: string; children: React.ReactNode }) {
   return (
@@ -132,6 +145,10 @@ function IncidentCard({ inc }: { inc: IncidentSummary }) {
 
 function App() {
   const session = useSession();
+  // `speaking` and `text` in place of a `userTranscript !== null` check: `null`
+  // is silence and `""` is speech detected with no words back yet, and reading
+  // them as one falsy value hides the indicator at the start of every turn.
+  const { speaking, text: userTranscript } = useUserTranscript();
   // The agent's own board, projected by `syncState`. This replaced a
   // useState mirror that merged incident deltas out of tool events — the
   // projection is already the complete list, so there is nothing to merge.
@@ -169,7 +186,7 @@ function App() {
             <span
               className="w-2.5 h-2.5 rounded-full inline-block"
               style={{
-                background: stateColor(session.state),
+                background: STATE_COLORS[session.state],
                 animation:
                   session.state === "listening"
                     ? "dc-pulse 1.5s ease-in-out infinite"
@@ -249,7 +266,7 @@ function App() {
               ))}
             </AutoScroll>
 
-            {session.userTranscript !== null && (
+            {speaking && (
               <div
                 className="flex items-center px-4 py-2 text-xs italic min-h-8"
                 style={{ background: "#111827", borderTop: "1px solid #1e293b", color: "#64748b" }}
@@ -258,7 +275,7 @@ function App() {
                   className="w-2.5 h-2.5 rounded-full inline-block mr-2"
                   style={{ background: "#22c55e", animation: "dc-pulse 1.5s ease-in-out infinite" }}
                 />
-                {session.userTranscript === "" ? "..." : session.userTranscript}
+                {userTranscript}
               </div>
             )}
             {session.error && (