@tanstack/ai-acp 0.1.0

package/src/session/sandbox-server.ts

@@ -0,0 +1,195 @@
+import { connectAcpWebSocket } from '../transport/websocket'
+import type {
+  SandboxChannel,
+  SandboxHandle,
+  SpawnHandle,
+} from '@tanstack/ai-sandbox'
+import type { AcpMessageFraming } from '../transport/types'
+import type { AcpWebSocketConnection } from '../transport/websocket'
+
+export interface AcpSandboxServer {
+  /** WebSocket URL the orchestrator uses to reach the in-sandbox ACP server. */
+  wsUrl: string
+  /** Sandbox channel used to build {@link wsUrl} (auth headers, when issued). */
+  channel: SandboxChannel
+  /** Open the ACP JSON-RPC stream over WebSocket. */
+  connect: (signal?: AbortSignal) => Promise<AcpWebSocketConnection>
+  /** Stop the in-sandbox server process. */
+  dispose: () => Promise<void>
+}
+
+export interface StartAcpServerOptions {
+  port: number
+  cwd: string
+  /** Full shell command that starts the harness ACP server inside the sandbox. */
+  command: string
+  /** Build the WebSocket URL once the server is ready and the port is exposed. */
+  buildWsUrl: (input: {
+    channel: SandboxChannel
+    port: number
+    stdout: string
+  }) => string
+  /**
+   * Return true once {@link buildWsUrl} can be called. Receives accumulated
+   * stdout from the server process.
+   */
+  isReady?: (stdout: string) => boolean
+  /** Substring/regex marker used when {@link isReady} is omitted. */
+  readyMarker?: string
+  env?: Record<string, string>
+  timeoutMs?: number
+  signal?: AbortSignal
+  framing?: AcpMessageFraming
+  hostname?: string
+}
+
+const DEFAULT_READY_MARKER = 'WebSocket URL:'
+
+function waitForReady(
+  proc: SpawnHandle,
+  options: Pick<StartAcpServerOptions, 'isReady' | 'readyMarker' | 'timeoutMs'>,
+): Promise<{ stdout: string; stderr: string }> {
+  const readyMarker = options.readyMarker ?? DEFAULT_READY_MARKER
+  const isReady =
+    options.isReady ?? ((output: string) => output.includes(readyMarker))
+
+  return new Promise((resolve, reject) => {
+    let stdout = ''
+    let stderr = ''
+    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 combined = (): string => stdout + stderr
+    let stdoutDone = false
+    let stderrDone = false
+    const tryFinish = (): void => {
+      if (state.settled) return
+      if (isReady(combined())) {
+        settle(() => resolve({ stdout, stderr }))
+        return
+      }
+      if (stdoutDone && stderrDone) {
+        settle(() =>
+          reject(
+            new Error(
+              `ACP server exited before becoming ready${
+                diagnostics() ? `: ${diagnostics()}` : ' (no output)'
+              }`,
+            ),
+          ),
+        )
+      }
+    }
+
+    const timer = setTimeout(
+      () =>
+        settle(() =>
+          reject(
+            new Error(
+              `ACP server did not become ready within ${options.timeoutMs ?? 30_000}ms${
+                diagnostics() ? `: ${diagnostics()}` : ''
+              }`,
+            ),
+          ),
+        ),
+      options.timeoutMs ?? 30_000,
+    )
+
+    void (async () => {
+      try {
+        for await (const chunk of proc.stderr) {
+          stderr += chunk
+          tryFinish()
+          if (state.settled) return
+        }
+      } catch {
+        // non-fatal
+      } finally {
+        stderrDone = true
+        tryFinish()
+      }
+    })()
+
+    void (async () => {
+      try {
+        for await (const chunk of proc.stdout) {
+          stdout += chunk
+          tryFinish()
+          if (state.settled) return
+        }
+      } catch (error) {
+        settle(() => reject(error))
+        return
+      } finally {
+        stdoutDone = true
+        tryFinish()
+      }
+    })()
+  })
+}
+
+/**
+ * Boot a harness ACP WebSocket server inside a sandbox and expose its port via
+ * {@link SandboxHandle.ports.connect}. Mirrors the `opencode serve` pattern.
+ */
+export async function startAcpServerInSandbox(
+  sandbox: SandboxHandle,
+  options: StartAcpServerOptions,
+): Promise<AcpSandboxServer> {
+  const proc = await sandbox.process.spawn(options.command, {
+    cwd: options.cwd,
+    ...(options.env ? { env: options.env } : {}),
+    ...(options.signal ? { signal: options.signal } : {}),
+  })
+
+  const { stdout } = await waitForReady(proc, options)
+  const channel = await sandbox.ports.connect(options.port)
+  const wsUrl = options.buildWsUrl({
+    channel,
+    port: options.port,
+    stdout,
+  })
+
+  const headers =
+    channel.headers ??
+    (channel.token ? { Authorization: `Bearer ${channel.token}` } : undefined)
+
+  return {
+    wsUrl,
+    channel,
+    connect: (signal?: AbortSignal) =>
+      connectAcpWebSocket(wsUrl, {
+        ...(headers ? { headers } : {}),
+        ...(signal ? { signal } : {}),
+        framing: options.framing ?? 'frame',
+      }),
+    dispose: () => proc.kill(),
+  }
+}
+
+/** Parse a `WebSocket URL: ws://…` line printed by `grok agent serve`. */
+export function parseWebSocketUrlFromServeOutput(
+  output: string,
+): string | undefined {
+  const match = output.match(/WebSocket URL:\s*(ws\S+)/i)
+  return match?.[1]
+}
+
+/** Build a Grok `agent serve` WebSocket URL from a sandbox channel + secret. */
+export function buildGrokServeWebSocketUrl(
+  channelUrl: string,
+  secret: string,
+): string {
+  const wsBase = channelUrl.replace(/^http/i, 'ws').replace(/\/$/, '')
+  return `${wsBase}/ws?server-key=${encodeURIComponent(secret)}`
+}

