@wowyuarm/dsh-agent-team 0.1.8 → 0.1.10

package/packages/tool-agent-team/README.zh.md

@@ -6,15 +6,20 @@
 
 ## 工具
 
-- `team_inbox` 列出调用方 Member 的有界未读 Thread 摘要，先按 direct work、再按最近活动排序；只有 Thread 存在真实 Task overlay 时才出现 Task status/number。
-- `team_thread` 读取 Thread、分页历史、follow 或 unfollow。`threadRef` 是主身份；`taskRef` 只对 released task-only Client 是 Host alias。`read` 原子返回 Thread anchor、可选的当前 Task 与 Claim 快照、有界背景和一批连续未读事实，并推进持久 watermark；`history` 不改变 read 状态。
-- `team_message` 创建顶层 Thread，或回复已有 Thread。它默认创建 taskless Thread；传入 `asTask: true` 才原子创建 Task。Reply 必须携带准确的 `baseRevision`，并在检查 revision 前先处理未读门禁。
-- `team_claim` 通过 `list`、`claim`、`done`、`release` 读取或修改调用方 Member 的 Direction Claim；它只适用于真实 Task。Direction 互斥键执行 Unicode NFKC normalization、trim、空白压缩和确定性大小写折叠。
-- `team_view` 发现有界、按 membership 授权的 Channel、真实 Task 和 Member 摘要，不返回 Thread Message 或 Activity。
+- `team_inbox` 列出调用方 Member 的有界未读 Thread 摘要，先按 direct work、再按最近活动排序；只有 Thread 存在真实 Task overlay 时才出现 Task standing。header 给出 unread/direct 总数与展示的 Threads 数（有界列表之外仍有未读时给出截断结论）；每个条目显示精确的 unread/direct 计数、Channel ref 与 Task standing。页脚把阅读指向 `team_thread read`；渲染不携带 revision 与写令牌。
+- `team_thread` 读取 Thread、分页历史、follow 或 unfollow。`threadRef` 是主身份；`taskRef` 只对 released task-only Client 是 Host alias。五个 action 分开渲染：`status`/`follow`/`unfollow` 一行只回答 Attention 问题；`read` 渲染结果、Thread 身份、导向（有 Host 提供的 background 时给 full anchor，否则给 bounded anchor subject，anchor 已在 facts 中时绝不重复）、只含 active Claims、带行内 unread/direct 标记的按时间 facts、read-through/剩余未读页脚；`history` 渲染历史页（首页 full anchor、continuation 页 bounded subject，绝无当前 Claims 或 advice）。`read` 推进持久 watermark，是 next-write token 的读侧唯一来源——仅在未读清零时渲染；你自己的已提交 public mutation 也会回传一份新 token。Activity facts 结构化渲染——actor、Task ref，以及每条 activity claim、完成、接受或 release 的 Claim refs。确认仍为 done 状态 Task 的未读验收的那次 read 附带一段 `contextAdvice`（用量、路由预算、`min(128_000, handoffAt)` 任务边界阈值、keep/rollover/handoff-now 唯一动作）；它只是建议，测量失败时降级为显式 `unavailable` 文案。
+- `team_message` 创建顶层 Thread、回复既有 Thread 或发送 DM。默认创建 taskless Thread；传入 `asTask: true` 才原子创建 Task。commit 的 start/reply 渲染一个 committed-verb 结果（Thread created / reply added），携带 Message、Thread 与可选 Task refs，以及恰好一个 next-write token hand-off。Reply 在检查令牌新鲜度前先拒绝未读工作。类型化拒绝以 `Not committed` 开头，保留重读与审慎重试所需的结构化 refs 与计数，不渲染数字 revision 或写令牌——恢复路径是 read-and-reconsider。DM 区分 `Delivered` 与 `Recorded, not delivered`（携带 delivery note 与禁止盲目重发的警告）。
+- `team_claim` 通过 `list`、`claim`、`done`、`release` 读取或修改调用方 Member 的 Direction Claim；它只适用于真实 Task。`list` 渲染 Task/Thread 身份与只有 active Claims 的 collision surface，且无写令牌。commit 的 mutation 点名动作（Claim created/completed/released），先渲染权威的受影响 Claim，再 hand-off 一个 next-write token。拒绝与 message 拒绝共享同一形式。Direction 互斥键执行 Unicode NFKC normalization、trim、空白压缩和确定性大小写折叠。
+- `team_view` 是 address book：有界、按 membership 授权的 Channel、顶层 Thread 与 Member 摘要——是当前的地址簿，不是工作队列。Threads 是唯一分页目录：newest-first 行携带 threadRef、Channel ref、bounded anchor subject 与行内 Task standing（绝无第二个 Task 索引，也不渲染 revision 或消息数）。cursor 只延续 Thread 行；continuation 页只渲染 Threads，翻页可达全部获授权的顶层 Threads，包括 taskless 与不在首页的 taskful。
+- `context_rollover` 为调用方 Member 安排一次进入全新上下文的 rollover。工具向 Host 校验有界的私有 `handoff`（及可选 `relatedFiles`；传入 `checkpointRef` 则改为回返到已记录的 checkpoint），结束当前 turn 并返回 `status: 'scheduled'`；Host 只在成功的 tool result 持久落盘后才执行真正的换窗。`checkpointRef` 在工具与参数两级 description 上做了 copy hardening：普通续代与压力换窗必须省略，只有引用 `context_timeline` 结果中列为 restorable 的精确 ref 时才提供——绝不合成或猜测。当下不可能成功的 `checkpointRef`——伪造、未 resolve、无法归属、不缩减、不可测量、超预算或被多个 active Claim 阻塞——以 model-visible 的 error result 拒绝，而不是返回假 `scheduled`；可变 guards（jobs、route limits）在换窗 seam 复查，seam 失败后 Member 仍可通过后续 turn 的显式 fresh rollover 恢复。`context_rollover` 与 `context_checkpoint` 都会结束 Agent turn（换窗后不得再接旧代工作；checkpoint 在其所属 turn 结束时 resolve）。
+- `context_checkpoint` 为调用的 Member 记录一个命名的当前上下文 checkpoint。durable checkpoint 就是 Session projection 折叠的成功 `tool/call`+`tool/result` 对；返回的 ref 由 Member Session 身份加 tool call id 确定性派生。工具体不做 lifecycle 副作用，但会结束 turn：checkpoint 在其所属 turn 结束时 resolve，因此模型把它作为一个完整工作单元的最后动作来记录。
+- `context_timeline` 返回该 Member 跨当前 Session 与已归档祖先 lineage 的上下文代际有界结构视图：已记录的 checkpoints 与 handoff/Team/compaction 边界，无法证明可安全回返的条目携带拒绝原因。仅结构信息——不含任何 transcript 正文。fresh 的 `context_rollover` 从不需要先查 timeline。
 
 Agent 不能通过 mention 静默把另一个 unfollowed Agent 加入 Thread；Host 返回 `member_not_following`。Human confirmation 属于单独的 Host/Client 流程。Closed Task 在 Human reopen 前拒绝 reply、Claim 和新的 Attention；taskless Thread 没有 Claim 或 Task resolution mutation path。
 
