@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/dist-server/types/node/agent/main-agent-resolver.d.ts

@@ -0,0 +1,156 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { SettingsManager } from '../settings/settings-protocol';
+import { type MainAgentHostKind, type MainAgentPolicy } from './main-agent-policy';
+import { Agent } from '../../vendor/cbc-shared/node/index.js';
+export { MAIN_AGENT_HOST_KIND_KEY, MAIN_AGENT_META_KEY } from './main-agent-session';
+/** settings 中主 agent 命名空间的顶层键 */
+export declare const CODEBUDDY_SETTINGS_KEY = "codebuddy";
+/** settings 总闸（不含宿主）。测试与旧调用方仍走这一层。 */
+export declare function isMainAgentSettingsEnabled(codebuddy: unknown): boolean;
+/**
+ * 进程级 gate 缓存（run 层，设计 v0.6 §3.3）。
+ *
+ * `codebuddy.mainAgent.enabled` 的同步布尔快照：resolveAgentForSession 是
+ * 全局热点（每个 run 都走），不能每轮做 async settings IO。参照
+ * HostCapabilityProvider 的 @Component 单例范式：initialize/配置变更时
+ * refresh 一次，热点路径零 await 短路。
+ */
+export declare class MainAgentGateProvider {
+    private policy;
+    /** TUI / headless 保持 native；ACP initialize 按 connectionId 记录 opted-in/unopted。 */
+    private readonly hostKinds;
+    /** WorkBuddy 断开后仍按 unopted 认遗留 connectionId，避免 fail-open 成 native。 */
+    private readonly rememberedUnopted;
+    /** 长寿命 --serve 上 sidecar 反复换 id 时封顶，按插入序淘汰最旧的。 */
+    private static readonly REMEMBERED_UNOPTED_LIMIT;
+    /** 非 ACP 会话（无 acpConnectionId）的宿主：native。 */
+    private defaultHostKind;
+    protected readonly settingsManager?: SettingsManager;
+    init(): void;
+    refresh(): Promise<boolean>;
+    setHostKind(kind: MainAgentHostKind, connectionId?: string): void;
+    /** ACP initialize：客户端是否声明了 mainAgentSupport。按连接隔离，避免多连接互相覆盖。 */
+    setClientOptedIn(optedIn: boolean, connectionId?: string): void;
+    removeConnection(connectionId: string): void;
+    /**
+     * Stamp the host kind for the connection that currently owns the request.
+     *
+     * Host identity is transport/session ownership, not an immutable property
+     * of the serialized conversation. An opted-in Web connection may reclaim a
+     * session previously opened by an unopted host; an unopted connection still
+     * always downgrades an opted-in session before deriving its modes/tools.
+     */
+    stampHostKind(session: Session | undefined, connectionId?: string): void;
+    getPolicy(): MainAgentPolicy;
+    isSettingsEnabled(): boolean;
+    isEnabled(connectionId?: string): boolean;
+    /** 是否已有未 opt-in 的 ACP 连接（WorkBuddy）。 */
+    hasUnoptedConnection(): boolean;
+    /** 按会话归属的 ACP 连接判定 gate；非 ACP 会话回退 native。 */
+    isEnabledForSession(session?: Session): boolean;
+    getHostKind(connectionId?: string): MainAgentHostKind;
+}
+/**
+ * 防御性获取 gate provider（测试 stub / 组件未注册场景返回 undefined）。
+ *
+ * 调用方统一用 `getMainAgentGateProvider()?.isEnabled() ?? false`，
+ * 避免 ContainerUtil.get 返回非真实例（如测试 mock）时炸 isEnabled。
+ */
+export declare function getMainAgentGateProvider(): MainAgentGateProvider | undefined;
+/**
+ * Persist a host-kind stamp without making ACP session setup depend on a fully
+ * wired SessionManager. Production hosts still persist normally; reduced ACP
+ * hosts and unit-test adapters may omit `save`, and persistence failures must
+ * never escape as unhandled rejections after a successful handshake.
+ */
+export declare function persistMainAgentHostKind(session: Session, sessionManager: {
+    save?: (value: Session) => Promise<unknown> | unknown;
+} | undefined, onError?: (error: unknown) => void): void;
+/**
+ * 解析 session 的主 agent 选择（纯函数，设计 v0.6 §3.2）。
+ *
+ * mainKey 是会话持久默认：仅当 gate 打开且 session.meta 存在该键时返回；
+ * 存在性校验（agentManager.get）由调用方负责，未命中即跳过（fallback
+ * 精确化：跳过 mainKey 分支，继续既有链，最终回落 default）。
+ *
+ * @param session 目标会话（可能为空）
+ * @param options.gateEnabled run 层 gate 同步布尔（MainAgentGateProvider.isEnabled()）
+ * @returns 主 agent 名（未启用/未设置时 undefined）
+ */
+export declare function resolveMainAgentName(session: Session | undefined, options: {
+    gateEnabled: boolean;
+}): string | undefined;
+/** 解析链所需的 agentManager 能力面（便于单测注入） */
+export interface MainAgentResolutionDeps {
+    getDefaultAgentName(): string;
+    get(agentName: string): Promise<Agent | undefined>;
+    getDefault(): Promise<Agent>;
+    /**
+     * 可选：settings 配置的默认主 agent（codebuddy.mainAgent.default，设置页"设默认"）。
+     * 仅在 gate 打开时生效；未配置/未命中回退产品默认 agent。
+     */
+    getConfiguredDefaultName?(): Promise<string | undefined>;
+    /**
+     * 可选：上次 chip 选择（codebuddy.mainAgent.lastUsed）。
+     * 仅空白会话、且未配置 `default` 时生效。不是「设为默认」。
+     */
+    getLastUsedName?(): Promise<string | undefined>;
+}
+/** 解析链日志回调（调用方注入 logger，保持纯函数可单测） */
+export type MainAgentResolutionLog = (level: 'warn', message: string) => void;
+export interface PickMainAgentNameInput {
+    session?: Session;
+    gateEnabled: boolean;
+    defaultAgentName: string;
+    /**
+     * true：run / chip（含 @agent leftover）。
+     * false：fork inherit，只跟站立键 / 空白默认，不吃 telemetry。
+     */
+    includeMention: boolean;
+    /** true：本轮 run 用协调器工具面。Code Mode 站立除外。chip / inherit 不要开。 */
+    useCoordinatorRuntime?: boolean;
+    /** 名字是否可解析。run 用 get()；chip 用 configNames，避免等 MCP rebuild。 */
+    nameExists: (name: string) => boolean | Promise<boolean>;
+    getConfiguredDefaultName?: () => Promise<string | undefined>;
+    getLastUsedName?: () => Promise<string | undefined>;
+    log?: MainAgentResolutionLog;
+}
+/**
+ * 主 agent **选名**唯一实现。run 与 chip 必须走这里，禁止再抄一套 Step 1/2/2.5。
+ *
+ * 0 compact → default
+ * 1 mention（可选）：先 @agent / 自定义，再 overlay 协调器 run，再 leftover；shipped leftover 须等于 mainKey
+ * 2 mainKey（gate 开；Explore 等子代理名跳过）
+ * 2.5/2.55 仅空白会话：settings default → lastUsed
+ * 3 产品默认
+ */
+export declare function pickMainAgentName(input: PickMainAgentNameInput): Promise<string>;
+/**
+ * 完整的主 agent 解析链（设计 v0.6 §3.2）。
+ * 选名只走 `pickMainAgentName`；本函数只负责把名字变成 Agent 实例。
+ */
+export declare function resolveMainAgentForSession(session: Session | undefined, deps: MainAgentResolutionDeps, options: {
+    gateEnabled: boolean;
+}, log?: MainAgentResolutionLog): Promise<Agent>;
+/**
+ * 会话的「站立」主 agent（mainKey → 配置默认 → 产品默认）。
+ *
+ * 不读 `session.agentName` / `meta.agentName`：那是 @agent / telemetry 的
+ * 临时身份，fork 子代理应对齐 DSH composeFrom，继承父会话的 preset，
+ * 而不是某轮 mention 切换。
+ */
+export declare function resolveInheritedMainAgent(session: Session | undefined, deps: MainAgentResolutionDeps, options: {
+    gateEnabled: boolean;
+}, log?: MainAgentResolutionLog): Promise<Agent>;
+/** 一次 settings 读取同时提供 default / lastUsed，给解析链注入。 */
+export declare function mainAgentSettingsReaders(readCodebuddy: () => Promise<{
+    mainAgent?: {
+        default?: unknown;
+        lastUsed?: unknown;
+    };
+} | undefined>): {
+    getConfiguredDefaultName(): Promise<string | undefined>;
+    getLastUsedName(): Promise<string | undefined>;
+};
+/** 把 chip 选择写进 user settings `codebuddy.mainAgent.lastUsed`（不碰 default）。 */
+export declare function persistMainAgentLastUsed(settingsManager: SettingsManager | undefined, name: string | undefined): Promise<void>;

