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

text.ts

483 lines19.0 KB

1import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
2import { toRunErrorRawEvent } from '@tanstack/ai/adapter-internals'
3import { BaseTextAdapter } from '@tanstack/ai/adapters'
4import {
5 SandboxCapability,
6 alignedIfAttaching,
7 createBridgeEventChannel,
8 createRunScopedIdGen,
9 encodeRunId,
10 getSandbox,
11 getSandboxDurability,
12 getSandboxPolicy,
13 getToolBridgeProvisioner,
14 getWorkspaceProjection,
15 journalOptionsFor,
16 mergeChunkStreams,
17 nodeHttpBridgeProvisioner,
18 resolveDurableRunId,
19 resolveDurableThreadId,
20 spawnNdjson,
21} from '@tanstack/ai-sandbox'
22import { buildPrompt } from '../messages/prompt'
23import { translateThreadEvents } from '../stream/translate'
24import { projectCodexWorkspace } from './projection'
25import { mapPolicyToCodexFlags } from './policy-map'
26import type { CodexPolicyFlags } from './policy-map'
27import type { HostToolBridge, SandboxHandle } from '@tanstack/ai-sandbox'
28import type {
29 StructuredOutputOptions,
30 StructuredOutputResult,
31} from '@tanstack/ai/adapters'
32import type {
33 DefaultMessageMetadataByModality,
34 Modality,
35 StreamChunk,
36 TextOptions,
37} from '@tanstack/ai'
38import type { CodexModel } from '../model-meta'
39import type { CodexTextProviderOptions } from '../provider-options'
40import type { CodexThreadEvent } from '../stream/sdk-types'
41​
42export type CodexSandboxMode =
43 | 'read-only'
44 | 'workspace-write'
45 | 'danger-full-access'
46export type CodexApprovalMode =
47 | 'never'
48 | 'on-failure'
49 | 'on-request'
50 | 'untrusted'
51​
52const DEFAULT_WORKDIR = '/workspace'
53​
54/**
55 * Providers that already isolate the agent in a VM or container where Codex
56 * cannot create a nested bubblewrap user namespace. Isolation is then the
57 * outer sandbox plus `defineSandboxPolicy`. Issue #1081 item 8.
58 */
59const NESTED_BWRAP_UNSUPPORTED = new Set(['daytona', 'cloudflare'])
60​
61function defaultSandboxMode(provider: string): CodexSandboxMode {
62 return NESTED_BWRAP_UNSUPPORTED.has(provider)
63 ? 'danger-full-access'
64 : 'workspace-write'
66​
67export interface CodexTextConfig {
68 /** Working directory inside the sandbox. Defaults to `/workspace`. */
69 cwd?: string
70 /**
71 * Codex's own sandbox mode (`--sandbox`). Defaults to `'workspace-write'`
72 * so the agent can edit the workspace — the outer TanStack sandbox is the
73 * real isolation boundary.
74 */
75 sandboxMode?: CodexSandboxMode
76 /** Codex approval policy (`--config approval_policy=`). Defaults to `'never'`. */
77 approvalPolicy?: CodexApprovalMode
78 /** Model reasoning effort (`--config model_reasoning_effort=`). */
79 modelReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high'
80 /** Skip Codex's git-repo safety check (`--skip-git-repo-check`). Defaults to true. */
81 skipGitRepoCheck?: boolean
82 /** Allow network in `workspace-write` (`--config sandbox_workspace_write.network_access=`). */
83 networkAccessEnabled?: boolean
84 /** Web search mode (`--config web_search=`). */
85 webSearchMode?: 'disabled' | 'live'
86 /** Extra writable directories (`--add-dir`). */
87 additionalDirectories?: Array<string>
88 /** Path/name of the codex executable inside the sandbox. Defaults to `codex`. */
89 codexExecutable?: string
90 /** Extra environment variables for the codex process inside the sandbox. */
91 env?: Record<string, string>
92 /** Extra raw `--config key=value` overrides (values passed verbatim as TOML). */
93 config?: Record<string, string>
95​
96function q(value: string): string {
97 return `'${value.replace(/'/g, `'\\''`)}'`
99​
100export class CodexTextAdapter<
101 TModel extends CodexModel,
102> extends BaseTextAdapter<
103 TModel,
104 CodexTextProviderOptions,
105 ReadonlyArray<Modality> & readonly ['text'],
106 DefaultMessageMetadataByModality,
107 ReadonlyArray<string>,
108 unknown,
109 never
110> {
111 readonly name = 'codex' as const
112​
113 override readonly requires = [SandboxCapability] as const
114​
115 private readonly adapterConfig: CodexTextConfig
116​
117 constructor(config: CodexTextConfig, model: TModel) {
118 super({}, model)
119 this.adapterConfig = config
120 }
121​
122 private sandboxFrom(
123 options: TextOptions<CodexTextProviderOptions>,
124 ): SandboxHandle {
125 const ctx = options.capabilities
126 if (!ctx) {
127 throw new Error(
128 'Adapter "codex" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.',
129 )
130 }
131 return getSandbox(ctx)
132 }
133​
134 private workdir(options: TextOptions<CodexTextProviderOptions>): string {
135 return (
136 options.modelOptions?.workingDirectory ??
137 this.adapterConfig.cwd ??
138 DEFAULT_WORKDIR
139 )
140 }
141​
142 /** Mirror @openai/codex-sdk's `codex exec --experimental-json` invocation. */
143 private buildCommand(
144 options: TextOptions<CodexTextProviderOptions>,
145 resume: string | undefined,
146 bridge: HostToolBridge | undefined,
147 policyFlags: CodexPolicyFlags,
148 provider: string,
149 ): string {
150 const config = this.adapterConfig
151 const modelOptions = options.modelOptions
152 const exe = config.codexExecutable ?? 'codex'
153 const args: Array<string> = ['exec', '--experimental-json']
154​
155 // Precedence: per-call modelOptions > adapter config > sandbox policy >
156 // provider default. Daytona/Cloudflare cannot nest bubblewrap.
157 const sandboxMode =
158 modelOptions?.sandboxMode ??
159 config.sandboxMode ??
160 policyFlags.sandboxMode ??
161 defaultSandboxMode(provider)
162 const approvalPolicy =
163 modelOptions?.approvalPolicy ??
164 config.approvalPolicy ??
165 policyFlags.approvalPolicy ??
166 'never'
167 const networkAccessEnabled =
168 config.networkAccessEnabled ?? policyFlags.networkAccessEnabled
169 const reasoning =
170 modelOptions?.modelReasoningEffort ?? config.modelReasoningEffort
171 const skipGitRepoCheck =
172 modelOptions?.skipGitRepoCheck ?? config.skipGitRepoCheck
173​
174 args.push('--model', q(this.model))
175 args.push('--sandbox', q(sandboxMode))
176 // NOTE: do NOT pass `--cd <cwd>`. `cwd` is the VIRTUAL `/workspace` root; the
177 // provider handle already maps it to the sandbox's real workdir and runs the
178 // process there (e.g. Daytona's `/home/daytona/workspace`). Passing it as a
179 // literal `--cd` makes codex chdir to a path that doesn't exist on the real
180 // filesystem → "No such file or directory (os error 2)". Codex inherits the
181 // handle-set process cwd instead.
182 if (skipGitRepoCheck !== false) args.push('--skip-git-repo-check')
183 for (const dir of config.additionalDirectories ?? []) {
184 args.push('--add-dir', q(dir))
185 }
186​
187 const cfg: Record<string, string> = {
188 approval_policy: `"${approvalPolicy}"`,
189 ...(reasoning ? { model_reasoning_effort: `"${reasoning}"` } : {}),
190 ...(networkAccessEnabled !== undefined
191 ? {
192 'sandbox_workspace_write.network_access':
193 String(networkAccessEnabled),
194 }
195 : {}),
196 ...(config.webSearchMode
197 ? { web_search: `"${config.webSearchMode}"` }
198 : {}),
199 // Bridge chat()-provided tools via a streamable-HTTP MCP server. A `url`
200 // makes codex use its streamable-HTTP transport, which authenticates via an
201 // `Authorization` header — codex REJECTS inline `bearer_token` for this
202 // transport ("bearer_token is not supported for streamable_http"; that field
203 // is only for the stdio transport). Pass the per-run bearer as an HTTP header
204 // instead; the host tool-bridge checks `Authorization: Bearer <token>`.
205 ...(bridge
206 ? {
207 [`mcp_servers.${bridge.name}.url`]: `"${bridge.url}"`,
208 [`mcp_servers.${bridge.name}.http_headers`]: `{ "Authorization" = "Bearer ${bridge.token}" }`,
209 }
210 : {}),
211 ...config.config,
212 }
213 for (const [key, value] of Object.entries(cfg)) {
214 args.push('--config', q(`${key}=${value}`))
215 }
216​
217 // Resume an existing thread (mirrors the SDK's `resume <threadId>`).
218 if (resume !== undefined) args.push('resume', q(resume))
219​
220 return `${exe} ${args.join(' ')}`
221 }
222​
223 async *chatStream(
224 options: TextOptions<CodexTextProviderOptions>,
225 ): AsyncIterable<StreamChunk> {
226 const { logger } = options
227 let bridge: HostToolBridge | undefined
228 const tempFiles: Array<string> = []
229 let cleanupSandbox: SandboxHandle | undefined
230 // Durability caveat: the journaled path below derives its journal file
231 // path from `runId` alone (see `journalPaths` in `@tanstack/ai-sandbox`),
232 // and a successor host must recompute that same path to resume this run.
233 // That is only possible when the caller supplies a stable `runId`.
234 // `resolveDurableRunId` enforces that when durability is wired (both
235 // `runs` and `durability.adapter` given to `withSandbox`) and preserves
236 // the generated fallback — `this.generateId()`, a fresh random id every
237 // call — when it is not, so a non-durable run's behavior is unchanged.
238 const durability = options.capabilities
239 ? getSandboxDurability(options.capabilities, { optional: true })
240 : undefined
241 const runId = resolveDurableRunId(options.runId, {
242 durable: durability !== undefined,
243 adapter: 'codex',
244 fallback: () => this.generateId(),
245 })
246 // `threadId` is stamped on every chunk `translateThreadEvents` emits, so an
247 // ATTACHING run that mints a fresh one replays a stream the stored log
248 // cannot match at index 0. `resolveDurableThreadId` refuses that up front
249 // instead of letting alignment discover it mid-stream; a durable FRESH run
250 // and a non-durable run both keep the generated fallback untouched.
251 const threadId = resolveDurableThreadId(options.threadId, {
252 durable: durability !== undefined,
253 attaching: durability?.attach === true,
254 adapter: 'codex',
255 fallback: () => this.generateId(),
256 })
257 // Surfaces custom events from bridged tools (e.g. code mode console logs)
258 // on this run's live output stream.
259 const channel = createBridgeEventChannel({
260 model: this.model,
261 threadId,
262 runId,
263 })
264 try {
265 const sandbox = this.sandboxFrom(options)
266 cleanupSandbox = sandbox
267 const cwd = this.workdir(options)
268​
269 // Project declarative workspace inputs (MCP/skills) into codex's native
270 // format. Re-runs each call so rotated secrets re-apply; idempotent ops
271 // are marker-gated inside the projector.
272 const projection = options.capabilities
273 ? getWorkspaceProjection(options.capabilities, { optional: true })
274 : undefined
275 if (projection) await projectCodexWorkspace(sandbox, projection)
276​
277 if (options.tools && options.tools.length > 0) {
278 const provisioner =
279 (options.capabilities
280 ? getToolBridgeProvisioner(options.capabilities, { optional: true })
281 : undefined) ?? nodeHttpBridgeProvisioner
282 bridge = await provisioner.provision(options.tools, {
283 provider: sandbox.provider,
284 context: options.context,
285 emitCustomEvent: channel.emitCustomEvent,
286 ...(options.abortController?.signal
287 ? { signal: options.abortController.signal }
288 : {}),
289 })
290 }
291​
292 const { prompt, resume } = buildPrompt(
293 options.messages,
294 options.modelOptions?.sessionId,
295 )
296 const systemPrompts = normalizeSystemPrompts(options.systemPrompts)
297 .map((p) => p.content)
298 .filter((c) => c.trim() !== '')
299 const fullPrompt =
300 systemPrompts.length > 0
301 ? `${systemPrompts.join('\n\n')}\n\n${prompt}`
302 : prompt
303​
304 const policy = options.capabilities
305 ? getSandboxPolicy(options.capabilities, { optional: true })
306 : undefined
307 const command = this.buildCommand(
308 options,
309 resume,
310 bridge,
311 mapPolicyToCodexFlags(policy),
312 sandbox.provider,
313 )
314​
315 logger.request(
316 `activity=chat provider=codex model=${this.model} sandbox=${sandbox.provider} messages=${options.messages.length} resume=${resume ?? 'none'}`,
317 { provider: 'codex', model: this.model },
318 )
319​
320 // Deliver the prompt. Default: over stdin. Providers without a writable
321 // host→process stdin can't accept that — Docker's hijacked exec severs
322 // stdout when stdin EOF is signalled (losing the agent's output), and
323 // Cloudflare can't write stdin at all — so feed the prompt from a file
324 // (`codex exec … < file`) instead.
325 let runCommand = command
326 let stdinInput: string | undefined = fullPrompt
327 if (sandbox.capabilities.writableStdin === false) {
328 // Reuse the ALREADY-RESOLVED `runId`, not a fresh `options.runId ?? this.generateId()`
329 // re-derivation: the latter mints a SECOND random id whenever
330 // `options.runId` is absent, so the prompt file's suffix would not
331 // even match the journal path derived from the run's own `runId`
332 // above (see `resolveDurableRunId`). That mismatch is invisible
333 // (the prompt still gets read), but it defeats the whole point of a
334 // stable, caller-supplied `runId` for anything keyed off it.
335 // `encodeRunId`, because durability makes `runId` CALLER-chosen and this
336 // interpolates it into a filesystem path. Raw, a `/` would silently turn
337 // the basename into a nested path (writing outside `/tmp` or failing on a
338 // missing dir), `..` would climb out of it, and a long id would fail the
339 // spawn with `ENAMETOOLONG`. The encoder collapses every id to one
340 // bounded, injective path segment — the same one `journalPaths` uses, so
341 // the prompt file and the journal agree on how this id spells.
342 const promptPath = `/tmp/tanstack-codex-prompt-${encodeRunId(runId)}`
343 await sandbox.fs.write(promptPath, fullPrompt)
344 tempFiles.push(promptPath)
345 runCommand = `${command} < ${q(promptPath)}`
346 stdinInput = undefined
347 }
348​
349 // `undefined` whenever the run is not durable, so `spawnNdjson` takes its
350 // original, unjournaled path and behavior stays byte-identical to a
351 // pre-durability run. When durable, this also carries `attach`, which is
352 // how `spawnNdjson` decides to tail an EXISTING journal instead of
353 // starting a new agent — set by the attach route's `drive()` callback,
354 // never by an application's POST handler (see `SandboxDurabilityOptions.attach`).
355 const journalOptions = journalOptionsFor(durability, runId)
356​
357 const rawEvents = spawnNdjson(sandbox, runCommand, {
358 cwd,
359 ...(stdinInput !== undefined ? { input: stdinInput } : {}),
360 ...(this.adapterConfig.env ? { env: this.adapterConfig.env } : {}),
361 ...(options.abortController?.signal
362 ? { signal: options.abortController.signal }
363 : options.request?.signal
364 ? { signal: options.request.signal }
365 : {}),
366 onNonJsonLine: (line) =>
367 logger.provider(`provider=codex non-json line: ${line}`, {
368 chunk: line,
369 }),
370 // Route stdout through the in-sandbox journal so a resuming host can
371 // re-read it from byte 0 (see `@tanstack/ai-sandbox`'s journal.ts).
372 ...(journalOptions === undefined ? {} : { journal: journalOptions }),
373 })
374​
375 async function* asEvents(): AsyncIterable<CodexThreadEvent> {
376 for await (const event of rawEvents) yield event as CodexThreadEvent
377 }
378​
379 // Deterministic, run-scoped ids: journal replay re-translates the same
380 // journal bytes, and `this.generateId()` (Date.now() + Math.random())
381 // would mint different message ids on every replay. See
382 // chunk-identity.ts in `@tanstack/ai-sandbox` for why this is required.
383 const genId = createRunScopedIdGen(runId)
384​
385 // `mergeChunkStreams` below interleaves `translateThreadEvents`'s
386 // deterministic output with `channel.stream` (host-tool-bridge CUSTOM
387 // events from LIVE tool execution — see `createBridgeEventChannel`
388 // above). Those events do not occur on a replay, so a takeover's replay
389 // is NOT chunk-for-chunk identical to what the log holds.
390 // `alignedIfAttaching` handles it: alignment skips stored out-of-band
391 // CUSTOM entries within a bounded window (see `align.ts`), so a
392 // bridged-tool run can be taken over without a spurious
393 // `JournalReplayDivergedError`, while a genuine determinism regression
394 // still throws. It is a no-op (passes the stream through untouched)
395 // whenever the run is not durable or is not attaching, so a
396 // non-durable run's output is unaffected byte for byte.
397 //
398 // The wrap goes OUTSIDE `mergeChunkStreams`, never around the pre-merge
399 // translator alone: the stored log holds the previous host's MERGED
400 // output, so comparing against anything else would compare against a
401 // stream the log never contained.
402 yield* alignedIfAttaching(
403 mergeChunkStreams(
404 translateThreadEvents(asEvents(), {
405 model: this.model,
406 runId,
407 threadId,
408 ...(options.parentRunId !== undefined && {
409 parentRunId: options.parentRunId,
410 }),
411 genId,
412 onThreadEvent: (event) =>
413 logger.provider(`provider=codex type=${event.type}`, {
414 chunk: event,
415 }),
416 }),
417 channel.stream,
418 ),
419 durability,
420 logger,
421 )
422 } catch (error: unknown) {
423 const err = error as Error & { code?: string }
424 const rawEvent = toRunErrorRawEvent(error)
425 logger.errors('codex.chatStream fatal', {
426 error,
427 source: 'codex.chatStream',
428 })
429 yield {
430 type: EventType.RUN_ERROR,
431 model: options.model,
432 timestamp: Date.now(),
433 message: err.message || 'Unknown error occurred',
434 ...(err.code !== undefined && { code: err.code }),
435 ...(rawEvent !== undefined && { rawEvent }),
436 error: {
437 message: err.message || 'Unknown error occurred',
438 ...(err.code !== undefined && { code: err.code }),
439 },
440 }
441 } finally {
442 channel.close()
443 await bridge?.close()
444 if (cleanupSandbox) {
445 for (const path of tempFiles) {
446 try {
447 await cleanupSandbox.fs.remove(path)
448 } catch {
449 // already gone / sandbox torn down — nothing to clean up
450 }
451 }
452 }
453 }
454 }
455​
456 structuredOutput(
457 _options: StructuredOutputOptions<CodexTextProviderOptions>,
458 ): Promise<StructuredOutputResult<unknown>> {
459 return Promise.reject(
460 new Error(
461 'Structured output is not yet supported by the in-sandbox Codex adapter. ' +
462 'Use a model adapter for structured output, or omit outputSchema.',
463 ),
464 )
465 }
467​
468/**
469 * Creates a Codex harness adapter that runs **inside a sandbox**.
470 *
471 * It declares `requires: [SandboxCapability]` and spawns
472 * `codex exec --experimental-json` inside the sandbox (mirroring
473 * `@openai/codex-sdk`'s own CLI invocation), feeding the prompt via stdin and
474 * streaming its JSONL thread events back as AG-UI chunks. The sandbox image
475 * must provide the `codex` executable and `CODEX_API_KEY` (or a `codex login`)
476 * in its environment.
477 */
478export function codexText<TModel extends CodexModel>(
479 model: TModel,
480 config: CodexTextConfig = {},
481): CodexTextAdapter<TModel> {
482 return new CodexTextAdapter(config, model)