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

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

@@ -0,0 +1,72 @@
+/**
+ * Agent persistent memory — Claude Code parity.
+ *
+ * An agent definition may declare `memory: user | project | local`. When auto
+ * memory is enabled, the subagent gets:
+ * - a scope-specific memory directory (created on first use),
+ * - a "Persistent Agent Memory" section appended to its system prompt with the
+ *   current MEMORY.md content (truncated to 200 lines / 25KB).
+ *
+ * 对齐 Claude Code：memory 启用时除注入提示段落外，若 agent 显式声明了 tools
+ * 白名单，还会自动补 Read/Write/Edit（CC loadAgentsDir.ts:662-674），保证 agent
+ * 能读写 MEMORY.md；tools 缺省（继承默认工具集）时不改动。注入逻辑见
+ * agent-manager.ts registerAgent。
+ *
+ * Directory layout (mirrors Claude Code's ~/.claude → ~/.codebuddy mapping):
+ * - user:    <configDir>/agent-memory/<agentType>/            (shared across projects)
+ * - project: <cwd>/.codebuddy/agent-memory/<agentType>/       (checked into the repo)
+ * - local:   <cwd>/.codebuddy/agent-memory-local/<agentType>/ (per-project, not for VCS)
+ *
+ * Out of scope (deliberate): Claude Code's feature-flagged project→user snapshot
+ * initialization; genie has no remote-memory host equivalent either.
+ */
+export type AgentMemoryScope = 'user' | 'project' | 'local';
+export declare const AGENT_MEMORY_SCOPES: readonly AgentMemoryScope[];
+/** Entry file read into the prompt; topic files live beside it. */
+export declare const MEMORY_ENTRYPOINT_NAME = "MEMORY.md";
+/** MEMORY.md truncation caps (Claude Code values). */
+export declare const MAX_MEMORY_ENTRYPOINT_LINES = 200;
+export declare const MAX_MEMORY_ENTRYPOINT_BYTES = 25000;
+/** Kill-switch: truthy disables agent memory entirely. Default: enabled. */
+export declare const ENV_DISABLE_AUTO_MEMORY = "CODEBUDDY_CODE_DISABLE_AUTO_MEMORY";
+export declare function isAutoMemoryEnabled(): boolean;
+export declare function normalizeAgentMemoryScope(value: unknown): AgentMemoryScope | undefined;
+/**
+ * Flatten an agent type into a single path segment.
+ * - `:` (plugin scoped name separator) → `-`
+ * - `/` and `\` → `-` so a malicious/typo'd frontmatter `name` cannot escape
+ *   the memory root via `../` or absolute-looking segments
+ * - empty / `.` / `..` after sanitization → `_` (never a traversable segment)
+ */
+export declare function sanitizeAgentTypeForPath(agentType: string): string;
+export declare function getAgentMemoryDir(agentType: string, scope: AgentMemoryScope): string;
+export interface TruncatedMemory {
+    text: string;
+    /** Which cap fired, if any. */
+    truncatedBy?: 'lines' | 'bytes';
+}
+/**
+ * Truncate MEMORY.md content: first 200 lines, then a 25KB byte cap cut at the
+ * last newline before the limit (hard cut when the text has no newline). A
+ * warning naming the cap is appended so the agent knows the index is partial.
+ */
+export declare function truncateMemoryEntrypoint(content: string): TruncatedMemory;
+/**
+ * Build the "Persistent Agent Memory" system-prompt section for an agent.
+ * Ensures the memory directory exists, then embeds the (truncated) MEMORY.md.
+ * Evaluated lazily at agent-instructions time, so each spawn sees fresh memory.
+ */
+export declare function buildAgentMemoryPrompt(agentType: string, scope: AgentMemoryScope): Promise<string>;
+export declare const MEMORY_SNAPSHOT_DIR_NAME = "agent-memory-snapshots";
+export declare const SNAPSHOT_METADATA_NAME = "snapshot.json";
+export declare const SNAPSHOT_SYNC_MARKER_NAME = ".snapshot-synced.json";
+export declare function getAgentMemorySnapshotDir(agentType: string, workDir?: string): string;
+export type SnapshotInitResult = 'initialized' | 'pending-update' | 'none';
+/**
+ * Seed a user-scope agent's memory from the project snapshot when the memory
+ * dir has no markdown yet, mirroring Claude Code's snapshot initialization.
+ * Idempotent: the `.snapshot-synced.json` marker plus existing `*.md` files
+ * prevent re-copying; a newer snapshot yields 'pending-update' without
+ * overwriting the agent's accumulated memory.
+ */
+export declare function initializeMemoryFromSnapshotIfNeeded(agentType: string, scope: AgentMemoryScope, workDir?: string): Promise<SnapshotInitResult>;

