@agenthippo-ai/agenthippo 0.1.0 → 0.2.3-dataplane

package/out/cli/commands/serve.js

@@ -37,18 +37,26 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.serveCommand = serveCommand;
+exports.resolveGatewaySessionKey = resolveGatewaySessionKey;
+exports.runGatewayTurn = runGatewayTurn;
 /**
  * Serve Command - HTTP Server
  */
 const fs = __importStar(require("fs"));
 const http = __importStar(require("http"));
 const path = __importStar(require("path"));
+const node_crypto_1 = require("node:crypto");
 const headless_1 = require("../../headless");
 const pack_loader_1 = require("../pack-loader");
 const utils_1 = require("../utils");
 const runtime_1 = require("../runtime");
 const serve_hardening_1 = require("../serve-hardening");
 const credential_context_1 = require("../credential-context");
+const data_plane_1 = require("../data-plane");
+const runtime_2 = require("../runtime");
+const outboundSend_1 = require("../../gateway/outboundSend");
+const sessionEvents_1 = require("../../analytics/sessionEvents");
+const base_1 = require("../../engines/base");
 const state_sync_1 = require("../state-sync");
 const cli_agent_id_js_1 = require("../../gateway/cli-agent-id.js");
 const openclaw_channel_routing_js_1 = require("../../gateway/openclaw-channel-routing.js");
