minimal-agent 0.12.0 → 0.14.0

package/src/types.ts

@@ -73,6 +73,19 @@ export interface ImageInputSpec {
   maxLongSidePixel?: number;
 }
 
+/** Host-authorized file supplied for the current workflow invocation. */
+export interface InvocationResource {
+  id: string;
+  origin: 'path' | 'attachment';
+  name: string;
+  mime: string;
+  size?: number;
+  sha256?: string;
+  localPath: string;
+  visionPath?: string;
+  kind: 'file' | 'directory';
+}
+
 /**
  * 用户消息关联的附件展示元数据。
  *
@@ -105,6 +118,18 @@ export interface MessageBrowserReference {
   capturedAt: number;
 }
 
+/** Local-only origin metadata used to keep one Session safe across private and group turns. */
+export interface ConversationProvenance {
+  mode: 'private' | 'group';
+  visibility: 'owner-private' | 'group-public';
+  groupId?: string;
+  groupMessageId?: string;
+  senderId?: string;
+  senderName?: string;
+  taskId?: string;
+  grantId?: string;
+}
+
 /**
  * 所有 Message variant 共享的可选字段。
  *
@@ -124,8 +149,7 @@ export type Message = (
        *
        *  - saveContext（persistContext.ts）写盘前过滤掉 _ephemeral=true 的 system 消息
        *  - MessageList 识别此标记走暗灰单行样式（其他 system 消息保持 hide）
-       *  - 其他场景（LLM 调用等）暂时不过滤；短消息无害，下个版本再做 runQuery 入参过滤
-       *  - 已知限制：本期 LLM 收到 ephemeral 消息（不影响功能，仅噪声）
+       *  - provider 请求（包括本地与团队网关）会过滤掉这类消息
        */
       _ephemeral?: true;
     }
@@ -168,6 +192,8 @@ export type Message = (
       tool_call_id: string;
       /** 本地展示元数据；发送 Provider 前会剥离。 */
       display_metadata?: ToolResultMetadata;
+      /** 本地压缩策略；发送 Provider 前会剥离。 */
+      tool_result_policy?: ToolResultPolicy;
       timestamp?: number;
     }
 ) & {
@@ -177,6 +203,8 @@ export type Message = (
    *   - 不发给 LLM：client.ts 在发送给 LLM 序列化消息前自动剔除。
    */
   id?: string;
+  /** Persisted locally, rendered as a trusted label for the model, never sent as a raw provider field. */
+  provenance?: ConversationProvenance;
 };
 
 // ---------------- 2. 工具 (Tool) ----------------
@@ -213,7 +241,12 @@ export interface AgentResultMetadata {
   };
 }
 
-export type FileActivityKind = 'read' | 'created' | 'modified' | 'generated' | 'deleted';
+export type FileActivityKind =
+  | 'read'
+  | 'created'
+  | 'modified'
+  | 'generated'
+  | 'deleted';
 export type FileVerification = 'passed' | 'failed' | 'not_run';
 export type ConversationFilePurpose = 'source' | 'deliverable' | 'support';
 export interface FilePatchSummary {
@@ -257,7 +290,11 @@ export interface DeliverableManifest {
     purpose: 'deliverable';
   }>;
   links?: Array<{ url: string; title?: string }>;
-  browserEvidence?: Array<{ tabId: string; url: string; screenshotId?: string }>;
+  browserEvidence?: Array<{
+    tabId: string;
+    url: string;
+    screenshotId?: string;
+  }>;
   warnings: string[];
 }
 
@@ -277,8 +314,18 @@ export interface ResultManifestMetadata {
   manifest: DeliverableManifest;
 }
 
