@armadra/agent 0.0.0-stage → 0.3.0

package/dist/agent/session-compaction.js

@@ -0,0 +1,251 @@
+/**
+ * 会话侧的压缩调度（设计 §9）。[B2]
+ *
+ * - 阈值检查（新提示前、`prepareNextTurn` 里）：估算 > 0.7 ×（窗口 − 预留）→ 档一裁剪；仍 > 窗口 − 预留
+ *   且熔断允许 → 档二摘要（trigger `threshold`）。
+ * - 溢出恢复（会话 run 结束后，失败尝试已用 context_edit 剔除）：PreCompact Hook → 档二摘要（trigger
+ *   `overflow`，不受「每 run 一次」限制但受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
+ * - 手动 `/compact`：PreCompact（trigger `manual`）→ 摘要；成功清零熔断。
+ * PreCompact 的 `decision: "block"` 取消本次压缩；`customInstructions` 追加到摘要提示。
+ * [W3-C1b] 阈值 / 手动压缩与分支摘要优先走会话前缀续写（缓存控制器给前缀），溢出恢复不走
+ * （前缀本身已超窗口）；续写失败回落独立请求并记 warning。
+ */
+import { AmaError } from "../errors.js";
+import { CompactionBreaker } from "../compaction/breaker.js";
+import { estimateProjectedTokens } from "../compaction/estimate.js";
+import { planPrune, shouldPrune } from "../compaction/prune-tier.js";
+import { prepareCompaction, runCompaction, } from "../compaction/summarize-tier.js";
+import { prepareBranchSummary, runBranchSummary } from "../compaction/branch-summary.js";
+import { buildProjection } from "../session/projection.js";
+export const DEFAULT_COMPACTION_SETTINGS = {
+    enabled: true,
+    reserveTokens: 16_384,
+    keepRecentTokens: 20_000,
+};
+/** 保留区不超过 (窗口 − 预留) 的 40%，否则小窗口模型上摘要后仍然溢出。 */
+export const KEEP_RECENT_MAX_RATIO = 0.4;
+export class CompactionController {
+    breaker;
+    settings;
+    core;
+    compacting = false;
+    constructor(core, settings = {}) {
+        this.core = core;
+        this.settings = { ...DEFAULT_COMPACTION_SETTINGS, ...settings };
+        this.breaker = new CompactionBreaker(this.settings.enabled, core.model().contextWindow);
+    }
+    get isCompacting() {
+        return this.compacting;
+    }
+    /** 模型或开关变化后调用。 */
+    refresh() {
+        this.breaker.configure(this.settings.enabled, this.core.model().contextWindow);
+    }
+    setAuto(enabled) {
+        this.settings = { ...this.settings, enabled };
+        this.refresh();
+    }
+    estimate() {
+        const branch = this.core.manager.branch();
+        return estimateProjectedTokens(buildProjection(branch).items, branch);
+    }
+    budget() {
+        const window = this.core.model().contextWindow;
+        return window === undefined ? undefined : Math.max(0, window - this.settings.reserveTokens);
+    }
+    keepRecent() {
+        const budget = this.budget();
+        if (budget === undefined)
+            return this.settings.keepRecentTokens;
+        return Math.max(1, Math.min(this.settings.keepRecentTokens, Math.floor(budget * KEEP_RECENT_MAX_RATIO)));
+    }
+    /** 摘要请求的公共选项；`continuation` 时附上会话前缀续写的材料。 */
+    async summarizer(signal, instructions, continuation) {
+        const core = this.core;
+        const options = {
+            stream: core.stream,
+            model: core.model(),
+            apiKey: await core.resolveApiKey(),
+            signal,
+            customInstructions: instructions,
+            onFallback: (reason) => core.log("warn", `summary by prefix continuation failed (${reason}); used a separate request`),
+        };
+        if (continuation)
+            options.continuation = core.cache?.summaryContinuation();
+        return options;
+    }
+    /** 档一；返回是否裁剪了内容。 */
+    prune() {
+        const branch = this.core.manager.branch();
+        const plan = planPrune(buildProjection(branch).items, { outputDir: this.core.outputDir() });
+        for (const item of plan) {
+            this.core.appendEntry({
+                type: "context_edit",
+                targetId: item.targetId,
+                replacement: item.replacement,
+                reason: "prune",
+            });
+        }
+        if (plan.length > 0)
+            this.core.reloadMessages();
+        return plan.length > 0;
+    }
+    /** 阈值检查（档一 → 档二）。失败只记录，不打断 run。 */
+    async checkThreshold(signal) {
+        if (!this.breaker.autoEnabled || this.compacting || signal.aborted)
+            return;
+        const window = this.core.model().contextWindow;
+        const reserve = this.settings.reserveTokens;
+        let tokens = this.estimate().tokens;
+        if (shouldPrune(tokens, window, reserve) && this.prune())
+            tokens = this.estimate().tokens;
+        if (tokens <= window - reserve || !this.breaker.canSummarize())
+            return;
+        await this.summarize("threshold", signal);
+    }
+    /** 溢出恢复：返回是否应以新 run 重试。 */
+    async recoverOverflow(signal) {
+        if (!this.settings.enabled)
+            return { retry: false, warning: "context overflow: auto-compaction is disabled" };
+        if (this.core.model().contextWindow === undefined) {
+            return {
+                retry: false,
+                warning: "context overflow: model has no contextWindow, auto-compaction is off",
+            };
+        }
+        if (this.breaker.tripped) {
+            return {
+                retry: false,
+                warning: "context overflow: auto-compaction disabled after repeated failures",
+            };
+        }
+        const outcome = await this.summarize("overflow", signal);
+        if (outcome.result === undefined) {
+            if (signal.aborted)
+                return { retry: false };
+            return {
+                retry: false,
+                warning: `context overflow: compaction failed (${outcome.error ?? "unknown"})`,
+            };
+        }
+        if (!this.breaker.shouldRetryAfterCompaction(outcome.tokensAfter ?? Number.POSITIVE_INFINITY)) {
+            return {
+                retry: false,
+                warning: "context overflow: still above 80% of the window after compaction",
+            };
+        }
+        return { retry: true };
+    }
+    async compactManual(instructions, signal) {
+        const outcome = await this.summarize("manual", signal, instructions);
+        if (outcome.result === undefined) {
+            if (outcome.aborted)
+                throw new AmaError("aborted", "compaction aborted");
+            throw new AmaError("compaction_failed", outcome.error ?? "compaction failed");
+        }
+        this.breaker.reset();
+        return outcome.result;
+    }
+    /** `/tree` 离开分支：换叶子，并为离开的那段写 branch_summary（挂在新叶子下）。 */
+    async leaveBranch(targetId, instructions, signal) {
+        const core = this.core;
+        const index = new Map(core.manager.entries().map((entry) => [entry.id, entry]));
+        const plan = prepareBranchSummary(index, core.manager.leafId(), targetId);
+        core.manager.setLeaf(targetId);
+        if (plan === undefined)
+            return undefined;
+        const draft = await runBranchSummary(plan, await this.summarizer(signal, instructions, true));
+        return core.appendEntry({
+            type: "branch_summary",
+            fromId: draft.fromId,
+            summary: draft.summary,
+            usage: draft.usage,
+            details: draft.details,
+        });
+    }
+    async summarize(trigger, signal, instructions) {
+        const core = this.core;
+        this.compacting = true;
+        core.emit({ type: "compaction_start", trigger });
+        const end = (outcome, willRetry) => {
+            const event = {
+                type: "compaction_end",
+                trigger,
+                aborted: outcome.aborted,
+                willRetry,
+            };
+            if (outcome.result !== undefined)
+                event.result = outcome.result;
+            if (outcome.error !== undefined)
+                event.error = outcome.error;
+            core.emit(event);
+            this.compacting = false;
+            return outcome;
+        };
+        const fail = (error, aborted = false) => end({ result: undefined, tokensAfter: undefined, error, aborted }, false);
+        const tokensBefore = this.estimate().tokens;
+        let customInstructions = instructions;
+        const hook = await core.runHook("PreCompact", { tokensBefore, trigger: trigger === "manual" ? "manual" : "auto" }, signal);
+        if (hook !== undefined) {
+            if (hook.decision === "block" || hook.decision === "deny") {
+                return fail(hook.reason ?? "compaction blocked by PreCompact hook", true);
+            }
+            if (hook.customInstructions !== undefined) {
+                customInstructions = [customInstructions, hook.customInstructions]
+                    .filter(Boolean)
+                    .join("\n\n");
+            }
+        }
+        if (signal.aborted)
+            return fail("aborted", true);
+        // 保留区按预算切不出可摘要的前缀（单条消息很大）时逐级缩小，最后只保留最近一个切点。
+        const projection = buildProjection(core.manager.branch());
+        const keep = this.keepRecent();
+        let plan;
+        for (const budget of [keep, Math.floor(keep / 4), 1]) {
+            plan = prepareCompaction(projection, Math.max(1, budget));
+            if (plan !== undefined)
+                break;
+        }
+        if (plan === undefined) {
+            if (trigger !== "manual")
+                this.breaker.recordSummary(false);
+            return fail("nothing to compact");
+        }
+        try {
+            const options = await this.summarizer(signal, customInstructions, trigger !== "overflow");
+            const draft = await runCompaction(plan, options);
+            if (signal.aborted)
+                return fail("aborted", true);
+            const entry = {
+                type: "compaction",
+                summary: draft.summary,
+                firstKeptEntryId: draft.firstKeptEntryId,
+                tokensBefore,
+                details: draft.details,
+            };
+            if (draft.usage !== undefined)
+                entry.usage = draft.usage;
+            core.appendEntry(entry);
+            core.reloadMessages();
+            this.breaker.recordSummary(true);
+            const tokensAfter = this.estimate().tokens;
+            const result = {
+                summary: draft.summary,
+                firstKeptEntryId: draft.firstKeptEntryId,
+                tokensBefore,
+                tokensAfter,
+            };
+            if (draft.usage !== undefined)
+                result.usage = draft.usage;
+            const willRetry = trigger === "overflow" && this.breaker.shouldRetryAfterCompaction(tokensAfter);
+            return end({ result, tokensAfter, error: undefined, aborted: false }, willRetry);
+        }
+        catch (error) {
+            const aborted = signal.aborted || (error instanceof AmaError && error.code === "aborted");
+            if (!aborted)
+                this.breaker.recordSummary(false);
+            return fail(error instanceof Error ? error.message : String(error), aborted);
+        }
+    }
+}

