diff --git a/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.i18n.yaml index 95b171d364..29f0dd7d88 100644 --- a/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md -2026-08-03-per-session-agent-presets.md: 98ff20d1c0e6e5c0369a064790880438a67b2992 -2026-08-03-per-session-agent-presets.zh.md: 2845db46cbdaa64dcfaeda90cfed69325ef251e8 +2026-08-03-per-session-agent-presets.md: 5a82f0220058c10892b819a83499c817aa9be6ad +2026-08-03-per-session-agent-presets.zh.md: 0fb3330014eb703c854f70c9e5ed552256651c31 diff --git a/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md b/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md index 98ff20d1c0..5a82f02200 100644 --- a/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md +++ b/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md @@ -31,7 +31,7 @@ Which preset an unnamed session gets is a user setting (`agent-presets.default`) ## Consequences -**The effective default is read per resolution, never snapshotted.** A cached value would need a `watch` subscription and a reload path to stay honest, and the resolved scope already re-reads a hot-reloaded document. Reading through is also what makes the boundary correct rather than merely cheap: the new value applies to the next session created, and every running session keeps the composition it was built from. That invariant is the same one the session header enforces from the other side — the header records the id a session actually runs, so a resume rebuilds that composition rather than today's default, and the gateway rejects an attempt to adopt a live session under a different one. A snapshot would make the two disagree at exactly the moment the setting changes. +**The effective default is read per resolution, never snapshotted.** A cached value would need a `watch` subscription and a reload path to stay honest, and the resolved scope already re-reads a hot-reloaded document. Reading through is also what makes the boundary correct rather than merely cheap: the new value applies to the next session created, and every running session keeps the composition it was built from. That invariant is the same one the session log enforces from the other side — the header records the id a session was CREATED with and an `agent-preset/selected` event records any later blank-session switch, so a reader resolves the pair (`resolveSessionPreset`) and never the header alone: a resume rebuilds the composition its history was produced under rather than today's default, a cold transcript's presenters resolve in that composition's layer, and the gateway rejects an attempt to adopt a live session under a preset other than the one it currently runs. A snapshot would make the two disagree at exactly the moment the setting changes. **A directly-plugged subtree is invisible to the boot audit.** It never links itself to an `Entry`, so it is absent from `ctx.loader.entries()` and `assertEntriesActivated` cannot see it. The mount audits its own rows instead, reading the tree through an `Include` subclass that publishes it. diff --git a/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.zh.md b/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.zh.md index 2845db46cb..0fb3330014 100644 --- a/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.zh.md @@ -31,7 +31,7 @@ Status: implemented ## 后果 -**有效默认值在每次解析时读取，从不快照。** 缓存下来就需要一个 `watch` 订阅和一条重载路径才能保持诚实，而解析后的 scope 本来就会重读热重载过的文档。读穿也不只是省事，它让边界本身是对的：新值作用于**下一个新建的会话**，每个运行中的会话保持它被构建时的那份组装。这条不变量正是 session header 从另一侧执行的同一条——header 记录会话实际运行的 id，因此恢复重建的是那份组装而不是当下的默认值，网关也会拒绝把一个活着的会话收编到另一个 preset 之下。快照会让两者恰好在设置改变的那一刻各说各话。 +**有效默认值在每次解析时读取，从不快照。** 缓存下来就需要一个 `watch` 订阅和一条重载路径才能保持诚实，而解析后的 scope 本来就会重读热重载过的文档。读穿也不只是省事，它让边界本身是对的：新值作用于**下一个新建的会话**，每个运行中的会话保持它被构建时的那份组装。这条不变量正是 session 日志从另一侧执行的同一条——header 记录会话**创建时**的 id，此后空白期的任何切换由 `agent-preset/selected` 事件记录，因此读取方解析的是两者之和（`resolveSessionPreset`）、绝不单看 header：恢复重建的是其历史所产出的那份组装而不是当下的默认值，冷读记录的 presenter 在那份组装的层里解析，网关也会拒绝把一个活着的会话收编到它当前运行的 preset 以外的 preset 之下。快照会让两者恰好在设置改变的那一刻各说各话。 **直接挂载的子树对启动审计不可见。** 它不会把自己关联到 `Entry`，因此不在 `ctx.loader.entries()` 中，`assertEntriesActivated` 也看不到它。改由挂载过程自行校验各行，通过一个会公开自身 tree 的 `Include` 子类读取。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.i18n.yaml new file mode 100644 index 0000000000..351632fcc5 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.md +2026-08-10-child-agents-join-their-parent-preset.md: 4534004ad54df69822872b9595a29443fc3a990b +2026-08-10-child-agents-join-their-parent-preset.zh.md: bdf9928bea4b75e2915c8adf5c15f8a01c6583e4 diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.md b/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.md new file mode 100644 index 0000000000..4534004ad5 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.md @@ -0,0 +1,59 @@ +# Agent Note: Child agents join their parent's preset composition + +Status: implemented + +English | [中文](2026-08-10-child-agents-join-their-parent-preset.zh.md) + +## Problem + +Tool and prompt-section visibility is inherited along `dsh-scope`'s parent chain, and an agent's scope key is minted with no parent. [Per-session agent presets](../architecture/2026-08-03-per-session-agent-presets.md) moved every model-facing row onto the agent plane and made `AgentPresets.mount()` the one thing that binds that parent link — from the api-proxy's session create, resume, and fork paths. The two in-process subagent drivers compose their children through `applyChildComposition()`, which installed only the per-child persona and tool filter, so a child's scope chain had length one and its registry view resolved the global layer alone. + +That layer is now empty in any deployment with a preset roster: the web-app patch layer disables every host-plane tool row. A one-shot child therefore reached the model with zero tools, a continuable child with only the host-plane `report`, and neither carried its parent's persona, workspace context, plan-mode section, or skill catalog. The fork path had already been given the same treatment for the same reason; delegation had not. + +The child's durable header compounded it. `childSessionMeta()` recorded no preset, so a cold read of a child session resolved the deployment default — a tool set the child never ran under, which is exactly what the model-visible ⟺ logged rule exists to prevent. + +## Decision + +`AgentPresets.composeFrom(agentCtx, parentCtx)` joins one agent to the standing composition another already runs on, and returns the preset id joined. It locates the parent's mount through `standingMountFor()` — the agent's key is parented to its preset's standing key, the same relation `serviceForAgent()` reads — and binds the child's key to that same standing key, keeping the binding under the roster's sole re-link authority. A parent that joined no preset yields no join and no error, which is the rosterless deployment: its model-facing rows sit in the host composition, where the child already resolves them through the global layer. + +This is a bind, not a mount, and both differences are load-bearing. The child gets its parent's exact generation, so a composition file edited since the parent started cannot hand the child a different one than its parent's history was produced under, and a preset deleted since cannot fail a child whose parent keeps running. It is also synchronous, which is what lets the child creation windows use it — both in-process drivers compose inside a synchronous `setup`. + +`applyChildComposition(childCtx, parent, composition)` takes the parent and performs the join before applying the child's own registrations. The parameter is the point: it makes composing a child without the join unrepresentable at the call sites, rather than leaving each new driver to remember a second step. `childSessionMeta()` records the joined id through `AgentPresets.composedPreset()`, read from the parent's live scope chain rather than its header, because a parent that switched preset while blank runs on the newer composition while its header still names the older one. + +`dsh-subagent` reaches the roster through `ctx.get('agentPresets')` with a type-only import and an optional peer dependency — the documented opportunistic-consumption pattern it already uses for `sandboxPolicy` and `approval`. + +Giving the child its parent's tools exposed a second defect the same agent-plane move introduced: `ToolRegistry` exempted SCOPED registrations from a restriction and filtered only the global layer, so once every model-facing row became an ancestor contribution, a child's `toolFilter` stopped constraining anything — and, with the global layer empty, `restrict()` rejected every name it was given as unknown, failing the child outright. The exempt set is the tools a scope registers ITSELF, not the tools that happen to live in the global layer; reading it the second way held only while those two sets coincided. `view()` now filters everything a scope inherits — the global layer and every ancestor layer — and exempts only its own. The own-layer exemption is load-bearing rather than incidental: the delegation runtime registers a child's `report` and structured-output tools into the child's own layer, and a filter naming the capabilities the child may use must not strip the machinery it answers through. + +## Alternatives considered + +**Re-mount the parent's preset by id in the child's setup.** Rejected on both semantics and mechanics. It re-reads the roster and re-stats the composition file, so an edit since the parent started forks the child onto a different generation, and a preset deleted since fails the child while its parent runs on. `mount()` is also asynchronous, which the synchronous creation windows cannot accept without restructuring both drivers. + +**Bind the child's key to the PARENT's key rather than to the standing mount.** Rejected because it changes what a child inherits: the parent's own scope layer carries its per-agent restrictions, which would then intersect into every descendant, and a child outliving its parent would hang off a disposed agent's key. Joining the standing mount gives the child its parent's composition and nothing else. + +**Extend the continuable activation setup registry to cover one-shot children.** Rejected because that registry's contribution type is synchronous `(childCtx) => () => void` with per-installation revocation, modelling deployment capabilities that come and go, while a preset join is a one-time bind with no revocation of its own. Widening it would have made the omission possible again for any driver that skipped the registry. + +**Let `dsh-subagent` import `resolveSessionPreset` and mount by the resolved id.** Rejected because it makes the preset roster a hard module edge for a package that must work without one, and it lands back on the remount semantics above. + +**Filter every layer on the chain, including the scope's own.** Rejected because it makes a per-child capability filter delete that child's reporting and structured-output tools, which the delegation runtime registers into the child's own layer — an `allow` naming the capabilities a child may use would leave it unable to answer at all. + +**Leave the durable header alone and fix only the live join.** Rejected because the live child and the same child read cold would then disagree about which composition produced its history — the same class of defect, moved rather than fixed. + +## Testing + +`packages/preset/agent-presets/tests/mount.spec.ts` covers the join against real fixture compositions: the child sees its parent's tools and prompt sections, no second generation is mounted, the join survives the parent's disposal (a background child outliving its parent), the reported id matches, a parent without a preset joins nothing, and an unscoped context is refused. + +`packages/core/tools/tests/scoped.spec.ts` covers the restriction rule directly: a child's filter removes a tool it inherited from an ancestor scope, the child's own registrations survive its own filter, and an ancestor's restriction still reaches every scope nested inside it. + +`packages/subagent/subagent-inprocess/tests/preset-inheritance.spec.ts` asserts the model-visible result through `startInProcessRun()` on a host composition carrying no model-facing rows: the schemas in the child's own request, its parent's prompt section, the recorded header preset, a `toolFilter` applied over the inherited preset tools, and a parent that switched preset while blank — to a DIFFERENT preset, so the assertion distinguishes reading the parent's live scope chain from reading its creation header. + +The assembled-transcript layer is the shipped Web composition's e2e rather than a keyless snapshot. Every runnable example this repo ships composes no preset roster, so the defect is not observable in the snapshot harness at all: a snapshot scenario would first need an example that mounts a roster AND delegates. The Web e2e boots the real `base` + `web-app` patch layers with both shipped presets, which is the assembled evidence the testing policy asks for; the Web browser lane's subagent goldens carry the visible consequence, since a child that records its preset now shows the preset badge its parent shows. + +## Consequences + +Delegation now costs a scope-parent bind per child and nothing else — no extra plugin instances, no roster read, no failure mode. A child's capabilities are exactly its parent's, minus whatever its own `toolFilter` removes; a per-subagent preset ("agent types") remains unbuilt and would be a new request field rather than a change to this join. + +`applyChildComposition()` changed shape, so any future out-of-tree in-process driver must supply the parent. That is the intended cost: the previous signature let a caller compose a capability-less child and get no error. + +A cold-resumed continuable child joins its parent's CURRENT composition rather than the one its own header records. The window is narrow — the parent must create the child, stay blank, switch preset, and only then wake it, since a resident child never re-joins and a one-shot child never resumes — and the alternative is worse: resolving the child's own recorded id would re-read the roster and hand back the preset-deleted failure mode this join exists to avoid. The child's header still records what it started under, so the divergence is observable rather than silent. + +`ToolRegistry` now reads a restriction's exempt set as "what this scope registers itself" rather than "the global layer", which changes one documented behavior beyond delegation: a tool an ANCESTOR scope contributes is now subject to a descendant's filter, where before only global-layer tools were. Nothing else on the chain loses its exemption — a scope's own registrations stay outside its own filter, which is the property the delegation runtime depends on. diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.zh.md b/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.zh.md new file mode 100644 index 0000000000..bdf9928bea --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-10-child-agents-join-their-parent-preset.zh.md @@ -0,0 +1,59 @@ +# Agent Note: Child agents join their parent's preset composition + +Status: implemented + +[English](2026-08-10-child-agents-join-their-parent-preset.md) | 中文 + +## Problem + +工具与提示段的可见性沿 `dsh-scope` 的父链继承，而 agent 的 scope key 铸造出来时没有父。[逐会话 agent preset](../architecture/2026-08-03-per-session-agent-presets.md) 把所有面向模型的行搬到了 agent 平面，并让 `AgentPresets.mount()` 成为绑定那条父链的唯一途径——调用点在 api-proxy 的会话创建、恢复与 fork 路径上。两个进程内 subagent 驱动通过 `applyChildComposition()` 组装子 agent，而它只安装了逐子 agent 的 persona 与工具限制，于是子 agent 的 scope 链长度为一，其注册表视图只能解析到全局层。 + +在任何配置了 preset roster 的部署里，那一层现在是空的：web-app 补丁层禁用了全部宿主平面工具行。因此一次性子 agent 抵达模型时工具为零，可继续子 agent 只剩宿主平面的 `report`，两者都不带父方的 persona、工作区上下文、plan-mode 段与技能目录。fork 路径此前已因同一理由做过相同处理；委派没有。 + +子 agent 的持久化 header 让问题更进一步。`childSessionMeta()` 不记录任何 preset，于是冷读一个子会话解析到的是部署默认值——一套该子 agent 从未运行过的工具集，而这正是"模型可见 ⟺ 已记录"规则要杜绝的情形。 + +## Decision + +`AgentPresets.composeFrom(agentCtx, parentCtx)` 让一个 agent 加入另一个 agent 已在运行的常驻组装，并返回所加入的 preset id。它通过 `standingMountFor()` 定位父方的挂载——agent 的 key 认父到其 preset 的常驻 key，正是 `serviceForAgent()` 读取的同一关系——再把子 agent 的 key 绑到同一个常驻 key 上，绑定句柄仍归 roster 独有的重链权威持有。未加入任何 preset 的父方不产生加入、也不报错，那就是无 roster 的部署：它面向模型的行位于宿主组装中，子 agent 已经能通过全局层解析到它们。 + +这是认父而非挂载，两处差别都要紧。子 agent 拿到的是父方那个确切的代际，因此父方启动后被编辑过的组装文件不可能把与父方历史所产出时不同的另一个代际交给它，此后被删除的 preset 也不可能让一个父方仍在运行的子 agent 失败。它还是同步的，这正是子 agent 创建窗口能够使用它的前提——两个进程内驱动都在同步的 `setup` 中完成组装。 + +`applyChildComposition(childCtx, parent, composition)` 接收父方，并在应用子 agent 自身注册之前完成加入。这个参数正是要点所在：它让"组装子 agent 却不做该加入"在各调用点无法表达，而不是把第二个步骤留给每个新驱动去记住。`childSessionMeta()` 通过 `AgentPresets.composedPreset()` 记录所加入的 id，该值从父方**活着的** scope 链读取而不是从其 header 读取，因为在空白期切换过 preset 的父方运行在更新的那份组装上，而它的 header 仍写着旧的那个。 + +`dsh-subagent` 以类型级导入加可选 peer 依赖的方式，通过 `ctx.get('agentPresets')` 触达 roster——这正是它对 `sandboxPolicy` 与 `approval` 已在使用的、有明确文档的机会性消费模式。 + +把父方的工具交给子 agent 之后，暴露出同一次 agent 平面搬迁引入的第二个缺陷：`ToolRegistry` 把**作用域级**注册排除在限制之外、只过滤全局层，因此当所有面向模型的行都变成祖先贡献之后，子 agent 的 `toolFilter` 就不再约束任何东西——而且全局层为空时，`restrict()` 会把收到的每个名字都判为未知并直接让子 agent 创建失败。豁免集合应当是作用域**自己注册**的工具，而不是恰好位于全局层的工具；后一种读法只在这两个集合重合时才成立。`view()` 现在过滤作用域继承来的一切——全局层与每个祖先层——只豁免它自己那层。这条自身层豁免是承重的而非顺带的：委派运行时把子 agent 的 `report` 与结构化输出工具注册进子 agent 自己那层，而一个只点名子 agent 可用能力的过滤器绝不能把它回报所依赖的机制一并剥掉。 + +## Alternatives considered + +**在子 agent 的 setup 里按 id 重新挂载父方的 preset。** 语义与机制两方面都不成立而被否决。它会重读 roster 并重新 stat 组装文件，因此父方启动后的一次编辑就会把子 agent 分叉到另一个代际，而此后被删除的 preset 会让子 agent 失败、父方却照常运行。`mount()` 还是异步的，同步的创建窗口无法在不重构两个驱动的前提下接受它。 + +**把子 agent 的 key 绑到**父方的** key 而不是常驻挂载上。** 否决，因为这改变了子 agent 继承的内容：父方自己的 scope 层携带其逐 agent 限制，那些限制会就此与每个后代求交，而活得比父方久的子 agent 会挂在一个已 dispose 的 agent key 上。加入常驻挂载给到子 agent 的是父方的组装，仅此而已。 + +**扩展可继续 activation setup 注册表以覆盖一次性子 agent。** 否决，因为该注册表的贡献类型是同步的 `(childCtx) => () => void` 并带有逐次安装的撤销，建模的是会来会走的部署能力，而 preset 加入是一次性认父、自身没有撤销可言。扩展它反而会让任何绕过该注册表的驱动重新具备遗漏的可能。 + +**让 `dsh-subagent` 导入 `resolveSessionPreset` 并按解析出的 id 挂载。** 否决，因为这会给一个必须在没有 roster 时也能工作的包引入硬模块边，而且最终仍落回上述的重新挂载语义。 + +**过滤链上的每一层，包括作用域自身那层。** 否决，因为那会让逐子 agent 的能力过滤器把该子 agent 的回报与结构化输出工具一并删掉——它们由委派运行时注册进子 agent 自己那层——于是一个点名"子 agent 可用哪些能力"的 `allow` 会让它彻底无法回报。 + +**只修活着的加入，不动持久化 header。** 否决，因为那样活着的子 agent 与冷读同一个子 agent 会对"哪份组装产出了这段历史"给出不同答案——同一类缺陷，只是被搬了个地方而不是被修掉。 + +## Testing + +`packages/preset/agent-presets/tests/mount.spec.ts` 用真实 fixture 组装覆盖该加入：子 agent 看到父方的工具与提示段、不会挂载出第二个代际、加入在父方 dispose 后依然成立（活得比父方久的后台子 agent）、上报的 id 一致、没有 preset 的父方不产生加入、以及无 scope 的上下文被拒绝。 + +`packages/core/tools/tests/scoped.spec.ts` 直接覆盖该限制规则：子 agent 的过滤器能移除它从祖先作用域继承来的工具、子 agent 自身的注册在自己的过滤器下存活、祖先的限制仍作用于其内嵌套的每个作用域。 + +`packages/subagent/subagent-inprocess/tests/preset-inheritance.spec.ts` 在一个不含任何面向模型行的宿主组装上，通过 `startInProcessRun()` 断言模型可见的结果：子 agent 自身请求中的 schema、父方的提示段、记录下来的 header preset、施加在继承来的 preset 工具之上的 `toolFilter`，以及在空白期切换过 preset 的父方——切换到**另一个** preset，这样断言才能区分"读父方活 scope 链"与"读父方创建 header"。 + +组装记录这一层用的是真实 shipped Web 组装的 e2e，而不是无密钥快照。本仓库所有可运行 example 都不组装 preset roster，因此该缺陷在快照 harness 里根本不可观察：要做快照场景，得先有一个既挂载 roster 又发起委派的 example。Web e2e 启动的是真实的 `base` + `web-app` 补丁层与两个 shipped preset，这正是测试政策要求的组装证据；Web 浏览器 lane 的 subagent golden 承载了可见后果——记录了 preset 的子 agent 现在会显示与其父方相同的 preset 徽标。 + +## Consequences + +委派现在的成本是每个子 agent 一次 scope 认父，再无其他——没有额外的插件实例、没有 roster 读取、没有新的失败模式。子 agent 的能力恰好等于父方的能力，减去它自己的 `toolFilter` 所移除的部分；逐 subagent 的 preset（"agent 类型"）仍未构建，那会是一个新的请求字段，而不是对这次加入的改动。 + +`applyChildComposition()` 的形态变了，因此将来任何仓库外的进程内驱动都必须提供父方。这是刻意付出的代价：此前的签名允许调用方组装出一个毫无能力的子 agent 而不报任何错。 + +冷恢复的可继续子 agent 加入的是父方**当前**的组装，而不是它自己 header 所记录的那份。窗口很窄——父方必须先建子、保持空白、切换 preset，之后才唤醒它；驻留中的子 agent 不会重新加入，一次性子 agent 也不会恢复——而替代方案更糟：按子 agent 自己记录的 id 解析会重读 roster，把这次认父刻意规避掉的"preset 已删除"失败模式又请回来。子 agent 的 header 仍记录它启动时的那份，因此这处分歧是可观察的而非静默的。 + +`ToolRegistry` 现在把限制的豁免集合读作"该作用域自己注册的东西"而不是"全局层"，这在委派之外改变了一处既有行为：**祖先**作用域贡献的工具现在会受后代过滤器约束，而此前只有全局层的工具会。链上其余部分的豁免不变——作用域自身的注册仍在自己的过滤器之外，这正是委派运行时所依赖的性质。 diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml index e60442bb37..3b685e614b 100644 --- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-24-workspace-context.md -2026-06-24-workspace-context.md: e7a3724847b9dc8cfad11e87b2c96a3ef442bcba -2026-06-24-workspace-context.zh.md: 39c3f52da10b7299301d10bd8b78330cbae8e19c +2026-06-24-workspace-context.md: 4398fbb1606e764dde9fad8a8f3c325f5e0fead4 +2026-06-24-workspace-context.zh.md: 72ae077be08e95ce582584e66945c2187255abdd diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md index e7a3724847..4398fbb160 100644 --- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md +++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md @@ -52,7 +52,7 @@ Every workspace context event stores versioned metadata with `{ action, scope, p At reconciliation time the plugin scans workspace-sourced `user/message` events and derives the latest state for each visible scope. Successful nested touches aggregate under their parent execution token, including when a later composite result is blocked; the top-level result transfers them either to the open session step or directly to a per-agent projection queue. A `step/end` releases its staged touches only after that boundary is durable, and the next `agent/pre-step` waits for the serialized projections. Each projection composes against visible history plus the current inbox and replaces the single pending workspace context instead of accumulating intermediate renderings. -An unchanged path and digest is suppressed. A logged removal is a tombstone, so a reappearing candidate becomes a new `set`. Resume works from persisted metadata: a compatible visible baseline supplies comparison state rather than causing another complete baseline to be appended. If compaction removes an instruction event from the visible surface, that state no longer suppresses a later load, matching the fact that the model can no longer see it. Only changes actually included under the byte budget enter metadata or pending state, so an omitted file remains eligible on a later touch. +An unchanged path and digest is suppressed. A logged removal is a tombstone, so a reappearing candidate becomes a new `set`. Resume works from persisted metadata: a compatible visible baseline supplies comparison state rather than causing another complete baseline to be appended. If compaction removes an instruction event from the visible surface, that state no longer suppresses a later load, matching the fact that the model can no longer see it. A change enters metadata or pending state only when its file-specific section retains at least one content byte, or when the original content is genuinely empty. Partial truncation commits the full-content digest once any byte survives; zero-content truncation remains eligible on a later touch. A baseline may retain budget diagnostics with no committed changes. A dynamic batch with no committed change is withheld entirely and retried on a later touch. An omitted file remains eligible on a later touch. The initial baseline's typed changes are comparison state only while its event remains in the visible session surface. Resume retains a compatible baseline and reconciles current baseline and visible dynamic scopes, so changes made while the agent was offline append transitions before the first resumed request. When compaction shadows the baseline event, the next entering pre-step composes the complete current baseline and records it in the same request; a successful filesystem touch can instead re-add an unchanged baseline scope or append baseline edits or removals as dynamic messages. Neither path rewrites the original event. The in-memory scope marker and provider-version cache only select and accelerate probes, so neither can suppress context the model no longer sees. diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md index 39c3f52da1..72ae077be0 100644 --- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md +++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md @@ -52,7 +52,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell， 协调时，插件扫描带工作区来源的 `user/message` 事件，并派生每个可见作用域的最新状态。即使后续复合结果被拦截，成功的嵌套 touch 也会聚合到父级执行 token 下；顶层结果会将它们交给打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界持久化后释放其暂存的 touch；下一次 `agent/pre-step` 会等待串行投影完成。每次投影都会根据可见历史和当前 inbox 进行组合，并替换唯一一条待处理工作区上下文，而不会累积中间渲染结果。 -路径和 digest 均未变化时会被抑制。日志中的移除操作是一条墓碑记录，因此重新出现的候选项会成为新的 `set`。恢复操作从持久化元数据继续工作：兼容的可见基线会提供比较状态，而不会导致再次追加完整基线。如果压缩从可见表面移除某条指令事件，该状态不再抑制后续加载，这与模型已经无法看见它的事实一致。只有真正纳入字节预算的变更才会进入元数据或待处理状态，因此被省略的文件在之后的触碰中仍有资格加载。 +路径和 digest 均未变化时会被抑制。日志中的移除操作是一条墓碑记录，因此重新出现的候选项会成为新的 `set`。恢复操作从持久化元数据继续工作：兼容的可见基线会提供比较状态，而不会导致再次追加完整基线。如果压缩从可见表面移除某条指令事件，该状态不再抑制后续加载，这与模型已经无法看见它的事实一致。变更只有在对应文件专属段落保留至少一个内容字节，或原始内容确实为空时，才会进入元数据或待处理状态。只要任一内容字节保留下来，部分截断就会提交完整内容 digest；截断到零内容仍可在后续触碰中处理。基线可以保留字节预算诊断而不提交任何变更。动态批次若没有可提交变更，则整批不注入，并在后续触碰中重试。被省略的文件仍可在之后的触碰中加载。 只有当初始基线事件仍在可见会话表层中时，其类型化变更才用作比较状态。恢复会保留兼容的基线，并对账当前基线和可见的动态 scope，因此 agent 离线期间的变更会在第一次恢复请求前追加为转换。当压缩遮蔽基线事件时，下一次进入步骤的 pre-step 会组合完整的当前基线，并在同一请求中记录它；也可以改由一次成功的文件系统触碰重新添加未变化的基线 scope，或把基线编辑或移除操作追加为动态消息。两条路径都不会重写原始事件。内存中的 scope 标记和提供方版本 cache 只用于选择探测对象并加速探测，因此二者都不能抑制模型已无法看见的上下文。 diff --git a/apps/cli/config/agent-presets/code/preset.yml b/apps/cli/config/agent-presets/code/preset.yml index f3426e52f4..17eaccb871 100644 --- a/apps/cli/config/agent-presets/code/preset.yml +++ b/apps/cli/config/agent-presets/code/preset.yml @@ -1,3 +1,3 @@ name: 代码模式 -description: 标准模式的工具改为 Code Mode 呈现：模型写一段 TypeScript 调用 SDK，一次执行代替多轮工具调用。 +description: 具备标准模式的全部能力，并通过 Code Mode SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。 order: 2 diff --git a/apps/cli/config/agent-presets/cordis/preset.yml b/apps/cli/config/agent-presets/cordis/preset.yml index 49cb3c6d44..62475b6454 100644 --- a/apps/cli/config/agent-presets/cordis/preset.yml +++ b/apps/cli/config/agent-presets/cordis/preset.yml @@ -1,3 +1,3 @@ name: 创造模式 -description: 标准模式加上自指工具集，可以读改自己运行的这套组装，并据此创作新的预设。 +description: 用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、插件实验和 preset 创作指导。 order: 4 diff --git a/apps/cli/config/agent-presets/minimal/preset.yml b/apps/cli/config/agent-presets/minimal/preset.yml index 5521dda140..7160b51c43 100644 --- a/apps/cli/config/agent-presets/minimal/preset.yml +++ b/apps/cli/config/agent-presets/minimal/preset.yml @@ -1,3 +1,3 @@ name: 极简模式 -description: 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。 +description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。 order: 3 diff --git a/apps/cli/config/agent-presets/standard/preset.yml b/apps/cli/config/agent-presets/standard/preset.yml index 8eddfbde48..caeacd1c1e 100644 --- a/apps/cli/config/agent-presets/standard/preset.yml +++ b/apps/cli/config/agent-presets/standard/preset.yml @@ -1,3 +1,3 @@ name: 标准模式 -description: 完整的编码 agent：文件读写、shell、检索、计划、委派与工作流。 +description: 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。 order: 1 diff --git a/apps/cli/package.json b/apps/cli/package.json index d312dd28d9..03bd4c3db9 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -77,6 +77,7 @@ "@deepseek-ai/dsh-loader-smoke": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-settings": "workspace:^", + "@deepseek-ai/dsh-subagent": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@types/js-yaml": "^4.0.9", diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts index 4e0dcc3a1d..1c67650523 100644 --- a/apps/cli/tests/web-agent-presets.e2e.ts +++ b/apps/cli/tests/web-agent-presets.e2e.ts @@ -11,6 +11,7 @@ import type { PatchOptions } from '@cordisjs/plugin-include' import { afterAll, beforeAll, describe, expect, it } from 'vitest' import { settingsNamespace } from '@deepseek-ai/dsh-settings' import { resolveSessionPreset, SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-agent-presets' +import { applyChildComposition, childSessionMeta } from '@deepseek-ai/dsh-subagent' import { CallId } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-skill' import type {} from '@deepseek-ai/dsh-tools' @@ -526,6 +527,59 @@ describe('a forked session', () => { }) }) +describe('a delegated child', () => { + it('runs on the composition its parent runs on', async () => { + const parent = await ctx.agents.create({ + sessionId: SessionId('preset-child-parent'), + meta: { agentPreset: 'standard' }, + setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined), + }) + // Exactly what an in-process subagent driver's creation window does. + const child = await parent.agent.ctx.agents.create({ + sessionId: SessionId('preset-child'), + meta: childSessionMeta(parent.agent, 1, 0), + setup: (agentCtx) => { + applyChildComposition(agentCtx, parent.agent, {}) + }, + }) + try { + expect(toolNames(ctx, child.agent)).toEqual(toolNames(ctx, parent.agent)) + // The shipped `standard` preset is the whole coding agent; an empty + // child here is the defect, and equality alone would not catch it. + expect(toolNames(ctx, child.agent)).toContain('bash') + expect(child.agent.session.header.agentPreset).toBe('standard') + } finally { + await child.dispose() + await parent.dispose() + } + }) + + it('follows a parent that switched preset while blank', async () => { + const parent = await ctx.agents.create({ + sessionId: SessionId('preset-child-switch-parent'), + meta: { agentPreset: 'standard' }, + setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined), + }) + await ctx.agentPresets.recompose(parent.agent.ctx, 'minimal') + const child = await parent.agent.ctx.agents.create({ + sessionId: SessionId('preset-child-switch'), + meta: childSessionMeta(parent.agent, 1, 0), + setup: (agentCtx) => { + applyChildComposition(agentCtx, parent.agent, {}) + }, + }) + try { + // The live scope chain is the authority, not the parent's creation + // header — which still names `standard`. + expect(toolNames(ctx, child.agent)).toEqual(toolNames(ctx, parent.agent)) + expect(child.agent.session.header.agentPreset).toBe('minimal') + } finally { + await child.dispose() + await parent.dispose() + } + }) +}) + describe('authoring a preset on the shipped composition', () => { let authorCtx: Context let userRoot: string diff --git a/apps/web/tests/agent-preset-authoring.e2e.ts b/apps/web/tests/agent-preset-authoring.e2e.ts index 0b82d6d808..e8ff5aa538 100644 --- a/apps/web/tests/agent-preset-authoring.e2e.ts +++ b/apps/web/tests/agent-preset-authoring.e2e.ts @@ -161,7 +161,7 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => { expect(composition).toBe(await readFile(join(SHIPPED_PRESETS, 'minimal', 'agent.cordis.yml'), 'utf8')) const metadata = await readFile(join(userRoot, 'my-agent', 'preset.yml'), 'utf8') expect(metadata).toContain('name: 我的模式') - expect(metadata).toContain('description: 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。') + expect(metadata).toContain('description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。') expect(metadata).not.toContain('order:') }, 60_000) diff --git a/apps/web/tests/agent-preset-selection.e2e.ts b/apps/web/tests/agent-preset-selection.e2e.ts index 2bcaa5e628..4a7f6eb819 100644 --- a/apps/web/tests/agent-preset-selection.e2e.ts +++ b/apps/web/tests/agent-preset-selection.e2e.ts @@ -16,6 +16,10 @@ import { join } from 'node:path' import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { + SESSION_FORMAT_VERSION, SessionId as sessionId, type SessionEvent, type SessionId, +} from '@deepseek-ai/dsh-session' +import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent' import { captureStableAria, compareOrRefreshGolden, launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold, @@ -78,6 +82,60 @@ function seedLog(): string { ].join('\n') } +/** + * Persist one child so the assembled header snapshot exercises both action + * contributors whose relative order is the product contract under test. + * @param scaffold - the booted Web scaffold. + * @param parentId - the seeded session whose header the browser opens. + */ +async function seedSubagent(scaffold: WebScaffold, parentId: SessionId): Promise { + const childId = sessionId('agent-preset-selection-child') + const createdAt = 1784974100100 + await scaffold.ctx.sessionPersistence.create({ + version: SESSION_FORMAT_VERSION, + id: childId, + createdAt, + cwd: scaffold.workspaceCwd, + parentSession: parentId, + origin: 'subagent', + delegationDepth: 1, + agentPreset: 'minimal', + }) + await scaffold.ctx.sessionPersistence.append(childId, [ + { + type: 'turn/start', + seq: 0, + time: createdAt, + data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }, + }, + { + type: 'user/message', + seq: 1, + time: createdAt + 1, + data: { + content: [{ type: 'text', text: 'Check the session-header action order.' }], + source: { kind: 'user' }, + }, + surfaceOp: 'append', + }, + { + type: 'subagent/descriptor', + seq: 2, + time: createdAt + 2, + data: snapshotSubagentDescriptor({ + mode: 'one-shot', provider: 'spawn', label: 'header order probe', + }), + }, + { + type: 'turn/end', + seq: 3, + time: createdAt + 3, + data: { turn: 1, reason: { kind: 'completed' } }, + }, + ] as SessionEvent[]) + await scaffold.ctx.sessionProjectionCache.coldSnapshot(childId) +} + /** * The preset the host reports for the blank session the workspace connect * produced. Addressed by id rather than by scanning the serialized list: the @@ -120,7 +178,8 @@ describe('web e2e: agent-preset selection', () => { // A resumed session runs what it was created with; seeding one that // records `minimal` is what makes the header label a claim about the // session rather than an echo of the current default. - await seedSession(scaffold, seedLog(), SEED_ID, 'minimal') + const seededId = await seedSession(scaffold, seedLog(), SEED_ID, 'minimal') + await seedSubagent(scaffold, seededId) await seedWorkspaceSkill(scaffold.workspaceCwd) browser = await chromium.launch() page = await newEnglishPage(browser) @@ -143,12 +202,12 @@ describe('web e2e: agent-preset selection', () => { await compareOrRefreshGolden(HERO_EXPECTED, snapshot, MODE) // The chip opens on the deployment default, by the name that preset // publishes rather than its directory name. - expect(snapshot).toContain('标准模式') + expect(snapshot).toContain('Standard mode') }) it('names every preset and what it is for', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-agent-preset-menu')) - await page.getByRole('button', { name: '标准模式' }).click() + await page.getByRole('button', { name: 'Standard mode' }).click() const menu = page.getByRole('menu') await menu.waitFor({ timeout: 10_000 }) @@ -157,15 +216,15 @@ describe('web e2e: agent-preset selection', () => { await compareOrRefreshGolden(MENU_EXPECTED, snapshot, MODE) // Every shipped preset, each with the sentence saying what it composes — // the id alone never said what a preset does. - expect(snapshot).toContain('极简模式') - expect(snapshot).toContain('创造模式') + expect(snapshot).toContain('Minimal mode') + expect(snapshot).toContain('Creator mode') await page.keyboard.press('Escape') }) it('applies the staged pick to the blank session, and the host honors it', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-agent-preset-stage')) - await page.getByRole('button', { name: '标准模式' }).click() - await page.getByRole('menuitem', { name: /极简模式/ }).click() + await page.getByRole('button', { name: 'Standard mode' }).click() + await page.getByRole('menuitem', { name: /Minimal mode/ }).click() // The chip stages; the blank session the workspace connect produced is // what the stage lands on. The host's own answer is what comes back. @@ -197,8 +256,8 @@ describe('web e2e: agent-preset selection', () => { // against its list row, so a row that never reprojected the first switch // answers "already standard" and sends nothing — and restores the catalog // instead of leaving the session reading the narrower composition. - await page.getByRole('button', { name: '极简模式' }).click() - await page.getByRole('menuitem', { name: /^标准模式/ }).first().click() + await page.getByRole('button', { name: 'Minimal mode' }).click() + await page.getByRole('menuitem', { name: /^Standard mode/ }).first().click() await expect.poll(() => livePreset(scaffold.baseUrl), { timeout: 15_000 }).toBe('standard') await composer.fill('/') @@ -221,10 +280,12 @@ describe('web e2e: agent-preset selection', () => { const snapshot = await captureStableAria(page, '[class*="titleRow"]', scaffold.workspaceCwd) await compareOrRefreshGolden(HEADER_EXPECTED, snapshot, MODE) - expect(snapshot).toContain('极简模式') + expect(snapshot).toContain('Minimal mode') + expect(snapshot).toContain('button "1 subagent"') + expect(snapshot.indexOf('Minimal mode')).toBeLessThan(snapshot.indexOf('button "1 subagent"')) // Static chrome, not a control: the header can only report a composition // the host would refuse to change. - expect(snapshot).not.toContain('button "极简模式"') + expect(snapshot).not.toContain('button "Minimal mode"') }) it('drove every surface without a page error or a stream warning', () => { diff --git a/apps/web/tests/snapshots/agent-preset-authoring/created.expected.md b/apps/web/tests/snapshots/agent-preset-authoring/created.expected.md index e5cefe28ef..395e517aa1 100644 --- a/apps/web/tests/snapshots/agent-preset-authoring/created.expected.md +++ b/apps/web/tests/snapshots/agent-preset-authoring/created.expected.md @@ -20,7 +20,7 @@ - list: - listitem: - 'button "当前使用: 标准模式" [disabled] [pressed]': - - text: 标准模式 内置 当前使用 完整的编码 agent：文件读写、shell、检索、计划、委派与工作流。 + - text: 标准模式 内置 当前使用 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。 - code: standard - 'button "查看: 标准模式"': - img @@ -30,7 +30,7 @@ - text: 复制 - listitem: - 'button "设为默认: 代码模式"': - - text: 代码模式 内置 标准模式的工具改为 Code Mode 呈现：模型写一段 TypeScript 调用 SDK，一次执行代替多轮工具调用。 + - text: 代码模式 内置 具备标准模式的全部能力，并通过 Code Mode SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。 - code: code - 'button "查看: 代码模式"': - img @@ -40,7 +40,7 @@ - text: 复制 - listitem: - 'button "设为默认: 极简模式"': - - text: 极简模式 内置 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。 + - text: 极简模式 内置 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。 - code: minimal - 'button "查看: 极简模式"': - img @@ -50,7 +50,7 @@ - text: 复制 - listitem: - 'button "设为默认: 创造模式"': - - text: 创造模式 内置 标准模式加上自指工具集，可以读改自己运行的这套组装，并据此创作新的预设。 + - text: 创造模式 内置 用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、插件实验和 preset 创作指导。 - code: cordis - 'button "查看: 创造模式"': - img @@ -62,7 +62,7 @@ - list: - listitem: - 'button "设为默认: 我的模式"': - - text: 我的模式 自定义 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。 + - text: 我的模式 自定义 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。 - code: my-agent - 'button "查看路径: 我的模式"': - img diff --git a/apps/web/tests/snapshots/agent-preset-authoring/damaged.expected.md b/apps/web/tests/snapshots/agent-preset-authoring/damaged.expected.md index 8269dc2993..b40b848b5e 100644 --- a/apps/web/tests/snapshots/agent-preset-authoring/damaged.expected.md +++ b/apps/web/tests/snapshots/agent-preset-authoring/damaged.expected.md @@ -20,7 +20,7 @@ - list: - listitem: - 'button "当前使用: 标准模式" [disabled] [pressed]': - - text: 标准模式 内置 当前使用 完整的编码 agent：文件读写、shell、检索、计划、委派与工作流。 + - text: 标准模式 内置 当前使用 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。 - code: standard - 'button "查看: 标准模式"': - img @@ -30,7 +30,7 @@ - text: 复制 - listitem: - 'button "设为默认: 代码模式"': - - text: 代码模式 内置 标准模式的工具改为 Code Mode 呈现：模型写一段 TypeScript 调用 SDK，一次执行代替多轮工具调用。 + - text: 代码模式 内置 具备标准模式的全部能力，并通过 Code Mode SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。 - code: code - 'button "查看: 代码模式"': - img @@ -40,7 +40,7 @@ - text: 复制 - listitem: - 'button "设为默认: 极简模式"': - - text: 极简模式 内置 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。 + - text: 极简模式 内置 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。 - code: minimal - 'button "查看: 极简模式"': - img @@ -50,7 +50,7 @@ - text: 复制 - listitem: - 'button "设为默认: 创造模式"': - - text: 创造模式 内置 标准模式加上自指工具集，可以读改自己运行的这套组装，并据此创作新的预设。 + - text: 创造模式 内置 用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、插件实验和 preset 创作指导。 - code: cordis - 'button "查看: 创造模式"': - img diff --git a/apps/web/tests/snapshots/agent-preset-authoring/section.expected.md b/apps/web/tests/snapshots/agent-preset-authoring/section.expected.md index ac5d6f6736..dcbe72641c 100644 --- a/apps/web/tests/snapshots/agent-preset-authoring/section.expected.md +++ b/apps/web/tests/snapshots/agent-preset-authoring/section.expected.md @@ -20,7 +20,7 @@ - list: - listitem: - 'button "当前使用: 标准模式" [disabled] [pressed]': - - text: 标准模式 内置 当前使用 完整的编码 agent：文件读写、shell、检索、计划、委派与工作流。 + - text: 标准模式 内置 当前使用 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。 - code: standard - 'button "查看: 标准模式"': - img @@ -30,7 +30,7 @@ - text: 复制 - listitem: - 'button "设为默认: 代码模式"': - - text: 代码模式 内置 标准模式的工具改为 Code Mode 呈现：模型写一段 TypeScript 调用 SDK，一次执行代替多轮工具调用。 + - text: 代码模式 内置 具备标准模式的全部能力，并通过 Code Mode SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。 - code: code - 'button "查看: 代码模式"': - img @@ -40,7 +40,7 @@ - text: 复制 - listitem: - 'button "设为默认: 极简模式"': - - text: 极简模式 内置 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。 + - text: 极简模式 内置 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。 - code: minimal - 'button "查看: 极简模式"': - img @@ -50,7 +50,7 @@ - text: 复制 - listitem: - 'button "设为默认: 创造模式"': - - text: 创造模式 内置 标准模式加上自指工具集，可以读改自己运行的这套组装，并据此创作新的预设。 + - text: 创造模式 内置 用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、插件实验和 preset 创作指导。 - code: cordis - 'button "查看: 创造模式"': - img diff --git a/apps/web/tests/snapshots/agent-preset-selection/header.expected.md b/apps/web/tests/snapshots/agent-preset-selection/header.expected.md index ef2ad4ef57..5a78c6461e 100644 --- a/apps/web/tests/snapshots/agent-preset-selection/header.expected.md +++ b/apps/web/tests/snapshots/agent-preset-selection/header.expected.md @@ -1,4 +1,7 @@ - navigation "Session hierarchy": - button "Seeded turn" [disabled] - img -- text: 极简模式 +- text: Minimal mode +- button "1 subagent": + - text: 1 subagent + - img diff --git a/apps/web/tests/snapshots/agent-preset-selection/hero.expected.md b/apps/web/tests/snapshots/agent-preset-selection/hero.expected.md index f2d54eb579..a320fa3e2f 100644 --- a/apps/web/tests/snapshots/agent-preset-selection/hero.expected.md +++ b/apps/web/tests/snapshots/agent-preset-selection/hero.expected.md @@ -2,7 +2,7 @@ - img - text: workspace - img -- button "标准模式": +- button "Standard mode": - img - - text: 标准模式 + - text: Standard mode - img diff --git a/apps/web/tests/snapshots/agent-preset-selection/menu.expected.md b/apps/web/tests/snapshots/agent-preset-selection/menu.expected.md index fd92ab8b5a..78ec056f56 100644 --- a/apps/web/tests/snapshots/agent-preset-selection/menu.expected.md +++ b/apps/web/tests/snapshots/agent-preset-selection/menu.expected.md @@ -1,7 +1,7 @@ - menu: - - menuitem "标准模式 完整的编码 agent：文件读写、shell、检索、计划、委派与工作流。": - - text: 标准模式 完整的编码 agent：文件读写、shell、检索、计划、委派与工作流。 + - menuitem "Standard mode Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.": + - text: Standard mode Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows. - img - - menuitem "代码模式 标准模式的工具改为 Code Mode 呈现：模型写一段 TypeScript 调用 SDK，一次执行代替多轮工具调用。" - - menuitem "极简模式 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。" - - menuitem "创造模式 标准模式加上自指工具集，可以读改自己运行的这套组装，并据此创作新的预设。" + - menuitem "Code mode All Standard mode capabilities, with tools exposed through the Code Mode SDK so the model can combine multi-step operations in one TypeScript program." + - menuitem "Minimal mode Two-tool coding agent with only bash and str_replace_editor, for benchmarks and minimal reproductions." + - menuitem "Creator mode Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, plugin experiments, and preset-authoring guidance." diff --git a/apps/web/tests/snapshots/code-mode-round/ui.expected.md b/apps/web/tests/snapshots/code-mode-round/ui.expected.md index f426539e87..9d9ea8ab0e 100644 --- a/apps/web/tests/snapshots/code-mode-round/ui.expected.md +++ b/apps/web/tests/snapshots/code-mode-round/ui.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - 'button "Using ONE run_code program: run" [disabled]' - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md b/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md index 2bc6f76a93..42197364ae 100644 --- a/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md +++ b/apps/web/tests/snapshots/cordis-tool-round/ui.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use only Cordis tools. First" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md b/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md index 0529e000b7..d360f936bd 100644 --- a/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md +++ b/apps/web/tests/snapshots/fresh-round-trip/ui.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use the bash tool to" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md b/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md index fa178e30d8..c0ece71be8 100644 --- a/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md +++ b/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "workspace" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md index 223006d59d..c666681b0b 100644 --- a/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md +++ b/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md @@ -25,9 +25,9 @@ - img - text: workspace - img -- button "标准模式": +- button "Standard mode": - img - - text: 标准模式 + - text: Standard mode - img - textbox "Describe what you want to build" - button "Commands": diff --git a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md index a234028a16..2f9c701936 100644 --- a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md +++ b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md @@ -25,9 +25,9 @@ - img - text: workspace - img -- button "标准模式": +- button "Standard mode": - img - - text: 标准模式 + - text: Standard mode - img - textbox "Describe what you want to build" - button "Commands": diff --git a/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md index 149d8ce3f9..19283ae51d 100644 --- a/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md +++ b/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with the single word" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/live-interactions/cancel.expected.md b/apps/web/tests/snapshots/live-interactions/cancel.expected.md index 1d87f01525..4fa0394693 100644 --- a/apps/web/tests/snapshots/live-interactions/cancel.expected.md +++ b/apps/web/tests/snapshots/live-interactions/cancel.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/live-interactions/error-auth.expected.md b/apps/web/tests/snapshots/live-interactions/error-auth.expected.md index 94d739baf1..83be4dc961 100644 --- a/apps/web/tests/snapshots/live-interactions/error-auth.expected.md +++ b/apps/web/tests/snapshots/live-interactions/error-auth.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/live-interactions/loading.expected.md b/apps/web/tests/snapshots/live-interactions/loading.expected.md index c461dd985a..c475c05e05 100644 --- a/apps/web/tests/snapshots/live-interactions/loading.expected.md +++ b/apps/web/tests/snapshots/live-interactions/loading.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/live-interactions/retry.expected.md b/apps/web/tests/snapshots/live-interactions/retry.expected.md index 70a9e69e95..7bb61c5b27 100644 --- a/apps/web/tests/snapshots/live-interactions/retry.expected.md +++ b/apps/web/tests/snapshots/live-interactions/retry.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/plan-review/approved.expected.md b/apps/web/tests/snapshots/plan-review/approved.expected.md index cdd844062a..23664b4a1d 100644 --- a/apps/web/tests/snapshots/plan-review/approved.expected.md +++ b/apps/web/tests/snapshots/plan-review/approved.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - 'button "Plan a small change: add" [disabled]' - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/question-composer/answered.expected.md b/apps/web/tests/snapshots/question-composer/answered.expected.md index 32e3e4bc75..d15b2af3a1 100644 --- a/apps/web/tests/snapshots/question-composer/answered.expected.md +++ b/apps/web/tests/snapshots/question-composer/answered.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use the ask_user_question tool to" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/collapsed.expected.md b/apps/web/tests/snapshots/queue-actions/collapsed.expected.md index d039c3d6d6..5438f084ae 100644 --- a/apps/web/tests/snapshots/queue-actions/collapsed.expected.md +++ b/apps/web/tests/snapshots/queue-actions/collapsed.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/editing.expected.md b/apps/web/tests/snapshots/queue-actions/editing.expected.md index 453b83e20e..186f0b0169 100644 --- a/apps/web/tests/snapshots/queue-actions/editing.expected.md +++ b/apps/web/tests/snapshots/queue-actions/editing.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/layout.expected.md b/apps/web/tests/snapshots/queue-actions/layout.expected.md index 64451ab4ce..9996bdcd0b 100644 --- a/apps/web/tests/snapshots/queue-actions/layout.expected.md +++ b/apps/web/tests/snapshots/queue-actions/layout.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "workspace" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/preserved.expected.md b/apps/web/tests/snapshots/queue-actions/preserved.expected.md index a845590873..54410743dc 100644 --- a/apps/web/tests/snapshots/queue-actions/preserved.expected.md +++ b/apps/web/tests/snapshots/queue-actions/preserved.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/queue-actions/ui.expected.md b/apps/web/tests/snapshots/queue-actions/ui.expected.md index 386b3e9889..1467c50d97 100644 --- a/apps/web/tests/snapshots/queue-actions/ui.expected.md +++ b/apps/web/tests/snapshots/queue-actions/ui.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Reply with a one-sentence description" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md b/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md index 63bd2ef401..1f1cd0ea18 100644 --- a/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md +++ b/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "/user-invoke-demo and confirm the fixtur" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/steer-all/mid-steer.expected.md b/apps/web/tests/snapshots/steer-all/mid-steer.expected.md index 8b77a77a0c..ce2d4a66e6 100644 --- a/apps/web/tests/snapshots/steer-all/mid-steer.expected.md +++ b/apps/web/tests/snapshots/steer-all/mid-steer.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use the ask_user_question tool to" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/steer-all/settled.expected.md b/apps/web/tests/snapshots/steer-all/settled.expected.md index 0899529a09..b20e590686 100644 --- a/apps/web/tests/snapshots/steer-all/settled.expected.md +++ b/apps/web/tests/snapshots/steer-all/settled.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use the ask_user_question tool to" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/steering/mid-steer.expected.md b/apps/web/tests/snapshots/steering/mid-steer.expected.md index 5fd1fccaaf..30d4d7ac4b 100644 --- a/apps/web/tests/snapshots/steering/mid-steer.expected.md +++ b/apps/web/tests/snapshots/steering/mid-steer.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use the ask_user_question tool to" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/steering/settled.expected.md b/apps/web/tests/snapshots/steering/settled.expected.md index cba73282f3..93c311cce4 100644 --- a/apps/web/tests/snapshots/steering/settled.expected.md +++ b/apps/web/tests/snapshots/steering/settled.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use the ask_user_question tool to" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/subagent-conversation/ui.expected.md b/apps/web/tests/snapshots/subagent-conversation/ui.expected.md index 27c7ec092e..cf22f5b566 100644 --- a/apps/web/tests/snapshots/subagent-conversation/ui.expected.md +++ b/apps/web/tests/snapshots/subagent-conversation/ui.expected.md @@ -3,6 +3,8 @@ - button "Ask a research subagent to" - text: / - button "event-sourcing researcher" [disabled] + - img + - text: Standard mode - button "1 subagent": - text: 1 subagent - img diff --git a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md index a977afbbea..7fe41a532d 100644 --- a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md +++ b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md @@ -3,6 +3,8 @@ - button "Ask a research subagent to" - text: / - button "event-sourcing researcher" [disabled] + - img + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/turn-tail-actions/running.expected.md b/apps/web/tests/snapshots/turn-tail-actions/running.expected.md index b1a32406de..8e5d4c5858 100644 --- a/apps/web/tests/snapshots/turn-tail-actions/running.expected.md +++ b/apps/web/tests/snapshots/turn-tail-actions/running.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Begin your reply with the" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/turn-tail-actions/settled.expected.md b/apps/web/tests/snapshots/turn-tail-actions/settled.expected.md index 32ea9a9b1e..47203f70eb 100644 --- a/apps/web/tests/snapshots/turn-tail-actions/settled.expected.md +++ b/apps/web/tests/snapshots/turn-tail-actions/settled.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Begin your reply with the" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/snapshots/web-search-round/ui.expected.md b/apps/web/tests/snapshots/web-search-round/ui.expected.md index b24385d48f..9e86cdcf2c 100644 --- a/apps/web/tests/snapshots/web-search-round/ui.expected.md +++ b/apps/web/tests/snapshots/web-search-round/ui.expected.md @@ -2,7 +2,7 @@ - navigation "Session hierarchy": - button "Use web_search to search exactly" [disabled] - img - - text: 标准模式 + - text: Standard mode - tablist: - tab "Chat" [selected] - tab "Trajectory" diff --git a/apps/web/tests/steering.e2e.ts b/apps/web/tests/steering.e2e.ts index a527081fbe..01b3a85b56 100644 --- a/apps/web/tests/steering.e2e.ts +++ b/apps/web/tests/steering.e2e.ts @@ -314,7 +314,7 @@ describe('web e2e: empty-draft Cmd+Enter steers the whole queue', () => { await page.goto(scaffold.baseUrl, { waitUntil: 'load' }) await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) await connectFreshWorkspace(page, scaffold.workspaceCwd) - await page.getByText('标准模式', { exact: true }).waitFor({ timeout: 10_000 }) + await page.getByText('Standard mode', { exact: true }).waitFor({ timeout: 10_000 }) }, 120_000) afterAll(async () => { diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 128581d1ba..77fcfca867 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/module-graph.md -module-graph.md: a81c8fa85eb85d5ec31bfff286fceff511880715 -module-graph.zh.md: b1ec05f45d1dac545e020f6438f2e2b4d197ebdf +module-graph.md: b596cb564943e321ff42cd59855bd7dc10981319 +module-graph.zh.md: b64f30c2df1eedb1a1fa106b79710558b765fdde diff --git a/docs/module-graph.md b/docs/module-graph.md index a81c8fa85e..b596cb5649 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -825,6 +825,7 @@ flowchart TD pkg_command_compact --> pkg_compact pkg_command_compact --> pkg_invariants pkg_subagent --> pkg_agent + pkg_subagent --> pkg_agent_presets pkg_subagent --> pkg_brand pkg_subagent --> pkg_invariants pkg_subagent --> pkg_llm @@ -1390,7 +1391,7 @@ flowchart TD | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) | | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) | | [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) | -| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) | +| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) | | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) | | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index b1ec05f45d..b64f30c2df 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -827,6 +827,7 @@ flowchart TD pkg_command_compact --> pkg_compact pkg_command_compact --> pkg_invariants pkg_subagent --> pkg_agent + pkg_subagent --> pkg_agent_presets pkg_subagent --> pkg_brand pkg_subagent --> pkg_invariants pkg_subagent --> pkg_llm @@ -1392,7 +1393,7 @@ flowchart TD | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) | | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) | | [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) | -| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) | +| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) | | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) | | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml index 9915a99b63..a7d26cee1b 100644 --- a/docs/subsystems/core.i18n.yaml +++ b/docs/subsystems/core.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/core.md -core.md: 75f55fe5b1837576ba79564b9aee7e289f5f16f4 -core.zh.md: 7cd55b41c8f1358a89c6f35a4d3f733ccd8550ee +core.md: ad00c4da7d77b0e1ab4728173b202ebc17fb56a0 +core.zh.md: 9c606023c85369643e7148f829526b1f75ea3631 diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md index 75f55fe5b1..ad00c4da7d 100644 --- a/docs/subsystems/core.md +++ b/docs/subsystems/core.md @@ -419,6 +419,45 @@ async resolve(id?: string): Promise */ async mount(agentCtx: Context, id?: string): Promise +/** + * Join one agent to the SAME standing composition another already runs on. + * + * This is how a child agent inherits its parent's capabilities. It is a bind, + * not a mount: the parent's generation is already composed, so the child gets + * that exact instance — the same plugin objects, the same tool registrations, + * the same prompt sections. Re-resolving the parent's preset by id instead + * would re-read the roster, and a composition file edited since the parent + * started would hand the child a DIFFERENT generation than the one its + * parent's history was produced under (and a preset deleted since would fail + * the child outright while its parent keeps running). + * + * Synchronous, and with no composition failure mode of its own — it reads no + * roster, mounts nothing, and touches no file — which is what lets a child + * creation window use it: the two in-process subagent drivers compose their + * children inside a synchronous `setup`. It still rejects a caller error, as + * the `@throws` below record. + * + * A parent that joined no preset — a rosterless deployment — yields no join + * and no error: there, the model-facing rows sit in the host composition and + * the child already sees them through the global layer. + * @param agentCtx - the joining agent's scope context. + * @param parentCtx - the scope context of the agent whose composition to join. + * @returns the preset id joined, or undefined when the parent joined none. + * @throws when `agentCtx` carries no scope, or has already joined a preset. + */ +composeFrom(agentCtx: Context, parentCtx: Context): string | undefined + +/** + * The preset one live agent runs on. + * + * Read from the live scope chain rather than from the session, so it answers + * for an agent whose session has not recorded a preset yet — a child agent + * whose durable header is being built from its parent's composition. + * @param agentCtx - the agent's scope context. + * @returns the preset id, or undefined when the agent joined none. + */ +composedPreset(agentCtx: Context): string | undefined + /** * Read one preset's composition text. * @param id - the preset id. diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md index 7cd55b41c8..9c606023c8 100644 --- a/docs/subsystems/core.zh.md +++ b/docs/subsystems/core.zh.md @@ -427,6 +427,45 @@ async resolve(id?: string): Promise */ async mount(agentCtx: Context, id?: string): Promise +/** + * Join one agent to the SAME standing composition another already runs on. + * + * This is how a child agent inherits its parent's capabilities. It is a bind, + * not a mount: the parent's generation is already composed, so the child gets + * that exact instance — the same plugin objects, the same tool registrations, + * the same prompt sections. Re-resolving the parent's preset by id instead + * would re-read the roster, and a composition file edited since the parent + * started would hand the child a DIFFERENT generation than the one its + * parent's history was produced under (and a preset deleted since would fail + * the child outright while its parent keeps running). + * + * Synchronous, and with no composition failure mode of its own — it reads no + * roster, mounts nothing, and touches no file — which is what lets a child + * creation window use it: the two in-process subagent drivers compose their + * children inside a synchronous `setup`. It still rejects a caller error, as + * the `@throws` below record. + * + * A parent that joined no preset — a rosterless deployment — yields no join + * and no error: there, the model-facing rows sit in the host composition and + * the child already sees them through the global layer. + * @param agentCtx - the joining agent's scope context. + * @param parentCtx - the scope context of the agent whose composition to join. + * @returns the preset id joined, or undefined when the parent joined none. + * @throws when `agentCtx` carries no scope, or has already joined a preset. + */ +composeFrom(agentCtx: Context, parentCtx: Context): string | undefined + +/** + * The preset one live agent runs on. + * + * Read from the live scope chain rather than from the session, so it answers + * for an agent whose session has not recorded a preset yet — a child agent + * whose durable header is being built from its parent's composition. + * @param agentCtx - the agent's scope context. + * @returns the preset id, or undefined when the agent joined none. + */ +composedPreset(agentCtx: Context): string | undefined + /** * Read one preset's composition text. * @param id - the preset id. diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml index 3f7e33a795..fbf617f20a 100644 --- a/docs/subsystems/tools.i18n.yaml +++ b/docs/subsystems/tools.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/tools.md -tools.md: f8d86704a2237219530c8c23b46a68383458e1cf -tools.zh.md: 87269e5532b0cdfb0a38501d7b98c9986665df1d +tools.md: 6ff2d967c5631d096dd78236ffd0383ddb2b0493 +tools.zh.md: 82ade5d8d4117387138296cf54fbc8e88ad335e7 diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md index f8d86704a2..6ff2d967c5 100644 --- a/docs/subsystems/tools.md +++ b/docs/subsystems/tools.md @@ -150,19 +150,20 @@ type InferArgs = InferProperties Registration is a trusted same-process contract. The registry borrows the typed definition as readonly input, requires `output`, validates its raw schema, and checks semantic requirements such as a positive finite `timeoutMs`; `schemas()` constructs the model-facing projection when building a request, so execution and presentation share one resolved definition without leaking callbacks onto the wire. -## `ToolRestriction` — one scope's live global filter +## `ToolRestriction` — one scope's live filter over what it inherits -`ToolRestriction` applies only to the live deployment-global tool layer. The registry compiles readonly names into private sets, intersects multiple restrictions, then overlays scope-local tools. A deny-only filter admits later unlisted globals, while an allow-list excludes them. +`ToolRestriction` applies to the tools a scope inherits: the deployment-global layer plus every ancestor scope on its chain. The registry compiles readonly names into private sets, intersects multiple restrictions, then overlays the scope's OWN registrations, which stay exempt so a delegated child keeps the tools it answers through. A deny-only filter admits later unlisted inherited tools, while an allow-list excludes them. ```ts type-equiv /** - * Per-scope filter over global tools. Restrictions intersect and do not affect - * scoped registrations or the reserved Code Mode transport. + * Per-scope filter over the tools a scope INHERITS — the global layer and + * every ancestor layer on its chain. Restrictions intersect, and do not affect + * the scope's own registrations or the reserved Code Mode transport. */ interface ToolRestriction { - /** Global tool names that stay visible; everything else is removed. */ + /** Inherited tool names that stay visible; every other inherited one is removed. */ readonly allow?: readonly string[] - /** Global tool names removed from visibility. */ + /** Inherited tool names removed from visibility. */ readonly deny?: readonly string[] } ``` @@ -565,7 +566,7 @@ async execute(exec: ToolExecutionInput): Promise Types: [ScopeKey](scope.md) -Source: [`packages/core/tools/src/index.ts:760`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:761`](../../packages/core/tools/src/index.ts) diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md index 87269e5532..82ade5d8d4 100644 --- a/docs/subsystems/tools.zh.md +++ b/docs/subsystems/tools.zh.md @@ -150,19 +150,20 @@ type InferArgs = InferProperties 注册是一项受信任的同进程约定。注册表以 readonly 输入借用已类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在构建请求时生成面向模型的投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。 -## `ToolRestriction` — 单个作用域的实时全局过滤器 +## `ToolRestriction` — 单个作用域对其继承内容的实时过滤器 -`ToolRestriction` 仅作用于实时的部署全局工具层。注册表将 readonly 名称编译为私有集合，对多个限制取交集，再叠加作用域本地工具。仅 deny 的过滤器允许后续未列出的全局工具通过，而 allow 列表则排除它们。 +`ToolRestriction` 作用于该作用域继承来的工具：部署全局层，加上其链上的每个祖先作用域。注册表将 readonly 名称编译为私有集合，对多个限制取交集，再叠加该作用域**自身**的注册——后者不受约束，因此被委派的子 agent 会保留其回报所依赖的工具。仅 deny 的过滤器允许后续未列出的继承工具通过，而 allow 列表则排除它们。 ```ts type-equiv /** - * Per-scope filter over global tools. Restrictions intersect and do not affect - * scoped registrations or the reserved Code Mode transport. + * Per-scope filter over the tools a scope INHERITS — the global layer and + * every ancestor layer on its chain. Restrictions intersect, and do not affect + * the scope's own registrations or the reserved Code Mode transport. */ interface ToolRestriction { - /** Global tool names that stay visible; everything else is removed. */ + /** Inherited tool names that stay visible; every other inherited one is removed. */ readonly allow?: readonly string[] - /** Global tool names removed from visibility. */ + /** Inherited tool names removed from visibility. */ readonly deny?: readonly string[] } ``` @@ -565,7 +566,7 @@ async execute(exec: ToolExecutionInput): Promise Types: [ScopeKey](scope.md) -Source: [`packages/core/tools/src/index.ts:760`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:761`](../../packages/core/tools/src/index.ts) diff --git a/packages/client/ui-agent-preset/README.i18n.yaml b/packages/client/ui-agent-preset/README.i18n.yaml index 6943e47673..ca91d9f97e 100644 --- a/packages/client/ui-agent-preset/README.i18n.yaml +++ b/packages/client/ui-agent-preset/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-agent-preset/README.md -README.md: 32a4e7d9e25d3c70d2cc2e8a01c94d093d19659c -README.zh.md: b65a1bdf926f7a34bc3813833ca5ac2d3b6dfabd +README.md: 008066114e9c49e5c74299979e24c27a4c9621c9 +README.zh.md: e07d5994ae196cd03be7818fe4ade1aafda9aa55 diff --git a/packages/client/ui-agent-preset/README.md b/packages/client/ui-agent-preset/README.md index 32a4e7d9e2..008066114e 100644 --- a/packages/client/ui-agent-preset/README.md +++ b/packages/client/ui-agent-preset/README.md @@ -26,6 +26,8 @@ Options and the current default both come from one `agentPreset.list` call. The A locally authored preset is exactly as privileged as the plugins it names, so the list marks `user` rows rather than presenting every preset as shipped and vetted. +Preset files publish one unlocalized `name` and `description`, which Web uses for every `user` row and unknown `system` row. For the four shipped ids (`standard`, `code`, `minimal`, and `cordis`), Web resolves both fields from its active locale only when the roster marks the row `system`; an identically named `user` preset keeps its file metadata. + The row re-reads on `settings/changed` for its own namespace and on `connection/reset`: the roster is a live directory and the default is a settings field, so an external edit or a reconnect can both move it. ## The management section diff --git a/packages/client/ui-agent-preset/README.zh.md b/packages/client/ui-agent-preset/README.zh.md index b65a1bdf92..e07d5994ae 100644 --- a/packages/client/ui-agent-preset/README.zh.md +++ b/packages/client/ui-agent-preset/README.zh.md @@ -26,6 +26,8 @@ chip 以部署默认值打开，其选择是**暂存**的——该界面先于 本地创作的 preset 的权限恰好等于它所引用的插件，因此列表会标注 `user` 行，而不是把每个 preset 都呈现为随附且已审核的。 +preset 文件提供一套未国际化的 `name` 与 `description`，Web 将其用于所有 `user` 行和未知的 `system` 行。对于四个随附 id（`standard`、`code`、`minimal` 与 `cordis`），只有名单将该行标记为 `system` 时，Web 才会从当前 locale 解析这两个字段；同名的 `user` preset 仍使用其文件元数据。 + 本行在自身命名空间的 `settings/changed` 以及 `connection/reset` 时重新读取：名单是一个活动目录，默认值是一项设置，外部编辑与重新连接都可能改变它。 ## 管理分区 diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx index 82688dd7c2..517a856e9a 100644 --- a/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx +++ b/packages/client/ui-agent-preset/src/client/AgentPresetLabel.tsx @@ -15,6 +15,7 @@ import { IconThinkOutline16 } from '@deepseek-ai/dsh-client-ui-primitives' // Type-only: pulls the ui-conversation SlotMap merge (the header actions). import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' import type { AgentPresetSettingsState } from './settings-store.ts' +import { presetDisplayText } from './locales.ts' import css from './AgentPresetLabel.module.css' /** Registration-side business face for the header label. */ @@ -53,10 +54,11 @@ export function AgentPresetLabel({ if (preset === undefined) return null const option = options.find(entry => entry.id === preset) + const text = option === undefined ? undefined : presetDisplayText(option, t) return ( - + - {option?.name ?? preset} + {text?.name ?? preset} ) } diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx index ba875b0b95..eab363122c 100644 --- a/packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx +++ b/packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx @@ -8,7 +8,7 @@ import { useEffect, useState } from 'react' import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' import type { AgentPresetSettingsState } from './settings-store.ts' -import type { AgentPresetSettingsKey } from './locales.ts' +import { presetDisplayText, type AgentPresetSettingsKey } from './locales.ts' import { PresetMenu } from './PresetMenu.tsx' import css from './AgentPresetRow.module.css' @@ -52,11 +52,11 @@ export function AgentPresetRow({ load, select, useAgentPreset, t }: AgentPresetR // every session shares the host composition — the row simply does not exist. if (state.status === 'unavailable') return null const busy = state.status === 'loading' || state.status === 'saving' - // The metadata name is what every other surface shows — the id is the - // addressing, not the label. A preset that names itself nothing falls back - // to its id, which is then all there is to say about it. + // Every preset surface applies the same display-copy rule. The id remains + // addressing rather than a label, except where no display name exists. const chosen = state.options.find(option => option.id === state.currentValue) - const label = state.currentValue === '' ? t('loading') : (chosen?.name ?? state.currentValue) + const chosenText = chosen === undefined ? undefined : presetDisplayText(chosen, t) + const label = state.currentValue === '' ? t('loading') : (chosenText?.name ?? state.currentValue) const description: string = state.error ?? t('description') return ( @@ -69,7 +69,7 @@ export function AgentPresetRow({ load, select, useAgentPreset, t }: AgentPresetR options={state.options} selectedId={state.currentValue} label={label} - userTrustLabel={t('userTrust')} + t={t} buttonClassName={css.selector} chevronClassName={css.chevron} disabled={busy || !state.writable || state.options.length === 0} diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx index 8e18471fbc..f4357870bb 100644 --- a/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx +++ b/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx @@ -19,6 +19,7 @@ import { IconChevronDownOutline14, IconThinkOutline16, Menu } from '@deepseek-ai // Type-only: pulls the ui-conversation SlotMap merge (the hero seat). import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' import type { AgentPresetSeatState } from './seat-store.ts' +import { presetDisplayText } from './locales.ts' import css from './AgentPresetSeat.module.css' /** Registration-side business face for the hero chip. */ @@ -57,22 +58,26 @@ export function AgentPresetSeat({ load, select, useAgentPresetSeat, t }: AgentPr if (state.options.length === 0 || state.current === '') return null const chosen = state.options.find(option => option.id === state.current) + const chosenText = chosen === undefined ? undefined : presetDisplayText(chosen, t) return ( { setOpen(false) }} - items={state.options.map(option => ({ - id: option.id, - // Name and description together: the id alone never said what a - // preset does, which is the whole reason the metadata exists. - label: ( - - {option.name ?? option.id} - {option.description ?? t('noDescription')} - - ), - }))} + items={state.options.map((option) => { + const text = presetDisplayText(option, t) + return { + id: option.id, + // Name and description together: the id alone never says what a + // preset does, which is why the roster carries display copy. + label: ( + + {text.name} + {text.description ?? t('noDescription')} + + ), + } + })} selectedId={state.current} onSelect={(id) => { setOpen(false) @@ -91,7 +96,7 @@ export function AgentPresetSeat({ load, select, useAgentPresetSeat, t }: AgentPr onClick={() => { setOpen(value => !value) }} > - {chosen?.name ?? state.current} + {chosenText?.name ?? state.current} )} diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx index 3a9d0b960a..f5a31fcdf8 100644 --- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx +++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx @@ -18,7 +18,7 @@ import { import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' import { draftBlocker, type AgentPresetSectionState } from './section-store.ts' -import type { AgentPresetSettingsKey } from './locales.ts' +import { presetDisplayText, type AgentPresetSettingsKey } from './locales.ts' import css from './AgentPresetSection.module.css' /** Registration-side business face for the management section. */ @@ -77,11 +77,13 @@ function CopyDialog({ state, t, actions }: CopyDialogProps): ReactNode { const draft = state.copy const blocker = draft === null ? undefined : draftBlocker(draft, state.rows) const message = draft === null ? null : draft.error ?? (blocker === undefined ? null : t(blocker)) + const source = draft === null ? undefined : state.rows.find(row => row.id === draft.from) + const sourceTitle = source === undefined ? draft?.fromTitle : presetDisplayText(source, t).name return ( { actions.cancelCopy() }} - title={draft === null ? t('copyTitle') : `${t('copyTitle')} · ${t('copyOf')} ${draft.fromTitle}`} + title={draft === null ? t('copyTitle') : `${t('copyTitle')} · ${t('copyOf')} ${sourceTitle}`} closeLabel={t('close')} description={t('copyIntro')} className={css.dialog as string} @@ -143,6 +145,11 @@ function CopyDialog({ state, t, actions }: CopyDialogProps): ReactNode { export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode { const { useAgentPresetSection, t, load } = props const state = useAgentPresetSection(snapshot => snapshot) + const viewedId = state.view?.id + const viewedRow = viewedId === undefined ? undefined : state.rows.find(row => row.id === viewedId) + const viewedTitle = state.view === null + ? '' + : viewedRow === undefined ? state.view.title : presetDisplayText(viewedRow, t).name useEffect(() => { void load() @@ -170,13 +177,15 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {

