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

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
@@ -38,6 +40,22 @@ export declare class AgentServiceImpl implements AgentService {
      */
     private lifecycleOwners;
     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。 */
@@ -154,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 同步调用；
@@ -187,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,11 +1,15 @@
 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';
 export * from './agent-factory.js';
 export * from './runner-factory.js';
 export * from './runner-provider.js';
+export * from './speaker-label.js';
 export * from './ordered-tools-agent.js';
 export * from './tool-call-loop-detector-protocol.js';
 export * from './tool-call-loop-detector-service.js';

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

@@ -17,12 +17,7 @@ export declare class MessageQueueAgentRunInterceptor implements AgentRunIntercep
     protected readonly logger: Logger;
     protected readonly stateMachine: SessionRunStateMachine;
     intercept(request: AgentRunRequest): Promise<void>;
-    /**
-     * 触发后不再重复打 error（防日志风暴）；下次"有实际工作"分支复位 counter/flag，
-     * session 自动恢复处理能力。
-     */
-    private trackEmptyDrainAndMaybeTripGuard;
-    private resetEmptyDrainLoopGuard;
+    private consumeQueueItems;
 }
 /**
  * 用户查询包裹拦截器

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

@@ -1,4 +1,4 @@
-import { type RunConfig, Runner } from '../../../../cbc-shared/lib/node/index.js';
+import { type AgentInputItem, type RunConfig, Runner } from '../../../../cbc-shared/lib/node/index.js';
 import { ProductManager } from '../../../../product/lib/common/index.js';
 import { Logger } from '../../../../telemetry/lib/common/index.js';
 import { type NotificationInjectionBuffer as INotificationInjectionBuffer } from '../message-queue/notification-injection-buffer-protocol.js';
@@ -15,6 +15,15 @@ import { ToolCallLoopDetector } from './tool-call-loop-detector-protocol.js';
  * Used by finishReasonErrorInterceptor to detect prior retries across both mechanisms.
  */
 export declare const TRUNCATION_RETRY_MARKER = "Do NOT repeat the same oversized tool call. Break it into smaller operations.";
+export interface ModelInputMemoryPressure {
+    heapUsed: number;
+    heapLimit: number;
+    headroom: number;
+    inputItems: number;
+    estimatedInputBytes?: number;
+    reject: boolean;
+}
+export declare function assessModelInputMemoryPressure(input: AgentInputItem[], heapUsed?: number, heapLimit?: number): ModelInputMemoryPressure;
 /**
  * Tool-specific hints for how to decompose a truncated tool call into smaller operations.
  */
@@ -72,6 +81,7 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      */
     protected readonly acpBroadcastService?: AgentQueueOutput;
     create(config?: Partial<RunConfig>): Promise<Runner>;
+    private assertModelInputCloneHeadroom;
     /**
      * 在每次模型请求前检查是否需要自动压缩。
      * 此时所有工具都已执行完毕，可以安全地触发压缩。
@@ -80,10 +90,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` 在收尾时实时判定是否
@@ -101,6 +111,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）的消费。
      *
@@ -129,11 +155,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 一次，也不可能被
@@ -211,10 +237,10 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      * model / agent / argumentsDisplayText 等键同样会跟着走，它们是惰性字段、上游不解读，
      * 这里不做处理；真正需要清掉的只有语义已经反转的 discard。
      *
-     * 改写与删标记都只作用于当轮副本（见 filterTruncatedToolCalls 的
-     * "Scope of the rewrite"），session.history 里的原值保持不变。
+     * 返回一个浅复制的新 item；providerData 仅在需要删除 discard 时 copy-on-write。
+     * session.history 与 SDK 传入的原 item 始终保持不变。
      */
