@tangle-network/create-agent-app 0.44.36

package/template-chat/src/sandbox.ts

@@ -0,0 +1,159 @@
+/**
+ * src/sandbox.ts — the config-driven sandbox lane. CODE, not data.
+ *
+ * Everything agent-shaped runs in a Tangle sandbox (a full agent harness:
+ * skills, tools, bash, MCP) reached through `@tangle-network/agent-app`'s
+ * sandbox helpers. This file turns `agent.config.ts` + env into the three
+ * seams the chat vertical needs:
+ *
+ *   - `createSandboxProduce`   — the turn producer (`createChatTurnRoutes`'s
+ *     `produce` seam): resolve the workspace box, stream the prompt, bridge
+ *     raw sidecar events through `createSandboxChatProducer`.
+ *   - `resolveUploadSink`      — where >inline-cap uploads land (`box.fs`).
+ *   - `resolveSidecarConnection` — where interaction answers go.
+ *
+ * No mock fallback: without SANDBOX_API_KEY / SANDBOX_GATEWAY_URL the turn
+ * fails loud with a clear error instead of pretending to answer.
+ */
+
+import { config } from '../agent.config'
+import {
+  createSandboxChatProducer,
+  normalizeChatPromptForSandbox,
+  type ChatTurnProduceArgs,
+  type ChatTurnRouteProducer,
+  type SandboxUploadSink,
+} from '@tangle-network/agent-app/chat-routes'
+import type { SidecarInteractionsConnection } from '@tangle-network/agent-app/interactions'
+import {
+  ensureWorkspaceSandbox,
+  streamSandboxPrompt,
+  type SandboxRuntimeConfig,
+} from '@tangle-network/agent-app/sandbox'
+import type { AppEnv } from './env'
+
+/** Lowercased, non-alphanumerics collapsed: box names + projectId. */
+export const appSlug = config.name
+  .toLowerCase()
+  .replace(/[^a-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '')
+
+/**
+ * The sandbox shell: how boxes are named, credentialed, and provisioned for
+ * this product. Extend here when you add per-workspace env, file mounts, or
+ * per-user key minting (see `resolveSandboxClientCredentials` in
+ * `@tangle-network/agent-app/sandbox` for the credential-policy helper).
+ */
+export function createSandboxShell(env: AppEnv): SandboxRuntimeConfig {
+  return {
+    credentials: () => {
+      const apiKey = env.SANDBOX_API_KEY?.trim()
+      const baseUrl = env.SANDBOX_GATEWAY_URL?.trim()
+      if (!apiKey || !baseUrl) return null
+      return { apiKey, baseUrl }
+    },
+    name: (workspaceId) => `${appSlug}-${workspaceId}`.slice(0, 63),
+    metadata: (harness) => ({ app: appSlug, harness }),
+    connectedIntegrationIds: async () => [],
+    env: async () => ({}),
+    files: async () => [],
+    secrets: async () => [],
+    profile: ({ systemPrompt, extraMcp }) => ({
+      name: appSlug,
+      prompt: { systemPrompt: systemPrompt ?? config.systemPrompt },
+      ...(extraMcp && Object.keys(extraMcp).length > 0 ? { mcp: extraMcp } : {}),
+    }),
+    provider: {
+      ...(env.TANGLE_API_KEY ? { apiKey: env.TANGLE_API_KEY } : {}),
+      ...(env.TANGLE_ROUTER_URL ? { routerBaseUrl: env.TANGLE_ROUTER_URL } : {}),
+      ...(env.MODEL_NAME ? { modelName: env.MODEL_NAME } : {}),
+      defaultModel: config.model.default,
+    },
+  }
+}
+
+/**
+ * The `produce` seam for `createChatTurnRoutes`: one call per turn. The
+ * chat thread id doubles as the agent session id, so follow-up turns land in
+ * the same sidecar session and keep its context.
+ */
+export function createSandboxProduce(env: AppEnv) {
+  const shell = createSandboxShell(env)
+  return async ({
+    body,
+    identity,
+    prompt,
+    executionId,
+  }: ChatTurnProduceArgs<void>): Promise<ChatTurnRouteProducer> => {
+    const box = await ensureWorkspaceSandbox(shell, {
+      workspaceId: identity.tenantId,
+      userId: identity.userId,
+      harness: config.harness,
+    })
+    const model = body.model ?? env.MODEL_NAME ?? config.model.default
+    return createSandboxChatProducer({
+      model,
+      // Reactive model failover, ON by default: when `model`'s upstream is
+      // dead (quota wall, 502, provider outage), the turn moves to the next
+      // model in `config.model.fallbacks` BEFORE any client-visible byte.
+      // Never silent: the persisted row and billing receipt name the model
+      // that actually served, and the transcript gets a visible notice.
+      // Opt out with `modelFailover: false` (or empty `fallbacks`).
+      fallbackModels: config.model.fallbacks,
+      openEvents: ({ model: attemptModel, attempt }) =>
+        streamSandboxPrompt(shell, box, normalizeChatPromptForSandbox(prompt), {
+          sessionId: identity.sessionId,
+          // A failover attempt is a NEW dispatch, not a reconnect to the dead
+          // one — it needs its own execution identity or the platform would
+          // resume the failed execution instead of starting a fresh run.
+          executionId: attempt === 1 ? executionId : `${executionId}-f${attempt}`,
+          model: attemptModel,
+          effort: body.effort ?? config.model.effort,
+          harness: config.harness,
+          systemPrompt: config.systemPrompt,
+          // Durable by default: the run keeps executing server-side if the operator
+          // refreshes, closes the tab, or the Worker restarts mid-turn. On reopen
+          // the client re-attaches via GET /api/chat/running → /api/chat/replay, so
+          // nothing is lost. Drop this only for a run that should stop when the tab
+          // closes (e.g. a throwaway preview).
+          detach: true,
+          interactions: config.interactions,
+        }),
+    })
+  }
+}
+
+/** Where large uploads land: the workspace box's filesystem. Returns null when
+ *  no sandbox is configured — the upload route then accepts inline files only
+ *  and rejects oversized ones with an explicit 413. */
+export async function resolveUploadSink(
+  env: AppEnv,
+  scope: { workspaceId: string; userId: string },
+): Promise<SandboxUploadSink | null> {
+  if (!env.SANDBOX_API_KEY?.trim() || !env.SANDBOX_GATEWAY_URL?.trim()) return null
+  const shell = createSandboxShell(env)
+  const box = await ensureWorkspaceSandbox(shell, { ...scope, harness: config.harness })
+  return box.fs
+}
+
+/** The sidecar connection interaction answers travel over. `sessionId` is the
+ *  thread id — the same session the turn streams under. */
+export async function resolveSidecarConnection(
+  env: AppEnv,
+  scope: { workspaceId: string; userId: string; threadId: string },
+): Promise<SidecarInteractionsConnection | null> {
+  if (!env.SANDBOX_API_KEY?.trim() || !env.SANDBOX_GATEWAY_URL?.trim()) return null
+  const shell = createSandboxShell(env)
+  const box = await ensureWorkspaceSandbox(shell, {
+    workspaceId: scope.workspaceId,
+    userId: scope.userId,
+    harness: config.harness,
+  })
+  const connection = box.connection
+  if (!connection?.runtimeUrl) return null
+  return {
+    runtimeUrl: connection.runtimeUrl,
+    ...(connection.authToken ? { authToken: connection.authToken } : {}),
+    sessionId: scope.threadId,
+  }
+}

package/template-chat/src/worker.ts

@@ -0,0 +1,58 @@
+/**
+ * src/worker.ts — the HTTP surface. Routing only; every handler is a factory
+ * product from `src/chat.ts`. Static assets (the dev chat page in `public/`)
+ * are served by the Workers assets pipeline before this fetch handler runs.
+ *
+ * Route map:
+ *   ALL  /api/auth/*                    better-auth (sign-up/sign-in/session)
+ *   POST /api/threads                   create a thread
+ *   GET  /api/threads                   list threads
+ *   GET  /api/threads/:id/messages      typed transcript (parts + usage)
+ *   POST /api/chat                      run one turn (NDJSON stream)
+ *   GET  /api/chat/replay/:turnId       replay a buffered turn (?fromSeq=)
+ *   GET  /api/chat/running              live turn ids on a thread (?threadId=)
+ *   POST /api/chat/upload               multipart upload → prompt parts
+ *   GET  /api/chat/interactions         outstanding agent asks (?threadId=)
+ *   POST /api/chat/interactions         answer an ask
+ */
+
+import { buildChatApp } from './chat'
+import type { AppEnv } from './env'
+
+export default {
+  async fetch(request: Request, env: AppEnv, ctx: ExecutionContext): Promise<Response> {
+    // Per-request assembly is the standard Workers pattern: env only exists
+    // inside fetch, and the factories are cheap closures over it.
+    const app = buildChatApp(env)
+    const url = new URL(request.url)
+    const { pathname } = url
+    const method = request.method
+
+    if (pathname.startsWith('/api/auth/')) return app.auth.auth.handler(request)
+
+    if (pathname === '/api/chat' && method === 'POST') {
+      // Pass waitUntil so the turn keeps running (and buffering for replay)
+      // after a client disconnect.
+      return app.routes.turn(request, ctx)
+    }
+    const replay = pathname.match(/^\/api\/chat\/replay\/([^/]+)$/)
+    if (replay && method === 'GET') return app.routes.replay(request, { turnId: replay[1]! })
+    // Reconnect discovery: which turns are still live on a thread, so a page
+    // reloaded mid-turn re-attaches via /replay instead of losing the run.
+    if (pathname === '/api/chat/running' && method === 'GET') return app.routes.running(request)
+    if (pathname === '/api/chat/upload' && method === 'POST') return app.upload(request)
+    if (pathname === '/api/chat/interactions' && app.routes.interactions) {
+      if (method === 'GET') return app.routes.interactions.list(request)
+      if (method === 'POST') return app.routes.interactions.answer(request)
+    }
+
+    if (pathname === '/api/threads' && method === 'POST') return app.routes.createThread(request)
+    if (pathname === '/api/threads' && method === 'GET') return app.routes.listThreads(request)
+    const transcript = pathname.match(/^\/api\/threads\/([^/]+)\/messages$/)
+    if (transcript && method === 'GET') {
+      return app.routes.threadMessages(request, { threadId: transcript[1]! })
+    }
+
+    return Response.json({ error: 'Not found' }, { status: 404 })
+  },
+} satisfies ExportedHandler<AppEnv>

package/template-chat/tests/chat-turn.e2e.test.ts

@@ -0,0 +1,277 @@
+/**
+ * The e2e gate this app ships with: the REAL assembly (`buildChatApp` — auth,
+ * store, turn routes, upload, replay) driven end to end against the REAL
+ * migration, with exactly one fake at the outermost seam — the sandbox event
+ * feed. `createSandboxChatProducer` (the real bridge) consumes canonical
+ * sidecar events a live box would emit, so everything below the fake is
+ * production code:
+ *
+ *   sign-up (better-auth drizzle adapter over the migrated tables)
+ *   → create thread → upload a file (inline `data:` part)
+ *   → POST /api/chat with content + parts → consume the NDJSON stream
+ *   → user + assistant rows persisted with typed parts + usage receipt
+ *   → replay the buffered turn after the live stream is gone.
+ *
+ * If this file fails after an edit, the app has drifted from the framework
+ * contract (or the migration from the schema). Fix the drift, not the test.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { describe, expect, it } from 'vitest'
+
+import {
+  createSandboxChatProducer,
+  normalizeChatPromptForSandbox,
+  type ChatTurnRouteProducer,
+} from '@tangle-network/agent-app/chat-routes'
+import type { ChatDatabase } from '@tangle-network/agent-app/chat-store'
+import {
+  createMemoryTurnEventStore,
+  TURN_EVENTS_MIGRATION_SQL,
+} from '@tangle-network/agent-app/stream'
+
+import { config } from '../agent.config'
+import { buildChatApp, type ChatApp } from '../src/chat'
+import type { AppEnv } from '../src/env'
+
+const BASE = 'http://localhost:8787'
+const MODEL = 'test/model-1'
+
+// ── fixtures ────────────────────────────────────────────────────────────────
+
+const MIGRATION = join(dirname(fileURLToPath(import.meta.url)), '..', 'migrations', '0001_init.sql')
+
+/** The real migration, executed against a real SQLite database. Every query
+ *  the test makes afterwards runs over THESE tables — schema drift between
+ *  `migrations/` and `src/db/schema.ts` fails here, not in production. */
+function openMigratedDb(): ChatDatabase {
+  const sqlite = new Database(':memory:')
+  sqlite.pragma('foreign_keys = ON')
+  sqlite.exec(readFileSync(MIGRATION, 'utf8'))
+  // better-sqlite3's sync drizzle handle narrows the driver generic; the store
+  // treats sync and async drivers identically (builders are awaited).
+  return drizzle(sqlite) as unknown as ChatDatabase
+}
+
+/** Raw sidecar events, exactly as `streamSandboxPrompt` would yield them from
+ *  a live box: reasoning + text deltas, a tool round-trip, the usage receipt,
+ *  and the final-text result. */
+const RAW_TURN_EVENTS: Array<Record<string, unknown>> = [
+  { type: 'message.part.updated', data: { part: { type: 'reasoning', id: 'r1', text: 'checking the records' }, delta: 'checking the records' } },
+  { type: 'message.part.updated', data: { part: { type: 'text', id: 't1', text: 'Filed ' }, delta: 'Filed ' } },
+  { type: 'message.part.updated', data: { part: { type: 'tool', id: 'call-1', tool: 'record_search', state: { status: 'running', input: { query: 'lease' } } } } },
+  { type: 'message.part.updated', data: { part: { type: 'tool', id: 'call-1', tool: 'record_search', state: { status: 'completed', input: { query: 'lease' }, output: { hits: 2 } } } } },
+  { type: 'message.part.updated', data: { part: { type: 'text', id: 't1', text: 'Filed the summary.' }, delta: 'the summary.' } },
+  { type: 'message.part.updated', data: { part: { type: 'step-finish', reason: 'stop', tokens: { input: 40, output: 20, reasoning: 5, cache: { read: 10, write: 2 } }, cost: 0.0123 } } },
+  { type: 'result', data: { finalText: 'Filed the summary.' } },
+]
+
+async function* feed(events: Array<Record<string, unknown>>): AsyncGenerator<unknown> {
+  for (const event of events) yield event
+}
+
+const env: AppEnv = {
+  // The DB binding is unused when the test injects its own drizzle handle.
+  DB: null as unknown as AppEnv['DB'],
+  BETTER_AUTH_URL: BASE,
+  BETTER_AUTH_SECRET: 'e2e-test-secret-not-for-production',
+}
+
+interface Harness {
+  app: ChatApp
+  cookie: string
+  settle(): Promise<unknown>
+}
+
+async function createHarness(
+  produce: () => ChatTurnRouteProducer = () =>
+    createSandboxChatProducer({ events: feed(RAW_TURN_EVENTS), model: MODEL }),
+): Promise<Harness> {
+  const app = buildChatApp(env, {
+    db: openMigratedDb(),
+    turnStore: createMemoryTurnEventStore(),
+    produce,
+    uploadSink: async () => null, // inline uploads only; no box in tests
+  })
+  // Real sign-up through better-auth; the returned cookie is what a browser
+  // would replay on every API call.
+  const res = await app.auth.auth.handler(
+    new Request(`${BASE}/api/auth/sign-up/email`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', origin: BASE },
+      body: JSON.stringify({ email: 'e2e@example.com', password: 'correct-horse-battery', name: 'e2e' }),
+    }),
+  )
+  expect(res.status).toBe(200)
+  const cookie = res.headers
+    .getSetCookie()
+    .map((c) => c.split(';')[0]!)
+    .join('; ')
+
+  const pending: Promise<unknown>[] = []
+  const originalTurn = app.routes.turn
+  app.routes.turn = (request) =>
+    originalTurn(request, { waitUntil: (p) => void pending.push(p) })
+  return { app, cookie, settle: () => Promise.all(pending) }
+}
+
+function post(path: string, cookie: string, body: unknown): Request {
+  return new Request(`${BASE}${path}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', cookie },
+    body: JSON.stringify(body),
+  })
+}
+
+async function readLines(res: Response): Promise<Array<Record<string, unknown>>> {
+  const text = await new Response(res.body).text()
+  return text
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as Record<string, unknown>)
+}
+
+/** Flatten the NDJSON line vocabulary (`{kind:'event', event}` wrappers) the
+ *  same way web-react's `dispatchChatStreamLine` does. */
+function eventsOf(lines: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+  return lines.map((l) => (l.kind === 'event' ? (l.event as Record<string, unknown>) : l))
+}
+
+// ── the gate ────────────────────────────────────────────────────────────────
+
+describe('e2e: fake sandbox producer → streamed turn → persisted transcript', () => {
+  it('normalizes path-backed generic files for the sandbox prompt API', () => {
+    expect(
+      normalizeChatPromptForSandbox([
+        { type: 'text', text: 'Read this' },
+        {
+          type: 'file',
+          filename: 'lease terms.pdf',
+          mediaType: 'application/pdf',
+          path: '/workspace/uploads/lease terms.pdf',
+        },
+      ]),
+    ).toEqual([
+      { type: 'text', text: 'Read this' },
+      {
+        type: 'file',
+        filename: 'lease terms.pdf',
+        mediaType: 'application/pdf',
+        url: 'file:///workspace/uploads/lease%20terms.pdf',
+      },
+    ])
+  })
+
+  it('runs the full multimodal vertical: upload, turn, stream, rows, replay', async () => {
+    const { app, cookie, settle } = await createHarness()
+
+    // Thread
+    const threadRes = await app.routes.createThread(
+      post('/api/threads', cookie, { firstMessage: 'File my lease summary' }),
+    )
+    expect(threadRes.status).toBe(200)
+    const { thread } = (await threadRes.json()) as { thread: { id: string } }
+
+    // Upload → inline `data:` part (≤700 KiB stays in the turn body)
+    const form = new FormData()
+    form.append('files', new File(['%PDF-1.4 fake'], 'lease.pdf', { type: 'application/pdf' }))
+    const uploadRes = await app.upload(
+      new Request(`${BASE}/api/chat/upload`, { method: 'POST', headers: { cookie }, body: form }),
+    )
+    expect(uploadRes.status).toBe(200)
+    const { files } = (await uploadRes.json()) as {
+      files: Array<{ inline: boolean; part: Record<string, unknown> }>
+    }
+    expect(files[0]!.inline).toBe(true)
+    expect(String(files[0]!.part.url)).toMatch(/^data:application\/pdf;base64,/)
+
+    // Turn: content + the uploaded part, streamed as NDJSON
+    const turnRes = await app.routes.turn(
+      post('/api/chat', cookie, {
+        threadId: thread.id,
+        content: 'File my lease summary',
+        parts: [files[0]!.part],
+      }),
+    )
+    expect(turnRes.status).toBe(200)
+    const lines = await readLines(turnRes)
+    const events = eventsOf(lines)
+
+    // The stream announced the replay handle first, then the client vocabulary.
+    const turnId = String(lines[0]!.turnId ?? '')
+    expect(lines[0]).toMatchObject({ type: 'turn' })
+    expect(turnId).toBeTruthy()
+    expect(
+      events.filter((e) => e.type === 'text').map((e) => String(e.text)).join(''),
+    ).toBe('Filed the summary.')
+    expect(events.some((e) => e.type === 'reasoning')).toBe(true)
+    const toolCall = events.find((e) => e.type === 'tool_call') as
+      | { call?: { toolName?: string } }
+      | undefined
+    expect(toolCall?.call?.toolName).toBe('record_search')
+    expect(events).toContainEqual(
+      expect.objectContaining({ type: 'usage', usage: { promptTokens: 40, completionTokens: 20 } }),
+    )
+    await settle()
+
+    // A later page load reads back both rows with typed parts + the receipt.
+    const transcriptRes = await app.routes.threadMessages(
+      new Request(`${BASE}/api/threads/${thread.id}/messages`, { headers: { cookie } }),
+      { threadId: thread.id },
+    )
+    const { messages } = (await transcriptRes.json()) as {
+      messages: Array<Record<string, unknown> & { parts?: Array<Record<string, unknown>> }>
+    }
+    expect(messages.map((m) => m.role)).toEqual(['user', 'assistant'])
+
+    const user = messages[0]!
+    expect(user.parts?.some((p) => p.type === 'file' && p.filename === 'lease.pdf')).toBe(true)
+
+    const assistant = messages[1]!
+    expect(assistant.content).toBe('Filed the summary.')
+    expect(assistant.model).toBe(MODEL)
+    expect(assistant.inputTokens).toBe(40)
+    expect(assistant.outputTokens).toBe(20)
+    expect(assistant.reasoningTokens).toBe(5)
+    expect(assistant.costUsd).toBeCloseTo(0.0123)
+    expect(assistant.parts?.some((p) => p.type === 'reasoning')).toBe(true)
+    const tool = assistant.parts?.find((p) => p.type === 'tool')
+    expect(tool).toMatchObject({ tool: 'record_search', state: { status: 'completed' } })
+    expect(assistant.parts?.some((p) => p.type === 'step-finish')).toBe(true)
+
+    // The buffered turn replays in full after the live stream is long gone.
+    const replayRes = await app.routes.replay(
+      new Request(`${BASE}/api/chat/replay/${turnId}?fromSeq=0`, { headers: { cookie } }),
+      { turnId },
+    )
+    const replayEvents = eventsOf(await readLines(replayRes))
+    expect(
+      replayEvents.filter((e) => e.type === 'text').map((e) => String(e.text)).join(''),
+    ).toBe('Filed the summary.')
+    expect(replayEvents.at(-1)).toMatchObject({ type: 'turn_status', status: 'complete' })
+  })
+
+  it('rejects an unauthenticated turn with the guard 401, before any row is written', async () => {
+    const { app, cookie } = await createHarness()
+    const threadRes = await app.routes.createThread(post('/api/threads', cookie, { firstMessage: 'seed' }))
+    const { thread } = (await threadRes.json()) as { thread: { id: string } }
+
+    const res = await app.routes.turn(post('/api/chat', '', { threadId: thread.id, content: 'hi' }))
+    expect(res.status).toBe(401)
+    expect(await app.store.listMessages(thread.id)).toEqual([])
+  })
+
+  it('the migration carries the turn-buffer DDL the /stream store expects, verbatim', () => {
+    const normalize = (sql: string) => sql.replace(/\s+/g, ' ').trim()
+    expect(normalize(readFileSync(MIGRATION, 'utf8'))).toContain(normalize(TURN_EVENTS_MIGRATION_SQL))
+  })
+
+  it('agent.config carries a real system prompt (prompts/system.md is wired)', () => {
+    expect(config.systemPrompt.length).toBeGreaterThan(0)
+    expect(config.name.length).toBeGreaterThan(0)
+  })
+})

package/template-chat/vitest.config.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  plugins: [
+    {
+      // Mirror wrangler's `[[rules]]` Text modules: `.md` imports (the system
+      // prompt) resolve to plain strings under vitest too.
+      name: 'text-markdown',
+      enforce: 'pre',
+      load(id) {
+        if (id.endsWith('.md')) {
+          return `export default ${JSON.stringify(readFileSync(id, 'utf8'))}`
+        }
+        return null
+      },
+    },
+  ],
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+})