@jsonstudio/llms 0.6.938 → 0.6.1164

package/dist/conversion/shared/bridge-policies.js

@@ -1,105 +1,5 @@
 import { RESPONSES_INSTRUCTIONS_REASONING_FIELD } from './reasoning-normalizer.js';
-const OPENAI_CHAT_ALLOWED_FIELDS = [
-    'messages',
-    'tools',
-    'tool_outputs',
-    'model',
-    'temperature',
-    'top_p',
-    'top_k',
-    'max_tokens',
-    'frequency_penalty',
-    'presence_penalty',
-    'logit_bias',
-    'response_format',
-    'parallel_tool_calls',
-    'tool_choice',
-    'seed',
-    'user',
-    'metadata',
-    'stop',
-    'stop_sequences',
-    'stream'
-];
-const ANTHROPIC_ALLOWED_FIELDS = [
-    'model',
-    'messages',
-    'tools',
-    'system',
-    'stop_sequences',
-    'temperature',
-    'top_p',
-    'top_k',
-    'max_tokens',
-    'max_output_tokens',
-    'metadata',
-    'stream',
-    'tool_choice'
-];
-const RESPONSES_ALLOWED_FIELDS = [
-    'id',
-    'object',
-    'created_at',
-    'model',
-    'status',
-    'input',
-    'instructions',
-    'output',
-    'output_text',
-    'required_action',
-    'response_id',
-    'previous_response_id',
-    'tool_outputs',
-    'tools',
-    'metadata',
-    'include',
-    'store',
-    'user',
-    'response_format',
-    'temperature',
-    'top_p',
-    'top_k',
-    'max_tokens',
-    'max_output_tokens',
-    'logit_bias',
-    'seed',
-    'parallel_tool_calls',
-    'tool_choice',
-    'stream',
-    'instructions_is_raw'
-];
-const GEMINI_ALLOWED_FIELDS = [
-    'model',
-    'contents',
-    'systemInstruction',
-    'system_instruction',
-    'generationConfig',
-    'generation_config',
-    'safetySettings',
-    'safety_settings',
-    'metadata',
-    'toolConfig',
-    'tool_config',
-    'tools',
-    'tool_choice',
-    'parallelToolCalls',
-    'parallel_tool_calls',
-    'responseMimeType',
-    'response_mime_type',
-    'stopSequences',
-    'stop_sequences',
-    'cachedContent',
-    'prompt',
-    'response',
-    'candidates',
-    'usageMetadata',
-    'responseMetadata',
-    'promptFeedback',
-    'modelVersion',
-    'client',
-    'user',
-    'stream'
-];
+import { ANTHROPIC_ALLOWED_FIELDS, GEMINI_ALLOWED_FIELDS, OPENAI_CHAT_ALLOWED_FIELDS, OPENAI_RESPONSES_ALLOWED_FIELDS } from './protocol-field-allowlists.js';
 function reasoningAction(idPrefix) {
     return {
         name: 'reasoning.extract',
@@ -134,7 +34,7 @@ const RESPONSES_POLICY = {
             reasoningAction('responses_reasoning'),
             toolCallNormalizationAction('responses_tool_call'),
             { name: 'tools.ensure-placeholders' },
-            { name: 'metadata.extra-fields', options: { allowedKeys: RESPONSES_ALLOWED_FIELDS } },
+            { name: 'metadata.extra-fields', options: { allowedKeys: OPENAI_RESPONSES_ALLOWED_FIELDS } },
             { name: 'metadata.provider-field', options: { field: 'metadata', target: 'providerMetadata' } },
             { name: 'metadata.provider-sentinel', options: { sentinel: '__rcc_provider_metadata', target: 'providerMetadata' } }
         ],
@@ -146,7 +46,7 @@ const RESPONSES_POLICY = {
             { name: 'messages.ensure-output-fields', options: { toolFallback: 'Tool call completed (no output).' } },
             { name: 'messages.ensure-system-instruction' },
             reasoningAction('responses_reasoning'),
-            { name: 'metadata.extra-fields', options: { allowedKeys: RESPONSES_ALLOWED_FIELDS } },
+            { name: 'metadata.extra-fields', options: { allowedKeys: OPENAI_RESPONSES_ALLOWED_FIELDS } },
             { name: 'metadata.provider-field', options: { field: 'metadata', target: 'providerMetadata' } },
             { name: 'metadata.provider-sentinel', options: { sentinel: '__rcc_provider_metadata', target: 'providerMetadata' } }
         ]
@@ -156,12 +56,12 @@ const RESPONSES_POLICY = {
             { name: 'reasoning.attach-output' },
             reasoningAction('responses_reasoning'),
             toolCallNormalizationAction('responses_tool_call'),
-            { name: 'metadata.extra-fields', options: { allowedKeys: RESPONSES_ALLOWED_FIELDS } }
+            { name: 'metadata.extra-fields', options: { allowedKeys: OPENAI_RESPONSES_ALLOWED_FIELDS } }
         ],
         outbound: [
             reasoningAction('responses_reasoning'),
             toolCallNormalizationAction('responses_tool_call'),
-            { name: 'metadata.extra-fields', options: { allowedKeys: RESPONSES_ALLOWED_FIELDS } }
+            { name: 'metadata.extra-fields', options: { allowedKeys: OPENAI_RESPONSES_ALLOWED_FIELDS } }
         ]
     }
 };