@@ -79,8 +87,11 @@ async function serveCommand(options) {
     const defaultModel = (0, headless_1.resolveModelAlias)(rawModel);
     const rawCheapModel = pack.manifest.spec.cheapModel?.trim();
     const claudeCheapModel = rawCheapModel ? (0, headless_1.resolveModelAlias)(rawCheapModel) : undefined;
-    if (!apiConfig.apiKey && (defaultEngine === 'claude' || defaultEngine === 'codex')) {
-        console.error('Error: No API key found. Set AGENTHIPPO_LITELLM_API_KEY or ANTHROPIC_API_KEY');
+    // Engine-aware: a codex deploy needs an OpenAI (or LiteLLM) key; a claude deploy needs an
+    // Anthropic (or LiteLLM) key. Fail loudly at boot rather than 401 at the first model call.
+    if (!(0, pack_loader_1.hasCredentialForEngine)(defaultEngine, apiConfig)) {
+        const need = defaultEngine === 'claude' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY';
+        console.error(`Error: No usable API key for engine "${defaultEngine}". Set ${need}, or configure the LiteLLM proxy (AGENTHIPPO_LITELLM_API_KEY + AGENTHIPPO_LITELLM_BASE_URL).`);
         for (const line of (0, utils_1.getLiteLLMQuickstartHintLines)()) {
             console.error(line);
         }
@@ -90,14 +101,76 @@ async function serveCommand(options) {
     const bundledPromptsDir = (0, utils_1.findBundledBasePromptsDir)();
     await (0, headless_1.syncPackToWorkspace)(options.workspace, pack.packPath, packId, defaultEngine, syncLogger, bundledPromptsDir);
     console.log(`OK: Loaded agent: ${pack.manifest.metadata.name} v${pack.manifest.metadata.version}`);
+    // Structural attribution (pack-standard WS2) — greppable for CISO/SRE boot audits.
+    console.log(`agenthippo pack=${pack.manifest.metadata.name}@${pack.manifest.metadata.version} engine=${defaultEngine}`);
     // Resolve persistent session state (serve-v3 §A1: replaces the tmpdir default).
     const { dir: storagePath, ephemeral } = (0, serve_hardening_1.resolveStateDir)(options.stateDir);
     const bindHost = (0, serve_hardening_1.resolveBindHost)(options.host);
+    // Passed to createHeadlessRunner below so the runner's own SessionEventWriter uses the same
+    // root — a fail-closed warrant denial lands in the same per-session JSONL as the tool events
+    // it precedes. The denial happens before runner.run() is ever called, so it needs its own
+    // writer here too. See resolveAnalyticsSessionsDir's docstring for the precedence.
+    const analyticsSessionsDir = (0, serve_hardening_1.resolveAnalyticsSessionsDir)(storagePath, ephemeral);
+    const sessionEventWriter = new sessionEvents_1.SessionEventWriter(analyticsSessionsDir);
+    const logWarrantDenied = (sessionKey) => (reason) => sessionEventWriter.append(sessionKey, (0, base_1.generateRequestId)(), 'warrant_denied', { reason });
+    // Data-plane gateway (secure-obo-design §3): when the pack declares spec.dataPlane,
+    // serve runs the connector broker-side and engines get a per-turn nonce instead of the
+    // credential. The raw data credential never crosses into the agent's trust domain.
+    const dataPlaneCfg = (0, data_plane_1.resolveDataPlaneConfig)(pack.manifest.spec, pack.packPath);
+    // One shared registry: a single per-turn nonce grants BOTH the data-plane and egress
+    // capabilities (secure-obo-design §7.6 step 2). Created when either broker will run.
+    const turnRegistry = (dataPlaneCfg || options.gatewayBridge) ? new data_plane_1.TurnRegistry() : null;
+    const auditEvent = (sessionKey, event, fields) => sessionEventWriter.append(sessionKey, (0, base_1.generateRequestId)(), event, fields);
+    let dataPlane = null;
+    if (dataPlaneCfg) {
+        try {
+            dataPlane = await data_plane_1.DataPlane.start(dataPlaneCfg, {
+                logger: options.verbose ? new headless_1.ConsoleLogger('[DataPlane]') : new headless_1.NoOpLogger(),
+                audit: auditEvent,
+                registry: turnRegistry ?? undefined,
+            });
+            // Boot-stable process env: engines resolve ${env:AGENTHIPPO_DATA_MCP_URL} from it,
+            // so codex's config.toml stays byte-identical across turns. The NONCE is never set
+            // here — it rides the per-spawn child env only.
+            process.env[data_plane_1.DATA_MCP_URL_ENV] = dataPlane.url;
+            console.log(`OK: Data gateway (provider=${dataPlane.broker.provider.name}) on loopback — connector: ${dataPlaneCfg.connectorPath}`);
+        }
+        catch (err) {
+            console.error(`${utils_1.COLORS.red}Error: failed to start the data-plane gateway:${utils_1.COLORS.reset} ${err instanceof Error ? err.message : err}`);
+            process.exit(1);
+        }
+    }
+    // Egress broker (secure-obo-design §7.6): capture the gateway token broker-side BEFORE any
+    // engine spawns, so it can be stripped from the process env the children inherit. The broker
+    // starts alongside the gateway bridge below; the token is held only in this closure.
+    const brokerGatewayToken = options.gatewayBridge ? (0, runtime_2.readOpenClawGatewayToken)() : undefined;
+    let egressBroker = null;
+    // Mint one nonce per turn and assemble the per-spawn child env. Returns null outside any
+    // broker (no capability to grant). The URLs ride process.env (boot-stable) for config
+    // invariance; only the nonce is per-spawn.
+    const registerServeTurn = (reg) => {
+        if (!turnRegistry) {
+            return null;
+        }
+        const { nonce, release } = turnRegistry.register(reg);
+        const env = { [data_plane_1.TURN_NONCE_ENV]: nonce };
+        if (dataPlane) {
+            env[data_plane_1.DATA_MCP_URL_ENV] = dataPlane.url;
+        }
+        if (egressBroker) {
+            env[data_plane_1.EGRESS_URL_ENV] = egressBroker.url;
+        }
+        return { nonce, env, release };
+    };
     const turnLimiter = new serve_hardening_1.TurnLimiter(options.maxTurnsPerSession ?? 0);
     // Per-identity request-rate cap (req/min). Keyed on the trusted user id (falling back to
     // client IP) so rotating session_id can't bypass it. AGENTHIPPO_SERVE_RATE_LIMIT=0 disables.
     const rateLimitPerMin = Number(process.env.AGENTHIPPO_SERVE_RATE_LIMIT ?? 120);
     const rateLimiter = new serve_hardening_1.RateLimiter(Number.isFinite(rateLimitPerMin) ? rateLimitPerMin : 120);
+    // Process-wide inflight cap (serve-v4 P0.1). Prevents a burst from spawning N engine
+    // subprocesses and OOMing the container. AGENTHIPPO_MAX_CONCURRENT_TURNS=0 disables.
+    const turnGate = (0, serve_hardening_1.createTurnGateFromEnv)();
+    const warnGateReject = (0, serve_hardening_1.createRejectionWarner)();
     let landingPageHtml;
     if (options.wwwDir?.trim()) {
         const indexPath = path.join(path.resolve(options.wwwDir.trim()), 'index.html');
@@ -111,21 +184,34 @@ async function serveCommand(options) {
     if (ephemeral) {
         console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} Session state is in a tmpdir (ephemeral). Pass --state-dir or set AGENTHIPPO_HOME to persist sessions across restarts.`);
     }
-    // Q1: object-store state sync (no-op unless AGENTHIPPO_STATE_S3_URI is set).
-    // Boot-restore so sessions survive a fresh instance with no FS mount (R2/S3/Databricks).
+    // Q1 + serve-v4 P1.2: object-store state sync (no-op unless AGENTHIPPO_STATE_S3_URI is set).
+    // Multi-replica: AGENTHIPPO_STATE_RESTORE_BOOT=none + restore-on-miss per session.
+    // Single-instance default: boot-restore the whole prefix (backward compatible).
     const s3State = (0, state_sync_1.resolveS3StateConfig)();
+    const restoreBoot = (0, state_sync_1.resolveRestoreBootMode)();
     if (s3State) {
         // Preflight: state sync shells out to `aws`. If it's missing, sessions would
         // silently never persist — fail fast since durable state was explicitly opted into.
         if (!(await (0, state_sync_1.isAwsCliAvailable)())) {
             console.error(`${utils_1.COLORS.red}Error: AGENTHIPPO_STATE_S3_URI is set but the \`aws\` CLI was not found.${utils_1.COLORS.reset}`);
-            console.error('   State sync requires the AWS CLI. Install it (https://aws.amazon.com/cli/) or unset AGENTHIPPO_STATE_S3_URI.');
+            console.error('   State sync requires the AWS CLI (S3-compatible via --endpoint-url). Install it or unset AGENTHIPPO_STATE_S3_URI.');
             process.exit(1);
         }
-        console.log(`State sync: restoring from ${s3State.uri} …`);
-        await (0, state_sync_1.restoreState)(s3State, storagePath, (m) => console.log(`  ${m}`));
+        if (restoreBoot === 'all') {
+            console.log(`State sync: boot-restore from ${s3State.uri} …`);
+            await (0, state_sync_1.restoreState)(s3State, storagePath, (m) => console.log(`  ${m}`));
+        }
+        else {
+            console.log(`State sync: restore-on-miss from ${s3State.uri} (boot restore disabled)`);
+        }
     }
     const statePusher = s3State ? (0, state_sync_1.makeStatePusher)(s3State, storagePath, options.verbose ? (m) => console.error(m) : undefined) : null;
+    const stateLog = options.verbose ? (m) => console.error(m) : undefined;
+    const prepareSession = async (sessionKey) => {
+        if (s3State) {
+            await (0, state_sync_1.ensureSessionLocal)(s3State, storagePath, sessionKey, stateLog);
+        }
+    };
     const logger = options.verbose ? new headless_1.ConsoleLogger('[Server]') : new headless_1.NoOpLogger();
     // Find SDK CLI paths
     const claudeCodePath = (0, utils_1.findClaudeCodePath)();
@@ -150,12 +236,18 @@ async function serveCommand(options) {
     };
     const runner = (0, headless_1.createHeadlessRunner)({
         storagePath,
+        analyticsSessionsDir,
         packId,
         packVersion: pack?.manifest.metadata.version,
         bundledPromptsDir,
         apiKey: apiConfig.apiKey,
         baseUrl: apiConfig.baseUrl,
         useLiteLLM: apiConfig.useLiteLLM,
+        // Per-destination keys so each engine authenticates to the endpoint it actually dials
+        // (codex→OpenAI, claude→Anthropic, or the LiteLLM proxy) — no provider-blind collapse.
+        litellmApiKey: apiConfig.litellmApiKey,
+        openaiApiKey: apiConfig.openaiApiKey,
+        anthropicApiKey: apiConfig.anthropicApiKey,
         logger,
         freshState: false,
         claudeCodeExecutablePath: claudeCodePath,
@@ -192,9 +284,15 @@ async function serveCommand(options) {
                 return;
             }
             // Readiness — pack synced (+ gateway connected when bridged).
+            // Inflight/queue depth for operators and load balancers (serve-v4 P0.1).
             if (req.method === 'GET' && req.url === '/ready') {
                 res.writeHead(ready ? 200 : 503, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ready }));
+                res.end(JSON.stringify({
+                    ready,
+                    inflight: turnGate.inflight,
+                    queued: turnGate.queued,
+                    max: turnGate.max,
+                }));
                 return;
             }
             const urlPath = req.url?.split('?')[0] ?? '';
@@ -208,22 +306,57 @@ async function serveCommand(options) {
                 const body = await parseBody(req);
                 const userId = (0, serve_hardening_1.resolveUserId)(req.headers, body);
                 const dataToken = (0, serve_hardening_1.resolveDataToken)(req.headers);
-                const rlKey = userId ?? (0, serve_hardening_1.clientIp)(req);
+                // Rate-limit on the trusted proxy identity (or client IP), never the client-supplied
+                // body user_id — otherwise a caller rotates user_id per request to reset the bucket.
+                const rlKey = (0, serve_hardening_1.resolveUserId)(req.headers, undefined) ?? (0, serve_hardening_1.clientIp)(req);
                 if (!rateLimiter.tryConsume(rlKey)) {
                     res.writeHead(429, { 'Content-Type': 'application/json', 'Retry-After': String(rateLimiter.retryAfterSeconds(rlKey)) });
                     res.end(JSON.stringify({ error: 'Rate limit exceeded' }));
                     return;
                 }
-                const sessionKey = body.session_id || `anon-${userId ?? 'unknown'}`;
-                if (!turnLimiter.tryConsume(sessionKey)) {
-                    res.writeHead(429, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                // User-namespaced session key (secure-obo-design §3.4): kills cross-user session
+                // attachment via a guessed session_id. Fails closed on pinned-identity deployments.
+                const { sessionKey, rejected } = (0, serve_hardening_1.resolveServeSessionKey)(body.session_id, userId);
+                if (rejected) {
+                    sessionEventWriter.append('unverified', (0, base_1.generateRequestId)(), 'warrant_denied', { reason: rejected });
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'session_id requires an authenticated user' }));
                     return;
                 }
-                const result = await (0, credential_context_1.runWithCredential)({ userId: userId ?? 'anonymous', dataToken }, () => handleChat(runner, body, defaultEngine, defaultModel, options.workspace, permissions, userId), { dataTokenDir: storagePath });
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(result));
-                statePusher?.schedule(); // async-delta push, off the response path
+                // Acquire before turn-limiter so a capacity reject does not burn a turn slot.
+                const release = await turnGate.acquire();
+                if (!release) {
+                    warnGateReject(`TurnGate: rejecting /v1/chat (inflight=${turnGate.inflight} queued=${turnGate.queued} max=${turnGate.max})`);
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(serve_hardening_1.TURN_GATE_RETRY_AFTER_SECONDS),
+                    });
+                    res.end(JSON.stringify({ error: 'At capacity' }));
+                    return;
+                }
+                // Turn-scoped data capability: mint a nonce bound to the verified user; the
+                // engine gets it via per-spawn env only. Deleted in the finally — a stale
+                // engine/tool fails closed at the gateway after that (secure-obo-design §3.1).
+                let turnReg = null;
+                try {
+                    if (!turnLimiter.tryConsume(sessionKey)) {
+                        res.writeHead(429, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                        return;
+                    }
+                    await prepareSession(sessionKey);
+                    if (userId?.trim()) {
+                        turnReg = registerServeTurn({ userId: userId.trim(), sessionKey, inboundToken: dataToken });
+                    }
+                    const result = await (0, credential_context_1.runWithCredential)({ userId, dataToken }, () => handleChat(runner, body, sessionKey, defaultEngine, defaultModel, options.workspace, permissions, userId, turnReg?.env), { onDenied: logWarrantDenied(sessionKey) });
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(result));
+                    statePusher?.schedule(sessionKey); // per-session delta push, off the response path
+                }
+                finally {
+                    turnReg?.release();
+                    release();
+                }
                 return;
             }
             // Streaming chat endpoint
