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

package/cli/dist-server/types/vendor/cbc-core/node/session/recovery-budget.d.ts

@@ -0,0 +1,55 @@
+import type { Session } from './session-protocol';
+/**
+ * `finish_reason=error` 三种表现（已有输出 / 仅 reasoning / 零 token）共用的预算键。
+ *
+ * 三者是同一次上游故障的不同形态，而且会在恢复过程中互相转化（第一次零 token、
+ * 重试后只吐 reasoning、再重试吐了内容后又 error）。各记各的会让一次故障的总轮数
+ * 远超约定上限，所以必须认领同一个键。
+ */
+export declare const ERROR_RECOVERY_COUNT_META_KEY = "errorRecoveryCount";
+/**
+ * 流开始之后的网络错误（错误仍带原始 errno）使用的预算键。
+ *
+ * 响应头之前的连接失败由模型层连接级重试处理，耗尽后被归一化成 HTTP 502 上抛，
+ * 不会再走到这里——两层不会为同一次失败接力。
+ */
+export declare const NETWORK_RECOVERY_COUNT_META_KEY = "networkErrorRetryCount";
+/**
+ * `finish_reason=error` 后注入给模型的续写提示。
+ *
+ * 与截断续写（TRUNCATION_CONTINUATION_PROMPT）的区别是刻意去掉了「把剩下的工作拆小」：
+ * 那句是在修「一次输出太长」的因果，上游内部错误与输出长度无关，带上它既是错误归因，
+ * 也可能让模型把任务切碎、多烧轮次。同样不告诉模型「是服务端出错」——那会给它道歉和
+ * 复述的由头，与 no apology / no recap 自相矛盾。
+ */
+export declare const ERROR_RECOVERY_PROMPT: string;
+/**
+ * 包成 error-recovery system-reminder：stream-json 等输出通道会把只含 system-reminder
+ * 的内部用户消息清空丢弃，避免恢复提示混进用户可见的对话。
+ */
+export declare function buildErrorRecoveryReminder(): string;
+export declare function readRecoveryBudgetCount(session: Session, key: string): number;
+export declare function hasExhaustedRecoveryBudget(session: Session, key: string, limit?: number): boolean;
+/**
+ * 同步完成「判定 + 认领」，返回本次恢复的序号（1-based）；预算已用尽返回 `undefined`。
+ *
+ * 判定与消耗必须在同一个同步段里完成：分散到 `await` 两侧时，两处调用可能同时在
+ * `count = limit - 1` 通过检查，上限就不再成立。
+ */
+export declare function claimRecoveryBudget(session: Session, key: string, limit?: number): number | undefined;
+/** 认领后没有真正发起恢复（退避期间被取消、发起失败）时退回额度。 */
+export declare function releaseRecoveryBudget(session: Session, key: string): void;
+/** 清零并返回旧值，供日志使用。 */
+export declare function resetRecoveryBudget(session: Session, key: string): number;
+/**
+ * 「下一个模型请求是自动恢复轮」的一次性标记。
+ *
+ * 恢复轮的首 token 时限比首次请求短（见模型层）。这个标记在发起恢复 run 前由恢复
+ * 入口显式写入，由模型层在该 run 的第一个模型请求上读取并清除——之后同一 run 的工具
+ * 循环请求回到普通时限。不能改用重试计数反推「是否恢复轮」：计数跨多个模型请求累计，
+ * 反推会让恢复链之后的所有请求都被当成恢复轮。
+ */
+export declare const RECOVERY_REQUEST_PENDING_META_KEY = "recoveryRequestPending";
+export declare function markRecoveryRequestPending(session: Session): void;
+export declare function consumeRecoveryRequestPending(session: Session | undefined): boolean;
+export declare function clearRecoveryRequestPending(session: Session): void;

package/cli/dist-server/types/vendor/cbc-core/node/session/session-hook-manager.d.ts

