@neuraltrust/trustgate 0.1.0

package/src/client.ts

@@ -0,0 +1,203 @@
+import { Agent, EndUserAgent, endUserAgent } from './agent.js'
+import { API_KEY_HEADER, resolveConfig, type ResolvedConfig, type TrustGateConfig } from './config.js'
+import { listConnections } from './connections.js'
+import {
+	MissingToolsError,
+	TrustGateError,
+	UpstreamNotConnectedError,
+	type BlockedUpstream,
+} from './errors.js'
+import { MCPTransport } from './mcp.js'
+import { resolveToolName, type Connection, type GatewayTool } from './types.js'
+import { selectConsumer, whoAmI, type KeyIdentity, type KeyUpstream } from './whoami.js'
+
+export type ConnectOptions = {
+	/**
+	 * Tool names this agent is written around.
+	 *
+	 * The toolkit belongs to an admin, not to the code that uses it, so it can
+	 * be narrowed without warning. Declaring what you need turns that into a
+	 * refusal at startup instead of a failure mid-conversation.
+	 */
+	requires?: string[]
+	signal?: AbortSignal
+}
+
+/** What the LLM plane needs to be handed to a provider's own client. */
+export type LLMEndpoint = {
+	/** Pass as `baseURL` to the OpenAI client. It ends in `/v1`. */
+	baseUrl: string
+	/**
+	 * Pass as `baseURL` to the Anthropic client.
+	 *
+	 * The two clients disagree on where the version goes. OpenAI's is handed a
+	 * base that already ends in `/v1` and appends `/chat/completions`;
+	 * Anthropic's appends `/v1/messages` to what it is given, so handing it
+	 * `baseUrl` asks the gateway for `/v1/v1/messages`. This is the
+	 * application's root, the one every dialect but OpenAI's hangs from.
+	 */
+	anthropicBaseUrl: string
+	apiKey: string
+	headers: Record<string, string>
+	/** The consumer behind it, for logs and for error messages. */
+	consumer: string
+}
+
+/**
+ * The entry point: a gateway and a key, and everything else is asked for.
+ *
+ * The key is attached to consumers, and a consumer has one type — so the tools
+ * live behind an MCP consumer and the models behind an LLM one. Their slugs
+ * were chosen by whoever created them, and the two planes do not share a host,
+ * so neither is something a caller should have to carry: the gateway is asked
+ * once, at `connect()`, and answers both.
+ */
+export class TrustGate {
+	private readonly config: ResolvedConfig
+	private identityPromise?: Promise<KeyIdentity>
+
+	constructor(config: TrustGateConfig = {}) {
+		this.config = resolveConfig(config)
+	}
+
+	/**
+	 * What this key reaches. Read once and remembered: it is a property of the
+	 * key, and a long-lived process should not re-ask on every call.
+	 */
+	async identity(signal?: AbortSignal): Promise<KeyIdentity> {
+		this.identityPromise ??= whoAmI(this.config, signal).catch((error: unknown) => {
+			this.identityPromise = undefined
+			throw asIdentityError(error, this.config.baseUrl)
+		})
+		return this.identityPromise
+	}
+
+	/**
+	 * The LLM plane, ready for a provider's own SDK.
+	 *
+	 * The gateway speaks the providers' own APIs, so nothing here wraps their
+	 * clients — it points them somewhere else. Wrapping would mean chasing
+	 * every change they make and breaking streaming on the way.
+	 */
+	async llm(signal?: AbortSignal): Promise<LLMEndpoint> {
+		const identity = await this.identity(signal)
+		const consumer = selectConsumer(identity, 'LLM', this.config.llmConsumer, 'llmConsumer')
+		return {
+			baseUrl: consumer.url,
+			anthropicBaseUrl: withoutVersion(consumer.url),
+			apiKey: this.config.apiKey,
+			headers: { [API_KEY_HEADER]: this.config.apiKey },
+			consumer: consumer.slug,
+		}
+	}
+
+	/**
+	 * Opens the application's own surface and proves it is usable before
+	 * anything runs.
+	 *
+	 * Two things happen here, and both are the kind that are cheap now and
+	 * expensive later: whether the tools the agent needs are actually on its
+	 * toolkit, and whether the servers behind it have an account to call with.
+	 * The second has no runtime remedy for this handle — nobody is present to
+	 * open a connect link once a batch is going — which is the whole reason it
+	 * is checked at startup.
+	 *
+	 * This is the application actor: the key and nothing else, so the gateway
+	 * runs the calls as `app:<consumer_id>`. For a call on behalf of a person,
+	 * use {@link forEndUser}; both work on the same consumer, because who a
+	 * request runs as is read from the request rather than declared anywhere.
+	 */
+	async connect(options: ConnectOptions = {}): Promise<Agent> {
+		const identity = await this.identity(options.signal)
+		const consumer = selectConsumer(identity, 'MCP', this.config.mcpConsumer, 'mcpConsumer')
+
+		// Accounts before tools: a server with no account for the application can
+		// fail the listing itself, which would surface as a bare gateway error
+		// before this check — the one that says who fixes it — ever ran.
+		const connections = await listConnections(this.config, consumer.slug, undefined, options.signal)
+		const blocked = blockedUpstreams(consumer.upstreams, connections)
+		if (blocked.length > 0) {
+			throw new UpstreamNotConnectedError(blocked)
+		}
+
+		const transport = new MCPTransport(this.config, consumer.url)
+		const tools = await transport.listTools(options.signal)
+		const missing = missingTools(tools, options.requires ?? [])
+		if (missing.length > 0) {
+			throw new MissingToolsError(missing, tools.map((tool) => tool.name))
+		}
+		return new Agent(this.config, consumer.slug, transport, tools, missing, connections)
+	}
+
+	/**
+	 * The handle for one named person, on the same consumer and the same key.
+	 *
+	 * The name is asserted by this application and not verified, so the gateway
+	 * namespaces it: two applications naming `user_123` never share an account.
+	 * What that person still has to connect is theirs to connect — the handle's
+	 * own `connections` mint the link to put in front of them — which is why
+	 * there is no startup preflight here and one in {@link connect}.
+	 */
+	async forEndUser(endUser: string, options: ConnectOptions = {}): Promise<EndUserAgent> {
+		const identity = await this.identity(options.signal)
+		const consumer = selectConsumer(identity, 'MCP', this.config.mcpConsumer, 'mcpConsumer')
+		const agent = endUserAgent(this.config, consumer.slug, endUser, consumer.url, [])
+		const tools = await agent.refresh(options.signal)
+		const missing = missingTools(tools, options.requires ?? [])
+		if (missing.length > 0) {
+			throw new MissingToolsError(missing, tools.map((tool) => tool.name))
+		}
+		return agent
+	}
+}
+
+/**
+ * The required tools this toolkit does not carry.
+ *
+ * Each name is resolved the way callTool resolves it, so an agent may require
+ * the name its server gave the tool and leave the gateway's server prefix to
+ * the gateway.
+ */
+function missingTools(tools: GatewayTool[], required: string[]): string[] {
+	const names = new Set(tools.map((tool) => tool.name))
+	return required.filter((name) => !names.has(resolveToolName(name, tools)))
+}
+
+function withoutVersion(url: string): string {
+	const trimmed = url.replace(/\/+$/, '')
+	return trimmed.endsWith('/v1') ? trimmed.slice(0, -'/v1'.length) : trimmed
+}
+
+/** A gateway that cannot answer for a key cannot be used with one secret. */
+function asIdentityError(error: unknown, baseUrl: string): unknown {
+	if (error instanceof TrustGateError && error.status === 404) {
+		return new TrustGateError(
+			`${baseUrl}/whoami answered 404, so the SDK cannot resolve which consumers ` +
+				'this key reaches. Usually the base URL is the wrong address: it is the MCP ' +
+				"plane's host on its own, with no consumer path after it — not the " +
+				'/<application>/mcp endpoint, and not the LLM plane. Otherwise the gateway ' +
+				'predates /whoami and needs upgrading.',
+			{ status: 404, cause: error }
+		)
+	}
+	return error
+}
+
+/**
+ * What this application still has to have connected before it can run.
+ *
+ * `whoami` answers it best, because it also names who has to act. But the field
+ * is absent on a gateway too old to send it, and an absent list is not an empty
+ * one: taking it for "nothing to connect" is how a batch gets past its own
+ * startup check and fails on the first row instead, which is the failure the
+ * check exists to prevent. So when it is missing the connections list answers,
+ * as it did before `whoami` carried this at all.
+ */
+function blockedUpstreams(upstreams: KeyUpstream[] | undefined, connections: Connection[]): BlockedUpstream[] {
+	if (upstreams) {
+		return upstreams.filter((upstream) => upstream.blocked)
+	}
+	return connections
+		.filter((connection) => connection.status !== 'connected')
+		.map((connection) => ({ server: connection.registry || connection.provider }))
+}