-    private rewriteCallArguments;
+    private withRewrittenCallArguments;
     /**
      * SDK callModelInputFilter: called before every model API request within the SDK run loop.
      *
@@ -240,13 +266,23 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      *   message instructing the model to break the call into smaller operations. This
      *   turns the SDK's automatic retry into a valid, useful request.
      *
-     * Scope of the rewrite: `agents-core`'s `applyCallModelInputFilter` hands us a
-     * `structuredClone` of the turn input and clones our return value again, explicitly so
-     * that filter-side mutations cannot touch cached turn state. So every rewrite here
-     * lands on a per-turn copy only — `session.history` keeps the malformed arguments and
-     * we redo the same rewrite on every subsequent turn. That is correct but not free:
-     * anything reported from this path must be aggregated per turn rather than logged per
-     * call, or a long session with N bad calls emits N log lines every turn.
+     * Scope of the rewrite: this filter opts into the SDK's `preserveInputIdentity` mode,
+     * so existing history items arrive by identity and MUST remain immutable. Repairs use
+     * item-level copy-on-write and array-level shallow copies; the SDK still creates isolated
+     * model/session copies after the filter returns. `session.history` therefore keeps the
+     * malformed arguments and we redo the same rewrite on every subsequent turn. Anything
+     * reported from this path must be aggregated per turn rather than logged per call.
+     */
+    /**
+     * 模型输入的两步修复，**顺序不能反**：
+     *
+     * 1. `filterTruncatedToolCalls` 先跑。截断（finish_reason=length）与坏 JSON 的
+     *    call 正是「参数半截 + 没有任何 result」那一类；它删掉这些 call 的同时会注入
+     *    拆解引导与防循环停止标记。若先按配对摘掉它们，该分支因 `invalidCallIds` 为空
+     *    直接早退，模型拿不到任何引导，退回 #75892 那条老路，而且请求本身合法、无错可见。
+     * 2. `filterUnpairedToolCalls` 后跑，收掉剩下的孤儿（参数合法但结果丢失、重复 callId、
+     *    头部被截断留下的孤儿结果）。本地正文里的孤儿是持久化的，留着每次恢复都被上游 400。
      */
+    private repairModelInput;
     private filterTruncatedToolCalls;
 }

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

@@ -0,0 +1,44 @@
+export declare function resolveMessageSpeakerLabel(input: {
+    session?: {
+        id?: string;
+        storeId?: string;
+        meta?: Record<string, unknown>;
+    } | undefined;
+    runAgentName?: string;
+}): string | undefined;
+/**
+ * 子会话的**展示名**（给人看）：团队成员用成员名，其余子代理用自身预设名（`meta.agentName`）；
+ * 主会话 / 无会话 / 无身份线索返回 undefined。**只用于展示与遥测标签，不要拿它查表。**
+ */
+export declare function resolveSubAgentDisplayName(session: {
+    id?: string;
+    storeId?: string;
+    meta?: Record<string, unknown>;
+} | undefined): string | undefined;
+/**
+ * 子会话的**查表键**（REPL 沙箱白名单 / overlay 缓存用）：只认「预设名」这一种语义。
+ *
+ * 与展示名刻意分开（评审）：团队成员会把自己的成员名写进 `meta.agentName`（teammate-runner），
+ * 于是 `meta.agentName` 同时承载「预设名」与「成员名」两种含义 —— 拿成员名去查 agent 配置查不到，
+ * 只能落到默认 agent 的兜底（既不是成员自己的白名单、也不是「不过滤」）。取不到可信的预设名时
+ * 返回 undefined = 不额外收窄（与改动前一致），不去猜。
+ */
+export declare function resolveSubAgentAgentKey(session: {
+    id?: string;
+    storeId?: string;
+    meta?: Record<string, unknown>;
+} | undefined): string | undefined;
+/** 展示名的**派发侧镜像**：子会话还没建时拿不到 `meta.teamContext`，但这对值就是稍后写进 session 的同一对。 */
+export declare function resolveSubAgentDisplayNameFromParts(input: {
+    memberName?: string;
+    presetName?: string;
+}): string | undefined;
+/**
+ * 查表键的**派发侧镜像**（AgentManager.sandboxScopedAgentView 传身份用）：
+ * 预设名与成员名**同值**（团队成员把自己的名字写进 meta.agentName）时判为「没有可信预设名」→ undefined，
+ * 与运行期 `resolveSubAgentAgentKey` 同源 —— 否则派发侧按成员名收窄、执行侧判不到，两边分叉。
+ */
+export declare function resolveSubAgentAgentKeyFromParts(input: {
+    memberName?: string;
+    presetName?: string;
+}): string | undefined;

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