@@ -231,25 +364,63 @@ async function serveCommand(options) {
                 const body = await parseBody(req);
                 const userId = (0, serve_hardening_1.resolveUserId)(req.headers, body);
                 const dataToken = (0, serve_hardening_1.resolveDataToken)(req.headers);
-                const rlKey = userId ?? (0, serve_hardening_1.clientIp)(req);
+                // Rate-limit on the trusted proxy identity (or client IP), never the client-supplied
+                // body user_id — otherwise a caller rotates user_id per request to reset the bucket.
+                const rlKey = (0, serve_hardening_1.resolveUserId)(req.headers, undefined) ?? (0, serve_hardening_1.clientIp)(req);
                 if (!rateLimiter.tryConsume(rlKey)) {
                     res.writeHead(429, { 'Content-Type': 'application/json', 'Retry-After': String(rateLimiter.retryAfterSeconds(rlKey)) });
                     res.end(JSON.stringify({ error: 'Rate limit exceeded' }));
                     return;
                 }
-                const sessionKey = body.session_id || `anon-${userId ?? 'unknown'}`;
-                if (!turnLimiter.tryConsume(sessionKey)) {
-                    res.writeHead(429, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                // Same user-namespaced session key + fail-closed rule as /v1/chat above.
+                const { sessionKey, rejected } = (0, serve_hardening_1.resolveServeSessionKey)(body.session_id, userId);
+                if (rejected) {
+                    sessionEventWriter.append('unverified', (0, base_1.generateRequestId)(), 'warrant_denied', { reason: rejected });
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'session_id requires an authenticated user' }));
+                    return;
+                }
+                // Acquire BEFORE writeHead(200, SSE) so a reject still gets a clean 429.
+                const release = await turnGate.acquire();
+                if (!release) {
+                    warnGateReject(`TurnGate: rejecting /v1/chat/stream (inflight=${turnGate.inflight} queued=${turnGate.queued} max=${turnGate.max})`);
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(serve_hardening_1.TURN_GATE_RETRY_AFTER_SECONDS),
+                    });
+                    res.end(JSON.stringify({ error: 'At capacity' }));
                     return;
                 }