package/src/config.ts

@@ -0,0 +1,78 @@
+import { TrustGateError } from './errors.js'
+
+export type TrustGateConfig = {
+	/**
+	 * The gateway's base URL, without a consumer path:
+	 * `https://gw.acme.ai`. Defaults to `TRUSTGATE_URL`.
+	 */
+	baseUrl?: string
+	/** The consumer's API key. Defaults to `TRUSTGATE_API_KEY`. */
+	apiKey?: string
+	/**
+	 * Slug of the MCP consumer — the one carrying the agent's tools. Defaults
+	 * to `TRUSTGATE_MCP_CONSUMER`.
+	 */
+	mcpConsumer?: string
+	/**
+	 * Slug of the LLM consumer — the one in front of the models. Defaults to
+	 * `TRUSTGATE_LLM_CONSUMER`. It is a different consumer from the MCP one
+	 * because a consumer has one type; the same API key may be attached to
+	 * both.
+	 */
+	llmConsumer?: string
+	/** Overrides the fetch implementation. Tests and proxies use this. */
+	fetch?: typeof globalThis.fetch
+	/** Per-request timeout in milliseconds. Default 30000. */
+	timeoutMs?: number
+}
+
+export type ResolvedConfig = {
+	baseUrl: string
+	apiKey: string
+	mcpConsumer?: string
+	llmConsumer?: string
+	fetch: typeof globalThis.fetch
+	timeoutMs: number
+}
+
+function fromEnv(name: string): string | undefined {
+	const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+	return env?.[name]
+}
+
+export function resolveConfig(config: TrustGateConfig = {}): ResolvedConfig {
+	const baseUrl = (config.baseUrl ?? fromEnv('TRUSTGATE_URL') ?? '').trim().replace(/\/+$/, '')
+	const apiKey = (config.apiKey ?? fromEnv('TRUSTGATE_API_KEY') ?? '').trim()
+	if (!baseUrl) {
+		throw new TrustGateError('baseUrl is required (or set TRUSTGATE_URL)')
+	}
+	if (!/^https?:\/\//.test(baseUrl)) {
+		throw new TrustGateError(`baseUrl must be an http(s) URL, got "${baseUrl}"`)
+	}
+	if (!apiKey) {
+		throw new TrustGateError('apiKey is required (or set TRUSTGATE_API_KEY)')
+	}
+	const fetchImpl = config.fetch ?? globalThis.fetch
+	if (typeof fetchImpl !== 'function') {
+		throw new TrustGateError('no fetch available; pass one in config.fetch (Node 18+ has a global)')
+	}
+	return {
+		baseUrl,
+		apiKey,
+		mcpConsumer: config.mcpConsumer?.trim() || fromEnv('TRUSTGATE_MCP_CONSUMER')?.trim(),
+		llmConsumer: config.llmConsumer?.trim() || fromEnv('TRUSTGATE_LLM_CONSUMER')?.trim(),
+		fetch: fetchImpl,
+		timeoutMs: config.timeoutMs ?? 30_000,
+	}
+}
+
+/**
+ * The header the gateway reads the consumer's API key from.
+ *
+ * It also accepts `x-api-key` and `Authorization: Bearer ag_…`; this one is
+ * the unambiguous spelling, so it is the one the SDK sends.
+ */
+export const API_KEY_HEADER = 'X-AG-API-Key'
+
+/** The header that names which of the application's end users a call is for. */
+export const END_USER_HEADER = 'X-NeuralTrust-End-User'

