@m6d/cortex-server 1.7.0 → 2.0.0

package/src/lib/ai/finish-turn.ts

@@ -0,0 +1,75 @@
+import type { ResolvedCortexAgentConfig } from "@/config";
+import type { ChatMessage, Thread } from "@/types";
+import { notify } from "@/ws/connections";
+import { toThreadSummary } from "@/types";
+import { optimizeThreadContext } from "./context/optimize-thread-context";
+import type { CapturedStep } from "./inspector";
+
+type FinishTurnOptions = {
+    /** What this run produced — the only messages the turn writes. */
+    messages: ChatMessage[];
+    /** The thread including them, which is what a summary has to be judged against. */
+    threadMessages: ChatMessage[];
+    isAborted: boolean;
+    assistantMessageId: string | undefined;
+    thread: Thread;
+    userId: string;
+    capturedSteps: CapturedStep[];
+    config: ResolvedCortexAgentConfig;
+};
+
+/**
+ * Persists everything a completed turn produced, then tells the client to refetch.
+ *
+ * The thread is re-read first: it may have been deleted mid-stream, in which case
+ * there is nothing to write to and the whole turn is discarded.
+ */
+export async function finishTurn(options: FinishTurnOptions) {
+    const { messages, threadMessages, isAborted, assistantMessageId, thread, userId } = options;
+    const { capturedSteps, config } = options;
+
+    const persistedThread = await config.db.threads.getById(userId, thread.id);
+    if (!persistedThread) return;
+
+    await config.db.messages.upsert(thread.id, messages);
+    await persistCapturedSteps(capturedSteps, assistantMessageId, config);
+
+    config.onStreamFinish?.({ messages: threadMessages, isAborted });
+
+    // The turn's terminal event is held back until this write lands, so a client
+    // that refetches on stream end already sees committed rows. This event exists
+    // for the other tabs and devices, which have no stream of their own.
+    notify(userId, persistedThread.agentId, {
+        type: "thread:messages-updated",
+        payload: { threadId: thread.id, thread: toThreadSummary(persistedThread, false) },
+    });
+
+    // Fire-and-forget: the terminal event is waiting on this function, and
+    // summarizing the thread must not be what a user waits for.
+    optimizeThreadContext(thread, threadMessages, config).catch((err: unknown) => {
+        console.error("[cortex-server] Context optimization failed:", err);
+    });
+}
+
+/** Debug data only — losing it must never fail an otherwise-good turn. */
+async function persistCapturedSteps(
+    capturedSteps: CapturedStep[],
+    messageId: string | undefined,
+    config: ResolvedCortexAgentConfig,
+) {
+    if (capturedSteps.length === 0 || !messageId) return;
+
+    try {
+        await config.db.llmRequests.insert(
+            capturedSteps.map((step, index) => ({
+                messageId,
+                stepNumber: index,
+                prompt: step.prompt,
+                output: step.output,
+                tokenUsage: step.tokenUsage,
+            })),
+        );
+    } catch (err) {
+        console.error("[cortex-server] Failed to persist AI requests:", err);
+    }
+}

package/src/lib/ai/helpers.ts

