@neuraltrust/trustgate 0.1.0

package/src/formats.ts

@@ -0,0 +1,362 @@
+import { inlineRefs, stripInjectedNulls, toStrict } from "./schema.js";
+import {
+  ToolFormat,
+  type GatewayTool,
+  type JSONSchema,
+  type ToolCall,
+} from "./types.js";
+
+export type ConversionWarning = { tool: string; reason: string };
+
+export type Conversion = {
+  tools: unknown[];
+  warnings: ConversionWarning[];
+  /** The schema each tool had before translation, for the return trip. */
+  originals: Map<string, JSONSchema>;
+};
+
+export type ToolResult = { call: ToolCall; result: Record<string, unknown> };
+
+/**
+ * Each provider's function-calling dialect, in one place.
+ *
+ * A format knows three things: how to describe a tool, how to recognise the
+ * model asking for one, and how to hand the answer back. They are grouped per
+ * provider rather than per agent framework on purpose — a framework brings its
+ * own MCP client and never sees any of this.
+ */
+export type FormatAdapter = {
+  convert(tools: GatewayTool[], options: { strict: boolean }): Conversion;
+  extractCalls(output: unknown): ToolCall[];
+  toOutputs(results: ToolResult[]): unknown[];
+};
+
+export function adapterFor(format: ToolFormat): FormatAdapter {
+  const adapter = ADAPTERS[format];
+  if (!adapter) throw new Error(`unknown tool format "${format}"`);
+  return adapter;
+}
+
+/** Undoes whatever the outbound conversion added to the arguments. */
+export function restoreArguments(
+  args: Record<string, unknown>,
+  original: JSONSchema | undefined,
+): Record<string, unknown> {
+  return stripInjectedNulls(args, original) as Record<string, unknown>;
+}
+
+function convertWith(
+  tools: GatewayTool[],
+  options: { strict: boolean },
+  shape: (tool: GatewayTool, schema: JSONSchema, strict: boolean) => unknown,
+): Conversion {
+  const warnings: ConversionWarning[] = [];
+  const originals = new Map<string, JSONSchema>();
+  const converted = tools.map((tool) => {
+    originals.set(tool.name, tool.inputSchema);
+    if (!options.strict)
+      return shape(tool, inlineRefs(tool.inputSchema), false);
+    const result = toStrict(tool.inputSchema);
+    if (!result.strict)
+      warnings.push({ tool: tool.name, reason: result.reason ?? "unknown" });
+    return shape(tool, result.schema, result.strict);
+  });
+  return { tools: converted, warnings, originals };
+}
+
+const openAIResponses: FormatAdapter = {
+  convert: (tools, options) =>
+    convertWith(tools, options, (tool, schema, strict) => ({
+      type: "function",
+      name: tool.name,
+      description: tool.description ?? "",
+      parameters: schema,
+      strict,
+    })),
+  extractCalls(output) {
+    // Accepts the whole response or just its output array, because both are
+    // what people have in hand at the call site.
+    const items = Array.isArray(output)
+      ? output
+      : ((output as { output?: unknown[] } | undefined)?.output ?? []);
+    return items.flatMap((item) => {
+      const call = item as Record<string, unknown>;
+      if (call.type !== "function_call") return [];
+      return [
+        {
+          id: String(call.call_id ?? call.id ?? ""),
+          name: String(call.name ?? ""),
+          arguments: parseArguments(call.arguments),
+        },
+      ];
+    });
+  },
+  toOutputs: (results) =>
+    results.map(({ call, result }) => ({
+      type: "function_call_output",
+      call_id: call.id,
+      output: resultToText(result),
+    })),
+};
+
+const openAIChat: FormatAdapter = {
+  convert: (tools, options) =>
+    convertWith(tools, options, (tool, schema, strict) => ({
+      type: "function",
+      function: {
+        name: tool.name,
+        description: tool.description ?? "",
+        parameters: schema,
+        strict,
+      },
+    })),
+  extractCalls(output) {
+    const calls = Array.isArray(output)
+      ? output
+      : (((output as { choices?: { message?: { tool_calls?: unknown[] } }[] })
+          ?.choices?.[0]?.message?.tool_calls ?? []) as unknown[]);
+    return calls.flatMap((item) => {
+      const call = item as {
+        id?: unknown;
+        function?: { name?: unknown; arguments?: unknown };
+      };
+      if (!call.function) return [];
+      return [
+        {
+          id: String(call.id ?? ""),
+          name: String(call.function.name ?? ""),
+          arguments: parseArguments(call.function.arguments),
+        },
+      ];
+    });
+  },
+  toOutputs: (results) =>
+    results.map(({ call, result }) => ({
+      role: "tool",
+      tool_call_id: call.id,
+      content: resultToText(result),
+    })),
+};
+
+const anthropicMessages: FormatAdapter = {
+  convert: (tools, options) =>
+    // Anthropic takes plain JSON Schema, so strict has nothing to add here:
+    // asking for it would close objects for no gain.
+    convertWith(tools, { strict: false }, (tool, schema) => ({
+      name: tool.name,
+      description: tool.description ?? "",
+      input_schema: schema,
+    })),
+  extractCalls(output) {
+    const content = Array.isArray(output)
+      ? output
+      : ((output as { content?: unknown[] } | undefined)?.content ?? []);
+    return content.flatMap((item) => {
+      const block = item as Record<string, unknown>;
+      if (block.type !== "tool_use") return [];
+      return [
+        {
+          id: String(block.id ?? ""),
+          name: String(block.name ?? ""),
+          arguments: (block.input as Record<string, unknown>) ?? {},
+        },
+      ];
+    });
+  },
+  // No results means the model called nothing, and that is what an empty array
+  // says. A message wrapped around no blocks says the opposite — and Anthropic
+  // refuses a user message with no content, so the turn a caller reads as "keep
+  // going" is the one that cannot be sent.
+  toOutputs: (results) =>
+    results.length === 0
+      ? []
+      : [
+          {
+            role: "user",
+            content: results.map(({ call, result }) => ({
+              type: "tool_result",
+              tool_use_id: call.id,
+              content: resultToText(result),
+              ...(result.isError === true ? { is_error: true } : {}),
+            })),
+          },
+        ],
+};
+
+const gemini: FormatAdapter = {
+  convert(tools, _options) {
+    const warnings: ConversionWarning[] = [];
+    const originals = new Map<string, JSONSchema>();
+    const declarations = tools.map((tool) => {
+      originals.set(tool.name, tool.inputSchema);
+      const { schema, dropped } = geminiSchema(inlineRefs(tool.inputSchema));
+      if (dropped.length > 0) {
+        warnings.push({
+          tool: tool.name,
+          reason: `dropped keywords Gemini does not accept: ${[...new Set(dropped)].join(", ")}`,
+        });
+      }
+      return {
+        name: tool.name,
+        description: tool.description ?? "",
+        parameters: schema,
+      };
+    });
+    return {
+      tools: [{ functionDeclarations: declarations }],
+      warnings,
+      originals,
+    };
+  },
+  extractCalls(output) {
+    const parts = Array.isArray(output)
+      ? output
+      : (((output as { candidates?: { content?: { parts?: unknown[] } }[] })
+          ?.candidates?.[0]?.content?.parts ?? []) as unknown[]);
+    return parts.flatMap((item, index) => {
+      const part = item as {
+        functionCall?: { name?: unknown; args?: unknown };
+      };
+      if (!part.functionCall) return [];
+      const name = String(part.functionCall.name ?? "");
+      return [
+        {
+          // Gemini does not give a call an id, so one is made from its
+          // position — enough to pair a result with its call.
+          id: `${name}:${index}`,
+          name,
+          arguments: (part.functionCall.args as Record<string, unknown>) ?? {},
+        },
+      ];
+    });
+  },
+  // Empty means the model called nothing; see anthropicMessages.
+  toOutputs: (results) =>
+    results.length === 0
+      ? []
+      : [
+          {
+            role: "user",
+            parts: results.map(({ call, result }) => ({
+              functionResponse: {
+                name: call.name,
+                response: resultToResponse(result),
+              },
+            })),
+          },
+        ],
+};
+
+const ADAPTERS: Record<string, FormatAdapter> = {
+  [ToolFormat.OpenAIResponses]: openAIResponses,
+  [ToolFormat.OpenAIChat]: openAIChat,
+  [ToolFormat.AnthropicMessages]: anthropicMessages,
+  [ToolFormat.Gemini]: gemini,
+};
+
+/** Keywords Gemini's function declarations accept; everything else is dropped. */
+const GEMINI_KEYWORDS = new Set([
+  "type",
+  "format",
+  "description",
+  "nullable",
+  "enum",
+  "properties",
+  "required",
+  "items",
+  "anyOf",
+  "minimum",
+  "maximum",
+]);
+
+function geminiSchema(schema: JSONSchema): {
+  schema: JSONSchema;
+  dropped: string[];
+} {
+  const dropped: string[] = [];
+
+  // Inside `properties` the keys are the caller's own property names, not
+  // schema keywords, so they are carried across untouched — filtering them
+  // would delete the arguments rather than the syntax.
+  const walkProperties = (node: unknown): unknown => {
+    if (typeof node !== "object" || node === null) return node;
+    const out: Record<string, unknown> = {};
+    for (const [name, value] of Object.entries(
+      node as Record<string, unknown>,
+    )) {
+      out[name] = walk(value);
+    }
+    return out;
+  };
+
+  const walk = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(walk);
+    if (typeof node !== "object" || node === null) return node;
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(
+      node as Record<string, unknown>,
+    )) {
+      if (!GEMINI_KEYWORDS.has(key)) {
+        dropped.push(key);
+        continue;
+      }
+      if (key === "properties") {
+        out[key] = walkProperties(value);
+        continue;
+      }
+      out[key] = key === "required" || key === "enum" ? value : walk(value);
+    }
+    return out;
+  };
+
+  return { schema: walk(schema) as JSONSchema, dropped };
+}
+
+function parseArguments(raw: unknown): Record<string, unknown> {
+  if (typeof raw === "object" && raw !== null)
+    return raw as Record<string, unknown>;
+  if (typeof raw !== "string" || raw.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * What the model gets back from a tool.
+ *
+ * A structured result is the one worth giving it, since that is what the tool
+ * promised in its output schema; the text blocks are the fallback, and the
+ * whole result is the last resort. A tool that failed still answers here
+ * rather than throwing: MCP puts tool errors in the result precisely so the
+ * model can read them and correct itself.
+ */
+export function resultToText(result: Record<string, unknown>): string {
+  if (result.structuredContent !== undefined)
+    return JSON.stringify(result.structuredContent);
+  const content = result.content;
+  if (Array.isArray(content)) {
+    const text = content
+      .filter((block) => (block as { type?: string }).type === "text")
+      .map((block) => String((block as { text?: unknown }).text ?? ""))
+      .join("\n");
+    if (text) return text;
+  }
+  return JSON.stringify(result);
+}
+
+function resultToResponse(
+  result: Record<string, unknown>,
+): Record<string, unknown> {
+  if (
+    result.structuredContent !== undefined &&
+    typeof result.structuredContent === "object"
+  ) {
+    return result.structuredContent as Record<string, unknown>;
+  }
+  return { result: resultToText(result) };
+}

package/src/http.ts

@@ -0,0 +1,106 @@
+import { API_KEY_HEADER, type ResolvedConfig } from './config.js'
+import {
+	AuthenticationError,
+	InvalidRequestError,
+	RateLimitedError,
+	ServiceUnavailableError,
+	TrustGateError,
+	TrustGateServerError,
+} from './errors.js'
+
+export type ErrorBody = { error?: string; message?: string }
+
+/**
+ * A JSON request against the gateway's REST surface (the connections API).
+ *
+ * The gateway answers `{error, message}` on failure; this turns each `error`
+ * code into the type that says whose problem it is. `expect` names statuses
+ * the caller handles itself — the actor probe uses it to read a 409 as an
+ * answer rather than a failure.
+ */
+export async function requestJSON<T>(
+	config: ResolvedConfig,
+	method: string,
+	path: string,
+	options: { body?: unknown; headers?: Record<string, string>; expect?: number[]; signal?: AbortSignal } = {}
+): Promise<{ status: number; body: T }> {
+	const url = `${config.baseUrl}${path}`
+	const controller = new AbortController()
+	const timeout = setTimeout(() => controller.abort(), config.timeoutMs)
+	const signal = options.signal ? anySignal([options.signal, controller.signal]) : controller.signal
+	let response: Response
+	try {
+		response = await config.fetch(url, {
+			method,
+			headers: {
+				[API_KEY_HEADER]: config.apiKey,
+				Accept: 'application/json',
+				...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+				...options.headers,
+			},
+			body: options.body === undefined ? undefined : JSON.stringify(options.body),
+			signal,
+		})
+	} catch (cause) {
+		throw new TrustGateError(`${method} ${path} failed to reach the gateway`, { cause })
+	} finally {
+		clearTimeout(timeout)
+	}
+
+	const text = await response.text()
+	const body = text ? safeParse(text) : undefined
+	if (response.ok || options.expect?.includes(response.status)) {
+		return { status: response.status, body: body as T }
+	}
+	throw errorForResponse(response, body as ErrorBody | undefined, text)
+}
+
+function errorForResponse(response: Response, body: ErrorBody | undefined, raw: string): TrustGateError {
+	const code = body?.error
+	const message = body?.message ?? raw ?? response.statusText
+	const status = response.status
+	switch (code) {
+		case 'unauthenticated':
+			return new AuthenticationError(message, { status, code })
+		case 'invalid_request':
+			return new InvalidRequestError(message, { status, code })
+		case 'unavailable':
+			return new ServiceUnavailableError(message, { status, code })
+	}
+	if (status === 401 || status === 403) return new AuthenticationError(message, { status, code })
+	if (status === 429) {
+		return new RateLimitedError(message, retryAfterMs(response))
+	}
+	if (status >= 500) return new TrustGateServerError(message, { status, code })
+	return new TrustGateError(message, { status, code })
+}
+
+function retryAfterMs(response: Response): number | undefined {
+	const header = response.headers.get('Retry-After')
+	if (!header) return undefined
+	const seconds = Number(header)
+	return Number.isFinite(seconds) ? seconds * 1000 : undefined
+}
+
+function safeParse(text: string): unknown {
+	try {
+		return JSON.parse(text)
+	} catch {
+		return undefined
+	}
+}
+
+/** AbortSignal.any is not on every runtime the SDK supports yet. */
+function anySignal(signals: AbortSignal[]): AbortSignal {
+	const anyOf = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => AbortSignal }).any
+	if (typeof anyOf === 'function') return anyOf(signals)
+	const controller = new AbortController()
+	for (const signal of signals) {
+		if (signal.aborted) {
+			controller.abort(signal.reason)
+			break
+		}
+		signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true })
+	}
+	return controller.signal
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+export { TrustGate, type ConnectOptions, type LLMEndpoint } from './client.js'
+export {
+	whoAmI,
+	selectConsumer,
+	type KeyConsumer,
+	type KeyIdentity,
+	type KeyInfo,
+	type KeyUpstream,
+	type UpstreamAccount,
+	type UpstreamBlockedBy,
+} from './whoami.js'
+export { Agent, EndUserAgent, Toolkit, type ToolkitOptions } from './agent.js'
+export { type TrustGateConfig, API_KEY_HEADER, END_USER_HEADER } from './config.js'
+export { MCPTransport } from './mcp.js'
+export { inlineRefs, stripInjectedNulls, toStrict, type StrictResult } from './schema.js'
+export { adapterFor, resultToText, type ConversionWarning } from './formats.js'
+export {
+	Actor,
+	ToolFormat,
+	type ConnectLink,
+	type Connection,
+	type Endpoint,
+	type GatewayTool,
+	type JSONSchema,
+	type ToolCall,
+} from './types.js'
+export {
+	AuthenticationError,
+	ConsentRequiredError,
+	InvalidRequestError,
+	MissingToolsError,
+	PlaneUnavailableError,
+	PolicyBlockedError,
+	RateLimitedError,
+	ServiceUnavailableError,
+	ToolNotFoundError,
+	TrustGateError,
+	TrustGateServerError,
+	UpstreamNotConnectedError,
+	type BlockedUpstream,
+} from './errors.js'

