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

package/cli/dist-server/types/vendor/cbc-core/node/utils/history-utils.d.ts

@@ -226,10 +226,10 @@ export declare abstract class HistoryUtils {
      * <conversation_history_summary>…</conversation_history_summary> 包裹的正文)。
      *
      * 规则(与 replaceCompactWithSummary / getCompactHistory 对齐):
-     *   1. 仅查看 `providerData.agent === AgentNames.COMPACT` 且为 assistant 的 message
-     *   2. 从后向前扫描,命中第一条满足格式的 compact assistant 即返回
-     *   3. "满足格式"由 `SummaryUtils.extractCompactSummaryFromText` 统一判定
-     *      (内含结构校验 + 非空正文双闸)
+     *   1. 查看 compact-agent assistant，或 PreMessage/MaxToken 写入的显式 compact boundary
+     *   2. 从后向前扫描,命中第一条可用摘要即返回
+     *   3. compact assistant 继续要求结构化 summary envelope；显式 boundary 同时支持
+     *      工程压缩的 `<cb_summary>` 与 LLM summary envelope
      *   4. 全程扫描都拿不到 → 返回 `undefined`(history 中**从未**出现过合法摘要)
      *
      * ⚠️ 不适合用于"判断本次 compact run 是否成功"!

package/cli/dist-server/types/vendor/cbc-core/node/utils/input-item-utils.d.ts

