@tencent-ai/agent-harness 0.2.0-beta.2 → 0.2.0-beta.4

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

@@ -737,6 +737,8 @@ export interface AcpRequestTracking {
     conversationRequestId?: string;
 }
 export interface AcpPromptItem {
+    /** Host-validated mod receipt; never copied from client metadata. */
+    modsPromptSubmitted?: true;
     request: PromptRequest;
     responseDeferred: Deferred<PromptResponse>;
     tracking: AcpRequestTracking;
@@ -954,6 +956,12 @@ export interface AcpAgentManager {
      * 获取所有已注册的 AcpAgent 实例
      */
     getAll(): Map<string, AcpAgent>;
+    /**
+     * Subscribe to agent-registered events. Enables the mods paint pipe
+     * to push a first-frame MOD_RENDER to a newly-connected webui
+     * without waiting for the mod's own `$.ui.invalidate` cadence.
+     */
+    onAgentRegistered?(cb: (connectionId: string, agent: AcpAgent) => void): () => void;
     /**
      * 移除并释放指定连接的 AcpAgent 实例。重复移除同一连接是 no-op。
      * @param connectionId 连接 ID

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

@@ -447,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;

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

@@ -9,6 +9,11 @@ export interface CommonRequest extends SessionOptions {
      * 字段，只给 native 会话创建时盖站立键用。ACP 请求走 `acp:true`，不在这里盖。
      */
     agent?: string;
+    /** Request-level debug options forwarded from CLI/serve callers. */
+    debug?: boolean | string;
+    debugToStderr?: boolean;
+    /** Automatically connect to a single available IDE on startup. */
+    ide?: boolean;
 }
 export interface ResumeRequest {
     resume: boolean | string;

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,5 +1,5 @@
 import { Session } from '../../vendor/cbc-core/node/index.js';
-import type { QueryInput, QueryOptions, QueryTicket, ReloadOptions, RewindOptions, RewindResult, SessionEventListener, SessionSubscription, SteerOptions, SteerResult } from './types';
+import type { FormattedSessionEvent, QueryInput, QueryOptions, QueryTicket, ReloadOptions, RewindOptions, RewindResult, SessionOutputFormat, SessionSubscription, SteerOptions, SteerResult, SubscribeOptions } from './types';
 interface SettleOutcome {
     assistantText: string;
     completedError?: unknown;
@@ -46,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.

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;
     }>;
 }
 /**
@@ -396,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;
 };
@@ -435,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).
@@ -469,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/tools/tool-protocol.d.ts

@@ -21,13 +21,13 @@ export declare const DEFAULT_SLASH_COMMAND_TOOL_CHAR_BUDGET = 8000;
 export declare const DEFAULT_SKILL_TOOL_CHAR_BUDGET = 8000;
 export declare const DEFAULT_AGENT_TOOL_CHAR_BUDGET = 30000;
 /** Per-entry hard cap for a single skill's description */
-export declare const MAX_SKILL_DESC_CHARS = 150;
+export declare const MAX_SKILL_DESC_CHARS = 200;
 /** Minimum maxDescLen below which non-protected skills degrade to names-only (aligned with CC MIN_DESC_LENGTH=20) */
 export declare const MIN_SKILL_DESC_LENGTH = 20;
 /**
  * Env name for per-skill description hard-cap overrides.
  *
- * By default every skill's description is hard-capped to {@link MAX_SKILL_DESC_CHARS}(150)
+ * By default every skill's description is hard-capped to {@link MAX_SKILL_DESC_CHARS}(200)
  * per entry. A host can loosen (or tighten) this cap for **specific** skills — identified
  * by skill name — without changing the global default, by exporting this env.
  *
@@ -261,6 +261,8 @@ export interface Tool<TParameters extends ToolInputParameters = any, Context = U
      * The name of the tool. Must be unique within the agent.
      */
     name: string;
+    /** Host-created mod proxies dispatch once, inside their own execute method. */
+    readonly dispatchesModToolCall?: boolean;
     /**
      * Stability of the model-facing definition while the process is alive.
      * Agent tools default to stable; runtime-varying definitions opt into volatile.
@@ -349,6 +351,12 @@ export interface Tool<TParameters extends ToolInputParameters = any, Context = U
 }
 export type { BackgroundTask, TerminalEvidence } from '../../vendor/cbc-core/node/index.js';
 export interface ToolManager {
+    /** Dynamic definitions share the registry used by get/execute. Builtins cannot be replaced. */
+    register(tool: Tool): Promise<void>;
+    unregister(name: string): Promise<void>;
+    listDynamicToolNames(): string[];
+    /** Agent tool snapshots must be rebuilt when this version changes. */
+    readonly registryVersion: number;
     get<TParameters extends ToolInputParameters = any, Context = UnknownContext>(name: string, agentConfig?: ProductAgent, cachedProductConfig?: {
         agents?: any[];
         models?: any[];
@@ -377,6 +385,20 @@ export interface ToolManager {
      * 仅作用于 toolMap 中的内置工具；MCP 工具不走此路径。
      */
     ensureBuiltinDeferIndexed(toolName: string): Promise<boolean>;
+    /**
+     * 在工具执行前创建文件备份（file-history 快照），返回被跟踪的文件路径。
+     *
+     * 直连路径由 {@link executeToolWithHooks} 内部自动调用；REPL/Code Mode 沙箱
+     * 执行路径（DeferExecuteTool.routeToolCall → executeBuiltinTool）绕过该 hook
+     * 包装，需在真正执行工具前显式调用本方法，否则沙箱内的 Edit/Write 不产生
+     * FileHistorySnapshotItem，rewind 无快照可恢复（#130664）。
+     *
+     * 依赖 FileTrackService.trackFile 幂等（文件已在当前 checkpoint 即跳过），两条
+     * 路径都触达时也只落一次快照。
+     */
+    trackFileForToolCall(toolName: string, toolInput: unknown, session: Session, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<string | undefined>;
     addBackgroundTask(task: BackgroundTask): void;
     removeBackgroundTask(id: string): void;
     getBackgroundTasks(): BackgroundTask[];
@@ -926,26 +948,15 @@ export interface VideoService {
 }
 export declare const AudioTranscribeService: unique symbol;
 /**
- * 录音文件识别（长音频转文本）请求参数。
- * `channel_num:1` 由 service 固定注入，不暴露给调用方。
+ * tool 层已判定好的音频来源。
+ * 本地文件需要先上传 COS 才有公网可下载地址；调用方给出的 URL 直接提交。
  */
-export interface AudioTranscribeOptions {
-    /** 说话人分离：0 关闭（默认）/ 1 开启（需 channel_num=1） */
-    speaker_diarization?: 0 | 1;
-    /** 临时热词表 "词|权重,..."（最多 128） */
-    hotword_list?: string;
-    /** 阿拉伯数字智能转换：0 / 1 / 3 */
-    convert_num_mode?: 0 | 1 | 3;
-    /** 脏词过滤：0 / 1 / 2 */
-    filter_dirty?: 0 | 1 | 2;
-    /** 标点过滤：0 / 1 / 2 */
-    filter_punc?: 0 | 1 | 2;
-    /** 语气词过滤：0 / 1 / 2 */
-    filter_modal?: 0 | 1 | 2;
-    /** 上游附加参数（合法 JSON 字符串），如 '{"Domain":3}' */
-    extra?: string;
-}
-/** service 内部解析出的音频来源（COS-only：始终为 audio_url）。 */
+export type AudioTranscribeSource = {
+    readonly filePath: string;
+} | {
+    readonly audioUrl: string;
+};
+/** 提交给上游的音频来源（本服务始终用 audio_url，从不用 audio_data）。 */
 export interface AudioSource {
     audio_url: string;
 }
@@ -1022,11 +1033,15 @@ export interface AudioTranscribeResult {
 }
 /**
  * 录音文件识别服务接口。
- * COS-only：本地文件先经后端预签名上传 COS，再以 audio_url 提交异步转写并轮询。
+ * 本地文件先经后端预签名上传 COS 换取 download_url；调用方给的 URL 直接用。
+ * 两种来源都以 audio_url 提交异步转写并轮询。
+ *
+ * 识别参数（`channel_num` / `speaker_diarization`）由 service 固定注入，
+ * 按 #128310 不向 Agent 暴露开关。
  */
 export interface AudioTranscribeService {
     /**
-     * 转写本地音频文件：预签名上传 → 提交任务 → 轮询直至终态。
+     * 转写音频：解析来源（本地文件则预签名上传）→ 提交任务 → 轮询直至终态。
      */
-    transcribe(filePath: string, options: AudioTranscribeOptions, context: RunContext<Session>): Promise<AudioTranscribeResult>;
+    transcribe(source: AudioTranscribeSource, context: RunContext<Session>): Promise<AudioTranscribeResult>;
 }

package/cli/dist-server/types/vendor/cbc-core/node/agent/agent-protocol.d.ts

@@ -550,6 +550,19 @@ export interface AgentServiceRunControlOptions {
     bypassMessageQueue?: boolean;
     /** Input is already present in Session history; do not append it again. */
     skipAddHistory?: boolean;
+    /** Let an interactive host route external `/compact` before normal run admission. */
+    routeManualCompact?: boolean;
+    /**
+     * Per-call out-signal of `runDefault`: invoked once, synchronously, after
+     * this call passed run admission (its startup controller is installed on
+     * the Session) and before the agent is resolved. Not invoked when admission
+     * throws. It says nothing about the model having started or the run
+     * succeeding; without `bypassMessageQueue` the run may still be queued
+     * afterwards (see `onEnqueued`). A throwing callback is logged and does not
+     * affect the run. Internal re-runs pass fresh options and never carry it; it
+     * is stripped before AgentRunRequest and the SDK.
+     */
+    onAdmitted?: () => void;
 }
 /** Options for an isolated run or an SDK RunState resume. */
 export type AgentStandardRunOptions<TContext = Session> = AgentSdkRunOptions<TContext> & AgentServiceRunControlOptions & {
@@ -566,6 +579,8 @@ export type AgentStandardRunOptions<TContext = Session> = AgentSdkRunOptions<TCo
      * cannot clobber each other's outcome.
      */
     onEnqueued?: () => void;
+    /** Exact result of this arrival, including execution after a queue drain. */
+    onResult?: (result: NonNullable<Session['resultSubject']['value']>) => void;
 };
 /**
  * Explicitly claim the current process-local logical turn.
@@ -585,12 +600,19 @@ export interface AgentService {
     tryCloseTaskSession?(session: Session, result: NonNullable<Session['resultSubject']['value']>): Promise<boolean>;
     /** Stop accepting task work and join its physical runs before releasing dependencies. */
     retireTaskSession?(session: Session): Promise<void>;
+    /**
+     * 有界等待该 session 上的物理 run 收尾（含它把最终产出写进 history）。
+     *
+     * `agent_end` 早于 run 的 finalize，所以「上一轮 history 已写完」不能靠 `agent_end`
+     * 判定；需要该因果的调用方（队列 drain）join 到这里。超时会放行并告警，不会挂死。
+     */
+    waitForRunsSettled?(session: Session): Promise<void>;
     run<TAgent extends Agent<any, any>>(agent: TAgent, input: string | AgentInputItem[], options: AgentCurrentContinuationOptions): Promise<void>;
     run<TAgent extends Agent<any, any>, TContext = Session>(agent: TAgent, input: string | AgentInputItem[] | RunState<TContext, TAgent>, options?: AgentStandardRunOptions<TContext>): Promise<void>;
     runDefault<TAgent extends Agent<any, any>>(input: string | AgentInputItem[], options: AgentCurrentContinuationOptions): Promise<void>;
     runDefault<TAgent extends Agent<any, any>, TContext = Session>(input: string | AgentInputItem[] | RunState<TContext, TAgent>, options?: AgentStandardRunOptions<TContext>): Promise<void>;
-    runOneTime<TContext = Session>(agentName: string, input: string | AgentInputItem[], options?: NonStreamRunOptions<TContext>): Promise<string>;
-    runOneTime<TContext = Session>(agentName: string, input: string | AgentInputItem[], options?: StreamRunOptions<TContext>): Promise<string>;
+    runOneTime<TContext = Session>(agentName: string, input: string | AgentInputItem[], options?: NonStreamRunOptions<TContext> & OneTimeRunOptions): Promise<string>;
+    runOneTime<TContext = Session>(agentName: string, input: string | AgentInputItem[], options?: StreamRunOptions<TContext> & OneTimeRunOptions): Promise<string>;
     /**
      * Run a one-shot agent call in a forked (isolated) session that inherits
      * the conversation history from the parent session. The forked session is
@@ -656,6 +678,11 @@ export interface ForkedAgentOptions {
     /** Optional cap on number of turns (default: 1 for one-shot) */
     maxTurns?: number;
 }
+/** Options of `runOneTime` on top of the SDK run options. */
+export interface OneTimeRunOptions {
+    /** X-Agent-Purpose of the call; defaults to the agent's `AGENT_PURPOSE_MAP` entry, else its name. */
+    purpose?: string;
+}
 export interface RunRequest {
     prompt?: string;
     inputFormat?: 'text' | 'stream-json';
@@ -697,6 +724,8 @@ export interface AgentRunRequest<TContext = Session> extends SessionOptions {
     skipAddHistory?: boolean;
     bypassMessageQueue?: boolean;
     inputOrigin?: AgentRunOrigin;
+    /** Process-local arrival callback; never passed to the SDK. */
+    onResult?: AgentStandardRunOptions['onResult'];
     traceId?: string;
     /**
      * #59319-5: 普通 run 二次裁决发现 session 仍 busy 时由 AgentService 设置。

package/cli/dist-server/types/vendor/cbc-core/node/agent/agent-purpose-protocol.d.ts

@@ -58,7 +58,9 @@ export declare enum AgentPurpose {
     /** Auto mode permission risk classification (runOneTime: AUTO_MODE_CLASSIFIER) */
     AutoModeClassifier = "auto_mode_classifier",
     /** Automation scheduled task execution */
-    Automation = "automation"
+    Automation = "automation",
+    /** `/btw` side question on a forked Session (runForked); Claude Code's `side_question` source */
+    SideQuestion = "side_question"
 }
 /**
  * Dynamic purpose prefix for built-in subagents.
@@ -127,6 +129,9 @@ export declare const AUXILIARY_PURPOSES: ReadonlySet<string>;
  * 时 purpose 可能尚未设置的普通对话仍按原行为发出 MODEL_REQUEST_STARTED。
  */
 export declare function isAuxiliaryPurpose(purpose?: string): boolean;
+/** Purposes of compaction summary calls (X-Agent-Type `compaction`). */
+export declare const COMPACTION_PURPOSES: ReadonlySet<string>;
+export declare function isCompactionPurpose(purpose?: string): boolean;
 /**
  * 按 purpose 旁路 agent 生命周期事件（agent_start / agent_end / tool / handoff）。
  *
@@ -145,9 +150,8 @@ export declare function isAuxiliaryPurpose(purpose?: string): boolean;
  *
  * 因此这里只收 PreMessage 这一种 purpose。
  *
- * 依赖前提：`PreMessageCompactStrategy` 在 runOneTime 前后设置 / 还原
- * `session.agentPurpose`，且用 try/finally 保证异常路径也会还原——否则 purpose 泄漏
- * 会让**主 run** 也被误旁路，反而放大本要修复的孤儿 run 问题。
+ * The purpose is scoped to the summary call (`runOneTime` → `runWithAgentPurpose`), so it
+ * cannot leak onto the pending main run.
  *
  * multi-session（#44317）回归时，PreMessage 承载应改回临时子 Session；本名单保留为
  * 冗余防线即可（临时 Session 上旁路是无害的）。

package/cli/dist-server/types/vendor/cbc-core/node/agent/agent-purpose-scope.d.ts

@@ -0,0 +1,46 @@
+import type { AgentType } from '../../../../workspace/telemetry/lib/common/index.js';
+interface PurposeCarrier {
+    agentPurpose?: string;
+    conversationRequestId?: string;
+}
+/**
+ * Runs an auxiliary model call (title, summary, WebFetch analysis, ...) on a
+ * caller-owned Session without writing its purpose / request id onto the shared
+ * Session, where a concurrent main run would read and send them as its own.
+ */
+export declare function runWithAgentPurpose<T>(session: object, purpose: string, callback: () => T, options?: {
+    conversationRequestId?: string;
+}): T;
+/** True when the current async chain is an auxiliary call scoped to `session`. */
+export declare function isInAgentPurposeScope(session: object | undefined): boolean;
+/** Purpose of the model call running in the current async chain. */
+export declare function getEffectiveAgentPurpose(session: PurposeCarrier | undefined): string | undefined;
+/** Request id of the model call running in the current async chain. */
+export declare function getEffectiveConversationRequestId(session: PurposeCarrier | undefined): string | undefined;
+/** Purposes whose model calls are steps of a Session's own agent loop. */
+export declare function isMainConversationPurpose(purpose: string | undefined): boolean;
+/** True when the model call in the current async chain is a step of `session`'s agent loop. */
+export declare function isMainLoopModelCall(session: PurposeCarrier | undefined): boolean;
+/** True when the model call in the current async chain has an `AUXILIARY_PURPOSES` purpose. */
+export declare function isAuxiliaryPurposeCall(session: PurposeCarrier | undefined): boolean;
+/**
+ * Runs `callback` outside any purpose scope. A run started from a helper call's async
+ * chain (e.g. a queued message drained on its agent_end) is a new agent-loop run.
+ */
+export declare function runOutsideAgentPurposeScope<T>(callback: () => T): T;
+export type ModelCallAgentType = AgentType;
+/** Role of the Session's own agent loop, for request-level events. */
+export declare function resolveSessionAgentType(session: {
+    meta?: Record<string, unknown>;
+}): 'main' | 'subagent' | 'team';
+/**
+ * Role of the model call in the current async chain (X-Agent-Type / telemetry
+ * `agentType`), mirroring Claude Code's `x-claude-code-request-class`: compaction
+ * summaries report `compaction`, other one-shot helpers (title, WebFetch analysis,
+ * ...) report `auxiliary`, whatever Session they run on. The specific helper
+ * stays in X-Agent-Purpose.
+ */
+export declare function resolveModelCallAgentType(session: PurposeCarrier & {
+    meta?: Record<string, unknown>;
+}): ModelCallAgentType;
+export {};