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

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

@@ -0,0 +1,73 @@
+/** Agent Home 自治能力的配额与护栏：纯常量 + 纯校验，工具层与 HTTP 共用。 */
+import type { AgentHomeDirectoryFile } from './agent-home-directory';
+/** 同事总数上限（不含默认 Agent），对齐 grok 的 MAX_AGENTS_PER_USER。 */
+export declare const MAX_AGENTS_PER_USER = 50;
+/** 频道总数上限：每频道 1 transcript + 1 board + 1 侧栏项。 */
+export declare const MAX_CHANNELS = 20;
+/**
+ * 成员数上限/下限的唯一来源（domain sanitize、HTTP controller、web-ui 共用一份。
+ * 以前同一个数字在四五个文件里各写一遍，改一处就会漂）。
+ */
+/** 私信房（数据模型里的 group）成员 2–6。 */
+export declare const GROUP_MIN_MEMBERS = 2;
+export declare const GROUP_MAX_MEMBERS = 6;
+/** 频道成员 2–6。 */
+export declare const CHANNEL_MIN_MEMBERS = 2;
+export declare const CHANNEL_MAX_MEMBERS = 6;
+/** 单个频道任务板的任务上限。 */
+export declare const MAX_TASKS_PER_CHANNEL = 50;
+/**
+ * 单行短字段（名字/标题/引擎/权限模式）长度上限。
+ *
+ * HTTP 入参截断（controller/groups）与 domain 落盘截断（建人/建频道）必须同数：
+ * 以前 60 在 HTTP 的 NAME_MAX、COLLEAGUE_NAME_MAX、CHANNEL_NAME_MAX 各写一遍，
+ * 改一处就漂（HTTP 先截一刀、domain 再截一刀，两边不一致时用户看到的名字会莫名其妙）。
+ */
+export declare const AGENT_HOME_NAME_MAX = 60;
+/** 长文本（描述/发言正文/预览）长度上限，同样 HTTP 与 domain 共用一份。 */
+export declare const AGENT_HOME_TEXT_MAX = 2000;
+/** 任务标题长度上限（HTTP / domain / web-ui 输入框共用一份）。 */
+export declare const TASK_SUBJECT_MAX = 200;
+/** 单条任务最多几条引用。 */
+export declare const TASK_REFS_MAX = 20;
+/** 单条任务引用的值（路径 / 链接 / 提交号）长度上限。 */
+export declare const TASK_REF_VALUE_MAX = 1024;
+/** 单个频道附件体积上限（聊天场景常识值 20MB；服务端校验与 web-ui 选择器共用一份）。 */
+export declare const CHANNEL_ATTACHMENT_MAX_BYTES: number;
+/** 一条消息最多几个附件（服务端与 web-ui composer 共用一份）。 */
+export declare const CHANNEL_ATTACHMENT_MAX_PER_MESSAGE = 4;
+/** 唤醒预算：同一任务对同一个人的自动唤醒次数上限，超限标 stalled。 */
+export declare const MAX_WAKE_PER_TASK_PER_AGENT = 5;
+/**
+ * 成员互叫护栏（见 agent-home-channel-wake-guard）：每频道每窗口最多这么多次**自动**唤醒，
+ * 超出就抑制（消息与未读照留，只是不叫人）。用户发言 / @ 点名 / 派单不受限。
+ * 可用 env 覆盖：`CODEBUDDY_AGENT_HOME_WAKE_WINDOW_MS` / `CODEBUDDY_AGENT_HOME_WAKE_MAX`。
+ */
+export declare const CHANNEL_AUTO_WAKE_WINDOW_MS: number;
+export declare const CHANNEL_AUTO_WAKE_MAX = 3;
+export declare function channelAutoWakeWindowMs(): number;
+export declare function channelAutoWakeMax(): number;
+/** 创建深度：默认 Agent 建的人 depth=0，其再建 +1；超过即拒。 */
+export declare const MAX_CREATOR_DEPTH = 2;
+/** escalate nudge 的默认「多久没动算卡住」阈值。 */
+export declare const DEFAULT_NUDGE_STALE_MS: number;
+/** create / dispatch 的 requestId 幂等窗口。 */
+export declare const REQUEST_ID_WINDOW_MS: number;
+/** 注入给成员的房间消息单条截断长度（轮次/条数上限见 channel-room-turn.ts）。 */
+export declare const CHANNEL_TRANSCRIPT_MESSAGE_MAX = 2000;
+/** 一次 dispatch 最多派几条（防止一次刷爆看板）。 */
+export declare const MAX_DISPATCH_BATCH = 10;
+export declare function countColleagues(directory: AgentHomeDirectoryFile): number;
+export declare function countChannels(directory: AgentHomeDirectoryFile): number;
+/** 建人前的配额判据：返回 true = 还能建。 */
+export declare function canCreateColleague(directory: AgentHomeDirectoryFile): boolean;
+/** 建频道前的配额判据：返回 true = 还能建。 */
+export declare function canCreateChannel(directory: AgentHomeDirectoryFile): boolean;
+/** 进程消失后跳过它的保护窗：交棒后 15s 内进程没在跑算"还在起"，不跳过。 */
+export declare const ROOM_TURN_WATCHDOG_MIN_AGE_MS = 15000;
+/** 一轮的绝对上限（到点直接收场，不叫任何人）：兜底一切卡死形态。 */
+export declare const ROOM_TURN_MAX_AGE_MS: number;
+/** 活着但迟迟不回：每 4 分钟催办一次。 */
+export declare const ROOM_TURN_NUDGE_AFTER_MS: number;
+/** 每人每棒最多催办 3 次；催满仍不回就按弃权推进队列。 */
+export declare const ROOM_TURN_MAX_NUDGES = 3;

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