-Canonical result 包含稳定 refs、可选的 Task status、Thread revision、Claim history、Attention 和未读 facts。类型化的 `unread_required` 与 `stale_revision` 结果包含重新读取和审慎重试所需字段。工具执行通过准确的 live `exec.agent` 解析 actor；参数不能选择或冒充 actor 或 Workspace。写操作的 request identity 由 sessionId 与 tool callId 派生。Team tools 将结果返回模型循环，不主动结束 turn。
+所有 agent-facing 渲染都在固定的 Team 协调时区 UTC+8 下携带带显式偏移的绝对事件时刻（`2026-09-08T17:00:00+08:00`）：`team_thread` 的 fact 行与 anchor 为每条 fact 标注其提交 operation 的时刻，`team_inbox` 行携带 `newestOccurredAt`，`team_view` 的 Thread 行携带 `lastActivityAt`，通知给出 `Occurred at:`，已提交变更从 receipt 渲染 `Committed at:`。同一存储时刻在任何重读路径中渲染完全一致；只渲染绝对 timestamp，绝不出现相对时间文案，且 sequence 与 revision——而非 wall-clock 时间——仍是顺序 authority。
+
+Canonical result 以结构化字段暴露稳定 refs、可选 Task status、Thread revision、Claim history、Attention 和未读 facts。模型可见的渲染遵循 action decision surface：写令牌只出现在未读清零的 `team_thread read` 与一次已提交的 public mutation 上；浏览类结果（`team_view`、`team_inbox`、status/follow/unfollow、`history`、`team_claim list`）与所有类型化拒绝都不渲染 revision 与令牌。类型化的 `unread_required` 与 `stale_revision` 结果保留重新读取和审慎重试所需的结构化字段。工具执行通过准确的 live `exec.agent` 解析 actor；参数不能选择或冒充 actor 或 Workspace。写操作的 request identity 由 sessionId 与 tool callId 派生。`context_rollover` 与 `context_checkpoint` 结束 Agent turn；其余 Team tools 将结果返回模型循环，不主动结束 turn。
 
 完整的已实现协议见 [`../../docs/team-collaboration.md`](../../docs/team-collaboration.md)。
 