-                res.writeHead(200, {
-                    'Content-Type': 'text/event-stream',
-                    'Cache-Control': 'no-cache',
-                    'Connection': 'keep-alive',
-                });
-                await (0, credential_context_1.runWithCredential)({ userId: userId ?? 'anonymous', dataToken }, () => handleStreamingChat(runner, body, defaultEngine, defaultModel, options.workspace, permissions, res, userId), { dataTokenDir: storagePath });
-                statePusher?.schedule(); // async-delta push, off the response path
+                // Turn-scoped data capability — same rules as /v1/chat above.
+                let turnReg = null;
+                try {
+                    if (!turnLimiter.tryConsume(sessionKey)) {
+                        res.writeHead(429, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                        return;
+                    }
+                    await prepareSession(sessionKey);
+                    if (userId?.trim()) {
+                        turnReg = registerServeTurn({ userId: userId.trim(), sessionKey, inboundToken: dataToken });
+                    }
+                    // Fail-closed credential check MUST run before SSE writeHead(200).
+                    // Otherwise a warrant denial lands after headers are committed, the outer
+                    // catch can only append raw JSON (not an SSE error event), and the IDE
+                    // client's SSE parser falls through to emitter.done() → silent success.
+                    await (0, credential_context_1.runWithCredential)({ userId, dataToken }, async () => {
+                        res.writeHead(200, {
+                            'Content-Type': 'text/event-stream',
+                            'Cache-Control': 'no-cache',
+                            'Connection': 'keep-alive',
+                        });
+                        await handleStreamingChat(runner, body, sessionKey, defaultEngine, defaultModel, options.workspace, permissions, res, userId, turnReg?.env);
+                    }, { onDenied: logWarrantDenied(sessionKey) });
+                    statePusher?.schedule(sessionKey); // per-session delta push, off the response path
+                }
+                finally {
+                    turnReg?.release();
+                    release();
+                }
                 return;
             }
             // 404