package/src/connections.ts

@@ -0,0 +1,90 @@
+import type { ResolvedConfig } from './config.js'
+import { END_USER_HEADER } from './config.js'
+import { requestJSON } from './http.js'
+import { InvalidRequestError } from './errors.js'
+import type { ConnectLink, Connection } from './types.js'
+
+type ConnectionPayload = {
+	provider: string
+	registry?: string
+	code?: string
+	status: Connection['status']
+	account_ref?: string
+	expires_at?: string
+}
+
+type ConnectionsPayload = {
+	end_user?: string
+	actor?: string
+	connections?: ConnectionPayload[]
+}
+
+type LinkPayload = {
+	connect_url: string
+	ticket: string
+	provider?: string
+	expires_at: string
+}
+
+export function connectionsPath(slug: string, endUser?: string): string {
+	const query = endUser ? `?end_user=${encodeURIComponent(endUser)}` : ''
+	return `/${encodeURIComponent(slug)}/connections${query}`
+}
+
+export async function listConnections(
+	config: ResolvedConfig,
+	slug: string,
+	endUser?: string,
+	signal?: AbortSignal
+): Promise<Connection[]> {
+	const { body } = await requestJSON<ConnectionsPayload>(config, 'GET', connectionsPath(slug, endUser), {
+		signal,
+	})
+	return (body?.connections ?? []).map(toConnection)
+}
+
+export async function createConnectLink(
+	config: ResolvedConfig,
+	slug: string,
+	endUser: string,
+	provider: string | undefined,
+	signal?: AbortSignal
+): Promise<ConnectLink> {
+	const { body } = await requestJSON<LinkPayload>(
+		config,
+		'POST',
+		`/${encodeURIComponent(slug)}/connections/links`,
+		{ body: { end_user: endUser, ...(provider ? { provider } : {}) }, headers: { [END_USER_HEADER]: endUser }, signal }
+	)
+	return {
+		connectUrl: body.connect_url,
+		ticket: body.ticket,
+		provider: body.provider || undefined,
+		expiresAt: new Date(body.expires_at),
+	}
+}
+
+function toConnection(payload: ConnectionPayload): Connection {
+	return {
+		provider: payload.provider,
+		registry: payload.registry || undefined,
+		code: payload.code || undefined,
+		status: payload.status,
+		accountRef: payload.account_ref || undefined,
+		expiresAt: payload.expires_at ? new Date(payload.expires_at) : undefined,
+	}
+}
+
+/**
+ * The gateway is the authority on what an end-user id may be; this only
+ * catches the mistake worth catching locally, which is the empty one — it
+ * would otherwise be sent as a header the gateway reads as "no user named"
+ * and answer for the wrong actor.
+ */
+export function requireEndUser(endUser: string): string {
+	const trimmed = endUser?.trim() ?? ''
+	if (!trimmed) {
+		throw new InvalidRequestError('an end-user id is required to act for a user')
+	}
+	return trimmed
+}

