@agenthippo-ai/agenthippo 0.1.1 → 0.2.3-dataplane

package/out/cli/idp-init.js

@@ -0,0 +1,303 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderIdpArtifacts = renderIdpArtifacts;
+/**
+ * `agenthippo idp init` — generator for the central IdP stack (PLAN/deploy.md, "customer 0").
+ *
+ * Why this exists: the org IdP used to be static files checked into this source repo
+ * (enterprise-deploy/idp/), which meant the actual identity routes could drift from
+ * renderIdentityLayer() (fixed once already) AND — the bigger problem — an enterprise
+ * customer standing up their own IdP had no way to get any of it at all, since they only
+ * receive the compiled `agenthippo` binary, never this repo. Generating it here, from the
+ * same shared identity/auth-env/Dockerfile renderers every `deploy init` target already
+ * uses, fixes both: it ships in the binary, and it can never drift from what agents expect.
+ *
+ * AgentHippo's own auth.agenthippo.ai instance is "customer 0" — stood up with this exact
+ * command, not a bespoke internal setup.
+ */
+const identity_1 = require("./deploy/layers/identity");
+const deploy_init_1 = require("./deploy-init");
+function resolveCookieDomain(ctx) {
+    if (ctx.cookieDomain?.trim()) {
+        return ctx.cookieDomain.trim();
+    }
+    const parts = ctx.hostname.split('.');
+    return parts.length > 2 ? `.${parts.slice(-2).join('.')}` : `.${ctx.hostname}`;
+}
+function renderIdpComposeYaml() {
+    return [
+        '# Central IdP. See PLAN/deploy-runbook.md scenario E/F.',
+        '#',
+        '#   ./run.sh',
+        '#',
+        '# Env split (matches `agenthippo deploy init`):',
+        '#   ~/.agent-hippo/.env (+ optional ./.env)           — hostname only',
+        '#   ~/.agent-hippo/.env.auth (+ optional ./.env.auth) — JWT/OAuth; broker + oauth2-proxy ONLY',
+        '# Profiles: edge (SSO stack), tunnel (Cloudflare → Caddy)',
+        '# Org identity infra only — no agent runs here. Per-agent edges are generated separately',
+        '# by `agenthippo deploy init` and deployed on their own host/service.',
+        'services:',
+        '  oauth2-proxy:',
+        '    profiles: ["edge"]',
+        '    image: quay.io/oauth2-proxy/oauth2-proxy:v7.7.1',
+        '    env_file:',
+        '      - path: ${HOME}/.agent-hippo/.env',
+        '        required: false',
+        '      - path: .env',
+        '        required: false',
+        '      - path: ${HOME}/.agent-hippo/.env.auth',
+        '        required: false',
+        '      - path: .env.auth',
+        '        required: false',
+        '    environment:',
+        '      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180',
+        '      OAUTH2_PROXY_UPSTREAMS: file:///dev/null',
+        '      OAUTH2_PROXY_SET_XAUTHREQUEST: "true"',
+        '      OAUTH2_PROXY_PASS_AUTHORIZATION_HEADER: "true"',
+        '      OAUTH2_PROXY_SKIP_PROVIDER_BUTTON: "true"',
+        '      OAUTH2_PROXY_REVERSE_PROXY: "true"',
+        '    expose: ["4180"]',
+        '',
+        '  auth-broker:',
+        '    profiles: ["edge"]',
+        '    build:',
+        '      context: .',
+        '      dockerfile: Dockerfile.auth-broker',
+        '    env_file:',
+        '      - path: ${HOME}/.agent-hippo/.env',
+        '        required: false',
+        '      - path: .env',
+        '        required: false',
+        '      - path: ${HOME}/.agent-hippo/.env.auth',
+        '        required: false',
+        '      - path: .env.auth',
+        '        required: false',
+        '    environment:',
+        '      AGENTHIPPO_AUTH_PORT: "9780"',
+        '      AGENTHIPPO_AUTH_DATA_DIR: /data',
+        '      # Proxy hops in front of the broker: 1 = Caddy only (edge profile), 2 = Cloudflare',
+        '      # Tunnel → Caddy (run.sh sets 2; at 1 the rate limiter would key every tunnel',
+        '      # client on cloudflared\'s IP — one shared bucket).',
+        '      AGENTHIPPO_XFF_TRUSTED_HOPS: ${AGENTHIPPO_XFF_TRUSTED_HOPS:-1}',
+        '    volumes: ["auth-broker-data:/data"]',
+        '    expose: ["9780"]',
+        '',
+        '  caddy:',
+        '    profiles: ["edge"]',
+        '    image: caddy:2.8-alpine',
+        '    env_file:',
+        '      - path: ${HOME}/.agent-hippo/.env',
+        '        required: false',
+        '      - path: .env',
+        '        required: false',
+        '    # With the tunnel profile, set AGENTHIPPO_CADDY_BIND=127.0.0.1 so a public-IP host',
+        '    # cannot be hit directly on 80/443, bypassing Cloudflare.',
+        '    # Bare-metal / BYO nginx or ALB already on 80/443? Set AGENTHIPPO_CADDY_HTTP_PORT /',
+        '    # AGENTHIPPO_CADDY_HTTPS_PORT to alternate host ports and point your own reverse proxy',
+        '    # at them — the container still listens on 80 internally, only the host mapping moves.',
+        '    ports:',
+        '      - "${AGENTHIPPO_CADDY_BIND:-0.0.0.0}:${AGENTHIPPO_CADDY_HTTP_PORT:-80}:80"',
+        '      - "${AGENTHIPPO_CADDY_BIND:-0.0.0.0}:${AGENTHIPPO_CADDY_HTTPS_PORT:-443}:443"',
+        '    volumes:',
+        '      - ./Caddyfile:/etc/caddy/Caddyfile:ro',
+        '      # Colocated agents (deploy init --colocate) drop a route snippet here — see Caddyfile.',
+        '      - ./agents:/etc/caddy/agents:ro',
+        '    networks: [default, colocate]',
+        '    depends_on: [oauth2-proxy, auth-broker]',
+        '',
+        '  cloudflared:',
+        '    profiles: ["tunnel"]',
+        '    image: cloudflare/cloudflared:2024.12.2',
+        '    restart: unless-stopped',
+        '    command: tunnel --config /etc/cloudflared/config.yml run',
+        '    volumes:',
+        '      - ./cloudflared.yml:/etc/cloudflared/config.yml:ro',
+        '      # Set by run.sh from its argument (./run.sh /path/to/tunnel-credentials.json);',
+        '      # falls back to the conventional location for a direct `docker compose` invocation.',
+        '      - ${AGENTHIPPO_TUNNEL_CREDENTIALS:-${HOME}/.agent-hippo/tunnel-credentials.json}:/etc/cloudflared/credentials.json:ro',
+        '    depends_on: [caddy]',
+        '',
+        'volumes:',
+        '  auth-broker-data:',
+        '',
+        'networks:',
+        '  default:',
+        '  # Stable, explicitly-named network (not the implicit "idp_default") so a colocated agent\'s',
+        '  # own compose project can join it reliably regardless of which directory `docker compose`',
+        '  # runs from. Only Caddy needs it — its per-agent snippets `reverse_proxy` straight to the',
+        '  # agent container by name; auth-broker is reached over the (already-shared) default network.',
+        '  colocate:',
+        '    name: agenthippo-idp-colocate',
+        '',
+    ].join('\n');
+}
+function renderIdpCaddyfile() {
+    const identityLines = (0, identity_1.renderIdentityLayer)({
+        mode: 'self-issued',
+        oauth2ProxyAddr: 'oauth2-proxy:4180',
+        authBrokerAddr: 'auth-broker:9780',
+        healthProxy: ['    reverse_proxy auth-broker:9780'],
+        // No agent behind the IdP: a Bearer request to /v1/* doesn't exist here (404, not a
+        // silent pass-through), and an unauthenticated browser sees a plain confirmation once
+        // past the SSO gate.
+        agentProxy: ['    respond "not_found" 404'],
+        catchallBody: ['    respond "AgentHippo IdP" 200'],
+    });
+    return [
+        '# SSO edge + Cloudflare Tunnel. Set AGENTHIPPO_PUBLIC_HOSTNAME in .env (Caddy reads it below).',
+        '# TLS terminates at Cloudflare; origin listens on HTTP only.',
+        '{',
+        '  auto_https off',
+        '}',
+        '',
+        '# Same-host colocation: agents deployed with `deploy init --ingress edge-fed --colocate`',
+        '# on THIS host ship a route snippet instead of their own Caddy/oauth2-proxy/auth-broker.',
+        '# Drop it in ./agents/<name>.caddy (mounted in docker-compose.yml) and',
+        '# `docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile` to pick it up —',
+        '# no rebuild, no restart of the IdP itself.',
+        'import agents/*.caddy',
+        '',
+        `http://{$AGENTHIPPO_PUBLIC_HOSTNAME} {`,
+        ...identityLines,
+        '}',
+        '',
+    ].join('\n');
+}
+/** Render every artifact for `agenthippo idp init` (relative path → file content). Pure: no fs writes. */
+function renderIdpArtifacts(ctx) {
+    const cookieDomain = resolveCookieDomain(ctx);
+    return {
+        'docker-compose.yml': renderIdpComposeYaml(),
+        'Dockerfile.auth-broker': (0, deploy_init_1.renderAuthBrokerDockerfile)(),
+        'Caddyfile': renderIdpCaddyfile(),
+        '.env.example': [
+            '# Caddy hostname for the central IdP. No agent runs on this stack — auth secrets:',
+            '# see .env.auth.example → ~/.agent-hippo/.env.auth (broker + oauth2-proxy only).',
+            '',
+            `AGENTHIPPO_PUBLIC_HOSTNAME=${ctx.hostname}`,
+            '',
+            '# Proxy hops / Caddy bind (optional; run.sh sets XFF hops=2 for tunnel)',
+            '# AGENTHIPPO_XFF_TRUSTED_HOPS=1',
+            '# AGENTHIPPO_CADDY_BIND=0.0.0.0',
+            '',
+            '# Bare metal / BYO nginx or ALB already on 80/443? Rebind Caddy to alternate host ports',
+            '# and point your reverse proxy at them (container still listens on 80 internally):',
+            '# AGENTHIPPO_CADDY_HTTP_PORT=8080',
+            '# AGENTHIPPO_CADDY_HTTPS_PORT=8443',
+            '',
+        ].join('\n'),
+        '.env.auth.example': (0, deploy_init_1.renderAuthEnvExample)({ hostname: ctx.hostname, fed: false, cookieDomain }),
+        'cloudflared.yml.example': [
+            '# Copy to cloudflared.yml; the credentials JSON lives in ~/.agent-hippo/ (never in the repo).',
+            '#   cloudflared tunnel create agenthippo-auth',
+            '#   cp ~/.cloudflared/<tunnel-id>.json ~/.agent-hippo/tunnel-credentials.json',
+            `#   cloudflared tunnel route dns agenthippo-auth ${ctx.hostname}`,
+            'tunnel: REPLACE_WITH_TUNNEL_ID',
+            'credentials-file: /etc/cloudflared/credentials.json',
+            'ingress:',
+            `  - hostname: ${ctx.hostname}`,
+            '    service: http://caddy:80',
+            '  - service: http_status:404',
+            '',
+        ].join('\n'),
+        'run.sh': [
+            '#!/usr/bin/env bash',
+            '# Start central IdP: Caddy + oauth2-proxy + auth-broker (+ Cloudflare tunnel, if requested).',
+            '# No agent here — per-agent edges are generated separately by `agenthippo deploy init`.',
+            '#',
+            '# Usage:',
+            '#   ./run.sh                                       bare metal / BYO nginx or ALB in front',
+            '#   ./run.sh /path/to/tunnel-credentials.json       Cloudflare Tunnel',
+            '#',
+            '# Bare metal / BYO nginx or ALB: run with no argument — starts --profile edge only.',
+            '# If 80/443 are already taken by your reverse proxy, set AGENTHIPPO_CADDY_HTTP_PORT/',
+            '# _HTTPS_PORT in .env first so Caddy rebinds elsewhere.',
+            'set -euo pipefail',
+            'cd "$(dirname "$0")"',
+            'if [[ $# -ge 1 ]]; then',
+            '  export AGENTHIPPO_TUNNEL_CREDENTIALS="$1"',
+            '  [[ -f "$AGENTHIPPO_TUNNEL_CREDENTIALS" ]] || {',
+            '    echo "Tunnel credentials file not found: $AGENTHIPPO_TUNNEL_CREDENTIALS" >&2; exit 1; }',
+            '  # Two proxy hops behind the tunnel (cloudflared → Caddy) — see docker-compose.yml.',
+            '  export AGENTHIPPO_XFF_TRUSTED_HOPS="${AGENTHIPPO_XFF_TRUSTED_HOPS:-2}"',
+            '  docker compose --profile edge --profile tunnel up -d --build',
+            `  echo "IdP: https://\${AGENTHIPPO_PUBLIC_HOSTNAME:-${ctx.hostname}} (via Cloudflare Tunnel)"`,
+            'else',
+            '  echo "No tunnel credentials path given — starting --profile edge only (no tunnel)."',
+            '  echo "Front this host with your own nginx/ALB; see AGENTHIPPO_CADDY_HTTP_PORT/AGENTHIPPO_CADDY_BIND in .env."',
+            '  echo "(To use a Cloudflare Tunnel instead: ./run.sh /path/to/tunnel-credentials.json)"',
+            '  docker compose --profile edge up -d --build',
+            `  echo "IdP: http://\${AGENTHIPPO_PUBLIC_HOSTNAME:-${ctx.hostname}} (behind your own reverse proxy)"`,
+            'fi',
+            '',
+        ].join('\n'),
+        'agents/README.md': [
+            '# Colocated agent routes',
+            '',
+            'Drop `*.caddy` route snippets here for agents deployed on **this same host** via:',
+            '',
+            '```bash',
+            'agenthippo deploy init <pack> --target compose --ingress edge-fed --colocate',
+            '```',
+            '',
+            'That command generates `deploy/agent-route.caddy` (copy it here, renamed to something',
+            'identifying the agent) plus a `docker-compose.yml` containing only the `agent` service',
+            '(no Caddy/oauth2-proxy/auth-broker of its own — it joins this IdP\'s',
+            '`agenthippo-idp-colocate` network and rides the IdP\'s existing edge).',
+            '',
+            'After copying a new snippet in:',
+            '',
+            '```bash',
+            'docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile',
+            '```',
+            '',
+            'No rebuild, no restart of the IdP itself. See `../Caddyfile`\'s `import agents/*.caddy` and',
+            '`PLAN/deploy-runbook.md` scenario F for the full picture.',
+            '',
+        ].join('\n'),
+        'README.md': [
+            '# Central IdP',
+            '',
+            '**One per organization.** Hosts Google SSO (oauth2-proxy) and the IDE auth-broker only —',
+            'no agent runs here. Agent edges are generated and deployed separately.',
+            '',
+            'Generated by `agenthippo idp init` — regenerate (don\'t hand-edit `Caddyfile`, which comes',
+            'straight from the same identity module every agent\'s Caddyfile uses) if you need to change',
+            'routing: that lives in the CLI itself, not in this output.',
+            '',
+            'This stack runs on **any host with Docker** — local laptop, team VM, cloud VM, or on-prem.',
+            '`./run.sh` picks the path below based on whether you pass it a tunnel credentials path.',
+            '',
+            '## Quick start',
+            '',
+            '```bash',
+            'cp .env.example ~/.agent-hippo/.env',
+            'cp .env.auth.example ~/.agent-hippo/.env.auth   # fill in; never put AGENTHIPPO_AUTH_JWT_SECRET in .env',
+            '```',
+            '',
+            '**Cloudflare Tunnel** (no public ports to manage yourself):',
+            '',
+            '```bash',
+            'cp cloudflared.yml.example cloudflared.yml   # set tunnel id',
+            'cloudflared tunnel create agenthippo-auth     # writes ~/.cloudflared/<tunnel-id>.json',
+            'cp ~/.cloudflared/<tunnel-id>.json ~/.agent-hippo/tunnel-credentials.json',
+            './run.sh ~/.agent-hippo/tunnel-credentials.json',
+            '```',
+            '',
+            '**Bare metal / BYO nginx or ALB already fronting this host:**',
+            '',
+            '```bash',
+            '# skip cloudflared.yml entirely. If 80/443 are already taken by your reverse proxy,',
+            '# set AGENTHIPPO_CADDY_HTTP_PORT/AGENTHIPPO_CADDY_HTTPS_PORT in .env first.',
+            './run.sh   # no argument — starts --profile edge only',
+            '# point your nginx/ALB at this host\'s Caddy (AGENTHIPPO_CADDY_BIND / _HTTP_PORT above)',
+            '```',
+            '',
+            'Agent edges (e.g. `cs.corp.example`) are separate — see `PLAN/deploy-runbook.md` scenarios E/F.',
+            '',
+        ].join('\n'),
+    };
+}

