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

package/cli/dist-server/types/vendor/cbc-shared/node/utils/retry-backoff.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 自动恢复链的统一口径：最多 3 次，1s 起步、2 倍指数退避（基准 1s → 2s → 4s）。
+ *
+ * 适用于会话层的 error / 网络 / 流超时恢复，以及模型层的连接级透明重试。
+ * 第 1 层请求级（429/502/503 等）不带网关 retry_policy 时仍保持自己的 500ms 基数，
+ * 所以这里只共享算法，基数与上限由调用方传入。
+ */
+export declare const MAX_RECOVERY_RETRIES = 3;
+export declare const RECOVERY_RETRY_BASE_DELAY_MS = 1000;
+export declare const RECOVERY_RETRY_MAX_DELAY_MS = 32000;
+export interface ExponentialBackoffOptions {
+    baseDelayMs: number;
+    maxDelayMs: number;
+    random?: () => number;
+}
+/**
+ * `base * 2^(attempt-1)` 封顶到 `maxDelayMs`，再做 25% 下减抖动（区间 `[0.75x, 1x]`）。
+ *
+ * 必须下减而不是上加：上加会让实际等待越过 `maxDelayMs` 25%，调用方对封顶的承诺就不成立。
+ * `attempt` 从 1 起，小于 1 按 1 处理。
+ */
+export declare function computeExponentialBackoffMs(attempt: number, options: ExponentialBackoffOptions): number;
+export declare function computeRecoveryBackoffMs(attempt: number, random?: () => number): number;
+/**
+ * 可取消的等待。`signal` 在等待前或等待中 abort 时返回 `false`，正常等满返回 `true`。
+ *
+ * 返回布尔而不是 reject：恢复链上的调用方拿到 `false` 后要自己决定退还额度、跳过发起，
+ * 用异常表达会把「用户取消」和「真正的错误」混在一条 catch 路径里。
+ */
+export declare function waitForRecoveryBackoff(ms: number, signal?: AbortSignal): Promise<boolean>;

package/cli/dist-server/types/vendor/cbc-shared/node/utils/retry-policy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 模型网关在 HTTP 错误体里下发的重试指示，与 `code` / `msg` / `displayMsg` 同层：
+ *
+ * ```json
+ * { "code": 11101, "msg": "...", "retry_policy": { "retry": false }, "displayMsg": { ... } }
+ * ```
+ *
+ * - `force-retry`：策略是普通对象且 `retry !== false`（含 `true`、缺 `retry` 键、类型异常）。
+ *   只在本地已判定可重试的范围内把请求级重试提到 3 次，不扩大可重试状态码。
+ * - `forbid-retry`：策略是普通对象且 `retry === false`。不重试、不换模型、不重放备站、不做鉴权刷新重试。
+ * - `unset`：字段缺失、`null`、数组或其他非对象形态，完全按原有逻辑处理。
+ *
+ * 只有显式 `false` 才阻断：网关形态小改动时宁可多试一次，也不要静默丧失恢复能力。
+ */
+export type RetryPolicyDecision = 'force-retry' | 'forbid-retry' | 'unset';
+export declare const RETRY_POLICY_FIELD = "retry_policy";
+/**
+ * 按固定层级找 `retry_policy` 原值，返回第一个存在的值（可能是非法形态，由调用方裁决）。
+ *
+ * 同一份策略会以三种形态出现：网关原始错误体（顶层或 `data` / `error.data`）、错误分析器
+ * 规范化后的 `{ error: { code, message, data } }`、SDK 包装后的 APIError（`error.data`，
+ * 外层再包一层时为 `error.error.data`）。层级写死、不递归，避免在任意嵌套里误捡字段。
+ */
+export declare function findRetryPolicy(source: unknown): unknown;
+export declare function decideRetryPolicy(policy: unknown): RetryPolicyDecision;
+export declare function resolveRetryPolicy(source: unknown): RetryPolicyDecision;

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,8 +1,8 @@
 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 { Account, APIResult, AuthenticationProvider, AuthSession, AuthState, AuthToken, LoginContext, ProductEnvService, SignContext } from './authentication-protocol.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.
  *
