dsh-lcx-codex 0.4.3 → 0.5.0-pre.1

package/lib/index.js

@@ -1,6 +1,7 @@
 import z from "@deepseek-ai/schemastery";
 import { recordHostedUsage, withAuxiliaryUsage } from "./auxiliary-usage.js";
 import { installSearchUsage } from "./search-usage.js";
+import { projectToolUpdates } from "@deepseek-ai/dsh-llm";
 import { WEB_SEARCH_MAX_QUERIES, applyWebSearchTool, } from "@deepseek-ai/dsh-tool-web";
 import "@deepseek-ai/dsh-agent";
 import "@deepseek-ai/dsh-tools";
@@ -11,7 +12,7 @@ import { join } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getSupportedThinkingLevels } from "./pi-responses-runtime.js";
 import { fetchJsonWithRetry } from "./transport.js";
-import { agentSessionId, agentUsesSession, compactionConfigState, compactionPatchCandidate, installCompactionPatch, patchCompactionConfig, patchToolResultPruner, readAgentRouteState, resolveAgentService, resolveContextService, resolveScopedService, restoreCompactionConfig, restoreCompactionPatches, restoreToolResultPruner, sessionFor, sessionFromAgent, scopedToolRuntime, tokenMeterTotal, toolResultPrunerState, } from "./dsh-compat.js";
+import { agentSessionId, agentUsesSession, compactionConfigState, compactionPatchCandidate, installCompactionPatch, patchCompactionConfig, patchToolResultPruner, readAgentRouteState, readSelectedAgentRouteState, recordAgentRouteEvent, resolveAgentService, resolveContextService, resolveScopedService, restoreCompactionConfig, restoreCompactionPatches, restoreToolResultPruner, sessionFor, sessionFromAgent, scopedToolRuntime, tokenMeterTotal, toolResultPrunerState, } from "./dsh-compat.js";
 import { InvocationPolicyScope } from "./invocation-policy-scope.js";
 import { authenticatedGrokHeaders, authenticatedHeaders, currentRoute, generationControlsFromSession, grokPromptCacheSessionId, promptCacheKey, promptCacheRetention, promptCacheSessionId, resolveGrokResponsesRouteConfig, resolveResponsesRouteConfig, routeFingerprint, } from "./route.js";
 import { DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_REQUEST_IMAGE_MAX_BYTES, hydrateNativeImageReferences, resolveModelImageSupport, responseInputItems, serializeDshMessages, } from "./dsh-responses.js";
@@ -20,14 +21,14 @@ import { buildResponsesBody } from "./responses-request.js";
 import { managedFailureChunk, streamResponsesRequest, } from "./responses-stream.js";
 import { assertSupportedCheckpointMessage, checkpointStateForMessage, compactCheckpointId, createNativeCheckpointBlock, nativeCheckpointChunks, portableMessagesForCheckpoint, stateRouteCompatible, } from "./native-checkpoint.js";
 import { HOSTED_SEARCH_OUTPUT, HOSTED_SEARCH_PARAMETERS, buildHostedSearchBody, hostedMediaPresentationMeta, normalizeHostedSearchArgs, parseHostedSearchResponse, renderHostedSearchResult, } from "./web-search-hosted.js";
-import { ALPHA_SCHEMA_FINGERPRINT, alphaRefRequiresStore, isAlphaContinuationUrl, isAlphaHttpUrl, ALPHA_SEARCH_OUTPUT, ALPHA_SEARCH_PARAMETERS, alphaSearchRetryOptions, buildAlphaSearchBody, normalizeAlphaSearchArgs, parseAlphaSearchResponse, renderAlphaSearchResult, runWithAlphaSessionLock, } from "./web-search-alpha.js";
+import { ALPHA_SCHEMA_FINGERPRINT, alphaRefRequiresStore, isAlphaContinuationUrl, isAlphaHttpUrl, ALPHA_SEARCH_OUTPUT, ALPHA_SEARCH_PARAMETERS, alphaSearchRetryOptions, buildAlphaSearchBody, normalizeAlphaSearchArgs, parseAlphaSearchResponse, remapAlphaResultRefs, renderAlphaSearchResult, runWithAlphaSessionLock, } from "./web-search-alpha.js";
+import { recentAlphaInput } from "./web-search-alpha-history.js";
 import { AlphaCapabilityStore, alphaCapabilityFingerprint, alphaCapabilityUsable, alphaSearchParametersFor, assertAlphaActionAllowed, } from "./web-search-capability.js";
 import { AlphaRefStore } from "./web-search-ref-store.js";
 import { ServiceMutex } from "./service-mutex.js";
 import { GROK_NATIVE_SERVER_TOOL_TYPES, grokNativeSearchEnabled, grokVisibleFunctionTools, isGrokNativeServerToolItem, grokWireTools, restoreGrokNativeReplay, } from "./grok-native-search.js";
 export const name = "lcx-codex";
 export const inject = ["llm", "web", "sessions", "tools", "settings", "credentials", "attachments", "fs"];