package/src/errors.ts

@@ -0,0 +1,154 @@
+/**
+ * Every failure the SDK raises, as a type you can catch.
+ *
+ * The gateway answers a tool call with a JSON-RPC error and the connections
+ * API with `{error, message}`. Both are relayed here as classes rather than
+ * status codes, because the useful question is never "what number came back"
+ * but "is this mine to fix, my user's, or my admin's".
+ */
+export class TrustGateError extends Error {
+	readonly status?: number
+	readonly code?: string
+
+	constructor(message: string, options: { status?: number; code?: string; cause?: unknown } = {}) {
+		super(message, { cause: options.cause })
+		this.name = new.target.name
+		this.status = options.status
+		this.code = options.code
+	}
+}
+
+/** The API key is wrong, or it does not belong to this consumer. */
+export class AuthenticationError extends TrustGateError {}
+
+/** The request was malformed — a bad end-user id, an unknown provider. */
+export class InvalidRequestError extends TrustGateError {}
+
+/**
+ * The consumer's toolkit does not carry every tool the agent declared.
+ *
+ * An admin owns that toolkit, so this is not something the caller can fix in
+ * code: it is raised at startup, by name, so the agent never reaches a user
+ * only to find the tool it was written around is not there.
+ */
+export class MissingToolsError extends TrustGateError {
+	constructor(readonly missing: string[], readonly available: string[]) {
+		super(
+			`the consumer's toolkit is missing ${missing.map((t) => `"${t}"`).join(', ')}. ` +
+				`It offers: ${available.length ? available.join(', ') : '(nothing)'}. ` +
+				'Ask the admin who owns this application to add them.'
+		)
+	}
+}
+
+/**
+ * Servers the application cannot call yet, and who has to fix that.
+ *
+ * Raised at startup only, for the application handle: nobody is present to
+ * follow a connect link once a batch is running, so the run either knows
+ * beforehand or fails halfway through. The remedy is never the caller's — an
+ * account a whole team rides on is an administrator's to connect, and a
+ * per-caller account wants the person this call is for, which is what
+ * `forEndUser` is.
+ */
+export class UpstreamNotConnectedError extends TrustGateError {
+	constructor(readonly upstreams: BlockedUpstream[]) {
+		super(describeBlocked(upstreams))
+	}
+
+	/** The server names, for a caller that wants to log or list them. */
+	get servers(): string[] {
+		return this.upstreams.map((upstream) => upstream.server)
+	}
+}
+
+/** One server from {@link UpstreamNotConnectedError}. */
+export type BlockedUpstream = {
+	server: string
+	blocked?: 'administrator' | 'end_user'
+}
+
+/**
+ * Says who fixes each server, with the line of code when it is the caller.
+ *
+ * Read on a terminal at startup, so it is written to be acted on there: the
+ * per-user case is the one a developer hits first, and the fix is one call
+ * they have not seen yet, so the call is in the message.
+ */
+function describeBlocked(upstreams: BlockedUpstream[]): string {
+	const byAdmin = upstreams.filter((upstream) => upstream.blocked === 'administrator')
+	const byUser = upstreams.filter((upstream) => upstream.blocked === 'end_user')
+	const parts: string[] = []
+	if (byUser.length > 0) {
+		parts.push(
+			`${names(byUser)} ${verb(byUser, 'keeps', 'keep')} one account per user, and ` +
+				'connect() runs as the application, which has none there.\n' +
+				'\n' +
+				'Run as the person the work is for:\n' +
+				'\n' +
+				"    const agent = await tg.forEndUser('user_123')\n" +
+				'\n' +
+				`or have an administrator set ${names(byUser)} to a shared account in the ` +
+				"console (Registry, on the server's instance), and connect() works as it is."
+		)
+	}
+	if (byAdmin.length > 0) {
+		parts.push(
+			`${names(byAdmin)} ${verb(byAdmin, 'uses', 'use')} one shared account for every ` +
+				'caller, and nobody has connected it yet. An administrator connects it in the ' +
+				"console: Registry, on the server's instance, Connect."
+		)
+	}
+	return parts.length > 0 ? parts.join('\n\n') : `${names(upstreams)} ${verb(upstreams, 'is', 'are')} not connected.`
+}
+
+function names(upstreams: BlockedUpstream[]): string {
+	return upstreams.map((upstream) => `"${upstream.server}"`).join(', ')
+}
+
+function verb(upstreams: BlockedUpstream[], one: string, many: string): string {
+	return upstreams.length === 1 ? one : many
+}
+
+/**
+ * An end user has not connected the account this call needs.
+ *
+ * The link comes with the error because the gateway mints it there: it is the
+ * page to put in front of that user, and it expires.
+ */
+export class ConsentRequiredError extends TrustGateError {
+	constructor(
+		readonly provider: string,
+		readonly connectUrl: string,
+		readonly cause_: string,
+		message?: string
+	) {
+		super(message ?? `user consent required for ${provider}: open ${connectUrl}`, { code: 'consent_required' })
+	}
+}
+
+/** A policy on the gateway refused the call. Not retryable. */
+export class PolicyBlockedError extends TrustGateError {}
+
+/** The tool is not on this consumer's surface — usually because it just left it. */
+export class ToolNotFoundError extends TrustGateError {
+	constructor(readonly tool: string, message?: string) {
+		super(message ?? `the gateway does not serve a tool named "${tool}"`)
+	}
+}
+
+/** The connect-attempt limiter refused this call. */
+export class RateLimitedError extends TrustGateError {
+	constructor(message: string, readonly retryAfterMs?: number) {
+		super(message, { status: 429, code: 'rate_limited' })
+	}
+}
+
+/** The gateway could not serve the request and says so. Retryable. */
+export class ServiceUnavailableError extends TrustGateError {}
+
+/** The gateway failed on its own account. */
+export class TrustGateServerError extends TrustGateError {}
+
+/** The SDK was pointed at a plane this API key does not reach. */
+export class PlaneUnavailableError extends TrustGateError {}