@adtl/gateway 0.0.0-stage → 0.1.0

package/dist/startup.js

@@ -0,0 +1,133 @@
+/**
+ * Build a running gateway from an adtl.yaml file: start the interceptor
+ * server, connect every upstream, and check that ADTL's interceptors are there.
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { INTERCEPTORS_EXTENSION, LABEL_INTERCEPTOR, POLICY_INTERCEPTOR, parseConfigText } from "@adtl/interceptors";
+import { parse as parseYaml } from "yaml";
+import { ZodError } from "zod";
+import { JsonlAuditLog } from "./audit.js";
+import { GatewayConfigSchema, expandUpstream, isHttpUpstream, } from "./config.js";
+import { AdtlGateway, GATEWAY_VERSION } from "./gateway.js";
+import { InterceptorInvoker } from "./invoker.js";
+export class GatewayConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GatewayConfigError";
+    }
+}
+export async function loadGatewayConfig(path) {
+    const abs = resolve(path);
+    let text;
+    try {
+        text = await readFile(abs, "utf8");
+    }
+    catch (err) {
+        throw new GatewayConfigError(`Cannot read config file ${abs}: ${err.message}`);
+    }
+    let labels;
+    try {
+        labels = parseConfigText(text, abs);
+    }
+    catch (err) {
+        throw new GatewayConfigError(err.message);
+    }
+    const raw = (parseYaml(text) ?? {});
+    if (raw.gateway === undefined) {
+        throw new GatewayConfigError(`${abs}: missing "gateway:" section (at least one upstream under gateway.upstreams)`);
+    }
+    try {
+        return { path: abs, labels, gateway: GatewayConfigSchema.parse(raw.gateway) };
+    }
+    catch (err) {
+        if (err instanceof ZodError) {
+            const problems = err.issues.map((i) => `  - gateway.${i.path.join(".")}: ${i.message}`).join("\n");
+            throw new GatewayConfigError(`${abs}: invalid gateway config\n${problems}`);
+        }
+        throw err;
+    }
+}
+/** Path of the bundled adtl-interceptors CLI. */
+export function bundledInterceptorsCli() {
+    // Resolve via package.json: works in plain Node and under tools that lack import.meta.resolve.
+    const pkg = createRequire(import.meta.url).resolve("@adtl/interceptors/package.json");
+    return resolve(dirname(pkg), "dist", "cli.js");
+}
+function stdioTransport(u, baseDir) {
+    return new StdioClientTransport({
+        command: u.command,
+        args: u.args,
+        // The SDK passes only `env` when given, which would drop PATH; start from its safe defaults.
+        env: { ...getDefaultEnvironment(), ...u.env },
+        ...(u.cwd !== undefined ? { cwd: isAbsolute(u.cwd) ? u.cwd : resolve(baseDir, u.cwd) } : {}),
+        stderr: "inherit",
+    });
+}
+async function connect(id, u, baseDir) {
+    const client = new Client({ name: `adtl-gateway→${id}`, version: GATEWAY_VERSION });
+    const transport = isHttpUpstream(u)
+        ? new StreamableHTTPClientTransport(new URL(u.url), { requestInit: { headers: u.headers } })
+        : stdioTransport(u, baseDir);
+    await client.connect(transport);
+    return client;
+}
+export async function startGateway(loaded, opts = {}) {
+    const env = opts.env ?? process.env;
+    const baseDir = dirname(loaded.path);
+    const log = opts.logger ?? { info: (m) => console.error(`[adtl-gateway] ${m}`), warn: (m) => console.error(`[adtl-gateway] warning: ${m}`) };
+    const clients = [];
+    const closeAll = () => Promise.allSettled(clients.map((c) => c.close())).then(() => undefined);
+    try {
+        // 1. Interceptor server (out of process, per the Interceptors WG).
+        const icfg = loaded.gateway.interceptors
+            ? expandUpstream("interceptors", loaded.gateway.interceptors, env)
+            : { command: process.execPath, args: [bundledInterceptorsCli(), "--config", loaded.path], env: {} };
+        const interceptors = await connect("interceptors", icfg, baseDir);
+        clients.push(interceptors);
+        if (!interceptors.getServerCapabilities()?.extensions?.[INTERCEPTORS_EXTENSION]) {
+            throw new GatewayConfigError(`The interceptor server does not declare the ${INTERCEPTORS_EXTENSION} extension`);
+        }
+        const bound = await InterceptorInvoker.discover(interceptors);
+        const names = bound.map((b) => b.definition.name);
+        for (const required of [POLICY_INTERCEPTOR, LABEL_INTERCEPTOR]) {
+            if (!names.includes(required)) {
+                throw new GatewayConfigError(`The interceptor server does not offer ${required}; refusing to start without it`);
+            }
+        }
+        const invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs);
+        log.info(`interceptors: ${names.join(", ")}`);
+        // 2. Upstream servers. One failing upstream does not stop the others.
+        const upstreams = new Map();
+        const ids = Object.keys(loaded.gateway.upstreams);
+        const settled = await Promise.allSettled(ids.map((id) => connect(id, expandUpstream(id, loaded.gateway.upstreams[id], env), baseDir)));
+        settled.forEach((s, i) => {
+            const id = ids[i];
+            if (s.status === "fulfilled") {
+                clients.push(s.value);
+                upstreams.set(id, s.value);
+                if (!loaded.labels.servers[id]) {
+                    log.warn(`upstream "${id}" has no entry under servers: in the label config; its results get the default label`);
+                }
+            }
+            else {
+                log.warn(`could not connect to upstream "${id}": ${s.reason.message}`);
+            }
+        });
+        if (upstreams.size === 0)
+            throw new GatewayConfigError("No upstream server could be connected");
+        log.info(`upstreams: ${[...upstreams.keys()].join(", ")}`);
+        const audit = loaded.gateway.audit ? new JsonlAuditLog(resolve(baseDir, loaded.gateway.audit)) : undefined;
+        const gateway = new AdtlGateway({ upstreams, invoker, ...(audit ? { audit } : {}), logger: log });
+        return { gateway, close: closeAll };
+    }
+    catch (err) {
+        await closeAll();
+        throw err;
+    }
+}
+//# sourceMappingURL=startup.js.map

