@tanstack/ai-opencode 0.1.0

package/src/model-meta.ts

@@ -0,0 +1,24 @@
+/**
+ * Models known to work with OpenCode. OpenCode is provider-agnostic — it
+ * resolves any `provider/model` id its configured providers support (via the
+ * Vercel AI SDK + Models.dev), so this list exists for autocomplete. Any
+ * string is accepted via the `(string & {})` escape hatch in
+ * {@link OpencodeModel}.
+ *
+ * Models are addressed as `provider_id/model_id` (e.g.
+ * `anthropic/claude-sonnet-4-5`); the adapter splits on the first `/`.
+ */
+export const OPENCODE_MODELS = [
+  'anthropic/claude-opus-4-5',
+  'anthropic/claude-sonnet-4-5',
+  'openai/gpt-5.2',
+  'openai/gpt-5.1-codex',
+  'google/gemini-3-pro-preview',
+  'opencode/claude-sonnet-4-5',
+  'opencode/gpt-5.1-codex',
+] as const
+
+export type KnownOpencodeModel = (typeof OPENCODE_MODELS)[number]
+
+/** Any `provider/model` id accepted by OpenCode; known ids get autocomplete. */
+export type OpencodeModel = KnownOpencodeModel | (string & {})

package/src/process/permissions.ts