package/packages/tool-agent-team/lib/context-tools.js

@@ -0,0 +1,179 @@
+/**
+ * Model-facing context-management tools for Team Members. Thin adapters
+ * only: validation runs in the Host adapter, the successful result is the
+ * durable intent, and every lifecycle side effect — generation swap, Session
+ * creation, inbox handling — happens in the Host coordinator after the
+ * result is durably appended. `concludeTurn()` rides the success result of
+ * `context_rollover` and `context_checkpoint`, so sibling calls settle in model
+ * order before the turn closes.
+ * @module @wowyuarm/dsh-agent-team/context-tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+function service(agent) {
+    const host = agent.ctx.get('agentTeam');
+    if (host === undefined)
+        throw new Error('Agent Team Host is unavailable');
+    return host;
+}
+function member(agent) {
+    const current = service(agent).memberForAgent(agent);
+    if (current === undefined)
+        throw new Error('team tool requires an active Team Member');
+    return current;
+}
+const MAX_HANDOFF_CHARS = 32 * 1024;
+const MAX_RELATED_FILES = 32;
+const contextRollover = defineTool({
+    name: 'context_rollover',
+    description: 'context_rollover: end this context generation and continue as the same Team Member in a new one. Without checkpointRef the context starts fresh and empty, seeded only by your handoff — this is the default, cheapest path at context pressure, and the right choice for ordinary generation changes and pressure-driven handoffs. Omit checkpointRef unless you are deliberately returning to a restorable anchor you just selected from a context_timeline result: supply a checkpointRef only when that timeline listed it as restorable and you are citing its exact ref — never synthesize, guess, or reconstruct one; a fabricated ref rejects as a model-visible error. Write the handoff as one prose string covering: current objective and every active Thread/Claim; verified facts and evidence; inferences and unresolved conflicts; current external side effects and their verification state (files, git, jobs, browser state, remote calls); one explicit next step. A context change never rolls back any external effect — describe current state so the next generation can re-verify. Record anything worth keeping in your private memory/notes first. Collect or stop your background jobs before calling: a rollover is refused while jobs this Member owns are still running.',
+    parameters: {
+        handoff: { type: 'string', required: true, description: 'Prose handoff for the next context generation: objective, active Threads/Claims, verified facts, inferences, external side effects and their verification state, next step.' },
+        checkpointRef: { type: 'string', description: 'Optional. Omit for the default fresh rollover — ordinary generation changes and pressure-driven handoffs must not supply this. Provide it only to resume from a restorable anchor you just selected in a context_timeline result, citing that exact ref; never synthesize or guess a ref.' },
+        relatedFiles: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true }, reason: { type: 'string', required: true } } }, description: 'Workspace paths the next generation should look at first, each with one reason.' },
+    },
+    output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+                mode: { type: 'string', required: true }, status: { type: 'string', required: true },
+            } },
+        render: (_args, value) => [{ type: 'text', text: `Context rollover scheduled (${value.mode}). Finish this turn; the Host switches you to the next context generation afterward.` }],
+    },
+    async execute(args, exec) {
+        const agent = exec.agent;
+        if (agent === undefined)
+            throw new Error('context_rollover requires an Agent session');
+        const current = member(agent);
+        const host = service(agent);
+        const handoff = typeof args.handoff === 'string' ? args.handoff : '';
+        if (handoff.trim() === '')
+            throw new Error('context_rollover requires a non-empty handoff');
+        if (handoff.length > MAX_HANDOFF_CHARS)
+            throw new Error(`context_rollover handoff exceeds ${MAX_HANDOFF_CHARS} characters`);
+        const relatedFilesInput = Array.isArray(args.relatedFiles) ? args.relatedFiles : [];
+        if (relatedFilesInput.length > MAX_RELATED_FILES)
+            throw new Error(`context_rollover accepts at most ${MAX_RELATED_FILES} related files`);
+        // Tool argument validation is layered: the Harness schema (required and
+        // type checks) rejects at the execute boundary, and this body adds the
+        // checks the schema cannot express — each related file is validated
+        // here, so a blank path/reason rejects instead of seeding the handoff
+        // envelope with empty fields.
+        const relatedFiles = [];
+        for (const [index, entry] of relatedFilesInput.entries()) {
+            if (typeof entry !== 'object' || entry === null)
+                throw new Error(`context_rollover relatedFiles[${index}] must be an object with path and reason`);
+            const candidate = entry;
+            if (typeof candidate.path !== 'string' || candidate.path.trim() === '')
+                throw new Error(`context_rollover relatedFiles[${index}].path must be a non-empty string`);
+            if (typeof candidate.reason !== 'string' || candidate.reason.trim() === '')
+                throw new Error(`context_rollover relatedFiles[${index}].reason must be a non-empty string`);
+            relatedFiles.push({ path: candidate.path, reason: candidate.reason });
+        }
+        // Tool schemas are open at the root (Harness parameter specs set no
+        // `additionalProperties: false`), so an undeclared shape can still reach
+        // the body. Any supplied value that is not a non-empty string rejects
+        // here rather than being treated as absent — an absent ref means fresh,
+        // which is not what the model asked for.
+        const raw = args;
+        const suppliedRef = Object.hasOwn(raw, 'checkpointRef') ? raw.checkpointRef : undefined;
+        if (suppliedRef !== undefined && (typeof suppliedRef !== 'string' || suppliedRef.trim() === '')) {
+            throw new Error('context_rollover checkpointRef must be a non-empty string when supplied');
+        }
+        const checkpointRef = typeof suppliedRef === 'string' ? suppliedRef.trim() : undefined;
+        const outcome = await host.requestNewContext(agent, {
+            memberId: current.memberId,
+            ...(checkpointRef === undefined || checkpointRef === '' ? {} : { checkpointRef: checkpointRef }),
+            ...(relatedFiles.length === 0 ? {} : { relatedFiles }),
+        });
+        exec.concludeTurn();
+        return { mode: outcome.mode, status: 'scheduled' };
+    },
+});
+const contextCheckpoint = defineTool({
+    name: 'context_checkpoint',
+    description: 'Record a named checkpoint at the end of the current turn: an opaque, private, restorable anchor for this Member\'s context lineage. Use it before a noisy or risky phase — a broad refactor, an experiment whose value is unproven — when returning to the current completed state may later be useful. The checkpoint resolves only when this turn completes; the Host continues work in the next turn automatically. A checkpoint never snapshots files, git, jobs, or any external state: returning to one (via context_rollover with its checkpointRef) resumes the conversation prefix and nothing else. Checkpoints are private context structure, not Team facts, and are never visible to other Members.',
+    parameters: {
+        name: { type: 'string', required: true, description: 'Short semantic label for this checkpoint, shown in context_timeline.' },
+    },
+    output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+                checkpointRef: { type: 'string', required: true }, name: { type: 'string', required: true },
+            } },
+        // The ref is the selection surface for `context_rollover`: rendering only the
+        // name left the model with no legitimate way to cite the anchor it just
+        // recorded. Renders are the only channel results reach the model through.
+        render: (_args, value) => [{ type: 'text', text: `Checkpoint recorded: ${value.name} (ref: ${value.checkpointRef}). Work continues in the next turn; the Host will continue automatically.` }],
+    },
+    async execute(args, exec) {
+        const agent = exec.agent;
+        if (agent === undefined)
+            throw new Error('context_checkpoint requires an Agent session');
+        const current = member(agent);
+        const host = service(agent);
+        const name = typeof args.name === 'string' ? args.name : '';
+        // The Host validates binding, running-turn fencing, and the name budget;
+        // the durable checkpoint is the successful call/result pair the Session
+        // projection folds, and the ref derives from the tool call id.
+        const outcome = host.recordCheckpointForAgent(agent, { memberId: current.memberId, callId: exec.callId, name });
+        exec.concludeTurn();
+        return { checkpointRef: outcome.checkpointRef, name: outcome.name };
+    },
+});
+const contextTimeline = defineTool({
+    name: 'context_timeline',
+    description: 'Inspect the bounded structural timeline of this Member\'s context lineage: named checkpoints you recorded, Team boundaries (effect anchors: a committed team_message, a successful team_claim mutation, a follow/unfollow — rendered as `Team message`, `Team task claim change`, `Team attention change`; plus a Thread\'s first delivered notice, rendered as `First arrival: <refs>`), handoff and compaction boundaries, and the current head — across the current generation and its archived ancestors. Only the first delivery of a Thread\'s facts anchors; later re-deliveries and reminders produce no boundary. Returns approximate retained/discarded token estimates, current usage against the pressure budget, the Threads whose facts entered your context by each anchor, and which anchors are restorable. A Team boundary is a selectable default checkpoint exactly when it resolved at a completed turn and exactly one Thread is attributable to it; unattributable or multi-Thread boundaries state their reason. Structural only: no transcript content. A fresh context_rollover (no checkpointRef) never requires consulting this timeline first — call it directly. Use this tool only when you specifically intend a checkpointRef return: to pick the smallest sufficient ref, or to confirm that a fresh handoff is the better path when every anchor is marked non-restorable.',
+    parameters: {
+        limit: { type: 'number', description: 'Maximum number of items to return (default 12, at most 24).' },
+    },
+    output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+                usageTokens: { type: 'number', required: true },
+                hardLimit: { type: 'number', required: true },
+                handoffAt: { type: 'number', required: true },
+                items: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
+                            checkpointRef: { type: 'string', required: true },
+                            name: { type: 'string', required: true },
+                            source: { type: 'string', required: true },
+                            retainedTokens: { type: 'number', required: true },
+                            discardedTokens: { type: 'number', required: true },
+                            affectedThreads: { type: 'array', required: true, items: { type: 'string' } },
+                            restorable: { type: 'boolean', required: true },
+                            reason: { type: 'string' },
+                            sourceSessionId: { type: 'string' },
+                        } } },
+            } },
+        // The item list is the whole decision surface: without each anchor's
+        // ref, label, source, size estimates, affected Threads, and
+        // restorable/reason verdict, the model cannot pick a `checkpointRef` for
+        // `context_rollover` — the summary line alone left the tool unusable for
+        // seeded returns. The Host bounds items (default 12, at most 24), so this
+        // list cannot grow unbounded.
+        render: (_args, value) => {
+            const lines = [`Context timeline: ${value.usageTokens} tokens used (handoff at ${value.handoffAt}, hard limit ${value.hardLimit}). ${value.items.length} item(s):`];
+            for (const item of value.items) {
+                const threads = item.affectedThreads.length === 0 ? 'no Threads' : `Threads ${item.affectedThreads.join(', ')}`;
+                const size = `retained ~${item.retainedTokens}, discarded ~${item.discardedTokens}`;
+                const restorable = item.restorable
+                    ? `restorable — ref: ${item.checkpointRef}`
+                    : `not restorable — ${item.reason ?? 'no reason given'}`;
+                lines.push(`- ${item.name} [source: ${item.source}] (${size}; ${threads}) — ${restorable}`);
+            }
+            return [{ type: 'text', text: lines.join('\n') }];
+        },
+    },
+    async execute(args, exec) {
+        const agent = exec.agent;
+        if (agent === undefined)
+            throw new Error('context_timeline requires an Agent session');
+        const current = member(agent);
+        const host = service(agent);
+        const limit = typeof args.limit === 'number' ? args.limit : undefined;
+        const result = await host.contextTimelineForAgent(agent, { memberId: current.memberId, ...(limit === undefined ? {} : { limit }) });
+        // The Host result is deeply immutable; the tool output contract carries
+        // plain arrays, so re-shape without any semantic change.
+        return { usageTokens: result.usageTokens, hardLimit: result.hardLimit, handoffAt: result.handoffAt, items: result.items.map(item => ({ ...item, affectedThreads: [...item.affectedThreads] })) };
+    },
+});
+export function registerContextTools(ctx) {
+    ctx.tools.register(contextRollover);
+    ctx.tools.register(contextCheckpoint);
+    ctx.tools.register(contextTimeline);
+}