@@ -0,0 +1,34 @@
+/**
+ * 组队/房间/频道共用的加入规则。无 I/O，web-ui 可直接 import。
+ *
+ * 一句话定位：**主 Agent 是委托侧（用户当前的工作现场），房间是执行侧**，
+ * 所以主 Agent 不进房间也不进频道——它不是常驻执行者：
+ * - 它随窗口/进程生灭，房间编排要的"稳定身份 + 能判活 + 常驻上下文"三条都不满足；
+ * - 它占着轮次的一棒却判不了死活（看门狗只能"判不了就当活着"），唤醒投递又会落到
+ *   一口无主邮箱（谁先醒谁读），10 个窗口就等于 10 个"房间里的你"；
+ * - 它的上下文是用户私有的工作现场，房间信息不该注入进去。
+ * 委托只允许单向：主 Agent → 房间（建群 / 派单 / 读板 / 说一句），
+ * **不存在 房间 → 主 Agent**（不唤醒、不注入、不占席位）。
+ * 上游同理：成员清一色是 agent，用户是"发言人"而不是成员
+ * （resolveResponders 扫的是 speaker.kind === user）。
+ *
+ * 空 id / 主 Agent / 极简都不能进。
+ */
+export type RoomMessageCallStyle = 'none' | 'direct' | 'repl';
+export declare function roomMessageCallStyle(engine?: string): RoomMessageCallStyle;
+export declare function canJoinAgentHomeTeam(agentId: string, defaultAgentId?: string | null, engine?: string): boolean;
+/** 进不了房间/频道的原因。主 Agent 与极简同一条禁令，文案分开。 */
+export type AgentHomeTeamJoinBlock = 'default' | 'minimal';
+export declare function agentHomeTeamJoinBlock(agentId: string, defaultAgentId?: string | null, engine?: string): AgentHomeTeamJoinBlock | undefined;
+/** 主 Agent + 极简。sanitize / 加人计划共用。 */
+export declare function blockedTeamAgentIds(agents: readonly {
+    id: string;
+    engine?: string;
+}[], defaultAgentId?: string | null): Set<string>;
+export declare function canJoinAgentHomeRoom(agentId: string, defaultAgentId?: string | null, engine?: string): boolean;
+/**
+ * 频道成员资格：**与组队同一条**（主 Agent 是委托侧的工作现场，不进房间；
+ * 极简在房间里说不了话也不进）。留这个函数名只为在调用点表达"这是频道面的资格判定"，
+ * 策略只有 canJoinAgentHomeTeam 一份。
+ */
+export declare function canJoinAgentHomeChannel(agentId: string, defaultAgentId?: string | null, engine?: string): boolean;

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

