@tanstack/ai-acp 0.1.0

package/dist/esm/transport/websocket.js.map

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

package/dist/esm/types/acp-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tanstack/ai-acp",
+  "version": "0.1.0",
+  "description": "Shared Agent Client Protocol (ACP) transport, session, and AG-UI translation for TanStack AI harness adapters.",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-acp"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "acp",
+    "agent-client-protocol",
+    "harness",
+    "sandbox"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.25.0"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-sandbox": "workspace:^"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-sandbox": "workspace:*",
+    "@tanstack/ai-sandbox-local-process": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}