package/dist/agent/session-core.d.ts

@@ -0,0 +1,103 @@
+/**
+ * AgentSessionImpl 的装配选项与内部协作接口。[B2]
+ *
+ * `AgentSessionOptions` 是集成者（B5 bootstrap / B6 sdk）构造会话时注入的全部依赖；
+ * `SessionCore` 是 session.ts 交给 session-tools.ts / session-compaction.ts 的内部视图（避免循环 import）。
+ */
+import type { WarmingDecisionHandler } from "../ai/cache/types.js";
+import type { Model, ModelThinkingLevel, ProviderRegistryApi } from "../ai/types.js";
+import type { HookDispatcherApi, HookEvent, HookEventPayload, HookOutcome } from "../hooks/types.js";
+import type { ApprovalBroker, PermissionPipelineApi } from "../permissions/types.js";
+import type { SessionManager } from "../session/manager.js";
+import type { SessionEntry, SessionEntryInput } from "../session/types.js";
+import type { SubagentRequest, SubagentResult, ToolDefinition } from "../tools/types.js";
+import type { Agent } from "./agent.js";
+import type { StreamFn } from "./loop.js";
+import type { SessionCacheController } from "./session-cache.js";
+import type { SystemPromptInput } from "./system-prompt.js";
+import type { CacheSettings, CompactionSettings, QueueMode, RetrySettings, SessionEvent } from "./types.js";
+export type PromptExpansion = {
+    text: string;
+} | {
+    handled: true;
+};
+export interface AgentSessionOptions {
+    sessionManager: SessionManager;
+    /** 供应商注册表：getApi / resolveApiKey / findModel（setModel 与子 Agent 用）。 */
+    providers: ProviderRegistryApi;
+    model: Model;
+    thinkingLevel?: ModelThinkingLevel;
+    /** 全部可用工具（内置 + 宿主 + SDK）。 */
+    tools?: readonly ToolDefinition[];
+    /** 活动集；缺省 = tools 全部。 */
+    activeTools?: readonly string[];
+    /** 权限管线（B3）；缺省 = 全部放行。 */
+    permission?: PermissionPipelineApi;
+    /** 审批回答者链：宿主 broker → UI broker；都返回 undefined → deny（无人值守）。 */
+    brokers?: readonly ApprovalBroker[];
+    /** 无人值守：权限管线把 ask 变 deny。 */
+    unattended?: boolean;
+    /** 审批超时，缺省 10 分钟（超时 deny）。 */
+    approvalTimeoutMs?: number;
+    /** 命令式 Hook（B5）；缺省无 Hook。 */
+    hooks?: HookDispatcherApi;
+    /** 系统提示的静态部分（工具与 cwd 由会话填）。 */
+    system?: Omit<SystemPromptInput, "tools" | "cwd">;
+    compaction?: Partial<CompactionSettings>;
+    retry?: Partial<RetrySettings>;
+    steeringMode?: QueueMode;
+    followUpMode?: QueueMode;
+    /** 模板 / `/skill:` 展开（B3 / B7）；`handled` = 已作为命令处理，不进模型。 */
+    expandPrompt?(text: string): Promise<PromptExpansion>;
+    /** 溢出文案识别（B1 的 ai/overflow.ts）；缺省用 retry.ts 内置正则。 */
+    isContextOverflow?(errorMessage: string): boolean;
+    /** 缺省 30 000。 */
+    maxToolResultChars?: number;
+    /** abort 后等待工具自行结束的上限，缺省 3 000 ms。 */
+    abortGraceMs?: number;
+    /** 截断全文目录；缺省 `<会话文件目录>/outputs`，内存会话 undefined。 */
+    outputDir?: string;
+    /** task 深度：主会话 0。 */
+    depth?: number;
+    /** 子 Agent 的回合上限（maxTurns）。 */
+    maxTurns?: number;
+    /** 子 Agent 并发上限，缺省 4；`false` 关闭 spawnSubagent。 */
+    subagents?: {
+        maxConcurrent?: number;
+    } | false;
+    /** 宿主适配器 id（写进 HookInput.host）。 */
+    hostId?: string;
+    /** [W3-C1b] 会话层缓存设置（config `cache` 段 + 环境变量，组装根解析）；缺省见 DEFAULT_CACHE_SETTINGS。 */
+    cache?: Partial<CacheSettings>;
+    /** [W3-C1b] 宿主 `cache.onWarmingDecision` 的处理器（每次保温前现取）。 */
+    warmingDecider?(): WarmingDecisionHandler | undefined;
+    log?(level: "debug" | "info" | "warn" | "error", message: string): void;
+}
+export interface SessionCore {
+    readonly options: AgentSessionOptions;
+    readonly manager: SessionManager;
+    readonly agent: Agent;
+    readonly cwd: string;
+    readonly depth: number;
+    readonly readFiles: Set<string>;
+    /** [W3-C1b] 会话层缓存控制器（摘要续写取前缀）。 */
+    readonly cache?: SessionCacheController;
+    model(): Model;
+    thinkingLevel(): ModelThinkingLevel;
+    outputDir(): string | undefined;
+    stream: StreamFn;
+    resolveApiKey(): Promise<string | undefined>;
+    emit(event: SessionEvent): void;
+    appendEntry(input: SessionEntryInput): SessionEntry;
+    /** 从会话管理器重建 Agent 的上下文消息。 */
+    reloadMessages(): void;
+    activeTool(name: string): ToolDefinition | undefined;
+    /** 任一已登记工具（不限于活动集；嵌套调用用）。 */
+    tool(name: string): ToolDefinition | undefined;
+    activeToolNames(): string[];
+    runHook(event: HookEvent, payload: HookEventPayload, signal?: AbortSignal): Promise<HookOutcome | undefined>;
+    /** Hook 返回 continue:false 时记下，finishTurn 据此结束 run。 */
+    requestStop(reason: string | undefined): void;
+    spawnSubagent(request: SubagentRequest): Promise<SubagentResult>;
+    log(level: "debug" | "info" | "warn" | "error", message: string): void;
+}

