Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

text.ts

417 lines15.5 KB

1import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
2import { toRunErrorRawEvent } from '@tanstack/ai/adapter-internals'
3import { BaseTextAdapter } from '@tanstack/ai/adapters'
4import {
5 DurableAttachNotSupportedError,
6 SandboxCapability,
7 buildApprovalRequestedEvent,
8 createBridgeEventChannel,
9 getSandbox,
10 getSandboxDurability,
11 getToolBridgeProvisioner,
12 getWorkspaceProjection,
13 mergeChunkStreams,
14 nodeHttpBridgeProvisioner,
15 resolveDurableRunId,
16} from '@tanstack/ai-sandbox'
17import { buildPrompt } from '../messages/prompt'
18import { startOpencodeSession } from '../process/server'
19import { startOpencodeServerInSandbox } from '../process/sandbox-server'
20import { resolveInteractivePermission } from '../process/permissions'
21import { AsyncQueue } from '../stream/queue'
22import { translateOpencodeStream } from '../stream/translate'
23import { projectOpencodeWorkspace } from './projection'
24import type { HostToolBridge, SandboxHandle } from '@tanstack/ai-sandbox'
25import type {
26 StructuredOutputOptions,
27 StructuredOutputResult,
28} from '@tanstack/ai/adapters'
29import type {
30 DefaultMessageMetadataByModality,
31 Modality,
32 StreamChunk,
33 TextOptions,
34} from '@tanstack/ai'
35import type { OpencodeSessionHandle } from '../process/server'
36import type {
37 OpencodePermissionMode,
38 PermissionHandler,
39} from '../process/permissions'
40import type { OpencodeStreamEvent } from '../stream/sdk-types'
41import type { OpencodeModel } from '../model-meta'
42import type { OpencodeTextProviderOptions } from '../provider-options'
43​
44const DEFAULT_WORKDIR = '/workspace'
45const DEFAULT_PORT = 4096
46​
47export interface OpencodeTextConfig {
48 /** Working directory inside the sandbox. Defaults to `/workspace`. */
49 directory?: string
50 /**
51 * Port the in-sandbox `opencode serve` listens on. Defaults to 4096. For the
52 * Docker provider this port must also be published (`publishPorts: [4096]`)
53 * so the host can reach it.
54 */
55 port?: number
56 /** Hostname the in-sandbox server binds. Defaults to `0.0.0.0`. */
57 hostname?: string
58 /**
59 * OpenCode permission mode driving the dynamic permission handler. Defaults
60 * to `'default'`; set `'acceptEdits'` / `'bypassPermissions'` to let the
61 * harness edit files and run commands autonomously inside the sandbox.
62 */
63 permissionMode?: OpencodePermissionMode
64 /** Custom permission handler; replaces the adapter's default policy. */
65 onPermissionRequest?: PermissionHandler
67​
68/** Split a `provider/model` id into its provider and model halves. */
69function splitModel(model: string): { providerID: string; modelID: string } {
70 const slash = model.indexOf('/')
71 if (slash <= 0 || slash === model.length - 1) {
72 throw new Error(
73 `OpenCode models must be addressed as "provider/model" (e.g. "anthropic/claude-sonnet-4-5"); received "${model}".`,
74 )
75 }
76 return { providerID: model.slice(0, slash), modelID: model.slice(slash + 1) }
78​
79export class OpencodeTextAdapter<
80 TModel extends OpencodeModel,
81> extends BaseTextAdapter<
82 TModel,
83 OpencodeTextProviderOptions,
84 ReadonlyArray<Modality> & readonly ['text'],
85 DefaultMessageMetadataByModality,
86 ReadonlyArray<string>,
87 unknown,
88 never
89> {
90 readonly name = 'opencode' as const
91​
92 override readonly requires = [SandboxCapability] as const
93​
94 private readonly adapterConfig: OpencodeTextConfig
95​
96 constructor(config: OpencodeTextConfig, model: TModel) {
97 super({}, model)
98 this.adapterConfig = config
99 }
100​
101 private sandboxFrom(
102 options: TextOptions<OpencodeTextProviderOptions>,
103 ): SandboxHandle {
104 const ctx = options.capabilities
105 if (!ctx) {
106 throw new Error(
107 'Adapter "opencode" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.',
108 )
109 }
110 return getSandbox(ctx)
111 }
112​
113 private applySystemPrompts(
114 options: TextOptions<OpencodeTextProviderOptions>,
115 prompt: string,
116 ): string {
117 const systemPrompts = normalizeSystemPrompts(options.systemPrompts)
118 .map((systemPrompt) => systemPrompt.content)
119 .filter((content) => content.trim() !== '')
120 if (systemPrompts.length === 0) return prompt
121 return `${systemPrompts.join('\n\n')}\n\n${prompt}`
122 }
123​
124 async *chatStream(
125 options: TextOptions<OpencodeTextProviderOptions>,
126 ): AsyncIterable<StreamChunk> {
127 const { logger } = options
128 let server:
129 | Awaited<ReturnType<typeof startOpencodeServerInSandbox>>
130 | undefined
131 let handle: OpencodeSessionHandle | undefined
132 let bridge: HostToolBridge | undefined
133 const externalSignal =
134 options.abortController?.signal ?? options.request?.signal ?? undefined
135 let onAbort: (() => void) | undefined
136 // This adapter does not journal yet, so a generated id is still fine.
137 // Routed through the helper anyway so journaling here inherits the
138 // caller-supplied-runId requirement instead of re-deriving it.
139 const runId = resolveDurableRunId(options.runId, {
140 durable: false,
141 adapter: 'opencode',
142 fallback: () => this.generateId(),
143 })
144 const threadId = options.threadId ?? this.generateId()
145 // Surfaces custom events from bridged tools (e.g. code mode console logs)
146 // on this run's live output stream.
147 const channel = createBridgeEventChannel({
148 model: this.model,
149 threadId,
150 runId,
151 })
152​
153 try {
154 const sandbox = this.sandboxFrom(options)
155 const directory =
156 options.modelOptions?.directory ??
157 this.adapterConfig.directory ??
158 DEFAULT_WORKDIR
159​
160 // Durability wired onto a path that cannot deliver it. Two outcomes, split
161 // by whether a first attempt has already run.
162 //
163 // ATTACH is fatal. `sandboxRunDriver`'s `drive()` sets `attach: true` only
164 // when a previous host was already streaming this run, so continuing past
165 // here reaches `startOpencodeServerInSandbox` + the session prompt and
166 // re-runs the agent from scratch against the workspace that attempt
167 // already mutated, appending its whole output to a log that still holds
168 // the first attempt's. This adapter has no journal to tail, no
169 // `awaitAttachableJournal` to refuse the attach up front, and no
170 // `alignedIfAttaching` to suppress the already-delivered prefix — so there
171 // is nothing between here and that corruption except this throw.
172 //
173 // A FRESH durable run only fails to be recoverable LATER, which an app may
174 // knowingly accept (it can wire `withSandbox({ runs, durability })` once at
175 // the middleware level and still route some runs through this adapter). So
176 // that is a warn, not a throw: audible, not fatal. Once per run, not per
177 // chunk — a per-chunk warning would be worse than none. Mirrors
178 // `ai-grok-build`'s `chatStreamAcp`.
179 const durability = options.capabilities
180 ? getSandboxDurability(options.capabilities, { optional: true })
181 : undefined
182 if (durability !== undefined) {
183 if (durability.attach) {
184 throw new DurableAttachNotSupportedError(
185 'opencode',
186 'this adapter drives the harness over the opencode HTTP server ' +
187 'and does not journal',
188 )
189 }
190 logger.warn(
191 'opencode: sandbox durability is wired but this adapter never ' +
192 'journals — this run will not be recoverable on reconnect. Use a ' +
193 'journaling harness adapter for runs that must survive a host ' +
194 'restart, or drop durability if these runs are not meant to.',
195 { runId, adapter: 'opencode' },
196 )
197 }
198​
199 // Project workspace skills / MCP servers into the sandbox before starting
200 // the opencode server so the workspace config is in place for the session.
201 if (options.capabilities !== undefined) {
202 const projection = getWorkspaceProjection(options.capabilities, {
203 optional: true,
204 })
205 if (projection !== undefined) {
206 await projectOpencodeWorkspace(sandbox, projection)
207 }
208 }
209​
210 const modelOptions = options.modelOptions
211 const sessionId = modelOptions?.sessionId
212 const { prompt: resumePrompt } = buildPrompt(options.messages, sessionId)
213 const { providerID, modelID } = splitModel(this.model)
214​
215 // Bridge chat()-provided tools into the in-sandbox server over MCP
216 // (configured via OPENCODE_CONFIG_CONTENT at server spawn).
217 const bridgedToolNames = new Set(
218 (options.tools ?? []).map((tool) => tool.name),
219 )
220 if (options.tools && options.tools.length > 0) {
221 const provisioner =
222 (options.capabilities
223 ? getToolBridgeProvisioner(options.capabilities, { optional: true })
224 : undefined) ?? nodeHttpBridgeProvisioner
225 bridge = await provisioner.provision(options.tools, {
226 provider: sandbox.provider,
227 context: options.context,
228 emitCustomEvent: channel.emitCustomEvent,
229 ...(externalSignal ? { signal: externalSignal } : {}),
230 })
231 }
232​
233 // Approval-requested events for `ask`-policy actions with no client
234 // decision yet, emitted after the stream so the client can approve + re-run.
235 const approvalRequests: Array<StreamChunk> = []
236​
237 const queue = new AsyncQueue<OpencodeStreamEvent>()
238 const mode =
239 modelOptions?.permissionMode ??
240 this.adapterConfig.permissionMode ??
241 'default'
242 const permissionHandler: PermissionHandler =
243 this.adapterConfig.onPermissionRequest ??
244 ((request) => {
245 const result = resolveInteractivePermission(
246 request,
247 mode,
248 bridgedToolNames,
249 options.approvals,
250 )
251 if (result.approvalId !== undefined) {
252 approvalRequests.push(
253 buildApprovalRequestedEvent({
254 approvalId: result.approvalId,
255 title: result.title ?? request.title,
256 threadId,
257 runId,
258 detail: { provider: 'opencode' },
259 }),
260 )
261 }
262 return result.response
263 })
264​
265 logger.request(
266 `activity=chat provider=opencode model=${this.model} sandbox=${sandbox.provider} messages=${options.messages.length} resume=${sessionId ?? 'none'}`,
267 { provider: 'opencode', model: this.model },
268 )
269​
270 const serverEnv = bridge
271 ? {
272 OPENCODE_CONFIG_CONTENT: JSON.stringify({
273 mcp: {
274 [bridge.name]: {
275 type: 'remote',
276 url: bridge.url,
277 enabled: true,
278 headers: { Authorization: `Bearer ${bridge.token}` },
279 },
280 },
281 }),
282 }
283 : undefined
284​
285 server = await startOpencodeServerInSandbox(sandbox, {
286 port: this.adapterConfig.port ?? DEFAULT_PORT,
287 ...(this.adapterConfig.hostname !== undefined && {
288 hostname: this.adapterConfig.hostname,
289 }),
290 cwd: directory,
291 ...(serverEnv ? { env: serverEnv } : {}),
292 ...(externalSignal ? { signal: externalSignal } : {}),
293 })
294​
295 handle = await startOpencodeSession({
296 baseUrl: server.baseUrl,
297 // Forward the channel's auth headers (e.g. Daytona's preview token) so
298 // the host client can reach a token-gated preview proxy.
299 ...(server.headers !== undefined && { headers: server.headers }),
300 // NOTE: do NOT pass `directory` here. `directory` is the VIRTUAL sandbox
301 // path (e.g. `/workspace`); the server is already spawned with that as its
302 // cwd (the provider handle maps it to the real workdir — `/workspace`
303 // inside Docker, a host temp dir for local-process). Forwarding the
304 // virtual path to the host-side opencode HTTP API breaks local-process,
305 // where `/workspace` doesn't exist → the API stalls until the request
306 // times out. Omitting it makes opencode use the server's (correct) cwd.
307 providerID,
308 modelID,
309 ...(sessionId !== undefined && { resumeSessionId: sessionId }),
310 onEvent: (event) => queue.push({ kind: 'event', event }),
311 onPermissionRequest: permissionHandler,
312 onError: (error) => queue.fail(error),
313 })
314 const session = handle
315​
316 if (externalSignal !== undefined) {
317 onAbort = () => void session.abort().catch(() => undefined)
318 if (externalSignal.aborted) onAbort()
319 else externalSignal.addEventListener('abort', onAbort, { once: true })
320 }
321​
322 queue.push({ kind: 'session', sessionId: session.sessionId })
323​
324 const promptText = this.applySystemPrompts(
325 options,
326 session.resumed || sessionId === undefined
327 ? resumePrompt
328 : buildPrompt(options.messages, undefined).prompt,
329 )
330​
331 session
332 .prompt(promptText)
333 .then(({ message }) => {
334 queue.push({ kind: 'done', message })
335 queue.end()
336 })
337 .catch((error: unknown) => queue.fail(error))
338​
339 yield* mergeChunkStreams(
340 translateOpencodeStream(queue, {
341 model: this.model,
342 runId,
343 threadId,
344 ...(options.parentRunId !== undefined && {
345 parentRunId: options.parentRunId,
346 }),
347 genId: () => this.generateId(),
348 bridgedToolNames,
349 onStreamEvent: (event) =>
350 logger.provider(`provider=opencode kind=${event.kind}`, {
351 chunk: event,
352 }),
353 }),
354 channel.stream,
355 )
356​
357 // Surface pending approval requests (ask-policy actions awaiting a client
358 // decision); the client approves and re-runs to continue.
359 for (const event of approvalRequests) yield event
360 } catch (error: unknown) {
361 const err = error as Error & { code?: string }
362 const rawEvent = toRunErrorRawEvent(error)
363 logger.errors('opencode.chatStream fatal', {
364 error,
365 source: 'opencode.chatStream',
366 })
367 yield {
368 type: EventType.RUN_ERROR,
369 model: options.model,
370 timestamp: Date.now(),
371 message: err.message || 'Unknown error occurred',
372 ...(err.code !== undefined && { code: err.code }),
373 ...(rawEvent !== undefined && { rawEvent }),
374 error: {
375 message: err.message || 'Unknown error occurred',
376 ...(err.code !== undefined && { code: err.code }),
377 },
378 }
379 } finally {
380 if (externalSignal !== undefined && onAbort !== undefined) {
381 externalSignal.removeEventListener('abort', onAbort)
382 }
383 channel.close()
384 await handle?.dispose()
385 await server?.dispose()
386 await bridge?.close()
387 }
388 }
389​
390 structuredOutput(
391 _options: StructuredOutputOptions<OpencodeTextProviderOptions>,
392 ): Promise<StructuredOutputResult<unknown>> {
393 return Promise.reject(
394 new Error(
395 'Structured output is not yet supported by the in-sandbox OpenCode adapter. ' +
396 'Use a model adapter for structured output, or omit outputSchema.',
397 ),
398 )
399 }
401​
402/**
403 * Creates an OpenCode harness adapter that runs **inside a sandbox**.
404 *
405 * It declares `requires: [SandboxCapability]`, spawns `opencode serve` inside
406 * the sandbox provided by `withSandbox(...)`, exposes its port, and connects
407 * the `@opencode-ai/sdk` HTTP client to it. OpenCode owns the agent loop and
408 * executes its native tools against the sandbox workspace. The sandbox image
409 * must provide the `opencode` executable (Docker: also publish the server port
410 * via `publishPorts`). chat()-provided tools aren't bridged yet.
411 */
412export function opencodeText<TModel extends OpencodeModel>(
413 model: TModel,
414 config: OpencodeTextConfig = {},
415): OpencodeTextAdapter<TModel> {
416 return new OpencodeTextAdapter(config, model)