dsh-lcx-codex 0.4.3-pre.2 → 0.4.3-pre.3

package/lib/responses-stream.js

@@ -3,6 +3,7 @@ import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
 import { processResponsesStream } from "@earendil-works/pi-ai/api/openai-responses-shared";
 import { ToolCallId } from "@deepseek-ai/dsh-llm";
 import { fetchSseWithRetry } from "./transport.js";
+import { createGrokNativeReplayEnvelope, } from "./grok-native-search.js";
 function emptyUsage() {
     return {
         input: 0,
@@ -167,10 +168,84 @@ export function managedFailureChunk(error, signal) {
             : { kind: "error", failure },
     };
 }
+async function readWithSignal(reader, signal) {
+    if (!signal)
+        return reader.read();
+    if (signal.aborted)
+        throw signal.reason;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        reader.read().then(resolve, reject).finally(() => {
+            signal.removeEventListener("abort", onAbort);
+        });
+    });
+}
+function requestDeadline(parent, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const onParentAbort = () => controller.abort(parent?.reason);
+    if (parent?.aborted)
+        onParentAbort();
+    else
+        parent?.addEventListener("abort", onParentAbort, { once: true });
+    if (!controller.signal.aborted &&
+        typeof timeoutMs === "number" &&
+        Number.isFinite(timeoutMs) &&
+        timeoutMs > 0)
+        timer = setTimeout(() => controller.abort(Object.assign(new Error(`Responses request timeout after ${timeoutMs}ms`), { code: "LCX_REQUEST_TIMEOUT" })), timeoutMs);
+    return {
+        signal: controller.signal,
+        dispose() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            parent?.removeEventListener("abort", onParentAbort);
+            if (!controller.signal.aborted)
+                controller.abort(Object.assign(new Error("Responses request consumer stopped"), {
+                    code: "LCX_ABORTED",
+                }));
+        },
+    };
+}
+function streamIdleWatchdog(parent, idleTimeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const onParentAbort = () => controller.abort(parent?.reason);
+    if (parent?.aborted)
+        onParentAbort();
+    else
+        parent?.addEventListener("abort", onParentAbort, { once: true });
+    const disarm = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    };
+    const arm = () => {
+        if (controller.signal.aborted)
+            return;
+        disarm();
+        if (typeof idleTimeoutMs === "number" && Number.isFinite(idleTimeoutMs) && idleTimeoutMs > 0)
+            timer = setTimeout(() => controller.abort(Object.assign(new Error(`Responses stream idle timeout after ${idleTimeoutMs}ms`), { code: "LCX_STREAM_IDLE_TIMEOUT" })), idleTimeoutMs);
+    };
+    return {
+        signal: controller.signal,
+        arm,
+        disarm,
+        dispose() {
+            disarm();
+            parent?.removeEventListener("abort", onParentAbort);
+            if (!controller.signal.aborted)
+                controller.abort(Object.assign(new Error("Responses stream consumer stopped"), {
+                    code: "LCX_ABORTED",
+                }));
+        },
+    };
+}
 /**
  * Minimal JSON SSE reader. LCX owns the exact HTTP wire; Pi owns event semantics after this boundary.
+ * Stream liveness is measured after Pi emits meaningful DSH progress, not here.
  * @param {Response} response
- * @param {{ signal?: AbortSignal, maxResponseBytes?: number }} [options]
+ * @param {StreamOptions} [options]
  */
 async function* responseEvents(response, options = {}) {
     if (!response?.body)
@@ -204,7 +279,7 @@ async function* responseEvents(response, options = {}) {
             if (options.signal?.aborted)
                 throw (options.signal.reason ??
                     Object.assign(new Error("request aborted"), { code: "LCX_ABORTED" }));
-            const { done, value } = await reader.read();
+            const { done, value } = await readWithSignal(reader, options.signal);
             if (done)
                 break;
             bytes += value.byteLength;
@@ -497,9 +572,55 @@ function recordMatches(record, item) {
  * @param {AsyncIterable<unknown>} source
  * @param {{ responseModel?: string }} [meta]
  */
-async function* normalizedResponseEvents(source, meta = {}) {
+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);
+        }
+        catch { }
+    };
+    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);
+            }
+        }
+        if (item.type === "web_search_call" &&
+            isObject(item.action) &&
+            Array.isArray(item.action.sources))
+            for (const source of item.action.sources)
+                observeCitation(source);
+    };
+    const isServerToolItem = (value) => isObject(value) && options.serverToolTypes?.has(String(value.type ?? "")) === true;
+    const observeServerTool = (item) => {
+        const type = String(item.type);
+        let ids = serverToolIds.get(type);
+        if (!ids) {
+            ids = new Set();
+            serverToolIds.set(type, ids);
+        }
+        ids.add(typeof item.id === "string" && item.id ? item.id : `${type}:${ids.size}`);
+    };
     /** @param {number} index @param {UnknownRecord} item */
     const ensure = function* (index, item) {
         let record = open.get(index);
@@ -522,6 +643,18 @@ async function* normalizedResponseEvents(source, meta = {}) {
         const index = Number.isInteger(event.output_index)
             ? Number(event.output_index)
             : 0;
+        if ((event.type === "response.output_item.added" ||
+            event.type === "response.output_item.done") &&
+            isObject(event.item))
+            observeCitations(event.item);
+        if (event.type === "response.output_item.done" && isObject(event.item))
+            completedWireItems.set(index, structuredClone(event.item));
+        if ((event.type === "response.output_item.added" ||
+            event.type === "response.output_item.done") &&
+            isServerToolItem(event.item)) {
+            observeServerTool(event.item);
+            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) });
@@ -636,11 +769,57 @@ async function* normalizedResponseEvents(source, meta = {}) {
             const response = /** @type {UnknownRecord} */ event.response;
             if (typeof response.model === "string" && response.model.length > 0)
                 meta.responseModel = response.model;
-            const output = Array.isArray(response.output)
-                ? response.output.map((item, terminalIndex) => isObject(item)
-                    ? normalizedTerminalItem(item, terminalIndex)
-                    : item)
-                : [];
+            const terminalOutput = Array.isArray(response.output) && response.output.length > 0
+                ? response.output
+                : [...completedWireItems.entries()]
+                    .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))
+                    observeServerTool(item);
+            }
+            const output = terminalOutput
+                .filter((item) => !isServerToolItem(item))
+                .map((item, terminalIndex) => isObject(item)
+                ? 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;
+            }
             const used = new Set();
             for (const [streamIndex, record] of open) {
                 let terminalIndex = output.findIndex((item, candidateIndex) => !used.has(candidateIndex) &&
@@ -725,6 +904,20 @@ async function* normalizedResponseEvents(source, meta = {}) {
                 if (identity)
                     completed.add(identity);
             }
+            if (options.onServerToolUsage) {
+                const usage = isObject(response.usage) ? response.usage : {};
+                const details = isObject(usage.server_side_tool_usage_details)
+                    ? usage.server_side_tool_usage_details
+                    : {};
+                const safeCount = (value, fallback) => Number.isSafeInteger(value) && Number(value) >= 0
+                    ? Number(value)
+                    : fallback;
+                const webSearchCalls = safeCount(details.web_search_calls, serverToolIds.get("web_search_call")?.size ?? 0);
+                const xSearchCalls = safeCount(details.x_search_calls, serverToolIds.get("x_search_call")?.size ?? 0);
+                const total = safeCount(usage.num_server_side_tools_used, webSearchCalls + xSearchCalls);
+                if (total > 0 || webSearchCalls > 0 || xSearchCalls > 0)
+                    options.onServerToolUsage({ webSearchCalls, xSearchCalls, total });
+            }
             yield { ...event, response: { ...response, output } };
             continue;
         }
@@ -767,7 +960,7 @@ function rawArguments(value) {
     }
 }
 /** @param {unknown} message */