@@ -6,9 +6,9 @@
  * wastes tokens/credits.
  *
  * Detection rules:
- * 1. Generic loop: blacklisted tool with identical arguments 4 consecutive times
+ * 1. Generic loop: blacklisted tool with semantically identical JSON arguments 4 consecutive times
  * 2. Read file loop: Read tool targeting the same file_path 40 consecutive times
- * 3. Non-blacklist loop: any tool NOT in blacklist with identical arguments 40 consecutive times
+ * 3. Non-blacklist loop: any tool NOT in blacklist with semantically identical JSON arguments 40 consecutive times
  */
 import type { AgentInputItem } from '../../../../cbc-shared/lib/node/index.js';
 import { Logger } from '../../../../telemetry/lib/common/index.js';
@@ -38,14 +38,15 @@ export declare class ToolCallLoopDetectorImpl implements ToolCallLoopDetector {
         arguments: string;
     }>;
     /**
-     * Check for generic loop: same tool with identical arguments N consecutive times.
+     * Check for generic loop: same tool with semantically identical JSON arguments
+     * N consecutive times. Malformed or very large argument payloads retain exact-string semantics.
      */
     protected checkGenericLoop(tailCalls: Array<{
         name: string;
         arguments: string;
     }>): LoopDetectionResult;
     /**
-     * Check for non-blacklist tool loop: any tool NOT in the blacklist with identical arguments
+     * Check for non-blacklist tool loop: any tool NOT in the blacklist with semantically identical JSON arguments
      * called N consecutive times (threshold: NON_BLACKLIST_LOOP_THRESHOLD).
      * Scans from the tail of input, collecting only non-blacklist function_call items.
      */

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 次 / 周期序列重复 10 轮）。
+ *   它覆盖新增的两条规则（同工具连续 40 次，Bash 与 Write 单独放到 80 次 / 周期序列重复 10 轮）。
  *
  * 两者刻意并存：旧规则的静默语义已被线上验证，不因新能力回归。
  */

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

@@ -5,8 +5,13 @@
  */
 import type { ToolCallLoopTriggerType } from '../../../../telemetry/lib/common/event/types/craft.js';
 export interface ToolCallLoopThresholds {
-    /** 同一工具连续调用达到该次数即判定为循环。 */
+    /** 同一工具连续调用达到该次数即判定为循环。Bash / Write 走单独阈值。 */
     consecutiveThreshold: number;
+    /**
+     * Bash 与 Write 连续调用的单独阈值。长任务里模型会连续跑很多条命令、
+     * 或连续落很多个文件，只看工具名时 40 次容易把正常推进误判成循环。
+     */
+    bashConsecutiveThreshold: number;
     /** AAB 块需要连续重复的轮数。 */
     sequenceRepeats: number;
 }
@@ -17,6 +22,9 @@ export interface ToolCallLoopHit {
     /** 重复序列的周期长度；AAB 恒为 3，连续同工具恒为 1。 */
     patternLength: number;
 }