@@ -0,0 +1,39 @@
+/**
+ * 频道 @：**正文里的名字**就是地址（对齐上游 `parseGroupMentions`）。
+ * 撞名不判、不猜——同名的人**全部**被点到（上游就是逐个成员匹配后全收）。要精确到人
+ * 就用 id：完整 id 或前 8 位（`@59c89708`）；`@所有人` / `@everyone` / `@all` 点全部成员。
+ *
+ * 工具参数不走这里：那是 id（见 agent-home-recipients 的说明）。
+ */
+export interface ChannelMentionMember {
+    id: string;
+    name: string;
+}
+export type ChannelTextPart = {
+    kind: 'text';
+    text: string;
+}
+/**
+ * `linkAgentId` 只给芯片链接用（首个匹配，**不是**权威地址）；
+ * 这次 @ 真正叫到的所有人是 `agentIds`（撞名时可能多个，唤醒一律用它）。
+ */
+ | {
+    kind: 'mention';
+    linkAgentId: string;
+    agentIds: readonly string[];
+    name: string;
+} | {
+    kind: 'everyone';
+    name: string;
+};
+export declare const CHANNEL_EVERYONE_ALIASES: readonly ["所有人", "everyone", "all"];
+/** @ 前的词边界（web-ui 补全与 node 切词共用一份，别各写一份漂移）。 */
+export declare const CHANNEL_MENTION_BOUND: RegExp;
+export declare function isEveryoneMentionName(name: string): boolean;
+export declare function mentionAgentIdsFromText(text: string, members: readonly ChannelMentionMember[]): string[];
+/** 工具 mentions[]：先 id（完整/前 8 位），再名字句柄（全名 / 去空格 / 第一个词），命中全部。 */
+export declare function resolveChannelMentionIds(needles: readonly string[], members: readonly ChannelMentionMember[]): string[];
+export declare function collectMentionAgentIds(text: string, members: readonly ChannelMentionMember[], options?: {
+    everyone?: boolean;
+}): string[];
+export declare function splitChannelText(text: string, members: readonly ChannelMentionMember[]): ChannelTextPart[];

package/cli/dist-server/types/node/agent-home/agent-home-room-contacts.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 房间联系人解析。无 fs；吃 directory 形状。
+ */
+import type { AgentHomeDirectoryFile, AgentHomeProfile } from './agent-home-directory';
+export interface RoomContact {
+    id: string;
+    name: string;
+    /** 投递目标：对方的主对话。没有=还没开口，联系不上 */
+    jobId?: string;
+}
+export interface RoomContactScope {
+    groupId: string;
+    groupName: string;
+    contacts: RoomContact[];
+}
+/** `resolveMeAsAgent` 的身份解析策略：**可见性宽松、动作严格**（#125667 评审）。 */
+export interface ResolveMeAsAgentOptions {
+    /**
+     * 认不出同事身份时（jobId 存在但 jobAssignments / sessionAssignments 都对不上）是否回落默认 Agent。
+     *
+     * - `true` / 缺省 —— 回落。**只给可见性路径用**：用户口径要求 job agent 的频道能力与
+     *   main agent 等同（`cbc --bg` / 认领窗口期的 job 也要能看见这三个工具）。
+     * - `false` —— 不回落，返回 `undefined`。**动作路径必须用它**：默认 Agent 就是用户，
+     *   拿它去发言会落成 `from:"user"`（越权 + 开一轮唤醒全员）、去私信会冒名
+     *   `teammate_id="default"`、去改板会让 `actor.kind==='agent'` 的校验整体失效。
+     *   认不出身份就 fail-closed，由调用方给出「没有 Agent Home 身份」的明确拒绝。
+     *
+     * 无 jobId 的真实主会话与这个开关无关，永远回落默认 Agent（主 Agent 语义不变）。
+     */
+    fallbackToDefault?: boolean;
+}
+/**
+ * 当前说话人。
+ *
+ * 顺序：jobId 映射 → 会话级登记（sessionAssignments）→ 默认 Agent（可关，见 options）。
+ * 中间那步是为了兜住 jobId 缺失或尚未写入 jobAssignments 的同事会话（jobId 是进程级
+ * 一次性信号，job 内派生会话拿不到）——没有它，同事解析不出身份，频道工具会整体消失。
+ *
+ * 最后那步是**两义**的：默认 Agent 是「用户」，所以它既是可见性兜底（工具在不在），
+ * 也是身份冒用的入口（发言/私信/改板的归属）。`fallbackToDefault: false` 关掉它，
+ * 让动作路径只认真实身份 —— 见 ResolveMeAsAgentOptions 与各处调用点。
+ */
+export declare function resolveMeAsAgent(directory: AgentHomeDirectoryFile, myJobId: string | undefined, mySessionId?: string, options?: ResolveMeAsAgentOptions): AgentHomeProfile | undefined;
+/**
+ * 只看我所在的可见房间。没有 job id = 默认 Agent，联系人永远为空。
+ * `mySessionId` 必须和工具路径同源地传进来：会话已登记、进程又没有 jobId 的同事
+ * （「新建智能体」续跑 / job 内派生会话）只有靠它才认得出自己，否则花名册会按默认
+ * Agent（= 用户）算 —— 同一会话在工具路径与提醒路径给出两个身份（#125667 F6）。
+ */
+export declare function resolveRoomContacts(directory: AgentHomeDirectoryFile | undefined, myJobId: string | undefined, mySessionId: string): RoomContactScope[];
+export declare function flattenRoomContacts(scopes: readonly RoomContactScope[]): RoomContact[];

