@tangle-network/create-agent-app 0.44.36

package/template-chat/CUSTOMIZE.md

@@ -0,0 +1,88 @@
+# CUSTOMIZE.md — fill this project, in order
+
+This is the trail. Walk it top to bottom. Each step is a checklist item paired
+with the DISCOVERY QUESTION it answers — answer the question, then make the
+edit. The whole job is filling `agent.config.ts` + `prompts/system.md` (DATA)
+and wiring credentials; the chat vertical itself is already assembled and
+proven by the e2e test.
+
+When every box is checked and `pnpm typecheck && pnpm test` are green and a
+message round-trips on `pnpm dev`, the app is customized.
+
+---
+
+## ① Identity — `agent.config.ts` + `prompts/system.md`
+
+Discovery: **Whose job does this agent do, in whose voice, under what hard rules?**
+
+- [ ] Set `name` in `agent.config.ts` to the product/agent name.
+- [ ] Rewrite `prompts/system.md` as the real persona: role + voice + remit +
+      hard rules. State intents, never implementations (no commands, no tool
+      scripts — the sandboxed agent picks its own tools).
+- [ ] Keep the grounding rule (never fabricate; cite a record or NOT ON FILE).
+
+## ② Model + harness — `agent.config.ts` → `model`, `harness`
+
+Discovery: **Which model answers by default, at what effort, on which harness?**
+
+- [ ] Set `model.default` to a model your Tangle Router key can reach.
+- [ ] Pick `harness` (`opencode` default; vendor-locked harnesses like
+      `claude-code` must pair with their own provider's models).
+- [ ] Leave per-turn overrides alone — the client can send `model`/`effort`
+      per request and `MODEL_NAME` overrides without a redeploy.
+
+## ③ Infrastructure — `wrangler.toml` + `.dev.vars` + `migrations/`
+
+Discovery: **Where does this app live and what may it spend?**
+
+- [ ] `wrangler d1 create <name>` → paste `database_id` into `wrangler.toml`.
+- [ ] Copy `.dev.vars.example` → `.dev.vars`; fill `BETTER_AUTH_SECRET`,
+      `TANGLE_API_KEY`, `SANDBOX_API_KEY`, `SANDBOX_GATEWAY_URL`.
+- [ ] `pnpm db:migrate:local` — applies `migrations/0001_init.sql` (auth +
+      chat + turn buffer). The e2e test executes this same file, so it cannot
+      silently drift from the schema.
+- [ ] R2 stays commented out unless the product stores artifacts.
+
+## ④ Prove the loop — `pnpm dev`
+
+Discovery: **Does a real message round-trip through a real box?**
+
+- [ ] `pnpm dev`, open http://localhost:8787, sign up, send a message.
+- [ ] Confirm: streamed text renders live, the transcript reloads with parts
+      and a usage receipt, and a second turn continues the same agent session.
+- [ ] Kill the tab mid-turn, reopen the thread — the persisted row is intact
+      (the turn keeps running server-side and buffers for replay).
+
+## ⑤ The product UI — replace the dev page
+
+Discovery: **What does the real surface look like?**
+
+- [ ] `public/index.html` is the dev harness, not the product. Build the real
+      surface in React on `@tangle-network/agent-app/web-react`:
+      `ChatComposer` (`onSendParts` + `onAttach`), `ChatMessages`,
+      `streamChatTurn` (start + resume against `/api/chat/replay/:turnId`),
+      `useChatInteractions` + `InteractionQuestionCard`/`InteractionPlanCard`
+      for the ask channel this server already exposes.
+- [ ] Keep the wire contract: `chatTurnRequestInit` from web-react serializes
+      exactly what `createChatTurnRoutes` parses.
+
+## ⑥ Extend, don't fork
+
+Discovery: **What does this product add beyond the vertical?**
+
+- [ ] Billing/audit/titles → `onTurnComplete` seam in `src/chat.ts`.
+- [ ] PII scrubbing before persistence → `transformFinalText` +
+      `@tangle-network/agent-app/redact`.
+- [ ] Structured agent writes (proposals, records) → the shell's `/tools`
+      side channel, never prose parsing.
+- [ ] Multi-user teams → `@tangle-network/agent-app/teams` and pass your
+      workspace table to `createChatTables({ workspaceTable })` (new migration).
+
+## ⑦ Verify
+
+Discovery: **Does the customized app hold its contract?**
+
+- [ ] `pnpm typecheck` — clean.
+- [ ] `pnpm test` — green (the e2e turn gate + fail-closed auth).
+- [ ] `pnpm dev` — a real turn round-trips end to end.
+- [ ] `pnpm deploy` + `pnpm db:migrate` when it's real.

package/template-chat/README.md

@@ -0,0 +1,50 @@
+# __PROJECT_NAME__
+
+A multimodal chat agent product scaffolded with `create-agent-app --chat`, built
+on [`@tangle-network/agent-app`](https://github.com/tangle-network/agent-app):
+the whole server chat vertical — better-auth sessions, thread/message
+persistence with typed parts + usage receipts, streaming turns with buffered
+replay, file uploads, human-in-the-loop asks — assembled from shell factories.
+The agent itself runs in a Tangle sandbox (a full harness: skills, tools, bash,
+MCP); this app coordinates UI, durability, and access around it.
+
+## Layout
+
+| Path | Surface | Edit when |
+|---|---|---|
+| `agent.config.ts` | DATA — name, model default, harness, ask kinds | defining the agent |
+| `prompts/system.md` | DATA — the persona (imported as a Text module) | shaping behavior |
+| `src/chat.ts` | CODE — the composer (factories → the chat vertical) | extending seams |
+| `src/sandbox.ts` | CODE — the sandbox lane (boxes, credentials, profile) | provisioning changes |
+| `src/worker.ts` | CODE — HTTP routing only | adding an endpoint |
+| `src/db/schema.ts` | CODE — auth tables + `createChatTables()` | schema changes (+ migration) |
+| `migrations/` | SQL the e2e test executes for real | schema changes |
+| `public/index.html` | the dev chat page (not the product UI) | never — replace it (CUSTOMIZE ⑤) |
+| `tests/` | the e2e turn gate this app ships with | extending coverage |
+
+## Get started
+
+```bash
+pnpm install
+pnpm typecheck && pnpm test   # green before you edit anything
+```
+
+Then walk the trail:
+
+1. `AGENTS.md` — the behavior contract (you are customizing a chat agent-app).
+2. `CUSTOMIZE.md` — the ordered fill-checklist, from persona to deploy.
+
+## Scripts
+
+- `pnpm dev` — run the worker + dev page locally (fill `wrangler.toml` + `.dev.vars` first).
+- `pnpm db:migrate:local` / `pnpm db:migrate` — apply `migrations/` to D1.
+- `pnpm typecheck` — `tsc --noEmit`.
+- `pnpm test` — vitest, including the end-to-end turn gate (fake sandbox
+  producer → streamed turn → persisted transcript → replay).
+- `pnpm deploy` — `wrangler deploy`.
+
+## Invariants
+
+Identity comes from the session, never a request body. Inaccessible threads
+read as 404. No mock agent — missing sandbox credentials fail loud. See
+`AGENTS.md` for the full contract.

package/template-chat/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.wrangler/
+.dev.vars
+*.local
+.DS_Store

package/template-chat/_package.json

@@ -0,0 +1,38 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "db:migrate": "wrangler d1 migrations apply __PACKAGE_NAME__ --remote",
+    "db:migrate:local": "wrangler d1 migrations apply __PACKAGE_NAME__ --local",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@tangle-network/agent-app": "__AGENT_APP_VERSION__",
+    "@tangle-network/agent-interface": "0.36.0",
+    "@tangle-network/agent-runtime": "0.109.0",
+    "@tangle-network/sandbox": "0.15.2",
+    "better-auth": "^1.6.16",
+    "drizzle-orm": "^0.45.2"
+  },
+  "peerDependencies": {
+    "@tangle-network/agent-eval": "0.135.1",
+    "@tangle-network/agent-integrations": ">=0.44.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250620.0",
+    "@tangle-network/agent-eval": "0.135.1",
+    "@tangle-network/agent-integrations": "^0.44.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.6.0",
+    "better-sqlite3": "^12.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "wrangler": "^4.0.0"
+  }
+}