+/** 与 `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;
@@ -36,7 +44,7 @@ export declare class ToolCallLoopTracker {
      * 记录一次即将执行的工具调用，返回本次是否命中循环。
      *
      * 命中优先级：先判连续同工具，再判 AAB 重复。两条规则的阈值默认不重叠
-     * （40 次 vs AAB 重复 10 轮），实践中不会互相抢占。
+     * （普通工具 40 次、Bash / Write 80 次 vs AAB 重复 10 轮），实践中不会互相抢占。
      */
     record(toolName: string): ToolCallLoopHit | undefined;
     /**
@@ -52,14 +60,18 @@ export declare class ToolCallLoopTracker {
  * - `ABC`（三者互不相同）通常是正常的多步工作流（读文件 → 改文件 → 跑测试，
  *   然后换下一个文件），按周期重复判它循环误伤面太大；
  * - `ABAB` 这类两工具交替同样不判，避免把翻页 / 分批处理误当循环；
- * - `AAA…` 属于连续同工具，由 consecutiveThreshold 那条规则负责。
+ * - `AAA…` 属于连续同工具，由 consecutiveThreshold / bashConsecutiveThreshold（Bash、Write）那条规则负责。
  *
  * `X ≠ Y` 顺带保证了 AAB 一定是本原周期（唯一可能的更短整除周期是 1，
  * 那要求三个元素全等），所以不需要额外的本原性校验。
  */
 export declare function matchesRepeatedAabSequence(history: readonly string[], repeats: number): boolean;
 /**
- * 读取阈值配置。两个环境变量只用于 QA 快速复现，生产不设置即走默认值。
+ * 读取阈值配置。环境变量只用于 QA 快速复现，生产不设置即走默认值。
  * AAB 的周期是形状定义的一部分，不开放配置。
+ *
+ * `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;

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

@@ -16,6 +16,7 @@ import { CompactStrategy, type ContextCompactResult, ContextCompactSummarizeOpti
  * 不包含任何具体的压缩逻辑实现。
  */
 export declare class ContextCompactSummarizerImpl implements ContextCompactSummarizer {
+    private activeCompactions?;
     protected readonly productManager: ProductManager;
     protected readonly agentManager: AgentManager;
     protected readonly logger: Logger;
@@ -25,6 +26,7 @@ export declare class ContextCompactSummarizerImpl implements ContextCompactSumma
     protected readonly strategyProvider: Provider<CompactStrategy>;
     compactAndSummarize(session: Session, options?: ContextCompactSummarizeOptions): Promise<boolean>;
     compactWithResult(session: Session, options?: ContextCompactSummarizeOptions): Promise<ContextCompactResult>;
+    private compactWithResultOwned;
     /**
      * 按优先级匹配（PreMessage → MaxToken），跳过 Blocking（仅作最终兜底），执行第一个命中的策略；
      * 都不命中则安全网回落到 Blocking。逻辑与压缩 span 化之前完全一致，只是把散落的 `return` 收敛成

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

@@ -1,7 +1,10 @@
+import type { AgentInputItem } from '../../../../cbc-shared/lib/node/index.js';
+import type { CompactionTrigger } from '../../../../telemetry/lib/common/index.js';
 import { Session } from '../session/session-protocol.js';
 export declare const PromptContextProvider: unique symbol;
 export declare const PromptContextInitializer: unique symbol;
 export declare const ContextCompactSummarizer: unique symbol;
+export declare const ManualCompactRequestHandler: unique symbol;
 export declare const PromptRenderer: unique symbol;
 export declare const COMPACT_PROMPT = "compact-prompt";
 export declare const DEFAULT_TOKEN_THRESHOLD = 0.7;
@@ -190,6 +193,8 @@ export interface ContextCompactSummarizeOptions {
     type?: CompactType;
     /** Stable identity shared by live updates and the durable compact boundary. */
     compactionId?: string;
+    /** Why this compaction runs; defaults from `type` (manual / pre_message_threshold / emergency_threshold). */
+    trigger?: CompactionTrigger;
 }
 export type ContextCompactSkipReason = 'already_compacting' | 'pending_interruption' | 'auto_disabled' | 'empty_history' | 'already_compacted' | 'non_default_agent' | 'below_threshold';
 export type ContextCompactFailureReason = 'strategy_failed' | 'strategy_unavailable';
@@ -214,6 +219,8 @@ export declare function createCompactionId(): string;
 export declare const SESSION_META_COMPACT_TYPE: 'compactType';
 /** Current stable compaction identity, persisted onto the boundary item. */
 export declare const SESSION_META_COMPACTION_ID: 'compactionId';