package/cli/dist-server/types/node/agent-home/channel-wake-service.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 频道唤醒编排服务：依赖（JobStore / Daemon）在这里解析一次，工具不再各自 ContainerUtil.get。
+ * 只做「落盘之后叫醒」，永远在目录锁外调用；单测直接 new + 赋字段即可。
+ */
+import { type IDaemonProcessManager } from '../../workspace/cbc-daemon/lib/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { type IJobStore } from '../agent-view/agent-view-protocol';
+import { SettingsManager } from '../settings/settings-protocol';
+import { type ChannelWakeSkipReason } from './agent-home-channel-wake';
+import { type AgentHomeChannel, type AgentHomeChannelMessage, type AgentHomeDirectoryFile } from './agent-home-directory';
+export interface ChannelWakeDeps {
+    store?: IJobStore;
+    processManager?: IDaemonProcessManager;
+}
+/**
+ * 叫醒审计的两个回调（单一实现）：工具路径（ChannelWakeService）与 HTTP 路径
+ * （local-agent-home-controller 的用户发言）共用，字段/文案不会各写一份。
+ * 投递成功的语义是「信已经进了对方的 job 收件箱」，不代表对方已经开始处理。
+ */
+export declare function channelWakeAudit(input: {
+    homeDir: string;
+    channelId: string;
+    actorAgentId?: string;
+    messageId?: string;
+    log?: (message: string) => void;
+}): {
+    onSkip: (agentId: string, reason: ChannelWakeSkipReason) => void;
+    onDelivered: (agentId: string) => void;
+};
+export declare class ChannelWakeService {
+    protected readonly injectedStore?: IJobStore;
+    protected readonly injectedProcessManager?: IDaemonProcessManager;
+    protected readonly settingsManager?: SettingsManager;
+    protected readonly logger?: Logger;
+    /** 注入优先；缺注入时退回容器（真实运行；单测没有容器也不会炸）。 */
+    resolveDeps(): ChannelWakeDeps;
+    /**
+     * 发言落盘后的叫醒出口。返回 false = 拿不到 JobStore（只记日志，不影响发言结果）。
+     * job worker 进程里 canRespawn 强制 false，只写信 + wake 票，避免双 fork。
+     */
+    wakeAfterSpeech(input: {
+        homeDir: string;
+        directory: AgentHomeDirectoryFile;
+        channel: AgentHomeChannel;
+        message: AgentHomeChannelMessage;
+        /** speech 侧结果：没有推进轮次就别重复叫人。 */
+        advancedTurn?: boolean;
+        onSkip?: (agentId: string, reason: ChannelWakeSkipReason) => void;
+    }): Promise<boolean>;
+    /** 叫醒审计（onSkip / onDelivered 回调），供各路径在投递结果上落审计行。 */
+    private audit;
+    /** 自治总闸（Web UI 那个开关）关掉就不投递：票与轮次留在原地，开关打开后自然继续。 */
+    private wakeAllowed;
+    /** 任务事件等非发言路径的定向叫醒。返回 false = 开关关着或拿不到 JobStore。 */
+    wakeMembers(input: {
+        homeDir: string;
+        directory: AgentHomeDirectoryFile;
+        channel: AgentHomeChannel;
+        text: string;
+        from?: string;
+        mentionNames?: string[];
+        messageId?: string;
+        onlyAgentIds?: readonly string[];
+        excludeAgentId?: string;
+        onSkip?: (agentId: string, reason: ChannelWakeSkipReason) => void;
+    }): Promise<boolean>;
+    /** 招人起 job 用的 logDir；工具拿不到容器时退化为默认。 */
+    logDir(): string;
+}

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