package/cli/dist-server/types/node/agent/main-agent-session.d.ts

@@ -0,0 +1,212 @@
+import { AgentNames, Session } from '../../vendor/cbc-core/node/index.js';
+export { MAIN_AGENT_META_KEY, standingMainAgentName } from './standing-main-agent';
+/** First-seen ACP host kind. Survives connectionId rebind on load/reconnect. */
+export declare const MAIN_AGENT_HOST_KIND_KEY = "codebuddy.ai/hostKind";
+/**
+ * 读名只留三套对外入口：
+ * - `standingMainAgentName`：持久身份（只读 meta 键）
+ * - `constraintMainAgentName`：本轮工具 / Plan / REPL 约束名（子代理、leftover、gate）
+ * - `codeModeSpecOf`：PTC / 极简工具契约，由 constraint 派生
+ * 选 Agent 实例走 `pickMainAgentName`（resolver）。不要再加第四套 leftover 读法。
+ */
+interface SessionAgentRef {
+    meta?: Record<string, unknown>;
+    agentName?: string;
+}
+type StandingConstraintGate = (session?: SessionAgentRef) => boolean;
+/**
+ * Production binds this from MainAgentGateProvider so leftover standing keys
+ * stop mutating tools/REPL/Plan when the kill switch or unopted host is off.
+ * Unbound (unit tests / no container) keeps name matching so specs stay local.
+ */
+export declare function bindStandingConstraintGate(gate?: StandingConstraintGate): void;
+export declare function isStandingConstraintActive(session?: SessionAgentRef): boolean;
+/**
+ * 空白会话判定（设计 v0.6 §3.5，持久可判据）。
+ *
+ * 会话历史中不存在"主 agent 产出"的 assistant 消息即空白：
+ * - type==='message' 且 role==='assistant'
+ * - providerData.agent !== COMPACT（排除 compact 摘要项）
+ * - 且 !isSubAgent / !isCompactInternal / !isSummary（input-item-processors 的持久 stamp 字段）
+ *
+ * 边界（文档化）：refusal/内容过滤/无效 tool call 失败轮会产生非 compact 的
+ * assistant 终止消息 → 判定为非空白（保守锁定，符合"会话已开始"语义）。
+ * 不依赖 runState（不持久化，重启恒 IDLE）。
+ */
+export declare function isSessionBlank(session: Session | undefined): boolean;
+/**
+ * `session.agentName` / `meta.agentName` 上的 ptc/minimal/create 是 telemetry
+ * 或进程 `--agent` leftover，不是站立切换。
+ *
+ * 只在它与已落盘的 mainKey 一致时才认（stamp / set_agent / 空白会话 persist）。
+ * 总闸关闭（WorkBuddy）一律忽略 shipped leftover；Explore / 自定义 @agent 不是
+ * shipped，调用方继续走 Step 1。
+ *
+ * 与 `constraintMainAgentName` 对齐：无站立键时不认 leftover agentName。
+ */
+export declare function isIgnorableShippedAgentLeftover(session: SessionAgentRef | undefined, agentName: string | undefined, gateEnabled: boolean): boolean;
+/**
+ * 本轮 run 的 agent 名。OpenAI `RunContext` 没有 agent 字段，isEnabled / 调用方
+ * 可以挂在 context.agent 上；没有就让 codeModeSpecOf 只认站立键。
+ * 参数用 unknown：与 `RunContext<Session>` 没有交集，写成 `{ agent? }` 会 TS2559。
+ */
+export declare function runAgentNameFromRunContext(context?: unknown): string | undefined;
+/**
+ * Code Mode（PTC / Minimal）的完整工具面契约。
+ *
+ * **这是「某个会话是不是 Code Mode、能调什么」的唯一事实源。** 四个消费点
+ * （LLM 工具列表门控、REPL 总闸、沙箱目录采集、沙箱执行放行）必须全部经由
+ * 本函数，不得各自重写等价判据 —— 历史教训：`agent-manager` 按「直连白名单」
+ * 判定、`repl-tool` 只认 PTC，两处与 `tools: ['REPL']` 不同步，直接导致
+ * Minimal 模式下 REPL 被自己的门过滤掉、模型一个工具都拿不到。
+ */
+export interface CodeModeSpec {
+    /** 站立模式名，用于日志与错误文案。 */
+    readonly mode: AgentNames.PTC | AgentNames.MINIMAL;
+    /** 模型面可直连的工具（两个模式都只有 REPL）。 */
+    readonly directTools: readonly string[];
+    /**
+     * REPL 沙箱内可见 **且**可调用的工具白名单。
+     * `undefined` = 不做模式级收窄（PTC 全量开放），仍受 session `--tools`、
+     * `--disallowed-tools`、deny 规则与 repl_expose 约束。
+     */
+    readonly sandboxTools?: readonly string[];
+    /**
+     * 沙箱内是否允许 MCP 工具。与 `sandboxTools` 白名单正交：白名单只约束内置
+     * 工具；`mcp__` 前缀走本开关（见 `isCodeModeSandboxTool` / `isCodeModeMcpOpen`）。
+     * PTC 为 true（并豁免 `repl_expose`）；极简为 false。
+     */
+    readonly allowMcpInSandbox: boolean;
+    /**
+     * 沙箱工具描述覆盖：产品模板的措辞可能与本模式的工具面矛盾
+     * （Bash/Edit 模板教模型「先 Read」，而极简没有 Read）。
+     */
+    readonly toolDescriptionOverrides?: Readonly<Record<string, string>>;
+}
+/**
+ * 解析当前会话的 Code Mode 契约；非 Code Mode（cli / create / 自定义 agent）
+ * 返回 `undefined`，调用方走原生工具面。
+ *
+ * 唯一派生自 `constraintMainAgentName`（站立键优先、leftover 忽略、gate 关闭失效），
+ * 所以 WorkBuddy 未 opt-in 的会话恒返回 undefined。
+ */
+export declare function codeModeSpecOf(session?: SessionAgentRef, runAgentName?: string, gateActive?: boolean): CodeModeSpec | undefined;
+/** 该工具是否允许出现在模型面（Code Mode 只放行 REPL）。 */
+export declare function isCodeModeDirectTool(spec: CodeModeSpec | undefined, toolName: string): boolean;
+/** Code Mode 沙箱是否对 MCP 开放（站立 PTC 是，极简 / PTC overlay 否）。 */
+export declare function isCodeModeMcpOpen(spec: CodeModeSpec | undefined): boolean;
+/** 收窄沙箱（Minimal / PTC overlay）：注入层不得再教白名单外的工具。原生 / 站立 PTC 为 false。 */
+export declare function isNarrowCodeMode(spec: CodeModeSpec | undefined): boolean;
+/**
+ * 抑制 MCP 能力提示（MCP UI 等）。仅收窄且关 MCP 时为 true。
+ * 原生 cli（spec 空）和 PTC 都要放行 MCP UI。
+ */
+export declare function codeModeHidesMcpHints(spec: CodeModeSpec | undefined): boolean;
+/**
+ * 该工具是否允许在 REPL 沙箱内被调用。
+ * `sandboxTools` 缺省表示不收窄内置面；`mcp__` 前缀只看 `allowMcpInSandbox`。
+ */
+export declare function isCodeModeSandboxTool(spec: CodeModeSpec | undefined, toolName: string): boolean;
+/** 沙箱目录里该工具的描述：模式覆盖优先，否则用工具自带描述。 */
+export declare function codeModeToolDescription(spec: CodeModeSpec | undefined, toolName: string, fallback: string | undefined): string;
+/** SDK / ACP 脱敏后的「工具不存在」文案里解析工具名。 */
+export declare function parseUnknownDirectToolName(message: string): string | undefined;
+/**
+ * 沙箱里 MCP 工具的准确调用名：`mcp_<serverName>.<rawToolName>`。
+ *
+ * 两个入参只能取自 `DeferredToolInfo`（延迟索引里由 mcp-manager 写入），**不能**
+ * 从 canonical 名 `mcp__server__tool` 切分猜——transparent_proxy 场景下
+ * canonical 段与实际 serverName 不同（如 connector-proxy 代管的服务）。
+ * 拿不到完整 info 时返回 undefined，由调用方决定退回近似名还是不给示例。
+ */
+export declare function mcpSandboxCallName(serverName?: string, rawToolName?: string): string | undefined;
+/**
+ * 模型在 Code Mode 把沙箱工具当对话层直连调用时的纠正文案。
+ *
+ * 不能说「工具不存在」：PTC 下 Bash/Glob/SendMessage 都在 REPL 里。
+ * 也不能指路 DeferExecuteTool：那也不是直连工具，会再失败一轮。
+ *
+ * `sandboxCallName` 是 REPL 里可直接调用的准确名（见 {@link mcpSandboxCallName}）；
+ * 调用方能从 `DeferredToolInfo` 拿到 serverName/rawToolName 时必须传，缺省才退回近似名。
+ */
+export declare function codeModeDirectCallGuidance(spec: CodeModeSpec, toolName: string, sandboxCallName?: string): string;
+/**
+ * Code Mode 会话上的 unknown-tool SDK 错误 → REPL 引导；非 Code Mode 返回 undefined。
+ */
+export declare function rewriteUnknownToolForCodeMode(session: SessionAgentRef | undefined, message: string, runAgentName?: string): string | undefined;
+/**
+ * 本轮工具 / Plan / REPL 约束名。会话身份只认这一处。
+ *
+ * - dedicated 子代理（Explore 等）用自己的 run 名，不吃父站立键
+ * - gate 关：丢掉 shipped leftover / 磁盘站立键（WorkBuddy 走原生 cli）
+ * - gate 开：站立键优先；无站立键只认本轮显式 run，不认 telemetry leftover
+ */
+export declare function constraintMainAgentName(session?: SessionAgentRef, runAgentName?: string, gateActive?: boolean): string | undefined;
+/**
+ * REPL 沙箱目录 / overlay / MCP 白名单用的 agent 名。
+ *
+ * Code Mode（PTC / Minimal）返回 `undefined`：沙箱必须按完整 cli 工具集
+ * 计算 allowed tools。按 ptc/minimal 自己的直连白名单（只有 REPL）去
+ * `getAllowedToolsForAgent` 会把 Bash/Edit/Skill 全部滤掉。创造同样回
+ * `undefined`（下面 `CREATE` 分支）。极简的收窄由 `sandboxTools` 负责。
+ */
+export declare function sandboxCatalogAgentName(session?: SessionAgentRef, runAgentName?: string, gateActive?: boolean): string | undefined;
+/**
+ * 极简模式门控：约束名是 `minimal`。WorkBuddy 默认 `cli`，不会进这条。
+ */
+export declare function isMinimalStandingAgent(session?: SessionAgentRef, runAgentName?: string, gateActive?: boolean): boolean;
+/**
+ * 创造模式门控：约束名是 `create`。WorkBuddy 默认 `cli`，不会进这条。
+ */
+export declare function isCreateStandingAgent(session?: SessionAgentRef, runAgentName?: string, gateActive?: boolean): boolean;
+/**
+ * PTC / Code Mode 门控：约束名是 `ptc`。WorkBuddy 默认 `cli`，不会进这条；
+ * REPL 不得改成进程级默认开。
+ */
+export declare function isPtcStandingAgent(session?: SessionAgentRef, runAgentName?: string, gateActive?: boolean): boolean;
+/**
+ * set_agent 在 ACP 请求里常常盖不到 run 用的那份内存 session：
+ * getCurrent() 在 ALS 外会抛，sessionSubject 可能是 TUI 另一份，于是 handler
+ * 只改了磁盘反序列化副本。run 仍拿未盖章的 live 实例 → 偶发第一轮走 cli。
+ * 把站立键抄到同 id 的 live 引用上。
+ */
+export declare function mirrorMainAgentOntoLiveSessions(stamped: Session, live: ReadonlyArray<Session | undefined>): void;
+/**
+ * 把站立键写进 session.meta。set_agent / --agent / 首次 persist 共用，避免三处各写一份。
+ */
+export declare function writeStandingMainAgentKey(session: Session, name: string, options?: {
+    setAgentName?: 'always' | 'if-missing';
+}): void;
+/**
+ * 空白新会话首次命中配置默认后，把站立键落盘。
+ * 否则第一轮用 ptc、第二轮（已非空白、无 mainKey）会掉回产品默认。
+ * 仅在已有 mainKey 缺失且解析结果不是产品默认时写入；不覆盖 @agent 镜像。
+ */
+export declare function maybePersistStandingMainAgent(session: Session | undefined, agentName: string, productDefault: string, save: (session: Session) => Promise<void>): Promise<boolean>;
+/**
+ * Native CLI / 新建智能体 first POST 上的 `--agent`。
+ *
+ * RequestBuilder 把 commander opts 摊进 `/internal/agent` body。ACP 请求带
+ * `acp:true`，站立键改在 opt-in 之后盖（WorkBuddy 未声明能力位则不盖）。
+ */
+export declare function nativeCliStandingAgentName(body: {
+    acp?: boolean;
+    agent?: unknown;
+}): string | undefined;
+/**
+ * CLI `--agent ptc|minimal|create` 只在**新建空白会话**上盖站立键。
+ * 会话一旦有站立键或已有历史，进程 `--agent` 不得覆盖。
+ * 自定义 @agent 不盖。
+ *
+ * 与 ACP `session/set_agent` 同一持久键。不走 applySettingsAgent 叠到 cli：
+ * 叠上去会改工具面、不改身份，Code Mode / 目录 chip 仍显示标准。
+ *
+ * `--agent cli` 也要盖站立键：cli 不是 shipped standing，不盖的话空白会话会
+ * 继续吃 lastUsed（ptc），再被 maybePersistStandingMainAgent 写进 settings。
+ */
+export declare function stampShippedStandingFromCliAgent(session: Session | undefined, input: {
+    cliAgentName: string | undefined;
+    productDefault: string;
+    gateEnabled: boolean;
+    save: (session: Session) => Promise<void>;
+}): Promise<boolean>;