package/out/cli/index.js

@@ -77,6 +77,7 @@ const ask_1 = require("./commands/ask");
 const serve_1 = require("./commands/serve");
 const auth_broker_1 = require("./commands/auth-broker");
 const deploy_1 = require("./commands/deploy");
+const idp_1 = require("./commands/idp");
 const pack_1 = require("./commands/pack");
 const store_1 = require("./commands/store");
 const anywhere_1 = require("./commands/anywhere");
@@ -247,22 +248,29 @@ program
 // Deploy command - generate platform-native deploy artifacts
 program
     .command('deploy <action> [pack]')
-    .description('Generate a self-contained deploy staging dir (init). Targets: vm, compose, cloudrun, databricks-app, spcs, cloudflare, all')
+    .description('Generate a self-contained deploy staging dir (init). Targets: vm, compose, cloudrun, databricks-app, spcs, cloudflare, aws-ecs, azure-container-apps, all. Or pick a --blueprint instead of raw --target/--ingress.')
     .option('-t, --target <target>', 'Deploy target', 'vm')
-    .option('-o, --out <path>', 'Staging directory (default: ./deploy-out/<pack>-<target>)')
+    .option('--blueprint <id>', 'Named preset (sandbox, prospect-demo, team-pilot, regulated-air-gapped, enterprise-fleet) — resolves --target/--ingress for you (PLAN/deploy.md §3); overrides both when set')
+    .option('--platform <platform>', 'Which platform to use within --blueprint\'s supported set (defaults to the blueprint\'s first); ignored without --blueprint')
+    .option('-o, --out <path>', 'Staging directory (default: ./deploy-out/<pack>-<target> relative to cwd; run from the pack parent, not from inside the pack)')
     .option('--packdir <path>', 'Pack directory (defaults to [pack] arg or cwd)')
     .option('--image <ref>', 'Runtime image ref (default: engine runtime:latest, or :latest-cursor for cursor packs)')
     .option('-p, --port <port>', 'Container port', '8080')
     .option('--gateway <channels>', 'Agent Anywhere: bind channels (e.g. "slack") + add OpenClaw gateway service (compose target)')
     .option('--hostname <host>', 'Public hostname for SSO edge (Caddy, OAuth, tunnel)', 'auth.agenthippo.ai')
