@jsonstudio/llms 0.6.1739 → 0.6.1890

package/dist/servertool/registry.js

@@ -1,5 +1,36 @@
 const SERVER_TOOL_HANDLERS = Object.create(null);
 const AUTO_SERVER_TOOL_HANDLERS = [];
+const DEFAULT_AUTO_HOOK_PRIORITY = 100;
+let autoHookRegistrationOrder = 0;
+function normalizeAutoHookPhase(value) {
+    const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (normalized === 'pre' || normalized === 'before') {
+        return 'pre';
+    }
+    if (normalized === 'post' || normalized === 'after') {
+        return 'post';
+    }
+    return 'default';
+}
+function normalizeAutoHookPriority(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.floor(value);
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number.parseInt(value.trim(), 10);
+        if (Number.isFinite(parsed)) {
+            return Math.floor(parsed);
+        }
+    }
+    return DEFAULT_AUTO_HOOK_PRIORITY;
+}
+function resolveAutoHookPhaseRank(phase) {
+    if (phase === 'pre')
+        return 0;
+    if (phase === 'post')
+        return 2;
+    return 1;
+}
 export function registerServerToolHandler(name, handler, options) {
     if (!name || typeof name !== 'string' || typeof handler !== 'function')
         return;
@@ -9,6 +40,14 @@ export function registerServerToolHandler(name, handler, options) {
     const trigger = options?.trigger ?? 'tool_call';
     const entry = { name: key, trigger, handler };
     if (trigger === 'auto') {
+        const priority = normalizeAutoHookPriority(options?.hook?.priority ?? options?.priority);
+        const phase = normalizeAutoHookPhase(options?.hook?.phase ?? options?.phase);
+        entry.autoHook = {
+            id: key,
+            phase,
+            priority,
+            order: autoHookRegistrationOrder++
+        };
         AUTO_SERVER_TOOL_HANDLERS.push(entry);
         return;
     }
@@ -23,5 +62,31 @@ export function getServerToolHandler(name) {
     return SERVER_TOOL_HANDLERS[key];
 }
 export function listAutoServerToolHandlers() {
-    return [...AUTO_SERVER_TOOL_HANDLERS];
+    return [...AUTO_SERVER_TOOL_HANDLERS].sort((left, right) => {
+        const leftHook = left.autoHook;
+        const rightHook = right.autoHook;
+        const phaseRankDiff = resolveAutoHookPhaseRank(leftHook?.phase ?? 'default') -
+            resolveAutoHookPhaseRank(rightHook?.phase ?? 'default');
+        if (phaseRankDiff !== 0) {
+            return phaseRankDiff;
+        }
+        const priorityDiff = (leftHook?.priority ?? DEFAULT_AUTO_HOOK_PRIORITY) - (rightHook?.priority ?? DEFAULT_AUTO_HOOK_PRIORITY);
+        if (priorityDiff !== 0) {
+            return priorityDiff;
+        }
+        const orderDiff = (leftHook?.order ?? 0) - (rightHook?.order ?? 0);
+        if (orderDiff !== 0) {
+            return orderDiff;
+        }
+        return left.name.localeCompare(right.name);
+    });
+}
+export function listAutoServerToolHooks() {
+    return listAutoServerToolHandlers().map((entry) => ({
+        id: entry.name,
+        phase: entry.autoHook?.phase ?? 'default',
+        priority: entry.autoHook?.priority ?? DEFAULT_AUTO_HOOK_PRIORITY,
+        order: entry.autoHook?.order ?? 0,
+        handler: entry.handler
+    }));
 }

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

@@ -9,6 +9,7 @@ import './handlers/clock-auto.js';
 import './handlers/exec-command-guard.js';
 import './handlers/apply-patch-guard.js';
 import './handlers/recursive-detection-guard.js';
+import './handlers/continue-execution.js';
 export declare function runServerSideToolEngine(options: ServerSideToolEngineOptions): Promise<ServerSideToolEngineResult>;
 export declare function extractToolCalls(chatResponse: JsonObject): ToolCall[];
 export declare function cloneJson<T>(value: T): T;

package/dist/servertool/server-side-tools.js

@@ -1,4 +1,4 @@
-import { getServerToolHandler, listAutoServerToolHandlers } from './registry.js';
+import { getServerToolHandler, listAutoServerToolHooks } from './registry.js';
 import { ProviderProtocolError } from '../conversion/shared/errors.js';
 import { executeWebSearchBackendPlan } from './handlers/web-search.js';
 import { executeVisionBackendPlan } from './handlers/vision.js';
@@ -11,6 +11,77 @@ import './handlers/clock-auto.js';
 import './handlers/exec-command-guard.js';
 import './handlers/apply-patch-guard.js';
 import './handlers/recursive-detection-guard.js';
+import './handlers/continue-execution.js';
+import { runPreCommandHooks } from './pre-command-hooks.js';
+import { readRuntimeMetadata } from '../conversion/shared/runtime-metadata.js';
+function traceAutoHook(options, event) {
+    try {
+        options.onAutoHookTrace?.(event);
+    }
+    catch {
+        // best-effort trace callback
+    }
+}
+const OPTIONAL_PRIMARY_HOOK_ORDER = ['empty_reply_continue', 'stop_message_auto', 'clock_auto'];
+const MANDATORY_HOOK_ORDER = [];
+let fallbackToolCallIdSeq = 0;
+function ensureToolCallId(record) {
+    const existing = typeof record.id === 'string' ? String(record.id).trim() : '';
+    if (existing) {
+        return existing;
+    }
+    fallbackToolCallIdSeq += 1;
+    const generated = `call_servertool_fallback_${Date.now()}_${fallbackToolCallIdSeq}`;
+    record.id = generated;
+    return generated;
+}
+function buildAutoHookQueues(hooks) {
+    const hookById = new Map();
+    for (const hook of hooks) {
+        if (!hook || typeof hook.id !== 'string') {
+            continue;
+        }
+        hookById.set(hook.id, hook);
+    }
+    const consumed = new Set();
+    const optionalQueue = [];
+    for (const hook of hooks) {
+        if (hook.phase !== 'pre') {
+            continue;
+        }
+        if (consumed.has(hook.id)) {
+            continue;
+        }
+        optionalQueue.push(hook);
+        consumed.add(hook.id);
+    }
+    for (const id of OPTIONAL_PRIMARY_HOOK_ORDER) {
+        const hook = hookById.get(id);
+        if (!hook || consumed.has(hook.id)) {
+            continue;
+        }
+        optionalQueue.push(hook);
+        consumed.add(hook.id);
+    }
+    for (const hook of hooks) {
+        if (consumed.has(hook.id)) {
+            continue;
+        }
+        optionalQueue.push(hook);
+        consumed.add(hook.id);
+    }
+    const mandatoryQueue = [];
+    const mandatorySeen = new Set();
+    for (const id of MANDATORY_HOOK_ORDER) {
+        const hook = hookById.get(id);
+        if (!hook || mandatorySeen.has(hook.id)) {
+            continue;
+        }
+        mandatoryQueue.push(hook);
+        mandatorySeen.add(hook.id);
+    }
+    return { optionalQueue, mandatoryQueue };
+}
 function extractToolCallsFromMessage(message) {
     const toolCalls = getArray(message.tool_calls);
     const out = [];
@@ -18,7 +89,7 @@ function extractToolCallsFromMessage(message) {
         const tc = asObject(raw);
         if (!tc)
             continue;
-        const id = typeof tc.id === 'string' && String(tc.id).trim() ? String(tc.id).trim() : '';
+        const id = ensureToolCallId(tc);
         const fn = asObject(tc.function) ??
             asObject(tc.functionCall) ??
             asObject(tc.function_call);
@@ -44,7 +115,7 @@ function extractToolCallsFromMessage(message) {
         else if (rawArgs !== undefined && rawArgs !== null) {
             args = String(rawArgs);
         }
-        if (!id || !name)
+        if (!name)
             continue;
         out.push({ raw: tc, parsed: { id, name, arguments: args } });
     }
@@ -104,6 +175,45 @@ function replaceJsonObjectInPlace(target, next) {
         // ignore
     }
 }
+function patchToolCallArgumentsById(chatResponse, toolCallId, argumentsText) {
+    if (!toolCallId || typeof argumentsText !== 'string') {
+        return;
+    }
+    const choices = getArray(chatResponse.choices);
+    for (const choice of choices) {
+        const choiceObj = asObject(choice);
+        if (!choiceObj)
+            continue;
+        const message = asObject(choiceObj.message);
+        if (!message)
+            continue;
+        const toolCalls = getArray(message.tool_calls);
+        for (const toolCall of toolCalls) {
+            const record = asObject(toolCall);
+            if (!record)
+                continue;
+            const id = typeof record.id === 'string' ? String(record.id).trim() : '';
+            if (!id || id !== toolCallId) {
+                continue;
+            }
+            const fn = asObject(record.function);
+            if (fn) {
+                fn.arguments = argumentsText;
+            }
+            const fnCamel = asObject(record.functionCall);
+            if (fnCamel) {
+                fnCamel.arguments = argumentsText;
+            }
+            const fnSnake = asObject(record.function_call);
+            if (fnSnake) {
+                fnSnake.arguments = argumentsText;
+            }
+            if (Object.prototype.hasOwnProperty.call(record, 'arguments')) {
+                record.arguments = argumentsText;
+            }
+        }
+    }
+}
 function filterOutExecutedToolCalls(chatResponse, executedIds) {
     const choices = getArray(chatResponse.choices);
     for (const choice of choices) {
@@ -157,6 +267,10 @@ export async function runServerSideToolEngine(options) {
     const executedFlowIds = [];
     let lastExecution;
     const attemptedToolCallsByMessage = [];
+    const runtimeMetadata = readRuntimeMetadata(options.adapterContext);
+    const runtimePreCommandState = runtimeMetadata && typeof runtimeMetadata === 'object'
+        ? runtimeMetadata.preCommandState
+        : undefined;
     const choices = getArray(base.choices);
     for (const choice of choices) {
         const choiceObj = asObject(choice);
@@ -168,6 +282,23 @@ export async function runServerSideToolEngine(options) {
         attemptedToolCallsByMessage.push(...extractToolCallsFromMessage(message));
     }
     for (const { parsed: toolCall } of attemptedToolCallsByMessage) {
+        const preHookResult = runPreCommandHooks({
+            requestId: options.requestId,
+            entryEndpoint: options.entryEndpoint,
+            providerProtocol: options.providerProtocol,
+            toolName: toolCall.name,
+            toolCallId: toolCall.id,
+            toolArguments: toolCall.arguments,
+            preCommandState: runtimePreCommandState
+        });
+        for (const trace of preHookResult.traces) {
+            traceAutoHook(options, trace);
+        }
+        if (preHookResult.changed && preHookResult.toolArguments !== toolCall.arguments) {
+            toolCall.arguments = preHookResult.toolArguments;
+            patchToolCallArgumentsById(base, toolCall.id, preHookResult.toolArguments);
+            patchToolCallArgumentsById(baseForExecution, toolCall.id, preHookResult.toolArguments);
+        }
         const entry = getServerToolHandler(toolCall.name);
         if (!entry || entry.trigger !== 'tool_call') {
             continue;
@@ -276,18 +407,89 @@ export async function runServerSideToolEngine(options) {
             }
         };
     }
-    for (const entry of listAutoServerToolHandlers()) {
-        const planned = await runHandler(entry.handler, contextBase);
-        const result = planned ? await materializePlannedResult(planned, options) : null;
+    const autoHookExecutionList = listAutoServerToolHooks();
+    const { optionalQueue, mandatoryQueue } = buildAutoHookQueues(autoHookExecutionList);
+    const optionalResult = await runAutoHookQueue({
+        queueName: 'A_optional',
+        hooks: optionalQueue,
+        options,
+        contextBase: contextBase
+    });
+    if (optionalResult) {
+        return {
+            mode: 'tool_flow',
+            finalChatResponse: optionalResult.chatResponse,
+            execution: optionalResult.execution
+        };
+    }
+    const mandatoryResult = await runAutoHookQueue({
+        queueName: 'B_mandatory',
+        hooks: mandatoryQueue,
+        options,
+        contextBase: contextBase
+    });
+    if (mandatoryResult) {
+        return {
+            mode: 'tool_flow',
+            finalChatResponse: mandatoryResult.chatResponse,
+            execution: mandatoryResult.execution
+        };
+    }
+    return { mode: 'passthrough', finalChatResponse: base };
+}
+async function runAutoHookQueue(options) {
+    const queueTotal = options.hooks.length;
+    for (let idx = 0; idx < options.hooks.length; idx += 1) {
+        const hook = options.hooks[idx];
+        const traceBase = {
+            hookId: hook.id,
+            phase: hook.phase,
+            priority: hook.priority,
+            queue: options.queueName,
+            queueIndex: idx + 1,
+            queueTotal
+        };
+        let planned = null;
+        try {
+            planned = await runHandler(hook.handler, options.contextBase);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error ?? 'unknown');
+            traceAutoHook(options.options, {
+                ...traceBase,
+                result: 'error',
+                reason: message
+            });
+            throw error;
+        }
+        if (!planned) {
+            traceAutoHook(options.options, {
+                ...traceBase,
+                result: 'miss',
+                reason: 'predicate_false'
+            });
+            continue;
+        }
+        const result = await materializePlannedResult(planned, options.options);
         if (result) {
-            return {
-                mode: 'tool_flow',
-                finalChatResponse: result.chatResponse,
-                execution: result.execution
-            };
+            const flowId = result.execution && typeof result.execution.flowId === 'string' && result.execution.flowId.trim()
+                ? result.execution.flowId.trim()
+                : undefined;
+            traceAutoHook(options.options, {
+                ...traceBase,
+                result: 'match',
+                reason: flowId ? 'matched' : 'matched_without_flow',
+                ...(flowId ? { flowId } : {})
+            });
+            return result;
         }
+        traceAutoHook(options.options, {
+            ...traceBase,
+            result: 'miss',
+            reason: 'empty_materialized_result'
+        });
     }
-    return { mode: 'passthrough', finalChatResponse: base };
+    return null;
 }
 async function runHandler(handler, ctx) {
     try {
@@ -350,7 +552,7 @@ export function extractToolCalls(chatResponse) {
             const tc = asObject(raw);
             if (!tc)
                 continue;
-            const id = typeof tc.id === 'string' && tc.id.trim() ? tc.id.trim() : '';
+            const id = ensureToolCallId(tc);
             const fn = asObject(tc.function) ??
                 asObject(tc.functionCall) ??
                 asObject(tc.function_call);
@@ -376,7 +578,7 @@ export function extractToolCalls(chatResponse) {
             else if (rawArgs !== undefined && rawArgs !== null) {
                 args = String(rawArgs);
             }
-            if (!id || !name)
+            if (!name)
                 continue;
             calls.push({ id, name, arguments: args });
         }

package/dist/servertool/stop-gateway-context.d.ts

@@ -0,0 +1,14 @@
+import type { AdapterContext } from '../conversion/hub/types/chat-envelope.js';
+export interface StopGatewayContext {
+    observed: boolean;
+    eligible: boolean;
+    source: 'chat' | 'responses' | 'none';
+    reason: string;
+    choiceIndex?: number;
+    hasToolCalls?: boolean;
+}
+export declare function inspectStopGatewaySignal(base: unknown): StopGatewayContext;
+export declare function attachStopGatewayContext(adapterContext: AdapterContext, context: StopGatewayContext): void;
+export declare function readStopGatewayContext(adapterContext: unknown): StopGatewayContext | undefined;
+export declare function resolveStopGatewayContext(base: unknown, adapterContext?: unknown): StopGatewayContext;
+export declare function isStopEligibleForServerTool(base: unknown, adapterContext?: unknown): boolean;

package/dist/servertool/stop-gateway-context.js

@@ -0,0 +1,167 @@
+import { ensureRuntimeMetadata, readRuntimeMetadata } from '../conversion/shared/runtime-metadata.js';
+export function inspectStopGatewaySignal(base) {
+    if (!base || typeof base !== 'object' || Array.isArray(base)) {
+        return {
+            observed: false,
+            eligible: false,
+            source: 'none',
+            reason: 'invalid_payload'
+        };
+    }
+    const payload = base;
+    const choicesRaw = payload.choices;
+    if (Array.isArray(choicesRaw) && choicesRaw.length) {
+        for (let idx = 0; idx < choicesRaw.length; idx += 1) {
+            const choice = choicesRaw[idx];
+            if (!choice || typeof choice !== 'object' || Array.isArray(choice)) {
+                continue;
+            }
+            const finishReasonRaw = choice.finish_reason;
+            const finishReason = typeof finishReasonRaw === 'string' && finishReasonRaw.trim()
+                ? finishReasonRaw.trim().toLowerCase()
+                : '';
+            if (!finishReason || finishReason === 'tool_calls') {
+                continue;
+            }
+            if (finishReason !== 'stop' && finishReason !== 'length') {
+                continue;
+            }
+            const message = choice.message &&
+                typeof choice.message === 'object' &&
+                !Array.isArray(choice.message)
+                ? choice.message
+                : null;
+            const toolCalls = message && Array.isArray(message.tool_calls) ? message.tool_calls : [];
+            const hasToolCalls = toolCalls.length > 0;
+            return {
+                observed: true,
+                eligible: !hasToolCalls,
+                source: 'chat',
+                reason: `finish_reason_${finishReason}`,
+                choiceIndex: idx,
+                hasToolCalls
+            };
+        }
+        return {
+            observed: false,
+            eligible: false,
+            source: 'chat',
+            reason: 'no_stop_finish_reason'
+        };
+    }
+    const statusRaw = typeof payload.status === 'string' ? payload.status.trim().toLowerCase() : '';
+    if (statusRaw && statusRaw !== 'completed') {
+        return {
+            observed: false,
+            eligible: false,
+            source: 'responses',
+            reason: `status_${statusRaw}`
+        };
+    }
+    const hasRequiredAction = Boolean(payload.required_action && typeof payload.required_action === 'object');
+    const outputRaw = Array.isArray(payload.output) ? payload.output : [];
+    if (!statusRaw && outputRaw.length === 0) {
+        return {
+            observed: false,
+            eligible: false,
+            source: 'responses',
+            reason: 'no_status_or_output'
+        };
+    }
+    if (outputRaw.some((item) => hasToolLikeOutput(item))) {
+        return {
+            observed: true,
+            eligible: false,
+            source: 'responses',
+            reason: 'responses_tool_like_output'
+        };
+    }
+    if (hasRequiredAction) {
+        return {
+            observed: true,
+            eligible: false,
+            source: 'responses',
+            reason: 'responses_required_action'
+        };
+    }
+    return {
+        observed: true,
+        eligible: true,
+        source: 'responses',
+        reason: statusRaw ? `status_${statusRaw}` : 'responses_output_completed'
+    };
+}
+export function attachStopGatewayContext(adapterContext, context) {
+    try {
+        const rt = ensureRuntimeMetadata(adapterContext);
+        rt.stopGatewayContext = {
+            observed: context.observed,
+            eligible: context.eligible,
+            source: context.source,
+            reason: context.reason,
+            ...(typeof context.choiceIndex === 'number' ? { choiceIndex: context.choiceIndex } : {}),
+            ...(typeof context.hasToolCalls === 'boolean' ? { hasToolCalls: context.hasToolCalls } : {})
+        };
+    }
+    catch {
+        // ignore metadata write failures
+    }
+}
+export function readStopGatewayContext(adapterContext) {
+    if (!adapterContext || typeof adapterContext !== 'object' || Array.isArray(adapterContext)) {
+        return undefined;
+    }
+    const rt = readRuntimeMetadata(adapterContext);
+    const raw = rt && typeof rt === 'object' ? rt.stopGatewayContext : undefined;
+    return normalizeStopGatewayContext(raw);
+}
+export function resolveStopGatewayContext(base, adapterContext) {
+    const fromMetadata = readStopGatewayContext(adapterContext);
+    if (fromMetadata) {
+        return fromMetadata;
+    }
+    return inspectStopGatewaySignal(base);
+}
+export function isStopEligibleForServerTool(base, adapterContext) {
+    return resolveStopGatewayContext(base, adapterContext).eligible;
+}
+function normalizeStopGatewayContext(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const record = raw;
+    if (typeof record.observed !== 'boolean' || typeof record.eligible !== 'boolean') {
+        return undefined;
+    }
+    const sourceRaw = typeof record.source === 'string' ? record.source.trim().toLowerCase() : '';
+    const source = sourceRaw === 'chat' || sourceRaw === 'responses' || sourceRaw === 'none'
+        ? sourceRaw
+        : 'none';
+    const reason = typeof record.reason === 'string' && record.reason.trim() ? record.reason.trim() : 'unknown';
+    const choiceIndex = typeof record.choiceIndex === 'number' && Number.isFinite(record.choiceIndex)
+        ? Math.floor(record.choiceIndex)
+        : undefined;
+    const hasToolCalls = typeof record.hasToolCalls === 'boolean' ? record.hasToolCalls : undefined;
+    return {
+        observed: record.observed,
+        eligible: record.eligible,
+        source,
+        reason,
+        ...(typeof choiceIndex === 'number' ? { choiceIndex } : {}),
+        ...(typeof hasToolCalls === 'boolean' ? { hasToolCalls } : {})
+    };
+}
+function hasToolLikeOutput(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const typeRaw = value.type;
+    const type = typeof typeRaw === 'string' ? typeRaw.trim().toLowerCase() : '';
+    if (!type) {
+        return false;
+    }
+    return (type === 'tool_call' ||
+        type === 'tool_use' ||
+        type === 'function_call' ||
+        type.includes('tool'));
+}

package/dist/servertool/stop-message-compare-context.d.ts

@@ -0,0 +1,24 @@
+export interface StopMessageCompareContext {
+    armed: boolean;
+    mode: 'off' | 'on' | 'auto';
+    allowModeOnly: boolean;
+    textLength: number;
+    maxRepeats: number;
+    used: number;
+    remaining: number;
+    active: boolean;
+    stopEligible: boolean;
+    hasCapturedRequest: boolean;
+    compactionRequest: boolean;
+    hasSeed: boolean;
+    decision: 'trigger' | 'skip';
+    reason: string;
+    stage?: string;
+    bdWorkState?: string;
+    observationHash?: string;
+    observationStableCount?: number;
+    toolSignatureHash?: string;
+}
+export declare function attachStopMessageCompareContext(adapterContext: unknown, context: StopMessageCompareContext): void;
+export declare function readStopMessageCompareContext(adapterContext: unknown): StopMessageCompareContext | undefined;
+export declare function formatStopMessageCompareContext(context: StopMessageCompareContext | undefined): string;