@alexkroman1/aai 0.8.2 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "type": "module",
   "bin": {
     "aai": "dist/aai.js"
@@ -12,133 +12,154 @@
   ],
   "exports": {
     ".": {
+      "source": "./sdk/mod.ts",
       "types": "./dist/sdk/mod.d.ts",
       "default": "./dist/sdk/mod.js"
     },
     "./types": {
+      "source": "./sdk/types.ts",
       "types": "./dist/sdk/types.d.ts",
       "default": "./dist/sdk/types.js"
     },
-    "./define-agent": {
-      "types": "./dist/sdk/define_agent.d.ts",
-      "default": "./dist/sdk/define_agent.js"
-    },
     "./kv": {
+      "source": "./sdk/kv.ts",
       "types": "./dist/sdk/kv.d.ts",
       "default": "./dist/sdk/kv.js"
     },
     "./vector": {
+      "source": "./sdk/vector.ts",
       "types": "./dist/sdk/vector.d.ts",
       "default": "./dist/sdk/vector.js"
     },
     "./testing": {
+      "source": "./sdk/_mock_ws.ts",
       "types": "./dist/sdk/_mock_ws.d.ts",
       "default": "./dist/sdk/_mock_ws.js"
     },
     "./server": {
+      "source": "./sdk/server.ts",
       "types": "./dist/sdk/server.d.ts",
       "default": "./dist/sdk/server.js"
     },
     "./runtime": {
+      "source": "./sdk/runtime.ts",
       "types": "./dist/sdk/runtime.d.ts",
       "default": "./dist/sdk/runtime.js"
     },
     "./ui": {
+      "source": "./ui/mod.ts",
       "types": "./dist/ui/mod.d.ts",
       "default": "./dist/ui/mod.js"
     },
     "./ui/styles.css": "./ui/styles.css",
     "./ui/session": {
+      "source": "./ui/session_mod.ts",
       "types": "./dist/ui/session_mod.d.ts",
       "default": "./dist/ui/session_mod.js"
     },
     "./ui/components": {
+      "source": "./ui/components_mod.ts",
       "types": "./dist/ui/components_mod.d.ts",
       "default": "./dist/ui/components_mod.js"
     },
     "./internal-types": {
+      "source": "./sdk/_internal_types.ts",
       "types": "./dist/sdk/_internal_types.d.ts",
       "default": "./dist/sdk/_internal_types.js"
     },
     "./protocol": {
+      "source": "./sdk/protocol.ts",
       "types": "./dist/sdk/protocol.d.ts",
       "default": "./dist/sdk/protocol.js"
     },
     "./worker-entry": {
+      "source": "./sdk/worker_entry.ts",
       "types": "./dist/sdk/worker_entry.d.ts",
       "default": "./dist/sdk/worker_entry.js"
     },
     "./builtin-tools": {
+      "source": "./sdk/builtin_tools.ts",
       "types": "./dist/sdk/builtin_tools.d.ts",
       "default": "./dist/sdk/builtin_tools.js"
     },
     "./s2s": {
+      "source": "./sdk/s2s.ts",
       "types": "./dist/sdk/s2s.d.ts",
       "default": "./dist/sdk/s2s.js"
     },
     "./session": {
+      "source": "./sdk/session.ts",
       "types": "./dist/sdk/session.d.ts",
       "default": "./dist/sdk/session.js"
     },
-    "./system-prompt": {
-      "types": "./dist/sdk/system_prompt.d.ts",
-      "default": "./dist/sdk/system_prompt.js"
-    },
     "./ws-handler": {
+      "source": "./sdk/ws_handler.ts",
       "types": "./dist/sdk/ws_handler.d.ts",
       "default": "./dist/sdk/ws_handler.js"
     },
     "./direct-executor": {
+      "source": "./sdk/direct_executor.ts",
       "types": "./dist/sdk/direct_executor.d.ts",
       "default": "./dist/sdk/direct_executor.js"
     },
     "./capnweb": {
+      "source": "./sdk/capnweb.ts",
       "types": "./dist/sdk/capnweb.d.ts",
       "default": "./dist/sdk/capnweb.js"
     },
+    "./host": {
+      "source": "./sdk/host.ts",
+      "types": "./dist/sdk/host.d.ts",
+      "default": "./dist/sdk/host.js"
+    },
     "./winterc-server": {
+      "source": "./sdk/winterc_server.ts",
       "types": "./dist/sdk/winterc_server.d.ts",
       "default": "./dist/sdk/winterc_server.js"
     },
     "./worker-shim": {
+      "source": "./sdk/worker_shim.ts",
       "types": "./dist/sdk/worker_shim.d.ts",
       "default": "./dist/sdk/worker_shim.js"
     }
   },
   "dependencies": {
     "@chonkiejs/core": "^0.0.8",
+    "@hono/node-server": "^1.19.11",
     "@inkjs/ui": "^2.0.0",
     "@preact/preset-vite": "^2.10.4",
     "@preact/signals": "^2.8.2",
     "@tailwindcss/vite": "^4.2.1",
     "@types/json-schema": "^7.0.15",
+    "capnweb": "^0.6.1",
     "chalk": "^5.6.2",
-    "fast-glob": "^3.3.3",
-    "fs-extra": "^11.3.4",
+    "clsx": "^2.1.1",
+    "commander": "^14.0.3",
+    "hono": "^4.12.8",
     "html-to-text": "^9.0.5",
     "human-id": "^4.1.3",
     "ink": "^6.8.0",
-    "minimist": "^1.2.8",
     "p-limit": "^7.3.0",
     "preact": "^10.29.0",
     "react": "^19.2.4",
+    "tsx": "^4.21.0",
     "vite": "^7.3.1",
     "ws": "^8.18.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.7",
-    "@types/fs-extra": "^11.0.4",
+    "@testing-library/preact": "^3.2.4",
     "@types/html-to-text": "^9.0.4",
-    "@types/minimist": "^1.2.5",
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.0",
+    "concurrently": "^9.2.1",
     "ink-testing-library": "^4.0.0",
+    "jsdom": "^29.0.1",
     "linkedom": "^0.18.12",
     "markdownlint-cli2": "^0.21.0",
-    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   },
@@ -166,6 +187,8 @@
     "test": "vitest run",
     "lint": "biome check sdk/ ui/ cli/",
     "lint:fix": "biome check --write sdk/ ui/ cli/",