package/dist/startup.js.map

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

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@adtl/gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Experimental: MCP gateway that labels every tool result and blocks risky tool calls using ADTL trust labels",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-gateway",
+    "mcp-proxy",
+    "ai-agents",
+    "ai-security",
+    "prompt-injection",
+    "trust-labels"
+  ],
+  "author": "Murthy G",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "adtl-gateway": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/probita-ai/adtl.git",
+    "directory": "packages/gateway"
+  },
+  "homepage": "https://github.com/probita-ai/adtl/tree/main/packages/gateway#readme",
+  "bugs": {
+    "url": "https://github.com/probita-ai/adtl/issues"
+  },
+  "dependencies": {
+    "@adtl/interceptors": "0.1.0",
+    "@adtl/labels": "0.1.0",
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "yaml": "2.9.1",
+    "zod": "3.25.76"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/audit.ts

@@ -0,0 +1,47 @@
+/**
+ * Append-only JSONL audit log. One line per tool call.
+ *
+ * Arguments and results are never written; the call is identified by its
+ * hash, so the log can be shared without leaking the data it describes.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface AuditEntry {
+  ts: string;
+  sessionId: string;
+  event: "tools/call";
+  server: string;
+  tool: string;
+  /** Final outcome of the call. */
+  outcome: "forwarded" | "blocked" | "upstream_error";
+  decision?: string;
+  reason?: string;
+  matched?: unknown;
+  callHash?: unknown;
+  label?: unknown;
+  sessionLabel?: unknown;
+  warnings?: string[];
+  durationMs: number;
+}
+
+export interface AuditSink {
+  write(entry: AuditEntry): void;
+}
+
+export class JsonlAuditLog implements AuditSink {
+  constructor(readonly path: string) {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+
+  write(entry: AuditEntry): void {
+    appendFileSync(this.path, `${JSON.stringify(entry)}\n`, "utf8");
+  }
+}
+
+export class MemoryAuditLog implements AuditSink {
+  readonly entries: AuditEntry[] = [];
+  write(entry: AuditEntry): void {
+    this.entries.push(entry);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * adtl-gateway: an MCP server for your agent that proxies to your real MCP
+ * servers through ADTL's interceptors.
+ *
+ *   adtl-gateway --config adtl.yaml
+ *
+ * Point your MCP client (e.g. Claude Code's .mcp.json) at this command.
+ * Logs go to stderr; stdout carries MCP JSON-RPC only.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { EnvExpansionError } from "./config.js";
+import { GATEWAY_VERSION } from "./gateway.js";
+import { GatewayConfigError, loadGatewayConfig, startGateway } from "./startup.js";
+
+const USAGE = `Usage: adtl-gateway --config <adtl.yaml>
+
+Runs an MCP server over stdio that forwards tool calls to the upstream
+servers in the config, checking and labeling each call with ADTL.
+
+Options:
+  -c, --config <path>  ADTL config file with a gateway: section. Required.
+  -v, --version        Print the version and exit.
+  -h, --help           Show this help.`;
+
+function parseArgs(argv: string[]): { config?: string; help?: boolean; version?: boolean } {
+  const out: { config?: string; help?: boolean; version?: boolean } = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") out.help = true;
+    else if (a === "-v" || a === "--version") out.version = true;
+    else if (a === "-c" || a === "--config") out.config = argv[++i];
+    else if (a?.startsWith("--config=")) out.config = a.slice("--config=".length);
+    else throw new GatewayConfigError(`Unknown argument: ${a}\n\n${USAGE}`);
+  }
+  return out;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  // --help and --version print to stdout and exit; MCP is never served in these modes.
+  if (args.help) return void console.log(USAGE);
+  if (args.version) return void console.log(GATEWAY_VERSION);
+  if (!args.config) throw new GatewayConfigError(`Missing --config\n\n${USAGE}`);
+
+  const loaded = await loadGatewayConfig(args.config);
+  const started = await startGateway(loaded);
+  const server = started.gateway.createServer();
+
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    await server.close().catch(() => undefined);
+    await started.close();
+    process.exit(0);
+  };
+  server.onclose = () => void shutdown();
+  // The agent closing our stdin means the session is over; don't wait for a signal.
+  process.stdin.on("end", () => void shutdown());
+  process.stdin.on("close", () => void shutdown());
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+
+  await server.connect(new StdioServerTransport());
+  console.error(`[adtl-gateway] ${GATEWAY_VERSION} ready (session ${started.gateway.sessionId})`);
+}
+
+main().catch((err: unknown) => {
+  const known = err instanceof GatewayConfigError || err instanceof EnvExpansionError;
+  console.error(known ? `[adtl-gateway] ${(err as Error).message}` : err);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,100 @@
+/**
+ * The `gateway:` section of adtl.yaml.
+ *
+ *   gateway:
+ *     audit: ./adtl-audit.jsonl          # optional JSONL audit log
+ *     upstreams:
+ *       github:                          # id must match `servers.github` in the label config
+ *         command: npx
+ *         args: ["-y", "@modelcontextprotocol/server-github"]
+ *         env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}" }
+ *       docs:
+ *         url: https://example.com/mcp
+ *         headers: { Authorization: "Bearer ${DOCS_TOKEN}" }
+ *
+ * `${VAR}` in command, args, env, cwd, url and headers is replaced from the
+ * gateway's environment. A missing variable is a config error.
+ */
+import { z } from "zod";
+
+const UPSTREAM_ID = /^[A-Za-z0-9-]+$/;
+
+export const StdioUpstreamSchema = z
+  .object({
+    command: z.string().min(1),
+    args: z.array(z.string()).default([]),
+    env: z.record(z.string()).default({}),
+    cwd: z.string().optional(),
+  })
+  .strict();
+
+export const HttpUpstreamSchema = z
+  .object({
+    url: z.string().min(1),
+    headers: z.record(z.string()).default({}),
+  })
+  .strict();
+
+export const UpstreamSchema = z.union([StdioUpstreamSchema, HttpUpstreamSchema]);
+export type StdioUpstream = z.infer<typeof StdioUpstreamSchema>;
+export type HttpUpstream = z.infer<typeof HttpUpstreamSchema>;
+export type Upstream = z.infer<typeof UpstreamSchema>;
+
+export const GatewayConfigSchema = z
+  .object({
+    upstreams: z
+      .record(UpstreamSchema)
+      .refine((u) => Object.keys(u).length > 0, "At least one upstream server is required")
+      .refine((u) => Object.keys(u).every((id) => UPSTREAM_ID.test(id)), {
+        message: "Upstream ids may only contain letters, digits and '-' (they prefix tool names as <id>__<tool>)",
+      }),
+    /** How to start the interceptor server. Default: the bundled adtl-interceptors with this same config file. */
+    interceptors: StdioUpstreamSchema.optional(),
+    /** Path of a JSONL audit log. Relative paths are resolved against the config file's directory. */
+    audit: z.string().min(1).optional(),
+    /** Timeout for each interceptor invocation, in milliseconds. */
+    interceptorTimeoutMs: z.number().int().positive().default(5000),
+  })
+  .strict();
+export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;
+
+export const TOOL_SEPARATOR = "__";
+
+export class EnvExpansionError extends Error {
+  constructor(readonly variable: string, where: string) {
+    super(`Environment variable ${variable} is not set (used in ${where})`);
+    this.name = "EnvExpansionError";
+  }
+}
+
+/** Replace `${VAR}` with values from `env`. `$${VAR}` keeps a literal `${VAR}`. */
+export function expandEnv(value: string, env: NodeJS.ProcessEnv, where: string): string {
+  return value.replace(/(\$?)\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, escape: string, name: string) => {
+    if (escape) return match.slice(1);
+    const v = env[name];
+    if (v === undefined) throw new EnvExpansionError(name, where);
+    return v;
+  });
+}
+
+function expandRecord(rec: Record<string, string>, env: NodeJS.ProcessEnv, where: string): Record<string, string> {
+  return Object.fromEntries(Object.entries(rec).map(([k, v]) => [k, expandEnv(v, env, `${where}.${k}`)]));
+}
+
+export function expandUpstream<T extends Upstream>(id: string, u: T, env: NodeJS.ProcessEnv): T {
+  const where = `gateway.upstreams.${id}`;
+  if ("url" in u) {
+    return { ...u, url: expandEnv(u.url, env, `${where}.url`), headers: expandRecord(u.headers, env, `${where}.headers`) };
+  }
+  return {
+    ...u,
+    command: expandEnv(u.command, env, `${where}.command`),
+    args: u.args.map((a, i) => expandEnv(a, env, `${where}.args[${i}]`)),
+    env: expandRecord(u.env, env, `${where}.env`),
+    ...(u.cwd !== undefined ? { cwd: expandEnv(u.cwd, env, `${where}.cwd`) } : {}),
+  };
+}
+
+export function isHttpUpstream(u: Upstream): u is HttpUpstream {
+  return "url" in u;
+}

package/src/gateway.ts

@@ -0,0 +1,198 @@
+/**
+ * The gateway: one MCP server facing the agent, many MCP clients facing the
+ * upstream servers, and an interceptor chain in between.
+ *
+ * tools/list  → every upstream's tools, renamed <upstream>__<tool>
+ * tools/call  → request interceptors (adtl.policy) → upstream → response
+ *               interceptors (adtl.label) → agent
+ *
+ * When a call is stopped, the agent receives a normal tool result with
+ * `isError: true` explaining why, so the model can tell the user. In v0.1 an
+ * "ask" decision is treated as a block; approvals arrive in v0.2.
+ */
+import { randomUUID } from "node:crypto";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+  type Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { InvocationContext } from "@adtl/interceptors";
+import type { AuditEntry, AuditSink } from "./audit.js";
+import { TOOL_SEPARATOR } from "./config.js";
+import type { Blocked, ChainOutcome, InterceptorInvoker } from "./invoker.js";
+
+export const GATEWAY_VERSION = "0.1.0";
+
+/** `_meta` key on gateway-generated error results describing why a call was stopped. */
+export const GATEWAY_DECISION_KEY = "adtl/gateway";
+
+interface Route {
+  upstream: string;
+  tool: string;
+  annotations?: Tool["annotations"];
+}
+
+export interface GatewayLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+const stderrLogger: GatewayLogger = {
+  info: (m) => console.error(`[adtl-gateway] ${m}`),
+  warn: (m) => console.error(`[adtl-gateway] warning: ${m}`),
+};
+
+export interface AdtlGatewayOptions {
+  upstreams: Map<string, Client>;
+  invoker: InterceptorInvoker;
+  /** One gateway process serves one agent session over stdio. */
+  sessionId?: string;
+  audit?: AuditSink;
+  logger?: GatewayLogger;
+}
+
+function textError(text: string, meta: Record<string, unknown>): CallToolResult {
+  return { content: [{ type: "text", text }], isError: true, _meta: { [GATEWAY_DECISION_KEY]: meta } };
+}
+
+function blockedMessage(b: Blocked): string {
+  if (b.decision === "ask") {
+    return (
+      `ADTL stopped this call because it needs a human's approval: ${b.reason}. ` +
+      `This version of ADTL cannot ask for approval yet, so the call was not run. Tell the user what you were trying to do.`
+    );
+  }
+  return `ADTL blocked this call: ${b.reason}. The call was not run.`;
+}
+
+function infoOf(outcome: ChainOutcome, interceptor: string): Record<string, unknown> {
+  return outcome.results.find((r) => r.interceptor === interceptor)?.info ?? {};
+}
+
+export class AdtlGateway {
+  readonly sessionId: string;
+  private readonly upstreams: Map<string, Client>;
+  private readonly invoker: InterceptorInvoker;
+  private readonly audit: AuditSink | undefined;
+  private readonly log: GatewayLogger;
+  private routes = new Map<string, Route>();
+
+  constructor(opts: AdtlGatewayOptions) {
+    this.upstreams = opts.upstreams;
+    this.invoker = opts.invoker;
+    this.sessionId = opts.sessionId ?? randomUUID();
+    this.audit = opts.audit;
+    this.log = opts.logger ?? stderrLogger;
+  }
+
+  /** The downstream MCP server the agent connects to. */
+  createServer(): Server {
+    const server = new Server(
+      { name: "adtl-gateway", version: GATEWAY_VERSION },
+      {
+        capabilities: { tools: {} },
+        instructions:
+          "Tools from several MCP servers, named <server>__<tool>. ADTL checks each call against trust labels; " +
+          "if a call is stopped, the result explains why.",
+      },
+    );
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await this.listTools() }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => this.callTool(req.params.name, req.params.arguments ?? {}));
+    return server;
+  }
+
+  async listTools(): Promise<Tool[]> {
+    const routes = new Map<string, Route>();
+    const tools: Tool[] = [];
+    for (const [upstream, client] of this.upstreams) {
+      let cursor: string | undefined;
+      try {
+        do {
+          const page = await client.listTools(cursor ? { cursor } : {});
+          for (const t of page.tools) {
+            const name = `${upstream}${TOOL_SEPARATOR}${t.name}`;
+            routes.set(name, { upstream, tool: t.name, ...(t.annotations ? { annotations: t.annotations } : {}) });
+            tools.push({ ...t, name });
+          }
+          cursor = page.nextCursor;
+        } while (cursor);
+      } catch (err) {
+        this.log.warn(`tools/list failed for ${upstream}: ${(err as Error).message}`);
+      }
+    }
+    this.routes = routes;
+    return tools;
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult> {
+    const started = performance.now();
+    let route = this.routes.get(name);
+    if (!route) {
+      await this.listTools();
+      route = this.routes.get(name);
+    }
+    if (!route) return textError(`Unknown tool: ${name}`, { reason: "unknown_tool" });
+
+    const client = this.upstreams.get(route.upstream)!;
+    const context: InvocationContext = {
+      sessionId: this.sessionId,
+      timestamp: new Date().toISOString(),
+      principal: { type: "anonymous" },
+    };
+    const config: Record<string, unknown> = {
+      server: route.upstream,
+      ...(route.annotations ? { toolAnnotations: route.annotations } : {}),
+    };
+    const base = { sessionId: this.sessionId, event: "tools/call" as const, server: route.upstream, tool: route.tool };
+    const finish = (entry: Omit<AuditEntry, keyof typeof base | "ts" | "durationMs">) =>
+      this.audit?.write({ ts: context.timestamp!, ...base, ...entry, durationMs: Math.round(performance.now() - started) });
+
+    // 1. Request phase: adtl.policy decides whether the call may run.
+    const requestPayload = { method: "tools/call", params: { name: route.tool, arguments: args } };
+    const req = await this.invoker.runRequest({ event: "tools/call", payload: requestPayload, config, context });
+    const policy = infoOf(req, "adtl.policy");
+    if (req.blocked) {
+      finish({ outcome: "blocked", decision: req.blocked.decision, reason: req.blocked.reason, matched: policy.matched, callHash: policy.callHash, sessionLabel: policy.sessionLabel, warnings: req.warnings });
+      this.log.info(`${req.blocked.decision} ${name}: ${req.blocked.reason}`);
+      return textError(blockedMessage(req.blocked), { ...req.blocked, callHash: policy.callHash });
+    }
+    const forwarded = (req.payload as typeof requestPayload).params;
+
+    // 2. Forward to the upstream server.
+    let result: CallToolResult;
+    try {
+      result = (await client.callTool({ name: forwarded.name, arguments: forwarded.arguments })) as CallToolResult;
+    } catch (err) {
+      const reason = (err as Error).message;
+      finish({ outcome: "upstream_error", decision: "allow", reason, callHash: policy.callHash, warnings: req.warnings });
+      return textError(`The ${route.upstream} server returned an error: ${reason}`, { reason: "upstream_error" });
+    }
+
+    // 3. Response phase: adtl.label labels the result and records it in the session.
+    const res = await this.invoker.runResponse({
+      event: "tools/call",
+      payload: { method: "tools/call", params: forwarded, result },
+      config,
+      context,
+    });
+    if (res.blocked) {
+      // Fail closed: an unlabeled result must not reach the agent.
+      finish({ outcome: "blocked", decision: res.blocked.decision, reason: res.blocked.reason, callHash: policy.callHash, warnings: [...req.warnings, ...res.warnings] });
+      this.log.warn(`result of ${name} withheld: ${res.blocked.reason}`);
+      return textError(`ADTL could not label the result of this call, so it was withheld: ${res.blocked.reason}`, { ...res.blocked });
+    }
+    const label = infoOf(res, "adtl.label");
+    finish({
+      outcome: "forwarded",
+      decision: (policy["adtl/decision"] as string | undefined) ?? "allow",
+      callHash: policy.callHash,
+      label: label.label,
+      sessionLabel: label.sessionLabel,
+      warnings: [...req.warnings, ...res.warnings],
+    });
+    return (res.payload as { result: CallToolResult }).result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./config.js";
+export * from "./invoker.js";
+export * from "./audit.js";
+export * from "./gateway.js";
+export * from "./startup.js";