package/cli/dist-server/types/node/agent/memory-context-interceptor.d.ts

@@ -0,0 +1,84 @@
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest, SessionRunStateMachine } from '../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { MemoryRelevanceService } from '../memory';
+import { SettingsManager } from '../settings';
+export declare class MemoryContextInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly logger: Logger;
+    protected readonly memoryRelevanceService?: MemoryRelevanceService;
+    protected readonly stateMachine: SessionRunStateMachine;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * 检查 Auto Memory 功能是否启用
+     */
+    private isAutoMemoryEnabled;
+    /**
+     * 检查团队记忆是否启用
+     */
+    private isTeamMemoryEnabled;
+    /**
+     * 获取团队用户 ID
+     */
+    private getTeamUserId;
+    /**
+     * 检查 Typed Memory 是否启用（默认启用，与 Claude Code 对齐）
+     */
+    private isTypedMemoryEnabled;
+    /**
+     * 判断是否应注入 Memory 上下文
+     *
+     * 不再仅依赖 session.options.continue 标记（/resume 等场景下可能未设置），
+     * 而是增加 fallback：检查第一条 user message 是否已包含 memory system-reminder。
+     * 确保 resume 后第一条 user message 的 content 结构与原始会话一致（prompt cache 一致性）。
+     */
+    private shouldInjectMemoryContext;
+    /**
+     * 解析这次 run 的记忆落点。
+     *
+     * 同事（Agent Home colleague job）走私有分区 + 共享只读层（见
+     * agent-home-colleague-memory：上游 shard per assistant 的单写者纪律）。
+     * 不是同事时逐字节等同原实现——主 Agent / TUI / WorkBuddy 行为不变。
+     */
+    private resolveMemoryScope;
+    /**
+     * 生成 Auto Memory 上下文提示
+     */
+    private generateMemoryPrompt;
+    /**
+     * Typed Memory Prompt — 使用 buildMemoryPrompt() 与 Claude Code 对齐
+     *
+     * 包含：4 类型定义、What NOT to save（含显式保存门控）、
+     * When to access（含漂移警告）、Before recommending from memory
+     */
+    private generateTypedMemoryPrompt;
+    /**
+     * Legacy Memory Prompt — 通用记忆格式（Typed Memory 关闭时使用）
+     *
+     * 保留独立实现，确保 typedMemory=false 时行为和改动前完全一致：
+     * - 无 4 类型系统
+     * - 无 YAML frontmatter 要求
+     * - 简化的 "What to save" / "What NOT to save" 指导
+     */
+    private generateLegacyMemoryPrompt;
+    /**
+     * 注入相关记忆到当前请求
+     *
+     * ESC 取消支持：Memory Relevance Selection 会调用 memorySelector agent
+     * （AgentService.runOneTime），需要让用户在该阶段也能用 ESC 中断。
+     * 对齐 InsightsDataAgentRunInterceptor 的做法：
+     * 1. 通过 SessionRunStateMachine 推进到 AGENT_RUNNING，让 LoadingBox
+     *    的 ESC 逻辑立即生效（pending 态下 ESC 只会延后 abort）
+     * 2. 将主 run 的 abortSignal 透传给 selectRelevantMemories
+     * 3. abort 时通过 stateMachine.forceIdle 统一回到 IDLE
+     */
+    private injectRelevantMemories;
+    /**
+     * 获取相关记忆内容（异步文件读取）
+     */
+    private getRelevantMemoriesContent;
+    /**
+     * 从输入中提取最后一条用户消息的原始文本（去除 system-reminder 注入内容）
+     */
+    private extractLastUserQuery;
+}