package/cli/dist-server/types/node/agent/agent-runtime-adapter.d.ts

@@ -0,0 +1,71 @@
+import { type AgentLoopCancellation, AgentLoopInteraction, AgentLoopTelemetry, AgentManager, AgentPluginRefresh, AgentQueueOutput, type AgentRunInterceptor, AgentRunObserver, AgentRunSettings, type AgentRunSettingsValues, AgentRuntimeResolver, AgentToolRuntime, RunnerModelProvider, type Session, SessionManager, type ToolCallLoopEventKind, type ToolCallLoopEvidence } from '../../vendor/cbc-core/node/index.js';
+import { PluginRuntimeRefreshService } from '../../workspace/cbc-plugins/lib/node/index.js';
+import type { Agent } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { AcpBroadcastService } from '../acp/acp-protocol';
+import { ModelProvider } from '../model/model-protocol';
+import { SettingsManager } from '../settings';
+import { TelemetryService } from '../telemetry/telemetry-protocol';
+import { ToolArgumentRewriteService } from '../tools/tool-protocol';
+import { projectPromptFilesForModel } from '../utils/embedded-resource';
+import { MainAgentGateProvider } from './main-agent-resolver';
+export declare class CliAgentRuntimeResolver implements AgentRuntimeResolver {
+    protected readonly agentManager: AgentManager;
+    protected readonly sessionManager: SessionManager;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly mainAgentGateProvider?: MainAgentGateProvider;
+    protected readonly logger: Logger;
+    resolveAgentForSession(session?: Session): Promise<Agent>;
+}
+export declare class CliAgentPluginRefresh implements AgentPluginRefresh {
+    protected readonly refresh?: PluginRuntimeRefreshService;
+    waitForRefreshSettled(): Promise<void>;
+    waitForComposePluginsReady(): Promise<void>;
+}
+export declare class CliAgentToolRuntime implements AgentToolRuntime {
+    protected readonly argumentRewrite: ToolArgumentRewriteService;
+    rewriteArguments(argumentsText: string): unknown;
+    enterToolCall(callId: string, toolName: string, sessionId?: string): void;
+    leaveToolCall(callId: string): void;
+    isPolicyDeniedResult(output: unknown): output is {
+        terminal: {
+            reason: 'policy-denied';
+            finalOutput: string;
+        };
+    };
+}
+export declare class CliAgentQueueOutput implements AgentQueueOutput {
+    protected readonly broadcast?: AcpBroadcastService;
+    broadcastMessageQueueUpdate(sessionId: string, queueData: Record<string, unknown>): Promise<void>;
+    broadcastUserMessage(...args: Parameters<AgentQueueOutput['broadcastUserMessage']>): Promise<void>;
+}
+export declare class CliAgentRunSettings implements AgentRunSettings {
+    protected readonly settings: SettingsManager;
+    get<K extends keyof AgentRunSettingsValues>(key: K): Promise<AgentRunSettingsValues[K]>;
+}
+export declare class CliRunnerModelProvider implements RunnerModelProvider {
+    projectInput(input: Parameters<typeof projectPromptFilesForModel>[0]): ReturnType<typeof projectPromptFilesForModel>;
+    protected readonly provider: ModelProvider;
+    getModel(modelName: Parameters<RunnerModelProvider['getModel']>[0]): ReturnType<RunnerModelProvider['getModel']>;
+}
+export declare class CliAgentRunObserver implements AgentRunObserver {
+    enterJobActivity(): () => void;
+    resolveInterceptorName(interceptor: AgentRunInterceptor): string;
+    markStart(phase: string, label?: string): void;
+    markEnd(phase: string): void;
+    begin(phase: string, label: string): unknown;
+    end(span: unknown, status?: 'error'): void;
+    private profiler;
+}
+export declare class CliAgentLoopTelemetry implements AgentLoopTelemetry {
+    protected readonly telemetry: TelemetryService;
+    reportUserTaskFailedCreditRefund(session: Session, reason: 'loop_detected'): Promise<void>;
+    reportToolCallLoopEvent(kind: ToolCallLoopEventKind, session: Session, evidence: ToolCallLoopEvidence): Promise<void>;
+}
+export declare class CliAgentLoopInteraction implements AgentLoopInteraction {
+    readonly cancelReasonKey: "codebuddy.ai/cancelReason";
+    readonly cancelledReason: "tool_call_loop_stopped";
+    readonly interceptType: "tool-call-loop";
+    isEnabled(): boolean;
+    getCancellationForSession(session: Session): AgentLoopCancellation | undefined;
+}

