@cat-factory/server 0.166.2 → 0.169.0

package/dist/modules/llmProxy/LlmProxyController.js

@@ -3,7 +3,7 @@ import { bodyLimit } from 'hono/body-limit';
 import { promptCacheParams, readInputTokenClasses } from '@cat-factory/agents';
 import { isLocalRunner } from '@cat-factory/contracts';
 import { fetchLocalRunner } from '@cat-factory/integrations';
-import { contextWindowFor, runBestEffort } from '@cat-factory/kernel';
+import { contextWindowFor, normalizeCallPhase, runBestEffort, } from '@cat-factory/kernel';
 import { openAiCompatibleBaseUrlError } from '../../agents/providerErrors.js';
 import { ContainerSessionService, } from '../../containers/ContainerSessionService.js';
 import { makeWaitUntil } from '../../http/waitUntil.js';
@@ -124,7 +124,12 @@ async function dispatchInProcess(c, ctx) {
             errorMessage: `Provider '${session.provider}' is not available`,
             upstreamMs: 0,
         });
-        return c.json({ error: { message: `Provider '${session.provider}' is not available` } }, 502);
+        return c.json({
+            error: {
+                code: 'upstream_unavailable',
+                message: `Provider '${session.provider}' is not available`,
+            },
+        }, 502);
     }
     try {
         return await inProcess;
@@ -141,7 +146,12 @@ async function dispatchInProcess(c, ctx) {
             errorMessage: message,
             upstreamMs: Date.now() - dispatchAt,
         });
-        return c.json({ error: { message: `In-process call failed for model '${session.model}': ${message}` } }, 502);
+        return c.json({
+            error: {
+                code: 'upstream_error',
+                message: `In-process call failed for model '${session.model}': ${message}`,
+            },
+        }, 502);
     }
 }
 /**
@@ -175,7 +185,12 @@ async function resolveUpstreamTarget(c, ctx) {
                 upstreamMs: 0,
             });
             return {
-                failure: c.json({ error: { message: `No local runner '${session.provider}' configured for this run` } }, 502),
+                failure: c.json({
+                    error: {
+                        code: 'upstream_unavailable',
+                        message: `No local runner '${session.provider}' configured for this run`,
+                    },
+                }, 502),
             };
         }
         // Most local runners ignore auth; the SDK/fetch still emit an Authorization header.
@@ -199,7 +214,14 @@ async function resolveUpstreamTarget(c, ctx) {
             errorMessage: message,
             upstreamMs: 0,
         });
-        return { failure: c.json({ error: { message } }, 502) };
+        // The raw exception text from an upstream/SDK call is NOT wire-safe: a fetch or SDK
+        // error routinely echoes the request URL (with its query) or an auth header back in its
+        // own message, and this response crosses out of the deployment. The cause is already
+        // logged above and recorded on the call metric — both of which are scrubbed sinks the
+        // operator can read — so the wire gets the generic framing instead.
+        return {
+            failure: c.json({ error: { code: 'upstream_error', message: 'Upstream provider request failed' } }, 502),
+        };
     }
     // Lease the API key for this provider from the DB-backed pool (workspace + owning account + the
     // run initiator), scoped from the signed session claims. Keys are no longer env-baked: an empty
@@ -215,7 +237,9 @@ async function resolveUpstreamTarget(c, ctx) {
             errorMessage: 'API-key store is not configured',
             upstreamMs: 0,
         });
-        return { failure: c.json({ error: { message: 'API-key store is not configured' } }, 502) };
+        return {
+            failure: c.json({ error: { code: 'unavailable', message: 'API-key store is not configured' } }, 502),
+        };
     }
     try {
         const leased = await apiKeys.lease(session.workspaceId, session.provider, {
@@ -242,7 +266,12 @@ async function resolveUpstreamTarget(c, ctx) {
             upstreamMs: 0,
         });
         return {
-            failure: c.json({ error: { message: `No API key configured for provider '${session.provider}'` } }, 502),
+            failure: c.json({
+                error: {
+                    code: 'unavailable',
+                    message: `No API key configured for provider '${session.provider}'`,
+                },
+            }, 502),
         };
     }
 }
@@ -289,7 +318,7 @@ async function relayUpstream(c, ctx, target) {
                 errorMessage: message,
                 upstreamMs: Date.now() - dispatchAt,
             });
-            return c.json({ error: { message } }, 502);
+            return c.json({ error: { code: 'upstream_blocked', message } }, 502);
         }
     }
     else {
@@ -348,229 +377,287 @@ async function relayUpstream(c, ctx, target) {
  * upload routes' explicit `bodyLimit`.
  */
 const MAX_PROXY_BODY_BYTES = 32 * 1024 * 1024;