package/cli/dist-server/types/node/agent/standing-main-agent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 站立模式的纯数据读取层，不导入 agent/multitask 的运行时模块。
+ * 子任务、workflow 等启动路径在组合根初始化期间也可以安全读取。
+ *
+ * session.meta 中主 agent 选择的持久键（设计 v0.6 §3.1 唯一权威源）。
+ * `meta.agentName` 是子代理身份，`session.agentName` 是临时运行名；站立模式只读本键。
+ */
+export declare const MAIN_AGENT_META_KEY = "codebuddy.ai/mainAgent";
+/** 会话持久的站立主 agent（只读 meta 键，不读 telemetry `session.agentName`）。 */
+export declare function standingMainAgentName(session?: {
+    meta?: Record<string, unknown>;
+}): string | undefined;

package/cli/dist-server/types/node/agent/stream-json-init-interceptor.d.ts

@@ -0,0 +1,9 @@
+import { AgentRunInterceptor, AgentRunRequest } from '../../vendor/cbc-core/node/index.js';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { CommandManager } from '../command';
+export declare class StreamJsonInitInterceptor implements AgentRunInterceptor {
+    priority: number;
+    protected readonly productManager: ProductManager;
+    protected readonly commandManager: CommandManager;
+    intercept(request: AgentRunRequest): Promise<void>;
+}

