@ai-agent-forge/agent-forge 0.85.0

package/dist/core/extensions/bootstrap-agent-loop.js

@@ -0,0 +1,565 @@
+/**
+ * Default agent-loop bootstrap executor (W3).
+ *
+/**
+ * Registers the default main-loop capabilities through the public extension
+ * face so the default loop stays a replaceable first-party plugin:
+ * - the five default loop-hook links (capability lifecycle dispatch, image
+ *   normalization, context strategy, compaction + next-turn refresh, and the
+ *   repeated-tool-call guard: shouldStopAfterTurn decision + transformContext
+ *   warn-reminder injection), and
+ * - the default post-run continuation strategy (the host's own candidate
+ *   decision).
+ *
+ * The default links need session-bound host state (session id, revision,
+ * correlation id, error observation, settings). That state is injected as
+ * {@link AgentLoopWiringV1} — host wiring, not a plugin capability. Third-party
+ * plugins register additional links through `api.registerLoopHook`; they run
+ * after the default links in registration order.
+ */
+import { createHash } from "node:crypto";
+import { normalizeToolResultImages } from "../../utils/tool-result-images.js";
+import { loadCapabilityPluginSync } from "./capability-plugin.js";
+import { applyCapabilityContextStrategy } from "./context-strategy-binding.js";
+import { TOOL_CALL_EVENT_ID, TOOL_CALL_EVENT_VERSION, TOOL_EXECUTE_EVENT_ID, TOOL_EXECUTE_EVENT_VERSION, TOOL_RESULT_RAW_EVENT_ID, TOOL_RESULT_RAW_EVENT_VERSION, TOOL_RESULT_TRANSFORM_EVENT_ID, TOOL_RESULT_TRANSFORM_EVENT_VERSION, } from "./lifecycle-catalog.js";
+import { detachedSessionSnapshot, EXPERIMENTAL_PUBLIC_API_VERSION, } from "./public-api.js";
+export const BOOTSTRAP_AGENT_LOOP_PLUGIN_ID = "agent-forge.bootstrap-agent-loop";
+export const DEFAULT_RUN_LOOP_STRATEGY_NAME = "default";
+/** 滑动窗口大小：护栏只回看最近 N 个工具调用签名（跨回合累计）。 */
+export const REPEATED_TOOL_CALL_WINDOW_SIZE = 6;
+/** 提醒阈值：窗口尾部连续相同签名达到该次数时提醒模型（不停机，两级响应第一级）。 */
+export const REPEATED_TOOL_CALL_WARN_THRESHOLD = 3;
+/** 停机阈值：提醒后仍连续相同达到该次数才请求停机（两级响应第二级兜底）。 */
+export const REPEATED_TOOL_CALL_STOP_THRESHOLD = 5;
+/** 停机提示消息的 customType（用户可见面，随 agent_end 的 messages 带出）。 */
+export const REPEATED_TOOL_CALL_STOP_CUSTOM_TYPE = "loop_guard_stop";
+/** 提醒消息的 customType（用户可见面经 sendMessage 持久化+渲染；模型面注入复用同一标记）。 */
+export const REPEATED_TOOL_CALL_WARN_CUSTOM_TYPE = "loop_guard_warn";
+/** 提示消息中参数串的最大长度，超出截断（只影响提示文本，不影响检测签名）。 */
+export const REPEATED_TOOL_CALL_NOTICE_MAX_ARGS_CHARS = 200;
+/**
+ * 参数稳定字符串化：对象键递归排序后逐层拼接（数组保持顺序），循环引用输出
+ * 固定占位。只用于签名比较与提示文本，不是通用 JSON 序列化器。
+ */
+export function stableSerializeValue(value, seen = new WeakSet()) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "number":
+            return String(value);
+        case "boolean":
+            return String(value);
+        case "undefined":
+            return "undefined";
+        case "bigint":
+            return `bigint:${String(value)}`;
+        case "function":
+            return "function";
+        case "symbol":
+            return "symbol";
+        case "object":
+            break;
+        default:
+            return "unknown";
+    }
+    if (seen.has(value))
+        return '"[cycle]"';
+    seen.add(value);
+    const serialized = Array.isArray(value)
+        ? `[${value.map((item) => stableSerializeValue(item, seen)).join(",")}]`
+        : (() => {
+            const record = value;
+            const keys = Object.keys(record).sort();
+            return `{${keys.map((key) => `${JSON.stringify(key)}:${stableSerializeValue(record[key], seen)}`).join(",")}}`;
+        })();
+    seen.delete(value);
+    return serialized;
+}
+/**
+ * 工具结果哈希（签名第三要素）：拼接结果的 text 内容后做全量 SHA-256（十六进制），
+ * isError 一并纳入（同参同果且同错误状态才计重复）。任何字节差异都产生不同哈希，
+ * 因此长结果（前缀稳定、尾部变化）的合法轮询不会被误判成"同果"——签名不受任何
+ * 截断影响。无文本结果（纯图像等）与结果缺席都返回空串占位：签名退化为两要素
+ * （工具名 + 参数），这是已知局限——无文本的同参结果彼此不可区分。
+ * 调用与结果按 toolCallId 对应，正常流程中每个调用都有结果；无结果返回空串。
+ */
+export function toolResultHash(result) {
+    if (!result)
+        return "";
+    const text = result.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    if (text === "")
+        return "";
+    return `${result.isError ? "error" : "ok"}:${createHash("sha256").update(text).digest("hex")}`;
+}
+/** 工具调用签名：工具名 + 参数稳定字符串化 + 结果哈希。 */
+export function repeatedToolCallSignature(toolName, args, resultHash) {
+    return `${JSON.stringify(toolName)}:${stableSerializeValue(args)}:${resultHash}`;
+}
+/** 参数摘要截断：超出 {@link REPEATED_TOOL_CALL_NOTICE_MAX_ARGS_CHARS} 打截断标记（用户可见消息与日志通道共用）。 */
+function truncateNoticeArgs(argsText) {
+    return argsText.length > REPEATED_TOOL_CALL_NOTICE_MAX_ARGS_CHARS
+        ? `${argsText.slice(0, REPEATED_TOOL_CALL_NOTICE_MAX_ARGS_CHARS)}...(truncated)`
+        : argsText;
+}
+/** 停机提示消息：随停机回合的 newMessages 带出（agent_end 可见），并经 deliverNotice 投递到宿主公共面。 */
+export function createRepeatedToolCallStopNotice(toolName, argsText, stopThreshold) {
+    const truncated = truncateNoticeArgs(argsText);
+    return {
+        role: "custom",
+        customType: REPEATED_TOOL_CALL_STOP_CUSTOM_TYPE,
+        content: `Loop guard: stopped after the same tool call (${toolName}) was repeated ${stopThreshold} times in a row. Args: ${truncated}`,
+        display: true,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * 提醒通知消息（用户可见面，loop_guard_warn）：经 deliverWarn 投递（默认安装接
+ * `SessionAPI.sendMessage`，持久化 + 实时渲染），与停机通知（loop_guard_stop）
+ * 的 customType 区分。提醒不进入 newMessages——模型面提醒由 transformContext
+ * 注入承担，用户面提醒由本消息的持久化+渲染承担。
+ */
+export function createRepeatedToolCallWarnNotice(toolName, argsText, warnThreshold) {
+    const truncated = truncateNoticeArgs(argsText);
+    return {
+        role: "custom",
+        customType: REPEATED_TOOL_CALL_WARN_CUSTOM_TYPE,
+        content: `Loop guard: the same tool call (${toolName}) was repeated ${warnThreshold} times in a row with the same result. Args: ${truncated}`,
+        display: true,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * 模型面提醒消息（transformContext 注入用）：display:false 的 custom 消息，
+ * 经 convertToLlm 转为 user 文本进入下一次模型请求。只存在于该次请求视图
+ * （不写 context.messages、不进 newMessages，故不持久化）；customType 复用
+ * loop_guard_warn 标记来源。
+ */
+export function createRepeatedToolCallWarnReminder(warnThreshold) {
+    return {
+        role: "custom",
+        customType: REPEATED_TOOL_CALL_WARN_CUSTOM_TYPE,
+        content: `You have repeated the identical tool call with an identical result ${warnThreshold} times. If you are waiting for external state to change, change your approach instead of retrying the same call.`,
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * 默认重复工具调用护栏（主对话循环护栏切片A，两级响应）。
+ *
+ * 每个完成的回合从 assistant 消息中按序取出工具调用，签名（工具名 + 键序参数
+ * + 本轮结果哈希，结果按 toolCallId 对应）追加进滑动窗口并裁剪到 windowSize；
+ * 然后按窗口尾部连续相同签名段（含同一回合内多次相同调用）做两级响应：
+ *
+ * - 第一级（达到 warnThreshold，缺省 3）：返回 false 不停机，改为提醒——内部
+ *   标记 pendingWarn，由本工厂返回的 transformContext 链路在下一轮请求前把提醒
+ *   消息追加到请求视图尾部（agent-loop 的 runLoop 在每次 shouldStopAfterTurn
+ *   之后、下一次 streamAssistantResponse 之前消费 transformContext，故提醒必然
+ *   进入下一次请求）；同时把用户可见提醒经 deliverWarn 投递、事实经 onWarn 记
+ *   日志。同一连续重复段只提醒一次（warnedForRun 闩）；连续段断开（模型改变
+ *   行为）即复位，后续新的连续段可再次提醒。
+ * - 第二级（达到 stopThreshold，缺省 5）：返回 true 请求停机——先向
+ *   {@link ShouldStopAfterTurnContext} 的 newMessages 追加一条用户可见的停机消
+ *   息并交给 deliverNotice（禁止静默停机），再经 onStop 记日志。判据不可能完
+ *   美，因此不可逆停机不是第一响应。
+ *
+ * 同参不同果（合法轮询，如等待外部状态就绪）不计重复：结果要素是全量哈希，
+ * 任何字节差异（包括 >200 字符长结果仅尾部变化）都产生不同签名；无文本结果
+ * 退化为两要素（见 {@link toolResultHash} 局限声明）。无工具调用或结果缺席的
+ * 轮次不进窗口。
+ *
+ * 挂载点说明：两条链路都由 {@link installBootstrapAgentLoop} 经公共扩展面
+ * `api.registerLoopHook` 注册为默认链路（transformContext 注入链注册在默认上
+ * 下文策略链之后，提醒落到最终请求视图尾部）；disabledBootstrapPlugins 跳过本
+ * 插件时均不注册，护栏随之关闭。wireDefaultLoop 只消费链，不直接安装本策略。
+ */
+export function createRepeatedToolCallStopPolicy(options = {}) {
+    const windowSize = options.windowSize ?? REPEATED_TOOL_CALL_WINDOW_SIZE;
+    const warnThreshold = options.warnThreshold ?? REPEATED_TOOL_CALL_WARN_THRESHOLD;
+    const stopThreshold = options.stopThreshold ?? REPEATED_TOOL_CALL_STOP_THRESHOLD;
+    const window = [];
+    let lastToolName = "";
+    let lastArgsText = "";
+    /** 待注入的提醒事实：warn 时置位，transformContext 消费即清除（只注入一次）。 */
+    let pendingWarn;
+    /** 当前连续重复段已提醒闩：同段不重复提醒；段断开（尾部连续段短于提醒阈值）时复位。 */
+    let warnedForRun = false;
+    /** 窗口尾部连续相同签名的段长。 */
+    const trailingRunLength = () => {
+        const last = window[window.length - 1];
+        if (last === undefined)
+            return 0;
+        let run = 0;
+        for (let i = window.length - 1; i >= 0 && window[i] === last; i -= 1)
+            run += 1;
+        return run;
+    };
+    const shouldStopAfterTurn = (context) => {
+        const toolCalls = context.message.content.filter((block) => block.type === "toolCall");
+        // 三要素签名需要本轮工具结果：结果缺席时无法判定"同果"，该轮不进窗口，
+        // 避免把合法轮询误判成重复。
+        if (toolCalls.length > 0 && context.toolResults.length > 0) {
+            const resultById = new Map(context.toolResults.map((result) => [result.toolCallId, result]));
+            for (const call of toolCalls) {
+                window.push(repeatedToolCallSignature(call.name, call.arguments, toolResultHash(resultById.get(call.id))));
+                lastToolName = call.name;
+                lastArgsText = stableSerializeValue(call.arguments);
+            }
+        }
+        if (window.length > windowSize) {
+            window.splice(0, window.length - windowSize);
+        }
+        const run = trailingRunLength();
+        if (run >= stopThreshold) {
+            // 第二级兜底：硬停，走停机全通道（newMessages + deliverNotice + onStop）。
+            // 先于提醒判定：stopThreshold 被显式覆盖到不大于 warnThreshold 时停机优先。
+            pendingWarn = undefined;
+            const notice = createRepeatedToolCallStopNotice(lastToolName, lastArgsText, stopThreshold);
+            context.newMessages.push(notice);
+            options.deliverNotice?.(notice);
+            // 日志可见通道（D-072 6(a)）：与用户可见提示成对发出；onStop 属宿主接线，
+            // 策略本身不知道任何具体日志实现。
+            options.onStop?.({ toolName: lastToolName, argsSummary: truncateNoticeArgs(lastArgsText), stopThreshold });
+            return true;
+        }
+        if (run < warnThreshold) {
+            // 连续段断开：模型改变行为。复位已提醒闩并丢弃未消费的待注入提醒
+            // （正常流程中它已在下一轮请求前被消费；此处只兜底运行中断的残留）。
+            warnedForRun = false;
+            pendingWarn = undefined;
+            return false;
+        }
+        // 第一级：提醒不停机。标记待注入（transformContext 链路消费），经
+        // deliverWarn/onWarn 双通道可见；同一连续段只提醒一次。
+        if (!warnedForRun) {
+            warnedForRun = true;
+            pendingWarn = { toolName: lastToolName, argsSummary: truncateNoticeArgs(lastArgsText), warnThreshold };
+            options.deliverWarn?.(createRepeatedToolCallWarnNotice(lastToolName, lastArgsText, warnThreshold));
+            options.onWarn?.(pendingWarn);
+        }
+        return false;
+    };
+    const transformContext = async (messages, _signal) => {
+        const info = pendingWarn;
+        if (!info)
+            return undefined;
+        // 消费即清除：提醒只注入一次；重复继续发生不重复注入。非变异地追加到
+        // 请求视图尾部（不写 context.messages，故不持久化、不进 newMessages）。
+        pendingWarn = undefined;
+        return [...messages, createRepeatedToolCallWarnReminder(info.warnThreshold)];
+    };
+    return { shouldStopAfterTurn, transformContext };
+}
+/**
+ * Default beforeToolCall link: the `tool.call@1` candidate dispatch with
+ * identity/revision checks. Moved from the AgentSession tool-hook wiring.
+ */
+function createDefaultBeforeToolCallLink(runtime, wiring) {
+    return async ({ toolCallId, toolName, args, signal }) => {
+        // v8 ignore next -- bootstrap lifecycle 恒定义全部生命周期事件，其 token 在 dispose 前恒活跃，提前返回不可达
+        if (!runtime.hasLifecycleEvent(TOOL_CALL_EVENT_ID, TOOL_CALL_EVENT_VERSION))
+            return undefined;
+        const data = {
+            version: 1,
+            sessionId: wiring.getSessionId(),
+            revision: wiring.getRevision(),
+            toolCallId,
+            toolName,
+            input: detachedSessionSnapshot(args),
+        };
+        try {
+            const delivery = await runtime.dispatchLifecycle({
+                type: TOOL_CALL_EVENT_ID,
+                version: TOOL_CALL_EVENT_VERSION,
+                phase: "candidate",
+                data,
+                source: "agent-session",
+                correlationId: wiring.getTurnCorrelationId(),
+                signal,
+            });
+            for (const failure of delivery.report.failures) {
+                wiring.observeError(failure.error, failure.pluginId, `${TOOL_CALL_EVENT_ID}@${TOOL_CALL_EVENT_VERSION}/${failure.kind}`);
+            }
+            const transformed = delivery.data;
+            const revision = transformed.revision;
+            if (transformed.sessionId !== data.sessionId ||
+                transformed.toolCallId !== data.toolCallId ||
+                transformed.toolName !== data.toolName ||
+                revision.version !== data.revision.version ||
+                revision.sessionId !== data.revision.sessionId ||
+                revision.sequence !== data.revision.sequence ||
+                revision.leafId !== data.revision.leafId) {
+                throw new Error(`${TOOL_CALL_EVENT_ID} transform cannot change call identity or revision`);
+            }
+            return { args: transformed.input };
+        }
+        catch (error) {
+            const report = error.report;
+            if (report?.failures) {
+                for (const failure of report.failures) {
+                    wiring.observeError(failure.error, failure.pluginId, `${TOOL_CALL_EVENT_ID}@${TOOL_CALL_EVENT_VERSION}/${failure.kind}`);
+                }
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Default afterToolCall link: `tool.execute@1` committed, `tool.result.raw@1`
+ * raw, the legacy `tool_result` extension hook (via wiring), image
+ * normalization, and the `tool.result.transform@1` candidate dispatch — in the
+ * exact order the previous single AgentSession hook used. Moved from the
+ * AgentSession tool-hook wiring.
+ */
+function createDefaultAfterToolCallLink(runtime, wiring) {
+    return async ({ toolCallId, toolName, args, result, isError, signal }) => {
+        const toolResult = result;
+        if (runtime.hasLifecycleEvent(TOOL_EXECUTE_EVENT_ID, TOOL_EXECUTE_EVENT_VERSION)) {
+            try {
+                const data = {
+                    version: 1,
+                    sessionId: wiring.getSessionId(),
+                    revision: wiring.getRevision(),
+                    toolCallId,
+                    toolName,
+                    input: detachedSessionSnapshot(args),
+                    isError,
+                    content: detachedSessionSnapshot(toolResult.content ?? []),
+                };
+                const delivery = await runtime.dispatchLifecycle({
+                    type: TOOL_EXECUTE_EVENT_ID,
+                    version: TOOL_EXECUTE_EVENT_VERSION,
+                    phase: "committed",
+                    data,
+                    source: "agent-session",
+                    correlationId: wiring.getTurnCorrelationId(),
+                });
+                for (const failure of delivery.report.failures) {
+                    wiring.observeError(failure.error, failure.pluginId, `${TOOL_EXECUTE_EVENT_ID}@${TOOL_EXECUTE_EVENT_VERSION}/${failure.kind}`);
+                }
+            }
+            catch (error) {
+                const report = error.report;
+                if (report?.failures) {
+                    for (const failure of report.failures) {
+                        wiring.observeError(failure.error, failure.pluginId, `${TOOL_EXECUTE_EVENT_ID}@${TOOL_EXECUTE_EVENT_VERSION}/${failure.kind}`);
+                    }
+                }
+                else {
+                    wiring.observeError(error, "<capability-lifecycle>", `${TOOL_EXECUTE_EVENT_ID}@${TOOL_EXECUTE_EVENT_VERSION}`);
+                }
+            }
+        }
+        if (runtime.hasLifecycleEvent(TOOL_RESULT_RAW_EVENT_ID, TOOL_RESULT_RAW_EVENT_VERSION) && !signal?.aborted) {
+            try {
+                const data = {
+                    version: 1,
+                    sessionId: wiring.getSessionId(),
+                    revision: wiring.getRevision(),
+                    toolCallId,
+                    toolName,
+                    isError,
+                    content: detachedSessionSnapshot(toolResult.content ?? []),
+                };
+                const delivery = await runtime.dispatchLifecycle({
+                    type: TOOL_RESULT_RAW_EVENT_ID,
+                    version: TOOL_RESULT_RAW_EVENT_VERSION,
+                    phase: "raw",
+                    data,
+                    source: "agent-session",
+                    correlationId: wiring.getTurnCorrelationId(),
+                    signal,
+                });
+                for (const failure of delivery.report.failures) {
+                    wiring.observeError(failure.error, failure.pluginId, `${TOOL_RESULT_RAW_EVENT_ID}@${TOOL_RESULT_RAW_EVENT_VERSION}/${failure.kind}`);
+                }
+            }
+            catch (error) {
+                if (!signal?.aborted) {
+                    wiring.observeError(error, "host", `${TOOL_RESULT_RAW_EVENT_ID}@${TOOL_RESULT_RAW_EVENT_VERSION}/dispatch`);
+                }
+            }
+        }
+        const content = toolResult.content ?? [];
+        // Images are normalized before the transform dispatch so injected or
+        // replaced images are normalized too.
+        const normalizedContent = await normalizeToolResultImages(content, {
+            autoResizeImages: wiring.getImageAutoResize(),
+        });
+        const legacyIsError = isError;
+        // Standard tool.result.transform@1 candidate dispatch runs on the
+        // normalized result candidate, after the legacy tool_result hook and
+        // before the result is returned for session commit. Transform output is
+        // schema-validated and identity-checked; failures propagate to the
+        // agent loop's existing afterToolCall error isolation.
+        let finalContent = normalizedContent;
+        let finalIsError = legacyIsError;
+        if (runtime.hasLifecycleEvent(TOOL_RESULT_TRANSFORM_EVENT_ID, TOOL_RESULT_TRANSFORM_EVENT_VERSION) &&
+            !signal?.aborted) {
+            const data = {
+                version: 1,
+                sessionId: wiring.getSessionId(),
+                revision: wiring.getRevision(),
+                toolCallId,
+                toolName,
+                isError: legacyIsError,
+                content: detachedSessionSnapshot(normalizedContent),
+            };
+            try {
+                const delivery = await runtime.dispatchLifecycle({
+                    type: TOOL_RESULT_TRANSFORM_EVENT_ID,
+                    version: TOOL_RESULT_TRANSFORM_EVENT_VERSION,
+                    phase: "candidate",
+                    data,
+                    source: "agent-session",
+                    correlationId: wiring.getTurnCorrelationId(),
+                    signal,
+                });
+                for (const failure of delivery.report.failures) {
+                    wiring.observeError(failure.error, failure.pluginId, `${TOOL_RESULT_TRANSFORM_EVENT_ID}@${TOOL_RESULT_TRANSFORM_EVENT_VERSION}/${failure.kind}`);
+                }
+                const transformed = delivery.data;
+                const revision = transformed.revision;
+                if (transformed.sessionId !== data.sessionId ||
+                    transformed.toolCallId !== data.toolCallId ||
+                    transformed.toolName !== data.toolName ||
+                    revision.version !== data.revision.version ||
+                    revision.sessionId !== data.revision.sessionId ||
+                    revision.sequence !== data.revision.sequence ||
+                    revision.leafId !== data.revision.leafId) {
+                    throw new Error(`${TOOL_RESULT_TRANSFORM_EVENT_ID} transform cannot change result identity or revision`);
+                }
+                finalContent = transformed.content;
+                finalIsError = transformed.isError;
+            }
+            catch (error) {
+                const report = error.report;
+                if (report?.failures) {
+                    for (const failure of report.failures) {
+                        wiring.observeError(failure.error, failure.pluginId, `${TOOL_RESULT_TRANSFORM_EVENT_ID}@${TOOL_RESULT_TRANSFORM_EVENT_VERSION}/${failure.kind}`);
+                    }
+                }
+                throw error;
+            }
+        }
+        if (finalContent === content && finalIsError === isError) {
+            return undefined;
+        }
+        return {
+            content: finalContent,
+            details: toolResult.details,
+            isError: finalIsError,
+            usage: toolResult.usage,
+        };
+    };
+}
+/**
+ * Default transformContext link: the explicitly selected capability context
+ * strategy. Moved from the AgentSession context-transform wiring (the legacy
+ * chaining wrapper keeps composing it for the pre-chain path).
+ */
+function createDefaultTransformContextLink(runtime, wiring) {
+    return async (messages, signal) => {
+        const strategyName = wiring.getContextStrategyName();
+        if (!strategyName)
+            return undefined;
+        return applyCapabilityContextStrategy(messages, runtime, strategyName, wiring.getSessionId(), signal);
+    };
+}
+/**
+ * Default prepareNextTurn link: compaction first, then the agent's
+ * construction-time prepare adapter, then the system-prompt/tools/model/
+ * thinking-level refresh. Moved from the AgentSession next-turn wiring.
+ */
+function createDefaultPrepareNextTurnLink(wiring) {
+    return async (turn, signal) => {
+        const turnContext = turn;
+        const context = await wiring.compactBeforeNextAssistantResponse(turnContext.context, signal);
+        const previousSnapshot = await wiring.getInitialPrepareNextTurn()?.({ ...turnContext, context }, signal);
+        const nextContext = previousSnapshot?.context ?? context;
+        const refresh = wiring.getTurnRefresh();
+        return {
+            ...previousSnapshot,
+            context: {
+                ...nextContext,
+                systemPrompt: refresh.systemPrompt,
+                tools: refresh.tools,
+            },
+            model: refresh.model,
+            thinkingLevel: refresh.thinkingLevel,
+        };
+    };
+}
+/**
+ * Install the default agent-loop executor as a first-party plugin. Default
+ * links register first, so third-party links registered later chain after
+ * them in registration order.
+ */
+export function installBootstrapAgentLoop(runtime, wiring) {
+    return loadCapabilityPluginSync(runtime, {
+        id: BOOTSTRAP_AGENT_LOOP_PLUGIN_ID,
+        version: "0.0.0",
+        apiVersion: EXPERIMENTAL_PUBLIC_API_VERSION,
+        entry: "<embedded:bootstrap-agent-loop>",
+    }, (api) => {
+        api.registerLoopHook("beforeToolCall", createDefaultBeforeToolCallLink(runtime, wiring));
+        api.registerLoopHook("afterToolCall", createDefaultAfterToolCallLink(runtime, wiring));
+        api.registerLoopHook("transformContext", createDefaultTransformContextLink(runtime, wiring));
+        api.registerLoopHook("prepareNextTurn", createDefaultPrepareNextTurnLink(wiring));
+        // The default repeated-tool-call guard rides the public loop-hook
+        // chains like any other first-party link; disabling this plugin
+        // removes both of its links. It answers with two levels (judgments
+        // can be wrong, so an irreversible stop is never the first response):
+        // - warn (third identical call): the shouldStopAfterTurn link votes
+        //   false and the transformContext link below injects a reminder into
+        //   the next request view (runLoop consumes transformContext after
+        //   shouldStopAfterTurn and before the next model call); the user-
+        //   facing warn notice is delivered through the public SessionAPI
+        //   sendMessage face (persisted custom_message entry with live
+        //   message_start/message_end rendering), plus a warn log through
+        //   the public LoggerAPI.
+        // - stop (fifth identical call): the shouldStopAfterTurn link votes
+        //   true; the stop notice rides agent_end newMessages, sendMessage
+        //   persistence + rendering, and a warn log — all channels on.
+        // Absent host features (session/logger) degrade to the remaining
+        // channels instead of blocking the guard.
+        const loopGuard = createRepeatedToolCallStopPolicy({
+            deliverWarn: (notice) => {
+                void api.session?.sendMessage?.(notice, { triggerTurn: false });
+            },
+            onWarn: (info) => {
+                api.logger?.warn("Loop guard warned the model", {
+                    tool: info.toolName,
+                    repeats: info.warnThreshold,
+                    argsSummary: info.argsSummary,
+                });
+            },
+            deliverNotice: (notice) => {
+                void api.session?.sendMessage?.(notice, { triggerTurn: false });
+            },
+            onStop: (info) => {
+                api.logger?.warn("Loop guard stopped the turn", {
+                    tool: info.toolName,
+                    repeats: info.stopThreshold,
+                    argsSummary: info.argsSummary,
+                });
+            },
+        });
+        api.registerLoopHook("shouldStopAfterTurn", loopGuard.shouldStopAfterTurn);
+        // Registered after the default context-strategy link, so the reminder
+        // is appended to the final post-strategy request view (survives any
+        // strategy pruning) at its tail.
+        api.registerLoopHook("transformContext", loopGuard.transformContext);
+        // The default continuation strategy reproduces the host's own
+        // post-run decision byte for byte; a replacement strategy overrides
+        // the continue/stop call through registerRunLoopStrategy.
+        api.registerRunLoopStrategy(DEFAULT_RUN_LOOP_STRATEGY_NAME, {
+            decideNextCycle: (request) => ({ continueLoop: request.hostWillContinue }),
+        });
+    });
+}
+//# sourceMappingURL=bootstrap-agent-loop.js.map