@@ -208,4 +208,19 @@ export declare class SessionHookManagerImpl implements SessionHookManager {
      * Does NOT support continueRequest.
      */
     executeFinalStopHooks(session: Session, reason?: FinalStopReason): Promise<void>;
+    /**
+     * UserPromptExpansion — Claude Code 官方事件：任何用户输入的命令/skill 展开成
+     * prompt、送进模型之前统一从这里触发，可阻断展开。`command_args` / `prompt` 按
+     * 官方 schema 是必填字段（无参数时发空串，而不是整个省略 key）。
+     */
+    executeUserPromptExpansionHooks(session: Session, payload: {
+        expansionType: 'slash_command' | 'mcp_prompt' | string;
+        commandName: string;
+        commandArgs: string;
+        commandSource?: string;
+        prompt: string;
+    }): Promise<{
+        allowed: boolean;
+        message?: string;
+    }>;
 }

package/cli/dist-server/types/vendor/cbc-core/node/session/session-manager-host-protocol.d.ts

@@ -1,5 +1,5 @@
 import type { AgentInputItem } from '../../../cbc-shared/node/index.js';
-import type { ModelResponseMetadata, Session } from './session-protocol';
+import type { ModelCallGeneration, ModelResponseMetadata, Session } from './session-protocol';
 export declare const SessionCheckpointHost: unique symbol;
 export interface SessionCheckpointHost {
     createCheckpoint(session: Session): Promise<void>;
@@ -57,7 +57,8 @@ export declare const SessionResponseTelemetryHost: unique symbol;
 export interface SessionResponseTelemetryHost {
     reportChatRequestResponseTelemetry(session: Session, result: NonNullable<Session['resultSubject']['value']>, isSuccessful: boolean, error: unknown, metadata: ModelResponseMetadata): Promise<void>;
     reportMessageResponseTelemetryStream(session: Session, usage: SessionResponseUsage | undefined, metadata: ModelResponseMetadata, error: unknown): Promise<void>;
-    reportChatMessageStatus(session: Session, errorCode: string, error?: unknown): Promise<void>;
+    /** Status of one model call (`generation`); run failures no model call owns are not reported. */
+    reportChatMessageStatus(session: Session, errorCode: string, generation: ModelCallGeneration, error?: unknown): Promise<void>;
 }
 export type SessionResponseTelemetrySnapshot = Pick<NonNullable<Session['telemetry']>, 'modelId' | 'modelName' | 'currentTurn' | 'traceId'>;
 export declare const SessionResponseObserver: unique symbol;

package/cli/dist-server/types/vendor/cbc-core/node/session/session-manager.d.ts

@@ -4,7 +4,7 @@ import { Logger } from '../../../../workspace/telemetry/lib/common/index.js';
 import { BehaviorSubject } from 'rxjs';
 import { SessionRequestContextHost, SessionSettingsHost as SettingsManager, SessionUsageHost as UserStateManager } from './session-host-protocol';
 import { SessionBackgroundTaskHost as ToolManager, SessionCheckpointHost as CheckpointService, SessionProgressHost as ProgressSyncService, SessionResponseObserver as GalileoSessionBridge, SessionResponseTelemetryHost as TelemetryService, SessionSchedulerHost as CronSchedulerService, SessionSensitiveProjectionHost, SessionTaskLifecycleHost as AgentTaskManager } from './session-manager-host-protocol';
-import { AgentInputItemProcessor, InterruptionService, ModelResponseInterceptor, ModelResponseMetadata, Session, SessionFactory, SessionGetOptions, SessionHookManager, SessionManager, SessionStore } from './session-protocol';
+import { AgentInputItemProcessor, InterruptionService, ModelResponseInterceptor, ModelResponseMetadata, OverrideModelSource, Session, SessionFactory, SessionGetOptions, SessionHookManager, SessionManager, SessionStore } from './session-protocol';
 import { SessionRunStateMachine } from './session-run-state-machine-protocol';
 export declare class SessionManagerImpl implements SessionManager, ApplicationLifecycle<Application> {
     protected readonly sessionFactory: SessionFactory;
@@ -33,8 +33,19 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
     private sessionStartTimes;
     private addHistoryLocks;
     private resultSubscriptions;
+    private readonly resultSubscriptionOwners;
+    /**
+     * 每个 sessionId 当前活着的会话对象。身份守卫不能只认 result 订阅的登记：
+     * 订阅由调用方事后 `initRunResultHandler` 挂上（teammate / agent-task），而
+     * drain / team-inbox / turn-metrics 在 create 时就按 id 注册了，中间那段
+     * 「已注册、无订阅」的窗口里 owner 读不到，旧任务的延迟释放会摘掉同 id 后继
+     * 会话的注册。WeakRef：登记不得延长会话寿命，deref 为空即无需保护的对象。
+     */
+    private readonly liveSessionsById;
     private overridePermissionModes;
     private overrideModels;
+    /** 与 overrideModels 同生命周期的意图来源（user / declared / materialized）。 */
+    private overrideModelSources;
     /**
      * Issue #12554：会话级 thinking override（按 sessionId 隔离）。
      * 由 ACP setSessionConfigOption('thought_level') 或 prompt _meta 写入。
@@ -177,13 +188,15 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
      *
      * 幂等：未注册的 id 为 no-op；DI 容错：精简变体缺 service 时降级跳过。
      */
-    releaseInMemory(id: string): void;
+    releaseInMemory(target: string | Session): void;
     rename(session: Session, name: string): Promise<void>;
     setOverridePermissionMode(sessionId: string, mode: PermissionMode): void;
     getOverridePermissionMode(sessionId: string): PermissionMode | undefined;
-    setOverrideModel(sessionId: string, model: string): void;
+    setOverrideModel(sessionId: string, model: string, source?: OverrideModelSource): void;
     getOverrideModel(sessionId: string): string | undefined;
-    setRuntimeModel(session: Session | undefined, modelId: string): void;
+    getOverrideModelSource(sessionId: string): OverrideModelSource | undefined;
+    clearOverrideModel(sessionId: string): void;
+    setRuntimeModel(session: Session | undefined, modelId: string, source?: OverrideModelSource): void;
     setRuntimeOutputStyle(session: Session | undefined, style: string): void;
     /**
      * Issue #83229：把 settings.json 中的 model / outputStyle 读一次"钉"进 session.options，

package/cli/dist-server/types/vendor/cbc-core/node/session/session-persistence-error.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed local-transcript I/O failure (issue #119545).
+ *
+ * The only reason this type exists: `addHistory` must be able to tell "the
+ * local JSONL copy could not be written" apart from "this turn is broken".
+ * Windows `EBUSY` on the transcript is a third-party sharing violation, and a
+ * side-channel copy must never terminate a turn that is still executing tools.
+ *
+ * Everything else about persistence stays best-effort on purpose: there is no
+ * pending queue, no cross-process outbox and no durability barrier, so nothing
+ * else in the runtime waits on, or can be vetoed by, this file.
+ */
+export type SessionPersistencePhase = 'open' | 'stat' | 'write' | 'close' | 'rollback';
+export type SessionPersistenceRollbackOutcome = 'not-needed' | 'succeeded' | 'failed';
+export interface SessionPersistenceErrorOptions {
+    phase: SessionPersistencePhase;
+    cause: unknown;
+    attempt?: number;
+    rollbackOutcome?: SessionPersistenceRollbackOutcome;
+    retryable?: boolean;
+}
+/**
+ * Windows sharing violations and their POSIX lookalikes. `EBUSY` is the one
+ * this ticket measured (25% of appends within 10ms of the previous write);
+ * `EPERM` / `EACCES` ride along because the same scanners produce them.
+ */
+export declare function isRetryableSessionPersistenceError(error: unknown): boolean;
+export declare class SessionPersistenceError extends Error {
+    readonly phase: SessionPersistencePhase;
+    readonly code?: string;
+    readonly attempt: number;
+    readonly rollbackOutcome: SessionPersistenceRollbackOutcome;
+    readonly retryable: boolean;
+    constructor(options: SessionPersistenceErrorOptions);
+}
+/**
+ * Duck-typed on purpose: core and the host package can each hold their own copy
+ * of this class, so `instanceof` is not reliable across the package boundary.
+ * The required fields keep a foreign error named `SessionPersistenceError` from
+ * being mistaken for one of ours — an unrecognized error still fails the run,
+ * which is the safe direction.
+ */
+export declare function isSessionPersistenceError(error: unknown): error is SessionPersistenceError;

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

@@ -2,6 +2,7 @@ import { Deferred } from '@celljs/core';
 import { type AgentInputItem, ApprovalOptions, type Checkpoint, FinalStopReason, NotificationType, PermissionMode, ReasoningEffortLevel, type ResponseStreamEvent, type RunItem, type RunResult, type RunState, type RunToolApprovalItem, type SdkCapabilities, SessionEndReason, SessionStartSource, type StreamedRunResult, type TerminalEvent, type ToolDeferOverlaySnapshot, ToolPermissionContext, type Usage } from '../../../cbc-shared/node/index.js';
 import { Command } from '../../../../workspace/product/lib/common/index.js';
 import { BehaviorSubject, Subject } from 'rxjs';
+import type { CompactionLineage } from '../context/compaction-lineage';
 import { BackgroundTask } from './background-task-protocol';
 import type { SessionRunStateSnapshot } from './session-run-state-machine-protocol';
 import type { Lane, LanePointer, SessionKey, SessionStoreEntry } from './session-store-contract';
@@ -86,9 +87,11 @@ export type AgentState = 'agent_pending' | 'agent_start' | 'agent_tool_start' |
  *                              则 emit，触发 UI 显示"正在同步文件"提示)
  */
 export type AgentPhase = 'preparing' | 'model_requesting' | 'model_streaming' | 'model_done' | 'tool_executing' | 'waiting_for_permission' | 'waiting_for_user' | 'retrying' | 'finalization_file_projection_sync' | 'finalization_file_projection_sync_notify' | 'idle';
+export type AgentRetryReason = 'network';
 export interface AgentPhaseInfo {
     phase: AgentPhase;
     toolName?: string;
+    toolCallId?: string;
     streamingToolName?: string;
     startedAt: number;
     /**
@@ -101,6 +104,13 @@ export interface AgentPhaseInfo {
         current: number;
         total: number;
     };
+    /**
+     * 仅 retrying phase 使用，经 ACP `_meta['codebuddy.ai/agentPhase']` 透传给上层。
+     * 缺省表示原因未分类（如流超时），不代表网络正常。
+     */
+    retry?: {
+        reason: AgentRetryReason;
+    };
 }
 export declare const AgentPhaseUtils: {
     /** Create an AgentPhaseInfo with the current timestamp. */
@@ -177,6 +187,8 @@ export interface PreToolUseHookResult {
     permissionDecision?: 'allow' | 'deny' | 'ask';
     permissionDecisionReason?: string;
     runtimeSecurity?: Record<string, unknown>;
+    /** PreToolUse `continue:false` — stop the current turn after the deny result is recorded. */
+    preventContinuation?: boolean;
 }
 export interface Session {
     id: string;
@@ -206,6 +218,8 @@ export interface Session {
      */
     replSandboxDepth?: number;
     state?: RunState<any, any>;
+    /** Emitted after a physical run releases its lifecycle owner and abort links. */
+    runSettledSubject?: Subject<void>;
     createdAt: number;
     updatedAt: number;
     meta?: Record<string, any>;
@@ -348,6 +362,14 @@ export interface Session {
      * field and pass it through as `options.maxTurns` explicitly.
      */
     lastRunMaxTurns?: number;
+    /**
+     * Latest agent-loop model call number (`providerData.stepSeq`). Unlike the
+     * SDK turn counter it survives runs, compaction and resume; see
+     * `allocateModelStepSeq`.
+     */
+    modelStepSeq?: number;
+    /** Compactions of this Session's context; see `getCompactionLineage`. */
+    compactionLineage?: CompactionLineage;
     queue: AgentInputItem[];
     queueSubject: BehaviorSubject<AgentInputItem[]>;
     /**
@@ -638,6 +660,12 @@ export interface Session {
          * Context from UserPromptSubmit hook to be injected into current user message
          */
         userPromptSubmitContext?: string;
+        /**
+         * Context from UserPromptExpansion hook (hookSpecificOutput.additionalContext),
+         * to be injected alongside the expanded prompt (Claude Code parity: same
+         * injection point as UserPromptSubmit — "alongside the submitted prompt").
+         */
+        userPromptExpansionContext?: string;
         /**
          * Context from PostToolUse hook to be injected after tool execution
          */
@@ -849,7 +877,7 @@ export interface SubagentInvocationRecord {
     lifecycle: SubagentLifecycleSnapshot;
 }
 export type SubagentLifecycleDescriptor = Omit<SubagentLifecycleSnapshot, 'status' | 'updatedAt' | 'usage'>;
-export type CombineEvent = (AgentInputItemEvent | ModelRawResponseEvent | ResultEndEvent | InterruptResultEvent | NoticeEvent | SubagentStatusEvent | CompactionLifecycleEvent | TerminalEvent) & CombineEventMeta;
+export type CombineEvent = (AgentInputItemEvent | AgentSdkStreamEvent | ModelRawResponseEvent | ResultEndEvent | InterruptResultEvent | NoticeEvent | SubagentStatusEvent | CompactionLifecycleEvent | TerminalEvent) & CombineEventMeta;
 export interface CompactionLifecycleEvent {
     type: 'compaction';
     data: {
@@ -864,6 +892,11 @@ export interface SubagentStatusEvent {
     type: 'subagent_status';
     data: SubagentLifecycleSnapshot;
 }
+/** Original SDK stream payload, observed by the existing single stream consumer. */
+export interface AgentSdkStreamEvent {
+    type: 'sdk';
+    data: import('../../../cbc-shared/node/index.js').RunStreamEvent;
+}
 export interface AgentInputItemEvent {
     type: 'input';
     data: AgentInputItem;
@@ -915,6 +948,8 @@ export interface SessionOptions {
     debugToStderr?: boolean;
     verbose?: boolean;
     print?: boolean;
+    /** Host Bash output preference; omitted preserves the CLI's PTY selection. */
+    usePty?: boolean;
     outputFormat?: 'text' | 'json' | 'stream-json';
     inputFormat?: 'text' | 'stream-json';
     /** Whether to persist the session transcript. Defaults to true; false keeps history in memory only. */
@@ -1050,6 +1085,13 @@ export interface SessionRewindMutationOptions {
     cwd: string;
     headMessageId: string | undefined;
 }
+/**
+ * model override 的意图来源：决定该值是否等价于「用户显式选择」。
+ * - 'user'：/model 命令、ACP set_model、SDK 控制信号等用户动作；
+ * - 'declared'：主 Agent 声明模型（declaredModel）联动写入；
+ * - 'materialized'：Web UI 会话装配期钉住的兜底解析值（非用户意图）。
+ */
+export type OverrideModelSource = 'user' | 'declared' | 'materialized';
 export interface SessionManager {
     getCurrent(): Session;
     setCurrent(session: Session): void;
@@ -1123,9 +1165,11 @@ export interface SessionManager {
      *
      * 幂等：未注册的 sessionId 为 no-op。
      *
-     * @param id 已完成 subagent 的 session id
+     * @param target 传 Session 对象时，索引键与身份校验同源——只有注册表当前持有
+     * 的正是这个对象才释放，复用同一 sessionId 的后继对象不会被误清。只拿得到
+     * id 的调用方（RPC、`remove(id)`）传字符串，此时不做身份校验。
      */
-    releaseInMemory(id: string): void;
+    releaseInMemory(target: string | Session): void;
     /**
      * 该 sessionId 是否已在本进程通过 get() 加载过（且尚未 remove()/releaseInMemory()）。
      *
@@ -1150,11 +1194,15 @@ export interface SessionManager {
     setOverridePermissionMode(sessionId: string, mode: PermissionMode): void;
     getOverridePermissionMode(sessionId: string): PermissionMode | undefined;
     /**
-     * 设置 session 的 model 覆盖值（来自 SDK control signal）
-     * 这些值会覆盖 CLI 参数和配置文件的设置
+     * 设置 session 的 model 覆盖值。source 记录意图来源，供「是否用户显式选择」判定：
+     * - 'user'（默认）：/model 命令、ACP set_model、SDK 控制信号等用户动作；
+     * - 'declared'：主 Agent 声明模型（declaredModel）联动写入；
+     * - 'materialized'：Web UI 会话装配期钉住的兜底解析值（非用户意图）。
      */
-    setOverrideModel(sessionId: string, model: string): void;
+    setOverrideModel(sessionId: string, model: string, source?: OverrideModelSource): void;
     getOverrideModel(sessionId: string): string | undefined;
+    getOverrideModelSource(sessionId: string): OverrideModelSource | undefined;
+    clearOverrideModel(sessionId: string): void;
     /**
      * 设置会话运行时模型：同步写 session.options.model + requestOptions.model + override map。
      *
@@ -1163,7 +1211,7 @@ export interface SessionManager {
      * 供 applyOverrideModel 每轮重建 requestOptions（Issue #82146）。/model 命令与模型面板
      * 共用此入口；ACP set_model（applyRuntimeSessionModel）仍为独立实现，待统一收敛。
      */
-    setRuntimeModel(session: Session | undefined, modelId: string): void;
+    setRuntimeModel(session: Session | undefined, modelId: string, source?: OverrideModelSource): void;
     /**
      * 设置会话运行时 outputStyle：同步写 session.options.outputStyle。
      *
@@ -1216,8 +1264,31 @@ export interface SessionManager {
      */
     flushHistory(session: Session): Promise<void>;
 }
+/**
+ * Cumulative transcript persistence counters (issue #119545 埋点建议).
+ * A best-effort side channel, so every reader must treat the numbers as a
+ * snapshot that may be sampled at any moment.
+ */
+export interface TranscriptPersistenceMetrics {
+    /** In-band retry attempts consumed. */
+    retries: number;
+    /** Batches that only landed because of a retry. */
+    retrySucceeded: number;
+    /** Batches given up on after the retry budget. */
+    abandonedBatches: number;
+    /** Lines lost with those batches. */
+    abandonedLines: number;
+}
 export interface SessionStore {
     getSessionFilePath(id: string, parentSessionId?: string, cwd?: string): string;
+    /**
+     * Transcript persistence counters, when the implementation keeps any.
+     * Optional so in-memory and host-delegating stores do not have to fake it.
+     * Exposed so callers that observe a degradation can log the counters from
+     * their own call site: the store's own abandon audit line is best-effort
+     * and a lost line would otherwise take the only copy of the numbers.
+     */
+    transcriptPersistenceMetrics?(): Readonly<TranscriptPersistenceMetrics>;
     get(id: string, options?: SessionGetOptions): Promise<Session | undefined>;
     getAcrossProjects(id: string, options?: SessionGetOptions): Promise<Session | undefined>;
     save(session: Session, cwd?: string): Promise<void>;
@@ -1376,6 +1447,26 @@ export interface SessionHookManager {
      * Does NOT support continueRequest.
      */
     executeFinalStopHooks(session: Session, reason?: FinalStopReason): Promise<void>;
+    /**
+     * UserPromptExpansion — Claude Code 官方事件（非 cbc 专属扩展）：任何用户输入的
+     * 命令/skill 在展开成 prompt、送进模型之前统一从这里触发，可阻断展开。适用于
+     * skill、自定义命令、Dynamic Workflow、MCP prompt 等一切"输入即展开"的路径，
+     * 不是只服务某一个具体调用方（如统一资产门控）。
+     */
+    executeUserPromptExpansionHooks(session: Session, payload: {
+        /** Claude Code spec: 'slash_command' for skill/custom commands, 'mcp_prompt' for MCP prompts. */
+        expansionType: 'slash_command' | 'mcp_prompt' | string;
+        commandName: string;
+        /** Claude Code spec: required field (empty string when no args), always sent. */
+        commandArgs: string;
+        /** e.g. Skill.source / Command.scope ('project' | 'user' | 'plugin' | 'mcp' | ...). */
+        commandSource?: string;
+        /** Claude Code spec: required field — raw, pre-expansion prompt text as typed by the user. */
+        prompt: string;
+    }): Promise<{
+        allowed: boolean;
+        message?: string;
+    }>;
 }
 export interface RunItemProcessor {
     process(runItem: RunItem): Promise<void>;
@@ -1444,6 +1535,7 @@ export interface InterruptionService {
     approve(item: RunToolApprovalItem, options?: ApprovalOptions): void;
     reject(item: RunToolApprovalItem, options?: {
         decision?: 'deny' | 'rejectAndExitPlan';
+        cancelTurn?: boolean;
     }): void;
     waitFor(session: Session): Promise<void>;
     /** Resolve the main/leader session for a given session (returns self if already main). */
@@ -1494,9 +1586,10 @@ export interface InterruptionService {
      *
      * 幂等：session 未注册时为 no-op。只清内存映射，不动磁盘 jsonl。
      *
-     * @param sessionId 已完成 subagent 的 session id
+     * @param target 传 Session 对象时按对象身份校验，同 id 的后继对象不会被误清；
+     * 只拿得到 id 的调用方传字符串，此时不做身份校验。
      */
-    releaseSession(sessionId: string): void;
+    releaseSession(target: string | Session): void;
 }
 export interface MessageQueueManager {
     enqueueMessage(session: Session, message: AgentInputItem): string;
@@ -1653,6 +1746,12 @@ export interface TurnMetricsReporter {
      */
     unregister(sessionId: string): void;
 }
+/** Ids of one model call, as stamped by the model wrapper. */
+export interface ModelCallGeneration {
+    messageId: string;
+    conversationRequestId?: string;
+    stepSeq?: number;
+}
 export interface ModelResponseMetadata {
     /** 响应中的模型 ID */
     model?: string;
@@ -1666,6 +1765,8 @@ export interface ModelResponseMetadata {
      * 都带 providerData.messageId === 此值，handleContentFilteredResponse 据此剔除并替换为安全提示。
      */
     contentFilterMessageId?: string;
+    /** Correlation of the generation that just completed, as stamped by the model wrapper. */
+    generation?: ModelCallGeneration;
     usage?: {
         prompt_tokens: number;
         completion_tokens: number;

package/cli/dist-server/types/vendor/cbc-core/node/session/session-run-state-machine-protocol.d.ts

@@ -1,5 +1,5 @@
 import type { Observable } from 'rxjs';
-import type { Session } from './session-protocol';
+import type { AgentRetryReason, Session } from './session-protocol';
 export declare const SessionRunStateMachine: unique symbol;
 export declare const SessionRunStateProjectionService: unique symbol;
 export declare const SESSION_RUN_STATE_PROJECTION_SCHEMA: 'session-run-state.v1';
@@ -114,6 +114,7 @@ export type SessionRunEvent = {
 } | {
     type: SessionRunEventType.TOOL_STARTED;
     toolName?: string;
+    toolCallId?: string;
     reason?: string;
 } | {
     type: SessionRunEventType.TOOL_ENDED;
@@ -143,6 +144,7 @@ export type SessionRunEvent = {
 } | {
     type: SessionRunEventType.RETRYING;
     reason?: string;
+    retryReason?: AgentRetryReason;
 } | {
     type: SessionRunEventType.COMPACT_STARTED;
     reason?: string;
@@ -188,6 +190,18 @@ export interface SessionRunStateMachine {
      */
     getChange$(session: Session, skipFirst?: boolean): Observable<void>;
 }
+export declare const ModelRequestRetryPhase: unique symbol;
+/**
+ * 模型请求层（宿主 provider）在同一次请求内部退避重发时，借此把会话投影为 retrying。
+ * 状态写入与守卫收口在 core，宿主只包住退避等待，不直接驱动状态机。
+ */
+export interface ModelRequestRetryPhase {
+    /**
+     * `wait` 期间会话显示 retrying 并携带 `reason`；结束（含抛错 / 取消）后恢复 model_requesting。
+     * 非本轮主请求（无 session、辅助型 purpose、状态不在 model_requesting）时只执行 `wait`。
+     */
+    during<T>(session: Session | undefined, reason: AgentRetryReason, wait: () => Promise<T>): Promise<T>;
+}
 /**
  * Pure derivations from a `SessionRunStatus`. The state machine implementation
  * MUST keep its instance methods (`getLifecycle`, `isBusy`, etc.) consistent

package/cli/dist-server/types/vendor/cbc-core/node/session/session-runtime-lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { Session } from './session-protocol';
+export declare function isSessionRuntimeClosed(session: Session): boolean;
+export declare function closeSessionRuntime(session: Session): void;
+export declare function sessionRuntimeSignal(session: Session): AbortSignal;
+export declare function assertSessionRuntimeOpen(session: Session | undefined): void;