package/cli/dist-server/types/node/agent/subagent-limits.d.ts

@@ -0,0 +1,90 @@
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+/**
+ * Subagent spawn limits — 对齐 Claude Code 的 subagent 约束（机制差异见下文）。
+ *
+ * 与 Claude Code 的关系（已对 CC 源码核对）：CC 的基线做法是「子代理拿不到 Agent
+ * 工具」——非 ant 用户的子代理工具集里直接移除 Agent，因此根本无法再 spawn（等效 0
+ * 层嵌套），并没有一个可配置的 depth 计数器。genie 在此之上保留三道闸（防御纵深）：
+ * - **Nesting depth**: 子代理到第 5 层不能再 spawn（固定，不可配置）。
+ * - **Concurrent executions**: 参考 Codex 的共享 execution limiter， 同一根会话树最多同时运行 N 个子代理，默认 20，可用
+ *   CODEBUDDY_CODE_MAX_CONCURRENT_SUBAGENTS 调整（正整数，不能关）。采用 reservation +
+ *   幂等 release，避免并发 check-then-increment 穿透上限；终态或移除时归还槽位。
+ * - **Per-session budget**: 每次 CLI 进程运行内最多 N 次 spawn，默认 200，可用
+ *   CODEBUDDY_CODE_MAX_SUBAGENTS_PER_SESSION 上调（正整数，不能关）。计数存活于内存
+ *   （`session.meta.subagentSpawnBudget`）。注意：该计数**不跨进程持久化**——meta.json
+ *   仅在会话创建时落盘（彼时 count=0），consumeSpawn 的增量不回写，故跨进程
+ *   resume 会从 0 重新计数，`/clear` 新建 session 也重置。因此这道闸拦的是
+ *   「单次运行内失控刷 subagent」，而非会话整个生命周期的累计上限。
+ *
+ * 整棵会话树的计数以共享 spawn budget 对象为锚点：
+ * - 并发执行状态仅存于运行时，并以该共享对象为键；
+ * - `subagentDepth`: number of subagent levels below the main conversation
+ *   (main session = 0). Stamped onto each sub-session at spawn.
+ * - `subagentSpawnBudget`: a `{ count }` object owned by the root session and
+ *   SHARED by reference with every descendant sub-session, so nested spawns
+ *   consume the same budget no matter which level initiates them.
+ *
+ * Scope note: propagation covers in-process subagents (AgentTask sync +
+ * in-process background/team members). Subprocess teammates (tmux/detached
+ * backends) run in their own OS process with a fresh session and are not
+ * chained into the parent budget.
+ */
+/** Fixed maximum nesting depth (levels below the main conversation). */
+export declare const MAX_SUBAGENT_DEPTH = 5;
+/** 单个根会话树中默认允许同时执行的子代理数量。 */
+export declare const DEFAULT_MAX_CONCURRENT_SUBAGENTS = 20;
+/** 子代理并发执行上限的环境变量覆盖值（正整数，无固定最大值）。 */
+export declare const ENV_MAX_CONCURRENT_SUBAGENTS = "CODEBUDDY_CODE_MAX_CONCURRENT_SUBAGENTS";
+/** Default per-session subagent spawn budget. */
+export declare const DEFAULT_MAX_SUBAGENTS_PER_SESSION = 200;
+/** Env override for the per-session budget (positive integer, no upper bound). */
+export declare const ENV_MAX_SUBAGENTS_PER_SESSION = "CODEBUDDY_CODE_MAX_SUBAGENTS_PER_SESSION";
+export interface SubagentSpawnBudget {
+    count: number;
+}
+export interface SubagentExecutionSlot {
+    release(): void;
+}
+/** Depth of the given session below the main conversation (main = 0). */
+export declare function getSubagentDepth(session: Pick<Session, 'meta'>): number;
+/** Depth to stamp on a sub-session spawned FROM the given session. */
+export declare function nextSubagentDepth(spawningSession: Pick<Session, 'meta'>): number;
+/** 生效的并发执行上限：有效的正整数环境变量值，否则使用默认值。 */
+export declare function getMaxConcurrentSubagents(): number;
+/** Effective per-session budget: env override (positive int) or the default. */
+export declare function getMaxSubagentsPerSession(): number;
+/**
+ * The session's spawn budget object. Created lazily on the root session;
+ * sub-sessions receive the same object by reference at spawn time, so this
+ * returns the shared root budget for any session in the tree.
+ */
+export declare function getOrCreateSpawnBudget(session: Pick<Session, 'meta'>): SubagentSpawnBudget;
+export type SpawnCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    kind: 'depth' | 'concurrency' | 'budget';
+    reason: string;
+};
+export declare function getActiveSubagentExecutions(session: Pick<Session, 'meta'>): number;
+/** 原子预留一个执行槽；返回的释放操作具备幂等性。 */
+export declare function acquireSubagentExecutionSlot(session: Pick<Session, 'meta'>): SubagentExecutionSlot;
+/**
+ * Gate a spawn attempt from `spawningSession`: enforce the depth cap, current
+ * execution capacity, and shared per-session budget WITHOUT consuming either counter. Call once per Agent-tool
+ * dispatch, before any spawn path runs, so over-limit spawns are rejected
+ * early; pair with `consumeSpawn` after a spawn has actually succeeded, so
+ * failed attempts (invalid type, no active team, internal spawn failure) and
+ * resume calls never burn budget.
+ */
+export declare function checkSpawnAllowed(spawningSession: Pick<Session, 'meta'>): SpawnCheckResult;
+/**
+ * Consume one unit of the shared session budget. Call only after a spawn has
+ * actually been created — never on resume calls or on failed spawn attempts.
+ */
+export declare function consumeSpawn(spawningSession: Pick<Session, 'meta'>): void;
+/**
+ * Refund one unit after a spawn that never produced a result (sync / quick fail).
+ * Never decrements below 0.
+ */
+export declare function refundSpawn(spawningSession: Pick<Session, 'meta'>): void;