package/dist/agent/session-core.js

@@ -0,0 +1,7 @@
+/**
+ * AgentSessionImpl 的装配选项与内部协作接口。[B2]
+ *
+ * `AgentSessionOptions` 是集成者（B5 bootstrap / B6 sdk）构造会话时注入的全部依赖；
+ * `SessionCore` 是 session.ts 交给 session-tools.ts / session-compaction.ts 的内部视图（避免循环 import）。
+ */
+export {};

package/dist/agent/session-run.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 会话级 run 编排（设计 §3.6 重试、§4.2 abort、§6.1 Stop Hook、§9 溢出恢复）。[B2]
+ *
+ * 一次「会话周期」（prompt 到 agent_settled）可以包含多个 Agent run：
+ * - 可重试错误：agent_end{willRetry:true} → 失败尝试 context_edit{reason:"retry"} 剔除 →
+ *   auto_retry_start → 退避（abort 可打断）→ 新 run（continue）；结束时 auto_retry_end。
+ * - 溢出 / length 无工具调用：agent_end{willRetry:true} → context_edit{reason:"overflow"} 剔除 →
+ *   PreCompact → 压缩 → 以新 run 重试**一次**；失败 / 取消则保留剔除、不重试，agent_settled{warning}。
+ * - abort：不清队列；落盘 custom_message{customType:"ama.aborted"}；不再自动续跑。
+ * - 将要停下时发 agent_before_settle 并跑 Stop（子 Agent 为 SubagentStop）Hook：block + reason →
+ *   以 reason 作为新 user 消息再跑一轮（上限 3 次，stopHookActive 传给 Hook）。
+ * - 最终失败后若 followUp 队列非空，照常投递。
+ */
+import type { AssistantMessage, ImageBlock, UserMessage } from "../ai/types.js";
+import type { AgentMessage } from "../session/types.js";
+import type { RunOutcome } from "./loop.js";
+import type { SessionCore } from "./session-core.js";
+import type { CompactionController } from "./session-compaction.js";
+import type { PromptDisposition, RetrySettings } from "./types.js";
+export declare const MAX_STOP_HOOK_CONTINUATIONS = 3;
+export declare const ABORTED_CUSTOM_TYPE = "ama.aborted";
+export type RunDecision = {
+    kind: "done";
+} | {
+    kind: "aborted";
+} | {
+    kind: "retry";
+    errorMessage: string;
+} | {
+    kind: "overflow";
+} | {
+    kind: "failed";
+    errorMessage: string;
+};
+export interface RunCycleDeps {
+    core: SessionCore;
+    compaction: CompactionController;
+    retry(): RetrySettings;
+    syncSystem(): void;
+    stopRequested(): boolean;
+    setRetrying(value: boolean): void;
+    lastAssistantText(): string | null;
+}
+export declare function decideAfterRun(deps: RunCycleDeps, outcome: RunOutcome, retryAttempt: number, overflowRecovered: boolean): RunDecision;
+/** 用 context_edit 把失败尝试（助手消息与其后补的结果）从上下文剔除。 */
+export declare function excludeFailedAttempt(core: SessionCore, failed: AssistantMessage | undefined, reason: "retry" | "overflow"): void;
+export declare function recordAbort(core: SessionCore): void;
+export declare function runCycle(deps: RunCycleDeps, prompts: AgentMessage[], signal: AbortSignal): Promise<void>;
+export declare function makeUserMessage(text: string, images?: readonly ImageBlock[], origin?: string): UserMessage;
+/**
+ * 一次提示：展开（expandPrompt）→ UserPromptSubmit Hook（block 拒绝；updatedPrompt 替换；
+ * additionalContext 作为 custom_message 随提示进上下文）→ 阈值压缩检查 → system 同步 →
+ * `before_agent_start`（宿主事件同名，由组装根桥接）→ 会话周期。
+ */
+export declare function runPrompt(deps: RunCycleDeps, text: string, images: readonly ImageBlock[] | undefined, origin: string | undefined, signal: AbortSignal): Promise<PromptDisposition>;

