@jsonstudio/llms 0.6.954 → 0.6.1172

package/dist/servertool/clock/session-store.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDir, readSessionDirEnv, resolveClockStateFile } from './paths.js';
+import { buildEmptyState, cleanExpiredTasks, coerceState, nowMs } from './state.js';
+import { readJsonFile, writeJsonFileAtomic } from './io.js';
+export async function loadClockSessionState(sessionId, config) {
+    const sessionDir = readSessionDirEnv();
+    if (!sessionDir) {
+        return buildEmptyState(sessionId);
+    }
+    const filePath = resolveClockStateFile(sessionDir, sessionId);
+    if (!filePath) {
+        return buildEmptyState(sessionId);
+    }
+    try {
+        const raw = await readJsonFile(filePath);
+        const state = coerceState(raw, sessionId);
+        const at = nowMs();
+        const cleaned = cleanExpiredTasks(state.tasks, config, at);
+        if (cleaned.length !== state.tasks.length) {
+            const next = { ...state, tasks: cleaned, updatedAtMs: at };
+            if (!next.tasks.length) {
+                await fs.rm(filePath, { force: true });
+            }
+            else {
+                await ensureDir(path.dirname(filePath));
+                await writeJsonFileAtomic(filePath, next);
+            }
+            return next;
+        }
+        return state;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error ?? 'unknown');
+        if (message.includes('ENOENT')) {
+            return buildEmptyState(sessionId);
+        }
+        return buildEmptyState(sessionId);
+    }
+}
+export async function clearClockSession(sessionId) {
+    const sessionDir = readSessionDirEnv();
+    if (!sessionDir) {
+        return;
+    }
+    const filePath = resolveClockStateFile(sessionDir, sessionId);
+    if (!filePath) {
+        return;
+    }
+    try {
+        await fs.rm(filePath, { force: true });
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/servertool/clock/state.d.ts

@@ -0,0 +1,5 @@
+import type { ClockConfigSnapshot, ClockSessionState, ClockTask } from './types.js';
+export declare function nowMs(): number;
+export declare function buildEmptyState(sessionId: string): ClockSessionState;
+export declare function coerceState(raw: unknown, sessionId: string): ClockSessionState;
+export declare function cleanExpiredTasks(tasks: ClockTask[], config: ClockConfigSnapshot, atMs: number): ClockTask[];

package/dist/servertool/clock/state.js

@@ -0,0 +1,62 @@
+export function nowMs() {
+    return Date.now();
+}
+export function buildEmptyState(sessionId) {
+    const t = nowMs();
+    return { version: 1, sessionId, tasks: [], updatedAtMs: t };
+}
+export function coerceState(raw, sessionId) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return buildEmptyState(sessionId);
+    }
+    const record = raw;
+    const tasksRaw = Array.isArray(record.tasks) ? record.tasks : [];
+    const tasks = [];
+    for (const entry of tasksRaw) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const e = entry;
+        const taskId = typeof e.taskId === 'string' ? e.taskId.trim() : '';
+        const dueAtMs = typeof e.dueAtMs === 'number' && Number.isFinite(e.dueAtMs) ? Math.floor(e.dueAtMs) : NaN;
+        const createdAtMs = typeof e.createdAtMs === 'number' && Number.isFinite(e.createdAtMs) ? Math.floor(e.createdAtMs) : NaN;
+        const updatedAtMs = typeof e.updatedAtMs === 'number' && Number.isFinite(e.updatedAtMs) ? Math.floor(e.updatedAtMs) : NaN;
+        const task = typeof e.task === 'string' ? e.task.trim() : '';
+        if (!taskId || !task || !Number.isFinite(dueAtMs) || !Number.isFinite(createdAtMs) || !Number.isFinite(updatedAtMs)) {
+            continue;
+        }
+        const tool = typeof e.tool === 'string' && e.tool.trim() ? e.tool.trim() : undefined;
+        const args = e.arguments && typeof e.arguments === 'object' && !Array.isArray(e.arguments)
+            ? e.arguments
+            : undefined;
+        const deliveredAtMs = typeof e.deliveredAtMs === 'number' && Number.isFinite(e.deliveredAtMs) ? Math.floor(e.deliveredAtMs) : undefined;
+        const deliveryCount = typeof e.deliveryCount === 'number' && Number.isFinite(e.deliveryCount) ? Math.max(0, Math.floor(e.deliveryCount)) : 0;
+        tasks.push({
+            taskId,
+            sessionId,
+            dueAtMs,
+            createdAtMs,
+            updatedAtMs,
+            task,
+            ...(tool ? { tool } : {}),
+            ...(args ? { arguments: args } : {}),
+            ...(deliveredAtMs !== undefined ? { deliveredAtMs } : {}),
+            deliveryCount
+        });
+    }
+    const updatedAtMs = typeof record.updatedAtMs === 'number' && Number.isFinite(record.updatedAtMs) ? Math.floor(record.updatedAtMs) : nowMs();
+    return { version: 1, sessionId, tasks, updatedAtMs };
+}
+export function cleanExpiredTasks(tasks, config, atMs) {
+    const out = [];
+    for (const task of tasks) {
+        if (!task || typeof task !== 'object')
+            continue;
+        if (!Number.isFinite(task.dueAtMs))
+            continue;
+        if (atMs > task.dueAtMs + config.retentionMs) {
+            continue;
+        }
+        out.push(task);
+    }
+    return out;
+}

