@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.11

package/out/cli/deploy/layers/identity.js

@@ -7,28 +7,112 @@ exports.EDGE_AGENT_PORT = void 0;
 exports.renderIdentityLayer = renderIdentityLayer;
 exports.renderSidecarEdgeCaddyfile = renderSidecarEdgeCaddyfile;
 exports.renderSidecarFedCaddyfile = renderSidecarFedCaddyfile;
+/**
+ * Proof that `X-Auth-Request-Email` was set by THIS Caddy and not by a client.
+ *
+ * The broker now 401s an `X-Auth-Request-Email` that arrives without a matching
+ * `x-agenthippo-proxy-secret` (constant-time compared), because the header is otherwise a bearer
+ * assertion of identity that anything able to reach the broker's port could make. Only the routes
+ * that actually forward a verified email upstream carry it — adding it elsewhere would spread the
+ * secret across hops that have no use for it.
+ *
+ * `{env.…}` rather than `{$…}`: a runtime placeholder, so the secret is never baked into the
+ * rendered config on disk. Unset ⇒ empty ⇒ the broker refuses, which is the intended direction.
+ */
+const BROKER_PROXY_SECRET_LINES = [
+    '      # Proves this hop is the trusted proxy — the broker 401s X-Auth-Request-Email without it.',
+    '      header_up x-agenthippo-proxy-secret {env.AGENTHIPPO_AUTH_PROXY_SECRET}',
+];
 function renderIdentityLayer(opts) {
     const { mode, authBrokerAddr, healthProxy, agentProxy } = opts;
     const oauth2ProxyAddr = opts.oauth2ProxyAddr ?? '';
     const catchallBody = opts.catchallBody ?? agentProxy;
+    const turn = opts.turnRegistration;
+    // The turn-registration hop, inserted AFTER the identity forward_auth (which sets
+    // X-Agent-User — the user the sidecar mints the nonce for). Only POST chat turns match.
+    const turnHop = turn
+        ? [
+            '      # Turn registration — after identity: X-Agent-User (set above) names the user the',
+            '      # sidecar mints the nonce for. Only POST chat turns match; others pass through.',
+            '      # X-Agent-User-Assertion (also set above) rides along as the turn\'s inboundToken:',
+            '      # without it `passthrough` fails closed on every call and an RFC 8693 `exchange`',
+            '      # provider has no subject_token. See PLAN/agent-identity.md §8.5 G1.',
+            `      forward_auth @turnStart ${turn.connectorAddr} {`,
+            '        uri /edge/turn',
+            '        copy_headers X-Agent-Turn-Nonce',
+            `        header_up Authorization "Bearer {$${turn.tokenEnvVar}}"`,
+            '      }',
+        ]
+        : [];
+    // NOTE: two forward_auth in one handle block do NOT run in source order — Caddy sorts by
+    // its directive table, so the turn-registration hop could fire before identity is
+    // established (the connector then gets no X-Agent-User → 400). Wrapping the sequence in
+    // `route {}` forces source order: identity first (unauth short-circuits), then turn
+    // registration, then proxy.
+    // Re-indent wrapped directives one level so the generated file stays readable — operators
+    // copy these snippets by hand onto the IdP host.
+    const indent = (lines) => lines.map((l) => (l.trim() ? `  ${l}` : l));
+    const gated = (identityGate, body) => turn
+        ? ['    route {', ...indent(identityGate), ...turnHop, ...indent(body), '    }']
+        : [...identityGate, ...body];
     const lines = [];
+    if (turn) {
+        lines.push('  # Hygiene: never let a client-supplied nonce header through (copy_headers overwrites it', '  # on chat paths anyway, and a forged nonce fails closed at the gateway — belt-and-braces).', '  request_header -X-Agent-Turn-Nonce', '  # Same for the user assertion: it is set from the verified /api/ide/me response below,', '  # never from the client. A forged one would become the turn\'s inboundToken.', '  request_header -X-Agent-User-Assertion');
+    }
     if (mode === 'self-issued') {
-        lines.push('  # IDE PKCE sign-in: broker requires X-Auth-Request-Email from oauth2-proxy. Must come', '  # before the generic /oauth/* handle so authorize is gated (not dumped straight to broker).', '  handle /oauth/authorize {', `    forward_auth ${oauth2ProxyAddr} {`, '      uri /oauth2/auth', '      copy_headers X-Auth-Request-Email', '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '      @unauth status 401', '      handle_response @unauth {', '        redir * "/oauth2/sign_in?rd={http.request.uri}"', '      }', '    }', `    reverse_proxy ${authBrokerAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '    }', '  }', '  # Federated SSO (A′): browsers from other subdomains land here to stamp the shared cookie.', '  # Same oauth2-proxy gate as authorize; must precede the generic /oauth/* handle.', '  handle /oauth/browser-login {', `    forward_auth ${oauth2ProxyAddr} {`, '      uri /oauth2/auth', '      copy_headers X-Auth-Request-Email', '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '      @unauth status 401', '      handle_response @unauth {', '        redir * "/oauth2/sign_in?rd={http.request.uri}"', '      }', '    }', `    reverse_proxy ${authBrokerAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '    }', '  }', '  # Auth-broker: token exchange + other /oauth/* routes that must stay ungated.', '  handle /oauth/* {', `    reverse_proxy ${authBrokerAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '    }', '  }');
+        lines.push('  # IDE PKCE sign-in: broker requires X-Auth-Request-Email from oauth2-proxy. Must come', '  # before the generic /oauth/* handle so authorize is gated (not dumped straight to broker).', '  handle /oauth/authorize {', `    forward_auth ${oauth2ProxyAddr} {`, '      uri /oauth2/auth', '      copy_headers X-Auth-Request-Email', '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '      @unauth status 401', '      handle_response @unauth {', '        redir * "/oauth2/sign_in?rd={http.request.uri}"', '      }', '    }', `    reverse_proxy ${authBrokerAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', ...BROKER_PROXY_SECRET_LINES, '    }', '  }', '  # Federated SSO (A′): browsers from other subdomains land here to stamp the shared cookie.', '  # Same oauth2-proxy gate as authorize; must precede the generic /oauth/* handle.', '  handle /oauth/browser-login {', `    forward_auth ${oauth2ProxyAddr} {`, '      uri /oauth2/auth', '      copy_headers X-Auth-Request-Email', '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '      @unauth status 401', '      handle_response @unauth {', '        redir * "/oauth2/sign_in?rd={http.request.uri}"', '      }', '    }', `    reverse_proxy ${authBrokerAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', ...BROKER_PROXY_SECRET_LINES, '    }', '  }', '  # Auth-broker: token exchange + other /oauth/* routes that must stay ungated.', '  handle /oauth/* {', `    reverse_proxy ${authBrokerAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '    }', '  }');
     }
     lines.push('  handle /api/ide/* {', `    reverse_proxy ${authBrokerAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '    }', '  }');
     if (mode === 'self-issued') {
         lines.push('  # oauth2-proxy: Google SSO callback + sign-in.', '  handle /oauth2/* {', `    reverse_proxy ${oauth2ProxyAddr} {`, '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '    }', '  }');
     }