package/dist/agent/session-run.js

@@ -0,0 +1,246 @@
+/**
+ * 会话级 run 编排（设计 §3.6 重试、§4.2 abort、§6.1 Stop Hook、§9 溢出恢复）。[B2]
+ *
+ * 一次「会话周期」（prompt 到 agent_settled）可以包含多个 Agent run：
+ * - 可重试错误：agent_end{willRetry:true} → 失败尝试 context_edit{reason:"retry"} 剔除 →
+ *   auto_retry_start → 退避（abort 可打断）→ 新 run（continue）；结束时 auto_retry_end。
+ * - 溢出 / length 无工具调用：agent_end{willRetry:true} → context_edit{reason:"overflow"} 剔除 →
+ *   PreCompact → 压缩 → 以新 run 重试**一次**；失败 / 取消则保留剔除、不重试，agent_settled{warning}。
+ * - abort：不清队列；落盘 custom_message{customType:"ama.aborted"}；不再自动续跑。
+ * - 将要停下时发 agent_before_settle 并跑 Stop（子 Agent 为 SubagentStop）Hook：block + reason →
+ *   以 reason 作为新 user 消息再跑一轮（上限 3 次，stopHookActive 传给 Hook）。
+ * - 最终失败后若 followUp 队列非空，照常投递。
+ */
+import { AmaError } from "../errors.js";
+import { classifyFailure, retryDelayMs, sleep } from "./retry.js";
+export const MAX_STOP_HOOK_CONTINUATIONS = 3;
+export const ABORTED_CUSTOM_TYPE = "ama.aborted";
+export function decideAfterRun(deps, outcome, retryAttempt, overflowRecovered) {
+    if (outcome.stopReason === "aborted")
+        return { kind: "aborted" };
+    const last = outcome.lastAssistant;
+    if (last === undefined)
+        return { kind: "done" };
+    const failedStop = last.stopReason === "error" || outcome.stopReason === "length";
+    if (!failedStop)
+        return { kind: "done" };
+    const errorMessage = last.errorMessage ?? (last.stopReason === "length" ? "output hit the token limit" : "error");
+    const classifyOptions = deps.core.options.isContextOverflow === undefined
+        ? {}
+        : { isContextOverflow: deps.core.options.isContextOverflow };
+    const kind = classifyFailure(last, classifyOptions);
+    if (kind === "overflow") {
+        const compaction = deps.compaction;
+        const recoverable = !overflowRecovered &&
+            compaction.settings.enabled &&
+            deps.core.model().contextWindow !== undefined &&
+            !compaction.breaker.tripped;
+        return recoverable ? { kind: "overflow" } : { kind: "failed", errorMessage };
+    }
+    const settings = deps.retry();
+    if (kind === "retryable" && settings.enabled && retryAttempt < settings.maxRetries) {
+        return { kind: "retry", errorMessage };
+    }
+    return { kind: "failed", errorMessage };
+}
+/** 用 context_edit 把失败尝试（助手消息与其后补的结果）从上下文剔除。 */
+export function excludeFailedAttempt(core, failed, reason) {
+    if (failed === undefined)
+        return;
+    const branch = core.manager.branch();
+    const at = branch.findIndex((entry) => entry.type === "message" && entry.message === failed);
+    if (at < 0)
+        return;
+    const targets = [branch[at]?.id];
+    for (const entry of branch.slice(at + 1)) {
+        if (entry.type === "message" && entry.message.role === "toolResult")
+            targets.push(entry.id);
+    }
+    for (const targetId of targets) {
+        if (targetId !== undefined) {
+            core.appendEntry({ type: "context_edit", targetId, replacement: null, reason });
+        }
+    }
+    core.reloadMessages();
+}
+export function recordAbort(core) {
+    core.appendEntry({
+        type: "custom_message",
+        customType: ABORTED_CUSTOM_TYPE,
+        content: "The user interrupted the previous response before it finished.",
+        display: false,
+    });
+    core.reloadMessages();
+}
+export async function runCycle(deps, prompts, signal) {
+    const { core, compaction } = deps;
+    let next = prompts;
+    let retryAttempt = 0;
+    let overflowRecovered = false;
+    let stopHooks = 0;
+    let warning;
+    let announced = false;
+    const endRetry = (success, finalError) => {
+        if (retryAttempt === 0)
+            return;
+        const event = {
+            type: "auto_retry_end",
+            success,
+            attempt: retryAttempt,
+        };
+        if (finalError !== undefined)
+            event.finalError = finalError;
+        core.emit(event);
+        deps.setRetrying(false);
+        retryAttempt = 0;
+    };
+    while (next !== undefined) {
+        announced = false;
+        let decision = { kind: "done" };
+        const outcome = await core.agent.run(next, {
+            signal,
+            onRunEnd: (result) => {
+                decision = decideAfterRun(deps, result, retryAttempt, overflowRecovered);
+                return decision.kind === "retry" || decision.kind === "overflow";
+            },
+        });
+        next = undefined;
+        const current = decision;
+        if (current.kind === "aborted" || signal.aborted) {
+            endRetry(false, "aborted");
+            recordAbort(core);
+            break;
+        }
+        if (current.kind === "retry") {
+            retryAttempt++;
+            deps.setRetrying(true);
+            excludeFailedAttempt(core, outcome.lastAssistant, "retry");
+            const settings = deps.retry();
+            const delayMs = retryDelayMs(retryAttempt, settings);
+            core.emit({
+                type: "auto_retry_start",
+                attempt: retryAttempt,
+                maxAttempts: settings.maxRetries,
+                delayMs,
+                errorMessage: current.errorMessage,
+            });
+            void core.runHook("Notification", {
+                notification: {
+                    kind: "retry",
+                    message: `retry ${retryAttempt}/${settings.maxRetries}: ${current.errorMessage}`,
+                },
+            });
+            try {
+                await sleep(delayMs, signal);
+            }
+            catch {
+                endRetry(false, "aborted");
+                recordAbort(core);
+                break;
+            }
+            next = [];
+            continue;
+        }
+        endRetry(current.kind === "done", current.kind === "failed" ? current.errorMessage : undefined);
+        if (current.kind === "overflow") {
+            overflowRecovered = true;
+            excludeFailedAttempt(core, outcome.lastAssistant, "overflow");
+            const recovery = await compaction.recoverOverflow(signal);
+            if (signal.aborted) {
+                recordAbort(core);
+                break;
+            }
+            if (recovery.retry) {
+                next = [];
+                continue;
+            }
+            warning = recovery.warning;
+        }
+        else if (current.kind === "failed") {
+            warning = current.errorMessage;
+            void core.runHook("Notification", {
+                notification: { kind: "error", message: current.errorMessage },
+            });
+        }
+        if (current.kind === "failed" && core.agent.followUpQueue.hasItems()) {
+            next = core.agent.followUpQueue.drain();
+            continue;
+        }
+        core.emit({ type: "agent_before_settle" });
+        announced = true;
+        if (current.kind === "done" &&
+            !deps.stopRequested() &&
+            stopHooks < MAX_STOP_HOOK_CONTINUATIONS) {
+            const event = core.depth > 0 ? "SubagentStop" : "Stop";
+            const lastText = deps.lastAssistantText();
+            const payload = lastText === null
+                ? { stopHookActive: stopHooks > 0 }
+                : { lastAssistantText: lastText, stopHookActive: stopHooks > 0 };
+            const hook = await core.runHook(event, payload, signal);
+            if (hook !== undefined && hook.decision === "block" && !hook.stop && !signal.aborted) {
+                stopHooks++;
+                next = [makeUserMessage(hook.reason ?? "Continue.", undefined, "hook")];
+                continue;
+            }
+        }
+    }
+    if (!announced)
+        core.emit({ type: "agent_before_settle" });
+    const settled = { type: "agent_settled" };
+    if (warning !== undefined)
+        settled.warning = warning;
+    core.emit(settled);
+    void core.runHook("Notification", {
+        notification: { kind: "settled", message: warning ?? "run finished" },
+    });
+}
+export function makeUserMessage(text, images, origin) {
+    const message = {
+        role: "user",
+        content: images !== undefined && images.length > 0 ? [{ type: "text", text }, ...images] : text,
+        timestamp: Date.now(),
+    };
+    if (origin !== undefined)
+        message.origin = origin;
+    return message;
+}
+/**
+ * 一次提示：展开（expandPrompt）→ UserPromptSubmit Hook（block 拒绝；updatedPrompt 替换；
+ * additionalContext 作为 custom_message 随提示进上下文）→ 阈值压缩检查 → system 同步 →
+ * `before_agent_start`（宿主事件同名，由组装根桥接）→ 会话周期。
+ */
+export async function runPrompt(deps, text, images, origin, signal) {
+    const { core } = deps;
+    let prompt = text;
+    if (core.options.expandPrompt !== undefined) {
+        const expanded = await core.options.expandPrompt(text);
+        if ("handled" in expanded)
+            return "handled";
+        prompt = expanded.text;
+    }
+    const hook = await core.runHook("UserPromptSubmit", { prompt }, signal);
+    if (hook !== undefined) {
+        if (hook.decision === "block" || hook.decision === "deny" || hook.stop) {
+            throw new AmaError("prompt_blocked", hook.reason ?? "prompt blocked by UserPromptSubmit hook");
+        }
+        if (hook.updatedPrompt !== undefined)
+            prompt = hook.updatedPrompt;
+    }
+    const prompts = [makeUserMessage(prompt, images, origin)];
+    if (hook?.additionalContext !== undefined && hook.additionalContext !== "") {
+        prompts.push({
+            role: "custom",
+            customType: "ama.hook_context",
+            content: hook.additionalContext,
+            display: false,
+            timestamp: Date.now(),
+        });
+    }
+    await deps.compaction.checkThreshold(signal);
+    if (signal.aborted)
+        return "handled";
+    deps.syncSystem();
+    core.emit({ type: "before_agent_start", prompt });
+    await runCycle(deps, prompts, signal);
+    return "started";
+}