package/src/mcp.ts

@@ -0,0 +1,203 @@
+import { API_KEY_HEADER, type ResolvedConfig } from './config.js'
+import {
+	AuthenticationError,
+	ConsentRequiredError,
+	InvalidRequestError,
+	PolicyBlockedError,
+	ToolNotFoundError,
+	TrustGateError,
+	TrustGateServerError,
+} from './errors.js'
+import type { GatewayTool, JSONSchema } from './types.js'
+
+/** JSON-RPC codes the gateway answers with, beyond the standard four. */
+const CODE_CONSENT_REQUIRED = -32003
+const CODE_RESOURCE_NOT_FOUND = -32002
+const CODE_POLICY_BLOCKED = -32001
+const CODE_INVALID_REQUEST = -32600
+const CODE_INVALID_PARAMS = -32602
+const CODE_INTERNAL = -32603
+
+type RPCError = { code: number; message: string; data?: unknown }
+type RPCResponse = { id?: unknown; result?: Record<string, unknown>; error?: RPCError }
+
+/**
+ * The gateway's MCP endpoint, spoken directly.
+ *
+ * Only two methods are needed to put a consumer's tools in front of a model —
+ * list them and call them — so this is a JSON-RPC client rather than a whole
+ * MCP implementation. The gateway is stateless: there is no handshake to do
+ * and no session to carry, so every call stands on its own.
+ */
+export class MCPTransport {
+	private nextId = 1
+
+	constructor(
+		private readonly config: ResolvedConfig,
+		readonly url: string,
+		private readonly extraHeaders: Record<string, string> = {}
+	) {}
+
+	get headers(): Record<string, string> {
+		return { [API_KEY_HEADER]: this.config.apiKey, ...this.extraHeaders }
+	}
+
+	async listTools(signal?: AbortSignal): Promise<GatewayTool[]> {
+		const result = await this.call('tools/list', {}, signal)
+		const tools = Array.isArray(result.tools) ? result.tools : []
+		return tools.map((tool) => {
+			const raw = tool as Record<string, unknown>
+			return {
+				name: String(raw.name ?? ''),
+				title: typeof raw.title === 'string' ? raw.title : undefined,
+				description: typeof raw.description === 'string' ? raw.description : undefined,
+				inputSchema: (raw.inputSchema as JSONSchema) ?? { type: 'object', properties: {} },
+				outputSchema: raw.outputSchema as JSONSchema | undefined,
+			}
+		})
+	}
+
+	async callTool(
+		name: string,
+		args: Record<string, unknown>,
+		signal?: AbortSignal
+	): Promise<Record<string, unknown>> {
+		try {
+			return await this.call('tools/call', { name, arguments: args }, signal)
+		} catch (error) {
+			// The gateway reports an unknown tool as invalid params, which is
+			// true of the request and useless to the caller: what they need to
+			// know is which tool, because a toolkit can lose one under them.
+			if (error instanceof InvalidRequestError && error.code === String(CODE_INVALID_PARAMS)) {
+				throw new ToolNotFoundError(name, error.message)
+			}
+			throw error
+		}
+	}
+
+	async call(
+		method: string,
+		params: Record<string, unknown>,
+		signal?: AbortSignal
+	): Promise<Record<string, unknown>> {
+		const id = this.nextId++
+		const controller = new AbortController()
+		const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs)
+		let response: Response
+		try {
+			response = await this.config.fetch(this.url, {
+				method: 'POST',
+				headers: {
+					...this.headers,
+					'Content-Type': 'application/json',
+					// A plain JSON answer is enough: the SDK re-lists on demand
+					// rather than listening for a change on the response.
+					Accept: 'application/json',
+				},
+				body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+				signal: signal ?? controller.signal,
+			})
+		} catch (cause) {
+			throw new TrustGateError(`MCP ${method} failed to reach ${this.url}`, { cause })
+		} finally {
+			clearTimeout(timeout)
+		}
+
+		if (response.status === 401 || response.status === 403) {
+			throw new AuthenticationError(
+				`the gateway refused this API key for ${this.url}`,
+				{ status: response.status }
+			)
+		}
+		const text = await response.text()
+		const rpc = parseRPCResponse(text, id)
+		if (!rpc) {
+			throw new TrustGateError(
+				`MCP ${method} returned no JSON-RPC response (HTTP ${response.status})` +
+					whatItSaid(text),
+				{ status: response.status }
+			)
+		}
+		if (rpc.error) throw errorForRPC(rpc.error)
+		return rpc.result ?? {}
+	}
+}
+
+/**
+ * Reads the response body, which is not always JSON.
+ *
+ * When a change to the surface has to be announced, the gateway answers the
+ * same request as an event stream and puts the response in a frame after the
+ * notification. Both shapes carry the same JSON-RPC object, so both are read
+ * here; a frame that is not this request's answer is skipped rather than
+ * mistaken for it.
+ */
+export function parseRPCResponse(text: string, id: number): RPCResponse | undefined {
+	const trimmed = text.trim()
+	if (!trimmed) return undefined
+	if (trimmed.startsWith('{')) {
+		try {
+			return JSON.parse(trimmed) as RPCResponse
+		} catch {
+			return undefined
+		}
+	}
+	for (const line of trimmed.split('\n')) {
+		if (!line.startsWith('data:')) continue
+		try {
+			const frame = JSON.parse(line.slice('data:'.length).trim()) as RPCResponse
+			if (frame.id === id) return frame
+		} catch {
+			continue
+		}
+	}
+	return undefined
+}
+
+function errorForRPC(error: RPCError): TrustGateError {
+	const data = (error.data ?? {}) as Record<string, unknown>
+	switch (error.code) {
+		case CODE_CONSENT_REQUIRED:
+			return new ConsentRequiredError(
+				String(data.provider ?? 'this provider'),
+				String(data.connect_url ?? ''),
+				String(data.cause ?? ''),
+				error.message
+			)
+		case CODE_POLICY_BLOCKED:
+			return new PolicyBlockedError(error.message, { code: String(error.code) })
+		case CODE_INTERNAL:
+			return new TrustGateServerError(error.message, { code: String(error.code) })
+		case CODE_INVALID_PARAMS:
+		case CODE_INVALID_REQUEST:
+		case CODE_RESOURCE_NOT_FOUND:
+			return new InvalidRequestError(error.message, { code: String(error.code) })
+		default:
+			return new TrustGateError(error.message, { code: String(error.code) })
+	}
+}
+
+/**
+ * The reason the endpoint gave, when it did not give it in JSON-RPC.
+ *
+ * A plain HTTP error — a missing header, a path that is no virtual MCP — says
+ * why in its body, and dropping that leaves a status code to guess from.
+ */
+function whatItSaid(text: string): string {
+	let said = (text ?? '').split(/\s+/).filter(Boolean).join(' ')
+	try {
+		const body: unknown = JSON.parse(text)
+		if (body && typeof body === 'object') {
+			for (const key of ['error', 'message', 'detail']) {
+				const value = (body as Record<string, unknown>)[key]
+				if (typeof value === 'string' && value.trim()) {
+					said = value.trim()
+					break
+				}
+			}
+		}
+	} catch {
+		// Not JSON. The whitespace-collapsed body is the best there is.
+	}
+	return said ? `: ${said.slice(0, 200)}` : ''
+}