@@ -0,0 +1,119 @@
+import { approvalId } from '@tanstack/ai-sandbox'
+
+/**
+ * Permission modes for the OpenCode adapter, mirroring the Claude Code and
+ * Gemini CLI adapters' semantics:
+ *
+ * - `'default'`: bridged TanStack tools run; anything else that asks for
+ *   permission is rejected with no prompt (a headless server must never hang
+ *   on an interactive question).
+ * - `'acceptEdits'`: additionally auto-approves file-mutation requests
+ *   (edit / write / patch).
+ * - `'bypassPermissions'`: approves everything.
+ */
+export type OpencodePermissionMode =
+  | 'default'
+  | 'acceptEdits'
+  | 'bypassPermissions'
+
+/** Structural subset of an OpenCode `permission.updated` payload. */
+export interface OpencodePermissionRequest {
+  id: string
+  sessionID: string
+  /** Permission category, e.g. `'edit'`, `'bash'`, `'webfetch'`, a tool id. */
+  type: string
+  title: string
+  /** Tool call id this permission gates, when it gates a tool. */
+  callID?: string
+}
+
+/** OpenCode permission reply: allow once, allow always, or reject. */
+export type OpencodePermissionResponse = 'once' | 'always' | 'reject'
+
+/** Custom permission handler; replaces the adapter's default policy. */
+export type PermissionHandler = (
+  request: OpencodePermissionRequest,
+) => Promise<OpencodePermissionResponse> | OpencodePermissionResponse
+
+/** Permission categories treated as file mutations for `'acceptEdits'`. */
+const EDIT_TYPES = new Set(['edit', 'write', 'patch'])
+
+/**
+ * Decide whether an OpenCode permission request targets one of the bridged
+ * TanStack tools. OpenCode names MCP tools `<server>_<tool>` (e.g.
+ * `tanstack_lookup_user`), so a request is bridged when its type or title is
+ * a registered tool name, or carries the `tanstack` server prefix.
+ */
+export function matchBridgedToolName(
+  request: OpencodePermissionRequest,
+  bridgedToolNames: ReadonlySet<string> | undefined,
+): boolean {
+  if (!bridgedToolNames || bridgedToolNames.size === 0) return false
+  for (const field of [request.type, request.title]) {
+    if (typeof field !== 'string' || field === '') continue
+    if (bridgedToolNames.has(field)) return true
+    if (field.startsWith('tanstack_') && bridgedToolNames.has(field.slice(9))) {
+      return true
+    }
+    if (field.startsWith('tanstack.') && bridgedToolNames.has(field.slice(9))) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * The adapter's default permission policy. Always answers immediately — never
+ * hangs a headless server on a question only an interactive user could
+ * answer.
+ */
+export function resolvePermission(
+  request: OpencodePermissionRequest,
+  mode: OpencodePermissionMode,
+  bridgedToolNames: ReadonlySet<string> | undefined,
+): OpencodePermissionResponse {
+  if (matchBridgedToolName(request, bridgedToolNames)) {
+    return 'once'
+  }
+  if (mode === 'bypassPermissions') {
+    return 'once'
+  }
+  if (mode === 'acceptEdits' && EDIT_TYPES.has(request.type)) {
+    return 'once'
+  }
+  return 'reject'
+}
+
+/**
+ * Interactive variant: when the mode/bridge policy would reject, consult the
+ * client's approval decisions. Returns the OpenCode response plus, when the
+ * action still needs a client decision, the `approvalId`/`title` the adapter
+ * should surface via an `approval-requested` event.
+ */
+export function resolveInteractivePermission(
+  request: OpencodePermissionRequest,
+  mode: OpencodePermissionMode,
+  bridgedToolNames: ReadonlySet<string> | undefined,
+  approvals: ReadonlyMap<string, boolean> | undefined,
+): {
+  response: OpencodePermissionResponse
+  approvalId?: string
+  title?: string
+} {
+  if (matchBridgedToolName(request, bridgedToolNames))
+    return { response: 'once' }
+  if (mode === 'bypassPermissions') return { response: 'once' }
+  if (mode === 'acceptEdits' && EDIT_TYPES.has(request.type)) {
+    return { response: 'once' }
+  }
+
+  const id = approvalId({
+    provider: 'opencode',
+    kind: 'tool',
+    target: request.type || request.title,
+  })
+  const granted = approvals?.get(id)
+  if (granted === true) return { response: 'once' }
+  if (granted === false) return { response: 'reject' }
+  return { response: 'reject', approvalId: id, title: request.title }
+}

package/src/process/sandbox-server.ts

@@ -0,0 +1,130 @@
+/**
+ * Boot an `opencode serve` HTTP server INSIDE a sandbox and expose its port so
+ * the host `@opencode-ai/sdk` client can connect over `baseUrl`. Mirrors the
+ * SDK's own server launch (`opencode serve --hostname=H --port=P`, ready when
+ * stdout logs `opencode server listening`).
+ */
+import type { SandboxHandle, SpawnHandle } from '@tanstack/ai-sandbox'
+
+const READY_MARKER = 'opencode server listening'
+
+export interface SandboxOpencodeServer {
+  /** URL the host uses to reach the in-sandbox server. */
+  baseUrl: string
+  /**
+   * Headers that authenticate requests to {@link baseUrl}, when the provider's
+   * channel is token-gated (e.g. Daytona's `x-daytona-preview-token`). The host
+   * opencode client must send these on every request or the preview proxy 404s.
+   */
+  headers?: Record<string, string>
+  /** Stop the server process. */
+  dispose: () => Promise<void>
+}
+
+export interface StartServerOptions {
+  port: number
+  hostname?: string
+  cwd: string
+  /** Extra env for the server process (e.g. `OPENCODE_CONFIG_CONTENT`). */
+  env?: Record<string, string>
+  timeoutMs?: number
+  signal?: AbortSignal
+}
+
+export async function startOpencodeServerInSandbox(
+  sandbox: SandboxHandle,
+  options: StartServerOptions,
+): Promise<SandboxOpencodeServer> {
+  const hostname = options.hostname ?? '0.0.0.0'
+  const command = `opencode serve --hostname=${hostname} --port=${options.port}`
+  const proc: SpawnHandle = await sandbox.process.spawn(command, {
+    cwd: options.cwd,
+    ...(options.env ? { env: options.env } : {}),
+    ...(options.signal ? { signal: options.signal } : {}),
+  })
+
+  await waitForReady(proc, options.timeoutMs ?? 30_000)
+
+  const channel = await sandbox.ports.connect(options.port)
+  // Carry the channel's auth so the host client can reach a token-gated preview.
+  // Prefer ready-made `headers`; fall back to a bearer token if that's all the
+  // provider issued.
+  const headers =
+    channel.headers ??
+    (channel.token ? { Authorization: `Bearer ${channel.token}` } : undefined)
+  return {
+    baseUrl: channel.url,
+    ...(headers ? { headers } : {}),
+    dispose: () => proc.kill(),
+  }
+}
+
+function waitForReady(proc: SpawnHandle, timeoutMs: number): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let stdout = ''
+    // Capture stderr too: opencode logs startup failures (e.g. "address already
+    // in use" when a previous run's server still holds the port) to stderr, not
+    // stdout. Without this the error message is empty and the real cause is lost.
+    let stderr = ''
+    // Holder object so reads stay typed as `boolean` across async closures
+    // (a plain `let` gets flow-narrowed to a literal and trips lint).
+    const state = { settled: false }
+    const settle = (fn: () => void): void => {
+      if (state.settled) return
+      state.settled = true
+      clearTimeout(timer)
+      fn()
+    }
+    const diagnostics = (): string =>
+      [stdout, stderr]
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .join('\n')
+        .slice(-500)
+    const timer = setTimeout(
+      () =>
+        settle(() =>
+          reject(
+            new Error(
+              `opencode serve did not become ready within ${timeoutMs}ms${
+                diagnostics() ? `: ${diagnostics()}` : ''
+              }`,
+            ),
+          ),
+        ),
+      timeoutMs,
+    )
+
+    // Drain stderr in the background so its text is available for diagnostics.
+    void (async () => {
+      try {
+        for await (const chunk of proc.stderr) stderr += chunk
+      } catch {
+        // Ignore: stderr drain errors are non-fatal; stdout drives readiness.
+      }
+    })()
+
+    void (async () => {
+      try {
+        for await (const chunk of proc.stdout) {
+          stdout += chunk
+          if (stdout.includes(READY_MARKER)) {
+            settle(resolve)
+            return
+          }
+        }
+        settle(() =>
+          reject(
+            new Error(
+              `opencode serve exited before becoming ready${
+                diagnostics() ? `: ${diagnostics()}` : ' (no output)'
+              }`,
+            ),
+          ),
+        )
+      } catch (error) {
+        settle(() => reject(error))
+      }
+    })()
+  })
+}