-    lines.push('  @health path /health /ready', '  handle @health {', ...healthProxy, '  }', '  # API clients (IDE) with a Bearer token: validate via auth-broker, copy identity header.', '  @apiWithAuth {', '    path /v1/*', '    header Authorization *', '  }', '  handle @apiWithAuth {', `    forward_auth ${authBrokerAddr} {`, '      uri /api/ide/me', '      copy_headers X-Agent-User', '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '      @unauth status 401', '      handle_response @unauth {', '        respond "Unauthorized" 401', '      }', '    }', ...agentProxy, '  }');
+    lines.push('  @health path /health /ready', '  handle @health {', ...healthProxy, '  }');
+    if (turn) {
+        lines.push('  # Chat-turn matcher for edge turn registration (P1 fix): only POST chat turns register.', '  @turnStart {', '    method POST', '    path /v1/chat /v1/chat/stream', '  }');
+    }
+    lines.push('  # API clients (IDE) with a Bearer token: validate via auth-broker, copy identity header.', '  @apiWithAuth {', '    path /v1/*', '    header Authorization *', '  }', '  handle @apiWithAuth {', ...gated([
+        `    forward_auth ${authBrokerAddr} {`,
+        '      uri /api/ide/me',
+        `      copy_headers X-Agent-User${turn ? ' X-Agent-User-Assertion' : ''}`,
+        '      header_up X-Forwarded-Proto https',
+        '      header_up X-Forwarded-Host {http.request.host}',
+        '      @unauth status 401',
+        '      handle_response @unauth {',
+        '        respond "Unauthorized" 401',
+        '      }',
+        '    }',
+    ], agentProxy), '  }');
     if (mode === 'self-issued') {
-        lines.push('  # Browser clients: SSO via oauth2-proxy, identity injected as X-Agent-User.', '  handle {', `    forward_auth ${oauth2ProxyAddr} {`, '      uri /oauth2/auth', '      copy_headers X-Auth-Request-Email>X-Agent-User', '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '      @unauth status 401', '      handle_response @unauth {', '        redir * "/oauth2/sign_in?rd={http.request.uri}"', '      }', '    }', ...catchallBody, '  }');
+        lines.push('  # Browser clients: SSO via oauth2-proxy, identity injected as X-Agent-User.', '  handle {', ...gated([
+            `    forward_auth ${oauth2ProxyAddr} {`,
+            '      uri /oauth2/auth',
+            '      copy_headers X-Auth-Request-Email>X-Agent-User',
+            '      header_up X-Forwarded-Proto https',
+            '      header_up X-Forwarded-Host {http.request.host}',
+            '      @unauth status 401',
+            '      handle_response @unauth {',
+            '        redir * "/oauth2/sign_in?rd={http.request.uri}"',
+            '      }',
+            '    }',
+        ], catchallBody), '  }');
     }
     else {
         const idp = opts.idpUrl?.trim() || '';
         const loginRedirect = idp
             ? `        redir * "${idp}/oauth/browser-login?return_to=https://{http.request.host}{http.request.uri}" 302`
             : '        respond "Unauthorized" 401';
-        lines.push('  # Browser clients: the shared .agenthippo.ai cookie is verified by auth-broker. No cookie', '  # → redirect to the central IdP to log in (it stamps the cookie), then return.', '  handle {', `    forward_auth ${authBrokerAddr} {`, '      uri /api/ide/me', '      copy_headers X-Agent-User', '      header_up X-Forwarded-Proto https', '      header_up X-Forwarded-Host {http.request.host}', '      @unauth status 401', '      handle_response @unauth {', loginRedirect, '      }', '    }', ...catchallBody, '  }');
+        lines.push('  # Browser clients: the shared .agenthippo.ai cookie is verified by auth-broker. No cookie', '  # → redirect to the central IdP to log in (it stamps the cookie), then return.', '  handle {', ...gated([
+            `    forward_auth ${authBrokerAddr} {`,
+            '      uri /api/ide/me',
+            '      copy_headers X-Agent-User',
+            '      header_up X-Forwarded-Proto https',
+            '      header_up X-Forwarded-Host {http.request.host}',
+            '      @unauth status 401',
+            '      handle_response @unauth {',
+            loginRedirect,
+            '      }',
+            '    }',
+        ], catchallBody), '  }');
     }
     return lines;
 }

