@tangle-network/create-agent-app 0.46.40 → 0.46.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/create-agent-app",
-  "version": "0.46.40",
+  "version": "0.46.42",
   "description": "Create a tested Tangle agent application with either a tool loop or a complete chat interface.",
   "keywords": [
     "tangle",

package/template/_package.json

@@ -24,15 +24,15 @@
     "@tangle-network/agent-eval": "0.172.1",
     "@tangle-network/agent-integrations": ">=0.53.55 <0.54.0",
     "@tangle-network/agent-interface": "2.2.0",
-    "@tangle-network/agent-runtime": "0.188.1"
+    "@tangle-network/agent-runtime": "0.189.0"
   },
   "devDependencies": {
     "@tangle-network/agent-eval": "0.172.1",
     "@tangle-network/agent-integrations": "0.53.55",
     "@tangle-network/agent-interface": "2.2.0",
     "@tangle-network/agent-knowledge": "13.0.0",
-    "@tangle-network/agent-runtime": "0.188.1",
-    "@tangle-network/sandbox": "0.36.3",
+    "@tangle-network/agent-runtime": "0.189.0",
+    "@tangle-network/sandbox": "0.36.4",
     "@types/node": "^22.20.1",
     "typescript": "^7.0.2",
     "viem": "^2.0.0",

package/template-chat/CUSTOMIZE.md

@@ -46,6 +46,8 @@ Discovery: **Where does this app live and what may it spend?**
 - [ ] `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.
+- [ ] Existing app only: add `sandbox_prewarm_claims` in a new migration.
+      Do not edit an applied `0001_init.sql`; Wrangler will not run it again.
 - [ ] R2 stays commented out unless the product stores artifacts.
 
 ## ④ Prove the loop — `pnpm dev`

package/template-chat/_package.json

@@ -21,8 +21,8 @@
   "dependencies": {
     "@tangle-network/agent-app": "__AGENT_APP_VERSION__",
     "@tangle-network/agent-interface": "2.2.0",
-    "@tangle-network/agent-runtime": "0.188.1",
-    "@tangle-network/sandbox": "0.36.3",
+    "@tangle-network/agent-runtime": "0.189.0",
+    "@tangle-network/sandbox": "0.36.4",
     "better-auth": "^1.7.2",
     "drizzle-orm": "^0.45.2",
     "viem": "^2.0.0"

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

@@ -96,6 +96,16 @@ CREATE TABLE IF NOT EXISTS message (
 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);
 
+-- ── sandbox provisioning claim (PREWARM_CLAIM_TABLE_DDL from
+-- @tangle-network/agent-app/sandbox) ──────────────────────────────────────
+-- A positive value is a live fenced lease. A negative value is the retained
+-- release marker that prevents an expired owner from releasing its successor.
+
+CREATE TABLE IF NOT EXISTS sandbox_prewarm_claims (
+  key TEXT PRIMARY KEY,
+  expires_at INTEGER NOT NULL
+);
+
 -- ── 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.

package/template-chat/src/sandbox.ts

@@ -26,7 +26,10 @@ import {
 } from '@tangle-network/agent-app/chat-routes'
 import type { SidecarInteractionsConnection } from '@tangle-network/agent-app/interactions'
 import {
+  createD1PrewarmClaimStore,
   ensureWorkspaceSandbox,
+  peekWorkspaceSandbox,
+  runForegroundSandboxSingleFlight,
   streamSandboxPrompt,
   type SandboxRuntimeConfig,
 } from '@tangle-network/agent-app/sandbox'
@@ -72,6 +75,26 @@ export function createSandboxShell(env: AppEnv): SandboxRuntimeConfig {
   }
 }
 
+/**
+ * Provision once across Worker isolates. A turn, upload, and interaction can
+ * arrive together for one new workspace. They must adopt one box, not create
+ * three boxes with the same name.
+ */
+async function ensureForegroundWorkspaceSandbox(
+  env: AppEnv,
+  shell: SandboxRuntimeConfig,
+  scope: { workspaceId: string; userId: string },
+) {
+  return runForegroundSandboxSingleFlight({
+    claim: createD1PrewarmClaimStore(env.DB),
+    workspaceId: scope.workspaceId,
+    harness: config.harness,
+    provision: () => ensureWorkspaceSandbox(shell, { ...scope, harness: config.harness }),
+    peek: () => peekWorkspaceSandbox(shell, scope),
+    adopt: ({ box }) => box,
+  })
+}
+
 /**
  * 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
@@ -85,10 +108,9 @@ export function createSandboxProduce(env: AppEnv) {
     prompt,
     executionId,
   }: ChatTurnProduceArgs<void>): Promise<ChatTurnRouteProducer> => {
-    const box = await ensureWorkspaceSandbox(shell, {
+    const box = await ensureForegroundWorkspaceSandbox(env, shell, {
       workspaceId: identity.tenantId,
       userId: identity.userId,
-      harness: config.harness,
     })
     const model = body.model ?? env.MODEL_NAME ?? config.model.default
     return createSandboxChatProducer({
@@ -133,7 +155,7 @@ export async function resolveUploadSink(
 ): 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 })
+  const box = await ensureForegroundWorkspaceSandbox(env, shell, scope)
   return box.fs
 }
 
@@ -145,10 +167,9 @@ export async function resolveSidecarConnection(
 ): 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, {
+  const box = await ensureForegroundWorkspaceSandbox(env, shell, {
     workspaceId: scope.workspaceId,
     userId: scope.userId,
-    harness: config.harness,
   })
   const connection = box.connection
   if (!connection?.runtimeUrl) return null

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

@@ -29,6 +29,7 @@ import {
   type ChatTurnRouteProducer,
 } from '@tangle-network/agent-app/chat-routes'
 import type { ChatDatabase } from '@tangle-network/agent-app/chat-store'
+import { PREWARM_CLAIM_TABLE_DDL } from '@tangle-network/agent-app/sandbox'
 import {
   createMemoryTurnEventStore,
   TURN_EVENTS_MIGRATION_SQL,
@@ -274,6 +275,11 @@ describe('e2e: fake sandbox producer → streamed turn → persisted transcript'
     expect(normalize(readFileSync(MIGRATION, 'utf8'))).toContain(normalize(TURN_EVENTS_MIGRATION_SQL))
   })
 
+  it('the migration carries the fenced sandbox claim table, verbatim', () => {
+    const normalize = (sql: string) => sql.replace(/\s+/g, ' ').replace(/;$/, '').trim()
+    expect(normalize(readFileSync(MIGRATION, 'utf8'))).toContain(normalize(PREWARM_CLAIM_TABLE_DDL))
+  })
+
   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/tests/sandbox-fence.test.ts

@@ -0,0 +1,76 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const sandboxMocks = vi.hoisted(() => ({
+  createClaimStore: vi.fn(),
+  ensureWorkspace: vi.fn(),
+  peekWorkspace: vi.fn(),
+}))
+
+vi.mock('@tangle-network/agent-app/sandbox', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@tangle-network/agent-app/sandbox')>()
+  return {
+    ...actual,
+    createD1PrewarmClaimStore: sandboxMocks.createClaimStore,
+    ensureWorkspaceSandbox: sandboxMocks.ensureWorkspace,
+    peekWorkspaceSandbox: sandboxMocks.peekWorkspace,
+  }
+})
+
+import { createSandboxProduce } from '../src/sandbox'
+import type { AppEnv } from '../src/env'
+
+describe('sandbox foreground provisioning', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('runs createSandboxProduce through the shared fenced claim', async () => {
+    const lease = { key: 'workspace-1::opencode', expiresAt: 123 }
+    const claim = {
+      acquire: vi.fn(async () => true),
+      release: vi.fn(async () => undefined),
+      isHeld: vi.fn(async () => false),
+      inspect: vi.fn(async () => ({ status: 'absent' as const })),
+      acquireLease: vi.fn(async () => lease),
+      releaseLease: vi.fn(async () => undefined),
+    }
+    const box = { id: 'box-1' }
+    const db = {} as D1Database
+    const env: AppEnv = {
+      DB: db,
+      BETTER_AUTH_URL: 'http://localhost:8787',
+      BETTER_AUTH_SECRET: 'test-secret',
+      SANDBOX_API_KEY: 'sandbox-key',
+      SANDBOX_GATEWAY_URL: 'https://sandbox.example.test',
+    }
+    sandboxMocks.createClaimStore.mockReturnValue(claim)
+    sandboxMocks.ensureWorkspace.mockResolvedValue(box)
+
+    const producer = await createSandboxProduce(env)({
+      request: new Request('http://localhost:8787/api/chat', { method: 'POST' }),
+      body: { threadId: 'thread-1', content: 'Hello' },
+      identity: {
+        tenantId: 'workspace-1',
+        sessionId: 'thread-1',
+        userId: 'user-1',
+        turnIndex: 0,
+      },
+      context: undefined,
+      prompt: 'Hello',
+      executionId: 'execution-1',
+      turnStreamId: 'turn-1',
+      priorMessages: [],
+      userMessageId: 'message-1',
+    })
+
+    expect(producer.stream).toBeDefined()
+    expect(sandboxMocks.createClaimStore).toHaveBeenCalledWith(db)
+    expect(claim.acquireLease).toHaveBeenCalledWith('workspace-1::opencode', 180)
+    expect(sandboxMocks.ensureWorkspace).toHaveBeenCalledWith(
+      expect.objectContaining({ name: expect.any(Function) }),
+      { workspaceId: 'workspace-1', userId: 'user-1', harness: 'opencode' },
+    )
+    expect(claim.releaseLease).toHaveBeenCalledWith(lease)
+    expect(sandboxMocks.peekWorkspace).not.toHaveBeenCalled()
+  })
+})