@neuraltrust/trustgate 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+/** Which actor a handle speaks as. The consumer decides this, not the caller. */
+export declare const Actor: {
+    /** The application itself — principal `app:<consumer_id>`. */
+    readonly Application: "application";
+    /** One of the application's own end users. */
+    readonly EndUser: "end_user";
+};
+export type Actor = (typeof Actor)[keyof typeof Actor];
+/**
+ * The tool shapes the SDK can emit.
+ *
+ * These are model providers, not agent frameworks. A framework brings its own
+ * MCP client, so it takes the gateway's URL and lists the tools itself — there
+ * is nothing to convert. Conversion only happens when you call a provider's
+ * API directly, which is why nothing here is called "langchain".
+ */
+export declare const ToolFormat: {
+    /** OpenAI Responses API — function tools, flattened. */
+    readonly OpenAIResponses: "openai-responses";
+    /** OpenAI Chat Completions — function tools, nested under `function`. */
+    readonly OpenAIChat: "openai-chat";
+    /** Anthropic Messages — `input_schema`. */
+    readonly AnthropicMessages: "anthropic-messages";
+    /** Google Gemini — a single `functionDeclarations` entry. */
+    readonly Gemini: "gemini";
+};
+export type ToolFormat = (typeof ToolFormat)[keyof typeof ToolFormat];
+/** A tool as the gateway serves it, before any provider dialect is applied. */
+export type GatewayTool = {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: JSONSchema;
+    outputSchema?: JSONSchema;
+};
+export type JSONSchema = Record<string, unknown>;
+/** One upstream account of an actor, as the connections API reports it. */
+export type Connection = {
+    provider: string;
+    registry?: string;
+    code?: string;
+    status: 'connected' | 'needs_reconnect' | 'not_connected';
+    accountRef?: string;
+    expiresAt?: Date;
+};
+/** The link an end user opens to connect their own account. */
+export type ConnectLink = {
+    connectUrl: string;
+    ticket: string;
+    provider?: string;
+    expiresAt: Date;
+};
+/** Everything a provider's client needs to reach the gateway. */
+export type Endpoint = {
+    url: string;
+    headers: Record<string, string>;
+};
+/** A tool call as the SDK understands it, whatever provider asked for it. */
+export type ToolCall = {
+    /** The provider's own identifier for this call, echoed back in the result. */
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+/**
+ * The exposed name of a tool the caller named.
+ *
+ * The gateway prefixes every tool with the server it came from, so Linear's
+ * `list_issues` is served as `linear_list_issues`. That prefix is the gateway's
+ * doing and not the caller's, so a name written without one resolves — as long
+ * as exactly one server serves it. Two that do is a genuine question only the
+ * caller can answer, and it is asked rather than guessed.
+ *
+ * A name that matches nothing is returned unchanged, so the error that follows
+ * is about the tool rather than about this.
+ */
+export declare function resolveToolName(name: string, tools: GatewayTool[]): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,KAAK;IACjB,8DAA8D;;IAE9D,8CAA8C;;CAErC,CAAA;AACV,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,OAAO,KAAK,CAAC,CAAA;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;IACtB,wDAAwD;;IAExD,yEAAyE;;IAEzE,2CAA2C;;IAE3C,6DAA6D;;CAEpD,CAAA;AACV,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAA;AAErE,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,UAAU,CAAA;IACvB,YAAY,CAAC,EAAE,UAAU,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEhD,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,GAAG,iBAAiB,GAAG,eAAe,CAAA;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,IAAI,CAAA;CAChB,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,IAAI,CAAA;CACf,CAAA;AAED,iEAAiE;AACjE,MAAM,MAAM,QAAQ,GAAG;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,CAAA;AAED,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,GAAG;IACtB,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAY1E"}

package/dist/types.js

@@ -0,0 +1,52 @@
+import { TrustGateError } from './errors.js';
+/** Which actor a handle speaks as. The consumer decides this, not the caller. */
+export const Actor = {
+    /** The application itself — principal `app:<consumer_id>`. */
+    Application: 'application',
+    /** One of the application's own end users. */
+    EndUser: 'end_user',
+};
+/**
+ * The tool shapes the SDK can emit.
+ *
+ * These are model providers, not agent frameworks. A framework brings its own
+ * MCP client, so it takes the gateway's URL and lists the tools itself — there
+ * is nothing to convert. Conversion only happens when you call a provider's
+ * API directly, which is why nothing here is called "langchain".
+ */
+export const ToolFormat = {
+    /** OpenAI Responses API — function tools, flattened. */
+    OpenAIResponses: 'openai-responses',
+    /** OpenAI Chat Completions — function tools, nested under `function`. */
+    OpenAIChat: 'openai-chat',
+    /** Anthropic Messages — `input_schema`. */
+    AnthropicMessages: 'anthropic-messages',
+    /** Google Gemini — a single `functionDeclarations` entry. */
+    Gemini: 'gemini',
+};
+/**
+ * The exposed name of a tool the caller named.
+ *
+ * The gateway prefixes every tool with the server it came from, so Linear's
+ * `list_issues` is served as `linear_list_issues`. That prefix is the gateway's
+ * doing and not the caller's, so a name written without one resolves — as long
+ * as exactly one server serves it. Two that do is a genuine question only the
+ * caller can answer, and it is asked rather than guessed.
+ *
+ * A name that matches nothing is returned unchanged, so the error that follows
+ * is about the tool rather than about this.
+ */
+export function resolveToolName(name, tools) {
+    const names = tools.map((tool) => tool.name);
+    if (names.includes(name))
+        return name;
+    const matches = names.filter((candidate) => candidate.endsWith(`_${name}`));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new TrustGateError(`"${name}" is served by more than one of this application's servers ` +
+            `(${[...matches].sort().join(', ')}). Name the one you mean.`);
+    }
+    return name;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,iFAAiF;AACjF,MAAM,CAAC,MAAM,KAAK,GAAG;IACpB,8DAA8D;IAC9D,WAAW,EAAE,aAAa;IAC1B,8CAA8C;IAC9C,OAAO,EAAE,UAAU;CACV,CAAA;AAGV;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACzB,wDAAwD;IACxD,eAAe,EAAE,kBAAkB;IACnC,yEAAyE;IACzE,UAAU,EAAE,aAAa;IACzB,2CAA2C;IAC3C,iBAAiB,EAAE,oBAAoB;IACvC,6DAA6D;IAC7D,MAAM,EAAE,QAAQ;CACP,CAAA;AA8CV;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,KAAoB;IACjE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC5C,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAA;IAC3E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,cAAc,CACvB,IAAI,IAAI,6DAA6D;YACpE,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,CAC9D,CAAA;IACF,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC"}

package/dist/whoami.d.ts

@@ -0,0 +1,73 @@
+import type { ResolvedConfig } from './config.js';
+/** Whose account an MCP server reads: the one its instance holds, or one per caller. */
+export type UpstreamAccount = 'shared' | 'user';
+/**
+ * Who has to act before a server answers a call that runs as the application.
+ *
+ * `administrator` is an instance whose shared account nobody has connected —
+ * no caller can connect it, because it is the account every other caller rides
+ * on. `end_user` is an instance that keeps an account per caller, which an
+ * application is not: it names the person it acts for, and the account becomes
+ * theirs to connect.
+ */
+export type UpstreamBlockedBy = 'administrator' | 'end_user';
+/** One MCP server the application is bound to, and what it is waiting for. */
+export type KeyUpstream = {
+    server: string;
+    provider?: string;
+    account: UpstreamAccount;
+    connected: boolean;
+    needsReconnect: boolean;
+    blocked?: UpstreamBlockedBy;
+};
+/** One consumer the key reaches, with the address it is served on. */
+export type KeyConsumer = {
+    slug: string;
+    name?: string;
+    /** The plane this consumer belongs to: MCP, LLM or A2A. */
+    type: string;
+    active: boolean;
+    /** Where it answers. Empty when the gateway publishes no host for its plane. */
+    url: string;
+    /**
+     * The servers behind it that read a stored account, answered for this key —
+     * which is the application itself.
+     *
+     * `undefined` is not "nothing to connect": it is also what a gateway that
+     * could not read the accounts answers, and a server carrying its own
+     * credential is never listed. Read `blocked`, never a length.
+     */
+    upstreams?: KeyUpstream[];
+};
+/** The calling key itself. The secret is never echoed. */
+export type KeyInfo = {
+    name?: string;
+    /** When it retires itself. `undefined` means never. */
+    expiresAt?: Date;
+};
+/** Everything the key can say about itself. */
+export type KeyIdentity = {
+    gateway: string;
+    key: KeyInfo;
+    consumers: KeyConsumer[];
+};
+/**
+ * Asks the key what it reaches, when it dies, and what is not connected yet.
+ *
+ * It is what lets a client be configured with one secret: the slugs were
+ * chosen by whoever created the consumers, and the LLM plane is on a host the
+ * MCP URL says nothing about, so both have to come from the gateway. The other
+ * two answers are the failures a client would otherwise meet at runtime — an
+ * expired key as a 401 mid-run, an unconnected server as a refusal on the
+ * first tool call — moved to where something can still be done about them.
+ */
+export declare function whoAmI(config: ResolvedConfig, signal?: AbortSignal): Promise<KeyIdentity>;
+/**
+ * Picks the one consumer of a plane, or explains why it cannot.
+ *
+ * A key attached to two consumers of the same type is a legitimate setup that
+ * this SDK cannot resolve on its own, so it names them and asks — rather than
+ * guessing and running an agent against the wrong surface.
+ */
+export declare function selectConsumer(identity: KeyIdentity, plane: 'MCP' | 'LLM', configured: string | undefined, envName: string): KeyConsumer;
+//# sourceMappingURL=whoami.d.ts.map

package/dist/whoami.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.d.ts","sourceRoot":"","sources":["../src/whoami.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAIjD,wFAAwF;AACxF,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE/C;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,UAAU,CAAA;AAE5D,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,eAAe,CAAA;IACxB,SAAS,EAAE,OAAO,CAAA;IAClB,cAAc,EAAE,OAAO,CAAA;IACvB,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAC3B,CAAA;AAED,sEAAsE;AACtE,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,WAAW,EAAE,CAAA;CACzB,CAAA;AAED,0DAA0D;AAC1D,MAAM,MAAM,OAAO,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,SAAS,CAAC,EAAE,IAAI,CAAA;CAChB,CAAA;AAED,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,OAAO,CAAA;IACZ,SAAS,EAAE,WAAW,EAAE,CAAA;CACxB,CAAA;AAsBD;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAwB/F;AAYD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,KAAK,GAAG,KAAK,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,MAAM,GACb,WAAW,CA+Bb"}

package/dist/whoami.js

@@ -0,0 +1,79 @@
+import { PlaneUnavailableError, TrustGateError } from './errors.js';
+import { requestJSON } from './http.js';
+/**
+ * Asks the key what it reaches, when it dies, and what is not connected yet.
+ *
+ * It is what lets a client be configured with one secret: the slugs were
+ * chosen by whoever created the consumers, and the LLM plane is on a host the
+ * MCP URL says nothing about, so both have to come from the gateway. The other
+ * two answers are the failures a client would otherwise meet at runtime — an
+ * expired key as a 401 mid-run, an unconnected server as a refusal on the
+ * first tool call — moved to where something can still be done about them.
+ */
+export async function whoAmI(config, signal) {
+    const { body } = await requestJSON(config, 'GET', '/whoami', { signal });
+    return {
+        gateway: body?.gateway ?? '',
+        key: {
+            name: body?.key?.name || undefined,
+            expiresAt: parseDate(body?.key?.expires_at),
+        },
+        consumers: (body?.consumers ?? []).map((consumer) => ({
+            slug: consumer.slug,
+            name: consumer.name || undefined,
+            type: String(consumer.type ?? '').toUpperCase(),
+            active: consumer.active !== false,
+            url: consumer.url ?? '',
+            upstreams: consumer.upstreams?.map((upstream) => ({
+                server: upstream.server ?? '',
+                provider: upstream.provider || undefined,
+                account: upstream.account === 'shared' ? 'shared' : 'user',
+                connected: upstream.connected === true,
+                needsReconnect: upstream.needs_reconnect === true,
+                blocked: blockedBy(upstream.blocked),
+            })),
+        })),
+    };
+}
+function blockedBy(raw) {
+    return raw === 'administrator' || raw === 'end_user' ? raw : undefined;
+}
+function parseDate(raw) {
+    if (!raw)
+        return undefined;
+    const at = new Date(raw);
+    return Number.isNaN(at.getTime()) ? undefined : at;
+}
+/**
+ * Picks the one consumer of a plane, or explains why it cannot.
+ *
+ * A key attached to two consumers of the same type is a legitimate setup that
+ * this SDK cannot resolve on its own, so it names them and asks — rather than
+ * guessing and running an agent against the wrong surface.
+ */
+export function selectConsumer(identity, plane, configured, envName) {
+    const candidates = identity.consumers.filter((consumer) => consumer.type === plane);
+    if (configured) {
+        const named = candidates.find((consumer) => consumer.slug === configured);
+        if (named)
+            return named;
+        throw new PlaneUnavailableError(`this API key does not reach a ${plane} consumer called "${configured}"` +
+            (candidates.length ? `; it reaches ${candidates.map((c) => c.slug).join(', ')}` : ''));
+    }
+    if (candidates.length === 0) {
+        throw new PlaneUnavailableError(`this API key reaches no ${plane} consumer. ` +
+            'Ask the admin who owns this application to attach one, or name it explicitly.');
+    }
+    if (candidates.length > 1) {
+        throw new TrustGateError(`this API key reaches several ${plane} consumers (${candidates
+            .map((consumer) => consumer.slug)
+            .join(', ')}); name the one this agent uses.`);
+    }
+    const only = candidates[0];
+    if (!only.url) {
+        throw new PlaneUnavailableError(`the gateway publishes no host for its ${plane} plane, so "${only.slug}" has no address. ` +
+            `Set ${envName} and a base URL for it, or ask an operator to configure that plane's domain.`);
+    }
+    return only;
+}
+//# sourceMappingURL=whoami.js.map

package/dist/whoami.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.js","sourceRoot":"","sources":["../src/whoami.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@neuraltrust/trustgate",
+  "version": "0.1.0",
+  "description": "TrustGate SDK — governed tools and models for agents, over the MCP and LLM planes of a TrustGate gateway.",
+  "license": "Apache-2.0",
+  "author": "NeuralTrust",
+  "homepage": "https://docs.neuraltrust.ai/trustgate/mcp/connect",
+  "repository": { "type": "git", "url": "git+https://github.com/NeuralTrust/trustgate-sdk.git", "directory": "typescript" },
+  "bugs": { "url": "https://github.com/NeuralTrust/trustgate-sdk/issues" },
+  "keywords": ["mcp", "model-context-protocol", "agents", "llm", "gateway", "trustgate", "neuraltrust"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^5.0.1"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,267 @@
+import { END_USER_HEADER, type ResolvedConfig } from './config.js'
+import { createConnectLink, listConnections, requireEndUser } from './connections.js'
+import { ToolNotFoundError } from './errors.js'
+import { adapterFor, restoreArguments, type ConversionWarning, type ToolResult } from './formats.js'
+import { MCPTransport } from './mcp.js'
+import {
+	Actor,
+	ToolFormat,
+	resolveToolName,
+	type ConnectLink,
+	type Connection,
+	type Endpoint,
+	type GatewayTool,
+	type JSONSchema,
+	type ToolCall,
+} from './types.js'
+
+export type ToolkitOptions = {
+	/**
+	 * Ask the provider to hold the model to the schema. Off by default: it is
+	 * a stricter promise bought with a lossy rewrite, and some tools cannot be
+	 * expressed under it at all (see `warnings`).
+	 */
+	strict?: boolean
+}
+
+/**
+ * A tool surface in one provider's dialect, with the executor that belongs to
+ * it.
+ *
+ * They travel together because they are two halves of one translation: what
+ * `tools` added on the way out, `execute` has to undo on the way back.
+ *
+ * `Tool` and `Output` are the provider's own types, named by the caller:
+ *
+ * ```ts
+ * const { tools, execute } = agent.toolkit<
+ *   OpenAI.Responses.Tool,
+ *   OpenAI.Responses.ResponseInputItem
+ * >(ToolFormat.OpenAIResponses)
+ * ```
+ *
+ * They default to `unknown`, so nothing breaks by leaving them out — but then
+ * "pass this straight to the provider's API" is a promise the type does not
+ * keep, and the caller casts at the boundary. The SDK cannot name them itself:
+ * it carries no dependency on any provider's package, which is what lets one
+ * install serve all of them.
+ */
+export class Toolkit<Tool = unknown, Output = unknown> {
+	constructor(
+		/** Pass this straight to the provider's API. */
+		readonly tools: Tool[],
+		/** Tools whose schema could not be expressed in the requested dialect. */
+		readonly warnings: ConversionWarning[],
+		private readonly format: ToolFormat,
+		private readonly originals: Map<string, JSONSchema>,
+		private readonly transport: MCPTransport
+	) {
+		// Bound, because the documented way to use this is to destructure it —
+		// `const { tools, execute } = agent.toolkit(…)` — and an unbound method
+		// loses the format it needs the moment it is called that way.
+		this.calls = this.calls.bind(this)
+		this.execute = this.execute.bind(this)
+	}
+
+	/** The calls the model asked for, read out of the provider's response. */
+	calls(output: unknown): ToolCall[] {
+		return adapterFor(this.format).extractCalls(output)
+	}
+
+	/**
+	 * Runs the calls the model asked for and returns what to send back.
+	 *
+	 * Every call goes to the gateway, so the policy, the audit trail and the
+	 * upstream credentials stay where they were. The caller's process only
+	 * decides whether to make the call at all.
+	 */
+	async execute(output: unknown, signal?: AbortSignal): Promise<Output[]> {
+		const adapter = adapterFor(this.format)
+		const calls = adapter.extractCalls(output)
+		const results: ToolResult[] = []
+		for (const call of calls) {
+			const args = restoreArguments(call.arguments, this.originals.get(call.name))
+			const result = await this.transport.callTool(call.name, args, signal)
+			results.push({ call, result })
+		}
+		return adapter.toOutputs(results) as Output[]
+	}
+}
+
+/**
+ * An application's handle on its gateway.
+ *
+ * It speaks as the application itself: one principal, its own upstream
+ * accounts, nothing per-user. Which handle you get is not a choice made here —
+ * it follows from how the consumer was configured, which is why `connect()`
+ * returns one of these or refuses.
+ */
+export class Agent {
+	readonly actor = Actor.Application
+
+	constructor(
+		private readonly config: ResolvedConfig,
+		readonly slug: string,
+		private readonly transport: MCPTransport,
+		/** The tools this consumer serves, as the gateway named them. */
+		public tools: GatewayTool[],
+		/** Tools asked for in `requires` that the toolkit does not carry. */
+		readonly missing: string[],
+		/** The application's own upstream accounts, as of `connect()`. */
+		readonly connections: Connection[]
+	) {}
+
+	/** URL and headers for a framework that brings its own MCP client. */
+	get mcp(): Endpoint {
+		return { url: this.transport.url, headers: this.transport.headers }
+	}
+
+	/**
+	 * The same surface, translated for a provider you call directly.
+	 *
+	 * Name the provider's types to have them travel with it:
+	 * `toolkit<OpenAI.Responses.Tool, OpenAI.Responses.ResponseInputItem>(…)`.
+	 */
+	toolkit<Tool = unknown, Output = unknown>(
+		format: ToolFormat,
+		options: ToolkitOptions = {}
+	): Toolkit<Tool, Output> {
+		const { tools, warnings, originals } = adapterFor(format).convert(this.tools, {
+			strict: options.strict ?? false,
+		})
+		return new Toolkit<Tool, Output>(
+			tools as Tool[],
+			warnings,
+			format,
+			originals,
+			this.transport
+		)
+	}
+
+	/**
+	 * One tool, called directly. The escape hatch under the toolkits.
+	 *
+	 * The server prefix is optional here: "list_issues" reaches
+	 * "linear_list_issues" while Linear is the only server of this application
+	 * that serves it. The gateway put that prefix there, so a caller writing the
+	 * name by hand should not have to.
+	 */
+	async callTool(
+		name: string,
+		args: Record<string, unknown> = {},
+		signal?: AbortSignal
+	): Promise<Record<string, unknown>> {
+		return this.transport.callTool(resolveToolName(name, this.tools), args, signal)
+	}
+
+	/**
+	 * Re-reads the surface.
+	 *
+	 * An admin owns this toolkit and can change it under a running agent, so a
+	 * long-lived process re-reads rather than trusting the list it took at
+	 * startup.
+	 */
+	async refresh(signal?: AbortSignal): Promise<GatewayTool[]> {
+		this.tools = await this.transport.listTools(signal)
+		return this.tools
+	}
+
+	/** What the application still owes before it can call every server. */
+	async refreshConnections(signal?: AbortSignal): Promise<Connection[]> {
+		return listConnections(this.config, this.slug, undefined, signal)
+	}
+
+	/**
+	 * The same application, acting for one named person.
+	 *
+	 * No round trip and no second surface to read: the toolkit an admin bound
+	 * is the application's, identical for everyone it acts for. What changes is
+	 * one header, and with it whose upstream account the gateway reaches for.
+	 */
+	forEndUser(endUser: string): EndUserAgent {
+		return endUserAgent(this.config, this.slug, endUser, this.transport.url, this.tools)
+	}
+}
+
+/**
+ * An application's handle for one of its own end users.
+ *
+ * The user travels in a header, so a handle is a header and nothing more —
+ * but the MCP endpoint's headers are fixed when a client connects, which is
+ * why each user needs their own transport rather than a shared one.
+ */
+export class EndUserAgent {
+	readonly actor = Actor.EndUser
+
+	constructor(
+		private readonly config: ResolvedConfig,
+		readonly slug: string,
+		readonly endUser: string,
+		private readonly transport: MCPTransport,
+		public tools: GatewayTool[]
+	) {}
+
+	get mcp(): Endpoint {
+		return { url: this.transport.url, headers: this.transport.headers }
+	}
+
+	toolkit<Tool = unknown, Output = unknown>(
+		format: ToolFormat,
+		options: ToolkitOptions = {}
+	): Toolkit<Tool, Output> {
+		const { tools, warnings, originals } = adapterFor(format).convert(this.tools, {
+			strict: options.strict ?? false,
+		})
+		return new Toolkit<Tool, Output>(
+			tools as Tool[],
+			warnings,
+			format,
+			originals,
+			this.transport
+		)
+	}
+
+	async callTool(
+		name: string,
+		args: Record<string, unknown> = {},
+		signal?: AbortSignal
+	): Promise<Record<string, unknown>> {
+		return this.transport.callTool(name, args, signal)
+	}
+
+	async refresh(signal?: AbortSignal): Promise<GatewayTool[]> {
+		this.tools = await this.transport.listTools(signal)
+		return this.tools
+	}
+
+	/** Which servers this user has connected, and which they have not. */
+	async connections(signal?: AbortSignal): Promise<Connection[]> {
+		return listConnections(this.config, this.slug, this.endUser, signal)
+	}
+
+	/**
+	 * The page to put in front of this user so they can connect an account.
+	 *
+	 * Naming a provider narrows it to that one server; omitting it covers every
+	 * server of the application that forwards a credential. The link expires,
+	 * so it is minted when it is about to be shown, not cached.
+	 */
+	async connectLink(provider?: string, signal?: AbortSignal): Promise<ConnectLink> {
+		return createConnectLink(this.config, this.slug, this.endUser, provider, signal)
+	}
+}
+
+/** Builds the per-user handle, with the header that names them. */
+export function endUserAgent(
+	config: ResolvedConfig,
+	slug: string,
+	rawEndUser: string,
+	url: string,
+	tools: GatewayTool[]
+): EndUserAgent {
+	const endUser = requireEndUser(rawEndUser)
+	const transport = new MCPTransport(config, url, { [END_USER_HEADER]: endUser })
+	return new EndUserAgent(config, slug, endUser, transport, tools)
+}
+
+export { ToolNotFoundError }