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

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

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

@@ -21,6 +21,14 @@ export interface ModelInputMemoryPressure {
     headroom: number;
     inputItems: number;
     estimatedInputBytes?: number;
+    /**
+     * Whether the retained-size walk finished (fully traversed, or provably ≥ the byte budget).
+     * `false` means the walk stopped on the node cap with bytes still under budget — the graph is
+     * deep/wide but not necessarily large, so `estimatedInputBytes` must NOT drive a rejection.
+     */
+    estimateComplete: boolean;
+    /** Real, content-independent OOM signal: heap is already near its ceiling. */
+    heapCritical: boolean;
     reject: boolean;
 }
 export declare function assessModelInputMemoryPressure(input: AgentInputItem[], heapUsed?: number, heapLimit?: number): ModelInputMemoryPressure;
@@ -80,8 +88,18 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      * 否则前端的 sending 态无人清除、永久转圈（#73022）。
      */
     protected readonly acpBroadcastService?: AgentQueueOutput;
+    /** Sessions with a deferred emergency compaction already scheduled (see scheduleEmergencyCompact). */
+    private readonly emergencyCompactInFlight;
     create(config?: Partial<RunConfig>): Promise<Runner>;
     private assertModelInputCloneHeadroom;
+    /**
+     * Fire a one-shot emergency compaction for an over-large history so the user's retry can
+     * succeed. Deferred + de-duplicated per session; failures are swallowed because the surfaced
+     * error already tells the user how to recover. Mirrors checkAutoCompact's non-blocking branch
+     * (setImmediate keeps it off the current runner's abort signal). compactAndSummarize has its
+     * own session-level lock, so the in-flight set only avoids scheduling redundant callbacks.
+     */
+    private scheduleEmergencyCompact;
     /**
      * 在每次模型请求前检查是否需要自动压缩。
      * 此时所有工具都已执行完毕，可以安全地触发压缩。
@@ -90,10 +108,10 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
     /**
      * Mode B：把「立即发送」队列项注入正在运行的 turn（#73022）。
      *
-     * 调用点在 `callModelInputFilter`（见 `create()`），即**每次模型请求之前**，
-     * 且此时本轮工具已全部执行完、tool result 已回填。选这个边界是因为既不用
-     * 打断在跑的工具，也不会破坏 `tool_call` 与 `tool_result` 的配对——Codex 与
-     * Claude Code 同样选在这个位置。
+     * 调用点在 `callModelInputFilter`（见 `create()`），即**每次模型请求之前**。
+     * rich message / notification / drain prompt 仍在这里注入请求副本；真实 steer
+     * 由 `continuationInputProvider` 在 `prepareTurn` 前写入 SDK RunState，避免后续
+     * 工具 step 从权威状态重建请求时丢失。
      *
      * 注入内容已经进入本次模型请求，无需再为“曾经注入过”强制续圈。只有模型响应期间
      * 新到达、尚未被取出的消息，才由 `__codebuddySteerPending` 在收尾时实时判定是否
@@ -111,6 +129,22 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      *   `create()` 注释）。payload 与授权同为调用局部值，天然不跨 run 共享。
      */
     private injectSendNowItems;