@@ -0,0 +1,242 @@
+import { Application, ApplicationLifecycle, Logger } from '@celljs/core';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { AgentTask, AgentTaskEvent, AgentTaskManager, AgentTaskStatus, TeamNotificationSettledListener } from './agent-task-protocol';
+export declare const ENV_WAIT_FOR_RUNNING_TASKS_TIMEOUT_MS = "CODEBUDDY_CODE_WAIT_FOR_RUNNING_TASKS_TIMEOUT_MS";
+export declare const DEFAULT_WAIT_FOR_RUNNING_TASKS_TIMEOUT_MS = 600000;
+export declare const MAX_WAIT_FOR_RUNNING_TASKS_TIMEOUT_MS = 600000;
+/** Clamp 0-600000 like TaskOutput. Default 600000. `0` means "no wait". */
+export declare function resolveWaitForRunningTasksTimeoutMs(explicit?: number): number;
+/** Dedup window: a member SendMessage newer than this is treated as "recent". */
+export declare const FRAMEWORK_NOTIFICATION_DEDUP_WINDOW_MS = 30000;
+/**
+ * Decide whether a team member's framework completion-notification should be
+ * delivered to the team-lead inbox, or deduped away.
+ *
+ * Pure function (no DI / no I/O) so the race-sensitive decision can be unit
+ * tested directly — mirrors the `decidePausedQueueAction` pattern in
+ * `team-inbox-dispatch-service.ts`.
+ *
+ * The dedup exists to avoid double-notifying when a member's own fresh
+ * SendMessage is still the lead's most recent signal from that member. But it
+ * must NOT apply to the *last* finishing member: that completion is the team's
+ * "everyone is done, go aggregate" trigger. Suppressing it deadlocks the lead
+ * at idle (UI stuck "thinking", no further model calls, no credit spend) when
+ * the lead consumed the member's SendMessage in a turn that ended without a
+ * final answer and was relying on the completion notification to wake it again.
+ *
+ * @param hasOtherActiveMember whether any *other* member of the team still has a
+ *        pending/running task. False ⇒ this member is the last to finish.
+ * @param hasRecentMemberMessage whether the lead inbox already holds a SendMessage
+ *        from this member inside the dedup window.
+ * @returns `true` to send the notification, `false` to skip it.
+ */
+export declare function shouldDeliverFrameworkNotification(hasOtherActiveMember: boolean, hasRecentMemberMessage: boolean): boolean;
+/**
+ * Implementation of AgentTaskManager
+ * Manages the lifecycle of agent tasks executing sub-agents
+ */
+export declare class AgentTaskManagerImpl implements AgentTaskManager, ApplicationLifecycle<Application> {
+    protected readonly logger: Logger;
+    init(): void;
+    onStop(): Promise<void>;
+    private tasks;
+    /**
+     * 任务生命周期事件的 emitter。
+     *
+     * 上限调离 Node 默认的 10：这是一个 **hub** —— 同一个事件（尤其
+     * `task-killed`）的订阅方天然就有好几路，且其中一路的数量随**并发在途
+     * prompt** 增长：
+     *
+     * - `completion-bus` 常驻 1；
+     * - `acp-team-bridge` 常驻 1；
+     * - TUI 的 `use-team-progress` / `use-coordinator-workers` /
+     *   `use-focused-member` 各 1（组件挂载期间）；
+     * - `acp-agent` 每个在途 prompt 1（订阅/退订成对，见 acp-agent 的 cleanup）。
+     *
+     * 团队会话里几个 member 同时跑就越过 10，于是报
+     * `MaxListenersExceededWarning: 11 task-killed listeners` —— 那是扇出，不是漏。
+     *
+     * **不设 0（不限）**：那会连真正的泄漏一起静音。留一个远高于正常扇出、又能
+     * 兜住失控增长的有限值。
+     */
+    private eventEmitter;
+    private waitPromises;
+    private mainSession;
+    /**
+     * Track pending team-member notification timers for dedup/cancellation.
+     * Key: "{teamName}/{memberName}", Value: NodeJS.Timeout
+     */
+    private pendingTeamNotifications;
+    /**
+     * Timer for auto-team completion cleanup.
+     * Set when all auto-team members have finished; cleared if a new member spawns.
+     */
+    private autoTeamCleanupTimer;
+    private autoTeamCleanupDepth;
+    private readonly onTeamMemberStateChange;
+    /**
+     * Timer for periodic cleanup of completed/failed tasks.
+     * Runs every 60 seconds to remove tasks that have been in a terminal state
+     * for longer than COMPLETED_TASK_TTL_MS, preventing unbounded Map growth
+     * in long-running sessions (memory leak fix for monorepo scenarios).
+     */
+    private completedTaskCleanupTimer;
+    /**
+     * Time-to-live for completed/failed tasks before automatic removal.
+     * Tasks in terminal state for longer than this are eligible for cleanup.
+     */
+    private static readonly COMPLETED_TASK_TTL_MS;
+    /**
+     * Interval between cleanup sweeps.
+     */
+    private static readonly CLEANUP_INTERVAL_MS;
+    /**
+     * Maximum number of terminal team member sessions to keep in memory.
+     * When exceeded, the oldest terminal team member's subAgentSession is
+     * released to allow GC of its history (which can be very large).
+     */
+    private static readonly MAX_TERMINAL_TEAM_SESSIONS;
+    /**
+     * Register an existing agent task
+     * @param task The task to register
+     * @param skipStatusMonitoring If true, task is registered but status changes are not monitored
+     */
+    registerTask(task: AgentTask, skipStatusMonitoring?: boolean): void;
+    /**
+     * Get a specific task by ID.
+     * Supports both internal task IDs (e.g. "agent-a1b2c3d4") and
+     * team member agent IDs (e.g. "general-purpose-2@_auto_xxx").
+     */
+    getTask(id: string): AgentTask | undefined;
+    /**
+     * Get all tasks
+     */
+    getTasks(): AgentTask[];
+    /**
+     * Get tasks by status
+     */
+    getTasksByStatus(status: AgentTaskStatus): AgentTask[];
+    /**
+     * Get tasks by session ID
+     * Matches against mainSessionId (the parent session that spawned the task)
+     */
+    getTasksBySession(sessionId: string): AgentTask[];
+    /**
+     * Wait for a task to complete
+     */
+    waitFor(id: string, timeout?: number): Promise<AgentTask>;
+    /**
+     * Cancel a task
+     */
+    cancel(id: string): Promise<void>;
+    /**
+     * Subscribe to task events
+     */
+    on(event: AgentTaskEvent, listener: (task: AgentTask) => void): void;
+    /**
+     * Unsubscribe from task events
+     */
+    off(event: AgentTaskEvent, listener: (task: AgentTask) => void): void;
+    /**
+     * Remove a specific task by ID
+     */
+    removeTask(id: string): void;
+    /**
+     * Clear completed tasks
+     */
+    clearCompleted(): void;
+    /**
+     * Clear tasks for a specific session
+     */
+    clearBySession(sessionId: string): Promise<void>;
+    /**
+     * Subscribe to task status change events
+     */
+    private subscribeToTaskStatus;
+    /**
+     * Handle task status changes
+     */
+    private handleTaskStatusChange;
+    /**
+     * Internal: Resolve all waitFor promises for a task
+     */
+    private resolveWaitPromises;
+    /**
+     * Internal: Remove a waitFor promise
+     */
+    private removeWaitPromise;
+    /**
+     * Set the main session reference for task completion notifications
+     */
+    setMainSession(session: Session): void;
+    /**
+     * Get the configured main session
+     */
+    getMainSession(): Session | undefined;
+    hasPendingTeamNotifications(teamName: string): boolean;
+    onTeamNotificationSettled(listener: TeamNotificationSettledListener): void;
+    offTeamNotificationSettled(listener: TeamNotificationSettledListener): void;
+    private emitTeamNotificationSettled;
+    /**
+     * Trigger completion notification for a task.
+     *
+     * All background tasks have teamContext (via auto-team), so notifications
+     * are sent through the team mailbox with a delay for dedup.
+     */
+    private triggerNotification;
+    /**
+     * Schedule a delayed notification for a team member completion/failure.
+     *
+     * After a 4-second delay, checks if the teammate already sent a SendMessage
+     * to team-lead (by scanning the inbox for recent messages from this member).
+     * If so, the framework notification is skipped (dedup). Otherwise, a concise
+     * status notification is written to team-lead's inbox.
+     */
+    private scheduleTeamMemberNotification;
+    /**
+     * Build a concise notification message for the team-lead inbox.
+     * Contains only status metadata — no actual task output.
+     */
+    private buildTeamMemberNotification;
+    /**
+     * Check if all auto-team members have completed, and if so,
+     * schedule cleanup after a delay so the UI has time to show final status.
+     */
+    private checkAutoTeamCompletion;
+    /**
+     * Cancel all pending team member notification timers.
+     * Called during session/team cleanup.
+     */
+    private cancelPendingTeamNotifications;
+    /**
+     * Evict the oldest terminal team member sessions when the count exceeds
+     * MAX_TERMINAL_TEAM_SESSIONS. Releases their subAgentSession references
+     * to allow GC of potentially large conversation histories.
+     *
+     * This prevents unbounded memory growth when many team members are spawned
+     * in long-running monorepo sessions.
+     */
+    private evictOldestTeamSessions;
+    /**
+     * Start periodic cleanup of completed/failed tasks.
+     * Prevents unbounded growth of the tasks Map in long-running sessions.
+     */
+    private startCompletedTaskCleanup;
+    /**
+     * Remove non-team tasks that have been in a terminal state longer than TTL.
+     * Team member task records and retained sessions are managed separately by
+     * the team lifecycle and bounded session retention.
+     */
+    private cleanupExpiredTasks;
+    /**
+     * Stop the completed task cleanup timer.
+     * Should be called during shutdown to prevent leaking timers.
+     */
+    stopCleanup(): void;
+    /**
+     * Wait for all running/pending tasks to reach a terminal state.
+     * Used by CliExecutor to keep the process alive until background agents finish.
+     * Fail-open: timeout / reject logs a warning and continues shutdown.
+     */
+    waitForRunningTasks(timeout?: number): Promise<void>;
+}

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

