{"_id":"@buckeyestudio/toh-tool-subagent-report","name":"@buckeyestudio/toh-tool-subagent-report","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-tool-subagent-report","description":"Child-scoped report tool over ctx.subagents continuations","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/subagent/tool-subagent-report"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/toh-subagent":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"dependencies":{"@buckeyestudio/schemastery":"^3.18.1"},"devDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-agent-loop":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-agent-loop-testkit":"^0.1.1-rc.2","@buckeyestudio/toh-session":"^0.1.1-rc.2","@buckeyestudio/toh-session-persistence":"^0.1.1-rc.2","@buckeyestudio/toh-session-persistence-jsonl":"^0.1.1-rc.2","@buckeyestudio/toh-subagent-spawn-in-process":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/toh-subagent":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/toh-tool-subagent-control":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-tool-subagent-report@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-SvH9WXMa85Rr2GPjyTVdOlIpHGapaHNS9xki95sw5kd6JZaZTtgLcpM+qhqOCTAro4IhBJ1qy4dgCRsEh+BJSA==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-subagent-report-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-subagent-report-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-SvH9WXMa85Rr2GPjyTVdOlIpHGapaHNS9xki95sw5kd6JZaZTtgLcpM+qhqOCTAro4IhBJ1qy4dgCRsEh+BJSA==","shasum":"f3bb941694f9b1babc7acd7986af881aaca6f5f3","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-tool-subagent-report/-/toh-tool-subagent-report-0.1.1-rc.2.tgz","fileCount":9,"unpackedSize":26351,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDeZbl7RMsm6TxprzQApbrrwL5kGoVbEEQ5yOMFrJ9dAAIhALdpl/GOf9NbP3AmBZZPyD0tM9GwsAy3ZLC0NDplwRUE"}]},"_npmUser":{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"},"directories":{},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toh-tool-subagent-report_0.1.1-rc.2_1787489417221_0.8343117788187262"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:50:17.008Z","0.1.1-rc.2":"2026-08-23T12:50:17.371Z","modified":"2026-08-23T12:50:17.589Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Child-scoped report tool over ctx.subagents continuations","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/subagent/tool-subagent-report"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-tool-subagent-report\n\n[English](README.md) | 中文\n\n可选的子级作用域 `report` 工具是 `ctx.subagents.reportFrom()` 之上的轻量适配器。它为每个可继续的进程内子级提供一条返回通道，指向启动该子级的 Agent（智能体），并安装指示子级使用该通道的提示词 section。本包注册的是可继续子级设置贡献，而不是全局工具，因此该工具及其指引只存在于这些子级内部。根 Agent、一次性 subagent、远程 subagent 提供方、同级作用域以及不关联 Agent 的工具执行都不会提供或执行它。安装本包只授予这项子级作用域能力；父到子方向仍由独立的 [`@buckeyestudio/toh-tool-subagent-control`](../tool-subagent-control/README.zh.md) 负责，可继续模式不依赖这两个包中的任一个。\n\n子级作用域的 `tool:report` 提示词 section 要求子级在结束前调用一次 `report` 并给出自足的答案，并在部分发现会改变父级下一步动作时提前上报。该指令是引导而非强制：机制本身仍接受一个轮次中调用零次或多次，也没有任何运行时路径会拒绝从不上报的子级。调用成功既不会结束轮次或结算 Activation，也不会阻止父级后续消息；轮次结束也绝不会自动上报。该工具不接受接收方参数：`exec.agent` 是发送方确切在线的 Agent，也是权限凭据；服务根据该子级持久化的 `parentSession` 推导唯一接收方。成功时返回父级已接受消息的稳定 `MessageId`，不表示已读回执、inbox 中该次出现的 id、父级日志确认、轮次完成回执或持久化刷盘。父级解析由注册表中的存在性决定：父级不在注册表时，调用失败并返回 `direct parent is not live; report was not delivered`；已开始由宿主管理的 dispose（资源释放）但仍在注册表中的父级在其日志仍接受追加时仍会接受。服务不会执行注入、父级冷恢复或离线 mailbox 写入；持久化子级 transcript（文本记录）仍是恢复依据，且工具调用失败不能证明未送达（后续 `tools/post-execute` 否决可能让报告已被接受的调用以失败结束）。\n\n`reportDelivery` 为每条已接受的报告选择父级调度方式。`next-step`（默认值）使用 `parent.steer()`：运行中的父级会在最近的安全 step 边界收到报告，空闲父级则会启动一个轮次。按顺序接受的报告会共享 next-step FIFO，稍后由管理器撰写的结算通知也进入该队列，因此父级不会在更早的报告之前看到结算；一起等待的报告会进入同一个领取批次。`quiet` 使用 `parent.inject()`，添加相同的 next-step 上下文，但不会唤醒停驻的父级。这是部署调度策略，因此面向模型的 schema 不能在单次调用中选择或覆盖该策略。\n\n作用域局部注册有意不受子级全局 `toolFilter` 影响，因此委派允许列表无法移除唯一的返回通道。需要子级不具备返回通道的部署应省略本包。\n\n贡献体以 `installReportTool(childCtx, ctx, delivery)` 导出，以便检查类消费方把 `report` 及其指引安装到新创建的子级作用域中，并返回同时撤销两者的唯一 disposer。全局注册表无法公开作用域局部 schema，因此生成的工具目录会使用这条路径。生产组合仍通过 `apply()` 进入；subagent seam 的贡献注册表保持私有。\n\n## 模型体验\n\n### 工具 schema\n\n#### 模型看到的内容\n\n已生成的 [`report` schema](../../../docs/tool-catalog.zh.md#buckeyestudiotoh-tool-subagent-report)：包含一个必填 `output` 字符串。其描述说明子级必须在结束前上报一次，上报只会到达启动该子级的 Agent，并且不会结束轮次。它不包含接收方或投递模式参数。独立的 `tool:report` 提示词 section 在 schema 之外重申该义务，使忽略工具描述的子级仍能读到。\n\n#### Token 影响\n\n每个可继续子级请求支付固定的 schema 与提示词 section 成本，其他任何 Agent 的请求均无此成本。\n\n#### KV Cache 影响\n\n子级中的前缀保持稳定；schema 与该 section 都不会在运行时改变。移除本包会从驻留子级中撤销两者，从而改变其下一次请求前缀。\n\n### 上报结果\n\n#### 模型看到的内容\n\n接受时返回 `report accepted by the agent that started you as message <messageId>`；规范输出携带稳定的 `messageId`。发送方未授权、父级不可用或生命周期正在关闭时，会返回错误结果。描述中会说明，失败的调用仍可能已经送达，因为 `reportFrom()` 接受消息后，后续 `tools/post-execute` 失败可能替换工具结果。\n\n#### Token 影响\n\n每次调用都会在执行上报的子级中产生一条简短确认消息。父级还会为上报内容支付 token 成本：next-step 投递会加入父级已打开轮次的下一次请求，或为空闲父级启动一个轮次；静默投递则等待其他输入唤醒父级。\n\n#### KV Cache 影响\n\n在子级中仅追加。在父级中，带前缀的报告位于现有历史之后，并保留可复用前缀。\n\n### 父级可见的报告\n\n#### 模型看到的内容\n\n一条用户角色的父级消息，以 `Background subagent <child-id> reported:` 开头，后接子级未经改动的 `output`，并带有指明该子级的持久化来源 `{ kind: 'subagent-report', senderSessionId: <child-id> }`。\n\n#### Token 影响\n\n子级的完整 `output` 加上一行前缀；本包不设上限。\n\n#### KV Cache 影响\n\n仅追加；报告位于父级可复用请求前缀之后。next-step 投递会唤醒父级，并可能延长其已打开的轮次；静默投递则不会唤醒父级。\n\n## 已知限制与暂缓事项\n\n- **父级可能在宿主启动 dispose 后继续接受报告**：`AgentHandle.dispose()` 会先取消并等待完全停稳，然后才撤销作用域并离开注册表；它不公开「dispose 已开始」信号。在该窗口内接受的报告会追加到父级 transcript，但该父级不会在本进程中处理它。对于由继续执行管理器拥有的父级，管理器的准入边界会在整片森林拆卸期间拒绝该上报。\n- **接受弱于持久投递**：没有持久化 mailbox、幂等键、投递回执、重试协议，也不保证恰好一次。任一侧记录接受后若进程失败，结果都不明确；外部重试可能产生重复上报。\n- **暂存的静默报告无法立即重建**：接受时会返回其稳定 `MessageId`，但只有当待处理上下文到达普通日志边界后，父级会话才能重建带前缀的内容。\n- **授权须等到下一个 Activation，撤销则立即生效**：子级驻留后再安装本包，只会在该子级的下一个 Activation 中授予 `report` 及其指引；移除本包则会立即从驻留子级撤销两者。\n- **嵌套上报只向上到达一条直接边**：孙级只向作为其直接父级的子级上报，不会直接到达顶层协调器；该直接父级必须随后显式发出一条衍生更新。\n- **没有速率限制**：嵌套子级频繁上报时，默认的 `next-step` 模式会放大模型工作量，但一起等待的报告会共享一个 step；宁可接受报告无人阅读也要避免这种放大的部署应选择 `quiet`。\n","readmeFilename":"README.zh.md","_rev":"1-dd78c1652c3f46529f4b0e70ff3fe914"}