package/src/process/server.ts

@@ -0,0 +1,270 @@
+import { createOpencode, createOpencodeClient } from '@opencode-ai/sdk'
+import type { Config, Event, OpencodeClient, Part } from '@opencode-ai/sdk'
+import type {
+  OpencodeAssistantMessage,
+  OpencodeEvent,
+} from '../stream/sdk-types'
+import type {
+  OpencodePermissionRequest,
+  OpencodePermissionResponse,
+} from './permissions'
+
+/** A live OpenCode session backed by an `opencode serve` HTTP server. */
+export interface OpencodeSessionHandle {
+  sessionId: string
+  /** Whether an existing session was actually resumed. */
+  resumed: boolean
+  /**
+   * Run one prompt turn. Resolves with the final assistant message (finish
+   * reason, token usage, error) and its concatenated text once the harness
+   * goes idle. Streaming deltas arrive via `onEvent` while this is pending.
+   */
+  prompt: (
+    text: string,
+  ) => Promise<{ message: OpencodeAssistantMessage; text: string }>
+  /** Ask the harness to abort the in-flight prompt turn. */
+  abort: () => Promise<void>
+  /** Tear down the event subscription and (if owned) the server. */
+  dispose: () => Promise<void>
+}
+
+export interface StartOpencodeSessionOptions {
+  /** Connect to an already-running server instead of spawning one. */
+  baseUrl?: string
+  /**
+   * Headers attached to every request to the opencode server — used to
+   * authenticate a token-gated preview channel (e.g. Daytona). Without them a
+   * gated preview proxy rejects the requests (404 "Not found.").
+   */
+  headers?: Record<string, string>
+  /** Hostname for the spawned server. Defaults to the SDK default. */
+  hostname?: string
+  /** Port for the spawned server. Defaults to the SDK default. */
+  port?: number
+  /**
+   * Directory the opencode HTTP API scopes the session to. Omit to use the
+   * server's own launch cwd (the common case): the server is spawned with the
+   * correct working dir per-provider, so passing a directory here is only needed
+   * to override it. Passing a VIRTUAL sandbox path (e.g. `/workspace`) is wrong
+   * for host-running providers (local-process), where that path doesn't exist —
+   * the API then stalls on it. Leave undefined and rely on the server cwd.
+   */
+  directory?: string
+  /** Provider id (the part before `/` in the model id). */
+  providerID: string
+  /** Model id (the part after `/` in the model id). */
+  modelID: string
+  /** Extra OpenCode config merged with the adapter's mcp/permission config. */
+  config?: Config
+  /** Baseline permission policy applied to the spawned server. */
+  permission?: Config['permission']
+  /** MCP servers (e.g. the TanStack tool bridge) for the session. */
+  mcpServers?: Array<{ name: string; url: string }>
+  /** Session id to resume; falls back to a fresh session when not found. */
+  resumeSessionId?: string
+  onEvent: (event: OpencodeEvent) => void
+  onPermissionRequest: (
+    request: OpencodePermissionRequest,
+  ) => Promise<OpencodePermissionResponse> | OpencodePermissionResponse
+  /** Called when the event subscription fails mid-turn. */
+  onError?: (error: unknown) => void
+}
+
+/** Locate the session id an OpenCode event belongs to, when it carries one. */
+function sessionIdOf(event: Event): string | undefined {
+  const props = event.properties as { sessionID?: string } | undefined
+  if (props?.sessionID !== undefined) return props.sessionID
+  if (event.type === 'message.part.updated') {
+    return event.properties.part.sessionID
+  }
+  if (event.type === 'message.updated') {
+    return event.properties.info.sessionID
+  }
+  if (event.type === 'permission.updated') {
+    return event.properties.sessionID
+  }
+  return undefined
+}
+
+function buildConfig(options: StartOpencodeSessionOptions): Config {
+  const mcp: NonNullable<Config['mcp']> = { ...options.config?.mcp }
+  for (const server of options.mcpServers ?? []) {
+    mcp[server.name] = { type: 'remote', url: server.url, enabled: true }
+  }
+  return {
+    ...options.config,
+    ...(Object.keys(mcp).length > 0 && { mcp }),
+    ...(options.permission !== undefined && { permission: options.permission }),
+  }
+}
+
+/**
+ * Boot (or attach to) an OpenCode HTTP server, resolve a session, and wire its
+ * event subscription + permission replies.
+ *
+ * This module is the only place that touches `@opencode-ai/sdk`; the rest of
+ * the package works with the structural types in `sdk-types.ts`.
+ *
+ * Resume semantics: when `resumeSessionId` is set and the server still knows
+ * the session (same machine, same data dir), it is reused. Otherwise a fresh
+ * session is created and `resumed: false` tells the adapter to send the
+ * flattened transcript.
+ */
+export async function startOpencodeSession(
+  options: StartOpencodeSessionOptions,
+): Promise<OpencodeSessionHandle> {
+  const { directory } = options
+  // Spread into a `query` object only when set; omitting lets opencode use the
+  // server's launch cwd (correct for every provider — see `directory` docs).
+  const dirQuery = directory !== undefined ? { directory } : {}
+
+  let client: OpencodeClient
+  let ownedServer: { close: () => void } | undefined
+
+  if (options.baseUrl !== undefined) {
+    client = createOpencodeClient({
+      baseUrl: options.baseUrl,
+      ...(options.headers !== undefined && { headers: options.headers }),
+      ...(directory !== undefined && { directory }),
+    })
+  } else {
+    const config = buildConfig(options)
+    const result = await createOpencode({
+      ...(options.hostname !== undefined && { hostname: options.hostname }),
+      ...(options.port !== undefined && { port: options.port }),
+      ...(Object.keys(config).length > 0 && { config }),
+    })
+    client = result.client
+    ownedServer = result.server
+  }
+
+  // Mutated from several closures (the subscription loop, dispose, teardown);
+  // a holder object keeps reads typed as `boolean` rather than being
+  // flow-narrowed to a literal across those boundaries.
+  const lifecycle = { disposed: false }
+
+  const teardown = async (): Promise<void> => {
+    if (lifecycle.disposed) return
+    lifecycle.disposed = true
+    ownedServer?.close()
+    await Promise.resolve()
+  }
+
+  try {
+    // Resolve the session before subscribing so the event filter has an id.
+    let sessionId: string | undefined
+    let resumed = false
+    if (options.resumeSessionId !== undefined) {
+      const existing = await client.session.get({
+        path: { id: options.resumeSessionId },
+        query: dirQuery,
+      })
+      if (existing.data) {
+        sessionId = options.resumeSessionId
+        resumed = true
+      }
+    }
+    if (sessionId === undefined) {
+      const created = await client.session.create({
+        query: dirQuery,
+        body: {},
+        throwOnError: true,
+      })
+      sessionId = created.data.id
+    }
+    const resolvedSessionId = sessionId
+
+    const handlePermission = async (
+      permission: Extract<Event, { type: 'permission.updated' }>['properties'],
+    ): Promise<void> => {
+      try {
+        const response = await options.onPermissionRequest({
+          id: permission.id,
+          sessionID: permission.sessionID,
+          type: permission.type,
+          title: permission.title,
+          ...(permission.callID !== undefined && { callID: permission.callID }),
+        })
+        await client.postSessionIdPermissionsPermissionId({
+          path: { id: permission.sessionID, permissionID: permission.id },
+          query: dirQuery,
+          body: { response },
+          throwOnError: true,
+        })
+      } catch (error) {
+        if (!lifecycle.disposed) options.onError?.(error)
+      }
+    }
+
+    const subscription = await client.event.subscribe()
+    const stream = subscription.stream
+
+    void (async () => {
+      try {
+        for await (const event of stream) {
+          if (lifecycle.disposed) break
+          const sid = sessionIdOf(event)
+          if (sid !== undefined && sid !== resolvedSessionId) continue
+          if (event.type === 'permission.updated') {
+            void handlePermission(event.properties)
+            continue
+          }
+          // The SDK event union is a structural superset of the subset the
+          // translator consumes; unknown event types match no translator
+          // branch and are ignored.
+          options.onEvent(event as OpencodeEvent)
+        }
+      } catch (error) {
+        if (!lifecycle.disposed) options.onError?.(error)
+      }
+    })()
+
+    return {
+      sessionId: resolvedSessionId,
+      resumed,
+      prompt: async (text: string) => {
+        const result = await client.session.prompt({
+          path: { id: resolvedSessionId },
+          query: dirQuery,
+          body: {
+            model: { providerID: options.providerID, modelID: options.modelID },
+            parts: [{ type: 'text', text }],
+          },
+          throwOnError: true,
+        })
+        const data = result.data
+        const message = data.info as OpencodeAssistantMessage
+        const responseText = data.parts
+          .filter(
+            (part): part is Extract<Part, { type: 'text' }> =>
+              part.type === 'text',
+          )
+          .map((part) => part.text)
+          .join('')
+        return { message, text: responseText }
+      },
+      abort: async () => {
+        try {
+          await client.session.abort({
+            path: { id: resolvedSessionId },
+            query: dirQuery,
+          })
+        } catch {
+          // Best-effort: the turn may already be finishing.
+        }
+      },
+      dispose: async () => {
+        lifecycle.disposed = true
+        try {
+          await stream.return(undefined)
+        } catch {
+          // Ignore: stream may already be closed.
+        }
+        ownedServer?.close()
+      },
+    }
+  } catch (error) {
+    await teardown()
+    throw error
+  }
+}

