@tanstack/ai-acp 0.1.0

package/src/adapters/projection.ts

@@ -0,0 +1,164 @@
+/**
+ * Generic workspace projector for ACP harnesses.
+ *
+ * `withSandbox` surfaces a portable {@link WorkspaceProjection} (skills, plugins,
+ * a secret resolver, a one-time marker path) via a capability. Most of it maps
+ * onto ACP natively:
+ *
+ *   - **MCP skills** → passed straight through ACP's `newSession` `mcpServers`
+ *     (see {@link workspaceMcpServers}); no config file is written, because an
+ *     ACP agent receives MCP servers over the protocol. This is the key
+ *     difference from file-based harnesses (Claude Code, Codex) that read MCP
+ *     from disk.
+ *   - **gitSkill repos** → linked into the harness's skills directory (when the
+ *     harness declares one via `skillsDir`, e.g. `.pi/skills`).
+ *   - **agentSkill / plugins** → no generic ACP primitive, so we warn-and-skip.
+ *
+ * `fileSkill` and `instructions` are already written by the provider-agnostic
+ * bootstrap (into the workspace root + `AGENTS.md`), so they need no projection.
+ */
+import { isSecretRef, resolveGitSkillDir } from '@tanstack/ai-sandbox'
+import type {
+  BearerRef,
+  SandboxHandle,
+  SecretRef,
+  WorkspaceProjection,
+} from '@tanstack/ai-sandbox'
+
+/** ACP `newSession` MCP server descriptor (HTTP transport). */
+export interface AcpMcpServer {
+  name: string
+  url: string
+  headers: Array<{ name: string; value: string }>
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+function basenameOf(path: string): string {
+  const segments = path.split('/').filter((segment) => segment !== '')
+  return segments[segments.length - 1] ?? path
+}
+
+/**
+ * Make a sandbox path relative to the workspace root, so shell commands work on
+ * every provider. Only `fs.*` remaps the virtual `/workspace`; a raw `/workspace`
+ * in a shell command is the real path in a container but a non-existent absolute
+ * path on local-process. Running relative to the root (the exec cwd) is correct
+ * everywhere.
+ */
+function relativeToRoot(root: string, p: string): string {
+  return p.startsWith(`${root}/`) ? p.slice(root.length + 1) : p
+}
+
+function isBearerMarker(value: unknown): value is BearerRef {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    isSecretRef((value as { __bearerRef?: unknown }).__bearerRef)
+  )
+}
+
+function resolveHeaderValue(
+  value: string | SecretRef | BearerRef,
+  resolveSecret: (ref: SecretRef) => string,
+): string {
+  if (isSecretRef(value)) return resolveSecret(value)
+  if (isBearerMarker(value)) return `Bearer ${resolveSecret(value.__bearerRef)}`
+  return value
+}
+
+/**
+ * Build ACP `mcpServers` entries from the workspace's `mcp` skills, resolving
+ * every header value (SecretRef / bearer / plain string). Returns `[]` when
+ * there are no MCP skills. Pass the result to `startAcpSession({ mcpServers })`.
+ */
+export function workspaceMcpServers(
+  projection: WorkspaceProjection,
+): Array<AcpMcpServer> {
+  const servers: Array<AcpMcpServer> = []
+  for (const skill of projection.skills) {
+    if (skill.kind !== 'mcp') continue
+    const rawUrl = skill.config['url']
+    const url = typeof rawUrl === 'string' ? rawUrl : ''
+    const headers = Object.entries(skill.config.headers ?? {}).map(
+      ([name, value]) => ({
+        name,
+        value: resolveHeaderValue(value, projection.resolveSecret),
+      }),
+    )
+    servers.push({ name: skill.name, url, headers })
+  }
+  return servers
+}
+
+/**
+ * Project the non-MCP parts of a workspace into an ACP harness. Links each
+ * cloned `gitSkill` repo into the harness's skills directory when one is
+ * declared; warns and skips `agentSkill`s, `plugin`s, and (when no `skillsDir`
+ * is configured) `gitSkill`s. Idempotent — gated by the projection marker.
+ *
+ * MCP skills are NOT handled here; pass {@link workspaceMcpServers} to the ACP
+ * session instead.
+ */
+export async function projectAcpWorkspace(
+  handle: SandboxHandle,
+  projection: WorkspaceProjection,
+  options: { skillsDir?: string; harnessName: string },
+): Promise<void> {
+  // Idempotent, non-secret operations only — gate on the one-time marker.
+  if (await handle.fs.exists(projection.markerPath)) return
+
+  const { skillsDir, harnessName } = options
+  const gitSkills = projection.skills.filter((skill) => skill.kind === 'git')
+
+  if (gitSkills.length > 0) {
+    if (skillsDir === undefined) {
+      for (const skill of gitSkills) {
+        console.warn(
+          `[${harnessName}] gitSkill "${skill.repo}" cannot be projected: this ` +
+            'harness declares no `skillsDir`. The clone is still available under ' +
+            'the workspace, but the harness will not auto-discover it. Skipping link.',
+        )
+      }
+    } else {
+      // Create the skills dir via fs (which remaps the virtual root), then copy
+      // each clone in with paths relative to the exec cwd (the workspace root)
+      // so the shell command resolves on every provider.
+      await handle.fs.mkdir(`${projection.root}/${skillsDir}`)
+      for (const skill of gitSkills) {
+        const source = skill.into ?? resolveGitSkillDir(projection.root, skill)
+        const relSource = relativeToRoot(projection.root, source)
+        const relTarget = `${skillsDir}/${basenameOf(source)}`
+        const cp = await handle.process.exec(
+          `cp -r ${shellQuote(relSource)} ${shellQuote(relTarget)}`,
+          { cwd: projection.root },
+        )
+        if (cp.exitCode !== 0) {
+          console.warn(
+            `[${harnessName}] failed to copy gitSkill "${skill.repo}" into ${relTarget}: ${cp.stderr.trim()}`,
+          )
+        }
+      }
+    }
+  }
+
+  for (const skill of projection.skills) {
+    if (skill.kind === 'agent-skill') {
+      console.warn(
+        `[${harnessName}] agentSkill "${skill.name}" cannot be projected: there is ` +
+          'no generic ACP primitive to install a skill by bare name. Provide it as ' +
+          'a gitSkill instead. Skipping.',
+      )
+    }
+  }
+  for (const name of projection.plugins) {
+    console.warn(
+      `[${harnessName}] plugin "${name}" cannot be projected: ACP has no generic ` +
+        'plugin concept. Provide its functionality as a gitSkill or MCP server. Skipping.',
+    )
+  }
+
+  await handle.fs.write(projection.markerPath, '')
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+export type {
+  AcpContentBlock,
+  AcpPermissionMode,
+  AcpPermissionOption,
+  AcpPermissionOutcome,
+  AcpPermissionRequest,
+  AcpSessionUpdate,
+  AcpStopReason,
+  AcpToolCallStatus,
+  AcpToolCallUpdate,
+  AcpUsage,
+  PermissionHandler,
+} from './types/acp-types'
+
+export { AsyncQueue } from './stream/queue'
+
+export {
+  BRIDGED_MCP_SERVER_NAME,
+  matchBridgedToolName,
+  translateAcpStream,
+} from './stream/translate'
+export type {
+  AcpStreamEvent,
+  AcpTranslateLabels,
+  TranslateContext,
+} from './stream/translate'
+
+export type {
+  AcpByteTransport,
+  AcpJsonRpcStream,
+  AcpMessageFraming,
+  AcpSessionTransport,
+  AcpTransportPreference,
+} from './transport/types'
+
+export { spawnHandleToAcpTransport } from './transport/stdio'
+export type { AcpByteTransport as AcpTransport } from './transport/types'
+
+export {
+  connectAcpWebSocket,
+  httpChannelUrlToWsBase,
+  webSocketFrameToAcpStream,
+} from './transport/websocket'
+export type {
+  AcpWebSocketConnection,
+  ConnectAcpWebSocketOptions,
+} from './transport/websocket'
+
+export { resolveAcpTransportMode } from './transport/resolve'
+
+export {
+  buildGrokServeWebSocketUrl,
+  parseWebSocketUrlFromServeOutput,
+  startAcpServerInSandbox,
+} from './session/sandbox-server'
+export type {
+  AcpSandboxServer,
+  StartAcpServerOptions,
+} from './session/sandbox-server'
+
+export { startAcpSession } from './session/acp-client'
+export type {
+  AcpSessionHandle,
+  StartAcpSessionOptions,
+} from './session/acp-client'
+
+export { resolveInteractivePermission, resolvePermission } from './permissions'
+
+export {
+  AcpCompatibleTextAdapter,
+  acpCompatible,
+  acpCompatibleText,
+} from './adapters/compatible'
+export type {
+  AcpCompatibleConfig,
+  AcpCompatibleProviderOptions,
+  AcpHarnessContext,
+  AcpModelNameOf,
+} from './adapters/compatible'
+
+export { buildAcpPrompt } from './messages/prompt'
+export type { BuiltAcpPrompt } from './messages/prompt'
+
+export { projectAcpWorkspace, workspaceMcpServers } from './adapters/projection'
+export type { AcpMcpServer } from './adapters/projection'

package/src/messages/prompt.ts

@@ -0,0 +1,71 @@
+import type { ModelMessage } from '@tanstack/ai'
+
+export interface BuiltAcpPrompt {
+  prompt: string
+  /** Harness session id to resume, when the caller threaded one through. */
+  resume?: string
+}
+
+function extractText(content: ModelMessage['content']): string {
+  if (content === null) return ''
+  if (typeof content === 'string') return content
+  return content
+    .map((part) =>
+      part.type === 'text' && typeof part.content === 'string'
+        ? part.content
+        : '',
+    )
+    .join('')
+}
+
+/**
+ * Convert TanStack chat history into a harness prompt + resume inputs.
+ *
+ * With a `sessionId`, the harness already holds the conversation context, so
+ * only the trailing user message is sent and the session is resumed. Without
+ * one, prior user/assistant turns are flattened into a plain-text transcript
+ * preamble (tool messages and tool-call-only assistant turns are
+ * harness-internal noise and are skipped; prompts are text-only).
+ *
+ * Shared default for ACP harness adapters; pass a custom `buildPrompt` to
+ * {@link acpCompatible} to override.
+ */
+export function buildAcpPrompt(
+  messages: Array<ModelMessage>,
+  sessionId: string | undefined,
+  harnessName = 'ACP harness',
+): BuiltAcpPrompt {
+  const lastMessage = messages.at(-1)
+  const lastUserText =
+    lastMessage?.role === 'user' ? extractText(lastMessage.content).trim() : ''
+
+  if (!lastUserText) {
+    throw new Error(
+      `${harnessName} adapter requires a trailing user message with text content.`,
+    )
+  }
+
+  if (sessionId !== undefined) {
+    return { prompt: lastUserText, resume: sessionId }
+  }
+
+  const priorTurns = messages
+    .slice(0, -1)
+    .filter(
+      (message) =>
+        (message.role === 'user' || message.role === 'assistant') &&
+        extractText(message.content).trim() !== '',
+    )
+    .map(
+      (message) =>
+        `${message.role === 'user' ? 'User' : 'Assistant'}: ${extractText(message.content).trim()}`,
+    )
+
+  if (priorTurns.length === 0) {
+    return { prompt: lastUserText }
+  }
+
+  return {
+    prompt: `Previous conversation:\n${priorTurns.join('\n')}\n\n${lastUserText}`,
+  }
+}

package/src/permissions.ts

@@ -0,0 +1,71 @@
+import { approvalId } from '@tanstack/ai-sandbox'
+import { matchBridgedToolName } from './stream/translate'
+import type {
+  AcpPermissionMode,
+  AcpPermissionOutcome,
+  AcpPermissionRequest,
+  PermissionHandler,
+} from './types/acp-types'
+
+export type { AcpPermissionMode, PermissionHandler }
+
+const EDIT_KINDS = new Set(['edit', 'move', 'delete'])
+
+function pickOption(
+  request: AcpPermissionRequest,
+  kinds: Array<string>,
+): AcpPermissionOutcome {
+  for (const kind of kinds) {
+    const option = request.options.find((candidate) => candidate.kind === kind)
+    if (option) return { outcome: 'selected', optionId: option.optionId }
+  }
+  return { outcome: 'cancelled' }
+}
+
+export function resolvePermission(
+  request: AcpPermissionRequest,
+  mode: AcpPermissionMode,
+  bridgedToolNames: ReadonlySet<string> | undefined,
+): AcpPermissionOutcome {
+  const allow = () => pickOption(request, ['allow_once', 'allow_always'])
+  const reject = () => pickOption(request, ['reject_once', 'reject_always'])
+
+  if (
+    matchBridgedToolName(request.toolCall.title, bridgedToolNames) !== undefined
+  ) {
+    return allow()
+  }
+  if (mode === 'bypassPermissions') return allow()
+  if (mode === 'acceptEdits' && EDIT_KINDS.has(request.toolCall.kind ?? '')) {
+    return allow()
+  }
+  return reject()
+}
+
+export function resolveInteractivePermission(
+  request: AcpPermissionRequest,
+  mode: AcpPermissionMode,
+  bridgedToolNames: ReadonlySet<string> | undefined,
+  approvals: ReadonlyMap<string, boolean> | undefined,
+  provider: string,
+): { outcome: AcpPermissionOutcome; approvalId?: string; title?: string } {
+  const allow = (): AcpPermissionOutcome =>
+    pickOption(request, ['allow_once', 'allow_always'])
+  const reject = (): AcpPermissionOutcome =>
+    pickOption(request, ['reject_once', 'reject_always'])
+  const title = request.toolCall.title ?? request.toolCall.toolCallId
+
+  if (matchBridgedToolName(title, bridgedToolNames) !== undefined) {
+    return { outcome: allow() }
+  }
+  if (mode === 'bypassPermissions') return { outcome: allow() }
+  if (mode === 'acceptEdits' && EDIT_KINDS.has(request.toolCall.kind ?? '')) {
+    return { outcome: allow() }
+  }
+
+  const id = approvalId({ provider, kind: 'tool', target: title })
+  const granted = approvals?.get(id)
+  if (granted === true) return { outcome: allow() }
+  if (granted === false) return { outcome: reject() }
+  return { outcome: reject(), approvalId: id, title }
+}

package/src/session/acp-client.ts

@@ -0,0 +1,238 @@
+import {
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  ndJsonStream,
+} from '@agentclientprotocol/sdk'
+import { spawnHandleToAcpTransport } from '../transport/stdio'
+import type {
+  Client,
+  McpServer,
+  RequestPermissionRequest,
+  RequestPermissionResponse,
+  SessionNotification,
+} from '@agentclientprotocol/sdk'
+import type {
+  AcpPermissionOutcome,
+  AcpPermissionRequest,
+  AcpSessionUpdate,
+  AcpStopReason,
+  AcpUsage,
+} from '../types/acp-types'
+import type { AcpJsonRpcStream, AcpSessionTransport } from '../transport/types'
+
+/**
+ * Identifies this client to the agent in the ACP `initialize` handshake. The
+ * `version` is informational (sent in `clientInfo`); keep it loosely in step
+ * with the package version. `clientInfo` is currently optional in the protocol
+ * but will become required, so we always send it.
+ * ponytail: hardcoded — clientInfo is diagnostic; a stale patch version is harmless.
+ */
+const CLIENT_INFO = {
+  name: '@tanstack/ai-acp',
+  title: 'TanStack AI',
+  version: '0.1.0',
+} as const
+
+export interface AcpSessionHandle {
+  sessionId: string
+  resumed: boolean
+  prompt: (
+    text: string,
+  ) => Promise<{ stopReason: AcpStopReason; usage?: AcpUsage }>
+  cancel: () => Promise<void>
+  dispose: () => Promise<void>
+}
+
+export interface StartAcpSessionOptions {
+  transport: AcpSessionTransport
+  cwd: string
+  authMethodId?: string
+  mcpServers?: Array<{
+    name: string
+    url: string
+    headers?: Array<{ name: string; value: string }>
+  }>
+  resumeSessionId?: string
+  onUpdate: (update: AcpSessionUpdate) => void
+  onPermissionRequest: (
+    request: AcpPermissionRequest,
+  ) => Promise<AcpPermissionOutcome> | AcpPermissionOutcome
+  /**
+   * Harness-specific JSON-RPC notifications (e.g. Grok `_x.ai/session_notification`).
+   * Return without throwing — unknown vendor extensions must not tear down the session.
+   */
+  onExtNotification?: (method: string, params: Record<string, unknown>) => void
+}
+
+function streamFromTransport(transport: AcpSessionTransport): {
+  stream: AcpJsonRpcStream
+  teardown: () => Promise<void>
+  exited: Promise<never> | undefined
+  stderrTail: () => string
+} {
+  if (transport.kind === 'stdio') {
+    const byteTransport = spawnHandleToAcpTransport(transport.process)
+    return {
+      stream: ndJsonStream(byteTransport.writable, byteTransport.readable),
+      teardown: () => byteTransport.kill(),
+      exited: byteTransport.exited,
+      stderrTail: byteTransport.stderrTail,
+    }
+  }
+
+  return {
+    stream: transport.stream,
+    teardown: transport.dispose,
+    exited: undefined,
+    stderrTail: transport.stderrTail ?? (() => ''),
+  }
+}
+
+/**
+ * Drive an ACP harness over stdio or a pre-connected JSON-RPC stream.
+ */
+export async function startAcpSession(
+  options: StartAcpSessionOptions,
+): Promise<AcpSessionHandle> {
+  const { stream, teardown, exited, stderrTail } = streamFromTransport(
+    options.transport,
+  )
+
+  let replaying = false
+
+  const client: Client = {
+    requestPermission: async (
+      params: RequestPermissionRequest,
+    ): Promise<RequestPermissionResponse> => {
+      const outcome = await options.onPermissionRequest(params)
+      return { outcome }
+    },
+    sessionUpdate: (params: SessionNotification): Promise<void> => {
+      if (!replaying) {
+        options.onUpdate(params.update as AcpSessionUpdate)
+      }
+      return Promise.resolve()
+    },
+    extNotification: (method, params) => {
+      options.onExtNotification?.(method, params)
+      return Promise.resolve()
+    },
+  }
+
+  const race = <T>(work: Promise<T>): Promise<T> =>
+    exited !== undefined ? Promise.race([work, exited]) : work
+
+  try {
+    const connection = new ClientSideConnection(() => client, stream)
+
+    const initResult = await race(
+      connection.initialize({
+        protocolVersion: PROTOCOL_VERSION,
+        clientInfo: CLIENT_INFO,
+        clientCapabilities: {
+          // The agent runs inside the sandbox with direct filesystem + shell
+          // access, so it never needs to delegate file/terminal I/O back to the
+          // client. We advertise these as unsupported; per the ACP spec the
+          // agent MUST then treat them as unavailable and not call them.
+          fs: { readTextFile: false, writeTextFile: false },
+        },
+      }),
+    )
+
+    // Protocol-version negotiation: the agent echoes the version it will speak.
+    // The spec says a client SHOULD close the connection if that version is one
+    // it doesn't support. We only implement the current PROTOCOL_VERSION, so a
+    // higher number means the agent needs a newer client than this one.
+    if (
+      typeof initResult.protocolVersion === 'number' &&
+      initResult.protocolVersion > PROTOCOL_VERSION
+    ) {
+      throw new Error(
+        `ACP agent negotiated protocol version ${initResult.protocolVersion}, ` +
+          `but this client supports up to ${PROTOCOL_VERSION}. Update @tanstack/ai-acp.`,
+      )
+    }
+
+    if (options.authMethodId !== undefined) {
+      const available = initResult.authMethods ?? []
+      if (!available.some((method) => method.id === options.authMethodId)) {
+        throw new Error(
+          `Harness does not advertise the ACP auth method '${options.authMethodId}'. Available: ${
+            available.map((method) => method.id).join(', ') || '(none)'
+          }.`,
+        )
+      }
+      await race(connection.authenticate({ methodId: options.authMethodId }))
+    }
+
+    const mcpServers: Array<McpServer> = (options.mcpServers ?? []).map(
+      (server) => ({
+        type: 'http' as const,
+        name: server.name,
+        url: server.url,
+        headers: server.headers ?? [],
+      }),
+    )
+
+    let sessionId: string | undefined
+    let resumed = false
+    if (
+      options.resumeSessionId !== undefined &&
+      initResult.agentCapabilities?.loadSession === true
+    ) {
+      replaying = true
+      try {
+        await race(
+          connection.loadSession({
+            sessionId: options.resumeSessionId,
+            cwd: options.cwd,
+            mcpServers,
+          }),
+        )
+        sessionId = options.resumeSessionId
+        resumed = true
+      } catch {
+        // Session unknown — fall through to a fresh one.
+      } finally {
+        replaying = false
+      }
+    }
+
+    if (sessionId === undefined) {
+      const session = await race(
+        connection.newSession({ cwd: options.cwd, mcpServers }),
+      )
+      sessionId = session.sessionId
+    }
+
+    return {
+      sessionId,
+      resumed,
+      prompt: async (text: string) => {
+        const response = await race(
+          connection.prompt({
+            sessionId,
+            prompt: [{ type: 'text', text }],
+          }),
+        )
+        return {
+          stopReason: response.stopReason,
+          ...(response.usage != null && { usage: response.usage }),
+        }
+      },
+      cancel: () => connection.cancel({ sessionId }),
+      dispose: teardown,
+    }
+  } catch (error) {
+    await teardown()
+    const tail = stderrTail().trim()
+    if (
+      error instanceof Error &&
+      tail !== '' &&
+      !error.message.includes(tail)
+    ) {
+      throw new Error(`${error.message}\nstderr: ${tail}`, { cause: error })
+    }
+    throw error
+  }
+}