-    .option('--ingress <mode>', 'Cloud Run ingress: iap (built-in IAP), edge (per-service AgentHippo edge + Google OAuth), or edge-fed (federated: auth via auth.agenthippo.ai, no per-service OAuth)', 'iap')
+    .option('--ingress <mode>', 'iap (Cloud Run built-in IAP only), edge (self-issued AgentHippo edge + Google OAuth — vm/compose/cloudrun/aws-ecs/azure-container-apps), or edge-fed (federated: auth via the central IdP, no per-target OAuth client — same targets as edge)', 'iap')
     .option('--idp-url <url>', 'edge-fed: central IdP base URL browsers redirect to for login (e.g. https://auth.agenthippo.ai)', 'https://auth.agenthippo.ai')
     .option('--cookie-domain <domain>', 'edge-fed: parent domain the shared auth cookie is scoped to (e.g. .agenthippo.ai)', '.agenthippo.ai')
+    .option('--colocate', 'edge-fed + vm/compose only: ride the org IdP\'s already-running Caddy + auth-broker instead of shipping this agent\'s own (PLAN/deploy.md §4 state 4)')
+    .option('--model-routing <mode>', 'Cloud Run + edge-fed: sidecar (in-pod LiteLLM+OTEL, default) or gateway (agent → gateway.agenthippo.ai directly, lean)')
     .option('--force', 'Overwrite existing files')
     .action(async (action, pack, options) => {
     const ingress = options.ingress === 'edge' ? 'edge' : options.ingress === 'edge-fed' ? 'edge-fed' : 'iap';
+    const modelRouting = options.modelRouting === 'gateway' ? 'gateway' : options.modelRouting === 'sidecar' ? 'sidecar' : undefined;
     await (0, deploy_1.deployCommand)(action, pack, {
         target: options.target,
+        blueprint: options.blueprint,
+        platform: options.platform,
         out: options.out,
         image: options.image,
         gateway: options.gateway,
@@ -273,6 +281,24 @@ program
         ingress,
         idpUrl: options.idpUrl,
         cookieDomain: options.cookieDomain,
+        colocate: Boolean(options.colocate),
+        modelRouting,
+    });
+});
+// IdP command - generate the central IdP stack (org identity infra, set up once)
+program
+    .command('idp <action>')
+    .description('Generate the central IdP stack (init) — Caddy + oauth2-proxy + auth-broker. One per organization; agents federate against it with `deploy init --ingress edge-fed`.')
+    .option('--hostname <host>', 'Public hostname the IdP is reachable at (e.g. auth.corp.example) — required')
+    .option('--cookie-domain <domain>', 'Parent domain the shared auth cookie is scoped to (e.g. .corp.example); defaults to the hostname\'s own domain')
+    .option('-o, --out <path>', 'Output directory (default: ./enterprise-deploy/idp)')
+    .option('--force', 'Overwrite existing files')
+    .action(async (action, options) => {
+    await (0, idp_1.idpCommand)(action, {
+        hostname: options.hostname,
+        cookieDomain: options.cookieDomain,
+        out: options.out,
+        force: Boolean(options.force),
     });
 });
 // Pack command - pack management
