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

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

@@ -0,0 +1,375 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+export declare const TeamManager: unique symbol;
+export declare const TeamMailbox: unique symbol;
+export declare const TeamCleanupService: unique symbol;
+export declare const TeamInboxDispatchService: unique symbol;
+/**
+ * Team member info stored in config.json
+ * Based on ~/.codebuddy/teams/{name}/config.json format
+ */
+export interface TeamMemberInfo {
+    /** Unique agent ID in format "{name}@{team-name}" */
+    agentId: string;
+    /** Human-friendly name (e.g. "ux-designer", "tech-architect") */
+    name: string;
+    /** 角色/职责名称（用于 UI 展示） */
+    role?: string;
+    /** Agent type (e.g. "team-lead", "general-purpose") */
+    agentType: string;
+    /** Model to use for this member */
+    model?: string;
+    /** Initial prompt for teammates (not set for team-lead) */
+    prompt?: string;
+    /** Display color for UI differentiation */
+    color?: string;
+    /** Whether plan mode is required for this member */
+    planModeRequired?: boolean;
+    /** Timestamp when the member joined */
+    joinedAt: number;
+    /** tmux pane ID - empty string for lead, "in-process" for in-process teammates */
+    tmuxPaneId: string;
+    /** Working directory */
+    cwd: string;
+    /** Message subscriptions */
+    subscriptions: string[];
+    /** Backend execution type */
+    backendType?: 'in-process' | 'detached-process' | 'tmux';
+    /** Worktree path if the member runs in worktree isolation */
+    worktreePath?: string;
+    /** Process PID (detached-process / tmux mode) */
+    pid?: number;
+    /** Log file path (detached-process / tmux mode) */
+    logPath?: string;
+}
+/**
+ * Team configuration stored at ~/.codebuddy/teams/{team-name}/config.json
+ */
+export interface TeamConfig {
+    /** Canonical team name (also used as directory name) */
+    name: string;
+    /** Original name requested by TeamCreate when the canonical name was auto-renamed. */
+    requestedName?: string;
+    /** Team description/purpose */
+    description?: string;
+    /** Timestamp of team creation */
+    createdAt: number;
+    /** Agent ID of the team lead (format: "team-lead@{team-name}") */
+    leadAgentId: string;
+    /** Session ID of the team lead's session */
+    leadSessionId: string;
+    /** All team members including the lead */
+    members: TeamMemberInfo[];
+    /**
+     * Whether this team was auto-created for background tasks.
+     * Auto-teams are created transparently when run_in_background=true tasks
+     * are spawned, and cleaned up automatically on session end.
+     */
+    isAutoTeam?: boolean;
+}
+/**
+ * Message type for SendMessage tool
+ */
+export type TeamMessageType = 'message' | 'broadcast' | 'shutdown_request' | 'shutdown_response' | 'plan_approval_response';
+/**
+ * Single inbox message stored in ~/.codebuddy/teams/{team-name}/inboxes/{member}.json
+ *
+ * Each member's inbox is a JSON array of these messages.
+ */
+export interface InboxMessage {
+    /**
+     * Stable identity for exact acknowledgement. Legacy rows may omit this on
+     * disk; TeamMailbox derives and persists a deterministic ID when loading
+     * them.
+     */
+    id?: string;
+    /** Sender name (e.g. "team-lead", "ux-designer") */
+    from: string;
+    /** Message content text */
+    text: string;
+    /** TUI Tab input: keep this user message for the next turn when the member is busy. */
+    queueHold?: boolean;
+    /** Short summary for UI preview (5-10 words) */
+    summary?: string;
+    /** ISO 8601 timestamp string */
+    timestamp: string;
+    /** Display color of the sender */
+    color?: string;
+    /** Whether the message has been read by the recipient */
+    read: boolean;
+}
+export interface TeamManager {
+    /**
+     * Create a new team with config and directories
+     * - Creates ~/.codebuddy/teams/{teamName}/config.json
+     * - Creates ~/.codebuddy/teams/{teamName}/inboxes/
+     * - Creates ~/.codebuddy/tasks/{teamName}/
+     *
+     * @param teamName Team name (used as directory name)
+     * @param leadSession The lead agent's session
+     * @param description Optional team description
+     * @param agentType Optional lead agent type
+     * @returns The created team config
+     */
+    createTeam(teamName: string, leadSession: Session, description?: string, agentType?: string, options?: {
+        isAutoTeam?: boolean;
+    }): Promise<TeamConfig>;
+    /**
+     * Delete team and task directories
+     * Fails if active members still exist (non-lead members with active sessions)
+     */
+    deleteTeam(): Promise<void>;
+    /**
+     * Get current team config, or undefined if not in a team
+     */
+    getTeam(): TeamConfig | undefined;
+    /**
+     * Check if Agent Teams feature is enabled.
+     * Controlled by env CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS.
+     * When set to '0', all team features (TeamCreate, TeamDelete, SendMessage,
+     * background agent auto-team) are disabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if current session is in a team
+     */
+    isInTeam(): boolean;
+    /**
+     * Add a member to the team and persist config
+     */
+    addMember(member: TeamMemberInfo): Promise<void>;
+    /**
+     * Remove a member from the team by name and persist config
+     */
+    removeMember(memberName: string): Promise<void>;
+    /**
+     * Get all current team members
+     */
+    getMembers(): TeamMemberInfo[];
+    /**
+     * Find a member by name or agentId
+     */
+    getMember(nameOrId: string): TeamMemberInfo | undefined;
+    /**
+     * Update a member's info and persist config
+     */
+    updateMember(memberName: string, updates: Partial<TeamMemberInfo>): Promise<void>;
+    /**
+     * Load team config from disk for a given team name
+     * Used to restore team state after restart
+     */
+    loadTeam(teamName: string): Promise<TeamConfig | undefined>;
+    /**
+     * Persist current team config to disk
+     */
+    saveConfig(): Promise<void>;
+    /**
+     * Re-read the current team's `members` list from disk and overlay it
+     * onto the in-memory `teamConfig`. No-op when not currently in a team.
+     *
+     * Used to defeat snapshot/race conditions where one teammate's spawn has
+     * not yet completed in-memory but `config.json` may already reflect a
+     * later state (e.g. `SendMessage` resolves a recipient that was added
+     * concurrently). Failures (file missing, parse error) are swallowed
+     * silently — callers fall back to whatever the in-memory state was.
+     */
+    refreshFromDisk(): Promise<void>;
+    /**
+     * Get the team directory path: ~/.codebuddy/teams/{teamName}/
+     */
+    getTeamDir(): string | undefined;
+    /**
+     * Get the team's task directory path: ~/.codebuddy/tasks/{teamName}/
+     */
+    getTaskDir(): string | undefined;
+    /**
+     * Auto-create a lightweight team for background tasks.
+     * Creates a team named `_auto_{sessionId}` with the main agent as team-lead.
+     * Auto-teams bypass the agentTeam settings gate and are cleaned up on session end.
+     *
+     * @param sessionId The main session ID (used to generate team name)
+     * @param leadSession The main agent's session
+     * @returns The created team config
+     */
+    autoCreateTeam(sessionId: string, leadSession: Session): Promise<TeamConfig>;
+    /**
+     * Check if the current team is an auto-created team (for background tasks).
+     * Returns false if not in a team.
+     */
+    isAutoTeam(): boolean;
+    /**
+     * Cleanup all teams created by the current process during this session
+     * but never explicitly deleted via `deleteTeam()`.
+     *
+     * Mirrors Claude Code's `cleanupSessionTeams()` (gh-32730 fix): without
+     * this safety net, every `TeamCreate` invocation leaves a permanent
+     * `~/.codebuddy/teams/<name>/` directory on disk. With it, teams that
+     * outlive their usefulness (lead exits without calling TeamDelete, agent
+     * crashes mid-run, etc.) get wiped on graceful shutdown.
+     *
+     * Idempotent — safe to call multiple times. Implementations must:
+     *   - Skip teams already removed by `deleteTeam()` (those self-unregister
+     *     from the in-memory tracking set).
+     *   - Best-effort: `Promise.allSettled` style; never throw.
+     *   - Cleanup the same on-disk artifacts as `deleteTeam()` (config dir,
+     *     inboxes, task dir, member worktrees if any).
+     */
+    cleanupSessionTeams(): Promise<void>;
+}
+export interface TeamMailbox {
+    /**
+     * Send a message to a specific member's inbox
+     * Appends the message to ~/.codebuddy/teams/{teamName}/inboxes/{recipient}.json
+     */
+    send(teamName: string, recipient: string, message: Omit<InboxMessage, 'read'>): Promise<void>;
+    /**
+     * Broadcast a message to all members' inboxes (except the sender)
+     */
+    broadcast(teamName: string, sender: string, message: Omit<InboxMessage, 'read'>): Promise<string[]>;
+    /**
+     * Get all unread messages for a member
+     */
+    getUnread(teamName: string, memberName: string): Promise<InboxMessage[]>;
+    /**
+     * Get all messages for a member (read and unread)
+     */
+    getAll(teamName: string, memberName: string): Promise<InboxMessage[]>;
+    /** Mark only the named message snapshots as read. */
+    acknowledge(teamName: string, memberName: string, messageIds: readonly string[]): Promise<number>;
+    /**
+     * Serialize one exact unread delivery for this inbox. The callback must
+     * succeed before those snapshot IDs are acknowledged. Rows appended while
+     * the callback is running remain unread.
+     */
+    deliverUnreadOnce(teamName: string, memberName: string, callback: (messages: InboxMessage[]) => void | Promise<void>): Promise<boolean>;
+    /**
+     * Mark all messages as read for a member
+     */
+    markAllAsRead(teamName: string, memberName: string): Promise<void>;
+    /**
+     * Create an empty inbox file for a member
+     */
+    createInbox(teamName: string, memberName: string): Promise<void>;
+    /**
+     * Start polling for new messages for a member
+     *
+     * The callback may be sync (returns `void`) or async (returns
+     * `Promise<void>`). The poller `await`s the callback before marking
+     * exactly that unread snapshot as read, so a rejected promise (or a thrown
+     * exception) keeps the messages unread for retry on the next poll.
+     *
+     * @returns Cleanup function to stop polling
+     */
+    startPolling(teamName: string, memberName: string, callback: (messages: InboxMessage[]) => void | Promise<void>, intervalMs?: number): () => void;
+}
+/**
+ * Input for SendMessage tool - direct message
+ */
+export interface SendMessageInput {
+    type: TeamMessageType;
+    /** Recipient name (required for message, shutdown_request, plan_approval_response) */
+    recipient?: string;
+    /** Message text, reason, or feedback */
+    content?: string;
+    /** 5-10 word summary for UI preview (required for message, broadcast) */
+    summary?: string;
+    /** Request ID to respond to (required for shutdown_response, plan_approval_response) */
+    request_id?: string;
+    /** Whether to approve (required for shutdown_response, plan_approval_response) */
+    approve?: boolean;
+}
+/**
+ * Input for TeamCreate tool
+ */
+export interface TeamCreateInput {
+    /** Name for the new team */
+    team_name: string;
+    /** Team description/purpose */
+    description?: string;
+    /** Type/role of the team lead */
+    agent_type?: string;
+}
+/**
+ * Format for injecting messages into teammate sessions.
+ * Messages are wrapped in XML and injected as user-type messages:
+ *
+ * <teammate-message teammate_id="team-lead" summary="Brief summary">
+ *   message content here
+ * </teammate-message>
+ */
+export declare function formatTeammateMessage(from: string, summary: string, content: string): string;
+/**
+ * spawn 时初始任务分配的 summary 前缀。生产端（in-process-backend）与
+ * 解析端（AcpTeamBridge 串线护栏、各端 sidebar/loader 提取器）共享此常量，
+ * 避免消费侧硬编码字面量后随格式演进静默失配。
+ */
+export declare const INITIAL_ASSIGNMENT_SUMMARY_PREFIX = "Initial task assignment for ";
+export declare function formatInitialAssignmentSummary(memberName: string): string;
+/**
+ * 从文本中解析初始任务分配的归属成员名；非初始任务文本返回 undefined。
+ * 与 formatTeammateMessage + formatInitialAssignmentSummary 的输出同源，
+ * 属性尾部用 [^>]* 容忍未来新增属性（与 repo 内其它 teammate-message 提取器一致）。
+ */
+export declare function parseInitialAssignmentOwner(text: string): string | undefined;
+/**
+ * Default color palette for teammates
+ * Colors cycle for successive members
+ */
+export declare const TEAM_MEMBER_COLORS: readonly ["blue", "green", "yellow", "magenta", "cyan", "red"];
+/**
+ * Get a color for a team member based on their index (0-based, excluding lead)
+ */
+export declare function getTeamMemberColor(index: number): string;
+/**
+ * Service for cleaning up team resources, especially worktrees
+ */
+export interface TeamCleanupService {
+    /**
+     * Cleanup worktrees for all team members.
+     * Called when the team is being dissolved.
+     *
+     * @param members Array of team members to cleanup
+     * @returns Summary of cleanup results
+     */
+    cleanupTeamWorktrees(members: TeamMemberInfo[]): Promise<{
+        cleaned: string[];
+        preserved: string[];
+        failed: string[];
+    }>;
+    /**
+     * Cleanup worktree for a single team member.
+     * Called when a member is removed from the team.
+     *
+     * @param member The team member to cleanup
+     * @returns true if cleaned, false if preserved due to changes
+     */
+    cleanupMemberWorktree(member: TeamMemberInfo): Promise<boolean>;
+}
+/**
+ * Auto-dispatch service for team inbox messages.
+ *
+ * Background: when the team-lead agent is busy (`stateMachine.isBusy(session)`),
+ * teammate messages arriving via `TeamMailbox` are enqueued into the rich message queue
+ * in Mode B. Without this service, no one would trigger `RichMessageQueueManager.activate()`,
+ * so the queued messages would sit in the queue indefinitely until the user manually
+ * intervenes. UI-sourced queue items rely on the renderer to activate; team-sourced items
+ * have no UI hook, hence this CLI-internal auto-activator.
+ *
+ * Responsibility: subscribe to `SessionRunStateMachine.getChange$`, and on every transition
+ * back to `idle` (the canonical equivalent of legacy `agent_end`) detect dispatchable items
+ * in the rich queue. If any are present (and guards pass), call `activate()` and then
+ * `AgentService.run()` to send the item as a fresh independent turn.
+ *
+ * Scope: one subscription per session, managed via `register` / `unregister`.
+ */
+export interface TeamInboxDispatchService {
+    /**
+     * Begin monitoring this session for auto-dispatch. Idempotent — calling twice on
+     * the same session is a no-op.
+     */
+    register(session: Session): void;
+    /**
+     * Stop monitoring the session and release the underlying subscription.
+     * Safe to call even if the session was never registered.
+     */
+    unregister(sessionId: string): void;
+}

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