package/cli/dist-server/types/node/agent/builtin-agent-modes.d.ts

@@ -0,0 +1,47 @@
+export { MAIN_AGENT_PRESET_TAG } from './main-agent-preset';
+/**
+ * Shipped main-agent mode ids that travel with the CLI install bundle.
+ * Display names live in the Web i18n map (`agent-labels.ts`), not here.
+ *
+ * The modes are injected at runtime by `BuiltinMainAgentModesProvider`
+ * (packages/agent-cli), not by patching tracked product.json files.
+ *
+ * WorkBuddy Desktop does not opt into the picker; do not treat presence of an
+ * id as “WorkBuddy UI should show a seat”.
+ */
+export declare const BUILTIN_AGENT_MODE_NAMES: readonly ["cli", "ptc", "minimal", "create", "multitask"];
+export type BuiltinAgentModeName = (typeof BUILTIN_AGENT_MODE_NAMES)[number];
+export declare const MAIN_MODE_AGENT_TAG = "main-mode";
+export declare function isBuiltinAgentModeName(name: string | undefined): name is BuiltinAgentModeName;
+/**
+ * Chip / getAgents / set_agent / 新会话盖章只认四套 shipped + 带
+ * `mainAgent: true`（加载后 `main-agent-preset`）的自定义 agent。
+ * 普通 `.codebuddy/agents/*.md` / Explore / Plan 不当站立主 Agent。
+ */
+export declare function isStandingMainAgentCandidate(agent: {
+    name?: string;
+    tags?: readonly string[];
+}, defaultAgentName: string): boolean;
+/**
+ * 主会话提示词管线：产品默认 + 四套 shipped + 带 `mainAgent: true` 的自定义预设。
+ * 普通自定义 .md 仍走 markdown body 当完整 instructions。
+ */
+export declare function usesMainAgentPromptPipeline(agent: {
+    name?: string;
+    tags?: readonly string[];
+}, defaultAgentName: string): boolean;
+/** settings lastUsed/default 里残留的子代理名，解析链直接跳过。 */
+export declare function isBuiltinSubagentStandingName(name: string | undefined): boolean;
+export declare function tuiModeLabel(name: string | undefined): string | undefined;
+export declare function tuiModeShortDescription(name: string | undefined): string | undefined;
+/**
+ * TUI chrome color keys (theme.colors). Distinct per shipped mode;
+ * every custom agent shares one extra gold (`delegateMode`).
+ */
+export type TuiModeColorName = 'info' | 'planMode' | 'success' | 'warning' | 'delegateMode';
+export declare function tuiModeColorName(agentName?: string, custom?: boolean): TuiModeColorName;
+export declare function builtinModeLocale(language?: string): 'zh' | 'en';
+export declare function localizeBuiltinAgentMode(name: string | undefined, language?: string): {
+    displayName: string;
+    description: string;
+} | undefined;