@@ -326,8 +352,12 @@ const gatewayCmd = program.command('gateway').description('Gateway outbound mess
 gatewayCmd
     .command('send')
     .description('Send a proactive message via the gateway (WebSocket RPC; hippoclaw CLI fallback)')
-    .requiredOption('--outbound <path>', 'Session gateway-outbound.json (see AGENTHIPPO_GATEWAY_OUTBOUND_FILE)')
-    .requiredOption('-a, --agent <id>', 'Agent pack id')
+    // --outbound/--agent are optional: under `serve` with the egress broker active
+    // (AGENTHIPPO_EGRESS_URL + AGENTHIPPO_TURN_NONCE set), the broker resolves the destination
+    // server-side from the turn nonce and neither is needed (secure-obo-design §7.6). Off-serve
+    // the direct path still requires both (validated in gatewaySendCommand).
+    .option('--outbound <path>', 'Session gateway-outbound.json (see AGENTHIPPO_GATEWAY_OUTBOUND_FILE)')
+    .option('-a, --agent <id>', 'Agent pack id')
     .requiredOption('-m, --message <text>', 'Message to send')
     .option('--media <path-or-url>', 'Attach media (image/audio/video/document); local path or URL. Sent via gateway RPC so the bot token resolves from the gateway runtime snapshot.')
     .option('-t, --target <target>', 'Explicit target (e.g. channel:C01234567); defaults to last inbound route')
@@ -336,8 +366,8 @@ gatewayCmd
     .option('--json', 'Output handle + result as JSON')
     .action(async (options) => {
     await (0, gateway_1.gatewaySendCommand)({
-        outbound: options.outbound,
-        agent: options.agent,
+        outbound: options.outbound ?? '',
+        agent: options.agent ?? '',
         message: options.message,
         media: options.media,
         target: options.target,

package/out/cli/pack-loader.js

@@ -42,6 +42,7 @@ exports.loadAgentPack = loadAgentPack;
 exports.getDefaultConfig = getDefaultConfig;
 exports.getEnvDefaultModel = getEnvDefaultModel;
 exports.getApiConfig = getApiConfig;
+exports.hasCredentialForEngine = hasCredentialForEngine;
 exports.getFileAccess = getFileAccess;
 /**
  * Agent Pack Loader
@@ -330,6 +331,14 @@ function validateManifest(manifest, sourcePath) {
     if (manifest.spec?.cheapModel !== undefined && typeof manifest.spec.cheapModel !== 'string') {
         errors.push('Invalid spec.cheapModel: must be a string when provided');
     }
+    if (manifest.spec?.dataPlane !== undefined) {
+        if (typeof manifest.spec.dataPlane !== 'object' || !manifest.spec.dataPlane.connector?.trim()) {
+            errors.push('Invalid spec.dataPlane: requires a `connector` path (stdio MCP module run broker-side)');
+        }
+        if (manifest.spec.dataPlane?.provider !== undefined && typeof manifest.spec.dataPlane.provider !== 'string') {
+            errors.push('Invalid spec.dataPlane.provider: must be a string when provided');
+        }
+    }
     if (errors.length > 0) {
         throw new Error(`Invalid agent manifest at ${sourcePath}:\n  - ${errors.join('\n  - ')}`);
     }
@@ -354,20 +363,46 @@ function getEnvDefaultModel() {
 }
 /**
  * Get API configuration from environment.
+ *
+ * Returns the credentials keyed by destination (litellm / openai / anthropic) rather than a
+ * single collapsed key. The engine selects the one matching the endpoint it dials — see
+ * resolveApiRouting — so a codex deployment can no longer send an Anthropic key to OpenAI.
  */
 function getApiConfig() {
     const litellmApiKey = getEnvVar('AGENTHIPPO_LITELLM_API_KEY', 'AGENTIDE_LITELLM_API_KEY');
     const litellmBaseUrl = getEnvVar('AGENTHIPPO_LITELLM_BASE_URL', 'AGENTIDE_LITELLM_BASE_URL');
     const anthropicApiKey = process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_API_KEY;
     const openaiApiKey = process.env.OPENAI_API_KEY;
-    const apiKey = litellmApiKey || anthropicApiKey || openaiApiKey;
     const useLiteLLM = Boolean(litellmApiKey && litellmBaseUrl);
     return {
-        apiKey,
+        // Kept only for the "is any credential present at all?" boot check; routing never uses it.
+        apiKey: litellmApiKey || anthropicApiKey || openaiApiKey,
         baseUrl: litellmBaseUrl,
         useLiteLLM,
+        litellmApiKey,
+        openaiApiKey,
+        anthropicApiKey,
     };
 }
+/**
+ * Does the environment carry a usable credential for `engine`? Engine-aware so a codex
+ * deployment with only an Anthropic key (or vice-versa) fails loudly at boot instead of
+ * 401-ing at the first model call. A configured LiteLLM proxy satisfies every engine.
+ */
+function hasCredentialForEngine(engine, cfg = getApiConfig()) {
+    if (cfg.useLiteLLM) {
+        return true;
+    }
+    const e = engine.trim().toLowerCase();
+    if (e === 'claude') {
+        return Boolean(cfg.anthropicApiKey);
+    }
+    if (e === 'codex') {
+        return Boolean(cfg.openaiApiKey);
+    }
+    // Custom engines can authenticate via their own manifest-declared env var — don't gate them here.
+    return true;
+}
 /**
  * Get file access mode from pack manifest.
  */

package/out/cli/runtime.js

@@ -315,9 +315,16 @@ function buildCliEnvPatch(args) {
             chatSessionId: args.chatSessionId,
         }),
     };
-    const gatewayToken = readOpenClawGatewayToken(args.baseEnv);
-    if (gatewayToken) {
-        env[exports.OPENCLAW_GATEWAY_TOKEN_ENV] = gatewayToken;
+    // When serve runs the egress broker (secure-obo-design §7.6), the gateway token must NOT
+    // reach the agent's trust domain: the broker holds it, the agent presents only the turn
+    // nonce. AGENTHIPPO_EGRESS_URL in the process env is that signal — with it set, never bake
+    // the token into a child env (this closes §7.4 gap 1 for custom engines; codex/claude are
+    // covered by serve stripping the token from its own process.env).
+    if (!process.env.AGENTHIPPO_EGRESS_URL?.trim()) {
+        const gatewayToken = readOpenClawGatewayToken(args.baseEnv);
+        if (gatewayToken) {
+            env[exports.OPENCLAW_GATEWAY_TOKEN_ENV] = gatewayToken;
+        }
     }
     // Claude SDK refuses nested sessions when CLAUDECODE is present.
     // Force-unset in child runtime for CLI ask/chat/serve subprocesses.

package/out/cli/serve-hardening.js

@@ -36,13 +36,16 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TurnGate = exports.TURN_GATE_BUSY_MESSAGE = exports.TURN_GATE_RETRY_AFTER_SECONDS = exports.TURN_QUEUE_ENV = exports.MAX_CONCURRENT_TURNS_ENV = exports.TurnLimiter = exports.IDENTITY_HEADER_ENV = exports.RateLimiter = exports.XFF_TRUSTED_HOPS_ENV = exports.CONTAINER_SERVE_HOST = exports.SERVE_HOST_ENV = exports.DEFAULT_BIND_HOST = exports.DEFAULT_MAX_BODY_BYTES = void 0;
+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.IDENTITY_HEADER_ENV = exports.RateLimiter = exports.XFF_TRUSTED_HOPS_ENV = exports.CONTAINER_SERVE_HOST = exports.SERVE_HOST_ENV = exports.DEFAULT_BIND_HOST = exports.DEFAULT_MAX_BODY_BYTES = void 0;
 exports.resolveStateDir = resolveStateDir;
+exports.resolveAnalyticsSessionsDir = resolveAnalyticsSessionsDir;
 exports.resolveBindHost = resolveBindHost;
 exports.clientIp = clientIp;
 exports.resolveUserId = resolveUserId;
 exports.resolveDataToken = resolveDataToken;
 exports.peerToUserId = peerToUserId;
+exports.userNamespaceHash = userNamespaceHash;
+exports.resolveServeSessionKey = resolveServeSessionKey;
 exports.corsHeaders = corsHeaders;
 exports.createTurnGateFromEnv = createTurnGateFromEnv;
 exports.createRejectionWarner = createRejectionWarner;
@@ -60,6 +63,8 @@ exports.readBodyWithCap = readBodyWithCap;
  */
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const paths_1 = require("../utils/paths");
 /** 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;
 /**
@@ -82,6 +87,26 @@ function resolveStateDir(stateDirOpt, env = process.env) {
     }
     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');
+}
 /** Loopback default — safe everywhere a human runs `serve` locally. */
 exports.DEFAULT_BIND_HOST = '127.0.0.1';
 /** Env var for the listen address (used by generated deploy Dockerfiles). */
@@ -275,6 +300,36 @@ function peerToUserId(peer) {
     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) and a request carries a session_id but no verified user,
+ * reject — never let an unauthenticated caller name a session. Unpinned deployments
+ * (local dev, no identity boundary at all) keep today's raw-key behavior.
+ */
+function resolveServeSessionKey(sessionId, userId, env = process.env) {
+    const sid = sessionId?.trim();
+    const uid = userId?.trim();
+    if (uid) {
+        return { sessionKey: `u${userNamespaceHash(uid)}--${sid || 'default'}` };
+    }
+    if (sid && env[exports.IDENTITY_HEADER_ENV]?.trim()) {
+        return { sessionKey: '', rejected: exports.SESSION_WITHOUT_USER_REASON };
+    }
+    return { sessionKey: sid || 'anon-unknown' };
+}
 /** Build CORS headers. Serve is always behind a proxy; CORS is wide-open here. */
 function corsHeaders() {
     return {
@@ -320,6 +375,10 @@ exports.TURN_QUEUE_ENV = 'AGENTHIPPO_TURN_QUEUE';
 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).
  *

package/out/cli/state-sync.js

@@ -216,17 +216,20 @@ async function pathExists(p) {
         return false;
     }
 }
-async function copyDirIfExists(src, dest) {
-    if (!(await pathExists(src))) {
-        return;
-    }
-    await fsp.mkdir(dest, { recursive: true });
-    await fsp.cp(src, dest, { recursive: true, force: true });
-}
 /**
- * Build a local staging tree for session S:
- *   provider-sessions/<shards for S>
- *   agents/            (replica snapshot — sticky-by-user keeps this scoped)
+ * Build a local staging tree for session S: provider-sessions/<shards for S> only.
+ *
+ * `<stateDir>/agents/<agentId>/{claude,codex}` (the SDK's own on-disk session/config
+ * cache — see agentpack/paths.ts) is deliberately NOT included here. That directory is
+ * shared by every session/user of the same pack on this replica, keyed only by agentId —
+ * never session-scoped. Treating it as part of one session's push/restore let one
+ * session's stale snapshot force-overwrite the live SDK cache for every other
+ * concurrently active session on the replica (fs.cp force:true in the old
+ * mergeSessionStagingIntoState). It's local-disk-only now, same as before object-store
+ * sync existed: it lives and dies with its replica. A resume target missing after a
+ * replica change already falls back to a fresh SDK session — the same path every
+ * session's true first turn on any replica already takes — so this doesn't introduce a
+ * new failure mode, it just stops the wrong-session-data clobber.
  */
 async function stageSessionPushDir(stateDir, sessionId, stagingDir) {
     await fsp.rm(stagingDir, { recursive: true, force: true });
@@ -239,11 +242,10 @@ async function stageSessionPushDir(stateDir, sessionId, stagingDir) {
             await fsp.copyFile(path.join(stateDir, 'provider-sessions', name), path.join(psDest, name));
         }
     }
-    await copyDirIfExists(path.join(stateDir, 'agents'), path.join(stagingDir, 'agents'));
-    const hasAgents = await pathExists(path.join(stagingDir, 'agents'));
-    return shards.length > 0 || hasAgents;
+    return shards.length > 0;
 }
-/** Merge a restored staging tree back into stateDir. */
+/** Merge a restored staging tree back into stateDir (provider-session shards only — see
+ *  stageSessionPushDir for why the SDK config cache is intentionally excluded). */
 async function mergeSessionStagingIntoState(stagingDir, stateDir) {
     const psSrc = path.join(stagingDir, 'provider-sessions');
     if (await pathExists(psSrc)) {
@@ -256,7 +258,6 @@ async function mergeSessionStagingIntoState(stagingDir, stateDir) {
             await fsp.copyFile(path.join(psSrc, name), path.join(psDest, name));
         }
     }
-    await copyDirIfExists(path.join(stagingDir, 'agents'), path.join(stateDir, 'agents'));
 }
 /** Download state from the bucket into stateDir on boot. An empty bucket is a no-op. */
 async function restoreState(cfg, stateDir, log) {