-function replayState(message) {
+function replayState(message, nativeOutput, nativeVisibleAdditions, nativeReplayRoute) {
     if (!isObject(message))
         return undefined;
     const content = Array.isArray(message.content)
@@ -778,6 +971,7 @@ function replayState(message) {
     const api = typeof message.api === "string" ? message.api : undefined;
     if (!provider || !model || !api)
         return undefined;
+    const grokNative = createGrokNativeReplayEnvelope(nativeOutput, nativeReplayRoute, nativeVisibleAdditions);
     return {
         response: {
             kind: "pi-ai",
@@ -821,6 +1015,7 @@ function replayState(message) {
                     : {}),
             };
         }),
+        ...(grokNative === undefined ? {} : { grokNative }),
     };
 }
 /** @param {unknown} message */
@@ -850,7 +1045,7 @@ function successfulFinish(message) {
  * @param {AsyncIterable<AssistantMessageEvent>} events
  * @param {AbortSignal} [signal]
  */
-async function* toDshChunks(events, signal) {
+async function* toDshChunks(events, signal, wireMeta, nativeReplayRoute) {
     const toolIds = new Map();
     for await (const event of events) {
         switch (event.type) {
@@ -952,7 +1147,9 @@ async function* toDshChunks(events, signal) {
                     : {};
                 yield { type: "usage", usage: dshUsage(message.usage) };
                 const reason = successfulFinish(message);
-                const replay = reason.kind === "error" ? undefined : replayState(message);
+                const replay = reason.kind === "error"
+                    ? undefined
+                    : replayState(message, wireMeta?.nativeOutput, wireMeta?.nativeVisibleAdditions, nativeReplayRoute);
                 yield {
                     type: "finish",
                     reason,
@@ -1009,10 +1206,18 @@ async function* toDshChunks(events, signal) {
  * @param {number} [options.timeoutMs]
  * @param {number} [options.maxAttempts]
  * @param {number} [options.maxResponseBytes]
+ * @param {ReadonlySet<string>} [options.serverToolTypes]
+ * @param {(usage: ServerToolUsage) => void} [options.onServerToolUsage]
  */
-export async function* streamResponsesRequest({ baseURL, provider, model, piModel, body, grammarToolInputProperties, headers, signal, timeoutMs, maxAttempts = 1, maxResponseBytes, }) {
+export async function* streamResponsesRequest({ baseURL, provider, model, piModel, body, grammarToolInputProperties, headers, signal, timeoutMs, applyDefaultTimeout = true, streamIdleTimeoutMs, maxAttempts = 1, maxResponseBytes, serverToolTypes, nativeReplayRoute, onServerToolUsage, }) {
+    const effectiveTimeoutMs = timeoutMs ?? (applyDefaultTimeout ? 300_000 : undefined);
+    const deadline = requestDeadline(signal, effectiveTimeoutMs);
+    const watchdog = streamIdleWatchdog(deadline.signal, streamIdleTimeoutMs);
     try {
-        const response = await fetchSseWithRetry(`${String(baseURL).replace(/\/+$/u, "")}/responses`, body, headers, signal, timeoutMs, { maxAttempts, maxResponseBytes });
+        // Match DSH's idleWatchdog.next(): the first outstanding next includes
+        // request dispatch and headers, and later intervals cover one DSH chunk.
+        watchdog.arm();
+        const response = await fetchSseWithRetry(`${String(baseURL).replace(/\/+$/u, "")}/responses`, body, headers, watchdog.signal, undefined, { maxAttempts, maxResponseBytes, applyDefaultTimeout: false });
         const output = {
             role: "assistant",
             content: [],
@@ -1028,7 +1233,10 @@ export async function* streamResponsesRequest({ baseURL, provider, model, piMode
         const parser = (async () => {
             try {
                 piEvents.push({ type: "start", partial: output });
-                await processResponsesStream(validatedResponseEvents(normalizedResponseEvents(responseEvents(response, { signal, maxResponseBytes }), wireMeta)), output, piEvents, piModel, { grammarToolInputProperties });
+                await processResponsesStream(validatedResponseEvents(normalizedResponseEvents(responseEvents(response, {
+                    signal: watchdog.signal,
+                    maxResponseBytes,
+                }), wireMeta, { serverToolTypes, onServerToolUsage })), output, piEvents, piModel, { grammarToolInputProperties });
                 if (typeof wireMeta.responseModel === "string" &&
                     wireMeta.responseModel.length > 0)
                     output.responseModel = wireMeta.responseModel;
@@ -1059,10 +1267,35 @@ export async function* streamResponsesRequest({ baseURL, provider, model, piMode
                 piEvents.end();
             }
         })();
-        yield* toDshChunks(piEvents, signal);
+        const chunks = toDshChunks(piEvents, signal, wireMeta, nativeReplayRoute)[Symbol.asyncIterator]();
+        let exhausted = false;
+        try {
+            while (true) {
+                const result = await chunks.next();
+                if (watchdog.signal.aborted)
+                    throw watchdog.signal.reason;
+                if (result.done) {
+                    exhausted = true;
+                    watchdog.disarm();
+                    break;
+                }
+                watchdog.disarm();
+                yield result.value;
+                watchdog.arm();
+            }
+        }
+        finally {
+            watchdog.disarm();
+            if (!exhausted)
+                await chunks.return?.(undefined);
+        }
         await parser;
     }
     catch (error) {
         yield managedFailureChunk(error, signal);
     }
+    finally {
+        watchdog.dispose();
+        deadline.dispose();
+    }
 }

package/lib/route.js

@@ -12,6 +12,9 @@ function isRecord(value) {
 function isPositiveInteger(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
+function isPositiveFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
 function asLlmSettingsSection(value) {
     if (!isRecord(value))
         return undefined;
@@ -72,6 +75,13 @@ export function promptCacheSessionId(route, config = {}, ctx = undefined) {
 export function promptCacheKey(route, config = {}, ctx = undefined) {
     return clampPromptCacheKey(promptCacheSessionId(route, config, ctx));
 }
+/** Grok follows Pi directly: cache/affinity belongs to the selected child session. */
+export function grokPromptCacheSessionId(route, config = {}) {
+    if (config.cacheRetention === "none")
+        return undefined;
+    const sessionId = String(route?.sessionId ?? "");
+    return sessionId || undefined;
+}
 /** @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention' | 'supportsLongCacheRetention' | 'responsesCompat'>>} [config] */
 export function promptCacheRetention(config = {}) {
     return config.cacheRetention === "long" && config.supportsLongCacheRetention === true && config.responsesCompat?.supportsExplicitPromptCacheMode !== true ? "24h" : undefined;
@@ -116,17 +126,68 @@ function builtinResponsesModel(provider, modelId) {
         return undefined;
     return getBuiltinModels(builtinProvider).find((model) => model.id === String(modelId ?? "") && model.api === "openai-responses");
 }
+function modelDescriptorDefaults(model) {
+    if (!model)
+        return undefined;
+    return {
+        reasoning: model.reasoning,
+        thinkingLevelMap: model.thinkingLevelMap,
+    };
+}
+function configuredModelProfile(profile, modelId) {
+    const configuredModels = Array.isArray(profile?.models) ? profile.models : [];
+    return configuredModels.length > 0
+        ? configuredModels.find((entry) => String(entry?.id ?? "") === String(modelId))
+        : profile?.modelOverrides?.[String(modelId)];
+}
 /** @param {ProviderProfile | null | undefined} profile @param {unknown} modelId @returns {ResponsesCompat | undefined} */
 function configuredResponsesCompat(profile, modelId) {
     const compat = {};
     copyResponsesCompat(compat, profile?.compat);
-    const configuredModels = Array.isArray(profile?.models) ? profile.models : [];
-    const modelEntry = configuredModels.length > 0
-        ? configuredModels.find((entry) => String(entry?.id ?? "") === String(modelId))
-        : profile?.modelOverrides?.[String(modelId)];
-    copyResponsesCompat(compat, modelEntry?.compat);
+    copyResponsesCompat(compat, configuredModelProfile(profile, modelId)?.compat);
     return Object.keys(compat).length ? compat : undefined;
 }
+const MODEL_THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+function profileReasoning(value) {
+    return MODEL_THINKING_LEVELS.find((level) => level === value);
+}
+function configuredModelControls(profile, modelId, base) {
+    const configured = configuredModelProfile(profile, modelId);
+    const efforts = configured?.reasoningEfforts;
+    if (efforts === undefined)
+        return {
+            reasoning: base?.reasoning ?? false,
+            ...(base?.thinkingLevelMap === undefined
+                ? {}
+                : { thinkingLevelMap: base.thinkingLevelMap }),
+        };
+    if (efforts === false)
+        return { reasoning: false };
+    if (!isRecord(efforts))
+        return { reasoning: false };
+    const thinkingLevelMap = {};
+    for (const level of MODEL_THINKING_LEVELS) {
+        const value = efforts[level];
+        if (value === undefined)
+            thinkingLevelMap[level] = null;
+        else if (value === null) {
+            // DSH permits only off:null: it means supported-off by omitting the wire option.
+            if (level !== "off")
+                thinkingLevelMap[level] = null;
+        }
+        else if (typeof value === "string")
+            thinkingLevelMap[level] = value;
+    }
+    return { reasoning: true, thinkingLevelMap };
+}
 function isLcxCapabilityRoute(provider, model) {
     return provider === "lcx" &&
         /^gpt-5\.6-(?:sol|luna|terra)$/iu.test(model);
@@ -189,6 +250,74 @@ export function resolveResponsesRouteConfig(ctx, options, policy) {
         requestImageMaxBytes: isPositiveInteger(configured.requestImageMaxBytes) ? configured.requestImageMaxBytes : policy.requestImageMaxBytes,
     };
 }
+/** Resolve a Grok-prefixed model through its selected DSH Responses profile. */
+export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
+    const provider = String(options?.provider ?? "");
+    const model = String(options?.model ?? "");
+    if (!provider.trim() || !/^grok/iu.test(model))
+        return undefined;
+    const section = settingsValue(ctx, "llm-pi-ai");
+    const configured = section?.providers?.[provider];
+    if (!isRecord(configured))
+        return undefined;
+    const selectedBuiltin = builtinResponsesModel(provider, model);
+    const api = configured.api ?? selectedBuiltin?.api;
+    if (api !== "openai-responses")
+        return undefined;
+    const baseURL = configured.baseURL ?? selectedBuiltin?.baseUrl;
+    const apiKeyEnv = configured.apiKeyEnv;
+    if (typeof baseURL !== "string" ||
+        !normalizeBaseURL(baseURL) ||
+        typeof apiKeyEnv !== "string" ||
+        !apiKeyEnv.trim())
+        return undefined;
+    const responsesCompat = {};
+    copyResponsesCompat(responsesCompat, selectedBuiltin?.compat);
+    copyResponsesCompat(responsesCompat, configuredResponsesCompat(configured, model));
+    const supportsLongCacheRetention = responsesCompat.supportsLongCacheRetention === true;
+    responsesCompat.supportsLongCacheRetention = supportsLongCacheRetention;
+    const requestedRetention = configured.cacheRetention;
+    const cacheRetention = requestedRetention === "none"
+        ? "none"
+        : requestedRetention === "long" && supportsLongCacheRetention
+            ? "long"
+            : "short";
+    return {
+        provider,
+        model,
+        api: "openai-responses",
+        baseURL: normalizeBaseURL(baseURL),
+        apiKeyEnv,
+        headers: effectiveGrokProfileHeaders(configured.headers),
+        cacheRetention,
+        supportsLongCacheRetention,
+        responsesCompat,
+        modelDefaults: modelDescriptorDefaults(selectedBuiltin),
+        modelControls: {
+            ...configuredModelControls(configured, model, selectedBuiltin),
+            includeEncryptedReasoning: true,
+        },
+        profileReasoning: profileReasoning(configured.reasoning),
+        // Pi applies only an explicitly configured request deadline; stream liveness
+        // is owned separately by the provider idle watchdog.
+        timeoutMs: isPositiveInteger(configured.timeoutMs)
+            ? configured.timeoutMs
+            : undefined,
+        streamIdleTimeoutMs: isPositiveFinite(configured.streamIdleTimeoutMs)
+            ? configured.streamIdleTimeoutMs
+            : 300_000,
+        maxAttempts: retryAttempts(configured.retryPolicy, policy.maxAttempts),
+        maxRequestImageBytes: isPositiveInteger(configured.maxRequestImageBytes)
+            ? configured.maxRequestImageBytes
+            : policy.maxRequestImageBytes,
+        requestImagePixelBudget: isPositiveInteger(configured.requestImagePixelBudget)
+            ? configured.requestImagePixelBudget
+            : policy.requestImagePixelBudget,
+        requestImageMaxBytes: isPositiveInteger(configured.requestImageMaxBytes)
+            ? configured.requestImageMaxBytes
+            : policy.requestImageMaxBytes,
+    };
+}
 /** @param {RouteContext | null | undefined} ctx @param {Pick<ResolvedResponsesRoute, 'apiKeyEnv'>} config */
 export async function resolveApiKey(ctx, config) {
     const resolved = await ctx?.credentials.resolve(credentialRef(config.apiKeyEnv));
@@ -201,6 +330,23 @@ export async function resolveApiKey(ctx, config) {
     error.code = "LCX_CREDENTIAL_UNAVAILABLE";
     throw error;
 }
+function setHeaderCaseInsensitive(headers, name, value) {
+    const normalized = name.toLowerCase();
+    for (const existing of Object.keys(headers))
+        if (existing.toLowerCase() === normalized)
+            delete headers[existing];
+    headers[name] = value;
+}
+/** Apply DSH's case-insensitive attribution reservation at profile resolution. */
+function effectiveGrokProfileHeaders(configured) {
+    const attribution = attributionHeaders();
+    const reserved = new Set(Object.keys(attribution).map((name) => name.toLowerCase()));
+    const effective = {};
+    for (const [name, value] of Object.entries(configured ?? {}))
+        if (!reserved.has(name.toLowerCase()))
+            setHeaderCaseInsensitive(effective, name, value);
+    return effective;
+}
 /** @param {HeaderMap | null | undefined} headers @param {string} name */
 function hasHeader(headers, name) { return Object.keys(headers ?? {}).some((key) => key.toLowerCase() === name.toLowerCase()); }
 /** @param {HeaderMap | null | undefined} headers */
@@ -239,6 +385,28 @@ export async function authenticatedHeaders(ctx, config, sessionId, requestId) {
     }
     return { ...headers, ...explicit };
 }
+/** Grok mirrors Pi createClient ordering without changing accepted GPT headers. */
+export async function authenticatedGrokHeaders(ctx, config, sessionId) {
+    const explicit = effectiveGrokProfileHeaders(config.headers);
+    const headers = {
+        authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
+    };
+    const sid = sessionId ? String(sessionId) : undefined;
+    const format = sessionAffinityFormat(config);
+    if (sid) {
+        if (format === "openai")
+            headers.session_id = sid;
+        else if (format === "openrouter")
+            headers["x-session-id"] = sid;
+        if (format === "openai" || format === "openai-nosession")
+            headers["x-client-request-id"] = sid;
+    }
+    for (const [name, value] of Object.entries(explicit))
+        setHeaderCaseInsensitive(headers, name, value);
+    for (const [name, value] of Object.entries(attributionHeaders()))
+        setHeaderCaseInsensitive(headers, name, value);
+    return headers;
+}
 /** @param {RouteOptions | null | undefined} options @param {Pick<UnresolvedRouteConfig, 'provider' | 'model' | 'baseURL'>} config @returns {RouteIdentity} */
 export function currentRoute(options, config) {
     return { provider: String(options?.provider ?? config.provider ?? ""), model: String(options?.model ?? config.model ?? ""), baseURL: normalizeBaseURL(config.baseURL), sessionId: String(options?.sessionId ?? "") };

package/lib/transport.js

@@ -168,13 +168,15 @@ export async function fetchJsonWithRetry(url, body, headers = {}, signal, timeou
     }
     throw last ?? makeError("request failed", "LCX_REQUEST_FAILED");
 }
-export async function fetchSseWithRetry(url, body, headers = {}, signal, timeoutMs = DEFAULT_TIMEOUT_MS, options = {}) {
+export async function fetchSseWithRetry(url, body, headers = {}, signal, timeoutMs, options = {}) {
+    const requestTimeoutMs = timeoutMs ??
+        (options.applyDefaultTimeout === false ? undefined : DEFAULT_TIMEOUT_MS);
     const maxAttempts = Math.max(1, Math.min(6, Number(options.maxAttempts ?? 3)));
     let last;
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
         abortIfNeeded(signal);
         try {
-            const requestSignal = combinedSignal(signal, timeoutMs);
+            const requestSignal = combinedSignal(signal, requestTimeoutMs);
             const response = await fetch(url, {
                 method: "POST",
                 headers: {

package/lib/types/dsh-compat.d.ts

@@ -40,7 +40,7 @@ export declare function readAgentRouteState(agent: unknown): {
     options: unknown;
     sessionId: string;
 };
-export declare function scopedToolRuntime(agent: unknown): Pick<ToolRuntime, "register"> | undefined;
+export declare function scopedToolRuntime(agent: unknown): (Pick<ToolRuntime, "register"> & Partial<Pick<ToolRuntime, "get">>) | undefined;
 export declare function tokenMeterTotal(value: unknown, session: Session): number | undefined;
 export declare function sessionsService(ctx: unknown): Pick<SessionStore, "get"> | undefined;
 export declare function sessionFor(ctx: unknown, sessionId: string): Session | undefined;

package/lib/types/grok-native-search.d.ts

@@ -0,0 +1,39 @@
+import type { Message, ToolSchema } from "@deepseek-ai/dsh-llm";
+export declare const GROK_NATIVE_SERVER_TOOL_TYPES: Set<string>;
+export type GrokNativeSearchState = {
+    web: boolean;
+    x: boolean;
+};
+export type GrokNativeReplayRoute = {
+    provider: string;
+    model: string;
+    sessionId: string;
+    baseURL: string;
+    apiKeyEnv: string;
+    headers?: Record<string, string>;
+};
+type WireTool = Record<string, unknown>;
+type WireItem = Record<string, unknown> & {
+    type: string;
+};
+type GrokNativeVisibleAddition = {
+    kind: "citation-sources";
+    textSha256: string;
+};
+type GrokNativeReplayEnvelope = {
+    kind: "xai-responses-native-search";
+    version: 2;
+    provider: string;
+    model: string;
+    sourceSessionId: string;
+    routeAuthorityFingerprint: string;
+    output: WireItem[];
+    visibleAdditions: GrokNativeVisibleAddition[];
+};
+export declare function grokNativeReplayRouteFingerprint(route: GrokNativeReplayRoute): string;
+export declare function grokNativeSearchEnabled(state: GrokNativeSearchState): boolean;
+export declare function grokVisibleFunctionTools(tools: readonly ToolSchema[] | undefined, state?: GrokNativeSearchState): ToolSchema[] | undefined;
+export declare function grokWireTools(tools: readonly unknown[] | undefined, state: GrokNativeSearchState): WireTool[];
+export declare function createGrokNativeReplayEnvelope(output: readonly unknown[] | undefined, route: GrokNativeReplayRoute | undefined, visibleAdditions?: readonly unknown[]): GrokNativeReplayEnvelope | undefined;
+export declare function restoreGrokNativeReplay(input: readonly unknown[], messages: readonly Message[], route: GrokNativeReplayRoute | undefined): unknown[];
+export {};

package/lib/types/responses-request.d.ts

@@ -11,6 +11,7 @@ type PiResponsesModel = {
     provider: string;
     reasoning?: boolean;
     thinkingLevelMap?: Record<string, string | null>;
+    includeEncryptedReasoning?: boolean;
     compat?: ResponsesCompat;
 };
 type GenerationControls = {