dsh-lcx-codex 0.4.3-pre.4 → 0.4.3

package/lib/responses-request.js

@@ -1,5 +1,5 @@
 // @ts-check
-import { clampOpenAIPromptCacheKey } from "@earendil-works/pi-ai/api/openai-prompt-cache";
+import { clampOpenAIPromptCacheKey } from "./pi-responses-runtime.js";
 import { responsesTools } from "./dsh-responses.js";
 const OPENAI_RESPONSES_MIN_OUTPUT_TOKENS = 16;
 /** @param {unknown} value */

package/lib/responses-stream.js

@@ -1,9 +1,8 @@
 // @ts-check
-import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
-import { processResponsesStream } from "@earendil-works/pi-ai/api/openai-responses-shared";
+import { createAssistantMessageEventStream, processResponsesStream, } from "./pi-responses-runtime.js";
 import { ToolCallId } from "@deepseek-ai/dsh-llm";
 import { fetchSseWithRetry } from "./transport.js";
-import { createGrokNativeReplayEnvelope, } from "./grok-native-search.js";
+import { createGrokNativeReplayEnvelope, grokPendingSourcesStart, sanitizeGrokVisibleText, } from "./grok-native-search.js";
 function emptyUsage() {
     return {
         input: 0,
@@ -92,9 +91,15 @@ export function managedFailure(error, signal) {
         code = "ABORTED";
     else if (sourceCodes.has("LCX_RESPONSES_UNSUPPORTED_OPTION"))
         code = "UNSUPPORTED_OPTION";
+    else if (sourceCodes.has("LCX_CHECKPOINT_PORTABLE_UNSUPPORTED_CONTENT"))
+        code = "UNSUPPORTED_CONTENT";
+    else if (sourceCodes.has("LCX_GROK_NATIVE_PROTOCOL_ERROR"))
+        code = "GROK_NATIVE_PROTOCOL_ERROR";
     else if (sourceCodes.has("LCX_RESPONSES_ROUTE_UNAVAILABLE") ||
         sourceCodes.has("LCX_RESPONSES_MODEL_UNAVAILABLE"))
         code = "NO_ADAPTER";
+    else if (sourceCodes.has("LCX_INSUFFICIENT_QUOTA"))
+        code = "INSUFFICIENT_QUOTA";
     else if (facts.status === 401 ||
         facts.status === 403 ||
         sourceCodes.has("AUTH") ||
@@ -128,6 +133,7 @@ export function managedFailure(error, signal) {
     const messages = /** @type {Record<string, string>} */ {
         ABORTED: "Responses request was aborted",
         AUTH: "Responses request was rejected by authentication",
+        INSUFFICIENT_QUOTA: "服务商额度不足或未满足请求预留额度，请检查中转额度（并非 API 密钥无效） / Provider quota is insufficient for this request",
         UNSUPPORTED_OPTION: "LCX Responses does not support this request option",
         NO_ADAPTER: "LCX could not resolve the selected Responses route",
         RATE_LIMIT: "Responses provider rate limit was reached",
@@ -136,6 +142,8 @@ export function managedFailure(error, signal) {
             ? "Unsupported or invalid LCX checkpoint; start a new session"
             : "Responses provider rejected the request",
         CONTEXT_WINDOW_EXCEEDED: "Responses request exceeded the model context window",
+        UNSUPPORTED_CONTENT: "LCX cannot serialize a DSH content block for this Responses route",
+        GROK_NATIVE_PROTOCOL_ERROR: "Grok returned an unrecognized client tool call while native search was enabled",
         TIMEOUT: "Responses request timed out",
         TRANSPORT: "Responses transport failed",
         RESPONSES_ERROR: "Responses request failed",
@@ -484,6 +492,27 @@ function itemText(item) {
         return String(item.input ?? "");
     return "";
 }
+function itemAnnotations(item) {
+    if (item.type !== "message" || !Array.isArray(item.content))
+        return [];
+    return item.content.flatMap((part) => isObject(part) && Array.isArray(part.annotations) ? part.annotations : []);
+}
+function sanitizeGrokTerminalItem(item, index) {
+    const normalized = normalizedTerminalItem(item, index);
+    if (normalized.type !== "message" || !Array.isArray(normalized.content))
+        return normalized;
+    return {
+        ...normalized,
+        content: normalized.content.map((part) => {
+            if (!isObject(part) || (part.type !== "output_text" && part.type !== "refusal"))
+                return structuredClone(part);
+            const text = sanitizeGrokVisibleText(String(part.text ?? part.refusal ?? ""), Array.isArray(part.annotations) ? part.annotations : []);
+            return part.type === "output_text"
+                ? { ...structuredClone(part), text }
+                : { ...structuredClone(part), refusal: text };
+        }),
+    };
+}
 /** @param {UnknownRecord} item @param {number} index */
 function normalizedTerminalItem(item, index) {
     if (item.type === "message")
@@ -574,42 +603,60 @@ function recordMatches(record, item) {
  */
 async function* normalizedResponseEvents(source, meta = {}, options = {}) {
     const open = new Map();
-    const completed = new Set();
-    const completedWireItems = new Map();
-    const serverToolIds = new Map();
-    const citations = new Map();
-    const observeCitation = (candidate) => {
-        if (!isObject(candidate))
-            return;
-        try {
-            const url = new URL(String(candidate.url ?? ""));
-            if (url.protocol !== "http:" && url.protocol !== "https:")
-                return;
-            const title = typeof candidate.title === "string"
-                ? candidate.title.replace(/[\r\n]+/gu, " ").trim()
-                : "";
-            if (!citations.has(url.href))
-                citations.set(url.href, title);
+    const grokTextProjection = new Map();
+    const hiddenPrefixTokens = ["sources:", "render_inline_citation", "{render_inline_citation", "render_inline_citation", "stateless_invoke", "[[", "<|eos|>"];
+    const safeGrokRawPrefix = (raw, final) => {
+        if (final)
+            return raw;
+        const lower = raw.toLowerCase();
+        let holdStart = raw.length;
+        const pendingSource = grokPendingSourcesStart(raw);
+        if (pendingSource !== undefined)
+            holdStart = Math.min(holdStart, pendingSource);
+        for (const token of hiddenPrefixTokens) {
+            const complete = lower.lastIndexOf(token);
+            if (complete >= 0) {
+                const tail = raw.slice(complete);
+                if (sanitizeGrokVisibleText(tail).toLowerCase().includes(token.replace(/^\{/u, "")))
+                    holdStart = Math.min(holdStart, complete);
+            }
+            const max = Math.min(token.length - 1, lower.length);
+            for (let size = max; size > 0; size -= 1) {
+                if (lower.endsWith(token.slice(0, size))) {
+                    holdStart = Math.min(holdStart, raw.length - size);
+                    break;
+                }
+            }
         }
-        catch { }
+        return raw.slice(0, holdStart);
     };
-    const observeCitations = (item) => {
-        if (!isObject(item))
-            return;
-        if (item.type === "message" && Array.isArray(item.content)) {
-            for (const part of item.content) {
-                if (!isObject(part) || part.type !== "output_text" || !Array.isArray(part.annotations))
-                    continue;
-                for (const annotation of part.annotations)
-                    if (isObject(annotation) && annotation.type === "url_citation")
-                        observeCitation(annotation);
-            }
+    const grokProjectionDelta = (index, rawText, final = false, annotations = []) => {
+        let state = grokTextProjection.get(index);
+        if (!state) {
+            state = { raw: "", emitted: "" };
+            grokTextProjection.set(index, state);
         }
-        // Search candidates are not answer citations. Only output_text annotations qualify.
+        state.raw = rawText;
+        const target = sanitizeGrokVisibleText(safeGrokRawPrefix(rawText, final), annotations);
+        if (!target.startsWith(state.emitted))
+            return "";
+        const delta = target.slice(state.emitted.length);
+        state.emitted = target;
+        if (final)
+            grokTextProjection.delete(index);
+        return delta;
     };
-    const isServerToolItem = (value) => isObject(value) && options.serverToolTypes?.has(String(value.type ?? "")) === true;
+    const completed = new Set();
+    const completedWireItems = new Map();
+    const hiddenServerToolIndexes = new Set();
+    const serverToolIds = new Map();
+    const nativeServerSearchEchoCallIds = new Set();
+    const isServerToolItem = (value) => isObject(value) && (options.serverToolTypes?.has(String(value.type ?? "")) === true ||
+        options.isServerToolItem?.(value) === true);
     const observeServerTool = (item) => {
         const type = String(item.type);
+        if (type === "custom_tool_call" && typeof item.call_id === "string")
+            nativeServerSearchEchoCallIds.add(item.call_id);
         let ids = serverToolIds.get(type);
         if (!ids) {
             ids = new Set();
@@ -645,8 +692,18 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
             event.type === "response.output_item.done") &&
             isServerToolItem(event.item)) {
             observeServerTool(event.item);
+            if (event.type === "response.output_item.added")
+                hiddenServerToolIndexes.add(index);
+            else
+                hiddenServerToolIndexes.delete(index);
             continue;
         }
+        if (hiddenServerToolIndexes.has(index) &&
+            (event.type === "response.custom_tool_call_input.delta" ||
+                event.type === "response.custom_tool_call_input.done" ||
+                event.type === "response.function_call_arguments.delta" ||
+                event.type === "response.function_call_arguments.done"))
+            continue;
         // Grok may send many encrypted reasoning items with no visible summary.
         // Keep them in completedWireItems/nativeOutput, but do not open empty UI blocks.
         if (options.serverToolTypes &&
@@ -655,9 +712,10 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
             !itemText(event.item).trim() && !open.get(index)?.text.trim())
             continue;
         if (event.type === "response.output_item.added" && isObject(event.item)) {
-            const item = normalizedTerminalItem(event.item, index);
-            open.set(index, { kind: itemKind(item), item, text: itemText(item) });
-            yield { ...event, item };
+            const rawItem = normalizedTerminalItem(event.item, index);
+            const item = options.serverToolTypes ? sanitizeGrokTerminalItem(rawItem, index) : rawItem;
+            open.set(index, { kind: itemKind(item), item: rawItem, text: itemText(rawItem) });
+            yield { ...event, item: options.serverToolTypes ? addedShell(item, index) : item };
             continue;
         }
         if (event.type === "response.output_text.delta") {
@@ -678,7 +736,13 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
                 record = next.value;
             }
             record.text = String(record.text ?? "") + String(event.delta ?? "");
-            yield event;
+            if (!options.serverToolTypes)
+                yield event;
+            else {
+                const delta = grokProjectionDelta(index, record.text);
+                if (delta)
+                    yield { ...event, delta };
+            }
             continue;
         }
         if (event.type === "response.reasoning_summary_text.delta" ||
@@ -756,7 +820,13 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
             continue;
         }
         if (event.type === "response.output_item.done" && isObject(event.item)) {
-            const item = normalizedTerminalItem(event.item, index);
+            const rawItem = normalizedTerminalItem(event.item, index);
+            const item = options.serverToolTypes ? sanitizeGrokTerminalItem(rawItem, index) : rawItem;
+            if (options.serverToolTypes && item.type === "message") {
+                const delta = grokProjectionDelta(index, itemText(rawItem), true, itemAnnotations(rawItem));
+                if (delta)
+                    yield { type: "response.output_text.delta", output_index: index, content_index: 0, item_id: item.id, delta };
+            }
             const identity = itemIdentity(item);
             if (identity)
                 completed.add(identity);
@@ -776,52 +846,36 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
                     .sort(([left], [right]) => left - right)
                     .map(([, item]) => item);
             const nativeOutput = terminalOutput.map((item) => structuredClone(item));
-            const nativeVisibleAdditions = [];
             for (const item of terminalOutput) {
-                observeCitations(item);
+                if (isServerToolItem(item) && isObject(item) && item.type === "custom_tool_call" &&
+                    item.status !== "completed")
+                    throw Object.assign(new Error("Grok native custom search item did not complete on the server"), { code: "LCX_GROK_NATIVE_PROTOCOL_ERROR" });
                 if (isServerToolItem(item))
                     observeServerTool(item);
+                else if (options.serverToolTypes && isObject(item) && item.type === "custom_tool_call" &&
+                    typeof item.name === "string" && options.declaredToolNames?.has(item.name) !== true)
+                    throw Object.assign(new Error(`Grok returned undeclared client custom tool "${item.name}"`), { code: "LCX_GROK_NATIVE_PROTOCOL_ERROR" });
             }
             const output = terminalOutput
                 .filter((item) => !isServerToolItem(item))
                 .filter((item) => !(options.serverToolTypes && isObject(item) &&
                 item.type === "reasoning" && !itemText(item).trim()))
                 .map((item, terminalIndex) => isObject(item)
-                ? normalizedTerminalItem(item, terminalIndex)
+                ? (options.serverToolTypes
+                    ? sanitizeGrokTerminalItem(item, terminalIndex)
+                    : normalizedTerminalItem(item, terminalIndex))
                 : item);
-            if (options.serverToolTypes && citations.size > 0) {
-                const visibleText = output
-                    .filter(isObject)
-                    .map((item) => itemText(item))
-                    .join("\n");
-                const missing = [...citations].filter(([url]) => !visibleText.includes(url));
-                if (missing.length > 0) {
-                    const suffix = missing
-                        .map(([url, title]) => `- ${title ? `${title}: ` : ""}${url}`)
-                        .join("\n");
-                    const responseId = String(response.id ?? "native")
-                        .replace(/[^A-Za-z0-9_-]/gu, "_")
-                        .slice(0, 40);
-                    const fallbackItem = {
-                        type: "message",
-                        id: `msg_lcx_sources_${responseId}`.slice(0, 64),
-                        role: "assistant",
-                        status: "completed",
-                        content: [{
-                                type: "output_text",
-                                text: `\n\nSources:\n${suffix}`,
-                                annotations: [],
-                            }],
-                    };
-                    output.push(fallbackItem);
-                    nativeVisibleAdditions.push(structuredClone(fallbackItem));
-                }
-            }
             if (event.type === "response.completed" &&
                 response.status === "completed" &&
                 options.serverToolTypes) {
                 meta.nativeOutput = nativeOutput;
-                meta.nativeVisibleAdditions = nativeVisibleAdditions;
+                meta.nativeServerSearchEchoCallIds = [...nativeServerSearchEchoCallIds];
+                const usage = isObject(response.usage) ? response.usage : {};
+                const details = isObject(usage.server_side_tool_usage_details) ? usage.server_side_tool_usage_details : {};
+                meta.inputTokenScope = serverToolIds.size > 0 || nativeOutput.some(isServerToolItem)
+                    || Number(usage.num_server_side_tools_used ?? 0) > 0
+                    || Number(details.web_search_calls ?? 0) > 0 || Number(details.x_search_calls ?? 0) > 0
+                    ? "aggregate" : "request";
             }
             const used = new Set();
             for (const [streamIndex, record] of open) {
@@ -838,6 +892,11 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
                     : normalizedTerminalItem(record.item, streamIndex);
                 if (terminalIndex >= 0)
                     used.add(terminalIndex);
+                if (options.serverToolTypes && item.type === "message") {
+                    const delta = grokProjectionDelta(streamIndex, itemText(item), true, itemAnnotations(item));
+                    if (delta)
+                        yield { type: "response.output_text.delta", output_index: streamIndex, content_index: 0, item_id: item.id, delta };
+                }
                 yield {
                     type: "response.output_item.done",
                     output_index: streamIndex,
@@ -848,6 +907,7 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
                     completed.add(identity);
             }
             open.clear();
+            grokTextProjection.clear();
             for (const [terminalIndex, candidate] of output.entries()) {
                 if (!isObject(candidate) ||
                     !itemKind(candidate) ||
@@ -939,15 +999,19 @@ function isManagedFailure(value) {
 }
 function dshUsage(usage) {
     const value = /** @type {UnknownRecord} */ isObject(usage) ? usage : {};
+    const inputTokens = Number(value.input ?? 0);
+    const outputTokens = Number(value.output ?? 0);
+    const cacheReadTokens = Number(value.cacheRead ?? 0);
+    const cacheWriteTokens = Number(value.cacheWrite ?? 0);
+    const reportedTotal = Number(value.totalTokens);
     return {
-        inputTokens: Number(value.input ?? 0),
-        outputTokens: Number(value.output ?? 0),
-        ...(Number(value.cacheRead ?? 0) > 0
-            ? { cacheReadTokens: Number(value.cacheRead) }
-            : {}),
-        ...(Number(value.cacheWrite ?? 0) > 0
-            ? { cacheWriteTokens: Number(value.cacheWrite) }
-            : {}),
+        inputTokens,
+        outputTokens,
+        totalTokens: Number.isSafeInteger(reportedTotal) && reportedTotal >= 0
+            ? reportedTotal
+            : inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
         ...(Number(value.reasoning ?? 0) > 0
             ? { reasoningTokens: Number(value.reasoning) }
             : {}),
@@ -963,7 +1027,7 @@ function rawArguments(value) {
     }
 }
 /** @param {unknown} message */
-function replayState(message, nativeOutput, nativeVisibleAdditions, nativeReplayRoute) {
+function replayState(message, nativeOutput, nativeReplayRoute, nativeServerSearchEchoCallIds = []) {
     if (!isObject(message))
         return undefined;
     const content = Array.isArray(message.content)
@@ -974,7 +1038,7 @@ function replayState(message, nativeOutput, nativeVisibleAdditions, nativeReplay
     const api = typeof message.api === "string" ? message.api : undefined;
     if (!provider || !model || !api)
         return undefined;
-    const grokNative = createGrokNativeReplayEnvelope(nativeOutput, nativeReplayRoute, nativeVisibleAdditions);
+    const grokNative = createGrokNativeReplayEnvelope(nativeOutput, nativeReplayRoute, nativeServerSearchEchoCallIds);
     return {
         response: {
             kind: "pi-ai",
@@ -1152,11 +1216,14 @@ async function* toDshChunks(events, signal, wireMeta, nativeReplayRoute) {
                 const reason = successfulFinish(message);
                 const replay = reason.kind === "error"
                     ? undefined
-                    : replayState(message, wireMeta?.nativeOutput, wireMeta?.nativeVisibleAdditions, nativeReplayRoute);
+                    : replayState(message, wireMeta?.nativeOutput, nativeReplayRoute, wireMeta?.nativeServerSearchEchoCallIds);
                 yield {
                     type: "finish",
                     reason,
-                    ...(replay === undefined ? {} : { replayState: replay }),
+                    ...(replay === undefined && !nativeReplayRoute ? {} : { replayState: {
+                            ...replay,
+                            response: { ...replay?.response, ...(nativeReplayRoute ? { lcxUsage: { version: 1, inputTokenScope: wireMeta?.inputTokenScope ?? "aggregate" } } : {}) },
+                        } }),
                 };
                 return;
             }
@@ -1185,6 +1252,7 @@ async function* toDshChunks(events, signal, wireMeta, nativeReplayRoute) {
                     reason: normalizedFailure.code === "ABORTED"
                         ? { kind: "aborted", failure: normalizedFailure }
                         : { kind: "error", failure: normalizedFailure },
+                    ...(nativeReplayRoute ? { replayState: { response: { lcxUsage: { version: 1, inputTokenScope: "aggregate" } } } } : {}),
                 };
                 return;
             }
@@ -1212,7 +1280,7 @@ async function* toDshChunks(events, signal, wireMeta, nativeReplayRoute) {
  * @param {ReadonlySet<string>} [options.serverToolTypes]
  * @param {(usage: ServerToolUsage) => void} [options.onServerToolUsage]
  */
-export async function* streamResponsesRequest({ baseURL, provider, model, piModel, body, grammarToolInputProperties, headers, signal, timeoutMs, applyDefaultTimeout = true, streamIdleTimeoutMs, maxAttempts = 1, maxResponseBytes, serverToolTypes, nativeReplayRoute, onServerToolUsage, }) {
+export async function* streamResponsesRequest({ baseURL, provider, model, piModel, body, grammarToolInputProperties, headers, signal, timeoutMs, applyDefaultTimeout = true, streamIdleTimeoutMs, maxAttempts = 1, maxResponseBytes, serverToolTypes, isServerToolItem, declaredToolNames, nativeReplayRoute, onServerToolUsage, }) {
     const effectiveTimeoutMs = timeoutMs ?? (applyDefaultTimeout ? 300_000 : undefined);
     const deadline = requestDeadline(signal, effectiveTimeoutMs);
     const watchdog = streamIdleWatchdog(deadline.signal, streamIdleTimeoutMs);
@@ -1239,7 +1307,7 @@ export async function* streamResponsesRequest({ baseURL, provider, model, piMode
                 await processResponsesStream(validatedResponseEvents(normalizedResponseEvents(responseEvents(response, {
                     signal: watchdog.signal,
                     maxResponseBytes,
-                }), wireMeta, { serverToolTypes, onServerToolUsage })), output, piEvents, piModel, { grammarToolInputProperties });
+                }), wireMeta, { serverToolTypes, isServerToolItem, declaredToolNames, onServerToolUsage })), output, piEvents, piModel, { grammarToolInputProperties });
                 if (typeof wireMeta.responseModel === "string" &&
                     wireMeta.responseModel.length > 0)
                     output.responseModel = wireMeta.responseModel;

package/lib/route.js

@@ -3,7 +3,7 @@ import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { SessionId } from "@deepseek-ai/dsh-session";
 import "@deepseek-ai/dsh-settings";
 import { attributionHeaders, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
-import { getBuiltinModels, getBuiltinProviders, } from "@earendil-works/pi-ai/providers/all";
+import { getBuiltinModels, getBuiltinProviders, } from "./pi-responses-runtime.js";
 /** @param {unknown} value */
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -102,6 +102,20 @@ function retryAttempts(policy, fallback = 3) {
 export function settingsValue(ctx, namespace) {
     return asLlmSettingsSection(ctx?.settings?.get(namespace));
 }
+/** The DSH 0.1.5 contract exposes deferred provider diagnostics separately from saved settings. */
+function providerDirectoryUsable(ctx, provider) {
+    const llm = ctx?.llm;
+    const list = llm?.listConfigurableProviders;
+    if (typeof list !== "function")
+        return true;
+    try {
+        const entry = list.call(llm).find((candidate) => candidate.provider === provider && candidate.settingsNs === "llm-pi-ai");
+        return typeof entry?.error !== "string" || entry.error.trim() === "";
+    }
+    catch {
+        return false;
+    }
+}
 /** @type {Set<keyof ResponsesCompat>} */
 const RESPONSES_COMPAT_FIELDS = new Set(["supportsDeveloperRole", "sessionAffinityFormat", "supportsStrictMode", "supportsLongCacheRetention", "supportsOpenAIGrammarTools", "supportsAdditionalTools", "supportsToolSearch", "supportsExplicitPromptCacheMode", "supportsMaxOutputTokens"]);
 /** @param {ResponsesCompat} target @param {unknown} source */
@@ -196,7 +210,7 @@ function isLcxCapabilityRoute(provider, model) {
 export function resolveResponsesRouteConfig(ctx, options, policy) {
     const provider = String(options?.provider ?? "");
     const model = String(options?.model ?? "");
-    if (!provider.trim() || !/^gpt-/iu.test(model))
+    if (!provider.trim() || !/^gpt-/iu.test(model) || !providerDirectoryUsable(ctx, provider))
         return undefined;
     const section = settingsValue(ctx, "llm-pi-ai");
     const profile = section?.providers?.[provider];
@@ -254,7 +268,7 @@ export function resolveResponsesRouteConfig(ctx, options, policy) {
 export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
     const provider = String(options?.provider ?? "");
     const model = String(options?.model ?? "");
-    if (!provider.trim() || !/^grok/iu.test(model))
+    if (!provider.trim() || !/^grok/iu.test(model) || !providerDirectoryUsable(ctx, provider))
         return undefined;
     const section = settingsValue(ctx, "llm-pi-ai");
     const configured = section?.providers?.[provider];

package/lib/search-accounting.js

@@ -0,0 +1,86 @@
+export const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const count = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+export const zeroBuckets = () => ({ uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 });
+export const isSearchTool = (name) => name === 'web_search' || name === 'websearch_gpt_advanced';
+export function auxiliaryUsageOf(event, toolName) {
+    if (!object(event) || event.type !== 'tool/result' || !object(event.data?.meta))
+        return [];
+    // Only our owned search results may contribute auxiliary billing.
+    // Official ToolMessageSource carries only callId; resolve its name from tool/call.
+    if (!isSearchTool(toolName))
+        return [];
+    const raw = event.data.meta.auxiliaryUsage;
+    if (!Array.isArray(raw))
+        return [];
+    const ids = new Set(), result = [];
+    for (const item of raw) {
+        if (!object(item) || typeof item.requestId !== 'string' || !item.requestId
+            || typeof item.provider !== 'string' || !item.provider || typeof item.model !== 'string' || !item.model
+            || !object(item.usage) || ids.has(item.requestId))
+            continue;
+        const u = item.usage;
+        if (![u.inputTokens, u.outputTokens, u.totalTokens, u.cacheReadTokens, u.cacheWriteTokens].every(count)
+            || u.inputTokens + u.outputTokens + u.cacheReadTokens + u.cacheWriteTokens !== u.totalTokens)
+            continue;
+        ids.add(item.requestId);
+        result.push(item);
+    }
+    return result;
+}
+export function addUsage(base, records) {
+    if (!records.length)
+        return base;
+    const next = { ...base };
+    for (const { usage: u } of records) {
+        next.uncachedInputTokens += u.inputTokens;
+        next.outputTokens += u.outputTokens;
+        next.cacheReadTokens += u.cacheReadTokens;
+        next.cacheWriteTokens += u.cacheWriteTokens;
+    }
+    if (!Object.values(next).every(count))
+        throw new Error('LCX search usage exceeds safe counters');
+    return next;
+}
+export function mergeBuckets(base, extra) {
+    if (!object(base) || Object.values(extra).every(n => n === 0))
+        return base;
+    const next = { ...base };
+    for (const key of Object.keys(extra)) {
+        // Keep unavailable host buckets unavailable rather than inventing zero.
+        if (count(base[key]))
+            next[key] = base[key] + extra[key];
+    }
+    return next;
+}
+export function addTurnUsage(base, records) {
+    if (!object(base) || !records.length || !count(base.totalTokens))
+        return base;
+    const next = mergeBuckets(base, addUsage(zeroBuckets(), records));
+    next.totalTokens = base.totalTokens + records.reduce((n, r) => n + r.usage.totalTokens, 0);
+    // Auxiliary responses do not always disclose a reasoning subset.
+    delete next.reasoningTokens;
+    if (Array.isArray(base.routes)) {
+        const routes = new Map();
+        for (const r of [...base.routes, ...records])
+            routes.set(`${r.provider}\0${r.model}`, { provider: r.provider, model: r.model });
+        next.routes = [...routes.values()];
+    }
+    return next;
+}
+/** The metadata is presentation/accounting state; it never changes request messages. */
+export function aggregateContextOf(event) {
+    if (!object(event) || !['assistant/message', 'assistant/attempt'].includes(event.type) || !object(event.data))
+        return;
+    const chunks = Array.isArray(event.data.stream) ? event.data.stream.filter((e) => e.type === 'chunk').map((e) => e.chunk) : [];
+    const sample = event.data.usage ?? chunks.findLast((c) => c?.type === 'usage')?.usage;
+    if (!object(sample))
+        return;
+    const replay = chunks.findLast((c) => c?.type === 'finish')?.replayState;
+    const mark = replay?.response?.lcxUsage;
+    if (mark?.version === 1 && ['request', 'aggregate'].includes(mark.inputTokenScope))
+        return mark.inputTokenScope === 'aggregate';
+    // Read the already-installed local candidate without rewriting its logs.
+    if (sample.inputTokenScope === 'aggregate' || sample.inputTokenScope === 'request')
+        return sample.inputTokenScope === 'aggregate';
+    return replay?.grokNative?.kind === 'xai-responses-native-search' && replay.grokNative.version === 3;
+}

package/lib/search-usage.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { SessionSeq } from '@deepseek-ai/dsh-session';
+import { addUsage, aggregateContextOf, auxiliaryUsageOf, isSearchTool, zeroBuckets } from './search-accounting.js';
+const n = z.number().int().nonnegative();
+const schema = z.object({ auxiliary: z.object({ uncachedInputTokens: n, outputTokens: n, cacheReadTokens: n, cacheWriteTokens: n }).strict(), aggregateContext: z.boolean() }).strict();
+/** Separate, durable extension: the host's own usage projection remains primary-call billing. */
+export const searchUsageProjection = {
+    key: 'lcxSearchUsage', stateVersion: 2, stateSchema: schema.extend({ pending: z.record(z.string(), z.string()) }),
+    init: () => ({ auxiliary: zeroBuckets(), aggregateContext: false, pending: {} }),
+    apply(state, event) {
+        if (event.type === 'tool/call' && isSearchTool(event.data.name))
+            return { ...state, pending: { ...state.pending, [event.data.callId]: event.data.name } };
+        const callId = event.type === 'tool/result' ? event.data.message.source.callId : undefined;
+        const auxiliary = addUsage(state.auxiliary, auxiliaryUsageOf(event, callId ? state.pending[callId] : undefined));
+        const aggregateContext = aggregateContextOf(event) ?? state.aggregateContext;
+        if (callId && Object.hasOwn(state.pending, callId)) {
+            const pending = { ...state.pending };
+            delete pending[callId];
+            return { auxiliary, aggregateContext, pending };
+        }
+        if (event.type === 'turn/end' && Object.keys(state.pending).length)
+            return { auxiliary, aggregateContext, pending: {} };
+        return auxiliary === state.auxiliary && aggregateContext === state.aggregateContext ? state : { ...state, auxiliary, aggregateContext };
+    },
+    wire: { viewSchema: schema, view: ({ auxiliary, aggregateContext }) => ({ auxiliary, aggregateContext }) },
+};
+const installed = new WeakMap();
+/** Own a reversible adapter on the public measure method, never a DSH file or private fold. */
+export function installSearchMeasurement(meter) {
+    const existing = installed.get(meter);
+    if (existing) {
+        existing.refs++;
+        let active = true;
+        return () => { if (active) {
+            active = false;
+            release(meter);
+        } };
+    }
+    const original = meter.measure, descriptor = Object.getOwnPropertyDescriptor(meter, 'measure');
+    const cursors = new WeakMap();
+    function measure(session, header) {
+        const value = original.call(this, session, header);
+        let state = cursors.get(session) ?? { seq: 0, aggregate: false };
+        while (state.seq < session.seq) {
+            const e = session.eventAt(SessionSeq(state.seq++));
+            if (e?.type === 'assistant/message')
+                state.aggregate = aggregateContextOf(e) ?? false;
+        }
+        cursors.set(session, state);
+        if (!state.aggregate || value.baseline.kind !== 'usage')
+            return value;
+        // The official measure already prices retained images/files and surface replacements.
+        // Only discard its unsuitable aggregate anchor; keep its current surface and node prices.
+        const tools = (header ?? session.requestHeader())?.tools;
+        const toolTokens = !tools?.length ? 0 : Math.ceil(JSON.stringify(tools).length / 4) + 4;
+        const tokens = value.surfaceTokens + toolTokens;
+        return Object.freeze({ ...value, baseline: Object.freeze({ kind: 'estimated', tokens }), surfaceDeltaTokens: 0, totalTokens: tokens });
+    }
+    Object.defineProperty(meter, 'measure', { configurable: true, writable: true, value: measure });
+    installed.set(meter, { refs: 1, release() {
+            if (Object.getOwnPropertyDescriptor(meter, 'measure')?.value !== measure)
+                return;
+            if (descriptor)
+                Object.defineProperty(meter, 'measure', descriptor);
+            else
+                delete meter.measure;
+        } });
+    let active = true;
+    return () => { if (active) {
+        active = false;
+        release(meter);
+    } };
+}
+function release(meter) {
+    const record = installed.get(meter);
+    if (record && --record.refs === 0) {
+        record.release();
+        installed.delete(meter);
+    }
+}
+export function installSearchUsage(ctx) {
+    ctx.inject(['sessionProjections'], c => { c.sessionProjections.register(searchUsageProjection); });
+    ctx.inject(['tokenMeter'], c => {
+        c.effect(() => installSearchMeasurement(c.tokenMeter), 'lcx search context measurement');
+    });
+}