@jsonstudio/llms 0.6.795 → 0.6.938

package/dist/conversion/shared/responses-request-adapter.js

@@ -1,430 +1 @@
-import { normalizeFunctionCallId, normalizeFunctionCallOutputId } from './responses-id-utils.js';
-import { ensureResponsesInstructions } from './responses-instructions.js';
-import { serializeToolArguments, coerceBridgeRole, serializeToolOutput } from './bridge-message-utils.js';
-export function captureResponsesContext(payload, dto) {
-    ensureResponsesInstructions(payload);
-    const context = {
-        requestId: dto?.route?.requestId,
-        instructions: typeof payload.instructions === 'string' ? payload.instructions : undefined,
-        input: Array.isArray(payload.input) ? payload.input : undefined,
-        include: payload.include,
-        store: payload.store,
-        toolChoice: payload.tool_choice,
-        parallelToolCalls: typeof payload.parallel_tool_calls === 'boolean' ? payload.parallel_tool_calls : undefined,
-        metadata: (payload.metadata && typeof payload.metadata === 'object') ? { ...payload.metadata } : undefined,
-        responseFormat: payload.response_format,
-        stream: typeof payload.stream === 'boolean' ? payload.stream : undefined,
-        instructionsIsRaw: payload.instructions_is_raw === true,
-        isChatPayload: Array.isArray(payload.messages)
-    };
-    if (Array.isArray(payload.tools)) {
-        context.toolsRaw = payload.tools;
-    }
-    context.isResponsesPayload = !context.isChatPayload && Array.isArray(context.input);
-    return context;
-}
-export function buildChatRequestFromResponses(payload, context) {
-    const toolOutputs = Array.isArray(payload.tool_outputs)
-        ? payload.tool_outputs
-        : undefined;
-    const responseId = typeof payload.response_id === 'string' ? payload.response_id : undefined;
-    const hasInput = Array.isArray(payload.input) && payload.input.length > 0;
-    const submitOnlyMode = !!toolOutputs && !!responseId && !hasInput;
-    if (submitOnlyMode) {
-        return {
-            request: {
-                type: 'submit_tool_outputs',
-                model: payload.model,
-                response_id: responseId,
-                tool_outputs: toolOutputs,
-                stream: payload.stream === true
-            }
-        };
-    }
-    let toolsNormalized = Array.isArray(payload.tools)
-        ? normalizeTools(payload.tools)
-        : undefined;
-    // Inject MCP tools (CCR style) if enabled
-    try {
-        const enableMcp = String(process.env?.ROUTECODEX_MCP_ENABLE ?? '1') !== '0';
-        if (enableMcp) {
-            // Discover servers from prior inputs if present (best-effort; depends on client payload)
-            const discovered = new Set();
-            try {
-                const input = Array.isArray(payload.input) ? payload.input : [];
-                for (const it of input) {
-                    const t = (it && typeof it === 'object') ? it : {};
-                    const isToolCall = (t.type === 'function_call' || t.type === 'tool_call');
-                    const isToolMsg = (t.type === 'tool_message' || t.type === 'tool_result');
-                    if (isToolCall) {
-                        const args = typeof t.arguments === 'string' ? (() => { try {
-                            return JSON.parse(t.arguments);
-                        }
-                        catch {
-                            return {};
-                        } })() : (t.arguments || {});
-                        const sv = (args && typeof args === 'object') ? args.server : undefined;
-                        if (typeof sv === 'string' && sv.trim())
-                            discovered.add(sv.trim());
-                    }
-                    else if (isToolMsg) {
-                        const output = t?.output;
-                        const val = (typeof output === 'string') ? (() => { try {
-                            return JSON.parse(output);
-                        }
-                        catch {
-                            return null;
-                        } })() : (output || null);
-                        const args = (val && typeof val === 'object') ? val.arguments : undefined;
-                        const sv = (args && typeof args === 'object') ? args.server : undefined;
-                        if (typeof sv === 'string' && sv.trim())
-                            discovered.add(sv.trim());
-                    }
-                }
-            }
-            catch { /* ignore */ }
-            const list = toolsNormalized && Array.isArray(toolsNormalized) ? toolsNormalized : [];
-            const have = new Set(list.map((t) => (t?.function?.name || '').toString()));
-            const addTool = (def) => { if (!have.has(def.function.name)) {
-                list.push(def);
-                have.add(def.function.name);
-            } };
-            const obj = (props, req) => ({ type: 'object', properties: props, required: req, additionalProperties: false });
-            const serversRaw = String(process.env?.ROUTECODEX_MCP_SERVERS || '').trim();
-            const envServers = serversRaw ? serversRaw.split(',').map((s) => s.trim()).filter(Boolean) : [];
-            const merged = Array.from(new Set([...envServers, ...Array.from(discovered)]));
-            const serverProp = merged.length ? { type: 'string', enum: merged } : { type: 'string' };
-            // 初始仅注入 list_mcp_resources；有已知 server 后再注入其余 MCP 工具
-            // 与 Chat 路径保持一致：server 可选（不强制要求）
-            addTool({ type: 'function', function: { name: 'list_mcp_resources', strict: true, description: 'List resources from a given MCP server (arguments.server = server label).', parameters: obj({ server: serverProp, filter: { type: 'string' }, root: { type: 'string' } }, [] /* server optional */) } });
-            if (merged.length > 0) {
-                addTool({ type: 'function', function: { name: 'read_mcp_resource', strict: true, description: 'Read a resource via MCP server.', parameters: obj({ server: serverProp, uri: { type: 'string' } }, ['server', 'uri']) } });
-                addTool({ type: 'function', function: { name: 'list_mcp_resource_templates', strict: true, description: 'List resource templates via MCP server.', parameters: obj({ server: serverProp }, ['server']) } });
-            }
-            toolsNormalized = list;
-        }
-    }
-    catch { /* ignore MCP injection */ }
-    const mergedInput = mergeToolOutputsIntoInput(context.input, payload.tool_outputs);
-    let messages = mapResponsesInputToChat({
-        instructions: context.instructions,
-        input: mergedInput,
-        toolsNormalized
-    });
-    const preservedSystemMessages = Array.isArray(context.originalSystemMessages)
-        ? context.originalSystemMessages
-            .map((text) => (typeof text === 'string' ? text.trim() : ''))
-            .filter((text) => text.length > 0)
-            .map((text) => ({ role: 'system', content: text }))
-        : undefined;
-    if (preservedSystemMessages && preservedSystemMessages.length) {
-        const nonSystemMessages = messages.filter((msg) => String(msg?.role || '').toLowerCase() !== 'system');
-        messages = [...preservedSystemMessages, ...nonSystemMessages];
-    }
-    const request = {
-        model: payload.model || 'gpt-4.1-mini',
-        messages
-    };
-    for (const key of ['temperature', 'top_p', 'max_tokens', 'tool_choice', 'parallel_tool_calls', 'user', 'logit_bias', 'seed', 'response_format']) {
-        if (payload[key] !== undefined) {
-            request[key] = payload[key];
-        }
-    }
-    if (Array.isArray(toolsNormalized) && toolsNormalized.length) {
-        request.tools = toolsNormalized;
-    }
-    if (typeof payload.stream === 'boolean') {
-        request.stream = payload.stream;
-    }
-    return {
-        request,
-        toolsNormalized
-    };
-}
-function mergeToolOutputsIntoInput(input, toolOutputsRaw) {
-    const result = Array.isArray(input) ? [...input] : [];
-    if (!Array.isArray(toolOutputsRaw)) {
-        return result;
-    }
-    for (const entry of toolOutputsRaw) {
-        if (!entry || typeof entry !== 'object')
-            continue;
-        const data = entry;
-        const callIdRaw = data.tool_call_id ?? data.call_id ?? data.id;
-        if (typeof callIdRaw !== 'string' || !callIdRaw.trim())
-            continue;
-        const outputRaw = data.output;
-        const outputText = normalizeToolOutputPayload(outputRaw);
-        const normalizedCallId = normalizeFunctionCallId({ callId: callIdRaw, fallback: callIdRaw });
-        const outputId = normalizeFunctionCallOutputId({ callId: normalizedCallId, fallback: normalizedCallId });
-        result.push({
-            type: 'function_call_output',
-            id: outputId,
-            call_id: normalizedCallId,
-            output: outputText
-        });
-    }
-    return result;
-}
-function normalizeToolOutputPayload(payload) {
-    if (typeof payload === 'string') {
-        return payload;
-    }
-    if (payload == null) {
-        return '';
-    }
-    try {
-        return JSON.stringify(payload);
-    }
-    catch {
-        return String(payload);
-    }
-}
-function mapResponsesInputToChat(options) {
-    const { instructions, input, toolsNormalized } = options;
-    const messages = [];
-    if (typeof instructions === 'string' && instructions.length) {
-        messages.push({ role: 'system', content: instructions });
-    }
-    if (!Array.isArray(input))
-        return messages;
-    const toolNameById = new Map();
-    const toolCallIdAliases = new Map();
-    let lastToolCallId = null;
-    for (const entry of input) {
-        if (!entry || typeof entry !== 'object')
-            continue;
-        const entryType = typeof entry.type === 'string' ? entry.type.toLowerCase() : 'message';
-        if (typeof entry.content === 'string') {
-            const directText = (entry.content || '').toString().trim();
-            if (directText.length) {
-                const normalizedRole = coerceBridgeRole(entry.role || 'user');
-                messages.push({ role: normalizedRole, content: directText });
-                continue;
-            }
-        }
-        if (entryType === 'function_call' || entryType === 'tool_call') {
-            const rawName = typeof entry.name === 'string' ? entry.name : (typeof entry?.function?.name === 'string' ? entry.function.name : undefined);
-            const name = (typeof rawName === 'string' && rawName.includes('.')) ? rawName.slice(rawName.indexOf('.') + 1).trim() : rawName;
-            if (typeof name !== 'string' || !name.trim() || name.toLowerCase() === 'tool') {
-                continue;
-            }
-            const args = entry.arguments ?? entry?.function?.arguments ?? {};
-            const parsedArgs = args;
-            const callIdRaw = typeof entry.id === 'string' ? entry.id : (typeof entry.call_id === 'string' ? entry.call_id : `call_${Math.random().toString(36).slice(2, 8)}`);
-            const callId = normalizeFunctionCallId({ callId: callIdRaw, fallback: `fc_call_${messages.length + 1}` });
-            if (callIdRaw && callIdRaw !== callId) {
-                toolCallIdAliases.set(callIdRaw, callId);
-            }
-            const serialized = serializeToolArguments(parsedArgs, name, toolsNormalized).trim();
-            toolNameById.set(callId, name);
-            messages.push({ role: 'assistant', tool_calls: [{ id: callId, type: 'function', function: { name, arguments: serialized } }] });
-            lastToolCallId = callId;
-            continue;
-        }
-        if (entryType === 'function_call_output' || entryType === 'tool_result' || entryType === 'tool_message') {
-            let toolCallId = entry.tool_call_id || entry.call_id || entry.tool_use_id || entry.id || lastToolCallId;
-            if (toolCallId && toolCallIdAliases.has(String(toolCallId))) {
-                toolCallId = toolCallIdAliases.get(String(toolCallId)) || toolCallId;
-            }
-            else if (typeof toolCallId === 'string' && toolCallId.trim().length) {
-                const normalized = normalizeFunctionCallId({ callId: toolCallId, fallback: toolCallId });
-                if (normalized !== toolCallId) {
-                    toolCallIdAliases.set(toolCallId, normalized);
-                }
-                toolCallId = normalized;
-            }
-            const output = serializeToolOutput(entry);
-            if (toolCallId) {
-                try {
-                    let contentStr = output != null ? String(output) : '';
-                    if (!contentStr || contentStr.trim().length === 0) {
-                        contentStr = 'Command succeeded (no output).';
-                    }
-                    const nm = toolNameById.get(String(toolCallId));
-                    const toolMsg = { role: 'tool', tool_call_id: String(toolCallId), content: contentStr };
-                    if (typeof nm === 'string' && nm.trim().length)
-                        toolMsg.name = nm;
-                    messages.push(toolMsg);
-                }
-                catch {
-                    const fallback = (output ?? '');
-                    const nm = toolNameById.get(String(toolCallId));
-                    const toolMsg = { role: 'tool', tool_call_id: String(toolCallId), content: String(fallback) };
-                    if (typeof nm === 'string' && nm.trim().length)
-                        toolMsg.name = nm;
-                    messages.push(toolMsg);
-                }
-                lastToolCallId = null;
-            }
-            continue;
-        }
-        let handledViaExplicitMessage = false;
-        if (entry && typeof entry.message === 'object' && Array.isArray(entry.message?.content)) {
-            const explicit = entry.message;
-            const { text, toolCalls, toolMessages, lastCallId } = processMessageBlocks(Array.isArray(explicit.content) ? explicit.content : [], toolsNormalized, toolNameById, toolCallIdAliases, lastToolCallId);
-            if (toolCalls.length)
-                messages.push({ role: 'assistant', tool_calls: toolCalls });
-            for (const msg of toolMessages)
-                messages.push(msg);
-            const normalizedRole = coerceBridgeRole((explicit.role ?? entry.role) || 'user');
-            if (typeof text === 'string' && text.trim().length) {
-                messages.push({ role: normalizedRole, content: text.trim() });
-            }
-            lastToolCallId = lastCallId;
-            handledViaExplicitMessage = true;
-        }
-        if (!handledViaExplicitMessage) {
-            const { text, toolCalls, toolMessages, lastCallId } = processMessageBlocks(Array.isArray(entry.content) ? entry.content : [], toolsNormalized, toolNameById, toolCallIdAliases, lastToolCallId);
-            if (toolCalls.length)
-                messages.push({ role: 'assistant', tool_calls: toolCalls });
-            for (const msg of toolMessages)
-                messages.push(msg);
-            const normalizedRole = coerceBridgeRole(entry.role || 'user');
-            if (typeof text === 'string' && text.trim().length) {
-                messages.push({ role: normalizedRole, content: text.trim() });
-            }
-            lastToolCallId = lastCallId;
-        }
-        try {
-            const t = String(entry.type || '').toLowerCase();
-            if ((t === 'input_text' || t === 'text' || t === 'output_text' || t === 'commentary') && typeof entry.text === 'string') {
-                const normalizedRole = coerceBridgeRole(entry.role || 'user');
-                const s = entry.text;
-                if (s && s.length)
-                    messages.push({ role: normalizedRole, content: s });
-            }
-        }
-        catch { /* ignore */ }
-    }
-    return messages;
-}
-function processMessageBlocks(blocks, toolsNormalized, toolNameById, toolCallIdAliases, lastToolCallId) {
-    const textParts = [];
-    const toolCalls = [];
-    const toolMessages = [];
-    let currentLastCall = lastToolCallId;
-    for (const block of blocks) {
-        if (!block || typeof block !== 'object')
-            continue;
-        const type = typeof block.type === 'string' ? block.type.toLowerCase() : '';
-        if (type === 'input_text' || type === 'output_text' || type === 'text' || type === 'commentary') {
-            if (typeof block.text === 'string')
-                textParts.push(block.text);
-            else if (typeof block.content === 'string')
-                textParts.push(block.content);
-            continue;
-        }
-        if (type === 'message' && Array.isArray(block.content)) {
-            const nested = processMessageBlocks(block.content, toolsNormalized, toolNameById, toolCallIdAliases, currentLastCall);
-            if (nested.text)
-                textParts.push(nested.text);
-            for (const tc of nested.toolCalls)
-                toolCalls.push(tc);
-            for (const tm of nested.toolMessages)
-                toolMessages.push(tm);
-            currentLastCall = nested.lastCallId;
-            continue;
-        }
-        if (type === 'function_call') {
-            const rawName = typeof block.name === 'string' ? block.name : (typeof block?.function?.name === 'string' ? block.function.name : undefined);
-            const name = (typeof rawName === 'string' && rawName.includes('.')) ? rawName.slice(rawName.indexOf('.') + 1).trim() : rawName;
-            const args = block.arguments ?? block?.function?.arguments ?? {};
-            const parsedArgs = args;
-            const callIdRaw = typeof block.id === 'string' ? block.id : (typeof block.call_id === 'string' ? block.call_id : `call_${Math.random().toString(36).slice(2, 8)}`);
-            const callId = normalizeFunctionCallId({ callId: callIdRaw, fallback: `fc_call_${toolCalls.length + 1}` });
-            if (callIdRaw && callIdRaw !== callId) {
-                toolCallIdAliases.set(callIdRaw, callId);
-            }
-            if (typeof name !== 'string' || !name.trim()) {
-                currentLastCall = null;
-                continue;
-            }
-            const serialized = serializeToolArguments(parsedArgs, name, toolsNormalized).trim();
-            toolNameById.set(callId, name);
-            toolCalls.push({ id: callId, type: 'function', function: { name, arguments: serialized } });
-            currentLastCall = callId;
-            continue;
-        }
-        if (type === 'function_call_output' || type === 'tool_result' || type === 'tool_message') {
-            let toolCallId = block.tool_call_id || block.call_id || block.tool_use_id || block.id || currentLastCall;
-            if (toolCallId && toolCallIdAliases.has(String(toolCallId))) {
-                toolCallId = toolCallIdAliases.get(String(toolCallId)) || toolCallId;
-            }
-            else if (typeof toolCallId === 'string' && toolCallId.trim().length) {
-                const normalized = normalizeFunctionCallId({ callId: toolCallId, fallback: toolCallId });
-                if (normalized !== toolCallId) {
-                    toolCallIdAliases.set(toolCallId, normalized);
-                }
-                toolCallId = normalized;
-            }
-            const output = serializeToolOutput(block);
-            if (toolCallId) {
-                try {
-                    let contentStr = output != null ? String(output) : '';
-                    if (!contentStr || contentStr.trim().length === 0) {
-                        contentStr = 'Command succeeded (no output).';
-                    }
-                    const nm = toolNameById.get(String(toolCallId));
-                    const toolMsg = { role: 'tool', tool_call_id: String(toolCallId), content: contentStr };
-                    if (typeof nm === 'string' && nm.trim().length)
-                        toolMsg.name = nm;
-                    toolMessages.push(toolMsg);
-                }
-                catch {
-                    const fallback = (output ?? '');
-                    const nm = toolNameById.get(String(toolCallId));
-                    const toolMsg = { role: 'tool', tool_call_id: String(toolCallId), content: String(fallback) };
-                    if (typeof nm === 'string' && nm.trim().length)
-                        toolMsg.name = nm;
-                    toolMessages.push(toolMsg);
-                }
-                currentLastCall = null;
-            }
-            continue;
-        }
-    }
-    return {
-        text: textParts.length ? textParts.join('\n') : null,
-        toolCalls,
-        toolMessages,
-        lastCallId: currentLastCall
-    };
-}
-function normalizeTools(tools) {
-    const normalized = [];
-    for (const tool of tools) {
-        if (!tool || typeof tool !== 'object')
-            continue;
-        const originalType = typeof tool.type === 'string' ? tool.type : 'function';
-        const mappedType = ['function', 'custom'].includes(originalType.toLowerCase())
-            ? 'function'
-            : originalType;
-        const fn = (tool.function && typeof tool.function === 'object')
-            ? tool.function
-            : {};
-        const topName = typeof tool.name === 'string' ? tool.name : undefined;
-        const fnName = typeof fn.name === 'string' ? fn.name : undefined;
-        const name = (fnName || topName || '').trim();
-        if (!name)
-            continue;
-        const topDesc = typeof tool.description === 'string' ? tool.description : undefined;
-        const fnDesc = typeof fn.description === 'string' ? fn.description : undefined;
-        const description = fnDesc || topDesc;
-        const fnParams = Object.prototype.hasOwnProperty.call(fn, 'parameters') ? fn.parameters : undefined;
-        const topParams = Object.prototype.hasOwnProperty.call(tool, 'parameters') ? tool.parameters : undefined;
-        const parameters = fnParams !== undefined ? fnParams : topParams;
-        const strict = typeof fn.strict === 'boolean' ? fn.strict :
-            typeof tool.strict === 'boolean' ? tool.strict :
-                undefined;
-        const fnOut = { name };
-        if (description)
-            fnOut.description = description;
-        if (parameters !== undefined)
-            fnOut.parameters = parameters;
-        if (strict !== undefined)
-            fnOut.strict = strict;
-        normalized.push({ type: mappedType, function: fnOut });
-    }
-    return normalized;
-}
+export { captureResponsesContext, buildChatRequestFromResponses } from '../responses/responses-openai-bridge.js';

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 const DEFAULT_SNAPSHOT_ROOT = path.join(os.homedir(), '.routecodex', 'codex-samples');
 const PENDING_PROVIDER_DIR = '__pending__';
