fix(agent-bff): resolve the environment id on demand, not at boot

packages/agent-bff/src/ai/ai-routes-middleware.ts

@@ -1,6 +1,7 @@
 import type AiProxyClient from './ai-proxy-client';
 import type { AiProxyResponse } from './ai-proxy-client';
 import type { BffAccessTokenPayload } from '../oauth/bff-token';
+import type { EnvironmentIdResolver } from '../oauth/environment-id';
 import type ForestServerClient from '../oauth/forest-server-client';
 import type { SessionStore } from '../oauth/session-store';
 import type { Logger } from '../ports/logger-port';
@@ -10,11 +11,13 @@ import { AiProxyTimeoutError } from './ai-proxy-client';
 import { requireRenderingId } from '../auth/auth-mode';
 import { unauthorized } from '../http/bff-http-error';
 import {
+  environmentUnresolved,
   oauthRequired,
   upstreamError,
   upstreamTimeout,
   upstreamUnreachable,
 } from '../http/bff-local-errors';
+import { environmentFailureLevel } from '../oauth/environment-fetch-error';
 import { OAuthRequestError } from '../oauth/oauth-error';
 import ensureFreshServerAccess from '../oauth/session-lifecycle';
 
@@ -28,7 +31,7 @@ export interface AiRoutesMiddlewareOptions {
   client: AiProxyClient;
   sessionStore: SessionStore;
   serverClient: ForestServerClient;
-  environmentId?: number;
+  resolveEnvironmentId?: EnvironmentIdResolver;
   logger: Logger;
 }
 
@@ -55,6 +58,32 @@ function describeFailure(error: unknown, depthLeft = MAX_CAUSE_DEPTH): string {
   return `${error.name}: ${clamp(error.message)}${tail}`;
 }
 
