@tencent-ai/agent-harness 0.2.0-beta.1 → 0.2.0-beta.3

package/cli/dist-server/types/node/acp/acp-protocol.d.ts

@@ -3,13 +3,12 @@ import type { Agent, AgentSideConnection, AuthenticateRequest, AuthenticateRespo
 import type { Deferred } from '@celljs/core';
 import type { ModelInfo, SetSessionModelRequest, SetSessionModelResponse } from '../../workspace/agent-client-protocol/lib/common/index.js';
 import type { CheckpointBroadcastEvent, CheckpointBroadcastInfo } from '../../workspace/cbc-checkpoint/lib/node/index.js';
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { PermissionMode, RunToolApprovalItem } from '../../vendor/cbc-shared/node/index.js';
 import type { W3CTraceContextMeta } from '../../workspace/telemetry/lib/common/index.js';
 import type { Subject } from 'rxjs';
-import type { RunToolApprovalItem } from '../../vendor/cbc-shared/node/index.js';
 import type { CommonRequest } from '../loopback/server-protocol';
 import type { McpFirstRunStatusEvent } from '../mcp/mcp-first-run-status-protocol';
-import type { Session } from '../../vendor/cbc-core/node/index.js';
-import type { PermissionMode } from '../../vendor/cbc-shared/node/index.js';
 export * from './acp-kernel-protocol';
 /**
  * 上下文消耗 5 类目细拆 schema。
@@ -409,9 +408,26 @@ export interface AcpBroadcastService {
  * scopeId / createdAt 等实现细节给前端。
  */
 export interface GoalRecapPayload {
+    /**
+     * 本次 recap 的生成时间：宿主用它区分「新一次查询」与「同一条重复下发」
+     * （关掉后同一次不再弹；再问一次 /goal 会拿到新的 at，应该重新弹）。
+     */
+    at?: number;
+    /**
+     * 进行中目标的状态：除条件 / 暂停态外，带上无参 /goal 要展示的详细项
+     * （运行时长 / 评估 turn 数 / Token 消耗 / 最近一次评估原因）。
+     */
     active?: {
         condition: string;
         paused?: boolean;
+        /** 已运行时长（暂停态冻在 pausedAt）。 */
+        durationMs?: number;
+        /** 已评估轮次（Stop hook 评估次数）。 */
+        turnCount?: number;
+        /** 目标期间累计消耗的 token（当前会话用量 - 目标起点用量）。 */
+        tokenDelta?: number;
+        /** 最近一次 Stop hook 的评估原因（goal-progress 项的 reason）。 */
+        reason?: string;
     };
     latest?: {
         ok: boolean;
@@ -764,6 +780,17 @@ export declare const ACP_CANCEL_REASON_TOOL_CALL_LOOP_STOPPED: "tool_call_loop_s
 /** `codebuddy.ai/interceptType` 取值：疑似工具调用循环，请用户决定继续还是停止。 */
 export declare const TOOL_CALL_LOOP_INTERCEPT_TYPE: "tool-call-loop";
 export declare const ACP_META_SENSITIVE_INPUT_DECISION: "codebuddy.ai/sensitiveInputDecision";
+/**
+ * `_codebuddy.ai/goalControl` 扩展方法名（宿主目标控制通道）。
+ *
+ * 必须与 workbuddy-core 的 `ConversationAcpMethod.GoalControl` 完全一致。
+ *
+ * 常量放在协议面而不是 acp-goal-control（控制实现）里：acp-stream-manager 只需要这个
+ * 字符串来判定 unary JSON 交付，若从实现文件取，冷启动链就会静态挂上整个控制实现
+ * （GoalService / broadcast / SDK 面），实现里任何新 import 都会静默落到 standby
+ * 冷启动路径上 —— bundle-lite-wb-prewarm-memory 卡点就是这么被顶穿的。
+ */
+export declare const GOAL_CONTROL_METHOD: "_codebuddy.ai/goalControl";
 /**
  * Cancel 事件
  * 用于 AcpAgent 向 AcpView 传递取消指令
@@ -947,22 +974,23 @@ export interface AcpAgentManager {
  *   事件触发，**会被 250ms 节流合并**，避免高频累加 usage 时刷屏。
  * - 其它来源全部**立即推送**（绕过节流）：
  *   - `'new_session'` / `'load_session'` / `'resume_session'`：首发，让客户端在第一帧就拿到 0% / 模型 size
+ *   - `'prompt_start'`：prompt 刚开始、模型思考/写文件尚未返回真实 usage 的窗口，用本地估算
+ *     的输入 token 推一帧占位（used 估算 + byCategory），避免上下文环空白；随后由 stream/prompt_end 校准
  *   - `'prompt_end'`：prompt 出口（无论 stopReason），保证终值正确
+ *   - `'compacted'`：压缩（自动/手动）完成后立即推一帧（used = 压缩后 history 估算），环即刻降到新值
+ *     而非等下一轮 prompt；publisher 同时重置 turn 高水位，使这次真实下降不被单调约束挡住
  *   - `'model_changed'`：分母切换
  *   - `'cancel'`：用户取消快照
  *
- * compact 完成不再触发 `usage_update`；上下文环数值由用户下一次 prompt 走
- * `combineSubject(input)` 节流路径自然回填真实 inputTokens。
- *
  * usageByCategory 触发拍：
- * - `ACP_USAGE_CATEGORY_SNAPSHOT_SOURCES` 中的路径在推送时附带
+ * - `ACP_USAGE_CATEGORY_SNAPSHOT_SOURCES` 中的路径走**全量**计算并附带
  *   `_meta['codebuddy.ai/usageByCategory']`，sum(usageByCategory) 严格 === update.used。
- * - `'stream'` / `'model_changed'` 路径**不写**该字段，客户端复用上一次缓存值；
- *   model_changed 只同步新的 context size，避免派生统计重跑动态 agent instructions
- *   并阻塞 set_model 控制 RPC。下一次 prompt_end 会刷新 category。
+ * - `'stream'` 路径走**turn 级增量**（见 usage-by-category-incremental），同样附带 usageByCategory，
+ *   让「对话进行中」也能实时展示 5 类明细，且不重跑动态 agent instructions（规避控制面阻塞）。
+ * - `'model_changed'` 路径**不写**该字段（只同步 context size），客户端复用上次缓存，下次 prompt_end 全量校准。
  * - calculator 计算异常时 publisher 也不写该字段（降级），不影响 used/size/cost 推送。
  */
-export type AcpUsageUpdateSource = 'new_session' | 'load_session' | 'resume_session' | 'prompt_end' | 'model_changed' | 'cancel' | 'stream';
+export type AcpUsageUpdateSource = 'new_session' | 'load_session' | 'resume_session' | 'prompt_start' | 'prompt_end' | 'compacted' | 'model_changed' | 'cancel' | 'stream';
 /**
  * 附带 `usageByCategory` 语义快照的推送来源（排除语义见上方
  * `AcpUsageUpdateSource` 注释）。publisher 与其 spec 共用此唯一事实源；
@@ -1007,7 +1035,7 @@ export interface AcpUsagePublisher {
      * 方案 Z（终版决议，2026-05-20）：移除 options.hintUsed 参数 —— compact 完成路径不
      * 再主动推送，由下次 prompt 走 combineSubject(input) 自然回填真实 inputTokens。
      */
-    publish(sessionId: string, source: AcpUsageUpdateSource, carrier?: W3CTraceContextMeta): Promise<void>;
+    publish(sessionId: string, source: AcpUsageUpdateSource, carrier?: W3CTraceContextMeta, pendingInputText?: string): Promise<void>;
     /**
      * 推送生成工具实际消耗。调用方只提供工具执行事实，publisher 统一复用
      * ACP usage_update.cost.amount 链路，并在内部做 session / stageId 幂等。

package/cli/dist-server/types/node/acp/usage-by-category-calculator.d.ts

@@ -40,6 +40,27 @@ export interface UsageByCategoryInput {
     /** ACP usage_update.used，作为最终归一化的总分母。 */
     totalTokens: number;
 }
+export declare const IMAGE_TOKEN_PER_PIECE = 85;
 export declare class UsageByCategoryCalculator {
     static compute(input: UsageByCategoryInput): UsageByCategory;
 }
+export declare function zeroUsageByCategory(): UsageByCategory;
+/**
+ * 单条 history item 对 systemPrompt / conversation / 图片张数的字符贡献。
+ *
+ * SSOT：全量 `compute` 与增量 publisher 共用本函数，保证「进行中增量」与
+ * 「prompt_end 全量」的类目结果严格一致（`weighted` 逐字符可加，item 边界不切
+ * 代理对，故 `weighted(Σparts) === Σ weighted(part)`）。
+ *
+ * - systemPrompt 贡献：仅 user message 的 hidden context block 第一个子 section
+ *   （UserInfoSection 等价物）；解析失败/无 hidden block 时为空，整条 user 文本
+ *   由 conversation 承接。
+ * - conversation 贡献：user/assistant 文本（user 去掉第一个 hidden section）
+ *   + function_call 的 JSON.stringify + function_call_result 的 output 文本。
+ * - 图片不计字符权重，按张数单独累加（由调用方 ×IMAGE_TOKEN_PER_PIECE）。
+ */
+export declare function collectHistoryItemChars(item: unknown): {
+    systemPromptChars: string;
+    conversationChars: string;
+    imagePieces: number;
+};

package/cli/dist-server/types/node/bash-sandbox/bash-sandbox-protocol.d.ts

@@ -33,6 +33,7 @@ export declare function resolveProgramBlacklistForPlatform(configuredPrograms: r
  * Bash 沙箱配置接口
  * 基于 SandboxRuntimeConfig,添加了额外的 CLI 特定配置
  */
+export type MacOSUnlinkPolicy = 'allow' | 'ask' | 'deny';
 export interface SandboxConfig {
     /** 是否启用沙箱 */
     enabled?: boolean;
@@ -98,6 +99,8 @@ export interface SandboxConfig {
     systemToolPolicy?: SystemToolPolicy;
     /** 实验功能：工作空间内文件版本管理 */
     versionControl?: boolean;
+    /** macOS 非白名单直接 unlink 的自动兜底动作；历史缺省为 ask。 */
+    macosUnlinkPolicy?: MacOSUnlinkPolicy;
     /** 实验功能：工作空间内删除进回收站 */
     deleteProtection?: boolean;
     /** 实验功能：运行时删除回收站保护（Node/Python/Git Bash 注入） */

package/cli/dist-server/types/node/cli/cli-protocol.d.ts

@@ -2,6 +2,9 @@ import { Command } from 'commander';
 export declare const CliDispatcher: unique symbol;
 export declare const CliProvider: unique symbol;
 export declare const DispatchStrategy: unique symbol;
+/** Request-local controller/view handoff; never part of a wire message or Session. */
+export declare const STREAM_JSON_RUN_RESULT = "codebuddy.streamJsonRunResult";
+export declare const STREAM_JSON_COMPLETED_REQUEST = "codebuddy.streamJsonCompletedRequest";
 export interface CliDispatcher {
     dispatch(): Promise<void>;
 }

package/cli/dist-server/types/node/cli/stream-json-protocol.d.ts

@@ -270,6 +270,20 @@ export interface ResultUsageExtension {
     modelUsage?: Record<string, ModelUsage>;
     _meta?: Record<string, unknown>;
 }
+/**
+ * 这一轮为什么结束，取值对齐 Claude Code 的 `terminal_reason`。
+ *
+ * 目前只在被取消的一轮上给出：
+ * - `aborted_streaming`：中止时没有未完成的工具调用（停在模型输出上）；
+ * - `aborted_tools`：中止时还有工具调用没执行完。
+ *
+ * 取消不是错误，所以取消的终态是 `subtype=success`、`is_error=false`，
+ * 消费方要靠这个字段把它与正常完成区分开，不要去匹配任何文案。
+ */
+export type TerminalReason = 'aborted_streaming' | 'aborted_tools';
+export interface ResultTerminalExtension {
+    terminal_reason?: TerminalReason;
+}
 /** Mirrors the Claude Agent SDK's SDKPermissionDenial (E20 alignment gate). */
 export interface PermissionDenial {
     tool_name: string;
@@ -433,7 +447,14 @@ export type ResultMessage = ({
      * - 字段全部可选：`status` (HTTP 状态码)、`code` (SDK/业务码)、`category`
      *   (与 acp-agent.ts `classifyErrorAsRequestError` 分类对齐)、`details` (脱敏文案)。
      *
-     * 详见 `result-message-utils.ts` 的 `buildErrorsInfo` / `extractStructuredErrorInfo`。
+     * 例外（`is_error: true` 的终态）：抛出物本身没有文案时（裸 `throw`、空 message 的
+     * `Error`、无 message 的对象），该槽位不再是 `null`，而是带
+     * `code: 'cbc_empty_error'` + 兜底 `details`。否则 `errors[i]` 与 `errors_info[i]`
+     * 同时为空，下游 `BuildErrorMessageFromCLIErrors` 会整条丢掉错误 `_meta`，
+     * 终态在观测侧退化为不可归因的 `stop_reason=refusal` + `error=""`。
+     *
+     * 详见 `result-message-utils.ts` 的 `buildErrorTerminalFields` /
+     * `buildErrorsInfo` / `extractStructuredErrorInfo`。
      */
     errors_info?: Array<{
         status?: number;
@@ -441,7 +462,7 @@ export type ResultMessage = ({
         category?: string;
         details?: string;
     } | null>;
-}) & ResultUsageExtension;
+}) & ResultUsageExtension & ResultTerminalExtension;
 type ApiKeySource = string;
 export interface SystemMessage {
     type: 'system';

package/cli/dist-server/types/node/data-fs/index.d.ts

@@ -38,6 +38,9 @@ export interface FileSystem {
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
     exists(path: string): Promise<boolean>;
     stat(path: string): Promise<FileSystemStat>;
+    /** Optional metadata for filesystems that can identify linked paths. */
+    lstat?(path: string): Promise<FileSystemStat>;
+    realpath?(path: string): Promise<string>;
     mkdir(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
@@ -82,6 +85,8 @@ export interface DataFs {
         withFileTypes: true;
     }): Promise<DataFsDirent[]>;
     stat(path: string): Promise<DataFsStats>;
+    lstat?(path: string): Promise<DataFsStats>;
+    realpath?(path: string): Promise<string>;
     rm(path: string, options?: {
         recursive?: boolean;
         force?: boolean;
@@ -141,7 +146,14 @@ export interface ScannedFile {
     fileName: string;
     relativePath: string;
 }
-export declare function scanFilesByExtension(baseDir: string, extension: string, maxDepth?: number): Promise<ScannedFile[]>;
+export interface ScanFilesOptions {
+    maxEntries?: number;
+    onError?: (error: Error, path: string) => void;
+    signal?: AbortSignal;
+    /** Filesystems with link metadata can supply realpath for cycle and alias detection. */
+    canonicalizeDirectory?: (path: string) => Promise<string>;
+}
+export declare function scanFilesByExtension(baseDir: string, extension: string, maxDepth?: number, options?: ScanFilesOptions): Promise<ScannedFile[]>;
 /**
  * Wrap a config-face filesystem into the node:fs/promises-shaped provider:
  * Stats/Dirent booleans become methods, Uint8Array becomes Buffer, errno

package/cli/dist-server/types/node/hooks/hook-protocol.d.ts

@@ -2,6 +2,7 @@
  * Hook mechanism protocol definitions
  * Compatible with Claude Code hooks specification
  */
+import type { HookInput } from '../../vendor/cbc-core/node/index.js';
 import { HookEvent, type HookExecutionOptions, type HookExecutionResult, type PromptHookResult } from '../../vendor/cbc-shared/node/index.js';
 export { HookBlockedError, HookEvent, NotificationType } from '../../vendor/cbc-shared/node/index.js';
 export type { BackgroundTaskInfo, CronTaskInfo, FinalStopReason, HookBlockingDetail, HookExecutionOptions, HookExecutionResult, HookOutput, HookPermissionMode, PromptHookResult, SessionEndReason, SessionStartSource, } from '../../vendor/cbc-shared/node/index.js';
@@ -240,8 +241,7 @@ export type HookDefinition = CommandHookDefinition | PromptHookDefinition | Agen
  * Input data passed to hook script via stdin
  * Format matches Claude Code hooks specification exactly
  */
-export type { HookInput } from "../../vendor/cbc-core/node/index.js";
-import type { HookInput } from "../../vendor/cbc-core/node/index.js";
+export type { HookInput } from '../../vendor/cbc-core/node/index.js';
 /**
  * Hook Manager interface
  */

package/cli/dist-server/types/node/sensitive-content/sensitive-content-protocol.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxRuleContext } from '../../workspace/agent-client-protocol/lib/common/index.js';
 export declare const SensitiveDecisionMediation: unique symbol;
 export declare const SensitiveContentMediation: unique symbol;
 export declare const SensitiveToolEgressGuard: unique symbol;
@@ -245,6 +246,11 @@ export type SensitiveDetectionOutcome = {
 } | {
     kind: 'detected';
     detectionRef: string;
+    ruleContext?: SandboxRuleContext;
+    ruleMatches?: Array<{
+        plaintext: string;
+        ruleContext: SandboxRuleContext;
+    }>;
     plaintexts: string[];
     /** 无可用密文条目的命中，仅作疑似提示展示，不参与加密/替换。 */
     unprotectablePlaintexts?: string[];
@@ -291,6 +297,7 @@ export interface SandboxCenterPort {
 export interface SensitiveApprovalPort {
     requestApproval(request: {
         detectionRef: string;
+        ruleContext?: SandboxRuleContext;
         direction: SensitiveReviewRequest['direction'];
         source: SensitiveReviewRequest['source'];
         allowedChoices: SensitiveApprovalChoice[];

package/cli/dist-server/types/node/server/boot.d.ts

@@ -1,15 +1,18 @@
 import 'reflect-metadata';
 import type { ProductConfiguration } from '../../workspace/product/lib/common/index.js';
+declare module '@celljs/core/lib/common/container/dynamic-container' {
+    function createContainer(): Promise<import('@celljs/core').Container>;
+}
 /**
- * Lazy 单次 boot；幂等。首个 start()/verb 驱动（ensureStarted 收口）。
+ * 每次生命周期内惰性且幂等。首个 start()/verb 驱动（ensureStarted 收口）。
  * boot 失败即出队：best-effort 释放半装配态后清缓存，下一次调用真重试——
  * rejected promise 常驻会把一次瞬时失败固化成进程终身拒绝（lamp 毒 pod
  * 判例：boot 崩一次后每个会话都撞 already-started，pod 成毒丸）。
  */
 export declare function ensureBoot(product?: ProductConfiguration): Promise<void>;
 /**
- * stop() 收尾的容器释放：Application.stop() 生命周期 + unbindAllAsync 归还
- * 内存给嵌入宿主。runtime 维持已停终态（verbs 继续按 stopped 拒绝）；释放
- * 失败不阻断关停。
+ * stop() 收尾：Application.stop() → unbindAllAsync → Effect.dispose。
+ * 成功后可由新的显式 start() 构造全新容器；失败仍尝试全部阶段，但拒绝
+ * 再次 boot，避免旧 finalizer 与新实例共享进程级适配器。
  */
 export declare function releaseContainer(): Promise<void>;

package/{lib/components → cli/dist-server/types/node/server/formats}/acp/acp-error-model.d.ts

@@ -1,4 +1,4 @@
-import { type PromptResponse, RequestError } from '@agentclientprotocol/sdk';
+import { type PromptResponse, RequestError } from '@agentclientprotocol/sdk-server';
 export declare const CODEBUDDY_ERROR_META_KEY = "codebuddy.ai/error";
 export declare const CODEBUDDY_ERROR_UPDATE_TYPE = "_codebuddy.ai/error";
 /**

package/{lib/components → cli/dist-server/types/node/server/formats}/acp/acp-protocol.d.ts

@@ -1,6 +1,5 @@
-export type * from '@agentclientprotocol/sdk';
-export type { AcpClientChannel } from './acp-client-channel.js';
-export type { McpUiBroadcastPayload, ModelInfo } from '../../../cli/dist-server/types/node/acp/acp-protocol.js';
+export type * from '@agentclientprotocol/sdk-server';
+export type { McpUiBroadcastPayload, ModelInfo } from '../../../acp/acp-protocol';
 export interface AcpConnectionProfile {
     endpoint: 'canonical' | 'compatibility';
     compatibilityExtensions: boolean;

package/cli/dist-server/types/node/server/formats/acp/index.d.ts

@@ -0,0 +1,12 @@
+import type { FormattedSessionEvent, SessionSourceEvent } from '../../types';
+/** Protocol presentation only. The Server remains the owner of run settlement. */
+export declare class AcpSessionFormatter {
+    private readonly version;
+    private readonly lanes;
+    private readonly compactions;
+    private readonly streamedV1Messages;
+    constructor(version: 'acp-v1' | 'acp-v2');
+    format(source: SessionSourceEvent): Promise<FormattedSessionEvent<'acp-v1' | 'acp-v2'>[]>;
+    private wrap;
+    private model;
+}

package/cli/dist-server/types/node/server/formats/acp/projection.d.ts

@@ -0,0 +1,10 @@
+import type { SessionNotification } from '@agentclientprotocol/sdk-server';
+import type { UpdateSessionNotification } from '@agentclientprotocol/sdk-server/experimental/v2';
+import type { AgentInputItem } from '../../../../vendor/cbc-shared/node/index.js';
+import type { AgentEvent } from '../../types';
+export declare function itemNotifications(sessionId: string, item: AgentInputItem, replay: boolean, readFile?: (path: string) => Promise<Uint8Array>): Promise<SessionNotification[]>;
+/** Live complete items and replay share content, tool and identity projection. */
+export declare const projectAgentItem: (sessionId: string, item: AgentInputItem) => Promise<UpdateSessionNotification[]>;
+/** Reuse the CLI's ACP extension vocabulary; the Agent only exports kernel facts. */
+export declare const projectNativeEvent: (frame: AgentEvent) => Promise<SessionNotification[]>;
+export declare function projectAgentEvent(frame: AgentEvent): Promise<UpdateSessionNotification[]>;

package/cli/dist-server/types/node/server/index.d.ts

@@ -15,7 +15,7 @@ export { start } from './start';
 export { readSession } from './read-session';
 export { readSessionCatalog } from './read-session-catalog';
 export { createSession } from './create-session';
-export type { ReadSessionCatalogOptions, ReloadOptions, CreateSessionOptions, ConfigChange, NotifyConfigChangeOptions, AgentEvent, AgentDefinition, HookCallback, HookCallbackMatcher, HookEvent, HookInput, HookJSONOutput, QueryHooks, OrphanedExecSettlement, QueryOptions, QueryResult, QueryTicket, QueryInput, ReadSessionOptions, RewindOptions, RewindResult, RunAccount, RunAuth, RunCompletedEvent, RunStartedEvent, Sandbox, SandboxCapabilities, SandboxDriver, SandboxFactory, SandboxFileStat, SandboxShellResult, Server, SessionEvent, SessionCatalog, SessionEventOrigin, SessionEventListener, SessionSubscription, SessionSubscriptionExit, SessionSnapshot, SessionKey, SessionStore, SessionStoreEntry, StartOptions, StopReason, SteerOptions, SteerResult, } from './types';
+export type { ReadSessionCatalogOptions, ReloadOptions, CreateSessionOptions, ConfigChange, NotifyConfigChangeOptions, AgentEvent, AgentDefinition, HookCallback, HookCallbackMatcher, HookEvent, HookInput, HookJSONOutput, QueryHooks, OrphanedExecSettlement, QueryOptions, QueryResult, QueryTicket, QueryInput, ReadSessionOptions, RewindOptions, RewindResult, RunAccount, RunAuth, RunCompletedEvent, RunStartedEvent, Sandbox, SandboxCapabilities, SandboxDriver, SandboxFactory, SandboxFileStat, SandboxShellResult, Server, SessionEvent, FormattedSessionEvent, SessionOutputFormat, SubscribeOptions, NativeSessionEvent, AgentSdkEvent, AcpSessionEvent, SessionCatalog, SessionEventOrigin, SessionEventListener, SessionSubscription, SessionSubscriptionExit, SessionSnapshot, SessionKey, SessionStore, SessionStoreEntry, StartOptions, StopReason, SteerOptions, SteerResult, } from './types';
 export { InMemorySessionStore } from './in-memory-session-store';
 export { WORKBUDDY_TOOLS } from './tool-presets';
 export { InMemoryFs, MountableFs, OverlayFs, ReadWriteFs } from './fs-kit';

package/cli/dist-server/types/node/server/sessions.d.ts

@@ -1,4 +1,9 @@
-import type { QueryInput, QueryOptions, QueryTicket, ReloadOptions, RewindOptions, RewindResult, SessionEventListener, SessionSubscription, SteerOptions, SteerResult } from './types';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import type { FormattedSessionEvent, QueryInput, QueryOptions, QueryTicket, ReloadOptions, RewindOptions, RewindResult, SessionOutputFormat, SessionSubscription, SteerOptions, SteerResult, SubscribeOptions } from './types';
+interface SettleOutcome {
+    assistantText: string;
+    completedError?: unknown;
+}
 /**
  * Submit input or a maintenance operation: creates the session on first touch, resumes it
  * otherwise. The ticket carries the run id synchronously — it is the kernel
@@ -9,6 +14,24 @@ export declare function query(sessionId: string, input: QueryInput, options?: Qu
 export declare function reload(sessionId: string, options?: ReloadOptions): void;
 /** Add input to an existing query. Rejection never creates or activates a session. */
 export declare function steer(sessionId: string, input: string | unknown[], options: SteerOptions): Promise<SteerResult>;
+/**
+ * Settlement discipline (ordered signal): the primary lane subscribes to the
+ * kernel's combine result/interrupt_result events, emitted only AFTER the
+ * run's bookkeeping (error item into history, Stop hooks); retried failures
+ * are suppressed and the recovery run emits its own (#64101, same gate
+ * discipline as stream-json-view). Each result is judged by its stamped
+ * interceptorGate — willRetry (and not __cancelNudge) means not terminal.
+ * interrupt_result settles immediately without awaiting `completed` (it may
+ * never resolve on that path). The completed-promise loop remains as a raced,
+ * stale-aware fallback with a grace window for terminal or pre-dispatch
+ * failures. A gate that promises continuation must instead await an actual
+ * result or ordered interrupt; a pending permission is not a timeout failure.
+ * Never pump the item stream here; the kernel's per-session subscription is
+ * its consumer.
+ */
+export declare function beginSettle(session: Session, isInterrupted: () => boolean): {
+    wait(): Promise<SettleOutcome>;
+};
 /**
  * Turn-level cancellation: the in-flight ticket resolves normally with
  * stopReason 'aborted', never rejects. Resolves after the run state settles.
@@ -23,7 +46,8 @@ export declare function interrupt(sessionId: string): Promise<void>;
  * whose queue exceeds the high-water mark is evicted — recover by
  * re-subscribing and catching up from the session store.
  */
-export declare function subscribe(sessionId: string, listener: SessionEventListener): SessionSubscription;
+export declare function subscribe(sessionId: string, listener: (event: FormattedSessionEvent) => void | Promise<void>): SessionSubscription;
+export declare function subscribe<F extends SessionOutputFormat>(sessionId: string, listener: (event: FormattedSessionEvent<F>) => void | Promise<void>, options: SubscribeOptions<F>): SessionSubscription;
 /**
  * Passivation hint. Optional, and never a terminal state: closing equals an
  * orderly crash, and any verb reactivates the session from storage.
@@ -35,3 +59,4 @@ export declare function close(sessionId: string): Promise<void>;
  * Does not emit a query lifecycle or discard existing subscriptions.
  */
 export declare function rewind(sessionId: string, options: RewindOptions): Promise<RewindResult>;
+export {};

package/cli/dist-server/types/node/server/types.d.ts

@@ -4,8 +4,11 @@
  * docs/cloud-native/agent-cli-server.md): the SessionStore
  * adapter contract, the Sandbox family, and the stream-json event union.
  */
-import type { AgentPhaseInfo, CanUseTool, CombineEvent, SubagentEventReference, SubagentTokenUsageSnapshot, TranscriptStore as SessionStore } from '../../vendor/cbc-core/node/index.js';
-import type { ProductConfiguration } from '../../workspace/product/lib/common/index.js';
+import type { SessionNotification } from '@agentclientprotocol/sdk-server';
+import type { UpdateSessionNotification } from '@agentclientprotocol/sdk-server/experimental/v2';
+import type { AgentPhaseInfo, CanUseTool, CombineEvent, SessionKey, SubagentEventReference, SubagentTokenUsageSnapshot, TranscriptStore as SessionStore } from '../../vendor/cbc-core/node/index.js';
+import type { AgentInputItem, ResponseStreamEvent, RunStreamEvent } from '../../vendor/cbc-shared/node/index.js';
+import type { Command, ProductConfiguration, Skill } from '../../workspace/product/lib/common/index.js';
 import type { RunAccount, RunAuth } from '../authentication/run-context';
 import type { Message } from '../cli/stream-json-protocol';
 import type { FileSystem, InitialFiles } from '../data-fs';
@@ -39,6 +42,7 @@ export interface StartOptions {
      * CODEBUDDY_AUTH_TOKEN / CODEBUDDY_SESSION_SKILL_DIRS）拒绝：凭据只认
      * query options（auth）与 start({ apiKey })。会话级差异走
      * `query({ settings: { env } })`——ALS 会话档，并行 run 各自解析无竞态。
+     * stop 或启动失败后恢复本次覆盖的环境值；宿主期间主动修改的值保留。
      */
     env?: Record<string, string>;
     /** Global SessionStore adapter (SDK shape). Durable events append here on settle. */
@@ -84,6 +88,7 @@ export interface StartOptions {
  * `stop()` drains in-flight work, then disconnects persistence. Supports
  * `await using`; deliberately no synchronous dispose — graceful shutdown is
  * inherently async.
+ * Await successful stop before starting a new runtime in the same process.
  */
 export interface Server {
     stop(): Promise<void>;
@@ -115,13 +120,15 @@ export interface RewindResult {
 }
 /** Durable Agent items, including message identities and conversation facts. */
 export interface SessionSnapshot {
+    /** Persisted standing Agent, independent of current Product defaults. */
+    mainAgent?: string;
     sessionId: string;
     cwd: string;
-    history: import('../../vendor/cbc-shared/node/index.js').AgentInputItem[];
+    history: AgentInputItem[];
     /** Store-owned locators. Pass a key to readSession to read that child lazily. */
     subagents?: Array<{
         sessionId: string;
-        key: import('../../vendor/cbc-core/node/index.js').SessionKey;
+        key: SessionKey;
     }>;
 }
 /**
@@ -159,6 +166,12 @@ export interface QueryOptions {
     multitask?: boolean;
     /** Enable the host's local sandbox. Changes apply when the session has no background work. */
     sandboxEnabled?: boolean;
+    /**
+     * Request a PTY for Bash executions, or false for separate stdout/stderr pipes.
+     * Omitted preserves the session's current selection and existing CLI defaults.
+     * Execution drivers may require pipes; this does not change sandbox permissions.
+     */
+    usePty?: boolean;
     /**
      * 会话级自定义 agent 定义（#108461 D6，形态对齐 stream-json `initialize.agents`
      * / SDK `--agents`）：名字 → 定义（`prompt`/`description`/`tools`/`model`/
@@ -390,7 +403,7 @@ export type SteerResult = {
  */
 export type SessionEvent = (Message | RunStartedEvent | RunCompletedEvent | AgentEvent) & {
     /** Complete Agent item behind a message frame, shared with readSession(). */
-    readonly item?: import('../../vendor/cbc-shared/node/index.js').AgentInputItem;
+    readonly item?: AgentInputItem;
     /** Producer-owned identity. Background and child events retain their original run. */
     readonly origin?: SessionEventOrigin;
 };
@@ -429,13 +442,19 @@ export interface AgentEvent {
     } | {
         readonly type: 'catalog';
         readonly data: SessionCatalog;
+    } | {
+        readonly type: 'title';
+        readonly data: string;
+    } | {
+        readonly type: 'error';
+        readonly data: unknown;
     };
     readonly _requestId?: string;
     readonly _meta?: Record<string, unknown> | null;
 }
 export interface SessionCatalog {
-    readonly commands: Array<Pick<import('../../workspace/product/lib/common/index.js').Command, 'name' | 'description' | 'argumentHint' | 'tags'>>;
-    readonly skills: Array<Pick<import('../../workspace/product/lib/common/index.js').Skill, 'name' | 'description' | 'source' | 'userInvocable' | 'disableModelInvocation' | 'pluginInfo'>>;
+    readonly commands: Array<Pick<Command, 'name' | 'description' | 'argumentHint' | 'tags'>>;
+    readonly skills: Array<Pick<Skill, 'name' | 'description' | 'source' | 'userInvocable' | 'disableModelInvocation' | 'pluginInfo'>>;
     readonly skillOverrides?: Settings['skillOverrides'];
 }
 /** Refresh resident components before the next queued turn (including continuations).
@@ -463,6 +482,45 @@ export interface RunCompletedEvent extends QueryResult {
     readonly session_id: string;
     readonly _meta?: Record<string, unknown> | null;
 }
+/** Selects only presentation; query lifecycle and persistence are shared. */
+export type SessionOutputFormat = 'openai' | 'messages' | 'acp-v1' | 'acp-v2';
+export interface SubscribeOptions<F extends SessionOutputFormat = 'messages'> {
+    readonly format: F;
+}
+/** All SDK stream event variants, with the original object as data (no JSON conversion). */
+export interface AgentSdkEvent {
+    readonly type: 'agent_sdk';
+    readonly parentToolUseId?: string;
+    readonly session_id: string;
+    readonly data: RunStreamEvent;
+    readonly origin?: SessionEventOrigin;
+    readonly _meta?: Record<string, unknown> | null;
+}
+/** Native model facts used by formatters, never stream-json intermediates. */
+export interface AgentModelEvent {
+    readonly type: 'agent_model';
+    readonly parentToolUseId?: string;
+    readonly session_id: string;
+    readonly data: ResponseStreamEvent;
+    readonly origin?: SessionEventOrigin;
+    readonly _meta?: Record<string, unknown> | null;
+}
+export interface AcpSessionEvent<F extends 'acp-v1' | 'acp-v2'> {
+    readonly type: 'acp_update';
+    readonly notification: F extends 'acp-v1' ? SessionNotification : UpdateSessionNotification;
+    readonly item?: AgentInputItem;
+    readonly origin?: SessionEventOrigin;
+    readonly _meta?: Record<string, unknown> | null;
+}
+export type NativeSessionEvent = (AgentSdkEvent | AgentEvent | RunStartedEvent | RunCompletedEvent) & {
+    readonly origin?: SessionEventOrigin;
+};
+export type FormattedSessionEvent<F extends SessionOutputFormat = 'messages'> = (F extends 'messages' ? SessionEvent : F extends 'acp-v1' | 'acp-v2' ? AcpSessionEvent<F> | AgentEvent | RunStartedEvent | RunCompletedEvent : NativeSessionEvent) & {
+    readonly origin?: SessionEventOrigin;
+    readonly item?: AgentInputItem;
+};
+/** Internal source union. ACP never consumes stream-json messages. */
+export type SessionSourceEvent = SessionEvent | AgentSdkEvent | AgentModelEvent;
 export type SessionEventListener = (event: SessionEvent) => void | Promise<void>;
 export type SessionSubscriptionExit = {
     readonly reason: 'unsubscribed';

package/cli/dist-server/types/node/settings/settings-protocol.d.ts

@@ -92,6 +92,7 @@ export declare const ENV_KEY_CODEBUDDY_IMAGE_TO_VIDEO_MODEL = "CODEBUDDY_IMAGE_T
 export declare const ENV_KEY_CODEBUDDY_IMAGE_GEN_ENABLED = "CODEBUDDY_IMAGE_GEN_ENABLED";
 export declare const ENV_KEY_CODEBUDDY_IMAGE_EDIT_ENABLED = "CODEBUDDY_IMAGE_EDIT_ENABLED";
 export declare const ENV_KEY_CODEBUDDY_VIDEO_GEN_ENABLED = "CODEBUDDY_VIDEO_GEN_ENABLED";
+export declare const ENV_KEY_CODEBUDDY_AUDIO_TRANSCRIBE_ENABLED = "CODEBUDDY_AUDIO_TRANSCRIBE_ENABLED";
 export declare const ENV_KEY_CODEBUDDY_HIGH_CREDIT_APPROVAL_ENABLED = "CODEBUDDY_HIGH_CREDIT_APPROVAL_ENABLED";
 export declare const ENV_KEY_CODEBUDDY_ARTIFACT_ENABLED = "CODEBUDDY_ARTIFACT_ENABLED";
 /** @deprecated 兼容保留，请改用 CODEBUDDY_ARTIFACT_ENABLED（新名优先，旧名兜底）。 */
@@ -413,6 +414,8 @@ export interface CodebuddySettings {
     agentHome?: {
         enabled?: boolean;
         orchestration?: boolean;
+        /** 自动投递到主 Agent 的任务完成回执。默认 all。 */
+        taskReceipts?: 'all' | 'batch' | 'off';
     };
     /**
      * Web 输入框在 agent 忙碌时的发送方式（仅 agent-cli Web；不进 WorkBuddy overlay）。
@@ -643,6 +646,8 @@ export interface Hooks {
     CwdChanged?: HookConfig[];
     /** Internal-only hooks triggered when agent truly stops */
     FinalStop?: HookConfig[];
+    /** Hooks triggered when a user-typed command/skill expands into a prompt (matcher on command_name) */
+    UserPromptExpansion?: HookConfig[];
 }
 export interface StatusLine {
     /** 类型 */