package/out/cli/deploy-init.js

@@ -36,8 +36,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENTHIPPO_CLI_NPM_VERSION_FALLBACK = exports.AGENTHIPPO_CLI_NPM_PACKAGE = exports.DEPLOY_PUBLIC_HOSTNAME = exports.DEFAULT_DEPLOY_PUBLIC_HOSTNAME = exports.DEPLOY_TARGETS = void 0;
+exports.AGENTHIPPO_CLI_NPM_VERSION_FALLBACK = exports.AGENTHIPPO_CLI_NPM_PACKAGE = exports.DEPLOY_PUBLIC_HOSTNAME = exports.DEFAULT_DEPLOY_PUBLIC_HOSTNAME = exports.CLAUDE_CODE_NPM_VERSION = exports.AGENTHIPPO_IMAGE_TAG = exports.AGENTHIPPO_IMAGE_REGISTRY = exports.DEPLOY_TARGETS = void 0;
 exports.isDeployTarget = isDeployTarget;
+exports.agenthippoImage = agenthippoImage;
 exports.defaultRuntimeImage = defaultRuntimeImage;
 exports.packAttributionBody = packAttributionBody;
 exports.packAttributionComment = packAttributionComment;
@@ -50,6 +51,7 @@ exports.renderEnvExample = renderEnvExample;
 exports.renderAuthEnvExample = renderAuthEnvExample;
 exports.renderAuthBrokerDockerfile = renderAuthBrokerDockerfile;
 exports.isSecretLikeBasename = isSecretLikeBasename;