@@ -0,0 +1,100 @@
+import { OpenAICompatibleChatAdapter } from "@tanstack/ai-openai/compatible";
+import OpenAI from "openai";
+
+/** Everything cortex needs to reach one OpenAI-compatible chat endpoint. */
+export type ProviderConfig = {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+    providerName?: string;
+};
+
+/**
+ * `openaiCompatible()` drops streamed reasoning: its `extractReasoning` hook is
+ * a no-op and nothing shipped overrides it. Cortex renders thinking parts, so it
+ * takes the sanctioned subclass seam and reads the `reasoning_content` delta.
+ */
+class ReasoningChatAdapter extends OpenAICompatibleChatAdapter<string> {
+    protected override extractReasoning(chunk: unknown) {
+        const delta = (chunk as { choices?: { delta?: { reasoning_content?: string } }[] })
+            .choices?.[0]?.delta;
+        return delta?.reasoning_content ? { text: delta.reasoning_content } : undefined;
+    }
+}
+
+/**
+ * `fetch` is how the caller observes or rewrites the raw HTTP exchange — the LLM
+ * inspector captures through it, the vision model adapts `max_tokens` through it.
+ */
+export function createModel(
+    config: ProviderConfig,
+    options: { name?: string; fetch?: typeof globalThis.fetch } = {},
+) {
+    const client = new OpenAI({
+        baseURL: config.baseURL,
+        apiKey: config.apiKey,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+
+    return new ReasoningChatAdapter(
+        client,
+        config.modelName,
+        config.providerName ?? options.name ?? "default",
+    );
+}
+
+const visionModels = new WeakMap<object, ReturnType<typeof createModel>>();
+
+/** Vision calls cap output tokens, so they need the max_tokens parameter shim. */
+export function createVisionModel(config: ProviderConfig) {
+    const cached = visionModels.get(config);
+    if (cached) return cached;
+
+    const model = createModel(config, {
+        name: "vision",
+        fetch: createMaxTokensAdaptingFetch(),
+    });
+    visionModels.set(config, model);
+    return model;
+}
+
+export async function streamToBase64(stream: ReadableStream<Uint8Array>) {
+    return new Response(stream)
+        .arrayBuffer()
+        .then((buffer) => Buffer.from(buffer).toString("base64"));
+}
+
+/**
+ * OpenAI's newer models reject `max_tokens` in favor of `max_completion_tokens`,
+ * while most OpenAI-compatible gateways only accept `max_tokens`. Retry once on
+ * that specific rejection and remember the answer for this fetch's lifetime.
+ */
+export function createMaxTokensAdaptingFetch() {
+    let renameMaxTokens = false;
+
+    function renamed(init?: RequestInit) {
+        if (typeof init?.body !== "string") return init;
+        const body = JSON.parse(init.body) as Record<string, unknown>;
+        if (!("max_tokens" in body)) return init;
+        body["max_completion_tokens"] = body["max_tokens"];
+        delete body["max_tokens"];
+        return { ...init, body: JSON.stringify(body) };
+    }
+
+    async function adaptiveFetch(input: string | URL | Request, init?: RequestInit) {
+        if (renameMaxTokens) return fetch(input, renamed(init));
+
+        const response = await fetch(input, init);
+        if (response.status === 400) {
+            const text = await response.clone().text();
+            if (text.includes("max_completion_tokens")) {
+                renameMaxTokens = true;
+                return fetch(input, renamed(init));
+            }
+        }
+        return response;
+    }
+
+    // Bun's fetch type carries preconnect; delegate so the provider accepts the shim.
+    return Object.assign(adaptiveFetch, { preconnect: fetch.preconnect });
+}

package/src/lib/ai/index.ts

@@ -0,0 +1,408 @@
+import {
+    chat,
+    chatParamsFromRequest,
+    convertMessagesToModelMessages,
+    generateMessageId,
+    maxIterations,
+    mergeAgentTools,
+    normalizeToUIMessage,
+    resumeServerSentEventsResponse,
+    toServerSentEventsResponse,
+    type UIMessage,
+} from "@tanstack/ai";
+import { HTTPException } from "hono/http-exception";
+import type { ResolvedCortexAgentConfig, ToolSet } from "@/config";
+import type { ChatMessage, MessageMetadata, Thread } from "@/types";
+import { createModel } from "./helpers";
+import { buildSystemPrompt, resolveSession } from "./prompt";
+import { ControlCenterClient } from "@/cc/client";
+import { getControlCenterConfig } from "@/cc/config-cache";
+import { buildPromptVariables } from "@/cc/format";
+import { getRecentCcTools } from "@/cc/registry";
+import { createEmbedder, createNeo4jClient } from "@cortex/contracts/graph";
+import { resolveFromGraph } from "@/graph/resolver";
+import { notify } from "@/ws/connections";
+import { buildContextMessages, trimMessagesToFit } from "./context/builder";
+import { estimateTokens } from "./context/token-estimator";
+import { createCompressionMiddleware } from "./context/compression-middleware";
+import { createCcRuntime } from "./cc-runtime";
+import {
+    buildTurnTools,
+    createToolInstrumentation,
+    hasDefaultAttachmentInterceptor,
+} from "./turn-tools";
+import { createInspector } from "./inspector";
+import { commitBeforeTerminal } from "./commit-gate";
+import { finishTurn } from "./finish-turn";
+import { endRun, isRunning, joinLog, producerLog, startRun } from "./active-runs";
+import { toThreadSummary } from "@/types";
+import { buildAttachmentListing, prepareAttachmentsForTurn } from "./attachments";
+
+/** The AG-UI request body, as the route parsed it. */
+export type TurnParams = Awaited<ReturnType<typeof chatParamsFromRequest>>;
+
+/** Cortex's agentic loop cap; the SDK's own default is 5. */
+const MAX_ITERATIONS = 25;
+
+export async function startTurn(
+    params: TurnParams,
+    thread: Thread,
+    userId: string,
+    token: string,
+    requestContext: Record<string, unknown>,
+    config: ResolvedCortexAgentConfig,
+) {
+    const run = await startRun(thread.id);
+    try {
+        // The client owns its own messages, and the assistant turn it sends back
+        // once a client-side tool has answered — without that answer stored, the
+        // next turn replays an assistant message whose tool calls nothing ever
+        // resolved, and the provider rejects the thread from there on. Everything
+        // else the server generated stays the server's; the repository keeps the
+        // usage and model id only it ever knew.
+        const incoming = params.messages
+            .map((message) => toChatMessage(normalizeToUIMessage(message, generateMessageId)))
+            .filter((message) => message.role === "user" || answersToolCalls(message));
+        await config.db.messages.upsert(thread.id, incoming);
+
+        const lastUserMessage = incoming.findLast((message) => message.role === "user");
+        const prompt = textOf(lastUserMessage);
+        if (thread.title === null && prompt) {
+            void generateTitle(thread.id, prompt, userId, config);
+        }
+
+        const updatedThread = await config.db.threads.touch(thread.id);
+
+        // A stop can land while the claim exists but before the run is
+        // announced; announcing anyway would put run-started after the abort's
+        // run-finished and pin the thread as running on every other tab. No
+        // await sits between this check and the notify, so once it passes the
+        // abort's run-finished can only follow the announcement.
+        if (run.abortController.signal.aborted) {
+            releaseRun(thread.id, run.runId);
+            return null;
+        }
+
+        notify(userId, thread.agentId, {
+            type: "thread:run-started",
+            payload: { thread: toThreadSummary(updatedThread, true) },
+        });
+
+        const threadAttachments = lastUserMessage
+            ? await prepareAttachmentsForTurn({
+                  config,
+                  threadId: thread.id,
+                  userId,
+                  message: lastUserMessage,
+                  abortSignal: run.abortController.signal,
+              })
+            : await config.db.attachments.listByThread(thread.id, userId);
+
+        // Claiming rewrites the message the user just sent, and the tabs that did
+        // not send it are already showing that message — with the run underway,
+        // this is their only chance to learn which files it carries.
+        if (threadAttachments.some((attachment) => attachment.messageId === lastUserMessage?.id)) {
+            notify(userId, thread.agentId, {
+                type: "thread:messages-updated",
+                payload: { threadId: thread.id, thread: toThreadSummary(updatedThread, true) },
+            });
+        }
+
+        const turnKey = lastUserMessage?.id ?? "0";
+
+        const inspector = createInspector();
+        const { model, embed, neo4j, ccClient } = createTurnProviders(config, inspector.fetch);
+
+        // Run independent operations in parallel
+        const [contextResult, resolved, session, ccConfig, ccResolved] = await Promise.all([
+            // Branch A: Load messages + build token-aware context window
+            buildContextMessages(userId, thread, config.db, config.context),
+            // Branch B: Resolve graph context (400-2000ms, the bottleneck)
+            neo4j && embed
+                ? resolveFromGraph(prompt, { neo4j, embed, reranker: config.reranker })
+                : Promise.resolve(null),
+            // Branch C: Resolve session data
+            resolveSession(config, thread, token),
+            // Branch D: Control Center config (ETag-revalidated, last-known-good on outage)
+            ccClient
+                ? getControlCenterConfig(ccClient, config.agentId, run.abortController.signal)
+                : Promise.resolve(null),
+            // Branch E: Control Center /resolve — on failure the turn degrades to
+            // the search meta-tools, it never blocks
+            ccClient && prompt
+                ? ccClient.resolve(
+                      config.agentId,
+                      {
+                          query: prompt,
+                          hints: {
+                              threadId: thread.id,
+                              recentToolNames: getRecentCcTools(thread.id),
+                          },
+                      },
+                      run.abortController.signal,
+                  )
+                : Promise.resolve(null),
+        ]);
+
+        const cc = createCcRuntime({
+            ccClient,
+            ccConfig,
+            ccResolved,
+            config,
+            thread,
+            userId,
+            token,
+            turnKey,
+            abortSignal: run.abortController.signal,
+            getStepIndex: () => inspector.steps.length,
+            onToolProgress: (toolName, toolCallId, status) =>
+                emitToolProgress(userId, thread, toolName, toolCallId, status),
+        });
+
+        const { messages: contextMessages, allMessages } = contextResult;
+
+        const turnToolsOptions = {
+            config,
+            cc,
+            neo4j,
+            thread,
+            userId,
+            token,
+            session,
+            requestContext,
+            threadAttachments,
+        };
+        const tools = buildTurnTools(turnToolsOptions);
+        const instrumentation = createToolInstrumentation({
+            ...turnToolsOptions,
+            onToolStart: (toolName, toolCallId) =>
+                emitToolProgress(userId, thread, toolName, toolCallId, "started"),
+            onToolFinish: (toolName, toolCallId) =>
+                emitToolProgress(userId, thread, toolName, toolCallId, "finished"),
+        });
+
+        const systemPrompt = await buildSystemPrompt(
+            config,
+            resolved,
+            { session, requestContext },
+            cc
+                ? {
+                      config: cc.config,
+                      resolved: ccResolved,
+                      variables: buildPromptVariables(cc.config.promptVariables, {
+                          ...session,
+                          ...requestContext,
+                          locale: cc.locale,
+                      }),
+                  }
+                : undefined,
+            buildAttachmentListing(threadAttachments, lastUserMessage?.id, {
+                readAttachment: tools.some((tool) => tool.name === "readAttachment"),
+                attachmentSentinels: hasDefaultAttachmentInterceptor(config),
+            }),
+        );
+
+        const stream = chat({
+            adapter: model,
+            // Client tool declarations ride in on every request, so the server
+            // never re-declares them.
+            tools: mergeAgentTools(tools, params.tools),
+            messages: convertMessagesToModelMessages(
+                fitToContextWindow(contextMessages, systemPrompt, tools, config),
+            ),
+            systemPrompts: [systemPrompt],
+            agentLoopStrategy: maxIterations(MAX_ITERATIONS),
+            abortController: run.abortController,
+            middleware: [
+                createCompressionMiddleware(config),
+                ...(instrumentation ? [instrumentation] : []),
+                inspector.middleware,
+            ],
+            threadId: thread.id,
+            runId: run.runId,
+        });
+
+        const producer = toServerSentEventsResponse(
+            commitBeforeTerminal(stream, {
+                isAborted: () => run.abortController.signal.aborted,
+                commit: async function (produced) {
+                    const messages = produced.map(toChatMessage).map(withTurnMetadata);
+                    await finishTurn({
+                        messages,
+                        // Summarization and the consumer hook judge the thread, not
+                        // the turn — the run's own output is only its tail.
+                        threadMessages: [...allMessages, ...messages],
+                        isAborted: run.abortController.signal.aborted,
+                        assistantMessageId: messages.at(-1)?.id,
+                        thread,
+                        userId,
+                        capturedSteps: inspector.steps,
+                        config,
+                    });
+                },
+            }),
+            {
+                // Append per chunk rather than per batch of 32: a client joining
+                // the log is waiting on real tokens, not on a buffer filling up.
+                durability: { adapter: producerLog(run.runId), batch: 1 },
+                abortController: run.abortController,
+            },
+        );
+
+        function withTurnMetadata(message: ChatMessage, index: number, all: ChatMessage[]) {
+            if (index !== all.length - 1 || message.role !== "assistant") return message;
+
+            return {
+                ...message,
+                metadata: {
+                    modelId: inspector.modelId,
+                    isAborted: run.abortController.signal.aborted,
+                    tokenUsage: inspector.tokenUsage,
+                } satisfies MessageMetadata,
+            };
+        }
+
+        // Generation outlives the request that started it, so a reload mid-turn
+        // rejoins the log instead of restarting the model. Draining into a sink
+        // that never cancels is what detaches the producer from this response;
+        // the client gets a reader on the same log.
+        void producer
+            .body!.pipeTo(new WritableStream())
+            .catch(() => undefined)
+            .finally(() => releaseRun(thread.id, run.runId));
+
+        return resumeServerSentEventsResponse({ adapter: joinLog(thread.id, run.runId) });
+    } catch (error) {
+        releaseRun(thread.id, run.runId);
+        throw error;
+    }
+}
+
+/** Releasing the claim must never mask the turn's own error or reject unhandled. */
+function releaseRun(threadId: string, runId: string) {
+    endRun(threadId, runId).catch((error: unknown) =>
+        console.error("[cortex-server] Failed to release run claim:", error),
+    );
+}
+
+/** Drops the SDK's transport shape into the envelope cortex persists and serves. */
+function toChatMessage(message: UIMessage) {
+    return { id: message.id, role: message.role, parts: message.parts } satisfies ChatMessage;
+}
+
+/**
+ * An assistant turn the client is sending back because it resolved a tool call.
+ *
+ * The wire fans that turn out into a `role: "tool"` message per result, and each
+ * of those normalizes back into an assistant message carrying only the result,
+ * under a freshly generated id. Stored as rows of their own they would replay as
+ * assistant turns answering calls that no message makes, so the turn is picked
+ * out by holding both halves of the exchange.
+ */
+function answersToolCalls(message: ChatMessage) {
+    return (
+        message.role === "assistant" &&
+        message.parts.some((part) => part.type === "tool-call") &&
+        message.parts.some((part) => part.type === "tool-result")
+    );
+}
+
+function textOf(message: ChatMessage | undefined) {
+    const part = message?.parts.find((candidate) => candidate.type === "text");
+    return part?.type === "text" ? part.content : "";
+}
+
+/**
+ * Builds the clients one turn needs. Neo4j runs vector search through an embedding
+ * model, so configuring a graph without one is a misconfiguration we surface
+ * loudly rather than quietly serving every turn with no graph context.
+ */
+function createTurnProviders(config: ResolvedCortexAgentConfig, fetch: typeof globalThis.fetch) {
+    if (config.neo4j && !config.embedding) {
+        throw new HTTPException(500, {
+            message: "embedding config is required when neo4j is configured",
+        });
+    }
+
+    const embed = config.embedding ? createEmbedder(config.embedding) : undefined;
+
+    return {
+        // The inspector's fetch is per-turn, so the model is too.
+        model: createModel(config.model, { fetch }),
+        embed,
+        neo4j: config.neo4j && embed ? createNeo4jClient(config.neo4j, embed) : undefined,
+        ccClient: config.controlCenter ? new ControlCenterClient(config.controlCenter) : null,
+    };
+}
+
+/**
+ * The context builder reserved a static token budget for the system prompt and
+ * tools before either existed. Now that both are real, drop the oldest messages
+ * if the reserve fell short.
+ */
+function fitToContextWindow(
+    contextMessages: ChatMessage[],
+    systemPrompt: string,
+    tools: ToolSet,
+    config: ResolvedCortexAgentConfig,
+) {
+    const actualFixedCost = estimateTokens(systemPrompt) + estimateTokens(JSON.stringify(tools));
+    const { reservedTokenBudget, maxContextTokens } = config.context;
+    if (actualFixedCost <= reservedTokenBudget) return contextMessages;
+
+    return trimMessagesToFit(contextMessages, maxContextTokens - actualFixedCost);
+}
+
+const TITLE_SYSTEM_PROMPT = `You are an expert in generating titles for threads of chats
+given the first message in that thread.
+
+When asked, only respond with the title without saying you're
+going to do so or any other speech. Spit out only the title.`;
+
+export async function generateTitle(
+    threadId: string,
+    prompt: string,
+    userId: string,
+    config: ResolvedCortexAgentConfig,
+) {
+    const title = await chat({
+        adapter: createModel(config.model, { name: "title" }),
+        stream: false,
+        systemPrompts: [TITLE_SYSTEM_PROMPT],
+        messages: [
+            {
+                id: generateMessageId(),
+                role: "user",
+                parts: [{ type: "text", content: `Generate a title for this prompt: ${prompt}` }],
+            },
+        ],
+    });
+
+    // A failed generation resolves to empty text rather than throwing, and the
+    // only trigger for a retry is the title still being null — so writing "" here
+    // would leave the thread permanently unnamed.
+    if (!title) return;
+
+    await config.db.threads.updateTitle(threadId, title);
+
+    const thread = await config.db.threads.getById(userId, threadId);
+    if (!thread) return;
+
+    notify(userId, thread.agentId, {
+        type: "thread:title-updated",
+        payload: { thread: toThreadSummary(thread, await isRunning(thread.id)) },
+    });
+}
+
+function emitToolProgress(
+    userId: string,
+    thread: Thread,
+    toolName: string,
+    toolCallId: string,
+    status: "started" | "finished",
+) {
+    notify(userId, thread.agentId, {
+        type: "thread:tool-progress",
+        payload: { threadId: thread.id, toolCallId, toolName, status },
+    });
+}

package/src/lib/ai/inspector.ts

@@ -0,0 +1,112 @@
+import type { ChatMiddleware, TokenUsage as ProviderTokenUsage } from "@tanstack/ai";
+import type { TokenUsage } from "@/types";
+
+/** One model call's raw exchange, as the LLM request inspector renders it. */
+export type CapturedStep = {
+    prompt: string;
+    output: string | null;
+    tokenUsage: TokenUsage | null;
+};
+
+/**
+ * Watches one turn's model calls. The SDK's `debug` logger reports call metadata
+ * but never raw bodies, so the raw exchange is captured where it actually
+ * exists — on the HTTP client — while usage arrives through middleware.
+ */
+export function createInspector() {
+    const steps: CapturedStep[] = [];
+    let modelId = "";
+    let tokenUsage: TokenUsage | undefined;
+
+    async function capturingFetch(input: string | URL | Request, init?: RequestInit) {
+        const step: CapturedStep = {
+            prompt: typeof init?.body === "string" ? init.body : "",
+            output: null,
+            tokenUsage: null,
+        };
+        steps.push(step);
+
+        const response = await fetch(input, init);
+        // Drain a tee rather than the response itself: the model call must keep
+        // streaming at full speed, and losing debug data must never fail a turn.
+        void response
+            .clone()
+            .text()
+            .then(function (text) {
+                step.output = text;
+            })
+            .catch(() => undefined);
+
+        return response;
+    }
+
+    const middleware: ChatMiddleware = {
+        name: "cortex-inspector",
+        onUsage(ctx, usage) {
+            modelId = ctx.model;
+            const stepUsage = toTokenUsage(usage);
+            const lastStep = steps.at(-1);
+            if (lastStep) lastStep.tokenUsage = stepUsage;
+            tokenUsage = addTokenUsage(tokenUsage, stepUsage);
+        },
+    };
+
+    return {
+        steps,
+        middleware,
+        // Bun's fetch type carries preconnect; delegate so the client accepts the shim.
+        fetch: Object.assign(capturingFetch, { preconnect: fetch.preconnect }),
+        get modelId() {
+            return modelId;
+        },
+        get tokenUsage() {
+            return tokenUsage;
+        },
+    };
+}
+
+/**
+ * Flattens the provider's usage shape into ours. The provider reports cached and
+ * cache-written prompt tokens but no uncached counter, so that dimension is the
+ * remainder — which is what makes the client's breakdown add up to the total.
+ */
+export function toTokenUsage(usage: ProviderTokenUsage) {
+    const cacheRead = usage.promptTokensDetails?.cachedTokens ?? 0;
+    const cacheWrite = usage.promptTokensDetails?.cacheWriteTokens ?? 0;
+    const reasoning = usage.completionTokensDetails?.reasoningTokens ?? 0;
+
+    return {
+        input: {
+            noCache: Math.max(usage.promptTokens - cacheRead - cacheWrite, 0),
+            cacheRead,
+            cacheWrite,
+            total: usage.promptTokens,
+        },
+        output: {
+            reasoning,
+            text: usage.completionTokensDetails?.textTokens ?? usage.completionTokens - reasoning,
+            total: usage.completionTokens,
+        },
+        total: usage.totalTokens,
+    } satisfies TokenUsage;
+}
+
+/** The agent loop reports usage per iteration; a turn's cost is their sum. */
+function addTokenUsage(left: TokenUsage | undefined, right: TokenUsage) {
+    if (!left) return right;
+
+    return {
+        input: {
+            noCache: left.input.noCache + right.input.noCache,
+            cacheRead: left.input.cacheRead + right.input.cacheRead,
+            cacheWrite: left.input.cacheWrite + right.input.cacheWrite,
+            total: left.input.total + right.input.total,
+        },
+        output: {
+            reasoning: left.output.reasoning + right.output.reasoning,
+            text: left.output.text + right.output.text,
+            total: left.output.total + right.output.total,
+        },
+        total: left.total + right.total,
+    } satisfies TokenUsage;
+}