@tangle-network/create-agent-app 0.60.159 → 0.60.161

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,47 @@
1
+ import { OPERATOR_API_BASE_PATH, OPERATOR_ROUTES } from '@tangle-network/agent-app/operator'
2
+ import { config } from '../agent.config'
3
+
4
+ /** Core routes come from the shared contract, never a separate path catalog.
5
+ * Optional product storage operations are discovered after authentication.
6
+ */
7
+ export function operatorOpenApi(origin: string, runEnabled = false) {
8
+ const optional = new Set(['workspaces.create', 'journal.list', 'files.list', 'files.read', 'assets.read', 'scorecard.get'])
9
+ const paths: Record<string, Record<string, unknown>> = {}
10
+ for (const route of OPERATOR_ROUTES) {
11
+ if (optional.has(route.id) || (!runEnabled && route.id === 'turns.start')) continue
12
+ const path = OPERATOR_API_BASE_PATH + route.path.replace(/:([A-Za-z]+)/g, '{$1}')
13
+ const parameters: unknown[] = [...route.path.matchAll(/:([A-Za-z]+)/g)].map(match => ({ name: match[1], in: 'path', required: true, schema: { type: 'string' } }))
14
+ if (route.id === 'turns.get') parameters.push({ name: 'wait', in: 'query', schema: { type: 'integer', minimum: 0, maximum: 25, default: 0 } })
15
+ if (route.id === 'threads.list') parameters.push({ name: 'cursor', in: 'query', schema: { type: 'string' } }, { name: 'limit', in: 'query', schema: { type: 'integer', minimum: 1, maximum: 100, default: 25 } })
16
+ const operation = {
17
+ operationId: route.id,
18
+ 'x-required-scopes': route.scopes,
19
+ ...(parameters.length ? { parameters } : {}),
20
+ ...(route.id === 'turns.start' ? { requestBody: { required: true, content: { 'application/json': { schema: {
21
+ type: 'object', additionalProperties: false, required: ['turnId', 'content'], properties: {
22
+ turnId: { type: 'string', format: 'uuid', description: 'Persist before sending; reuse after an ambiguous outcome. Concurrent or interrupted claims can report unknown until the retained transcript establishes an outcome.' },
23
+ content: { type: 'string', minLength: 1, description: 'At most 65536 UTF-8 bytes.' },
24
+ threadId: { type: 'string', maxLength: 256 }, title: { type: 'string', maxLength: 200 }, model: { type: 'string', maxLength: 200 },
25
+ },
26
+ } } } } } : {}),
27
+ responses: {
28
+ [route.id === 'turns.start' ? '202' : '200']: { description: route.id.startsWith('turns.') ? 'A turn record. Inspect state; HTTP success alone does not establish task success.' : 'Authorized response.', content: { 'application/json': { schema: route.id.startsWith('turns.') ? { type: 'object', required: ['turn'], properties: { turn: { $ref: '#/components/schemas/Turn' } } } : { type: 'object' } } } },
29
+ '400': { description: 'Invalid JSON, input, UUID or query.' },
30
+ '401': { description: 'Missing, invalid, revoked or expired local key.' }, '402': { description: 'Capped execution is unsupported on the browser-backed operator lane.' },
31
+ '403': { description: 'Required scopes were not granted.' }, '404': { description: 'Unknown or inaccessible resource.' },
32
+ '409': { description: 'UUID conflicts with a different thread. Inspect the existing work rather than starting another UUID.' },
33
+ '429': { description: 'Per-key request quota. Honor Retry-After.' }, '503': { description: 'Source unavailable, unknown decision state, or bounded adapter capacity exceeded.' },
34
+ },
35
+ }
36
+ paths[path] = { ...paths[path], [route.method.toLowerCase()]: operation }
37
+ }
38
+ return { openapi: '3.1.0', info: { title: `${config.name} operator API`, version: '1.0.0' }, servers: [{ url: origin }],
39
+ security: [{ localKey: [] }], paths,
40
+ components: { securitySchemes: { localKey: { type: 'http', scheme: 'bearer', bearerFormat: 'ak_', description: 'Owner-issued expiring key; no cookie fallback or Platform key support.' } },
41
+ schemas: { Turn: { type: 'object', required: ['workspaceId', 'threadId', 'turnId', 'state', 'reply', 'failure', 'assets', 'files', 'approvals'], properties: {
42
+ workspaceId: { type: 'string' }, threadId: { type: 'string' }, turnId: { type: 'string' },
43
+ state: { type: 'string', enum: ['queued', 'working', 'input-required', 'succeeded', 'failed', 'unknown'] },
44
+ reply: { type: ['object', 'null'] }, failure: { type: ['object', 'null'] }, assets: { type: 'array' }, files: { type: 'array' }, approvals: { type: 'array', description: 'Only the named owner decides; no operator approval mutation endpoint.' },
45
+ } } } },
46
+ }
47
+ }
@@ -0,0 +1,148 @@
1
+ /** Scoped external-agent access to this app's existing personal workspace.
2
+ * Uses the shared operator contract, key store and persisted chat path.
3
+ */
4
+ import { createChatOperatorAdapter, createOperatorApi, OperatorError, type ChatOperatorAdapterOptions } from '@tangle-network/agent-app/operator'
5
+ import { d1ToSqlAdapter, SqlApiKeyStore, verifyApiKeyFromStore, type SqlAdapter } from '@tangle-network/agent-gateway'
6
+ import { config } from '../agent.config'
7
+ import { buildChatApp, type ChatApp } from './chat'
8
+ import type { AppEnv } from './env'
9
+ import { appSlug } from './sandbox'
10
+
11
+ export interface OperatorAppOptions {
12
+ sql?: SqlAdapter
13
+ createTrustedChatApp?: (ownerId: string) => ChatApp
14
+ /** Product-owned safe storage adapters. Never substitute unconfined sandbox reads. */
15
+ files?: ChatOperatorAdapterOptions<Identity>['files']
16
+ assets?: ChatOperatorAdapterOptions<Identity>['assets']
17
+ waitUntil?: (promise: Promise<unknown>) => void
18
+ }
19
+
20
+ export interface Identity { userId: string; spendingLimitCents: number | null }
21
+
22
+ export function buildOperatorApi(env: AppEnv, chat: ChatApp, options: OperatorAppOptions = {}) {
23
+ const sql = options.sql ?? d1ToSqlAdapter(env.DB)
24
+ const keys = new SqlApiKeyStore(sql)
25
+ const trusted = options.createTrustedChatApp ?? ((ownerId: string) => buildChatApp(env, { trustedUserId: ownerId }))
26
+ const origin = new URL(env.BETTER_AUTH_URL).origin
27
+ const workspace = (userId: string) => ({ id: userId, name: config.name, role: 'owner' as const })
28
+ const requestFor = (path: string) => new Request(origin + path)
29
+ const adapter = createChatOperatorAdapter<Identity>({
30
+ origin,
31
+ admissions: {
32
+ get: async (ctx, workspaceId, turnId) => {
33
+ if (workspaceId !== ctx.identity.userId) return null
34
+ const rows = await sql.query<{ thread_id: string; refusal_json: string | null }>('SELECT thread_id, refusal_json FROM operator_turn_admissions WHERE owner_id = ? AND turn_id = ? LIMIT 1', [ctx.identity.userId, turnId])
35
+ const row = rows[0]
36
+ return row ? { threadId: row.thread_id, ...(row.refusal_json ? { refusal: JSON.parse(row.refusal_json) as { code?: string; message: string } } : {}) } : null
37
+ },
38
+ claim: async (ctx, input) => {
39
+ if (input.workspaceId !== ctx.identity.userId) throw new OperatorError('operator.workspace_not_found', 404)
40
+ const result = await sql.exec('INSERT INTO operator_turn_admissions (owner_id, turn_id, thread_id, created_at) VALUES (?, ?, ?, ?) ON CONFLICT(owner_id, turn_id) DO NOTHING', [ctx.identity.userId, input.turnId, input.threadId, Date.now()])
41
+ return result.rowsAffected === 1
42
+ },
43
+ recordRefusal: async (ctx, input, refusal) => {
44
+ await sql.exec('UPDATE operator_turn_admissions SET refusal_json = ? WHERE owner_id = ? AND turn_id = ? AND thread_id = ?', [JSON.stringify(refusal), ctx.identity.userId, input.turnId, input.threadId])
45
+ },
46
+ },
47
+ ...(options.files ? { files: options.files } : {}),
48
+ ...(options.assets ? { assets: options.assets } : {}),
49
+ workspacePath: () => '/',
50
+ threadPath: (_workspace, threadId) => `/?threadId=${encodeURIComponent(threadId)}`,
51
+ workspaces: {
52
+ list: async ctx => [workspace(ctx.identity.userId)],
53
+ authorize: async (ctx, id, access) => {
54
+ if (id !== ctx.identity.userId) return null
55
+ if (access === 'run' && env.OPERATOR_RUN_ENABLED !== 'true') throw new OperatorError('operator.execution_disabled', 403, 'The deployment payer has not enabled operator execution')
56
+ if (access === 'run' && ctx.identity.spendingLimitCents !== null) throw new OperatorError('operator.capped_execution_unsupported', 402, 'This lane cannot enforce a finite key spending cap')
57
+ return workspace(id)
58
+ },
59
+ },
60
+ threads: {
61
+ get: async (id, ctx) => {
62
+ const thread = await chat.store.getThread(id)
63
+ return thread?.workspaceId === ctx.identity.userId ? thread : null
64
+ },
65
+ create: async (ctx, input) => {
66
+ if (input.workspaceId !== ctx.identity.userId) throw new OperatorError('operator.workspace_not_found', 404)
67
+ return chat.store.createThread(input)
68
+ },
69
+ listMessages: async (id, ctx) => {
70
+ const thread = await chat.store.getThread(id)
71
+ if (!thread || thread.workspaceId !== ctx.identity.userId) throw new OperatorError('operator.thread_not_found', 404)
72
+ const rows = await chat.store.listMessages(id, { limit: 1000 })
73
+ if (rows.length === 1000) throw new OperatorError('operator.history_limit', 503, 'This conversation needs a paginated product history adapter')
74
+ return rows
75
+ },
76
+ list: async (_ctx, workspaceId, query) => {
77
+ const offset = query.cursor === undefined ? 0 : Number(query.cursor)
78
+ if (!Number.isSafeInteger(offset) || offset < 0) throw new OperatorError('operator.invalid_cursor', 400)
79
+ const page = await chat.store.listThreads({ workspaceId, limit: query.limit, offset })
80
+ const next = offset + page.threads.length
81
+ return { threads: page.threads, nextCursor: next < page.total ? String(next) : null }
82
+ },
83
+ },
84
+ turnStatus: async (_ctx, _workspaceId, _threadId, user) => {
85
+ const rows = await sql.query<{ turn_stream_id: string | null; backend_terminal: number }>('SELECT turn_stream_id, backend_terminal FROM message WHERE id = ? LIMIT 1', [user.id])
86
+ const id = rows[0]?.turn_stream_id
87
+ if (!id) return null
88
+ const status = await chat.turnStore.getStatus(id)
89
+ return rows[0]?.backend_terminal ? status : status === 'running' ? 'running' : null
90
+ },
91
+ runningTurns: async (ctx, _workspaceId, threadId) => {
92
+ const response = await trusted(ctx.identity.userId).routes.running(requestFor(`/api/chat/running?threadId=${encodeURIComponent(threadId)}`))
93
+ if (!response.ok) return null
94
+ const body = await response.json() as { running?: string[] }
95
+ return Array.isArray(body.running) ? body.running : null
96
+ },
97
+ approvals: async (ctx, _workspaceId, threadId) => {
98
+ const app = trusted(ctx.identity.userId)
99
+ if (!app.routes.interactions) throw new OperatorError('operator.unsupported', 501)
100
+ const page = threadId ? { threads: [{ id: threadId }], total: 1 } : await chat.store.listThreads({ workspaceId: ctx.identity.userId, limit: 100 })
101
+ if (page.total > page.threads.length) throw new OperatorError('operator.approvals_limit', 503, 'A product-wide approval index is required for this many conversations; the result would be incomplete')
102
+ const threads = page.threads
103
+ const approvals = []
104
+ for (const thread of threads) {
105
+ const response = await app.routes.interactions.list(requestFor(`/api/chat/interactions?threadId=${encodeURIComponent(thread.id)}`))
106
+ if (!response.ok) throw new OperatorError('operator.approvals_unavailable', 503, 'Cannot establish pending decisions', true)
107
+ const body = await response.json() as { unavailable?: string; interactions?: Array<{ id: string; kind: string; title?: string }> }
108
+ if (body.unavailable) throw new OperatorError('operator.approvals_unavailable', 503, 'Cannot establish pending decisions', true)
109
+ for (const interaction of body.interactions ?? []) {
110
+ approvals.push({ id: interaction.id, kind: interaction.kind === 'permission' ? 'permission' as const : interaction.kind === 'plan' ? 'plan' as const : 'question' as const,
111
+ title: interaction.title ?? 'Your agent needs a decision', threadId: thread.id, decidedBy: 'owner' as const,
112
+ url: `${origin}/?threadId=${encodeURIComponent(thread.id)}` })
113
+ }
114
+ }
115
+ return approvals
116
+ },
117
+ runTurn: async (ctx, input) => {
118
+ // The browser path bills the deployment's provider credentials. A capped
119
+ // key must never enter it and silently bypass the gateway's enforcement.
120
+ if (env.OPERATOR_RUN_ENABLED !== 'true') throw new OperatorError('operator.execution_disabled', 403, 'The deployment payer has not enabled operator execution')
121
+ if (ctx.identity.spendingLimitCents !== null) throw new OperatorError('operator.capped_execution_unsupported', 402, 'Use the paid gateway with a backend that enforces this key spending cap')
122
+ return trusted(ctx.identity.userId).routes.turn(new Request(origin + '/api/chat', {
123
+ method: 'POST', headers: { 'content-type': 'application/json' },
124
+ body: JSON.stringify({ threadId: input.threadId, turnId: input.turnId, content: input.content, ...(input.model ? { model: input.model } : {}) }),
125
+ }), { waitUntil: options.waitUntil ?? (() => undefined) })
126
+ },
127
+ })
128
+ return createOperatorApi({
129
+ app: { id: appSlug, name: config.name },
130
+ keys: {
131
+ verify: async authorization => {
132
+ const found = await verifyApiKeyFromStore(authorization, keys, 'ak_')
133
+ return found ? { ...found, expiresAt: found.key.expiresAt?.getTime() ?? 0 } : null
134
+ },
135
+ resolveIdentity: async key => {
136
+ const rows = await sql.query<{ id: string }>('SELECT id FROM users WHERE id = ? LIMIT 1', [key.ownerId])
137
+ return rows.length ? { userId: key.ownerId, spendingLimitCents: key.spendingLimitCents } : null
138
+ },
139
+ claimRequest: async (key, requestId) => {
140
+ const result = await keys.claimRequest(key.keyId, requestId, new Date(), 0)
141
+ // Reads consume request quota, not money. Execution checks its authority separately.
142
+ if (result.allowed) await keys.reservations.release(key.keyId, requestId)
143
+ return { allowed: result.allowed, ...(result.allowed ? {} : { retryAfterSeconds: Math.max(1, Math.ceil(((result.reason === 'daily' ? result.dailyResetAt : result.minuteResetAt) - Date.now()) / 1000)) }) }
144
+ },
145
+ },
146
+ adapter,
147
+ })
148
+ }
@@ -116,22 +116,15 @@ export function createSandboxProduce(env: AppEnv) {
116
116
  const model = body.model ?? env.MODEL_NAME ?? config.model.default
117
117
  return createSandboxChatProducer({
118
118
  model,
119
- // Reactive model failover, ON by default: when `model`'s upstream is
120
- // dead (quota wall, 502, provider outage), the turn moves to the next
121
- // model in `config.model.fallbacks` BEFORE any client-visible byte.
122
- // Never silent: the persisted row and billing receipt name the model
123
- // that actually served, and the transcript gets a visible notice.
124
- // Opt out with `modelFailover: false` (or empty `fallbacks`).
125
- fallbackModels: config.model.fallbacks,
126
- openEvents: ({ model: attemptModel, attempt, signal }) => {
127
- // A failover attempt is a NEW dispatch, not a reconnect to the dead
128
- // one — it needs its own execution identity or the platform would
129
- // resume the failed execution instead of starting a fresh run.
130
- const attemptExecutionId = attempt === 1 ? executionId : `${executionId}-f${attempt}`
119
+ errorNotice: true,
120
+ // A detached dispatch can keep doing hidden work after transport loss.
121
+ // Do not turn observation failure into another model dispatch.
122
+ modelFailover: false,
123
+ openEvents: ({ model: attemptModel, signal }) => {
131
124
  return streamSandboxPrompt(shell, box, normalizeChatPromptForSandbox(prompt), {
132
125
  sessionId: identity.sessionId,
133
- executionId: attemptExecutionId,
134
- turnId: attemptExecutionId,
126
+ executionId,
127
+ turnId: executionId,
135
128
  model: attemptModel,
136
129
  signal,
137
130
  // A zero reasoning allowance maps to the profile's supported
@@ -183,13 +176,16 @@ export async function resolveUploadSink(
183
176
  export async function resolveSidecarConnection(
184
177
  env: AppEnv,
185
178
  scope: { workspaceId: string; userId: string; threadId: string },
179
+ options: { readOnly?: boolean } = {},
186
180
  ): Promise<SidecarInteractionsConnection | null> {
187
181
  if (!env.SANDBOX_API_KEY?.trim() || !env.SANDBOX_GATEWAY_URL?.trim()) return null
188
182
  const shell = createSandboxShell(env)
189
- const box = await ensureForegroundWorkspaceSandbox(env, shell, {
190
- workspaceId: scope.workspaceId,
191
- userId: scope.userId,
192
- })
183
+ // Reading pending decisions must not provision paid compute.
184
+ const found = options.readOnly ? await peekWorkspaceSandbox(shell, { workspaceId: scope.workspaceId, userId: scope.userId }) : null
185
+ const box = options.readOnly
186
+ ? found?.status === 'running' ? found.box : null
187
+ : await ensureForegroundWorkspaceSandbox(env, shell, { workspaceId: scope.workspaceId, userId: scope.userId })
188
+ if (!box) return null
193
189
  const connection = box.connection
194
190
  if (!connection?.runtimeUrl) return null
195
191
  return {
@@ -0,0 +1,12 @@
1
+ import { TurnStreamDO as SharedTurnStreamDO, TURN_STREAM_STORAGE_KEYS, type DurableTurnLock } from '@tangle-network/agent-app/turn-stream'
2
+
3
+ /** A detached sandbox may outlive a Worker and the shared default lease.
4
+ * Keep admission closed until cooperative release or an operator reconciles
5
+ * the actual backend execution. Elapsed time alone never proves it stopped.
6
+ * Auth, atomic admission, fencing and release remain owned by the shared DO.
7
+ */
8
+ export class TurnStreamDO extends SharedTurnStreamDO {
9
+ protected override async loadActiveLock(): Promise<DurableTurnLock | null> {
10
+ return await this.state.storage.get<DurableTurnLock>(TURN_STREAM_STORAGE_KEYS.lock) ?? null
11
+ }
12
+ }
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * src/worker.ts — the HTTP surface. Routing only; every handler is a factory
3
- * product from `src/chat.ts`. Static assets (the dev chat page in `public/`)
4
- * are served by the Workers assets pipeline before this fetch handler runs.
3
+ * product from shared factories. Public agent docs answer before auth/database
4
+ * assembly; the home route negotiates markdown or compiled browser assets.
5
5
  *
6
6
  * Route map:
7
7
  * ALL /api/auth/* better-auth (sign-up/sign-in/session)
@@ -19,6 +19,9 @@
19
19
  * POST /v1/agents/:slug/chat/completions OpenAI-compatible API
20
20
  */
21
21
 
22
+ export { TurnStreamDO } from './turn-lock'
23
+
24
+ import { agentSurfaces } from './agent-surfaces'
22
25
  import { createArtifactIndex } from './files'
23
26
  import type { peekWorkspaceSandbox } from '@tangle-network/agent-app/sandbox'
24
27
  import { config } from '../agent.config'
@@ -80,11 +83,16 @@ export function createWorker(assembly: WorkerAssembly = defaultAssembly): Export
80
83
 
81
84
  return {
82
85
  async fetch(request: Request, env: AppEnv, ctx: ExecutionContext): Promise<Response> {
86
+ const surfaces = agentSurfaces(new URL(env.BETTER_AUTH_URL).origin, env.OPERATOR_RUN_ENABLED === 'true')
87
+ const surface = surfaces.handle(request)
88
+ if (surface) return surface
83
89
  const url = new URL(request.url)
84
90
  const { pathname } = url
85
91
  const method = request.method
86
92
 
87
- const isGatewayPath = pathname === '/api/keys'
93
+ const isGatewayPath = pathname === '/api/operator/v1'
94
+ || pathname.startsWith('/api/operator/v1/')
95
+ || pathname === '/api/keys'
88
96
  || pathname.startsWith('/api/keys/')
89
97
  || pathname === '/v1/agents'
90
98
  || pathname.startsWith('/v1/agents/')
@@ -134,6 +142,7 @@ export function createWorker(assembly: WorkerAssembly = defaultAssembly): Export
134
142
  return app.routes.threadMessages(request, { threadId: transcript[1]! })
135
143
  }
136
144
 
145
+ if (pathname === '/' && env.ASSETS) return surfaces.finalize(request, await env.ASSETS.fetch(request))
137
146
  return Response.json({ error: 'Not found' }, { status: 404 })
138
147
  },
139
148
  }
@@ -19,6 +19,7 @@
19
19
  import { readdirSync, readFileSync } from 'node:fs'
20
20
  import { dirname, join } from 'node:path'
21
21
  import { fileURLToPath } from 'node:url'
22
+ import { createServer } from 'node:http'
22
23
  import Database from 'better-sqlite3'
23
24
  import { drizzle } from 'drizzle-orm/better-sqlite3'
24
25
  import { describe, expect, it, vi } from 'vitest'
@@ -41,10 +42,13 @@ import {
41
42
  type SqlAdapter,
42
43
  } from '@tangle-network/agent-gateway'
43
44
 
45
+ import { createMemoryTurnStreamHarness, MEMORY_TURN_STREAM_AUTH_SECRET } from '@tangle-network/agent-app/turn-stream'
46
+ import type { OperatorTurn } from '@tangle-network/agent-app/operator'
47
+ import { TurnStreamDO } from '../src/turn-lock'
44
48
  import { config } from '../agent.config'
45
- import { buildChatApp, type ChatApp } from '../src/chat'
49
+ import { buildChatApp, type ChatApp, type ChatAppOverrides } from '../src/chat'
46
50
  import type { AppEnv } from '../src/env'
47
- import { buildGatewayApp } from '../src/gateway'
51
+ import { buildGatewayApp, type GatewayAppOptions } from '../src/gateway'
48
52
  import { appSlug } from '../src/sandbox'
49
53
  import { ARTIFACT_ROOT } from '../src/files'
50
54
  import { createWorker, type WorkerAssembly } from '../src/worker'
@@ -122,6 +126,7 @@ interface Harness {
122
126
  sql: SqlAdapter
123
127
  cookie: string
124
128
  gatewayBuilds(): number
129
+ setOperatorRunEnabled(enabled: boolean): void
125
130
  settle(): Promise<unknown>
126
131
  }
127
132
 
@@ -129,26 +134,31 @@ async function createHarness(
129
134
  produce: (args: ChatTurnProduceArgs<void>) => ChatTurnRouteProducer = () =>
130
135
  createSandboxChatProducer({ events: feed(RAW_TURN_EVENTS), model: MODEL }),
131
136
  peekWorkspace?: WorkerAssembly['peekWorkspace'],
137
+ origin = BASE,
138
+ operatorStorage: Pick<GatewayAppOptions, 'files' | 'assets'> = {},
139
+ sidecarConnection?: ChatAppOverrides['sidecarConnection'],
132
140
  ): Promise<Harness> {
141
+ const localEnv: AppEnv = { ...env, BETTER_AUTH_URL: origin, TURN_STREAM: createMemoryTurnStreamHarness((state, secret) => new TurnStreamDO(state, { TURN_STREAM_AUTH_SECRET: secret })).namespace, TURN_STREAM_AUTH_SECRET: MEMORY_TURN_STREAM_AUTH_SECRET }
133
142
  const database = openMigratedDb()
134
143
  const pending: Promise<unknown>[] = []
135
144
  let gatewayBuildCount = 0
136
145
  const chatOverrides = {
146
+ ...(sidecarConnection ? { sidecarConnection } : {}),
137
147
  db: database.db,
138
148
  turnStore: createMemoryTurnEventStore(),
139
149
  produce,
140
150
  uploadSink: async () => null,
141
151
  }
142
- const app = buildChatApp(env, {
152
+ const app = buildChatApp(localEnv, {
143
153
  ...chatOverrides,
144
154
  uploadSink: async () => null, // inline uploads only; no box in tests
145
155
  })
146
156
  // Real sign-up through better-auth; the returned cookie is what a browser
147
157
  // would replay on every API call.
148
158
  const res = await app.auth.auth.handler(
149
- new Request(`${BASE}/api/auth/sign-up/email`, {
159
+ new Request(`${origin}/api/auth/sign-up/email`, {
150
160
  method: 'POST',
151
- headers: { 'content-type': 'application/json', origin: BASE },
161
+ headers: { 'content-type': 'application/json', origin },
152
162
  body: JSON.stringify({ email: 'e2e@example.com', password: 'correct-horse-battery', name: 'e2e' }),
153
163
  }),
154
164
  )
@@ -166,10 +176,11 @@ async function createHarness(
166
176
  buildChatApp: () => app,
167
177
  buildGatewayApp: (_env, chatApp, options) => {
168
178
  gatewayBuildCount += 1
169
- return buildGatewayApp(env, chatApp, {
179
+ return buildGatewayApp(localEnv, chatApp, {
170
180
  ...options,
181
+ ...operatorStorage,
171
182
  sql: database.sql,
172
- createTrustedChatApp: (ownerId) => buildChatApp(env, {
183
+ createTrustedChatApp: (ownerId) => buildChatApp(localEnv, {
173
184
  ...chatOverrides,
174
185
  trustedUserId: ownerId,
175
186
  }),
@@ -187,12 +198,13 @@ async function createHarness(
187
198
  app,
188
199
  workerFetch: async (request) => workerHandler(
189
200
  request as Parameters<typeof workerHandler>[0],
190
- env,
201
+ localEnv,
191
202
  executionContext,
192
203
  ),
193
204
  sql: database.sql,
194
205
  cookie,
195
206
  gatewayBuilds: () => gatewayBuildCount,
207
+ setOperatorRunEnabled: enabled => { localEnv.OPERATOR_RUN_ENABLED = enabled ? 'true' : 'false' },
196
208
  settle: () => Promise.all(pending),
197
209
  }
198
210
  }
@@ -767,3 +779,170 @@ describe('e2e: fake sandbox producer → streamed turn → persisted transcript'
767
779
  expect(config.name.length).toBeGreaterThan(0)
768
780
  })
769
781
  })
782
+
783
+ /** A fresh HTTP client crosses an actual socket, real signup/key issuance,
784
+ * migrated SQLite, Worker routing and the shared operator adapter. Only the
785
+ * model/sandbox event source and explicitly configured owned artifact storage
786
+ * are deterministic fixtures. No credential or paid call is used.
787
+ */
788
+ describe('external-agent HTTP customer journey', () => {
789
+ it('discovers, signs up, scopes, runs once, reads owned bytes and revokes', async () => {
790
+ let h: Harness
791
+ let executions = 0
792
+ let finishSlow = () => {}
793
+ let signalSlow = () => {}
794
+ const slowStarted = new Promise<void>(resolve => { signalSlow = resolve })
795
+ const slowRelease = new Promise<void>(resolve => { finishSlow = resolve })
796
+ const artifact = 'artifact bytes produced by the deterministic backend\n'
797
+ const ownedArtifacts = new Map<string, string>()
798
+ const server = createServer(async (incoming, outgoing) => {
799
+ try {
800
+ const chunks: Buffer[] = []
801
+ for await (const chunk of incoming) chunks.push(Buffer.from(chunk))
802
+ const headers = new Headers()
803
+ for (const [name, value] of Object.entries(incoming.headers)) {
804
+ if (Array.isArray(value)) for (const item of value) headers.append(name, item)
805
+ else if (value !== undefined) headers.set(name, value)
806
+ }
807
+ const request = new Request(`${origin}${incoming.url}`, { method: incoming.method, headers,
808
+ ...(['GET', 'HEAD'].includes(incoming.method ?? 'GET') ? {} : { body: Buffer.concat(chunks) }) })
809
+ const response = await h.workerFetch(request)
810
+ outgoing.statusCode = response.status
811
+ for (const [name, value] of response.headers) if (name !== 'set-cookie') outgoing.setHeader(name, value)
812
+ const cookies = response.headers.getSetCookie()
813
+ if (cookies.length) outgoing.setHeader('set-cookie', cookies)
814
+ outgoing.end(Buffer.from(await response.arrayBuffer()))
815
+ } catch (error) { outgoing.statusCode = 500; outgoing.end(String(error)) }
816
+ })
817
+ await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
818
+ const address = server.address()
819
+ if (!address || typeof address === 'string') throw new Error('No local server address')
820
+ const origin = `http://127.0.0.1:${address.port}`
821
+ try {
822
+ h = await createHarness(args => {
823
+ executions++
824
+ ownedArtifacts.set(`${args.identity.userId}/proof.txt`, artifact)
825
+ if (args.body.content === 'Lose detached observation') return createSandboxChatProducer({ errorNotice: true, model: MODEL, events: (async function* () { yield RAW_TURN_EVENTS[0]!; throw new Error('Replay lost while deterministic backend remains active') })() })
826
+ if (args.body.content === 'Hold the workspace lock') {
827
+ signalSlow()
828
+ return createSandboxChatProducer({ events: (async function* () { await slowRelease; yield* feed(RAW_TURN_EVENTS) })(), model: MODEL, errorNotice: true })
829
+ }
830
+ return createSandboxChatProducer({ events: feed(RAW_TURN_EVENTS), model: MODEL, errorNotice: true })
831
+ }, undefined, origin, {
832
+ files: {
833
+ list: async ctx => ownedArtifacts.has(`${ctx.identity.userId}/proof.txt`) ? [{ path: 'proof.txt', bytes: new TextEncoder().encode(artifact).length }] : [],
834
+ read: async (ctx, _workspace, path) => {
835
+ const content = ownedArtifacts.get(`${ctx.identity.userId}/${path}`)
836
+ return content === undefined ? null : { path, content, mediaType: 'text/plain', revision: 'fixture-v1' }
837
+ },
838
+ },
839
+ }, async (_env, scope) => ({ runtimeUrl: 'http://sidecar.fixture.test', sessionId: scope.threadId,
840
+ fetchImpl: async () => Response.json({ data: { interactions: [{ id: 'owner-decision', kind: 'permission', title: 'Publish the draft?' }] } }) }))
841
+ const call = (path: string, init?: RequestInit) => fetch(origin + path, { ...init, redirect: 'error' })
842
+ for (const path of ['/llms.txt', '/llms-full.txt', '/agent-setup.md', '/agent-api.md', '/.well-known/tangle-agent.json']) {
843
+ const response = await call(path)
844
+ expect(response.status, path).toBe(200)
845
+ expect(response.headers.get('content-type')).not.toMatch(/text\/html/)
846
+ if (path.endsWith('.json')) expect(((await response.json()) as { operator_api: string }).operator_api).toBe(`${origin}/api/operator/v1`)
847
+ }
848
+ const schema = await (await call('/openapi.json')).json() as { paths: Record<string, unknown> }
849
+ expect(schema.paths).not.toHaveProperty('/api/operator/v1/workspaces/{workspaceId}/assets/{assetId}')
850
+ const markdown = await call('/', { headers: { accept: 'text/markdown' } })
851
+ expect(markdown.headers.get('vary')).toContain('Accept')
852
+ expect(markdown.headers.get('content-type')).toContain('text/markdown')
853
+ const signup = await call('/api/auth/sign-up/email', { method: 'POST', headers: { 'content-type': 'application/json', origin },
854
+ body: JSON.stringify({ name: 'External client owner', email: 'external-client@example.test', password: 'fixture-only-password' }) })
855
+ expect(signup.status).toBe(200)
856
+ const ownerCookie = signup.headers.getSetCookie().map(value => value.split(';')[0]).join('; ')
857
+ const issue = async (scopes: string[], extra: Record<string, unknown> = {}) => {
858
+ const response = await call('/api/keys', { method: 'POST', headers: { cookie: ownerCookie, 'content-type': 'application/json' },
859
+ body: JSON.stringify({ name: 'external client', scopes, expiresAt: new Date(Date.now() + 60_000).toISOString(), ...extra }) })
860
+ expect(response.status).toBe(201)
861
+ return await response.json() as { key: string; id: string }
862
+ }
863
+ const read = await issue(['operator:read'])
864
+ const deniedIssue = await call('/api/keys', { method: 'POST', headers: { cookie: ownerCookie, 'content-type': 'application/json' }, body: JSON.stringify({ name: 'No payer authority', scopes: ['operator:read', 'operator:run'], expiresAt: new Date(Date.now() + 60_000).toISOString() }) })
865
+ expect(deniedIssue.status).toBe(403)
866
+ expect(schema.paths).not.toHaveProperty('/api/operator/v1/workspaces/{workspaceId}/turns')
867
+ expect(await (await call('/api/keys/access', { headers: { cookie: ownerCookie } })).json()).toEqual({ operatorRunEnabled: false })
868
+ h.setOperatorRunEnabled(true) // Explicit deployment-payer opt-in for the deterministic fixture.
869
+ const run = await issue(['operator:read', 'operator:run'])
870
+ const authorized = (key: string, path: string, body?: unknown) => call(`/api/operator/v1${path}`, { method: body === undefined ? 'GET' : 'POST',
871
+ headers: { authorization: `Bearer ${key}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
872
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }) })
873
+ expect((await call('/api/operator/v1', { headers: { cookie: ownerCookie } })).status).toBe(401)
874
+ const discovery = await (await authorized(read.key, '')).json() as { app: { capabilities: string[] } }
875
+ expect(discovery.app.capabilities).toContain('files.read')
876
+ expect(discovery.app.capabilities).not.toContain('workspaces.create')
877
+ const { workspaces } = await (await authorized(read.key, '/workspaces')).json() as { workspaces: Array<{ id: string }> }
878
+ expect(workspaces).toHaveLength(1)
879
+ const workspace = workspaces[0]!.id
880
+ const input = { turnId: crypto.randomUUID(), content: 'Produce the deterministic proof result' }
881
+ expect((await authorized(read.key, `/workspaces/${workspace}/turns`, input)).status).toBe(403)
882
+ h.setOperatorRunEnabled(false)
883
+ expect((await authorized(run.key, `/workspaces/${workspace}/turns`, input)).status).toBe(403)
884
+ expect(executions).toBe(0)
885
+ expect(await h.sql.query('SELECT turn_id FROM operator_turn_admissions')).toHaveLength(0)
886
+ expect((await h.app.store.listThreads({ workspaceId: workspace })).total).toBe(0)
887
+ h.setOperatorRunEnabled(true)
888
+ expect((await authorized(run.key, '/workspaces/another-owner/turns', input)).status).toBe(404)
889
+ const capped = await issue(['operator:read', 'operator:run'], { spendingLimitCents: 100 })
890
+ expect((await authorized(capped.key, `/workspaces/${workspace}/turns`, input)).status).toBe(402)
891
+ expect(executions).toBe(0)
892
+ expect((await authorized(read.key, `/workspaces/${workspace}/file?path=proof.txt`)).status).toBe(404)
893
+ const [start, raced] = await Promise.all([authorized(run.key, `/workspaces/${workspace}/turns`, input), authorized(run.key, `/workspaces/${workspace}/turns`, input)])
894
+ expect(raced.status).toBe(202)
895
+ expect(start.status).toBe(202)
896
+ const outcomes = await Promise.all([start.json(), raced.json()]) as Array<{ turn: OperatorTurn }>
897
+ const turn = outcomes.find(result => result.turn.state === 'succeeded')!.turn
898
+ expect(turn.state).toBe('succeeded')
899
+ expect(turn.reply!.content).toContain('Filed')
900
+ const retry = await authorized(run.key, `/workspaces/${workspace}/turns`, input)
901
+ expect(retry.status).toBe(202)
902
+ expect(((await retry.json()) as { turn: OperatorTurn }).turn.turnId).toBe(input.turnId)
903
+ expect(executions).toBe(1)
904
+ const polled = await authorized(read.key, `/workspaces/${workspace}/threads/${turn.threadId}/turns/${input.turnId}?wait=1`)
905
+ expect(((await polled.json()) as { turn: OperatorTurn }).turn.state).toBe('succeeded')
906
+ // A new HTTP request builds a new operator adapter over the same database:
907
+ // simulate retained claim state from a process that died before transcript insertion.
908
+ const interruptedId = crypto.randomUUID()
909
+ await h.sql.exec('INSERT INTO operator_turn_admissions (owner_id, turn_id, thread_id, created_at) VALUES (?, ?, ?, ?)', [workspace, interruptedId, turn.threadId, Date.now()])
910
+ const interrupted = await authorized(run.key, `/workspaces/${workspace}/turns`, { turnId: interruptedId, threadId: turn.threadId, content: 'Do not repeat uncertain effects' })
911
+ expect(((await interrupted.json()) as { turn: OperatorTurn }).turn.state).toBe('unknown')
912
+ expect(executions).toBe(1)
913
+ const slow = authorized(run.key, `/workspaces/${workspace}/turns`, { turnId: crypto.randomUUID(), threadId: turn.threadId, content: 'Hold the workspace lock' })
914
+ await slowStarted
915
+ const browserContender = await call('/api/chat', { method: 'POST', headers: { cookie: ownerCookie, 'content-type': 'application/json' }, body: JSON.stringify({ threadId: turn.threadId, turnId: crypto.randomUUID(), content: 'Browser contender' }) })
916
+ expect(browserContender.status).toBe(409)
917
+ const contender = await authorized(run.key, `/workspaces/${workspace}/turns`, { turnId: crypto.randomUUID(), threadId: turn.threadId, content: 'Operator contender' })
918
+ expect(await contender.json()).toMatchObject({ turn: { state: 'failed', failure: { code: 'workspace_turn_in_flight' } } })
919
+ expect(executions).toBe(2)
920
+ const during = await h.app.store.listMessages(turn.threadId)
921
+ expect(during.filter(row => row.role === 'user').map(row => row.content)).toEqual([input.content, 'Hold the workspace lock'])
922
+ finishSlow()
923
+ expect(await (await slow).json()).toMatchObject({ turn: { state: 'succeeded', reply: { content: expect.stringContaining('Filed') } } })
924
+ const approvals = await authorized(read.key, `/workspaces/${workspace}/approvals`)
925
+ expect(approvals.status).toBe(200)
926
+ const held = await approvals.json() as { approvals: Array<{ decidedBy: string; url: string }> }
927
+ expect(held.approvals[0]?.decidedBy).toBe('owner')
928
+ expect(held.approvals.map(item => item.url)).toContain(`${origin}/?threadId=${encodeURIComponent(turn.threadId)}`)
929
+ const file = await (await authorized(read.key, `/workspaces/${workspace}/file?path=proof.txt`)).json() as { file: { content: string } }
930
+ expect(file.file.content).toBe(artifact)
931
+ expect((await authorized(read.key, '/workspaces/another-owner/file?path=proof.txt')).status).toBe(404)
932
+ expect((await authorized(read.key, `/workspaces/${workspace}/file?path=..%2Fsecret`)).status).toBe(400)
933
+ expect((await authorized(run.key, `/workspaces/${workspace}/approvals`, { id: 'decision', outcome: 'accepted' })).status).toBe(404)
934
+ const lostId = crypto.randomUUID()
935
+ const lost = await authorized(run.key, `/workspaces/${workspace}/turns`, { turnId: lostId, threadId: turn.threadId, content: 'Lose detached observation' })
936
+ expect(lost.status).toBe(202)
937
+ await h.settle()
938
+ const uncertain = await authorized(read.key, `/workspaces/${workspace}/threads/${turn.threadId}/turns/${lostId}`)
939
+ expect(await uncertain.json()).toMatchObject({ turn: { state: 'unknown', reply: null } })
940
+ const forbiddenRestart = await authorized(run.key, `/workspaces/${workspace}/turns`, { turnId: crypto.randomUUID(), threadId: turn.threadId, content: 'Must not overlap detached backend' })
941
+ expect(await forbiddenRestart.json()).toMatchObject({ turn: { state: 'failed', failure: { code: 'workspace_turn_in_flight' } } })
942
+ expect(executions).toBe(3)
943
+ expect((await call(`/api/keys/${run.id}`, { method: 'DELETE', headers: { cookie: ownerCookie } })).status).toBe(200)
944
+ expect((await authorized(run.key, '')).status).toBe(401)
945
+ await h.settle()
946
+ } finally { finishSlow(); await new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve())) }
947
+ }, 30_000)
948
+ })
@@ -74,3 +74,15 @@ describe('sandbox foreground provisioning', () => {
74
74
  expect(sandboxMocks.peekWorkspace).not.toHaveBeenCalled()
75
75
  })
76
76
  })
77
+
78
+ it('listing decisions never provisions or resumes paid compute', async () => {
79
+ const { resolveSidecarConnection } = await import('../src/sandbox')
80
+ sandboxMocks.ensureWorkspace.mockClear()
81
+ sandboxMocks.peekWorkspace.mockResolvedValue({ status: 'absent' })
82
+ const result = await resolveSidecarConnection({ DB: {} as D1Database,
83
+ BETTER_AUTH_URL: 'http://localhost:8787', BETTER_AUTH_SECRET: 'fixture',
84
+ SANDBOX_API_KEY: 'fixture', SANDBOX_GATEWAY_URL: 'https://sandbox.example.test',
85
+ }, { workspaceId: 'owner', userId: 'owner', threadId: 'thread' }, { readOnly: true })
86
+ expect(result).toBeNull()
87
+ expect(sandboxMocks.ensureWorkspace).not.toHaveBeenCalled()
88
+ })
@@ -0,0 +1,23 @@
1
+ import { describe, expect, it, vi } from 'vitest'
2
+ import { createMemoryTurnStreamHarness, createDurableTurnLock, MEMORY_TURN_STREAM_AUTH_SECRET, TURN_LOCK_TTL_MS } from '@tangle-network/agent-app/turn-stream'
3
+ import { TurnStreamDO } from '../src/turn-lock'
4
+
5
+ describe('detached workspace admission', () => {
6
+ it('does not release an uncertain execution merely because the shared lease elapsed', async () => {
7
+ const clock = vi.spyOn(Date, 'now')
8
+ let now = 1_900_000_000_000
9
+ clock.mockImplementation(() => now)
10
+ try {
11
+ const { namespace } = createMemoryTurnStreamHarness((state, secret) => new TurnStreamDO(state, { TURN_STREAM_AUTH_SECRET: secret }))
12
+ const lock = createDurableTurnLock({ namespace, auth: { secret: MEMORY_TURN_STREAM_AUTH_SECRET }, scopeOf: () => 'workspace' })
13
+ const input = { identity: { tenantId: 'owner', sessionId: 'thread' }, executionId: 'one', context: undefined, body: { turnId: crypto.randomUUID() } }
14
+ const first = await lock.acquire(input)
15
+ expect(first.acquired).toBe(true)
16
+ now += TURN_LOCK_TTL_MS + 1
17
+ expect((await lock.acquire({ ...input, executionId: 'two', body: { turnId: crypto.randomUUID() } })).acquired).toBe(false)
18
+ if (!first.acquired) throw new Error('No lock')
19
+ await lock.release(first.handle)
20
+ expect((await lock.acquire({ ...input, executionId: 'two' })).acquired).toBe(true)
21
+ } finally { clock.mockRestore() }
22
+ })
23
+ })