package/dist/servertool/clock/task-store.d.ts

@@ -0,0 +1,5 @@
+export type { ClockConfigSnapshot, ClockReservation, ClockScheduleItem, ClockSessionState, ClockTask } from './types.js';
+export { normalizeClockConfig } from './config.js';
+export { startClockDaemonIfNeeded, stopClockDaemonForTests } from './daemon.js';
+export { loadClockSessionState, clearClockSession } from './session-store.js';
+export { cancelClockTask, clearClockTasks, commitClockReservation, findNextUndeliveredDueAtMs, listClockTasks, parseDueAtMs, reserveDueTasksForRequest, scheduleClockTasks, selectDueUndeliveredTasks } from './tasks.js';

package/dist/servertool/clock/task-store.js

@@ -0,0 +1,4 @@
+export { normalizeClockConfig } from './config.js';
+export { startClockDaemonIfNeeded, stopClockDaemonForTests } from './daemon.js';
+export { loadClockSessionState, clearClockSession } from './session-store.js';
+export { cancelClockTask, clearClockTasks, commitClockReservation, findNextUndeliveredDueAtMs, listClockTasks, parseDueAtMs, reserveDueTasksForRequest, scheduleClockTasks, selectDueUndeliveredTasks } from './tasks.js';

package/dist/servertool/clock/tasks.d.ts

@@ -0,0 +1,17 @@
+import type { ClockConfigSnapshot, ClockReservation, ClockScheduleItem, ClockTask } from './types.js';
+export declare function parseDueAtMs(value: unknown): number | null;
+export declare function listClockTasks(sessionId: string, config: ClockConfigSnapshot): Promise<ClockTask[]>;
+export declare function scheduleClockTasks(sessionId: string, items: ClockScheduleItem[], config: ClockConfigSnapshot): Promise<ClockTask[]>;
+export declare function cancelClockTask(sessionId: string, taskId: string, config: ClockConfigSnapshot): Promise<boolean>;
+export declare function clearClockTasks(sessionId: string, config: ClockConfigSnapshot): Promise<number>;
+export declare function selectDueUndeliveredTasks(tasks: ClockTask[], config: ClockConfigSnapshot, atMs: number): ClockTask[];
+export declare function findNextUndeliveredDueAtMs(tasks: ClockTask[], atMs: number): number | null;
+export declare function reserveDueTasksForRequest(args: {
+    reservationId: string;
+    sessionId: string;
+    config: ClockConfigSnapshot;
+}): Promise<{
+    reservation: ClockReservation | null;
+    injectText?: string;
+}>;
+export declare function commitClockReservation(reservation: ClockReservation, config: ClockConfigSnapshot): Promise<void>;

package/dist/servertool/clock/tasks.js

