@ai-sdk/harness-acp 0.0.0 → 1.0.0

package/src/v1/bridge/host-tool-mcp-server.ts

@@ -0,0 +1,180 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+  type CallToolResult,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { HarnessV1BridgeToolWire } from '@ai-sdk/harness';
+
+declare const __PACKAGE_VERSION__: string | undefined;
+
+const VERSION: string =
+  typeof __PACKAGE_VERSION__ !== 'undefined'
+    ? __PACKAGE_VERSION__
+    : '0.0.0-test';
+
+export type HostToolMCPInvocationResult = {
+  readonly output: unknown;
+  readonly isError?: boolean;
+  readonly correlationToken: string;
+};
+
+export type HostToolMCPServer = {
+  readonly server: Server;
+  updateCatalog(options: {
+    revision: number;
+    tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  }): Promise<void>;
+};
+
+export function createHostToolMCPServer({
+  tools,
+  revision = 1,
+  invoke,
+  onListTools,
+}: {
+  tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  revision?: number;
+  invoke: (options: {
+    toolName: string;
+    input: Readonly<Record<string, unknown>>;
+    catalogRevision: number;
+  }) => Promise<HostToolMCPInvocationResult>;
+  onListTools?: (options: { revision: number }) => Promise<void>;
+}): HostToolMCPServer {
+  let catalog = createCatalog({ revision, tools });
+  let catalogAcknowledgmentError: unknown;
+  const server = new Server(
+    {
+      name: '@ai-sdk/harness-acp-host-tools',
+      version: VERSION,
+    },
+    { capabilities: { tools: { listChanged: true } } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    if (catalogAcknowledgmentError != null) {
+      throw catalogAcknowledgmentError;
+    }
+    const current = catalog;
+    if (onListTools != null) {
+      setImmediate(() => {
+        void onListTools({ revision: current.revision }).catch(error => {
+          catalogAcknowledgmentError = error;
+        });
+      });
+    }
+    return { tools: current.tools.map(toMCPTool) };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    const current = catalog;
+    const tool = current.byName.get(request.params.name);
+    if (tool == null) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `Unknown host tool: ${request.params.name}`,
+      );
+    }
+    const input = request.params.arguments ?? {};
+    const result = await invoke({
+      toolName: tool.name,
+      input,
+      catalogRevision: current.revision,
+    });
+    return toCallToolResult({ result });
+  });
+
+  return {
+    server,
+    updateCatalog: async ({ revision: nextRevision, tools: nextTools }) => {
+      catalog = createCatalog({
+        revision: nextRevision,
+        tools: nextTools,
+      });
+      await server.sendToolListChanged();
+    },
+  };
+}
+
+function createCatalog({
+  revision,
+  tools,
+}: {
+  revision: number;
+  tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+}): {
+  readonly revision: number;
+  readonly tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  readonly byName: ReadonlyMap<string, HarnessV1BridgeToolWire>;
+} {
+  return {
+    revision,
+    tools: [...tools],
+    byName: new Map(tools.map(tool => [tool.name, tool])),
+  };
+}
+
+function toMCPTool(tool: HarnessV1BridgeToolWire): Tool {
+  return {
+    name: tool.name,
+    ...(tool.description == null ? {} : { description: tool.description }),
+    inputSchema: requireObjectSchema({
+      toolName: tool.name,
+      schema: tool.inputSchema ?? { type: 'object' },
+    }),
+  };
+}
+
+function requireObjectSchema({
+  toolName,
+  schema,
+}: {
+  toolName: string;
+  schema: unknown;
+}): Tool['inputSchema'] {
+  if (
+    schema == null ||
+    typeof schema !== 'object' ||
+    Array.isArray(schema) ||
+    (Reflect.get(schema, 'type') !== undefined &&
+      Reflect.get(schema, 'type') !== 'object')
+  ) {
+    throw new Error(
+      `Host tool ${toolName} must use an object JSON Schema for MCP.`,
+    );
+  }
+  return schema as Tool['inputSchema'];
+}
+
+function toCallToolResult({
+  result,
+}: {
+  result: HostToolMCPInvocationResult;
+}): CallToolResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: stringifyOutput({ output: result.output }),
+      },
+    ],
+    ...(result.isError ? { isError: true } : {}),
+    _meta: {
+      'ai-sdk-harness-acp-correlation': result.correlationToken,
+    },
+  };
+}
+
+function stringifyOutput({ output }: { output: unknown }): string {
+  if (output === undefined) return 'null';
+  try {
+    return JSON.stringify(output);
+  } catch {
+    return JSON.stringify({
+      error: 'Host tool output could not be serialized as JSON.',
+    });
+  }
+}

package/src/v1/bridge/host-tool-mcp.ts