package/cli/dist-server/types/node/agent/custom-agent-identity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * New custom agents created by AI must be a single lowercase hyphenated id.
+ * Existing on-disk agents are NOT required to match this — WorkBuddy and
+ * older CLI users may already have mixed-case or underscored names.
+ */
+export declare const NEW_CUSTOM_AGENT_NAME_PATTERN: RegExp;
+export type CustomAgentNameFailure = 'invalid' | 'reserved';
+export interface CustomAgentNameOk {
+    readonly ok: true;
+    readonly name: string;
+}
+export interface CustomAgentNameErr {
+    readonly ok: false;
+    readonly reason: CustomAgentNameFailure;
+}
+export type CustomAgentNameInspection = CustomAgentNameOk | CustomAgentNameErr;
+/**
+ * Names that must not be minted by create-by-AI (SmartMerge would overlay
+ * the shipped agent). Load path does not use this set — existing files stay
+ * visible so WorkBuddy / legacy custom agents keep working.
+ */
+export declare function reservedCustomAgentNames(): ReadonlySet<string>;
+/**
+ * Path-safety only: one segment, no traversal, no absolute, no NUL.
+ * Allows mixed case / underscores so existing WorkBuddy agents still load.
+ */
+export declare function isSafeCustomAgentPathSegment(name: unknown): name is string;
+export declare function inspectNewCustomAgentName(name: unknown): CustomAgentNameInspection;
+export declare function describeCustomAgentNameFailure(reason: CustomAgentNameFailure): string;
+/**
+ * Resolve `<directory>/<name>.md` and refuse anything that escapes `directory`.
+ * `name` must be a safe path segment (not the stricter create-by-AI pattern),
+ * so delete/open of existing mixed-case agents still works.
+ */
+export declare function resolveCustomAgentFilePath(directory: string, name: string): string;
+/**
+ * Containment check for management operations (write / delete / open).
+ *
+ * `PathUtils.isPathInside` is a string-prefix test, so a symlink placed inside
+ * the agents directory passes it while the OS resolves to a target elsewhere —
+ * `unlink` would then follow the link and an editor would open the target. So
+ * resolve both sides with `realpath` before comparing.
+ *
+ * Lexical mismatch is not enough to refuse: macOS `/var` and `/private/var`
+ * are the same directory after realpath. Only the resolved paths decide.
+ *
+ * Non-existent paths are expected (create writes a new file): fall back to the
+ * deepest existing ancestor. Do not use that fallback for a dangling symlink —
+ * the hop chain already decided whether its target escapes.
+ *
+ * Async on purpose — this runs on the daemon's HTTP path (`/api/v1/agents/*`),
+ * where a sync realpath on a slow/network filesystem would block the loop.
+ */
+export declare function assertCustomAgentFileContained(filePath: string, baseDirectory: string): Promise<void>;

package/cli/dist-server/types/node/agent/custom-agent-manager.d.ts