@@ -0,0 +1,209 @@
+import { type AgentJobState, type AgentJobView, type IJobStore } from './agent-view-protocol';
+import { type Workspace } from './launch-workspace';
+export interface AgentViewActionDeps {
+    store: IJobStore;
+    /** Injectable for process fakes; production always validates the real cwd. */
+    prepareWorkspace?: (state: Workspace) => Promise<string>;
+    /** 复用 DaemonProcessManager 的 detached fork 与信号能力 */
+    processManager: {
+        forkBgSession(args: string[], options: {
+            name?: string;
+            cwd?: string;
+            extraEnv?: Record<string, string>;
+            skipPrintMode?: boolean;
+            jobWorker?: boolean;
+        }): Promise<{
+            pid: number;
+            logPath: string;
+        }>;
+        sendSignal(pid: number, signal: NodeJS.Signals): boolean;
+        isProcessRunning(pid: number): boolean;
+        waitForExit(pid: number, timeoutMs?: number): Promise<boolean>;
+    };
+    /** 日志目录，shell job 的输出落在这里 */
+    logDir: string;
+    /**
+     * Optional override for tests. Default: kill(0) + process-start identity.
+     * Identity mismatch ⇒ not alive (do not signal).
+     */
+    isJobProcessAlive?(pid: number | undefined, identity: {
+        procStart?: string | null;
+        procStartFt?: string | null;
+        procStartTicks?: string | null;
+    } | undefined): Promise<boolean>;
+}
+export interface DispatchOptions {
+    prompt: string;
+    cwd: string;
+    /** 指定主 agent */
+    agent?: string;
+    /** 覆盖模型 */
+    model?: string;
+    /** 覆盖权限模式 */
+    permissionMode?: string;
+    /** 覆盖推理投入档位 */
+    effort?: string;
+    /** 用户显式命名 */
+    name?: string;
+    /** 后台首次写文件时是否自动进入隔离 worktree；缺省继续跟随 TUI/全局设置。 */
+    bgIsolation?: 'none' | 'worktree';
+    /**
+     * 注入到首条 prompt 之前的隐藏上下文（如主会话受限预览）。
+     * 只进入 spawn 的位置参数；intent/initialPrompt 保持干净 prompt，
+     * 标题与列表不受污染。
+     */
+    contextPrefix?: string;
+    /**
+     * 打开 agent view 时给的配置 flag（`--effort` / `--settings` / `--add-dir`
+     * / `--plugin-dir` / `--mcp-config` / `--strict-mcp-config` 等）。
+     * 文档要求这些 flag 既作用于视图自身也透传给它派发的每个会话。
+     */
+    extraFlags?: readonly string[];
+}
+export interface DispatchResult {
+    id: string;
+    pid: number;
+    logPath: string;
+}
+export interface DispatchLifecycle {
+    /**
+     * The durable job record now exists and can be selected by clients. Process
+     * startup intentionally happens afterwards so HTTP callers do not wait for
+     * the worker to finish booting before entering the agent view.
+     */
+    onJobCreated?: (job: {
+        id: string;
+        sessionId: string;
+    }) => void | Promise<void>;
+    /** Keep an already-visible row restartable when worker startup fails. */
+    keepJobOnStartupFailure?: boolean;
+}
+/**
+ * 派发一个新的后台会话。
+ *
+ * 顺序很关键：先生成 sessionId 并建好 job 目录，再 fork。
+ * 反过来的话子进程可能在 job 目录存在之前就开始汇报状态，
+ * 那些汇报会静默丢掉，行上就会一直停在 "starting…"。
+ */
+export declare function dispatchBackgroundSession(deps: AgentViewActionDeps, options: DispatchOptions, lifecycle?: DispatchLifecycle): Promise<DispatchResult>;
+/**
+ * 把一个历史会话作为后台 job 重新挂回列表（agent view 里的 `/resume` picker）。
+ *
+ * 靠 `--resume <sessionId>` 拉起常驻 worker：只恢复历史、不重放任何 prompt，
+ * 回来后停在 idle 等你下一句话（与 respawn 同构，但这里 job 记录是新建的
+ * —— 之前它可能已从列表删除，只剩磁盘上的 transcript）。
+ */
+export declare function resumeSessionAsJob(deps: AgentViewActionDeps, options: {
+    sessionId: string;
+    cwd: string;
+    name?: string;
+    extraFlags?: readonly string[];
+}): Promise<DispatchResult>;
+/**
+ * 还没开过 1:1 的同事：起一个空会话 job，停在 idle 等收件箱。
+ * 不把频道信封当位置参数（那会画成用户气泡）。
+ */
+export declare function spawnIdleBackgroundSession(deps: AgentViewActionDeps, options: {
+    cwd: string;
+    name?: string;
+    agent?: string;
+    /** 这个同事固定跑哪个模型 / 权限模式（建人时定，随 respawnArgs 一起持久化）。 */
+    model?: string;
+    permissionMode?: string;
+}): Promise<DispatchResult>;
+/**
+ * 派发一个 shell job（输入框 `!` 前缀）。
+ *
+ * 不调用模型，输出也不进任何会话——就是把一条命令挂在后台跑，
+ * 行上显示它最近一行输出。
+ */
+export declare function dispatchShellJob(deps: AgentViewActionDeps, options: {
+    command: string;
+    cwd: string;
+}): Promise<DispatchResult>;
+/**
+ * 读取日志尾部的若干非空行。
+ *
+ * 后台会话跑在 `-p` 模式下，模型的最终回答就是它写到日志里的内容，
+ * 所以这是"不发起额外模型请求就能拿到结果摘要"的唯一来源
+ * （对齐 Claude 的 15 秒无请求刷新路径）。
+ */
+export declare function readLogTailLines(logPath: string, maxLines?: number): Promise<string[]>;
+/** 读取日志最后一行，作为 shell job 的行内摘要 */
+export declare function readLogTailLine(logPath: string): Promise<string | undefined>;
+/** 停止会话进程并把状态标记为 stopped */
+export declare function stopJob(deps: AgentViewActionDeps, job: AgentJobView): Promise<void>;
+export interface DeleteJobResult {
+    deleted: boolean;
+    /** 未删除时的原因，会渲染成行内 `not deleted` 提示 */
+    reason?: string;
+    /** 会话已删但 worktree 目录被保留在盘上时，报出它的路径 */
+    keptWorktreePath?: string;
+}
+/** 判断 worktree 能否安全移除。返回 undefined 表示可以删 */
+export type WorktreeGuard = (job: AgentJobView) => Promise<string | undefined>;
+export interface DeleteJobOptions {
+    worktreeGuard?: WorktreeGuard;
+    /**
+     * 守卫放行后移除会话代管的 worktree（含未提交更改）。
+     * 抛错表示目录被保留 —— 会话照删，路径途经 keptWorktreePath 报出。
+     */
+    removeWorktree?: (worktreePath: string) => Promise<void>;
+}
+/**
+ * 删除会话。
+ *
+ * 会话与它的 worktree 是绑定的：守卫拒绝（未推送 commit / 他会话占用）时
+ * 会话也必须留下，否则用户就再也找不到那些提交在哪了（行上会显示
+ * `not deleted` + 原因）。守卫放行后删会话，再尽力移除代管 worktree；
+ * 移除失败（如 git 已不认识它）不回滚删除，只报出被保留的路径。
+ */
+export declare function deleteJob(deps: AgentViewActionDeps, job: AgentJobView, options?: DeleteJobOptions | WorktreeGuard): Promise<DeleteJobResult>;
+/**
+ * 重启会话，保留对话。
+ *
+ * 靠 `--resume <sessionId>` 让新进程接上原来的 transcript；
+ * respawnArgs 里的模型/权限/agent 参数原样回放，避免重启后行为漂移。
+ */
+export declare function respawnJob(deps: AgentViewActionDeps, job: AgentJobView): Promise<DispatchResult>;
+/** 去掉位置参数，只留 `--flag` 与它们的值 */
+export declare function stripPositionalArgs(args: readonly string[]): string[];
+export interface SendReplyResult {
+    /** 已写入收件箱，运行中的会话会消费 */
+    delivered: boolean;
+    /** 进程不在，已存为下次启动的首个 prompt */
+    saved: boolean;
+    /** 给用户看的提示 */
+    notice: string;
+}
+/**
+ * 把回复送给一个会话。
+ *
+ * 进程活着就进收件箱，由会话进程内的 `JobInboxConsumer` 走**逻辑消息通道**
+ * 送进对话（不是往 PTY 里模拟按键——那会在权限框、AskUserQuestion 之类的
+ * 对话框上变成误操作）。进程已退出则存成 pending，会话下次启动时补发。
+ *
+ * `!` 开头的 Bash 回复两条路都走不了：会话层没有 `!` 这个概念，
+ * 送过去只会以纯文本抵达，"执行命令"就变成了"说了句话"，属于静默错误。
+ * 所以明确拒绝，并告诉用户去哪儿才能执行。
+ */
+export declare function sendReply(deps: AgentViewActionDeps, job: AgentJobView, reply: {
+    text: string;
+    bash?: boolean;
+}): Promise<SendReplyResult>;
+export interface AttachHandoff {
+    /** 要执行的 CLI 入口 */
+    entry: string;
+    /** 传给入口的参数 */
+    args: string[];
+    /** 子进程工作目录 */
+    cwd: string;
+}
+/**
+ * 构造"接管一个会话"的启动参数。
+ *
+ * agent view 与后台会话是两个进程，接管的实现是在当前终端里用
+ * `--resume <sessionId>` 拉起完整交互会话——transcript 已经在盘上，
+ * 所以对话历史是完整的，不是只看日志。
+ */
+export declare function buildAttachHandoff(job: AgentJobState, entry: string): AttachHandoff;