@@ -0,0 +1,221 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { ensureDir, readSessionDirEnv, resolveClockStateFile } from './paths.js';
+import { cleanExpiredTasks, nowMs } from './state.js';
+import { writeJsonFileAtomic } from './io.js';
+import { clearClockSession, loadClockSessionState } from './session-store.js';
+function safeJson(value) {
+    try {
+        return JSON.stringify(value ?? {});
+    }
+    catch {
+        return '{}';
+    }
+}
+function safeQuoted(text) {
+    const normalized = String(text ?? '');
+    const escaped = normalized.replace(/\"/g, '\\"');
+    return `"${escaped}"`;
+}
+function buildTaskId() {
+    try {
+        return crypto.randomUUID();
+    }
+    catch {
+        return `task_${Math.random().toString(16).slice(2)}_${Date.now()}`;
+    }
+}
+export function parseDueAtMs(value) {
+    if (typeof value !== 'string')
+        return null;
+    const t = value.trim();
+    if (!t)
+        return null;
+    const ms = Date.parse(t);
+    if (!Number.isFinite(ms))
+        return null;
+    return ms;
+}
+export async function listClockTasks(sessionId, config) {
+    const state = await loadClockSessionState(sessionId, config);
+    return state.tasks.slice();
+}
+export async function scheduleClockTasks(sessionId, items, config) {
+    const sessionDir = readSessionDirEnv();
+    if (!sessionDir) {
+        throw new Error('clock: missing ROUTECODEX_SESSION_DIR');
+    }
+    const filePath = resolveClockStateFile(sessionDir, sessionId);
+    if (!filePath) {
+        throw new Error('clock: invalid sessionId');
+    }
+    await ensureDir(path.dirname(filePath));
+    const at = nowMs();
+    const existing = await loadClockSessionState(sessionId, config);
+    const cleaned = cleanExpiredTasks(existing.tasks, config, at);
+    const scheduled = [];
+    for (const item of items) {
+        const text = typeof item.task === 'string' ? item.task.trim() : '';
+        const dueAtMs = item.dueAtMs;
+        if (!text || !Number.isFinite(dueAtMs)) {
+            continue;
+        }
+        const taskId = buildTaskId();
+        scheduled.push({
+            taskId,
+            sessionId,
+            dueAtMs: Math.floor(dueAtMs),
+            createdAtMs: at,
+            updatedAtMs: at,
+            task: text,
+            ...(item.tool ? { tool: item.tool } : {}),
+            ...(item.arguments ? { arguments: item.arguments } : {}),
+            deliveryCount: 0
+        });
+    }
+    const nextTasks = cleanExpiredTasks([...cleaned, ...scheduled], config, at);
+    const next = {
+        version: 1,
+        sessionId,
+        tasks: nextTasks,
+        updatedAtMs: at
+    };
+    if (!next.tasks.length) {
+        await fs.rm(filePath, { force: true });
+    }
+    else {
+        await writeJsonFileAtomic(filePath, next);
+    }
+    return scheduled;
+}
+export async function cancelClockTask(sessionId, taskId, config) {
+    const sessionDir = readSessionDirEnv();
+    if (!sessionDir) {
+        throw new Error('clock: missing ROUTECODEX_SESSION_DIR');
+    }
+    const filePath = resolveClockStateFile(sessionDir, sessionId);
+    if (!filePath) {
+        throw new Error('clock: invalid sessionId');
+    }
+    await ensureDir(path.dirname(filePath));
+    const at = nowMs();
+    const state = await loadClockSessionState(sessionId, config);
+    const cleaned = cleanExpiredTasks(state.tasks, config, at);
+    const nextTasks = cleaned.filter((t) => t.taskId !== taskId);
+    const removed = nextTasks.length !== cleaned.length;
+    const next = { version: 1, sessionId, tasks: nextTasks, updatedAtMs: at };
+    if (!next.tasks.length) {
+        await fs.rm(filePath, { force: true });
+    }
+    else {
+        await writeJsonFileAtomic(filePath, next);
+    }
+    return removed;
+}
+export async function clearClockTasks(sessionId, config) {
+    const items = await listClockTasks(sessionId, config);
+    await clearClockSession(sessionId);
+    return items.length;
+}
+export function selectDueUndeliveredTasks(tasks, config, atMs) {
+    const due = [];
+    for (const task of tasks) {
+        if (!task || typeof task !== 'object')
+            continue;
+        if (task.deliveredAtMs !== undefined)
+            continue;
+        if (!Number.isFinite(task.dueAtMs))
+            continue;
+        if (atMs < task.dueAtMs - config.dueWindowMs)
+            continue;
+        if (atMs > task.dueAtMs + config.retentionMs)
+            continue;
+        due.push(task);
+    }
+    due.sort((a, b) => a.dueAtMs - b.dueAtMs);
+    return due;
+}
+export function findNextUndeliveredDueAtMs(tasks, atMs) {
+    let next = null;
+    for (const task of tasks) {
+        if (!task || typeof task !== 'object')
+            continue;
+        if (task.deliveredAtMs !== undefined)
+            continue;
+        if (!Number.isFinite(task.dueAtMs))
+            continue;
+        if (task.dueAtMs < atMs) {
+            // keep past due tasks as "next" too (will be due immediately)
+        }
+        if (next === null || task.dueAtMs < next) {
+            next = task.dueAtMs;
+        }
+    }
+    return next;
+}
+export async function reserveDueTasksForRequest(args) {
+    const state = await loadClockSessionState(args.sessionId, args.config);
+    const at = nowMs();
+    const due = selectDueUndeliveredTasks(state.tasks, args.config, at);
+    if (!due.length) {
+        return { reservation: null };
+    }
+    const taskIds = due.map((t) => t.taskId);
+    const reservation = {
+        reservationId: args.reservationId,
+        sessionId: args.sessionId,
+        taskIds,
+        reservedAtMs: at
+    };
+    const injectText = due
+        .map((t) => {
+        const dueAtIso = new Date(t.dueAtMs).toISOString();
+        const toolLabel = t.tool ? ` tool=${t.tool}` : '';
+        const argsLabel = t.arguments ? ` args=${safeJson(t.arguments)}` : '';
+        return `[scheduled task:${safeQuoted(t.task)}${toolLabel}${argsLabel} dueAt=${dueAtIso}]`;
+    })
+        .join('\n');
+    return { reservation, injectText };
+}
+export async function commitClockReservation(reservation, config) {
+    const sessionDir = readSessionDirEnv();
+    if (!sessionDir) {
+        return;
+    }
+    const filePath = resolveClockStateFile(sessionDir, reservation.sessionId);
+    if (!filePath) {
+        return;
+    }
+    const at = nowMs();
+    const state = await loadClockSessionState(reservation.sessionId, config);
+    const cleaned = cleanExpiredTasks(state.tasks, config, at);
+    const reservedSet = new Set(reservation.taskIds);
+    let touched = false;
+    const nextTasks = cleaned.map((t) => {
+        if (!reservedSet.has(t.taskId)) {
+            return t;
+        }
+        if (t.deliveredAtMs !== undefined) {
+            return t;
+        }
+        touched = true;
+        return {
+            ...t,
+            deliveredAtMs: at,
+            deliveryCount: (typeof t.deliveryCount === 'number' ? t.deliveryCount : 0) + 1,
+            updatedAtMs: at
+        };
+    });
+    if (!touched) {
+        return;
+    }
+    const next = { version: 1, sessionId: reservation.sessionId, tasks: nextTasks, updatedAtMs: at };
+    await ensureDir(path.dirname(filePath));
+    if (!next.tasks.length) {
+        await fs.rm(filePath, { force: true });
+    }
+    else {
+        await writeJsonFileAtomic(filePath, next);
+    }
+}

package/dist/servertool/clock/types.d.ts

@@ -0,0 +1,36 @@
+export type ClockTask = {
+    taskId: string;
+    sessionId: string;
+    dueAtMs: number;
+    createdAtMs: number;
+    updatedAtMs: number;
+    task: string;
+    tool?: string;
+    arguments?: Record<string, unknown>;
+    deliveredAtMs?: number;
+    deliveryCount: number;
+};
+export type ClockSessionState = {
+    version: 1;
+    sessionId: string;
+    tasks: ClockTask[];
+    updatedAtMs: number;
+};
+export type ClockReservation = {
+    reservationId: string;
+    sessionId: string;
+    taskIds: string[];
+    reservedAtMs: number;
+};
+export type ClockConfigSnapshot = {
+    enabled: boolean;
+    retentionMs: number;
+    dueWindowMs: number;
+    tickMs: number;
+};
+export type ClockScheduleItem = {
+    dueAtMs: number;
+    task: string;
+    tool?: string;
+    arguments?: Record<string, unknown>;
+};

package/dist/servertool/clock/types.js

@@ -0,0 +1 @@
+export {};

package/dist/servertool/engine.d.ts

@@ -1,12 +1,14 @@
 import type { AdapterContext } from '../conversion/hub/types/chat-envelope.js';
 import type { JsonObject } from '../conversion/hub/types/json.js';
 import type { ProviderInvoker } from './types.js';
+import type { StageRecorder } from '../conversion/hub/format-adapters/index.js';
 export interface ServerToolOrchestrationOptions {
     chat: JsonObject;
     adapterContext: AdapterContext;
     requestId: string;
     entryEndpoint: string;
     providerProtocol: string;
+    stageRecorder?: StageRecorder;
     reenterPipeline?: (options: {
         entryEndpoint: string;
         requestId: string;

package/dist/servertool/engine.js

@@ -3,6 +3,9 @@ import { ProviderProtocolError } from '../conversion/shared/errors.js';
 import { createHash } from 'node:crypto';
 import { loadRoutingInstructionStateSync, saveRoutingInstructionStateSync } from '../router/virtual-router/sticky-session-store.js';
 import { deserializeRoutingInstructionState, serializeRoutingInstructionState } from '../router/virtual-router/routing-instructions.js';
+import { applyHubFollowupPolicyShadow } from './followup-shadow.js';
+import { buildServerToolFollowupChatPayloadFromInjection } from './handlers/followup-request-builder.js';
+import { findNextUndeliveredDueAtMs, listClockTasks, normalizeClockConfig } from './clock/task-store.js';
 function parseTimeoutMs(raw, fallback) {
     const n = typeof raw === 'string' ? Number(raw.trim()) : typeof raw === 'number' ? raw : NaN;
     if (!Number.isFinite(n) || n <= 0) {
@@ -153,8 +156,108 @@ function isEmptyClientResponsePayload(payload) {
     }
     return true;
 }
+function isStopFinishReasonWithoutToolCalls(base) {
+    if (!base || typeof base !== 'object' || Array.isArray(base)) {
+        return false;
+    }
+    const payload = base;
+    const choicesRaw = payload.choices;
+    if (Array.isArray(choicesRaw) && choicesRaw.length) {
+        const first = choicesRaw[0];
+        if (!first || typeof first !== 'object' || Array.isArray(first)) {
+            return false;
+        }
+        const finishReasonRaw = first.finish_reason;
+        const finishReason = typeof finishReasonRaw === 'string' && finishReasonRaw.trim()
+            ? finishReasonRaw.trim().toLowerCase()
+            : '';
+        if (!finishReason || finishReason === 'tool_calls') {
+            return false;
+        }
+        if (finishReason !== 'stop' && finishReason !== 'length') {
+            return false;
+        }
+        const message = first.message &&
+            typeof first.message === 'object' &&
+            !Array.isArray(first.message)
+            ? first.message
+            : null;
+        if (!message) {
+            return false;
+        }
+        const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+        if (toolCalls.length > 0) {
+            return false;
+        }
+        return true;
+    }
+    // Responses-like: completed without required_action generally counts as stop.
+    const statusRaw = typeof payload.status === 'string' ? payload.status.trim().toLowerCase() : '';
+    if (statusRaw && statusRaw !== 'completed') {
+        return false;
+    }
+    if (payload.required_action && typeof payload.required_action === 'object') {
+        return false;
+    }
+    return true;
+}
+async function shouldDisableServerToolTimeoutForClockHold(args) {
+    // Only relevant for stop/length responses: clock_auto may hold indefinitely.
+    if (!isStopFinishReasonWithoutToolCalls(args.chat)) {
+        return false;
+    }
+    const record = args.adapterContext;
+    const clockConfig = normalizeClockConfig(record.clock);
+    if (!clockConfig) {
+        return false;
+    }
+    const sessionId = typeof record.sessionId === 'string' ? record.sessionId.trim() : '';
+    if (!sessionId) {
+        return false;
+    }
+    // If already within due window, clock_auto won't need long hold.
+    try {
+        const tasks = await listClockTasks(sessionId, clockConfig);
+        const at = Date.now();
+        const nextDueAtMs = findNextUndeliveredDueAtMs(tasks, at);
+        if (!nextDueAtMs) {
+            return false;
+        }
+        const thresholdMs = nextDueAtMs - clockConfig.dueWindowMs;
+        if (thresholdMs <= at) {
+            return false;
+        }
+        // Only disable when the wait exceeds current timeout.
+        if (args.serverToolTimeoutMs > 0 && thresholdMs - at <= args.serverToolTimeoutMs) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function runServerToolOrchestration(options) {
+    const YELLOW = '\x1b[38;5;214m';
+    const RESET = '\x1b[0m';
+    const logProgress = (step, total, message, extra) => {
+        try {
+            // eslint-disable-next-line no-console
+            console.log(`${YELLOW}[servertool][progress ${step}/${total}] requestId=${options.requestId} ${message}` +
+                (extra ? ` ${JSON.stringify(extra)}` : '') +
+                RESET);
+        }
+        catch {
+            /* best-effort logging */
+        }
+    };
     const serverToolTimeoutMs = resolveServerToolTimeoutMs();
+    const shouldDisableTimeout = await shouldDisableServerToolTimeoutForClockHold({
+        chat: options.chat,
+        adapterContext: options.adapterContext,
+        serverToolTimeoutMs
+    });
+    const effectiveServerToolTimeoutMs = shouldDisableTimeout ? 0 : serverToolTimeoutMs;
     const followupTimeoutMs = resolveServerToolFollowupTimeoutMs(serverToolTimeoutMs);
     const engineOptions = {
         chatResponse: options.chat,
@@ -165,10 +268,10 @@ export async function runServerToolOrchestration(options) {
         providerInvoker: options.providerInvoker,
         reenterPipeline: options.reenterPipeline
     };
-    const engineResult = await withTimeout(runServerSideToolEngine(engineOptions), serverToolTimeoutMs, () => createServerToolTimeoutError({
+    const engineResult = await withTimeout(runServerSideToolEngine(engineOptions), effectiveServerToolTimeoutMs, () => createServerToolTimeoutError({
         requestId: options.requestId,
         phase: 'engine',
-        timeoutMs: serverToolTimeoutMs
+        timeoutMs: effectiveServerToolTimeoutMs || serverToolTimeoutMs
     }));
     if (engineResult.mode === 'passthrough' || !engineResult.execution) {
         return {
@@ -176,7 +279,11 @@ export async function runServerToolOrchestration(options) {
             executed: false
         };
     }
+    const flowId = engineResult.execution.flowId ?? 'unknown';
+    const totalSteps = 5;
+    logProgress(1, totalSteps, 'matched', { flowId });
     if (!engineResult.execution.followup || !options.reenterPipeline) {
+        logProgress(5, totalSteps, 'completed (no followup)', { flowId });
         return {
             chat: engineResult.finalChatResponse,
             executed: true,
@@ -193,8 +300,45 @@ export async function runServerToolOrchestration(options) {
     const applyAutoLimit = isAutoStopMessage || isErrorAutoFlow || isGeminiEmptyReplyContinue || isApplyPatchGuard || isExecCommandGuard;
     // ServerTool followups must not inherit or inject any routeHint; always route fresh.
     const preserveRouteHint = false;
-    const loopState = buildServerToolLoopState(options.adapterContext, engineResult.execution.flowId, engineResult.execution.followup.payload);
+    const followupPlan = engineResult.execution.followup;
+    const followupEntryEndpoint = engineResult.execution.followup.entryEndpoint ||
+        options.entryEndpoint ||
+        '/v1/chat/completions';
+    const followupPayloadRaw = (() => {
+        if (followupPlan &&
+            typeof followupPlan === 'object' &&
+            !Array.isArray(followupPlan) &&
+            Object.prototype.hasOwnProperty.call(followupPlan, 'payload')) {
+            const candidate = followupPlan.payload;
+            return candidate && typeof candidate === 'object' && !Array.isArray(candidate) ? candidate : null;
+        }
+        if (followupPlan &&
+            typeof followupPlan === 'object' &&
+            !Array.isArray(followupPlan) &&
+            Object.prototype.hasOwnProperty.call(followupPlan, 'injection')) {
+            const injection = followupPlan.injection;
+            if (!injection || typeof injection !== 'object' || Array.isArray(injection)) {
+                return null;
+            }
+            return buildServerToolFollowupChatPayloadFromInjection({
+                adapterContext: options.adapterContext,
+                chatResponse: engineResult.finalChatResponse,
+                injection: injection
+            });
+        }
+        return null;
+    })();
+    if (!followupPayloadRaw) {
+        logProgress(5, totalSteps, 'completed (missing followup payload)', { flowId });
+        return {
+            chat: engineResult.finalChatResponse,
+            executed: true,
+            flowId: engineResult.execution.flowId
+        };
+    }
+    const loopState = buildServerToolLoopState(options.adapterContext, engineResult.execution.flowId, followupPayloadRaw);
     if (applyAutoLimit && loopState && typeof loopState.repeatCount === 'number' && loopState.repeatCount >= 3) {
+        logProgress(5, totalSteps, 'completed (auto limit hit)', { flowId });
         return {
             chat: engineResult.finalChatResponse,
             executed: true,
@@ -202,21 +346,22 @@ export async function runServerToolOrchestration(options) {
         };
     }
     if (isAdapterClientDisconnected(options.adapterContext)) {
+        logProgress(5, totalSteps, 'completed (client disconnected)', { flowId });
         return {
             chat: engineResult.finalChatResponse,
             executed: true,
             flowId: engineResult.execution.flowId
         };
     }
-    const followupEntryEndpoint = engineResult.execution.followup.entryEndpoint ||
-        options.entryEndpoint ||
-        '/v1/chat/completions';
     const metadata = {
         serverToolFollowup: true,
         stream: false,
         ...(loopState ? { serverToolLoopState: loopState } : {}),
         ...(engineResult.execution.followup.metadata ?? {})
     };
+    // Followup re-enters HubPipeline at chat-process entry with a canonical "chat-like" body.
+    // This avoids re-running per-protocol inbound parse/semantic-map for each client protocol.
+    metadata.__hubEntry = 'chat_process';
     // Enforce unified followup contract:
     // - clear any inherited routeHint
     // - do not inherit sticky target
@@ -232,7 +377,14 @@ export async function runServerToolOrchestration(options) {
     const retryEmptyFollowupOnce = isStopMessageFlow || isGeminiEmptyReplyContinue;
     const maxAttempts = retryEmptyFollowupOnce ? 2 : 1;
     const followupRequestId = buildFollowupRequestId(options.requestId, engineResult.execution.followup.requestIdSuffix);
-    const followupPayload = coerceFollowupPayloadStream(engineResult.execution.followup.payload, metadata.stream === true);
+    let followupPayload = coerceFollowupPayloadStream(followupPayloadRaw, metadata.stream === true);
+    followupPayload = applyHubFollowupPolicyShadow({
+        requestId: followupRequestId,
+        entryEndpoint: followupEntryEndpoint,
+        flowId: engineResult.execution.flowId,
+        payload: followupPayload,
+        stageRecorder: options.stageRecorder
+    });
     let followup;
     let lastError;
     // stopMessage 是一种“状态型” servertool：一旦触发，我们需要尽量避免因 followup 失败而把状态留在可继续触发的位置，
@@ -303,6 +455,7 @@ export async function runServerToolOrchestration(options) {
             // 对 stopMessage：避免把 empty followup 升级为 502，直接清理 stopMessage 状态并返回原始响应。
             // 这样客户端至少能拿到本轮输出，且 stopMessage 不会在后续请求里继续触发导致“永远 502”。
             disableStopMessageAfterFailedFollowup(options.adapterContext, stopMessageReservation);
+            logProgress(5, totalSteps, 'completed (stopMessage followup empty; cleaned state)', { flowId });
             return {
                 chat: engineResult.finalChatResponse,
                 executed: true,
@@ -323,6 +476,7 @@ export async function runServerToolOrchestration(options) {
         throw wrapped;
     }
     const decorated = decorateFinalChatWithServerToolContext(followupBody ?? engineResult.finalChatResponse, engineResult.execution);
+    logProgress(5, totalSteps, 'completed', { flowId });
     return {
         chat: decorated,
         executed: true,