The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(runner): add authenticated semantic MCP bridge (#12402)
Dotta9036d3c4848e
diff --git a/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts b/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.tsnew file mode 100644index 0000000000..b552adcb28--- /dev/null+++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts@@ -0,0 +1,447 @@+import { connect } from "node:net";++import { afterEach, describe, expect, it, vi } from "vitest";++import {+ canonicalRunnerToolName,+ startRunnerToolBridge,+ type RunnerToolBridge,+} from "./runner-tool-bridge.js";++const bridges: RunnerToolBridge[] = [];++afterEach(async () => {+ await Promise.all(bridges.splice(0).map((bridge) => bridge.close()));+});++async function rpc(+ bridge: RunnerToolBridge,+ body: Record<string, unknown>,+ secret = bridge.secret,+): Promise<Response> {+ return fetch(bridge.url, {+ method: "POST",+ headers: {+ Authorization: `Bearer ${secret}`,+ "Content-Type": "application/json",+ },+ body: JSON.stringify({ jsonrpc: "2.0", ...body }),+ });+}++describe("runner semantic MCP bridge", () => {+ it("binds to loopback, requires authentication, and exposes a closed catalog", async () => {+ const bridge = await startRunnerToolBridge({+ secret: "session-secret",+ tools: [tool("documents.read")],+ handler: async () => ({ ok: true }),+ });+ bridges.push(bridge);++ expect(new URL(bridge.url).hostname).toBe("127.0.0.1");+ expect(+ (await rpc(bridge, { id: 1, method: "tools/list" }, "wrong")).status,+ ).toBe(401);+ expect(+ await (await rpc(bridge, { id: 2, method: "tools/list" })).json(),+ ).toMatchObject({+ result: {+ tools: [+ { name: "documents.read" },+ { name: "paperclip_finish" },+ { name: "paperclip_block" },+ ],+ },+ });+ });++ it("keeps private operations callable but undiscoverable", async () => {+ const handler = vi.fn(async ({ tool: name }) => ({ name }));+ const bridge = await startRunnerToolBridge({+ tools: [tool("documents.read")],+ privateTools: [tool("__paperclip_permission")],+ handler,+ });+ bridges.push(bridge);+ const listed = (await (+ await rpc(bridge, { id: 1, method: "tools/list" })+ ).json()) as { result: { tools: Array<{ name: string }> } };+ expect(listed.result.tools.map(({ name }) => name)).not.toContain(+ "__paperclip_permission",+ );+ expect(+ await (+ await rpc(bridge, {+ id: "private-1",+ method: "tools/call",+ params: { name: "__paperclip_permission", arguments: {} },+ })+ ).json(),+ ).toMatchObject({+ result: {+ content: [{ text: expect.stringContaining("__paperclip_permission") }],+ },+ });+ });++ it("normalizes names and executes identical duplicate calls once", async () => {+ const handler = vi.fn(async () => ({ value: 7 }));+ const bridge = await startRunnerToolBridge({+ tools: [tool("documents.read")],+ handler,+ });+ bridges.push(bridge);+ const request = {+ id: "call-1",+ method: "tools/call",+ params: {+ name: "paperclip_documents.read",+ arguments: { id: "doc" },+ },+ };++ expect(await (await rpc(bridge, request)).json()).toMatchObject({+ result: { content: [{ text: '{"value":7}' }] },+ });+ expect(await (await rpc(bridge, request)).json()).toMatchObject({+ result: { content: [{ text: '{"value":7}' }] },+ });+ expect(handler).toHaveBeenCalledTimes(1);+ expect(handler).toHaveBeenCalledWith(+ expect.objectContaining({+ tool: "documents.read",+ callId: "call-1",+ arguments: { id: "doc" },+ }),+ );+ });++ it("rejects conflicting duplicate identities and validates before dispatch", async () => {+ const handler = vi.fn(async () => ({ ok: true }));+ const bridge = await startRunnerToolBridge({+ tools: [+ {+ name: "documents.read",+ inputSchema: {+ type: "object",+ required: ["id"],+ properties: { id: { type: "string" } },+ additionalProperties: false,+ },+ },+ ],+ handler,+ });+ bridges.push(bridge);++ expect(+ await (+ await rpc(bridge, {+ id: "same",+ method: "tools/call",+ params: { name: "documents.read", arguments: { id: 9 } },+ })+ ).json(),+ ).toMatchObject({ result: { isError: true } });+ expect(handler).not.toHaveBeenCalled();+ await rpc(bridge, {+ id: "same",+ method: "tools/call",+ params: { name: "documents.read", arguments: { id: "a" } },+ });+ expect(+ await (+ await rpc(bridge, {+ id: "same",+ method: "tools/call",+ params: { name: "documents.read", arguments: { id: "b" } },+ })+ ).json(),+ ).toMatchObject({+ result: {+ isError: true,+ content: [{ text: "Duplicate call identity conflict." }],+ },+ });+ });++ it("keeps numeric and string JSON-RPC identities distinct", async () => {+ const handler = vi.fn(async ({ callId }) => ({ callId }));+ const bridge = await startRunnerToolBridge({+ tools: [tool("documents.read")],+ handler,+ });+ bridges.push(bridge);++ await rpc(bridge, {+ id: 1,+ method: "tools/call",+ params: { name: "documents.read", arguments: { kind: "number" } },+ });+ await rpc(bridge, {+ id: "1",+ method: "tools/call",+ params: { name: "documents.read", arguments: { kind: "string" } },+ });+ expect(handler).toHaveBeenCalledTimes(2);+ });++ it("times out calls and honors MCP cancellation", async () => {+ const starts: string[] = [];+ const bridge = await startRunnerToolBridge({+ tools: [tool("documents.read")],+ timeoutMs: 20,+ handler: ({ callId, signal }) =>+ new Promise((_resolve, reject) => {+ starts.push(callId);+ signal.addEventListener(+ "abort",+ () => reject(new Error("handler aborted")),+ { once: true },+ );+ }),+ });+ bridges.push(bridge);++ expect(+ await (+ await rpc(bridge, {+ id: "slow",+ method: "tools/call",+ params: { name: "documents.read", arguments: {} },+ })+ ).json(),+ ).toMatchObject({+ result: {+ isError: true,+ content: [{ text: "Paperclip tool call timed out" }],+ },+ });+ const pending = rpc(bridge, {+ id: "cancel-me",+ method: "tools/call",+ params: { name: "documents.read", arguments: {} },+ });+ await vi.waitFor(() => expect(starts).toContain("cancel-me"), {+ interval: 1,+ timeout: 15,+ });+ expect(+ (+ await rpc(bridge, {+ method: "notifications/cancelled",+ params: { requestId: "cancel-me" },+ })+ ).status,+ ).toBe(202);+ expect(await (await pending).json()).toMatchObject({+ result: {+ isError: true,+ content: [{ text: "Paperclip tool call cancelled" }],+ },+ });+ });++ it("preserves successful mutation identity when the result is oversized", async () => {+ const result = { text: `snowman-${"☃".repeat(65 * 1024)}` };+ const handler = vi.fn(async () => result);+ const bridge = await startRunnerToolBridge({+ tools: [tool("documents.read")],+ handler,+ });+ bridges.push(bridge);+ const request = {+ id: "large-result",+ method: "tools/call",+ params: { name: "documents.read", arguments: {} },+ };++ const bodies = [];+ for (const response of [+ await rpc(bridge, request),+ await rpc(bridge, request),+ ]) {+ const body = (await response.json()) as {+ result: { content: Array<{ text: string }>; isError?: boolean };+ };+ expect(body.result).not.toHaveProperty("isError");+ const manifest = JSON.parse(body.result.content[0]!.text) as {+ schema: string;+ encoding: string;+ chunkCount: number;+ byteLength: number;+ sha256: string;+ };+ const serialized = body.result.content+ .slice(1)+ .map(({ text }) => text)+ .join("");+ expect(manifest).toMatchObject({+ schema: "paperclip.semantic_tool_result_chunks.v1",+ encoding: "json",+ chunkCount: body.result.content.length - 1,+ byteLength: Buffer.byteLength(serialized),+ });+ expect(+ body.result.content+ .slice(1)+ .every(({ text }) => Buffer.byteLength(text) <= 64 * 1024),+ ).toBe(true);+ expect(JSON.parse(serialized)).toEqual(result);+ bodies.push(body);+ }+ expect(bodies[1]).toEqual(bodies[0]);+ expect(handler).toHaveBeenCalledTimes(1);+ });++ it("returns a complete tagged receipt for cyclic results without re-executing", async () => {+ const cyclic: Record<string, unknown> = {};+ cyclic.self = cyclic;+ cyclic.revision = 9_007_199_254_740_993n;+ const handler = vi.fn(async () => cyclic);+ const bridge = await startRunnerToolBridge({+ tools: [tool("documents.read")],+ handler,+ });+ bridges.push(bridge);++ const request = {+ id: "cyclic-result",+ method: "tools/call",+ params: { name: "documents.read", arguments: {} },+ };+ const first = (await (await rpc(bridge, request)).json()) as {+ result: { content: Array<{ text: string }>; isError?: boolean };+ };+ const second = (await (await rpc(bridge, request)).json()) as typeof first;+ expect(first.result).not.toHaveProperty("isError");+ expect(JSON.parse(first.result.content[0]!.text)).toMatchObject({+ schema: "paperclip.semantic_tool_result.v1",+ status: "completed",+ tool: "documents.read",+ callIdentitySha256: expect.stringMatching(/^[0-9a-f]{64}$/),+ encoding: "paperclip.tagged_graph.v1",+ result: {+ root: { $ref: 1 },+ nodes: [+ {+ id: 1,+ type: "Object",+ properties: [+ { key: "self", value: { $ref: 1 } },+ {+ key: "revision",+ value: { $type: "bigint", value: "9007199254740993" },+ },+ ],+ },+ ],+ },+ });+ expect(second).toEqual(first);+ expect(handler).toHaveBeenCalledTimes(1);+ });++ it("destroys oversized and stalled request bodies before dispatch", async () => {+ const handler = vi.fn(async () => ({ ok: true }));+ const bridge = await startRunnerToolBridge({+ tools: [tool("documents.read")],+ handler,+ maxBodyBytes: 64,+ requestBodyTimeoutMs: 20,+ });+ bridges.push(bridge);++ await expect(+ rpc(bridge, {+ id: "oversized",+ method: "tools/call",+ params: {+ name: "documents.read",+ arguments: { value: "x".repeat(128) },+ },+ }),+ ).rejects.toThrow();++ const endpoint = new URL(bridge.url);+ const socket = connect({+ host: endpoint.hostname,+ port: Number(endpoint.port),+ });+ const closed = new Promise<void>((resolve) =>+ socket.once("close", () => resolve()),+ );+ socket.write(+ [+ "POST /mcp HTTP/1.1",+ `Host: ${endpoint.host}`,+ `Authorization: Bearer ${bridge.secret}`,+ "Content-Type: application/json",+ "Transfer-Encoding: chunked",+ "",+ "5",+ "{",+ ].join("\r\n"),+ );+ await expect(closed).resolves.toBeUndefined();+ expect(handler).not.toHaveBeenCalled();+ });++ it("prevents catalog ambiguity and reserved schema replacement", async () => {+ await expect(+ startRunnerToolBridge({+ tools: [tool("documents.read"), tool("paperclip_documents.read")],+ handler: async () => null,+ }),+ ).rejects.toThrow("duplicated");+ await expect(+ startRunnerToolBridge({+ tools: [tool("paperclip_finish")],+ handler: async () => null,+ }),+ ).rejects.toThrow("reserved by the protocol");+ await expect(+ startRunnerToolBridge({+ tools: [tool("documents.read")],+ privateTools: [tool("documents.read")],+ handler: async () => null,+ }),+ ).rejects.toThrow("both public and private");+ });++ it("rejects unsupported HTTP shapes and closes idempotently", async () => {+ const bridge = await startRunnerToolBridge({+ tools: [],+ handler: async () => null,+ });+ bridges.push(bridge);+ expect(+ (+ await fetch(bridge.url, {+ method: "POST",+ headers: { Authorization: `Bearer ${bridge.secret}` },+ body: "{}",+ })+ ).status,+ ).toBe(415);+ await bridge.close();+ await bridge.close();+ bridges.splice(bridges.indexOf(bridge), 1);+ });++ it("normalizes every supported provider prefix", () => {+ expect(canonicalRunnerToolName("paperclip_documents.read")).toBe(+ "documents.read",+ );+ expect(canonicalRunnerToolName("paperclip__documents.read")).toBe(+ "documents.read",+ );+ expect(canonicalRunnerToolName("paperclip.documents.read")).toBe(+ "documents.read",+ );+ });+});++function tool(name: string): Readonly<Record<string, unknown>> {+ return { name, inputSchema: { type: "object" } };+}diff --git a/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts b/packages/paperclip-runner/src/drivers/runner-tool-bridge.tsnew file mode 100644index 0000000000..4c7d5a35a2--- /dev/null+++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts@@ -0,0 +1,851 @@+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";+import {+ createServer,+ type IncomingMessage,+ type Server,+ type ServerResponse,+} from "node:http";++import { Ajv2020, type ValidateFunction } from "ajv/dist/2020.js";++import {+ PRP_BLOCK_RESULT_PROVIDER_INPUT_SCHEMA,+ PRP_BLOCK_TOOL_NAME,+ PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA,+ PRP_COMPLETION_TOOL_NAME,+} from "../contracts/completion-result.js";++export interface RunnerToolDefinition {+ name: string;+ description?: string;+ inputSchema: Record<string, unknown>;+}++export interface RunnerToolCall {+ tool: string;+ callId: string;+ arguments: unknown;+ signal: AbortSignal;+}++export interface RunnerToolBridgeOptions {+ tools?: readonly Readonly<Record<string, unknown>>[];+ /** Runner-owned operations that are callable but never model-visible. */+ privateTools?: readonly Readonly<Record<string, unknown>>[];+ handler(call: RunnerToolCall): Promise<unknown>;+ timeoutMs?: number;+ privateToolTimeoutMs?: number;+ maxBodyBytes?: number;+ /** Internal test seam; production bounds headers and body reads to 30 seconds. */+ requestBodyTimeoutMs?: number;+ secret?: string;+}++export interface RunnerToolBridge {+ readonly url: string;+ readonly secret: string;+ close(): Promise<void>;+}++interface AdmittedCall {+ fingerprint: string;+ promise: Promise<RunnerToolCallResult>;+}++interface RunnerToolTextContent {+ type: "text";+ text: string;+}++interface RunnerToolCallResult {+ content: RunnerToolTextContent[];+}++const DEFAULT_TIMEOUT_MS = 30_000;+const DEFAULT_PRIVATE_TOOL_TIMEOUT_MS = 24 * 60 * 60 * 1_000;+const DEFAULT_MAX_BODY_BYTES = 1_048_576;+const DEFAULT_REQUEST_BODY_TIMEOUT_MS = 30_000;+const MAX_CALLS = 2_048;+const MAX_RESULT_CHUNK_BYTES = 64 * 1024;+const RESERVED_TOOLS: readonly RunnerToolDefinition[] = [+ {+ name: PRP_COMPLETION_TOOL_NAME,+ description: "Return the semantic completion result.",+ inputSchema: PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA,+ },+ {+ name: PRP_BLOCK_TOOL_NAME,+ description: "Return the semantic blocked result.",+ inputSchema: PRP_BLOCK_RESULT_PROVIDER_INPUT_SCHEMA,+ },+];++export function canonicalRunnerToolName(name: string): string {+ const trimmed = name.trim();+ if (trimmed === PRP_COMPLETION_TOOL_NAME || trimmed === PRP_BLOCK_TOOL_NAME) {+ return trimmed;+ }+ for (const prefix of ["paperclip__", "paperclip_", "paperclip."]) {+ if (trimmed.startsWith(prefix)) return trimmed.slice(prefix.length);+ }+ return trimmed;+}++/** Start one authenticated, loopback-only MCP endpoint for a closed run catalog. */+export async function startRunnerToolBridge(+ options: RunnerToolBridgeOptions,+): Promise<RunnerToolBridge> {+ const secret = options.secret ?? randomBytes(32).toString("base64url");+ if (secret.length === 0)+ throw new Error("Runner tool bridge secret is empty");+ const tools = normalizeTools(options.tools ?? [], "public");+ const privateTools = normalizeTools(options.privateTools ?? [], "private");+ const publicNames = new Set(tools.map((tool) => tool.name));+ for (const tool of privateTools) {+ if (publicNames.has(tool.name)) {+ throw new Error(+ `Runner tool ${tool.name} cannot be both public and private`,+ );+ }+ }+ const visibleTools = [...tools, ...structuredClone(RESERVED_TOOLS)];+ const admittedTools = [...visibleTools, ...privateTools];+ const validators = compileValidators(admittedTools);+ const calls = new Map<string, AdmittedCall>();+ const controllers = new Map<string, AbortController>();+ const context = {+ secret,+ visibleTools,+ admittedTools: new Map(admittedTools.map((tool) => [tool.name, tool])),+ validators,+ calls,+ controllers,+ handler: options.handler,+ timeoutMs: positiveBoundedInteger(+ options.timeoutMs,+ DEFAULT_TIMEOUT_MS,+ 1,+ 24 * 60 * 60 * 1_000,+ "tool timeout",+ ),+ privateToolTimeoutMs: positiveBoundedInteger(+ options.privateToolTimeoutMs,+ DEFAULT_PRIVATE_TOOL_TIMEOUT_MS,+ 1,+ 24 * 60 * 60 * 1_000,+ "private tool timeout",+ ),+ privateToolNames: new Set(privateTools.map((tool) => tool.name)),+ maxBodyBytes: positiveBoundedInteger(+ options.maxBodyBytes,+ DEFAULT_MAX_BODY_BYTES,+ 1,+ 16 * 1024 * 1024,+ "request size",+ ),+ requestBodyTimeoutMs: positiveBoundedInteger(+ options.requestBodyTimeoutMs,+ DEFAULT_REQUEST_BODY_TIMEOUT_MS,+ 1,+ 5 * 60 * 1_000,+ "request body timeout",+ ),+ };+ const server = createServer((request, response) => {+ void handleRequest(request, response, context).catch(() => {+ if (!response.headersSent) response.statusCode = 500;+ if (!response.writableEnded) response.end();+ });+ });+ server.requestTimeout = context.requestBodyTimeoutMs;+ server.headersTimeout = context.requestBodyTimeoutMs;+ server.on("clientError", (_error, socket) => socket.destroy());+ await listenLoopback(server);+ const address = server.address();+ if (address === null || typeof address === "string") {+ await closeServer(server);+ throw new Error("Runner tool bridge failed to bind a loopback port");+ }+ let closed = false;+ return Object.freeze({+ url: `http://127.0.0.1:${address.port}/mcp`,+ secret,+ async close() {+ if (closed) return;+ closed = true;+ for (const controller of controllers.values()) controller.abort();+ await closeServer(server);+ },+ });+}++async function handleRequest(+ request: IncomingMessage,+ response: ServerResponse,+ context: {+ secret: string;+ visibleTools: RunnerToolDefinition[];+ admittedTools: Map<string, RunnerToolDefinition>;+ validators: Map<string, ValidateFunction>;+ calls: Map<string, AdmittedCall>;+ controllers: Map<string, AbortController>;+ handler: RunnerToolBridgeOptions["handler"];+ timeoutMs: number;+ privateToolTimeoutMs: number;+ privateToolNames: ReadonlySet<string>;+ maxBodyBytes: number;+ requestBodyTimeoutMs: number;+ },+): Promise<void> {+ setSecurityHeaders(response);+ if (!authorized(request.headers.authorization, context.secret)) {+ response.statusCode = 401;+ response.end();+ return;+ }+ if (request.method !== "POST" || request.url !== "/mcp") {+ response.statusCode = request.method === "GET" ? 405 : 404;+ if (request.method === "GET") response.setHeader("Allow", "POST");+ response.end();+ return;+ }+ if (!isJsonContentType(request.headers["content-type"])) {+ response.statusCode = 415;+ response.end();+ return;+ }+ let message: Record<string, unknown>;+ try {+ message = parseMessage(+ await readBody(+ request,+ context.maxBodyBytes,+ context.requestBodyTimeoutMs,+ ),+ );+ } catch (error) {+ writeRpc(response, null, undefined, rpcError(-32700, safeError(error)));+ return;+ }+ const id = message.id ?? null;+ const method = typeof message.method === "string" ? message.method : "";+ if (method === "notifications/cancelled") {+ const params = isRecord(message.params) ? message.params : {};+ const requestId = params.requestId;+ if (typeof requestId === "string" || typeof requestId === "number") {+ context.controllers.get(rpcIdKey(requestId))?.abort();+ }+ response.statusCode = 202;+ response.end();+ return;+ }+ if (method === "notifications/initialized") {+ response.statusCode = 202;+ response.end();+ return;+ }+ if (method === "initialize") {+ response.setHeader("Mcp-Session-Id", randomBytes(16).toString("hex"));+ writeRpc(response, id, {+ protocolVersion: "2025-03-26",+ capabilities: { tools: { listChanged: false } },+ serverInfo: { name: "paperclip-runner", version: "1" },+ });+ return;+ }+ if (method === "ping") {+ writeRpc(response, id, {});+ return;+ }+ if (method === "tools/list") {+ writeRpc(response, id, { tools: context.visibleTools });+ return;+ }+ if (method !== "tools/call") {+ writeRpc(response, id, undefined, rpcError(-32601, "Method not found"));+ return;+ }++ const params = isRecord(message.params) ? message.params : {};+ const rawName = typeof params.name === "string" ? params.name : "";+ const tool = canonicalRunnerToolName(rawName);+ if (!context.admittedTools.has(tool)) {+ writeToolError(response, id, "Unsupported tool.");+ return;+ }+ if (typeof id !== "string" && typeof id !== "number") {+ writeRpc(+ response,+ null,+ undefined,+ rpcError(-32600, "Tool calls require a request id"),+ );+ return;+ }+ const callId = String(id);+ const callKey = rpcIdKey(id);+ const args = params.arguments ?? {};+ const validator = context.validators.get(tool);+ if (validator === undefined || !validator(args)) {+ const detail = validator?.errors+ ?.map(+ (error) =>+ `${error.instancePath || "/"} ${error.message ?? "is invalid"}`,+ )+ .join("; ");+ writeToolError(+ response,+ id,+ `Invalid tool input${detail ? `: ${detail}` : "."}`,+ );+ return;+ }++ const fingerprint = canonicalJson({ tool, args });+ const existing = context.calls.get(callKey);+ if (existing && existing.fingerprint !== fingerprint) {+ writeToolError(response, id, "Duplicate call identity conflict.");+ return;+ }+ if (!existing && context.calls.size >= MAX_CALLS) {+ for (const admittedId of context.calls.keys()) {+ if (context.controllers.has(admittedId)) continue;+ context.calls.delete(admittedId);+ break;+ }+ if (context.calls.size >= MAX_CALLS) {+ writeToolError(response, id, "Runner tool bridge is at call capacity.");+ return;+ }+ }+ const controller = existing === undefined ? new AbortController() : undefined;+ const execution: Promise<RunnerToolCallResult> =+ existing?.promise ??+ withCancellationAndTimeout(+ Promise.resolve()+ .then(() =>+ context.handler({+ tool,+ callId,+ arguments: structuredClone(args),+ signal: controller!.signal,+ }),+ )+ .then((result) => successfulToolResult(tool, callId, result)),+ controller!,+ context.privateToolNames.has(tool)+ ? context.privateToolTimeoutMs+ : context.timeoutMs,+ );+ if (!existing) {+ context.calls.set(callKey, { fingerprint, promise: execution });+ context.controllers.set(callKey, controller!);+ void execution+ .finally(() => context.controllers.delete(callKey))+ .catch(() => undefined);+ }+ try {+ const result = await execution;+ writeRpc(response, id, result);+ } catch (error) {+ writeToolError(response, id, safeError(error));+ }+}++function normalizeTools(+ input: readonly Readonly<Record<string, unknown>>[],+ visibility: "public" | "private",+): RunnerToolDefinition[] {+ const tools: RunnerToolDefinition[] = [];+ const seen = new Set<string>();+ const reservedNames = new Set(RESERVED_TOOLS.map((tool) => tool.name));+ for (const raw of input) {+ const name =+ typeof raw.name === "string" ? canonicalRunnerToolName(raw.name) : "";+ if (!/^[A-Za-z0-9_.:-]{1,256}$/.test(name)) {+ throw new Error(`Runner ${visibility} tool has an invalid name`);+ }+ if (reservedNames.has(name)) {+ throw new Error(`Runner tool ${name} is reserved by the protocol`);+ }+ if (seen.has(name)) {+ throw new Error(`Runner ${visibility} tool ${name} is duplicated`);+ }+ if (!isRecord(raw.inputSchema)) {+ throw new Error(`Runner tool ${name} requires an object input schema`);+ }+ tools.push({+ name,+ ...(typeof raw.description === "string"+ ? { description: raw.description.slice(0, 4_096) }+ : {}),+ inputSchema: structuredClone(raw.inputSchema),+ });+ seen.add(name);+ }+ return tools;+}++function compileValidators(+ tools: readonly RunnerToolDefinition[],+): Map<string, ValidateFunction> {+ const ajv = new Ajv2020({ allErrors: true, strict: false });+ return new Map(+ tools.map((tool) => [tool.name, ajv.compile(tool.inputSchema)]),+ );+}++function authorized(value: string | undefined, secret: string): boolean {+ if (!value?.startsWith("Bearer ")) return false;+ const supplied = Buffer.from(value.slice(7));+ const expected = Buffer.from(secret);+ return (+ supplied.length === expected.length && timingSafeEqual(supplied, expected)+ );+}++function readBody(+ request: IncomingMessage,+ maxBytes: number,+ timeoutMs: number,+): Promise<string> {+ return new Promise((resolve, reject) => {+ const chunks: Buffer[] = [];+ let size = 0;+ let settled = false;+ const cleanup = () => {+ clearTimeout(timer);+ request.off("data", onData);+ request.off("end", onEnd);+ request.off("error", onError);+ request.off("aborted", onAborted);+ };+ const fail = (error: Error, destroy = false) => {+ if (settled) return;+ settled = true;+ cleanup();+ if (destroy && !request.destroyed) request.destroy();+ reject(error);+ };+ const onData = (value: Buffer | string) => {+ if (settled) return;+ const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);+ if (chunk.length > maxBytes - size) {+ fail(+ new Error("MCP request exceeded the retained payload limit"),+ true,+ );+ return;+ }+ size += chunk.length;+ chunks.push(chunk);+ };+ const onEnd = () => {+ if (settled) return;+ settled = true;+ cleanup();+ resolve(Buffer.concat(chunks).toString("utf8"));+ };+ const onError = (error: Error) => fail(error);+ const onAborted = () => fail(new Error("MCP request body was aborted"));+ const timer = setTimeout(() => {+ fail(new Error("MCP request body timed out"), true);+ }, timeoutMs);+ timer.unref?.();+ request.on("data", onData);+ request.on("end", onEnd);+ request.on("error", onError);+ request.on("aborted", onAborted);+ });+}++function parseMessage(body: string): Record<string, unknown> {+ const parsed: unknown = JSON.parse(body);+ if (+ !isRecord(parsed) ||+ parsed.jsonrpc !== "2.0" ||+ typeof parsed.method !== "string"+ ) {+ throw new Error("Invalid JSON-RPC request");+ }+ return parsed;+}++function writeToolError(+ response: ServerResponse,+ id: unknown,+ message: string,+): void {+ writeRpc(response, id, {+ isError: true,+ content: [{ type: "text", text: message }],+ });+}++function writeRpc(+ response: ServerResponse,+ id: unknown,+ result?: unknown,+ error?: unknown,+): void {+ response.statusCode = 200;+ response.setHeader("Content-Type", "application/json");+ response.end(+ JSON.stringify({+ jsonrpc: "2.0",+ id,+ ...(error === undefined ? { result } : { error }),+ }),+ );+}++function rpcError(+ code: number,+ message: string,+): { code: number; message: string } {+ return { code, message };+}++function setSecurityHeaders(response: ServerResponse): void {+ response.setHeader("Cache-Control", "no-store");+ response.setHeader("X-Content-Type-Options", "nosniff");+}++function listenLoopback(server: Server): Promise<void> {+ return new Promise((resolve, reject) => {+ const onError = (error: Error) => {+ server.off("listening", onListening);+ reject(error);+ };+ const onListening = () => {+ server.off("error", onError);+ resolve();+ };+ server.once("error", onError);+ server.once("listening", onListening);+ server.listen(0, "127.0.0.1");+ });+}++function closeServer(server: Server): Promise<void> {+ return new Promise((resolve, reject) => {+ server.close((error) => (error ? reject(error) : resolve()));+ server.closeIdleConnections();+ });+}++function withCancellationAndTimeout<T>(+ promise: Promise<T>,+ controller: AbortController,+ timeoutMs: number,+): Promise<T> {+ return new Promise((resolve, reject) => {+ let settled = false;+ const finish = (callback: () => void) => {+ if (settled) return;+ settled = true;+ clearTimeout(timer);+ controller.signal.removeEventListener("abort", onAbort);+ callback();+ };+ const onAbort = () =>+ finish(() => reject(new Error("Paperclip tool call cancelled")));+ const timer = setTimeout(() => {+ finish(() => reject(new Error("Paperclip tool call timed out")));+ controller.abort();+ }, timeoutMs);+ timer.unref();+ controller.signal.addEventListener("abort", onAbort, { once: true });+ promise.then(+ (value) => finish(() => resolve(value)),+ (error) => finish(() => reject(error)),+ );+ });+}++function safeError(error: unknown): string {+ return (error instanceof Error ? error.message : String(error)).slice(+ 0,+ 2_000,+ );+}++function successfulToolResult(+ tool: string,+ callId: string,+ value: unknown,+): RunnerToolCallResult {+ const json = strictJson(value);+ if (json !== null) return chunkedToolResult(tool, callId, "json", json);+ const representation = JSON.stringify({+ schema: "paperclip.semantic_tool_result.v1",+ status: "completed",+ tool,+ callIdentitySha256: createHash("sha256").update(callId).digest("hex"),+ encoding: "paperclip.tagged_graph.v1",+ result: taggedGraph(value),+ });+ return chunkedToolResult(+ tool,+ callId,+ "paperclip.tagged_graph.v1",+ representation,+ );+}++function strictJson(value: unknown): string | null {+ try {+ const serialized = JSON.stringify(+ value,+ function strictJsonValue(key, candidate) {+ const source = this[key];+ if (+ typeof candidate === "undefined" ||+ typeof candidate === "bigint" ||+ typeof candidate === "function" ||+ typeof candidate === "symbol" ||+ (typeof candidate === "number" && !Number.isFinite(candidate)) ||+ (source !== null &&+ typeof source === "object" &&+ Reflect.ownKeys(source).some(+ (property) => typeof property === "symbol",+ )) ||+ (candidate !== null &&+ typeof candidate === "object" &&+ !Array.isArray(candidate) &&+ Object.getPrototypeOf(candidate) !== Object.prototype &&+ Object.getPrototypeOf(candidate) !== null)+ ) {+ throw new Error("Result requires tagged graph encoding");+ }+ return candidate;+ },+ );+ return serialized ?? null;+ } catch {+ return null;+ }+}++function chunkedToolResult(+ tool: string,+ callId: string,+ encoding: "json" | "paperclip.tagged_graph.v1",+ serialized: string,+): RunnerToolCallResult {+ if (Buffer.byteLength(serialized) <= MAX_RESULT_CHUNK_BYTES) {+ return { content: [{ type: "text", text: serialized }] };+ }+ const chunks = utf8Chunks(serialized, MAX_RESULT_CHUNK_BYTES);+ const manifest = JSON.stringify({+ schema: "paperclip.semantic_tool_result_chunks.v1",+ status: "completed",+ tool,+ callIdentitySha256: createHash("sha256").update(callId).digest("hex"),+ encoding,+ contentOffset: 1,+ chunkCount: chunks.length,+ byteLength: Buffer.byteLength(serialized),+ sha256: createHash("sha256").update(serialized).digest("hex"),+ });+ return {+ content: [+ { type: "text", text: manifest },+ ...chunks.map((text) => ({ type: "text" as const, text })),+ ],+ };+}++function utf8Chunks(value: string, maxBytes: number): string[] {+ const bytes = Buffer.from(value);+ const chunks: string[] = [];+ let start = 0;+ while (start < bytes.length) {+ let end = Math.min(start + maxBytes, bytes.length);+ while (end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end -= 1;+ if (end === start) {+ throw new Error("Runner tool result chunk boundary is invalid");+ }+ chunks.push(bytes.subarray(start, end).toString("utf8"));+ start = end;+ }+ return chunks;+}++interface TaggedGraphState {+ nodes: Array<Record<string, unknown>>;+ objects: Map<object, number>;+ symbols: Map<symbol, number>;+}++function taggedGraph(value: unknown): Record<string, unknown> {+ const state: TaggedGraphState = {+ nodes: [],+ objects: new Map(),+ symbols: new Map(),+ };+ return {+ root: taggedValue(value, state),+ nodes: state.nodes,+ };+}++function taggedValue(value: unknown, state: TaggedGraphState): unknown {+ if (+ value === null ||+ typeof value === "string" ||+ typeof value === "boolean"+ ) {+ return value;+ }+ if (typeof value === "number") {+ if (Number.isFinite(value)) return value;+ return {+ $type: "number",+ value: Number.isNaN(value)+ ? "NaN"+ : value === Number.POSITIVE_INFINITY+ ? "Infinity"+ : "-Infinity",+ };+ }+ if (typeof value === "undefined") return { $type: "undefined" };+ if (typeof value === "bigint") {+ return { $type: "bigint", value: value.toString() };+ }+ if (typeof value === "symbol") return taggedSymbol(value, state);++ const object = value as object;+ const existing = state.objects.get(object);+ if (existing !== undefined) return { $ref: existing };+ const id = state.nodes.length + 1;+ state.objects.set(object, id);+ const node: Record<string, unknown> = {+ id,+ type: taggedObjectType(value),+ };+ state.nodes.push(node);+ if (typeof value === "function") {+ node.source = Function.prototype.toString.call(value);+ } else if (value instanceof Date) {+ node.value = Number.isNaN(value.getTime())+ ? "Invalid Date"+ : value.toISOString();+ } else if (value instanceof RegExp) {+ node.source = value.source;+ node.flags = value.flags;+ node.lastIndex = value.lastIndex;+ } else if (value instanceof Map) {+ node.entries = [...value.entries()].map(([key, entry]) => [+ taggedValue(key, state),+ taggedValue(entry, state),+ ]);+ } else if (value instanceof Set) {+ node.entries = [...value.values()].map((entry) =>+ taggedValue(entry, state),+ );+ } else if (value instanceof ArrayBuffer) {+ node.base64 = Buffer.from(value).toString("base64");+ } else if (ArrayBuffer.isView(value)) {+ node.base64 = Buffer.from(+ value.buffer,+ value.byteOffset,+ value.byteLength,+ ).toString("base64");+ }+ node.properties = Reflect.ownKeys(value).map((key) => {+ const descriptor = Object.getOwnPropertyDescriptor(value, key)!;+ return {+ key: typeof key === "string" ? key : taggedSymbol(key, state),+ enumerable: descriptor.enumerable,+ configurable: descriptor.configurable,+ ...(Object.hasOwn(descriptor, "value")+ ? {+ writable: descriptor.writable,+ value: taggedValue(descriptor.value, state),+ }+ : {+ get:+ descriptor.get === undefined+ ? null+ : Function.prototype.toString.call(descriptor.get),+ set:+ descriptor.set === undefined+ ? null+ : Function.prototype.toString.call(descriptor.set),+ }),+ };+ });+ return { $ref: id };+}++function taggedSymbol(+ value: symbol,+ state: TaggedGraphState,+): Record<string, unknown> {+ const existing = state.symbols.get(value);+ if (existing !== undefined) return { $symbolRef: existing };+ const id = state.symbols.size + 1;+ state.symbols.set(value, id);+ return {+ $type: "symbol",+ id,+ key: Symbol.keyFor(value) ?? null,+ description: value.description ?? null,+ };+}++function taggedObjectType(value: object): string {+ if (Array.isArray(value)) return "Array";+ if (typeof value === "function") return "Function";+ if (ArrayBuffer.isView(value)) return value.constructor.name;+ const prototype = Object.getPrototypeOf(value) as {+ constructor?: { name?: unknown };+ } | null;+ return typeof prototype?.constructor?.name === "string"+ ? prototype.constructor.name+ : "Object";+}++function canonicalJson(value: unknown): string {+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;+ if (isRecord(value)) {+ return `{${Object.keys(value)+ .sort()+ .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)+ .join(",")}}`;+ }+ return JSON.stringify(value) ?? "undefined";+}++function isJsonContentType(value: string | undefined): boolean {+ return value?.split(";", 1)[0]?.trim().toLowerCase() === "application/json";+}++function rpcIdKey(value: string | number): string {+ return `${typeof value}:${String(value)}`;+}++function positiveBoundedInteger(+ value: number | undefined,+ fallback: number,+ minimum: number,+ maximum: number,+ label: string,+): number {+ const resolved = value ?? fallback;+ if (+ !Number.isSafeInteger(resolved) ||+ resolved < minimum ||+ resolved > maximum+ ) {+ throw new Error(+ `Runner tool bridge ${label} is outside its supported bound`,+ );+ }+ return resolved;+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}