{t('sectionIntro')}

{state.error === null ? null :

{state.error}

} {([['system', t('builtInGroup')], ['user', t('customGroup')]] as const).map(([trust, heading]) => { - const group = state.rows.filter(row => row.trust === trust) + const group = state.rows + .filter(row => row.trust === trust) + .map(row => ({ row, text: presetDisplayText(row, t) })) if (group.length === 0) return null return (

{heading}

    - {group.map(row => ( + {group.map(({ row, text }) => (
  • { void props.makeDefault(row.id) }} > - {row.name ?? row.id} + {text.name} {row.broken !== undefined ? {t('brokenBadge')} : null} @@ -210,7 +219,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode { {row.isDefault ? {t('inUse')} : null} - {row.description ?? t('noDescription')} + {text.description ?? t('noDescription')} {row.broken === undefined ? null : {row.broken}} @@ -231,7 +240,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode { type="button" className={css.iconButton} data-tip={t('view')} - aria-label={`${t('view')}: ${row.name ?? row.id}`} + aria-label={`${t('view')}: ${text.name}`} onClick={() => { void props.view(row.id) }} > @@ -243,7 +252,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode { type="button" className={css.iconButton} data-tip={state.hasDocument ? t('openLocation') : t('showLocation')} - aria-label={`${state.hasDocument ? t('openLocation') : t('showLocation')}: ${row.name ?? row.id}`} + aria-label={`${state.hasDocument ? t('openLocation') : t('showLocation')}: ${text.name}`} onClick={() => { void props.openLocation(row.id) }} > @@ -256,7 +265,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode { data-tip={row.broken !== undefined ? t('brokenNoCopy') : state.authorable ? t('duplicate') : t('duplicateUnavailable')} - aria-label={`${t('duplicate')}: ${row.name ?? row.id}`} + aria-label={`${t('duplicate')}: ${text.name}`} onClick={() => { props.beginCopy(row.id) }} > @@ -267,7 +276,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode { type="button" className={`${css.iconButton} ${css.iconDanger}`} data-tip={t('delete')} - aria-label={`${t('delete')}: ${row.name ?? row.id}`} + aria-label={`${t('delete')}: ${text.name}`} onClick={() => { props.confirmDelete(row.id) }} > @@ -325,7 +334,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode { { props.closeView() }} - title={state.view === null ? '' : `${t('view')} · ${state.view.title}`} + title={state.view === null ? '' : `${t('view')} · ${viewedTitle}`} closeLabel={t('close')} description={t('composition')} className={css.dialog as string} diff --git a/packages/client/ui-agent-preset/src/client/PresetMenu.tsx b/packages/client/ui-agent-preset/src/client/PresetMenu.tsx index 2a6bc6ea28..4b78d8ce6e 100644 --- a/packages/client/ui-agent-preset/src/client/PresetMenu.tsx +++ b/packages/client/ui-agent-preset/src/client/PresetMenu.tsx @@ -11,6 +11,7 @@ import { IconChevronDownOutline14, Menu } from '@deepseek-ai/dsh-client-ui-primitives' import type { AgentPresetOption } from './settings-store.ts' +import { presetDisplayText, type AgentPresetSettingsKey } from './locales.ts' /** What one surface passes to the shared picker. */ export interface PresetMenuProps { @@ -20,8 +21,8 @@ export interface PresetMenuProps { selectedId: string /** Text on the button; the surfaces word a pending roster differently. */ label: string - /** Suffix marking a locally authored preset in the menu. */ - userTrustLabel: string + /** Active Web locale lookup. */ + t: (key: AgentPresetSettingsKey) => string /** Class for the trigger button, owned by the calling surface. */ buttonClassName: string | undefined /** Class for the chevron, owned by the calling surface. */ @@ -42,22 +43,22 @@ export interface PresetMenuProps { * @returns the menu and its trigger. */ export function PresetMenu({ - options, selectedId, label, userTrustLabel, buttonClassName, chevronClassName, + options, selectedId, label, t, buttonClassName, chevronClassName, disabled, open, onOpenChange, onSelect, }: PresetMenuProps) { return ( { onOpenChange(false) }} - items={options.map(option => ({ - id: option.id, - // The metadata name is what every surface shows; the id is addressing, - // not a label. A preset that names itself nothing falls back to its id, - // which is then all there is to say about it. - label: option.trust === 'user' - ? `${option.name ?? option.id} · ${userTrustLabel}` - : option.name ?? option.id, - }))} + items={options.map((option) => { + const name = presetDisplayText(option, t).name + return { + id: option.id, + // All preset surfaces resolve copy the same way; the id is addressing, + // not a label, except where no display name exists. + label: option.trust === 'user' ? `${name} · ${t('userTrust')}` : name, + } + })} selectedId={selectedId} onSelect={(id) => { onOpenChange(false) diff --git a/packages/client/ui-agent-preset/src/client/index.ts b/packages/client/ui-agent-preset/src/client/index.ts index 97a7f66ce2..913639e9ab 100644 --- a/packages/client/ui-agent-preset/src/client/index.ts +++ b/packages/client/ui-agent-preset/src/client/index.ts @@ -157,7 +157,8 @@ export function apply(ctx: ClientContext): void { const label = scope.slots.register({ name: 'conversation.session.header.actions', id: 'agent-preset', - order: 20, + // Static session context occupies the header's leading negative-order band. + order: -10, locale: 'settings.agentPreset', inject: labelInjected, }, AgentPresetLabel) diff --git a/packages/client/ui-agent-preset/src/client/locales.ts b/packages/client/ui-agent-preset/src/client/locales.ts index 50a4e36138..0fab8db94b 100644 --- a/packages/client/ui-agent-preset/src/client/locales.ts +++ b/packages/client/ui-agent-preset/src/client/locales.ts @@ -4,6 +4,10 @@ export type AgentPresetSettingsKey = | 'title' | 'description' | 'loading' | 'error' | 'userTrust' | 'seatHint' | 'headerHint' | 'nav' | 'sectionIntro' | 'builtIn' | 'setDefault' | 'view' + | 'presetStandardName' | 'presetStandardDescription' + | 'presetCodeName' | 'presetCodeDescription' + | 'presetMinimalName' | 'presetMinimalDescription' + | 'presetCordisName' | 'presetCordisDescription' | 'duplicate' | 'duplicateUnavailable' | 'delete' | 'presetId' | 'presetIdPlaceholder' | 'copyOf' | 'displayName' | 'displayNamePlaceholder' | 'inUse' | 'noDescription' | 'builtInGroup' | 'customGroup' @@ -30,6 +34,18 @@ export const en: Record = { builtIn: 'Built-in', setDefault: 'Set as default', view: 'View', + presetStandardName: 'Standard mode', + presetStandardDescription: + 'Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.', + presetCodeName: 'Code mode', + presetCodeDescription: + 'All Standard mode capabilities, with tools exposed through the Code Mode SDK so the model can combine multi-step operations in one TypeScript program.', + presetMinimalName: 'Minimal mode', + presetMinimalDescription: + 'Two-tool coding agent with only bash and str_replace_editor, for benchmarks and minimal reproductions.', + presetCordisName: 'Creator mode', + presetCordisDescription: + 'Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, plugin experiments, and preset-authoring guidance.', duplicate: 'Duplicate', duplicateUnavailable: 'This deployment has no writable preset directory', delete: 'Delete', @@ -82,6 +98,14 @@ export const zh: Record = { builtIn: '内置', setDefault: '设为默认', view: '查看', + presetStandardName: '标准模式', + presetStandardDescription: '功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。', + presetCodeName: '代码模式', + presetCodeDescription: '具备标准模式的全部能力，并通过 Code Mode SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。', + presetMinimalName: '极简模式', + presetMinimalDescription: '仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。', + presetCordisName: '创造模式', + presetCordisDescription: '用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、插件实验和 preset 创作指导。', duplicate: '复制', duplicateUnavailable: '此部署未配置可写的预设目录', delete: '删除', @@ -116,3 +140,53 @@ export const zh: Record = { deleteConfirm: '删除', deleting: '正在删除…', } + +/** Preset roster fields needed to resolve Web display copy. */ +export interface PresetDisplaySource { + /** Stable preset id. */ + readonly id: string + /** Whether the deployment ships the preset or the user owns it. */ + readonly trust: 'system' | 'user' + /** Unlocalized name published by the preset. */ + readonly name?: string + /** Unlocalized description published by the preset. */ + readonly description?: string +} + +/** Display copy resolved for the active Web locale. */ +export interface PresetDisplayText { + /** Localized built-in name or the preset's own fallback name. */ + readonly name: string + /** Localized built-in description or the preset's own description. */ + readonly description?: string +} + +interface PresetLocaleKeys { + readonly name: AgentPresetSettingsKey + readonly description: AgentPresetSettingsKey +} + +const BUILT_IN_PRESET_KEYS: Readonly>> = { + standard: { name: 'presetStandardName', description: 'presetStandardDescription' }, + code: { name: 'presetCodeName', description: 'presetCodeDescription' }, + minimal: { name: 'presetMinimalName', description: 'presetMinimalDescription' }, + cordis: { name: 'presetCordisName', description: 'presetCordisDescription' }, +} + +/** + * Resolve preset display copy without making user-authored metadata translatable. + * @param preset - roster row whose copy is being rendered. + * @param t - active Web locale lookup. + * @returns localized copy for a known shipped preset, otherwise file metadata. + */ +export function presetDisplayText( + preset: PresetDisplaySource, + t: (key: AgentPresetSettingsKey) => string, +): PresetDisplayText { + const keys = preset.trust === 'system' ? BUILT_IN_PRESET_KEYS[preset.id] : undefined + if (keys !== undefined) return { name: t(keys.name), description: t(keys.description) } + return { + name: preset.name ?? preset.id, + ...preset.description === undefined ? {} : { description: preset.description }, + } +} diff --git a/packages/client/ui-agent-preset/tests/apply.spec.ts b/packages/client/ui-agent-preset/tests/apply.spec.ts index 6272501183..23e1944948 100644 --- a/packages/client/ui-agent-preset/tests/apply.spec.ts +++ b/packages/client/ui-agent-preset/tests/apply.spec.ts @@ -304,7 +304,7 @@ describe('ui-agent-preset apply', () => { expect(chip.component).toBe(AgentPresetSeat) const label = slots.entries('conversation.session.header.actions')[0]! expect(label.component).toBe(AgentPresetLabel) - expect(label.options).toMatchObject({ id: 'agent-preset', order: 20 }) + expect(label.options).toMatchObject({ id: 'agent-preset', order: -10 }) await fiber.dispose() expect(slots.entries('conversation.hero.agentPreset')).toHaveLength(0) expect(slots.entries('conversation.session.header.actions')).toHaveLength(0) diff --git a/packages/client/ui-agent-preset/tests/components.spec.tsx b/packages/client/ui-agent-preset/tests/components.spec.tsx index 7bc3d59e04..8a37a7af43 100644 --- a/packages/client/ui-agent-preset/tests/components.spec.tsx +++ b/packages/client/ui-agent-preset/tests/components.spec.tsx @@ -90,7 +90,7 @@ describe('the General-settings row', () => { const actions = renderRow() await waitFor(() => { expect(actions.load).toHaveBeenCalledTimes(1) }) - expect(screen.getByRole('button').textContent).toContain('标准模式') + expect(screen.getByRole('button').textContent).toContain(en.presetStandardName) }) it('marks a locally authored option as local', () => { @@ -102,7 +102,7 @@ describe('the General-settings row', () => { // list says which rows are local rather than presenting all as vetted. expect(screen.getByText(`mine · ${en.userTrust}`)).toBeTruthy() // The shipped one carries no marker; only local rows are called out. - expect(screen.getAllByText('标准模式')).toHaveLength(2) + expect(screen.getAllByText(en.presetStandardName)).toHaveLength(2) }) it('falls back to the id for a preset that published no name', () => { @@ -128,6 +128,12 @@ describe('the General-settings row', () => { expect(screen.getByText('bare')).toBeTruthy() }) + it('shows the selected id until a stale roster contains it', () => { + renderRow({ currentValue: 'arriving', options: [] }) + + expect(screen.getByRole('button').textContent).toContain('arriving') + }) + it('writes the picked preset and closes the menu', () => { const actions = renderRow() fireEvent.click(screen.getByRole('button')) @@ -194,7 +200,7 @@ describe('the new-session chip', () => { const actions = renderSeat() await waitFor(() => { expect(actions.load).toHaveBeenCalledTimes(1) }) - expect(screen.getByRole('button').textContent).toContain('标准模式') + expect(screen.getByRole('button').textContent).toContain(en.presetStandardName) expect(screen.getByRole('button').getAttribute('title')).toBe(en.seatHint) }) @@ -205,7 +211,7 @@ describe('the new-session chip', () => { // The id alone never said what a preset does; the description is the // whole reason a preset can publish metadata at all. - expect(screen.getByText('完整的编码 agent。')).toBeTruthy() + expect(screen.getByText(en.presetStandardDescription)).toBeTruthy() // A preset that published none still reads as a row, with its id standing // in for the name. expect(screen.getByText(en.noDescription)).toBeTruthy() @@ -218,6 +224,12 @@ describe('the new-session chip', () => { expect(screen.getByRole('button').textContent).toContain('mine') }) + it('shows the staged id until a stale roster contains it', () => { + renderSeat({ current: 'arriving' }) + + expect(screen.getByRole('button').textContent).toContain('arriving') + }) + it('stages the picked preset and closes the menu', () => { const actions = renderSeat() fireEvent.click(screen.getByRole('button')) @@ -267,7 +279,7 @@ describe('the session-header label', () => { await waitFor(() => { expect(load).toHaveBeenCalledTimes(1) }) // A control here would promise a switch the host refuses outright. expect(screen.queryByRole('button')).toBeNull() - expect(screen.getByTitle('完整的编码 agent。').textContent).toBe('标准模式') + expect(screen.getByTitle(en.presetStandardDescription).textContent).toBe(en.presetStandardName) }) it('falls back to the id, and to the generic hint, when metadata is absent', () => { diff --git a/packages/client/ui-agent-preset/tests/locales.spec.ts b/packages/client/ui-agent-preset/tests/locales.spec.ts new file mode 100644 index 0000000000..02623e7d7b --- /dev/null +++ b/packages/client/ui-agent-preset/tests/locales.spec.ts @@ -0,0 +1,33 @@ +/** Web-localized copy for the four shipped presets and file copy for every other row. */ + +import { describe, expect, it } from 'vitest' +import { en, presetDisplayText, zh } from '../src/client/locales.ts' + +const translate = (bundle: typeof en) => (key: keyof typeof en): string => bundle[key] + +describe('preset display copy', () => { + it.each([ + ['standard', 'presetStandardName', 'presetStandardDescription'], + ['code', 'presetCodeName', 'presetCodeDescription'], + ['minimal', 'presetMinimalName', 'presetMinimalDescription'], + ['cordis', 'presetCordisName', 'presetCordisDescription'], + ] as const)('localizes the shipped %s preset in English and Chinese', (id, nameKey, descriptionKey) => { + const preset = { id, trust: 'system' as const, name: 'file name', description: 'file description' } + + expect(presetDisplayText(preset, translate(en))) + .toEqual({ name: en[nameKey], description: en[descriptionKey] }) + expect(presetDisplayText(preset, translate(zh))) + .toEqual({ name: zh[nameKey], description: zh[descriptionKey] }) + }) + + it('keeps file metadata for user and unknown system presets', () => { + const fileCopy = { name: '我的标准', description: '团队自己的 preset。' } + + expect(presetDisplayText({ id: 'standard', trust: 'user', ...fileCopy }, translate(en))) + .toEqual(fileCopy) + expect(presetDisplayText({ id: 'deployment-extra', trust: 'system', ...fileCopy }, translate(en))) + .toEqual(fileCopy) + expect(presetDisplayText({ id: 'bare', trust: 'user' }, translate(en))) + .toEqual({ name: 'bare' }) + }) +}) diff --git a/packages/client/ui-agent-preset/tests/section.spec.tsx b/packages/client/ui-agent-preset/tests/section.spec.tsx index 36e34067b3..05c2b28d67 100644 --- a/packages/client/ui-agent-preset/tests/section.spec.tsx +++ b/packages/client/ui-agent-preset/tests/section.spec.tsx @@ -85,13 +85,13 @@ describe('the preset list', () => { await waitFor(() => { expect(actions.load).toHaveBeenCalledTimes(1) }) }) - it('shows the published name and description, falling back to the id', () => { + it('shows resolved copy for built-ins and falls back to custom ids', () => { renderSection() - // The name is what a picker reads; the id stays visible as the key the + // Display copy is what a picker reads; the id stays visible as the key the // composition and the session header actually carry. - expect(screen.getByText('标准模式')).toBeTruthy() - expect(screen.getByText('完整的编码 agent。')).toBeTruthy() + expect(screen.getByText(en.presetStandardName)).toBeTruthy() + expect(screen.getByText(en.presetStandardDescription)).toBeTruthy() const mine = rowFor('mine') expect(within(mine).getAllByText('mine').length).toBeGreaterThan(0) expect(within(mine).getByText(en.noDescription)).toBeTruthy() @@ -134,7 +134,7 @@ describe('the preset list', () => { it('picks a preset by clicking its card, and the one in use is inert', () => { const actions = renderSection() - const inUse = within(rowFor('standard')).getByRole('button', { name: `${en.inUse}: 标准模式` }) + const inUse = within(rowFor('standard')).getByRole('button', { name: `${en.inUse}: ${en.presetStandardName}` }) expect(inUse).toHaveProperty('disabled', true) fireEvent.click(inUse) @@ -150,8 +150,8 @@ describe('the preset list', () => { // the point. A custom preset is edited in its files, so its row leads // there instead; there is no editor for either. const standard = rowFor('standard') - expect(within(standard).getByRole('button', { name: `${en.view}: 标准模式` })).toBeTruthy() - expect(within(standard).queryByRole('button', { name: `${en.openLocation}: 标准模式` })).toBeNull() + expect(within(standard).getByRole('button', { name: `${en.view}: ${en.presetStandardName}` })).toBeTruthy() + expect(within(standard).queryByRole('button', { name: `${en.openLocation}: ${en.presetStandardName}` })).toBeNull() const mine = rowFor('mine') expect(within(mine).getByRole('button', { name: `${en.openLocation}: mine` })).toBeTruthy() expect(within(mine).queryByRole('button', { name: `${en.view}: mine` })).toBeNull() @@ -161,13 +161,13 @@ describe('the preset list', () => { renderSection() expect(within(rowFor('mine')).getByRole('button', { name: `${en.delete}: mine` })).toBeTruthy() - expect(within(rowFor('standard')).queryByRole('button', { name: `${en.delete}: 标准模式` })).toBeNull() + expect(within(rowFor('standard')).queryByRole('button', { name: `${en.delete}: ${en.presetStandardName}` })).toBeNull() }) it('disables duplication when nothing is writable, and says why', () => { renderSection({ authorable: false }) - const duplicate = within(rowFor('standard')).getByRole('button', { name: `${en.duplicate}: 标准模式` }) + const duplicate = within(rowFor('standard')).getByRole('button', { name: `${en.duplicate}: ${en.presetStandardName}` }) expect(duplicate).toHaveProperty('disabled', true) expect(duplicate.getAttribute('data-tip')).toBe(en.duplicateUnavailable) }) @@ -205,7 +205,7 @@ describe('the preset list', () => { // There is no readable composition to offer; the reason on the card is // the whole story a shipped row can tell. const standard = rowFor('standard') - expect(within(standard).queryByRole('button', { name: `${en.view}: 标准模式` })).toBeNull() + expect(within(standard).queryByRole('button', { name: `${en.view}: ${en.presetStandardName}` })).toBeNull() expect(within(standard).getByRole('alert').textContent).toContain('not valid YAML') }) @@ -232,7 +232,7 @@ describe('the preset list', () => { fireEvent.click(within(rowFor('mine')).getByRole('button', { name: `${en.setDefault}: mine` })) fireEvent.click(within(rowFor('mine')).getByRole('button', { name: `${en.openLocation}: mine` })) fireEvent.click(within(rowFor('mine')).getByRole('button', { name: `${en.duplicate}: mine` })) - fireEvent.click(within(rowFor('standard')).getByRole('button', { name: `${en.view}: 标准模式` })) + fireEvent.click(within(rowFor('standard')).getByRole('button', { name: `${en.view}: ${en.presetStandardName}` })) expect(actions.makeDefault).toHaveBeenCalledWith('mine') expect(actions.openLocation).toHaveBeenCalledWith('mine') @@ -311,7 +311,7 @@ describe('the copy dialog', () => { const actions = renderSection({ copy: draft }) const dialog = screen.getByRole('dialog') - expect(dialog.getAttribute('aria-label')).toBe(`${en.copyTitle} · ${en.copyOf} 标准模式`) + expect(dialog.getAttribute('aria-label')).toBe(`${en.copyTitle} · ${en.copyOf} ${en.presetStandardName}`) expect(within(dialog).getByText(en.copyIntro)).toBeTruthy() fireEvent.change(within(dialog).getByPlaceholderText(en.presetIdPlaceholder), { target: { value: 'my-agent' } }) fireEvent.change(within(dialog).getByPlaceholderText(en.displayNamePlaceholder), { target: { value: '我的模式' } }) @@ -374,11 +374,17 @@ describe('the read-only viewer', () => { renderSection({ view: { id: 'standard', title: '标准模式', content: '- id: tool-bash\n' } }) const dialog = screen.getByRole('dialog') - expect(dialog.getAttribute('aria-label')).toBe(`${en.view} · 标准模式`) + expect(dialog.getAttribute('aria-label')).toBe(`${en.view} · ${en.presetStandardName}`) expect(within(dialog).getByText(en.composition)).toBeTruthy() expect(within(dialog).getByText(/tool-bash/).textContent).toBe('- id: tool-bash\n') }) + it('keeps the loaded title when the viewed row leaves the roster', () => { + renderSection({ view: { id: 'retired', title: 'Retired mode', content: '- id: tool-bash\n' } }) + + expect(screen.getByRole('dialog').getAttribute('aria-label')).toBe(`${en.view} · Retired mode`) + }) + it('closes through the controller', () => { const actions = renderSection({ view: { id: 'standard', title: '标准模式', content: '- id: x\n' } }) diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts index c0749fcb46..bbca9254bc 100644 --- a/packages/client/ui-conversation/src/client/contract/slots.ts +++ b/packages/client/ui-conversation/src/client/contract/slots.ts @@ -38,7 +38,11 @@ declare module '@deepseek-ai/dsh-client-ui-slots' { 'conversation.session': { kind: 'single'; scope: 'session' } /** Strict-session header above the resident conversation scrollport. */ 'conversation.session.header': { kind: 'single'; scope: 'session' } - /** Session-header actions contributed by feature plugins. */ + /** + * Session-header actions contributed by feature plugins. Entries render + * by ascending `order`; negative values are reserved for static session + * context that precedes interactive actions. + */ 'conversation.session.header.actions': { kind: 'list'; scope: 'session'; owner: ConversationHeaderActionOwnerProps } /** * The conversation view ring: one list entry per view tab (chat here; diff --git a/packages/context/workspace-context/README.i18n.yaml b/packages/context/workspace-context/README.i18n.yaml index 3cf32ff662..13ea3d4a15 100644 --- a/packages/context/workspace-context/README.i18n.yaml +++ b/packages/context/workspace-context/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/context/workspace-context/README.md -README.md: 7ab21bbf8c72f8424bc8d4fdad9153c7ed8bb7e9 -README.zh.md: eb807bfc0611854d54eda3ff26c97c6af51da529 +README.md: 1ae47bef728a81c61f0db637872c93321a7bc687 +README.zh.md: 8087412057b3e5924764df179ae293db5699f9ae diff --git a/packages/context/workspace-context/README.md b/packages/context/workspace-context/README.md index 7ab21bbf8c..1ae47bef72 100644 --- a/packages/context/workspace-context/README.md +++ b/packages/context/workspace-context/README.md @@ -50,7 +50,7 @@ The plugin owns the complete `` framing, and every injected `us Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; a complete baseline also carries `baseline: true` and a `baselineIdentity` derived from normalized discovery, precedence, project-root, and budget configuration. A matching durable `user/message` confirms a queued baseline and its candidate versions. An entering pre-step waits for every queued projection, folds newly composed context into its final batch immediately after the claimed messages, and removes the pending inbox copy; rejection keeps the current context queued. If a listener rewrites away a claimed workspace message without entering its replacement, a later boundary recomposes the current context. Nested results aggregate successful file touches under their parent execution token, including when a later composite result is blocked; the top-level result transfers those touches either to the currently open session step or directly to the per-agent projection queue. A `step/end` releases its staged touches only after that boundary is in durable history, and serialized projections reconcile against visible session events plus the current inbox before replacing the single pending workspace context. -An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope provider cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the typed source, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter the source, pending state, and version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates only the provider cache. +An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope provider cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the typed source, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. A model-visible change enters the source, pending state, and version cache only when its file-specific section retains at least one content byte, or when its original content is genuinely empty. Partial truncation records the complete-content digest once any content byte survives; truncation to zero remains eligible for a later touch, while a same-digest version refresh updates only the provider cache. A baseline may still publish its budget diagnostic with an empty change list. A dynamic batch with no committed change is not injected at all, and a later touch retries it. The initial baseline event itself is not rewritten. Its typed changes remain authoritative only while that event is in the visible session surface. When compaction shadows the event, the next entering pre-step composes the current baseline and records it in the same request; a successful filesystem touch can instead re-add an unchanged baseline scope or append its replacement or removal. The in-memory scope marker and provider-version cache only select and accelerate probes. At the first pre-step after resume or hot remount, a compatible visible baseline is retained and compared with the files retained by the current complete rendering. Unchanged and budget-omitted files append nothing; offline additions, edits, removals, and files leaving the retained budget set append `set`, `replace`, or `remove` transitions. An incompatible visible baseline is superseded by one complete current baseline, including an explicit empty baseline when no candidate remains. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, when a resumed session reconciles its baseline, or when an entering pre-step restores a shadowed baseline. diff --git a/packages/context/workspace-context/README.zh.md b/packages/context/workspace-context/README.zh.md index eb807bfc06..8087412057 100644 --- a/packages/context/workspace-context/README.zh.md +++ b/packages/context/workspace-context/README.zh.md @@ -50,7 +50,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when 模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会等待所有已排队投影完成，再把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；若被拒绝，当前上下文则继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。即使后续复合结果被拦截，成功的嵌套文件 touch 也会聚合到父级执行 token 下；顶层结果会将这些 touch 交给当前打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界进入持久历史后释放其暂存的 touch；串行投影会根据可见会话事件和当前 inbox 协调状态，再替换唯一一条待处理工作区上下文。 -路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。 +路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。模型可见变更只有在对应文件专属段落保留至少一个内容字节，或原始内容确实为空时，才会进入来源、pending 状态和版本 cache。只要任一内容字节保留下来，部分截断就会记录完整内容的 digest；截断到零字节则仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。基线即使带空变更列表，仍可发布字节预算诊断。动态批次若没有可提交变更，则完全不注入，并在后续 touch 时重试。 初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态。当压缩遮蔽该事件时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中记录它；也可以改由一次成功的文件系统 touch 重新添加未变的基线 scope，或追加其替换或移除。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。恢复或插件热重挂后的第一次 pre-step 会保留兼容的可见基线，并将它与当前完整渲染所保留的文件进行比较。未变化和被预算省略的文件不追加任何内容；agent 离线期间新增、编辑、移除或不再属于预算保留集的文件会追加 `set`、`replace` 或 `remove` 转换。不兼容的可见基线会被一条完整的当前基线取代；如果没有候选文件，这条当前基线会是显式空基线。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在恢复后的会话对账其基线时，或进入步骤的 pre-step 恢复被遮蔽的基线时可见。 diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts index 6c8bfed533..e59b34402b 100644 --- a/packages/context/workspace-context/src/files.ts +++ b/packages/context/workspace-context/src/files.ts @@ -12,7 +12,13 @@ import { assertNever } from '@deepseek-ai/dsh-llm' import { dshHomeDisplay } from '@deepseek-ai/dsh-paths' import { resolveConfig, resolveDiscoveryConfig, type ResolvedConfig } from './config.ts' import { trimmedInstructionDigest } from './digest.ts' -import { decodeScopeKey, renderWorkspaceContext, USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE, type RenderedWorkspaceContext } from './render.ts' +import { + decodeScopeKey, + renderWorkspaceInstructionSet, + type RenderedWorkspaceContext, + USER_GLOBAL_DIRECTORY, + USER_GLOBAL_FILE, +} from './render.ts' /** An instruction candidate identified by absolute and model-facing paths. */ export interface InstructionFile { @@ -64,7 +70,6 @@ export interface RenderedInstructionSet { /** Candidates retained by content deduplication and byte budgeting. */ included: LoadedInstructionFile[] } - /** Tri-state scope probe that distinguishes confirmed absence from provider failure. */ export type ScopeInstructionProbe = | { kind: 'present'; file: ProbedInstructionFile } @@ -420,26 +425,26 @@ export async function loadBaselineInstructionSet( const deduped = dedupInstructionFilesByDirectory(loaded) if (deduped.length === 0) { if (options.replacePreviousBaseline !== true) return undefined + const { rendered, included } = renderWorkspaceInstructionSet([], { + maxBytes: config.maxBytes, + replacePreviousBaseline: true, + }) return { - rendered: renderWorkspaceContext([], { - maxBytes: config.maxBytes, - replacePreviousBaseline: true, - }), + rendered, observed: [], - included: [], + included, } } - const rendered = renderWorkspaceContext(deduped, { + const { rendered, included } = renderWorkspaceInstructionSet(deduped, { maxBytes: config.maxBytes, ...options.replacePreviousBaseline === undefined ? {} : { replacePreviousBaseline: options.replacePreviousBaseline }, }) - const omitted = new Set(rendered.omitted.map(file => file.absolutePath)) return { rendered, observed: loaded, - included: deduped.filter(file => !omitted.has(file.absolutePath)), + included, } } diff --git a/packages/context/workspace-context/src/render.ts b/packages/context/workspace-context/src/render.ts index 7b61f3b8fd..1919446e48 100644 --- a/packages/context/workspace-context/src/render.ts +++ b/packages/context/workspace-context/src/render.ts @@ -32,6 +32,17 @@ export interface RenderedWorkspaceContext { truncated: TruncatedInstruction[] } +interface RenderedInstructionContext extends RenderedWorkspaceContext { + /** + * Original files semantically represented by rendered section text. This is + * not the complement of `omitted`: a truncated file may be represented here + * and in `truncated`, while a notice-only file appears in neither. A genuinely + * empty file counts when its heading survives because that heading conveys + * that the instruction exists and has no content. + */ + represented: LoadedInstructionFile[] +} + /** Structured dynamic state persisted outside model-visible prompt prose. */ export interface WorkspaceInstructionChange { action: 'set' | 'replace' | 'remove' @@ -56,11 +67,15 @@ function byteLength(value: string): number { } function truncateUtf8(value: string, maxBytes: number): string { - let truncated = Buffer.from(value, 'utf8').subarray(0, Math.max(0, maxBytes)).toString('utf8') - while (byteLength(truncated) > maxBytes) { - truncated = truncated.slice(0, -1) + const bytes = Buffer.from(value, 'utf8') + if (bytes.length <= maxBytes) return value + let end = Math.max(0, Math.trunc(maxBytes)) + // If the first excluded byte is a UTF-8 continuation byte, the budget cut + // through that code point. Back up to its lead byte and exclude it too. + while (end > 0 && (bytes.readUInt8(end) & 0xc0) === 0x80) { + end -= 1 } - return truncated + return bytes.subarray(0, end).toString('utf8') } function escapeInstructionFrameBody(body: string): string { @@ -143,6 +158,16 @@ function additionalSectionText(file: LoadedInstructionFile): string { const BASELINE_RENDER_STYLE: RenderStyle = { intro: WORKSPACE_CONTEXT_INTRO, section: sectionText } +function baselineRenderStyle(files: LoadedInstructionFile[], replacePreviousBaseline: boolean | undefined): RenderStyle { + if (replacePreviousBaseline !== true) return BASELINE_RENDER_STYLE + return { + ...BASELINE_RENDER_STYLE, + intro: files.length === 0 + ? EMPTY_REPLACEMENT_WORKSPACE_CONTEXT_INTRO + : REPLACEMENT_WORKSPACE_CONTEXT_INTRO, + } +} + function changedSectionText(item: ChangeRenderItem): string { const { change, file } = item if (change.action === 'set') return additionalSectionText(file) @@ -178,13 +203,12 @@ export function renderInstructionChanges( }, } const rendered = renderInstructionContext(items.map(item => item.file), maxBytes, style) - const omitted = new Set(rendered.omitted.map(file => file.absolutePath)) + const represented = new Set(rendered.represented.map(file => file.absolutePath)) return { text: rendered.text, - // TODO(rendered-change-proof): retain a transition only when its semantic - // notice survived rendering; a tiny compact budget can currently return - // unrelated notice text while still committing the full state transition. - changes: items.filter(item => !omitted.has(item.file.absolutePath)).map(item => item.change), + changes: items + .filter(item => represented.has(item.file.absolutePath)) + .map(item => item.change), } } @@ -252,47 +276,75 @@ function renderInstructionContext( files: LoadedInstructionFile[], maxBytes: number, style: RenderStyle, -): RenderedWorkspaceContext { - if (maxBytes <= 0 || !Number.isFinite(maxBytes)) return { text: '', omitted: files, truncated: [] } +): RenderedInstructionContext { + if (maxBytes <= 0 || !Number.isFinite(maxBytes)) { + return { text: '', omitted: files, truncated: [], represented: [] } + } const fullText = buildInstructionText(files, maxBytes, [], [], style) - if (byteLength(fullText) <= maxBytes) return { text: fullText, omitted: [], truncated: [] } + if (byteLength(fullText) <= maxBytes) { + return { text: fullText, omitted: [], truncated: [], represented: files } + } for (let start = 1; start < files.length; start += 1) { const included = files.slice(start) const omitted = files.slice(0, start).map(file => ({ absolutePath: file.absolutePath, displayPath: file.displayPath })) const suffixText = buildInstructionText(included, maxBytes, omitted, [], style) - if (byteLength(suffixText) <= maxBytes) return { text: suffixText, omitted, truncated: [] } + if (byteLength(suffixText) <= maxBytes) return { text: suffixText, omitted, truncated: [], represented: included } } const mostSpecific = files.at(-1) /* v8 ignore next -- callers only reach this after a non-empty fullText was built. */ - if (mostSpecific === undefined) return { text: '', omitted: [], truncated: [] } + if (mostSpecific === undefined) return { text: '', omitted: [], truncated: [], represented: [] } const omitted = files.slice(0, -1).map(file => ({ absolutePath: file.absolutePath, displayPath: file.displayPath })) + const originalBytes = byteLength(mostSpecific.content) for (const candidateStyle of [style, { ...style, intro: COMPACT_WORKSPACE_CONTEXT_INTRO }]) { const truncatedFile = truncateToFit(mostSpecific, [], maxBytes, omitted, candidateStyle) + const includedBytes = byteLength(truncatedFile.content) const truncated = [{ displayPath: mostSpecific.displayPath, - originalBytes: byteLength(mostSpecific.content), - includedBytes: byteLength(truncatedFile.content), + originalBytes, + includedBytes, }] const text = buildInstructionText([truncatedFile], maxBytes, omitted, truncated, candidateStyle) - if (byteLength(text) <= maxBytes) return { text, omitted, truncated } + if (byteLength(text) <= maxBytes) { + const represented = includedBytes > 0 || originalBytes === 0 ? [mostSpecific] : [] + return { text, omitted, truncated, represented } + } } const truncated = [{ displayPath: mostSpecific.displayPath, - originalBytes: byteLength(mostSpecific.content), + originalBytes, includedBytes: 0, }] const compactNotice = escapeInstructionFrameBody(markerText(maxBytes, omitted, truncated)) const compactWithHeading = escapeInstructionFrameBody( [compactNotice, style.section(withTruncatedContent(mostSpecific, 0))].join('\n\n'), ) - if (byteLength(compactWithHeading) <= maxBytes) return { text: compactWithHeading, omitted, truncated } + if (byteLength(compactWithHeading) <= maxBytes) { + const represented = originalBytes === 0 ? [mostSpecific] : [] + return { text: compactWithHeading, omitted, truncated, represented } + } const text = byteLength(compactNotice) <= maxBytes ? compactNotice : truncateUtf8(compactNotice, maxBytes) - return { text, omitted, truncated } + return { text, omitted, truncated, represented: [] } +} + +/** + * Render a baseline together with the exact source files semantically represented in it. + * @param files - loaded files ordered from broadest to most specific. + * @param options - rendering byte budget and whether this baseline supersedes a visible predecessor. + * @returns bounded public rendering plus files with surviving content, including genuinely empty files. + * @internal + */ +export function renderWorkspaceInstructionSet( + files: LoadedInstructionFile[], + options: { maxBytes: number; replacePreviousBaseline?: boolean }, +): { rendered: RenderedWorkspaceContext; included: LoadedInstructionFile[] } { + const style = baselineRenderStyle(files, options.replacePreviousBaseline) + const { represented, ...rendered } = renderInstructionContext(files, options.maxBytes, style) + return { rendered, included: represented } } /** @@ -305,13 +357,5 @@ export function renderWorkspaceContext( files: LoadedInstructionFile[], options: { maxBytes: number; replacePreviousBaseline?: boolean }, ): RenderedWorkspaceContext { - const style = options.replacePreviousBaseline === true - ? { - ...BASELINE_RENDER_STYLE, - intro: files.length === 0 - ? EMPTY_REPLACEMENT_WORKSPACE_CONTEXT_INTRO - : REPLACEMENT_WORKSPACE_CONTEXT_INTRO, - } - : BASELINE_RENDER_STYLE - return renderInstructionContext(files, options.maxBytes, style) + return renderWorkspaceInstructionSet(files, options).rendered } diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts index 20343c9512..0db248bfe6 100644 --- a/packages/context/workspace-context/src/state.ts +++ b/packages/context/workspace-context/src/state.ts @@ -422,6 +422,10 @@ export async function reconcileInstructionContext( } if (items.length === 0) return undefined const rendered = renderInstructionChanges(items, resolved.maxBytes) + // When no transition survived rendering (tiny budgets render notice-only + // text), emit nothing and commit nothing — the uncommitted versions make the + // next pass retry instead of spamming notice-only contexts. + if (rendered.text.length === 0 || rendered.changes.length === 0) return undefined return { context: workspaceContextHook(rendered.text, rendered.changes), versionUpdates: retainedInstructionVersionUpdates(versionUpdates, rendered.changes), diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index 71073264cd..a40d3aec9a 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -40,7 +40,7 @@ import { type InstructionVersionCache, } from '../src/state.ts' import { resolveConfig } from '../src/config.ts' -import { candidateScopeKey, renderInstructionChanges, USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE } from '../src/render.ts' +import { candidateScopeKey, renderInstructionChanges, renderWorkspaceInstructionSet, USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE } from '../src/render.ts' import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' /** Per-candidate reconciliation scope key: directory paired with the file name. */ @@ -855,6 +855,33 @@ describe('workspace context rendering', () => { expect(Buffer.byteLength(rendered.text, 'utf8')).toBe(120) }) + it('represents a genuinely empty instruction when its compact heading fits', () => { + const file = { absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: '' } + const rendered = renderWorkspaceInstructionSet([file], { maxBytes: 117 }) + + expect(rendered.rendered.text).toContain('truncated pkg/AGENTS.md from 0 to 0 bytes') + expect(rendered.rendered.text).toContain('Instructions from: pkg/AGENTS.md') + expect(rendered.included).toEqual([file]) + }) + + it('represents a genuinely empty instruction through the framed compact-intro path', () => { + const file = { + absolutePath: '/repo/pkg/AGENTS.md', + displayPath: 'pkg/AGENTS.md', + content: '', + } + + const rendered = renderWorkspaceInstructionSet([file], { maxBytes: 300 }) + + expect(rendered.rendered.text).toContain('') + expect(rendered.rendered.text).toContain('Workspace instructions were omitted or truncated') + expect(rendered.rendered.text).toContain('Instructions from: pkg/AGENTS.md') + expect(rendered.rendered.truncated).toEqual([ + { displayPath: 'pkg/AGENTS.md', originalBytes: 0, includedBytes: 0 }, + ]) + expect(rendered.included).toEqual([file]) + }) + it('truncates the compact notice itself when the render budget is smaller than the notice', () => { const rendered = renderWorkspaceContext([ { absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'x'.repeat(1000) }, @@ -865,6 +892,76 @@ describe('workspace context rendering', () => { expect(Buffer.byteLength(rendered.text, 'utf8')).toBe(20) }) + it('does not commit a change when only the generic compact notice survives', () => { + const change = { + action: 'set' as const, + scope: sk('pkg', 'AGENTS.md'), + path: 'pkg/AGENTS.md', + digest: 'digest', + } + const rendered = renderInstructionChanges([{ + change, + file: { absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'x'.repeat(1000) }, + }], 20) + + expect(rendered.text).toBe('Workspace instructio') + expect(rendered.changes).toEqual([]) + }) + + it('commits a change when its file-specific semantic section survives truncation', () => { + const change = { + action: 'replace' as const, + scope: sk('pkg', 'AGENTS.md'), + path: 'pkg/AGENTS.md', + digest: 'digest', + } + const rendered = renderInstructionChanges([{ + change, + file: { absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'x'.repeat(1000) }, + }], 400) + + expect(rendered.text).toContain('Updated instructions from: pkg/AGENTS.md') + expect(rendered.changes).toEqual([change]) + }) + + // Each prose-derived budget is the smallest current value that retains the named heading plus a zero-byte marker. + it.each([ + { action: 'set' as const, maxBytes: 327, heading: 'Additional instructions from:' }, + { action: 'replace' as const, maxBytes: 256, heading: 'Updated instructions from:' }, + ])('does not commit a $action change when its heading survives with zero content bytes', ({ action, maxBytes, heading }) => { + const change = { + action, + scope: sk('pkg', 'AGENTS.md'), + path: 'pkg/AGENTS.md', + digest: 'digest', + } + const rendered = renderInstructionChanges([{ + change, + file: { absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: 'x'.repeat(1000) }, + }], maxBytes) + + expect(rendered.text).toContain(heading) + expect(rendered.text).toContain('from 1000 to 0 bytes') + expect(rendered.changes).toEqual([]) + }) + + it('does not commit a multibyte change when the budget cuts its first code point', () => { + const change = { + action: 'set' as const, + scope: sk('pkg', 'AGENTS.md'), + path: 'pkg/AGENTS.md', + digest: 'digest', + } + const rendered = renderInstructionChanges([{ + change, + file: { absolutePath: '/repo/pkg/AGENTS.md', displayPath: 'pkg/AGENTS.md', content: '😀'.repeat(100) }, + }], 366) + + expect(rendered.text).not.toContain('�') + expect(rendered.text).not.toContain('😀') + expect(rendered.changes).toEqual([]) + }) + it('keeps compact truncation notices within budget when a multibyte display path is cut', () => { const rendered = renderWorkspaceContext([ { absolutePath: '/repo/路径/AGENTS.md', displayPath: '路径/AGENTS.md', content: 'x'.repeat(1000) }, @@ -1832,21 +1929,30 @@ describe('workspace context request injection', () => { } }) - it('does not expose state markers when a tiny budget reduces the baseline contribution', async () => { + it.each([10, 120])('does not expose state markers when baseline content is omitted at %i bytes', async (maxBytes) => { const root = await tempRepo() const home = await tempRepo() try { await mkdir(join(root, '.git'), { recursive: true }) - await write(join(root, 'AGENTS.md'), 'repo rule') + await write(join(root, 'AGENTS.md'), 'x'.repeat(1000)) const ctx = new Context() - await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 10 }) + await mountWorkspaceContext(ctx, { dshHome: home, maxBytes }) const agent = stubAgent(root) await composeBaselinePrefix(ctx, agent) - expect(agent.session.events.filter(event => + const contexts = agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user', - )).toHaveLength(1) + ) + expect(contexts).toHaveLength(1) + const source = contexts[0]?.type === 'user/message' ? contexts[0].data.source : undefined + expect(source?.kind === 'workspace-instructions' ? source.changes : undefined).toEqual([]) + if (maxBytes === 120) { + expect(derivedText(agent)).toContain('Instructions from: AGENTS.md') + expect(derivedText(agent)).toContain('from 1000 to 0 bytes') + } else { + expect(derivedText(agent)).not.toContain('Instructions from: AGENTS.md') + } expect(derivedText(agent)).not.toContain('workspace-context:') } finally { await rm(root, { recursive: true, force: true }) @@ -4167,6 +4273,47 @@ describe('dynamic nested workspace context injection', () => { } }) + it('retries a nested instruction touch when only a truncated budget notice was rendered', async () => { + const root = join(await tempRepo(), 'virtual-repo') + const home = join(await tempRepo(), 'virtual-home') + const ctx = new Context() + try { + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(RecordingFileSystem) + const fs = ctx.fs as RecordingFileSystem + const instructionPath = join(root, 'pkg/AGENTS.md') + fs.entries.set(join(root, '.git'), { type: 'directory' }) + fs.entries.set(instructionPath, { type: 'file', content: 'x'.repeat(1000) }) + fs.entries.set(join(root, 'pkg/file.txt'), { type: 'file', content: 'hello' }) + await ctx.plugin(ToolFs) + await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 20 }) + const agent = stubAgent(root) + + const first = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-tiny-budget-1'), name: 'read', arguments: { file_path: join('pkg', 'file.txt') }, agent, + }) + await syncWorkspaceContext(ctx, agent) + const second = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-tiny-budget-2'), name: 'read', arguments: { file_path: join('pkg', 'file.txt') }, agent, + }) + await syncWorkspaceContext(ctx, agent) + + expect(first.additionalContexts).toBeUndefined() + expect(second.additionalContexts).toBeUndefined() + // Nothing was emitted, and the uncommitted version made the second sync + // probe the instruction file again — the retry. + expect(agent.inbox.nextStep).toHaveLength(0) + expect(fs.readTargets.filter(path => path === instructionPath)).toHaveLength(2) + } finally { + await ctx.fiber.dispose() + await rm(dirname(root), { recursive: true, force: true }) + await rm(dirname(home), { recursive: true, force: true }) + } + }) + it('does not attach nested instructions after a failed file read', async () => { const root = await tempRepo() const home = await tempRepo() @@ -4253,7 +4400,7 @@ describe('workspace context inbox synchronization', () => { } }) - it('keeps a dynamic change within a one-byte positive render budget', async () => { + it('holds back a dynamic change a one-byte positive render budget cannot represent', async () => { const root = await tempRepo() const home = await tempRepo() const ctx = new Context() @@ -4271,8 +4418,10 @@ describe('workspace context inbox synchronization', () => { await syncWorkspaceContext(ctx, agent) - expect(agent.inbox.nextStep).toHaveLength(1) - expect(Buffer.byteLength(blocksText(agent.inbox.nextStep[0]?.content), 'utf8')).toBeLessThanOrEqual(1) + // One byte cannot semantically represent the transition, so nothing is + // emitted and nothing commits — the uncommitted version retries on the + // next touch instead of committing state the model never saw. + expect(agent.inbox.nextStep).toHaveLength(0) } finally { await ctx.fiber.dispose() await rm(root, { recursive: true, force: true }) diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml index 0c5e1fee44..e3a9b36a95 100644 --- a/packages/core/tools/README.i18n.yaml +++ b/packages/core/tools/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/core/tools/README.md -README.md: 2c9833c3505c765283559590c8bc28b3c2077e2e -README.zh.md: d7766b432c5a319d214da80e3df438489519be92 +README.md: 21851ca887147364c76612bae2e6a00ebdccec39 +README.zh.md: aec3b434e52f473001505bbea5212d5e247eb46f diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index 2c9833c350..21851ca887 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -19,7 +19,7 @@ tools: - `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition with a mandatory canonical `output` declaration. The layer is the calling context's scope: a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, shadowing a same-named global tool there. Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. Missing or unsupported output declarations and a non-positive or non-finite `timeoutMs` fail at registration. The optional synchronous `finalizeContent` callback is snapshotted when a call starts and may replace only final model-facing content after every pipeline outcome is normalized, including an error discovered while materializing another result field. Disposed with the calling fiber. - `ctx.tools.presentAs(mode: ToolPresentationMode): () => void` selects this agent's model-facing presentation, shadowing the `mode` config for that agent alone; it throws from a plain context (a process-wide presentation is the config field) and from a second declaration in the same scope. A code mode also registers that agent's own `tools:sdk` section. The catalog is unchanged — `schemas(agent)` still reports the agent's capabilities; only the assembly's tools collapse. Disposed with the calling fiber. -- `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals). +- `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to the tools that scope INHERITS — the global layer and every ancestor scope on its chain — and throws from a plain context. The scope's OWN registrations are exempt and merge afterwards, which is what keeps a delegated child's reporting and structured-output tools alive under a filter naming only the capabilities it may use. The filter is snapshotted at registration; multiple masks intersect, and a mask on an ancestor reaches every scope nested inside it. Deny masks admit later unnamed inherited tools, while allow masks exclude later names. Unknown, own-layer, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals). - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed. - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)). - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber. diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md index d7766b432c..aec3b434e5 100644 --- a/packages/core/tools/README.zh.md +++ b/packages/core/tools/README.zh.md @@ -19,7 +19,7 @@ tools: - `ctx.tools.register(definition: ToolDefinition): () => void`：注册一个受信任、带类型的同进程定义，其中必须包含规范的 `output` 声明。所在层由调用上下文的作用域决定：普通插件上下文会全局注册；agent 的 `agent.ctx` 只为该 agent 注册，并在此处遮蔽同名全局工具。同一层内名称重复会抛出；非原生模式还会拒绝保留的 `run_code` 传输名称。缺失或不受支持的输出声明，以及非正数或非有限的 `timeoutMs`，都会使注册失败。可选的同步 `finalizeContent` 回调会在调用开始时创建快照；在所有流水线结果规范化之后，它只能替换最终面向模型的内容，包括实体化其他结果字段时发现的错误。随调用 fiber dispose（资源释放）。 - `ctx.tools.presentAs(mode: ToolPresentationMode): () => void`：为本 agent 选择面向模型的呈现方式，仅对该 agent 遮蔽 `mode` 配置；从普通上下文调用会抛出（进程级呈现方式是那个配置字段），同一 scope 内第二次声明也会抛出。code 类模式还会为该 agent 注册它自己的 `tools:sdk` 段。清单本身不变——`schemas(agent)` 报告的仍是该 agent 的能力，坍缩的只是 assembly 里的工具。随调用方 fiber 一同释放。 -- `ctx.tools.restrict(filter)`：对全局工具应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。筛选器在注册时创建快照；多个掩码取交集，随后再合并作用域本地工具。拒绝掩码会接纳后来出现且未点名的全局工具，而允许掩码会排除后来出现的名称。未知、本地或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。 +- `ctx.tools.restrict(filter)`：对该作用域**继承来的**工具——全局层以及其链上的每个祖先作用域——应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。作用域**自身**的注册不受掩码约束，并在其后合并进来，这正是让被委派子 agent 的回报与结构化输出工具能在只点名其可用能力的筛选器下存活的机制。筛选器在注册时创建快照；多个掩码取交集，祖先上的掩码作用于其内嵌套的每个作用域。拒绝掩码会接纳后来出现且未点名的继承工具，而允许掩码会排除后来出现的名称。未知、自身层或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined`：按某个作用域所见的结果解析（应用遮蔽；被限制掉的全局工具视为不存在）。呈现器会传入发起调用的 agent，使卡片与实际执行内容一致。 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]`：返回该作用域可见的所有 schema（不含 `execute` 函数）。已交付工具的 schema 收录在 [docs/tool-catalog.md](../../../docs/tool-catalog.md) 中；该目录通过启动每个工具插件并采集此方法的结果生成（参见[工具 schema 目录 Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)）。 - `ctx.tools.guard(guard: ToolGuard): () => void`：在 `tools/pre-execute` 之后注册单调同步执行守卫：返回理由会拒绝调用，返回 `undefined` 则保持原决定。普通上下文守卫全局生效；`agent.ctx` 守卫只对该 agent 生效。后续 waterfall（瀑布式事件）监听器无法将守卫的拒绝重新变为允许。随调用 fiber dispose。 diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index a1653e7d16..86c69d9307 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -647,13 +647,14 @@ export interface Config { } /** - * Per-scope filter over global tools. Restrictions intersect and do not affect - * scoped registrations or the reserved Code Mode transport. + * Per-scope filter over the tools a scope INHERITS — the global layer and + * every ancestor layer on its chain. Restrictions intersect, and do not affect + * the scope's own registrations or the reserved Code Mode transport. */ export interface ToolRestriction { - /** Global tool names that stay visible; everything else is removed. */ + /** Inherited tool names that stay visible; every other inherited one is removed. */ readonly allow?: readonly string[] - /** Global tool names removed from visibility. */ + /** Inherited tool names removed from visibility. */ readonly deny?: readonly string[] } @@ -669,7 +670,7 @@ interface ToolView { readonly visible: ReadonlyMap /** Pre-restriction capability names used by prompt-order validation. */ readonly knownNames: ReadonlySet - /** Current global names that a scoped restriction may name. */ + /** Current inherited names a scoped restriction may name; its own are exempt. */ readonly restrictableNames: ReadonlySet } @@ -707,7 +708,7 @@ class ToolLayer implements ScopeLayer { && this.mode === undefined } - /** Whether every compiled restriction in this layer admits a global tool name. */ + /** Whether every compiled restriction in this layer admits an inherited tool name. */ admits(name: string): boolean { for (const filter of this.restrictions.values()) { if ((filter.allow !== undefined && !filter.allow.has(name)) @@ -1029,7 +1030,7 @@ export class ToolRegistry extends Service { const known = this.view(scope).restrictableNames const unknown = [...allow ?? [], ...deny ?? []].filter(name => !known.has(name)) if (unknown.length > 0) { - throw new Error(`tools.restrict() names unknown global tool${unknown.length > 1 ? 's' : ''} ${unknown.map(n => `"${n}"`).join(', ')}; known global tools: ${[...known].sort().join(', ') || '(none)'}`) + throw new Error(`tools.restrict() names unknown inherited tool${unknown.length > 1 ? 's' : ''} ${unknown.map(n => `"${n}"`).join(', ')}; a restriction filters what this scope inherits, never what it registers itself. Restrictable tools: ${[...known].sort().join(', ') || '(none)'}`) } return this.layers.effect( this.ctx, @@ -1070,30 +1071,54 @@ export class ToolRegistry extends Service { /** * Resolve every registry fact one scope needs in one layer traversal. The - * visible map applies global restrictions, scoped shadowing, and the reserved - * presentation transport; the other sets retain the pre-restriction facts - * needed by restriction and prompt-order validation. + * visible map applies restrictions to the INHERITED surface, then the + * scope's own registrations and the reserved presentation transport; the + * other sets retain the pre-restriction facts needed by restriction and + * prompt-order validation. + * + * A restriction filters what a scope inherits — the global layer and every + * ancestor layer on its chain — and never what its OWN layer registers. + * That exemption is what a per-child capability filter has to keep intact: + * the delegation runtime registers a child's reporting and structured-output + * tools into the child's own layer, and a filter naming the capabilities the + * child may use must not strip the machinery it answers through. + * + * Reading the exempt set as "the global layer" instead of "not mine" held + * only while every model-facing tool sat in the host composition. Once + * presets moved them onto the agent plane they became an ANCESTOR + * contribution, so a child's filter silently stopped constraining anything + * it was given. * @param scope - the viewing scope (the agent), or undefined for the global view. * @returns the complete derived view for that scope. */ private view(scope?: ScopeKey): ToolView { // Scope-chain layers, farthest ancestor first, the exact scope last. const layers = this.layers.chainLayers(scope) + // Chain-blind on purpose: this is the ONE layer whose registrations the + // scope owns rather than inherits, and it is absent until the scope + // contributes something. + const own = this.layers.peek(scope) + // Inherited surface, nearest ancestor last: a nearer scope's same-name + // entry shadows a farther one, and the global layer is the farthest. + const inherited = new Map(this.layers.global.tools.entries()) + for (const layer of layers) { + if (layer === own) continue + for (const [name, definition] of layer.tools.entries()) inherited.set(name, definition) + } const visible = new Map() const knownNames = new Set() const restrictableNames = new Set() - for (const [name, definition] of this.layers.global.tools.entries()) { + for (const [name, definition] of inherited) { knownNames.add(name) restrictableNames.add(name) // Restrictions intersect across the whole chain: any scope on it may - // mask a global-surface name for everything nested inside it. + // mask an inherited name for everything nested inside it. if (layers.every(layer => layer.admits(name))) visible.set(name, definition) } - // Chain layers second, nearest last: same-name entries REPLACE (shadow) - // the global and farther-scope ones, and scope-local registrations are - // never part of the global filter above. - for (const layer of layers) { - for (const [name, definition] of layer.tools.entries()) { + // The scope's own registrations last, shadowing an inherited name and + // outside the filter above. + if (own !== undefined) { + for (const [name, definition] of own.tools.entries()) { knownNames.add(name) visible.set(name, definition) } diff --git a/packages/core/tools/tests/scoped.spec.ts b/packages/core/tools/tests/scoped.spec.ts index 922173653f..8f7be45b19 100644 --- a/packages/core/tools/tests/scoped.spec.ts +++ b/packages/core/tools/tests/scoped.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, expectTypeOf, it, vi } from 'vitest' import { Context } from 'cordis' import type { Events } from 'cordis' -import { createScope } from '@deepseek-ai/dsh-scope' +import { bindScopeParent, createScope } from '@deepseek-ai/dsh-scope' import type { Scope } from '@deepseek-ai/dsh-scope' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' @@ -181,21 +181,84 @@ describe('restrict()', () => { expect(ctx.tools.schemas(key).map(t => t.name)).toEqual(['b']) }) - it('fails loud on an unscoped call, an empty filter, and non-global names', async () => { + it('fails loud on an unscoped call, an empty filter, and names it does not inherit', async () => { const ctx = await mount() const { scope } = await mintAgentScope(ctx, 'a') ctx.tools.register(tool('real')) scope.ctx.tools.register(tool('local')) expect(() => ctx.tools.restrict({ deny: ['real'] })).toThrow(/requires a scoped context/) expect(() => scope.ctx.tools.restrict({})).toThrow(/no-op/) - expect(() => scope.ctx.tools.restrict({ allow: ['local'] })).toThrow(/unknown global tool "local"/) - expect(() => scope.ctx.tools.restrict({ allow: ['reall'] })).toThrow(/unknown global tool "reall"; known global tools: real/) - expect(() => scope.ctx.tools.restrict({ deny: ['ghost', 'wraith'] })).toThrow(/unknown global tools "ghost", "wraith"/) + // A scope's own registration is exempt from its own filter, so naming it + // is a caller error rather than a silent no-op. + expect(() => scope.ctx.tools.restrict({ allow: ['local'] })).toThrow(/unknown inherited tool "local"/) + expect(() => scope.ctx.tools.restrict({ allow: ['reall'] })).toThrow(/unknown inherited tool "reall".*Restrictable tools: real/s) + expect(() => scope.ctx.tools.restrict({ deny: ['ghost', 'wraith'] })).toThrow(/unknown inherited tools "ghost", "wraith"/) const emptyCtx = await mount() const { scope: emptyScope } = await mintAgentScope(emptyCtx, 'empty') expect(() => emptyScope.ctx.tools.restrict({ deny: ['ghost'] })) - .toThrow(/known global tools: \(none\)/) + .toThrow(/Restrictable tools: \(none\)/) + }) +}) + +describe('restrict() over an inherited scope layer', () => { + /** Mint a child scope parented to `parent`, as a subagent's creation window does. */ + async function mintChild(ctx: Context, parentKey: Agent, name: string): Promise<{ scope: Scope; key: Agent }> { + const key = { id: name as SessionId } as Agent + bindScopeParent(key, parentKey) + let scope!: Scope + await ctx.plugin(Object.assign((inner: Context) => { scope = createScope(inner, key) }, + { inject: ['tools', 'systemPrompt'] })) + return { scope, key } + } + + it('filters tools the child inherits from an ancestor scope, not only global ones', async () => { + // The shape every preset deployment has: no model-facing row in the global + // layer, all of them contributed by an ancestor scope the child joined. + const ctx = await mount() + const parent = await mintAgentScope(ctx, 'parent') + parent.scope.ctx.tools.register(tool('bash')) + parent.scope.ctx.tools.register(tool('read')) + const child = await mintChild(ctx, parent.key, 'child') + + expect(ctx.tools.schemas(child.key).map(t => t.name).sort()).toEqual(['bash', 'read']) + child.scope.ctx.tools.restrict({ deny: ['bash'] }) + + // Reading the exempt set as "the global layer" left this unfiltered, and + // the name unrestrictable in the first place. + expect(ctx.tools.schemas(child.key).map(t => t.name)).toEqual(['read']) + expect(await run(ctx, 'bash', child.key)).toBe('Error: unknown tool "bash"') + // The ancestor keeps its whole surface: a child's filter is its own. + expect(ctx.tools.schemas(parent.key).map(t => t.name).sort()).toEqual(['bash', 'read']) + }) + + it('keeps the child\'s own registrations outside its own filter', async () => { + // The delegation runtime registers a child's reporting and structured + // output tools into the child's own layer; an `allow` naming only the + // capabilities the child may use must not strip them. + const ctx = await mount() + const parent = await mintAgentScope(ctx, 'parent') + parent.scope.ctx.tools.register(tool('bash')) + parent.scope.ctx.tools.register(tool('read')) + const child = await mintChild(ctx, parent.key, 'child') + child.scope.ctx.tools.register(tool('report')) + + child.scope.ctx.tools.restrict({ allow: ['read'] }) + + expect(ctx.tools.schemas(child.key).map(t => t.name).sort()).toEqual(['read', 'report']) + expect(await run(ctx, 'report', child.key)).toBe('ran:report') + }) + + it('lets an ancestor\'s restriction reach every scope nested inside it', async () => { + const ctx = await mount() + ctx.tools.register(tool('web')) + const parent = await mintAgentScope(ctx, 'parent') + parent.scope.ctx.tools.register(tool('bash')) + const child = await mintChild(ctx, parent.key, 'child') + parent.scope.ctx.tools.restrict({ deny: ['web'] }) + + expect(ctx.tools.schemas(child.key).map(t => t.name)).toEqual(['bash']) + expect(ctx.tools.schemas(parent.key).map(t => t.name)).toEqual(['bash']) }) }) diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index cb59deecbe..3626ef9960 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -33,6 +33,7 @@ import { PresetNotWritableError, resolveSessionPreset, SETTINGS_NAMESPACE as AGENT_PRESET_SETTINGS_NAMESPACE, UnknownPresetError, } from '@deepseek-ai/dsh-agent-presets' +import type { PresetBearingSession } from '@deepseek-ai/dsh-agent-presets' import type {} from '@deepseek-ai/dsh-tools' import type { ApiProxy, ConfigurableProviderView, CredentialView, GoalRef, HistoryEntry, HostFrame, @@ -1037,7 +1038,9 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro * common paths — reconnecting, resuming, retrying a create — are unaffected. * @param sessionId - the identity being adopted. * @param requested - the preset the request named, if any. - * @param existing - the preset the session was created under, if any. + * @param existing - the preset the session RUNS, if any; both callers resolve + * it from the log, which differs from the creation header once a blank + * session has switched. * @throws when both are present and differ. */ function assertPresetUnchanged( @@ -1350,17 +1353,26 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro * The registry view scope a transcript's presenters resolve in. * * A live agent is that scope itself (its chain passes through its preset's - * standing layer). A cold session names its preset on the header, and the + * standing layer). A cold session resolves its preset from the LOG, and the * preset's STANDING key serves without resuming anything — ensuring the * mount composes plugins but starts no agent, session, or turn. No roster, * no recorded preset, or a preset the roster no longer supplies all fall * back to the global layer: the transcript still serves, with the generic * cards a viewless entry renders. + * + * Reading the header alone would render a session that switched while blank + * through the composition it was CREATED with. Every tool only the newer + * preset registers resolves to no presenter there, and the transcript + * silently degrades to generic cards for exactly the calls its history is + * made of. * @param sessionId - the transcript being read. - * @param header - that session's header (attached or inspected). + * @param session - that session's header and log (attached or inspected). * @returns the scope to pass to presenter lookups, or undefined for global. */ - async function presenterScopeFor(sessionId: SessionId, header: SessionHeader): Promise { + async function presenterScopeFor( + sessionId: SessionId, + session: PresetBearingSession, + ): Promise { const live = ctx.get('agents')?.get(sessionId) if (live !== undefined) return live const presets = ctx.get('agentPresets') @@ -1370,7 +1382,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro // through the DEFAULT preset's standing layer: that is the composition // an unnamed session composes today, and presenters are pure display, // so the worst a mismatch produces is the generic card it had anyway. - return await presets.standingKeyFor(header.agentPreset) + return await presets.standingKeyFor(resolveSessionPreset(session)) } catch { // Swallows only the unknown/unusable-preset rejection from the roster: // a deleted or broken preset must degrade this read, never fail it. @@ -1463,7 +1475,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro // Beside the cwd check for the same reason, and after the await so it // covers every path that yields a live agent — freshly created, adopted // live, resumed from disk, or recovered by the concurrent-creation catch. - assertPresetUnchanged(sessionId, presetId, agent.session.header.agentPreset) + assertPresetUnchanged(sessionId, presetId, resolveSessionPreset(agent.session)) if (agent.session.header.cwd !== cwd) { throw new SessionCwdConflict(sessionId, cwd, agent.session.header.cwd) } @@ -1979,12 +1991,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro }) } } - // Echo the RESOLVED composition so a client can label the session it - // just created without waiting for the next list refresh — the create - // is the commit point that knows it (a caller that named none gets - // the default the header recorded). + // Echo the composition the session RUNS so a client can label it + // without waiting for the next list refresh — the create is the commit + // point that knows it (a caller that named none gets the default). + // Resolved from the log for the same reason `sessionListFields()` is: + // this handler also adopts an already-live session, and one that + // switched while blank runs a preset its header no longer names, so + // echoing the header would contradict both the adoption this call just + // allowed and the row `session.list` serves for the same session. const created = ctx.agents.get(sessionId) - const createdPreset = created?.session.header.agentPreset + const createdPreset = created === undefined ? undefined : resolveSessionPreset(created.session) return ok(request, { sessionId, ...createdPreset === undefined ? {} : { agentPreset: createdPreset } }) }, @@ -2003,7 +2019,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro details: {}, }) } - const page = historyPage(ctx, state.events, beforeSeq, maxMessages, await presenterScopeFor(sessionId, state.header)) + const page = historyPage(ctx, state.events, beforeSeq, maxMessages, await presenterScopeFor(sessionId, state)) return ok(request, { events: page.events, hasMore: page.hasMore, @@ -2982,7 +2998,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro // The scope presenters resolve in — the live agent, else the recorded // preset's standing key, else the global layer — so a cold session's // '/' popup lists the catalog its composition actually serves. - const scope = await presenterScopeFor(sessionId, session.header) + const scope = await presenterScopeFor(sessionId, session) try { const skills = (await skillRegistry.list({ cwd, scope })).filter(isUserInvocable) return ok(request, { diff --git a/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts b/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts index eb707c01f6..106cb213da 100644 --- a/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts @@ -186,6 +186,29 @@ describe('session.create with an agent preset', () => { }) }) + it('adopts a live session under the preset it SWITCHED to', async () => { + const { api, ctx } = await harness(['standard', 'minimal']) + await api.sessions.create(request({ sessionId: SessionId('s4b'), agentPreset: 'standard' })) + // Exactly what `agentPreset.select` leaves behind on a blank session: the + // header keeps the creation fact, the log states what the agent runs. + ctx.sessions.get(SessionId('s4b'))?.append('agent-preset/selected', { agentPreset: 'minimal' }) + + const adopted = await api.sessions.create(request({ sessionId: SessionId('s4b'), agentPreset: 'minimal' })) + const stale = await api.sessions.create(request({ sessionId: SessionId('s4b'), agentPreset: 'standard' })) + + // Comparing against the header would invert both answers: the preset the + // session actually runs would be refused, and the one it left would pass. + expect(adopted.result.ok).toBe(true) + // The echo has to name the same preset the adoption just accepted, or the + // client labels the session with one it has already left — and disagrees + // with the row `session.list` serves for it. + if (!adopted.result.ok) throw new Error('unreachable') + expect(adopted.result.value).toMatchObject({ agentPreset: 'minimal' }) + expect(stale.result.ok).toBe(false) + if (stale.result.ok) throw new Error('unreachable') + expect(stale.result.error.details).toMatchObject({ existingPreset: 'minimal' }) + }) + it('adopts a live session unchanged when the caller names no preset', async () => { const { api } = await harness(['standard', 'minimal']) await api.sessions.create(request({ sessionId: SessionId('s5'), agentPreset: 'minimal' })) @@ -660,6 +683,27 @@ describe('session.history presenter scope', () => { expect(standingKeyRequests).toEqual([]) }) + it('resolves a switched session from the LOG, not its creation header', async () => { + // The header is a creation fact; a switch while blank is a logged event, + // and every turn after it ran under the newer composition. Reading the + // header would render that history through the older preset's layer, + // where the tools it is made of have no presenter at all. + const meta = { id: SessionId('p4'), createdAt: 1, cwd: '/tmp/p4', agentPreset: 'standard' } + const { api } = await harness(['standard', 'minimal'], { + list: () => Promise.resolve([meta]), + inspect: () => Promise.resolve({ + meta, + events: [{ type: 'agent-preset/selected', seq: 1, time: 0, data: { agentPreset: 'minimal' } }], + }), + }) + + standingKeyRequests.length = 0 + const response = await api.sessions.history(request({ sessionId: SessionId('p4') })) + + expect(response.result.ok).toBe(true) + expect(standingKeyRequests).toEqual(['minimal']) + }) + it('serves a COLD transcript whose standing mount is no longer usable', async () => { // A genuinely cold session: persistence knows it, no live agent exists. const meta = { id: SessionId('p3'), createdAt: 1, cwd: '/tmp/p3', agentPreset: 'standard' } diff --git a/packages/preset/agent-presets/README.i18n.yaml b/packages/preset/agent-presets/README.i18n.yaml index 65af853308..ecd2a5a6c0 100644 --- a/packages/preset/agent-presets/README.i18n.yaml +++ b/packages/preset/agent-presets/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/preset/agent-presets/README.md -README.md: b6d469b26a0254adc654e5cc49d3df2d10817b2d -README.zh.md: 60c7bc695c27bf2c0169a0e405aa84aa711b9b21 +README.md: 632fc7828313a932512cb59a924050005067a008 +README.zh.md: 41dfab1af81149a221cb333a5613ab0a2d899899 diff --git a/packages/preset/agent-presets/README.md b/packages/preset/agent-presets/README.md index b6d469b26a..632fc78283 100644 --- a/packages/preset/agent-presets/README.md +++ b/packages/preset/agent-presets/README.md @@ -14,6 +14,8 @@ Discovery is unmemoized: `list()` and `resolve()` re-read the roots on every cal - `ctx.agentPresets.list(): Promise` Every preset the configured roots currently supply, earlier root winning a duplicate id; broken presets included, each carrying its reason. - `ctx.agentPresets.resolve(id?): Promise` One preset by id, defaulting to `defaultId`. Throws naming the available ids when no root supplies it. A broken preset resolves — deleting, reading, and reporting one all need the row. - `ctx.agentPresets.mount(agentCtx, id?): Promise` Compose one agent from a preset — ensure its standing mount (single-flight) and parent the agent's scope key to it — returning the preset for the caller to record. Refuses a broken preset up front with its discovery-reported reason, so every unloadable shape fails the same way before the loader is involved. +- `ctx.agentPresets.composeFrom(agentCtx, parentCtx): string | undefined` Join one agent to the standing composition another already runs on, returning the preset id joined — `undefined` when the parent joined none, which is the rosterless deployment and not an error. A bind rather than a mount, so it is synchronous and has no composition failure mode; it still rejects a caller error (an unscoped context, or an agent that already joined). +- `ctx.agentPresets.composedPreset(agentCtx): string | undefined` The preset one LIVE agent runs on, read from its scope chain rather than from its session — the only answer available for an agent whose durable header is still being built. - `ctx.agentPresets.recompose(agentCtx, id): Promise` Re-link one agent to a different preset's standing composition. Valid only while the agent has produced nothing — **the caller owns that check**; the new mount is ensured before the link moves, so a failure leaves the agent as it was. Refuses a broken preset like `mount()`. - `ctx.agentPresets.standingKeyFor(id?): Promise` The standing scope key a host reader with no agent (a cold transcript read) resolves preset registrations in; ensures the mount without starting an agent, session, or turn. Refuses a broken preset like `mount()`. - `ctx.agentPresets.authorable: boolean` Whether any configured root has `user` trust, and therefore whether a preset can be created at all. @@ -27,6 +29,14 @@ Discovery is unmemoized: `list()` and `resolve()` re-read the roots on every cal The agent factory's `setup(agentCtx)` hook is the one supported call site. Only there is the join installed while the agent is still unpublished, so a rejected composition rolls the whole creation back rather than leaving a half-composed session. The standing subtree is owned by the roster service's own fiber — deliberately its UNTRACED context, because a subtree minted from a traced `this.ctx` resolves every service through the caller's shadow fiber instead of each entry's own inject store — so it survives every agent and unwinds only with the whole tree. Each generation records its composition file's stamp (mtime and size): a session that finds the stamp stale starts the next generation, while every session already joined keeps the one it runs on — the composition a running session joined outlives its file changing or disappearing underneath it, and files are the only composition editor, so the stamp is what carries an edit to later sessions. +### Composing a child agent + +A subagent's child joins its parent's standing composition through `composeFrom()`, never through `mount()`. Every model-facing row lives on the agent plane, so the tool registry's global layer is empty and a child that joins nothing reaches the model with no tools at all and none of its parent's prompt sections. + +Re-mounting the parent's preset by id would differ from the bind in two ways that both matter. A composition file edited since the parent started would hand the child a DIFFERENT generation than the one its parent's history was produced under, and a preset deleted since would fail the child outright while its parent keeps running. The bind is also synchronous, which is what lets the in-process subagent drivers use it at all — they compose their children inside a synchronous creation window. + +The child records the joined id on its own durable header ([`dsh-subagent`](../../subagent/subagent/README.md)), so a cold read of the child's history rebuilds the composition it actually ran under rather than the deployment default. + ### Which preset a session runs The creation header names the preset a session STARTED with; `resolveSessionPreset(session)` names the one it RUNS. They differ whenever a blank session switched, so every reconstruction path — the summary a picker reads, a resume, a fork — resolves rather than reading the header. @@ -63,7 +73,7 @@ A preset may publish display text in an optional `preset.yml` beside its composi ```yaml name: 极简模式 -description: 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。 +description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。 ``` It carries display text ONLY. `id` is the directory name and `trust` comes from the root the preset was discovered under, so neither is writable here — otherwise a locally authored preset could name itself into the shipped set. It is a separate file because the composition is a top-level list of plugin rows: YAML cannot carry sibling keys beside it, and a fake metadata row would hand the Loader something to load. diff --git a/packages/preset/agent-presets/README.zh.md b/packages/preset/agent-presets/README.zh.md index 60c7bc695c..41dfab1af8 100644 --- a/packages/preset/agent-presets/README.zh.md +++ b/packages/preset/agent-presets/README.zh.md @@ -14,6 +14,8 @@ - `ctx.agentPresets.list(): Promise` 当前各根目录提供的全部 preset；id 重复时靠前的根目录胜出；损坏的 preset 也在其中，各自携带原因。 - `ctx.agentPresets.resolve(id?): Promise` 按 id 取一个 preset，缺省取 `defaultId`。没有任何根目录提供该 id 时抛错，并列出可用 id。损坏的 preset 照样解析——删除、读取与上报都需要这一行。 - `ctx.agentPresets.mount(agentCtx, id?): Promise` 用一个 preset 组装一个 agent——确保其常驻挂载（并发去重）并把 agent 的 scope key 认父到它——返回该 preset 供调用方记录。对损坏的 preset 直接以发现时记下的原因拒绝，所以每种不可加载的形态都在加载器介入之前以同一方式失败。 +- `ctx.agentPresets.composeFrom(agentCtx, parentCtx): string | undefined` 让一个 agent 加入另一个 agent 已在运行的常驻组装，返回所加入的 preset id——父方未加入任何 preset 时返回 `undefined`，那是无 roster 的部署，不是错误。这是认父而非挂载，因此同步、且自身没有组装失败模式；调用方用错（上下文无 scope、agent 已加入过）仍会拒绝。 +- `ctx.agentPresets.composedPreset(agentCtx): string | undefined` 某个**活着的** agent 正在运行的 preset，从其 scope 链读取而不是从其会话读取——对于持久化 header 尚在构建中的 agent，这是唯一能拿到的答案。 - `ctx.agentPresets.recompose(agentCtx, id): Promise` 把一个 agent 重链到另一个 preset 的常驻组装。仅在该 agent 尚无任何产出时合法——**由调用方负责该检查**；新挂载在链移动之前确保完成，失败时 agent 原封不动。与 `mount()` 一样拒绝损坏的 preset。 - `ctx.agentPresets.standingKeyFor(id?): Promise` 没有 agent 的宿主读取方（冷读记录）解析 preset 注册所用的常驻 scope key；确保挂载而不启动任何 agent、会话或轮次。与 `mount()` 一样拒绝损坏的 preset。 - `ctx.agentPresets.authorable: boolean` 是否有任一配置根目录具备 `user` 信任级别，因而 preset 是否可创建。 @@ -27,6 +29,14 @@ agent 工厂的 `setup(agentCtx)` 钩子是唯一受支持的调用点。只有在那里，认父是在 agent 尚未发布时完成的，因此组装被拒绝会让整次创建回滚，而不会留下一个组装到一半的会话。常驻子树归 roster 服务自己的 fiber 所有——刻意用其未追踪的上下文，因为从被追踪的 `this.ctx` 派生的子树会经调用方的 shadow fiber 解析一切服务、无视各 entry 自己的 inject store——所以它比任何 agent 都活得久，只随整棵树卸载。每个代际记录其组装文件的 stamp（mtime 与大小）：发现 stamp 过期的会话会开启下一个代际，而所有已加入的会话保持各自正在运行的那个——正在运行的会话所加入的组装在其文件被修改或删除后继续存活；文件是唯一的组装编辑器，stamp 正是把编辑送达后续会话的机制。 +### 组装子 agent + +subagent 的子 agent 通过 `composeFrom()` 加入其父方的常驻组装，绝不走 `mount()`。所有面向模型的行都在 agent 平面，工具注册表的全局层是空的，因此没有加入任何组装的子 agent 抵达模型时既没有任何工具，也没有父方的任何提示段。 + +按 id 重新挂载父方的 preset 与认父有两处差别，且两处都要紧。父方启动后被编辑过的组装文件会把与父方历史所产出时**不同**的一个代际交给子 agent；而此后被删除的 preset 会让子 agent 直接失败，尽管其父方仍在正常运行。认父还是同步的，这正是进程内 subagent 驱动能够使用它的前提——它们在同步的创建窗口里组装子 agent。 + +子 agent 会把所加入的 id 记在自己的持久化 header 上（见 [`dsh-subagent`](../../subagent/subagent/README.md)），因此冷读子 agent 的历史时重建的是它实际运行过的组装，而不是部署默认值。 + ### 会话实际运行的是哪个 preset 创建头部记录的是会话**以什么开始**，`resolveSessionPreset(session)` 给出的才是它**实际运行的**。空白会话一旦切换过，两者就不同，因此所有重建路径——选择器读取的摘要、resume、fork——都走解析，而非直接读头部。 @@ -63,7 +73,7 @@ preset 可以在组装文件旁的可选 `preset.yml` 里发布展示文本： ```yaml name: 极简模式 -description: 只向模型呈现 bash 与 str_replace_editor，适合 benchmark 与最小复现。 +description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。 ``` 它**只**承载展示文本。`id` 是目录名，`trust` 取自 preset 被发现时所在的根目录，两者都不可写在这里——否则本地创作的 preset 就能把自己命名进随附集合。之所以是独立文件：组装是插件行的顶层列表，YAML 无法在其旁携带同级键，而伪造一个元信息行等于递给 Loader 一个要加载的东西。 diff --git a/packages/preset/agent-presets/src/index.ts b/packages/preset/agent-presets/src/index.ts index 58f523c4e3..1dde902234 100644 --- a/packages/preset/agent-presets/src/index.ts +++ b/packages/preset/agent-presets/src/index.ts @@ -28,7 +28,7 @@ import { bindScopeParent, createScope, scopeOf, type Scope, type ScopeKey, type import { settingsNamespace, type SettingsScope, type default as SettingsService } from '@deepseek-ai/dsh-settings' import { discoverPresets } from './discovery.ts' import { copyComposition, deleteComposition, readComposition } from './authoring.ts' -import { mountPreset, serviceForAgent } from './mount.ts' +import { mountPreset, serviceForAgent, standingMountFor } from './mount.ts' import { PresetExistsError } from './authoring.ts' import { PresetMountError, UnknownPresetError, type AgentPreset, type Config } from './types.ts' @@ -51,8 +51,8 @@ export { METADATA_FILE, readPresetMetadata, renderPresetMetadata, type PresetMetadata, } from './metadata.ts' export { - inactiveRows, leakedServices, livePresetMounts, mountPreset, serviceForAgent, - type PresetMount, + inactiveRows, leakedServices, livePresetMounts, mountPreset, serviceForAgent, standingMountFor, + type JoinedPresetMount, type PresetMount, } from './mount.ts' export { copyComposition, deleteComposition, InvalidPresetIdError, PresetExistsError, @@ -238,6 +238,56 @@ export class AgentPresets extends Service { return preset } + /** + * Join one agent to the SAME standing composition another already runs on. + * + * This is how a child agent inherits its parent's capabilities. It is a bind, + * not a mount: the parent's generation is already composed, so the child gets + * that exact instance — the same plugin objects, the same tool registrations, + * the same prompt sections. Re-resolving the parent's preset by id instead + * would re-read the roster, and a composition file edited since the parent + * started would hand the child a DIFFERENT generation than the one its + * parent's history was produced under (and a preset deleted since would fail + * the child outright while its parent keeps running). + * + * Synchronous, and with no composition failure mode of its own — it reads no + * roster, mounts nothing, and touches no file — which is what lets a child + * creation window use it: the two in-process subagent drivers compose their + * children inside a synchronous `setup`. It still rejects a caller error, as + * the `@throws` below record. + * + * A parent that joined no preset — a rosterless deployment — yields no join + * and no error: there, the model-facing rows sit in the host composition and + * the child already sees them through the global layer. + * @param agentCtx - the joining agent's scope context. + * @param parentCtx - the scope context of the agent whose composition to join. + * @returns the preset id joined, or undefined when the parent joined none. + * @throws when `agentCtx` carries no scope, or has already joined a preset. + */ + composeFrom(agentCtx: Context, parentCtx: Context): string | undefined { + const agentKey = scopeOf(agentCtx) + if (agentKey === undefined) { + throw new Error('agent-presets: refusing to compose an unscoped context; the scope key is what joins an agent to its preset') + } + const standing = standingMountFor(parentCtx) + if (standing === undefined) return undefined + this.bindings.set(agentKey, bindScopeParent(agentKey, standing.key)) + return standing.presetId + } + + /** + * The preset one live agent runs on. + * + * Read from the live scope chain rather than from the session, so it answers + * for an agent whose session has not recorded a preset yet — a child agent + * whose durable header is being built from its parent's composition. + * @param agentCtx - the agent's scope context. + * @returns the preset id, or undefined when the agent joined none. + */ + composedPreset(agentCtx: Context): string | undefined { + return standingMountFor(agentCtx)?.presetId + } + /** Whether this deployment configures a root locally authored presets go to. */ get authorable(): boolean { return this.config.roots.some(root => root.trust === 'user') diff --git a/packages/preset/agent-presets/src/mount.ts b/packages/preset/agent-presets/src/mount.ts index eb890255ca..e968a97c25 100644 --- a/packages/preset/agent-presets/src/mount.ts +++ b/packages/preset/agent-presets/src/mount.ts @@ -202,6 +202,33 @@ export function leakedServices(ctx: Context, mount: Fiber): string[] { return leaked.sort((left, right) => left.localeCompare(right)) } +/** A live standing mount located through one agent already joined to it. */ +export type JoinedPresetMount = PresetMount & { + /** The standing key, definite because it is what the lookup matched on. */ + readonly key: ScopeKey +} + +/** + * The standing composition one agent is joined to. + * + * The agent's own key is parented to its preset's standing key, so the mount + * is found by matching that parent rather than by walking up from the agent — + * the mount is not under the agent's fiber. An agent that joined no preset — + * a deployment composing no roster, or a child agent before its join — has no + * parent link and resolves to undefined. + * @param agentCtx - the agent's scope context. + * @returns the mount the agent joined, or undefined when it joined none. + */ +export function standingMountFor(agentCtx: Context): JoinedPresetMount | undefined { + const agentKey = scopeOf(agentCtx) + if (agentKey === undefined) return undefined + const standingKey = scopeParentOf(agentKey) + if (standingKey === undefined) return undefined + return livePresetMounts().find( + (candidate): candidate is JoinedPresetMount => candidate.key === standingKey, + ) +} + /** * One agent's instance of a service its preset mounted. * @@ -231,14 +258,7 @@ export function serviceForAgent( agent: { ctx: Context }, name: K, ): Context[K] | undefined { - // The agent's own key is parented to its preset's standing key; the mount - // is no longer under the agent's fiber, so the search roots at the standing - // mount instead of walking up from the agent. - const agentKey = scopeOf(agent.ctx) - if (agentKey === undefined) return undefined - const standingKey = scopeParentOf(agentKey) - if (standingKey === undefined) return undefined - const mount = livePresetMounts().find(candidate => candidate.key === standingKey) + const mount = standingMountFor(agent.ctx) if (mount === undefined) return undefined const store = ctx.reflect.store for (const key of Object.getOwnPropertySymbols(store)) { diff --git a/packages/preset/agent-presets/tests/mount.spec.ts b/packages/preset/agent-presets/tests/mount.spec.ts index 77c549a689..afe297a406 100644 --- a/packages/preset/agent-presets/tests/mount.spec.ts +++ b/packages/preset/agent-presets/tests/mount.spec.ts @@ -153,6 +153,79 @@ describe('composing an agent from a preset', () => { }) }) +describe('composing a child agent from its parent', () => { + /** Create one agent joined to `parent`'s composition, as a child creation window does. */ + async function childOf(ctx: Context, id: string, parent: Agent): Promise { + const handle = await ctx.agents.create({ + sessionId: SessionId(id), + setup: (childCtx: Context) => void ctx.agentPresets.composeFrom(childCtx, parent.ctx), + }) + return handle.agent + } + + it('gives the child its parent\'s tools and prompt sections', async () => { + const parent = await agentOn(ctx, 'sess-parent', 'standard') + + const child = await childOf(ctx, 'sess-child', parent) + + expect(toolNames(ctx, child)).toEqual(['alpha']) + const prompt = await ctx.systemPrompt.assemble(assembleContextFor(child)) + expect(prompt.sections.map(section => section.name)).toContain('preset:alpha') + }) + + it('joins the parent\'s own generation rather than remounting its preset', async () => { + const parent = await agentOn(ctx, 'sess-shared', 'standard') + const before = livePresetMounts().length + + await childOf(ctx, 'sess-shared-child', parent) + + // A remount would compose a second copy of every row in the preset; the + // child must run on the plugin instances its parent already runs on. + expect(livePresetMounts()).toHaveLength(before) + }) + + it('keeps the child composed after its parent is disposed', async () => { + const parentHandle = await ctx.agents.create({ + sessionId: SessionId('sess-dying-parent'), + setup: async (agentCtx: Context) => void await ctx.agentPresets.mount(agentCtx, 'standard'), + }) + const child = await childOf(ctx, 'sess-orphan', parentHandle.agent) + + await parentHandle.dispose() + + // Standing mounts outlive the agents that joined them, so a child outliving + // its parent — a background subagent — keeps the composition it started on. + expect(toolNames(ctx, child)).toEqual(['alpha']) + }) + + it('reports the preset id the child joined, for the durable header', async () => { + const parent = await agentOn(ctx, 'sess-named', 'minimal') + + const child = await childOf(ctx, 'sess-named-child', parent) + + expect(ctx.agentPresets.composedPreset(parent.ctx)).toBe('minimal') + expect(ctx.agentPresets.composedPreset(child.ctx)).toBe('minimal') + }) + + it('composes nothing when the parent joined no preset', async () => { + // The rosterless deployment: model-facing rows sit in the host composition + // and the child already resolves them through the registry's global layer. + const bare = (await ctx.agents.create({ sessionId: SessionId('sess-bare-parent') })).agent + + const child = await childOf(ctx, 'sess-bare-child', bare) + + expect(ctx.agentPresets.composedPreset(bare.ctx)).toBeUndefined() + expect(ctx.agentPresets.composeFrom(child.ctx, bare.ctx)).toBeUndefined() + expect(toolNames(ctx, child)).toEqual([]) + }) + + it('refuses to compose an unscoped context', async () => { + const parent = await agentOn(ctx, 'sess-unscoped-parent', 'standard') + + expect(() => ctx.agentPresets.composeFrom(ctx, parent.ctx)).toThrow(/unscoped context/) + }) +}) + describe('rejecting a composition that cannot be used', () => { it('refuses to mount into a context that carries no agent scope', async () => { await expect(ctx.agentPresets.mount(ctx, 'standard')) diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts index 9e63aa3ea3..69fac20609 100644 --- a/packages/self-modification/tool-cordis/src/api-catalog.ts +++ b/packages/self-modification/tool-cordis/src/api-catalog.ts @@ -110,6 +110,14 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ signature: 'async mount(agentCtx: Context, id?: string): Promise', jsDoc: '/**\n * Compose one agent from a preset: ensure the preset\'s standing mount, then\n * parent the agent\'s scope key to it so the mount\'s registrations and\n * listeners cover this agent.\n *\n * Call from the agent factory\'s `setup(agentCtx)`; a rejection there rolls\n * the agent creation back, so a broken preset never yields a half-composed\n * session.\n * @param agentCtx - the agent\'s scope context.\n * @param id - the preset id, or `undefined` for {@link defaultId}.\n * @returns the preset that was composed, for the caller to record.\n * @throws when the preset is unknown or its composition is unusable.\n */', }, + { + signature: 'composeFrom(agentCtx: Context, parentCtx: Context): string | undefined', + jsDoc: '/**\n * Join one agent to the SAME standing composition another already runs on.\n *\n * This is how a child agent inherits its parent\'s capabilities. It is a bind,\n * not a mount: the parent\'s generation is already composed, so the child gets\n * that exact instance — the same plugin objects, the same tool registrations,\n * the same prompt sections. Re-resolving the parent\'s preset by id instead\n * would re-read the roster, and a composition file edited since the parent\n * started would hand the child a DIFFERENT generation than the one its\n * parent\'s history was produced under (and a preset deleted since would fail\n * the child outright while its parent keeps running).\n *\n * Synchronous, and with no composition failure mode of its own — it reads no\n * roster, mounts nothing, and touches no file — which is what lets a child\n * creation window use it: the two in-process subagent drivers compose their\n * children inside a synchronous `setup`. It still rejects a caller error, as\n * the `@throws` below record.\n *\n * A parent that joined no preset — a rosterless deployment — yields no join\n * and no error: there, the model-facing rows sit in the host composition and\n * the child already sees them through the global layer.\n * @param agentCtx - the joining agent\'s scope context.\n * @param parentCtx - the scope context of the agent whose composition to join.\n * @returns the preset id joined, or undefined when the parent joined none.\n * @throws when `agentCtx` carries no scope, or has already joined a preset.\n */', + }, + { + signature: 'composedPreset(agentCtx: Context): string | undefined', + jsDoc: '/**\n * The preset one live agent runs on.\n *\n * Read from the live scope chain rather than from the session, so it answers\n * for an agent whose session has not recorded a preset yet — a child agent\n * whose durable header is being built from its parent\'s composition.\n * @param agentCtx - the agent\'s scope context.\n * @returns the preset id, or undefined when the agent joined none.\n */', + }, { signature: 'async read(id: string): Promise', jsDoc: '/**\n * Read one preset\'s composition text.\n * @param id - the preset id.\n * @returns the composition exactly as stored.\n * @throws when no configured root supplies that id.\n */', diff --git a/packages/subagent/subagent-inprocess/package.json b/packages/subagent/subagent-inprocess/package.json index e18752db74..36646e7f7a 100644 --- a/packages/subagent/subagent-inprocess/package.json +++ b/packages/subagent/subagent-inprocess/package.json @@ -45,9 +45,12 @@ } }, "devDependencies": { + "@cordisjs/plugin-include": "^1.0.4", + "@cordisjs/plugin-loader": "^1.0.0-rc.5", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^", + "@deepseek-ai/dsh-agent-presets": "workspace:^", "@deepseek-ai/dsh-fs-sandbox": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", diff --git a/packages/subagent/subagent-inprocess/src/index.ts b/packages/subagent/subagent-inprocess/src/index.ts index acb4e4d36e..ee7779447a 100644 --- a/packages/subagent/subagent-inprocess/src/index.ts +++ b/packages/subagent/subagent-inprocess/src/index.ts @@ -125,7 +125,7 @@ export async function startInProcessRun( if (inheritedPolicy !== undefined) { childSession.append('approval/policy', { policy: inheritedPolicy, source: 'delegation' }) } - applyChildComposition(childCtx, { + applyChildComposition(childCtx, parent, { persona: request.persona, toolFilter: request.toolFilter, }) diff --git a/packages/subagent/subagent-inprocess/tests/fixtures/plugins/preset-tool.js b/packages/subagent/subagent-inprocess/tests/fixtures/plugins/preset-tool.js new file mode 100644 index 0000000000..6fb224094d --- /dev/null +++ b/packages/subagent/subagent-inprocess/tests/fixtures/plugins/preset-tool.js @@ -0,0 +1,20 @@ +// A preset row standing in for the agent-plane tool rows a real preset mounts. +// Import-free on purpose — the Loader resolves entry modules through Node's ESM +// resolver, which cannot see this workspace's TypeScript sources. +export const name = 'preset-tool' +export const inject = ['tools', 'systemPrompt'] + +export function apply(ctx, config) { + ctx.effect(() => ctx.tools.register({ + name: config.tool, + description: `fixture tool ${config.tool}`, + parameters: { type: 'object', properties: {}, additionalProperties: false }, + output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: String(value) }] }, + execute: () => Promise.resolve(config.tool), + })) + ctx.effect(() => ctx.systemPrompt.section({ + name: `preset:${config.tool}`, + order: 10, + text: `section for ${config.tool}`, + })) +} diff --git a/packages/subagent/subagent-inprocess/tests/fixtures/presets/coding/agent.cordis.yml b/packages/subagent/subagent-inprocess/tests/fixtures/presets/coding/agent.cordis.yml new file mode 100644 index 0000000000..a801659220 --- /dev/null +++ b/packages/subagent/subagent-inprocess/tests/fixtures/presets/coding/agent.cordis.yml @@ -0,0 +1,5 @@ +# Agent-plane composition: the model-facing row lives here, not in the host. +- id: only + name: ../../plugins/preset-tool.js + config: + tool: preset_only diff --git a/packages/subagent/subagent-inprocess/tests/fixtures/presets/reviewing/agent.cordis.yml b/packages/subagent/subagent-inprocess/tests/fixtures/presets/reviewing/agent.cordis.yml new file mode 100644 index 0000000000..9971526c12 --- /dev/null +++ b/packages/subagent/subagent-inprocess/tests/fixtures/presets/reviewing/agent.cordis.yml @@ -0,0 +1,6 @@ +# A second agent-plane composition, so a switch is a real switch: the tool a +# joined child sees has to change with it. +- id: only + name: ../../plugins/preset-tool.js + config: + tool: reviewing_only diff --git a/packages/subagent/subagent-inprocess/tests/preset-inheritance.spec.ts b/packages/subagent/subagent-inprocess/tests/preset-inheritance.spec.ts new file mode 100644 index 0000000000..af199cd867 --- /dev/null +++ b/packages/subagent/subagent-inprocess/tests/preset-inheritance.spec.ts @@ -0,0 +1,135 @@ +/** + * Composition inheritance: a child runs on the preset its parent runs on. + * + * With every model-facing row on the agent plane, the tool registry's global + * layer is empty, so a child that joins no preset reaches the model with no + * tools at all. These assert the model-visible result — the schemas in the + * child's own request — rather than the join that produces it. + */ + +import { afterEach, describe, expect, it } from 'vitest' +import { dirname, join } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' +import { Context } from 'cordis' +import Loader from '@cordisjs/plugin-loader' +import Include from '@cordisjs/plugin-include' +import type { Agent } from '@deepseek-ai/dsh-agent' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit' +import AgentPresets from '@deepseek-ai/dsh-agent-presets' +import { SessionId } from '@deepseek-ai/dsh-session' +import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent' +import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' +import { startInProcessRun } from '../src/index.ts' + +const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures') +const ROOTS = [{ path: join(FIXTURES, 'presets'), trust: 'system' as const }] + +const contexts: Context[] = [] + +afterEach(async () => { + for (const ctx of contexts.splice(0).reverse()) await ctx.fiber.dispose() +}) + +/** A host composition carrying no model-facing rows, plus the preset roster. */ +async function setupPresetHost(): Promise<{ ctx: Context; adapter: MockAdapter; parent: Agent }> { + const ctx = new Context() + contexts.push(ctx) + ctx.baseUrl = pathToFileURL(FIXTURES).href + '/' + await ctx.plugin(Loader) + ctx.loader.builtins.include = Include + await mountAgentLoopTestDependencies(ctx) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(AgentPresets, { default: 'coding', roots: ROOTS }) + const adapter = new MockAdapter([textResponse('parent idle'), textResponse('child done')]) + ctx.llm.registerAdapter(['mock'], adapter) + const handle = await ctx.agents.create({ + sessionId: SessionId('parent'), + agentOptions: { provider: 'mock', model: 'mock' }, + setup: async (agentCtx: Context) => void await ctx.agentPresets.mount(agentCtx, 'coding'), + }) + return { ctx, adapter, parent: handle.agent } +} + +/** The one-shot spawn request shape both in-process providers build. */ +function spawnRequest(parent: Agent) { + return { + label: 'child task', + prompt: [{ type: 'text' as const, text: 'child task' }], + parent, + signal: new AbortController().signal, + descriptor: snapshotSubagentDescriptor({ + mode: 'one-shot' as const, + provider: 'spawn', + label: 'child task', + }), + } +} + +describe('a child agent composed in-process', () => { + it('reaches the model with its parent\'s preset tools', async () => { + const { ctx, adapter, parent } = await setupPresetHost() + + const run = await startInProcessRun(spawnRequest(parent), {}) + await run.result + + const childRequest = adapter.requests.at(-1) + expect(childRequest?.tools?.map(tool => tool.name)).toEqual(['preset_only']) + expect(ctx.tools.schemas(run.localAgent).map(schema => schema.name)).toEqual(['preset_only']) + await run.dispose() + }) + + it('carries its parent\'s prompt sections', async () => { + const { parent } = await setupPresetHost() + + const run = await startInProcessRun(spawnRequest(parent), {}) + await run.result + + expect(run.localAgent?.session.events.some(event => + event.type === 'request/header' + && JSON.stringify(event.data).includes('section for preset_only'))).toBe(true) + await run.dispose() + }) + + it('records the composition it ran under on the child header', async () => { + const { parent } = await setupPresetHost() + + const run = await startInProcessRun(spawnRequest(parent), {}) + await run.result + + // Without this the child's own history reads back under the deployment + // default, which is a different tool set than the one it actually used. + expect(run.localAgent?.session.header.agentPreset).toBe('coding') + await run.dispose() + }) + + it('honours a tool filter over the preset tools it inherited', async () => { + const { ctx, parent } = await setupPresetHost() + + const run = await startInProcessRun( + { ...spawnRequest(parent), toolFilter: { deny: ['preset_only'] } }, + {}, + ) + await run.result + + // The capability filter is the only thing bounding a delegated child, and + // every tool it can name now arrives from the preset rather than the host. + expect(ctx.tools.schemas(run.localAgent).map(schema => schema.name)).toEqual([]) + await run.dispose() + }) + + it('follows a parent that switched preset while blank', async () => { + const { ctx, parent } = await setupPresetHost() + // A DIFFERENT preset, so the assertion below distinguishes reading the + // parent's live scope chain from reading its creation header — re-linking + // to the same id would pass either way. + await ctx.agentPresets.recompose(parent.ctx, 'reviewing') + + const run = await startInProcessRun(spawnRequest(parent), {}) + await run.result + + expect(ctx.tools.schemas(run.localAgent).map(schema => schema.name)).toEqual(['reviewing_only']) + expect(run.localAgent?.session.header.agentPreset).toBe('reviewing') + await run.dispose() + }) +}) diff --git a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts index d175322381..46b94f9f5a 100644 --- a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts @@ -298,7 +298,7 @@ describe('startInProcessRun', () => { await expect(startInProcessRun({ ...request(parent), toolFilter: { deny: ['unknown-tool'] }, - }, {})).rejects.toThrow('unknown global tool') + }, {})).rejects.toThrow('unknown inherited tool') expect(ctx.agents.list()).toHaveLength(beforeAgents) expect(ctx.sessions.list()).toHaveLength(beforeSessions) }) diff --git a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts index 0310c0b0b3..508d5132fb 100644 --- a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts +++ b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts @@ -436,7 +436,7 @@ describe('dsh-subagent-spawn', () => { prompt: [{ type: 'text', text: 'do X' }], parent, toolFilter: { deny: ['no_such_tool'] }, - })).rejects.toThrow(/unknown global tool "no_such_tool"/) + })).rejects.toThrow(/unknown inherited tool "no_such_tool"/) expect(ctx.agents.list().length).toBe(before) }) }) diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml index 1241aa8042..495949dc0c 100644 --- a/packages/subagent/subagent/README.i18n.yaml +++ b/packages/subagent/subagent/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md -README.md: 762030629c09305c48adebc71244655a5faa6585 -README.zh.md: 535cc25895e04e82b6667e6d2769f2dcbfa49cff +README.md: b69428e4af7d1f53adb22be1e59beb79c054713f +README.zh.md: 9f5eb5f1c508135c21bf3923f60f4f872de8e9f6 diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md index 762030629c..b69428e4af 100644 --- a/packages/subagent/subagent/README.md +++ b/packages/subagent/subagent/README.md @@ -40,6 +40,10 @@ Start-time features are advertised in `provider.capabilities` because the servic - `toolFilter` — apply the requested child tool restriction. - `persona` — apply a per-child persona. +Every in-process child is composed by one call, `applyChildComposition(childCtx, parent, composition)`, which joins the parent's agent-preset composition before applying the child's own persona and tool filter. The join is what gives the child its capabilities: with every model-facing row on the agent plane, a child that joined nothing would reach the model with an empty tool registry ([`dsh-agent-presets`](../../preset/agent-presets/README.md)). Taking the parent as a parameter is deliberate — it makes composing a child WITHOUT that join unrepresentable at the call sites, which is the defect the one call exists to prevent. A deployment composing no preset roster joins nothing and needs nothing: its model-facing rows sit in the host composition, where the child already resolves them through the tool registry's global layer. + +`childSessionMeta()` records the joined preset id on the child's durable header for the same reason a top-level session records its own: the preset decides the tool schemas and prompt sections the model saw, so a cold read of the child's history has to rebuild that composition rather than the deployment default. It is read from the parent's live scope chain, not from the parent header, because a parent that switched preset while blank runs on the newer composition while its header still names the older one. + Continuable creation is the optional `SubagentProvider.prepareContinuable?()` method: its presence is the capability check, so the service rejects a configured continuable start on a provider without it, while a provider that has it may still serve ordinary one-shot delegations. The method returns only a detached `ContinuableCreateSpec` (`{ seed? }`) — data, never a capability: it carries no Agent, `AgentHandle`, prompt delivery, result, disposal, or resume operation, because the continuation manager owns identity reservation, composition, Agent creation, prompt delivery, cold resume, ownership, and disposal after preparation. A one-shot `SubagentRun` represents one disposable foreground delegation with one result and no cold-resume operation. ## The durable descriptor diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md index 535cc25895..9f5eb5f1c5 100644 --- a/packages/subagent/subagent/README.zh.md +++ b/packages/subagent/subagent/README.zh.md @@ -40,6 +40,10 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委 - `toolFilter`：应用请求的子 agent 工具限制； - `persona`：应用每个子 agent 独立的 persona。 +每个进程内子 agent 都由一次调用完成组装：`applyChildComposition(childCtx, parent, composition)` 先加入父方的 agent-preset 组装，再应用该子 agent 自己的 persona 与工具限制。加入组装正是子 agent 获得能力的途径：所有面向模型的行都在 agent 平面，没有加入任何组装的子 agent 抵达模型时工具注册表是空的（见 [`dsh-agent-presets`](../../preset/agent-presets/README.md)）。把父方作为参数是刻意的——这让"组装一个子 agent 却不做该加入"在各调用点无法表达，而这正是这一次调用所要杜绝的缺陷。未组装 preset roster 的部署不加入任何组装、也不需要加入：它的面向模型的行位于宿主组装中，子 agent 已经能通过工具注册表的全局层解析到它们。 + +`childSessionMeta()` 把所加入的 preset id 记在子 agent 的持久化 header 上，理由与顶层会话记录自己的那一个相同：preset 决定了模型所见的工具 schema 与提示段，因此冷读子 agent 的历史时必须重建那份组装，而不是部署默认值。该值从父方**活着的** scope 链读取，而不是从父方 header 读取，因为在空白期切换过 preset 的父方运行在更新的那份组装上，而它的 header 仍写着旧的那个。 + 可继续创建对应可选的 `SubagentProvider.prepareContinuable?()` 方法：方法是否存在就是能力检查，因此服务会在没有该方法的提供方上拒绝已配置的可继续启动，而具备该方法的提供方仍可服务普通一次性委派。该方法只返回分离的 `ContinuableCreateSpec`（`{ seed? }`）——这是数据，绝非能力：它不携带任何 Agent、`AgentHandle`、提示词投递、结果、dispose 或恢复操作，因为准备之后，继续执行管理器拥有身份预留、组合、Agent 创建、提示词投递、冷恢复、所有权和 dispose。一次性 `SubagentRun` 表示一次可 dispose 的前台委派，只有一个结果，且没有冷恢复操作。 ## 持久化描述符 diff --git a/packages/subagent/subagent/package.json b/packages/subagent/subagent/package.json index ba1dd0fbc4..35504c9dc4 100644 --- a/packages/subagent/subagent/package.json +++ b/packages/subagent/subagent/package.json @@ -34,6 +34,7 @@ }, "peerDependencies": { "@deepseek-ai/dsh-agent": "^0.0.1", + "@deepseek-ai/dsh-agent-presets": "^0.0.1", "@deepseek-ai/dsh-brand": "^0.0.1", "@deepseek-ai/dsh-invariants": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", @@ -47,6 +48,9 @@ "cordis": "^4.0.0-rc.7" }, "peerDependenciesMeta": { + "@deepseek-ai/dsh-agent-presets": { + "optional": true + }, "@deepseek-ai/dsh-session-persistence": { "optional": true }, @@ -62,6 +66,7 @@ }, "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-agent-presets": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", diff --git a/packages/subagent/subagent/src/child-agent.ts b/packages/subagent/subagent/src/child-agent.ts index c477954468..c501a19a56 100644 --- a/packages/subagent/subagent/src/child-agent.ts +++ b/packages/subagent/subagent/src/child-agent.ts @@ -12,6 +12,12 @@ import type { Context } from 'cordis' import type { Agent, AgentOptions, CreateAgentOptions } from '@deepseek-ai/dsh-agent' import type { SessionId } from '@deepseek-ai/dsh-session' import type { ToolRestriction } from '@deepseek-ai/dsh-tools' +// Type-only: make `ctx.get('agentPresets')` resolve to the preset roster when +// composed — a child inherits its parent's composition opportunistically (the +// documented `ctx.get` pattern), never as a hard dep. A rosterless deployment +// keeps its model-facing rows on the host plane, where the child already sees +// them through the tool registry's global layer. +import type {} from '@deepseek-ai/dsh-agent-presets' import { delegationDepthOf } from './depth.ts' /** Thrown when starting a child would exceed the requested depth cap. */ @@ -72,8 +78,15 @@ export function resolveChildAgentOptions( /** * Build the child session's durable creation metadata: the parent's workspace, * its direct lineage, coarse product origin, the recursion budget that must - * survive persistence, and the seed boundary that separates inherited parent - * history from child work. + * survive persistence, the seed boundary that separates inherited parent + * history from child work, and the composition the child runs under. + * + * The preset is read from the parent's LIVE scope chain rather than from its + * header, because a parent that switched preset while blank runs on the newer + * composition and its header still names the older one. Recording it is what + * makes a child's history reconstructable: without it a cold read of the child + * resolves the deployment default and rebuilds turns under a tool set the + * child never had. * @param parent - the delegating parent agent. * @param childDepth - the resolved delegation depth to persist. * @param lineageSeedLength - how many leading events came from the parent's log. @@ -85,8 +98,10 @@ export function childSessionMeta( lineageSeedLength: number, ): NonNullable { const parentHeader = parent.session.header + const agentPreset = parent.ctx.get('agentPresets')?.composedPreset(parent.ctx) return { ...parentHeader.cwd !== undefined ? { cwd: parentHeader.cwd } : {}, + ...agentPreset === undefined ? {} : { agentPreset }, parentSession: parentHeader.id, // Navigation classification only; the descriptor remains the authority // for mode and continuation capability. @@ -106,13 +121,31 @@ export interface ChildComposition { } /** - * Apply one child's scoped composition inside its creation window: a shadowing - * persona section and a tool restriction, both owned by the child's scope and - * therefore invisible to its parent and siblings. + * Compose one child inside its creation window: join its parent's preset, then + * apply the child's own shadowing persona section and tool restriction, both + * owned by the child's scope and therefore invisible to its parent and + * siblings. + * + * The join comes first and the child's own registrations second, which is the + * order the layering already implies — the nearest scope wins a name, and a + * per-child restriction intersects with everything its chain admits — but + * stating it here keeps the two steps from being read as independent. + * + * Both steps live in ONE call because a child composed with only the second is + * exactly the defect this function exists to prevent: with every model-facing + * row on the agent plane, a child that joins no preset sees an empty tool + * registry and none of its parent's prompt sections. Taking the parent as a + * parameter is what makes that omission unrepresentable at the call sites. * @param childCtx - the child agent's scoped creation context. - * @param composition - the persona and tool filter to install. + * @param parent - the delegating parent whose composition the child joins. + * @param composition - the per-child persona and tool filter to install. */ -export function applyChildComposition(childCtx: Context, composition: ChildComposition): void { +export function applyChildComposition( + childCtx: Context, + parent: Agent, + composition: ChildComposition, +): void { + childCtx.get('agentPresets')?.composeFrom(childCtx, parent.ctx) if (composition.persona !== undefined) { childCtx.systemPrompt.section({ name: 'deployment:persona', order: 0, text: composition.persona }) } diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts index 3425a12851..1cb16daca6 100644 --- a/packages/subagent/subagent/src/continuation.ts +++ b/packages/subagent/subagent/src/continuation.ts @@ -885,7 +885,7 @@ export class SubagentContinuationManager { // some other owner holds — a duplicate would reject there with rollback. inputs.signal.throwIfAborted() const setup = (childCtx: Context): AgentSetupCommit => { - applyChildComposition(childCtx, inputs.composition) + applyChildComposition(childCtx, parent, inputs.composition) return this.setupRegistry.apply(childCtx) } const observer = this.host.observeActivation(provider, childId, parent) diff --git a/packages/subagent/subagent/tsconfig.json b/packages/subagent/subagent/tsconfig.json index c72f2ef68d..afc6138bd9 100644 --- a/packages/subagent/subagent/tsconfig.json +++ b/packages/subagent/subagent/tsconfig.json @@ -26,6 +26,9 @@ { "path": "../../core/scope" }, + { + "path": "../../preset/agent-presets" + }, { "path": "../../session/session-persistence" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index dfa01799c9..7a6de4cb70 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -309,6 +309,9 @@ importers: '@deepseek-ai/dsh-settings': specifier: workspace:^ version: link:../../packages/settings/settings + '@deepseek-ai/dsh-subagent': + specifier: workspace:^ + version: link:../../packages/subagent/subagent '@deepseek-ai/dsh-system-prompt': specifier: workspace:^ version: link:../../packages/core/system-prompt @@ -6325,6 +6328,9 @@ importers: '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent + '@deepseek-ai/dsh-agent-presets': + specifier: workspace:^ + version: link:../../preset/agent-presets '@deepseek-ai/dsh-brand': specifier: workspace:^ version: link:../../util/brand @@ -6579,6 +6585,12 @@ importers: packages/subagent/subagent-inprocess: devDependencies: + '@cordisjs/plugin-include': + specifier: ^1.0.4 + version: link:../../../vendor/include + '@cordisjs/plugin-loader': + specifier: ^1.0.0-rc.5 + version: link:../../../vendor/loader '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -6588,6 +6600,9 @@ importers: '@deepseek-ai/dsh-agent-loop-testkit': specifier: workspace:^ version: link:../../support/agent-loop-testkit + '@deepseek-ai/dsh-agent-presets': + specifier: workspace:^ + version: link:../../preset/agent-presets '@deepseek-ai/dsh-fs-sandbox': specifier: workspace:^ version: link:../../fs/fs-sandbox