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

package/cli/dist-server/types/node/agent/teammate-failure-interceptor.d.ts

@@ -0,0 +1,67 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { TeammateFailureInfo } from '../agent-team/team-member';
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../vendor/cbc-core/node/index.js';
+/**
+ * Window within which a recorded teammate failure is still surfaced to the
+ * team-lead's system prompt. Older failures are ignored so stale errors do
+ * not keep re-polluting future turns.
+ *
+ * Kept in sync with `docs/workbuddy/fix/task-status-sync/issue-5-teammate-auth-failure.md` §4.3.
+ */
+export declare const TEAMMATE_FAILURE_TTL_MS: number;
+/**
+ * Lightweight shape used by `formatTeammateFailuresBlock` — exported for
+ * unit tests that exercise the formatting logic without going through
+ * CellJS DI + TeamMemberRegistry.
+ */
+export interface TeammateFailureEntry {
+    name: string;
+    lastFailure?: TeammateFailureInfo;
+}
+/**
+ * Pure formatter: given a list of team members (each carrying an optional
+ * `lastFailure`) and a `now` timestamp, return the markdown body of the
+ * `<teammate-failures>` block, or undefined when there is nothing to report.
+ *
+ * Filters by TTL so stale failures older than {@link TEAMMATE_FAILURE_TTL_MS}
+ * are dropped.
+ *
+ * This function is the single source of truth for the block's contents so
+ * behavior can be verified by unit tests independent of CellJS.
+ */
+export declare function formatTeammateFailuresBlock(members: ReadonlyArray<TeammateFailureEntry>, now?: number): string | undefined;
+/**
+ * Issue 5 · `TeammateFailureInterceptor`
+ *
+ * When the team-lead starts a new turn, inspect the TeamMemberRegistry for
+ * any teammates whose most recent AgentTask failed (non-silentAbort). For
+ * each such teammate within the TTL window, emit a `<teammate-failures>`
+ * `<system-reminder>` block so the main agent knows NOT to fabricate a
+ * success report and instead surfaces the failure to the user.
+ *
+ * Non-teammate / non-team-lead sessions are left untouched — `intercept`
+ * returns early.
+ *
+ * Design notes:
+ * - Runs at priority 1160 (between TeamContext=1175 and MemoryContext=1150)
+ *   so the failure notice follows the team-lead instructions but precedes
+ *   memory recall, reflecting its higher importance.
+ * - Reads failures from `TeamMember.lastFailure` which is populated by
+ *   `AgentTask.execute()`'s failed branch (see agent-task.ts
+ *   `recordTeammateFailure`). Error strings are already sanitized at write
+ *   time (credentials / URL query stripped, <=500 chars).
+ * - Deduplicates within a prompt by checking for `TEAMMATE_FAILURES_MARKER`
+ *   in the last user message — mirrors the pattern used by
+ *   `TeamContextInterceptor.shouldInjectTeamPrompt`.
+ */
+export declare class TeammateFailureInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * Check whether the input already contains a `<teammate-failures>` block
+     * from a prior interceptor pass (e.g. resumed prompt). Deduplication
+     * mirrors `TeamContextInterceptor.shouldInjectTeamPrompt`.
+     */
+    private hasExistingFailureMarker;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * 频道附件：对齐上游 SendMessage 的 type:attachment（file:// 路径 → 房间可见的文件）。
+ *
+ * 设计取舍：
+ * - **落盘复制而不是引用原路径**：成员的工作目录会被后续 turn 覆盖/清理，
+ *   只存路径的话过几轮就 404；复制一份才谈得上"房间里的东西一直在"。
+ * - **有类型与体积上限**：频道是给人看的，不是对象存储。超限/不认识的类型
+ *   直接拒绝（由调用方转告模型），避免把 GB 级二进制塞进 agent-home 目录。
+ * - **存内容寻址的文件名**：<sha256 前 16 位><ext>，天然去重、也不怕名字里有
+ *   斜杠/换行/中文导致路径穿越或展示问题；展示名另存在消息里。
+ */
+import { CHANNEL_ATTACHMENT_MAX_BYTES, CHANNEL_ATTACHMENT_MAX_PER_MESSAGE } from './agent-home-limits';
+/** 上限的唯一来源在 agent-home-limits（web-ui 也直接消费），这里只是 re-export 兼容既有调用方。 */
+export { CHANNEL_ATTACHMENT_MAX_BYTES, CHANNEL_ATTACHMENT_MAX_PER_MESSAGE };
+export interface ChannelAttachment {
+    /** 展示名（原文件名）。 */
+    name: string;
+    /** 存储文件名（内容寻址，直接拼在频道附件目录下）。 */
+    file: string;
+    mime: string;
+    size: number;
+}
+/** 频道附件目录：<homeDir>/agent-home/attachments/<channelId>/。 */
+export declare function channelAttachmentsDir(homeDir: string, channelId: string): string;
+export declare function channelAttachmentMime(name: string): string;
+/**
+ * 展示名净化（落盘文件名不用它，只进消息与扩展名推导）：
+ * 取 basename（路径分隔符一律当分隔符，含 Windows 反斜杠）、去控制字符、截 200。
+ * HTTP 上传的名字是**外部输入**，所以这条必须在入口处做，不能只靠"调用方给的是路径"。
+ */
+export declare function channelAttachmentDisplayName(raw: string | undefined): string;
+/**
+ * 存储文件名白名单：`<sha256 前 16 位>[.扩展名]`。
+ * POST /messages 会收到客户端回传的 `file`（上传时服务端给的哈希名），
+ * 必须按这条白名单收窄，不能靠"里面没有斜杠"隐式成立。
+ */
+export declare function normalizeChannelAttachmentFile(raw: unknown): string | undefined;
+/**
+ * 按字节收进频道附件目录（浏览器上传与本地路径两条入口共用的一套规则）。
+ * 失败返回原因字符串（给调用方看的人话），成功返回落盘信息。
+ */
+export declare function storeChannelAttachmentBytes(input: {
+    homeDir: string;
+    channelId: string;
+    bytes: Buffer;
+    /** 展示名（原文件名）；缺省回落 "attachment"。 */
+    name?: string;
+}): Promise<{
+    ok: true;
+    attachment: ChannelAttachment;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * 把一个本地文件收进频道附件目录。
+ * 失败返回原因字符串（给模型看的人话），成功返回落盘信息。
+ */
+export declare function ingestChannelAttachment(input: {
+    homeDir: string;
+    channelId: string;
+    sourcePath: string;
+    /** 展示名；缺省用原文件名。 */
+    name?: string;
+}): Promise<{
+    ok: true;
+    attachment: ChannelAttachment;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * 解析一个可对外读取的附件（HTTP 路由 / 发消息校验用）：路径 + 真实大小。
+ * 任何越界/未知文件一律 undefined —— 和 attachments-service 一样的包含性纪律。
+ */
+export declare function resolveChannelAttachment(input: {
+    homeDir: string;
+    channelId: string;
+    file: string;
+}): Promise<{
+    path: string;
+    size: number;
+} | undefined>;

package/cli/dist-server/types/node/agent-home/agent-home-channel-system-event.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 频道系统事件行（如轮次收场）：结构化本体，UI 按当前语言渲染。
+ *
+ * 零 import：目录记录（agent-home-directory）与 web-ui 都会引用它，
+ * 而这两条链路都受 agent-home-web-ui-shared-imports.spec.ts 约束（不许牵出 node 侧重模块）。
+ */
+/** 频道系统事件本体（落盘进 jsonl 的 `systemEvent`，界面按当前语言渲染）。 */
+export interface AgentHomeChannelSystemEvent {
+    type: 'room-turn-ended';
+    reason: 'timeout' | 'gone' | 'silent' | 'relay-exhausted';
+    /** 相关人名（"轮到谁没见回应" / "叫了谁都没接住"）。 */
+    names?: string[];
+}
+/** 落盘时的兜底文案（UI 有 systemEvent 就按当前语言重渲染，text 只是旧记录/导出用）。 */
+export declare function agentHomeChannelSystemEventText(event: AgentHomeChannelSystemEvent): string;

package/cli/dist-server/types/node/agent-home/agent-home-channel-task-event.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 任务板**事件本体**与它改动的字段集合：node 域、落盘记录、文案层与 web-ui 共用这一份。
+ *
+ * 零 import：目录记录（agent-home-directory）与 web-ui 都会引用它，
+ * 而这两条链路都受 agent-home-web-ui-shared-imports.spec.ts 约束（不许牵出 node 侧重模块）。
+ */
+/** `updated` 事件改了哪几项（与 i18n 的 field.* 一一对应）。 */
+export type AgentHomeChannelTaskChange = 'subject' | 'detail' | 'assignee' | 'refs' | 'owner';
+export declare function isAgentHomeChannelTaskChange(value: unknown): value is AgentHomeChannelTaskChange;
+/**
+ * 结构化事件（落盘进频道 jsonl 的 `taskPayload`，界面按当前语言渲染）。
+ * 单任务事件带 `subject`，批量事件带 `taskIds` / `subjects`。
+ */
+export interface AgentHomeChannelTaskEventPayload {
+    type: string;
+    taskId?: string;
+    taskIds?: string[];
+    subject?: string;
+    subjects?: string[];
+    ownerId?: string;
+    assigneeId?: string;
+    actorId?: string;
+    changes?: readonly AgentHomeChannelTaskChange[];
+}

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

@@ -0,0 +1,115 @@
+/** 落盘后叫醒频道成员。用户发言全员；同事发言只叫 @。 */
+import type { IDaemonProcessManager } from '../../workspace/cbc-daemon/lib/node/index.js';
+import type { IJobStore } from '../agent-view/agent-view-protocol';
+import { type AgentHomeChannel, type AgentHomeChannelMessage, type AgentHomeDirectoryFile } from './agent-home-directory';
+/** 唤醒被跳过时给审计的原因（写进 audit.jsonl 的 wake_skipped）。 */
+export type ChannelWakeSkipReason = 'no-job' | 'error' | 'user-stopped' | 'dead' | 'flood' | 'deferred';
+/** 落盘成功后的叫醒出口：HTTP 回车和 SpeakInChannel 共用。 */
+export declare function wakeAfterChannelSpeech(input: {
+    directory: AgentHomeDirectoryFile;
+    channel: AgentHomeChannel;
+    message: AgentHomeChannelMessage;
+    /** speech 侧的结果：这次发言有没有推进轮次。false = 别叫人（待发言的人早就叫过了）。 */
+    advancedTurn?: boolean;
+    homeDir: string;
+    store: IJobStore;
+    processManager?: IDaemonProcessManager;
+    canRespawn?: boolean;
+    reloadDirectory?: () => Promise<AgentHomeDirectoryFile | undefined>;
+    onSkip?: (agentId: string, reason: ChannelWakeSkipReason) => void;
+    onDelivered?: (agentId: string) => void;
+    log?: (message: string) => void;
+}): Promise<void>;
+export declare function wakeChannelMembers(input: {
+    directory: AgentHomeDirectoryFile;
+    channel: AgentHomeChannel;
+    text: string;
+    /** 说话人：user 或成员 agentId。 */
+    from?: string;
+    mentionNames?: string[];
+    messageId?: string;
+    /** 这条发言带的附件：信封会带绝对路径（只给名字同事读不到，会去磁盘翻同名旧图）。 */
+    attachments?: readonly {
+        name: string;
+        file: string;
+    }[];
+    /** 轮转标记（如 "3/10"）：这封是轮到你发言，不是被 @。 */
+    round?: string;
+    homeDir: string;
+    store: IJobStore;
+    processManager?: IDaemonProcessManager;
+    /** 拉起接缝：默认走 respawnColleagueJob + processManager；单测注入假实现。 */
+    respawn?: (jobId: string, options?: {
+        resumeStopped?: boolean;
+    }) => Promise<boolean>;
+    /** 默认 true。job worker 里应 false，只写信 + wake 票，避免双 fork。 */
+    canRespawn?: boolean;
+    /**
+     * 对方进程已死时**干脆不投**。默认 false：正常频道轮转与显式 @ 必须把信写入
+     * inbox 并留 wake ticket，让中央 broker 拉起被空闲回收的成员。仅用于调用方明确
+     * 只做在线 best-effort 通知的场景；不要按 `from === 'agent'` 自动开启，否则全员轮转
+     * 会在第一位之后静默断链。
+     */
+    skipIfDead?: boolean;
+    /** 没开过 1:1 时按招人同一条路起 job，写上 primaryJobId。不要把 channel.id 写进 jobAssignments。 */
+    ensureJob?: (agentId: string) => Promise<string | undefined>;
+    onSkip?: (agentId: string, reason: ChannelWakeSkipReason) => void;
+    /** 投递成功回调：信已经进对方的 job 收件箱。 */
+    onDelivered?: (agentId: string) => void;
+    /** 说话人自己不要再吃一封自己的入站。 */
+    excludeAgentId?: string;
+    /**
+     * 只叫醒这些成员（仍会去掉 exclude）。
+     * 不传 = 全员。传 [] = 谁也不叫（同事没 @ 任何人）。
+     */
+    onlyAgentIds?: readonly string[];
+    /**
+     * 这条消息里**用户真正 @ 到的人**（与 onlyAgentIds 不是一回事：用户发言开一轮时
+     * 只叫指针第一位，但那位不一定是被 @ 的）。
+     * 只用来判"要不要把被用户终止过的同事重新拉起"。不传 = 退回 onlyAgentIds（工具侧
+     * 的定向叫醒本来就只有这一份名单）。
+     */
+    mentionedAgentIds?: readonly string[];
+    /** 每人投递前再读一次目录，避免解锁后 primary 被改派。 */
+    reloadDirectory?: () => Promise<AgentHomeDirectoryFile | undefined>;
+    /**
+     * 这是不是**自动链**（成员发言触发的那一棒）：是则过互叫护栏（同轮去重 + 窗口限速）。
+     * 用户发言 / @ 点名 / 派单不传，不受限。
+     */
+    autoWake?: boolean;
+}): Promise<ChannelWakeOutcome>;
+/**
+ * 一次叫醒的结果（调用方据此决定"这一棒要不要当场交给下一位"）。
+ *
+ * - `delivered`：信真的进了对方 job 收件箱且人活着（或被拉起来了）。
+ * - `unreachable`：**这次没送到、而且不会再送到**（dead / no-job / user-stopped）——
+ *   轮次接力看到自己那一棒落在这里，就必须当场推进指针，不能等看门狗
+ *   （看门狗只在 `--serve` 表面进程里跑；TUI / 页面关掉时根本没人兜底）。
+ * - `deferred` 不进 unreachable：信已入收件箱 + 留了唤醒票，人起来自己会读，
+ *   推进指针反而会让他醒来发现"不是我的棒"。
+ */
+export interface ChannelWakeOutcome {
+    delivered: string[];
+    unreachable: string[];
+}
+/** 叫醒计划：叫谁（已按叫醒池过滤）+ 这封要不要带轮次标记。 */
+export interface ChannelWakePlan {
+    targets: string[];
+    /** 轮次标记（如 "1/3 · 2/10"）。没有进行中的轮次、或这次发言没推进轮次时不带。 */
+    round?: string;
+}
+/**
+ * 叫醒判定 —— **唯一一份**。HTTP 回执（要回 wokeAgentIds）与投递
+ * （wakeAfterChannelSpeech）都调它；两边输入相同，结论就相同，不存在"两处要保持一致"。
+ */
+export declare function planChannelWake(input: {
+    directory: AgentHomeDirectoryFile;
+    channel: AgentHomeChannel;
+    /** 说话人：'user' 或成员 agentId。 */
+    from?: string;
+    mentionAgentIds?: readonly string[];
+    /** speech 侧结果：这次发言有没有推进/开启轮次。false = 待发言的人早叫过了，别重复叫。 */
+    advancedTurn?: boolean;
+    /** 说话人自己不吃自己的入站。 */
+    excludeAgentId?: string;
+}): ChannelWakePlan;

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

@@ -0,0 +1,45 @@
+/**
+ * 频道选项卡卡片（对齐上游 SendMessage 的 type:widget）。
+ *
+ * 上游语义（照搬结论，注释记理由）：
+ * - 卡片 = 一个提问 + 2–6 个可选项，用户点一个，选项的 value 作为**用户回复**
+ *   回到房间，成员下一轮就能看到"用户选了 X"；
+ * - **发卡片即结束本轮发言**：模型发完就该停手等用户回答，而不是继续自说自话；
+ * - 选项必须是真实可选项，不能现编占位；能用查证解决的别问卡片
+ *   （上游把"少问"写进工具描述：默认自己决定并推进）。
+ *
+ * 我们这里的映射：卡片是一条频道消息（kind='widget'），用户点击后走普通的
+ * 用户发言（带 replyTo 指向卡片），因此"是否已答"完全可以从既有消息流推导，
+ * 不需要改写历史 —— transcript 仍是 append-only。
+ */
+/** 选项上限对齐上游 widget 的 1–6（我们要求至少 2：一个选项不算选择题）。 */
+export declare const CHANNEL_WIDGET_MIN_OPTIONS = 2;
+export declare const CHANNEL_WIDGET_MAX_OPTIONS = 6;
+/** 卡片标题与选项文本的长度上限（防止把整段话塞进卡片）。 */
+export declare const CHANNEL_WIDGET_PROMPT_MAX = 500;
+export declare const CHANNEL_WIDGET_LABEL_MAX = 120;
+export type AgentHomeChannelWidgetStyle = 'default' | 'primary' | 'danger';
+export interface AgentHomeChannelWidgetOption {
+    /** 选项按钮上的文字。 */
+    label: string;
+    /** 用户选中后回传给模型的文本；缺省 = label。 */
+    value?: string;
+    style?: AgentHomeChannelWidgetStyle;
+}
+export interface AgentHomeChannelWidget {
+    prompt: string;
+    helpText?: string;
+    options: AgentHomeChannelWidgetOption[];
+}
+export type NormalizeChannelWidgetResult = {
+    ok: true;
+    widget: AgentHomeChannelWidget;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 校验并归一化模型给的卡片。失败返回人话原因（工具结果会原样转告模型，
+ * 让它改成合法的卡片或改用普通发言）。
+ */
+export declare function normalizeChannelWidget(raw: unknown): NormalizeChannelWidgetResult;

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

@@ -0,0 +1,304 @@
+/**
+ * 落盘：`~/.codebuddy/agent-home/directory.json`。
+ * 写必须进 `withAgentHomeDirectoryLock`。
+ * Channel ≠ Room ≠ 1:1。组队禁令只在 UI 拦，读盘不按引擎 / 默认踢人。
+ *
+ * ⚠️ 本模块（连同 agent-home-limits / membership / mentions / envelope-body）会被 web-ui
+ * 直接 import。**别在这里引 node 侧的重模块**（../cli、../session、../tools，以及会牵出
+ * 它们的 agent-home-errors / agent-home-channel-tasks…）：type-only 也会把整个 node 端
+ * 拉进前端 typecheck，前端构建会炸出几千条无关的装饰器错误。
+ */
+import type { ChannelAttachment } from './agent-home-attachments';
+import type { AgentHomeChannelSystemEvent } from './agent-home-channel-system-event';
+import type { AgentHomeChannelTaskEventPayload } from './agent-home-channel-task-event';
+import type { AgentHomeChannelWidget } from './agent-home-channel-widget';
+import { type ResolveMeAsAgentOptions } from './agent-home-room-contacts';
+export { CHANNEL_MAX_MEMBERS, GROUP_MIN_MEMBERS } from './agent-home-limits';
+export { agentHomeTeamJoinBlock, blockedTeamAgentIds, canJoinAgentHomeChannel, canJoinAgentHomeRoom, canJoinAgentHomeTeam, type AgentHomeTeamJoinBlock, type RoomMessageCallStyle, roomMessageCallStyle, } from './agent-home-membership';
+export { flattenRoomContacts, resolveRoomContacts, type ResolveMeAsAgentOptions, type RoomContact, type RoomContactScope, } from './agent-home-room-contacts';
+export interface AgentHomeProfile {
+    id: string;
+    name: string;
+    /** 几何头像变体；0 专供默认 Agent，普通同事使用 1..15。 */
+    avatarVariant?: number;
+    /** 一行职务（侧栏次行可用） */
+    title?: string;
+    /** 人设 / 系统提示补充 */
+    description?: string;
+    /** 引擎：cli | ptc | minimal | create | 自定义 agent 名；缺省=产品默认 */
+    engine?: string;
+    /**
+     * 这个同事固定跑哪个模型 / 权限模式（建人时定，启 job 时拼进 --model / --permission-mode）。
+     * 缺省 = 跟随产品默认（和用户新开一个 Run 的默认一致）。
+     */
+    model?: string;
+    permissionMode?: string;
+    /** 家目录：新 Run 的默认 cwd */
+    homeCwd: string;
+    /**
+     * 这个人的主对话（第一句 createJob 的那条）。缺省=还没说过话。
+     * 点行只打开这一条，不抢桶里最新 Run。
+     */
+    primaryJobId?: string;
+    visibility: 'visible' | 'hidden';
+    /** 侧栏分组。缺省 = 未分组。私信房簇不进分组。 */
+    sectionId?: string;
+    createdAt: number;
+    lastActiveAt?: number;
+    /** 被频道 @ 了：侧栏人行黄点。点开人或点开频道再清。 */
+    unreadByUser?: number;
+    /** 谁建的（自治组的队）。缺省 = user（含历史数据）。 */
+    createdBy?: 'user' | 'agent';
+    /** 建人者 agentId（createdBy=agent 时）。 */
+    createdByAgentId?: string;
+    /** 自治创建的深度：默认 Agent 建的人=0，其再建 +1；上限见 agent-home-limits。 */
+    depth?: number;
+}
+/**
+ * 房间：把已有同事编成一组。只是分组 / ACL，不是第三个说话的人，
+ * 也不是 Agent Teams（那套是 `name@team` + `~/.codebuddy/teams/`）。
+ * 成员各自的对话和 homeCwd 不变。
+ */
+export interface AgentHomeGroup {
+    id: string;
+    name: string;
+    /** 2–6 人，去重；顺序 = 叠头像 / 成员条顺序。全目录只能有一间房。 */
+    memberAgentIds: string[];
+    /** 建房时定，加人/移出都不改（免得 Files 乱跳） */
+    homeCwd: string;
+    visibility: 'visible' | 'hidden';
+    pinned?: boolean;
+    /** 未置顶时的顺序，默认 createdAt */
+    sortIndex: number;
+    createdAt: number;
+    lastActiveAt?: number;
+    unreadByUser?: number;
+    lastPreview?: string;
+    /** 组队中（Agent Teams 的队名）：禁止改成员 / 解散 */
+    activeTeamName?: string;
+}
+/**
+ * 频道：通讯录里和人对等的一条群对话。
+ * 不是私信房（groups）：房间没有自己的会话；频道有自己的 transcript。
+ * 主键是 `id`（UUID），可以多间；禁止把 channel.id 写进 jobAssignments。
+ * `transcriptId` 必须等于 `id`，jsonl 路径 `channels/<id>.jsonl`。
+ */
+export interface AgentHomeChannel {
+    id: string;
+    name: string;
+    /** 2–6 人，都在 agents[]。用户发言可全员叫醒；成员发言只叫 @。默认 Agent 不叫。 */
+    memberAgentIds: string[];
+    /** 频道自己的会话 id，不是 jobId */
+    transcriptId: string;
+    /** 有人提文件时才用；默认第一个成员的家。不改成员档案。 */
+    homeCwd: string;
+    visibility: 'visible' | 'hidden';
+    pinned?: boolean;
+    sectionId?: string;
+    sortIndex: number;
+    unreadByUser?: number;
+    lastPreview?: string;
+    lastActiveAt?: number;
+    createdAt: number;
+    /**
+     * 频道 lead：看板快照只推给 lead，dispatch / escalate 也只有 lead 能调。
+     * 缺省 = user-as-lead（用户自己编排）。被移出成员时 sanitize 会清掉，自动降级。
+     */
+    leadAgentId?: string;
+    /** 谁建的频道。缺省 = user（含历史数据）。 */
+    createdBy?: 'user' | 'agent';
+    createdByAgentId?: string;
+    /**
+     * 进行中的房间轮次（对齐上游群聊：一次 room turn 最多 3 轮 / 10 条发言）。
+     * 不存在 = 当前没有轮次；由 channel-room-turn.ts 的状态机推进。
+     */
+    roomTurn?: AgentHomeChannelRoomTurn;
+    /**
+     * 跨人共享房间的 id（占位，对齐上游 SandGroupConfig.sharedRoomId）：
+     * 本机频道将来挂到共享房间上时填这里，现在不参与判定。
+     */
+    sharedRoomId?: string;
+    /** 共享房间的主机（占位，对齐上游 SandRemoteRoomConfig.hostAuthId/hostName）。 */
+    host?: {
+        authId: string;
+        name: string;
+    };
+}
+/** 房间轮次状态；字段语义见 agent-home-channel-room-turn.ts。 */
+export interface AgentHomeChannelRoomTurn {
+    startedAt: number;
+    round: number;
+    messages: number;
+    responderIds: string[];
+    order: string[];
+    cursor: number;
+    /** 当前这一棒是什么时候交出去的（看门狗按它算"刚叫醒"保护，而不是按轮起点）。 */
+    cursorSetAt?: number;
+    spokenThisRound: number;
+    /** 每人本轮已计条数（上限 ROOM_MAX_MESSAGES_PER_TURN）。 */
+    spokenByAgent?: Record<string, number>;
+    /**
+     * 这一棒已经催过几次（对齐上游 ack 语义：收到消息不回应算欠一条回信）。
+     * 到上限就不再催，避免无限烧钱。
+     */
+    nudges?: number;
+    /**
+     * 上一次催办的时间。与 cursorSetAt（交棒时刻）分开：催办要按"上次催了多久"
+     * 算间隔，交棒时刻还要给"进程死了多少秒才跳过"的保护窗用——催办刷新交棒时刻
+     * 会把死人的保护窗一起拉长（实测会让看门狗误判）。
+     */
+    lastNudgeAt?: number;
+}
+/** 频道 jsonl 一行。不进 JobStore，也不进对方 1:1。 */
+export interface AgentHomeChannelMessage {
+    id: string;
+    at: number;
+    from: 'user' | 'agent' | 'system';
+    agentId?: string;
+    text: string;
+    mentionAgentIds?: string[];
+    /**
+     * 任务板事件行（kind='task'）：text 是给人看的一行事件描述，
+     * taskPayload 是结构化本体（UI 按当前语言渲染）；taskEvent/taskId 只是
+     * 透传给前端的事件类型/任务 id 冗余字段（渲染只用 taskPayload）。
+     */
+    kind?: 'task' | 'widget' | 'system';
+    /**
+     * 系统事件行（kind='system'）：text 是给人看的一行兜底描述，
+     * systemEvent 是结构化本体（UI 按当前语言渲染）。
+     */
+    systemEvent?: AgentHomeChannelSystemEvent;
+    taskEvent?: string;
+    taskId?: string;
+    /**
+     * 结构化事件本体。UI 用它**按当前语言**渲染这一行（text 只是当时写下的那份，
+     * 英文界面不该看到中文系统行）；缺它（老记录）时回落 text。
+     */
+    taskPayload?: AgentHomeChannelTaskEventPayload;
+    /**
+     * 弃权标记（"(pass)"）。对齐上游：pass 不写进 transcript、不计入轮次条数，
+     * 只用于推进轮转 —— 所以它只存在于内存里的这条消息上，不落盘。
+     */
+    pass?: boolean;
+    /**
+     * 选项卡卡片（对齐上游 SendMessage 的 type:widget）：
+     * 用户点选后以普通用户发言回到房间（带 replyTo 指向本条），
+     * 因此"是否已答/答了什么"直接从消息流推导，不改写历史。
+     */
+    widget?: AgentHomeChannelWidget;
+    /**
+     * 附件（对齐上游 SendMessage 的 type:attachment）：
+     * 落盘时已复制进频道附件目录，file 是内容寻址的存储名。
+     */
+    attachments?: ChannelAttachment[];
+    /**
+     * 引用的消息 id（对齐上游 SendMessage 的 reply_to）。
+     * 房间历史里的每条消息都带一个短地址（#xxxxxxxx），成员用地址引用；
+     * 落盘存解析后的完整 id，UI 据此在气泡上方画一条引用。
+     */
+    replyTo?: string;
+}
+/** 侧栏分段。缺省 = 未分组。私信房簇不进分组。 */
+/**
+ * 外部成员（占位，对齐上游 RemoteRoomMember）：将来跨人/跨机协作时，
+ * 房间里可能出现"别人的 agent"或"另一个人"。现在**只留字段位**，
+ * 读盘原样透传，不参与任何权限/唤醒判定。
+ */
+export interface AgentHomeRemoteMember {
+    kind: 'agent' | 'human';
+    /** 对方的稳定身份（上游 authId）：同一个人的多个 agent 共享它。 */
+    authId: string;
+    /** kind=agent 时是对方的 agentId；human 时空。 */
+    agentId?: string;
+    displayName: string;
+    avatarUrl?: string;
+}
+export interface AgentHomeSection {
+    id: string;
+    name: string;
+    sortIndex: number;
+}
+export interface AgentHomeDirectoryFile {
+    version: 1;
+    defaultAgentId: string;
+    agents: AgentHomeProfile[];
+    /** jobId → 同事 agentId。没有映射的 job 未认领；默认 Agent 不进 jobs/。 */
+    jobAssignments: Record<string, string>;
+    /**
+     * sessionId → 同事 agentId：会话级身份登记。
+     *
+     * jobId 是进程级一次性信号（`claimJobIdentity` 读完即从 env 摘除），job 内派生的会话、
+     * 以及「新建智能体」首轮尚未写入 jobAssignments 的窗口里都拿不到它 —— 那时同事解析不出
+     * 自己是谁，频道工具会整体消失。本表是持久归属，按会话 id 兜住这些形态。
+     * 旧文件没有该字段，读成 {}，version 不升。
+     */
+    sessionAssignments?: Record<string, string>;
+    /** 房间。旧文件没有这个字段，读成 []，version 不升。 */
+    groups: AgentHomeGroup[];
+    /** 频道。旧文件没有这个字段，读成 []，version 不升。 */
+    channels?: AgentHomeChannel[];
+    /** 侧栏分组。旧文件没有这个字段，读成 []。 */
+    sections?: AgentHomeSection[];
+    /**
+     * 外部成员（占位，对齐上游 remote-room.json 的 members）：跨人协作的未来入口。
+     * 读盘清洗只做格式校验；不参与成员资格 / 唤醒 / 权限。
+     */
+    externalMembers?: AgentHomeRemoteMember[];
+}
+export declare function agentHomeDirectoryPath(homeDir: string): string;
+export { mentionAgentIdsFromText } from './agent-home-mentions';
+export declare function bumpUnread(target: {
+    unreadByUser?: number;
+}): void;
+/**
+ * 把默认 Agent 的家目录投影为宿主进程的当前启动目录（`--serve` cwd）。
+ *
+ * 档案只在首次 bootstrap 时记过一次 homeCwd，之后换目录启动不会更新 —— 主对话的
+ * 工作区（顶栏副标题 / 输入框目录 chip / 空状态 / 侧栏 chip）会一直显示历史目录。
+ * **只投影读快照、不落盘**：同一个 HOME 可能并存多个宿主（TUI + 多个 serve），落盘
+ * 会让默认 Agent 的家目录在它们之间来回改写。job 进程别传 hostCwd（同事 Run 的 cwd
+ * 是同事家目录）。值没变时保留原对象引用 —— 目录 15s 轮询一次，引用一换 memo 链就断。
+ */
+export declare function projectDefaultAgentHostCwd<T extends {
+    id: string;
+    homeCwd: string;
+}>(agents: T[], defaultAgentId: string | null | undefined, hostCwd: string | undefined): T[];
+/** 原子写 directory.json。调用方必须已经持有 withAgentHomeDirectoryLock。 */
+export declare function writeAgentHomeDirectoryFile(homeDir: string, directory: AgentHomeDirectoryFile): Promise<void>;
+/**
+ * 只读加载。文件不存在 / 损坏 / 版本对不上都返回 undefined——
+ * 读方一律降级成「没有房间」，绝不代替控制器 bootstrap 或写盘。
+ */
+export declare function readAgentHomeDirectory(homeDir: string): Promise<AgentHomeDirectoryFile | undefined>;
+/**
+ * 同步版：给必须同步作答的调用点用（工具的 isEnabled）。
+ * 目录是几 KB 的本地 JSON，且写方用的是原子 rename，读到的永远是完整文件。
+ */
+export declare function readAgentHomeDirectorySync(homeDir: string): AgentHomeDirectoryFile | undefined;
+/**
+ * 叫醒落点：只认仍归这个人的 primaryJobId。
+ * primary 被改派走：如果只剩一条 assignment 就用那条；多条不猜 Object.entries 顺序。
+ * 未映射的 primary 归默认 Agent 名下，不能当这个人的投递点。
+ */
+export declare function resolveMemberJobId(directory: AgentHomeDirectoryFile, agentId: string): string | undefined;
+export declare function ownedJobIds(directory: AgentHomeDirectoryFile, agentId: string): string[];
+/**
+ * 幽灵 job 对账用的清理：把这条 job 的映射整个忘掉（认领关系 + 任何指向它的 primary）。
+ * 返回有没有真的改到。纯函数，调用方负责在目录锁内落盘。
+ *
+ * 为什么需要：用户删掉某个 Run 之后，directory 里的 primaryJobId/jobAssignments 仍指向它；
+ * 于是「招人」判定命中 existing 不再重建，投递只会把信写进一个复活出来的空壳目录。成员就此永久哑掉。
+ */
+export declare function forgetJobId(directory: AgentHomeDirectoryFile, jobId: string): boolean;
+/** 我能说话的可见频道。不是房间 ACL。
+ * 主 Agent 不在成员表里（它是委托侧的工作现场），但说出来的话就是用户的话，
+ * 所以它对每个可见频道都能发言；同事仍然只认自己名下的频道。
+ */
+export declare function channelsForSelf(directory: AgentHomeDirectoryFile | undefined, jobId?: string, sessionId?: string): AgentHomeChannel[];
+/**
+ * 当前说话人。没有 job id = 主会话默认 Agent（用户 1:1，不是同事）。
+ * job worker 必须对上 primaryJobId / jobAssignments；认不出时看 options（见
+ * ResolveMeAsAgentOptions）：可见性路径回落默认 Agent，动作路径传
+ * `{ fallbackToDefault: false }` 拿 undefined 并据此拒绝。
+ */
+export declare function resolveAgentHomeSelf(directory: AgentHomeDirectoryFile | undefined, jobId?: string, sessionId?: string, options?: ResolveMeAsAgentOptions): AgentHomeProfile | undefined;