@tanstack/ai-acp 0.1.0

package/src/transport/stdio.ts

@@ -0,0 +1,63 @@
+/**
+ * Adapt a sandbox {@link SpawnHandle} into byte streams for ACP stdio
+ * (newline-delimited JSON-RPC).
+ */
+import type { SpawnHandle } from '@tanstack/ai-sandbox'
+import type { AcpByteTransport } from './types'
+
+export function spawnHandleToAcpTransport(
+  handle: SpawnHandle,
+): AcpByteTransport {
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+
+  const readable = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        for await (const chunk of handle.stdout) {
+          controller.enqueue(encoder.encode(chunk))
+        }
+        controller.close()
+      } catch (error) {
+        controller.error(error)
+      }
+    },
+  })
+
+  const writable = new WritableStream<Uint8Array>({
+    write(chunk) {
+      return handle.stdin.write(decoder.decode(chunk))
+    },
+    close() {
+      return handle.stdin.end()
+    },
+  })
+
+  let tail = ''
+  void (async () => {
+    try {
+      for await (const chunk of handle.stderr) {
+        tail = (tail + chunk).slice(-4096)
+      }
+    } catch {
+      // stderr closed
+    }
+  })()
+
+  const exited: Promise<never> = handle.wait().then((code) => {
+    throw new Error(
+      `ACP harness process exited unexpectedly (code ${code}).${
+        tail.trim() !== '' ? `\nstderr: ${tail.trim()}` : ''
+      }`,
+    )
+  })
+  void exited.catch(() => undefined)
+
+  return {
+    writable,
+    readable,
+    exited,
+    stderrTail: () => tail,
+    kill: () => handle.kill(),
+  }
+}

package/src/transport/types.ts

@@ -0,0 +1,33 @@
+import type { ndJsonStream } from '@agentclientprotocol/sdk'
+import type { SpawnHandle } from '@tanstack/ai-sandbox'
+
+/** How JSON-RPC messages are framed on the wire. */
+export type AcpMessageFraming = 'ndjson' | 'frame'
+
+/**
+ * Byte-level duplex transport consumed by {@link ndJsonStream} for stdio
+ * harnesses.
+ */
+export interface AcpByteTransport {
+  writable: WritableStream<Uint8Array>
+  readable: ReadableStream<Uint8Array>
+  /** Resolves (throws) when the underlying connection exits unexpectedly. */
+  exited: Promise<never>
+  /** Last bytes of stderr, for error messages. */
+  stderrTail: () => string
+  kill: () => Promise<void>
+}
+
+/** Parsed JSON-RPC object streams passed to {@link ClientSideConnection}. */
+export type AcpJsonRpcStream = ReturnType<typeof ndJsonStream>
+
+export type AcpSessionTransport =
+  | { kind: 'stdio'; process: SpawnHandle }
+  | {
+      kind: 'stream'
+      stream: AcpJsonRpcStream
+      dispose: () => Promise<void>
+      stderrTail?: () => string
+    }
+
+export type AcpTransportPreference = 'auto' | 'stdio' | 'websocket'

package/src/transport/websocket.ts