@@ -0,0 +1,43 @@
+import { Logger } from '@celljs/core';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { ConsoleManager } from '../console';
+import { type Session, SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { AgentService, CreateCustomAgentResult, CustomAgent, CustomAgentManager, CustomAgentScope } from '../../vendor/cbc-core/node/index.js';
+import { CustomAgentPathRegistry } from './custom-agent-path-registry';
+export declare class CustomAgentManagerImpl implements CustomAgentManager {
+    protected readonly productManager: ProductManager;
+    protected readonly sessionManager: SessionManager;
+    protected readonly agentService: AgentService;
+    protected readonly logger: Logger;
+    protected readonly consoleManager: ConsoleManager;
+    protected readonly customAgentPathRegistry?: CustomAgentPathRegistry;
+    protected customAgents: CustomAgent[];
+    init(): void;
+    /**
+     * Build the model catalog exposed to the one-time agent generator.
+     * Keep it derived from the current ProductConfiguration (the same filtered
+     * source used by `/model`) and omit endpoint/key fields.
+     */
+    private getAiModelChoices;
+    /**
+     * Normalize the model selected by the generator. Exact IDs are preferred,
+     * but display names and aliases are accepted for natural-language output.
+     * Unknown/disabled models fail closed to parent-model inheritance.
+     */
+    private resolveAiModel;
+    private buildAiModelPrompt;
+    private agentSettingsWithAI;
+    private static readonly AI_TOOLS_FALLBACK;
+    private resolveAiTools;
+    private createAgentMd;
+    private loadCustomAgents;
+    private getSavePath;
+    createByAI(session: Session, description: string, scope: CustomAgentScope): Promise<CreateCustomAgentResult>;
+    delete(agentName: string): Promise<void>;
+    get(agentName: string): CustomAgent | undefined;
+    getAll(): CustomAgent[];
+    resolveSettingsPath(agent: CustomAgent): Promise<string>;
+    openSettings(agent: CustomAgent, options?: {
+        allowTerminalEditor?: boolean;
+    }): Promise<void>;
+}

package/cli/dist-server/types/node/agent/custom-agent-path-registry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Maps loaded custom-agent names to their original markdown file paths.
+ *
+ * `CustomAgentsProductProvider` scans `.codebuddy/agents` recursively and is the
+ * only place that knows the real file (including subdirectories and files whose
+ * frontmatter `name` differs from the file name). It records that path here so
+ * `CustomAgentManager` can delete/open the exact file without re-scanning or
+ * carrying agent-cli internals on the shared product `Agent` type.
+ *
+ * The registry is rebuilt on every product provider pass (`clear()` then `set()`),
+ * so it cannot go stale across config hot-reloads.
+ */
+export declare class CustomAgentPathRegistry {
+    private readonly paths;
+    set(name: string, filePath: string): void;
+    get(name: string): string | undefined;
+    delete(name: string): void;
+    clear(): void;
+}

package/cli/dist-server/types/node/agent/exit-planmode-visibility.d.ts

@@ -0,0 +1,64 @@
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+/**
+ * Marker key on `session.meta` that flags a sub-agent session as having an
+ * explicitly-locked plan permission mode (Priority 1 or Priority 2 in
+ * `AgentTask.configurePermissionMode`). Only such sub-agents are entitled to
+ * own a plan and call `ExitPlanMode` themselves — ones that merely inherit
+ * the main session's plan mode (Priority 4) do NOT, because plan approval is
+ * owned by the main session in that case.
+ *
+ * Kept as a string literal (and exported) so both the writer (AgentTask) and
+ * the reader (agent-manager visibility gate / tests) reference the same key.
+ */
+export declare const SUB_AGENT_PLAN_MODE_LOCKED_META_KEY = "subAgentPlanModeLocked";
+/**
+ * Env switch that disables plan mode (Enter/ExitPlanMode tools) entirely.
+ *
+ * When set to a truthy value (parsed via `BooleanUtils.isTruthy`), both
+ * `EnterPlanMode` and `ExitPlanMode` are hidden from every agent — main and
+ * sub alike — so the LLM never sees them and plan approval is never offered.
+ * Hosts that want to opt out of plan mode (e.g. embedded scenarios where the
+ * approval popup would have nowhere to render) inject this env when launching
+ * the CLI.
+ *
+ * Default is unset (plan mode enabled). Naming follows `CODEBUDDY_DISABLE_*`
+ * (cf. `CODEBUDDY_DISABLE_FORK_SUBAGENT`) so the convention stays consistent.
+ */
+export declare const ENV_DISABLE_PLAN_MODE = "CODEBUDDY_DISABLE_PLAN_MODE";
+/**
+ * Whether plan mode is disabled in the current process via env
+ * `CODEBUDDY_DISABLE_PLAN_MODE` (truthy → disabled).
+ *
+ * Single source of truth for both visibility gates — agent-manager hides
+ * `EnterPlanMode` / `ExitPlanMode` when this returns true, and the same
+ * function backs `isExitPlanModeVisibleForSession` below.
+ */
+export declare function isPlanModeDisabled(): boolean;
+/**
+ * Decide whether the `ExitPlanMode` tool should appear in this session's tool
+ * list when the LLM asks for it.
+ *
+ * Visibility rules:
+ *
+ *   0. Env `CODEBUDDY_DISABLE_PLAN_MODE` is truthy: hidden everywhere.
+ *      Highest precedence — if the host opted out of plan mode, no agent
+ *      ever sees the tool.
+ *   1. Main session (no `parentSessionId`): always visible — gating happens
+ *      via the user-driven plan mode in product.json, not here.
+ *   2. Sub-agent in plan mode AND explicitly locked there (spawned with
+ *      `mode: 'plan'` or with an agent-level `permissionMode: 'plan'` in
+ *      product.json): visible. ExitPlanMode is the agent's only escape hatch
+ *      back to the parent.
+ *   3. Sub-agent that merely INHERITED plan mode from the main session
+ *      (Priority 4 in `configurePermissionMode`): hidden. Plan approval in
+ *      this case is owned by the main session, and exposing the tool would
+ *      tempt the LLM to call it — triggering an approval popup that, even if
+ *      the user dismisses it, has already polluted the UX. The hard reject in
+ *      `ExitPlanModeTool.execute` is a defense-in-depth fallback for the
+ *      same case.
+ *   4. Sub-agent not in plan mode at all: hidden (irrelevant).
+ *
+ * @param session The session the LLM is currently running in.
+ * @returns `true` if ExitPlanMode should be advertised to the LLM.
+ */
+export declare function isExitPlanModeVisibleForSession(session: Session): boolean;

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

@@ -0,0 +1,22 @@
+export * from '../../vendor/cbc-shared/node/index.js';
+export * from '../../vendor/cbc-core/node/index.js';
+export * from './agent-runtime-adapter';
+export * from './agent-config-cli-fields';
+export * from './agent-display';
+export * from './agent-memory';
+export * from './subagent-limits';
+export * from './agent-manager';
+export * from './exit-planmode-visibility';
+export * from './agent-controller';
+export * from './interceptors';
+export * from './stream-json-init-interceptor';
+export * from './memory-context-interceptor';
+export * from './team-context-interceptor';
+export * from './teammate-failure-interceptor';
+export * from './insights-data-agent-run-interceptor';
+export * from './builtin-agent-modes';
+export * from './custom-agent-identity';
+export * from './custom-agent-manager';
+export * from './main-agent-policy';
+export * from './main-agent-session';
+export * from './agent-completion-waiter';

package/cli/dist-server/types/node/agent/insights-data-agent-run-interceptor.d.ts

@@ -0,0 +1,67 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { PromptRenderer } from '../../vendor/cbc-core/node/index.js';
+import { SessionRunStateMachine } from '../../vendor/cbc-core/node/index.js';
+import { SettingsManager } from '../settings';
+import { InsightsReportService, SessionFacetService, StatsService } from '../stats';
+import { AgentRunInterceptor, AgentRunRequest } from '../../vendor/cbc-core/node/index.js';
+/**
+ * Insights 数据 Agent 运行拦截器
+ *
+ * 对齐 Claude Code 的增量 facet 架构：
+ * 1. 通过 SessionFacetService 增量分析每个 session（跳过未变化的）
+ * 2. 聚合所有 per-session facet 数据 + 全局统计数据
+ * 3. 并行发送 7 个汇总请求（基于聚合数据）
+ * 4. 发送第 8 个 at-a-glance 请求
+ * 5. 生成 HTML 报告并替换占位符
+ */
+export declare class InsightsDataAgentRunInterceptor implements AgentRunInterceptor {
+    priority: number;
+    protected readonly statsService: StatsService;
+    protected readonly sessionFacetService: SessionFacetService;
+    protected readonly promptRenderer: PromptRenderer;
+    protected readonly reportService: InsightsReportService;
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly stateMachine: SessionRunStateMachine;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * 从 per-session facets + 全局统计构建聚合数据
+     * 这是发送给 7 个汇总请求的输入
+     */
+    private buildAggregatedData;
+    /**
+     * 渲染模板
+     */
+    private renderPrompt;
+    /**
+     * 并行发送 7 个汇总分析请求
+     */
+    private runAggregateRequests;
+    /**
+     * 构建 facet 摘要（供 at-a-glance 使用）
+     */
+    private buildFacetSummary;
+    /**
+     * 发送 at-a-glance 汇总请求
+     */
+    private runConsolidationRequest;
+    /**
+     * 组装最终 InsightsData
+     */
+    private assembleInsightsData;
+    private parseJsonResponse;
+    private getFallback;
+    private replacePlaceholder;
+    /**
+     * 更新 loading box 中的进度文本
+     */
+    private emitProgress;
+    /**
+     * 清除进度文本，恢复默认 loading phrase
+     */
+    private clearProgress;
+    /**
+     * 检查 abort 信号，如果已取消则抛出 AbortError
+     */
+    private throwIfAborted;
+}

package/cli/dist-server/types/node/agent/interceptors/command-interceptors.d.ts

@@ -0,0 +1,89 @@
+import { AgentManager, AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest, PromptRenderer, SessionHookManager } from '../../../vendor/cbc-core/node/index.js';
+import { Command, ProductManager } from '../../../workspace/product/lib/common/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { CustomCommandRenderer, McpPromptRenderer } from '../../command';
+import { SettingsManager } from '../../settings/settings-protocol';
+export declare class AgentSwitchAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly agentManager: AgentManager;
+    protected readonly productManager: ProductManager;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly promptRenderer: PromptRenderer;
+    protected readonly customCommandRenderer: CustomCommandRenderer;
+    protected readonly mcpPromptRenderer: McpPromptRenderer;
+    protected readonly logger: Logger;
+    protected readonly sessionHookManager: SessionHookManager;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * `/compact` 直接路由到 compact agent，不经过 ContextCompactSummarizer，
+     * 因此需要在这里单独触发 PreCompact。内部压缩回灌消息带有
+     * isCompactInternal，必须跳过以避免重复触发。
+     */
+    protected executeManualPreCompactHooks(request: AgentRunRequest): Promise<void>;
+    /**
+     * 从输入中提取命令名（不含 / 前缀）。
+     * 支持从 <channel> 标签包裹的文本中提取斜杠命令。
+     */
+    private extractInputCommandName;
+    /**
+     * `command_source` 取值对齐 Claude Code 官方枚举（'plugin' | 'user' | 'project' | 'mcp'）：
+     * plugin 命令按 tag 识别，MCP prompt 命令固定 'mcp'，剩下的自定义/Workflow 命令
+     * 用 `Command.scope`（'user' | 'project'）。内置命令没有 scope，留空。
+     */
+    protected resolveCommandSource(command: Command): string | undefined;
+    /**
+     * UserPromptExpansion（Claude Code 官方事件）通用阻断入口：命令/skill 展开成
+     * prompt、送进模型之前统一从这里触发一次 hook，可被阻断。命令展开与 skill
+     * 展开共用同一个入口，不因调用方（如统一资产门控）而有特殊路径。
+     *
+     * 阻断时负责把提示追加进 input 并置 skipRun；调用方只需要在返回 true 时停止
+     * 继续渲染/展开当前这条命令。
+     */
+    protected guardPromptExpansion(request: AgentRunRequest, payload: {
+        expansionType: 'slash_command' | 'mcp_prompt';
+        commandName: string;
+        commandArgs: string;
+        commandSource?: string;
+        prompt: string;
+    }, fallbackMessage?: string): Promise<boolean>;
+    protected resolveAgent<TAgent>(command: Command): Promise<TAgent | undefined>;
+    protected handleCommands(request: AgentRunRequest, commands: Command[]): Promise<Command | undefined>;
+    protected safeRender(promptToRender: string, ctx?: Record<string, any>): Promise<string>;
+    protected isCommand(text: string, command: Command): boolean;
+    /**
+     * 构建命令上下文标签（统一格式）
+     * 用于 MCP prompt 和 custom command，确保两者拼接给模型的格式一致
+     * @param commandName 命令名称（如 /review-pr 或 /mcp__server__prompt）
+     * @param fullInput 完整输入（包含命令名和参数）
+     * @returns 格式化的标签字符串
+     */
+    protected buildCommandContextTags(commandName: string, fullInput: string): string;
+    /**
+     * Extract the command text from a message, unwrapping any envelope the client
+     * put around it. For plain text, returns the trimmed text.
+     */
+    private extractCommandText;
+    /**
+     * 拆开客户端加在命令文本外面的包裹，并保留改写后要还原的隐藏上下文。
+     *
+     * 支持两种形态：
+     * - `<channel source="...">/cmd</channel>`（多频道事件）；
+     * - `<system-reminder …>…</system-reminder>\n<user_query>/cmd</user_query>`
+     *   （WorkBuddy / IDE 客户端发送前就拼好的形态，见 HIDDEN_CONTEXT_USER_QUERY_RE）。
+     */
+    private parseCommandEnvelope;
+    /**
+     * 把隐藏上下文放回改写结果前面。
+     *
+     * 不重新套 `<user_query>`：TUI 路径下展开产物同样是裸的
+     * `<command-message>…`（`UserQueryWrapperAgentRunInterceptor` 认它是系统注入内容
+     * 而跳过包裹），这里保持一致，避免两条链路给模型的形状不同。
+     */
+    private restoreHiddenContext;
+    /**
+     * 处理 skill 的斜杠命令调用
+     * 当用户显式输入 /skill-name 且未匹配到 command 时，尝试在 skills 中查找
+     * 找到后将用户输入替换为 skill 指令内容，使 LLM 直接执行 skill
+     */
+    protected handleSkillSlashCommand(request: AgentRunRequest): Promise<boolean>;
+}

