{"_id":"@buddhilive/dsh-subagent-in-process-driver","name":"@buddhilive/dsh-subagent-in-process-driver","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-subagent-in-process-driver","description":"Shared in-process subagent run driver: drives a child agent on ctx.agents (used by the spawn and fork backends)","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subagent/subagent-in-process-driver"},"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","peerDependencies":{"@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@buddhilive/dsh-subagent":"^0.1.2-alpha.3"},"devDependencies":{"@deepseek-ai/cordis":"^4.0.2","@deepseek-ai/cordis-plugin-loader":"^1.0.3","@deepseek-ai/cordis-plugin-include":"^1.0.7","@buddhilive/dsh-agent-loop":"^0.1.2-alpha.3","@buddhilive/dsh-agent-loop-testkit":"^0.1.2-alpha.3","@buddhilive/dsh-agent-presets":"^0.1.2-alpha.3","@buddhilive/dsh-fs-sandbox":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-sandbox-policy":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@buddhilive/dsh-subagent":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-tool-fs":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@buddhilive/dsh-user-approval":"^0.1.2-alpha.3"},"dependencies":{"@buddhilive/dsh-brand":"^0.1.2-alpha.3"},"_id":"@buddhilive/dsh-subagent-in-process-driver@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-gEX1cC4VCWYjs8QW48YuQJYkOboq3hbRqArxHAd2DRLUaZ4ofTYwL80I/W624AuNQTGu38Y+/v53fV1qLGUr+Q==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-subagent-in-process-driver-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-subagent-in-process-driver-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-gEX1cC4VCWYjs8QW48YuQJYkOboq3hbRqArxHAd2DRLUaZ4ofTYwL80I/W624AuNQTGu38Y+/v53fV1qLGUr+Q==","shasum":"d755cc3666f735261626c5dd27cf8ff820d0e644","tarball":"https://registry.npmjs.org/@buddhilive/dsh-subagent-in-process-driver/-/dsh-subagent-in-process-driver-0.1.2-alpha.3.tgz","fileCount":10,"unpackedSize":40750,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE17lq1BQX9JzeydPJKFcayHchxAw28le4mgsw9ZJaArAiEAxLWml7QJSIxwFK1zajvNY66B3c1zfNDnw+yvnsAxKp8="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-subagent-in-process-driver_0.1.2-alpha.3_1788165826200_0.9391627921541081"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:43:45.986Z","0.1.2-alpha.3":"2026-08-31T08:43:46.336Z","modified":"2026-08-31T08:43:46.510Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Shared in-process subagent run driver: drives a child agent on ctx.agents (used by the spawn and fork backends)","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subagent/subagent-in-process-driver"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"共享进程内 subagent 运行驱动器，供维护者与后端作者理解或扩展 spawn 与 fork 的运行生命周期。\"\nkind: \"package-library\"\n---\n\n# @buddhilive/dsh-subagent-in-process-driver\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-subagent-in-process-driver` 是两个进程内 subagent 后端共用的运行驱动器：它通过宿主的 agent 工厂创建一个子 agent，应用按子 agent 的定制，把一项任务驱动到完成，并以单一完全停稳的 dispose（资源释放）路径返回子 agent 自身的最终输出。spawn 调用它时不传入会话初始内容；fork 调用它时传入父级已完成轮次的前缀。它是库而非独立功能：提供方后端调用 `startInProcessRun`，组合中没有任何东西配置它。阅读本页可理解两个进程内后端共享的运行生命周期。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n你通过提供方后端而非组合到达本包：`dsh-subagent-spawn-in-process` 与 `dsh-subagent-fork-in-process` 各自调用 `startInProcessRun(request, options)` 并拥有其外围的一切。本页记录两者共享的生命周期，使你读懂一个后端的行为后即可推断另一个。\n\n### 一次运行提供什么\n\n一次调用启动并驱动一个一次性子 agent。调用兑现意味着子 agent 已发布到 `ctx.agents`，调用方拥有返回的运行；启动被拒绝时，未发布的创建已经完全停稳，因此不会有创建到一半的子 agent 存活。运行暴露子 agent 的 id 与在线 agent、一个 `result` promise，以及一个 `dispose()`——它会停止循环、移除 agent 与会话，并撤销作用域内的注册。\n\n### 唯一输入\n\n`InProcessRunOptions` 的形态为 `{ seed?: SessionEvent[] }`——fork 的已配平父级事件初始内容。spawn 省略该值；fork 提供已完成轮次前缀并记录其长度，使结果读取器不会把作为初始内容的父级消息误认为子 agent 输出。\n\n### 子 agent 获得什么\n\n子 agent 获得父级的工作目录/会话谱系，除非 `request.agentOptions` 覆盖，否则继承父级的提供方、模型、推理等级与输出 token 上限。它获得全新的扁平注册作用域：父级工具限制与权限不会被导入。一次运行会把父级显式的沙箱覆盖项与 `'never'` 审批钉定带入子 agent，并在子 agent 的初始轮次内追加一份按运行的描述符。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释驱动器的生命周期约定与结构化输出运行时；可观察行为已在[使用本包](#use-this-package)中说明。\n\n### 启动约定\n\n驱动器按以下顺序运行：\n\n1. 校验父级深度与可选的绝对 `maxDepth`，然后把子级深度推导为父级深度加一，并持久化到子级会话 header。\n2. 通过宿主 agent 工厂创建子 agent，并把调用方必需的信号传入创建事务。\n3. 在该事务未发布的设置窗口内，安装请求的 persona、工具限制与结构化输出运行时。\n4. 发布子 agent，保留返回的句柄，并驱动一项任务。\n5. 从完整的自有运行中读取子 agent 自身的输出——最后一条非空 assistant 消息，若无则取其累积的 assistant 文本——以及最终持久化的轮次原因，并排除任何 fork 初始内容。\n\n### 取消与所有权\n\n必需的请求信号同时覆盖启动阶段与实时运行。发布前，创建事务会观察它、回滚并拒绝；驱动器在发布后再检查一次以消除交接竞态，然后安装最小化的实时运行监听器。兑现后，调用方拥有该运行：提供方插件卸载不会撤销它；`dispose()` 会移除中止监听器、记录取消，并委托给句柄经记忆化的完全停稳事务——后者停止循环、移除 agent 与会话，并撤销作用域内的注册。取消流程会接管所有尚未完成的进行中结果，并将其报告为 `aborted`；已经完成的轮次仍保持完成状态。\n\n### 结构化输出\n\n`attachStructuredRuntime(childCtx, schema)` 会在子 agent 作用域中安装完整约定：`structured_output` 工具按请求的 schema 校验并暂存模型值；位于末尾、first-party 顺序为 9900 的系统提示词段告诉子 agent 该工具调用就是终态答案；`tools/result` 观察器只在该次执行的权威最终工具结果成功后提交暂存值，包括 PTC mode 子分派外层的 `run_code` 结果；单调工具防护会在捕获后阻止后续调用。正常结束却始终未提交必需值的轮次会报告 `error`；驱动器不会重新提示。所有注册都附着于子 agent fiber，并随其一同消失。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 运行驱动器：创建、单轮驱动、结果读取、dispose |\n| [`src/structured.ts`](src/structured.ts) | 结构化输出运行时：捕获工具、提示词段、防护、提交 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件 |\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面；它们从共享 subagent 模型进入构建于本驱动器之上的后端，以及委派策略决策。\n\n- [Subagent 子系统](../../../docs/subsystems/subagent.zh.md)——启动请求、结果、提供方约定与进程内深度和初始内容。\n- [dsh-subagent-spawn-in-process](../subagent-spawn-in-process/README.zh.md)——构建于本驱动器之上的全新子级后端。\n- [dsh-subagent-fork-in-process](../subagent-fork-in-process/README.zh.md)——构建于本驱动器之上的初始内容子级后端。\n- [委派策略决策](../../../.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.zh.md)——父级沙箱与审批策略如何到达子 agent。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 子 agent 请求\n\n#### 模型看到什么\n\n共享驱动器把任务逐字作为子 agent 的用户消息发送；若有请求，还会在未发布子 agent 的全新作用域中遮蔽 persona，并限制全局工具 schema、查找、执行与 PTC mode SDK 绑定。父级限制不会被继承，独立的工具指导段仍会保留。spawn 不提供历史；fork 提供其已配平的初始内容。\n\n#### Token 影响\n\n子 agent 输入与父级隔离，并随子 agent 自身的步骤增长。persona 会改变重复提示词文本；过滤会改变 schema 或生成 SDK 的成本，但不影响独立注册的指导内容。\n\n#### KV Cache 影响\n\n与父级请求缓存相互独立。子 agent 后续历史仅追加，而 persona、工具过滤、生成 SDK、提供方或模型变化会建立不同的子 agent 前缀。\n\n### 结构化输出系统提示词、schema 与结果\n\n#### 模型看到什么\n\n结构化运行会添加下方的结构化输出指令，并添加子 agent 作用域的 `structured_output` 定义，其参数使用请求的 schema，精确描述为 `Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.` 该仅运行时存在的定义不在已生成并随产品发布的[工具包索引](../../../docs/tool-catalog.zh.md#tool-package-map)中。其规范确认值是 `{ recorded: true }`，渲染为 `Structured output recorded.`；后续调用会变为 ``Error: structured output already recorded: the run is complete, so `<tool>` is not executed``。\n\n##### 结构化输出指令\n\n```markdown\nWhen you have your final answer, you MUST report it by calling the `structured_output` tool with arguments matching its parameter schema exactly. Do not finish with a plain text answer: only the tool call counts as your result.\n```\n\n#### Token 影响\n\n固定指令与能力产生的 token 仅由该子 agent 承担。结果文本进入子 agent 历史，而只有捕获的值会成为父级结果。\n\n#### KV Cache 影响\n\n只要结构化输出指令与 schema 不变，子 agent 内部的前缀就保持稳定。更改 schema 或能力可能从该早期片段开始使子 agent 缓存失效；结果会分别追加到子 agent 与父级历史中。\n\n### 父级启动错误（间接）\n\n#### 模型看到什么\n\n通过 `dsh-tool-subagent`，无效深度状态会精确变为 `Error: agent subagentDepth must be a non-negative safe integer`、`Error: subagent child depth exceeds the safe-integer range` 或 `Error: subagent depth <attempted> exceeds maxDepth <max>`。发布前取消的中止原因会通过注册表的 `Error: <message>` 包装传递。\n\n#### Token 影响\n\n启动成功时为零 token；只有失败的父级工具调用会保留这段文本。\n\n#### KV Cache 影响\n\n仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n### 父级结果（间接）\n\n#### 模型看到什么\n\n驱动器只提取子 agent 自身最后的 assistant 输出或捕获的结构化值；作为初始内容的父级消息与子 agent 中间工作不会成为结果。\n\n#### Token 影响\n\n父级通过消费方接收一个依赖数据的结果；其他所有子 agent token 都留在子 agent 会话中。\n\n#### KV Cache 影响\n\n仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明进程内一次性运行不能做什么；它们是当前包约束。\n\n- **运行不公开 `sendMessage`/`resume`**——进程内一次性运行不具备这些可选运行时能力。\n- **结构化捕获只接受 `defineTool` schema 子集**——不支持的 JSON Schema 构造会在子 agent 创建前失败；需要更广 schema 词汇的提供方必须采用不同的运行时。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-7053f86df3453a2e935a2853917ec469"}