@agenthippo-ai/agenthippo 1.110.11 → 1.110.19

package/out/cli/serve-hardening.js

@@ -1,776 +0,0 @@
-"use strict";
-/*---------------------------------------------------------------------------------------------
- *  Copyright (c) AgentHippo.ai. All rights reserved.
- *--------------------------------------------------------------------------------------------*/
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TurnGate = exports.TURN_LIMIT_BUSY_MESSAGE = exports.RATE_LIMIT_BUSY_MESSAGE = exports.TURN_GATE_BUSY_MESSAGE = exports.TURN_GATE_RETRY_AFTER_SECONDS = exports.TURN_QUEUE_ENV = exports.MAX_CONCURRENT_TURNS_ENV = exports.TurnLimiter = exports.SESSION_WITHOUT_USER_REASON = exports.REQUIRE_TENANT_ISOLATION_ENV = exports.IDENTITY_PROXY_SECRET_ENV = exports.IDENTITY_HEADER_ENV = exports.PIN_ONLY_IDENTITY_HEADERS = exports.RateLimiter = exports.XFF_TRUSTED_HOPS_ENV = exports.CONTAINER_SERVE_HOST = exports.SERVE_HOST_ENV = exports.DEFAULT_BIND_HOST = exports.SERVICE_USER_ENV = exports.DEFAULT_MAX_BODY_BYTES = void 0;
-exports.resolveStateDir = resolveStateDir;
-exports.resolveAnalyticsSessionsDir = resolveAnalyticsSessionsDir;
-exports.resolveServiceIdentity = resolveServiceIdentity;
-exports.isLoopbackHost = isLoopbackHost;
-exports.resolveBindHost = resolveBindHost;
-exports.clientIp = clientIp;
-exports.hasTrustedProxyProof = hasTrustedProxyProof;
-exports.identityHeaderAdvice = identityHeaderAdvice;
-exports.tenantIsolationAdvice = tenantIsolationAdvice;
-exports.resolveUserId = resolveUserId;
-exports.resolveDataToken = resolveDataToken;
-exports.peerToUserId = peerToUserId;
-exports.userNamespaceHash = userNamespaceHash;
-exports.resolveServeSessionKey = resolveServeSessionKey;
-exports.corsHeaders = corsHeaders;
-exports.createTurnGateFromEnv = createTurnGateFromEnv;
-exports.createRejectionWarner = createRejectionWarner;
-exports.readBodyWithCap = readBodyWithCap;
-/**
- * Serve helpers: state-dir resolution, identity header reading, CORS, turn limiting, body cap.
- *
- * Auth and credential checking are the deploy layer's responsibility (Caddy, Cloud Run IAP,
- * Databricks Apps SSO, etc.). Serve trusts the identity headers set by the layer in front;
- * it does not validate tokens or enforce bearer keys itself.
- *
- * SECURITY CONTRACT: serve trusts the identity and data-token headers below unconditionally.
- * It MUST sit behind a proxy that (a) authenticates the caller and sets the identity header,
- * and (b) STRIPS any client-supplied copies of these headers on the way in. Deployments where
- * other workloads share the network with serve (compose, sidecar platforms) can additionally
- * require proof that a request came through that proxy — see IDENTITY_PROXY_SECRET_ENV.
- */
-const os = __importStar(require("os"));
-const path = __importStar(require("path"));
-const crypto = __importStar(require("crypto"));
-const paths_1 = require("../utils/paths");
-const config_1 = require("../auth-broker/config");
-/** Default cap on a single request body (1 MiB). Chat messages are small; large bodies are abuse or bugs. */
-exports.DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
-/**
- * Resolve where session state is persisted. Precedence:
- *   1. explicit --state-dir
- *   2. AGENTHIPPO_HOME (the documented container mount point)
- *   3. tmpdir (dev/local only; lost on restart)
- *
- * Returns `{ dir, ephemeral }` so the caller can warn when ephemeral state is
- * detected in a long-lived deployment.
- */
-function resolveStateDir(stateDirOpt, env = process.env) {
-    const explicit = stateDirOpt?.trim();
-    if (explicit) {
-        return { dir: path.resolve(explicit), ephemeral: false };
-    }
-    const home = env.AGENTHIPPO_HOME?.trim() || env.AGENTIDE_HOME?.trim();
-    if (home) {
-        return { dir: path.join(path.resolve(home), 'serve-state'), ephemeral: false };
-    }
-    return { dir: path.join(os.tmpdir(), 'agenthippo-server'), ephemeral: true };
-}
-/**
- * Where serve's Layer 2 analytics (tool-call/warrant JSONL) should live. Precedence:
- *   1. AGENT_HOME_DIR / AGENTHIPPO_HOME set → getAgentideHome()/analytics/sessions — the
- *      exact location sessionJsonlFleet.ts and query-analytics.sh already scan by default,
- *      so this data stays discoverable to Spotlight/DuckDB.
- *   2. Neither set, but the resolved state dir is non-ephemeral (an explicit --state-dir
- *      was given) → <stateDir>/analytics/sessions. Not the canonical scan location, but
- *      still durable — never regress below whatever durability the caller already
- *      established just to be discoverable.
- *   3. Neither set and state is ephemeral (no --state-dir, no home-dir env var at all) →
- *      falls through to getAgentideHome()'s own os.homedir() default, matching the
- *      already-correct IDE-local behavior — nothing durable was configured either way.
- */
-function resolveAnalyticsSessionsDir(stateDir, stateDirEphemeral, env = process.env) {
-    const homeOverride = env.AGENT_HOME_DIR?.trim() || env.AGENTHIPPO_HOME?.trim();
-    if (!homeOverride && !stateDirEphemeral) {
-        return path.join(stateDir, 'analytics', 'sessions');
-    }
-    return path.join((0, paths_1.getAgentideHome)(), 'analytics', 'sessions');
-}
-/**
- * Env: the identity an UNATTENDED turn runs as — a cron- or channel-fired run with no chat peer
- * (PLAN/agent-identity.md §5). Deployment configuration, deliberately not a pack field: it names
- * an identity that exists only in the operator's environment and must match their role map.
- */
-exports.SERVICE_USER_ENV = 'AGENTHIPPO_SERVICE_USER';
-/** Longest identity we will carry. Generous; the point is to reject a pasted file, not to be tight. */
-const MAX_SERVICE_USER_LEN = 256;
-/**
- * Validate the service identity at boot.
- *
- * **Shape, not vocabulary.** An earlier draft of the design required `^svc:[a-z0-9-]+$` and would
- * have refused to boot on the two handles an enterprise operator is most likely to bind: a SPIFFE
- * ID (`spiffe://corp/ns/agents/invoice`) and a Microsoft Entra agent identity object id. Both are
- * exactly the federated principals §8 wants this to become, so the validator checks that the value
- * is a usable single token and warns — rather than refuses — when it carries no recognisable
- * namespace.
- *
- * Malformed IS a boot refusal though: the alternative is a fleet that looks configured and runs
- * every scheduled job anonymously.
- */
-function resolveServiceIdentity(env = process.env) {
-    const raw = env[exports.SERVICE_USER_ENV];
-    if (raw === undefined) {
-        return {};
-    }
-    const identity = raw.trim();
-    if (!identity) {
-        return { error: `${exports.SERVICE_USER_ENV} is set but empty. Unset it, or give it the identity unattended runs should act as.` };
-    }
-    if (/\s/.test(identity)) {
-        return { error: `${exports.SERVICE_USER_ENV} must not contain whitespace, got ${JSON.stringify(raw)}.` };
-    }
-    if (identity.length > MAX_SERVICE_USER_LEN) {
-        return { error: `${exports.SERVICE_USER_ENV} is ${identity.length} chars; the maximum is ${MAX_SERVICE_USER_LEN}.` };
-    }
-    // Recognised shapes: the local convention, a SPIFFE ID, or a bare GUID (Entra object id).
-    const namespaced = /^svc:/.test(identity)
-        || /^spiffe:\/\//.test(identity)
-        || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identity);
-    if (!namespaced) {
-        return {
-            identity,
-            warning: `${exports.SERVICE_USER_ENV}="${identity}" carries no namespace marker (svc: / spiffe:// / GUID). `
-                + 'It will be used verbatim and must be mapped in the connector role map, exactly like a human identity. '
-                + 'If it can collide with a real user id, prefix it with `svc:`.',
-        };
-    }
-    return { identity };
-}
-/** Loopback default — safe everywhere a human runs `serve` locally. */
-exports.DEFAULT_BIND_HOST = '127.0.0.1';
-/** True when a bind address is reachable only from this machine. */
-function isLoopbackHost(host) {
-    const h = host.trim().toLowerCase().replace(/^\[|\]$/g, '');
-    return h === 'localhost' || h === '::1' || /^127\./.test(h);
-}
-/** Env var for the listen address (used by generated deploy Dockerfiles). */
-exports.SERVE_HOST_ENV = 'AGENTHIPPO_SERVE_HOST';
-/** Bind address baked into container deploy artifacts (Docker / Cloud Run sidecars). */
-exports.CONTAINER_SERVE_HOST = '0.0.0.0';
-/**
- * Resolve the listen address. Precedence: explicit `--host` → AGENTHIPPO_SERVE_HOST → 127.0.0.1.
- *
- * Defaults to loopback so a local `serve` is never reachable off-box by accident. Containers
- * (where the SSO proxy reaches the agent over a Docker network) MUST opt into `0.0.0.0` —
- * generated deploy artifacts set `AGENTHIPPO_SERVE_HOST=0.0.0.0` for exactly this reason.
- */
-function resolveBindHost(hostOpt, env = process.env) {
-    return hostOpt?.trim() || env.AGENTHIPPO_SERVE_HOST?.trim() || exports.DEFAULT_BIND_HOST;
-}
-/** Env var: number of trusted proxy hops in front of serve (default 1 — the single Caddy). */
-exports.XFF_TRUSTED_HOPS_ENV = 'AGENTHIPPO_XFF_TRUSTED_HOPS';
-/**
- * Best-effort client IP for rate-limiting keys.
- *
- * Each trusted proxy appends the IP it observed to `X-Forwarded-For`, so with N trusted hops
- * the real client is the Nth entry from the right (a client-spoofed left-most entry is just
- * prepended and never reached). Default is 1 (the documented single Caddy). Behind
- * Cloudflare Tunnel → Caddy there are two hops — Caddy appends cloudflared's container IP,
- * which is identical for every client, so leaving hops at 1 there collapses all users into one
- * rate-limit bucket. Set AGENTHIPPO_XFF_TRUSTED_HOPS=2 for the tunnel profile.
- * Falls back to the socket address for direct/local callers. This is a coarse abuse key, not
- * an identity — never use it for authorization.
- */
-function clientIp(req, env = process.env) {
-    const xff = req.headers['x-forwarded-for'];
-    const raw = Array.isArray(xff) ? xff[0] : xff;
-    if (raw) {
-        const parts = raw.split(',').map((s) => s.trim()).filter(Boolean);
-        if (parts.length > 0) {
-            const hopsRaw = Number(env[exports.XFF_TRUSTED_HOPS_ENV]);
-            const hops = Number.isInteger(hopsRaw) && hopsRaw >= 1 ? hopsRaw : 1;
-            return parts[Math.max(0, parts.length - hops)];
-        }
-    }
-    return req.socket?.remoteAddress || 'unknown';
-}
-/**
- * Fixed-window request rate limiter (per key, in-memory, per-process). Complements the
- * per-session TurnLimiter: keying on a stable identity (user id, or client IP) closes the
- * "rotate session_id to bypass" gap. `maxPerWindow <= 0` disables it.
- */
-class RateLimiter {
-    maxPerWindow;
-    windowMs;
-    hits = new Map();
-    /** Cap the key map so a flood of distinct keys can't grow memory unbounded. */
-    static MAX_KEYS = 100_000;
-    constructor(maxPerWindow, windowMs = 60_000) {
-        this.maxPerWindow = maxPerWindow;
-        this.windowMs = windowMs;
-    }
-    /** Returns true if the request is allowed (and records it); false when the window cap is hit. */
-    tryConsume(key, now = Date.now()) {
-        if (!Number.isFinite(this.maxPerWindow) || this.maxPerWindow <= 0) {
-            return true; // disabled
-        }
-        const entry = this.hits.get(key);
-        if (!entry || entry.resetAt <= now) {
-            if (this.hits.size >= RateLimiter.MAX_KEYS) {
-                this.prune(now);
-            }
-            this.hits.set(key, { count: 1, resetAt: now + this.windowMs });
-            return true;
-        }
-        if (entry.count >= this.maxPerWindow) {
-            return false;
-        }
-        entry.count += 1;
-        return true;
-    }
-    /** Seconds until the key's window resets — for a Retry-After header. */
-    retryAfterSeconds(key, now = Date.now()) {
-        const entry = this.hits.get(key);
-        if (!entry) {
-            return Math.ceil(this.windowMs / 1000);
-        }
-        return Math.max(1, Math.ceil((entry.resetAt - now) / 1000));
-    }
-    prune(now) {
-        for (const [key, entry] of this.hits) {
-            if (entry.resetAt <= now) {
-                this.hits.delete(key);
-            }
-        }
-        if (this.hits.size >= RateLimiter.MAX_KEYS) {
-            this.hits.clear();
-        }
-    }
-}
-exports.RateLimiter = RateLimiter;
-/**
- * Identity headers trusted when NOTHING is pinned.
- *
- * Every entry here is a header that exactly one platform sets AND owns the request path for, so
- * a client-supplied copy cannot reach serve without that platform having been bypassed entirely.
- *
- * `x-agent-user` is deliberately NOT in this list, and this is a breaking change for anything
- * that relied on it being trusted by default. It is AgentHippo's own canonical header — the name
- * an arbitrary client is most likely to guess — it belongs to no platform that strips it, and it
- * used to sit FIRST, so it beat every platform header that follows. The consequence on any
- * deployment that had not pinned `AGENTHIPPO_IDENTITY_HEADER`: any HTTP client could send
- * `x-agent-user: victim@example.com` and be namespaced into that user's session state, attach to
- * their conversation, and be issued a data-plane turn nonce scoped to them. Cloud Run IAP makes
- * this concrete — it strips `X-Goog-*` and forwards a client-supplied `x-agent-user` untouched.
- *
- * It remains perfectly valid as a PINNED header (`AGENTHIPPO_IDENTITY_HEADER=x-agent-user`),
- * which is what a deployment whose proxy really does set and strip it should use — including the
- * Caddy `forward_auth` flow, where `auth-broker/server.ts` sets `X-Agent-User` on `/api/ide/me`
- * so Caddy can copy a VALIDATED identity upstream. That direction is the correct and only source
- * of the header, and it is unaffected: pinning is exactly the declaration that it is trustworthy.
- */
-const HEADER_ALIASES = [
-    'x-forwarded-email', // Databricks Apps
-    'x-forwarded-preferred-username', // Databricks Apps
-    'x-goog-authenticated-user-email', // Cloud Run IAP (prefixed value, stripped below)
-    'cf-access-authenticated-user-email', // Cloudflare Access
-];
-/**
- * Headers that are only ever trusted when explicitly pinned.
- *
- * Kept as a named list rather than deleted, because "why is my identity header ignored?" needs an
- * answer, and `identityHeaderAdvice` gives one that names the env var to set.
- */
-exports.PIN_ONLY_IDENTITY_HEADERS = ['x-agent-user'];
-/** Env var: pin the single identity header the deploy layer actually sets (and strips). */
-exports.IDENTITY_HEADER_ENV = 'AGENTHIPPO_IDENTITY_HEADER';
-/**
- * Env var: shared secret proving the identity header was set by the trusted proxy, not by
- * something else that can reach serve's port.
- *
- * Pinning declares WHICH header carries identity; it says nothing about WHO may assert it. On a
- * shared network (compose, sidecar platforms where every container shares localhost) any
- * neighbour that can dial serve can send the pinned header and be namespaced as that user —
- * network topology cannot express "the agent may dial the gateway but not the reverse". When
- * this is set, serve honours identity headers only on requests that also carry the matching
- * `x-agenthippo-proxy-secret` (the same proof-of-proxy contract the auth-broker enforces for
- * `X-Auth-Request-Email`); without proof the request runs anonymous, same as an unpinned
- * header. Opt-in: unset keeps today's behaviour, because platform-header deployments (IAP,
- * Databricks Apps) have an unforgeable header and no proxy hop that could attach a secret.
- */
-exports.IDENTITY_PROXY_SECRET_ENV = 'AGENTHIPPO_IDENTITY_PROXY_SECRET';
-/**
- * Proof that an identity header was set by the trusted proxy and not by a client: the request
- * carries `x-agenthippo-proxy-secret` matching the configured secret. Shared with the
- * auth-broker, which applies the same contract to `X-Auth-Request-Email` (it lives here rather
- * than in the broker because the broker already imports from this module).
- */
-function hasTrustedProxyProof(headers, expectedSecret) {
-    if (!expectedSecret) {
-        return false;
-    }
-    const raw = headers[config_1.AUTH_PROXY_SECRET_HEADER];
-    const presented = typeof raw === 'string' ? raw : Array.isArray(raw) ? String(raw[0] ?? '') : '';
-    if (!presented) {
-        return false;
-    }
-    // Hash both sides first: timingSafeEqual throws on a length mismatch, which would itself leak
-    // the secret's length.
-    const a = crypto.createHash('sha256').update(presented).digest();
-    const b = crypto.createHash('sha256').update(expectedSecret).digest();
-    return crypto.timingSafeEqual(a, b);
-}
-/**
- * Boot-time advice about identity trust. Returns the lines serve must print, loudest first.
- *
- * Not a refusal. Refusing to boot without a pin would stop deployments that are configured
- * correctly today (Databricks Apps, Cloudflare Access) and whose platform header is genuinely
- * unforgeable — a fail-closed default that mostly punishes the compliant is not a security win.
- * What was actually dangerous was `x-agent-user` being trusted by default, and that is now gone.
- */
-function identityHeaderAdvice(env = process.env, bindHost) {
-    const pinned = env[exports.IDENTITY_HEADER_ENV]?.trim();
-    if (pinned) {
-        return [];
-    }
-    // Severity follows reachability. On loopback nothing off-box can reach the port, so the same
-    // paragraph every local run is warning fatigue — and fatigue is why the message gets ignored
-    // on the deploy where it decides whether strangers can name themselves as another user.
-    const host = bindHost?.trim();
-    if (host && isLoopbackHost(host)) {
-        return [
-            `${exports.IDENTITY_HEADER_ENV} is not set. Fine for this loopback bind; pin it before exposing ` +
-                `serve on a network interface.`,
-        ];
-    }
-    return [
-        ...(host
-            ? [`serve is bound to ${host} — reachable beyond this machine — with no ${exports.IDENTITY_HEADER_ENV} pinned. ` +
-                    `Anyone who can reach this port is trusted to state who they are.`]
-            : []),
-        `${exports.IDENTITY_HEADER_ENV} is not set, so identity falls back to the platform header aliases ` +
-            `(${HEADER_ALIASES.join(', ')}). That is only safe when your proxy sets AND STRIPS every one of them. ` +
-            `Pin the single header your deploy layer really controls, e.g. ${exports.IDENTITY_HEADER_ENV}=x-goog-authenticated-user-email.`,
-        `NOTE: ${exports.PIN_ONLY_IDENTITY_HEADERS.join(', ')} is NO LONGER trusted by default — it is not stripped by any ` +
-            `platform, so an arbitrary client could send it and be namespaced as another user. If your proxy does set it ` +
-            `(the Caddy forward_auth / auth-broker flow does), pin it: ${exports.IDENTITY_HEADER_ENV}=x-agent-user.`,
-    ];
-}
-/** Env var: turn the tenant-isolation advice below into a boot refusal. */
-exports.REQUIRE_TENANT_ISOLATION_ENV = 'AGENTHIPPO_REQUIRE_TENANT_ISOLATION';
-/** True when `child` is `parent` or sits beneath it. */
-function isWithin(child, parent) {
-    const c = path.resolve(child);
-    const p = path.resolve(parent);
-    return c === p || c.startsWith(p + path.sep);
-}
-/**
- * Boot-time advice about what a second user of this agent can read off the disk.
- *
- * The condition this exists for: a deployment that PINS an identity header has declared it serves
- * more than one person, and a tier-0 (`--sandbox=process`) or sandbox-less serve gives every one
- * of them the same uid, the same workspace and the same state dir. Per-user namespacing —
- * `userScopedEngineHome`'s `users/<hash>`, user-namespaced session keys, per-session analytics
- * JSONL — is naming, not access control: a same-uid process reads its neighbours' names by
- * listing the directory. What sits there is the engines' own session files, i.e. the plaintext of
- * every other user's conversation, including whatever rows the OBO connector correctly scoped to
- * them on the way in. The data path stays isolated and the artifact path undoes it.
- *
- * The nesting check is the sharper half. `--workspace=/state/workspace --state-dir=/state` is the
- * shape the samples shipped, and it puts the artifact store one `..` above the agent's own cwd —
- * so reaching it takes no traversal trick, just a relative path. Unrelated subtrees
- * (`--workspace=/work --state-dir=/state`) do not make a same-uid process unable to read /state;
- * they stop it being the obvious next directory.
- *
- * Warn, not refuse, by default — the shipped samples are in exactly this shape and a fatal check
- * would brick them on upgrade, which is the same trade `identityHeaderAdvice` documents. An
- * operator who has finished the migration sets REQUIRE_TENANT_ISOLATION_ENV and gets the refusal.
- */
-function tenantIsolationAdvice(input, env = process.env) {
-    // Unpinned means serve cannot tell one caller from another at all; identityHeaderAdvice owns
-    // that case and saying both at once buries the one the operator can act on.
-    if (!env[exports.IDENTITY_HEADER_ENV]?.trim()) {
-        return { level: 'ok', lines: [] };
-    }
-    const perSessionFilesystem = input.sandbox === 'container' && !input.sharedWorkspace;
-    if (perSessionFilesystem) {
-        return { level: 'ok', lines: [] };
-    }
-    const tier = input.sandbox === 'process' ? 'a tier-0 (--sandbox=process) sandbox' : 'no sandbox';
-    const lines = [
-        `${exports.IDENTITY_HEADER_ENV} is pinned — so this serve has more than one user — but it runs with ` +
-            `${tier}, which shares one uid, one workspace (${input.workspace ?? 'unset'}) and one state dir ` +
-            `(${input.stateDir}) across all of them. Any user can read every other user's engine session ` +
-            `files, which hold their conversations verbatim. Per-user paths are namespacing, not isolation.`,
-        `The boundary is --sandbox=container (per-session workspace and state, without ` +
-            `--shared-workspace) or one serve per tenant. Until then, restrict the pack's tool surface so ` +
-            `the agent has no way to read arbitrary files.`,
-    ];
-    if (input.workspace && isWithin(input.workspace, input.stateDir)) {
-        lines.push(`--workspace ${input.workspace} sits INSIDE --state-dir ${input.stateDir}: every other ` +
-            `user's sessions, analytics and evidence spool are one '..' above the agent's own cwd. ` +
-            `Put them in unrelated subtrees (e.g. --workspace=/work --state-dir=/state).`);
-    }
-    else if (input.workspace && isWithin(input.stateDir, input.workspace)) {
-        lines.push(`--state-dir ${input.stateDir} sits INSIDE --workspace ${input.workspace}: every other ` +
-            `user's sessions, analytics and evidence spool are inside the directory the agent is ` +
-            `pointed at. Put them in unrelated subtrees (e.g. --workspace=/work --state-dir=/state).`);
-    }
-    const strict = /^(1|true|yes|on)$/i.test(env[exports.REQUIRE_TENANT_ISOLATION_ENV]?.trim() ?? '');
-    return { level: strict ? 'refuse' : 'warn', lines };
-}
-/**
- * Resolve the end-user identity for a request.
- *
- * Proxy headers win over the request body. When AGENTHIPPO_IDENTITY_HEADER pins
- * trust to one header, that pin is a hard boundary: if the pinned header is
- * absent, identity resolves to undefined (never the request body) — a deployment
- * that pins a header has declared it has a real proxy-verified identity, so an
- * unauthenticated caller must not be able to name themselves via the client-
- * controlled body. Body fallback is dev/internal convenience for the *unpinned*
- * case only (e.g. direct curl against a local serve with no identity proxy) —
- * and it must be OPTED INTO via AGENTHIPPO_ALLOW_BODY_IDENTITY=1 (serve-v4 §10
- * hole 3). Before the gate it was safe "by convention": any deployment that
- * forgot to pin a header silently let every caller name an arbitrary victim.
- *
- * The alias-list default (used when unpinned) is only safe when the proxy strips
- * or overwrites ALL of the aliases; platforms that strip only their own header
- * (Cloud Run IAP strips `X-Goog-*` but forwards a client-supplied `x-agent-user`
- * untouched, which the alias list checks first) MUST pin theirs — deploy
- * artifacts set it (e.g. cloudrun-deploy.sh pins `x-goog-authenticated-user-email`)
- * so an authenticated caller cannot impersonate another user.
- *
- * Resolves identity for `analyticsUserId` attribution, the request-scoped
- * credential context (per-user data scoping), and the user-namespaced session
- * key (resolveServeSessionKey folds this identity into every session key).
- *
- * Per-turn *data credentials* (OBO token, e.g. X-Forwarded-Access-Token) are
- * handled by resolveDataToken — not read here.
- */
-function resolveUserId(headers, body, env = process.env) {
-    // Proof-of-proxy gate (IDENTITY_PROXY_SECRET_ENV): when configured, no identity — header OR
-    // body — is honoured without the matching secret header. A caller that fails this check is
-    // by definition not the trusted proxy, so the request runs anonymous rather than letting a
-    // network neighbour (or a dev body fallback) name a victim.
-    const proxySecret = env[exports.IDENTITY_PROXY_SECRET_ENV]?.trim();
-    if (proxySecret && !hasTrustedProxyProof(headers, proxySecret)) {
-        return undefined;
-    }
-    const pinned = env[exports.IDENTITY_HEADER_ENV]?.trim().toLowerCase();
-    const names = pinned ? [pinned] : HEADER_ALIASES;
-    for (const name of names) {
-        const v = headers[name];
-        const raw = (Array.isArray(v) ? v[0] : v)?.trim();
-        if (raw) {
-            // IAP sends "accounts.google.com:user@x.com"; keep the email half.
-            const colon = raw.lastIndexOf(':');
-            const value = colon >= 0 && raw.slice(colon + 1).includes('@') ? raw.slice(colon + 1) : raw;
-            return value;
-        }
-    }
-    if (pinned) {
-        // Pinned but absent: fail closed. Falling back to the body here would let any
-        // caller that merely reaches this port (proxy misconfiguration, direct network
-        // access, gcloud run services proxy bypassing IAP) name an arbitrary victim.
-        return undefined;
-    }
-    // Unpinned body identity is an explicit opt-in, never a default (§10 hole 3).
-    if (env.AGENTHIPPO_ALLOW_BODY_IDENTITY?.trim() !== '1') {
-        return undefined;
-    }
-    const fromBody = body?.user_id?.trim();
-    return fromBody || undefined;
-}
-const DATA_TOKEN_HEADERS = [
-    'x-forwarded-access-token', // Databricks Apps OBO token
-    'x-agent-data-token', // AgentHippo generic per-turn data credential
-];
-/**
- * Resolve the per-turn *data* credential (the OBO token), distinct from the
- * identity in resolveUserId. Fed into the request-scoped credential context so
- * a data tool can act as the asking user. serve-v3 §11.1 (Design B).
- *
- * Like the identity headers, this is trusted unconditionally and is only safe
- * behind a proxy that strips client-supplied copies (see the module SECURITY
- * CONTRACT above).
- */
-function resolveDataToken(headers) {
-    for (const name of DATA_TOKEN_HEADERS) {
-        const v = headers[name];
-        const raw = (Array.isArray(v) ? v[0] : v)?.trim();
-        if (raw) {
-            return raw;
-        }
-    }
-    return undefined;
-}
-/**
- * Map a gateway channel sender (PeerInfo) to a stable `user_id` (serve-v3 §11 / #4).
- * Prefers the stable channel id, namespaced by channel, so the Slack/Telegram
- * sender becomes the user_id that drives per-user attribution and data scoping —
- * extending the per-user-permission wedge to channel surfaces.
- */
-function peerToUserId(peer) {
-    if (!peer) {
-        return undefined;
-    }
-    const id = peer.senderId?.trim() || peer.senderUsername?.trim() || peer.senderName?.trim();
-    if (!id) {
-        return undefined;
-    }
-    const channel = peer.channel?.trim();
-    return channel ? `${channel}:${id}` : id;
-}
-/** Stable reason code when a session_id is presented without a verified user on a pinned-identity deployment. */
-exports.SESSION_WITHOUT_USER_REASON = 'session_without_verified_user';
-/** Filesystem/S3-safe per-user namespace segment (user ids are emails/subjects — never raw path segments). */
-function userNamespaceHash(userId) {
-    return crypto.createHash('sha256').update(userId).digest('hex').slice(0, 16);
-}
-/**
- * Namespace the session key by the verified user (secure-obo-design §3.4 / §8 Phase 0).
- *
- * `session_id` is client-supplied; un-namespaced, any authenticated user who guesses another
- * user's session_id attaches to that session's conversation state (which holds the other
- * user's row-filtered query results). Prefixing the key with a hash of the verified user makes
- * cross-user attachment structurally impossible without changing client behavior.
- *
- * Fail-closed rule: when the deployment pins an identity header (it declared a real
- * proxy-verified identity exists), any turn without a verified user is rejected — with or
- * without a session_id. Rejecting only named sessions would leave every identity-less
- * caller sharing the durable `anon-unknown` conversation state. Unpinned deployments
- * (local dev, no identity boundary at all) keep today's raw-key behavior.
- */
-function resolveServeSessionKey(sessionId, userId, scope = 'session', env = process.env) {
-    const sid = sessionId?.trim();
-    const uid = userId?.trim();
-    if (uid) {
-        const sessionKey = `u${userNamespaceHash(uid)}--${sid || 'default'}`;
-        return { sessionKey, sandboxKey: scope === 'user' ? `u${userNamespaceHash(uid)}` : sessionKey };
-    }
-    if (env[exports.IDENTITY_HEADER_ENV]?.trim()) {
-        return { sessionKey: '', sandboxKey: '', rejected: exports.SESSION_WITHOUT_USER_REASON };
-    }
-    // No verified user, so there is no user to scope a sandbox TO. `user` scope deliberately does
-    // not apply here: merging unidentified callers would put two strangers in one sandbox on the
-    // strength of a fact nobody established. Local dev keeps one sandbox per session.
-    const sessionKey = sid || 'anon-unknown';
-    return { sessionKey, sandboxKey: sessionKey };
-}
-/** Build CORS headers. Serve is always behind a proxy; CORS is wide-open here. */
-function corsHeaders() {
-    return {
-        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-        'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Agent-User',
-        'Access-Control-Allow-Origin': '*',
-    };
-}
-/**
- * Per-session turn admission control. Caps the number of turns a single
- * conversation may run (abuse / runaway-loop guard for exposed deployments).
- * In-memory and per-process — sufficient for single-container tiers; a shared
- * store is a later concern.
- */
-class TurnLimiter {
-    maxPerSession;
-    counts = new Map();
-    constructor(maxPerSession) {
-        this.maxPerSession = maxPerSession;
-    }
-    /** Returns true if the turn is allowed (and records it); false when the cap is exceeded. */
-    tryConsume(sessionKey) {
-        if (!Number.isFinite(this.maxPerSession) || this.maxPerSession <= 0) {
-            return true; // disabled
-        }
-        const current = this.counts.get(sessionKey) ?? 0;
-        if (current >= this.maxPerSession) {
-            return false;
-        }
-        this.counts.set(sessionKey, current + 1);
-        return true;
-    }
-    reset(sessionKey) {
-        this.counts.delete(sessionKey);
-    }
-}
-exports.TurnLimiter = TurnLimiter;
-/** Env: max concurrent engine turns per process (default 10). `0` disables the gate. */
-exports.MAX_CONCURRENT_TURNS_ENV = 'AGENTHIPPO_MAX_CONCURRENT_TURNS';
-/** Env: bounded FIFO waiter depth when at inflight cap (default 20). */
-exports.TURN_QUEUE_ENV = 'AGENTHIPPO_TURN_QUEUE';
-/** Fixed Retry-After seconds when the turn gate rejects (matches default queue timeout). */
-exports.TURN_GATE_RETRY_AFTER_SECONDS = 15;
-/** User-visible capacity message for gateway channels (Slack/Telegram can't receive HTTP 429). */
-exports.TURN_GATE_BUSY_MESSAGE = 'At capacity — please retry in a moment';
-/** User-visible message for gateway channels when the per-identity RateLimiter rejects. */
-exports.RATE_LIMIT_BUSY_MESSAGE = 'Rate limit exceeded — please retry in a moment';
-/** User-visible message for gateway channels when the per-session TurnLimiter rejects. */
-exports.TURN_LIMIT_BUSY_MESSAGE = 'Per-session turn limit reached';
-/**
- * Process-wide concurrency gate for engine turns (semaphore + bounded FIFO).
- *
- * Caps simultaneous engine subprocesses so a burst cannot OOM the container.
- * `maxInflight <= 0` disables. Waiters time out after `queueTimeoutMs` (burst
- * absorber, not a job queue). Rejected callers get `null` — HTTP maps that to
- * 429 + Retry-After; the gateway path emits a short channel message instead.
- */
-class TurnGate {
-    maxInflight;
-    maxQueue;
-    queueTimeoutMs;
-    inflightCount = 0;
-    waiters = [];
-    constructor(maxInflight, maxQueue, queueTimeoutMs = exports.TURN_GATE_RETRY_AFTER_SECONDS * 1000) {
-        this.maxInflight = maxInflight;
-        this.maxQueue = maxQueue;
-        this.queueTimeoutMs = queueTimeoutMs;
-    }
-    /**
-     * Acquire a turn slot. Resolves with a `release()` callback, or `null` when
-     * the queue is full or the wait timed out. Always call `release()` in a
-     * `finally` when non-null.
-     */
-    async acquire() {
-        if (!Number.isFinite(this.maxInflight) || this.maxInflight <= 0) {
-            return () => { };
-        }
-        if (this.inflightCount < this.maxInflight) {
-            this.inflightCount += 1;
-            return () => this.releaseSlot();
-        }
-        if (this.waiters.length >= this.maxQueue) {
-            return null;
-        }
-        return new Promise((resolve) => {
-            let settled = false;
-            const settle = (release) => {
-                if (settled) {
-                    // Timed out after a slot was already offered — give the slot back.
-                    if (release) {
-                        release();
-                    }
-                    return;
-                }
-                settled = true;
-                clearTimeout(timer);
-                resolve(release);
-            };
-            const entry = {
-                resolve: settle,
-                timer: null,
-            };
-            const timer = setTimeout(() => {
-                const idx = this.waiters.indexOf(entry);
-                if (idx >= 0) {
-                    this.waiters.splice(idx, 1);
-                }
-                settle(null);
-            }, this.queueTimeoutMs);
-            entry.timer = timer;
-            this.waiters.push(entry);
-        });
-    }
-    releaseSlot() {
-        const next = this.waiters.shift();
-        if (next) {
-            // Transfer the slot to the head waiter — do not decrement inflight.
-            next.resolve(() => this.releaseSlot());
-            return;
-        }
-        this.inflightCount = Math.max(0, this.inflightCount - 1);
-    }
-    get inflight() {
-        return this.inflightCount;
-    }
-    get queued() {
-        return this.waiters.length;
-    }
-    get max() {
-        return this.maxInflight > 0 ? this.maxInflight : 0;
-    }
-}
-exports.TurnGate = TurnGate;
-/** Build a TurnGate from env (serve-v4 P0.1). Defaults: 10 inflight, 20 queued. */
-function createTurnGateFromEnv(env = process.env) {
-    const inflightRaw = Number(env[exports.MAX_CONCURRENT_TURNS_ENV] ?? 10);
-    const queueRaw = Number(env[exports.TURN_QUEUE_ENV] ?? 20);
-    const maxInflight = Number.isFinite(inflightRaw) ? inflightRaw : 10;
-    const maxQueue = Number.isFinite(queueRaw) && queueRaw >= 0 ? queueRaw : 20;
-    return new TurnGate(maxInflight, maxQueue);
-}
-/**
- * Rate-limited rejection logger — at most one warn per `intervalMs` so a flood
- * of 429s does not spam the console.
- */
-function createRejectionWarner(intervalMs = 5_000) {
-    let lastAt = 0;
-    return (msg) => {
-        const now = Date.now();
-        if (now - lastAt < intervalMs) {
-            return;
-        }
-        lastAt = now;
-        console.warn(msg);
-    };
-}
-/**
- * Read a request body with a hard size cap. Past the cap it stops accumulating
- * and rejects with a `tooLarge`-tagged error so the caller can respond 413.
- *
- * Deliberately does NOT destroy the socket here: destroying mid-upload resets
- * the connection before the 413 can flush (the client only ever sees the
- * interim 100-continue). We detach our listeners and let the handler send 413
- * with `Connection: close`. Replaces serve's unbounded body accumulation.
- */
-function readBodyWithCap(req, maxBytes = exports.DEFAULT_MAX_BODY_BYTES) {
-    return new Promise((resolve, reject) => {
-        let size = 0;
-        const chunks = [];
-        const onData = (chunk) => {
-            size += chunk.length;
-            if (size > maxBytes) {
-                cleanup();
-                const err = new Error(`Request body exceeds ${maxBytes} bytes`);
-                err.tooLarge = true;
-                reject(err);
-                return;
-            }
-            chunks.push(chunk);
-        };
-        const onEnd = () => {
-            cleanup();
-            resolve(Buffer.concat(chunks).toString('utf8'));
-        };
-        const onError = (err) => {
-            cleanup();
-            reject(err);
-        };
-        const cleanup = () => {
-            req.off('data', onData);
-            req.off('end', onEnd);
-            req.off('error', onError);
-        };
-        req.on('data', onData);
-        req.on('end', onEnd);
-        req.on('error', onError);
-    });
-}