package/cli/dist-server/types/node/agent/interceptors/deep-research-pending-interceptor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DeepResearchPendingInterceptor —— 当 session 处于"已触发 /deep-research 但 Workflow 工具尚未调"
+ * 状态时,每轮在 user input 末尾注入一段加强 reminder,降低主 agent "澄清几轮就忘了调工具"的概率。
+ *
+ * 单一职责:扫 history → 判断 pending 状态 → 注入 reminder。
+ *
+ * Pending 判断:
+ *   - history 里有 user 消息含 `data-role="deep-research-trigger"` reminder
+ *   - 且 history 里**没有** Workflow 工具的 function_call (`name === ToolNames.WORKFLOW`)
+ *   两者同时成立 → pending → 注入。
+ *
+ * 一旦 Workflow 工具被调,pending 就解除,后续轮次不再注入。
+ *
+ * 优先级:与 keyword/effort 同档(SystemReminderContext - 35),先后无所谓。
+ */
+import { PromptManager } from '../../../workspace/prompts/lib/common/index.js';
+import { AgentRunInterceptor, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+import type { AgentInputItem } from '../../../vendor/cbc-shared/node/index.js';
+export declare class DeepResearchPendingInterceptor implements AgentRunInterceptor {
+    priority: number;
+    protected readonly promptManager: PromptManager;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * Visible-for-testing:扫 history 判定是否处于"已触发但未调工具"状态。
+     */
+    isPending(history: ReadonlyArray<AgentInputItem>): boolean;
+    private isWorkflowToolCall;
+    private containsDeepResearchTrigger;
+    private loadReminder;
+}

package/cli/dist-server/types/node/agent/interceptors/env-interceptor.d.ts

@@ -0,0 +1,7 @@
+import { SettingsManager } from '../../settings';
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+export declare class EnvAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly settingsManager: SettingsManager;
+    intercept(_request: AgentRunRequest): Promise<void>;
+}