+exports.dataPlaneTokenEnvVar = dataPlaneTokenEnvVar;
 exports.renderTarget = renderTarget;
 /**
  * `agenthippo deploy init` — generator for platform-native deploy artifacts
@@ -75,11 +77,40 @@ exports.DEPLOY_TARGETS = ['vm', 'compose', 'cloudrun', 'databricks-app', 'spcs',
 function isDeployTarget(value) {
     return exports.DEPLOY_TARGETS.includes(value);
 }
+/** GHCR namespace for every AgentHippo-published image. Canonical — `agenthippoai`,
+ *  matching what scripts/release/publish-runtime-image.sh actually pushes to.
+ *  (`ghcr.io/agenthippo/` — no trailing "ai" — is a dead namespace; do not reintroduce it.) */
+exports.AGENTHIPPO_IMAGE_REGISTRY = 'ghcr.io/agenthippoai';
+/**
+ * The ONE dated tag every generated artifact pins to.
+ *
+ * Generated customer artifacts must never say `:latest`: a floating tag silently
+ * re-points a customer's deployment at a different image, which is exactly what the
+ * dated-tag policy in scripts/release/publish-runtime-image.sh exists to prevent.
+ *
+ * MUST match the `--version` used by scripts/release/publish-runtime-image.sh for the
+ * currently promoted release (scheme: `YYYY.MM` or `YYYY.MM.DD` — see
+ * scripts/release/README.md § Versioning). Bump here and in the publish run together.
+ */
+exports.AGENTHIPPO_IMAGE_TAG = '2026.07';
+/**
+ * Claude Code CLI version pinned into generated customer artifacts.
+ *
+ * `"latest"` here meant every customer install resolved a different version, so two
+ * deploys of the same pack were not the same software. Keep this equal to the
+ * `CLAUDE_CODE_VERSION` build ARG in extensions/agentide/scripts/Dockerfile.runtime,
+ * so the source-based (Databricks) path and the container path ship the same engine.
+ */
+exports.CLAUDE_CODE_NPM_VERSION = '2.1.220';
+/** `ghcr.io/agenthippoai/<name>:<dated tag>` — the only way to name a published image. */
+function agenthippoImage(name, variant) {
+    return `${exports.AGENTHIPPO_IMAGE_REGISTRY}/${name}:${exports.AGENTHIPPO_IMAGE_TAG}${variant ? `-${variant}` : ''}`;
+}
 /** Default runtime image for a pack engine (cursor needs the /engines layer). */
 function defaultRuntimeImage(engine) {
     return engine.trim().toLowerCase() === 'cursor'
-        ? 'ghcr.io/agenthippoai/runtime:latest-cursor'
-        : 'ghcr.io/agenthippoai/runtime:latest';
+        ? agenthippoImage('runtime', 'cursor')
+        : agenthippoImage('runtime');
 }
 /** Provenance line for generated deploy artifacts (pack-standard WS2). */
 function packAttributionBody(ctx) {
@@ -285,14 +316,15 @@ function renderAuthEnvExample(opts) {
             `AGENTHIPPO_AUTH_IDP_URL=${idp}   # where browsers are sent to log in`,
             'AGENTHIPPO_AUTH_COOKIE_NAME=ah_token',
             '',
-            '# Team bootstrap (store + LiteLLM routing) — same as the IdP if you want parity.',
+            '# Team bootstrap (store + gateway routing) — same as the IdP if you want parity.',
             'AGENTHIPPO_TEAM_ID=team_default',
             'AGENTHIPPO_TEAM_NAME=Default Team',
             'AGENTHIPPO_TEAM_STORE_REPO=agenthippoai/agenthippo-store',
             'AGENTHIPPO_TEAM_STORE_INDEX_URL=https://agenthippoai.github.io/agenthippo-store',
             'AGENTHIPPO_TEAM_GITHUB_ORG=agenthippoai',
-            'AGENTHIPPO_TEAM_LITELLM_BASE_URL=http://127.0.0.1:4000',
-            'AGENTHIPPO_TEAM_LITELLM_API_KEY=',
+            '# An agenthippo-gateway deployment (JWT lane) — NOT bare LiteLLM. No key: the account',
+            '# JWT is the routing credential.',
+            'AGENTHIPPO_TEAM_GATEWAY_URL=https://gateway.agenthippo.ai/v1',
             '',
             '# No OAUTH2_PROXY_* here — this agent does not talk to Google. The one oauth2-proxy +',
             '# one Google OAuth client live only at the IdP.',
@@ -328,8 +360,9 @@ function renderAuthEnvExample(opts) {
         'AGENTHIPPO_TEAM_STORE_REPO=agenthippoai/agenthippo-store',
         'AGENTHIPPO_TEAM_STORE_INDEX_URL=https://agenthippoai.github.io/agenthippo-store',
         'AGENTHIPPO_TEAM_GITHUB_ORG=agenthippoai',
-        'AGENTHIPPO_TEAM_LITELLM_BASE_URL=http://127.0.0.1:4000',
-        'AGENTHIPPO_TEAM_LITELLM_API_KEY=',
+        '# An agenthippo-gateway deployment (JWT lane) — NOT bare LiteLLM. No key: the account',
+        '# JWT is the routing credential.',
+        'AGENTHIPPO_TEAM_GATEWAY_URL=https://gateway.agenthippo.ai/v1',
     ].join('\n') + '\n';
 }
 /** Auth broker sidecar for IDE sign-in + team bootstrap API. */
@@ -337,7 +370,7 @@ function renderAuthBrokerDockerfile() {
     return [
         '# Auth broker for IDE sign-in + team bootstrap API.',
         '# Build context = pack root: docker build -f deploy/Dockerfile.auth-broker -t <pack>-auth-broker:local .',
-        'FROM ghcr.io/agenthippoai/runtime:latest',
+        `FROM ${agenthippoImage('runtime')}`,
         'ENV AGENTHIPPO_AUTH_PORT=9780',
         'ENV AGENTHIPPO_AUTH_DATA_DIR=/data',
         'EXPOSE 9780',
@@ -392,6 +425,10 @@ function renderDockerignore() {
         '# Secrets anywhere in the pack (defensive; deploy/ secrets are also covered below).',
         '# Keep in sync with isSecretLikeBasename() above.',
         '**/.env',
+        // `**/.env` alone does NOT match `.env.auth` / `.env.local` / `.env.production`.
+        // `.env.auth` carries AGENTHIPPO_AUTH_JWT_SECRET and OAUTH2_PROXY_* — baking it
+        // into a published layer leaks fleet-wide token-forgery material.
+        '**/.env.*',
         '**/*credentials*',
         '**/*.pem',
         '**/*.key',
@@ -404,6 +441,9 @@ function renderDockerignore() {
         '**/id_dsa',
         '**/id_ecdsa',
         '**/id_ed25519',
+        '# …but *.example templates are safe and are what the README tells customers to copy.',
+        '!**/.env.example',
+        '!**/.env.*.example',
         '# deploy/ holds build/deploy artifacts + secrets; only deploy/www/ ships at runtime.',
         'deploy/*',
         '!deploy/www',
@@ -721,9 +761,16 @@ function renderEdgeTunnelUpScript(hostname) {
  * predictable container name) plus a Caddy route snippet for the operator to drop into the
  * IdP's `agents/` import directory (see enterprise-deploy/idp/Caddyfile + agents/README.md).
  */
+/** Env var (in the IdP/edge stack's env) holding the connector sidecar's register token —
+ *  matches the connector's own AGENTHIPPO_DATA_PLANE_TOKEN. Convention proven by the
+ *  dynamodb-analyst overlay: pack `dynamodb-analyst` → `DYNAMODB_ANALYST_DATA_PLANE_TOKEN`. */
+function dataPlaneTokenEnvVar(packName) {
+    return packName.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_DATA_PLANE_TOKEN';
+}
 function renderColocatedArtifacts(ctx) {
     const idp = (ctx.idpUrl || '').trim().replace(/\/+$/, '');
     const containerName = `${ctx.packName}-agent`;
+    const turnTokenEnvVar = dataPlaneTokenEnvVar(ctx.packName);
     const compose = [
         '# Colocated agent (PLAN/deploy.md §4 state 4) — no Caddy/oauth2-proxy/auth-broker of its',
         '# own. Joins the org IdP\'s docker network so its already-running Caddy can reach this',
@@ -768,6 +815,9 @@ function renderColocatedArtifacts(ctx) {
             idpUrl: idp,
             healthProxy: [`    reverse_proxy ${containerName}:${ctx.port}`],
             agentProxy: [`    reverse_proxy ${containerName}:${ctx.port}`],
+            ...(ctx.edgeTurnConnector
+                ? { turnRegistration: { connectorAddr: ctx.edgeTurnConnector, tokenEnvVar: turnTokenEnvVar } }
+                : {}),
         }),
         '}',
         '',
@@ -791,6 +841,16 @@ function renderColocatedArtifacts(ctx) {
             '',
             '# Wire the route into the IdP\'s Caddy (one-time per agent):',
             `cp deploy/agent-route.caddy <idp-host>:enterprise-deploy/idp/agents/${ctx.packName}.caddy`,
+            ...(ctx.edgeTurnConnector
+                ? [
+                    '',
+                    '# EDGE turn registration (P1 fix): the route registers each chat turn with the connector',
+                    `# sidecar (${ctx.edgeTurnConnector}). Set the register token in the IdP stack's env —`,
+                    `# same value as the connector's AGENTHIPPO_DATA_PLANE_TOKEN — before reloading:`,
+                    `#   echo "${turnTokenEnvVar}=<token>" >> enterprise-deploy/idp/.env`,
+                    '# The agent container never holds this token (that is the point).',
+                ]
+                : []),
             'docker compose -f enterprise-deploy/idp/docker-compose.yml exec caddy \\',
             '  caddy reload --config /etc/caddy/Caddyfile',
             '```',
@@ -991,7 +1051,7 @@ function composeArtifacts(ctx) {
             '  # OPENCLAW_GATEWAY_TOKEN (or a paired device) to connect. Set it in .env.',
             '  openclaw-gateway:',
             '    profiles: ["channels"]',
-            '    image: ghcr.io/agenthippoai/openclaw-gateway:2026.06',
+            `    image: ${agenthippoImage('openclaw-gateway')}`,
             '    env_file:',
             '      - path: .env',
             '        required: false',
@@ -1022,13 +1082,18 @@ function composeArtifacts(ctx) {
         '  # (build: docker build -f extensions/agentide/scripts/Dockerfile.litellm -t this-tag .)',
         '  litellm:',
         '    profiles: ["gateway"]',
-        '    image: ghcr.io/agenthippoai/litellm-gateway:2026.06',
+        `    image: ${agenthippoImage('agenthippo-litellm')}`,
         '    env_file:',
         '      - path: .env',
         '        required: false',
         '    environment:',
         '      OTEL_EXPORTER: otlp_http',
         '      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318',
+        '    # The image defaults to --host 127.0.0.1 (safe when someone runs it bare).',
+        '    # Here it must answer the agent container over the compose network, so bind',
+        '    # 0.0.0.0 — and keep `expose:` rather than `ports:` so it is never reachable',
+        '    # from the host. Requires general_settings.master_key in the baked config.',
+        '    command: ["--config", "/config/litellm.config.yaml", "--port", "4443", "--host", "0.0.0.0"]',
         '    expose: ["4443"]',
         '    depends_on: [otel-collector]',
         '',
@@ -1340,7 +1405,7 @@ function renderCloudrunSpotlightDeploy(ctx) {
         'PROJECT_ID="${PROJECT_ID:-$(gcloud config get-value project)}"',
         'REPO="${ARTIFACT_REPO:-agenthippo}"',
         'IMAGE="${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${SERVICE}:latest"',
-        'LITELLM_IMAGE="${LITELLM_IMAGE:-ghcr.io/agenthippoai/litellm-gateway:2026.07}"',
+        `LITELLM_IMAGE="\${LITELLM_IMAGE:-${agenthippoImage('agenthippo-litellm')}}"`,
         'STATE_BUCKET="${STATE_BUCKET:?set STATE_BUCKET=your-gcs-bucket (gcloud storage buckets create gs://...)}"',
         '# LITELLM_KEY = the proxy key the agent presents to LiteLLM (and LiteLLM master key).',
         'LITELLM_KEY="${LITELLM_KEY:?set LITELLM_KEY=<litellm proxy key>}"',
@@ -1351,8 +1416,8 @@ function renderCloudrunSpotlightDeploy(ctx) {
         '  || gcloud artifacts repositories create "$REPO" --repository-format=docker --location="$REGION"',
         'gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet',
         '',
-        '# Rewrite the runtime base to this project Artifact Registry (the ghcr.io/agenthippoai/runtime:latest',
-        '# tag was retired; AR has runtime:latest / :latest-cursor). No-op if the base already targets AR.',
+        '# Rewrite the runtime base to this project Artifact Registry. Customer artifacts pin a',
+        '# dated ghcr.io/agenthippoai/runtime tag; mirror that exact tag into AR. No-op if already AR.',
         'DF_TMP="$(mktemp)"',
         'sed "s|FROM ghcr.io/agenthippoai/runtime:|FROM ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/runtime:|" deploy/Dockerfile > "$DF_TMP"',
         'docker build --pull --platform linux/amd64 -f "$DF_TMP" -t "$IMAGE" .',
@@ -1527,7 +1592,7 @@ function renderCloudrunEdgeDeploy(ctx) {
         'PROJECT_ID="${PROJECT_ID:-$(gcloud config get-value project)}"',
         'REPO="${ARTIFACT_REPO:-agenthippo}"',
         'IMAGE="${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${SERVICE}:latest"',
-        'LITELLM_IMAGE="${LITELLM_IMAGE:-ghcr.io/agenthippoai/litellm-gateway:2026.07}"',
+        `LITELLM_IMAGE="\${LITELLM_IMAGE:-${agenthippoImage('agenthippo-litellm')}}"`,
         '# Public hostname (custom domain mapped to the service) + the Google Workspace domain allowed by SSO.',
         'PUBLIC_HOSTNAME="${PUBLIC_HOSTNAME:?set PUBLIC_HOSTNAME=your.edge.hostname (gcloud run domain-mappings create --service $SERVICE --domain ...)}"',
         'ALLOWED_DOMAINS="${ALLOWED_DOMAINS:?set ALLOWED_DOMAINS=yourworkspace.com (oauth2-proxy email domain + broker allowed domains)}"',
@@ -1550,8 +1615,8 @@ function renderCloudrunEdgeDeploy(ctx) {
         'gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet',
         '',
         '# One agent image serves both the agent and the auth-broker containers (CLI ships `auth-broker`).',
-        '# Rewrite the runtime base to this project Artifact Registry (the ghcr.io/agenthippoai/runtime:latest',
-        '# tag was retired; AR has runtime:latest / :latest-cursor). No-op if the base already targets AR.',
+        '# Rewrite the runtime base to this project Artifact Registry. Customer artifacts pin a',
+        '# dated ghcr.io/agenthippoai/runtime tag; mirror that exact tag into AR. No-op if already AR.',
         'DF_TMP="$(mktemp)"',
         'sed "s|FROM ghcr.io/agenthippoai/runtime:|FROM ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/runtime:|" deploy/Dockerfile > "$DF_TMP"',
         'docker build --pull --platform linux/amd64 -f "$DF_TMP" -t "$IMAGE" .',
@@ -1664,8 +1729,8 @@ function cloudrunArtifacts(ctx) {
         'gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet',
         '',
         '# Build from pack root; Dockerfile is deploy/Dockerfile (not pack root — gcloud --source . misses it).',
-        '# Rewrite the runtime base to this project Artifact Registry (the ghcr.io/agenthippoai/runtime:latest',
-        '# tag was retired; AR has runtime:latest / :latest-cursor). No-op if the base already targets AR.',
+        '# Rewrite the runtime base to this project Artifact Registry. Customer artifacts pin a',
+        '# dated ghcr.io/agenthippoai/runtime tag; mirror that exact tag into AR. No-op if already AR.',
         'DF_TMP="$(mktemp)"',
         'sed "s|FROM ghcr.io/agenthippoai/runtime:|FROM ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/runtime:|" deploy/Dockerfile > "$DF_TMP"',
         'docker build --pull --platform linux/amd64 -f "$DF_TMP" -t "$IMAGE" .',
@@ -1700,7 +1765,7 @@ function cloudrunArtifacts(ctx) {
             : '#  - No inbound channel (1a): scales to zero; state on the GCS volume survives the instance dying.',
         '#  - GCS-FUSE adds latency on session read/write vs local disk; fine for chat, watch for heavy I/O.',
         isCursor
-            ? '#  - Cursor engine: CURSOR_API_KEY secret + runtime:latest-cursor base (AGENTHIPPO_CUSTOM_ENGINES_DIR=/engines).'
+            ? `#  - Cursor engine: CURSOR_API_KEY secret + ${agenthippoImage('runtime', 'cursor')} base (AGENTHIPPO_CUSTOM_ENGINES_DIR=/engines).`
             : '#  - Vertex path = keyless Claude on your existing GCP entitlement; swap for ANTHROPIC_API_KEY if preferred.',
         '#  - First deploy without IAP org setup: ENABLE_IAP=0 bash deploy/cloudrun-deploy.sh',
         '',
@@ -2092,7 +2157,7 @@ function renderCloudrunFedDeploy(ctx) {
         'PROJECT_ID="${PROJECT_ID:-$(gcloud config get-value project)}"',
         'REPO="${ARTIFACT_REPO:-agenthippo}"',
         'IMAGE="${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${SERVICE}:latest"',
-        'LITELLM_IMAGE="${LITELLM_IMAGE:-ghcr.io/agenthippoai/litellm-gateway:2026.07}"',
+        `LITELLM_IMAGE="\${LITELLM_IMAGE:-${agenthippoImage('agenthippo-litellm')}}"`,
         '# Public hostname = a *.agenthippo.ai subdomain mapped to this service (one-time wildcard DNS).',
         'PUBLIC_HOSTNAME="${PUBLIC_HOSTNAME:?set PUBLIC_HOSTNAME=<subdomain>.agenthippo.ai}"',
         'ALLOWED_DOMAINS="${ALLOWED_DOMAINS:-agenthippo.ai}"',
@@ -2116,8 +2181,8 @@ function renderCloudrunFedDeploy(ctx) {
         'gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet',
         '',
         '# One agent image serves both the agent and the auth-broker containers (CLI ships `auth-broker`).',
-        '# Rewrite the runtime base to this project Artifact Registry (the ghcr.io/agenthippoai/runtime:latest',
-        '# tag was retired; AR has runtime:latest / :latest-cursor). No-op if the base already targets AR.',
+        '# Rewrite the runtime base to this project Artifact Registry. Customer artifacts pin a',
+        '# dated ghcr.io/agenthippoai/runtime tag; mirror that exact tag into AR. No-op if already AR.',
         'DF_TMP="$(mktemp)"',
         'sed "s|FROM ghcr.io/agenthippoai/runtime:|FROM ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/runtime:|" deploy/Dockerfile > "$DF_TMP"',
         'docker build --pull --platform linux/amd64 -f "$DF_TMP" -t "$IMAGE" .',
@@ -2229,7 +2294,7 @@ function databricksAppArtifacts(ctx) {
         private: true,
         dependencies: {
             [exports.AGENTHIPPO_CLI_NPM_PACKAGE]: resolveAgentHippoCliNpmVersion(),
-            '@anthropic-ai/claude-code': 'latest',
+            '@anthropic-ai/claude-code': exports.CLAUDE_CODE_NPM_VERSION,
         },
     }, null, 2) + '\n';
     const start = [

package/out/cli/deps.js

@@ -37,12 +37,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDepsDir = getDepsDir;
+exports.resolveFromOwnDeps = resolveFromOwnDeps;
 exports.areDepsInstalled = areDepsInstalled;
 exports.installDeps = installDeps;
 exports.isAutoInstallDisabled = isAutoInstallDisabled;
 exports.ensureDeps = ensureDeps;
 exports.getClaudeSdkCliPath = getClaudeSdkCliPath;
 exports.getCodexSdkBinaryPath = getCodexSdkBinaryPath;
+exports.installedEngineVersion = installedEngineVersion;
 /**
  * CLI Dependency Management
  *
@@ -50,6 +52,7 @@ exports.getCodexSdkBinaryPath = getCodexSdkBinaryPath;
  * This lets npm/bun handle platform-specific binaries automatically.
  */
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const utils_1 = require("./utils");
@@ -84,11 +87,60 @@ function resolveEngineDeps() {
 // Dependencies required for the engines (resolved once at startup).
 const ENGINE_DEPS = resolveEngineDeps();
 /**
- * Get the deps directory (next to the binary)
+ * Where engine SDKs are installed.
+ *
+ * Normally beside the binary — a self-contained install that survives `$HOME` changes. But
+ * `process.execPath` is the *interpreter* when the CLI runs as `node out/cli/index.js`, which
+ * on a locked-down host means `/usr/bin`, and the first run dies with
+ * `EACCES: mkdir '/usr/bin/.agenthippo-deps'` (observed on Amazon Linux, 2026-07-27). A
+ * runtime must not need write access to the system bin dir, so fall back to the agent home.
  */
 function getDepsDir() {
     const binaryDir = path.dirname(process.execPath);
-    return path.join(binaryDir, branding_1.AGENTIDE_DEPS_DIR_NAME);
+    const beside = path.join(binaryDir, branding_1.AGENTIDE_DEPS_DIR_NAME);
+    if (fs.existsSync(beside)) {
+        return beside;
+    }
+    try {
+        fs.accessSync(binaryDir, fs.constants.W_OK);
+        return beside;
+    }
+    catch {
+        // Not writable (system node, read-only image, non-root user): use the agent home.
+        return path.join(os.homedir(), branding_1.AGENTIDE_DIR_NAME, branding_1.AGENTIDE_DEPS_DIR_NAME);
+    }
+}
+/**
+ * Engine SDKs resolved from the CLI's OWN dependency tree.
+ *
+ * When the runtime ships as a node app (`node out/cli/index.js` beside a `node_modules/`) the
+ * SDKs are already installed as ordinary dependencies — there is nothing to fetch, and asking
+ * the user to set CLAUDE_CODE_PATH by hand for a dependency we declare ourselves is a
+ * papercut that costs a deployment. `require.resolve` finds them wherever the tree lives.
+ */
+function resolveFromOwnDeps(pkgName, relativeFile) {
+    // A node_modules walk, deliberately, rather than `require.resolve`. Neither SDK can be
+    // resolved by specifier: @anthropic-ai/claude-agent-sdk publishes an `exports` map that
+    // omits ./cli.js (deep resolve → ERR_PACKAGE_PATH_NOT_EXPORTED) and @openai/codex declares
+    // no main/exports at all, only a `bin` (bare resolve → MODULE_NOT_FOUND). Both were
+    // verified against the shipped versions on 2026-07-27. Walking for the file we actually
+    // want is immune to how a package chooses to advertise itself.
+    let dir = __dirname;
+    for (let hops = 0; hops < 8; hops++) {
+        const candidate = path.join(dir, 'node_modules', ...pkgName.split('/'), ...relativeFile.split('/'));
+        try {
+            if (fs.existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        catch { /* keep walking */ }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return undefined;
 }
 /**
  * Check if engine dependencies are installed
@@ -183,6 +235,14 @@ async function ensureDeps(verbose = false) {
     if (areDepsInstalled()) {
         return;
     }
+    // Already satisfied by our own dependency tree (node-app runtime): nothing to install, and
+    // attempting it would fail on a read-only or non-writable install dir for no benefit.
+    if (resolveFromOwnDeps('@anthropic-ai/claude-agent-sdk', 'cli.js') && resolveFromOwnDeps('@openai/codex', 'bin/codex.js')) {
+        if (verbose) {
+            console.error(`${utils_1.COLORS.dim}Engine SDKs resolved from the CLI's own node_modules — skipping install.${utils_1.COLORS.reset}`);
+        }
+        return;
+    }
     if (isAutoInstallDisabled()) {
         if (verbose) {
             console.error(`${utils_1.COLORS.dim}AGENTHIPPO_NO_AUTO_INSTALL set — skipping engine dependency install (expecting a self-contained image).${utils_1.COLORS.reset}`);
@@ -236,3 +296,47 @@ function getCodexPlatform() {
     }
     return undefined;
 }
+/**
+ * The engine version actually installed next to this binary.
+ *
+ * Reported on the lease poll so the console can answer "what is the fleet really running?" —
+ * pack version alone cannot explain a behaviour change that came from an engine upgrade, and the
+ * CLI is NOT engine-version agnostic (see AGENTIDE_CODEX_CONFIG_VERSION: config we write is only
+ * valid on codex >= 0.131, and getting it wrong silently cancels headless tool calls).
+ *
+ * Best effort by design: a deployment that vendors its engines elsewhere reports nothing rather
+ * than guessing, and the console shows a dash. Never throws — this is on the boot path.
+ *
+ * Expect nothing under a CONTAINER sandbox: there the engine runs inside the sandbox image, not
+ * beside serve, so serve genuinely does not know its version and the image digest is what
+ * identifies that build. Reporting serve's own (absent) copy would be a guess about someone
+ * else's filesystem. Process sandboxes and in-process runs share this binary's deps, so those
+ * report truthfully.
+ */
+function installedEngineVersion(engine) {
+    const pkg = engine === 'codex' ? path.join('@openai', 'codex')
+        : engine === 'claude' ? path.join('@anthropic-ai', 'claude-agent-sdk')
+            : undefined;
+    if (!pkg) {
+        return undefined;
+    }
+    const candidates = [
+        path.join(getDepsDir(), 'node_modules', pkg, 'package.json'),
+        // Runtime images install engines globally rather than beside the binary.
+        path.join('/usr/local/lib/node_modules', pkg, 'package.json'),
+        path.join('/usr/lib/node_modules', pkg, 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (!fs.existsSync(candidate)) {
+                continue;
+            }
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            if (parsed.version) {
+                return parsed.version;
+            }
+        }
+        catch { /* unreadable or malformed — try the next candidate */ }
+    }
+    return undefined;
+}

package/out/cli/idp-init.js

@@ -78,6 +78,18 @@ function renderIdpComposeYaml() {
         '    environment:',
         '      AGENTHIPPO_AUTH_PORT: "9780"',
         '      AGENTHIPPO_AUTH_DATA_DIR: /data',
+        '      # The broker now defaults to binding 127.0.0.1 and REFUSES a public bind unless told',
+        '      # otherwise. Here it must listen on the container interface, because Caddy reaches it',
+        '      # as `auth-broker:9780` over the compose network — a loopback bind makes it unreachable.',
+        '      # Safe: the port is `expose`d, never published to the host, so the only thing that can',
+        '      # dial it is another service on this network.',
+        '      AGENTHIPPO_AUTH_BIND: "0.0.0.0"',
+        '      AGENTHIPPO_AUTH_ALLOW_PUBLIC_BIND: "1"',
+        '      # Shared secret proving an X-Auth-Request-Email came from THIS Caddy. Without it the',
+        '      # broker treats that header as unverified and 401s the forward_auth-gated routes.',
+        '      # No default on purpose: compose FAILS to start rather than silently running with an',
+        '      # empty secret on both sides, which would accept every caller. Put it in ./.env.',
+        '      AGENTHIPPO_AUTH_PROXY_SECRET: "${AGENTHIPPO_AUTH_PROXY_SECRET:?set AGENTHIPPO_AUTH_PROXY_SECRET in .env (openssl rand -hex 32)}"',
         '      # 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).',
@@ -101,6 +113,11 @@ function renderIdpComposeYaml() {
         '    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"',
+        '    environment:',
+        '      # Caddy stamps this on the two broker hops that forward a verified X-Auth-Request-Email',
+        '      # (/oauth/authorize, /oauth/browser-login). Same value the broker checks; same fail-closed',
+        '      # rule — compose refuses to start rather than send an empty secret.',
+        '      AGENTHIPPO_AUTH_PROXY_SECRET: "${AGENTHIPPO_AUTH_PROXY_SECRET:?set AGENTHIPPO_AUTH_PROXY_SECRET in .env (openssl rand -hex 32)}"',
         '    volumes:',
         '      - ./Caddyfile:/etc/caddy/Caddyfile:ro',
         '      # Colocated agents (deploy init --colocate) drop a route snippet here — see Caddyfile.',
@@ -179,6 +196,15 @@ function renderIdpArtifacts(ctx) {
             '',
             `AGENTHIPPO_PUBLIC_HOSTNAME=${ctx.hostname}`,
             '',
+            '# REQUIRED. Shared secret between Caddy and auth-broker, proving that an',
+            '# X-Auth-Request-Email reached the broker through this Caddy rather than from a client',
+            '# that merely found the port. The broker 401s that header without a matching secret, and',
+            '# docker compose refuses to start if this is unset — an empty secret on both sides would',
+            '# accept everyone. It lives HERE (not .env.auth) because Caddy needs it too, and Caddy',
+            '# must not be handed the OAuth client secret or the JWT signing key.',
+            '#   openssl rand -hex 32',
+            'AGENTHIPPO_AUTH_PROXY_SECRET=',
+            '',
             '# 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',
@@ -276,8 +302,17 @@ function renderIdpArtifacts(ctx) {
             '```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',
+            '',
+            '# REQUIRED: the Caddy↔broker proxy secret. It must be visible to `docker compose`',
+            '# ITSELF (compose interpolates it into both services), so it goes in ./.env here —',
+            '# not only in ~/.agent-hippo/.env, which is read by containers but not by compose.',
+            'echo "AGENTHIPPO_AUTH_PROXY_SECRET=$(openssl rand -hex 32)" >> .env',
             '```',
             '',
+            'Without it `docker compose up` fails immediately with a message naming the variable. That',
+            'is deliberate: the broker refuses an `X-Auth-Request-Email` that arrives without a matching',
+            '`x-agenthippo-proxy-secret`, so an empty secret on both sides would accept every caller.',
+            '',
             '**Cloudflare Tunnel** (no public ports to manage yourself):',
             '',
             '```bash',