package/template-chat/_tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "types": ["@cloudflare/workers-types/2023-07-01", "node"]
+  },
+  "include": ["agent.config.ts", "declarations.d.ts", "src", "tests", "vitest.config.ts"]
+}

package/template-chat/_wrangler.toml

@@ -0,0 +1,38 @@
+name = "__PACKAGE_NAME__"
+main = "src/worker.ts"
+compatibility_date = "2025-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+# The dev chat page. Assets are served before the worker; /api/* falls
+# through to src/worker.ts.
+[assets]
+directory = "public"
+
+# D1 holds everything durable: auth, threads/messages, the turn buffer.
+# Setup: `wrangler d1 create __PACKAGE_NAME__`, paste the database_id, then
+# `pnpm db:migrate:local` (dev) / `pnpm db:migrate` (production).
+[[d1_databases]]
+binding = "DB"
+database_name = "__PACKAGE_NAME__"
+database_id = "REPLACE_WITH_D1_DATABASE_ID"
+migrations_dir = "migrations"
+
+# R2 is OFF by default — uncomment (and the ARTIFACTS binding in src/env.ts)
+# only when the product needs artifact/object storage.
+# [[r2_buckets]]
+# binding = "ARTIFACTS"
+# bucket_name = "__PACKAGE_NAME__-artifacts"
+
+# prompts/system.md is imported as a Text module (see declarations.d.ts;
+# vitest mirrors this via the plugin in vitest.config.ts).
+[[rules]]
+type = "Text"
+globs = ["**/*.md"]
+fallthrough = true
+
+# Secrets live in .dev.vars locally and `wrangler secret put` in production:
+# BETTER_AUTH_SECRET, TANGLE_API_KEY, SANDBOX_API_KEY, SANDBOX_GATEWAY_URL.
+# See .dev.vars.example for the full list.
+[vars]
+BETTER_AUTH_URL = "http://localhost:8787"
+# MODEL_NAME = "REPLACE_WITH_MODEL"   # overrides config.model.default

