@x-otto/agent 0.0.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,1625 @@
+import * as _$_x_otto_shared0 from "@x-otto/shared";
+import { AgentError, Logger, TypedEventEmitter } from "@x-otto/shared";
+import { AssistantMessage, Message, Model, StreamEvent, SystemNotificationMessage, ThinkingLevel, ToolCall, ToolResultMessage, Usage, extractToolResultText } from "@x-otto/interchange";
+import { CacheRetention, StreamFunction } from "@x-otto/provider";
+import { AgentMessage, AgentMessage as AgentMessage$1, AgentSessionEvent, AgentSessionEventMap, AgentSessionEventType, AgentSessionSubscriber, AgentTool, AgentTool as AgentTool$1, ApprovalRisk, ApprovalRisk as ApprovalRisk$1, AskUserQuestion, CustomAgentMessages, GrillAnswer, GrillOption, GrillQuestion, GrillRequest, HookInput, HookOutput, InterceptorTiming, ObserverTiming, ToolCallContext, ToolCallEvent, ToolCallEvent as ToolCallEvent$1, ToolResult, ToolResult as ToolResult$1 } from "@x-otto/hook-contracts";
+
+//#region src/engine-nodes.d.ts
+type EngineNodeCategory = 'agent_work_loop' | 'work_loop_injection' | 'tool_executor' | 'session_prompt_lifecycle' | 'lifecycle_hook' | 'turn_observable';
+interface EngineNodeDef {
+  readonly id: string;
+  readonly category: EngineNodeCategory;
+  readonly label: string;
+  readonly pausable?: boolean;
+  readonly hook?: 'interceptor' | 'observer';
+  readonly observable?: boolean;
+  readonly traceable?: boolean;
+}
+declare const ENGINE_NODES: readonly [{
+  readonly id: "loop.start";
+  readonly category: "agent_work_loop";
+  readonly label: "Loop Start";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "model.before";
+  readonly category: "agent_work_loop";
+  readonly label: "Model Before";
+  readonly pausable: true;
+}, {
+  readonly id: "model.after";
+  readonly category: "agent_work_loop";
+  readonly label: "Model After";
+  readonly pausable: true;
+}, {
+  readonly id: "tool.before";
+  readonly category: "agent_work_loop";
+  readonly label: "Tool Before";
+  readonly pausable: true;
+}, {
+  readonly id: "tool.after";
+  readonly category: "agent_work_loop";
+  readonly label: "Tool After";
+  readonly pausable: true;
+}, {
+  readonly id: "loop.end";
+  readonly category: "agent_work_loop";
+  readonly label: "Loop End";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "loop.cleanup";
+  readonly category: "agent_work_loop";
+  readonly label: "Loop Cleanup";
+  readonly pausable: true;
+}, {
+  readonly id: "agent.aborted";
+  readonly category: "agent_work_loop";
+  readonly label: "Agent Aborted";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "agent.error";
+  readonly category: "agent_work_loop";
+  readonly label: "Agent Error";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "agent.done";
+  readonly category: "agent_work_loop";
+  readonly label: "Agent Done";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "steering.check";
+  readonly category: "work_loop_injection";
+  readonly label: "Steering Check";
+  readonly pausable: true;
+}, {
+  readonly id: "follow.up.check";
+  readonly category: "work_loop_injection";
+  readonly label: "Follow Up Check";
+  readonly pausable: true;
+}, {
+  readonly id: "context.transform";
+  readonly category: "work_loop_injection";
+  readonly label: "Context Transform";
+  readonly pausable: true;
+}, {
+  readonly id: "tool.resolve";
+  readonly category: "tool_executor";
+  readonly label: "Tool Resolve";
+  readonly pausable: true;
+}, {
+  readonly id: "tool.validate";
+  readonly category: "tool_executor";
+  readonly label: "Tool Validate";
+  readonly pausable: true;
+}, {
+  readonly id: "tool.hook.before";
+  readonly category: "tool_executor";
+  readonly label: "Tool Hook Before";
+  readonly pausable: true;
+}, {
+  readonly id: "tool.hook.after";
+  readonly category: "tool_executor";
+  readonly label: "Tool Hook After";
+  readonly pausable: true;
+}, {
+  readonly id: "prompt.before";
+  readonly category: "session_prompt_lifecycle";
+  readonly label: "Prompt Before";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "prompt.after";
+  readonly category: "session_prompt_lifecycle";
+  readonly label: "Prompt After";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "context.build";
+  readonly category: "session_prompt_lifecycle";
+  readonly label: "Context Build";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "messages.persist";
+  readonly category: "session_prompt_lifecycle";
+  readonly label: "Messages Persist";
+  readonly pausable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "memory.prune";
+  readonly category: "work_loop_injection";
+  readonly label: "Memory Prune";
+  readonly traceable: true;
+}, {
+  readonly id: "memory.archive";
+  readonly category: "session_prompt_lifecycle";
+  readonly label: "Memory Archive";
+  readonly traceable: true;
+}, {
+  readonly id: "chat.message.before";
+  readonly category: "lifecycle_hook";
+  readonly label: "Chat Message Before";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "chat.message.after";
+  readonly category: "lifecycle_hook";
+  readonly label: "Chat Message After";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "chat.params";
+  readonly category: "lifecycle_hook";
+  readonly label: "Chat Params";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "system.prompt.transform";
+  readonly category: "lifecycle_hook";
+  readonly label: "System Prompt Transform";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "messages.transform";
+  readonly category: "lifecycle_hook";
+  readonly label: "Messages Transform";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "tool.execute.before";
+  readonly category: "lifecycle_hook";
+  readonly label: "Tool Execute Before";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "tool.execute.after";
+  readonly category: "lifecycle_hook";
+  readonly label: "Tool Execute After";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "memory.prune.before";
+  readonly category: "lifecycle_hook";
+  readonly label: "Memory Prune Before";
+  readonly hook: "interceptor";
+}, {
+  readonly id: "session.idle";
+  readonly category: "lifecycle_hook";
+  readonly label: "Session Idle";
+  readonly hook: "observer";
+}, {
+  readonly id: "session.error";
+  readonly category: "lifecycle_hook";
+  readonly label: "Session Error";
+  readonly hook: "observer";
+}, {
+  readonly id: "status.change";
+  readonly category: "turn_observable";
+  readonly label: "Status Change";
+  readonly observable: true;
+}, {
+  readonly id: "turn.start";
+  readonly category: "turn_observable";
+  readonly label: "Turn Start";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "turn.end";
+  readonly category: "turn_observable";
+  readonly label: "Turn End";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "stream.event";
+  readonly category: "turn_observable";
+  readonly label: "Stream Event";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "tool.call.start";
+  readonly category: "turn_observable";
+  readonly label: "Tool Call Start";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "tool.call.end";
+  readonly category: "turn_observable";
+  readonly label: "Tool Call End";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "steering.injected";
+  readonly category: "turn_observable";
+  readonly label: "Steering Injected";
+  readonly observable: true;
+}, {
+  readonly id: "follow.up.start";
+  readonly category: "turn_observable";
+  readonly label: "Follow Up Start";
+  readonly observable: true;
+}, {
+  readonly id: "max.turns";
+  readonly category: "turn_observable";
+  readonly label: "Max Tool Turns Reached";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "progress.stall";
+  readonly category: "turn_observable";
+  readonly label: "Progress Stall Detected";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "tool.call.mismatch";
+  readonly category: "turn_observable";
+  readonly label: "Tool Call Protocol Mismatch";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "prompt.budget";
+  readonly category: "turn_observable";
+  readonly label: "Prompt Budget Exceeded";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "compaction.reactive";
+  readonly category: "turn_observable";
+  readonly label: "Reactive Compaction";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "image.cap";
+  readonly category: "turn_observable";
+  readonly label: "Image Cap";
+  readonly traceable: true;
+}, {
+  readonly id: "image.vision-gate";
+  readonly category: "turn_observable";
+  readonly label: "Vision Capability Gate";
+  readonly traceable: true;
+}, {
+  readonly id: "image.vision-delegate";
+  readonly category: "turn_observable";
+  readonly label: "Vision Delegation Result";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "image.degradation";
+  readonly category: "turn_observable";
+  readonly label: "Image Degradation";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "process.memory.sample";
+  readonly category: "turn_observable";
+  readonly label: "Process Memory Sample";
+  readonly traceable: true;
+}, {
+  readonly id: "stream.retry";
+  readonly category: "turn_observable";
+  readonly label: "Stream Retry";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "stream.retry.accelerated";
+  readonly category: "turn_observable";
+  readonly label: "Stream Retry Accelerated";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "turn.truncated";
+  readonly category: "turn_observable";
+  readonly label: "Turn Truncated";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "rate.limit.exhausted";
+  readonly category: "turn_observable";
+  readonly label: "Rate Limit Exhausted";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "stream.auth-failed";
+  readonly category: "turn_observable";
+  readonly label: "Stream Auth Failed";
+  readonly observable: true;
+  readonly traceable: true;
+}, {
+  readonly id: "error";
+  readonly category: "turn_observable";
+  readonly label: "Error";
+  readonly observable: true;
+}, {
+  readonly id: "abort";
+  readonly category: "turn_observable";
+  readonly label: "Abort";
+  readonly observable: true;
+}, {
+  readonly id: "lifecycle.tool.completed";
+  readonly category: "turn_observable";
+  readonly label: "Lifecycle Tool Completed";
+  readonly observable: true;
+}, {
+  readonly id: "lifecycle.tool.completed.crossBoundary";
+  readonly category: "turn_observable";
+  readonly label: "Lifecycle Tool Completed (Cross Prompt Boundary)";
+  readonly observable: true;
+}];
+type EngineNode = (typeof ENGINE_NODES)[number];
+type PausableNode = Extract<EngineNode, {
+  pausable: true;
+}>;
+type ObservableNode = Extract<EngineNode, {
+  observable: true;
+}>;
+type TraceableNode = Extract<EngineNode, {
+  traceable: true;
+}>;
+type LifecycleHookNode = Extract<EngineNode, {
+  hook: 'interceptor' | 'observer';
+}>;
+type BreakpointPoint = PausableNode['id'];
+type ObservableNodeId = ObservableNode['id'];
+type TraceableNodeId = TraceableNode['id'];
+type LifecycleTiming = LifecycleHookNode['id'];
+declare function nodesWithCapability(cap: 'pausable' | 'hook' | 'observable' | 'traceable'): readonly EngineNodeDef[];
+declare const ENGINE_LIFECYCLE_TIMINGS: readonly LifecycleTiming[];
+declare const OBSERVABLE_NODE_IDS: readonly ObservableNodeId[];
+declare const TRACEABLE_NODE_IDS: readonly TraceableNodeId[];
+type BreakpointCategory = PausableNode['category'] | 'custom';
+interface BreakpointDefinition {
+  point: BreakpointPoint;
+  name: string;
+  category: BreakpointCategory;
+}
+declare const BREAKPOINT_POINTS: readonly BreakpointDefinition[];
+declare const ENGINE_DEFAULTS: {
+  /** 工具轮次预算缺省（单源）。触顶后按 maxToolTurnExtensions 决定是否压缩续跑。
+   * agent 核心 + runtime RUNTIME_DEFAULTS 均引用此处，消除散落的硬编码 `?? 120`。 */
+  readonly maxToolTurns: 120; /** tool.call.end trace 的 ToolResult 内容截断阈值（字符数）。默认 512。 */
+  readonly traceResultMaxChars: 512;
+  /** R7：单条工具结果进模型上下文的字符上限（默认 ~100k≈25k token）。超出头尾保留+中段省略，
+   * 防全仓 grep 等病态巨型结果撑爆 context window。仅截极端值，正常 read/edit 不受影响。 */
+  readonly maxToolResultChars: 100000;
+  /**
+   * RFC-340 M3 D5-2：单条工具结果的**保底**字符份额。
+   *
+   * per-prompt 额度耗尽后，后续工具结果的有效预算不再递减到低于此值——否则模型会收到
+   * 一堆只剩省略号的结果，比给一个头尾可辨的截断版更难判断刚才发生了什么。配合 clamp
+   * 既有的头 70%/尾 30% 保留策略，2000 字符足以看清结果的开头与结尾。
+   */
+  readonly minToolResultChars: 2000;
+  /**
+   * RFC-340 M3 D5-4：单个 prompt 内所有工具结果可占用的上下文比例。
+   *
+   * 缺口背景：`maxToolResultChars` 是 **per-tool** 固定值，不跨工具累计——20 个工具各
+   * 返回 99K 字符全部合法通过，但合计足以撑爆窗口，只能靠 `hardCeiling` 触发压缩事后
+   * 补救（= 用丢对话历史偿还工具输出超发，代价错配）。本比例给出 per-prompt 总闸。
+   *
+   * 取窗口的一半：留另一半给系统前缀 + 对话历史 + 模型输出。按窗口派生而非魔数，
+   * 小窗口模型自动收紧，无需逐模型调参。
+   */
+  readonly promptToolResultFraction: 0.5;
+  /** 单 turn 内可并行工具（readonly 或 isConcurrencySafe）的并发上限。
+   * 对齐 CC 的 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 默认 10——防一轮几十个委托/读取压垮资源。 */
+  readonly maxToolConcurrency: 10;
+  /** RFC-104 D1：进展闸门的签名多样性阈值——纯读窗口 distinct 签名占比 ≥ 此值判「有进展」。
+   * 0.5 保守起步（同一调用反复 → ratio→0 → 循环嫌疑；研究型多样 grep → ratio→1）。 */
+  readonly progressDistinctRatio: 0.5; /** RFC-104 D1：进展窗口签名 Map 上限；溢出只计 totalCalls（ratio 退化方向=更宽松，不误杀）。 */
+  readonly progressSignatureCap: 512;
+  /** RFC-104 D1：签名对 args stringify 的截断长度（大 args 如 write 全文件内容只 hash 头部；
+   * 截断只影响签名精度且方向是「更易判相同」=更严格，不影响语义）。 */
+  readonly progressSignatureArgsMaxChars: 1024; /** RFC-203 D1：早期停滞检测的滑动窗口大小（turn 数）——窗口未满恒不判停。 */
+  readonly stallWindowTurns: 8;
+  /** RFC-203 D1（评审 H3）：同一工具调用签名在窗口内重复 ≥ 此值且零写成功 → 判停滞。
+   * 不用 distinctRatio（会误伤"反复 read 同几个文件各 2-3 次"的合法审查），maxRepeat
+   * 只命中"同一件事反复做 N 次以上"的真打转。 */
+  readonly stallRepeatThreshold: 4;
+};
+//#endregion
+//#region src/ports.d.ts
+interface ClockPort {
+  now(): number;
+}
+interface RandomPort {
+  random(): number;
+}
+interface IdPort {
+  uuid(): string;
+}
+interface DeterminismPorts {
+  clock: ClockPort;
+  random: RandomPort;
+  id: IdPort;
+}
+/**
+ * RFC-093：工具结果溢出落盘端口。宿主（runtime AgentSession）注入实现（闭包捕获 sessionId），
+ * agent 包零存储依赖——与 approval 回调注入同型。
+ * 返回磁盘路径（占位符引用）；undefined = 未配置/写盘失败 → 调用方 fail-open 回退截断。
+ */
+interface SpillPort {
+  (toolCallId: string, text: string): Promise<string | undefined>;
+}
+declare const systemClock: ClockPort;
+declare const systemRandom: RandomPort;
+declare const systemId: IdPort;
+//#endregion
+//#region src/trace.d.ts
+type TraceEventKind = 'lifecycle' | 'stream' | 'tool' | 'nondet' | 'checkpoint';
+interface TraceEvent {
+  ts: number;
+  sessionId: string;
+  turn?: number;
+  kind: TraceEventKind;
+  /** 存档/回放事件保留 `string`——历史 trace 与跨版本节点名须容忍读取（生产侧由 Draft 编译期约束）。 */
+  node?: string;
+  payload?: unknown;
+  parentEventId?: string;
+  causalChain?: string[];
+  evalRunId?: string;
+}
+interface TraceEventDraft {
+  kind: TraceEventKind;
+  /** 生产侧 trace 锚点编译期绑回 ENGINE_NODES（traceable 子集）——拼错/未登记即编译错，取代正则扫描守。 */
+  node?: TraceableNodeId;
+  turn?: number;
+  payload?: unknown;
+  parentEventId?: string;
+  causalChain?: string[];
+  evalRunId?: string;
+}
+interface TraceRecorder {
+  record(draft: TraceEventDraft): void;
+}
+interface TraceSink {
+  append(event: TraceEvent): void | Promise<void>;
+}
+interface NondetDraw {
+  source: 'clock' | 'random' | 'uuid';
+  value: number | string;
+}
+interface TraceRecorderOptions {
+  sink: TraceSink;
+  sessionId: string;
+  clock?: ClockPort;
+  onError?: (error: unknown) => void;
+}
+declare function createTraceRecorder(options: TraceRecorderOptions): TraceRecorder;
+declare const noopRecorder: TraceRecorder;
+declare function shouldPersistStreamEvent(type: string): boolean;
+interface StreamTracePersister {
+  /** 喂入一个 stream 事件（按到达序）；内部按白名单过滤 + 滞后一拍剥离 partial。 */
+  push(payload: {
+    type?: string;
+  } & Record<string, unknown>, turn?: number): void;
+  /**
+   * 段结束冲洗（abort/流式错误/循环退出时调用；幂等）。
+   * 若缓存中还有未落盘的 `*_end`（= 段内无 done 到达），**保留 partial** 写出——
+   * replay 对无 done 段 fallback 到最后事件的 partial（replay.ts），无条件剥离会把
+   * abort 段回放从「降级」变「完全失败」（RFC-102 D2，真实 trace 8/1306 段无 done）。
+   */
+  flush(): void;
+}
+/**
+ * RFC-102 D1+D2：stream 事件的 trace 持久化器。
+ * 白名单过滤 delta；`*_end` 缓存一拍——下一事件到达说明段还在继续（其 partial 已被
+ * 后续事件覆盖，安全剥离）；段边界（flush）到达则保留 partial（abort 保护）。
+ */
+declare function createStreamTracePersister(recorder: TraceRecorder): StreamTracePersister;
+/**
+ * RFC-145 D3：录制端口 + nondet 批量冲洗。draw 不再逐条落盘（每条即一次 trace append，
+ * 实测占 trace 行数 36%、行数第一——RFC-102 白名单只治理 stream 类，nondet 是其盲区），
+ * 改为进程内累积、由宿主在回合边界与 work-loop 退出路径调用 `flushNondetBatch()`
+ * 落成单条 batch 事件 `{ kind:'nondet', payload:{ draws: NondetDraw[] } }`。
+ *
+ * batch 事件不设 node 字段——与既有逐条 nondet 记录一致（TraceEventDraft.node 是
+ * TraceableNodeId 编译期联合，nondet 类事件从不设 node）；消费侧以
+ * `Array.isArray(payload.draws)` 区分 batch 与旧逐条形态（extractNondetDraws 双形态兼容）。
+ *
+ * 崩溃语义（RFC-145 D3 显式承认）：崩溃时当前回合未 flush 的 draws 丢失 → 该回合重放
+ * underrun。可接受降级——重放以回合为单元消费（done.message 为终态权威），与 RFC-102 D2
+ * 的 abort 段降级语义一致。
+ */
+interface RecordingPorts extends DeterminismPorts {
+  /** 把累积的 nondet draws 落成单条 batch 事件并清空（空累积时 no-op，幂等）。 */
+  flushNondetBatch(): void;
+}
+declare function createRecordingPorts(base: DeterminismPorts, recorder: TraceRecorder): RecordingPorts;
+declare function createReplayPorts(draws: readonly NondetDraw[]): DeterminismPorts;
+/**
+ * RFC-145 D3 双形态兼容：同时接受旧的逐条 NondetDraw（存量 trace）与新的 batch
+ * `{draws: NondetDraw[]}`（展开，内部顺序 = 录制顺序）。旧形态兼容在存量 trace
+ * 存在期内不许移除（RFC-145 §5 规则 3）。
+ */
+declare function extractNondetDraws(events: Iterable<TraceEvent>): NondetDraw[];
+//#endregion
+//#region src/debug-port.d.ts
+interface MessageSummaryItem {
+  index: number;
+  role: 'user' | 'assistant' | 'tool_result' | 'system';
+  preview: string;
+  toolName?: string;
+  tokenEstimate?: number;
+}
+interface DebugSnapshot {
+  turn: number;
+  point: BreakpointPoint;
+  frameDepth: number;
+  messagesCount: number;
+  lastToolName?: string;
+  tokenUsage?: {
+    input: number;
+    output: number;
+  };
+  metadata?: Record<string, string | number | boolean | null>;
+  systemPrompt?: string;
+  messagesSummary?: MessageSummaryItem[];
+  llmParams?: {
+    temperature?: number;
+    maxTokens?: number;
+    thinkingLevel?: string;
+  };
+}
+interface InjectedMessage {
+  role: 'user' | 'system';
+  content: string;
+}
+interface PauseResumePayload {
+  systemPrompt?: string;
+  injectMessages?: InjectedMessage[];
+  removeMessageIndices?: number[];
+  llmParams?: {
+    temperature?: number;
+    maxTokens?: number;
+    thinkingLevel?: string;
+  };
+  metadata?: Record<string, string | number | boolean | null>;
+}
+type DebugCommand = {
+  type: 'next';
+  seq: number;
+} | {
+  type: 'step';
+  seq: number;
+} | {
+  type: 'over';
+  seq: number;
+  depth: number;
+} | {
+  type: 'continue';
+  seq: number;
+} | {
+  type: 'stop';
+  seq: number;
+  reason?: string;
+};
+interface PauseResult {
+  pauseId: string;
+  command: DebugCommand;
+  payload: PauseResumePayload | null;
+}
+interface DebugPort {
+  pause(snapshot: DebugSnapshot): Promise<PauseResult | undefined>;
+}
+declare function summarizeMessages(messages: readonly AgentMessage[], lastN: number): MessageSummaryItem[];
+interface PauseApplyTarget {
+  messages?: AgentMessage[];
+  setSystemPrompt?: (value: string) => void;
+  setTemperature?: (value: number) => void;
+  setMaxTokens?: (value: number) => void;
+  setThinkingLevel?: (value: string) => void;
+  now?: () => number;
+}
+declare function consumePause(result: PauseResult | undefined, target?: PauseApplyTarget): void;
+//#endregion
+//#region src/tool-executor.d.ts
+interface ToolExecutor {
+  execute(toolCall: ToolCall, signal: AbortSignal): Promise<ToolResult>;
+  list(): AgentTool[];
+}
+interface ToolExecutorOptions {
+  tools: AgentTool[];
+  hookExecutor?: ToolHookExecutor;
+  agentName?: string;
+  sessionId?: string;
+  debug?: DebugPort;
+  approval?: (toolName: string, args: Record<string, unknown>, reason: string, risk?: ApprovalRisk) => Promise<boolean>;
+  clock?: ClockPort;
+  depth?: number;
+}
+declare function createToolExecutor(tools: AgentTool[], options?: Omit<ToolExecutorOptions, 'tools'>): ToolExecutor;
+//#endregion
+//#region src/vision-gate.d.ts
+/**
+ * 图像委托描述端口（RFC-181 D3）。宿主（coding 包 VisionDelegateService）实现，
+ * 引擎侧只消费返回值——不感知模型选择、prompt、缓存。返回值与入参一一对应；
+ * `null` 表示该图描述失败（单图失败不连坐，其余图正常处理）。
+ *
+ * 约定：返回的非 null 字符串是**最终注入文本**（宿主已按 RFC-181 D2 格式拼好
+ * `[image seen by vision model <id>]\n<描述>` 前缀），引擎侧原样使用，不做二次
+ * 格式化——保持"agent 包零模型路由知识"（RFC-181 §4 规则 5）。
+ */
+type DescribeImagesPort = (images: Array<{
+  mime: string;
+  source: string;
+  contextHint?: string;
+}>, signal?: AbortSignal) => Promise<Array<string | null>>;
+interface VisionGateResult {
+  messages: AgentMessage[];
+  /** 因能力错配被处理的 image block 总数（含委托成功与占位两类）。 */
+  gatedCount: number;
+  /** 其中委托成功、替换为描述文本的数量。 */
+  describedCount: number;
+}
+/**
+ * 视觉能力门控投影。`model` 支持图像输入时直通（引用原样返回，零开销）；
+ * 不支持时收集全部 image block（不分新旧、不设边界——模型对任何图像都不可见），
+ * 尝试委托描述，按结果逐块替换。
+ */
+declare function applyVisionGate(messages: AgentMessage[], model: Pick<Model, 'input'>, describeImages?: DescribeImagesPort, signal?: AbortSignal): Promise<VisionGateResult>;
+//#endregion
+//#region src/work-loop-stream-error.d.ts
+interface StreamRetryConfig {
+  maxRetries: number;
+  initialDelayMs: number;
+  backoffFactor: number;
+  maxDelayMs: number;
+}
+//#endregion
+//#region src/types.d.ts
+type AgentStatus = 'idle' | 'streaming' | 'tool_executing' | 'completed' | 'error' | 'aborted' | 'archived';
+type AgentEvent = {
+  type: 'status.change';
+  from: AgentStatus;
+  to: AgentStatus;
+}
+/** toolTurnCount/maxToolTurns：当前工具轮次预算窗口的已用/上限（供宿主渲染 x/y 提示）。
+ *  promptOutputTokens/promptOutputTokenBudget（RFC-104 D3/D5）：本 prompt 累计输出 token
+ *  与预算（未配置预算时 budget 为 undefined，前端隐藏 n/N tok）。 */
+| {
+  type: 'turn.start';
+  turnIndex: number;
+  toolTurnCount: number;
+  maxToolTurns: number;
+  promptOutputTokens: number;
+  promptOutputTokenBudget?: number;
+} | {
+  type: 'turn.end';
+  turnIndex: number;
+  message: AssistantMessage;
+} | {
+  type: 'stream.event';
+  event: StreamEvent;
+} | {
+  type: 'tool.call.start';
+  toolCall: ToolCallEvent$1;
+}
+/**
+ * `contextChars`：本次工具结果**经 clamp/spill 后真正进入模型上下文**的文本字符数
+ * （`clampWithSpill` 产物，非原始 `result`）。宿主用它做上下文占用的实时估算——
+ * 原始 `result` 可能远大于入模内容（100k 字符上限 + spill 落盘只留 preview），
+ * 用原始长度估算会系统性高估，导致状态栏占用条在回合结算时明显回落。
+ */
+| {
+  type: 'tool.call.end';
+  toolCall: ToolCallEvent$1;
+  result: ToolResult$1;
+  contextChars?: number;
+} | {
+  type: 'steering.injected';
+  messages: AgentMessage$1[];
+} | {
+  type: 'follow.up.start';
+  messages: AgentMessage$1[];
+} /** progressDenied（RFC-104 D1）：还有扩展额度但窗口无进展被闸门拒绝（循环嫌疑），区别于额度耗尽。 */ | {
+  type: 'max.turns';
+  turnIndex: number;
+  maxTurns: number;
+  extended: boolean;
+  steered?: boolean;
+  progressDenied?: boolean;
+} /** RFC-104 D3：per-prompt token/时间预算超额（steered=true 收尾轮已注入；false 即将硬停）。 */ | {
+  type: 'prompt.budget';
+  turnIndex: number;
+  dimension: 'tokens' | 'time';
+  used: number;
+  budget: number;
+  steered: boolean;
+} /** RFC-203 D2：滑动窗口停滞检出（零写成功 + 同签名反复 ≥ 阈值）；软引导已注入，每 prompt 至多一次。 */ | {
+  type: 'progress.stall';
+  turnIndex: number;
+  windowTurns: number;
+  maxRepeat: number;
+} | {
+  type: 'tool.call.mismatch';
+  turnIndex: number;
+  outcome: 'retry' | 'terminate';
+  retryCount: number;
+} | {
+  type: 'compaction.reactive';
+  turnIndex: number;
+  messagesBefore: number;
+  messagesAfter: number;
+} | {
+  type: 'image.degradation';
+  turnIndex: number;
+  degradedCount: number;
+  trigger: 'context-overflow' | 'image-constraint';
+}
+/**
+ * RFC-181 D6/M3：视觉委托结果（仅在 describeImages 端口被实际调用时触发）——
+ * 供宿主（AgentSession→TUI）渲染"N 张图已由 vision 模型代述"提示。
+ */
+| {
+  type: 'image.vision-delegate';
+  turnIndex: number;
+  attemptedCount: number;
+  describedCount: number;
+  failedCount: number;
+} | {
+  type: 'stream.retry';
+  turnIndex: number;
+  attempt: number;
+  maxRetries: number;
+  delayMs: number;
+  reason: string;
+} | {
+  type: 'stream.retry.accelerated';
+  turnIndex: number;
+  attempt: number;
+  maxRetries: number;
+} | {
+  type: 'turn.truncated';
+  turnIndex: number;
+  action: 'escalate' | 'continue' | 'refusal';
+  maxTokens?: number;
+} | {
+  type: 'rate.limit.exhausted';
+  limitType?: 'five_hour' | 'seven_day' | 'seven_day_opus' | 'seven_day_sonnet' | 'seven_day_overage_included';
+  resetsAt?: number;
+  message: string;
+}
+/**
+ * 鉴权失败（fatal 分类下的认证子类，见 isAuthError）——本地无凭据或服务端 401 拒绝。
+ * 此前该场景在 handleStreamError 直接 rethrow，无任何记录（既不 emit 也不 record），
+ * 用户看到 TUI 弹窗后无法回溯"什么时候、哪个 provider/model 失效、失效了几次"。
+ * modelId/provider 取自 WorkLoopContext.model，供事后按模型/provider 聚合统计。
+ */
+| {
+  type: 'stream.auth-failed';
+  turnIndex: number;
+  provider: string;
+  modelId: string;
+  reason: string; /** RFC-139 D3：机器可读失效根因（credential-missing / refresh-failed / server-rejected）。 */
+  errorType: string;
+}
+/**
+ * RFC-144 M2：lifecycleAsync 工具真正完成（成功或失败）——`notifyToolCompletion()`
+ * 已完成 consume-once 标记，本事件携带完整 `result`，供宿主（TUI 后台面板）感知工具
+ * 完成、审计溯源。**不是**落库触发点——真正的落库（`messages.push`）由
+ * `work-loop.ts` 的 `runTools()` 直接完成（它持有 `messages` 数组引用），与本事件
+ * 的 emit 是并列关系而非因果关系。不用于 auto-trigger（那是 M3 的 workLoop
+ * `post-runTools yield` + 外层循环 `waitForPendingLifecycleTools()`，本事件只是
+ * 旁路通知）。
+ */
+| {
+  type: 'lifecycle.tool.completed';
+  toolCallId: string;
+  toolName: string;
+  isError: boolean;
+  result: ToolResult$1;
+}
+/**
+ * RFC-144 M4：lifecycleAsync 工具跨越 prompt 边界后完成——**叠加**于上面的
+ * `lifecycle.tool.completed`（非互斥）：`lifecycle.tool.completed` 是无条件的通用
+ * 审计/旁路通知（consume-once 消费成功即触发，不关心是否跨边界）；本事件是额外的、
+ * 专供宿主（CLI/TUI）做路由决策的信号——只在跨边界时才会紧跟着触发第二次 emit
+ * （见 work-loop.ts `notifyCompletion()` 的 `crossedPromptBoundary` 判定）。
+ *
+ * 工具启动时所属的 prompt（`run()` 调用）已经结束，一个新的 prompt 已经开始，完成
+ * 通知不会注入新 prompt 的 LLM 对话历史（避免污染当前无关任务的上下文）——这是本
+ * 事件真正影响的行为：`messages.push(SystemNotificationMessage)` 被跳过。宿主可
+ * 订阅本事件决定如何呈现给用户（如 toast，具体接线归后续项，不阻塞本事件类型的
+ * 落地）。
+ */
+| {
+  type: 'lifecycle.tool.completed.crossBoundary';
+  toolCallId: string;
+  toolName: string;
+  result: ToolResult$1;
+} | {
+  type: 'error';
+  error: Error;
+} | {
+  type: 'abort';
+};
+type AgentEventType = AgentEvent['type'];
+type AgentEventOf<T extends AgentEventType> = Extract<AgentEvent, {
+  type: T;
+}>;
+type AgentEventPayload<T extends AgentEventType> = Omit<AgentEventOf<T>, 'type'>;
+type AgentEvents = { [K in AgentEventType]: keyof AgentEventPayload<K> extends never ? () => void : (payload: AgentEventPayload<K>) => void } & _$_x_otto_shared0.Events;
+interface AgentState {
+  status: AgentStatus;
+  turnCount: number;
+  tokenUsage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+  };
+  isStreaming: boolean;
+  currentStreamMessage: AssistantMessage | null;
+  error?: Error;
+}
+interface PendingLifecycleTool {
+  toolCallId: string;
+  toolName: string;
+  promise: Promise<void>;
+  promptSeq: number;
+  consumed: boolean;
+  /**
+   * RFC-144 M4：per-tool 取消句柄——独立于 workLoop 级别的 AbortController（那个只在
+   * 用户主动 abort 当前 prompt 或整个 run() 结束时才会触发，不会因为"新 prompt 开始了"
+   * 而自动 abort）。工具启动时（`runTools()`）创建，与 loop-level signal 用
+   * `AbortSignal.any()` 组合后一起传给 `toolExecutor.execute()`——工具会同时响应
+   * "当前 prompt 被中断"与"这个具体的 lifecycleAsync 调用被跨边界取消"两种信号。
+   *
+   * `Agent.run()` 每次递增 `promptSeq` 前，会扫描所有未消费、且 `promptSeq` 落后于
+   * 新序号的 pending 条目，逐个调用本字段的 `abort()`——底层 `packages/tools/src/shell/
+   * process.ts` 的 `spawn()` 已经实现 SIGTERM + grace + SIGKILL（监听 signal 的
+   * 'abort' 事件），无需在 Agent 层重复实现进程终止细节，只需正确传播取消意图。
+   */
+  abortController: AbortController;
+}
+type ToolBeforeOutcome = {
+  kind: 'proceed';
+  args: Record<string, unknown>;
+} | {
+  kind: 'ask';
+  args: Record<string, unknown>;
+  reason: string;
+  risk?: ApprovalRisk$1;
+} | {
+  kind: 'deny';
+  reason: string;
+};
+interface ToolHookExecutor {
+  executeBeforeHooks(input: {
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    agentName: string;
+    sessionId: string;
+    paths?: readonly string[]; /** R1：工具是否只读——sandbox-guard 据此跳过只读工具的写评估。 */
+    readonly?: boolean;
+  }): Promise<ToolBeforeOutcome>;
+  executeAfterHooks(input: {
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    result: ToolResult$1;
+    agentName: string;
+    sessionId: string;
+    durationMs: number; /** R1：工具是否只读——after-hook 据此识别会改文件的工具，取代硬编码工具名集。 */
+    readonly?: boolean;
+  }): Promise<{
+    result: ToolResult$1;
+    metadata: Record<string, unknown>;
+  }>;
+}
+interface AgentConfig {
+  stream: StreamFunction;
+  logger: Logger;
+  maxToolTurns?: number;
+  maxToolTurnExtensions?: number;
+  /** RFC-104 D3：per-prompt 累计 output-token 预算（CC 口径）。配置后轮次上限自动 ×4 放宽（安全阀退位）。 */
+  promptOutputTokenBudget?: number;
+  /** RFC-104 D3：per-prompt 累计墙钟时间预算（ms）。 */
+  promptWallClockBudgetMs?: number;
+  /**
+   * RFC-050 D5（默认关 opt-in）：工具预算耗尽时，先注入收尾 steering 让模型用一轮优雅收尾
+   * （budget-limit 收尾提示），而非直接抛 MaxToolTurnsError。收尾轮仍调工具才硬停。
+   */
+  budgetSteerWrapUp?: boolean;
+  /**
+   * RFC-203：早期停滞检测配置（触顶前的滑动窗口打转发现）。缺省启用（走 ENGINE_DEFAULTS）；
+   * `false` 显式关闭。RFC-204 D4 修复：此前本字段只存在于 LoopBudget（work-loop 参数），
+   * AgentConfig 从未声明，agent.ts 组装 budget 对象时逐字段列出却唯独漏了它——三层断链的
+   * 第一层（AgentConfig 缺字段）。
+   */
+  stallDetection?: {
+    windowTurns?: number;
+    repeatThreshold?: number;
+  } | false;
+  agentName?: string;
+  sessionId?: string;
+  toolHookExecutor?: ToolHookExecutor;
+  debug?: DebugPort;
+  approval?: (toolName: string, args: Record<string, unknown>, reason: string, risk?: ApprovalRisk$1) => Promise<boolean>;
+  clock?: ClockPort;
+  recorder?: TraceRecorder;
+  /** RFC-145 D3：nondet batch 冲洗回调（RecordingPorts.flushNondetBatch）。缺省 = 不聚合。 */
+  nondetFlush?: () => void;
+  depth?: number;
+  retryAccelerate?: {
+    skip: boolean;
+  };
+  /**
+   * RFC-230：流式请求重试策略（429/5xx 指数退避）。缺省 = `DEFAULT_STREAM_RETRY`
+   * （`work-loop-stream-error.ts`）。经宿主（`@x-otto/coding` App）的 `ResilienceConfig`
+   * 投影而来，未注入时 work-loop 用其内部默认常量。
+   */
+  streamRetry?: StreamRetryConfig;
+  /**
+   * RFC-230：网络断连重试策略（固定间隔，不做指数退避）。缺省 = `NETWORK_DISCONNECT_RETRY`。
+   * 语义与 `streamRetry` 同源，见其注释。
+   */
+  networkDisconnectRetry?: StreamRetryConfig;
+  /** RFC-093：工具结果溢出落盘端口（宿主注入，闭包捕获 sessionId）。缺省 = 纯截断。 */
+  spill?: SpillPort;
+}
+interface AgentRunContext {
+  model: Model;
+  /** 会话内稳定的 system 前缀（进 prompt cache 前缀）。 */
+  systemPrompt: string;
+  /** 每轮可变的 system 尾段（volatile）：落在 cache 断点之后，不破坏缓存。 */
+  systemTail?: string[];
+  /** prompt cache 保留档（none/short/long）；缺省走 provider 默认 5m。 */
+  cacheRetention?: CacheRetention;
+  messages: AgentMessage$1[];
+  tools: AgentTool$1[];
+  thinkingLevel: ThinkingLevel;
+  maxTokens?: number;
+  temperature?: number;
+  convertToLLM?: (messages: AgentMessage$1[]) => Message[] | Promise<Message[]>;
+  transformContext?: (messages: AgentMessage$1[], signal?: AbortSignal) => Promise<AgentMessage$1[]>;
+  reactiveCompact?: (messages: AgentMessage$1[], signal?: AbortSignal) => Promise<AgentMessage$1[] | null>;
+  /**
+   * RFC-181 D3：图像委托描述端口（宿主 VisionDelegateService 实现）。透传给
+   * work-loop 的视觉能力门控——见 `./vision-gate.ts` 完整设计说明。
+   */
+  describeImages?: DescribeImagesPort;
+  /**
+   * RFC-170 D4：turn 边界增量持久化回调（pipeline.ts 每次 prompt() 调用时新建的闭包，
+   * 与 transformContext/reactiveCompact 同生命周期——prompt 作用域内共享同一个持久化
+   * 游标，三者协同推进同一份"已落树基准"，不会互相覆盖或产生重复落树）。
+   *
+   * work-loop.ts 在每个 turn（LLM 完成 + 工具执行结束）落定后调用一次，把本 turn 新增的
+   * 消息立即 append 进 session tree——修复此前"整个 prompt 循环结束才一次性 persistNew"
+   * 导致的崩溃丢失窗口（RFC-167 事故实测单 prompt 4.2 小时、101 轮工具循环全部丢失，
+   * 因为进程在循环中途被 OOM kill，从未走到 prompt() 尾部的 persistNew 调用）。
+   *
+   * 与 compaction（onCompaction/transformContext 内部）共享同一持久化游标：无论是"本
+   * turn 结束"还是"本轮触发了 compaction"，都推进同一个"已落树基准"，避免同一批
+   * 消息被 turn-persist 与 recordCompaction 的 replacement 各自独立写入两次逻辑重复
+   * （物理层面：即便如此仍写两次，RFC-160 D7 的内容寻址 blob 表按 sha256 幂等去重，
+   * 不产生重复存储字节；可见层面：buildContext()/messages() 均以 compaction 边界为界
+   * 读取，不会重复呈现——已见 RFC-170 M3 设计闸门核实）。
+   *
+   * 缺省（未注入）= 不做 turn 级增量持久化，退化为此前"prompt 结束才落树"的行为，
+   * 与旧代码零差异（fail-open，同 nondetFlush/registerPendingLifecycleTool 等既有回调
+   * 的缺省语义）。
+   */
+  onTurnPersist?: () => void;
+  /**
+   * RFC-180：turn 边界暂停请求探针（与 abortRequested 模式同构，但通道独立——本字段
+   * 走 AgentRunContext → WorkLoopContext 通道，随 prompt() → runner.run() 调用透传；
+   * TodoGateRunner 的 isAbortRequested 走独立的构造函数注入通道，只服务闸门循环，不
+   * 进入本接口）。work-loop.ts 的外层 prompt 循环在每个 turn 边界（onTurnPersist 已
+   * 调用、消息安全落盘之后，followUp 检查之前）读取；命中则不检查 followUp、不触发
+   * todo 闸门续跑，workLoop 正常 return（非 AbortError，完整收尾）。
+   *
+   * 缺省（未注入）= 不做暂停检查，与旧代码零差异（fail-open，同 onTurnPersist 等既有
+   * 回调的缺省语义）。
+   */
+  isPauseRequested?: () => boolean;
+}
+//#endregion
+//#region src/agent.d.ts
+declare class Agent extends TypedEventEmitter<AgentEvents> {
+  private state;
+  private abortController;
+  private pendingAbort;
+  private steeringQueue;
+  private followUpQueue;
+  /**
+   * RFC-144 M1：lifecycleAsync 工具的执行态追踪，独立于 messages 数组（Agent 实例在两次
+   * run() 之间不持有 messages 引用——由调用方每次通过 AgentRunContext.messages 传入）。
+   *
+   * 键 = toolCallId。存在期：runTools 启动 lifecycleAsync 工具时创建条目（M3 接线）；
+   * `notifyToolCompletion()` 消费（`consumed=true`）后条目保留供审计/溯源，不立即 delete
+   * （若需要严格释放内存，调用方可在 prompt 边界批量清理已 consumed 条目）。
+   *
+   * 真正把 system 通知消息写回 messages 数组的逻辑，依赖调用方持有的 messages 引用，
+   * 归属 M2（落库基础设施）+ M3（auto-trigger 控制流集成）——本字段仅提供状态追踪骨架。
+   */
+  private readonly pendingLifecycleTools;
+  /**
+   * RFC-144 M4：prompt 边界序号——每次 `run()` 被调用（即一次完整的 turn-loop 生命周期
+   * 起点）自增。用于 lifecycleAsync 工具的跨 prompt 隔离判定：工具启动时记录当前
+   * `promptSeq`（见 `PendingLifecycleTool.promptSeq`），完成时若序号已变化（说明工具
+   * 跨越了 prompt 边界——原 prompt 已经结束，一个新的 `run()` 已经开始），其完成通知
+   * 不应注入新 prompt 的 LLM 对话（避免"上一个任务的构建完成了"这类历史事件用一条
+   * mid-conversation system message 打断当前用户正在做的新任务，见 RFC-144 决策 4
+   * Q4 修正——system 角色被模型视为运营方权威事实，混入无关任务上下文比普通消息更
+   * 容易造成困惑或被误解为需要处理的指令）。
+   *
+   * **递增时机边界（重要）**：`Agent.run()` 是 turn-loop 生命周期的唯一入口，包括
+   * `AgentSession` 内部的 todo 续跑（`todoGateRunner`，`internal=true` 场景）——这类
+   * 续跑虽然是"同一用户任务"的延伸，但确实是走完整独立的 `run()` 调用（前一次
+   * `run()` 已经 `completed`/返回），语义上工具若跨越了这次调用边界，模型也确实已经
+   * 推进到了下一轮独立的 turn-loop，此时再看到上一轮的工具完成通知同样可能造成
+   * "为什么突然冒出一个我不认识的构建结果"的困惑——因此续跑同样应该视为新 promptSeq，
+   * 不额外区分 internal，保持递增规则简单统一（"每次 run() 调用 = 一个新 promptSeq"）。
+   */
+  private promptSeq;
+  /** 当前 prompt 序号（只读）——`work-loop.ts` 的 lifecycleAsync 工具启动逻辑读取它记录到
+   *  `PendingLifecycleTool.promptSeq`；完成时对比判定是否已跨越 prompt 边界。 */
+  get currentPromptSeq(): number;
+  /**
+   * 构造期静态配置（终局审查 2026-07-18 M7 收束；元审查 A 修正为派生类型）：`AgentConfig`
+   * 的字段此前逐个拷贝为同名私有字段，构造函数因此膨胀为纯粹的透传列表。收束为单一只读
+   * 配置对象后，构造函数只需一次赋值；下游读取点（`runLoop()` 内两处：`createToolExecutor`
+   * 配置 + `workLoop` 参数）从 `this.xxx` 改为 `this.config.xxx`。
+   *
+   * **类型从 `AgentConfig` 派生而非手写**（元审查 2026-07-18 A 项修正，lesson_46 手抄类型
+   * 副本反模式）：`Required<Pick<...>>` 段 = 构造期已消解默认值的字段（maxToolTurns 等
+   * 5 个，运行期非空）；`Pick<...>` 段 = 原样透传的可选字段。`AgentConfig` 加字段时本类型
+   * 不会静默漂移——新字段若需进 config 必须显式加进 Pick 列表（编译器在构造函数赋值处
+   * 报错提示）。唯一的重命名字段 `agentLogger`（源自 `AgentConfig.logger`）单独声明。
+   * 不改变公开的 `AgentConfig` 接口，仅内部实现重构（零行为变化）。
+   */
+  private readonly config;
+  get status(): AgentStatus;
+  get turnCount(): number;
+  constructor(config: AgentConfig);
+  getState(): Readonly<AgentState>;
+  run(context: AgentRunContext): Promise<AssistantMessage>;
+  /**
+   * RFC-144 M4：取消上一个 prompt 遗留、仍未消费的 lifecycleAsync pending 工具执行。
+   *
+   * 触发时机：每次 `run()` 被调用、**递增 `promptSeq` 之前**（新一轮 turn-loop 生命
+   * 周期起点）。由于同一时刻只会有一个 `run()` 在执行（`run()` 顶部对
+   * streaming/tool_executing 状态直接抛错拒绝并发调用），此刻任何仍未消费的 pending
+   * 条目必然是在**上一个** `run()` 调用期间注册的（`promptSeq` 等于递增前的
+   * `this.promptSeq`）——它们理应已经被上一个 `workLoop()` 返回前的兜底等待
+   * （M3，`waitForPendingLifecycleTools()`）消费完毕；仍然存在未消费条目，说明上一个
+   * `workLoop()` 是被 `AbortError` 中断退出的（用户主动 `abort()` 了上一个 prompt），
+   * 没有机会走到那段兜底等待——这正是本方法要处理的真实场景：用户中断了一个启动了
+   * 长任务工具的 prompt，随即发起了全新任务，旧工具仍在后台跑。
+   *
+   * 继续让它在后台跑对用户已无意义（新任务的模型不会再看到它的结果——见 work-loop.ts
+   * `notifyCompletion()` 的 `crossedPromptBoundary` 判定，跨边界完成不落库注入 LLM
+   * 对话），白白消耗资源（CPU/内存/可能仍在运行的子进程），故主动取消。不需要按
+   * `promptSeq` 数值比较——调用时刻的每一个未消费条目都定义上属于"即将成为历史"的
+   * 那个 prompt（若属于当前正要开始的这个新 prompt，此刻它还未被注册——工具注册
+   * 发生在 `runTools()` 内部，晚于本方法的调用时机）。
+   *
+   * 只 abort 每个条目独立的 `abortController`（M4 新增），不影响 loop 级别的
+   * `this.abortController`——那个 controller 属于"已经结束"的上一次 `runLoop()`
+   * 调用，`run()` 即将为本次调用创建一个全新的 controller，两者本就互不干扰；
+   * 用独立的 per-tool controller 是为了在**未来**"上一个 prompt 仍在正常运行、
+   * 只是启动了 lifecycleAsync 工具"的场景下也能精确取消，不会误伤同一个共享
+   * controller 下的其它逻辑。
+   *
+   * 已消费（`consumed:true`）的条目不取消（它们代表已经落库或已判定跨边界抑制的
+   * 工具，取消一个已经完成的工具是无意义操作），但**在此顺便清理**——终局审查
+   * 2026-07-21 发现：`notifyToolCompletion()` 只标记 `consumed=true` 从不 `delete`，
+   * 而 `reset()`（Map 唯一的清理点）在生产代码中从未被调用（`AgentSession` 持有的
+   * `Agent` 实例与会话同生命周期，一辈子不 reset），导致 Map 无界增长（慢性内存
+   * 泄漏，与 RFC-159/160/170/178 治理的"会话级状态无界增长"同类问题，只是发生在
+   * Agent 类私有字段、未被那几轮驻留审计覆盖到）。
+   *
+   * 清理时机安全性：本方法调用时刻严格早于 `this.promptSeq++`（见 `run()`），此刻
+   * Map 中的**全部**条目都必然注册于此前已经结束/被中断的 run() 调用——本次即将
+   * 开始的新 prompt 还未注册任何条目（注册发生在 `runTools()` 内部，晚于此调用）。
+   * 因此已消费的条目在此处删除对"当前 prompt 内的审计可见性"零影响，不需要按
+   * `promptSeq` 数值比较区分"是否跨越了本次边界"——它们全部跨越了。
+   */
+  private cancelStalePendingLifecycleTools;
+  steer(message: AgentMessage): void;
+  /**
+   * RFC-337 D2：按 `uuid` 从 steering 队列移除一条尚未被消费的 steer 消息，返回是否命中。
+   *
+   * 命中判定即「该 steer 是否仍未被模型消费」的权威真源：`drainSteeringQueue()` 一旦把队列
+   * 清空并交付给 workLoop（消息进入 LLM 上下文），本方法返回 `false`——调用方（cli ESC 撤回）
+   * 据此退化为「中止整回合」（已进历史的消息不可干净撤回，见 RFC-337 §D3 退化路径）。
+   *
+   * 只操作**内存态** `steeringQueue`，不触碰已落库消息、不涉及 save 路径——不违反 RFC-159。
+   */
+  removeSteer(uuid: string): boolean;
+  followUp(message: AgentMessage): void;
+  /**
+   * RFC-144 M1：注册一个 lifecycleAsync 工具的执行态（runTools 启动工具时调用）。
+   * 幂等：同一 toolCallId 重复注册会覆盖旧条目（不应发生，调用方保证每个 tool_call 唯一）。
+   *
+   * 不在此处挂 promise 完成回调——落库闭环的驱动方是 `work-loop.ts` 的 `runTools()`
+   * （见其 `promise.then(...)`/`.catch(...)` 直接调用 `ctx.notifyToolCompletion`），
+   * 因为它直接持有 `messages` 数组引用，能在 consume-once 通过后立即
+   * `messages.push(SystemNotificationMessage)`。Agent 实例本身不持有 messages，
+   * 若在此处也挂一次完成回调会与 workLoop 的调用重复触发 `notifyToolCompletion`
+   * （consume-once 会吞掉第二次调用，不产生双重落库，但属于职责重复的设计混乱，
+   * 故明确只保留 workLoop 一处驱动）。
+   */
+  registerPendingLifecycleTool(entry: PendingLifecycleTool): void;
+  /** 当前仍有 lifecycleAsync 工具在等待（M3 用于 post-runTools yield 判定）。 */
+  hasPendingLifecycleTools(): boolean;
+  /**
+   * RFC-144 M3：等待当前所有未消费的 lifecycleAsync pending 条目 settle。
+   *
+   * 用于外层 prompt 循环在内层 turn 循环因 pending 非空 yield 后的等待点——不轮询
+   * `hasPendingLifecycleTools()`（会引入轮询延迟 + CPU 空转），而是直接 await 每个
+   * pending 条目的 `promise` 字段。
+   *
+   * **`entry.promise` 是"落库完成"信号，不是"工具执行完成"信号**（M3 实现时的关键
+   * 修正，见 `PendingLifecycleTool.promise` 类型定义注释与 work-loop.ts 的
+   * `notifyCompletion()` 函数）：work-loop.ts 把工具执行 + consume-once 通知 +
+   * `messages.push(SystemNotificationMessage)` 三步包成一个函数，本字段存它的返回值。
+   * 若只等原始工具执行 Promise（不等落库这一步），本方法可能在通知真正写进 `messages`
+   * **之前**就返回，外层循环重新进入 `runTurnsUntilTerminate` 发起下一次 `runTurn` 时
+   * 模型会看不到工具完成结果——这是首版实现遗漏、二版修正的竞态。`entry.promise` 恒
+   * fulfilled（`notifyCompletion()` 内部吞掉所有异常，包括工具执行 reject 的情况），
+   * `Promise.allSettled` 不会因任何 pending 条目而挂起或需要错误处理。
+   *
+   * **快照语义**：只等待调用时刻已注册的 pending 条目——若等待期间又有新的
+   * lifecycleAsync 工具被启动（理论上不会发生，因为外层循环在等待期间不会重新调用
+   * `runTools`），不纳入本次等待范围。这与"等到 `hasPendingLifecycleTools()` 变
+   * false"语义等价，但避免了轮询。
+   */
+  waitForPendingLifecycleTools(): Promise<void>;
+  /**
+   * RFC-144 M1/M2：工具真正完成后的通知钩子——检查 consume-once、标记已消费、发出携带
+   * 完整 `result` 的事件。M2 起本方法主要由 `registerPendingLifecycleTool` 注册时挂的
+   * promise 完成回调**自动调用**（事件驱动，无需外部轮询）；也保留公开可调用（防御性/
+   * 测试场景下手动触发）。
+   *
+   * **不在此处把 system 通知写回 messages**——Agent 实例在两次 run() 之间不持有 messages
+   * 引用（见类字段注释）。真正的落库由订阅方（AgentSession，M2 落库基础设施）在
+   * `lifecycle.tool.completed` 事件回调中完成：拿到 `result` 后自行构造
+   * `SystemNotificationMessage` 并追加到其持有的 messages 数组。
+   *
+   * 返回 `consumed=false` 的情况：toolCallId 未注册（未知调用，防御性容错）或已被消费过
+   * （consume-once 语义，防止重复生成通知——即使 promise 的 `.then`/`.catch` 因竞态被
+   * 调用两次，也只有第一次真正标记 consumed 并 emit 事件）。
+   */
+  notifyToolCompletion(toolCallId: string, result: ToolResult): Promise<{
+    consumed: boolean;
+    entry?: PendingLifecycleTool;
+  }>;
+  abort(): void;
+  /** 归档：禁止后续 run()。仅终态(idle/completed/error/aborted)可归档。 */
+  archive(): void;
+  /** 取消归档：从 archived 回到 idle。 */
+  unarchive(): void;
+  /**
+   * 强制归零：不经 `VALID_TRANSITIONS` 表——`streaming`/`tool_executing` 没有到
+   * `idle` 的合法边（reset 的语义恰恰是"哪怕正在跑也强行归零"，先 abort 掉
+   * in-flight controller 再复位，这与常规状态转换的前提相反），故不能改用
+   * `transitionTo()`（那会在这两个状态下被表拒绝、静默不转换，状态反而卡死）。
+   *
+   * 但此前直接赋值 `this.state.status = 'idle'` 会跳过 `status.change` 事件——
+   * 任何订阅方（TUI 状态栏、Session 层状态镜像）收不到通知，与 Agent 内部真实
+   * 状态漂移（终局审查 2026-07-21 发现）。补发事件但保留强制赋值本身。
+   */
+  reset(): void;
+  private runLoop;
+  private transitionTo;
+  private drainSteeringQueue;
+  private drainFollowUpQueue;
+}
+declare function createAgent(config: AgentConfig): Agent;
+//#endregion
+//#region src/tool-result-clamp.d.ts
+/**
+ * RFC-151 D2：image 块内联字节上限（5MB）。超限时走 spill 落盘或占位符丢弃。
+ * 跨包单源 @x-otto/shared PROVIDER_IMAGE_INLINE_MAX_BYTES（C 组收敛，2026-08-09）——re-export
+ * 保持本包公共 API 名不变（消费方/测试 import 自本包）。底层是 provider 单图输入字节约束，
+ * 与 fs/read、mcp、clipboard 同源；shared 常量为纯字面量（不经 env），保证 agent 引擎确定性
+ * 重放不受环境影响（RFC-192）。
+ */
+declare const MAX_IMAGE_INLINE_BYTES: number;
+/**
+ * 剥离 ANSI 转义序列——完整 5 道正则（与 `@x-otto/tui` message-lines.ts 同源同构）。
+ * 本包独立维护不引 tui——agent 不应反向依赖 TUI 包。
+ *
+ * 道 1: OSC 序列（超链接/标题等）
+ * 道 2: 完整 CSI 序列（颜色/光标等，必须有终止字节）
+ * 道 3: 截断的 ESC 前缀（无终止字节的 CSI 碎片，如 `\x1b[38;2;86;182`）
+ * 道 4: 孤儿多参数 SGR 尾（无 ESC 前缀，上游 byte-slice 产物，如 `;194m` / `38;2;86;182;194m`）
+ * 道 5: 孤儿 truecolor 参数（精确匹配 38;2;R;G;Bm / 48;2;R;G;Bm 无 ESC[，英文文本假阳性极低）
+ */
+declare function stripAnsi(text: string): string;
+/**
+ * 源头钩子：工具执行器返回后、任何消费者拿到之前，统一剥离所有 text 块的 ANSI 转义序列。
+ *
+ * 设计意图——替代"散落在各消费路径上的独立 stripAnsi 调用"（打地鼠模式）为"执行边界单次
+ * 归一化"（源头截断）。`tool-turn-runner.ts` 的两个执行入口（sync 工具 + lifecycleAsync 工具）
+ * 在 `toolExecutor.execute()` 返回后立即调用本函数，确保 emitter、recorder、clamp、通知、
+ * trace 等全部下游自动获得洁净文本。下游已有的 stripAnsi 调用保留为纵深防御（对已洁净文本
+ * 是零开销 no-op）。
+ *
+ * 类型设计：泛型 `T extends { type: string; text?: string }` 兼容 `ToolResult.content`
+ * （`@x-otto/hook-contracts`）与 `ToolResultMessage['content']`（`@x-otto/interchange`）
+ * 两套 shape——text 块有 `{ type: 'text', text: string }`，image 块 `{ type: 'image', ... }`
+ * 无 text 字段原样返回。
+ */
+declare function normalizeToolResultContent<T extends {
+  type: string;
+  text?: string;
+}>(content: T[]): T[];
+/**
+ * R7：钳制工具结果文本进模型上下文的大小。仅截极端值（默认 100k 字符≈25k token）：
+ * text 块超阈值时头尾保留、中段以 `[… N chars truncated …]` 替换；非 text 块原样保留。
+ * 防全仓 grep / 巨型文件读等病态结果撑爆 context window；正常 read/edit 远低于阈值不受影响。
+ *
+ * 终局修复（ANSI 泄漏）：**钳制前先剥离 ANSI**，再基于洁净文本算 head/tail/slice——
+ * 否则 slice 可能恰好落在 ANSI 序列中间（如 head 落到 `\x1b[38;2;86;182` 中间位置），
+ * 导致下游 stripAnsi 仅剥离前半段 `\x1b[38;2;86;182` 无效序列、后半段 `;194mfunction`
+ * 无 ESC 前缀的残缺参数裸漏进对话流。先 strip → 基于洁净长度钳制 → 用洁净文本拼接。
+ * 钳制输出本就降级为截断预览，丢失 ANSI 颜色是可接受的。
+ */
+declare function clampToolResultContent(content: ToolResultMessage['content'], maxChars: number): ToolResultMessage['content'];
+/**
+ * 统计一段 tool result content 真正进入模型上下文的文本字符数。
+ *
+ * 调用方应传 **clamp/spill 之后**的 content——它才是模型下一轮实际看到的内容。
+ * image 块按 `IMAGE_CONTEXT_CHARS_EQUIVALENT` 折算（图片不是文本，但仍占窗口；
+ * 这里只给宿主一个量级可用的估算基数，精确图片 token 由 provider usage 结算）。
+ */
+declare const IMAGE_CONTEXT_CHARS_EQUIVALENT = 4000;
+declare function toolResultContextChars(content: ToolResultMessage['content']): number;
+/**
+ * RFC-093：spill-aware 钳制。超预算 text 块先尝试落盘（SpillPort）：
+ * 成功 → 占位符含磁盘路径 + 头尾 preview（模型可用 read 工具恢复全文）；
+ * 失败/未注入 → fail-open 回退 clampToolResultContent 纯截断（现状行为）。
+ */
+declare function clampWithSpill(content: ToolResultMessage['content'], maxChars: number, toolCallId: string, spill: SpillPort | undefined): Promise<ToolResultMessage['content']>;
+/**
+ * 有上限的并行执行（allSettled 语义）。最多 `limit` 个并发，其余排队；每个任务
+ * 自捕获异常成 PromiseSettledResult，绝不抛出（无孤儿）——调用方据 settled 数组统一传播。
+ * 保留输入顺序对应结果索引。
+ */
+declare function runBounded<T>(items: readonly T[], limit: number, fn: (item: T) => Promise<void>): Promise<PromiseSettledResult<void>[]>;
+//#endregion
+//#region src/lifecycle-async-tool.d.ts
+/**
+ * RFC-144 决策 1 "Q2 修正"：placeholder 内容必须是强制性、无歧义的行为约束，而非
+ * 状态陈述——LLM 对结构信号（tool_result 存在即代表完成）的服从度高于对文本指令，
+ * 简单陈述句（"已启动，尚未完成"）不足以抑制虚假完成信号。已通过真实 Claude Opus 4.8
+ * 端到端验证（2026-07-10，见 RFC M0 执行状态），确认此措辞有效。
+ */
+declare function buildLifecycleAsyncPlaceholderText(toolName: string, taskId: string, note?: string): string;
+/**
+ * 构造 lifecycleAsync 工具启动时的终态 placeholder tool_result。
+ *
+ * **终态**：一次写入后永不被替换或重排（见 RFC-144 决策 1、硬约束 1）——从写入的
+ * 那一刻起就满足 provider 的 tool_call↔tool_result 1:1 配对约束，不再需要任何
+ * 后续的 seal 排除或重排逻辑（原破窗点 #1/#7 因此被架构性消除）。
+ */
+declare function buildLifecycleAsyncPlaceholder(toolCallId: string, toolName: string, clock: {
+  now(): number;
+}, note?: string): ToolResultMessage;
+/**
+ * 构造工具真正完成时的 mid-conversation system 通知消息（第五轮修正：落回持久数组，
+ * 非临时 context 副本；provider 序列化归属 M2）。
+ */
+declare function buildLifecycleAsyncCompletionNotice(toolName: string, toolCallId: string, result: ToolResult, clock: {
+  now(): number;
+}): SystemNotificationMessage;
+//#endregion
+//#region src/pipeline.d.ts
+interface PipelineHooks {
+  execute<T extends InterceptorTiming>(timing: T, input: HookInput<T>, output: HookOutput<T>): Promise<void>;
+  emit<T extends ObserverTiming>(timing: T, input: HookInput<T>): Promise<void>;
+}
+interface PersistencePort {
+  messages(): readonly AgentMessage[];
+  append(message: AgentMessage): void;
+  buildContext(): {
+    messages: AgentMessage[];
+    summary?: string;
+  };
+  persistNew(messages: AgentMessage[], fromIndex: number): void;
+  /**
+   * 自动压缩(keep-recent)写回——把摘要 + 保留的近期消息记入会话树
+   * （replacement_history 模型），使压缩成为持久事件：重启原样恢复、不每轮重算。可选（旧适配器可不实现）。
+   */
+  recordCompaction?(summary: string, replacement: AgentMessage[]): void;
+  /**
+   * 裁剪（prune）发生时的 UI 通知——无持久化语义，仅供 AgentSession publish memory.pruned 会话事件
+   * 驱动「裁剪已启用」提示。与 recordCompaction 同为「agent 包调、runtime 实现并 publish」的 facade 桥。
+   * 可选（旧适配器/无 UI 时可不实现）。
+   *
+   * `metrics`：裁剪明细（prunedCount/messagesBefore/messagesAfter，可选——供 `/compact log`
+   * 详情面板展示"裁剪了多少条工具输出"，而非仅有 tokensSaved 单一数字）。
+   */
+  notifyPrune?(tokensSaved: number, metrics?: {
+    prunedCount: number;
+    messagesBefore: number;
+    messagesAfter: number;
+  }): void;
+  /**
+   * RFC-283 D2：移除最后一条 append 的 message entry（内存态回滚）。
+   * 用于 prompt 失败时回滚从未到达 LLM 的 user message。
+   * 只移除最后一条 message 类型 entry，回退 _leafId；不触碰 compaction/clear 等结构 entry。
+   * 只在 prompt 执行期间（save 之前）调用，不违反 RFC-159 save 路径不删行约束。
+   */
+  removeLast?(): void;
+  /**
+   * RFC-336 D2：**输入边界**落盘请求——本轮 user message 已进会话树、且上下文准备
+   * （planPromptContext）已成功，但尚未开始调用模型。宿主据此把新增 entries 落库。
+   *
+   * 要解决的问题：落库此前只由 `turn.end`/`prompt.end` 触发（RFC-305），两者都在**首个
+   * 模型回合完成之后**。故"用户已回车、模型还没吐字"这段窗口（≈ 一次完整模型往返，
+   * 数秒~数十秒）内进程被强杀，那条 user message 从未落库。RFC-336 M1 已保证会话行
+   * 存在（不再整个蒸发），本钩子进一步保证**消息本身**不丢。
+   *
+   * **调用时机固定在 prep 成功之后**（RFC-336 §D3 grill 定案方向 A，规则 7）：不得前移到
+   * `append()` 紧后——prep 失败时 RFC-283 D2 要 `removeLast()` 做内存回滚，若此前已落库
+   * 就会造成内存与 DB 不一致。放在 prep 成功后，两者语义天然自洽。
+   *
+   * **契约**：实现方必须 fire-and-forget（不得阻塞工作循环，RFC-336 规则 3）、必须复用
+   * 宿主既有的 per-session 串行写链（不得新开并发写路径，规则 2/9）。可选：旧适配器/
+   * 无持久化场景不实现即退回改动前行为（首个 turn 后才落库）。
+   */
+  persistInputBoundary?(): void;
+}
+interface MemoryPort {
+  needsPrune(messages: readonly Message[]): boolean;
+  needsCompaction(messages: readonly Message[]): boolean;
+  /**
+   * `/clear`——驱逐某会话的工作记忆（滚动压缩摘要桶）。可选：注入式/无 memory
+   * 场景安全跳过。清后下一轮压缩从空摘要重建，不再把已清内容的摘要喂回模型。
+   */
+  clearSession?(sessionId: string): void;
+  /**
+   * 审计修复：会话销毁/驱逐时遗忘其全部 per-session 状态(摘要桶 + 压缩游标 + archive 计数)。
+   * 区别于 clearSession(/clear 保留 archive 计数,会话继续):forget 是终态清理,防内存无界增长。
+   */
+  forgetSession?(sessionId: string): void;
+  /**
+   * 模型切换时更新上下文窗口 + 重算 compaction/prune 触发阈值。
+   * 切换低窗口模型后立即调用，防止下一轮 413。
+   */
+  reconfigure?(model: {
+    contextWindow: number;
+    maxOutput: number;
+  }): void;
+  /**
+   * 主动检查当前消息量是否超过压缩触发线；超过则 force-compact，
+   * 返回压缩后消息 + compacted flag + summary/replacement（供调用方写回 session 树）。
+   */
+  ensureFitsWindow?(messages: readonly Message[], sessionId?: string, signal?: AbortSignal): Promise<{
+    messages: Message[];
+    compacted: boolean;
+    summary?: string;
+    replacement?: Message[];
+  }>;
+  process(messages: readonly Message[], sessionId?: string, signal?: AbortSignal, options?: {
+    force?: boolean;
+    skipPrune?: boolean;
+  }): Promise<{
+    messages: Message[];
+    pruned: boolean;
+    compacted: boolean;
+    summary?: string;
+    replacement?: Message[];
+    archivePath?: string;
+    pruneMetrics?: {
+      prunedCount: number;
+      tokensSaved: number;
+      messagesBefore: number;
+      messagesAfter: number;
+    };
+  }>;
+}
+interface TurnRunner {
+  run(context: AgentRunContext): Promise<AssistantMessage>;
+}
+interface PromptParams {
+  systemPrompt: string;
+  thinkingLevel: ThinkingLevel;
+  temperature?: number;
+  maxTokens?: number;
+  /** prompt cache 保留档（none/short/long）；由会话据特征选档，透传至 provider。 */
+  cacheRetention?: CacheRetention;
+  /**
+   * 会话恒定的 **volatile system 尾段种子**（落在 cache 断点之后，不击穿 stable 前缀缓存）。
+   * 由宿主据会话配置填充——典型用例：append 模式子代理的角色块（保留共享 base system prompt 进缓存，
+   * 角色差异走断点后的尾段）。transformSystemPrompt 以此为 systemTail 起点，hook（phase/memory-delta）
+   * 续接其后。
+   */
+  systemTail?: string[];
+}
+interface PromptInput {
+  text: string;
+  /**
+   * RFC-111 D4b：可选的图片附件，随本轮用户消息一起注入上下文（如飞书桥接下载的图片）。
+   * 缺省（`undefined`）时行为与改动前完全一致——`createUserMessage` 只产出纯文本 content
+   * （§6 规则7 向后兼容红线）。
+   */
+  images?: Array<{
+    type: 'image';
+    data: string;
+    mediaType: string;
+  }>;
+  /**
+   * RFC-094：引擎注入的内部触发消息（todo 闸门续跑提示）——模型需要看到、但不渲染给用户
+   * （对齐 RFC-050 REV-1 internal 语义；provider 序列化忽略此字段）。
+   */
+  internal?: boolean;
+  sessionId: string;
+  agentName: string;
+  model: Model;
+  tools: AgentTool[];
+  params: PromptParams;
+  runner: TurnRunner;
+  hooks: PipelineHooks;
+  persistence: PersistencePort;
+  memory?: MemoryPort;
+  debug?: DebugPort;
+  clock?: ClockPort;
+  recorder?: TraceRecorder;
+  /** RFC-180：turn 边界暂停请求探针——透传给 runner.run() 的 AgentRunContext.isPauseRequested。 */
+  isPauseRequested?: () => boolean;
+  /**
+   * RFC-181 D3/M3：图像委托描述端口（宿主 VisionDelegateService 实现）——透传给
+   * runner.run() 的 AgentRunContext.describeImages（见 work-loop.ts vision-gate.ts
+   * 完整设计说明）。缺省 = 主模型不支持视觉时，image block 降级为占位文本。
+   */
+  describeImages?: DescribeImagesPort;
+}
+interface PromptResult {
+  cancelled: boolean;
+  message?: AssistantMessage;
+  newMessages: AgentMessage[];
+  /** D1：usage 增量聚合结果——AgentSession.promptUsage/hadToolActivity 不再扫描 newMessages 数组。 */
+  newMessagesUsageSummary: NewMessagesAccumulator;
+  params: PromptParams;
+}
+/** D1：消息切片元数据聚合——替代 newMessages 数组的 usage/hadTool 扫描路径。 */
+interface NewMessagesAccumulator {
+  usage: Usage;
+  hadToolActivity: boolean;
+  lastAssistantApi: string | undefined;
+  count: number;
+}
+declare function prompt(input: PromptInput): Promise<PromptResult>;
+//#endregion
+//#region src/context-pipeline.d.ts
+/**
+ * RFC-074 R-CTXARG：尾随可选项收成 options 对象（原 recorder/hooks/persistence/sink 四个位置参
+ * 在 apply/force 两函数间顺序不一致 → 易传错位）。memory/messages/sessionId/signal 仍位置参。
+ */
+interface MemoryTransformOptions {
+  recorder?: TraceRecorder;
+  hooks?: PipelineHooks;
+  persistence?: PersistencePort;
+  sink?: {
+    compacted: boolean;
+    replacement?: AgentMessage[];
+  };
+}
+declare function applyMemoryTransform(memory: MemoryPort | undefined, messages: AgentMessage[], sessionId: string, signal?: AbortSignal, opts?: MemoryTransformOptions): Promise<AgentMessage[]>;
+/**
+ * 反应式压缩——本轮 stream 因上下文溢出(413)失败时调用。无条件强制压缩
+ * （绕过 token 阈值闸），返回压缩后的消息数组；若无可压缩内容（消息太少等）返回 null，
+ * 调用方据此放弃重试并上抛原始溢出错误。**不**再跑 messages.transform hook：该 hook 已在
+ * 本轮 transformContext 跑过，重跑可能引入新内容、与「缩小上下文」的目标相悖。
+ */
+declare function forceMemoryTransform(memory: MemoryPort | undefined, messages: AgentMessage[], sessionId: string, signal?: AbortSignal, opts?: MemoryTransformOptions): Promise<AgentMessage[] | null>;
+//#endregion
+//#region src/memory-lifecycle.d.ts
+/**
+ * 记忆子系统生命周期（原设计稿 docs/design/memory-lifecycle.md 已随 RFC-067 M123-03 文档收敛
+ * 删除，内容并入 packages/memory/ARCHITECTURE.md，见 commit 5d6a9f5b）。
+ *
+ * P1（最小可观测）：仅录 trace —— 让裁剪/持久化在 inspector/replay/OTel 现形。
+ * 后续 P2 把本模块扩展为多通道 sink（同一事件再扇出 emitter(AgentEvent) + hooks 干预面），
+ * P3 收编 compaction.* 把压缩三路归一。当前仅 prune/archive 接线（compact 暂留 compaction.*；
+ * load/update 属其它层，待 P1b）。
+ */
+type MemoryPhase = 'load' | 'prune' | 'compact' | 'archive' | 'update';
+type MemoryTrigger = 'startup' | 'in_loop' | 'reactive_overflow' | 'manual' | 'tool';
+interface MemoryMetrics {
+  prunedCount?: number;
+  tokensSaved?: number;
+  messagesBefore?: number;
+  messagesAfter?: number;
+  archivePath?: string;
+  archivedCount?: number;
+}
+interface MemoryLifecycleEvent {
+  phase: MemoryPhase;
+  sessionId: string;
+  turn?: number;
+  trigger: MemoryTrigger;
+  metrics: MemoryMetrics;
+}
+/** P1：把一条记忆生命周期事件录成对应 trace 锚点（node 由 PHASE_TRACE_NODE 编译期约束为 traceable）。 */
+declare function recordMemoryLifecycle(recorder: TraceRecorder, event: MemoryLifecycleEvent): void;
+//#endregion
+//#region src/trace-views.d.ts
+interface TraceRecord {
+  seq: number;
+  entry: TraceEvent;
+}
+interface TraceSummary {
+  totalEvents: number;
+  kinds: Record<string, number>;
+  turns: number;
+  toolCalls: number;
+  firstTs?: number;
+  lastTs?: number;
+}
+interface TraceSpan {
+  seq: number;
+  ts: number;
+  kind: TraceEvent['kind'];
+  node?: string;
+  turn?: number;
+  digest?: string;
+}
+type Records = AsyncIterable<TraceRecord> | Iterable<TraceRecord>;
+declare function summarizeTrace(records: Records): Promise<TraceSummary>;
+declare function traceToSpans(records: Records, options?: {
+  digestMax?: number;
+}): Promise<TraceSpan[]>;
+/**
+ * payload 摘要（归一自旧 cli formatDigest 的富格式 + 旧 service 的长度上限语义）：
+ * text → 引号包裹；name → `name(args)`；reason → `done:reason`；message → `role:content`；
+ * 其余 JSON 截断。大 payload 只截输出长度（stringify 成本与旧实现持平，不引入新风险）。
+ *
+ * `node` 可选（向后兼容既有 2 参调用点/测试）——传入时优先走 `digestByNode` 精确分发，
+ * 未命中或未传时落回下方形状匹配链（见 digestByNode 上方注释的完整设计说明）。
+ */
+declare function digestTracePayload(payload: unknown, max?: number, node?: string): string | undefined;
+interface CausalNode {
+  eventId: string;
+  seq: number;
+  kind: string;
+  node?: string;
+  turn?: number;
+  parentEventId?: string;
+  causalChain?: string[];
+}
+interface CausalDag {
+  nodes: CausalNode[];
+  edges: Array<{
+    from: string;
+    to: string;
+  }>;
+  roots: string[];
+  leaves: string[];
+}
+/**
+ * 从 trace 事件列表构建因果 DAG（M34-01）。
+ * 利用 TraceEvent 中的 parentEventId / causalChain 字段构建有向无环图。
+ * 不支持字段的事件降级为平铺列表（每个节点独立为根）。
+ */
+declare function causalDag(records: TraceRecord[]): CausalDag;
+declare function traceWhy(records: TraceRecord[], targetSeq: number): string[];
+//#endregion
+//#region src/errors.d.ts
+declare class AbortError extends AgentError {
+  constructor(message?: string);
+}
+declare class MaxToolTurnsError extends AgentError {
+  readonly maxTurns: number;
+  readonly partialText: string;
+  readonly extensions: number;
+  constructor(maxTurns: number, partialText?: string, extensions?: number);
+  get effectiveMaxTurns(): number;
+}
+/**
+ * RFC-104 D3：per-prompt token/时间预算超额（steer 收尾轮之后仍超才抛）。
+ * 与 MaxToolTurnsError 并存：轮次触顶抛 MaxToolTurnsError（API 兼容），
+ * token/时间超额抛本错误；边界层（run-modes）需对称 catch 两者（RFC-104 评审 A2）。
+ */
+declare class PromptBudgetExceededError extends AgentError {
+  readonly dimension: 'tokens' | 'time';
+  readonly used: number;
+  readonly budget: number;
+  readonly partialText: string;
+  constructor(dimension: 'tokens' | 'time', used: number, budget: number, partialText?: string);
+}
+//#endregion
+export { AbortError, Agent, type AgentConfig, type AgentEvent, type AgentEventOf, type AgentEventPayload, type AgentEventType, type AgentEvents, type AgentMessage, type AgentRunContext, type AgentSessionEvent, type AgentSessionEventMap, type AgentSessionEventType, type AgentSessionSubscriber, type AgentState, type AgentStatus, type AgentTool, type ApprovalRisk, type AskUserQuestion, BREAKPOINT_POINTS, type BreakpointCategory, type BreakpointDefinition, type BreakpointPoint, type CausalDag, type CausalNode, type ClockPort, type CustomAgentMessages, type DebugCommand, type DebugPort, type DebugSnapshot, type DescribeImagesPort, type DeterminismPorts, ENGINE_DEFAULTS, ENGINE_LIFECYCLE_TIMINGS, ENGINE_NODES, type EngineNode, type EngineNodeCategory, type EngineNodeDef, type GrillAnswer, type GrillOption, type GrillQuestion, type GrillRequest, IMAGE_CONTEXT_CHARS_EQUIVALENT, type IdPort, type InjectedMessage, type LifecycleTiming, MAX_IMAGE_INLINE_BYTES, MaxToolTurnsError, type MemoryLifecycleEvent, type MemoryMetrics, type MemoryPhase, type MemoryPort, type MemoryTrigger, type MessageSummaryItem, type NewMessagesAccumulator, type NondetDraw, OBSERVABLE_NODE_IDS, type ObservableNodeId, type PauseApplyTarget, type PauseResult, type PauseResumePayload, type PendingLifecycleTool, type PersistencePort, type PipelineHooks, PromptBudgetExceededError, type PromptInput, type PromptParams, type PromptResult, type RandomPort, type RecordingPorts, type StreamFunction, type StreamRetryConfig, type StreamTracePersister, TRACEABLE_NODE_IDS, type ToolBeforeOutcome, type ToolCallContext, type ToolCallEvent, type ToolExecutor, type ToolHookExecutor, type ToolResult, type TraceEvent, type TraceEventDraft, type TraceEventKind, type TraceRecord, type TraceRecorder, type TraceRecorderOptions, type TraceSink, type TraceSpan, type TraceSummary, type TraceableNodeId, type TurnRunner, type VisionGateResult, applyMemoryTransform, applyVisionGate, buildLifecycleAsyncCompletionNotice, buildLifecycleAsyncPlaceholder, buildLifecycleAsyncPlaceholderText, causalDag, clampToolResultContent, clampWithSpill, consumePause, createAgent, createRecordingPorts, createReplayPorts, createStreamTracePersister, createToolExecutor, createTraceRecorder, digestTracePayload, extractNondetDraws, extractToolResultText, forceMemoryTransform, nodesWithCapability, noopRecorder, normalizeToolResultContent, prompt, recordMemoryLifecycle, runBounded, shouldPersistStreamEvent, stripAnsi, summarizeMessages, summarizeTrace, systemClock, systemId, systemRandom, toolResultContextChars, traceToSpans, traceWhy };
+//# sourceMappingURL=index.d.ts.map