@@ -289,7 +460,7 @@ async function serveCommand(options) {
             }
             console.log(`Workspace: ${options.workspace}`);
             if (pack) {
-                console.log(`Pack:      ${pack.manifest.metadata.name}`);
+                console.log(`Pack:      ${pack.manifest.metadata.name}@${pack.manifest.metadata.version}`);
                 console.log(`Gateway:   ${gatewayAgentId}`);
             }
             console.log(BANNER_LINE);
@@ -312,17 +483,50 @@ async function serveCommand(options) {
                 }
             }
             if (options.gatewayBridge) {
+                // Egress broker (secure-obo-design §7.6): start before the bridge so the URL is in
+                // process.env when the first channel turn spawns an engine. The broker holds the
+                // gateway token; the agent presents only the turn nonce.
+                if (turnRegistry) {
+                    try {
+                        egressBroker = await (0, data_plane_1.startEgressBroker)({
+                            registry: turnRegistry,
+                            workspaceRoot: options.workspace,
+                            agentId: pack.manifest.metadata.name,
+                            send: async (handle, message, media) => {
+                                const r = await (0, outboundSend_1.sendGatewayOutboundMessage)(handle, { message, media, token: brokerGatewayToken });
+                                return { ok: r.ok, via: r.via, stdout: r.stdout, stderr: r.stderr };
+                            },
+                            logger: options.verbose ? new headless_1.ConsoleLogger('[Egress]') : new headless_1.NoOpLogger(),
+                            audit: auditEvent,
+                        });
+                        process.env[data_plane_1.EGRESS_URL_ENV] = egressBroker.url;
+                        // Now that the broker holds the token, strip it from the process env so no
+                        // engine child (all spread process.env) inherits it (§7.4 gap 1 close).
+                        delete process.env.OPENCLAW_GATEWAY_TOKEN;
+                        console.log('OK: Egress broker on loopback — gateway token stays broker-side; agent sends via turn nonce');
+                    }
+                    catch (err) {
+                        console.error(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} Egress broker failed to start: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
                 try {
                     gatewayBridge = await startServeGatewayBridge({
                         gatewayAgentId,
                         packName: pack.manifest.metadata.name,
                         workspace: options.workspace,
-                        stateDir: storagePath,
+                        registerTurn: registerServeTurn,
+                        brokerGatewayToken,
                         engine: defaultEngine,
                         defaultModel,
                         runner,
                         permissions,
-                        onTurnComplete: () => statePusher?.schedule(),
+                        turnGate,
+                        rateLimiter,
+                        turnLimiter,
+                        warnGateReject,
+                        prepareSession,
+                        onTurnComplete: (sessionId) => statePusher?.schedule(sessionId),
+                        logWarrantDenied,
                     });
                 }
                 catch (err) {
@@ -360,6 +564,22 @@ async function serveCommand(options) {
                 }
                 gatewayBridge = null;
             }
+            if (dataPlane) {
+                try {
+                    await dataPlane.close();
+                }
+                catch {
+                    // best-effort
+                }
+            }
+            if (egressBroker) {
+                try {
+                    await egressBroker.close();
+                }
+                catch {
+                    // best-effort
+                }
+            }
             server.close(() => {
                 runner.dispose();
                 process.exit(0);
@@ -383,15 +603,18 @@ async function parseBody(req) {
         throw new Error('Invalid JSON');
     }
 }
-async function handleChat(runner, body, defaultEngine, defaultModel, workspace, permissions, userId) {
+async function handleChat(runner, body, sessionKey, defaultEngine, defaultModel, workspace, permissions, userId, turnEnv) {
     const result = await runner.run({
         engineId: resolveRequestedEngineId(body.engine, defaultEngine),
         modelId: body.model || defaultModel,
         message: body.message,
         workspaceRoot: workspace,
-        sessionId: body.session_id,
+        // The user-namespaced key (never raw body.session_id) so engine conversation
+        // state and per-session artifacts are per-user — see resolveServeSessionKey.
+        sessionId: sessionKey,
         analyticsUserId: userId,
         permissions,
+        turnEnv,
     });
     return {
         success: result.success,
@@ -401,6 +624,85 @@ async function handleChat(runner, body, defaultEngine, defaultModel, workspace,
         error: result.error,
     };
 }
+/**
+ * Session key for a gateway turn. Prefers the caller's own session identifiers; when the
+ * sender has a resolved identity but no session id, keys off that identity (stable, no
+ * collision risk — it's unique to that sender). Only when NEITHER a session id nor an
+ * identity is available does this fall back to a per-message unique key, rather than a
+ * shared 'gateway-anon' bucket — a shared bucket would let two unrelated, genuinely
+ * unidentified senders share one TurnLimiter budget and, when AGENTHIPPO_STATE_S3_URI is
+ * set, one S3 session-state prefix (ensureSessionLocal/pushSessionState), letting one
+ * anonymous sender's state be restored into another's turn.
+ *
+ * `durable` is false only for that one-off fallback key. A key that is by construction
+ * never reused can never hit its own TurnLimiter cap and can never have prior S3 state to
+ * restore or a future turn to restore it for — callers should skip per-session tracking
+ * (TurnLimiter, prepareSession/ensureSessionLocal, onTurnComplete/statePusher.schedule) for
+ * it entirely, rather than accumulate a permanent, never-useful entry in those stores.
+ *
+ * `sessionKey` is namespaced by the resolved sender identity when an explicit session id is
+ * supplied (secure-obo-design §3.4 — a caller-supplied id must not attach to another
+ * sender's engine session). `outboundKey` preserves the raw gateway key: the bridge records
+ * reply handles under it (bridge.ts upsertGatewayOutboundHandle), so the outbound-routing
+ * file must keep resolving from the un-namespaced key or reply-to-sender breaks.
+ */
+function resolveGatewaySessionKey(opts, userId) {
+    const explicit = opts.sessionId?.trim() || opts.gatewaySessionKey?.trim();
+    if (explicit) {
+        const sessionKey = userId ? `u${(0, serve_hardening_1.userNamespaceHash)(userId)}--${explicit}` : explicit;
+        return { sessionKey, outboundKey: explicit, durable: true };
+    }
+    if (userId) {
+        // Already keyed on the sender's own identity — no cross-user attachment surface.
+        return { sessionKey: `gateway-${userId}`, outboundKey: `gateway-${userId}`, durable: true };
+    }
+    // randomUUID (122 bits), not generateRequestId (~32 bits) — this is the sole thing
+    // standing between two unrelated anonymous senders and a real collision, so it needs to
+    // be architecturally collision-free, not just statistically unlikely.
+    const anon = `gateway-anon-${(0, node_crypto_1.randomUUID)()}`;
+    return { sessionKey: anon, outboundKey: anon, durable: false };
+}
+/**
+ * Gateway-channel turn admission: rate limit → turn gate (capacity) → per-session turn cap,
+ * then run. Extracted from the gateway bridge's messageHandler so this is directly testable
+ * without a live gateway connection — this exact sequence (mirroring the HTTP endpoints'
+ * admission order) previously didn't exist for gateway-originated turns at all: channel
+ * messages skipped both the identity-keyed rate limiter and the per-session turn cap.
+ * Gateway channels can't receive an HTTP 429, so each rejection emits a short channel
+ * message instead (best-effort — a channel-notice failure must not mask the rejection).
+ */
+async function runGatewayTurn(params) {
+    const notify = async (text) => {
+        try {
+            await params.emitter?.text(text);
+            await params.emitter?.done();
+        }
+        catch {
+            // best-effort channel notice
+        }
+    };
+    if (!params.rateLimiter.tryConsume(params.rlKey)) {
+        await notify(serve_hardening_1.RATE_LIMIT_BUSY_MESSAGE);
+        return { success: false, error: 'rate_limited' };
+    }
+    // Acquire before the turn-limiter so a capacity reject does not burn a turn slot.
+    const release = await params.turnGate.acquire();
+    if (!release) {
+        params.warnGateReject(`TurnGate: rejecting gateway turn (inflight=${params.turnGate.inflight} queued=${params.turnGate.queued} max=${params.turnGate.max})`);
+        await notify(serve_hardening_1.TURN_GATE_BUSY_MESSAGE);
+        return { success: false, error: 'busy' };
+    }
+    try {
+        if (params.trackSession !== false && !params.turnLimiter.tryConsume(params.sessionKey)) {
+            await notify(serve_hardening_1.TURN_LIMIT_BUSY_MESSAGE);
+            return { success: false, error: 'turn_limit' };
+        }
+        return await params.run();
+    }
+    finally {
+        release();
+    }
+}
 /**
  * Register this serve process as an OpenClaw external agent (WebSocket `agent.run` → headless runner).
  * Enables `openclaw agent --agent <packId> --message "…"` against the same gateway.
@@ -409,7 +711,9 @@ async function startServeGatewayBridge(params) {
     const { GatewayBridge: Bridge } = await import('../../gateway/bridge.js');
     const DEFAULT_GATEWAY_PORT = 18789;
     const gatewayUrl = process.env.OPENCLAW_GATEWAY_URL ?? `ws://127.0.0.1:${DEFAULT_GATEWAY_PORT}`;
-    const token = process.env.OPENCLAW_GATEWAY_TOKEN;
+    // Use the captured token — serve strips OPENCLAW_GATEWAY_TOKEN from process.env once the
+    // egress broker holds it, so the bridge must not depend on the env var (§7.6).
+    const token = params.brokerGatewayToken ?? process.env.OPENCLAW_GATEWAY_TOKEN;
     const bridge = new Bridge({ gatewayUrl, token });
     await bridge.connect();
     await bridge.registerAgent({
@@ -426,19 +730,65 @@ async function startServeGatewayBridge(params) {
                 : (requestedEngine || params.engine);
             // #4: the channel sender becomes the per-user user_id (analytics + per-user data scoping).
             const userId = (0, serve_hardening_1.peerToUserId)(opts.peerInfo);
-            const result = await (0, credential_context_1.runWithCredential)({ userId: userId ?? 'gateway' }, () => params.runner.run({
-                engineId: effectiveEngine,
-                modelId: params.defaultModel,
-                message,
-                workspaceRoot: params.workspace,
-                sessionId: opts.sessionId,
-                gatewaySessionKey: opts.gatewaySessionKey,
-                analyticsUserId: userId,
+            const { sessionKey, outboundKey, durable } = resolveGatewaySessionKey(opts, userId);
+            return runGatewayTurn({
+                rateLimiter: params.rateLimiter,
+                turnLimiter: params.turnLimiter,
+                turnGate: params.turnGate,
+                warnGateReject: params.warnGateReject,
+                // Same identity-keyed cap the HTTP endpoints enforce — a channel sender is already
+                // trusted enough here to gate the OBO credential scope below, so it's trusted enough
+                // to rate-limit on directly. Unidentified senders share one 'gateway' bucket rather
+                // than being exempt from throttling entirely.
+                rlKey: userId ?? 'gateway',
+                sessionKey,
+                trackSession: durable,
                 emitter: opts.emitter,
-                permissions: params.permissions,
-            }), { dataTokenDir: params.stateDir });
-            params.onTurnComplete?.();
-            return { success: result.success, error: result.error };
+                run: async () => {
+                    // A one-off anonymous sessionKey can never have prior state to restore, and
+                    // nothing will ever look it up again to push state for — skip both S3 round-trips.
+                    if (durable) {
+                        await params.prepareSession(sessionKey);
+                    }
+                    // Channel-originated turns carry no inbound platform token: with the
+                    // passthrough provider they fail closed at the gateway (an unlinked chat
+                    // peer gets NO data credential — secure-obo-design §7.5 bind-before-
+                    // credential); the identity provider maps the peer id server-side instead.
+                    // egressStoreKey is the RAW gateway key (outboundKey) the bridge records reply
+                    // handles under — it lets the egress broker resolve this session's bound
+                    // destinations server-side (§7.6). userId gates BOTH capabilities: an
+                    // unidentified peer gets neither a nonce nor an egress route.
+                    const turnReg = userId?.trim()
+                        ? params.registerTurn({ userId: userId.trim(), sessionKey, egressStoreKey: outboundKey })
+                        : null;
+                    try {
+                        const result = await (0, credential_context_1.runWithCredential)({ userId }, () => params.runner.run({
+                            engineId: effectiveEngine,
+                            modelId: params.defaultModel,
+                            message,
+                            workspaceRoot: params.workspace,
+                            // Use the resolved sessionKey (not the raw opts fields) so the engine's own
+                            // session state and the S3 restore/push above key off the same, user-namespaced
+                            // identity. The outbound-routing file (buildSessionEnvPatch) keeps the raw
+                            // gateway key — the bridge records reply handles under it, so namespacing it
+                            // here would break reply-to-sender. See resolveGatewaySessionKey.
+                            sessionId: sessionKey,
+                            gatewaySessionKey: outboundKey,
+                            analyticsUserId: userId,
+                            emitter: opts.emitter,
+                            permissions: params.permissions,
+                            turnEnv: turnReg?.env,
+                        }), { onDenied: params.logWarrantDenied(sessionKey) });
+                        if (durable) {
+                            params.onTurnComplete?.(sessionKey);
+                        }
+                        return { success: result.success, error: result.error };
+                    }
+                    finally {
+                        turnReg?.release();
+                    }
+                },
+            });
         },
     });
     console.log(`${utils_1.COLORS.green}✓${utils_1.COLORS.reset} Gateway bridge: registered "${params.gatewayAgentId}" at ${gatewayUrl}`);
@@ -502,7 +852,7 @@ async function bindToGatewayChannels(agentId, bindSpec) {
         client.close();
     }
 }
-async function handleStreamingChat(runner, body, defaultEngine, defaultModel, workspace, permissions, res, userId) {
+async function handleStreamingChat(runner, body, sessionKey, defaultEngine, defaultModel, workspace, permissions, res, userId, turnEnv) {
     let streamEnded = false;
     const sendEvent = (type, data) => {
         if (streamEnded || res.writableEnded) {
@@ -556,10 +906,12 @@ async function handleStreamingChat(runner, body, defaultEngine, defaultModel, wo
             modelId: body.model || defaultModel,
             message: body.message,
             workspaceRoot: workspace,
-            sessionId: body.session_id,
+            // The user-namespaced key (never raw body.session_id) — see resolveServeSessionKey.
+            sessionId: sessionKey,
             analyticsUserId: userId,
             emitter,
             permissions,
+            turnEnv,
         });
         if (!streamEnded) {
             sendEvent('done', {});