package/template-chat/agent.config.ts

@@ -0,0 +1,73 @@
+/**
+ * agent.config.ts — the DATA surface of this chat product.
+ *
+ * This is the ONE file (plus `prompts/system.md`) you fill to define who the
+ * agent is and how its turns execute. It is plain data consumed by
+ * `@tangle-network/agent-app`'s modules through typed seams — NOT behavior.
+ * Control flow lives in `src/` (the assembled chat vertical). See CUSTOMIZE.md
+ * for the ordered fill-checklist and AGENTS.md for the layering contract.
+ *
+ * Every field below is stubbed with a placeholder. Replace the placeholders;
+ * keep the shape. `pnpm typecheck` proves the shape; `pnpm test` proves the
+ * wiring end to end (fake sandbox producer → turn → persisted transcript).
+ */
+
+import type { Harness } from '@tangle-network/agent-app/harness'
+// Imported as a Text module: wrangler's `[[rules]]` and the vitest plugin in
+// `vitest.config.ts` both load `.md` files as strings (see declarations.d.ts).
+import systemPrompt from './prompts/system.md'
+
+export const config = {
+  /** Product/agent name — cookie prefix, sandbox box names, email subjects. */
+  name: '__PROJECT_NAME__',
+
+  /**
+   * The system prompt, verbatim from `prompts/system.md`. State intents and
+   * hard rules, never implementations — the executing agent chooses its own
+   * tools at execution time (see AGENTS.md "prompts state intents").
+   */
+  systemPrompt,
+
+  model: {
+    /**
+     * Model used when the client doesn't pick one and the `MODEL_NAME` env
+     * var is unset. Any model your Tangle Router key can reach.
+     */
+    default: 'REPLACE_WITH_MODEL',
+    /**
+     * Models to try, in order, when the chosen model's upstream is DEAD
+     * (quota wall, 502, provider outage). Failover is reactive — zero cost
+     * until the preferred model actually fails — and every fallback is
+     * surfaced: the persisted row and billing receipt name the model that
+     * actually served, and the transcript gets a visible notice. Keep this
+     * list cross-provider (an outage usually takes a whole provider down)
+     * and review it with your default: a stale ladder degrades to today's
+     * behavior (the turn fails), never to a silent wrong-model answer.
+     */
+    fallbacks: ['gemini-2.5-flash-lite', 'gpt-5-mini'],
+    /** Default reasoning effort for turns that don't specify one. */
+    effort: 'auto',
+  },
+
+  /**
+   * The agent harness the sandbox runs (`opencode`, `claude-code`, `codex`,
+   * …). Vendor-locked harnesses reject foreign-provider models — the sandbox
+   * lane enforces that pairing server-side.
+   */
+  harness: 'opencode',
+
+  /**
+   * Which sidecar ask kinds this app renders as cards. Anything the agent
+   * asks outside this set is auto-declined so a turn never hangs waiting on
+   * a card no client will show.
+   */
+  interactions: { question: true, plan: true },
+} as const satisfies {
+  name: string
+  systemPrompt: string
+  model: { default: string; fallbacks: readonly string[]; effort: 'auto' | 'low' | 'medium' | 'high' }
+  harness: Harness
+  interactions: { question?: boolean; permission?: boolean; plan?: boolean }
+}
+
+export type Config = typeof config