+/**
+ * Resolved outside the `try` that maps AI proxy failures: a Forest server refusing the environment
+ * read is not the AI proxy being unreachable, and telling the operator otherwise sends them
+ * debugging a component that was never contacted.
+ */
+async function resolveEnvironmentIdOrRefuse(
+  resolveEnvironmentId: EnvironmentIdResolver | undefined,
+  logger: Logger,
+): Promise<number | undefined> {
+  if (!resolveEnvironmentId) return undefined;
+
+  try {
+    return await resolveEnvironmentId();
+  } catch (error) {
+    logger(
+      environmentFailureLevel(error),
+      'AI query refused: the Forest environment id could not be resolved',
+      { cause: describeFailure(error) },
+    );
+
+    if (error instanceof Error && error.name === 'TimeoutError') throw upstreamTimeout();
+
+    throw environmentUnresolved();
+  }
+}
+
 async function resolveSessionAccessToken(
   principal: BffAccessTokenPayload,
   store: SessionStore,
@@ -104,7 +133,7 @@ export default function createAiRoutesMiddleware({
   client,
   sessionStore,
   serverClient,
-  environmentId,
+  resolveEnvironmentId,
   logger,
 }: AiRoutesMiddlewareOptions): Middleware {
   return async function aiRoutesMiddleware(ctx, next) {
@@ -124,6 +153,8 @@ export default function createAiRoutesMiddleware({
       logger,
     );
 
+    const environmentId = await resolveEnvironmentIdOrRefuse(resolveEnvironmentId, logger);
+
     let response: AiProxyResponse;
 
     try {

packages/agent-bff/src/build-bff.ts

@@ -1,4 +1,5 @@
 import type { BFFConfig } from './config/env-config';
+import type { EnvironmentIdResolver } from './oauth/environment-id';
 import type { SessionStore } from './oauth/session-store';
 import type { UnfoldSource } from './openapi/unfolded-document';
 import type { Logger } from './ports/logger-port';
@@ -30,6 +31,7 @@ import BODY_LIMIT, { AI_BODY_LIMIT } from './http/body-limit';
 import createErrorMiddleware from './http/error-middleware';
 import createHealthRoute from './http/health-route';
 import createVersionHeaderMiddleware from './http/version-header-middleware';
+import createEnvironmentIdResolver, { tolerateEnvironmentIdFailure } from './oauth/environment-id';
 import ForestServerClient from './oauth/forest-server-client';
 import createOAuthRoutes from './oauth/oauth-routes';
 import createInMemorySessionStore from './oauth/session-store';
@@ -134,11 +136,11 @@ interface OAuthSession {
 
 interface OAuthEdge {
   middlewares: Middleware[];
-  environmentId?: number;
+  resolveEnvironmentId?: EnvironmentIdResolver;
   session?: OAuthSession;
 }
 
-async function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): Promise<OAuthEdge> {
+function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): OAuthEdge {
   const oauthConfig = resolveOAuthConfig(config);
 
   if (!oauthConfig) {
@@ -151,7 +153,7 @@ async function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): Promise
     oauthConfig;
 
   const serverClient = new ForestServerClient({ forestServerUrl, envSecret: forestEnvSecret });
-  const environmentId = await serverClient.fetchEnvironmentId();
+  const resolveEnvironmentId = createEnvironmentIdResolver(serverClient);
 
   const sessionStore = createInMemorySessionStore({
     cipher: createTokenCipher(tokenEncryptionKey),
@@ -164,13 +166,13 @@ async function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): Promise
     sessionStore,
     forestAppUrl,
     authSecret: forestAuthSecret,
-    environmentId,
+    resolveEnvironmentId,
     logger,
   });
 
   return {
     middlewares: [oauthRoutes],
-    environmentId,
+    resolveEnvironmentId,
     session: { store: sessionStore, serverClient, forestServerUrl },
   };
 }
@@ -318,7 +320,7 @@ function buildAgentRouteMiddlewares(
 }
 
 function buildAiMiddlewares(config: BFFConfig, oauth: OAuthEdge, logger: Logger): Middleware[] {
-  const { session, environmentId } = oauth;
+  const { session, resolveEnvironmentId } = oauth;
 
   if (!session) {
     logger('Warn', 'AI query route disabled: the deployment carries no OAuth session');
@@ -336,7 +338,7 @@ function buildAiMiddlewares(config: BFFConfig, oauth: OAuthEdge, logger: Logger)
       client,
       sessionStore: session.store,
       serverClient: session.serverClient,
-      environmentId,
+      resolveEnvironmentId,
       logger,
     }),
   ];
@@ -349,7 +351,6 @@ function buildAgentMiddlewares(
   aiMiddlewares: Middleware[],
 ): Middleware[] {
   const { forestAuthSecret, defaultTimezone } = config;
-  const { environmentId } = oauth;
 
   if (!forestAuthSecret) {
     logger('Warn', 'Agent edge disabled: FOREST_AUTH_SECRET is missing');
@@ -373,7 +374,16 @@ function buildAgentMiddlewares(
       source,
       hasAiQueryRoute: aiMiddlewares.length > 0,
     }),
-    ...(bundle ? [createContextRoutesMiddleware({ store: bundle.store, environmentId })] : []),
+    ...(bundle
+      ? [
+          createContextRoutesMiddleware({
+            store: bundle.store,
+            resolveEnvironmentId: oauth.resolveEnvironmentId
+              ? tolerateEnvironmentIdFailure(oauth.resolveEnvironmentId, logger)
+              : undefined,
+          }),
+        ]
+      : []),
     ...aiMiddlewares,
     createTimezoneMiddleware({ defaultTimezone }),
     ...buildAgentRouteMiddlewares(bundle, config, logger),
@@ -397,7 +407,7 @@ export default async function buildBff({
     });
   }
 
-  const oauth = await buildOAuthMiddlewares(config, logger);
+  const oauth = buildOAuthMiddlewares(config, logger);
   const aiMiddlewares = buildAiMiddlewares(config, oauth, logger);
   const agentMiddlewares = buildAgentMiddlewares(config, logger, oauth, aiMiddlewares);
   const agentErrorMiddleware =

packages/agent-bff/src/context/context-routes-middleware.ts

@@ -8,12 +8,16 @@ const CONTEXT_ROUTE = '/agent/v1/context';
 
 export interface ContextRoutesMiddlewareOptions {
   store: ReadModelStore;
-  environmentId?: number;
+  /**
+   * Resolves to `undefined` rather than rejecting: the id decorates the payload, so a Forest server
+   * that cannot answer must not take the whole bootstrap route down with it.
+   */
+  resolveEnvironmentId?: () => Promise<number | undefined>;
 }
 
 export default function createContextRoutesMiddleware({
   store,
-  environmentId,
+  resolveEnvironmentId,
 }: ContextRoutesMiddlewareOptions): Middleware {
   return async function contextRoutesMiddleware(ctx, next) {
     if (ctx.path !== CONTEXT_ROUTE || ctx.method !== 'GET') {
@@ -23,6 +27,7 @@ export default function createContextRoutesMiddleware({
     }
 
     const { collections, readModel, revision } = await resolveSchemaSnapshot(store);
+    const environmentId = await resolveEnvironmentId?.();
 
     ctx.status = 200;
     ctx.body = buildContext(collections, readModel, { schemaRevision: revision, environmentId });

packages/agent-bff/src/http/bff-local-errors.ts

@@ -89,3 +89,11 @@ export function actionRequiresApproval(
 ): BffHttpError {
   return new BffHttpError(403, 'action_requires_approval', message, { details });
 }
+
+export function environmentUnresolved(): BffHttpError {
+  return new BffHttpError(
+    502,
+    'environment_unresolved',
+    'The Forest environment could not be resolved',
+  );
+}

packages/agent-bff/src/oauth/environment-fetch-error.ts

@@ -0,0 +1,38 @@
+/** Rate limiting is the one 4xx that heals on its own. */
+const RETRYABLE_CLIENT_STATUS = 429;
+
+function isPermanentStatus(status: number): boolean {
+  return status >= 400 && status < 500 && status !== RETRYABLE_CLIENT_STATUS;
+}
+
+/**
+ * A failed environment id read, told apart by whether retrying can ever help: a Forest server that
+ * answers and refuses is a configuration error that will never resolve, anything else is transport.
+ * Consumers log the first at `Error` and the second at `Warn`, which is the only thing that lets an
+ * operator distinguish a wrong FOREST_ENV_SECRET from a SaaS blip.
+ */
+export default class EnvironmentFetchError extends Error {
+  readonly permanent: boolean;
+
+  static fromStatus(status: number, statusText: string): EnvironmentFetchError {
+    return new EnvironmentFetchError(
+      `Failed to fetch environment: ${status} ${statusText}`,
+      isPermanentStatus(status),
+    );
+  }
+
+  constructor(message: string, permanent: boolean) {
+    super(message);
+    this.name = 'EnvironmentFetchError';
+    this.permanent = permanent;
+  }
+}
+
+/** Anything that is not a refusal from the Forest server — a socket error, a timeout — may heal. */
+export function isPermanentEnvironmentFailure(error: unknown): boolean {
+  return error instanceof EnvironmentFetchError && error.permanent;
+}
+
+export function environmentFailureLevel(error: unknown): 'Error' | 'Warn' {
+  return isPermanentEnvironmentFailure(error) ? 'Error' : 'Warn';
+}

packages/agent-bff/src/oauth/environment-id.ts

@@ -0,0 +1,85 @@
+import type ForestServerClient from './forest-server-client';
+import type { Logger } from '../ports/logger-port';
+
+import { environmentFailureLevel } from './environment-fetch-error';
+
+/** Resolves the Forest environment id, on demand rather than at boot. */
+export type EnvironmentIdResolver = () => Promise<number>;
+
+/**
+ * How long a failure is remembered. Short enough that a transient outage still heals on the next
+ * request — the whole point of resolving lazily — long enough that a burst of requests costs the
+ * Forest server one round trip instead of one each, and costs the caller one deadline instead of
+ * one per request.
+ */
+const FAILURE_TTL_MS = 5_000;
+
+/**
+ * Fetch the environment id at most once per success, and hold a failure only for `FAILURE_TTL_MS`:
+ * a Forest server that is briefly unreachable must not disable the routes that need the id for the
+ * life of the process, which is what resolving it at boot did. Concurrent callers share the
+ * in-flight fetch.
+ *
+ * The three consumers deliberately disagree on what a failure means, because the id is worth a
+ * different amount to each: `/oauth/authorize` cannot mint a login without it and surfaces
+ * `server_error`, the AI relay cannot address the proxy without it and refuses the query, and
+ * `/agent/v1/context` merely decorates its payload with it and drops the field (see
+ * `tolerateEnvironmentIdFailure`).
+ */
+export default function createEnvironmentIdResolver(
+  client: Pick<ForestServerClient, 'fetchEnvironmentId'>,
+  now: () => number = Date.now,
+): EnvironmentIdResolver {
+  let environmentId: number | undefined;
+  let inFlight: Promise<number> | null = null;
+  let failedAt: number | undefined;
+  let failure: unknown;
+
+  return async function resolveEnvironmentId(): Promise<number> {
+    if (environmentId !== undefined) return environmentId;
+    if (failedAt !== undefined && now() - failedAt < FAILURE_TTL_MS) throw failure;
+
+    inFlight ??= client
+      .fetchEnvironmentId()
+      .then(resolved => {
+        environmentId = resolved;
+        failedAt = undefined;
+
+        return resolved;
+      })
+      .catch(error => {
+        failedAt = now();
+        failure = error;
+
+        throw error;
+      })
+      .finally(() => {
+        inFlight = null;
+      });
+
+    return inFlight;
+  };
+}
+
+/**
+ * The context payload carries the environment id when there is one, and drops it when the Forest
+ * server cannot be reached — the route itself must keep answering either way. A refusal from the
+ * Forest server is logged at `Error` because it will never resolve on its own; a transport failure
+ * stays a `Warn`.
+ */
+export function tolerateEnvironmentIdFailure(
+  resolveEnvironmentId: EnvironmentIdResolver,
+  logger: Logger,
+): () => Promise<number | undefined> {
+  return async function resolveOrForget(): Promise<number | undefined> {
+    try {
+      return await resolveEnvironmentId();
+    } catch (error) {
+      logger(environmentFailureLevel(error), 'Serving the context without an environment id', {
+        cause: error instanceof Error ? error.message : String(error),
+      });
+
+      return undefined;
+    }
+  };
+}