feat(agent-bff): let the agent transport be injected

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

@@ -4,6 +4,7 @@ import type {
   AgentActionClient,
   AgentActionClientOptions,
 } from './agent-action-client';
+import type { AgentTransport } from '../agent/agent-transport';
 import type { Logger } from '../ports/logger-port';
 import type ReadModelStore from '../read-model/read-model-store';
 import type { Context, Middleware } from 'koa';
@@ -76,8 +77,7 @@ function describePayloadShape(raw: unknown): string {
 
 export interface ActionRoutesMiddlewareOptions {
   store: ReadModelStore;
-  agentUrl: string;
-  timeoutMs?: number;
+  transport: AgentTransport;
   logger: Logger;
   createClient?: (options: AgentActionClientOptions) => AgentActionClient;
 }
@@ -159,8 +159,7 @@ async function handleExecute({
 
 export default function createActionRoutesMiddleware({
   store,
-  agentUrl,
-  timeoutMs,
+  transport,
   logger,
   createClient = defaultCreateAgentActionClient,
 }: ActionRoutesMiddlewareOptions): Middleware {
@@ -193,10 +192,9 @@ export default function createActionRoutesMiddleware({
     const values = parseValues(body.values);
 
     const client = createClient({
-      agentUrl,
+      transport,
       token,
       actionEndpoints: readModel.getActionEndpoints(),
-      timeoutMs,
     });
 
     const action = await callAgent(

packages/agent-bff/src/action/agent-action-client.ts

@@ -1,10 +1,9 @@
+import type { AgentTransport } from '../agent/agent-transport';
 import type { ActionEndpointsByCollection } from '@forestadmin/agent-client';
 import type { ForestServerActionFormLayoutElement } from '@forestadmin/forestadmin-client';
 
 import { createRemoteAgentClient } from '@forestadmin/agent-client';
 
-import createAgentHttpRequester from '../agent/create-agent-http-requester';
-
 export interface ActionFormField {
   getName(): string;
   /** A list type is the array the agent sent, `['String']`, not `'StringList'`. */
@@ -41,10 +40,9 @@ export interface AgentActionClient {
 }
 
 export interface AgentActionClientOptions {
-  agentUrl: string;
+  transport: AgentTransport;
   token: string;
   actionEndpoints: ActionEndpointsByCollection;
-  timeoutMs?: number;
 }
 
 // The raw layout must be read AFTER tryToSetFields: a change hook rebuilds fields+layout in place.
@@ -64,16 +62,15 @@ export function extractRawLayout(action: ActionForm): ForestServerActionFormLayo
  * than reimplementing it. The endpoint map from the read-model is the action allow-list.
  */
 export default function createAgentActionClient({
-  agentUrl,
+  transport,
   token,
   actionEndpoints,
-  timeoutMs,
 }: AgentActionClientOptions): AgentActionClient {
   const client = createRemoteAgentClient({
-    url: agentUrl,
+    url: transport.url,
     token,
     actionEndpoints,
-    httpRequester: createAgentHttpRequester(token, agentUrl, timeoutMs),
+    httpRequester: transport.createRequester(token),
   });
 
   return {

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

@@ -0,0 +1,28 @@
+import type { HttpRequester } from '@forestadmin/agent-client';
+
+import createAgentHttpRequester from './create-agent-http-requester';
+
+/**
+ * How the BFF reaches the agent. Everything that talks to the agent takes one of these instead of a
+ * URL, so the same routes serve a remote agent over HTTP and an agent embedded in the same process.
+ */
+export interface AgentTransport {
+  /**
+   * Base url `createRemoteAgentClient` still requires. Over HTTP it is the agent; in-process it is a
+   * sentinel that never reaches the network, since the requester answers before any socket is opened.
+   */
+  url: string;
+  createRequester(token: string): HttpRequester;
+}
+
+export interface HttpTransportOptions {
+  agentUrl: string;
+  timeoutMs?: number;
+}
+
+export function createHttpTransport({ agentUrl, timeoutMs }: HttpTransportOptions): AgentTransport {
+  return {
+    url: agentUrl,
+    createRequester: token => createAgentHttpRequester(token, agentUrl, timeoutMs),
+  };
+}

packages/agent-bff/src/agent/in-process-transport.ts

@@ -0,0 +1,147 @@
+import type { AgentTransport } from './agent-transport';
+
+import { HttpRequester } from '@forestadmin/agent-client';
+
+import { streamingUnsupported } from '../http/bff-local-errors';
+
+/** A sentinel that never reaches the network: `query` answers before any socket is opened. */
+const IN_PROCESS_URL = 'http://in-process.agent';
+
+export interface AgentDispatchRequest {
+  method: 'get' | 'post' | 'put' | 'delete';
+  path: string;
+  headers: Record<string, string>;
+  query?: Record<string, unknown>;
+  payload?: Record<string, unknown>;
+  timeoutMs?: number;
+}
+
+export interface AgentDispatchResponse {
+  status: number;
+  body: unknown;
+  text?: string;
+}
+
+/**
+ * Dispatches a request into an agent living in the same process, without a socket. Declared
+ * structurally so neither package has to depend on the other for six primitive fields.
+ */
+export interface AgentDispatcher {
+  /**
+   * Bounding the call is the implementor's duty: there is no socket to abort, so nothing here can
+   * cut a hung agent handler loose. When `timeoutMs` is absent the deployment configured none —
+   * apply the 10s ceiling `HttpRequester.query` always has rather than waiting forever. A dispatch
+   * that fails, times out included, must reject.
+   */
+  request(request: AgentDispatchRequest): Promise<AgentDispatchResponse>;
+}
+
+/**
+ * Reaches the agent through the dispatcher instead of the network, reusing `HttpRequester`'s parse
+ * helpers so results and error shape stay identical to the HTTP path.
+ */
+class InProcessRequester extends HttpRequester {
+  constructor(
+    private readonly bearerToken: string,
+    private readonly dispatcher: AgentDispatcher,
+    private readonly defaultTimeoutMs?: number,
+  ) {
+    super(bearerToken, { url: IN_PROCESS_URL });
+  }
+
+  // No socket to stream from, and nothing in the BFF streams today. A typed 501 rather than a raw
+  // Error, so the day a route does reach here the client is told what is missing instead of being
+  // sent looking for a network the request never crossed.
+  override async stream(): Promise<void> {
+    throw streamingUnsupported('Streaming is not supported over the in-process transport');
+  }
+
+  override async query<Data = unknown>({
+    method,
+    path,
+    body,
+    query,
+    maxTimeAllowed,
+    contentType,
+    skipDeserialization,
+  }: {
+    method: 'get' | 'post' | 'put' | 'delete';
+    path: string;
+    body?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    maxTimeAllowed?: number;
+    contentType?: 'application/json' | 'text/csv';
+    skipDeserialization?: boolean;
+  }): Promise<Data> {
+    const target = InProcessRequester.toDispatchTarget(path);
+
+    const {
+      status,
+      body: responseBody,
+      text,
+    } = await this.dispatch({
+      method,
+      path: target.path,
+      headers: {
+        Authorization: `Bearer ${this.bearerToken}`,
+        'Content-Type': contentType ?? 'application/json',
+        Accept: contentType ?? 'application/json',
+      },
+      query: { timezone: 'Europe/Paris', ...target.query, ...query },
+      payload: body,
+      timeoutMs: maxTimeAllowed ?? this.defaultTimeoutMs,
+    });
+
+    if (status >= 400) throw this.buildError(status, responseBody, text);
+
+    return this.deserialize<Data>(responseBody, text, skipDeserialization);
+  }
+
+  /**
+   * A rejection here is the agent throwing or the dispatch itself failing — never a network hop,
+   * since there is none. Rethrown with the shape an agent 5xx has, so `mapAgentError` logs the real
+   * cause and answers `agent_unavailable` instead of sending whoever debugs it to look for a socket.
+   */
+  private async dispatch(request: AgentDispatchRequest): Promise<AgentDispatchResponse> {
+    try {
+      return await this.dispatcher.request(request);
+    } catch (error) {
+      const detail = error instanceof Error ? error.stack ?? error.message : String(error);
+
+      throw this.buildError(500, { errors: [{ detail }] });
+    }
+  }
+
+  /**
+   * Callers hand over raw segments — a record id, a collection name — because `buildUrl` escapes the
+   * whole path on the HTTP side, so the escaping has to happen here too. Escaping alone is not
+   * enough: `escapeUrlSlug` prefixes `+?*` with a backslash, which the WHATWG parser `buildUrl`
+   * feeds reads as a path separator, and that parse also resolves `..` and splits a trailing query
+   * off. Running it here is what keeps a given id addressing the same record over both transports —
+   * both remain wrong for those three characters, which is PRD-1124's to fix on both at once.
+   */
+  private static toDispatchTarget(path: string): {
+    path: string;
+    query: Record<string, string>;
+  } {
+    const normalized = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${IN_PROCESS_URL}${HttpRequester.escapeUrlSlug(normalized)}`);
+
+    return { path: url.pathname, query: Object.fromEntries(url.searchParams) };
+  }
+}
+
+export interface InProcessTransportOptions {
+  dispatcher: AgentDispatcher;
+  timeoutMs?: number;
+}
+
+export default function createInProcessTransport({
+  dispatcher,
+  timeoutMs,
+}: InProcessTransportOptions): AgentTransport {
+  return {
+    url: IN_PROCESS_URL,
+    createRequester: token => new InProcessRequester(token, dispatcher, timeoutMs),
+  };
+}

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

@@ -14,6 +14,7 @@ import Koa from 'koa';
 import createActionRoutesMiddleware from './action/action-routes-middleware';
 import createConsoleLogger from './adapters/console-logger';
 import createAgentStubMiddleware from './agent/agent-stub';
+import { createHttpTransport } from './agent/agent-transport';
 import AiProxyClient from './ai/ai-proxy-client';
 import createAiRoutesMiddleware, { AI_QUERY_ROUTE } from './ai/ai-routes-middleware';
 import createApiKeyAuthenticator from './api-key/api-key-authenticator';
@@ -260,8 +261,10 @@ function toUnfoldSource(
 
   return {
     store: bundle.store,
-    agentUrl: config.agentUrl,
-    timeoutMs: config.agentTimeoutMs,
+    transport: createHttpTransport({
+      agentUrl: config.agentUrl,
+      timeoutMs: config.agentTimeoutMs,
+    }),
     logger,
   };
 }
@@ -312,10 +315,12 @@ function buildAgentRouteMiddlewares(
     return [permissionsMiddleware, createAgentStubMiddleware()];
   }
 
+  const transport = createHttpTransport({ agentUrl, timeoutMs });
+
   return [
     permissionsMiddleware,
-    createDataRoutesMiddleware({ store, agentUrl, timeoutMs, logger }),
-    createActionRoutesMiddleware({ store, agentUrl, timeoutMs, logger }),
+    createDataRoutesMiddleware({ store, transport, logger }),
+    createActionRoutesMiddleware({ store, transport, logger }),
   ];
 }
 

packages/agent-bff/src/data/agent-data-client.ts

@@ -1,9 +1,8 @@
-import createAgentHttpRequester from '../agent/create-agent-http-requester';
+import type { AgentTransport } from '../agent/agent-transport';
 
 export interface AgentDataClientOptions {
-  agentUrl: string;
+  transport: AgentTransport;
   token: string;
-  timeoutMs?: number;
 }
 
 export interface AgentDataClient {
@@ -29,11 +28,10 @@ export interface AgentDataClient {
  * endpoint's raw payload, which `collection.count()` coerces through `Number()` and loses.
  */
 export default function createAgentDataClient({
-  agentUrl,
+  transport,
   token,
-  timeoutMs,
 }: AgentDataClientOptions): AgentDataClient {
-  const requester = createAgentHttpRequester(token, agentUrl, timeoutMs);
+  const requester = transport.createRequester(token);
 
   // Segments are passed raw: HttpRequester.buildUrl already runs the whole path through
   // escapeUrlSlug/encodeURI, so pre-encoding here would double-encode (`|` -> `%257C`).

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

@@ -5,6 +5,7 @@ import type {
   RelationCountRequestBody,
   RelationListRequestBody,
 } from './agent-query';
+import type { AgentTransport } from '../agent/agent-transport';
 import type { Logger } from '../ports/logger-port';
 import type { CapabilitiesResult } from '../read-model/capabilities-cache';
 import type ReadModel from '../read-model/read-model';
@@ -43,8 +44,7 @@ const RELATION_ROUTE = /^\/agent\/v1\/([^/]+)\/relations\/([^/]+)\/(list|count)$
 
 export interface DataRoutesMiddlewareOptions {
   store: ReadModelStore;
-  agentUrl: string;
-  timeoutMs?: number;
+  transport: AgentTransport;
   logger: Logger;
   createClient?: (options: AgentDataClientOptions) => AgentDataClient;
 }
@@ -53,8 +53,7 @@ interface RequestHandlerDeps {
   collection: string;
   client: AgentDataClient;
   store: ReadModelStore;
-  agentUrl: string;
-  timeoutMs?: number;
+  transport: AgentTransport;
   token: string;
   timezone: string;
   logger: Logger;
@@ -86,11 +85,7 @@ function resolveCapabilities(
     () =>
       deps.store.getCapabilities(
         collection,
-        createAgentCapabilitiesFetcher({
-          agentUrl: deps.agentUrl,
-          token: deps.token,
-          timeoutMs: deps.timeoutMs,
-        }),
+        createAgentCapabilitiesFetcher({ transport: deps.transport, token: deps.token }),
       ),
     deps.logger,
   );
@@ -306,8 +301,7 @@ async function handleRelation(
 
 export default function createDataRoutesMiddleware({
   store,
-  agentUrl,
-  timeoutMs,
+  transport,
   logger,
   createClient = defaultCreateAgentDataClient,
 }: DataRoutesMiddlewareOptions): Middleware {
@@ -336,10 +330,9 @@ export default function createDataRoutesMiddleware({
 
     const deps: RequestHandlerDeps = {
       collection,
-      client: createClient({ agentUrl, token, timeoutMs }),
+      client: createClient({ transport, token }),
       store,
-      agentUrl,
-      timeoutMs,
+      transport,
       token,
       timezone: ctx.state.timezone as string,
       logger,

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

@@ -40,6 +40,12 @@ export function unsupportedActionResult(message = 'Unsupported action result'):
   return new BffHttpError(501, 'unsupported_action_result', message);
 }
 
+export function streamingUnsupported(
+  message = 'Streaming is not supported over this transport',
+): BffHttpError {
+  return new BffHttpError(501, 'streaming_unsupported', message);
+}
+
 export function actionError(message = 'The action failed', details?: unknown): BffHttpError {
   return new BffHttpError(400, 'action_error', message, { details });
 }