-const SETTINGS_NS = "lcx-codex";
 const ADVANCED_HOSTED_TOOL = "websearch_gpt_advanced";
 const ALPHA_TOOL = "websearch_alpha";
 const hostedSearchRouteContext = new AsyncLocalStorage();
@@ -92,6 +93,13 @@ function defaultAlphaRefPath() {
     return join(dshHome(), "storages", "lcx-codex", "web-alpha-refs.json");
 }
 export const Config = z.object({
+    enabled: z.boolean().default(false).volatile(),
+    webSearch: z.boolean().default(false).volatile(),
+    advancedHostedSearch: z.boolean().default(false).volatile(),
+    alphaSearch: z.boolean().default(false).volatile(),
+    grokNativeWebSearch: z.boolean().default(false).volatile(),
+    grokNativeXSearch: z.boolean().default(false).volatile(),
+    searchMediaPreview: z.boolean().default(false).volatile(),
     supportsLongCacheRetention: z.boolean().default(false),
     supportsExplicitPromptCacheMode: z.boolean().default(false),
     alphaCapabilityPath: z.string().default(""),
@@ -114,15 +122,6 @@ export const Config = z.object({
     assistantRetentionTokenReserve: z.number().default(24_000),
     assistantRetentionPerMessageTokenCap: z.number().default(3_000),
 });
-const SettingsSchema = z.object({
-    enabled: z.boolean().default(false),
-    webSearch: z.boolean().default(false),
-    advancedHostedSearch: z.boolean().default(false),
-    alphaSearch: z.boolean().default(false),
-    grokNativeWebSearch: z.boolean().default(false),
-    grokNativeXSearch: z.boolean().default(false),
-    searchMediaPreview: z.boolean().default(false),
-});
 function normalizeConfig(input = {}) {
     return {
         supportsLongCacheRetention: input.supportsLongCacheRetention === true,
@@ -170,7 +169,7 @@ function activeAgentRoute(exec) {
     };
 }
 function selectedAgentRoute(agent) {
-    const route = readAgentRouteState(agent);
+    const route = readSelectedAgentRouteState(agent);
     return {
         provider: stringValue(routeConfigValue(route.requestConfig, "provider") ??
             routeConfigValue(route.options, "provider"), ""),
@@ -409,11 +408,13 @@ async function executeAlpha(ctx, routeConfig, capability, refStore, args, exec)
         const continuedRef = alphaRefRequiresStore(normalized.action, normalized.refId)
             ? refStore.assertUsable(sessionId, routeFp, normalized.refId)
             : undefined;
+        const rawRefId = continuedRef?.rawRefId ?? continuedRef?.refId;
+        const outbound = rawRefId ? { ...normalized, refId: rawRefId } : normalized;
         const requestId = randomUUID();
         const headers = await authenticatedHeaders(ctx, routeConfig, sessionId, requestId);
         let response;
         try {
-            response = await fetchJsonWithRetry(`${routeConfig.baseURL}/alpha/search`, buildAlphaSearchBody(normalized, routeConfig.model, sessionId, true, routeConfig.alphaMaxOutputTokens), headers, exec?.signal, routeConfig.timeoutMs, alphaSearchRetryOptions(routeConfig.maxResponseBytes));
+            response = await fetchJsonWithRetry(`${routeConfig.baseURL}/alpha/search`, buildAlphaSearchBody(outbound, routeConfig.model, sessionId, true, routeConfig.alphaMaxOutputTokens, recentAlphaInput(sessionFromAgent(exec?.agent)?.deriveMessages() ?? [])), headers, exec?.signal, routeConfig.timeoutMs, alphaSearchRetryOptions(routeConfig.maxResponseBytes));
         }
         catch (error) {
             const details = errorDetails(error);
@@ -427,22 +428,21 @@ async function executeAlpha(ctx, routeConfig, capability, refStore, args, exec)
             capability: capability.classification,
             requestId,
         });
-        const refRecords = observedRefs.map((observation) => {
-            if (observation.refId !== normalized.refId || !continuedRef)
-                return observation;
+        const echoed = {};
+        const refRecords = observedRefs.flatMap((observation) => {
+            if (observation.refId !== rawRefId || !continuedRef)
+                return [observation];
             const observedArtifact = observation.provenance.artifactFingerprint;
             const acceptedArtifact = continuedRef.provenance.artifactFingerprint;
-            if (observedArtifact && observedArtifact !== acceptedArtifact)
-                return observation;
-            // An echoed input ref retains its accepted origin; an omitted URL makes no new claim.
-            return {
-                ...observation,
-                ...(observation.url === undefined && continuedRef.url ? { url: continuedRef.url } : {}),
-                provenance: { ...continuedRef.provenance },
-            };
+            if ((observedArtifact && observedArtifact !== acceptedArtifact) ||
+                (observation.url && continuedRef.url && observation.url !== continuedRef.url))
+                throw webError("Alpha continuation changed its reference observation", "LCX_ALPHA_REF_COLLISION");
+            // Echoes retain their existing handle and cannot create a new observation.
+            echoed[observation.refId] = continuedRef.refId;
+            return [];
         });
-        refStore.record(sessionId, routeFp, refRecords);
-        return result;
+        const handles = refStore.record(sessionId, routeFp, refRecords, true);
+        return remapAlphaResultRefs(result, { ...handles, ...echoed });
     });
 }
 function createAlphaTool(ctx, state, getConfig, capabilityStore, refStore, advertisedRecord) {
@@ -521,10 +521,17 @@ function disposeAlphaToolForAgent(agent, registrations) {
     registration.dispose();
     registrations.delete(agent);
 }
+function isPersistedMessage(message) {
+    return typeof message.id === "string";
+}
 function isDshCompactionDirective(message) {
-    return (message?.role === "user" &&
-        message?.source?.kind === "plugin" &&
-        message?.source?.plugin === "dsh-compaction-basic");
+    // DSH compaction-basic appends a request-only user input in its
+    // purpose="compaction" call. Durable conversation messages have an id.
+    return (message.role === "user" &&
+        !("id" in message) &&
+        !("source" in message) &&
+        message.content.length === 1 &&
+        message.content[0]?.type === "text");
 }
 function stripCompactionDirective(messages) {
     if (messages.length === 0)
@@ -578,13 +585,13 @@ async function serializeNativeAware(messages, route, routeConfig, ctx, options)
         nativeModel = serialized.model ?? nativeModel;
         grammarToolInputProperties =
             serialized.grammarToolInputProperties ?? grammarToolInputProperties;
-        input.push(...restoreGrokNativeReplay(serialized.input, batch, options.grokNativeReplayRoute));
+        input.push(...restoreGrokNativeReplay(serialized.input, batch.filter(isPersistedMessage), options.grokNativeReplayRoute));
         mergeMap(imageMap, serialized.imageMap);
     };
     for (const message of surfaceMessages ?? []) {
         assertSupportedCheckpointMessage(message);
-        const state = session
-            ? checkpointStateForMessage(session, message)
+        const state = session && isPersistedMessage(message) && compactCheckpointId(message)
+            ? await checkpointStateForMessage(ctx, session, message)
             : undefined;
         if (state && session) {
             const checkpointId = compactCheckpointId(message);
@@ -601,7 +608,7 @@ async function serializeNativeAware(messages, route, routeConfig, ctx, options)
                 mergeMap(imageMap, hydratedMap);
             }
             else {
-                const portable = portableMessagesForCheckpoint(session, checkpointId, { maxChars: routeConfig.portableReplayMaxChars });
+                const portable = await portableMessagesForCheckpoint(ctx, session, checkpointId, { maxChars: routeConfig.portableReplayMaxChars });
                 const serialized = await serializeDshMessages(portable, ctx, serializeOptions());
                 input.push(...serialized.input);
                 mergeMap(imageMap, serialized.imageMap);
@@ -634,10 +641,11 @@ function fallbackEligible(error, signal) {
     return ["LCX_HTTP_RETRYABLE", "LCX_RETRY_EXHAUSTED"].includes(String(details.code ?? ""));
 }
 async function* remoteCompactionStream(options, routeConfig, ctx, next) {
-    const history = stripCompactionDirective(options.messages);
+    const projected = projectToolUpdates(options.messages, options.tools, undefined, options.toolHistory);
+    const history = stripCompactionDirective(projected.messages);
     const route = currentRoute(options, routeConfig);
     try {
-        const prepared = await serializeNativeAware(history, route, routeConfig, ctx, { signal: options.signal, tools: options.tools });
+        const prepared = await serializeNativeAware(history, route, routeConfig, ctx, { signal: options.signal, tools: projected.tools && [...projected.tools] });
         const cacheSessionId = promptCacheSessionId(route, routeConfig, ctx);
         const headers = await authenticatedHeaders(ctx, routeConfig, cacheSessionId, cacheSessionId === undefined ? null : route.sessionId);
         const generation = generationControlsFromSession(sessionFor(ctx, route.sessionId), route);
@@ -646,7 +654,7 @@ async function* remoteCompactionStream(options, routeConfig, ctx, next) {
             model: route.model,
             modelDescriptor: prepared.model,
             input: prepared.input,
-            tools: prepared.tools ?? options.tools,
+            tools: prepared.tools ?? (projected.tools && [...projected.tools]),
             promptCacheKey: promptCacheKey(route, routeConfig, ctx),
             promptCacheRetention: promptCacheRetention(routeConfig),
             cacheRetention: routeConfig.cacheRetention,
@@ -663,7 +671,8 @@ async function* remoteCompactionStream(options, routeConfig, ctx, next) {
         const session = sessionFor(ctx, route.sessionId);
         if (session === undefined)
             throw webError("Native compaction requires a live DSH session", "LCX_COMPACT_SESSION_UNAVAILABLE");
-        const block = createNativeCheckpointBlock({
+        const block = await createNativeCheckpointBlock({
+            ctx,
             session,
             route,
             result,
@@ -681,8 +690,10 @@ async function* remoteCompactionStream(options, routeConfig, ctx, next) {
             yield chunk;
     }
     catch (error) {
+        if (isRecord(error) && error.code === "LCX_SESSION_QUERY_UNAVAILABLE")
+            throw error;
         const session = sessionFor(ctx, route.sessionId);
-        const hasExistingCheckpoint = messagesContainNativeCheckpoint(history, session);
+        const hasExistingCheckpoint = await messagesContainNativeCheckpoint(ctx, history, session);
         const details = errorDetails(error);
         const code = details.code ?? details.name ?? "ERROR";
         const status = Number.isInteger(details.status)
@@ -718,16 +729,53 @@ function routedTargetForAgent(agent) {
     return provider && model ? { provider, model } : undefined;
 }
 export function compactionPressureBand(totalTokens, contextWindow, policy) {
-    const ratioPercent = (totalTokens / contextWindow) * 100;
+    const pressureBudget = contextWindow - policy.outputReserve - policy.headroomTokens;
+    const ratioPercent = (totalTokens / pressureBudget) * 100;
+    const nativeThreshold = Math.floor(pressureBudget * policy.auto / 100);
+    const emergencyThreshold = Math.floor(pressureBudget * policy.emergency / 100);
     return {
+        pressureBudget,
+        nativeThreshold,
+        emergencyThreshold,
         ratioPercent,
-        band: ratioPercent < policy.auto
+        band: totalTokens < nativeThreshold
             ? "below"
-            : ratioPercent < policy.emergency
+            : totalTokens < emergencyThreshold
                 ? "native"
                 : "emergency",
     };
 }
+function compactionHeadroomTokens(config, target) {
+    if (!isRecord(config))
+        return undefined;
+    const override = Array.isArray(config.modelPolicies)
+        ? config.modelPolicies.find((policy) => isRecord(policy) && policy.provider === target.provider && policy.model === target.model)
+        : undefined;
+    const headroom = isRecord(override)
+        ? override.headroomTokens ?? config.headroomTokens
+        : config.headroomTokens;
+    return Number.isSafeInteger(headroom) && headroom >= 0
+        ? headroom
+        : undefined;
+}
+function compactionRetainTokens(config, target, messageBudgetTokens) {
+    if (!isRecord(config))
+        return undefined;
+    const override = Array.isArray(config.modelPolicies)
+        ? config.modelPolicies.find((policy) => isRecord(policy) && policy.provider === target.provider && policy.model === target.model)
+        : undefined;
+    // Match compaction-basic's resolveRetention/resolveTargetPolicy precedence.
+    const retention = isRecord(override) &&
+        (override.retainTokens !== undefined || override.retainRatio !== undefined)
+        ? override
+        : config;
+    if (retention.retainTokens !== undefined)
+        return typeof retention.retainTokens === "number" ? retention.retainTokens : undefined;
+    const ratio = retention.retainRatio === undefined ? 0.16 : retention.retainRatio;
+    return typeof ratio === "number"
+        ? Math.floor(messageBudgetTokens * ratio)
+        : undefined;
+}
 function adjustedCompactionConfig(config, target, thresholdRatio) {
     if (!isRecord(config))
         return config;
@@ -778,15 +826,25 @@ function patchCompactionPressureService(compactionValue, state, getConfig, ctx,
                 if (!session || tokenMeter === undefined)
                     return callOriginal(activeSignal);
                 let contextWindow;
+                let defaultMaxTokens;
                 try {
-                    contextWindow = (await ctx.llm.resolveModelInfo(target.provider, target.model, activeSignal)).context?.contextWindow;
+                    const info = await ctx.llm.resolveModelInfo(target.provider, target.model, activeSignal);
+                    contextWindow = info.context?.contextWindow;
+                    defaultMaxTokens = info.defaultMaxTokens;
                 }
                 catch {
                     return callOriginal(activeSignal);
                 }
                 const totalTokens = tokenMeterTotal(tokenMeter, session);
-                if (contextWindow === undefined ||
+                const headroomTokens = compactionHeadroomTokens(compactionConfigState(candidate.compaction).original, target);
+                const outputReserve = session.requestHeader()?.config.maxTokens ?? defaultMaxTokens ?? 0;
+                if (typeof contextWindow !== "number" ||
+                    !Number.isSafeInteger(contextWindow) ||
                     contextWindow <= 0 ||
+                    !Number.isSafeInteger(outputReserve) ||
+                    outputReserve < 0 ||
+                    headroomTokens === undefined ||
+                    contextWindow - outputReserve - headroomTokens <= 0 ||
                     totalTokens === undefined)
                     return callOriginal(activeSignal);
                 const auto = AUTO_COMPACTION_THRESHOLD_PERCENT;
@@ -794,14 +852,23 @@ function patchCompactionPressureService(compactionValue, state, getConfig, ctx,
                 const pressure = compactionPressureBand(totalTokens, contextWindow, {
                     auto,
                     emergency,
+                    outputReserve,
+                    headroomTokens,
                 });
                 if (pressure.band === "below")
-                    return null;
+                    return callOriginal(activeSignal);
+                const effectiveRetain = compactionRetainTokens(compactionConfigState(candidate.compaction).original, target, contextWindow - outputReserve);
+                const scopedRatio = pressure.nativeThreshold / contextWindow;
+                const scopedThreshold = Math.floor(Math.min(contextWindow * scopedRatio, pressure.pressureBudget));
+                if (effectiveRetain === undefined || effectiveRetain >= scopedThreshold) {
+                    ctx.logger?.info?.("[lcx-codex] auto pressure: retaining upstream DSH threshold for the routed retention policy");
+                    return callOriginal(activeSignal);
+                }
                 const nativeFirst = pressure.band === "native";
                 const prunerPatch = nativeFirst
                     ? patchToolResultPruner(prunerState, () => ({ pruned: [], charsRemoved: 0 }))
                     : undefined;
-                const configPatch = patchCompactionConfig(compactionConfigState(candidate.compaction), (originalConfig) => adjustedCompactionConfig(originalConfig, target, auto / 100));
+                const configPatch = patchCompactionConfig(compactionConfigState(candidate.compaction), (originalConfig) => adjustedCompactionConfig(originalConfig, target, scopedRatio));
                 ctx.logger?.info?.(`[lcx-codex] auto pressure ${pressure.ratioPercent.toFixed(1)}%: ${nativeFirst ? "Native V2 first" : "emergency DSH prune allowed"} (native ${auto}%, emergency ${emergency}%)`);
                 try {
                     return await callOriginal(activeSignal);
@@ -835,8 +902,15 @@ async function restoreCompactionPressure(records) {
     for (const record of entries)
         record.policyScope.restore();
 }
-function messagesContainNativeCheckpoint(messages, session) {
-    return session !== undefined && messages.some((message) => checkpointStateForMessage(session, message));
+async function messagesContainNativeCheckpoint(ctx, messages, session) {
+    if (!session)
+        return false;
+    for (const message of messages) {
+        if (isPersistedMessage(message) && compactCheckpointId(message) &&
+            await checkpointStateForMessage(ctx, session, message))
+            return true;
+    }
+    return false;
 }
 function inputHasNativeState(input) {
     return input.some((item) => isRecord(item) && item.type === "compaction");
@@ -846,13 +920,14 @@ async function* managedResponsesStream(options, routeConfig, ctx) {
     try {
         if (options.stop !== undefined)
             throw Object.assign(new Error("LCX Responses does not support GenerateOptions.stop"), { code: "LCX_RESPONSES_UNSUPPORTED_OPTION" });
-        const prepared = await serializeNativeAware(options.messages, route, routeConfig, ctx, { signal: options.signal, tools: options.tools });
+        const projected = projectToolUpdates(options.messages, options.tools, undefined, options.toolHistory);
+        const prepared = await serializeNativeAware(projected.messages, route, routeConfig, ctx, { signal: options.signal, tools: projected.tools && [...projected.tools] });
         const cacheSessionId = promptCacheSessionId(route, routeConfig, ctx);
         const headers = await authenticatedHeaders(ctx, routeConfig, cacheSessionId, cacheSessionId === undefined ? null : route.sessionId);
         const body = buildResponsesBody({
             model: prepared.model,
             input: prepared.input,
-            tools: prepared.tools ?? options.tools,
+            tools: prepared.tools ?? (projected.tools && [...projected.tools]),
             sessionId: cacheSessionId,
             promptCacheKey: promptCacheKey(route, routeConfig, ctx),
             promptCacheRetention: promptCacheRetention(routeConfig),
@@ -890,9 +965,10 @@ async function* managedGrokNativeSearchStream(options, routeConfig, nativeSearch
     try {
         if (options.stop !== undefined)
             throw Object.assign(new Error("LCX Responses does not support GenerateOptions.stop"), { code: "LCX_RESPONSES_UNSUPPORTED_OPTION" });
-        const visibleTools = grokVisibleFunctionTools(options.tools, nativeSearch);
+        const projected = projectToolUpdates(options.messages, options.tools, undefined, options.toolHistory);
+        const visibleTools = grokVisibleFunctionTools(projected.tools, nativeSearch);
         const declaredToolNames = new Set(visibleTools?.map((tool) => tool.name) ?? []);
-        const prepared = await serializeNativeAware(options.messages, route, routeConfig, ctx, {
+        const prepared = await serializeNativeAware(projected.messages, route, routeConfig, ctx, {
             signal: options.signal,
             tools: visibleTools,
             grokNativeReplayRoute: nativeReplayRoute,
@@ -961,7 +1037,7 @@ function isGptLifecycleTarget(options) {
 async function* unavailableManagedRouteStream(options) {
     yield managedFailureChunk(Object.assign(new Error("LCX is enabled but the selected DSH route cannot be resolved as an authenticated OpenAI Responses wire route"), { code: "LCX_RESPONSES_ROUTE_UNAVAILABLE" }), options.signal);
 }
-function installInjected(ctx, configInput = {}) {
+function installInjected(ctx, configInput) {
     installSearchUsage(ctx);
     const baseConfig = normalizeConfig(configInput);
     let runtimeConfig = baseConfig;
@@ -997,73 +1073,66 @@ function installInjected(ctx, configInput = {}) {
             }
     }, { global: true });
     ctx.on("session/event", (session, event) => {
-        if (event.type === "request/header")
+        recordAgentRouteEvent(session, event);
+        // DSH 0.2 session/selectModel appends model/selection before the next
+        // prompt assembly projects tools (dsh-api-session-controller/lib/index.js:320).
+        if (event.type === "model/selection" || event.type === "request/header")
             for (const agent of managedAgents)
                 if (agentUsesSession(agent, session))
                     syncAgentTools(agent);
     }, { global: true });
-    const settingsEntry = {
-        enabled: false,
-        webSearch: false,
-        advancedHostedSearch: false,
-        alphaSearch: false,
-        grokNativeWebSearch: false,
-        grokNativeXSearch: false,
-        searchMediaPreview: false,
-    };
-    let source = () => settingsEntry;
-    ctx.settings.installSection(ctx, SETTINGS_NS, SettingsSchema, settingsEntry, {
-        setSource(current) {
-            source = current;
-        },
-        onChange() {
-            const value = source();
-            state.enabled = value.enabled;
-            state.webSearch = value.webSearch;
-            state.advancedHostedSearch = value.advancedHostedSearch;
-            state.alphaSearch = value.alphaSearch;
-            state.grokNativeWebSearch = value.grokNativeWebSearch;
-            state.grokNativeXSearch = value.grokNativeXSearch;
-            runtimeConfig = baseConfig;
-            refreshTools();
-        },
-    });
-    try {
-        const value = source();
-        Object.assign(state, {
-            enabled: Boolean(value.enabled),
-            webSearch: Boolean(value.webSearch),
-            advancedHostedSearch: Boolean(value.advancedHostedSearch),
-            alphaSearch: Boolean(value.alphaSearch),
-            grokNativeWebSearch: Boolean(value.grokNativeWebSearch),
-            grokNativeXSearch: Boolean(value.grokNativeXSearch),
-        });
+    ctx.effect(() => ctx.settings.configure({ auto: false }));
+    const syncSettings = () => {
+        state.enabled = configInput.enabled.get();
+        state.webSearch = configInput.webSearch.get();
+        state.advancedHostedSearch = configInput.advancedHostedSearch.get();
+        state.alphaSearch = configInput.alphaSearch.get();
+        state.grokNativeWebSearch = configInput.grokNativeWebSearch.get();
+        state.grokNativeXSearch = configInput.grokNativeXSearch.get();
         runtimeConfig = baseConfig;
-    }
-    catch { }
-    refreshTools();
+        refreshTools();
+    };
+    syncSettings();
+    ctx.on("loader/volatile-update", syncSettings);
+    ctx.on("settings/document-updated", refreshTools);
     ctx.inject(["compaction"], (compactionCtx) => {
         patchCompactionPressureService(resolveContextService(compactionCtx, "compaction"), state, () => runtimeConfig, ctx, compactionPatchRecords);
     });
-    ctx.on("agent/created", ({ agent }) => {
+    /**
+     * LCX instrumentation is optional capability, never a creation precondition.
+     * DSH 0.1.6 awaits `agent/created` serially, so an escaping failure would make
+     * an otherwise valid Agent uncreatable; `agent/status` stays a contained emit.
+     * Both edges therefore fail closed locally: the Agent runs uninstrumented and
+     * the reason is logged, rather than propagating into the host lifecycle.
+     */
+    const instrumentAgent = (agent, edge) => {
+        try {
+            managedAgents.add(agent);
+            syncAgentTools(agent);
+            const installed = patchCompactionPressureForAgent(agent, state, () => runtimeConfig, ctx, compactionPatchRecords);
+            if (installed)
+                ctx.logger?.info?.("[lcx-codex] pressure coordination installed through AgentPresets service resolver");
+        }
+        catch (error) {
+            ctx.logger?.warn?.(`[lcx-codex] agent instrumentation skipped on ${edge}: ${String(error)}`);
+        }
+    };
+    /** DSH 0.1.6 lifecycle source, recorded for diagnostics only. */
+    const startSource = (value) => typeof value === "string" && /^[a-z]+$/u.test(value) ? value : "unknown";
+    ctx.on("agent/created", (payload) => {
+        const agent = payload?.agent;
         if (agent === null || typeof agent !== "object")
             return;
-        managedAgents.add(agent);
-        syncAgentTools(agent);
-        const installed = patchCompactionPressureForAgent(agent, state, () => runtimeConfig, ctx, compactionPatchRecords);
-        if (installed)
-            ctx.logger?.info?.("[lcx-codex] pressure coordination installed through AgentPresets service resolver");
+        // `source` is startup | resume | clear | compact. Recorded, not branched on:
+        // no runtime evidence yet that a source needs different instrumentation.
+        instrumentAgent(agent, `agent/created(${startSource(payload?.source)})`);
     }, { global: true });
     ctx.on("agent/status", ({ agent, status }) => {
         if (status !== "running" ||
             agent === null ||
             typeof agent !== "object")
             return;
-        managedAgents.add(agent);
-        syncAgentTools(agent);
-        const installed = patchCompactionPressureForAgent(agent, state, () => runtimeConfig, ctx, compactionPatchRecords);
-        if (installed)
-            ctx.logger?.info?.("[lcx-codex] pressure coordination installed through AgentPresets service resolver");
+        instrumentAgent(agent, "agent/status(running)");
     }, { global: true });
     ctx.on("llm/stream", (options, next) => {
         if (options.purpose === "session-title")
@@ -1098,7 +1167,7 @@ function installInjected(ctx, configInput = {}) {
         await restoreCompactionPressure(compactionPatchRecords);
     }, "lcx-codex cleanup");
 }
-export function apply(ctx, configInput = {}) {
+export function apply(ctx, configInput) {
     return installInjected(ctx, configInput);
 }
 apply.inject = inject;

package/lib/invocation-policy-scope.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { abortError } from "./abort-error.js";
 const activePolicy = new AsyncLocalStorage();
 const projections = new WeakMap();
 function scopedValue(values, target, key) {
@@ -118,11 +119,6 @@ function restoreProjection(record) {
     }
     catch { }
 }
-function operationError(signal) {
-    if (signal?.reason instanceof Error)
-        return signal.reason;
-    return new DOMException("The operation was aborted", "AbortError");
-}
 export class InvocationPolicyScope {
     records = new Set();
     queue = [];
@@ -147,7 +143,7 @@ export class InvocationPolicyScope {
         if (this.closed)
             return Promise.reject(this.closeReason ?? new Error("invocation policy scope closed"));
         if (signal?.aborted)
-            return Promise.reject(operationError(signal));
+            return Promise.reject(abortError(signal));
         if (this.queue.length === 0 &&
             !this.exclusiveActive &&
             (mode === "shared" || this.sharedActive === 0)) {
@@ -165,7 +161,7 @@ export class InvocationPolicyScope {
                     if (index >= 0)
                         this.queue.splice(index, 1);
                     signal.removeEventListener("abort", onAbort);
-                    reject(operationError(signal));
+                    reject(abortError(signal));
                     this.flushQueue();
                 };
                 waiter.onAbort = onAbort;
@@ -193,7 +189,7 @@ export class InvocationPolicyScope {
                 this.queue.shift();
                 if (waiter.onAbort)
                     waiter.signal.removeEventListener("abort", waiter.onAbort);
-                waiter.reject(operationError(waiter.signal));
+                waiter.reject(abortError(waiter.signal));
                 continue;
             }
             if (waiter.mode === "exclusive") {