@jsonstudio/llms 0.6.938 → 0.6.1164

package/dist/servertool/handlers/vision.js

@@ -1,9 +1,10 @@
 import { registerServerToolHandler } from '../registry.js';
 import { cloneJson, extractTextFromChatLike } from '../server-side-tools.js';
-import { buildEntryAwareFollowupPayload, dropToolByFunctionName, extractCapturedChatSeed } from './followup-request-builder.js';
+import { extractCapturedChatSeed } from './followup-request-builder.js';
+import { reenterServerToolBackend } from '../reenter-backend.js';
 const FLOW_ID = 'vision_flow';
 const handler = async (ctx) => {
-    if (!ctx.options.reenterPipeline) {
+    if (!ctx.capabilities.reenterPipeline) {
         return null;
     }
     if (!shouldRunVisionFlow(ctx)) {
@@ -17,43 +18,70 @@ const handler = async (ctx) => {
     if (!analysisPayload) {
         return null;
     }
-    const visionResponse = await ctx.options.reenterPipeline({
+    const backend = {
+        kind: 'vision_analysis',
+        requestIdSuffix: ':vision',
         entryEndpoint: '/v1/chat/completions',
-        requestId: `${ctx.options.requestId}:vision`,
-        body: analysisPayload,
-        metadata: {
-            routeHint: 'vision',
-            serverToolFollowup: true,
-            stream: false
-        }
-    });
-    const visionBody = visionResponse.body && typeof visionResponse.body === 'object'
-        ? visionResponse.body
-        : null;
-    if (!visionBody) {
-        return null;
-    }
-    const visionSummary = extractTextFromChatLike(visionBody);
-    if (!visionSummary) {
-        return null;
-    }
-    const followupPayload = buildVisionFollowupPayload(captured, visionSummary, ctx.options.entryEndpoint || ctx.adapterContext?.entryEndpoint || '/v1/chat/completions');
-    if (!followupPayload) {
-        return null;
-    }
-    const execution = {
-        flowId: FLOW_ID,
-        followup: {
-            requestIdSuffix: ':vision_followup',
-            payload: followupPayload
-        }
+        payload: analysisPayload
     };
     return {
-        chatResponse: ctx.base,
-        execution
+        flowId: FLOW_ID,
+        backend,
+        finalize: async ({ backendResult }) => {
+            if (!backendResult || backendResult.kind !== 'vision_analysis') {
+                return null;
+            }
+            const body = backendResult.response.body && typeof backendResult.response.body === 'object'
+                ? backendResult.response.body
+                : null;
+            if (!body) {
+                return null;
+            }
+            const visionSummary = extractTextFromChatLike(body);
+            if (!visionSummary) {
+                return null;
+            }
+            // Fail-closed: if we cannot build followup seed, do not intercept.
+            const seed = extractCapturedChatSeed(captured);
+            if (!seed) {
+                return null;
+            }
+            return {
+                chatResponse: ctx.base,
+                execution: {
+                    flowId: FLOW_ID,
+                    followup: {
+                        requestIdSuffix: ':vision_followup',
+                        entryEndpoint: ctx.entryEndpoint,
+                        injection: {
+                            ops: [
+                                { op: 'inject_vision_summary', summary: visionSummary },
+                                { op: 'drop_tool_by_name', name: 'vision' }
+                            ]
+                        }
+                    }
+                }
+            };
+        }
     };
 };
 registerServerToolHandler('vision_auto', handler, { trigger: 'auto' });
+export async function executeVisionBackendPlan(args) {
+    const plan = args.plan;
+    const options = args.options;
+    if (!options.reenterPipeline) {
+        return { kind: 'vision_analysis', response: {} };
+    }
+    const response = await reenterServerToolBackend({
+        reenterPipeline: options.reenterPipeline,
+        entryEndpoint: plan.entryEndpoint,
+        requestId: `${options.requestId}${plan.requestIdSuffix}`,
+        body: plan.payload,
+        providerProtocol: 'openai-chat',
+        routeHint: 'vision'
+    });
+    return { kind: 'vision_analysis', response };
+}
 function shouldRunVisionFlow(ctx) {
     const record = ctx.adapterContext;
     const followupFlag = record.serverToolFollowup === true || record.serverToolFollowup === 'true';
@@ -194,87 +222,3 @@ function buildVisionUserMessage(source) {
     }
     return message;
 }
-function buildVisionFollowupPayload(source, summary, entryEndpoint) {
-    const seed = extractCapturedChatSeed(source);
-    if (!seed) {
-        return null;
-    }
-    const messages = injectVisionSummary(seed.messages, summary);
-    const filteredTools = dropToolByFunctionName(seed.tools, 'vision');
-    return buildEntryAwareFollowupPayload({
-        entryEndpoint,
-        model: seed.model,
-        messages,
-        ...(filteredTools ? { tools: filteredTools } : {}),
-        ...(seed.parameters ? { parameters: seed.parameters } : {})
-    });
-}
-function injectVisionSummary(source, summary) {
-    const messages = Array.isArray(source) ? cloneJson(source) : [];
-    let injected = false;
-    for (const message of messages) {
-        if (!message || typeof message !== 'object')
-            continue;
-        const content = message.content;
-        if (!Array.isArray(content))
-            continue;
-        const nextParts = [];
-        let removed = false;
-        for (const part of content) {
-            if (part && typeof part === 'object') {
-                const typeValue = typeof part.type === 'string'
-                    ? part.type.toLowerCase()
-                    : '';
-                if (typeValue.includes('image')) {
-                    removed = true;
-                    continue;
-                }
-            }
-            nextParts.push(part);
-        }
-        if (removed) {
-            nextParts.push({
-                type: 'text',
-                text: `[Vision] ${summary}`
-            });
-            message.content = nextParts;
-            injected = true;
-        }
-    }
-    if (!injected) {
-        for (let i = messages.length - 1; i >= 0; i -= 1) {
-            const msg = messages[i];
-            if (!msg || typeof msg !== 'object')
-                continue;
-            const role = typeof msg.role === 'string'
-                ? msg.role.toLowerCase()
-                : '';
-            if (role !== 'user')
-                continue;
-            const content = msg.content;
-            if (Array.isArray(content)) {
-                content.push({
-                    type: 'text',
-                    text: `[Vision] ${summary}`
-                });
-                injected = true;
-                break;
-            }
-            if (typeof content === 'string' && content.length) {
-                msg.content = `${content}\n[Vision] ${summary}`;
-            }
-            else {
-                msg.content = `[Vision] ${summary}`;
-            }
-            injected = true;
-            break;
-        }
-    }
-    if (!injected) {
-        messages.push({
-            role: 'system',
-            content: `[Vision] ${summary}`
-        });
-    }
-    return messages;
-}

package/dist/servertool/handlers/web-search.d.ts

@@ -1 +1,7 @@
-export {};
+import type { ServerSideToolEngineOptions, ServerToolBackendPlan, ServerToolBackendResult } from '../types.js';
+export declare function executeWebSearchBackendPlan(args: {
+    plan: Extract<ServerToolBackendPlan, {
+        kind: 'web_search';
+    }>;
+    options: ServerSideToolEngineOptions;
+}): Promise<ServerToolBackendResult>;

package/dist/servertool/handlers/web-search.js

@@ -1,14 +1,15 @@
 import { buildOpenAIChatFromGeminiResponse } from '../../conversion/codecs/gemini-openai-codec.js';
 import { registerServerToolHandler } from '../registry.js';
 import { cloneJson, extractTextFromChatLike } from '../server-side-tools.js';
-import { buildEntryAwareFollowupPayload, dropToolByFunctionName, extractCapturedChatSeed } from './followup-request-builder.js';
+import { extractCapturedChatSeed } from './followup-request-builder.js';
+import { reenterServerToolBackend } from '../reenter-backend.js';
 const FLOW_ID = 'web_search_flow';
 const handler = async (ctx) => {
     const toolCall = ctx.toolCall;
     if (!toolCall) {
         return null;
     }
-    if (!ctx.options.providerInvoker && !ctx.options.reenterPipeline) {
+    if (!ctx.capabilities.providerInvoker && !ctx.capabilities.reenterPipeline) {
         return null;
     }
     const webSearchConfig = getWebSearchConfig(ctx.adapterContext);
@@ -28,57 +29,61 @@ const handler = async (ctx) => {
         return null;
     }
     const resultCount = normalizeResultCount(parsedArgs.count);
-    let chosenEngine;
-    let chosenResult;
-    let lastFailure;
-    for (const engine of engines) {
-        const backendResult = await executeWebSearchBackend({
-            ctx,
-            engine,
-            query,
-            recency: parsedArgs.recency,
-            resultCount
-        });
-        if (backendResult.ok) {
-            chosenEngine = engine;
-            chosenResult = backendResult;
-            break;
-        }
-        lastFailure = { engine, result: backendResult };
-    }
-    if (!chosenEngine || !chosenResult) {
-        if (!lastFailure) {
-            return null;
-        }
-        chosenEngine = lastFailure.engine;
-        chosenResult = lastFailure.result;
-    }
-    const patched = injectWebSearchToolResult(ctx.base, toolCall, chosenEngine, query, chosenResult);
-    const followupPayload = buildWebSearchFollowupPayload(ctx.adapterContext, patched, ctx.options.entryEndpoint || ctx.adapterContext?.entryEndpoint || '/v1/chat/completions');
-    const execution = {
+    const recency = typeof parsedArgs.recency === 'string' && parsedArgs.recency.trim() ? parsedArgs.recency.trim() : undefined;
+    const backend = {
+        kind: 'web_search',
+        requestIdSuffix: ':web_search',
+        query,
+        ...(recency ? { recency } : {}),
+        resultCount,
+        engines
+    };
+    return {
         flowId: FLOW_ID,
-        followup: followupPayload
-            ? {
-                requestIdSuffix: ':web_search_followup',
-                payload: followupPayload,
-                metadata: {
-                    // keep minimal; servertool engine will inject the standard followup metadata defaults
-                    serverToolFollowup: true
-                }
+        backend,
+        finalize: async ({ backendResult }) => {
+            if (!backendResult || backendResult.kind !== 'web_search') {
+                return null;
             }
-            : undefined,
-        context: {
-            web_search: {
-                engineId: chosenEngine.id,
-                providerKey: chosenEngine.providerKey,
-                summary: chosenResult.summary
+            const chosen = backendResult.chosenEngine;
+            if (!chosen || !chosen.id || !chosen.providerKey) {
+                return null;
             }
+            const patched = injectWebSearchToolResult(ctx.base, toolCall, { id: chosen.id, providerKey: chosen.providerKey }, query, backendResult.result);
+            const seed = extractCapturedChatSeed(ctx.adapterContext?.capturedChatRequest);
+            const assistantMessage = seed ? extractAssistantMessage(patched) : null;
+            const toolMessages = seed ? buildToolMessages(patched) : [];
+            const canFollowup = Boolean(seed && assistantMessage && toolMessages.length > 0);
+            return {
+                chatResponse: patched,
+                execution: {
+                    flowId: FLOW_ID,
+                    ...(canFollowup
+                        ? {
+                            followup: {
+                                requestIdSuffix: ':web_search_followup',
+                                entryEndpoint: ctx.entryEndpoint,
+                                injection: {
+                                    ops: [
+                                        { op: 'append_assistant_message' },
+                                        { op: 'append_tool_messages_from_tool_outputs' },
+                                        { op: 'drop_tool_by_name', name: 'web_search' }
+                                    ]
+                                }
+                            }
+                        }
+                        : {}),
+                    context: {
+                        web_search: {
+                            engineId: chosen.id,
+                            providerKey: chosen.providerKey,
+                            summary: backendResult.result.summary
+                        }
+                    }
+                }
+            };
         }
     };
-    return {
-        chatResponse: patched,
-        execution
-    };
 };
 registerServerToolHandler('web_search', handler);
 function parseToolArguments(toolCall) {
@@ -220,19 +225,19 @@ function normalizeResultCount(value) {
     return 10;
 }
 async function executeWebSearchBackend(args) {
-    const { ctx, engine, query } = args;
+    const { options, engine, query } = args;
     const recency = typeof args.recency === 'string' && args.recency.trim() ? args.recency.trim() : undefined;
     let summary = '';
     let hits = [];
     let ok = true;
     try {
-        logServerToolWebSearch(engine, ctx.options.requestId, query);
-        const requestSuffix = `:web_search:${engine.id}`;
+        logServerToolWebSearch(engine, options.requestId, query);
+        const requestSuffix = args.requestSuffix;
         // 对于 iFlow，直接通过 providerInvoker 调用 /chat/retrieve，
         // 即使 reenterPipeline 可用，也不走 Chat 模型 + tools。
-        if (isIflowWebSearchEngine(engine) && ctx.options.providerInvoker) {
+        if (isIflowWebSearchEngine(engine) && options.providerInvoker) {
             const backendResult = await executeIflowWebSearchViaProvider({
-                ctx,
+                options,
                 engine,
                 query,
                 recency,
@@ -243,17 +248,15 @@ async function executeWebSearchBackend(args) {
             hits = backendResult.hits;
             ok = backendResult.ok;
         }
-        else if (ctx.options.reenterPipeline) {
+        else if (options.reenterPipeline) {
             const payload = buildWebSearchReenterPayload(engine, query, recency, args.resultCount);
-            const followup = await ctx.options.reenterPipeline({
+            const followup = await reenterServerToolBackend({
+                reenterPipeline: options.reenterPipeline,
                 entryEndpoint: '/v1/chat/completions',
-                requestId: `${ctx.options.requestId}${requestSuffix}`,
+                requestId: `${options.requestId}${requestSuffix}`,
                 body: payload,
-                metadata: {
-                    routeHint: 'web_search',
-                    serverToolFollowup: true,
-                    stream: false
-                }
+                providerProtocol: 'openai-chat',
+                routeHint: 'web_search'
             });
             const body = followup.body && typeof followup.body === 'object' ? followup.body : null;
             if (body) {
@@ -263,7 +266,7 @@ async function executeWebSearchBackend(args) {
                     try {
                         // eslint-disable-next-line no-console
                         console.log('\x1b[38;5;27m[server-tool][web_search][backend_debug]' +
-                            ` requestId=${ctx.options.requestId}${requestSuffix} payload=${JSON.stringify(body).slice(0, 2000)}\x1b[0m`);
+                            ` requestId=${options.requestId}${requestSuffix} payload=${JSON.stringify(body).slice(0, 2000)}\x1b[0m`);
                     }
                     catch {
                         /* logging best-effort */
@@ -271,9 +274,9 @@ async function executeWebSearchBackend(args) {
                 }
             }
         }
-        else if (ctx.options.providerInvoker) {
+        else if (options.providerInvoker) {
             summary = await executeWebSearchViaProvider({
-                ctx,
+                options,
                 engine,
                 query,
                 recency,
@@ -305,7 +308,7 @@ async function executeWebSearchBackend(args) {
     try {
         const preview = summary.length > 120 ? `${summary.slice(0, 117)}...` : summary;
         // eslint-disable-next-line no-console
-        console.log(`\x1b[38;5;27m[server-tool][web_search][result] requestId=${ctx.options.requestId} ` +
+        console.log(`\x1b[38;5;27m[server-tool][web_search][result] requestId=${options.requestId} ` +
             `engine=${engine.id} chars=${summary.length} preview=${JSON.stringify(preview)}\x1b[0m`);
     }
     catch {
@@ -320,6 +323,46 @@ async function executeWebSearchBackend(args) {
     }
     return { summary, hits: finalHits, ok };
 }
+export async function executeWebSearchBackendPlan(args) {
+    const plan = args.plan;
+    const options = args.options;
+    const engines = Array.isArray(plan.engines) ? plan.engines : [];
+    if (!engines.length) {
+        return { kind: 'web_search', result: { ok: false, summary: '', hits: [] } };
+    }
+    let chosenEngine;
+    let chosenResult;
+    let lastFailure;
+    for (const engine of engines) {
+        const requestSuffix = `${plan.requestIdSuffix}:${engine.id}`;
+        const backendResult = await executeWebSearchBackend({
+            options,
+            engine,
+            query: plan.query,
+            recency: plan.recency,
+            resultCount: plan.resultCount,
+            requestSuffix
+        });
+        if (backendResult.ok) {
+            chosenEngine = engine;
+            chosenResult = backendResult;
+            break;
+        }
+        lastFailure = { engine, result: backendResult };
+    }
+    if (!chosenEngine || !chosenResult) {
+        if (!lastFailure) {
+            return { kind: 'web_search', result: { ok: false, summary: '', hits: [] } };
+        }
+        chosenEngine = lastFailure.engine;
+        chosenResult = lastFailure.result;
+    }
+    return {
+        kind: 'web_search',
+        chosenEngine: { id: chosenEngine.id, providerKey: chosenEngine.providerKey },
+        result: { ok: chosenResult.ok, summary: chosenResult.summary, hits: chosenResult.hits }
+    };
+}
 function buildWebSearchReenterPayload(engine, query, recency, resultCount) {
     const systemPrompt = buildWebSearchSystemPrompt(resultCount);
     const basePayload = {
@@ -350,8 +393,8 @@ function buildWebSearchReenterPayload(engine, query, recency, resultCount) {
     };
 }
 async function executeWebSearchViaProvider(args) {
-    const { ctx, engine, query, recency, count, requestSuffix } = args;
-    if (!ctx.options.providerInvoker) {
+    const { options, engine, query, recency, count, requestSuffix } = args;
+    if (!options.providerInvoker) {
         return '';
     }
     if (isGeminiWebSearchEngine(engine)) {
@@ -373,14 +416,14 @@ async function executeWebSearchViaProvider(args) {
                 }
             ]
         };
-        const backend = await ctx.options.providerInvoker({
+        const backend = await options.providerInvoker({
             providerKey: engine.providerKey,
             providerType: undefined,
             modelId: engine.id,
             providerProtocol: 'gemini-chat',
             payload: geminiPayload,
             entryEndpoint: '/v1/models/gemini:generateContent',
-            requestId: `${ctx.options.requestId}${requestSuffix}`,
+            requestId: `${options.requestId}${requestSuffix}`,
             routeHint: 'web_search'
         });
         const providerResponse = backend.providerResponse && typeof backend.providerResponse === 'object'
@@ -412,14 +455,14 @@ async function executeWebSearchViaProvider(args) {
             engine: engine.id
         }
     };
-    const backend = await ctx.options.providerInvoker({
+    const backend = await options.providerInvoker({
         providerKey: engine.providerKey,
         providerType: undefined,
         modelId: undefined,
-        providerProtocol: ctx.options.providerProtocol,
+        providerProtocol: options.providerProtocol,
         payload: backendPayload,
         entryEndpoint: '/v1/chat/completions',
-        requestId: `${ctx.options.requestId}${requestSuffix}`,
+        requestId: `${options.requestId}${requestSuffix}`,
         routeHint: 'web_search'
     });
     const providerResponse = backend.providerResponse && typeof backend.providerResponse === 'object'
@@ -431,8 +474,8 @@ async function executeWebSearchViaProvider(args) {
     return extractTextFromChatLike(providerResponse);
 }
 async function executeIflowWebSearchViaProvider(args) {
-    const { ctx, engine, query, count, requestSuffix } = args;
-    if (!ctx.options.providerInvoker) {
+    const { options, engine, query, count, requestSuffix } = args;
+    if (!options.providerInvoker) {
         return {
             summary: '',
             hits: [],
@@ -457,8 +500,8 @@ async function executeIflowWebSearchViaProvider(args) {
     };
     let providerKey = engine.providerKey;
     try {
-        const adapter = ctx.adapterContext && typeof ctx.adapterContext === 'object'
-            ? ctx.adapterContext
+        const adapter = options.adapterContext && typeof options.adapterContext === 'object'
+            ? options.adapterContext
             : null;
         const target = adapter && adapter.target && typeof adapter.target === 'object'
             ? adapter.target
@@ -481,14 +524,14 @@ async function executeIflowWebSearchViaProvider(args) {
             routeName: 'web_search'
         }
     };
-    const backend = await ctx.options.providerInvoker({
+    const backend = await options.providerInvoker({
         providerKey,
         providerType: undefined,
         modelId: undefined,
-        providerProtocol: ctx.options.providerProtocol,
+        providerProtocol: options.providerProtocol,
         payload,
         entryEndpoint: '/v1/chat/retrieve',
-        requestId: `${ctx.options.requestId}${requestSuffix}`,
+        requestId: `${options.requestId}${requestSuffix}`,
         routeHint: 'web_search'
     });
     const providerResponse = backend.providerResponse && typeof backend.providerResponse === 'object'
@@ -569,32 +612,6 @@ function injectWebSearchToolResult(base, toolCall, engine, query, backendResult)
     ];
     return cloned;
 }
-function buildWebSearchFollowupPayload(adapterContext, chatResponse, entryEndpoint) {
-    const captured = adapterContext && typeof adapterContext === 'object'
-        ? adapterContext.capturedChatRequest
-        : undefined;
-    const seed = extractCapturedChatSeed(captured);
-    if (!seed) {
-        return null;
-    }
-    const assistantMessage = extractAssistantMessage(chatResponse);
-    if (!assistantMessage) {
-        return null;
-    }
-    const toolMessages = buildToolMessages(chatResponse);
-    if (!toolMessages.length) {
-        return null;
-    }
-    const reconstructed = [...seed.messages, assistantMessage, ...toolMessages];
-    const filteredTools = dropToolByFunctionName(seed.tools, 'web_search');
-    return buildEntryAwareFollowupPayload({
-        entryEndpoint,
-        model: seed.model,
-        messages: reconstructed,
-        ...(filteredTools ? { tools: filteredTools } : {}),
-        ...(seed.parameters ? { parameters: seed.parameters } : {})
-    });
-}
 function extractAssistantMessage(chatResponse) {
     const choices = Array.isArray(chatResponse.choices)
         ? chatResponse.choices

package/dist/servertool/reenter-backend.d.ts

@@ -0,0 +1,23 @@
+import type { JsonObject } from '../conversion/hub/types/json.js';
+export declare function reenterServerToolBackend(args: {
+    reenterPipeline: (options: {
+        entryEndpoint: string;
+        requestId: string;
+        body: JsonObject;
+        metadata?: JsonObject;
+    }) => Promise<{
+        body?: JsonObject;
+        __sse_responses?: unknown;
+        format?: string;
+    }>;
+    entryEndpoint: string;
+    requestId: string;
+    body: JsonObject;
+    providerProtocol: string;
+    routeHint?: string;
+    metadata?: JsonObject;
+}): Promise<{
+    body?: JsonObject;
+    __sse_responses?: unknown;
+    format?: string;
+}>;

package/dist/servertool/reenter-backend.js

@@ -0,0 +1,18 @@
+export async function reenterServerToolBackend(args) {
+    const routeHint = typeof args.routeHint === 'string' && args.routeHint.trim().length ? args.routeHint.trim() : undefined;
+    const merged = {
+        providerProtocol: args.providerProtocol,
+        serverToolFollowup: true,
+        stream: false,
+        preserveRouteHint: false,
+        disableStickyRoutes: true,
+        ...(routeHint ? { routeHint } : {}),
+        ...(args.metadata ?? {})
+    };
+    return await args.reenterPipeline({
+        entryEndpoint: args.entryEndpoint,
+        requestId: args.requestId,
+        body: args.body,
+        metadata: merged
+    });
+}

package/dist/servertool/server-side-tools.d.ts

@@ -1,12 +1,13 @@
 import type { JsonObject } from '../conversion/hub/types/json.js';
 import type { ServerSideToolEngineOptions, ServerSideToolEngineResult, ToolCall } from './types.js';
-import './handlers/web-search.js';
-import './handlers/vision.js';
 import './handlers/iflow-model-error-retry.js';
 import './handlers/gemini-empty-reply-continue.js';
 import './handlers/stop-message-auto.js';
+import './handlers/clock.js';
+import './handlers/clock-auto.js';
 import './handlers/exec-command-guard.js';
 import './handlers/apply-patch-guard.js';
+import './handlers/recursive-detection-guard.js';
 export declare function runServerSideToolEngine(options: ServerSideToolEngineOptions): Promise<ServerSideToolEngineResult>;
 export declare function extractToolCalls(chatResponse: JsonObject): ToolCall[];
 export declare function cloneJson<T>(value: T): T;