-    "check": "tsc --noEmit && tsc -p cli/tsconfig.json --noEmit && tsc -p tsconfig.build.json --noEmit && tsc -p tsconfig.templates.json && biome check sdk/ ui/ cli/ && markdownlint-cli2 '**/*.md' '#node_modules' '#.aai' && vitest run"
+    "exports": "node scripts/gen-exports.mjs --write",
+    "exports:check": "node scripts/gen-exports.mjs",
+    "check": "concurrently -g -n tsc,tsc:cli,tsc:build,tsc:tpl,biome,mdlint,exports,test \"tsc --noEmit\" \"tsc -p cli/tsconfig.json --noEmit\" \"tsc -p tsconfig.build.json --noEmit\" \"tsc -p tsconfig.templates.json\" \"biome check sdk/ ui/ cli/\" \"markdownlint-cli2 '**/*.md' '#node_modules' '#.aai'\" \"node scripts/gen-exports.mjs\" \"vitest run\""
   }
 }

package/templates/_shared/CLAUDE.md

@@ -10,7 +10,9 @@ You are helping a user build a voice agent using the **aai** framework.
    does what the user needs before writing custom code.
 3. **Start minimal** — Scaffold from the closest template, then layer on
    customizations. Don't over-engineer the first version.
-4. **Iterate** — Make small, focused changes. Verify each change works before
+4. **Verify** — After every change, run `aai build` to validate the bundle and
+   catch errors. Fix all errors before presenting work to the user.
+5. **Iterate** — Make small, focused changes. Verify each change works before
    moving on.
 
 ## Key rules
@@ -19,7 +21,7 @@ You are helping a user build a voice agent using the **aai** framework.
 - Custom UI goes in `client.tsx` alongside `agent.ts`
 - Optimize `instructions` for spoken conversation — short sentences, no visual
   formatting, no exclamation points
-- Never hardcode secrets — use `aai env add` and access via `ctx.env`
+- Never hardcode secrets — use `aai secret put` and access via `ctx.env`
 - Tool `execute` return values go into LLM context — filter and truncate large
   API responses
 - Agent code runs in a sandboxed worker — use `fetch` (proxied) for HTTP,