+/** Trigger of the compaction the summarizer is running; unset for a typed `/compact`. */
+export declare const SESSION_META_COMPACTION_TRIGGER: 'compactionTrigger';
 /**
  * session.meta 上标记当前 compact 成功后会继续执行一次真实 agent run。
  *
@@ -321,6 +328,16 @@ export interface ContextCompactSummarizer {
     /** Compatibility wrapper for existing automatic-compaction callers. */
     compactAndSummarize(session: Session, options?: ContextCompactSummarizeOptions): Promise<boolean>;
 }
+/**
+ * Host-owned boundary for external `/compact` requests.
+ *
+ * AgentService invokes this before creating a normal run lifecycle when an
+ * interactive host opts in. Implementations must return false for internal compact
+ * inputs so strategy-owned internal runs cannot recursively re-enter this boundary.
+ */
+export interface ManualCompactRequestHandler {
+    tryHandle(input: string | AgentInputItem[], session: Session): Promise<boolean>;
+}
 export interface PromptRenderer {
     render(template: string, context?: PromptContext): Promise<string>;
 }

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

@@ -1,4 +1,5 @@
 export * from './context-protocol.js';
+export * from './compaction-lineage.js';
 export * from './context-host-protocol.js';
 export * from './prompt-context-provider.js';
 export * from './prompt-renderer.js';

package/cli/dist-server/types/workspace/cbc-core/lib/node/context/pre-message-compact-strategy.d.ts

@@ -4,8 +4,7 @@ import { CompactStrategyContext, ContextCompactSummarizeOptions } from './contex
 /**
  * PreMessage 压缩策略：在发送用户消息前触发。
  *
- * 触发条件：PRE_MESSAGE_AUTO 或 WorkBuddy 的 USER_COMMAND。
- * CBC 手动 /compact 不走该策略，继续由 compact agent 路径处理。
+ * 触发条件：PRE_MESSAGE_AUTO 或 USER_COMMAND（WorkBuddy / TUI 手动压缩）。
  *
  * 流程：
  * 1. Engineering compact (no LLM call)

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

@@ -1,31 +1,15 @@
-/**
- * Agent-trigger payload helper, shared by SessionHookManager and ToolHookManager.
- *
- * Mirrors Claude Code's `createBaseHookInput` (utils/hooks.ts) so that every
- * hook event carries enough context for users to branch on
- * "main thread vs sub-agent" inside their Settings-level hooks.
- *
- * Rules (CC parity):
- *  - `agent_type` is the agent's display name; populated from `session.agentName`
- *    when set. On the main thread this is the `--agent` flag (when used) or the
- *    default agent name. Inside a sub-agent this is the sub-agent's `name`
- *    (e.g. "Explore", "Plan", "general-purpose").
- *  - `agent_id` is only meaningful inside a sub-agent run — CC leaves it
- *    `undefined` on the main thread. We honour the same convention by only
- *    emitting it when `session.storeId` is present (sub-agent sessions get a
- *    `agent-{8}` storeId; main sessions do not).
- *
- * Kept dependency-free so it can be imported from anywhere — including modules
- * that must avoid pulling the full `../session` barrel (which transitively
- * loads SessionManager / tips and triggers IoC initialisation).
- */
 export interface AgentTriggerLike {
     id?: string;
     agentName?: string;
     storeId?: string;
+    /** 会话 meta：身份标签要读 agentName / teamContext.memberName，parentSessionId 供子会话判定。 */
     meta?: {
         parentSessionId?: string;
-    };
+        agentName?: string;
+        teamContext?: {
+            memberName?: unknown;
+        };
+    } & Record<string, unknown>;
 }
 export declare function buildAgentTrigger(session: AgentTriggerLike | undefined | null): {
     agent_id?: string;

package/cli/dist-server/types/workspace/cbc-core/lib/node/hooks/hook-protocol.d.ts

@@ -31,7 +31,10 @@ export interface HookInput {
      */
     reason?: SessionEndReason;
     /**
-     * User prompt content (for UserPromptSubmit event)
+     * User prompt content.
+     * - UserPromptSubmit: the submitted prompt text.
+     * - UserPromptExpansion: Claude Code spec required field, always sent — the
+     *   raw, pre-expansion text as typed by the user (e.g. "/deploy prod").
      */
     prompt?: string;
     /**