@@ -0,0 +1,55 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { AgentTaskOutputFileManager } from './agent-task-protocol';
+/**
+ * Implementation of agent task output file management.
+ *
+ * fs 走 sandbox ambient 面（换源即迁移判据）：注入沙箱的会话里 tee 落虚拟
+ * 命名空间（pod 真实盘零写入），bin/local 直通逐字不变。写发生在子代理
+ * 运行内，ambient sandbox 经 root scope 四 seam 继承解析。
+ */
+export declare class AgentTaskOutputFileManagerImpl implements AgentTaskOutputFileManager {
+    protected readonly logger: Logger;
+    init(): void;
+    private readonly MAX_FILE_SIZE;
+    /** 写透尾环容量（字符 ≈ 字节，工具调用行为 ASCII 主体）。 */
+    private readonly RING_CAP;
+    /**
+     * 写透尾环 + 尺寸账本（remote fs 优化，CC getTaskOutputDelta 同语义面）：
+     * 写文件照旧（持久面/宿主可见性不变），同时进程内留最后 RING_CAP 尾窗与
+     * 绝对尺寸——running 态进度轮询与 append 前尺寸检查零远端 IO。
+     */
+    private readonly buffers;
+    /**
+     * AgentTask 输出属于临时运行资料，复用后台任务的用户隔离根目录。
+     * 不再写全局 /tmp/codebuddy，避免多人共用服务器时被首个创建者的目录权限阻断。
+     */
+    private getDefaultOutputDir;
+    /**
+     * Ensure the output directory exists
+     */
+    private ensureOutputDirectory;
+    /**
+     * Create an output file for a task
+     */
+    createOutputFile(taskId: string, outputDir?: string): Promise<string>;
+    /**
+     * Append content to a task's output file
+     * This is the main method used during task execution
+     */
+    appendToOutputFile(filePath: string, content: string): Promise<void>;
+    /**
+     * Append content to a task's output file by task ID
+     * This is a convenience method that resolves the file path internally
+     */
+    appendToOutputFileById(taskId: string, content: string): Promise<void>;
+    readProgressDelta(taskId: string, fromOffset: number): Promise<{
+        content: string;
+        offset: number;
+        omittedBytes: number;
+    }>;
+    finalizeOutputBuffer(taskId: string): void;
+    /**
+     * Get the output file path for a task
+     */
+    getOutputFilePath(taskId: string, outputDir?: string): string;
+}