package/cli/dist-server/types/node/agent/interceptors/file-interceptors.d.ts

@@ -0,0 +1,45 @@
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { ImageBlobService } from '../../blob-store';
+import { ConditionalRulesService } from '../../memory';
+import { ReferenceService } from '../../references/reference-protocol';
+import { ReadFileStateService } from '../../tools';
+export declare class ReferencePathProcessorAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly readFileStateService: ReadFileStateService;
+    protected readonly referenceService: ReferenceService;
+    protected readonly logger: Logger;
+    protected readonly imageBlobService: ImageBlobService;
+    private readonly MAX_FILE_SIZE;
+    private readonly MAX_TEXT_FILE_SIZE;
+    intercept(request: AgentRunRequest): Promise<void>;
+    private getFileSize;
+    private sendBashNotification;
+    private sendReadNotification;
+    private sendNotificationToUI;
+    private processUserMessageFiles;
+    private processTextForFilePaths;
+    /**
+     * A quoted file badge (`@"…"`, which the resource-link encoder writes for any
+     * path outside `[A-Za-z0-9_./-]`, e.g. non-ASCII characters or spaces) cannot
+     * be read by the `@path` syntax, which stops at the quote and the first space.
+     * When it is a structured `file://` reference, its URI names the file instead.
+     */
+    private extractReferencedPaths;
+    private resolvePath;
+    private isDirectory;
+    private isImageFile;
+    private isTextFile;
+    private createImageContent;
+    private createDirectoryContent;
+    private createTextContent;
+}
+/**
+ * 条件规则注入拦截器
+ * 处理 @ 文件引用触发的条件规则匹配和注入
+ */
+export declare class ConditionalRulesAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly conditionalRulesService: ConditionalRulesService;
+    intercept(request: AgentRunRequest): Promise<void>;
+}