+const POLICY_VIOLATIONS_DIR = '__policy_violations__';
 function resolveSnapshotRoot() {
     const envOverride = process.env.RCC_SNAPSHOT_DIR ||
         process.env.ROUTECODEX_SNAPSHOT_DIR;
@@ -110,6 +111,59 @@ function extractNestedGroupRequestId(value) {
     }
     return undefined;
 }
+function extractNestedEntryEndpoint(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const obj = value;
+    const direct = readStringField(obj.entryEndpoint) ||
+        readStringField(obj.entry_endpoint) ||
+        readStringField(obj.endpoint);
+    if (direct) {
+        return direct;
+    }
+    const meta = obj.meta;
+    if (meta && typeof meta === 'object') {
+        const m = meta;
+        const fromMeta = readStringField(m.entryEndpoint) ||
+            readStringField(m.entry_endpoint) ||
+            readStringField(m.endpoint);
+        if (fromMeta) {
+            return fromMeta;
+        }
+        const ctx = m.context;
+        if (ctx && typeof ctx === 'object') {
+            const c = ctx;
+            const fromCtx = readStringField(c.entryEndpoint) ||
+                readStringField(c.entry_endpoint) ||
+                readStringField(c.endpoint);
+            if (fromCtx) {
+                return fromCtx;
+            }
+        }
+    }
+    const metadata = obj.metadata;
+    if (metadata && typeof metadata === 'object') {
+        const md = metadata;
+        const fromMetadata = readStringField(md.entryEndpoint) ||
+            readStringField(md.entry_endpoint) ||
+            readStringField(md.endpoint);
+        if (fromMetadata) {
+            return fromMetadata;
+        }
+    }
+    const runtime = obj.runtime;
+    if (runtime && typeof runtime === 'object') {
+        const r = runtime;
+        const fromRuntime = readStringField(r.entryEndpoint) ||
+            readStringField(r.entry_endpoint) ||
+            readStringField(r.endpoint);
+        if (fromRuntime) {
+            return fromRuntime;
+        }
+    }
+    return undefined;
+}
 function toErrorCode(error) {
     if (!error || typeof error !== 'object') {
         return undefined;
@@ -117,6 +171,45 @@ function toErrorCode(error) {
     const code = error.code;
     return typeof code === 'string' && code.trim() ? code : undefined;
 }
+function readNumberField(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function isHubPolicyStage(stage) {
+    return typeof stage === 'string' && stage.startsWith('hub_policy.');
+}
+function hasPolicyViolations(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    const violations = obj.violations;
+    if (Array.isArray(violations) && violations.length > 0) {
+        return true;
+    }
+    const summary = obj.summary;
+    if (summary && typeof summary === 'object') {
+        const total = readNumberField(summary.totalViolations);
+        if (typeof total === 'number' && total > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasPolicyEnforcementChanges(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    const removed = obj.removedTopLevelKeys;
+    if (Array.isArray(removed) && removed.length > 0) {
+        return true;
+    }
+    const flattened = obj.flattenedWrappers;
+    if (Array.isArray(flattened) && flattened.length > 0) {
+        return true;
+    }
+    return false;
+}
 async function writeUniqueFile(dir, baseName, contents) {
     const parsed = path.parse(baseName);
     const ext = parsed.ext || '.json';
@@ -203,9 +296,9 @@ async function promotePendingDir(options) {
         await mergeDirs(pending, dest);
     }
 }
-async function writeSnapshotFile(options) {
-    const root = resolveSnapshotRoot();
-    const folder = resolveSnapshotFolder(options.endpoint);
+async function writeSnapshotFile(options, rootOverride) {
+    const root = rootOverride || resolveSnapshotRoot();
+    const folder = resolveSnapshotFolder(extractNestedEntryEndpoint(options.data) || options.endpoint);
     const stageToken = sanitizeToken(options.stage, 'snapshot');
     const groupRequestToken = sanitizeToken(options.groupRequestId ||
         extractNestedGroupRequestId(options.data) ||
@@ -228,10 +321,25 @@ async function writeSnapshotFile(options) {
     await writeUniqueFile(dir, fileName, payload);
 }
 export async function writeSnapshotViaHooks(options) {
+    const stage = sanitizeToken(options.stage, 'snapshot');
+    // 1) Normal snapshots (always).
     try {
-        await writeSnapshotFile(options);
+        await writeSnapshotFile({ ...options, stage });
     }
     catch {
         // snapshot writes must never block callers
     }
+    // 2) Policy violations snapshots (copy-on-violation only).
+    // This allows leaving observe mode always on without drowning normal codex-samples traffic.
+    try {
+        if (isHubPolicyStage(stage) &&
+            (hasPolicyViolations(options.data) || hasPolicyEnforcementChanges(options.data))) {
+            const base = resolveSnapshotRoot();
+            const policyRoot = path.join(base, POLICY_VIOLATIONS_DIR);
+            await writeSnapshotFile({ ...options, stage }, policyRoot);
+        }
+    }
+    catch {
+        // never block callers
+    }
 }

package/dist/conversion/shared/tool-governor.js

@@ -9,6 +9,10 @@ import { normalizeExecCommandArgs } from '../../tools/exec-command/normalize.js'
 function isObject(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
 // Note: tool schema strict augmentation removed per alignment
 function enforceChatBudget(chat, _modelId) { return chat; }
+function isTruthyEnv(value) {
+    const v = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
 function tryWriteSnapshot(options, stage, data) {
     try {
         // 仅在 verbose 级别保存快照（环境变量）
@@ -251,7 +255,8 @@ export function normalizeApplyPatchToolCallsOnResponse(chat) {
                                 originalArgs: rawArgs,
                                 normalizedArgs: argsStr,
                                 validationError: reason,
-                                source: 'tool-governor.response'
+                                source: 'tool-governor.response',
+                                meta: { applyPatchToolMode: 'freeform' }
                             });
                             const snippet = typeof argsStr === 'string' && argsStr.trim().length
                                 ? argsStr.trim().slice(0, 200).replace(/\s+/g, ' ')
@@ -325,7 +330,8 @@ function normalizeSpecialToolCallsOnRequest(request) {
                                     originalArgs: rawArgs,
                                     normalizedArgs: argsStr,
                                     validationError: reason,
-                                    source: 'tool-governor.request'
+                                    source: 'tool-governor.request',
+                                    meta: { applyPatchToolMode: 'freeform' }
                                 });
                                 const snippet = typeof argsStr === 'string' && argsStr.trim().length
                                     ? argsStr.trim().slice(0, 200).replace(/\s+/g, ' ')

package/dist/conversion/shared/tool-harvester.d.ts

@@ -0,0 +1,31 @@
+type Unknown = Record<string, unknown>;
+export interface HarvestContext {
+    requestId?: string;
+    idPrefix?: string;
+    chunkSize?: number;
+    source?: 'chat' | 'responses' | 'messages';
+}
+export interface HarvestSignal {
+    type: 'delta' | 'final' | 'compat';
+    payload: Unknown;
+}
+export interface DeltaEvent {
+    tool_calls?: Array<{
+        index: number;
+        id: string;
+        type: 'function';
+        function: {
+            name?: string;
+            arguments?: string;
+        };
+    }>;
+    content?: string;
+    role?: string;
+}
+export interface HarvestResult {
+    deltaEvents: DeltaEvent[];
+    normalized?: Unknown;
+    stats?: Unknown;
+}
+export declare function harvestTools(signal: HarvestSignal, ctx?: HarvestContext): HarvestResult;
+export {};