+    /**
+     * Drain steer only at the SDK continuation boundary, before it prepares the next model step.
+     *
+     * The returned model items are installed by the SDK into RunState.generatedItems before
+     * `prepareTurn`. This makes steer authoritative input for every later tool/model step instead
+     * of an ephemeral `callModelInputFilter` addition. The visible history stays the bare user
+     * message; it is admitted exactly once, by the stream consumer, in RunState order.
+     */
+    private takeSteerContinuationInput;
+    /**
+     * Visible-history + ACP admission of one drained steer group.
+     *
+     * Ordering is the caller's responsibility (continuation-history-queue.ts); this only performs
+     * the writes and must never throw back into the run.
+     */
+    private admitSteerToVisibleHistory;
     /**
      * #100404：落定来源一（rich queue sendNow）的消费。
      *
@@ -139,11 +173,11 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      * （`session/session-manager.ts` 的 `MODEL_STREAM_STARTED`），涉及跨模块反向布线与
      * 事件类型白名单依赖，另开 issue 跟进。
      *
-     * **落史顺序反转（显式接受）**：`modelData.input` 的 push 顺序是来源一 → 二 → 三 → 四，
-     * 但来源一的 `addHistory` 推迟到本方法内执行，来源二/三/四仍在 `injectSendNowItems` 里
-     * 就地 addHistory。同一 model step 同时命中多个来源时，history 里队员消息会排在
-     * steer / 通知之后，与模型当时看到的输入顺序相反。已确认下游按 role/type 消费、不依赖
-     * 交错位置，故接受该反转，不做「四来源 historyItems 统一收敛」的重构。
+     * **落史顺序反转（显式接受）**：`modelData.input` 的 filter push 顺序是来源一 → 三 → 四，
+     * 但来源一的 `addHistory` 推迟到本方法内执行，来源三/四仍在 `injectSendNowItems` 里
+     * 就地 addHistory。同一 model step 同时命中多个来源时，history 里队员消息会排在通知
+     * 之后，与模型当时看到的输入顺序相反。steer 已在更早的 SDK continuation 边界同时进入
+     * RunState 与可见历史，不参与这段反转。下游按 role/type 消费、不依赖交错位置，故接受。
      *
      * at-most-once 由**作用域**保证，不再依赖「commit 前清暂存」这类补偿动作：`pending` 是
      * 单次 `callModelInputFilter` 调用的局部值，每次调用最多把它 commit 一次，也不可能被

package/cli/dist-server/types/workspace/cbc-core/lib/node/agent/tool-call-loop-guard-protocol.d.ts

@@ -27,7 +27,7 @@ export declare const TOOL_CALL_LOOP_STOPPED_MESSAGE = "Request aborted: user sto
  * - `ToolCallLoopDetector` 在**模型请求前**拦截，静默向模型注入停止消息，用户无感；
  *   它覆盖的是旧的三条规则（黑名单同参 4 次 / Read 同文件 40 次 / 非黑名单同参 40 次）。
  * - `ToolCallLoopGuard` 在**工具执行前**拦截，弹窗让用户自己决定继续还是停止；
- *   它覆盖新增的两条规则（同工具连续 40 次，Bash 单独放到 80 次 / 周期序列重复 10 轮）。
+ *   它覆盖新增的两条规则（同工具连续 40 次，Bash 与 Write 单独放到 80 次 / 周期序列重复 10 轮）。
  *
  * 两者刻意并存：旧规则的静默语义已被线上验证，不因新能力回归。
  */

package/cli/dist-server/types/workspace/cbc-core/lib/node/agent/tool-call-loop-pattern.d.ts