@@ -0,0 +1,185 @@
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { env } from 'node:process';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { HarnessV1BridgeToolWire } from '@ai-sdk/harness';
+import {
+  createHostToolMCPServer,
+  type HostToolMCPInvocationResult,
+} from './host-tool-mcp-server';
+import { postHostToolRelay } from './host-tool-relay-client';
+
+const catalogPath = requireEnvironmentVariable({
+  name: 'AI_SDK_ACP_HOST_TOOLS_FILE',
+});
+const relayUrl = requireEnvironmentVariable({
+  name: 'AI_SDK_ACP_HOST_TOOL_RELAY_URL',
+});
+const relayCredential = requireEnvironmentVariable({
+  name: 'AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL',
+});
+const tools = await readToolCatalog({ path: catalogPath });
+const hostToolServer = createHostToolMCPServer({
+  tools,
+  invoke: async ({ toolName, input, catalogRevision }) =>
+    validateInvocationResult({
+      value: await postRelay({
+        path: '/invoke',
+        body: {
+          requestId: randomUUID(),
+          toolName,
+          input,
+          catalogRevision,
+        },
+      }),
+    }),
+  onListTools: async ({ revision }) => {
+    await postRelay({
+      path: '/catalog/seen',
+      body: { revision },
+    });
+  },
+});
+
+await hostToolServer.server.connect(new StdioServerTransport());
+void watchCatalog({
+  initialRevision: 1,
+  updateCatalog: hostToolServer.updateCatalog,
+}).catch(error => {
+  process.stderr.write(
+    `Host tool catalog synchronization failed: ${
+      error instanceof Error ? error.message : String(error)
+    }\n`,
+  );
+  void hostToolServer.server.close();
+  process.exitCode = 1;
+});
+
+async function watchCatalog({
+  initialRevision,
+  updateCatalog,
+}: {
+  initialRevision: number;
+  updateCatalog: (options: {
+    revision: number;
+    tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  }) => Promise<void>;
+}): Promise<void> {
+  let revision = initialRevision;
+  for (;;) {
+    const value = await postRelay({
+      path: '/catalog/next',
+      body: { afterRevision: revision },
+    });
+    if (isRecord(value) && value.closed === true) return;
+    if (
+      !isRecord(value) ||
+      !Number.isSafeInteger(value.revision) ||
+      (value.revision as number) < revision
+    ) {
+      throw new Error('Invalid host tool catalog poll response.');
+    }
+    const nextRevision = value.revision as number;
+    if (nextRevision === revision) continue;
+    const nextTools = validateToolCatalog({ value: value.tools });
+    await updateCatalog({ revision: nextRevision, tools: nextTools });
+    revision = nextRevision;
+  }
+}
+
+async function postRelay({
+  path,
+  body,
+}: {
+  path: string;
+  body: Readonly<Record<string, unknown>>;
+}): Promise<unknown> {
+  const response = await postHostToolRelay({
+    relayUrl,
+    relayCredential,
+    path,
+    body,
+  });
+  const { value } = response;
+  if (!response.ok) {
+    throw new Error(readErrorMessage({ value, status: response.status }));
+  }
+  return value;
+}
+
+function validateToolCatalog({
+  value,
+}: {
+  value: unknown;
+}): ReadonlyArray<HarnessV1BridgeToolWire> {
+  if (!Array.isArray(value) || !value.every(isTool)) {
+    throw new Error('Invalid host tool catalog.');
+  }
+  return value;
+}
+
+async function readToolCatalog({
+  path,
+}: {
+  path: string;
+}): Promise<ReadonlyArray<HarnessV1BridgeToolWire>> {
+  const text = await readFile(path, 'utf8');
+  const value = await new Response(text, {
+    headers: { 'content-type': 'application/json' },
+  }).json();
+  return validateToolCatalog({ value });
+}
+
+function isTool(value: unknown): value is HarnessV1BridgeToolWire {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    (value.description === undefined ||
+      typeof value.description === 'string') &&
+    (value.inputSchema === undefined ||
+      (isRecord(value.inputSchema) && !Array.isArray(value.inputSchema)))
+  );
+}
+
+function validateInvocationResult({
+  value,
+}: {
+  value: unknown;
+}): HostToolMCPInvocationResult {
+  if (
+    !isRecord(value) ||
+    typeof value.correlationToken !== 'string' ||
+    (value.isError !== undefined && typeof value.isError !== 'boolean')
+  ) {
+    throw new Error('Invalid host tool relay response.');
+  }
+  return {
+    output: value.output,
+    ...(value.isError ? { isError: true } : {}),
+    correlationToken: value.correlationToken,
+  };
+}
+
+function readErrorMessage({
+  value,
+  status,
+}: {
+  value: unknown;
+  status: number;
+}): string {
+  return isRecord(value) && typeof value.error === 'string'
+    ? value.error
+    : `Host tool relay returned HTTP ${status}.`;
+}
+
+function requireEnvironmentVariable({ name }: { name: string }): string {
+  const value = env[name];
+  if (value == null || value.length === 0) {
+    throw new Error(`Missing ${name}.`);
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/v1/bridge/host-tool-relay-client.ts

@@ -0,0 +1,53 @@
+import { Agent, request } from 'node:http';
+
+/*
+ * A host-tool call can remain pending while a person reviews an approval.
+ * The loopback connection therefore must not impose an inactivity deadline.
+ */
+const relayAgent = new Agent({ keepAlive: true, timeout: 0 });
+
+export async function postHostToolRelay({
+  relayUrl,
+  relayCredential,
+  path,
+  body,
+}: {
+  relayUrl: string;
+  relayCredential: string;
+  path: string;
+  body: Readonly<Record<string, unknown>>;
+}): Promise<{ status: number; ok: boolean; value: unknown }> {
+  const serializedBody = JSON.stringify(body);
+
+  return new Promise((resolve, reject) => {
+    const relayRequest = request(
+      new URL(path, relayUrl),
+      {
+        agent: relayAgent,
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${relayCredential}`,
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(serializedBody),
+        },
+      },
+      response => {
+        const chunks: Buffer[] = [];
+        response.on('data', (chunk: Buffer) => chunks.push(chunk));
+        response.on('error', reject);
+        response.on('end', () => {
+          void new Response(Buffer.concat(chunks)).json().then(value => {
+            const status = response.statusCode ?? 0;
+            resolve({
+              status,
+              ok: status >= 200 && status < 300,
+              value,
+            });
+          }, reject);
+        });
+      },
+    );
+    relayRequest.on('error', reject);
+    relayRequest.end(serializedBody);
+  });
+}