@@ -0,0 +1,192 @@
+import { ndJsonStream } from '@agentclientprotocol/sdk'
+import type { AcpJsonRpcStream, AcpMessageFraming } from './types'
+
+function waitForWebSocketOpen(
+  ws: WebSocket,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (ws.readyState === WebSocket.OPEN) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    const onOpen = (): void => {
+      cleanup()
+      resolve()
+    }
+    const onError = (): void => {
+      cleanup()
+      reject(new Error('WebSocket connection failed'))
+    }
+    const onAbort = (): void => {
+      cleanup()
+      ws.close()
+      reject(signal?.reason ?? new Error('WebSocket connection aborted'))
+    }
+    const cleanup = (): void => {
+      ws.removeEventListener('open', onOpen)
+      ws.removeEventListener('error', onError)
+      signal?.removeEventListener('abort', onAbort)
+    }
+    ws.addEventListener('open', onOpen)
+    ws.addEventListener('error', onError)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * Wrap a stream controller so its terminal calls are idempotent. A WebSocket can
+ * fire `close` after `error` (or after the reader cancels), and closing/erroring
+ * an already-settled controller throws `ERR_INVALID_STATE` out of the listener.
+ */
+function idempotentController<T>(
+  controller: ReadableStreamDefaultController<T>,
+): {
+  enqueue: (chunk: T) => void
+  close: () => void
+  error: (reason: unknown) => void
+} {
+  let settled = false
+  return {
+    enqueue: (chunk) => {
+      if (!settled) controller.enqueue(chunk)
+    },
+    close: () => {
+      if (settled) return
+      settled = true
+      controller.close()
+    },
+    error: (reason) => {
+      if (settled) return
+      settled = true
+      controller.error(reason)
+    },
+  }
+}
+
+/**
+ * One JSON-RPC object per WebSocket text frame (e.g. `grok agent serve`).
+ */
+export function webSocketFrameToAcpStream(ws: WebSocket): AcpJsonRpcStream {
+  const decoder = new TextDecoder()
+
+  const readable = new ReadableStream<unknown>({
+    start(rawController) {
+      const controller = idempotentController(rawController)
+      ws.addEventListener('message', (event) => {
+        const text =
+          typeof event.data === 'string'
+            ? event.data
+            : decoder.decode(event.data as ArrayBuffer)
+        const trimmed = text.trim()
+        if (trimmed === '') return
+        try {
+          controller.enqueue(JSON.parse(trimmed))
+        } catch (error) {
+          controller.error(
+            error instanceof Error ? error : new Error(String(error)),
+          )
+        }
+      })
+      ws.addEventListener('close', () => controller.close())
+      ws.addEventListener('error', () =>
+        controller.error(new Error('WebSocket connection error')),
+      )
+    },
+    cancel() {
+      ws.close()
+    },
+  })
+
+  const writable = new WritableStream({
+    write(message) {
+      ws.send(JSON.stringify(message))
+    },
+    close() {
+      ws.close()
+    },
+  })
+
+  return { readable, writable } as AcpJsonRpcStream
+}
+
+function webSocketNdjsonToAcpStream(ws: WebSocket): AcpJsonRpcStream {
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+
+  const readable = new ReadableStream<Uint8Array>({
+    start(rawController) {
+      const controller = idempotentController(rawController)
+      ws.addEventListener('message', (event) => {
+        const text =
+          typeof event.data === 'string'
+            ? event.data
+            : decoder.decode(event.data as ArrayBuffer)
+        controller.enqueue(encoder.encode(text))
+      })
+      ws.addEventListener('close', () => controller.close())
+      ws.addEventListener('error', () =>
+        controller.error(new Error('WebSocket connection error')),
+      )
+    },
+    cancel() {
+      ws.close()
+    },
+  })
+
+  const writable = new WritableStream<Uint8Array>({
+    write(chunk) {
+      ws.send(chunk)
+    },
+    close() {
+      ws.close()
+    },
+  })
+
+  return ndJsonStream(writable, readable)
+}
+
+export interface ConnectAcpWebSocketOptions {
+  headers?: Record<string, string>
+  signal?: AbortSignal
+  framing?: AcpMessageFraming
+}
+
+export interface AcpWebSocketConnection {
+  stream: AcpJsonRpcStream
+  close: () => void
+}
+
+/**
+ * Open a WebSocket to an in-sandbox ACP server and adapt it for
+ * {@link ClientSideConnection}.
+ */
+function openWebSocket(
+  url: string,
+  headers?: Record<string, string>,
+): WebSocket {
+  if (headers === undefined) return new WebSocket(url)
+  // Node/ws accepts `{ headers }`; DOM lib constructor types omit this overload.
+  return Reflect.construct(WebSocket, [url, { headers }]) as WebSocket
+}
+
+export async function connectAcpWebSocket(
+  url: string,
+  options: ConnectAcpWebSocketOptions = {},
+): Promise<AcpWebSocketConnection> {
+  const ws = openWebSocket(url, options.headers)
+  await waitForWebSocketOpen(ws, options.signal)
+
+  const framing = options.framing ?? 'frame'
+  const stream =
+    framing === 'ndjson'
+      ? webSocketNdjsonToAcpStream(ws)
+      : webSocketFrameToAcpStream(ws)
+
+  return {
+    stream,
+    close: () => ws.close(),
+  }
+}
+
+/** Convert an HTTP sandbox channel URL to a WebSocket base URL. */
+export function httpChannelUrlToWsBase(channelUrl: string): string {
+  return channelUrl.replace(/^http/i, 'ws').replace(/\/$/, '')
+}

package/src/types/acp-types.ts

@@ -0,0 +1,79 @@
+/**
+ * Structural subset of the Agent Client Protocol (ACP) types that harness
+ * adapters consume.
+ *
+ * Defined structurally (rather than imported from `@agentclientprotocol/sdk`)
+ * so the stream translator stays a pure, fixture-testable state machine.
+ */
+
+export type AcpContentBlock =
+  | { type: 'text'; text: string }
+  | { type: string; [key: string]: unknown }
+
+export type AcpToolCallStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'completed'
+  | 'failed'
+
+export interface AcpToolCallUpdate {
+  toolCallId: string
+  title?: string | null
+  kind?: string | null
+  status?: AcpToolCallStatus | null
+  rawInput?: unknown
+  rawOutput?: unknown
+  content?: Array<{
+    type: string
+    content?: AcpContentBlock
+    [key: string]: unknown
+  }> | null
+}
+
+export type AcpSessionUpdate =
+  | { sessionUpdate: 'agent_message_chunk'; content: AcpContentBlock }
+  | { sessionUpdate: 'agent_thought_chunk'; content: AcpContentBlock }
+  | ({ sessionUpdate: 'tool_call' } & AcpToolCallUpdate)
+  | ({ sessionUpdate: 'tool_call_update' } & AcpToolCallUpdate)
+  | { sessionUpdate: 'plan'; entries: Array<unknown> }
+  | { sessionUpdate: 'available_commands_update' }
+  | { sessionUpdate: 'current_mode_update' }
+  | { sessionUpdate: 'user_message_chunk'; content: AcpContentBlock }
+
+export type AcpStopReason =
+  | 'end_turn'
+  | 'max_tokens'
+  | 'max_turn_requests'
+  | 'refusal'
+  | 'cancelled'
+  | (string & {})
+
+export interface AcpUsage {
+  inputTokens?: number | null
+  outputTokens?: number | null
+  totalTokens?: number | null
+  cachedReadTokens?: number | null
+  thoughtTokens?: number | null
+}
+
+export interface AcpPermissionOption {
+  optionId: string
+  name: string
+  kind: 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always'
+}
+
+export interface AcpPermissionRequest {
+  sessionId: string
+  toolCall: AcpToolCallUpdate
+  options: Array<AcpPermissionOption>
+}
+
+export type AcpPermissionOutcome =
+  | { outcome: 'cancelled' }
+  | { outcome: 'selected'; optionId: string }
+
+export type AcpPermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions'
+
+export type PermissionHandler = (
+  request: AcpPermissionRequest,
+) => Promise<AcpPermissionOutcome> | AcpPermissionOutcome