package/dist/conversion/shared/gemini-tool-utils.js

@@ -73,8 +73,8 @@ function cloneParameters(value) {
                     continue;
                 if (key === 'exclusiveMinimum' || key === 'exclusiveMaximum' || key === 'propertyNames')
                     continue;
-                // Keep Gemini tool schemas permissive to avoid upstream MALFORMED_FUNCTION_CALL on strict validation.
-                // Validation is enforced by llmswitch-core / servertool layers instead.
+                // Keep Gemini tool schemas mostly permissive to avoid upstream MALFORMED_FUNCTION_CALL on strict validation.
+                // We selectively re-introduce safe required fields for critical tools in `buildGeminiToolsFromBridge`.
                 if (key === 'required' || key === 'additionalProperties')
                     continue;
                 // Combinators are handled at the node level above.
@@ -166,6 +166,123 @@ export function buildGeminiToolsFromBridge(defs) {
         return undefined;
     }
     const tools = [];
+    const applyFixups = (name, parameters) => {
+        if (!parameters || typeof parameters !== 'object' || Array.isArray(parameters)) {
+            return parameters;
+        }
+        const params = parameters;
+        const propsRaw = params.properties;
+        const props = isPlainRecord(propsRaw) ? propsRaw : {};
+        const lowered = String(name || '').trim().toLowerCase();
+        if (lowered === 'exec_command') {
+            // Keep Gemini tool schema aligned with both historical Codex and our runtime tool signature:
+            // - Codex CLI: { cmd, workdir }
+            // - Some history: { command, workdir }
+            // Strict Gemini validation (and/or tool selection) is sensitive to schema/arg drift.
+            if (!Object.prototype.hasOwnProperty.call(props, 'cmd') && Object.prototype.hasOwnProperty.call(props, 'command')) {
+                props.cmd = props.command;
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'command') && Object.prototype.hasOwnProperty.call(props, 'cmd')) {
+                props.command = props.cmd;
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'cmd')) {
+                props.cmd = { type: 'string' };
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'command')) {
+                props.command = { type: 'string' };
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'workdir')) {
+                props.workdir = { type: 'string' };
+            }
+            params.properties = props;
+            // Avoid hard required keys for Gemini: the model may emit either alias (cmd/command),
+            // and "required" mismatch surfaces as MALFORMED_FUNCTION_CALL (empty reply) upstream.
+            try {
+                delete params.required;
+            }
+            catch {
+                params.required = undefined;
+            }
+            return params;
+        }
+        if (lowered === 'write_stdin') {
+            // Keep both aliases to avoid strict validation failures when the model echoes history.
+            if (!Object.prototype.hasOwnProperty.call(props, 'chars') && Object.prototype.hasOwnProperty.call(props, 'text')) {
+                props.chars = props.text;
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'text') && Object.prototype.hasOwnProperty.call(props, 'chars')) {
+                props.text = props.chars;
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'session_id')) {
+                props.session_id = { type: 'number' };
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'chars')) {
+                props.chars = { type: 'string' };
+            }
+            params.properties = props;
+            try {
+                delete params.required;
+            }
+            catch {
+                params.required = undefined;
+            }
+            return params;
+        }
+        if (lowered === 'apply_patch') {
+            // Gemini function calling needs JSON args, but Codex tool docs often describe apply_patch as "freeform".
+            // To prevent MALFORMED_FUNCTION_CALL, accept common aliases used by various bridge layers:
+            // - patch: canonical patch text
+            // - input/instructions/text: historical aliases containing patch text
+            if (!Object.prototype.hasOwnProperty.call(props, 'patch')) {
+                props.patch = {
+                    type: 'string',
+                    description: 'Patch text (*** Begin Patch / *** End Patch or GNU unified diff).'
+                };
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'input')) {
+                props.input = {
+                    type: 'string',
+                    description: 'Alias of patch (patch text). Prefer patch.'
+                };
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'instructions')) {
+                props.instructions = {
+                    type: 'string',
+                    description: 'Alias of patch (patch text). Prefer patch.'
+                };
+            }
+            if (!Object.prototype.hasOwnProperty.call(props, 'text')) {
+                props.text = {
+                    type: 'string',
+                    description: 'Alias of patch (patch text). Prefer patch.'
+                };
+            }
+            params.properties = props;
+            try {
+                delete params.required;
+            }
+            catch {
+                params.required = undefined;
+            }
+            return params;
+        }
+        return params;
+    };
+    const rewriteDescription = (name, description) => {
+        const lowered = String(name || '').trim().toLowerCase();
+        if (lowered === 'apply_patch') {
+            return ('Edit files by providing patch text in `patch` (string). ' +
+                'Supports "*** Begin Patch" / "*** End Patch" or GNU unified diff. ' +
+                '`input`/`instructions`/`text` are accepted as aliases.');
+        }
+        if (lowered === 'exec_command') {
+            return ('Run a shell command. Provide `cmd` (string) (alias: `command`) and optional `workdir` (string).');
+        }
+        if (lowered === 'write_stdin') {
+            return 'Write to an existing exec session. Provide `session_id` (number) and optional `chars` (string).';
+        }
+        return description;
+    };
     defs.forEach((def) => {
         if (!def || typeof def !== 'object') {
             return;
@@ -184,12 +301,12 @@ export function buildGeminiToolsFromBridge(defs) {
             : typeof def.description === 'string'
                 ? def.description
                 : undefined;
-        const parameters = cloneParameters(fnNode?.parameters ?? def.parameters ?? { type: 'object', properties: {} });
+        const parameters = applyFixups(name, cloneParameters(fnNode?.parameters ?? def.parameters ?? { type: 'object', properties: {} }));
         tools.push({
             functionDeclarations: [
                 {
                     name,
-                    description,
+                    description: rewriteDescription(name, description),
                     parameters
                 }
             ]

package/dist/conversion/shared/protocol-field-allowlists.d.ts

@@ -0,0 +1,7 @@
+export declare const OPENAI_CHAT_ALLOWED_FIELDS: readonly ["messages", "tools", "tool_outputs", "model", "temperature", "top_p", "top_k", "max_tokens", "frequency_penalty", "presence_penalty", "logit_bias", "response_format", "parallel_tool_calls", "tool_choice", "seed", "user", "metadata", "stop", "stop_sequences", "stream"];
+export declare const ANTHROPIC_ALLOWED_FIELDS: readonly ["model", "messages", "tools", "system", "stop_sequences", "temperature", "top_p", "top_k", "max_tokens", "max_output_tokens", "metadata", "stream", "tool_choice"];
+export declare const OPENAI_RESPONSES_ALLOWED_FIELDS: readonly ["id", "object", "created_at", "model", "status", "input", "instructions", "output", "output_text", "required_action", "response_id", "previous_response_id", "tool_outputs", "tools", "metadata", "include", "store", "user", "response_format", "temperature", "top_p", "top_k", "max_tokens", "max_output_tokens", "logit_bias", "seed", "parallel_tool_calls", "tool_choice", "stream", "instructions_is_raw"];
+export declare const GEMINI_ALLOWED_FIELDS: readonly ["model", "contents", "systemInstruction", "system_instruction", "generationConfig", "generation_config", "safetySettings", "safety_settings", "metadata", "toolConfig", "tool_config", "tools", "tool_choice", "parallelToolCalls", "parallel_tool_calls", "responseMimeType", "response_mime_type", "stopSequences", "stop_sequences", "cachedContent", "prompt", "response", "candidates", "usageMetadata", "responseMetadata", "promptFeedback", "modelVersion", "client", "user", "stream"];
+export declare const OPENAI_RESPONSES_PARAMETERS_WRAPPER_ALLOW_KEYS: readonly ["temperature", "top_p", "max_output_tokens", "seed", "logit_bias", "user", "parallel_tool_calls", "tool_choice", "response_format", "stream", "stop", "stop_sequences", "modalities", "top_k"];
+export declare const OPENAI_CHAT_PARAMETERS_WRAPPER_ALLOW_KEYS: readonly ["temperature", "top_p", "top_k", "max_tokens", "frequency_penalty", "presence_penalty", "logit_bias", "seed", "user", "parallel_tool_calls", "tool_choice", "response_format", "stream", "stop", "stop_sequences"];
+export declare const ANTHROPIC_PARAMETERS_WRAPPER_ALLOW_KEYS: readonly ["stop_sequences", "temperature", "top_p", "top_k", "max_tokens", "max_output_tokens", "metadata", "stream", "tool_choice"];

package/dist/conversion/shared/protocol-field-allowlists.js

@@ -0,0 +1,145 @@
+export const OPENAI_CHAT_ALLOWED_FIELDS = [
+    'messages',
+    'tools',
+    'tool_outputs',
+    'model',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'frequency_penalty',
+    'presence_penalty',
+    'logit_bias',
+    'response_format',
+    'parallel_tool_calls',
+    'tool_choice',
+    'seed',
+    'user',
+    'metadata',
+    'stop',
+    'stop_sequences',
+    'stream'
+];
+export const ANTHROPIC_ALLOWED_FIELDS = [
+    'model',
+    'messages',
+    'tools',
+    'system',
+    'stop_sequences',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'max_output_tokens',
+    'metadata',
+    'stream',
+    'tool_choice'
+];
+export const OPENAI_RESPONSES_ALLOWED_FIELDS = [
+    'id',
+    'object',
+    'created_at',
+    'model',
+    'status',
+    'input',
+    'instructions',
+    'output',
+    'output_text',
+    'required_action',
+    'response_id',
+    'previous_response_id',
+    'tool_outputs',
+    'tools',
+    'metadata',
+    'include',
+    'store',
+    'user',
+    'response_format',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'max_output_tokens',
+    'logit_bias',
+    'seed',
+    'parallel_tool_calls',
+    'tool_choice',
+    'stream',
+    'instructions_is_raw'
+];
+export const GEMINI_ALLOWED_FIELDS = [
+    'model',
+    'contents',
+    'systemInstruction',
+    'system_instruction',
+    'generationConfig',
+    'generation_config',
+    'safetySettings',
+    'safety_settings',
+    'metadata',
+    'toolConfig',
+    'tool_config',
+    'tools',
+    'tool_choice',
+    'parallelToolCalls',
+    'parallel_tool_calls',
+    'responseMimeType',
+    'response_mime_type',
+    'stopSequences',
+    'stop_sequences',
+    'cachedContent',
+    'prompt',
+    'response',
+    'candidates',
+    'usageMetadata',
+    'responseMetadata',
+    'promptFeedback',
+    'modelVersion',
+    'client',
+    'user',
+    'stream'
+];
+export const OPENAI_RESPONSES_PARAMETERS_WRAPPER_ALLOW_KEYS = [
+    'temperature',
+    'top_p',
+    'max_output_tokens',
+    'seed',
+    'logit_bias',
+    'user',
+    'parallel_tool_calls',
+    'tool_choice',
+    'response_format',
+    'stream',
+    'stop',
+    'stop_sequences',
+    'modalities',
+    'top_k'
+];
+export const OPENAI_CHAT_PARAMETERS_WRAPPER_ALLOW_KEYS = [
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'frequency_penalty',
+    'presence_penalty',
+    'logit_bias',
+    'seed',
+    'user',
+    'parallel_tool_calls',
+    'tool_choice',
+    'response_format',
+    'stream',
+    'stop',
+    'stop_sequences'
+];
+export const ANTHROPIC_PARAMETERS_WRAPPER_ALLOW_KEYS = [
+    'stop_sequences',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'max_output_tokens',
+    'metadata',
+    'stream',
+    'tool_choice'
+];

package/dist/conversion/shared/reasoning-tool-normalizer.js

@@ -97,11 +97,13 @@ export function normalizeMessageReasoningTools(message, options) {
     const trimmed = (cleanedText || '').trim();
     writeReasoningContent(message, trimmed);
     // Chat 统一行为：如果 message 本身没有正文内容，但存在非空 reasoning_content，
-    // 则将思考内容提升到正文，前后包裹 [思考] 标记，避免客户端只看到“空回答”。
+    // 则将思考内容提升到正文，前后包裹 [思考] 标记，避免客户端只看到"空回答"。
     const rawContent = message.content;
     if ((typeof rawContent !== 'string' || rawContent.trim().length === 0) &&
         trimmed.length > 0) {
-        message.content = `[思考]\n${trimmed}\n[/思考]`;
+        // 检查是否已经包含 [思考] 标签，避免重复嵌套
+        const hasThinkingTags = trimmed.includes('[思考]') && trimmed.includes('[/思考]');
+        message.content = hasThinkingTags ? trimmed : `[思考]\n${trimmed}\n[/思考]`;
     }
     if (!Array.isArray(toolCalls) || toolCalls.length === 0) {
         return { toolCallsAdded: 0, cleanedReasoning: trimmed };

package/dist/conversion/shared/snapshot-hooks.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 const DEFAULT_SNAPSHOT_ROOT = path.join(os.homedir(), '.routecodex', 'codex-samples');
+const DEFAULT_ERRORSAMPLES_ROOT = path.join(os.homedir(), '.routecodex', 'errorsamples');
 const PENDING_PROVIDER_DIR = '__pending__';
 const POLICY_VIOLATIONS_DIR = '__policy_violations__';
 function resolveSnapshotRoot() {
@@ -12,6 +13,75 @@ function resolveSnapshotRoot() {
     }
     return DEFAULT_SNAPSHOT_ROOT;
 }
+function resolveErrorsamplesRoot() {
+    const envOverride = process.env.ROUTECODEX_ERRORSAMPLES_DIR ||
+        process.env.ROUTECODEX_ERROR_SAMPLES_DIR;
+    if (envOverride && String(envOverride).trim()) {
+        return path.resolve(String(envOverride).trim());
+    }
+    return DEFAULT_ERRORSAMPLES_ROOT;
+}
+function safeErrorsampleName(name) {
+    return String(name || 'sample').replace(/[^\w.-]/g, '_');
+}
+async function cleanupZeroByteJsonFiles(dir) {
+    let entries = [];
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const candidates = entries.filter((name) => name.endsWith('.json'));
+    if (candidates.length === 0) {
+        return;
+    }
+    await Promise.allSettled(candidates.map(async (name) => {
+        const full = path.join(dir, name);
+        try {
+            const st = await fs.stat(full);
+            if (!st.isFile() || st.size > 0) {
+                return;
+            }
+            await fs.unlink(full);
+        }
+        catch {
+            // ignore cleanup failures
+        }
+    }));
+}
+async function writeUniqueErrorsampleFile(dir, baseName, contents) {
+    const parsed = path.parse(baseName);
+    const ext = parsed.ext || '.json';
+    const stem = parsed.name || 'sample';
+    const tmpDir = path.join(dir, '_tmp');
+    try {
+        await fs.mkdir(tmpDir, { recursive: true });
+    }
+    catch {
+        // ignore; fallback to direct writes
+    }
+    for (let i = 0; i < 32; i += 1) {
+        const suffix = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const fileName = `${stem}_${suffix}${ext}`;
+        try {
+            const dest = path.join(dir, fileName);
+            const tmp = path.join(tmpDir, `${fileName}.tmp`);
+            await fs.writeFile(tmp, contents, { encoding: 'utf-8', flag: 'wx' });
+            await fs.rename(tmp, dest);
+            return;
+        }
+        catch (error) {
+            if (toErrorCode(error) === 'EEXIST') {
+                continue;
+            }
+            throw error;
+        }
+    }
+    // last resort (best-effort overwrite into a timestamped file)
+    const fallback = `${stem}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}${ext}`;
+    await fs.writeFile(path.join(dir, fallback), contents, { encoding: 'utf-8' });
+}
 function resolveSnapshotFolder(endpoint) {
     const lowered = (endpoint || '').toLowerCase();
     if (lowered.includes('/responses')) {
@@ -177,6 +247,9 @@ function readNumberField(value) {
 function isHubPolicyStage(stage) {
     return typeof stage === 'string' && stage.startsWith('hub_policy.');
 }
+function isHubToolSurfaceStage(stage) {
+    return typeof stage === 'string' && stage.startsWith('hub_toolsurface.');
+}
 function hasPolicyViolations(value) {
     if (!value || typeof value !== 'object') {
         return false;
@@ -195,6 +268,24 @@ function hasPolicyViolations(value) {
     }
     return false;
 }
+function hasToolSurfaceDiff(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    const diffCount = readNumberField(obj.diffCount);
+    if (typeof diffCount === 'number' && diffCount > 0) {
+        return true;
+    }
+    // Response-side tool surface mismatch detection records expected/detected protocol
+    // without a numeric diffCount; treat any protocol mismatch as a diff.
+    const expected = readStringField(obj.expectedProtocol);
+    const detected = readStringField(obj.detectedProtocol);
+    if (expected && detected && expected !== detected) {
+        return true;
+    }
+    return false;
+}
 function hasPolicyEnforcementChanges(value) {
     if (!value || typeof value !== 'object') {
         return false;
@@ -214,11 +305,25 @@ async function writeUniqueFile(dir, baseName, contents) {
     const parsed = path.parse(baseName);
     const ext = parsed.ext || '.json';
     const stem = parsed.name || 'snapshot';
+    const tmpPrefix = `.__tmp_${stem}_${process.pid}_${Date.now()}`;
     for (let i = 0; i < 64; i += 1) {
         const name = i === 0 ? `${stem}${ext}` : `${stem}_${i}${ext}`;
         try {
-            await fs.writeFile(path.join(dir, name), contents, { encoding: 'utf-8', flag: 'wx' });
-            return;
+            const dest = path.join(dir, name);
+            const tmp = path.join(dir, `${tmpPrefix}_${Math.random().toString(36).slice(2, 8)}${ext}`);
+            await fs.writeFile(tmp, contents, { encoding: 'utf-8', flag: 'wx' });
+            try {
+                await fs.link(tmp, dest);
+                await fs.unlink(tmp).catch(() => { });
+                return;
+            }
+            catch (error) {
+                await fs.unlink(tmp).catch(() => { });
+                if (toErrorCode(error) === 'EEXIST') {
+                    continue;
+                }
+                throw error;
+            }
         }
         catch (error) {
             if (toErrorCode(error) === 'EEXIST') {
@@ -228,7 +333,15 @@ async function writeUniqueFile(dir, baseName, contents) {
         }
     }
     const fallback = `${stem}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}${ext}`;
-    await fs.writeFile(path.join(dir, fallback), contents, 'utf-8');
+    const dest = path.join(dir, fallback);
+    const tmp = path.join(dir, `${tmpPrefix}_${Math.random().toString(36).slice(2, 8)}${ext}`);
+    await fs.writeFile(tmp, contents, { encoding: 'utf-8', flag: 'wx' });
+    try {
+        await fs.link(tmp, dest);
+    }
+    finally {
+        await fs.unlink(tmp).catch(() => { });
+    }
 }
 const requestProviderIndex = globalThis
     .__routecodexSnapshotProviderIndex ||
@@ -313,6 +426,23 @@ async function writeSnapshotFile(options, rootOverride) {
     }
     const dir = path.join(root, folder, providerToken, groupRequestToken);
     await fs.mkdir(dir, { recursive: true });
+    // Write a stable runtime marker for this request folder (best-effort).
+    try {
+        const metaPath = path.join(dir, '__runtime.json');
+        const payload = JSON.stringify({
+            timestamp: new Date().toISOString(),
+            versions: {
+                routecodex: process.env.ROUTECODEX_VERSION,
+                routecodexBuildTime: process.env.ROUTECODEX_BUILD_TIME,
+                llmswitchCore: process.env.ROUTECODEX_LLMSWITCH_CORE_VERSION,
+                node: process.version
+            }
+        }, null, 2);
+        await fs.writeFile(metaPath, payload, { encoding: 'utf-8', flag: 'wx' }).catch(() => { });
+    }
+    catch {
+        // ignore
+    }
     const spacing = options.verbosity === 'minimal' ? undefined : 2;
     const payload = spacing !== undefined
         ? JSON.stringify(options.data, null, spacing)
@@ -342,4 +472,37 @@ export async function writeSnapshotViaHooks(options) {
     catch {
         // never block callers
     }
+    // 3) Tool surface diffs (copy-on-diff only) → ~/.routecodex/errorsamples/tool-surface/
+    try {
+        if (isHubToolSurfaceStage(stage) && hasToolSurfaceDiff(options.data)) {
+            const root = resolveErrorsamplesRoot();
+            const dir = path.join(root, safeErrorsampleName('tool-surface'));
+            await fs.mkdir(dir, { recursive: true });
+            // Best-effort cleanup: when the process exits abruptly, an in-flight async
+            // write can leave behind 0-byte placeholder files. Keep the observable
+            // directory clean so operators can tail it.
+            await cleanupZeroByteJsonFiles(dir);
+            const stamp = new Date().toISOString();
+            const payload = {
+                kind: 'hub_toolsurface_diff',
+                timestamp: stamp,
+                endpoint: options.endpoint,
+                stage,
+                requestId: options.requestId,
+                providerKey: options.providerKey,
+                groupRequestId: options.groupRequestId,
+                runtime: {
+                    routecodexVersion: process.env.ROUTECODEX_VERSION,
+                    routecodexBuildTime: process.env.ROUTECODEX_BUILD_TIME,
+                    llmswitchCore: process.env.ROUTECODEX_LLMSWITCH_CORE_VERSION,
+                    node: process.version
+                },
+                observation: options.data
+            };
+            await writeUniqueErrorsampleFile(dir, `${safeErrorsampleName(stage)}.json`, JSON.stringify(payload, null, 2));
+        }
+    }
+    catch {
+        // never block callers
+    }
 }