@gethelio/proxy 0.2.0 → 0.4.0

package/dist/cli.js

@@ -171,6 +171,19 @@ var policiesSchema = z.object({
   flag_destructive: z.enum(["log", "require_approval"]).optional(),
   dry_run: z.boolean().default(false),
   rules: z.array(policyRuleSchema).default([]),
+  /**
+   * How to treat calls to a tool whose definition (annotations, schemas,
+   * description) has drifted from the baseline Helio captured on first
+   * sight.
+   * - "block": deny the call until the proxy is restarted (re-baselines)
+   *   or the upstream reverts. Conservative default when omitted.
+   * - "require_approval": escalate the call through the approval channel.
+   * - "log": audit the drift; rules evaluate against both baseline and
+   *   current annotations and the stricter decision wins.
+   * Kept optional (like hot_reload) so PoliciesConfig literal fixtures
+   * don't need the field; undefined is treated as "block".
+   */
+  on_tool_drift: z.enum(["block", "require_approval", "log"]).optional(),
   /**
    * Whether `helio start` should watch the config file for changes and
    * reconcile policy state on every save. Defaults to `true` when omitted.
@@ -233,14 +246,14 @@ var helioConfigBaseSchema = z.object({
 });
 var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
   const hasConfiguredEnvironment = typeof cfg.environment === "string" && cfg.environment.trim().length > 0;
-  const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval");
+  const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.on_tool_drift === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval");
   const hasSecret = hasDashboardApiSecret(cfg.dashboard.api_secret);
   if (requiresSecret) {
     if (!hasSecret) {
       ctx.addIssue({
         code: "custom",
         path: ["dashboard", "api_secret"],
-        message: 'dashboard.api_secret is required when any rule uses require_approval or policies.flag_destructive is "require_approval". Generate one with: `openssl rand -hex 32` and set it under `dashboard.api_secret` in your helio.yaml. (See docs/approvals.md.)'
+        message: 'dashboard.api_secret is required when any rule uses require_approval or policies.flag_destructive or policies.on_tool_drift is "require_approval". Generate one with: `openssl rand -hex 32` and set it under `dashboard.api_secret` in your helio.yaml. (See docs/approvals.md.)'
       });
     }
   }
@@ -459,6 +472,7 @@ function compilePolicies(config) {
     defaultAction: config.default,
     flagDestructive: config.flag_destructive,
     ...config.dry_run && { dryRun: true },
+    ...config.on_tool_drift && { onToolDrift: config.on_tool_drift },
     rules
   };
   return { policy, warnings };
@@ -1215,6 +1229,93 @@ async function parseUpstreamResponse(res) {
   return { status: res.status, headers, body };
 }
 
+// src/upstream/sse-parse.ts
+function parseSseChunk(chunk, state, onEvent) {
+  let { event, data, remainder } = state;
+  const text = remainder + chunk;
+  const lines = text.split("\n");
+  remainder = lines.pop() ?? "";
+  for (const rawLine of lines) {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    if (line === "") {
+      if (event || data) {
+        onEvent(event, data);
+        event = "";
+        data = "";
+      }
+    } else if (line.startsWith("event:")) {
+      const value = line.slice(6).replace(/^ /, "");
+      event = value;
+    } else if (line.startsWith("data:")) {
+      const value = line.slice(5).replace(/^ /, "");
+      data = data ? data + "\n" + value : value;
+    }
+  }
+  return { event, data, remainder };
+}
+async function readSseJsonRpcResponse(res, requestId) {
+  if (!res.body) {
+    throw new Error("upstream SSE response had no body");
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let state = { event: "", data: "", remainder: "" };
+  let found;
+  const onEvent = (event, data) => {
+    if (event && event !== "message") return;
+    let parsed;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (parsed === null || typeof parsed !== "object") return;
+    const id = parsed["id"];
+    if (id === requestId) {
+      found = parsed;
+    }
+  };
+  const processChunk = (chunk) => {
+    state = parseSseChunk(chunk, state, onEvent);
+  };
+  for (; ; ) {
+    const result = await reader.read();
+    if (result.value !== void 0) {
+      const chunk = result.value;
+      processChunk(decoder.decode(chunk, { stream: true }));
+      if (found) {
+        await reader.cancel().catch(() => void 0);
+        return found;
+      }
+    }
+    if (result.done) {
+      const tail = decoder.decode();
+      if (tail) {
+        processChunk(tail);
+        if (found) return found;
+      }
+      break;
+    }
+  }
+  throw new Error(
+    `upstream SSE stream closed with no JSON-RPC response for id ${String(requestId)}`
+  );
+}
+
+// src/upstream/merge-headers.ts
+function mergeUpstreamHeaders(base, forwarded, staticHeaders) {
+  const out = {};
+  const apply = (headers) => {
+    for (const [name, value] of Object.entries(headers)) {
+      out[name.toLowerCase()] = value;
+    }
+  };
+  apply(base);
+  apply(forwarded);
+  apply(staticHeaders);
+  return out;
+}
+
 // src/upstream/connection-error.ts
 var UPSTREAM_DOCS_URL = "https://github.com/gethelio/helio/blob/main/docs/getting-started.md";
 var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
@@ -1254,31 +1355,314 @@ function describeUnreachableUpstream(error, url) {
   );
 }
 
-// src/upstream/merge-headers.ts
-function mergeUpstreamHeaders(base, forwarded, staticHeaders) {
-  const out = {};
-  const apply = (headers) => {
-    for (const [name, value] of Object.entries(headers)) {
-      out[name.toLowerCase()] = value;
+// src/upstream/upstream-session-manager.ts
+var HELIO_MCP_PROTOCOL_VERSION = "2025-06-18";
+var MAX_SSE_ERROR_SCAN_BYTES = 256 * 1024;
+var UpstreamSessionManager = class {
+  url;
+  staticHeaders;
+  requestTimeoutMs;
+  internal;
+  inflight;
+  constructor(options) {
+    this.url = options.url;
+    this.staticHeaders = options.staticHeaders;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+  }
+  /** Return the internal session, performing the handshake once if needed. */
+  ensureInternalSession() {
+    if (this.internal) return Promise.resolve(this.internal);
+    this.inflight ??= this.initialize().then((session) => {
+      this.internal = session;
+      return session;
+    }).finally(() => {
+      this.inflight = void 0;
+    });
+    return this.inflight;
+  }
+  /**
+   * Drop the cached internal session so the next call re-initializes.
+   * Does not cancel any in-flight initialize.
+   */
+  invalidateInternalSession() {
+    this.internal = void 0;
+  }
+  /** Convert a fetch failure into an actionable error for the given step. */
+  describeFetchFailure(error, step) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      return new Error(`upstream ${step} timed out after ${String(this.requestTimeoutMs)}ms`);
     }
-  };
-  apply(base);
-  apply(forwarded);
-  apply(staticHeaders);
-  return out;
+    return describeUnreachableUpstream(error, this.url) ?? (error instanceof Error ? error : new Error(String(error)));
+  }
+  async initialize() {
+    const headers = mergeUpstreamHeaders(
+      {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream"
+      },
+      {},
+      this.staticHeaders
+    );
+    const initBody = {
+      jsonrpc: "2.0",
+      id: 0,
+      method: "initialize",
+      params: {
+        protocolVersion: HELIO_MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "helio-proxy", version: "0" }
+      }
+    };
+    let res;
+    try {
+      res = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(initBody),
+        signal: AbortSignal.timeout(this.requestTimeoutMs)
+      });
+    } catch (error) {
+      throw this.describeFetchFailure(error, "initialize");
+    }
+    if (!res.ok) {
+      throw new Error(`upstream initialize failed: HTTP ${String(res.status)}`);
+    }
+    const sessionId = res.headers.get("mcp-session-id") ?? void 0;
+    const initializeEnvelope = await this.readRequiredJsonRpcEnvelope(
+      res,
+      initBody.id,
+      "initialize"
+    );
+    const initializeError = extractJsonRpcErrorMessage(initializeEnvelope);
+    if (initializeError) {
+      throw new Error(`upstream initialize returned JSON-RPC error: ${initializeError}`);
+    }
+    const negotiatedProtocolVersion = extractNegotiatedProtocolVersion(initializeEnvelope);
+    const notifyHeaders = { ...headers };
+    if (sessionId) notifyHeaders["mcp-session-id"] = sessionId;
+    notifyHeaders["mcp-protocol-version"] = negotiatedProtocolVersion;
+    const notifyRes = await fetch(this.url, {
+      method: "POST",
+      headers: notifyHeaders,
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+      signal: AbortSignal.timeout(this.requestTimeoutMs)
+    }).catch((error) => {
+      throw this.describeFetchFailure(error, "notifications/initialized");
+    });
+    if (!notifyRes.ok) {
+      throw new Error(`upstream notifications/initialized failed: HTTP ${String(notifyRes.status)}`);
+    }
+    const notifyError = await this.readOptionalJsonRpcError(notifyRes);
+    if (notifyError) {
+      throw new Error(`upstream notifications/initialized returned JSON-RPC error: ${notifyError}`);
+    }
+    return { sessionId, protocolVersion: negotiatedProtocolVersion };
+  }
+  async readRequiredJsonRpcEnvelope(res, requestId, step) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      const payload = await readSseJsonRpcResponse(res, requestId);
+      return payload;
+    }
+    const raw = await res.text();
+    if (!raw.trim()) {
+      throw new Error(`upstream ${step} returned an empty body`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error(`upstream ${step} returned non-JSON body`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error(`upstream ${step} returned non-object JSON`);
+    }
+    return parsed;
+  }
+  async readOptionalJsonRpcError(res) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      if (!res.body) return void 0;
+      let errorMessage;
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let state = { event: "", data: "", remainder: "" };
+      let scannedBytes = 0;
+      const deadline = Date.now() + this.requestTimeoutMs;
+      const onEvent = (event, data) => {
+        if (errorMessage) return;
+        if (event && event !== "message") return;
+        let parsed2;
+        try {
+          parsed2 = JSON.parse(data);
+        } catch {
+          return;
+        }
+        if (typeof parsed2 !== "object" || parsed2 === null) return;
+        errorMessage = extractJsonRpcErrorMessage(parsed2);
+      };
+      for (; ; ) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          await reader.cancel().catch(() => void 0);
+          throw new Error(
+            `upstream notifications/initialized SSE response timed out after ${String(this.requestTimeoutMs)}ms`
+          );
+        }
+        let chunk;
+        try {
+          chunk = await readSseChunkWithTimeout(reader, remainingMs);
+        } catch {
+          await reader.cancel().catch(() => void 0);
+          throw new Error(
+            `upstream notifications/initialized SSE response timed out after ${String(this.requestTimeoutMs)}ms`
+          );
+        }
+        const { done, value } = chunk;
+        if (value !== void 0) {
+          scannedBytes += value.byteLength;
+          if (scannedBytes > MAX_SSE_ERROR_SCAN_BYTES) {
+            await reader.cancel().catch(() => void 0);
+            throw new Error(
+              `upstream notifications/initialized SSE response exceeded ${String(MAX_SSE_ERROR_SCAN_BYTES)} bytes`
+            );
+          }
+          state = parseSseChunk(decoder.decode(value, { stream: true }), state, onEvent);
+          if (errorMessage) {
+            await reader.cancel().catch(() => void 0);
+            return errorMessage;
+          }
+        }
+        if (done) {
+          const tail = decoder.decode();
+          if (tail) {
+            state = parseSseChunk(tail, state, onEvent);
+          }
+          return errorMessage;
+        }
+      }
+    }
+    const raw = await res.text();
+    if (!raw.trim()) return void 0;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+    if (typeof parsed !== "object" || parsed === null) return void 0;
+    return extractJsonRpcErrorMessage(parsed);
+  }
+};
+async function readSseChunkWithTimeout(reader, timeoutMs) {
+  let timeoutHandle;
+  try {
+    const result = await Promise.race([
+      reader.read(),
+      new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+          reject(new Error(`sse read timed out after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
+      })
+    ]);
+    if (!isSseReadChunk(result)) {
+      throw new Error("upstream notifications/initialized SSE response returned invalid chunk");
+    }
+    return result;
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+}
+function isSseReadChunk(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (typeof candidate.done !== "boolean") return false;
+  if (candidate.value === void 0) return true;
+  return candidate.value instanceof Uint8Array;
+}
+function extractJsonRpcErrorMessage(payload) {
+  const error = payload["error"];
+  if (typeof error === "string") return error;
+  if (typeof error !== "object" || error === null) return void 0;
+  const message = error["message"];
+  if (typeof message === "string" && message.trim()) return message;
+  return "unknown JSON-RPC error";
+}
+function extractNegotiatedProtocolVersion(payload) {
+  const result = payload["result"];
+  if (typeof result !== "object" || result === null) {
+    return HELIO_MCP_PROTOCOL_VERSION;
+  }
+  const protocolVersion = result["protocolVersion"];
+  return typeof protocolVersion === "string" && protocolVersion.trim() ? protocolVersion : HELIO_MCP_PROTOCOL_VERSION;
 }
 
-// src/upstream/forwarder.ts
-var UpstreamForwarder = class {
+// src/upstream/streamable-http-forwarder.ts
+var StreamableHttpForwarder = class {
   url;
   staticHeaders;
   requestTimeoutMs;
+  sessions;
   constructor(options) {
     this.url = options.url;
     this.staticHeaders = options.headers ?? {};
     this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+    this.sessions = new UpstreamSessionManager({
+      url: this.url,
+      staticHeaders: this.staticHeaders,
+      requestTimeoutMs: this.requestTimeoutMs
+    });
+  }
+  /** Lifecycle parity with sse/stdio. No eager connect — sessions are lazy. */
+  connect() {
+    return Promise.resolve();
+  }
+  /** Lifecycle parity with sse/stdio. */
+  close() {
+    this.sessions.invalidateInternalSession();
+    return Promise.resolve();
   }
   async forward(request) {
+    if (request.method === "initialize") {
+      return this.send(
+        request,
+        request.sessionId,
+        /* protocolVersion */
+        void 0
+      );
+    }
+    return this.send(request, request.sessionId, HELIO_MCP_PROTOCOL_VERSION);
+  }
+  /**
+   * Helio-internal execution path (startup prime / internal maintenance) that
+   * may borrow the proxy-managed internal session.
+   */
+  async forwardInternal(request) {
+    const session = await this.sessions.ensureInternalSession();
+    try {
+      return await this.send(
+        request,
+        session.sessionId,
+        session.protocolVersion,
+        /* internalManaged */
+        true
+      );
+    } catch (error) {
+      if (error instanceof UpstreamSessionExpiredError) {
+        this.sessions.invalidateInternalSession();
+        const fresh = await this.sessions.ensureInternalSession();
+        return this.send(
+          request,
+          fresh.sessionId,
+          fresh.protocolVersion,
+          /* internalManaged */
+          true
+        );
+      }
+      throw error;
+    }
+  }
+  async send(request, sessionId, protocolVersion, internalManaged = false) {
     const headers = mergeUpstreamHeaders(
       {
         "content-type": "application/json",
@@ -1287,8 +1671,9 @@ var UpstreamForwarder = class {
       request.headers ?? {},
       this.staticHeaders
     );
-    if (request.sessionId) {
-      headers["mcp-session-id"] = request.sessionId;
+    if (sessionId) headers["mcp-session-id"] = sessionId;
+    if (protocolVersion && headers["mcp-protocol-version"] === void 0) {
+      headers["mcp-protocol-version"] = protocolVersion;
     }
     const body = {
       jsonrpc: request.jsonrpc,
@@ -1302,31 +1687,46 @@ var UpstreamForwarder = class {
     const signal = requestSignal ? AbortSignal.any([requestSignal, timeoutSignal]) : timeoutSignal;
     let res;
     try {
-      res = await fetch(this.url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-        signal
-      });
+      res = await fetch(this.url, { method: "POST", headers, body: JSON.stringify(body), signal });
     } catch (error) {
       const isTimeout = error instanceof Error && error.name === "TimeoutError";
-      if (requestSignal?.aborted) {
-        throw new Error("request aborted by downstream client");
-      }
+      if (requestSignal?.aborted) throw new Error("request aborted by downstream client");
       if (isTimeout) {
         throw new Error(`upstream request timed out after ${String(this.requestTimeoutMs)}ms`);
       }
       throw describeUnreachableUpstream(error, this.url) ?? error;
     }
-    const durationMs = performance.now() - start;
+    if (internalManaged && res.status === 404 && sessionId) {
+      await res.text().catch(() => void 0);
+      throw new UpstreamSessionExpiredError();
+    }
     const contentType = res.headers.get("content-type") ?? "";
     if (contentType.includes("text/event-stream")) {
-      throw new Error(
-        "upstream returned text/event-stream; streamable-http passthrough is not supported in v0.1"
-      );
+      const responseHeaders = {};
+      res.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+      if (request.id === void 0) {
+        await res.body?.cancel().catch(() => void 0);
+        const response3 = {
+          status: res.status,
+          headers: responseHeaders,
+          body: { jsonrpc: "2.0" }
+        };
+        return { response: response3, durationMs: performance.now() - start };
+      }
+      const jsonRpc = await readSseJsonRpcResponse(res, request.id);
+      const response2 = { status: res.status, headers: responseHeaders, body: jsonRpc };
+      return { response: response2, durationMs: performance.now() - start };
     }
     const response = await parseUpstreamResponse(res);
-    return { response, durationMs };
+    return { response, durationMs: performance.now() - start };
+  }
+};
+var UpstreamSessionExpiredError = class extends Error {
+  constructor() {
+    super("upstream session expired (HTTP 404) for Helio-managed internal session");
+    this.name = "UpstreamSessionExpiredError";
   }
 };
 
@@ -1399,26 +1799,6 @@ function buildRequestSignal(request, timeoutMs) {
   const timeoutSignal = AbortSignal.timeout(timeoutMs);
   return request.signal ? AbortSignal.any([request.signal, timeoutSignal]) : timeoutSignal;
 }
-function parseSseChunk(chunk, state, onEvent) {
-  let { event, data, remainder } = state;
-  const text = remainder + chunk;
-  const lines = text.split("\n");
-  remainder = lines.pop() ?? "";
-  for (const line of lines) {
-    if (line === "") {
-      if (event || data) {
-        onEvent(event, data);
-        event = "";
-        data = "";
-      }
-    } else if (line.startsWith("event: ")) {
-      event = line.slice(7);
-    } else if (line.startsWith("data: ")) {
-      data = data ? data + "\n" + line.slice(6) : line.slice(6);
-    }
-  }
-  return { event, data, remainder };
-}
 var SseUpstreamForwarder = class {
   url;
   staticHeaders;
@@ -1812,13 +2192,13 @@ var StdioForwarder = class {
 async function createForwarderFromConfig(config) {
   switch (config.upstream.transport) {
     case "streamable-http": {
-      return {
-        forwarder: new UpstreamForwarder({
-          url: config.upstream.url,
-          headers: config.upstream.headers,
-          requestTimeoutMs: parseDuration(config.upstream.request_timeout)
-        })
-      };
+      const http = new StreamableHttpForwarder({
+        url: config.upstream.url,
+        headers: config.upstream.headers,
+        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
+      });
+      await http.connect();
+      return { forwarder: http, close: () => http.close() };
     }
     case "sse": {
       const sse = new SseUpstreamForwarder({
@@ -1940,49 +2320,161 @@ function evaluatePolicy(policy, ctx) {
 }
 
 // src/policy/annotation-cache.ts
+var ASPECT_FIELDS = [
+  "annotations",
+  "inputSchema",
+  "description",
+  "outputSchema",
+  "title"
+];
 var ToolAnnotationCache = class {
-  cache = /* @__PURE__ */ new Map();
-  /** Number of tools currently cached. */
+  baselines = /* @__PURE__ */ new Map();
+  present = /* @__PURE__ */ new Set();
+  currentAnnotations = /* @__PURE__ */ new Map();
+  driftedTools = /* @__PURE__ */ new Map();
+  /** Number of tools present in the most recent tools/list. */
   get size() {
-    return this.cache.size;
+    return this.present.size;
   }
-  /**
-   * Update the cache from a tools/list JSON-RPC response body.
-   *
-   * Performs a full replacement — tools that existed in the previous cache
-   * but are absent from the new response are removed. This correctly handles
-   * tool list changes (additions, removals, annotation updates).
-   *
-   * @returns `true` if the response body was a valid tools/list response and
-   *   the cache was updated, `false` if the body shape was unexpected.
-   */
+  /** Diff a tools/list JSON-RPC response body against the baselines. */
   update(responseBody) {
     const tools = extractTools(responseBody);
-    if (!tools) return false;
-    this.cache.clear();
+    if (!tools) return { updated: false, baselined: [], drifted: [], reverted: [] };
+    const baselined = [];
+    const drifted = [];
+    const reverted = [];
+    const present = /* @__PURE__ */ new Set();
+    const currentAnnotations = /* @__PURE__ */ new Map();
+    const entries = [];
+    const nameCounts = /* @__PURE__ */ new Map();
     for (const tool of tools) {
       if (typeof tool !== "object" || tool === null) continue;
       const t = tool;
       const name = t["name"];
       if (typeof name !== "string") continue;
-      const annotations = t["annotations"];
-      if (annotations && typeof annotations === "object") {
-        this.cache.set(name, annotations);
-      } else {
-        this.cache.set(name, void 0);
+      entries.push({ name, definition: t });
+      nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
+    }
+    const duplicateNames = /* @__PURE__ */ new Set();
+    for (const { name, definition: t } of entries) {
+      const isDuplicate = (nameCounts.get(name) ?? 0) > 1;
+      if (isDuplicate) {
+        present.add(name);
+        currentAnnotations.set(name, void 0);
+        if (duplicateNames.has(name)) continue;
+        duplicateNames.add(name);
+        const baseline2 = this.baselines.get(name);
+        const allDefinitions = entries.filter((e) => e.name === name).map((e) => e.definition);
+        const changes2 = [
+          {
+            aspect: "duplicate",
+            baseline: baseline2?.definition,
+            current: allDefinitions
+          }
+        ];
+        const event2 = { toolName: name, changes: changes2 };
+        const existing2 = this.driftedTools.get(name);
+        const isNewDrift2 = !existing2 || canonicalize(existing2.changes) !== canonicalize(changes2);
+        this.driftedTools.set(name, event2);
+        if (isNewDrift2) drifted.push(event2);
+        continue;
+      }
+      present.add(name);
+      const annotations = extractAnnotations(t);
+      currentAnnotations.set(name, annotations);
+      const definitionKey = canonicalize(t);
+      const baseline = this.baselines.get(name);
+      if (!baseline) {
+        this.baselines.set(name, { definition: t, definitionKey, annotations });
+        baselined.push(name);
+        if (this.driftedTools.has(name)) {
+          this.driftedTools.delete(name);
+          reverted.push(name);
+        }
+        continue;
       }
+      if (definitionKey === baseline.definitionKey) {
+        if (this.driftedTools.has(name)) {
+          this.driftedTools.delete(name);
+          reverted.push(name);
+        }
+        continue;
+      }
+      const changes = [];
+      for (const field of ASPECT_FIELDS) {
+        const baselineValue = baseline.definition[field];
+        const currentValue = t[field];
+        if (canonicalize(baselineValue) !== canonicalize(currentValue)) {
+          changes.push({ aspect: field, baseline: baselineValue, current: currentValue });
+        }
+      }
+      if (changes.length === 0) {
+        changes.push({ aspect: "other", baseline: baseline.definition, current: t });
+      }
+      const event = { toolName: name, changes };
+      const existing = this.driftedTools.get(name);
+      const isNewDrift = !existing || canonicalize(existing.changes) !== canonicalize(changes);
+      this.driftedTools.set(name, event);
+      if (isNewDrift) drifted.push(event);
     }
-    return true;
+    this.present = present;
+    this.currentAnnotations = currentAnnotations;
+    return { updated: true, baselined, drifted, reverted };
   }
-  /** Get cached annotations for a tool. Returns `undefined` if the tool is not in the cache. */
+  /**
+   * Get the **baseline** annotations for a tool — the definition first seen,
+   * not the latest upstream claim. Returns `undefined` if the tool has no
+   * annotations or was never seen.
+   */
   get(toolName) {
-    return this.cache.get(toolName);
+    return this.baselines.get(toolName)?.annotations;
   }
-  /** Check whether a tool exists in the cache (regardless of whether it has annotations). */
+  /**
+   * Get the annotations from the most recent tools/list. Used for the
+   * stricter-of-both evaluation of drifted tools in on_tool_drift: log mode.
+   * Returns `undefined` for tools absent from the latest list.
+   */
+  getCurrent(toolName) {
+    return this.currentAnnotations.get(toolName);
+  }
+  /** Whether the tool was present in the most recent tools/list. */
   has(toolName) {
-    return this.cache.has(toolName);
+    return this.present.has(toolName);
+  }
+  /** Whether the tool's current definition differs from its baseline. */
+  isDrifted(toolName) {
+    return this.driftedTools.has(toolName);
+  }
+  /** The active drift event for a tool, if any. */
+  getDrift(toolName) {
+    return this.driftedTools.get(toolName);
   }
 };
+function extractAnnotations(tool) {
+  const annotations = tool["annotations"];
+  return annotations && typeof annotations === "object" ? annotations : void 0;
+}
+function canonicalize(value) {
+  const encoded = JSON.stringify(sortKeysDeep(value));
+  return encoded ?? "";
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === "object") {
+    const source = value;
+    const out = {};
+    for (const key of Object.keys(source).sort()) {
+      Object.defineProperty(out, key, {
+        value: sortKeysDeep(source[key]),
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+    }
+    return out;
+  }
+  return value;
+}
 function extractTools(body) {
   if (typeof body !== "object" || body === null) return null;
   const b = body;
@@ -2184,6 +2676,19 @@ function buildRateLimitedFeedback(decision, result) {
     retry_allowed: true
   };
 }
+function buildToolDriftFeedback(drift, action) {
+  const aspects = drift.changes.map((change) => change.aspect);
+  return {
+    blocked: true,
+    reason: "tool_definition_drift",
+    rule: null,
+    ruleIndex: null,
+    action,
+    drifted_aspects: aspects,
+    suggestion: `The definition of "${drift.toolName}" changed upstream (${aspects.join(", ")}) after Helio baselined it. An operator must review the change; restarting the proxy re-baselines, or the upstream can revert the change.`,
+    retry_allowed: false
+  };
+}
 function buildSpendLimitedFeedback(decision, result, currency) {
   const { rule, ruleIndex } = ruleInfo(decision.matchedRule);
   const windowSeconds = Math.round(result.windowMs / 1e3);
@@ -2298,6 +2803,11 @@ var GovernedForwarder = class {
    *
    * This path is intended for startup warm-up and intentionally bypasses policy
    * and audit handling. Runtime tools/list requests still flow through forward().
+   *
+   * When the inner forwarder exposes `forwardInternal` (duck-typed), the prime
+   * request is routed through it so session-enforcing servers (e.g. Streamable
+   * HTTP upstreams) receive the request on the managed internal session rather
+   * than as a sessionless call that they would reject with HTTP 400.
    */
   async primeAnnotationCache() {
     const syntheticToolsList = {
@@ -2305,14 +2815,22 @@ var GovernedForwarder = class {
       id: "helio-prime-annotations",
       method: "tools/list"
     };
+    const internal = this.inner;
     try {
-      const result = await this.inner.forward(syntheticToolsList);
-      const updated = this.annotationCache.update(result.response.body);
-      if (!updated) {
+      const result = typeof internal.forwardInternal === "function" ? await internal.forwardInternal(syntheticToolsList) : await this.inner.forward(syntheticToolsList);
+      if (result.response.status >= 400) {
         return {
           success: false,
           toolsCached: this.annotationCache.size,
-          reason: "upstream tools/list response had unexpected shape"
+          reason: classifyPrimeFailure(result.response)
+        };
+      }
+      const update = this.applyToolDefinitionUpdate(result.response.body, void 0);
+      if (!update.updated) {
+        return {
+          success: false,
+          toolsCached: this.annotationCache.size,
+          reason: classifyPrimeFailure(result.response)
         };
       }
       return { success: true, toolsCached: this.annotationCache.size };
@@ -2330,10 +2848,62 @@ var GovernedForwarder = class {
     }
     const result = await this.inner.forward(request);
     if (request.method === "tools/list") {
-      this.annotationCache.update(result.response.body);
+      this.applyToolDefinitionUpdate(result.response.body, request.sessionId);
     }
     return result;
   }
+  /**
+   * Apply a tools/list response to the definition cache and surface any
+   * drift: console warning + immediate audit record per event. Single entry
+   * point for both runtime tools/list responses and startup priming, so the
+   * cache is updated exactly once per response.
+   */
+  applyToolDefinitionUpdate(responseBody, sessionId) {
+    const update = this.annotationCache.update(responseBody);
+    if (!update.updated) return update;
+    for (const drift of update.drifted) {
+      const aspects = drift.changes.map((change) => change.aspect).join(", ");
+      console.error(
+        `[helio] Tool definition drift detected: "${drift.toolName}" changed (${aspects}) after baseline \u2014 calls governed by policies.on_tool_drift (${this.policy.onToolDrift ?? "block"})`
+      );
+      this.writeDriftAuditRecord(drift, sessionId, "tool_drift");
+    }
+    for (const toolName of update.reverted) {
+      console.error(
+        `[helio] Tool definition drift cleared: "${toolName}" returned to its baseline definition`
+      );
+      this.writeDriftAuditRecord({ toolName, changes: [] }, sessionId, "tool_drift_reverted");
+    }
+    return update;
+  }
+  /** Write an immediate audit record for a drift event (not a tool call). */
+  writeDriftAuditRecord(drift, sessionId, decision) {
+    if (!this.auditWriter) return;
+    this.auditWriter.pushImmediate({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      session_id: sessionId ?? null,
+      agent_id: null,
+      environment: this.environment ?? null,
+      tool_name: drift.toolName,
+      tool_input: {},
+      policy_decision: decision,
+      block_reason: null,
+      matched_rule: null,
+      matched_rule_index: null,
+      evidence_chain: decision === "tool_drift" ? { tool_drift: { changes: drift.changes } } : null,
+      approval_status: null,
+      approved_by: null,
+      upstream_response: null,
+      upstream_error: null,
+      upstream_http_status: null,
+      upstream_latency_ms: null,
+      total_duration_ms: 0,
+      approval_wait_ms: 0,
+      proxy_compute_ms: 0,
+      flagged_destructive: false,
+      dry_run: false
+    });
+  }
   async handleToolsCall(request) {
     const startTime = performance.now();
     const timestamp = (/* @__PURE__ */ new Date()).toISOString();
@@ -2344,13 +2914,26 @@ var GovernedForwarder = class {
     }
     const toolArguments = params?.["arguments"] && typeof params["arguments"] === "object" ? params["arguments"] : void 0;
     const annotations = this.annotationCache.get(toolName);
+    const driftEvent = this.annotationCache.getDrift(toolName);
+    const driftMode = this.policy.onToolDrift ?? "block";
     let decision = evaluatePolicy(this.policy, {
       toolName,
       annotations,
       toolArguments,
       environment: this.environment
     });
-    const isDestructive = annotations?.destructiveHint ?? true;
+    if (driftEvent && driftMode === "log") {
+      const currentDecision = evaluatePolicy(this.policy, {
+        toolName,
+        annotations: this.annotationCache.getCurrent(toolName),
+        toolArguments,
+        environment: this.environment
+      });
+      decision = stricterDecision(decision, currentDecision);
+    }
+    const baselineDestructive = annotations?.destructiveHint ?? true;
+    const currentDestructive = driftEvent && driftMode === "log" ? this.annotationCache.getCurrent(toolName)?.destructiveHint ?? true : false;
+    const isDestructive = baselineDestructive || currentDestructive;
     let flaggedDestructive = false;
     if (isDestructive && !decision.matchedRule && this.policy.flagDestructive) {
       flaggedDestructive = true;
@@ -2364,6 +2947,15 @@ var GovernedForwarder = class {
         };
       }
     }
+    let driftBlocked = false;
+    if (driftEvent && driftMode !== "log") {
+      driftBlocked = driftMode === "block";
+      decision = {
+        action: driftMode === "block" ? "deny" : "require_approval",
+        matchedRule: void 0,
+        reason: `Tool "${toolName}" definition drifted from baseline (${driftEvent.changes.map((change) => change.aspect).join(", ")})`
+      };
+    }
     const originalAction = decision.action;
     let evidenceResult;
     let dependencyResult;
@@ -2427,6 +3019,8 @@ var GovernedForwarder = class {
         result = this.makeSessionRequiredBlockResult(request, decision);
       } else if (evidenceBlocked) {
         result = this.makeEvidenceBlockResult(request, decision, evidenceResult, dependencyResult);
+      } else if (driftBlocked && driftEvent) {
+        result = this.makeDriftBlockResult(request, driftEvent);
       } else if (decision.action === "allow") {
         result = await this.inner.forward(request);
       } else if (decision.action === "deny") {
@@ -2499,7 +3093,8 @@ var GovernedForwarder = class {
       rateLimitResult,
       spendLimitResult,
       isDryRun,
-      forwardingError
+      forwardingError,
+      driftEvent ? { event: driftEvent, mode: driftMode } : void 0
     );
     return result;
   }
@@ -2716,7 +3311,7 @@ var GovernedForwarder = class {
   wasForwardedUpstream(decision, approvalOutcome, rateLimitResult, spendLimitResult) {
     return decision.action === "allow" || approvalOutcome?.status === "approved" || approvalOutcome?.status === "break_glass" || approvalOutcome?.status === "timeout" && this.approvalRouter?.defaultOnTimeout === "allow" || rateLimitResult?.allowed === true || spendLimitResult?.allowed === true;
   }
-  writeAuditRecord(request, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, evidenceResult, dependencyResult, evidenceBlocked, approvalOutcome, rateLimitResult, spendLimitResult, isDryRun, forwardingError) {
+  writeAuditRecord(request, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, evidenceResult, dependencyResult, evidenceBlocked, approvalOutcome, rateLimitResult, spendLimitResult, isDryRun, forwardingError, drift) {
     if (!this.auditWriter) return;
     const wasForwarded = this.wasForwardedUpstream(
       decision,
@@ -2776,6 +3371,15 @@ var GovernedForwarder = class {
         }
       };
     }
+    if (drift) {
+      evidenceChain = {
+        ...evidenceChain ?? {},
+        tool_drift: {
+          mode: drift.mode,
+          changes: drift.event.changes
+        }
+      };
+    }
     const blockReason = extractBlockReason(result);
     const record = {
       timestamp,
@@ -2808,6 +3412,15 @@ var GovernedForwarder = class {
       this.auditWriter.push(record);
     }
   }
+  makeDriftBlockResult(request, drift) {
+    const feedback = buildToolDriftFeedback(drift, "deny");
+    return makeErrorResult(
+      request,
+      POLICY_DENIED,
+      `Tool definition drift: "${drift.toolName}" changed after baseline`,
+      { ...feedback }
+    );
+  }
   makeDenyResult(request, decision) {
     const feedback = buildPolicyDeniedFeedback(decision);
     const message = decision.matchedRule?.feedback?.message ?? `Policy denied: ${decision.reason}`;
@@ -2896,6 +3509,17 @@ function collectAllowedEvidenceKeys(policy) {
   }
   return [...keys];
 }
+var ACTION_SEVERITY = {
+  deny: 5,
+  require_approval: 4,
+  dry_run: 3,
+  spend_limit: 2,
+  rate_limit: 1,
+  allow: 0
+};
+function stricterDecision(a, b) {
+  return ACTION_SEVERITY[b.action] > ACTION_SEVERITY[a.action] ? b : a;
+}
 function makeErrorResult(request, code, message, data) {
   const body = {
     jsonrpc: "2.0",
@@ -2913,6 +3537,27 @@ function hasJsonRpcError(result) {
   const body = result.response.body;
   return body?.["error"] !== void 0;
 }
+function classifyPrimeFailure(response) {
+  if (response.status >= 400) {
+    return `upstream returned HTTP ${String(response.status)} to tools/list (session/initialize may be required)`;
+  }
+  const rawBody = response.body;
+  if (typeof rawBody !== "object" || rawBody === null) {
+    return `upstream tools/list returned a non-JSON body (content-type ${response.headers["content-type"] ?? "unknown"})`;
+  }
+  const body = rawBody;
+  const error = body["error"];
+  if (typeof error === "string") {
+    return `upstream tools/list returned a JSON-RPC error: ${error}`;
+  }
+  if (error !== null && typeof error === "object") {
+    const message = error["message"];
+    if (typeof message === "string") {
+      return `upstream tools/list returned a JSON-RPC error: ${message}`;
+    }
+  }
+  return "upstream tools/list response was missing result.tools";
+}
 function extractBlockReason(result) {
   const body = result.response.body;
   const error = body?.["error"];
@@ -3440,6 +4085,7 @@ function clampInt(value, fallback, min, max) {
 }
 
 // src/audit/store.ts
+var DRIFT_EVENT_DECISIONS_SQL = "('tool_drift', 'tool_drift_reverted')";
 var CREATE_TABLE_DDL = `
 CREATE TABLE IF NOT EXISTS audit_records (
   id                TEXT PRIMARY KEY,
@@ -3743,7 +4389,7 @@ var AuditStore = class {
     const totals = this.db.prepare(
       `SELECT
            COUNT(*) as total,
-           COALESCE(SUM(CASE WHEN block_reason IS NULL THEN 1 ELSE 0 END), 0) as allowed_total,
+           COALESCE(SUM(CASE WHEN block_reason IS NULL AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL} THEN 1 ELSE 0 END), 0) as allowed_total,
            COALESCE(SUM(CASE WHEN block_reason IS NOT NULL THEN 1 ELSE 0 END), 0) as blocked_total,
            COALESCE(SUM(CASE WHEN dry_run = 1 THEN 1 ELSE 0 END), 0) as dry_run_total,
            COALESCE(SUM(CASE WHEN dry_run = 0 THEN 1 ELSE 0 END), 0) as applied_total
@@ -3762,9 +4408,10 @@ var AuditStore = class {
          GROUP BY block_reason
          ORDER BY count DESC`
     ).all(...params);
+    const toolsClause = clause ? `${clause} AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL}` : `WHERE policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL}`;
     const top_tools = this.db.prepare(
       `SELECT tool_name, COUNT(*) as count
-         FROM audit_records ${clause}
+         FROM audit_records ${toolsClause}
          GROUP BY tool_name
          ORDER BY count DESC
          LIMIT 10`
@@ -6035,7 +6682,9 @@ async function startAnnotationPrimeLoop(governedForwarder) {
       primed = true;
       clearRetryTimer();
       const prefix = phase === "initial" ? "[helio] Annotation cache primed" : `[helio] Annotation cache primed after retry ${String(retryAttempt)}`;
-      console.error(`${prefix}: ${String(result.toolsCached)} tools cached`);
+      console.error(
+        `${prefix}: ${String(result.toolsCached)} tool definitions baselined for drift detection (baselines are per-process; a restart re-baselines \u2014 review tool_drift audit records before restarting)`
+      );
       return;
     }
     const reason = result.reason ?? "unknown reason";