-export type ProcessCommandKind = 'test' | 'typecheck' | 'build' | 'check' | 'other';
-export type ProcessExecutionStatus = 'started' | 'running' | 'completed' | 'failed' | 'stopped';
+export type ProcessCommandKind =
+  | 'test'
+  | 'typecheck'
+  | 'build'
+  | 'check'
+  | 'other';
+export type ProcessExecutionStatus =
+  | 'started'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'stopped';
 
 /** Structured process state shared by Bash, PowerShell, TaskOutput and the evidence ledger. */
 export interface ProcessExecutionMetadata {
@@ -291,10 +338,55 @@ export interface ProcessExecutionMetadata {
   exitCode?: number | null;
 }
 
+export type AdvisorCheckpoint =
+  | 'pre-execution'
+  | 'stalled'
+  | 'high-risk'
+  | 'pre-delivery';
+
+export interface AdvisorVersions {
+  taskVersion: number;
+  workVersion: number;
+  evidenceVersion: number;
+}
+
+export interface AdvisorCheckpointMetadata extends AdvisorVersions {
+  kind: 'advisor_checkpoint';
+  checkpoint: AdvisorCheckpoint;
+  checkpointKey: string;
+  status: 'required' | 'attempted-unavailable';
+}
+
+export interface AdvisorConsultationMetadata extends AdvisorVersions {
+  kind: 'advisor_consultation';
+  consultationId: string;
+  checkpoint: AdvisorCheckpoint;
+  checkpointKey: string;
+  status: 'completed' | 'failed';
+}
+
+export interface AdvisorDecisionMetadata extends AdvisorVersions {
+  kind: 'advisor_decision';
+  consultationId: string;
+  checkpoint: AdvisorCheckpoint;
+  checkpointKey: string;
+  decision: 'accept' | 'partial' | 'reject';
+  rationale: string;
+  acceptedPoints: string[];
+  rejectedPoints: string[];
+  verificationPlan: string[];
+}
+
 /** Agent 子任务的结构化阶段进度；仅供宿主展示，不写入会话历史或发送给 LLM。 */
 export interface SubagentProgress {
   kind: 'subagent';
-  phase: 'queued' | 'preparing' | 'analyzing' | 'using_tool' | 'drafting' | 'waiting_owner';
+  phase:
+    | 'queued'
+    | 'preparing'
+    | 'analyzing'
+    | 'using_tool'
+    | 'drafting'
+    | 'waiting_owner';
   queuePosition?: number;
   activeCount?: number;
   maxConcurrent?: number;
@@ -306,32 +398,73 @@ export interface SubagentProgress {
 
 export type ToolProgressDetail = SubagentProgress;
 
+/** A browser download lives under the agent state root, not the workspace. */
+export interface BrowserDownloadMetadata {
+  kind: 'browser_download';
+  downloads: Array<{
+    id: string;
+    url: string;
+    filename: string;
+    path: string;
+    state: 'start' | 'progress' | 'complete' | 'failed' | 'canceled';
+    mime?: string;
+    receivedBytes?: number;
+    totalBytes?: number;
+    error?: string;
+  }>;
+  /** Present when the batch requested `artifact.save_as`; the download is
+   * copied into the workspace and can be committed by the host as a normal
+   * conversation delivery. */
+  artifact?: DeliverableManifest;
+}
+
 export type ToolResultMetadata =
   | AgentResultMetadata
   | FileActivityMetadata
   | FileDiscoveryMetadata
   | ResultManifestMetadata
-  | ProcessExecutionMetadata;
+  | ProcessExecutionMetadata
+  | AdvisorCheckpointMetadata
+  | AdvisorConsultationMetadata
+  | AdvisorDecisionMetadata
+  | BrowserDownloadMetadata;
+
+/**
+ * 本地工具结果压缩策略；只用于 history 决策和 UI 诊断，发送 provider 前剥离。
+ * highValue 优先级高于 reclaimable：高价值结果不会被 Path C 回收或中段截断。
+ */
+export interface ToolResultPolicy {
+  reclaimable: boolean;
+  highValue: boolean;
+  archiveRef?: string;
+  originalChars?: number;
+}
 
 export type ToolResult =
   | {
-    ok: true;
-    content: string;
-    metadata?: ToolResultMetadata;
-    recovery?: 'none' | 'retry' | 'change-input' | 'user-action';
-    sensitivity?: 'public' | 'local' | 'sensitive';
-    visionImages?: ImageInputSpec[];
-    visionNote?: string;
-  }
+      ok: true;
+      content: string;
+      metadata?: ToolResultMetadata;
+      /** 可选的本地上下文压缩策略；未提供时由工具名策略兜底。 */
+      policy?: ToolResultPolicy;
+      recovery?: 'none' | 'retry' | 'change-input' | 'user-action';
+      sensitivity?: 'public' | 'local' | 'sensitive';
+      visionImages?: ImageInputSpec[];
+      visionNote?: string;
+    }
   | {
-    ok: false;
-    error: string;
-    metadata?: ToolResultMetadata;
-    recovery?: 'none' | 'retry' | 'change-input' | 'user-action';
-    sensitivity?: 'public' | 'local' | 'sensitive';
-    visionImages?: ImageInputSpec[];
-    visionNote?: string;
-  };
+      ok: false;
+      error: string;
+      /** deferred 是宿主检查点暂缓，不是工具失败；失败统计与 stall guard 必须忽略。 */
+      disposition?: 'error' | 'deferred';
+      metadata?: ToolResultMetadata;
+      /** 可选的本地上下文压缩策略；未提供时由工具名策略兜底。 */
+      policy?: ToolResultPolicy;
+      recovery?: 'none' | 'retry' | 'change-input' | 'user-action';
+      sensitivity?: 'public' | 'local' | 'sensitive';
+      visionImages?: ImageInputSpec[];
+      visionNote?: string;
+    };
 
 // visionImages：工具想让（视觉）模型「亲眼看一下」的图像（如浏览器关键节点实况截图）。
 // 主循环在回填工具结果后，把它们组装成一条带图的 user 消息喂给模型自我核验（见 loop.ts）。
@@ -364,6 +497,8 @@ export interface ToolCallContext {
   advisorCalls?: { used: number; max: number };
   /** 区分主模型自动咨询与用户显式 /advisor ask。 */
   advisorInvocation?: 'agent' | 'manual';
+  /** Advisor 协调器运行时桥；只存在于主循环，不暴露给模型或持久化。 */
+  advisorRuntime?: AdvisorRuntimeBridge;
   /**
    * 主循环使用的 provider —— Agent 等「工具内部再起子查询」的派生工具用它
    * 跑嵌套 runQuery（子 agent 与主 agent 同一模型，不另配凭据）。
@@ -399,6 +534,8 @@ export interface ToolCallContext {
   cwd?: string;
   /** 本机记忆权限由宿主明确声明；不可信宿主必须为 denied。 */
   memoryAccess?: import('./runtime/agentRuntimeContext.js').MemoryAccessInput;
+  conversationMode?: import('./runtime/agentRuntimeContext.js').ConversationMode;
+  surface?: import('./runtime/agentRuntimeContext.js').AgentSurface;
   /**
    * Browser actions are scoped to the owning conversation/run by the host.
    * `supervised` 由宿主声明「存在可见浏览器 + 真人可接管/resume」（仅 Desktop 置 true）：
@@ -459,6 +596,68 @@ export interface ToolCallContext {
   };
 }
 
+export interface AdvisorContextPacket {
+  objective: string;
+  currentRequest: string;
+  checkpoint: AdvisorCheckpoint;
+  versions: AdvisorVersions;
+  changedFiles: string[];
+  evidence: string[];
+  previousAdvice?: string;
+  actionsAfterPreviousAdvice: string[];
+  openQuestions: string[];
+}
+
+export interface AdvisorRuntimeBridge {
+  /**
+   * 有值 = 存在一次已成功、但还没被 AdvisorDecision 结清的咨询——下一次
+   * Advisor 调用是对它的复核，而不是一次全新检查点的咨询。`advisor.ts`
+   * 用它判断复核调用是否该豁免配额（复核不该因为撞配额墙而被迫放弃、
+   * 反而把本该把关的检查点悄悄标记完成）。
+   */
+  readonly pendingConsultationId: string | undefined;
+  /** 同一检查点最多允许一次不占配额的证据冲突复核。 */
+  readonly canReconcileConsultation: boolean;
+  beginConsultation(): AdvisorConsultationMetadata;
+  finishConsultation(
+    metadata: AdvisorConsultationMetadata,
+    ok: boolean,
+  ): AdvisorConsultationMetadata;
+  recordDecision(input: {
+    consultationId: string;
+    decision: 'accept' | 'partial' | 'reject';
+    rationale: string;
+    acceptedPoints?: string[];
+    rejectedPoints?: string[];
+    verificationPlan?: string[];
+  }): ToolResult;
+  contextPacket(note?: string): AdvisorContextPacket;
+}
+
+export type ToolCategory =
+  | 'files'
+  | 'shell'
+  | 'web'
+  | 'desktop'
+  | 'agents'
+  | 'memory'
+  | 'media';
+
+/**
+ * Compact, system-prompt-facing routing guidance.
+ *
+ * Tool descriptions identify the callable contract and parameter schemas
+ * describe fields.  Selection boundaries live here so every active tool can
+ * be presented once in the system prompt without copying long descriptions.
+ */
+export interface ToolPromptGuide {
+  category: ToolCategory;
+  useWhen: string;
+  method: string;
+  avoidWhen?: string;
+  priority?: 'preferred' | 'normal' | 'last-resort';
+}
+
 export interface Tool<TInput = unknown> {
   /** 工具名，必须和 kakadeai 一致：'Read' / 'Edit' / 'Write' / 'Glob' / 'Grep' */
   name: string;
@@ -469,6 +668,13 @@ export interface Tool<TInput = unknown> {
    */
   description: string | (() => string);
 
+  /**
+   * Tool-selection guidance rendered into the system prompt. Built-in tools
+   * must provide it; optionality preserves compatibility with third-party
+   * plugins, whose first description sentence is used as a fallback.
+   */
+  promptGuide?: ToolPromptGuide;
+
   /** Zod schema：模型返回的 arguments JSON 会用它校验和解析 */
   inputSchema: z.ZodType<TInput>;
 
@@ -490,6 +696,10 @@ export interface Tool<TInput = unknown> {
   /** 输出超过这个字符数会被截断（防止把巨大文件灌进上下文） */
   maxResultSizeChars?: number;
 
+  /** Declarative host gates. Omitted means available in every mode/surface. */
+  availableInModes?: import('./runtime/agentRuntimeContext.js').ConversationMode[];
+  availableOnSurfaces?: import('./runtime/agentRuntimeContext.js').AgentSurface[];
+
   /** Synchronous host/runtime probe used before the tool is shown to the model. */
   resolveAvailability?(
     runtime: import('./runtime/agentRuntimeContext.js').AgentRuntimeContext,
@@ -518,7 +728,12 @@ export interface Tool<TInput = unknown> {
   gateRequest?(
     input: TInput | undefined,
     context: ToolCallContext,
-  ): Partial<Pick<import('./toolGate.js').ToolGateRequest, 'isReadOnly' | 'runContext' | 'action'>>;
+  ): Partial<
+    Pick<
+      import('./toolGate.js').ToolGateRequest,
+      'isReadOnly' | 'runContext' | 'action'
+    >
+  >;
 
   /**
    * 真正干活的函数。
@@ -550,16 +765,10 @@ export interface ToolAvailability {
 //   MINIMAL_AGENT_PROVIDER   - 友好名称（可选，默认 "env"）
 //   MINIMAL_AGENT_CONTEXT_WINDOW - 上下文窗口（可选，默认 128000）
 
-export interface Provider {
+interface ProviderCommon {
   /** 友好名（仅展示用），如 "deepseek" */
   name: string;
 
-  /** API 完整端点 URL，如 "https://api.deepseek.com/v1/chat/completions" */
-  baseURL: string;
-
-  /** API key（敏感信息，用户自己填） */
-  apiKey: string;
-
   /** 模型 id，如 "deepseek-chat" */
   model: string;
 
@@ -603,7 +812,91 @@ export interface Provider {
    * 保守地不给可能非视觉的端点发图（免触发 400），并优雅降级（不截、不假装核验）。
    */
   supportsVision?: boolean;
+  /** Explicit provider declaration for reliable native JSON Schema output. */
+  supportsJsonSchema?: boolean;
   promptCache?: PromptCacheConfig;
+
+  /**
+   * 是否对 Anthropic 格式端点启用 cache_edits 式回收（对齐 kakadeai Cached MC）。
+   *
+   * **为什么默认关闭**：`cache_edits` content block（edits: [{type:'delete', cache_reference}]）
+   * 不在 Anthropic 公开 Messages API 文档里（2023-06-01 版协议无此字段）——kakadeai 主项目
+   * 依赖其自建网关（Mycro）的服务端 KV 原地编辑能力。对着不支持的自定义/官方端点发送
+   * 未知 block 类型会 400。仅当 baseURL 指向支持该协议的网关时显式开启。
+   *
+   * 开启后（须同时 apiFormat === 'anthropic'）：
+   *  - reclaimOldToolResults 进入 cacheEdits 模式：**本地 history 不再被改写**，
+   *    回收决策只记入 pending 删除清单（CacheEditsState）。
+   *  - anthropicFormat 请求组装时发送 cache_edits block，服务端在 KV 缓存内原地
+   *    删除这些 tool_result——模型实际看到的上下文变短，但前缀 hash 不变、
+   *    缓存命中完整保留（这是与 inline 占位符模式的本质区别）。
+   *  - wire 上完整内容仍然发送（省的是服务端 KV 驻留与模型注意力窗口，不是请求体积）。
+   */
+  cacheEdits?: boolean;
+}
+
+/** Direct local provider descriptor. Vendor endpoint and key exist only here. */
+export interface LocalProvider extends ProviderCommon {
+  source?: 'local';
+  /** API 完整端点 URL；仅本地 Provider 可拥有。 */
+  baseURL: string;
+  /** 本地模型 API key。 */
+  apiKey: string;
+}
+
+/** Runtime-only remote descriptor. It intentionally has no vendor endpoint or
+ * vendor credential fields; those exist only inside minimal-server. */
+export interface GatewayProvider extends ProviderCommon {
+  source: 'gateway';
+  remoteModelId: string;
+  gatewayUrl: string;
+  gatewayToken: string;
+  /** Server-enforced upper bound for this remote model. */
+  gatewayMaxToolCategories?: string[];
+  /** Server-provided initial Session selection. */
+  gatewayDefaultToolCategories?: string[];
+  /** Server-declared provider capabilities used for local preflight UX. */
+  gatewayCapabilities?: {
+    vision: boolean;
+    tools: boolean;
+    structuredOutput: boolean;
+  };
+  /** Effective categories for the current turn; retained as the wire-facing
+   * compatibility field while callers migrate to the explicit fields. */
+  gatewayToolCategories?: string[];
+}
+
+export type Provider = LocalProvider | GatewayProvider;
+
+/**
+ * cache_edits 式回收的运行时状态（Anthropic 格式 + provider.cacheEdits 开启时使用）。
+ *
+ * 放在 types.ts 而非 context/ 或 llm/ 的原因：context 层（microCompactLite，决策方）
+ * 与 llm 层（anthropicFormat，协议组装方）都要消费，放中立位置避免反向依赖。
+ *
+ * **下标稳定性契约**：pinned[].userMessageIndex 是 toAnthropicMessages() 翻译后数组
+ * 的下标。该契约依赖两个事实：history append-only（compact 时必须 resetCacheEdits），
+ * 且 toAnthropicMessages 是纯函数（同一份 history 翻译结果恒定）。旧消息的翻译后
+ * 下标因此跨轮稳定——cache_edits block 每轮必须重发在**原位置**，否则请求前缀
+ * 变化会破坏它本要保护的缓存（服务端无状态，指令须随每个请求重申）。
+ */
+export interface CacheEditsState {
+  /** 已标记删除的 tool_call_id 集合（幂等：重复标记自动忽略） */
+  deletedToolIds: Set<string>;
+  /** 已 pin 的编辑批次：每轮请求在原 userMessageIndex 位置重发的删除指令 */
+  pinned: Array<{ userMessageIndex: number; toolUseIds: string[] }>;
+  /** 本轮新增、尚未随请求发送过的删除目标（发送即清空，发送后转入 pinned） */
+  pendingNew: string[];
+  /**
+   * 当前有效删除量（token 估算）：服务端已删除、但本地 history 里仍完整存在的
+   * 工具结果内容的 token 总量。用于校正 autoCompact 的本地估算判据--cacheEdits
+   * 模式下 history 不瘦身，countMessagesTokens 会把这些已删内容重复计入，判据
+   * 虚高会导致压缩过早触发（压缩本身会重建整个前缀缓存，抵消 cacheEdits 的收益）。
+   *
+   * 生命周期：随每批删除累加；resetCacheEdits（compact/snip 后）清零--历史被
+   * 重写后旧账对应的已删内容可能已不在新历史里，继续减会过度校正。
+   */
+  activeDeletedTokens: number;
 }
 
 export type PromptCacheMode = 'auto' | 'session-key' | 'disabled';
@@ -694,6 +987,9 @@ export type LlmStreamEvent =
       /** 数组增量（reasoning_details） */
       items?: unknown[];
     }
+  /** Provider usage may arrive before the terminal event (not persisted in history). */
+  | { type: 'usage'; promptTokens?: number; outputTokens?: number }
+  // TurnResourceUsage 的定义在文件末尾附近（与 LoopEvent 同区），此处只是引用。
   /**
    * 流结束。
    *
@@ -716,6 +1012,17 @@ export type LlmStreamEvent =
       type: 'done';
       stopReason: 'stop' | 'tool_calls' | 'length' | 'unknown' | 'aborted';
       promptTokens?: number;
+      /**
+       * 本轮**真实**输出 token 数（OpenAI `completion_tokens` / Anthropic `output_tokens`）。
+       *
+       * 与 promptTokens 同一条纪律：**provider 不报就是 undefined，绝不填 0**。
+       * 填 0 会被上层预算刻度读成「这轮没花钱」，于是预算闸永远不触发 ——
+       * 那比没有预算更危险，因为它看起来在工作。
+       *
+       * 用途：喂给回合级资源账本（`TurnResourceUsage`），再由 Goal 的轮次边界预算闸消费。
+       * ⚠️ 它**不参与**自动压缩判定 —— 压缩只看 prompt 侧。
+       */
+      outputTokens?: number;
       cachedPromptTokens?: number;
       cacheMissTokens?: number;
       cacheWriteTokens?: number;
@@ -780,6 +1087,35 @@ export interface ToolStatusState {
   progressDetail?: ToolProgressDetail;
 }
 
+/**
+ * 一个**用户回合**（不是一个 TAOR 迭代）累计消耗的资源。
+ *
+ * 语义边界，改之前先读：
+ *  - 「一回合」= 从用户输入到模型不再调工具为止，中间可能有几十次 LLM 请求。
+ *  - 它是**账本**不是闸门。loop 只负责记账，**绝不因为它中断进行中的工具循环** ——
+ *    预算判定一律发生在「要不要开新一轮」的边界上（goal / ralph-loop 这类多轮工作流
+ *    在循环开头调 `budget()`）。这条是产品决策：宁可超一点预算，也不能把 agent
+ *    停在半成品状态。
+ *
+ * ⚠️ **消费前必须先看 `trustworthy`**。不是所有 provider 都回报 usage
+ * （OpenAI 需要 `stream_options.include_usage`，部分兼容实现直接不发）。
+ * 少报会让预算闸永远不触发 —— 那比没有预算更危险，因为它看起来在工作。
+ * 所以这里如实区分「真的是 0」与「没人告诉我」：不报的调用不计入，
+ * 由 `reportedCalls / totalCalls` 暴露这份账本的覆盖率。
+ */
+export interface TurnResourceUsage {
+  /** 累计输入 token（仅统计真实报告了 usage 的那些调用）。 */
+  inputTokens: number;
+  /** 累计输出 token（同上）。 */
+  outputTokens: number;
+  /** 本回合发出的 LLM 请求总数。 */
+  totalCalls: number;
+  /** 其中真实回报了 usage 的次数。 */
+  reportedCalls: number;
+  /** `totalCalls > 0 && reportedCalls === totalCalls` —— 只有全报了才算这份账可信。 */
+  trustworthy: boolean;
+}
+
 export type LoopEvent =
   /** 文本流（同 LlmStreamEvent.text_delta） */
   | { type: 'text'; delta: string }
@@ -792,9 +1128,24 @@ export type LoopEvent =
    * <Static> 直到整轮落定才一次性 commit「用户消息+reasoning+答案」，用户输入无法第一时间置顶。
    * UI 收到此事件立即 bump，让 <Static> 马上把用户消息 commit 进 scrollback（符合 T-A-O-R 顺序）。
    */
-  | { type: 'user_message_committed'; message?: Extract<Message, { role: 'user' }> }
+  | {
+      type: 'user_message_committed';
+      message?: Extract<Message, { role: 'user' }>;
+    }
   /** 一轮 assistant 消息已完整组装（含可能的 tool_calls） */
-  | { type: 'assistant_message'; message: Extract<Message, { role: 'assistant' }> }
+  | {
+      type: 'assistant_message';
+      message: Extract<Message, { role: 'assistant' }>;
+    }
+  /**
+   * 模型已经流出了一份正文/思考草稿，但宿主确定它还不能成为本轮回答。
+   * 消费方应清掉 live 草稿；该草稿不会写入会话 history。
+   */
+  | {
+      type: 'assistant_draft_discarded';
+      reason: 'formal_delivery' | 'advisor_checkpoint' | 'empty_response';
+      textLength: number;
+    }
   /**
    * 主循环在工具结果之后注入的「带外上下文消息」（当前用于浏览器关键节点实况截图回填）。
    * 宿主收到后应把它当作一条消息追加进对话展示；模型也会在下一轮看到它（已 push 进 history）。
@@ -871,8 +1222,25 @@ export type LoopEvent =
   /** 整轮交互结束（模型不再调工具） */
   | {
       type: 'turn_done';
-      completionStatus?: 'completed' | 'delivery_incomplete' | 'delivery_unverified' | 'claims_unverified';
+      completionStatus?:
+        | 'completed'
+        | 'delivery_incomplete'
+        | 'delivery_unverified'
+        | 'claims_unverified';
       warning?: string;
+      /** 本回合的资源账本。见 TurnResourceUsage —— 消费方务必先看 `trustworthy`。 */
+      usage?: TurnResourceUsage;
+      /**
+       * 托管运行时（`meta.managedRuntime`，目前只有 goal）的生命周期状态。
+       *
+       * ⚠️ 它与 `completionStatus` 回答的**不是同一个问题**，别合并：
+       *   · completionStatus = 模型宣称的事做没做（交付判定）
+       *   · managedStatus    = 这件事**有没有被人验收**（生命周期事实源）
+       * `completionStatus:'completed'` + `managedStatus:'ready_for_acceptance'`
+       * 是正常且重要的组合：机器自检通过，但还没有人点头。
+       * 取值与映射见 `src/goal/statusMapping.ts`。
+       */
+      managedStatus?: string;
     }
   /**
    * 中断事件
@@ -885,16 +1253,28 @@ export type LoopEvent =
    *
    * code（v2.x 新增，可选）：让 `-p --output-format json` 把终结原因映射成稳定的
    * stop_reason，也让 print.ts 区分"致命错误（退出）"与"非致命警告（继续）"：
-   *   - 'llm_error'      LLM 调用失败 → 终结，stop_reason='error'
-   *   - 'max_turns'      撞最大轮数上限 → 终结，stop_reason='max_turns'
-   *   - 'compact_failed' 自动压缩失败但 loop 想继续 → 非致命，print.ts 只 stderr 警告不退出
-   *   - 'aborted'        被中断（signal.aborted）
+   *   - 'llm_error'        LLM 调用失败 → 终结，stop_reason='error'
+   *   - 'max_turns'        撞最大轮数上限 → 终结，stop_reason='max_turns'
+   *   - 'compact_failed'   自动压缩失败但 loop 想继续 → 非致命，print.ts 只 stderr 警告不退出
+   *   - 'aborted'          被中断（signal.aborted）
+   *   - 'stalled'          StallGuard 判定原地打转（同一失败反复 / 整批调用无进展）
+   *                        → 终结，stop_reason='stalled'
+   *   - 'context_overflow' 即使降级后仍超模型输入上限，主动不发这次请求
+   *                        → 终结，stop_reason='error'
    * 缺省（旧调用方 / 未分类错误）按致命、stop_reason='error' 处理。
+   * ⚠️ 增删 code 时同步改 print.ts 的映射：那里只特判 max_turns / stalled，
+   * 其余一律落 'error'，新增的终结原因不特判就会被并进通用 error。
    */
   | {
       type: 'error';
       error: string;
-      code?: 'llm_error' | 'max_turns' | 'compact_failed' | 'aborted' | 'stalled' | 'context_overflow';
+      code?:
+        | 'llm_error'
+        | 'max_turns'
+        | 'compact_failed'
+        | 'aborted'
+        | 'stalled'
+        | 'context_overflow';
     }
   /**
    * 非致命警告：需冒泡给用户但不终止执行。
@@ -923,6 +1303,23 @@ export type LoopEvent =
       max?: number;
       message?: string;
     }
+  | {
+      type: 'workflow_progress';
+      workflow: string;
+      runId: string;
+      rootRunId: string;
+      parentRunId?: string;
+      depth?: number;
+      phase: string;
+      status: 'start' | 'update' | 'complete' | 'warning';
+      current?: number;
+      total?: number;
+      succeeded?: number;
+      failed?: number;
+      message?: string;
+      queuedMs?: number;
+      elapsedMs?: number;
+    }
   /**
    * 思维链流式片段。
    *
@@ -953,8 +1350,19 @@ export type LoopEvent =
    * 让远程通道（webchat / 网关）收到问题、渲染选择、把答案经 stdin 的 `ask_answer` 回灌。
    * requestId 用于关联问题与答案（一轮内可多次提问）。
    */
-  | { type: 'ask'; requestId: string; questions: AskQuestionSpec[]; source?: AskSource }
+  | {
+      type: 'ask';
+      requestId: string;
+      questions: AskQuestionSpec[];
+      source?: AskSource;
+    }
   /** 问题在本回合所有者队列中的状态；不写入 Session 历史。 */
-  | { type: 'ask_status'; source: AskSource; state: AskQueueState; queuePosition?: number; queuedCount?: number };
+  | {
+      type: 'ask_status';
+      source: AskSource;
+      state: AskQueueState;
+      queuePosition?: number;
+      queuedCount?: number;
+    };
 // 注：插件私有事件（如 workflow-runner 的 workflow_*）不再写在这里。
 // 插件通过 PluginEvent 开放契约 yield 任意 type 字符串的事件，UI 静默忽略未识别项。