package/src/stream/queue.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal promise-based async queue bridging callback-style ACP 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)
+    }
+  }
+
+  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 })
+    }
+  }
+
+  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 })
+        })
+      },
+    }
+  }
+}

package/src/stream/translate.ts

@@ -0,0 +1,412 @@
+import { EventType, buildBaseUsage } from '@tanstack/ai'
+import type { StreamChunk, TokenUsage } from '@tanstack/ai'
+import type {
+  AcpSessionUpdate,
+  AcpStopReason,
+  AcpToolCallUpdate,
+  AcpUsage,
+} from '../types/acp-types'
+
+export const BRIDGED_MCP_SERVER_NAME = 'tanstack'
+
+export type AcpStreamEvent =
+  | { kind: 'session'; sessionId: string }
+  | { kind: 'update'; update: AcpSessionUpdate }
+  | { kind: 'done'; stopReason: AcpStopReason; usage?: AcpUsage }
+
+export interface AcpTranslateLabels {
+  sessionIdEvent: string
+  planEvent?: string
+  refusalMessage?: string
+  /**
+   * When set, non-text agent message content (image / audio / resource /
+   * resource_link blocks) is surfaced as a CUSTOM event under this name instead
+   * of being dropped. Each event's `value` is `{ content: <ACP content block> }`.
+   * Omit to keep the text-only behavior.
+   */
+  contentEvent?: string
+}
+
+export interface TranslateContext {
+  model: string
+  runId: string
+  threadId: string
+  parentRunId?: string
+  genId: () => string
+  labels: AcpTranslateLabels
+  bridgedToolNames?: ReadonlySet<string>
+  onAcpEvent?: (event: AcpStreamEvent) => void
+}
+
+export function matchBridgedToolName(
+  title: string | null | undefined,
+  bridgedToolNames: ReadonlySet<string> | undefined,
+): string | undefined {
+  if (!title || !bridgedToolNames) return undefined
+  if (bridgedToolNames.has(title)) return title
+  for (const name of bridgedToolNames) {
+    if (title.startsWith(`${name} (`)) return name
+  }
+  return undefined
+}
+
+function resolveToolName(
+  update: AcpToolCallUpdate,
+  bridgedToolNames: ReadonlySet<string> | undefined,
+): string {
+  return (
+    matchBridgedToolName(update.title, bridgedToolNames) ??
+    update.kind ??
+    'tool'
+  )
+}
+
+function stringifyToolOutput(update: AcpToolCallUpdate): string {
+  if (update.rawOutput !== undefined) {
+    return typeof update.rawOutput === 'string'
+      ? update.rawOutput
+      : JSON.stringify(update.rawOutput)
+  }
+  const blocks = update.content ?? []
+  const text = blocks
+    .map((block) =>
+      block.content && typeof block.content.text === 'string'
+        ? block.content.text
+        : '',
+    )
+    .join('')
+  // Preserve non-text tool content (diff / terminal / image / resource blocks)
+  // by serializing the structured array, rather than collapsing to a stub.
+  const hasNonText = blocks.some(
+    (block) =>
+      block.type !== 'content' ||
+      (block.content !== undefined && block.content.type !== 'text'),
+  )
+  if (hasNonText) return JSON.stringify(blocks)
+  if (text !== '') return text
+  return JSON.stringify({ status: update.status ?? 'completed' })
+}
+
+function buildUsage(usage: AcpUsage | undefined): TokenUsage | undefined {
+  if (!usage) return undefined
+  const promptTokens = usage.inputTokens ?? 0
+  const completionTokens = usage.outputTokens ?? 0
+  const result = buildBaseUsage({
+    promptTokens,
+    completionTokens,
+    totalTokens: usage.totalTokens ?? promptTokens + completionTokens,
+  })
+  if (usage.cachedReadTokens) {
+    result.promptTokensDetails = { cachedTokens: usage.cachedReadTokens }
+  }
+  if (usage.thoughtTokens) {
+    result.completionTokensDetails = { reasoningTokens: usage.thoughtTokens }
+  }
+  return result
+}
+
+export async function* translateAcpStream(
+  events: AsyncIterable<AcpStreamEvent>,
+  ctx: TranslateContext,
+): AsyncIterable<StreamChunk> {
+  const { model, runId, threadId, genId, labels } = ctx
+  const now = () => Date.now()
+
+  let runStarted = false
+  const unresolvedToolCalls = new Set<string>()
+  const knownToolCalls = new Set<string>()
+
+  let textMessageId: string | null = null
+  let textContent = ''
+  let reasoningId: string | null = null
+
+  function* startRun(): Generator<StreamChunk> {
+    if (runStarted) return
+    runStarted = true
+    yield {
+      type: EventType.RUN_STARTED,
+      runId,
+      threadId,
+      model,
+      timestamp: now(),
+      ...(ctx.parentRunId !== undefined && { parentRunId: ctx.parentRunId }),
+    }
+  }
+
+  function* closeText(): Generator<StreamChunk> {
+    if (textMessageId !== null) {
+      yield {
+        type: EventType.TEXT_MESSAGE_END,
+        messageId: textMessageId,
+        model,
+        timestamp: now(),
+      }
+    }
+    textMessageId = null
+    textContent = ''
+  }
+
+  function* closeReasoning(): Generator<StreamChunk> {
+    if (reasoningId !== null) {
+      yield {
+        type: EventType.REASONING_MESSAGE_END,
+        messageId: reasoningId,
+        model,
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.REASONING_END,
+        messageId: reasoningId,
+        model,
+        timestamp: now(),
+      }
+    }
+    reasoningId = null
+  }
+
+  function* synthesizeUnresolvedResults(): Generator<StreamChunk> {
+    for (const toolCallId of unresolvedToolCalls) {
+      yield {
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId,
+        messageId: genId(),
+        model,
+        timestamp: now(),
+        content: JSON.stringify({ status: 'interrupted' }),
+      }
+    }
+    unresolvedToolCalls.clear()
+  }
+
+  function* openToolCall(update: AcpToolCallUpdate): Generator<StreamChunk> {
+    if (knownToolCalls.has(update.toolCallId)) return
+    knownToolCalls.add(update.toolCallId)
+    const toolCallName = resolveToolName(update, ctx.bridgedToolNames)
+    const input = {
+      ...(update.title != null && { title: update.title }),
+      ...(update.rawInput !== undefined && update.rawInput !== null
+        ? typeof update.rawInput === 'object'
+          ? (update.rawInput as Record<string, unknown>)
+          : { input: update.rawInput }
+        : {}),
+    }
+    const args = JSON.stringify(input)
+    yield {
+      type: EventType.TOOL_CALL_START,
+      toolCallId: update.toolCallId,
+      toolCallName,
+      toolName: toolCallName,
+      model,
+      timestamp: now(),
+    }
+    yield {
+      type: EventType.TOOL_CALL_ARGS,
+      toolCallId: update.toolCallId,
+      model,
+      timestamp: now(),
+      delta: args,
+      args,
+    }
+    yield {
+      type: EventType.TOOL_CALL_END,
+      toolCallId: update.toolCallId,
+      toolCallName,
+      toolName: toolCallName,
+      model,
+      timestamp: now(),
+      input,
+    }
+    unresolvedToolCalls.add(update.toolCallId)
+  }
+
+  function* resolveToolCall(update: AcpToolCallUpdate): Generator<StreamChunk> {
+    yield* openToolCall(update)
+    unresolvedToolCalls.delete(update.toolCallId)
+    yield {
+      type: EventType.TOOL_CALL_RESULT,
+      toolCallId: update.toolCallId,
+      messageId: genId(),
+      model,
+      timestamp: now(),
+      content: stringifyToolOutput(update),
+      ...(update.status === 'failed' && { state: 'output-error' as const }),
+    }
+  }
+
+  function* handleUpdate(update: AcpSessionUpdate): Generator<StreamChunk> {
+    if (update.sessionUpdate === 'agent_message_chunk') {
+      yield* closeReasoning()
+      // Non-text content (image / audio / resource / resource_link): surface it
+      // as a CUSTOM event when the harness opted in, instead of dropping it.
+      if (update.content.type !== 'text') {
+        if (labels.contentEvent !== undefined) {
+          yield* closeText()
+          yield {
+            type: EventType.CUSTOM,
+            model,
+            timestamp: now(),
+            name: labels.contentEvent,
+            value: { content: update.content },
+          }
+        }
+        return
+      }
+      const text =
+        typeof update.content.text === 'string' ? update.content.text : ''
+      if (text === '') return
+      if (textMessageId === null) {
+        textMessageId = genId()
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId: textMessageId,
+          model,
+          timestamp: now(),
+          role: 'assistant',
+        }
+      }
+      textContent += text
+      yield {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: textMessageId,
+        model,
+        timestamp: now(),
+        delta: text,
+        content: textContent,
+      }
+    } else if (update.sessionUpdate === 'agent_thought_chunk') {
+      yield* closeText()
+      const thought =
+        typeof update.content.text === 'string' ? update.content.text : ''
+      if (thought === '') return
+      if (reasoningId === null) {
+        reasoningId = genId()
+        yield {
+          type: EventType.REASONING_START,
+          messageId: reasoningId,
+          model,
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.REASONING_MESSAGE_START,
+          messageId: reasoningId,
+          role: 'reasoning' as const,
+          model,
+          timestamp: now(),
+        }
+      }
+      yield {
+        type: EventType.REASONING_MESSAGE_CONTENT,
+        messageId: reasoningId,
+        delta: thought,
+        model,
+        timestamp: now(),
+      }
+    } else if (update.sessionUpdate === 'tool_call') {
+      yield* closeText()
+      yield* closeReasoning()
+      yield* openToolCall(update)
+      if (update.status === 'completed' || update.status === 'failed') {
+        yield* resolveToolCall(update)
+      }
+    } else if (update.sessionUpdate === 'tool_call_update') {
+      if (update.status === 'completed' || update.status === 'failed') {
+        yield* resolveToolCall(update)
+      } else if (
+        update.status === 'in_progress' &&
+        update.rawInput !== undefined
+      ) {
+        yield* closeText()
+        yield* closeReasoning()
+        if (!knownToolCalls.has(update.toolCallId)) {
+          yield* openToolCall(update)
+        } else {
+          const input = {
+            ...(update.title != null && { title: update.title }),
+            ...(typeof update.rawInput === 'object' && update.rawInput !== null
+              ? (update.rawInput as Record<string, unknown>)
+              : { input: update.rawInput }),
+          }
+          const args = JSON.stringify(input)
+          yield {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: update.toolCallId,
+            model,
+            timestamp: now(),
+            delta: args,
+            args,
+          }
+        }
+      }
+    } else if (
+      update.sessionUpdate === 'plan' &&
+      labels.planEvent !== undefined
+    ) {
+      yield {
+        type: EventType.CUSTOM,
+        model,
+        timestamp: now(),
+        name: labels.planEvent,
+        value: { entries: update.entries },
+      }
+    }
+  }
+
+  try {
+    for await (const event of events) {
+      ctx.onAcpEvent?.(event)
+
+      if (event.kind === 'session') {
+        yield* startRun()
+        yield {
+          type: EventType.CUSTOM,
+          model,
+          timestamp: now(),
+          name: labels.sessionIdEvent,
+          value: { sessionId: event.sessionId },
+        }
+      } else if (event.kind === 'update') {
+        yield* startRun()
+        yield* handleUpdate(event.update)
+      } else {
+        yield* startRun()
+        yield* closeText()
+        yield* closeReasoning()
+        yield* synthesizeUnresolvedResults()
+
+        if (event.stopReason === 'refusal') {
+          const message =
+            labels.refusalMessage ?? 'The harness refused the request.'
+          yield {
+            type: EventType.RUN_ERROR,
+            model,
+            timestamp: now(),
+            message,
+            code: 'refusal',
+            error: { message, code: 'refusal' },
+          }
+        } else {
+          const usage = buildUsage(event.usage)
+          const finishReason =
+            event.stopReason === 'max_tokens' ||
+            event.stopReason === 'max_turn_requests'
+              ? ('length' as const)
+              : ('stop' as const)
+          yield {
+            type: EventType.RUN_FINISHED,
+            runId,
+            threadId,
+            model,
+            timestamp: now(),
+            finishReason,
+            ...(usage !== undefined && { usage }),
+          }
+        }
+      }
+    }
+  } catch (error) {
+    yield* closeText()
+    yield* closeReasoning()
+    yield* synthesizeUnresolvedResults()
+    throw error
+  }
+}