package/src/provider-options.ts

@@ -0,0 +1,19 @@
+import type { OpencodePermissionMode } from './process/permissions'
+
+/**
+ * Per-call provider options for the OpenCode adapter, passed via
+ * `modelOptions` on `chat()`.
+ */
+export interface OpencodeTextProviderOptions {
+  /**
+   * Resume an existing OpenCode session. The adapter emits the session id of
+   * every fresh run via a CUSTOM `opencode.session-id` stream event; thread
+   * it back here to continue that session (only the latest user message is
+   * sent — the harness already holds the prior context).
+   */
+  sessionId?: string
+  /** Per-call override of the configured permission mode. */
+  permissionMode?: OpencodePermissionMode
+  /** Per-call override of the harness working directory. */
+  directory?: string
+}

package/src/stream/queue.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal promise-based async queue bridging the OpenCode event
+ * subscription's callback-style notifications into the async-iterable world
+ * the stream translator consumes.
+ */
+export class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly values: Array<T> = []
+  private readonly waiters: Array<{
+    resolve: (result: IteratorResult<T>) => void
+    reject: (error: unknown) => void
+  }> = []
+  private ended = false
+  private error: unknown = undefined
+  private failed = false
+
+  push(value: T): void {
+    if (this.ended || this.failed) return
+    const waiter = this.waiters.shift()
+    if (waiter) {
+      waiter.resolve({ value, done: false })
+    } else {
+      this.values.push(value)
+    }
+  }
+
+  /** Signal normal completion; pending and future reads resolve as done. */
+  end(): void {
+    if (this.ended || this.failed) return
+    this.ended = true
+    for (const waiter of this.waiters.splice(0)) {
+      waiter.resolve({ value: undefined, done: true })
+    }
+  }
+
+  /** Signal failure; pending and future reads reject (after buffered values drain). */
+  fail(error: unknown): void {
+    if (this.ended || this.failed) return
+    this.failed = true
+    this.error = error
+    for (const waiter of this.waiters.splice(0)) {
+      waiter.reject(error)
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: (): Promise<IteratorResult<T>> => {
+        if (this.values.length > 0) {
+          return Promise.resolve({
+            value: this.values.shift() as T,
+            done: false,
+          })
+        }
+        if (this.failed) return Promise.reject(this.error)
+        if (this.ended) {
+          return Promise.resolve({ value: undefined, done: true })
+        }
+        return new Promise((resolve, reject) => {
+          this.waiters.push({ resolve, reject })
+        })
+      },
+    }
+  }
+}