-export function llmProxyController() {
-    const app = new Hono();
-    app.post('/v1/chat/completions', bodyLimit({
-        maxSize: MAX_PROXY_BODY_BYTES,
-        onError: (c) => c.json({ error: { message: 'Request body exceeds size limit' } }, 413),
-    }), async (c) => {
-        // Proxy-entry clock: everything from here to the upstream dispatch (and after the
-        // response) is transport overhead; the slice spent waiting on the model is the
-        // actual execution. The two are split in the observability sink.
-        const t0 = Date.now();
-        const { config, spendService, gateways, llmObservability, executionEventPublisher, apiKeys, localModelEndpoints, } = c.get('container');
-        const secret = config.auth.sessionSecret;
-        if (!secret) {
-            logger.error('llm proxy: session secret not configured', { scope: 'llmProxy' });
-            return c.json({ error: { message: 'LLM proxy is not configured' } }, 503);
-        }
-        const sessions = new ContainerSessionService({ secret });
-        const session = await sessions.verify(bearer(c.req.header('authorization')));
-        if (!session) {
-            logger.warn('llm proxy: invalid or expired session token', { scope: 'llmProxy' });
-            return c.json({ error: { message: 'Invalid or expired session token' } }, 401);
-        }
-        // Parse + harden the request: lock the model to the session's, and ask for
-        // usage on the final streamed chunk so we can always meter. Parsed before the
-        // spend gate so a refusal is still recorded with its prompt/shape for analysis.
-        let payload;
-        try {
-            payload = (await c.req.json());
-        }
-        catch {
-            return c.json({ error: { message: 'Invalid JSON body' } }, 400);
-        }
-        payload.model = session.model;
-        // Prompt caching: route this conversation's calls to the same cached prefix on
-        // providers that support it (keyed on the execution id, stable across the run's
-        // turns). A no-op for providers that cache automatically on the prefix or not at
-        // all — see `promptCacheParams`.
-        Object.assign(payload, promptCacheParams(session.provider, session.executionId));
-        const streaming = payload.stream === true;
-        const toolCount = Array.isArray(payload.tools) ? payload.tools.length : 0;
-        const messageCount = Array.isArray(payload.messages) ? payload.messages.length : 0;
-        // The EFFECTIVE output ceiling: updated below if the proxy overrides max_tokens
-        // (e.g. the Workers AI floor), so the recorded metric reflects what actually
-        // applied, not just what the client asked for.
-        let requestMaxTokens = typeof payload.max_tokens === 'number' ? payload.max_tokens : null;
-        const promptText = JSON.stringify(payload.messages ?? []);
-        // Correlate every proxied call with its run so a bootstrap/execution can be
-        // traced end to end. We log the tool count explicitly: an agent (Pi) that gets
-        // no tools back can't edit files, so a toolless call is the signature of a no-op.
-        const log = logger.child({
-            scope: 'llmProxy',
+/**
+ * The completions paths this proxy serves. The second carries the RUN PHASE the caller was in
+ * when it made the call (`agent`, `validation-repair`, `reproduction-repair`, …): the harness
+ * points Pi's provider config at `${proxyBaseUrl}/phase/<phase>` for the pass it is about to
+ * run, so the phase axis on `llm_call_metrics` is stamped by the component that OWNS the phase
+ * boundary rather than inferred downstream from timestamps
+ * (`docs/initiatives/token-burn-instrumentation.md`).
+ *
+ * A URL segment rather than a header because the harness does not make these requests — Pi
+ * does, from a config file whose only per-run knobs are the base URL and the token. The
+ * unphased path stays the canonical one: an image that predates the phase axis keeps working,
+ * and its calls land in the unattributed `''` slice.
+ */
+const COMPLETIONS_PATHS = ['/v1/chat/completions', '/v1/phase/:phase/chat/completions'];
+/**
+ * Build the per-call observation handler: (1) push a COMPACT live activity event (no
+ * prompt/response bodies) so an open "Model activity" panel updates in real time, independent
+ * of the durable driver — the proxy records calls even while the run's poll loop is evicted;
+ * (2) persist the full metric to the observability sink when it is wired.
+ *
+ * `upstreamMs` is supplied by whichever path made the call; `totalMs` is the proxy's end-to-end
+ * time. Both halves are best-effort and must never break the proxy. Extracted from
+ * {@link handleChatCompletion} because it is a cohesive collaborator (everything the metering
+ * boundary needs is in {@link CallMeterContext}) and the handler had no headroom left under the
+ * 300-line function budget.
+ */
+function makeCallObserver(meter, deps) {
+    const { session, callId, startedAt, streaming, phase, messageCount, toolCount, promptText } = meter;
+    const { waitUntil, log, executionEventPublisher, llmObservability } = deps;
+    return (obs) => {
+        const completionTokens = obs.usage?.completion_tokens ?? 0;
+        // The three input classes are recorded ORTHOGONALLY, so total input is their sum. An
+        // upstream path that already knows the split (a gateway whose own shape carries it)
+        // hands all three over together; otherwise they are read off the usage payload, which
+        // is where the inclusive-vs-exclusive reconciliation lives.
+        const input = obs.inputTokens ?? readInputTokenClasses(obs.usage);
+        const totalMs = Date.now() - startedAt;
+        const requestMaxTokens = meter.requestMaxTokens();
+        const totalTokens = input.fresh + input.cacheRead + input.cacheWrite + completionTokens;
+        // Emitted regardless of whether the persistence sink is wired, so the live view works
+        // even on a deployment that does not retain metrics. This fires on EVERY observed
+        // outcome, including refusals/errors (spend exhausted, unavailable provider, upstream
+        // non-2xx) where no model work ran: surfacing those live (with `ok:false`) is intentional
+        // and matches what the sink persists. Best-effort: a publish failure (no subscribers,
+        // transient hub error) must not break metering.
+        waitUntil(runBestEffort(log, 'llmProxy.publishCallObserved', () => 
+        // `?.` on the publisher itself, not just the method: a minimal container
+        // (e.g. the harness's real-proxy acceptance test) may omit it, and the live
+        // emit is best-effort — a missing publisher must never break metering.
+        executionEventPublisher?.llmCallObserved?.(session.workspaceId, {
+            id: callId,
             workspaceId: session.workspaceId,
             executionId: session.executionId,
             agentKind: session.agentKind,
             provider: session.provider,
             model: session.model,
+            createdAt: Date.now(),
+            streaming,
+            phase,
+            messageCount,
+            toolCount,
+            requestMaxTokens,
+            promptTokens: input.fresh,
+            cacheReadTokens: input.cacheRead,
+            cacheWriteTokens: input.cacheWrite,
+            completionTokens,
+            totalTokens,
+            finishReason: obs.finishReason,
+            upstreamMs: obs.upstreamMs,
+            overheadMs: Math.max(0, totalMs - obs.upstreamMs),
+            totalMs,
+            ok: obs.ok,
+            httpStatus: obs.httpStatus,
+            errorMessage: obs.errorMessage,
+        })));
+        if (!llmObservability)
+            return;
+        waitUntil(llmObservability
+            .record({
+            id: callId,
+            workspaceId: session.workspaceId,
+            executionId: session.executionId,
+            agentKind: session.agentKind,
+            provider: session.provider,
+            model: session.model,
+            streaming,
+            phase,
+            // A proxied call carries no job-scoped turn counter — the proxy sees one HTTP
+            // request at a time — so its rows order by `createdAt`, never by a faked turn.
+            turnIndex: null,
+            messageCount,
+            toolCount,
+            requestMaxTokens,
+            promptTokens: input.fresh,
+            cacheReadTokens: input.cacheRead,
+            cacheWriteTokens: input.cacheWrite,
+            completionTokens,
+            totalTokens,
+            finishReason: obs.finishReason,
+            totalMs,
+            upstreamMs: obs.upstreamMs,
+            ok: obs.ok,
+            httpStatus: obs.httpStatus,
+            errorMessage: obs.errorMessage,
+            promptText,
+            responseText: obs.responseText,
+            reasoningText: obs.reasoningText ?? '',
+        })
+            // Observability must never break the proxy.
+            .catch((err) => log.warn('llm proxy: failed to record metric', {
+            err: err instanceof Error ? err.message : String(err),
+        })));
+    };
+}
+/**
+ * Serve one proxied chat completion: verify the container session, harden the payload, gate on
+ * spend, forward to the resolved upstream and meter the call. Registered on BOTH completions
+ * paths (see {@link COMPLETIONS_PATHS}), which differ only in whether the caller tagged its run
+ * phase — hence a named handler rather than an inline one.
+ */
+async function handleChatCompletion(c) {
+    // Proxy-entry clock: everything from here to the upstream dispatch (and after the
+    // response) is transport overhead; the slice spent waiting on the model is the
+    // actual execution. The two are split in the observability sink.
+    const t0 = Date.now();
+    const { config, spendService, gateways, llmObservability, executionEventPublisher, apiKeys, localModelEndpoints, } = c.get('container');
+    const secret = config.auth.sessionSecret;
+    if (!secret) {
+        logger.error('llm proxy: session secret not configured', { scope: 'llmProxy' });
+        return c.json({ error: { code: 'unavailable', message: 'LLM proxy is not configured' } }, 503);
+    }
+    const sessions = new ContainerSessionService({ secret });
+    const session = await sessions.verify(bearer(c.req.header('authorization')));
+    if (!session) {
+        logger.warn('llm proxy: invalid or expired session token', { scope: 'llmProxy' });
+        return c.json({ error: { code: 'unauthorized', message: 'Invalid or expired session token' } }, 401);
+    }
+    // Parse + harden the request: lock the model to the session's, and ask for
+    // usage on the final streamed chunk so we can always meter. Parsed before the
+    // spend gate so a refusal is still recorded with its prompt/shape for analysis.
+    let payload;
+    try {
+        payload = (await c.req.json());
+    }
+    catch {
+        return c.json({ error: { code: 'validation', message: 'Invalid JSON body' } }, 400);
+    }
+    payload.model = session.model;
+    // Prompt caching: route this conversation's calls to the same cached prefix on
+    // providers that support it (keyed on the execution id, stable across the run's
+    // turns). A no-op for providers that cache automatically on the prefix or not at
+    // all — see `promptCacheParams`.
+    Object.assign(payload, promptCacheParams(session.provider, session.executionId));
+    // The run phase this call belongs to, off the (optional) path segment the caller was
+    // pointed at. Read through the untyped `param()` map because the SAME handler serves the
+    // unphased path too. Untrusted like any request path — a session token is all it takes to
+    // write here — so it is normalised to the phase alphabet before it becomes a grouping
+    // key; anything else lands in the unattributed `''` slice.
+    const phase = normalizeCallPhase(c.req.param().phase);
+    const streaming = payload.stream === true;
+    const toolCount = Array.isArray(payload.tools) ? payload.tools.length : 0;
+    const messageCount = Array.isArray(payload.messages) ? payload.messages.length : 0;
+    // The EFFECTIVE output ceiling: updated below if the proxy overrides max_tokens
+    // (e.g. the Workers AI floor), so the recorded metric reflects what actually
+    // applied, not just what the client asked for.
+    let requestMaxTokens = typeof payload.max_tokens === 'number' ? payload.max_tokens : null;
+    const promptText = JSON.stringify(payload.messages ?? []);
+    // Correlate every proxied call with its run so a bootstrap/execution can be
+    // traced end to end. We log the tool count explicitly: an agent (Pi) that gets
+    // no tools back can't edit files, so a toolless call is the signature of a no-op.
+    const log = logger.child({
+        scope: 'llmProxy',
+        workspaceId: session.workspaceId,
+        executionId: session.executionId,
+        agentKind: session.agentKind,
+        provider: session.provider,
+        model: session.model,
+    });
+    log.info('llm proxy: forwarding chat completion', { streaming, toolCount });
+    const waitUntil = makeWaitUntil(c);
+    // One id per proxied call, minted here so the SAME id rides both the live
+    // `llmCall` activity event and the persisted metric row — the drill-down panel
+    // keys its lazy body-load by it, and a live-appended summary row reconciles with
+    // the stored row on reload instead of duplicating.
+    const callId = `llm_${crypto.randomUUID()}`;
+    // Per-call observation handling, off the response path — see `makeCallObserver`.
+    const observe = makeCallObserver({
+        session,
+        callId,
+        startedAt: t0,
+        streaming,
+        phase,
+        messageCount,
+        toolCount,
+        promptText,
+        // Read lazily: the proxy may still raise `max_tokens` below (the Workers AI floor),
+        // and the metric must report the ceiling that actually applied, not the one asked for.
+        requestMaxTokens: () => requestMaxTokens,
+    }, { waitUntil, log, executionEventPublisher, llmObservability });
+    // Spend gate: refuse once the monthly budget is exhausted, mirroring the
+    // engine's pre-step check so a container can't keep spending.
+    if (await spendService.isOverBudget(session.workspaceId, {
+        accountId: session.accountId,
+        userId: session.userId,
+    })) {
+        logger.warn('llm proxy: spend budget exhausted — refusing call', {
+            scope: 'llmProxy',
+            workspaceId: session.workspaceId,
+            executionId: session.executionId,
         });
-        log.info('llm proxy: forwarding chat completion', { streaming, toolCount });
-        const waitUntil = makeWaitUntil(c);
-        // One id per proxied call, minted here so the SAME id rides both the live
-        // `llmCall` activity event and the persisted metric row — the drill-down panel
-        // keys its lazy body-load by it, and a live-appended summary row reconciles with
-        // the stored row on reload instead of duplicating.
-        const callId = `llm_${crypto.randomUUID()}`;
-        // Per-call observation handling, off the response path: (1) push a COMPACT live
-        // activity event (no prompt/response bodies) so an open "Model activity" panel
-        // updates in real time, independent of the durable driver — the proxy records
-        // calls even while the run's poll loop is evicted; (2) persist the full metric to
-        // the observability sink when it is wired. `upstreamMs` is supplied by whichever
-        // path made the call; `totalMs` is the proxy's end-to-end time. Both are
-        // best-effort and must never break the proxy.
-        const observe = (obs) => {
-            const completionTokens = obs.usage?.completion_tokens ?? 0;
-            // The three input classes are recorded ORTHOGONALLY, so total input is their sum. An
-            // upstream path that already knows the split (a gateway whose own shape carries it)
-            // hands all three over together; otherwise they are read off the usage payload, which
-            // is where the inclusive-vs-exclusive reconciliation lives.
-            const input = obs.inputTokens ?? readInputTokenClasses(obs.usage);
-            const totalMs = Date.now() - t0;
-            // Live activity event — emitted regardless of whether the persistence sink is
-            // wired, so the live view works even on a deployment that does not retain
-            // metrics. This fires on EVERY observed outcome, including refusals/errors (spend
-            // exhausted, unavailable provider, upstream non-2xx) where no model work ran:
-            // surfacing those live (with `ok:false`) is intentional and matches what the sink
-            // persists. Best-effort: a publish failure (no subscribers, transient hub error)
-            // must not break metering.
-            waitUntil(runBestEffort(log, 'llmProxy.publishCallObserved', () => 
-            // `?.` on the publisher itself, not just the method: a minimal container
-            // (e.g. the harness's real-proxy acceptance test) may omit it, and the live
-            // emit is best-effort — a missing publisher must never break metering.
-            executionEventPublisher?.llmCallObserved?.(session.workspaceId, {
-                id: callId,
-                workspaceId: session.workspaceId,
-                executionId: session.executionId,
-                agentKind: session.agentKind,
-                provider: session.provider,
-                model: session.model,
-                createdAt: Date.now(),
-                streaming,
-                messageCount,
-                toolCount,
-                requestMaxTokens,
-                promptTokens: input.fresh,
-                cacheReadTokens: input.cacheRead,
-                cacheWriteTokens: input.cacheWrite,
-                completionTokens,
-                totalTokens: input.fresh + input.cacheRead + input.cacheWrite + completionTokens,
-                finishReason: obs.finishReason,
-                upstreamMs: obs.upstreamMs,
-                overheadMs: Math.max(0, totalMs - obs.upstreamMs),
-                totalMs,
-                ok: obs.ok,
-                httpStatus: obs.httpStatus,
-                errorMessage: obs.errorMessage,
-            })));
-            if (!llmObservability)
-                return;
-            waitUntil(llmObservability
-                .record({
-                id: callId,
-                workspaceId: session.workspaceId,
-                executionId: session.executionId,
-                agentKind: session.agentKind,
-                provider: session.provider,
-                model: session.model,
-                streaming,
-                messageCount,
-                toolCount,
-                requestMaxTokens,
-                promptTokens: input.fresh,
-                cacheReadTokens: input.cacheRead,
-                cacheWriteTokens: input.cacheWrite,
-                completionTokens,
-                totalTokens: input.fresh + input.cacheRead + input.cacheWrite + completionTokens,
-                finishReason: obs.finishReason,
-                totalMs,
-                upstreamMs: obs.upstreamMs,
-                ok: obs.ok,
-                httpStatus: obs.httpStatus,
-                errorMessage: obs.errorMessage,
-                promptText,
-                responseText: obs.responseText,
-                reasoningText: obs.reasoningText ?? '',
-            })
-                // Observability must never break the proxy.
-                .catch((err) => log.warn('llm proxy: failed to record metric', {
-                err: err instanceof Error ? err.message : String(err),
-            })));
-        };
-        // Spend gate: refuse once the monthly budget is exhausted, mirroring the
-        // engine's pre-step check so a container can't keep spending.
-        if (await spendService.isOverBudget(session.workspaceId, {
+        observe({
+            usage: null,
+            finishReason: null,
+            responseText: '',
+            ok: false,
+            httpStatus: 402,
+            errorMessage: 'Spend budget exhausted',
+            upstreamMs: 0,
+        });
+        return c.json({ error: { code: 'spend_exhausted', message: 'Spend budget exhausted' } }, 402);
+    }
+    // Give container agents generous output room for in-process Workers AI models (a no-op
+    // for other providers); records the ceiling actually applied so the metric is accurate.
+    requestMaxTokens = applyWorkersAiCeiling(session, payload, promptText, requestMaxTokens);
+    // The pooled API key leased for this call (non-binding providers), so usage can be
+    // folded back into its rolling-window rotation counters when the call completes.
+    let leasedApiKeyId = null;
+    const record = (usage) => {
+        if (!usage)
+            return Promise.resolve(0);
+        const inputTokens = usage.prompt_tokens ?? 0;
+        const outputTokens = usage.completion_tokens ?? 0;
+        // Fold usage into the leased key's rotation counters (best-effort, off the meter).
+        if (leasedApiKeyId && apiKeys) {
+            void runBestEffort(log, 'apiKeys.recordUsage', () => apiKeys.recordUsage(leasedApiKeyId, { inputTokens, outputTokens }), { apiKeyId: leasedApiKeyId });
+        }
+        return spendService.record({
+            workspaceId: session.workspaceId,
             accountId: session.accountId,
             userId: session.userId,
-        })) {
-            logger.warn('llm proxy: spend budget exhausted — refusing call', {
-                scope: 'llmProxy',
-                workspaceId: session.workspaceId,
-                executionId: session.executionId,
-            });
-            observe({
-                usage: null,
-                finishReason: null,
-                responseText: '',
-                ok: false,
-                httpStatus: 402,
-                errorMessage: 'Spend budget exhausted',
-                upstreamMs: 0,
-            });
-            return c.json({ error: { message: 'Spend budget exhausted' } }, 402);
-        }
-        // Give container agents generous output room for in-process Workers AI models (a no-op
-        // for other providers); records the ceiling actually applied so the metric is accurate.
-        requestMaxTokens = applyWorkersAiCeiling(session, payload, promptText, requestMaxTokens);
-        // The pooled API key leased for this call (non-binding providers), so usage can be
-        // folded back into its rolling-window rotation counters when the call completes.
-        let leasedApiKeyId = null;
-        const record = (usage) => {
-            if (!usage)
-                return Promise.resolve(0);
-            const inputTokens = usage.prompt_tokens ?? 0;
-            const outputTokens = usage.completion_tokens ?? 0;
-            // Fold usage into the leased key's rotation counters (best-effort, off the meter).
-            if (leasedApiKeyId && apiKeys) {
-                void runBestEffort(log, 'apiKeys.recordUsage', () => apiKeys.recordUsage(leasedApiKeyId, { inputTokens, outputTokens }), { apiKeyId: leasedApiKeyId });
-            }
-            return spendService.record({
-                workspaceId: session.workspaceId,
-                accountId: session.accountId,
-                userId: session.userId,
-                executionId: session.executionId,
-                agentKind: session.agentKind,
-                model: `${session.provider}:${session.model}`,
-                usage: { inputTokens, outputTokens },
-            });
-        };
-        // The per-call state the dispatch helpers below thread through; `observe` / `record` stay
-        // bound to this handler's mutable `requestMaxTokens` / `leasedApiKeyId`.
-        const ctx = {
-            session,
-            payload,
-            streaming,
-            promptText,
-            log,
-            gateways,
-            apiKeys,
-            localModelEndpoints,
-            waitUntil,
-            observe,
-            record,
-        };
-        // Workers AI (and any binding-reached provider) has no external upstream: run it in-process
-        // via the facade's gateway. Null-provider (e.g. Node can't) surfaces as unavailable.
-        if (session.provider === 'workers-ai')
-            return dispatchInProcess(c, ctx);
-        // Resolve the upstream base URL + bearer key (local runner vs the DB-backed key pool), then
-        // forward + meter. A failure is already observed and returned ready-to-send.
-        const target = await resolveUpstreamTarget(c, ctx);
-        if ('failure' in target)
-            return target.failure;
-        leasedApiKeyId = target.leasedApiKeyId;
-        return relayUpstream(c, ctx, target);
+            executionId: session.executionId,
+            agentKind: session.agentKind,
+            model: `${session.provider}:${session.model}`,
+            usage: { inputTokens, outputTokens },
+        });
+    };
+    // The per-call state the dispatch helpers below thread through; `observe` / `record` stay
+    // bound to this handler's mutable `requestMaxTokens` / `leasedApiKeyId`.
+    const ctx = {
+        session,
+        payload,
+        streaming,
+        promptText,
+        log,
+        gateways,
+        apiKeys,
+        localModelEndpoints,
+        waitUntil,
+        observe,
+        record,
+    };
+    // Workers AI (and any binding-reached provider) has no external upstream: run it in-process
+    // via the facade's gateway. Null-provider (e.g. Node can't) surfaces as unavailable.
+    if (session.provider === 'workers-ai')
+        return dispatchInProcess(c, ctx);
+    // Resolve the upstream base URL + bearer key (local runner vs the DB-backed key pool), then
+    // forward + meter. A failure is already observed and returned ready-to-send.
+    const target = await resolveUpstreamTarget(c, ctx);
+    if ('failure' in target)
+        return target.failure;
+    leasedApiKeyId = target.leasedApiKeyId;
+    return relayUpstream(c, ctx, target);
+}
+export function llmProxyController() {
+    const app = new Hono();
+    const limit = bodyLimit({
+        maxSize: MAX_PROXY_BODY_BYTES,
+        onError: (c) => c.json({ error: { code: 'payload_too_large', message: 'Request body exceeds size limit' } }, 413),
     });
+    for (const path of COMPLETIONS_PATHS)
+        app.post(path, limit, handleChatCompletion);
     return app;
 }
 /** Pull the assistant text out of a buffered completion (empty when tool-only). */