@@ -35,10 +37,11 @@ aai build                # Bundle and validate (no server or deploy)
 aai deploy               # Bundle and deploy to production
 aai deploy -y            # Deploy without prompts
 aai deploy --dry-run     # Validate and bundle without deploying
-aai env add <NAME>       # Set an environment variable on the server
-aai env rm <NAME>        # Remove an environment variable
-aai env ls               # List environment variable names
-aai env pull             # Pull env var names into .env for local dev
+aai secret put <NAME>    # Set a secret on the server (prompts for value)
+aai secret delete <NAME> # Remove a secret
+aai secret list          # List secret names
+aai secret pull          # Pull secret names into .env for local dev
+aai rag <url>            # Ingest a site's llms-full.txt into the vector store
 ```
 
 ## Templates
@@ -61,9 +64,9 @@ with `aai init -t <template_name>`.
 | `pizza-ordering`    | Pizza order-taker with dynamic cart sidebar. **Has custom UI.**                    |
 | `dispatch-center`   | 911 dispatch with incident triage and resource assignment. **Has custom UI.**      |
 | `infocom-adventure` | Zork-style text adventure with state, puzzles, inventory. **Has custom UI.**       |
+| `solo-rpg`          | Solo dark-fantasy RPG with dice, oaths, combat, save/load. **Has custom UI.**      |
 | `embedded-assets`   | FAQ bot using embedded JSON knowledge (no web search)                              |
 | `support`           | RAG-powered support agent using vector_search (AssemblyAI docs example)            |
-| `terminal`          | STT-only mode for voice-driven kubectl commands                                    |
 
 ## Minimal agent
 
@@ -150,17 +153,17 @@ injected into agent workers at runtime and available as `ctx.env`. Secrets are
 
 ```sh
 # Set secrets on the server (prompts for value)
-aai env add ASSEMBLYAI_API_KEY
-aai env add MY_API_KEY
+aai secret put ASSEMBLYAI_API_KEY
+aai secret put MY_API_KEY
 
 # List what's set
-aai env ls
+aai secret list
 
-# Pull env var names into .env for local dev reference
-aai env pull
+# Pull secret names into .env for local dev reference
+aai secret pull
 
 # Remove a secret
-aai env rm MY_API_KEY
+aai secret delete MY_API_KEY
 ```
 
 Access secrets in tool code via `ctx.env`:
@@ -246,7 +249,7 @@ Enable via `builtinTools`.
 | `web_search`    | Search the web (Brave Search)                  | `query`, `max_results?` (default 5) |
 | `visit_webpage` | Fetch URL → Markdown                           | `url`                               |
 | `fetch_json`    | HTTP GET a JSON API                            | `url`, `headers?`                   |
-| `run_code`      | Execute JS in sandbox (no net/fs, 30s timeout) | `code`                              |
+| `run_code`      | Execute JS in sandbox (no net/fs, 5s timeout)  | `code`                              |
 | `vector_search` | Search the agent's RAG knowledge base          | `query`, `topK?` (default 5)        |
 | `memory`        | Persistent KV memory (4 tools, see below)      | —                                   |
 
@@ -258,8 +261,7 @@ LLM produces a text response.
 Every `execute` function and lifecycle hook receives a context object:
 
 ```ts
-ctx.sessionId; // string — unique per connection
-ctx.env; // Record<string, string> — secrets from `aai env add`
+ctx.env; // Record<string, string> — secrets from `aai secret put`
 ctx.abortSignal; // AbortSignal — cancelled on interruption (tools only)
 ctx.state; // per-session state
 ctx.kv; // persistent KV store
@@ -267,8 +269,7 @@ ctx.vector; // VectorStore — vector store for RAG (tools only)
 ctx.messages; // readonly Message[] — conversation history (tools only)
 ```
 
-Hooks get `HookContext` (same but without `abortSignal`, `vector`, and
-`messages`).
+Hooks get `HookContext` (same but without `abortSignal` and `messages`).
 
 **Timeouts:** Tool execution times out after **30 seconds** (`abortSignal`
 fires). Lifecycle hooks (`onConnect`, `onTurn`, etc.) time out after **5
@@ -318,6 +319,26 @@ export default defineAgent({
 });
 ```
 