package/template-chat/declarations.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Text-module declarations. `prompts/system.md` is imported as a plain string
+ * by `agent.config.ts`; wrangler loads it via the `[[rules]]` Text rule in
+ * wrangler.toml and vitest via the inline plugin in vitest.config.ts.
+ */
+declare module '*.md' {
+  const text: string
+  export default text
+}

package/template-chat/migrations/0001_init.sql

@@ -0,0 +1,109 @@
+-- 0001_init.sql — the complete schema for the assembled chat vertical.
+-- Apply with: pnpm db:migrate:local (dev) / pnpm db:migrate (production D1).
+--
+-- Three blocks, each mirroring a factory the app composes. The e2e test in
+-- tests/ executes THIS file against a real SQLite database and then drives
+-- sign-up, thread CRUD, and a full streamed turn through it — if any block
+-- drifts from the factory that owns it, the test fails before you ship.
+
+-- ── better-auth (src/db/schema.ts users/sessions/accounts/verifications) ────
+
+CREATE TABLE IF NOT EXISTS users (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT NOT NULL UNIQUE,
+  email_verified INTEGER NOT NULL,
+  image TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  expires_at INTEGER NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  ip_address TEXT,
+  user_agent TEXT,
+  user_id TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS accounts (
+  id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL,
+  provider_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  access_token TEXT,
+  refresh_token TEXT,
+  id_token TEXT,
+  access_token_expires_at INTEGER,
+  refresh_token_expires_at INTEGER,
+  scope TEXT,
+  password TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS verifications (
+  id TEXT PRIMARY KEY,
+  identifier TEXT NOT NULL,
+  value TEXT NOT NULL,
+  expires_at INTEGER NOT NULL,
+  created_at INTEGER,
+  updated_at INTEGER
+);
+
+-- ── chat threads/messages (createChatTables() in src/db/schema.ts) ──────────
+-- workspace_id is a plain column: this template ships single-user workspaces
+-- (workspace id = user id). Moving to real teams later adds the FK via
+-- createChatTables({ workspaceTable }).
+
+CREATE TABLE IF NOT EXISTS thread (
+  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  workspace_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  category TEXT,
+  is_pinned INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+CREATE INDEX IF NOT EXISTS idx_thread_workspace ON thread (workspace_id);
+CREATE INDEX IF NOT EXISTS idx_thread_workspace_updated ON thread (workspace_id, updated_at);
+
+CREATE TABLE IF NOT EXISTS message (
+  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  thread_id TEXT NOT NULL REFERENCES thread(id) ON DELETE CASCADE,
+  role TEXT NOT NULL,
+  content TEXT NOT NULL,
+  parts TEXT DEFAULT '[]',
+  tool_name TEXT,
+  model TEXT,
+  input_tokens INTEGER,
+  output_tokens INTEGER,
+  reasoning_tokens INTEGER,
+  cache_read_tokens INTEGER,
+  cache_write_tokens INTEGER,
+  cost_usd REAL,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+CREATE INDEX IF NOT EXISTS idx_message_thread ON message (thread_id);
+CREATE INDEX IF NOT EXISTS idx_message_thread_created ON message (thread_id, created_at);
+
+-- ── turn buffer (TURN_EVENTS_MIGRATION_SQL from @tangle-network/agent-app/stream)
+-- Byte-for-byte the constant the D1 turn-event store expects; the e2e test
+-- asserts this block matches the exported SQL so it cannot drift silently.
+
+CREATE TABLE IF NOT EXISTS turn_events (
+  turnId TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  event TEXT NOT NULL,
+  PRIMARY KEY (turnId, seq)
+);
+CREATE TABLE IF NOT EXISTS turn_status (
+  turnId TEXT PRIMARY KEY,
+  status TEXT NOT NULL,
+  scopeId TEXT,
+  updatedAt TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_turn_status_scope ON turn_status (scopeId, status);

package/template-chat/prompts/system.md

@@ -0,0 +1,11 @@
+# System prompt — replace this file with the real persona
+
+You are the __PROJECT_NAME__ assistant.
+Rewrite this paragraph as the real one-paragraph role + voice + remit: whose job this agent does, in whose voice, under what hard rules.
+It is the spine of every turn.
+
+Hard rules:
+
+- Never fabricate a figure (price, identifier, clause, date). Cite a real record or say NOT ON FILE.
+- Route every regulated or client-facing action to a named human for approval; propose, don't execute.
+- State what you did and what evidence backs it. No filler.