@@ -256,6 +256,14 @@ export declare abstract class InputItemUtils {
     static isUserInterrupted(item: AgentInputItem): boolean;
     static isSuccessfulFunctionCallResultItem(item: AgentInputItem): item is FunctionCallResultItem;
     static isCompactBoundaryMessage(item: AgentInputItem): boolean;
+    /**
+     * 仅凭 providerData 结构化标记判定 compact boundary，不使用内容正则兜底。
+     *
+     * 会删除或改写消息的路径（如 replaceCompactWithSummary）必须用这个版本：
+     * 内容兜底会把用户粘贴的 `<cb_summary>` / `<conversation_history_summary>` 文本
+     * 误判为 boundary，导致真实用户输入被移除。
+     */
+    static isStructuredCompactBoundaryMessage(item: AgentInputItem): boolean;
     static isReplayRecoverableCompactMessage(item: AgentInputItem): item is UserMessageItem;
     static isCompactUserMessage(item: AgentInputItem): item is UserMessageItem;
     private static hasCompactBoundaryContent;

package/cli/dist-server/types/vendor/cbc-core/node/utils/token-utils.d.ts

@@ -64,7 +64,9 @@ export declare class TokenUtils {
      * tool call 执行后产生的 function_call_result（这些结果在 API 返回后才追加到 history）。
      * 为了更准确地判断是否需要触发压缩，需要把这部分 token 补上。
      *
-     * 从 history 末尾往前扫描，收集连续的 function_call_result 条目直到遇到其他类型为止。
+     * 从 history 末尾往前扫描，只收集紧挨在末尾的连续 function_call_result。
+     * 一遇到非 function_call_result（含 function_call）即停止：function_call 属于上一轮
+     * 已经进过请求的内容，穿过它会把更早轮次的 result 重复计入 inputTokens（#133055）。
      * 注意：估算前会移除图片内容，避免 base64 图片数据导致 token 严重偏高。
      */
     static estimateTrailingToolResultTokens(history: any[]): number;

package/cli/dist-server/types/vendor/cbc-shared/node/agent/openai-agents-types.d.ts

@@ -31,6 +31,7 @@ import type { AgentOutputType, getAllMcpTools as getAllMcpToolsFn, MaxTurnsExcee
 import type { TextOutput, UnknownContext, UserContent } from '@openai/agents-core/types';
 import type { AcpTerminalStateItem, FileHistorySnapshotItem, ModelUsageItem, ResendForkNoticeItem } from './custom-input-item-types';
 export * from './custom-input-item-types';
+export type { RunStreamEvent } from '@openai/agents-core';
 export type Agent<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput> = AgentTypeCtor<TContext, TOutput>;
 export type RunContext<TContext = UnknownContext> = RunContextTypeCtor<TContext>;
 export type Runner = RunnerTypeCtor;

package/cli/dist-server/types/vendor/cbc-shared/node/checkpoint/checkpoint-types.d.ts

@@ -64,4 +64,10 @@ export interface CheckpointFileChangeStats {
     additions: number;
     /** 删除行数 */
     deletions: number;
+    /**
+     * 行数为近似值（PTC/Code Mode 兜底：files 来自本轮 trackFile 快照，additions/deletions
+     * 暂记 0）。需要精确行数的调用方（如 TUI rewind 面板）据此异步调用
+     * compareWithCurrentFiles 补齐后清除本标记。仅内存态，不持久化。
+     */
+    approximate?: boolean;
 }

package/cli/dist-server/types/vendor/cbc-shared/node/model/model-errors.d.ts

@@ -20,11 +20,23 @@ export declare class StreamTimeoutError extends CustomError {
  * reasoning-only：已流出思考、finish_reason=error 且无可用输出（#63761 / #122115）。
  * no-token：finish_reason=error 到达时一个模型 token 都没有（连 reasoning 也没有）。
  *
- * reasoning-only 与 no-token 都是上游瞬时失败，会话层按 error 恢复预算重试；
+ * reasoning-only 与 no-token 按「上游瞬时失败」处理，会话层按 error 恢复预算重试——
+ * 但仅限流没跑太久的那些：已经烧满上游硬时限的同样形态重跑必然再次跑满，由
+ * `isRetryableEmptyStreamError` 按 {@link EmptyStreamError.elapsedMs} 收口（#132616）。
  * placeholder 必须与 no-token 分开——两者共用一个值时，放开 no-token 会连带
  * 推翻空 200 的终态判定。
  */
 export type EmptyStreamKind = 'placeholder' | 'reasoning-only' | 'no-token';
+/**
+ * 空流错误的结构化 category，两条上报通道共用一个值。
+ *
+ * ACP 侧 `classifyErrorAsRequestError` 早就用它（前端按此映射业务码 3008「模型服务未返回消息」）；
+ * stream-json 侧此前没有任何结构化维度，`errors_info` 整体缺席，sandbox-proxy 的
+ * `BuildErrorMessageFromCLIErrors` 只能兜底成 `category=internal`，再由
+ * `ClassifyInBandPromptError` 推出 `error_origin=cli`——把上游故障记成 CLI 内部错误。
+ * 挂到错误对象的 `data` 上让两条通道读到同一个值，不再各说各话。
+ */
+export declare const EMPTY_STREAM_ERROR_CATEGORY = "empty_model_response";
 /**
  * 空流错误
  * 语义上仍然是"上游没有提供模型输出"，所以继承 StreamTimeoutError
@@ -33,10 +45,26 @@ export type EmptyStreamKind = 'placeholder' | 'reasoning-only' | 'no-token';
  * 典型触发：某些 OpenAI 兼容网关在后端异常时没有透传错误码，而是发一帧全空
  * `{"delta":{"role":"assistant","content":"","tool_calls":[],"refusal":""},"finish_reason":""}`
  * 然后直接关闭连接——用户看到的现象是 cbc 当前轮"空响应"并被 ACP 分类为 refusal。
+ *
+ * message **必须**按 kind 分开写：三种 kind 共用一句「only placeholder chunks」会谎报失败形态。
+ * 0924 沙箱实测的 reasoning-only 样本里上游发了 20397 帧 / 9.5 MB 真实 reasoning，
+ * 与「只有占位帧」正相反；而下游报表、看板、排障全靠这个字符串归因，于是把上游
+ * ~900s 时限问题记成了 CLI 内部错误（#132616）。
  */
 export declare class EmptyStreamError extends StreamTimeoutError {
     readonly emptyStreamKind: EmptyStreamKind;
-    constructor(chunkCount: number, totalBytes: number, kind?: EmptyStreamKind);
+    /**
+     * 流从打开到判定空流的时长。
+     *
+     * 用来区分「上游瞬时抖动（秒级空响应）」和「跑满上游硬时限（0924 实测 ~900s）」——
+     * 后者重跑同一段 prompt 必然再次跑满，重试只是把静默时长翻倍，见
+     * `isRetryableEmptyStreamError` 的时长闸门。
+     */
+    readonly elapsedMs: number;
+    readonly data: Readonly<{
+        category: "empty_model_response";
+    }>;
+    constructor(chunkCount: number, totalBytes: number, kind?: EmptyStreamKind, elapsedMs?: number);
 }
 /**
  * 认证缺失错误

package/cli/dist-server/types/workspace/agent-client-protocol/lib/common/index.d.ts

@@ -3,6 +3,7 @@ export * from './prompt-codec.js';
 export * from './prompt-context-xml.js';
 export * from './to-resolve-blocks.js';
 export * from './interactive-question-tools.js';
+export * from './sandbox-rule-context.js';
 export * from './sdk.js';
 export * from './transport/streamable-http.js';
 export * from './client/index.js';

package/cli/dist-server/types/workspace/agent-client-protocol/lib/common/sandbox-rule-context.d.ts

@@ -0,0 +1,38 @@
+export type SandboxRuleDomain = 'file' | 'command' | 'network';
+export type SandboxRuleSource = 'enterprise' | 'preset' | 'user';
+export type SandboxRuleCause = {
+    kind: 'ordered-rule';
+    domain: SandboxRuleDomain;
+    ruleRef: string;
+} | {
+    kind: 'sensitive-rule';
+    ruleId: string;
+    source?: SandboxRuleSource;
+} | {
+    kind: 'policy';
+    code: string;
+};
+export interface SandboxRuleContext {
+    causes: SandboxRuleCause[];
+}
+export interface FileApprovalScope {
+    directory: string;
+    operation: 'read' | 'write' | 'delete';
+    recursive: boolean;
+    lifetime: 'session';
+}
+export declare const SANDBOX_RULE_CONTEXT_META_KEY = "codebuddy.ai/sandboxRuleContext";
+export declare const FILE_APPROVAL_SCOPE_META_KEY = "codebuddy.ai/fileApprovalScope";
+/** 仅复制显示所需字段，不能将归因标识作为授权凭证。 */
+export declare function parseSandboxRuleContext(value: unknown): SandboxRuleContext | undefined;
+export declare function parseFileApprovalScope(value: unknown): FileApprovalScope | undefined;
+/**
+ * 目录授权的专用应答 optionId，不出现在 requestPermission 的选项列表中。
+ * 只有展示了 fileApprovalScope 的卡片会回传它；按选项 kind 自动应答的 IM、
+ * 自动化或旧 UI 选不到它，因而无法替用户登记目录授权。
+ */
+export declare const FILE_DIRECTORY_APPROVAL_OPTION_ID = "allow_directory";
+export declare function parseSandboxPermissionMetadata(meta: unknown): {
+    ruleContext?: SandboxRuleContext;
+    fileApprovalScope?: FileApprovalScope;
+};

package/cli/dist-server/types/workspace/authentication/lib/common/account-scoped-external-link-authentication-provider.d.ts

@@ -1,7 +1,7 @@
 import { RestOperations } from '@celljs/http';
 import { AuthenticationType, ClientInfoProvider, ProductConfiguration, ProductManager } from '../../../product/lib/common/index.js';
 import { ExternalUriOpener } from '../../../runtime/lib/common/index.js';
-import { Logger } from '../../../telemetry/lib/common/index.js';
+import { Logger, type Span } from '../../../telemetry/lib/common/index.js';
 import { Account, APIResult, AuthenticationProvider, AuthSession, AuthState, AuthToken, LoginContext, LogoutOptions, ProductEnvService, SignContext } from './authentication-protocol.js';
 /**
  * External-link auth variant whose current account is scoped by the token.
@@ -29,11 +29,11 @@ export declare class AccountScopedExternalLinkAuthenticationProvider implements
     removeSession(_session?: AuthSession, _options?: LogoutOptions): Promise<void>;
     switchAccount(account: Account, authSession: AuthSession, ctx: SignContext): Promise<AuthSession>;
     private toSessionAccountLists;
-    protected openAuthUrl(authState: AuthState): Promise<void>;
+    protected openAuthUrl(authState: AuthState, handoffSpan?: Span): Promise<void>;
     private fetchAuthState;
     private loopGetToken;
     private loopGetCurrentAccount;
-    protected fetchCurrentAccount(auth: AuthToken, ctx: SignContext): Promise<Account>;
+    protected fetchCurrentAccount(auth: AuthToken, ctx: SignContext, requestSpan?: Span): Promise<Account>;
     protected enterpriseHeaders(auth?: AuthToken): Record<string, string>;
     protected calculateExpiresAt(authToken: AuthToken): void;
     private isAuthenticationInvalidError;

package/cli/dist-server/types/workspace/authentication/lib/common/authentication-manager.d.ts

@@ -18,6 +18,12 @@ import { Account, APIResult, AuthenticationManager, AuthenticationProvider, type
  */
 export declare function setAuthDoInitProbeSink(sink: ((line: string) => void) | undefined): void;
 export declare class AuthenticationManagerImpl implements AuthenticationManager {
+    /** Host observation hook, called after currentSessionSubject published the session. No-op by default. */
+    protected observeSession(_session: AuthSession | undefined, _source: string, _observation?: unknown): void;
+    /** Captures host metadata while the storage publisher's synchronous context is available. */
+    protected captureSessionObservation(): unknown;
+    private notifySessionObserver;
+    private safelyCaptureSessionObservation;
     protected readonly productManager: ProductManager;
     protected readonly productEnvService: ProductEnvService;
     protected readonly authenticationProvider: Provider<AuthenticationProvider>;

package/cli/dist-server/types/workspace/authentication/lib/common/authentication-observation.d.ts

@@ -0,0 +1,36 @@
+import { type Span } from '../../../telemetry/lib/common/index.js';
+/** Login observation helpers. Every export swallows its own failures; authentication never depends on them. */
+/** W3C context for the login chain only; the shared Span.requestHeaders stay legacy-only. */
+export declare function loginTraceCarrier(span?: Span): {
+    traceparent?: string;
+    tracestate?: string;
+};
+/** Only for a host that registered login observation; other products keep their legacy login trace unchanged. */
+export declare function addLoginSpanEvent(span: Span | undefined, name: string, attributes?: Record<string, string>): void;
+/** Host login observation context registered together with setLoginStepCallback. */
+export interface LoginObservationContext {
+    /** Reauthentication correlation (`recovery_of_loss_id` / `previous_auth_session_id`). */
+    recovery?: Record<string, string>;
+    /** The host's login attempt ID; the web login page records it as the owner of its journey. */
+    journeyOwnerId?: string;
+    /** Entry context of the host-owned login journey. */
+    traceparent?: string;
+}
+export declare function setLoginObservationContext(context?: LoginObservationContext): void;
+export declare function appendLoginTraceParams(url: URL, span?: Span): void;
+/** Web login page parameters that join the host login journey. */
+export declare function appendLoginObservationParams(url: URL, handoffSpan?: Span): void;
+/** Narrow host hook: no credential/header objects or telemetry implementation cross this boundary. */
+export interface AuthRequestObservationInput {
+    method?: string;
+    url?: string;
+    traceparent?: string;
+}
+export type AuthRequestObservation = (request: AuthRequestObservationInput) => ((status?: number, businessCode?: number) => void) | undefined;
+export declare function setAuthRequestObservation(observer?: AuthRequestObservation): void;
+export declare function observeAuthRequest(config: {
+    method?: string;
+    url?: string;
+    headers?: Record<string, unknown>;
+}): void;
+export declare function observeAuthResponse(config: unknown, status?: number, businessCode?: unknown): void;

package/cli/dist-server/types/workspace/authentication/lib/common/authentication-protocol.d.ts

@@ -67,6 +67,27 @@ export declare const HTTP_HEADER_NO_AUTHORIZATION = "X-No-Authorization";
  * 用于请求发往自定义端点（如 LiteLLM 网关）时，避免携带 copilot 内部认证信息。
  */
 export declare const HTTP_HEADER_SKIP_AUTH_INTERCEPTOR = "X-Skip-Auth-Interceptor";
+/**
+ * `auth/state` 额外请求头数据源（可选 DI 依赖，中立抽象；Issue #94672）。
+ *
+ * authentication 包对具体头一无所知：只负责在登录链路的 `auth/state` 请求上
+ * 把本 provider 返回的所有 header 原样透传。**具体带哪些头、值怎么取，全部由
+ * 业务侧（WorkBuddy Desktop daemon 装配层）在实现里决定**，让上游 authentication
+ * 包无需反向依赖 Electron / Turing / qimei 等下游能力。
+ *
+ * 由宿主**可选**绑定到 CellJS 容器；未绑定（CLI / Web / headless / 单测）时按
+ * `@Optional()` 注入为 undefined，`auth/state` 不携带任何额外 header，对这些形态
+ * 零影响。
+ *
+ * 语义约定：**尽力而为、不等待、不阻断登录**。`provide()` 应立即返回当前快照
+ * （读缓存 / env），拿不到的头业务侧自己省略即可；内部异常由 authentication 包
+ * 兜底吞掉，绝不因遥测公参阻断登录。
+ */
+export declare const AuthStateHeaderProvider: unique symbol;
+export interface AuthStateHeaderProvider {
+    /** 返回要附加到 `auth/state` 请求上的额外 header 集合（可能为空）。 */
+    provide(): Promise<Record<string, string>>;
+}
 export declare const enum Edition {
     Pro = "pro",
     Personal = "personal",

package/cli/dist-server/types/workspace/authentication/lib/common/external-link-authentication-provider.d.ts

@@ -1,8 +1,9 @@
 import { RestOperations } from '@celljs/http';
 import { AuthenticationType, ClientInfoProvider, ProductManager } from '../../../product/lib/common/index.js';
 import { ExternalUriOpener } from '../../../runtime/lib/common/index.js';
-import { Logger } from '../../../telemetry/lib/common/index.js';
-import { Account, APIResult, AuthenticationProvider, AuthSession, LoginContext, LogoutOptions, ProductEnvService, SignContext, SignLicenseError } from './authentication-protocol.js';
+import { Logger, type Span } from '../../../telemetry/lib/common/index.js';
+import { type LoginObservationContext } from './authentication-observation.js';
+import { Account, APIResult, AuthenticationProvider, AuthSession, AuthStateHeaderProvider, LoginContext, LogoutOptions, ProductEnvService, SignContext, SignLicenseError } from './authentication-protocol.js';
 /** 登录漏斗步骤回调，由外部消费者（如 workbuddy-server）注入上报逻辑。 */
 export type LoginStepCallback = (step: string, dims: Record<string, string>) => void;
 /**
@@ -10,9 +11,14 @@ export type LoginStepCallback = (step: string, dims: Record<string, string>) =>
  * @param callback 回调函数，undefined 表示清除
  * @param onlyIfVersion 可选，传入时只有当前 version 匹配才执行清除（防止旧轮 finally 覆盖新轮）
  * @param loginSessionId 可选，当前登录会话 ID，供 openAuthUrl 注入到 authUrl 中传递给 Web 登录页
+ * @param observation 可选，宿主登录观测上下文，与回调同生命周期
  * @returns 设置后的 version
  */
-export declare function setLoginStepCallback(callback: LoginStepCallback | undefined, onlyIfVersion?: number, loginSessionId?: string): number;
+export declare function setLoginStepCallback(callback: LoginStepCallback | undefined, onlyIfVersion?: number, loginSessionId?: string, observation?: LoginObservationContext): number;
+/** Whether the host registered login observation; other products keep their login URLs unchanged. */
+export declare function hasHostLoginObservation(): boolean;
+/** 让 Web 登录页加入宿主登录 journey（仅国内版 workbuddy 平台）；宿主未注册观测时不改 URL。 */
+export declare function appendHostLoginJourneyParams(url: URL, platform: string | undefined, handoffSpan?: Span): void;
 interface AuthState {
     state: string;
     authUrl: string;
@@ -35,6 +41,11 @@ export declare class ExternalLinkAuthenticationProvider implements Authenticatio
     protected readonly restOperations: RestOperations;
     protected readonly logger: Logger;
     protected readonly clientInfoProvider: ClientInfoProvider;
+    /**
+     * `auth/state` 额外请求头数据源（Issue #94672）。可选依赖：仅 WorkBuddy Desktop
+     * daemon 绑定，CLI / Web / headless / 单测未绑定时为 undefined，不携带额外 header。
+     */
+    protected readonly authStateHeaderProvider?: AuthStateHeaderProvider;
     private configuration;
     /**
      * The last auth URL that was opened in the browser.
@@ -57,8 +68,13 @@ export declare class ExternalLinkAuthenticationProvider implements Authenticatio
     refreshSession(session: AuthSession, ctx: SignContext): Promise<AuthSession>;
     removeSession(session?: AuthSession, options?: LogoutOptions): Promise<void>;
     switchAccount(account: Account, authSession: AuthSession, ctx: SignContext): Promise<AuthSession>;
+    /**
+     * 取 `auth/state` 的额外请求头（Issue #94672）。provider 未绑定（CLI / Web /
+     * headless / 单测）返回空对象；实现内部任何异常都吞掉退化为空，绝不阻断登录。
+     */
+    private resolveAuthStateExtraHeaders;
     private fetchAuthState;
-    protected openAuthUrl(authState: AuthState): Promise<void>;
+    protected openAuthUrl(authState: AuthState, handoffSpan?: Span): Promise<void>;
     /**
      * 打开登录页前对 authUrl 追加环境相关参数的可覆写钩子。
      * 基类默认不追加任何参数；子类（如 CLI IOA 分支）覆写此方法即可注入自己的 query，

package/cli/dist-server/types/workspace/authentication/lib/common/index.d.ts

@@ -10,3 +10,4 @@ export * from './custom-token-authentication-storage.js';
 export * from './wx-authentication-provider.js';
 export * from './product-env-service.js';
 export * from './account-utils.js';
+export * from './authentication-observation.js';

package/cli/dist-server/types/workspace/cbc-checkpoint/lib/node/checkpoint/checkpoint-protocol.d.ts

@@ -30,6 +30,7 @@ export interface CheckpointService {
      * @param options.autoAddToHistory - 是否自动添加到 session history (默认 true)
      * @param options.messageId - 快照关联的消息ID (默认为空)
      * @param options.isSnapshotUpdate - 是否为快照更新 (默认 false)
+     * @param options.filePath - 只更新该路径的文件版本 (默认更新全部已跟踪文件)
      * @returns 创建的 checkpoint,无需创建时返回 undefined
      */
     createCheckpoint(session: Session, options?: {
@@ -37,6 +38,7 @@ export interface CheckpointService {
         throwOnError?: boolean;
         messageId?: string;
         isSnapshotUpdate?: boolean;
+        filePath?: string;
     }): Promise<Checkpoint | undefined>;
     /** 回退到指定 checkpoint */
     revertToCheckpoint(session: Session, checkpoint: Checkpoint, scope: RevertScope): Promise<void>;

package/cli/dist-server/types/workspace/cbc-checkpoint/lib/node/checkpoint/checkpoint-service.d.ts

@@ -16,6 +16,7 @@ export declare class CheckpointServiceImpl implements CheckpointService {
         throwOnError?: boolean;
         messageId?: string;
         isSnapshotUpdate?: boolean;
+        filePath?: string;
     }): Promise<Checkpoint | undefined>;
     revertToCheckpoint(session: Session, checkpoint: Checkpoint, scope: import('./checkpoint-protocol.js').RevertScope): Promise<void>;
     getRewindableCheckpoints(session: Session): Checkpoint[];

package/cli/dist-server/types/workspace/cbc-core/lib/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/workspace/cbc-core/lib/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/workspace/cbc-core/lib/node/agent/agent-purpose-scope.d.ts

@@ -0,0 +1,46 @@
+import type { AgentType } from '../../../../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 {};

package/cli/dist-server/types/workspace/cbc-core/lib/node/agent/agent-service.d.ts

@@ -3,10 +3,11 @@ import { AuthenticationManager } from '../../../../authentication/lib/common/ind
 import { type AbortLinkDisposer, Agent, type AgentInputItem, type NonStreamRunOptions, RunState, type StreamRunOptions } from '../../../../cbc-shared/lib/node/index.js';
 import { type LanguageModel } from '../../../../product/lib/common/index.js';
 import { Logger } from '../../../../telemetry/lib/common/index.js';
+import { type ManualCompactRequestHandler as ManualCompactRequestHandlerContract } from '../context/context-protocol.js';
 import { type FileRollbackOperationLock as FileRollbackOperationLockContract } from '../file-rollback/file-rollback-service-protocol.js';
 import { Session, SessionManager } from '../session/session-protocol.js';
 import { SessionRunStateMachine } from '../session/session-run-state-machine-protocol.js';
-import { type AgentCurrentContinuationOptions, AgentManager, AgentRunInterceptor, AgentRunRequest, AgentService, type AgentStandardRunOptions, RunnerProvider } from './agent-protocol.js';
+import { type AgentCurrentContinuationOptions, AgentManager, AgentRunInterceptor, AgentRunRequest, AgentService, type AgentStandardRunOptions, type OneTimeRunOptions, RunnerProvider } from './agent-protocol.js';
 import { type AgentRunScope as IAgentRunScope } from './agent-run-scope.js';
 import { AgentPluginRefresh, AgentRunObserver, AgentRuntimeResolver } from './agent-runtime-protocol.js';
 export declare class AgentServiceImpl implements AgentService {
@@ -22,6 +23,7 @@ export declare class AgentServiceImpl implements AgentService {
     protected readonly agentRunInterceptorProvider: Provider<AgentRunInterceptor>;
     protected readonly fileRollbackOperationLock?: FileRollbackOperationLockContract;
     protected readonly logger: Logger;
+    protected readonly manualCompactRequestHandler?: ManualCompactRequestHandlerContract;
     /**
      * Preserve the pre-start cancellation snapshot across runDefault's agent
      * lookup controller and run()'s own controller. This is process-local
@@ -40,6 +42,20 @@ export declare class AgentServiceImpl implements AgentService {
     protected getLifecycleOwners(): WeakMap<Session, AbortController>;
     tryCloseTaskSession(session: Session, result: NonNullable<Session['resultSubject']['value']>): Promise<boolean>;
     retireTaskSession(session: Session): Promise<void>;
+    waitForRunsSettled(session: Session): Promise<void>;
+    /**
+     * 有界 join：等到该 session 上的物理 run 全部交还 lifecycle owner 与 in-flight 信号。
+     *
+     * 为什么需要它而不是直接看 `agent_end`：`finalizeRun` 晚于本轮把最终产出写进
+     * history，`agent_end` 却早于 `finalizeRun`。任何依赖「上一轮 history 已写完」这个
+     * 因果的调用方（如队列 drain）必须 join 到这里。
+     *
+     * Bounded: `runSettledSubject` is optional, so a session built without
+     * one has nothing to observe and would hang the caller's cleanup — which
+     * owns hook, MCP and background-shell teardown. `agent_end` 也可能来自没有物理
+     * run 的路径（skipRun / 迟到事件），无界等待会把调用方永久挂住。
+     */
+    private joinRunsSettled;
     /** compare-and-delete：仅当 token 仍指向本轮 controller 时清除。 */
     private clearLifecycleOwner;
     /** 本轮是否是当前 lifecycle owner。 */
@@ -156,6 +172,7 @@ export declare class AgentServiceImpl implements AgentService {
     protected resolveRunOneTimeModel(agentName: string, session?: Session): Promise<LanguageModel>;
     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>;
+    private runPipeline;
     /**
      * #59319-stream: 抽取的 physical run cleanup 逻辑。
      * 非 stream 路径由 run() finally 同步调用；
@@ -189,8 +206,14 @@ export declare class AgentServiceImpl implements AgentService {
     private prepareRunAdmission;
     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>;
+    /**
+     * Streams the text of a one-shot run on `session`. A reused caller Session is shared
+     * with its in-flight main run, so the call's purpose and request id live in its async
+     * scope instead of on the Session.
+     */
+    private streamOneTimeText;
+    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>;
     /**
      * Enhanced version of runOneTime that supports per-request overrides
      * for temperature, maxTokens, maxTurns, systemPrompt, and bypassPermissions.

package/cli/dist-server/types/workspace/cbc-core/lib/node/agent/index.d.ts

@@ -1,5 +1,8 @@
 export * from './agent-protocol.js';
 export * from './agent-purpose-protocol.js';
+export * from './agent-purpose-scope.js';
+export * from './model-step-sequence.js';
+export * from './model-call-failure.js';
 export * from './agent-runtime-protocol.js';
 export * from './agent-run-scope.js';
 export * from './agent-service.js';

package/cli/dist-server/types/workspace/cbc-core/lib/node/agent/model-call-failure.d.ts

@@ -0,0 +1,9 @@
+import type { ModelCallGeneration } from '../session/session-protocol.js';
+/**
+ * Marks `error` as the failure of one model call. The call's ids live in the model-call
+ * async scope, which does not reach the consumer of the SDK run stream; the error does.
+ * An error rethrown through an outer call keeps the innermost call's mark.
+ */
+export declare function markModelCallFailure<T>(error: T, sessionId: string, generation: ModelCallGeneration): T;
+/** The model call of this Session that failed with `error`; undefined when the failure is not one. */
+export declare function getFailedModelCall(error: unknown, sessionId: string): ModelCallGeneration | undefined;

package/cli/dist-server/types/workspace/cbc-core/lib/node/agent/model-step-sequence.d.ts

@@ -0,0 +1,11 @@
+import type { Session } from '../session/session-protocol.js';
+type StepSequenceSession = Pick<Session, 'id' | 'history' | 'agentPurpose' | 'modelStepSeq'>;
+/** Latest step of the Session's agent loop, restored from persisted history after resume. */
+export declare function currentModelStepSeq(session: StepSequenceSession): number;
+/**
+ * Step number for the model call in the current async chain. Agent-loop calls
+ * advance the counter; auxiliary calls reuse the latest step. The counter never
+ * resets across runs, compaction continuations or teammate wake-ups.
+ */
+export declare function allocateModelStepSeq(session: StepSequenceSession): number;
+export {};