+### Persisting state across reconnects
+
+Use the KV store to auto-save and auto-load state:
+
+```ts
+export default defineAgent({
+  state: () => ({ score: 0, initialized: false }),
+  onConnect: async (ctx) => {
+    const saved = await ctx.kv.get("save:game");
+    if (saved) Object.assign(ctx.state, saved);
+  },
+  onTurn: async (_text, ctx) => {
+    await ctx.kv.set("save:game", ctx.state);
+  },
+});
+```
+
+This works for games, workflows,
+or any agent where users expect to resume where they left off.
+
 ### Persistent storage (KV)
 
 `ctx.kv` is a persistent key-value store scoped per agent. Values are
@@ -841,12 +862,12 @@ const agent = defineAgent({
   instructions: "You are a helpful assistant.",
 });
 
-const server = createServer(agent, {
-  port: 3000,       // default: 3000
-  staticDir: "public", // optional: serve static files
+const server = createServer({
+  agent,
+  clientDir: "public", // optional: serve static files
 });
 
-server.listen();
+await server.listen(3000);
 ```
 
 Run with `node --experimental-strip-types server.ts` or bundle with your
@@ -1018,22 +1039,21 @@ Use directional words naturally: "To the north you see..." not "N: forest"
 - **Returning huge payloads from tools** — Everything a tool returns goes into
   the LLM context. Filter, summarize, or truncate API responses before
   returning. Return only what the agent needs to formulate a spoken answer.
-- **Forgetting sandbox constraints** — Agent code runs in a Deno Worker with
-  _all permissions disabled_ (no net, no fs, no env). Use `fetch` (proxied
-  through the host) for HTTP. Use `ctx.env` for secrets. `Deno.readFile`,
-  `Deno.env.get`, and direct network access will fail silently or throw.
+- **Forgetting sandbox constraints** — Agent code runs in a sandboxed Worker
+  with no direct network or filesystem access. Use `fetch` (proxied through the
+  host) for HTTP. Use `ctx.env` for secrets. Direct network access will fail.
 - **Ignoring `ctx.abortSignal`** — When the user interrupts, in-flight tool
   calls are cancelled via `ctx.abortSignal`. Long-running tools (polling,
   multi-step fetches) should check `ctx.abortSignal.aborted` or pass the signal
   to `fetch`.
 - **Hardcoding secrets** — Never put API keys in `agent.ts`. Use
-  `aai env add MY_KEY` to store them on the server, then access via
+  `aai secret put MY_KEY` to store them on the server, then access via
   `ctx.env.MY_KEY`.
 - **Telling the agent to be verbose** — Voice responses should be 1-3 sentences.
   If your `instructions` say "provide detailed explanations", the agent will
   monologue. Instruct it to be brief and let the user ask follow-ups.
-- **Not setting env vars before deploying** — If your agent needs custom env
-  vars, set them with `aai env add MY_KEY` before deploying.
+- **Not setting secrets before deploying** — If your agent needs custom
+  secrets, set them with `aai secret put MY_KEY` before deploying.
 - **Forgetting SSRF restrictions on `fetch`** — The host validates all proxied
   fetch URLs. Requests to private/internal IP addresses (localhost, 10.x,
   192.168.x, etc.) are blocked.
@@ -1043,7 +1063,7 @@ Use directional words naturally: "To the north you see..." not "N: forest"
 - **"no agent found"** — Ensure `agent.ts` exists in the current directory
 - **"bundle failed"** — TypeScript syntax error — check imports, brackets
 - **"No .aai/project.json found"** — Run `aai deploy` first before using
-  `aai env`
+  `aai secret`
 - **Tool returns `undefined`** — Make sure `execute` returns a value. Even
   `return { ok: true }` is better than an implicit void return.
 - **Agent doesn't use a tool** — Check `description` is clear about when to use

package/templates/_shared/global.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/templates/_shared/package.json

@@ -11,7 +11,8 @@
     "@alexkroman1/aai": "*",
     "@preact/signals": "^2.8.2",
     "preact": "^10.29.0",
-    "tailwindcss": "^4.2.1"
+    "tailwindcss": "^4.2.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2",