@@ -26,14 +26,14 @@ export declare class AccountScopedExternalLinkAuthenticationProvider implements
     checkNetworkConnectivity(): Promise<APIResult<boolean>>;
     createSession(ctx: SignContext): Promise<AuthSession>;
     refreshSession(session: AuthSession, ctx: SignContext): Promise<AuthSession>;
-    removeSession(): Promise<void>;
+    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/account-utils.d.ts

@@ -51,4 +51,29 @@ export declare function mergeCurrentAccountDetails(account: Account, accounts: A
  * 仅以账号类型为准，不用 enterpriseId 反推，避免 unknown/legacy account 被误判。
  */
 export declare function isPersonalAccount(account?: Pick<Account, 'type'>): boolean;
+/**
+ * 判断账号是否属于「个人版」这一**商业化版本**（个人版 + 个人版已订阅 Pro）。
+ *
+ * 与 {@link isPersonalAccount} 的区别，调用前请先确认要哪一个：
+ * - `isPersonalAccount`：严格的类型判定，只认 `type === 'personal'`，用于需要区分
+ *   「免费个人版」与其它一切档位的场景（如 IOA 请求头是否补默认企业 ID）。
+ * - `isPersonalEditionAccount`（本函数）：版本归属判定，把 `pro`（「个人版已订阅 Pro」，
+ *   见 agent-provider `types.ts` 的 Edition 注释）也算进个人版，用于「个人版专属功能」
+ *   门禁——把付费个人用户挡在个人版功能外不符合产品预期。
+ *
+ * 判定采用**反向排除**而非 type 白名单，原因是 `Account.type` 在协议层仅声明为 `string`，
+ * 完全透传后端 `/console/accounts`，前端不做任何映射校正：
+ * - 历史上出现过空串 type，白名单写法会把付费账号整块漏掉（见 agent-provider
+ *   `backend-provider.ts:getEditionDisplayType` 的同款踩坑注释）；反向排除对未知值
+ *   降级为「个人版」，与该处「其余（含 type 为空串 / 未知值）按个人账号推导」一致。
+ * - `enterpriseId` 非空一律视为企业租户：它是 enterprise-policy 包区分
+ *   personal / enterprise 的唯一依据（`bypass-personal` 语义），也是现有 4 处
+ *   `isPersonalAccount()` 调用统一叠加 `&& !enterpriseId` 的原因。这样即便后端返回
+ *   `type=personal` + 非空 enterpriseId（IOA 个人账号即属此类），也不会误放行。
+ *
+ * **未登录（`account` 为空）返回 `false`**：此时无从判断版本归属，不能因为「查不到企业
+ * 特征」就当成个人版放行个人版专属能力。这与上面对「已登录但 type 未知」降级为个人版
+ * 是两件事——后者至少确认了不是企业租户。
+ */
+export declare function isPersonalEditionAccount(account?: Pick<Account, 'type' | 'enterpriseId'>): boolean;
 export {};

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

@@ -5,7 +5,7 @@ import { AuthenticationType, ProductManager } from '../../../product/lib/common/
 import { Notifier } from '../../../runtime/lib/common/index.js';
 import { EventService, Logger, TraceService } from '../../../telemetry/lib/common/index.js';
 import { BehaviorSubject } from 'rxjs';
-import { Account, APIResult, AuthenticationManager, AuthenticationProvider, type AuthenticationStartupGate as IAuthenticationStartupGate, AuthenticationStorage, AuthSession, LoginContext, type PrewarmActivationGate as IPrewarmActivationGate, ProductEnvService } from './authentication-protocol.js';
+import { Account, APIResult, AuthenticationManager, AuthenticationProvider, type AuthenticationStartupGate as IAuthenticationStartupGate, AuthenticationStorage, AuthSession, LoginContext, LogoutOptions, type PrewarmActivationGate as IPrewarmActivationGate, ProductEnvService } from './authentication-protocol.js';
 /**
  * 注入 doInit 二级探针 sink。仅供 daemon 装配层调用，把 [AuthDoInitProbe] 复制一路
  * 落到 daemon.log；main.log 主 sink 走 celljs Logger 不受影响。
@@ -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>;
@@ -97,7 +103,7 @@ export declare class AuthenticationManagerImpl implements AuthenticationManager
     cancelLogin(): void;
     private clearLastAuthUrl;
     login(ctx?: LoginContext): Promise<boolean>;
-    logout(): Promise<void>;
+    logout(options?: LogoutOptions): Promise<void>;
     refreshSession(): Promise<void>;
     waitForSessionRefresh(): Promise<void>;
     refreshSessionForAuthenticationFailure(): Promise<AuthSession>;

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",
@@ -159,12 +180,29 @@ export interface AuthDevice {
     expiresIn: number;
     interval: number;
 }
+/**
+ * Options shared by the logout decision point (`AuthenticationManager.logout`)
+ * and the provider hook (`AuthenticationProvider.removeSession`).
+ */
+export interface LogoutOptions {
+    /**
+     * Whether to revoke the session on the server (call the server logout
+     * endpoint) in addition to clearing local state.
+     *
+     * Only user-initiated ("manual") logout should set this to `true`. Passive
+     * logout (e.g. auto-logout triggered by a 401 on an auth verification path)
+     * must leave it `false`/unset: at that point the token is already rejected
+     * by the server and the endpoint/refresh-token context is unreliable, so a
+     * server revoke call would be useless noise. Defaults to `false`.
+     */
+    revokeServerSession?: boolean;
+}
 export interface AuthenticationProvider {
     getAuthenticationType(): Promise<AuthenticationType[]>;
     support(ctx?: LoginContext): Promise<boolean>;
     createSession(ctx: SignContext): Promise<AuthSession>;
     refreshSession(session: AuthSession, ctx: SignContext): Promise<AuthSession>;
-    removeSession(session: AuthSession): Promise<void>;
+    removeSession(session: AuthSession, options?: LogoutOptions): Promise<void>;
     switchAccount(account: Account, authSession: AuthSession, ctx: SignContext): Promise<AuthSession>;
     checkNetworkConnectivity?(): Promise<APIResult<boolean>>;
 }
@@ -217,7 +255,7 @@ export interface AuthenticationManager {
     currentSessionSubject: BehaviorSubject<AuthSession | undefined>;
     login(ctx?: LoginContext): Promise<boolean>;
     cancelLogin(): void;
-    logout(): Promise<void>;
+    logout(options?: LogoutOptions): Promise<void>;
     refreshSession(): Promise<void>;
     waitForSessionRefresh(): Promise<void>;
     /** Force one authoritative, singleflight refresh after an auth failure. */

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, 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.
@@ -55,10 +66,15 @@ export declare class ExternalLinkAuthenticationProvider implements Authenticatio
     getAuthenticationType(): Promise<AuthenticationType[]>;
     createSession(ctx: SignContext): Promise<AuthSession>;
     refreshSession(session: AuthSession, ctx: SignContext): Promise<AuthSession>;
-    removeSession(): Promise<void>;
+    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/authentication/lib/common/wx-authentication-provider.d.ts

@@ -1,7 +1,7 @@
 import { Logger } from '@celljs/core';
 import { RestOperations } from '@celljs/http';
 import { AuthenticationType, ProductManager } from '../../../product/lib/common/index.js';
-import { Account, AuthenticationProvider, AuthSession, SignContext } from './authentication-protocol.js';
+import { Account, AuthenticationProvider, AuthSession, LogoutOptions, SignContext } from './authentication-protocol.js';
 export declare class WxAuthenticationProvider implements AuthenticationProvider {
     protected readonly restOperations: RestOperations;
     protected readonly productManager: ProductManager;
@@ -12,7 +12,7 @@ export declare class WxAuthenticationProvider implements AuthenticationProvider
     getAuthenticationType(): Promise<AuthenticationType[]>;
     createSession(ctx: SignContext): Promise<AuthSession>;
     refreshSession(session: AuthSession, ctx: SignContext): Promise<AuthSession>;
-    removeSession(): Promise<void>;
+    removeSession(_session?: AuthSession, _options?: LogoutOptions): Promise<void>;
     switchAccount(account: Account, authSession: AuthSession, ctx: SignContext): Promise<AuthSession>;
     private fetchTokenByTmpCode;
     private fetchAccounts;

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

@@ -179,6 +179,12 @@ export declare function isBuiltinDisableableAgent(agentName: string): boolean;
  * waste prompt tokens on a tool they can never legitimately call (the SendMessage
  * tool itself returns an error when invoked outside a team context), and for
  * structured-output agents like `compact` it can pollute the model's output.
+ *
+ * **这些名字是保留字，不得被用作子代理 / teammate 预设名**（评审 #128343）：
+ * `resolveMessageSpeakerLabel` 把本名单的判定放在「子会话报自身身份」**之前**，因为历史与
+ * 用量多处按 `providerData.agent === 'compact'` 这类字符串比较判定，子会话里跑 compact 时
+ * 不能被身份名覆盖。反过来说，一旦有真实子代理取了这里的名字，它的消息会被标成生成器名
+ * 而不是自己的身份 —— 属于要靠人眼才能发现的错标。新增名字前先确认它不会与任何预设名撞。
  */
 export declare const INTERNAL_GENERATOR_AGENTS: Set<string>;
 /**
@@ -289,6 +295,13 @@ export interface AgentManager {
      * 同输入逐轮返回同一对象（prompt cache 稳定）；视图字节永不写回全局物化面。
      */
     sessionScopedAgentView(session: Session, base: Agent): Promise<Agent>;
+    /**
+     * sandbox-agent-view：把 REPL 的动态 schema 按子代理身份重新物化一遍。Code Mode 的
+     * agent 实例进程级共享（`get('ptc')` 命中同一对象），schema 在构建期用合成会话采集 ——
+     * 继承模式的子代理（Explore 等）会看到模式的全量目录。派发侧知道身份，经此覆盖。
+     * 只克隆 REPL 一个工具，视图不进 agentMap；空身份 / 同名 / 无 REPL 时原样返回基座。
+     */
+    sandboxScopedAgentView(base: Agent, sandboxAgentName: string): Promise<Agent>;
     /** served 激活链的视图预热（默认 agent），派发路径是失效兜底。 */
     prepareSessionAgentView(session: Session): Promise<void>;
     get(agentName: string): Promise<Agent | undefined>;
@@ -537,12 +550,37 @@ 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 & {
     /** Process-local provenance for fresh user turns; stripped before SDK dispatch. */
     inputOrigin?: AgentRunOrigin;
     continuation?: never;
+    /**
+     * Per-arrival out-signal: invoked when this run was routed to the message
+     * queue (skipRun, session busy) instead of executing now. Callers that owe
+     * their caller *this* prompt's own result (print / stream-json) use it to
+     * keep waiting until the queue drains and their turn actually runs.
+     *
+     * A run-scoped callback (not a shared session flag) so concurrent arrivals
+     * 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.
@@ -558,12 +596,23 @@ export type AgentCurrentContinuationOptions = AgentSdkRunOptions<Session> & Agen
 };
 export type AgentServiceRunOptions<TContext = Session> = AgentStandardRunOptions<TContext> | AgentCurrentContinuationOptions;
 export interface AgentService {
+    /** Atomically close a task's runtime only after its last result and queued work settle. */
+    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
@@ -629,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';
@@ -670,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 设置。
@@ -779,6 +835,8 @@ export declare enum CustomAgentSavePath {
 }
 export declare enum OutputStyleType {
     DEFAULT = "default",
+    PROACTIVE = "proactive",
+    CONCISE = "concise",
     EXPLANATORY = "explanatory",
     LEARNING = "learning"
 }

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 {};