package/cli/dist-server/types/node/agent/team-context-interceptor.d.ts

@@ -0,0 +1,42 @@
+import { PromptManager } from '../../workspace/prompts/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../vendor/cbc-core/node/index.js';
+/**
+ * TeamContextInterceptor injects the team communication prompt into sessions.
+ *
+ * Two modes:
+ * 1. Teammate sessions (session.meta.teamContext) — injects `team-sys-prompt` template
+ * 2. Main agent sessions in a team (formal or auto) — injects a team-lead prompt
+ *    listing current teammates and how to communicate with them via SendMessage
+ *
+ * Priority 1175: runs after SystemReminderContext (1200) and before MemoryContext (1150),
+ * so the team prompt is injected alongside other system reminders.
+ */
+export declare class TeamContextInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly promptManager: PromptManager;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * Inject team-sys-prompt template for teammate sessions.
+     */
+    private injectTeammatePrompt;
+    /**
+     * Inject a prompt for the main agent (team-lead) when in a team (formal or auto).
+     * Uses the `team-lead-prompt` template which includes teammate listing,
+     * communication rules, worker prompt writing guides, and task workflow.
+     */
+    private injectTeamLeadPrompt;
+    /**
+     * Decide whether to (re-)inject the team system reminder this turn.
+     *
+     * Returns true when any of the following holds:
+     *   - First user message in the session
+     *   - Resumed session (history not yet replayed)
+     *   - The marker text is missing from history (e.g. context was compacted)
+     *   - The current roster differs from the last roster we injected
+     *     (so newly-spawned teammates show up without waiting for compaction)
+     */
+    private shouldInjectTeamPrompt;
+    private recordInjectedRoster;
+}