@@ -5,11 +5,11 @@
  */
 import type { ToolCallLoopTriggerType } from '../../../../telemetry/lib/common/event/types/craft.js';
 export interface ToolCallLoopThresholds {
-    /** 同一工具连续调用达到该次数即判定为循环。Bash 走单独阈值。 */
+    /** 同一工具连续调用达到该次数即判定为循环。Bash / Write 走单独阈值。 */
     consecutiveThreshold: number;
     /**
-     * Bash 连续调用的单独阈值。长任务里模型会连续跑很多条不同命令，
-     * 只看工具名时 40 次容易把正常推进误判成循环。
+     * Bash 与 Write 连续调用的单独阈值。长任务里模型会连续跑很多条命令、
+     * 或连续落很多个文件，只看工具名时 40 次容易把正常推进误判成循环。
      */
     bashConsecutiveThreshold: number;
     /** AAB 块需要连续重复的轮数。 */
@@ -22,8 +22,9 @@ export interface ToolCallLoopHit {
     /** 重复序列的周期长度；AAB 恒为 3，连续同工具恒为 1。 */
     patternLength: number;
 }
-/** 与 `ToolNames.BASH` 对齐。模式识别层不依赖 agent-protocol，避免把工具名枚举拉进来。 */
+/** 与 `ToolNames.BASH` / `ToolNames.WRITE` 对齐。模式识别层不依赖 agent-protocol，避免把工具名枚举拉进来。 */
 export declare const BASH_LOOP_TOOL_NAME = "Bash";
+export declare const WRITE_LOOP_TOOL_NAME = "Write";
 export declare const DEFAULT_TOOL_CALL_LOOP_THRESHOLDS: ToolCallLoopThresholds;
 /** AAB 块的长度。多工具循环只识别这一种形状，因此是常量而非可配阈值。 */
 export declare const AAB_PERIOD = 3;
@@ -43,7 +44,7 @@ export declare class ToolCallLoopTracker {
      * 记录一次即将执行的工具调用，返回本次是否命中循环。
      *
      * 命中优先级：先判连续同工具，再判 AAB 重复。两条规则的阈值默认不重叠
-     * （普通工具 40 次、Bash 80 次 vs AAB 重复 10 轮），实践中不会互相抢占。
+     * （普通工具 40 次、Bash / Write 80 次 vs AAB 重复 10 轮），实践中不会互相抢占。
      */
     record(toolName: string): ToolCallLoopHit | undefined;
     /**
@@ -59,7 +60,7 @@ export declare class ToolCallLoopTracker {
  * - `ABC`（三者互不相同）通常是正常的多步工作流（读文件 → 改文件 → 跑测试，
  *   然后换下一个文件），按周期重复判它循环误伤面太大；
  * - `ABAB` 这类两工具交替同样不判，避免把翻页 / 分批处理误当循环；
- * - `AAA…` 属于连续同工具，由 consecutiveThreshold / bashConsecutiveThreshold 那条规则负责。
+ * - `AAA…` 属于连续同工具，由 consecutiveThreshold / bashConsecutiveThreshold（Bash、Write）那条规则负责。
  *
  * `X ≠ Y` 顺带保证了 AAB 一定是本原周期（唯一可能的更短整除周期是 1，
  * 那要求三个元素全等），所以不需要额外的本原性校验。
@@ -69,8 +70,8 @@ export declare function matchesRepeatedAabSequence(history: readonly string[], r
  * 读取阈值配置。环境变量只用于 QA 快速复现，生产不设置即走默认值。
  * AAB 的周期是形状定义的一部分，不开放配置。
  *
- * `CBC_LOOP_GUARD_CONSECUTIVE_THRESHOLD` 只覆盖非 Bash 工具。Bash 用
- * `CBC_LOOP_GUARD_BASH_CONSECUTIVE_THRESHOLD`，避免 QA 把通用阈值压低时
+ * `CBC_LOOP_GUARD_CONSECUTIVE_THRESHOLD` 只覆盖非 Bash / Write 工具。Bash 与 Write
+ * 共用 `CBC_LOOP_GUARD_BASH_CONSECUTIVE_THRESHOLD`，避免 QA 把通用阈值压低时
  * 把长任务放宽一并关掉。
  */
 export declare function resolveToolCallLoopThresholds(env?: NodeJS.ProcessEnv): ToolCallLoopThresholds;

package/cli/dist-server/types/workspace/cbc-core/lib/node/context/compaction-lineage.d.ts

@@ -0,0 +1,39 @@
+import type { CompactionKind, CompactionTrigger } from '../../../../telemetry/lib/common/index.js';
+import type { Session } from '../session/session-protocol.js';
+export type { CompactionKind, CompactionTrigger };
+export declare function compactionKindOf(trigger: CompactionTrigger): CompactionKind;
+/** Compactions of a Session's context. Never resets, like `modelStepSeq`. */
+export interface CompactionLineage {
+    /** Completed compactions. */
+    count: number;
+    /** Compaction the current context starts from. */
+    lastId?: string;
+    /** Trigger of the completed compaction the next agent-loop model call reports. */
+    pending?: CompactionTrigger;
+}
+type LineageSession = Pick<Session, 'id' | 'history' | 'compactionLineage' | 'meta'>;
+/** Compaction lineage of `session`, restored from its history after resume. */
+export declare function getCompactionLineage(session: LineageSession): CompactionLineage;
+/**
+ * Numbers a compaction boundary item before it enters history and stamps the running
+ * compaction onto it; the next agent-loop model call reports it.
+ */
+export declare function recordCompactionBoundary(session: LineageSession, providerData: Record<string, unknown>): void;
+/** Compaction lineage of one model call (gateway headers, `chat_message_send`). */
+export interface ModelCallCompaction {
+    /** Completed compactions of the Session when the call is sent. */
+    readonly count: number;
+    /** Compaction the call's context starts from. */
+    readonly id?: string;
+    /** Compaction calls: class of the running compaction (`X-Compaction`). */
+    readonly kind?: CompactionKind;
+    /** First agent-loop call after a compaction: its class (`X-Context-Compacted`) and trigger. */
+    readonly contextCompacted?: CompactionKind;
+    readonly trigger?: CompactionTrigger;
+}
+/**
+ * Compaction lineage for the model call in the current async chain. Only the first
+ * agent-loop call after a compaction reports it, like Claude Code's
+ * `consumePendingContextCompacted`.
+ */
+export declare function resolveModelCallCompaction(session: LineageSession & Pick<Session, 'agentPurpose' | 'conversationRequestId'>): ModelCallCompaction;