package/src/transport/resolve.ts

@@ -0,0 +1,46 @@
+import type { SandboxHandle } from '@tanstack/ai-sandbox'
+import type { AcpTransportPreference } from './types'
+
+/**
+ * Pick stdio vs WebSocket for ACP based on sandbox capabilities and caller
+ * preference.
+ */
+export function resolveAcpTransportMode(
+  sandbox: SandboxHandle,
+  preference: AcpTransportPreference = 'auto',
+): 'stdio' | 'websocket' {
+  if (preference === 'stdio') {
+    if (sandbox.capabilities.writableStdin !== true) {
+      throw new Error(
+        `${sandbox.provider}: ACP stdio transport requires capabilities.writableStdin, but this sandbox cannot write to process stdin. Use transport: 'websocket' or 'auto'.`,
+      )
+    }
+    return 'stdio'
+  }
+
+  if (preference === 'websocket') {
+    if (sandbox.capabilities.ports !== true) {
+      throw new Error(
+        `${sandbox.provider}: ACP WebSocket transport requires capabilities.ports so the harness server can be reached from the orchestrator.`,
+      )
+    }
+    if (sandbox.capabilities.backgroundProcesses !== true) {
+      throw new Error(
+        `${sandbox.provider}: ACP WebSocket transport requires capabilities.backgroundProcesses to run the in-sandbox harness server.`,
+      )
+    }
+    return 'websocket'
+  }
+
+  if (sandbox.capabilities.writableStdin === true) return 'stdio'
+  if (
+    sandbox.capabilities.ports === true &&
+    sandbox.capabilities.backgroundProcesses === true
+  ) {
+    return 'websocket'
+  }
+
+  throw new Error(
+    `${sandbox.provider}: cannot run ACP — no writable stdin and no port-exposed background-process support. Use a Docker/local-process sandbox or enable ports on the provider.`,
+  )
+}