diff --git a/README.md b/README.md
index 113236c5..1a3fb9b6 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@
- 提供一系列常驻高级工具,大约增加约1000token的系统提示词,可关闭。高级工具会使用 [Tranquillitatis-Lab/ops-ga](https://github.com/Tranquillitatis-Lab/ops-ga) ,以及其他方案进行持续优化,并跟进最新的模型进展
- 提供缓存友好的动态工具加载框架,可以按需加载面向具体场景的高级专项工具,可关闭
- 提供一个包含教师模型轨迹的预设,让AI学会单次调用多个工具以减少任务完成需要的轮数
+- PTC SDK 目录包含 18 个 API:15 个文件/文档工具,加批处理、结果引用和加载器。
- 可与 [Tranquillitatis-Lab/dsh-live-compact](https://github.com/Tranquillitatis-Lab/dsh-live-compact) 搭配使用。两个插件都属于独立乘区,和上下文管理/记忆框架/上下文压缩/提示词注入等token节省方案乘算叠加
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 796c78dc..ae4f8a63 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -7,6 +7,25 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
## [Unreleased]
+- ops-ptc's batching teacher trajectory now teaches sandbox authority: the lesson states the
+ host-reported mode, keeps only that tier, and at `danger-full-access` says never to send
+ `sandbox_permissions` or `justification`; it also pins the closed vocabulary
+ (`workspace-write`, `danger-full-access`) instead of letting the model invent a wider target
+ (#963).
+- ops-ptc 的批量调用教师轨迹新增沙箱权限教学:按宿主报告的当前模式只保留对应档位,
+ `danger-full-access` 下明确「绝不发送 `sandbox_permissions`/`justification`」,并钉住
+ 合法值只有 `workspace-write` 与 `danger-full-access`,避免模型编造更宽的目标(#963)。
+- OPS-PTC batch-call guidance now rides the pre-step user batch as plain user text: the opening lesson
+ and every `bypass`/`plan`/`shape` notice are ordinary user messages with source kind `user`, no
+ `[Plugin context ...]` envelope and no "not a user instruction" disclaimer. The lesson is delivered on
+ the first accepted pre-step (and counts as taught only after the host commits it), notices are queued by
+ the root `run_code` result and delivered on the next pre-step, and the tool result itself is untouched.
+ This deliberately supersedes the #929 same-step-inbox route so the model reads the guidance as the user's
+ instruction.
+- OPS-PTC 批量调用提示改走 pre-step 用户消息:开局教学与每条 `bypass`/`plan`/`shape` 提醒都是
+ source kind 为 `user` 的普通用户消息,不再带 `[Plugin context ...]` 信封,也不再声明"不是用户指令"。
+ 教学在首个被接受的 pre-step 投递(宿主提交后才算兑现),提醒由根 `run_code` 结果排队、在下一个
+ pre-step 投递,工具结果本身不被改写。这是对 #929 同一步收件箱路线的有意取代,让模型把提示当作用户指令来读。
- Niubash no longer refuses to prepare its runtime when a full-access session's workspace contains
the default `~/.dsh` home (#870). The workspace boundary stays armed in read-only and
workspace-write modes, where host workspace labeling and write gating could otherwise reach the
diff --git a/docs/component-reference.md b/docs/component-reference.md
index 0aab3d35..feca5306 100644
--- a/docs/component-reference.md
+++ b/docs/component-reference.md
@@ -19,7 +19,7 @@ The `dsh-ops` row owns built-in and explicitly configured consumer plans. Native
`dsh-ops/shell`, `dsh-ops/file`, `dsh-ops/ptc` and `dsh-ops/hide-official` modules remain as
unsupported legacy exports for old profiles and are not part of the bundle.
-`ops-ptc` is the merged row's fifth built-in mode: the plugin registers the preset at runtime through the host `agentPresets.register` (definition from the shipped `presets/ops-ptc.patch.yml` fragment parsed by the host's `loadOverlayPatches`), so the plugin manager has no matching preset row; disabling or unloading the plugin row removes the preset together with the tool surface. The default preset is never written automatically: the detail page's button makes `ops-ptc` the default once (`applied`/`no-update`/`unavailable`/`failed`), while apply, remount and unload leave the operator's own choice alone; see [Presets and the default mode](presets.md). It publishes the same surface as `ptc` and adds the YAML-only `batchingGuidance`: the English lesson arrives once on the first accepted root `run_code` result as `additionalContexts` (from `prompts/batching-guidance.md`; same-step inbox, never logged history, never the system prompt), and a **root** `run_code` program that breaks one of the three latched shape categories — `bypass`, `plan` or `shape` — gets one short notice appended to its own result as `additionalContexts`; each category latches once per turn, a compliant program re-arms it, priority is `bypass` → `plan` → `shape`, and the program is never blocked or rewritten. A legacy profile that still names `dsh-ops/mode-ops-ptc` loads that module; under the merged bundle it only warns and stays inert, and its configuration belongs in the merged row's `ops-ptc` section.
+`ops-ptc` is the merged row's fifth built-in mode: the plugin registers the preset at runtime through the host `agentPresets.register` (definition from the shipped `presets/ops-ptc.patch.yml` fragment parsed by the host's `loadOverlayPatches`), so the plugin manager has no matching preset row; disabling or unloading the plugin row removes the preset together with the tool surface. The default preset is never written automatically: the detail page's button makes `ops-ptc` the default once (`applied`/`no-update`/`unavailable`/`failed`), while apply, remount and unload leave the operator's own choice alone; see [Presets and the default mode](presets.md). It publishes the same surface as `ptc` and adds the YAML-only `batchingGuidance`: the English lesson arrives once as a plain user message on the first accepted pre-step batch (from `prompts/batching-guidance.md`; source kind `user`, no plugin envelope, never the system prompt), and a **root** `run_code` program that breaks one of the three latched shape categories — `bypass`, `plan` or `shape` — queues one short notice that the next pre-step appends the same way; each category latches once per turn, a compliant program re-arms it, priority is `bypass` → `plan` → `shape`, and the program is never blocked or rewritten. A legacy profile that still names `dsh-ops/mode-ops-ptc` loads that module; under the merged bundle it only warns and stays inert, and its configuration belongs in the merged row's `ops-ptc` section.
The former `dsh-ops/background` component (FastCtx background jobs: `ops_run`, `ops_run_background`, `ops_job_output`, `ops_job_list`, `ops_job_kill`) has been removed. A profile row that still names it loads as a no-op: it accepts any config, publishes nothing, and logs one warning that the row can be deleted.
diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md
index 3503ac27..7aec604c 100644
--- a/docs/configuration-reference.md
+++ b/docs/configuration-reference.md
@@ -75,7 +75,7 @@ the row's status card, which sets it once when pressed. Generation and the manua
| `hideOfficialTools` | true | Hide the official file tools this mode replaces, including PTC presentation: when the projection can serve the matching `ops_*` API, official `read/glob/grep` leave the tool surface and the SDK declaration. `write`/`edit`/`read_image` stay; a name the projection cannot serve keeps its official tool (an unattached projection, `glob`/`grep` under `dynamicTools: false`, or a name excluded by a narrowed `allowedTools`). Disabled entirely when `global.hideOfficialTools` is false |
| `dynamicTools` | true | Publish the progressive SDK loader `ops_load_sdk`; effective only while `global.dynamicTools` is also on (AND gate) |
| `disclosurePolicy` | `on-demand` | YAML-only explicit first-round disclosure tier: `on-demand` keeps the legacy progressive path (resident + loader); `full` publishes the whole `allowedTools` pool plus `result` in the first round with no loader (implemented; see the D3 addendum in docs/design-decisions-20261119.md). Effective only while `global.dynamicTools` is on — the explicit opt-in never overrides the bundle switch; while it is off the row keeps its legacy resident/always-loaded surface and the saved choice is preserved. Rejected on non-PTC rows; illegal values are errors naming the key and the received value or type. No upgrade, settings save or switch flip ever writes this key for you |
-| `batchingGuidance` | true for `ops-ptc`, false otherwise | Teach once, riding the first accepted root `run_code` result as `additionalContexts` (same-step inbox, never logged history; system prompt untouched), then correct the shape of root `run_code` programs: `bypass`, `plan` and `shape` each latch once per turn and re-arm when the program complies; the notice rides the triggering result as `additionalContexts` and never blocks or rewrites the program. Text lives in the editable `prompts/batching-guidance.md`. YAML-only; an omitted `ops-ptc` section in a legacy whole-row profile override retains true; explicit false disables it |
+| `batchingGuidance` | true for `ops-ptc`, false otherwise | Teach once, as a plain user message on the first accepted pre-step batch (source kind `user`, no plugin envelope, logged history; system prompt untouched), then correct the shape of root `run_code` programs: `bypass`, `plan` and `shape` each latch once per turn and re-arm when the program complies; the notice is queued by the triggering result and appended to the next pre-step as a plain user message, and never blocks or rewrites the program. Text lives in the editable `prompts/batching-guidance.md`. YAML-only; an omitted `ops-ptc` section in a legacy whole-row profile override retains true; explicit false disables it |
| `spillRetentionDays` | 30 | Host subprocess spill retention window; `0` reports only and never deletes |
| `spillTotalBudgetMiB` | 256 | Total retained spill budget in MiB; `0` disables the budget |
| `spillSweepEnabled` | true | Run one bounded sweep on activation and every 256 settlements |
@@ -96,20 +96,18 @@ recorded in the same document's D2 addendum, with publication owned by the D3 sl
### Batch-call guidance (`batchingGuidance`)
-Off contributes no extra context. The code default is on for `ops-ptc` only, even when a legacy profile replaces the whole row config without that section; explicit `batchingGuidance: false` still disables it. On, two kinds of guidance ride tool results as `additionalContexts`, rendered from one
+Off contributes no extra context. The code default is on for `ops-ptc` only, even when a legacy profile replaces the whole row config without that section; explicit `batchingGuidance: false` still disables it. On, two kinds of guidance ride the pre-step batch as plain user messages, rendered from one
external English Markdown file:
-- **Once per agent entry**: one plugin-context message rides the first accepted root `run_code` result as
- `additionalContexts` (source `dsh-ops:step-tail`, contributor `batching-guidance:lesson`). That inbox is
- same-step only and never logged as user history, so the model sees the whole procedure on the request that
- follows the first accepted call: the first-line `// plan:` comment, the dependency split, the
+- **Once per agent entry**: one plain user message rides the first accepted pre-step batch (source kind `user`, no plugin envelope)
+ and enters logged history, so the model sees the whole procedure on the first request: the first-line `// plan:` comment, the dependency split, the
load-before-call step (only while dynamic loading publishes the loader) and four copyable trajectories.
- The first-round text teaches each rule once (revision 7): the anti-pattern rewrite and the prose that
+ The first-round text teaches each rule once (revision 8): the anti-pattern rewrite and the prose that
repeated the dependency split are gone, the core rules state load-only-missing and recheck-after-a-mode-change
explicitly, and the four trajectories ship byte-identical.
- **On a thin program**: when a **root** `run_code` program breaks one of three latched categories, a short
- notice is appended to that call's own result as `additionalContexts`. The tool result keeps its value, its
- content and its existing contexts; the program is never blocked or rewritten.
+ notice is queued by that call and appended to the next pre-step as a plain user message. The tool result keeps
+ its value, its content and its existing contexts; the program is never blocked or rewritten.
- The three categories are `bypass` (file work through the shell or `node:fs`), `plan` (no `// plan:` on the
first physical line) and `shape` (a single operation in its own round trip). Each is latched once per turn,
and a program that complies with a category re-arms it, so a regression inside the same turn speaks again;
@@ -120,9 +118,9 @@ external English Markdown file:
- The analysis is a literal heuristic over the program text: a loop or `map` counts one dispatch site, not its
runtime fan-out, and strings or comments can mislead it. Notices say so, nothing claims a measured dispatch
count, and a cancelled or never-dispatched call is not analysed.
-- Everything rides `additionalContexts` on the tool result and the tool schema is untouched, so the system
- prompt and its cache survive. The lesson is spent at the delivery point — the accepted root `run_code`
- decision — so a call that is cancelled or never accepted leaves the next accepted call free to teach it.
+- Everything rides the pre-step user batch and the tool schema is untouched, so the system prompt and its
+ cache survive. The lesson is spent only once the host commits the delivered message; a batch that is rejected
+ or cancelled commits nothing, so the next accepted batch still teaches it.
- The text follows the published surface. While dynamic loading publishes `ops_load_sdk`, the lesson ships
byte for byte, load step included. With `dynamicTools: false` the scope publishes no loader, so that step and
its table row are replaced by a direct-call section that lists the APIs this scope actually publishes; a
@@ -145,7 +143,11 @@ observation only: no context, no message, no extra dependency.
The text file is `prompts/batching-guidance.md` (shipped with the package, English, editable). It is read
once per path and cached in the process, so restart to apply edits; an unreadable file logs one warning and
skips delivery, an empty file also skips, and a failed delivery only logs a warning without rewriting the
-tool result.
+tool result. Its "Sandbox permissions" section follows the mode the host `sandboxPolicy` reports:
+`danger-full-access` keeps only "this is the widest tier, never send `sandbox_permissions` or
+`justification`", while `workspace-write` and `read-only` keep their own escalation advice; without a host
+policy the shipped three-tier text is delivered unchanged. Only `workspace-write` and `danger-full-access`
+are legal values, and an invalid one rejects the program before it runs (#963).
**Contrast-arm usage.** To compare the guidance on one shared PTC surface, keep `ptc` and `ops-ptc` on the same
API configuration and set `batchingGuidance: true` only on the `ops-ptc` section (the packaged default), or
diff --git a/docs/presets.md b/docs/presets.md
index afb30f1a..709baf6e 100644
--- a/docs/presets.md
+++ b/docs/presets.md
@@ -128,7 +128,7 @@ default comes from that profile's own composition.
| Plugin-manager row | a dedicated preset row | no preset row; lives and dies with the `dsh-ops` row |
| Publication surface | official PTC tools | same as the `ptc` section: `run_code` under real PTC presentation plus the same-stack typed SDK file tools |
| Compaction | official `compaction-basic` | official `compaction-basic` as well; no `dsh-compress-codex` |
-| Batch-call guidance | none | `batchingGuidance`: defaults true in code and the packaged `ops-ptc` section, including legacy whole-row overrides that omit the section; explicit false disables it; one lesson riding the first accepted root `run_code` result, then shape notices for root `run_code` programs (`bypass`/`plan`/`shape`, each latched per turn and re-armed by compliance); both are delivered as `additionalContexts` that never enter logged history; text in the editable `prompts/batching-guidance.md` |
+| Batch-call guidance | none | `batchingGuidance`: defaults true in code and the packaged `ops-ptc` section, including legacy whole-row overrides that omit the section; explicit false disables it; one lesson riding the first accepted pre-step batch, then shape notices for root `run_code` programs (`bypass`/`plan`/`shape`, each latched per turn and re-armed by compliance); both are delivered as plain user messages (source kind `user`, no plugin envelope) that enter logged history; text in the editable `prompts/batching-guidance.md` |
| Single-row section | `ptc` | `ops-ptc` (same keys plus `batchingGuidance`) |
| Default preset | decided by the host/operator | set once by the detail page's button (`applied`/`no-update`); never forced; unloading restores the host default only when the current selection is still `ops-ptc` |
| Ordering | order 2 | order 6, sorted after the official rows |
diff --git a/docs/prompt-injection.md b/docs/prompt-injection.md
index 75d6453f..ac7809b9 100644
--- a/docs/prompt-injection.md
+++ b/docs/prompt-injection.md
@@ -37,11 +37,11 @@ Verified with the installed `0.2.0-rc.2` host's real AgentLoop and fake LLM capt
## Accepted step tails
-`registerStepTailProvider(owner, agent, options)` wraps the host `agent/pre-step` waterfall: after its downstream `next()` returns `enter`, providers run only if that decision contains a nonempty accepted user-message batch. Providers receive a frozen read-only snapshot plus agent, turn, step, and the admission signal. Results are ordered by priority and id and become plugin-attributed `UserMessage` values appended to the admitted batch.
+`registerStepTailProvider(owner, agent, options)` wraps the host `agent/pre-step` waterfall: after its downstream `next()` returns `enter`, providers run only if that decision contains a nonempty accepted user-message batch. Providers receive a frozen read-only snapshot plus agent, turn, step, and the admission signal. Results are ordered by priority and id and become plugin-attributed `UserMessage` values appended to the admitted batch. The delivered text is the provider's text as-is: no synthetic provenance envelope is inserted, and attribution stays in the message `source` metadata.
-This is logged session history, not an ephemeral request overlay, system-role tail, fake user authorization, or a hook guaranteed to run on every model request. Empty batches—including tool-only continuation and turn-closing probes—do not invoke providers and cannot be used to wake a loop. Empty provider results create no message. A provider rejection aborts admission through the host's normal error path; admission-signal cancellation before commit prevents commit. Provider disposal is narrower: it cancels pending evaluation without waiting for non-cooperative promises and filters completed contributions at the final active check, immediately before this hook returns its batch to host pre-step. There is no asynchronous gap between this check and return. This is the snapshot handoff (linearization) boundary, not a revocation guarantee until commit. The installed host then runs `agent/request` and `prepareCall()` before appending the accepted batch to the session log; disposal during those phases does not retract the handed-off snapshot or erase earlier history. Retries reuse the same admitted messages and do not duplicate tails.
+This is logged session history, not an ephemeral request overlay, a system-role tail, or a hook guaranteed to run on every model request. Empty batches—including tool-only continuation and turn-closing probes—do not invoke providers and cannot be used to wake a loop. Empty provider results create no message. A provider rejection aborts admission through the host's normal error path; admission-signal cancellation before commit prevents commit. Provider disposal is narrower: it cancels pending evaluation without waiting for non-cooperative promises and filters completed contributions at the final active check, immediately before this hook returns its batch to host pre-step. There is no asynchronous gap between this check and return. This is the snapshot handoff (linearization) boundary, not a revocation guarantee until commit. The installed host then runs `agent/request` and `prepareCall()` before appending the accepted batch to the session log; disposal during those phases does not retract the handed-off snapshot or erase earlier history. Retries reuse the same admitted messages and do not duplicate tails.
-The source kind is `dsh-ops:step-tail`, with contributor, revision, turn, and step metadata for attribution and replay.
+The source kind is `dsh-ops:step-tail`, with contributor, revision, turn, and step metadata for attribution and replay; the content carries exactly the provider's text.
## Conditional job-wait guidance
diff --git a/docs/prompt-injection.zh.md b/docs/prompt-injection.zh.md
index 1a22ce66..d9a42253 100644
--- a/docs/prompt-injection.zh.md
+++ b/docs/prompt-injection.zh.md
@@ -37,11 +37,11 @@ removeSection()
## 已接纳步骤尾部
-`registerStepTailProvider(owner, agent, options)` 包装宿主 `agent/pre-step` waterfall:下游 `next()` 返回 `enter` 后,只有该决定包含非空的已接纳用户消息 batch 时才运行 provider。provider 收到冻结的只读快照、agent、turn、step 与本次 admission signal。结果按 priority 和 id 排序,并作为带插件归属的 `UserMessage` 追加到已接纳 batch 尾部。
+`registerStepTailProvider(owner, agent, options)` 包装宿主 `agent/pre-step` waterfall:下游 `next()` 返回 `enter` 后,只有该决定包含非空的已接纳用户消息 batch 时才运行 provider。provider 收到冻结的只读快照、agent、turn、step 与本次 admission signal。结果按 priority 和 id 排序,并作为带插件归属的 `UserMessage` 追加到已接纳 batch 尾部。正文就是 provider 返回的原文,不插入额外的来源信封;归属只留在消息 `source` 元数据里。
-这是会写入 session 日志的历史,不是临时 request overlay、system-role 尾部、伪造的用户授权,也不是保证每次模型请求都运行的 hook。空 batch(包括纯工具续步与 turn-closing 探针)不会调用 provider,也不能借此唤醒 loop。空结果不创建消息。provider 拒绝会沿宿主正常错误路径中止 admission;admission signal 在提交前取消会阻止提交。provider 释放的范围更窄:它会取消等待中的计算,不等待不协作的 promise;已完成的贡献会在本 hook 把 batch 交还给宿主 pre-step 之前进行最后一次 active 检查,并且该检查与返回之间没有异步间隙。这就是快照交接(线性化)边界,不是直到 commit 都可撤回的保证。已安装宿主随后还会运行 `agent/request` 和 `prepareCall()`,才把接纳 batch 追加到 session 日志;这些阶段中的释放不会撤回已经交接的快照,也不会擦除已有历史。模型重试复用同一批已接纳消息,不会重复追加尾部。
+这是会写入 session 日志的历史,不是临时 request overlay、system-role 尾部,也不是保证每次模型请求都运行的 hook。空 batch(包括纯工具续步与 turn-closing 探针)不会调用 provider,也不能借此唤醒 loop。空结果不创建消息。provider 拒绝会沿宿主正常错误路径中止 admission;admission signal 在提交前取消会阻止提交。provider 释放的范围更窄:它会取消等待中的计算,不等待不协作的 promise;已完成的贡献会在本 hook 把 batch 交还给宿主 pre-step 之前进行最后一次 active 检查,并且该检查与返回之间没有异步间隙。这就是快照交接(线性化)边界,不是直到 commit 都可撤回的保证。已安装宿主随后还会运行 `agent/request` 和 `prepareCall()`,才把接纳 batch 追加到 session 日志;这些阶段中的释放不会撤回已经交接的快照,也不会擦除已有历史。模型重试复用同一批已接纳消息,不会重复追加尾部。
-source kind 为 `dsh-ops:step-tail`,并携带 contributor、revision、turn、step 元数据以支持归属与回放。
+source kind 为 `dsh-ops:step-tail`,并携带 contributor、revision、turn、step 元数据以支持归属与回放;正文与 provider 返回的原文逐字一致。
## 条件式任务等待指导
diff --git a/docs/ptc-cost-accounts.md b/docs/ptc-cost-accounts.md
index 55a21e0e..5feff907 100644
--- a/docs/ptc-cost-accounts.md
+++ b/docs/ptc-cost-accounts.md
@@ -5,9 +5,9 @@
The common accounting mistakes for OPS-PTC are structural: counting the
`tools:sdk` section twice by adding it on top of a system total that already
contains it, mixing the Native tool schemas into a PTC measurement, or
-misplacing the dsh-ops guidance — the one-time teaching is same-step
-`additionalContexts` on the accepted tool result and is never logged, the shape
-notices are what the guidance account records, and neither is the system prompt.
+misplacing the dsh-ops guidance — the lesson and the shape notices are plain
+user messages on the pre-step batch and enter the history account, and neither
+is the system prompt.
V1 (#990, `test/lib/ptc-entry.mjs`) already guarantees the measured group truly
entered OPS-PTC; this suite extends that entry with the byte accounting and never
lets the four answers blur together.
@@ -24,15 +24,15 @@ Readings below are one run at commit `205cb94`, plugin 0.5.5, host
0.2.2-rc.1, linux-x64, staged worker sha256 `2b5f988d…`, preset `ops-ptc`,
resident + dynamic + batching guidance on, official read/glob/grep mounted.
Absolute bytes are only comparable inside this configuration. The history row records
-the post-#929 composition: the one-time teaching is same-step context, not part of the
-account.
+the current composition: the lesson is a user message on the first request and stays in
+history; its two byte sizes below are measured on the current guidance text.
| Account | First request (resident only) | After the load | Repeat |
| --- | --- | --- | --- |
| system (delivered rendered prompt) | 12,782 B | 37,892 B | 37,892 B |
| — of which `tools:sdk` | 11,739 B | 36,849 B | 36,849 B |
| wire (outer tool schemas) | 2,500 B | 2,500 B | 2,500 B |
-| history (dsh-ops notice) | — | + notice:plan 284 B | unchanged |
+| history (dsh-ops guidance) | teaching 7,538 B | + notice:plan 200 B | unchanged |
- **system** is the delivered rendered prompt, byte-measured exactly as the
provider request carries it; the suite asserts the request's system message
@@ -48,12 +48,10 @@ account.
`run_code` here, byte-identical on every request and equal to the idle
assembly's wire.
- **history** is the dsh-ops guidance the suite records from the messages delivered on
- each request for contributor `batching-guidance`: the plan notice the thin program
- earns (once, 284 B). The one-time teaching never appears there: it rides the first
- accepted root `run_code` result as same-step `additionalContexts` (contributor
- `batching-guidance:lesson`), never logged as user history, so this account carries no
- teaching bytes; its full text is 8,729 B. The suite asserts neither touches the system
- account — the post-notice system sha equals the baseline.
+ each request: the opening lesson (7,538 B in the current text) on the first request,
+ then the plan notice the thin program earns (200 B). Both are plain user messages
+ (source kind `user`, no plugin envelope) on the pre-step batch. The suite asserts
+ neither touches the system account — the post-notice system sha equals the baseline.
## The arithmetic that must hold
diff --git a/docs/usage.md b/docs/usage.md
index e3da8c41..0662837c 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -24,10 +24,10 @@ this row before removing obsolete overrides; OPS does not rewrite profiles autom
Standard and Cordis publish resident Native tools; Minimal has no file baseline; PTC publishes
typed APIs with a separate SDK loader; OPS PTC (`ops-ptc`) is registered at plugin runtime and keeps
-that surface, adding the batch-call guidance from the editable `prompts/batching-guidance.md`: one lesson
-riding the first accepted root `run_code` result, then shape notices for root `run_code` programs
-(`bypass`/`plan`/`shape`, each latched per turn), all delivered as same-step `additionalContexts` that never
-enter logged history (on in the packaged bundle; see [presets](presets.md)).
+that surface, adding the batch-call guidance from the editable `prompts/batching-guidance.md`: one lesson on
+the first accepted pre-step batch, then shape notices for root `run_code` programs
+(`bypass`/`plan`/`shape`, each latched per turn), all delivered as plain user messages (source kind `user`,
+no plugin envelope) that enter logged history (on in the packaged bundle; see [presets](presets.md)).
The default preset is set by one button on the row's detail page; nothing forces or restores it automatically.
Residency, dynamic loading, Bash, file replacement and
Windows host-shell hiding are independently controlled. Global gates preserve saved per-preset
diff --git "a/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" "b/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md"
index e871a1d7..4010b18b 100644
--- "a/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md"
+++ "b/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md"
@@ -16,7 +16,7 @@ Native 文件路径(含 copy/move 的目标)、省略的搜索路径,以
本检出是未发布候选。Bundle 只声明一行 `dsh-ops`:五个预设、动态加载、数据采集、TUI 联动与伴随插件联动都在这一行的插件页里配置(其中第五个预设 `ops-ptc` 由插件运行时注册,定义来自随包片段 `presets/ops-ptc.patch.yml`,不是插件管理器行)。五个预设与 discovery 默认开启,数据采集与 TUI 联动默认关闭。已移除的 `mode-*`、`discovery`、`compat`、`panel`、`tui`、`shell`、`file`、`ptc`、`hide-official` 行的已保存覆盖必须删除,它们在新 bundle 中没有对应行。
-消费者只为匹配预设发布工具。Standard/Cordis 提供 Native 常驻文件工具,Minimal 没有文件常驻基线;PTC 提供类型化 API 与独立 SDK loader;`ops-ptc` 继承同一工具面并默认开启批量调用提示(`batchingGuidance`:随首个被接受的根 `run_code` 结果英文教学一次 + 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮一次、合规解锁)纠偏,均以 `additionalContexts` 投递、从不进入会话历史;文案在可编辑的 `prompts/batching-guidance.md`;YAML 可关;默认预设不自动强制:详情页按钮点一次即设为 `ops-ptc`,apply/重挂载/卸载都不改你自己选的默认,详见[预设与默认模式](预设与默认模式.md))。常驻、动态、Bash、文件替换和 Windows 宿主 Shell 隐藏独立控制,总开关保留各预设保存意图。显式消费者共用装配器,未列出的预设保持原样;内置 Native discovery 可独立于常驻面启用。[配置参考](配置参考.md)说明原生开关页、精确自定义 id 与默认值;迁移见[升级说明](升级与卸载.md#从-04x-迁移到-05x)。
+消费者只为匹配预设发布工具。Standard/Cordis 提供 Native 常驻文件工具,Minimal 没有文件常驻基线;PTC 提供类型化 API 与独立 SDK loader;`ops-ptc` 继承同一工具面并默认开启批量调用提示(`batchingGuidance`:在首个被接受的 pre-step batch 上以普通用户消息英文教学一次 + 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮一次、合规解锁)纠偏,均以普通用户消息投递(source kind `user`、无插件信封)、进入会话历史;文案在可编辑的 `prompts/batching-guidance.md`;YAML 可关;默认预设不自动强制:详情页按钮点一次即设为 `ops-ptc`,apply/重挂载/卸载都不改你自己选的默认,详见[预设与默认模式](预设与默认模式.md))。常驻、动态、Bash、文件替换和 Windows 宿主 Shell 隐藏独立控制,总开关保留各预设保存意图。显式消费者共用装配器,未列出的预设保持原样;内置 Native discovery 可独立于常驻面启用。[配置参考](配置参考.md)说明原生开关页、精确自定义 id 与默认值;迁移见[升级说明](升级与卸载.md#从-04x-迁移到-05x)。
0.5 中,开启原版工具替换不保证条件性工具从模型工具表消失。OPS 对应项采用条件准入时,原版注册仍可见;只有同一已捕获步骤 toolSet 准入该对应项且消费者当前仍有权限时,OPS 才在分派时拒绝原版调用。对应项缺失、撤销或尚未就绪时,不得连带禁用原版工具。安全的无条件常驻替换仍可使用宿主限制。OPS 不包装原版定义,也不在准入条件或提示词组装中隐藏工具。
diff --git "a/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md" "b/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md"
index f55e0234..a9dd7eef 100644
--- "a/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md"
+++ "b/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md"
@@ -2,25 +2,25 @@
## 为什么要有这本账
-OPS-PTC 计量常见的错误是结构性的:把 `tools:sdk` 在已包含它的 system 总量上再加一遍造成双计;把 Native 的工具 schema 混进 PTC 测量;或者放错 dsh-ops 引导的位置:一次性教学随被接受的工具结果走同一步 `additionalContexts`、从不记为历史,history 账只记录形状提醒,两者都不是系统提示。V1(#990,`test/lib/ptc-entry.mjs`)已经保证被测组真正进入 OPS-PTC;本套件在那条入口上补齐字节分账,四本账永远不互相混同。
+OPS-PTC 计量常见的错误是结构性的:把 `tools:sdk` 在已包含它的 system 总量上再加一遍造成双计;把 Native 的工具 schema 混进 PTC 测量;或者放错 dsh-ops 引导的位置:一次性教学与形状提醒都是 pre-step batch 上的普通用户消息、都进入会话历史,两者都不是系统提示。V1(#990,`test/lib/ptc-entry.mjs`)已经保证被测组真正进入 OPS-PTC;本套件在那条入口上补齐字节分账,四本账永远不互相混同。
`test/ptc-cost-accounts.test.mjs` 用 `bootEntryGroup` 启动一个隔离组,先用 `enterPtc` 证明路由,再走一段脚本化场景——首次教学、一个引来 plan 提醒的薄程序、一次合规的 `ops_load_sdk` 加载(`glob`/`grep`/`read_files`)、以及同配置重复请求——每本账都以原始 UTF-8 字节加各项名字清单输出。
## 四本账
-下表读数取自 commit `205cb94`、插件 0.5.5、宿主 0.2.2-rc.1、linux-x64、staged worker sha256 `2b5f988d…`、预设 `ops-ptc`、常驻 + 动态 + 批量教学开启、官方 read/glob/grep 已挂载的一次运行。绝对字节只在同一配置内可比。history 行记录 #929 之后的构成:一次性教学是同一步上下文,不计入该账。
+下表读数取自 commit `205cb94`、插件 0.5.5、宿主 0.2.2-rc.1、linux-x64、staged worker sha256 `2b5f988d…`、预设 `ops-ptc`、常驻 + 动态 + 批量教学开启、官方 read/glob/grep 已挂载的一次运行。绝对字节只在同一配置内可比。history 行记录当前构成:一次性教学以首个请求上的用户消息进入该账;下表中它的两个字节数按当前文案计量。
| 账目 | 首次请求(仅常驻) | 加载后 | 重复 |
| --- | --- | --- | --- |
| system(投递的渲染提示) | 12,782 B | 37,892 B | 37,892 B |
| ——其中 `tools:sdk` | 11,739 B | 36,849 B | 36,849 B |
| wire(外层工具 schema) | 2,500 B | 2,500 B | 2,500 B |
-| history(dsh-ops 提醒) | — | + 提醒:plan 284 B | 不变 |
+| history(dsh-ops 引导) | teaching 7,538 B | + 提醒:plan 200 B | 不变 |
- **system** 是投递出去的渲染提示,按 provider 请求实际携带的口径计字节;套件断言每个配置点的请求 system 消息与空闲快照的渲染结果一致。首次请求的逐项清单:`harness:identity` 48、`tools:ptc-only` 159、`tool:read` 130、`tool:write` 92、`tool:edit` 83、`tool:glob` 75、`tool:grep` 133、`dsh-ops:repository-tooling:mode-ptc` 307、`tools:sdk` 11,739。
- **sdk** 是 system 内唯一的一个 `tools:sdk` 小节——严格子集,绝不是另立账目。归一化规则由断言钉死:system = 逐小节字节按 `\n\n` 连接,即 12,766 + 8 个连接 × 2 B = 12,782,可用上表清单手工复核。
- **wire** 是请求外层工具 schema 的 `JSON.stringify`——本场景恒为 `run_code` 一项,每个请求字节一致,且等于空闲装配的 wire。
-- **history** 是套件按每次请求实际投递的消息、针对 contributor `batching-guidance` 记录的 dsh-ops 引导:薄程序引来的 plan 提醒(一次,284 B)。一次性教学不出现在这里:它随首个被接受的根 `run_code` 结果走同一步 `additionalContexts`(contributor `batching-guidance:lesson`),从不记为 user 历史,因此该账不含教学字节;完整教学正文为 8,729 B。套件断言两者都不进 system 账——提醒之后的 system sha 与基线相同。
+- **history** 是套件按每次请求实际投递的消息记录的 dsh-ops 引导:首个请求上的完整教学(当前文案 7,538 B),随后是薄程序引来的 plan 提醒(200 B)。两者都是 pre-step batch 上的普通用户消息(source kind `user`、无插件信封)。套件断言两者都不进 system 账——提醒之后的 system sha 与基线相同。
## 必须成立的算术
diff --git "a/docs/\347\273\204\344\273\266\345\217\202\350\200\203.md" "b/docs/\347\273\204\344\273\266\345\217\202\350\200\203.md"
index e987f2a9..6d359641 100644
--- "a/docs/\347\273\204\344\273\266\345\217\202\350\200\203.md"
+++ "b/docs/\347\273\204\344\273\266\345\217\202\350\200\203.md"
@@ -16,7 +16,7 @@
`dsh-ops` 行拥有内置和显式配置的消费者方案。Native 发现与 PTC SDK loader 是独立的发布选择;文件替换与宿主 Shell 隐藏也是独立屏蔽。旧入口仅为让旧 profile 可加载,新配置都属于单行。原 `dsh-ops/shell`、`dsh-ops/file`、`dsh-ops/ptc`、`dsh-ops/hide-official` 模块仅作为旧 profile 的 legacy 导出保留,不属于 bundle。
-`ops-ptc` 是单行的第五个内置模式:预设由 `dsh-ops` 在运行时通过宿主 `agentPresets.register` 注册(定义来自随包片段 `presets/ops-ptc.patch.yml`,由宿主 `loadOverlayPatches` 解析),插件管理器里没有对应预设行;插件行禁用/卸载时预设与工具面一起消失。默认预设不会被自动改写:详情页按钮点一次把它设为默认(`applied`/`no-update`/`unavailable`/`failed`),apply、重挂载与卸载都不碰操作者自己的选择,见[预设与默认模式](预设与默认模式.md)。它发布与 `ptc` 相同的工具面,并新增 YAML-only 的 `batchingGuidance`:随首个被接受的根 `run_code` 结果以 `additionalContexts` 教学一次(`prompts/batching-guidance.md`,同一步 ephemeral、从不进入会话历史、不改系统提示词);之后**根** `run_code` 程序命中 `bypass`、`plan`、`shape` 三类锁之一时,在该次调用自身结果上以 `additionalContexts` 追加一条短提醒——每类每轮各锁一次、合规即解锁,优先级 `bypass` → `plan` → `shape`,不阻断也不改写程序。旧 profile 写 `dsh-ops/mode-ops-ptc` 行时仍加载 legacy 模块;merged bundle 下它只告警并保持惰性,配置须迁入单行 `ops-ptc` 分区。
+`ops-ptc` 是单行的第五个内置模式:预设由 `dsh-ops` 在运行时通过宿主 `agentPresets.register` 注册(定义来自随包片段 `presets/ops-ptc.patch.yml`,由宿主 `loadOverlayPatches` 解析),插件管理器里没有对应预设行;插件行禁用/卸载时预设与工具面一起消失。默认预设不会被自动改写:详情页按钮点一次把它设为默认(`applied`/`no-update`/`unavailable`/`failed`),apply、重挂载与卸载都不碰操作者自己的选择,见[预设与默认模式](预设与默认模式.md)。它发布与 `ptc` 相同的工具面,并新增 YAML-only 的 `batchingGuidance`:在首个被接受的 pre-step batch 上以普通用户消息教学一次(`prompts/batching-guidance.md`,source kind `user`、无插件信封、进入会话历史、不改系统提示词);之后**根** `run_code` 程序命中 `bypass`、`plan`、`shape` 三类锁之一时,排队一条短提醒,在下一个 pre-step 以普通用户消息追加——每类每轮各锁一次、合规即解锁,优先级 `bypass` → `plan` → `shape`,不阻断也不改写程序。旧 profile 写 `dsh-ops/mode-ops-ptc` 行时仍加载 legacy 模块;merged bundle 下它只告警并保持惰性,配置须迁入单行 `ops-ptc` 分区。
原 `dsh-ops/background` 组件(FastCtx 后台任务:`ops_run`、`ops_run_background`、`ops_job_output`、`ops_job_list`、`ops_job_kill`)已移除。仍写着它的 profile 行会作为空操作加载:接受任意配置、不发布任何工具,只记录一条警告提示可删除该行。
diff --git "a/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md" "b/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md"
index f1eeba65..ed65eb14 100644
--- "a/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md"
+++ "b/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md"
@@ -48,7 +48,7 @@ OPS 沿用单行插件页:bundle 只插入一个 `dsh-ops` 行。内置预设
| `hideOfficialTools` | true | 隐藏本模式替代的官方文件工具,含 PTC 呈现:PTC 投影能服务对应 `ops_*` 时,官方 `read/glob/grep` 从工具面与 SDK 声明移除;`write/edit/read_image` 保留;投影无法服务某个名字时保留该名字的官方工具(如未就绪、`dynamicTools:false` 下的 `glob/grep`,或 `allowedTools` 收窄排除的名字);`global.hideOfficialTools` 为 false 时整体失效 |
| `dynamicTools` | true | 发布渐进式 SDK 加载器 `ops_load_sdk`;与 `global.dynamicTools` 同时开启才生效(与门) |
| `disclosurePolicy` | `on-demand` | YAML-only 显式首轮披露档位:`on-demand` 保持旧渐进路径(常驻 + loader);`full` 首轮直接发布整个 `allowedTools` 池外加 `result`,且无 loader(已实现,详见 docs/设计决策-20261119.md 的 D3 附录)。仅在 `global.dynamicTools` 开启时生效——显式 opt-in 不压过总开关;关闭期间该行保持旧 resident/alwaysLoaded 面,已保存的选择原样保留。非 PTC 行拒绝该键;非法值报错点名键与收到的值或类型。升级、保存设置与开关翻转都不会替你写入该键 |
-| `batchingGuidance` | `ops-ptc` 为 true,其它模式为 false | 首个被接受的根 `run_code` 结果随 `additionalContexts` 投递一次完整教学(同一步 ephemeral、从不进入会话历史、不改系统提示词),之后按根 `run_code` 程序形状纠偏:`bypass`/`plan`/`shape` 三类每类每轮各锁一次、合规即解锁;提醒以 `additionalContexts` 附在触发调用结果上,不阻断也不改写程序。文案来自可编辑的 `prompts/batching-guidance.md`。仅 YAML 可配;旧 profile 整行覆盖配置且缺少 `ops-ptc` 节时仍默认 true,显式 false 可关闭 |
+| `batchingGuidance` | `ops-ptc` 为 true,其它模式为 false | 在首个被接受的 pre-step batch 上以普通用户消息投递一次完整教学(source kind `user`、无插件信封、进入会话历史、不改系统提示词),之后按根 `run_code` 程序形状纠偏:`bypass`/`plan`/`shape` 三类每类每轮各锁一次、合规即解锁;提醒由触发调用排队、在下一个 pre-step 以普通用户消息追加,不阻断也不改写程序。文案来自可编辑的 `prompts/batching-guidance.md`。仅 YAML 可配;旧 profile 整行覆盖配置且缺少 `ops-ptc` 节时仍默认 true,显式 false 可关闭 |
| `spillRetentionDays` | 30 | 宿主 subprocess spill 保留窗口;`0` 只报告、永不删除 |
| `spillTotalBudgetMiB` | 256 | 保留总字节预算(MiB);`0` 关闭预算 |
| `spillSweepEnabled` | true | 组件激活时与每 256 次结算后执行一次有界清扫 |
@@ -67,15 +67,14 @@ opt-in,其解析契约与保守优先级记录在同一文档的 D2 附录,
### 批量调用提示(`batchingGuidance`)
-关闭时不产生任何额外上下文。代码仅对 `ops-ptc` 默认开启,旧 profile 整行覆盖配置且缺少该节时也保留此默认值;显式 `batchingGuidance: false` 仍可关闭。开启后两类提示都以 `additionalContexts` 附在工具结果上,文案来自外置英文 Markdown:
+关闭时不产生任何额外上下文。代码仅对 `ops-ptc` 默认开启,旧 profile 整行覆盖配置且缺少该节时也保留此默认值;显式 `batchingGuidance: false` 仍可关闭。开启后两类提示都以普通用户消息(source kind `user`、无插件信封)追加到 pre-step batch 上并进入会话历史,文案来自外置英文 Markdown:
-- **每个 agent 一次**:随第一个被接受的根 `run_code` 结果以 `additionalContexts` 追加一条插件上下文
- (来源 `dsh-ops:step-tail`、contributor `batching-guidance:lesson`)。这是同一步的 ephemeral 收件箱,
- 从不记为 user 历史,模型在首个被接受调用之后的请求即可看到完整范式:首行
+- **每个 agent 一次**:在第一个被接受的 pre-step batch 上追加一条普通用户消息
+ (source kind `user`、无插件信封),进入会话历史,模型在首个请求即可看到完整范式:首行
`// plan:` 指令、按依赖拆分、先加载再调用(仅动态加载发布加载器时),以及四条可照抄的轨迹。首轮
- 文案按「每条规则只讲一次」精简(修订号 7):反例改写与重复依赖拆分的散文已删,「只加载缺失 API」
+ 文案按「每条规则只讲一次」精简(修订号 8):反例改写与重复依赖拆分的散文已删,「只加载缺失 API」
与「模式变化后重查 SDK」升为核心规则,四条轨迹逐字节保留。
-- **薄程序触发**:**根** `run_code` 程序命中三类锁中的一类时,在该次调用的结果上以 `additionalContexts`
+- **薄程序触发**:**根** `run_code` 程序命中三类锁中的一类时,由该次调用排队、在下一个 pre-step 以普通用户消息
追加一条短提醒。工具结果的值、正文与既有上下文都不变,程序既不阻断也不改写。
- 三类分别是 `bypass`(用 shell 或 `node:fs` 做文件工作)、`plan`(第一物理行没有 `// plan:`)与 `shape`
(一次往返只做一件事)。每类每轮各锁一次;某个类别一旦合规即解锁,所以同一轮内先改对再退回还会再次
@@ -84,8 +83,8 @@ opt-in,其解析契约与保守优先级记录在同一文档的 D2 附录,
- 只检查根调用(`exec.parent === undefined`)。嵌套的 `tools.ops_*` 属于 PTC 执行层,说明不了这一步的形状。
- 分析是对程序文本的字面启发式:循环或 `map` 只算一个调用站点,不是运行时扇出;字符串与注释也可能误导。
提醒文案会说明这一点,不宣称实测的 dispatch 数;被取消或从未派发的调用不参与分析。
-- 提示全部随工具结果走 `additionalContexts`,tool schema 不变,系统提示词与其缓存因此不受影响。教学在
- 投递点(被接受的根 `run_code` 结果)即算兑现;被取消或从未被接受的调用不消耗它,下一个被接受的调用仍会教学。
+- 提示全部随 pre-step 用户消息投递,tool schema 不变,系统提示词与其缓存因此不受影响。教学在宿主提交
+ 投递消息后才算兑现;被拒绝或取消的 batch 不提交,下一个被接受的 batch 仍会教学。
- 文案跟随实际发布面。动态加载发布 `ops_load_sdk` 时,教学文本逐字节照发,含"先加载再调用"这一步;`dynamicTools:
false` 时该作用域没有加载器,这一步与其表格行会被替换成"直接调用"一节,并列出本作用域实际发布的 API;一个
OPS API 都不发布时则明确说明并指向官方工具。无加载器作用域仅发布 `ops_inspect_local_file` 这一个文件类 API 时,
@@ -102,7 +101,10 @@ opt-in,其解析契约与保守优先级记录在同一文档的 D2 附录,
文案文件是 `prompts/batching-guidance.md`(随包发布,英文、软编码,可直接编辑)。进程内按路径读取一次
并缓存,改完重启生效;读不到文件时打印一次 warning 并跳过投递,空文件同样跳过;投递失败只记一条
-warning,不改写工具结果。
+warning,不改写工具结果。教学里的「Sandbox permissions」一节随宿主 `sandboxPolicy` 报告的当前模式
+渲染:`danger-full-access` 下只保留「已是最宽档,绝不发送 `sandbox_permissions`/`justification`」,
+`workspace-write` 与 `read-only` 各自保留自己的升级建议;宿主没有策略时保留随包的三档原文。合法值只有
+`workspace-write` 与 `danger-full-access`,非法值会在程序执行前被拒(#963)。
**对照臂用法。** 想在同一套 PTC 发布面上比较提示效果时,让 `ptc` 与 `ops-ptc` 两个分区保留相同的 API
配置,只在 `ops-ptc` 节置 `batchingGuidance: true`(随包默认),或反过来在 `ptc` 节置 true 复核提示本身;
diff --git "a/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md" "b/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md"
index f88d933a..717f7177 100644
--- "a/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md"
+++ "b/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md"
@@ -113,7 +113,7 @@ node scripts/sync-preset-ops-ptc.mjs --source [--ou
| 插件管理器行 | 有独立的 preset 行 | 无预设行,随 `dsh-ops` 行启停 |
| 发布面 | 官方 PTC 工具 | 与 `ptc` 分区相同:真实 PTC 呈现下的 `run_code` 加同栈类型化 SDK 文件工具 |
| 压缩 | 官方 `compaction-basic` | 同为官方 `compaction-basic`,不引入 `dsh-compress-codex` |
-| 批量调用提示 | 无 | `batchingGuidance`:代码与随包 `ops-ptc` 节均默认 true,旧配置整行覆盖且缺少该节也保留默认值,显式 false 可关闭;随首个被接受的根 `run_code` 结果教学一次(`additionalContexts`,从不进入会话历史)+ 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮各锁一次、合规解锁)纠偏;文案在可编辑的 `prompts/batching-guidance.md` |
+| 批量调用提示 | 无 | `batchingGuidance`:代码与随包 `ops-ptc` 节均默认 true,旧配置整行覆盖且缺少该节也保留默认值,显式 false 可关闭;在首个被接受的 pre-step batch 上以普通用户消息教学一次(source kind `user`、无插件信封、进入会话历史)+ 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮各锁一次、合规解锁)纠偏;文案在可编辑的 `prompts/batching-guidance.md` |
| 单行配置分区 | `ptc` | `ops-ptc`(键与 `ptc` 相同,另加 `batchingGuidance`) |
| 默认预设 | 由宿主/操作者决定 | 由详情页按钮点一次设定(`applied`/`no-update`),不再自动强制或回退 |
| 排序 | order 2 | order 6,排在官方行之后 |
diff --git a/prompts/batching-guidance.md b/prompts/batching-guidance.md
index 1e8b2385..a1880223 100644
--- a/prompts/batching-guidance.md
+++ b/prompts/batching-guidance.md
@@ -21,6 +21,19 @@ Return enough status and completion facts for the next decision.
8. **Recheck the SDK after a mode change**: a mode or component switch can change
the pool; read the current SDK before planning the next call.
+## Sandbox permissions
+
+`sandbox_permissions` accepts only `workspace-write` or `danger-full-access`, and
+`justification` must accompany it. Never invent a tier name: an invalid value rejects
+the whole program before any line runs.
+
+- **read-only**: reads and searches only. To write, request `workspace-write` (or
+ `danger-full-access`) with a reason.
+- **workspace-write**: work inside the workspace needs no request. Request
+ `danger-full-access` only to leave the workspace.
+- **danger-full-access**: the widest tier. Never send `sandbox_permissions` or
+ `justification`: no wider target exists, and any value invents one.
+
## Step 0 - the plan line
Declare the intended calls on the first line of every program:
diff --git a/src/prompt-injection/index.ts b/src/prompt-injection/index.ts
index 51cdf77d..a434beea 100644
--- a/src/prompt-injection/index.ts
+++ b/src/prompt-injection/index.ts
@@ -122,7 +122,7 @@ async function appendTails(state: AgentState, payload: Omit entry.active).map(({ entry, text }) => createUserMessage({
source: { kind: 'dsh-ops:step-tail', contributor: entry.options.id, revision: entry.options.revision, turn: payload.turn, step: payload.step },
- content: [{ type: 'text', text: `[Plugin context from ${JSON.stringify(entry.options.id)}; not a user instruction or authorization.]\n${text}` }],
+ content: [{ type: 'text', text }],
}))
return messages.length ? { ...decision, messages: [...decision.messages, ...messages] } : decision
}
diff --git a/src/ptc/batching-guidance.ts b/src/ptc/batching-guidance.ts
index 40880ad9..4e5ea210 100644
--- a/src/ptc/batching-guidance.ts
+++ b/src/ptc/batching-guidance.ts
@@ -9,15 +9,13 @@
import { readFileSync } from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
-import type { Agent } from '../adapter/dsh/types.js'
+import type { Agent, SandboxMode } from '../adapter/dsh/types.js'
import { literalShellFileWork } from './shell-file-work.js'
/** Identity of the guidance in the host message source. */
export const BATCHING_GUIDANCE_ID = 'batching-guidance'
-/** Contributor of the one-time full lesson; the per-violation notices keep the base id. */
-export const BATCHING_GUIDANCE_LESSON_ID = `${BATCHING_GUIDANCE_ID}:lesson`
/** Revision of the guidance text; bump it when the wording or the file format changes. */
-export const BATCHING_GUIDANCE_REVISION = '7'
+export const BATCHING_GUIDANCE_REVISION = '8'
/** The shipped guidance file, resolved from this module's own location (src or lib). */
const DEFAULT_GUIDANCE_FILE = new URL('../../prompts/batching-guidance.md', import.meta.url)
@@ -79,6 +77,13 @@ export interface GuidanceSurface {
readonly resident: readonly string[]
/** Public names the loader can add, empty when the scope publishes no loader. */
readonly loadable: readonly string[]
+ /**
+ * The session's current sandbox mode, read from the host policy.
+ *
+ * When present, the lesson states this mode and keeps only its own tier; when
+ * absent, the shipped three-tier lesson is delivered unchanged.
+ */
+ readonly sandbox?: SandboxMode
}
/** The file-work APIs the guidance names, in the order it names them. */
@@ -181,6 +186,8 @@ function stripLoader(rows: readonly string[]): string[] {
/** The heading that starts the loader lesson in the guidance file. */
export const LOAD_SECTION_HEADING = '## Step 3 - load before you call'
+/** The heading that starts the sandbox-authority lesson in the guidance file. */
+export const SANDBOX_SECTION_HEADING = '## Sandbox permissions'
/** A heading that names loading, by word: "payload" is not a load step. */
const LOAD_HEADING = /\bload(?:ing|er)?\b/i
@@ -242,14 +249,15 @@ function directSteps(surface: GuidanceSurface): string[] {
* @returns the next heading index, or the line count when the section is last.
*/
/**
- * The index of the load-step heading, ignoring anything inside a fence.
+ * The index of one exact heading line, ignoring anything inside a fence.
*
* A fenced example that quotes the heading is text, not structure: taking it for the
* anchor would cut the document in the wrong place.
* @param lines - the guidance lines.
+ * @param heading - the exact heading line to find.
* @returns the heading index, or -1 when the file lost it.
*/
-function anchorIndex(lines: readonly string[]): number {
+function headingIndex(lines: readonly string[], heading: string): number {
let fence: string | null = null
for (let index = 0; index < lines.length; index += 1) {
const row = lines[index]!
@@ -262,11 +270,16 @@ function anchorIndex(lines: readonly string[]): number {
fence = opening[1]!
continue
}
- if (row.trim() === LOAD_SECTION_HEADING) return index
+ if (row.trim() === heading) return index
}
return -1
}
+/** The index of the load-step heading; -1 when the file lost it. */
+function anchorIndex(lines: readonly string[]): number {
+ return headingIndex(lines, LOAD_SECTION_HEADING)
+}
+
function nextHeading(lines: readonly string[], from: number): number {
let fence: string | null = null
for (let index = from; index < lines.length; index += 1) {
@@ -296,17 +309,78 @@ function sectionEnd(lines: readonly string[], start: number): number {
}
/**
- * Render the guidance for one published surface.
+ * The sandbox lesson for the mode the host reports.
*
- * A scope with the loader receives the file byte for byte, so the default path is
- * unchanged. A loader-less scope receives the same lesson with the load step
- * replaced: the prose that tells the model to load cannot be true there.
+ * The shipped file carries all three tiers because it is also delivered without a
+ * host policy; when the mode is known, only the active tier's rule is kept, so a
+ * full-access session is never primed with a request it must not make.
+ * @param mode - the session's current sandbox mode.
+ * @returns the replacement lines, heading included.
+ */
+function sandboxLesson(mode: SandboxMode): string[] {
+ const common = [
+ '`sandbox_permissions` accepts only `workspace-write` or `danger-full-access`, and',
+ '`justification` must accompany it. Never invent a tier name: an invalid value rejects',
+ 'the whole program before any line runs.',
+ '',
+ ]
+ switch (mode) {
+ case 'read-only':
+ return [SANDBOX_SECTION_HEADING + ' - current mode: read-only', '', ...common,
+ 'This session runs at read-only: reads and searches only. To write, send',
+ '`sandbox_permissions: \"workspace-write\"` (or `\"danger-full-access\"`) with a',
+ '`justification`.']
+ case 'workspace-write':
+ return [SANDBOX_SECTION_HEADING + ' - current mode: workspace-write', '', ...common,
+ 'This session runs at workspace-write: work inside the workspace needs no request.',
+ 'Send `sandbox_permissions: \"danger-full-access\"` with a `justification` only to',
+ 'leave the workspace.']
+ default:
+ return [SANDBOX_SECTION_HEADING + ' - current mode: danger-full-access', '', ...common,
+ 'This session runs at the widest tier: never send `sandbox_permissions` or',
+ '`justification`. No wider target exists, and any value would invent one.']
+ }
+}
+
+/** Reported once: the shipped file lost the sandbox anchor the renderer rewrites. */
+let warnedSandboxAnchor = false
+
+/**
+ * Replace the sandbox section with the lesson for the reported mode.
+ *
+ * A drifted file keeps its lesson: the replacement is inserted before the first
+ * section rather than dropped, and the drift is reported once.
+ * @param text - the guidance file.
+ * @param mode - the session's current sandbox mode.
+ * @returns the file with the active tier substituted.
+ */
+function replaceSandboxLesson(text: string, mode: SandboxMode): string {
+ const lines = text.split('\n')
+ const replacement = sandboxLesson(mode)
+ const start = headingIndex(lines, SANDBOX_SECTION_HEADING)
+ if (start < 0) {
+ if (!warnedSandboxAnchor) {
+ warnedSandboxAnchor = true
+ console.warn('dsh-ops: the batching guidance lost its "' + SANDBOX_SECTION_HEADING
+ + '" anchor; the sandbox lesson is inserted before the first section instead.')
+ }
+ const at = nextHeading(lines, 0)
+ return [...lines.slice(0, at), ...replacement, '', ...lines.slice(at)].join('\n')
+ }
+ return [...lines.slice(0, start), ...replacement, '', ...lines.slice(sectionEnd(lines, start))].join('\n')
+}
+
+/**
+ * Replace the load step for a scope that publishes no loader.
+ *
+ * The default path does not call this: a loader scope keeps the shipped file
+ * byte for byte unless the sandbox lesson was also substituted. A loader-less scope
+ * cannot load, so the prose and the table row that teach loading are removed.
* @param text - the loaded guidance file.
* @param surface - what the scope publishes.
* @returns the model-facing guidance text.
*/
-export function renderBatchingGuidance(text: string, surface: GuidanceSurface): string {
- if (text === '' || surface.loader) return text
+function replaceLoaderLesson(text: string, surface: GuidanceSurface): string {
const lines = text.split('\n')
const start = anchorIndex(lines)
// Lines that teach loading, and the table row that points at it, never reach a
@@ -331,6 +405,23 @@ export function renderBatchingGuidance(text: string, surface: GuidanceSurface):
return [...before, ...directSteps(surface), '', ...after].join('\n')
}
+/**
+ * Render the guidance for one published surface.
+ *
+ * A scope with the loader receives the shipped file unchanged unless the host
+ * reports a sandbox mode, in which case only the active tier's rule is kept. A
+ * loader-less scope additionally receives the same lesson with the load step
+ * replaced: the prose that tells the model to load cannot be true there.
+ * @param text - the loaded guidance file.
+ * @param surface - what the scope publishes.
+ * @returns the model-facing guidance text.
+ */
+export function renderBatchingGuidance(text: string, surface: GuidanceSurface): string {
+ if (text === '') return text
+ const withSandbox = surface.sandbox === undefined ? text : replaceSandboxLesson(text, surface.sandbox)
+ return surface.loader ? withSandbox : replaceLoaderLesson(withSandbox, surface)
+}
+
// ---- program shape: what one run_code program says about its step ----
/** A program shorter than this is treated as single-step unless it is structured. */
diff --git a/src/publication/ptc.ts b/src/publication/ptc.ts
index 26b95374..bbc9a172 100644
--- a/src/publication/ptc.ts
+++ b/src/publication/ptc.ts
@@ -1,5 +1,5 @@
/** Stable, scoped PTC definitions; DSH resolves selection once per model step. */
-import type { Agent, Context, Fiber, ToolActivationContext, ToolDefinition, ToolRunContext, UserMessage } from '../adapter/dsh/types.js'
+import type { Agent, Context, Fiber, ToolActivationContext, ToolDefinition, ToolRunContext } from '../adapter/dsh/types.js'
import { loadUserMessage } from '../adapter/dsh/host.js'
import { resolvePtcConfig } from '../config.js'
import { acquirePtcFile, acquireSharedFile, isSharedFileApi } from './scope-owner.js'
@@ -13,7 +13,7 @@ import { renderSdkDirectory } from '../projections/ptc/directory.js'
import type { ApiName } from '../ptc/config.js'
import { disclosurePlan } from '../ptc/disclosure.js'
import { ownPtcScopes } from '../ptc/ownership.js'
-import { BATCHING_GUIDANCE_ID, BATCHING_GUIDANCE_LESSON_ID, BATCHING_GUIDANCE_REVISION, createProgramLatch, loadBatchingGuidance, renderBatchingGuidance } from '../ptc/batching-guidance.js'
+import { createProgramLatch, loadBatchingGuidance, renderBatchingGuidance } from '../ptc/batching-guidance.js'
import type { GuidanceSurface } from '../ptc/batching-guidance.js'
import { InvocationLifetime, InvocationNotStarted } from '../lifecycle/invocations.js'
import { monitoredInvoke } from '../execution/monitored.js'
@@ -54,8 +54,14 @@ interface Entry {
pending: Set
definitions: Map
disposers: (() => void)[]
- /** Whether this agent already received the one-time lesson through the ephemeral tool-result inbox. */
+ /** Whether the one-time lesson was committed to this agent's durable history. */
taught: boolean
+ /** Identity of the lesson message awaiting the host's durable commit. */
+ lessonId?: string
+ /** Plain user-text guidance waiting for the next pre-step. */
+ queuedGuidance: string[]
+ /** Host turn the delivery window belongs to; stale notices are dropped. */
+ guidanceTurn: number
files: Map void; dispatch: ToolDefinition['execute']; granted?: { entitled: boolean; selected: boolean; config: object } }>
}
/** Consumer routing controls; invocation authority always remains host-owned. */
@@ -63,7 +69,7 @@ export interface PtcGate {
guidance?: boolean
resident?: boolean
dynamic?: boolean
- /** Deliver the program-shape batch notice through tool-result context. */
+ /** Deliver the one-time lesson and program-shape notices as user messages. */
batching?: boolean
/** Emit one structured line per delivered notice; observation only, never context. */
telemetry?: boolean
@@ -154,18 +160,10 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
loader: plan.loader,
resident: [...resident].filter(api => reachable(mode, api)).map(api => publicToolName(api)),
loadable: allowedApis(agent).map(api => publicToolName(api)),
+ sandbox: mode,
}
}
const shapeLatch = createProgramLatch(surfaceFor)
- // The one-time lesson and the per-violation notices share a revision; the
- // contributor suffix lets listeners tell the full lesson from a notice.
- const guidanceMessage = async (turn: number, text: string, contributor: string = BATCHING_GUIDANCE_ID): Promise => {
- const createUserMessage = await loadUserMessage()
- return createUserMessage({
- source: { kind: 'dsh-ops:step-tail', contributor, revision: BATCHING_GUIDANCE_REVISION, turn, step: 0 },
- content: [{ type: 'text', text: `[Plugin context from ${JSON.stringify(contributor)}; not a user instruction or authorization.]\n${text}` }],
- })
- }
/** Point a declared-but-unselected pool API at the loader; undefined when loading cannot help (#968). */
const deferredRejection = (entry: Entry, api: ApiName): Outcome | undefined => {
@@ -272,7 +270,7 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
if (stopped || retired.has(agent) || !agent.ctx || !owns(agent)) return Promise.resolve()
const existing = entries.get(agent)
if (existing) return existing.ready
- const entry: Entry = { agent, ready: Promise.resolve(), calls: new InvocationLifetime(), selected: new Set(), pending: new Set(), definitions: new Map(), disposers: [], taught: false, files: new Map() }
+ const entry: Entry = { agent, ready: Promise.resolve(), calls: new InvocationLifetime(), selected: new Set(), pending: new Set(), definitions: new Map(), disposers: [], taught: false, queuedGuidance: [], guidanceTurn: -1, files: new Map() }
entries.set(agent, entry); ownership?.track(agent)
entry.ready = Promise.resolve().then(async () => {
if (!owns(agent) || entries.get(agent) !== entry) return
@@ -282,9 +280,50 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
// A new host turn starts a fresh repeated-write window. This listener is
// agent-scoped and unwinds with the entry's other disposers.
if (gate.batching === true) {
+ // Deliver the one-time lesson and every corrective notice as plain user
+ // text on the pre-step batch: the same role, source and shape as a real
+ // user instruction, with no plugin envelope that discounts it.
entry.disposers.push(agent.ctx!.on('agent/pre-step', async (payload, next) => {
if (payload.agent === agent) shapeLatch.noteTurn(agent, payload.turn)
- return next()
+ const decision = await next()
+ if (payload.agent !== agent || decision.kind !== 'enter' || payload.signal.aborted) return decision
+ if (stopped || entries.get(agent) !== entry || !entry.ctx) return decision
+ // A new host turn opens a fresh delivery window: a notice queued by an
+ // aborted step must not surface in a later turn.
+ if (entry.guidanceTurn !== payload.turn) {
+ entry.guidanceTurn = payload.turn
+ entry.queuedGuidance.length = 0
+ }
+ const texts: string[] = []
+ let lessonQueued = false
+ // Teach once, before the model's first request: the lesson rides the
+ // user's own accepted batch, so the model reads it as the instruction
+ // that governs the task instead of a tool result it can ignore.
+ if (!entry.taught) {
+ try {
+ // Render for the surface this step actually publishes (P1): a
+ // loader-less row never teaches the loader, and a read-only scope
+ // never names a write API.
+ const lesson = renderBatchingGuidance(loadBatchingGuidance(), surfaceFor(agent))
+ if (lesson.length > 0) { texts.push(lesson); lessonQueued = true }
+ } catch (error) {
+ // A delivery failure is an optimisation loss, never a turn failure.
+ ctx.logger.warn('dsh-ops: batching lesson rendering failed: ' + String(error))
+ }
+ }
+ texts.push(...entry.queuedGuidance.splice(0))
+ if (texts.length === 0) return decision
+ const createUserMessage = await loadUserMessage()
+ if (stopped || entries.get(agent) !== entry) return decision
+ const messages = texts.map(text => createUserMessage({
+ source: { kind: 'user' },
+ content: [{ type: 'text', text }],
+ }))
+ // Count the lesson as taught only once the host commits that exact
+ // message: the session/event latch below observes the durable commit, so
+ // a rejected or cancelled batch teaches again on the next accepted batch.
+ if (lessonQueued) entry.lessonId = messages[0]!.id
+ return { ...decision, messages: [...decision.messages, ...messages] }
}))
// The program-shape trigger observes the ROOT run_code call: only there is
// the whole program text visible. Nested tools.ops_* calls carry a parent
@@ -295,44 +334,25 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
if (exec.agent !== agent || exec.name !== 'run_code' || exec.parent !== undefined) return decision
if (exec.signal.aborted) return decision
const code = (exec.arguments as { code?: unknown } | undefined)?.code
- // Teach the rules once, riding the first accepted root run_code result:
- // additionalContexts is the same-step ephemeral inbox, never logged
- // history, so a lesson can never read as fresh user input and the
- // model's answer cannot loop on its own guidance (#929). The latch is
- // set at the delivery point: a post-execute decision that returns is
- // the tool result the host renders, with no later admission step that
- // could still withdraw it.
- const contexts = [...(decision.additionalContexts ?? [])]
try {
- // Render the lesson for the surface this step actually publishes (P1):
- // a loader-less row never teaches the loader, and a read-only scope never
- // names a write API.
- if (!entry.taught) {
- const text = renderBatchingGuidance(loadBatchingGuidance(), surfaceFor(agent))
- if (text.length > 0) {
- contexts.push(await guidanceMessage(shapeLatch.stats(agent).turn, text, BATCHING_GUIDANCE_LESSON_ID))
- entry.taught = true
- }
- }
+ // Queue the corrective notice for the next pre-step, where it is
+ // delivered as plain user text; the tool result keeps its own value,
+ // content and contexts untouched.
const notice = shapeLatch.observe(agent, code)
if (notice !== undefined) {
- const message = await guidanceMessage(notice.turn, notice.text)
+ entry.queuedGuidance.push(notice.text)
// Observation only: one line, no context, no new dependency.
if (gate.telemetry === true) {
const counts = shapeLatch.stats(agent)
ctx.logger.info('dsh-ops batching: turn=' + notice.turn + ' category=' + notice.category
+ ' plan=' + counts.plan + ' bypass=' + counts.bypass + ' shape=' + counts.shape + ' total=' + counts.total)
}
- contexts.push(message)
}
- // Append only: the tool result keeps its own value, content and contexts.
- return contexts.length > 0 ? { ...decision, additionalContexts: contexts } : decision
} catch (error) {
- // A delivery failure is an optimisation loss, never a tool failure:
- // contexts already collected still ride this result.
- ctx.logger.warn('dsh-ops: batching notice delivery failed: ' + String(error))
- return contexts.length > 0 ? { ...decision, additionalContexts: contexts } : decision
+ // A delivery failure is an optimisation loss, never a tool failure.
+ ctx.logger.warn('dsh-ops: batching notice queueing failed: ' + String(error))
}
+ return decision
}))
}
const publish = (api: ApiName | 'load_sdk', def: ToolDefinition): void => {
@@ -422,10 +442,15 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al
ctx.on('session/event', (session, event) => {
if ((event as { type: string }).type === 'agent-preset/selected') { refresh(); return }
for (const [agent, entry] of entries) if (agent.session === session) {
- // The batching lesson no longer latches on user/message events: it rides
- // the first accepted root run_code tool result, whose returned decision is
- // the delivery point itself, so there is no admission step to wait for.
- if (event.type === 'step/end') {
+ // The lesson counts as taught only once the host commits the exact message
+ // the pre-step delivered: a rejected or cancelled batch commits nothing, so
+ // the next accepted batch teaches again instead of going silent forever.
+ if (event.type === 'user/message') {
+ if (entry.lessonId !== undefined && (event.data as { id?: unknown }).id === entry.lessonId) {
+ entry.taught = true
+ entry.lessonId = undefined
+ }
+ } else if (event.type === 'step/end') {
for (const api of entry.pending) if (permitted(agent, api)) entry.selected.add(api)
entry.pending.clear()
rotateFiles(entry)
diff --git a/test/batching-guidance.test.mjs b/test/batching-guidance.test.mjs
index c97d5b98..4cce9309 100644
--- a/test/batching-guidance.test.mjs
+++ b/test/batching-guidance.test.mjs
@@ -7,7 +7,7 @@
import fs from 'node:fs'
import path from 'node:path'
import { assert, test, report, PACKAGE_ROOT } from './lib/harness.mjs'
-import { BATCHING_GUIDANCE_ID, BATCHING_GUIDANCE_REVISION, LOAD_PROSE_ANCHOR, LOAD_SECTION_HEADING, LOAD_TABLE_ROW_PREFIX, loadBatchingGuidance, renderBatchingGuidance } from '../lib/ptc/batching-guidance.js'
+import { BATCHING_GUIDANCE_ID, BATCHING_GUIDANCE_REVISION, LOAD_PROSE_ANCHOR, LOAD_SECTION_HEADING, LOAD_TABLE_ROW_PREFIX, SANDBOX_SECTION_HEADING, loadBatchingGuidance, renderBatchingGuidance } from '../lib/ptc/batching-guidance.js'
/** The editable guidance file shipped at the package root, outside the build output. */
const GUIDANCE_FILE = path.join(PACKAGE_ROOT, 'prompts', 'batching-guidance.md')
@@ -20,7 +20,7 @@ await test('the shipped guidance is English Markdown with its host-source identi
}
assert.equal(BATCHING_GUIDANCE_ID, 'batching-guidance')
// A wording or format change is a product change and must bump the revision.
- assert.equal(BATCHING_GUIDANCE_REVISION, '7')
+ assert.equal(BATCHING_GUIDANCE_REVISION, '8')
})
await test('the guidance loader returns exactly the shipped Markdown file', () => {
@@ -130,7 +130,7 @@ await test('the trimmed lesson keeps the four trajectories and restores the two
await test('the shipped lesson measures its declared trimmed size', () => {
// The trim record in the PR declares this size; a wording edit must bump the
// revision and this number together. The 84 B delivery prefix is counted separately.
- assert.equal(Buffer.byteLength(loadBatchingGuidance(), 'utf8'), 7538)
+ assert.equal(Buffer.byteLength(loadBatchingGuidance(), 'utf8'), 8169)
})
await test('a scope with the loader receives the shipped file unchanged', () => {
@@ -141,6 +141,53 @@ await test('a scope with the loader receives the shipped file unchanged', () =>
assert.equal(renderBatchingGuidance('', { loader: false, resident: ['ops_glob'], loadable: [] }), '')
})
+await test('the sandbox lesson names both legal values and the full-access prohibition', () => {
+ // #963: a full-access program that invents a wider tier is rejected before it runs,
+ // so the lesson must state the closed vocabulary and forbid the request at the top.
+ const text = loadBatchingGuidance()
+ assert.match(text, /## Sandbox permissions/, 'the shipped lesson carries the sandbox rules')
+ assert.match(text, /accepts only `workspace-write` or `danger-full-access`/, 'the vocabulary is closed')
+ assert.match(text, /Never invent a tier name/, 'inventing a value is called out')
+ assert.match(text, /\*\*danger-full-access\*\*: the widest tier\. Never send `sandbox_permissions` or/, 'full access forbids the request')
+})
+
+await test('a reported sandbox mode keeps only its own tier', () => {
+ const text = loadBatchingGuidance()
+ const full = renderBatchingGuidance(text, { loader: true, resident: [], sandbox: 'danger-full-access' })
+ assert.match(full, /## Sandbox permissions - current mode: danger-full-access/)
+ assert.match(full, /widest tier: never send `sandbox_permissions` or/)
+ assert.equal(full.includes('**read-only**'), false, 'inactive tiers are not primed')
+ const readOnly = renderBatchingGuidance(text, { loader: true, resident: [], sandbox: 'read-only' })
+ assert.match(readOnly, /## Sandbox permissions - current mode: read-only/)
+ assert.match(readOnly, /To write, send/)
+ assert.equal(readOnly.includes('**danger-full-access**'), false, 'inactive tiers are gone here too')
+ const workspace = renderBatchingGuidance(text, { loader: true, resident: [], sandbox: 'workspace-write' })
+ assert.match(workspace, /## Sandbox permissions - current mode: workspace-write/)
+ assert.match(workspace, /leave the workspace/)
+ assert.equal(workspace.includes('**read-only**'), false)
+ // Substituting one section must not disturb the rest of the lesson.
+ for (const rendered of [full, readOnly, workspace]) {
+ assert.ok(rendered.includes('## Step 0 - the plan line'), 'the rest of the lesson survives')
+ assert.ok(rendered.includes('## Common mistakes'), 'the closing table survives')
+ assert.ok(rendered.includes('## Trajectory 4 - paging'), 'the trajectories survive')
+ }
+})
+
+await test('a loader-less scope keeps the sandbox tier and drops the load step together', () => {
+ const rendered = renderBatchingGuidance(loadBatchingGuidance(), { loader: false, resident: ['ops_glob'], loadable: [], sandbox: 'read-only' })
+ assert.match(rendered, /## Sandbox permissions - current mode: read-only/)
+ assert.equal(rendered.includes('ops_load_sdk'), false, 'the load step is still gone')
+ assert.ok(rendered.includes('ops_glob'), 'the published surface is still listed')
+})
+
+await test('a drifted sandbox anchor inserts the tier instead of silently dropping it', () => {
+ const drifted = '# Batch tool calls\n\nintro\n## Step 0 - the plan line\nbody\n'
+ const out = renderBatchingGuidance(drifted, { loader: true, resident: [], sandbox: 'danger-full-access' })
+ assert.match(out, /## Sandbox permissions - current mode: danger-full-access/)
+ assert.ok(out.includes('## Step 0 - the plan line'), 'the following section survives')
+ assert.ok(out.startsWith('# Batch tool calls'), 'the H1 stays first')
+})
+
await test('a loader-less scope is never taught to load', () => {
const rendered = renderBatchingGuidance(loadBatchingGuidance(), { loader: false, resident: ['ops_glob', 'ops_grep'], loadable: [] })
// The defect this guards: the lesson named a call that cannot succeed in this scope.
@@ -229,6 +276,7 @@ await test('the shipped file still carries the anchors the renderer rewrites', (
// The loader-less rendering edits prose by anchor: moving either one must fail here, not at runtime.
const lines = loadBatchingGuidance().split('\n')
assert.ok(lines.some(line => line.trim() === LOAD_SECTION_HEADING), 'the load heading is present')
+ assert.ok(lines.some(line => line.trim() === SANDBOX_SECTION_HEADING), 'the sandbox heading is present')
assert.ok(lines.some(line => line.startsWith(LOAD_TABLE_ROW_PREFIX)), 'the load row is present')
// The Step 1 prose must sit on its own line, or the prose filter would cut a shared
// line short and leave the split lesson truncated.
diff --git a/test/prompt-ephemeral-teaching.test.mjs b/test/prompt-ephemeral-teaching.test.mjs
deleted file mode 100644
index 5246460e..00000000
--- a/test/prompt-ephemeral-teaching.test.mjs
+++ /dev/null
@@ -1,109 +0,0 @@
-/**
- * The batching lesson rides a tool result, never the user batch (#929).
- *
- * The step-tail channel appends UserMessages to an accepted user batch, which
- * the host logs as durable history: a lesson that arrives there reads as fresh
- * user input, and the model answers the lesson instead of the task, looping on
- * its own guidance. These checks pin the replacement contract: the user batch
- * carries no guidance at all, the first accepted root `run_code` result carries
- * the full lesson exactly once through the same-step ephemeral inbox
- * (`additionalContexts`), and nothing re-enters the user batch afterwards.
- */
-import { createScope, scopeOf, scopeParentOf } from '@deepseek-ai/dsh-scope'
-import Subprocess from '@deepseek-ai/dsh-subprocess-local'
-import Sandbox from '@deepseek-ai/dsh-sandbox-local'
-import FileSystem from '@deepseek-ai/dsh-fs-local'
-import NodePtc from '@deepseek-ai/dsh-ptc-runtime-node'
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { apply } from '../lib/index.js'
-import { publicToolName } from '../lib/policy.js'
-import { bootHost, shutdown } from './lib/host.mjs'
-import { prepareStep, executeCall, selectExecutor } from './lib/executor.mjs'
-import { assert, test, report, waitFor, withTempDir } from './lib/harness.mjs'
-import { WORKER, requireWorker } from './lib/boundary.mjs'
-
-requireWorker('prompt-ephemeral-teaching')
-let sequence = 0
-
-const names = (ctx, agent) => ctx.get('tools').definitions(agent, agent.prepared?.toolSet).map(tool => tool.name).sort()
-
-async function scoped(parent, key, parentKey) {
- let result
- await parent.plugin({ inject: ['tools'], apply: inner => {
- result = createScope(inner, key, parentKey ? { parent: parentKey } : undefined).ctx
- } })
- return result
-}
-
-/** The same merged-row fixture resident-switch uses, restricted to the ops-ptc row. */
-async function setup(cwd) {
- const { ctx } = await bootHost({ withWorkingDirectory: true })
- await ctx.plugin(Subprocess); await ctx.plugin(Sandbox); await ctx.plugin(FileSystem); await ctx.plugin(NodePtc)
- ctx.provide('sandboxPolicy', { resolve: ({ session } = {}) => ({ mode: session?.mode ?? 'danger-full-access', workspaceRoot: cwd, sessionId: session?.id }) })
- const presets = new Map(), agents = []
- ctx.provide('agents', { list: () => [...agents] })
- ctx.provide('agentPresets', { composedPreset: inner => presets.get(scopeParentOf(scopeOf(inner))) })
- const config = { global: {}, discovery: { binaryPath: WORKER, required: true } }
- for (const id of ['minimal', 'standard', 'ptc', 'ops-ptc', 'cordis']) config[id] = { enabled: id === 'ops-ptc',
- binaryPath: WORKER, required: true, ...(id === 'ops-ptc' ? { residentTools: true, dynamicTools: true, batchingGuidance: true, alwaysLoaded: ['stat'], allowedTools: ['stat'] } : {}) }
- await ctx.plugin({ name: 'prompt-ephemeral-teaching-fixture', apply: inner => apply(inner, config) })
- const id = 'ephemeral-' + ++sequence, preset = await scoped(ctx, { preset: id })
- presets.set(scopeOf(preset), 'ops-ptc')
- const agent = { id, session: { id, mode: 'danger-full-access', header: { cwd }, append() {}, read() { return [] } } }
- agent.ctx = await scoped(preset, agent, scopeOf(preset))
- await agent.ctx.plugin({ inject: ['tools', 'systemPrompt'], apply: inner => { selectExecutor(inner, 'ptc') } })
- agents.push(agent)
- await ctx.serial('agent/created', { agent })
- agent.prepared = await prepareStep(ctx, agent)
- return { ctx, agent }
-}
-
-/** Drive the real agent pre-step waterfall once, exactly as the host loop does. */
-const drivePreStep = async (agent, turn) => {
- const accepted = createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: 'Start the task.' }] })
- return agent.ctx.waterfall('agent/pre-step', {
- agent, messages: [accepted], turn, step: 1, signal: new AbortController().signal,
- modelSelection: { provider: 'fixture', model: 'capture' },
- }, async () => ({ kind: 'enter', messages: [accepted] }))
-}
-
-/** The one-time full lesson the first accepted root result carries. */
-const guidedContexts = result => (result.additionalContexts ?? []).filter(context => context.source?.kind === 'dsh-ops:step-tail' && context.source?.contributor === 'batching-guidance:lesson')
-
-/** A compliant root program: plan line, two dispatches under Promise.all, no bypass. */
-const compliantProgram = '// plan: two checks\nconst [a, b] = await Promise.all([tools.ops_stat({ path: "x" }), tools.ops_stat({ path: "y" })])\nreturn [a.status, b.status]'
-
-const rootCall = (ctx, agent, callId) => executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
- arguments: { description: 'Compliant fixture', code: compliantProgram }, callId, signal: new AbortController().signal })
-
-await test('the user batch carries no batching guidance, before or after the lesson', () => withTempDir('ephemeral-pre', async cwd => {
- const { ctx, agent } = await setup(cwd)
- try {
- await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
- const first = await drivePreStep(agent, 1)
- const before = first.messages.filter(message => message.source?.kind === 'dsh-ops:step-tail')
- assert.equal(before.length, 0, 'a user-role lesson reads as fresh user input and the model answers it (#929)')
- const run = await rootCall(ctx, agent, 'ephemeral-teach-1')
- assert.equal(run.isError, false, JSON.stringify(run))
- const after = (await drivePreStep(agent, 2)).messages.filter(message => message.source?.kind === 'dsh-ops:step-tail')
- assert.equal(after.length, 0, 'nothing re-enters the user batch once the lesson is delivered')
- } finally { await shutdown(ctx) }
-}))
-
-await test('the first accepted root run_code result carries the full lesson exactly once', () => withTempDir('ephemeral-once', async cwd => {
- const { ctx, agent } = await setup(cwd)
- try {
- await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
- const first = await rootCall(ctx, agent, 'ephemeral-teach-2')
- assert.equal(first.isError, false, JSON.stringify(first))
- const taught = guidedContexts(first)
- assert.equal(taught.length, 1, JSON.stringify(first.additionalContexts))
- assert.match(JSON.stringify(taught), /Batch tool calls/)
- assert.match(JSON.stringify(taught), /not a user instruction or authorization/)
- const second = await rootCall(ctx, agent, 'ephemeral-teach-3')
- assert.equal(second.isError, false, JSON.stringify(second))
- assert.equal(guidedContexts(second).length, 0, 'the lesson is spent after its one delivery')
- } finally { await shutdown(ctx) }
-}))
-
-report('prompt-ephemeral-teaching')
diff --git a/test/prompt-injection.test.mjs b/test/prompt-injection.test.mjs
index 11294be2..1dc279cb 100644
--- a/test/prompt-injection.test.mjs
+++ b/test/prompt-injection.test.mjs
@@ -55,7 +55,8 @@ await test('real loop appends ordered attributed messages after accepted input,
assert.equal(request.messages.find(m => m.source?.kind === 'user').content[0].text, 'Real user task.')
assert.deepEqual(tailMessages(request).map(m => m.source.contributor), ['a', 'b', 'z'])
assert.equal(request.messages.at(-1), tailMessages(request).at(-1))
- for (const m of tailMessages(request)) { assert.equal(m.role, 'user'); assert.match(m.content[0].text, /not a user instruction or authorization/); assert.notEqual(m.source.kind, 'user') }
+ assert.deepEqual(tailMessages(request).map(m => m.content[0].text), ['A', 'B', 'Last {{literal}}'])
+ for (const m of tailMessages(request)) { assert.equal(m.role, 'user'); assert.equal(m.source.kind, 'dsh-ops:step-tail'); assert.equal(m.content[0].text.includes('not a user instruction'), false) }
assert.match(request.messages.at(-1).content[0].text, /Last \{\{literal\}\}/)
assert.deepEqual(h.requests[1].messages.map(m => m.id), request.messages.map(m => m.id))
const committed = h.events.filter(({ session, event }) => session === a.session && event.type === 'user/message').map(({ event }) => event)
diff --git a/test/prompt-user-teaching.test.mjs b/test/prompt-user-teaching.test.mjs
new file mode 100644
index 00000000..1fa4e892
--- /dev/null
+++ b/test/prompt-user-teaching.test.mjs
@@ -0,0 +1,134 @@
+/**
+ * The batching lesson and the corrective notices ride the pre-step batch as plain
+ * user text.
+ *
+ * The lesson is one user-role message on the first accepted batch, before the
+ * model's first request; a violation queues one short notice that the next
+ * pre-step appends the same way. Neither carries a plugin envelope or a
+ * tool-result context, so the model reads them exactly as the user's own
+ * instructions.
+ */
+import { createScope, scopeOf, scopeParentOf } from '@deepseek-ai/dsh-scope'
+import Subprocess from '@deepseek-ai/dsh-subprocess-local'
+import Sandbox from '@deepseek-ai/dsh-sandbox-local'
+import FileSystem from '@deepseek-ai/dsh-fs-local'
+import NodePtc from '@deepseek-ai/dsh-ptc-runtime-node'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { apply } from '../lib/index.js'
+import { publicToolName } from '../lib/policy.js'
+import { bootHost, shutdown } from './lib/host.mjs'
+import { prepareStep, executeCall, selectExecutor } from './lib/executor.mjs'
+import { assert, test, report, waitFor, withTempDir } from './lib/harness.mjs'
+import { WORKER, requireWorker } from './lib/boundary.mjs'
+
+requireWorker('prompt-user-teaching')
+let sequence = 0
+
+const names = (ctx, agent) => ctx.get('tools').definitions(agent, agent.prepared?.toolSet).map(tool => tool.name).sort()
+
+async function scoped(parent, key, parentKey) {
+ let result
+ await parent.plugin({ inject: ['tools'], apply: inner => {
+ result = createScope(inner, key, parentKey ? { parent: parentKey } : undefined).ctx
+ } })
+ return result
+}
+
+/** The same merged-row fixture resident-switch uses, restricted to the ops-ptc row. */
+async function setup(cwd, { batchingGuidance = true } = {}) {
+ const { ctx } = await bootHost({ withWorkingDirectory: true })
+ await ctx.plugin(Subprocess); await ctx.plugin(Sandbox); await ctx.plugin(FileSystem); await ctx.plugin(NodePtc)
+ ctx.provide('sandboxPolicy', { resolve: ({ session } = {}) => ({ mode: session?.mode ?? 'danger-full-access', workspaceRoot: cwd, sessionId: session?.id }) })
+ const presets = new Map(), agents = []
+ ctx.provide('agents', { list: () => [...agents] })
+ ctx.provide('agentPresets', { composedPreset: inner => presets.get(scopeParentOf(scopeOf(inner))) })
+ const config = { global: {}, discovery: { binaryPath: WORKER, required: true } }
+ for (const id of ['minimal', 'standard', 'ptc', 'ops-ptc', 'cordis']) config[id] = { enabled: id === 'ops-ptc',
+ binaryPath: WORKER, required: true, ...(id === 'ops-ptc' ? { residentTools: true, dynamicTools: true, batchingGuidance, alwaysLoaded: ['stat'], allowedTools: ['stat'] } : {}) }
+ await ctx.plugin({ name: 'prompt-user-teaching-fixture', apply: inner => apply(inner, config) })
+ const id = 'user-teaching-' + ++sequence, preset = await scoped(ctx, { preset: id })
+ presets.set(scopeOf(preset), 'ops-ptc')
+ const agent = { id, session: { id, mode: 'danger-full-access', header: { cwd }, append() {}, read() { return [] } } }
+ agent.ctx = await scoped(preset, agent, scopeOf(preset))
+ await agent.ctx.plugin({ inject: ['tools', 'systemPrompt'], apply: inner => { selectExecutor(inner, 'ptc') } })
+ agents.push(agent)
+ await ctx.serial('agent/created', { agent })
+ agent.prepared = await prepareStep(ctx, agent)
+ return { ctx, agent }
+}
+
+/** Drive the real agent pre-step waterfall once, exactly as the host loop does. */
+const drivePreStep = async (agent, turn) => {
+ const accepted = createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: 'Start the task.' }] })
+ const decision = await agent.ctx.waterfall('agent/pre-step', {
+ agent, messages: [accepted], turn, step: 1, signal: new AbortController().signal,
+ modelSelection: { provider: 'fixture', model: 'capture' },
+ }, async () => ({ kind: 'enter', messages: [accepted] }))
+ return { accepted, decision }
+}
+/** Guidance appended to the accepted batch as plain user text; never the accepted message itself. */
+const guidanceOf = ({ accepted, decision }) => decision.messages.filter(message => message.id !== accepted.id && message.source?.kind === 'user')
+const textsOf = messages => messages.map(message => message.content.map(part => part.text ?? '').join('')).join('\n')
+
+/** A compliant root program: plan line, two dispatches under Promise.all, no bypass. */
+const compliantProgram = '// plan: two checks\nconst [a, b] = await Promise.all([tools.ops_stat({ path: "x" }), tools.ops_stat({ path: "y" })])\nreturn [a.status, b.status]'
+const thinProgram = 'const r = await tools.ops_stat({ path: "x" })\nreturn r.status'
+const rootCall = (ctx, agent, callId, code = compliantProgram) => executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
+ arguments: { description: 'Fixture program', code }, callId, signal: new AbortController().signal })
+
+await test('the opening lesson rides the first accepted pre-step as plain user text', () => withTempDir('user-teach-open', async cwd => {
+ const { ctx, agent } = await setup(cwd)
+ try {
+ await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
+ const first = await drivePreStep(agent, 1)
+ const taught = guidanceOf(first)
+ assert.equal(taught.length, 1, JSON.stringify(first.decision.messages))
+ assert.equal(taught[0].source.kind, 'user', 'the guidance carries the user source, not a plugin context')
+ const text = textsOf(taught)
+ assert.match(text, /^# Batch tool calls/, 'the lesson opens the message, with no envelope')
+ assert.equal(text.includes('not a user instruction'), false, 'no plugin self-narration')
+ // The lesson states the mode the policy reports, so a full-access program is
+ // never primed with an escalation request (#963).
+ assert.match(text, /current mode: danger-full-access/)
+ assert.equal(text.includes('current mode: read-only'), false)
+ // It follows the user's own message in the same accepted batch.
+ assert.equal(first.decision.messages.at(-1).id, taught[0].id)
+ } finally { await shutdown(ctx) }
+}))
+
+await test('the lesson is spent only after its durable commit, and a thin program queues one notice', () => withTempDir('user-teach-once', async cwd => {
+ const { ctx, agent } = await setup(cwd)
+ try {
+ await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
+ assert.equal(guidanceOf(await drivePreStep(agent, 1)).length, 1)
+ // No commit yet: the next pre-step teaches again instead of going silent.
+ const second = await drivePreStep(agent, 2)
+ assert.equal(guidanceOf(second).length, 1, 'an uncommitted delivery re-teaches')
+ // Commit the delivered message exactly as the host does, then the lesson is spent.
+ for (const message of guidanceOf(second)) ctx.emit('session/event', agent.session, { type: 'user/message', data: message })
+ assert.equal(guidanceOf(await drivePreStep(agent, 3)).length, 0, 'the durable commit spends the lesson')
+ // A thin program earns one notice on the next pre-step; the tool result stays clean.
+ const run = await rootCall(ctx, agent, 'user-teach-thin', thinProgram)
+ assert.equal(run.isError, false, JSON.stringify(run))
+ assert.equal((run.additionalContexts ?? []).length, 0, 'guidance never rides the tool result')
+ const notice = guidanceOf(await drivePreStep(agent, 3))
+ assert.equal(notice.length, 1, JSON.stringify(notice))
+ assert.match(textsOf(notice), /did not open with a plan line/)
+ // A compliant program earns nothing.
+ const good = await rootCall(ctx, agent, 'user-teach-good')
+ assert.equal(good.isError, false, JSON.stringify(good))
+ assert.equal(guidanceOf(await drivePreStep(agent, 3)).length, 0)
+ } finally { await shutdown(ctx) }
+}))
+
+await test('a disabled switch delivers no lesson and no notice', () => withTempDir('user-teach-off', async cwd => {
+ const { ctx, agent } = await setup(cwd, { batchingGuidance: false })
+ try {
+ await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
+ assert.equal(guidanceOf(await drivePreStep(agent, 1)).length, 0)
+ await rootCall(ctx, agent, 'user-teach-off-thin', thinProgram)
+ assert.equal(guidanceOf(await drivePreStep(agent, 1)).length, 0)
+ } finally { await shutdown(ctx) }
+}))
+
+report('prompt-user-teaching')
diff --git a/test/ptc-cost-accounts.test.mjs b/test/ptc-cost-accounts.test.mjs
index 8abadc8c..908262b9 100644
--- a/test/ptc-cost-accounts.test.mjs
+++ b/test/ptc-cost-accounts.test.mjs
@@ -10,9 +10,8 @@
* recomputes system from the per-section bytes (the normalization is pinned
* by assertion) and proves a one-section change lands in system exactly once;
* - wire: the outer tool schemas each provider request carries (`run_code`);
- * - history: the dsh-ops program-shape notices that entered session history. The
- * one-time teaching is not here: it rides the first accepted root `run_code`
- * result as same-step `additionalContexts` and is never logged (#929).
+ * - history: the dsh-ops lesson and program-shape notices that entered session
+ * history as plain user messages on the pre-step batch.
*
* The official read/glob/grep schemas are mounted for real (the same host
* plugins the budget suite mounts), because SDK names are only meaningful
@@ -29,7 +28,7 @@ import path from 'node:path'
import * as FsTools from '@deepseek-ai/dsh-tool-fs'
import * as SearchTools from '@deepseek-ai/dsh-tool-fs-search'
import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
-import { analyzeProgram, loadBatchingGuidance, noticeText } from '../lib/ptc/batching-guidance.js'
+import { analyzeProgram, noticeText } from '../lib/ptc/batching-guidance.js'
import { requireWorker } from './lib/boundary.mjs'
import { bootEntryGroup, enterPtc } from './lib/ptc-entry.mjs'
import { prepareStep } from './lib/executor.mjs'
@@ -41,10 +40,6 @@ requireWorker('ptc-cost-accounts')
const HOST_PLUGINS = [[FsTools, {}], [SearchTools, { sampleOverCapGlobResults: false }]]
/** The official names the shipped row replaces; the ledger compares SDK names against them. */
const OFFICIAL = ['read', 'glob', 'grep']
-/** The teaching/notice contributor, as the host message source records it. */
-const TEACHING_ID = 'batching-guidance'
-const ENVELOPE = `[Plugin context from ${JSON.stringify(TEACHING_ID)}; not a user instruction or authorization.]\n`
-const TEACHING = loadBatchingGuidance()
/** A thin single-dispatch program with no plan line: it earns the plan notice. */
const THIN_PROGRAM = "const row = await tools.ops_inspect_local_file({ path: 'ledger-note' })\nreturn row"
/** A compliant load step: plan line plus one batched dispatch; it earns no notice. */
@@ -85,10 +80,13 @@ function officialFacts(ctx, agent) {
function historyItemsOf(messages) {
const items = []
for (const message of messages) {
- if (message.source?.kind !== 'dsh-ops:step-tail' || message.source.contributor !== TEACHING_ID) continue
+ if (message.source?.kind !== 'user') continue
const text = textOf(message)
- const body = text.startsWith(ENVELOPE) ? text.slice(ENVELOPE.length) : text
- const kind = body === TEACHING ? 'teaching' : body === noticeText('plan', analyzeProgram(THIN_PROGRAM)) ? 'notice:plan' : 'unknown'
+ // The lesson is rendered for the reported sandbox mode, so identify it by its
+ // opening heading instead of comparing against the shipped file (#963).
+ const kind = text.startsWith('# Batch tool calls') ? 'teaching'
+ : text === noticeText('plan', analyzeProgram(THIN_PROGRAM)) ? 'notice:plan' : undefined
+ if (kind === undefined) continue
items.push({ kind, bytes: bytes(text), sha: sha(text) })
}
return items
@@ -194,10 +192,9 @@ await test('the four accounts of one OPS-PTC group: system, its SDK subset, the
'normalization pinned: system = per-section bytes joined by \'\n\n\', exactly renderPrompt')
assert.ok(snapshot.sdk.bytes > 0 && snapshot.sdk.bytes < snapshot.system.bytes, 'SDK is a strict subset of system')
}
- // The notices enter history; the one-time teaching rides the first accepted
- // root run_code result as same-step ephemeral context (#929), so it adds no
- // history message. The system account never moves either way.
- assert.equal(snapshots.steady.system.sha, snapshots.baseline.system.sha, 'the plan notice is history, not a prompt change')
+ // The lesson and the notices are plain user messages on the pre-step batch, so
+ // both enter history; the system account never moves either way.
+ assert.equal(snapshots.steady.system.sha, snapshots.baseline.system.sha, 'the guidance is history, not a prompt change')
assert.equal(snapshots.steady.sdk.sha, snapshots.baseline.sdk.sha)
// B: the hand-computed example — loading three APIs changes only tools:sdk, exactly once.
const nonSdk = snapshot => snapshot.system.items.filter(item => item.name !== 'tools:sdk').map(item => item.sha)
@@ -226,14 +223,14 @@ await test('the four accounts of one OPS-PTC group: system, its SDK subset, the
for (const request of requests) assert.deepEqual(request.wireNames, ['run_code'])
assert.equal(new Set(requests.map(request => request.wireSha)).size, 1, 'wire is byte-identical on every request')
assert.equal(requests[0].wireSha, snapshots.baseline.wire.sha, 'the idle snapshot wire is the delivered wire')
- // D: the history account — the lesson never enters it (#929); only the plan notice
- // is history, once, and nothing is appended thereafter.
+ // D: the history account — the opening lesson is the first guidance the model
+ // reads, then exactly one plan notice, and nothing is appended thereafter.
const kindsAt = label => requests.find(request => request.label === label).history.map(item => item.kind)
- assert.deepEqual(kindsAt('first'), [], 'the first request carries no teaching in history')
- assert.deepEqual(kindsAt('after-notice'), ['notice:plan'], 'the thin program earns exactly one plan notice')
- assert.deepEqual(kindsAt('before-load'), ['notice:plan'])
- assert.deepEqual(kindsAt('after-load'), ['notice:plan'], 'a compliant load step earns no new notice')
- assert.deepEqual(kindsAt('repeat'), ['notice:plan'], 'no re-teaching, no duplicate notice')
+ assert.deepEqual(kindsAt('first'), ['teaching'], 'the first request opens with the lesson in history')
+ assert.deepEqual(kindsAt('after-notice'), ['teaching', 'notice:plan'], 'the thin program earns exactly one plan notice')
+ assert.deepEqual(kindsAt('before-load'), ['teaching', 'notice:plan'])
+ assert.deepEqual(kindsAt('after-load'), ['teaching', 'notice:plan'], 'a compliant load step earns no new notice')
+ assert.deepEqual(kindsAt('repeat'), ['teaching', 'notice:plan'], 'no re-teaching, no duplicate notice')
// The delivered system message is the idle assembly, and repeats are byte-identical.
const systemAt = label => requests.find(request => request.label === label).systemSha
assert.equal(systemAt('first'), snapshots.baseline.system.sha)
diff --git a/test/resident-switch.test.mjs b/test/resident-switch.test.mjs
index 886a5c73..3d5df800 100644
--- a/test/resident-switch.test.mjs
+++ b/test/resident-switch.test.mjs
@@ -167,57 +167,60 @@ await test('a row with batchingGuidance off publishes no notice at all', () => w
callId: 'batching-off-' + ++sequence, signal: new AbortController().signal })
assert.equal(result.isError, false, JSON.stringify(result))
assert.equal((result.additionalContexts ?? []).length, 0, 'switch off: no listener, therefore no notice')
+ assert.equal(guidanceOf(await drivePreStep(agent, 1)).length, 0, 'switch off: no lesson either')
} finally { await shutdown(ctx) }
}))
/** Drive the real agent pre-step waterfall once, exactly as the host loop does. */
-const drivePreStep = async (agent, turn) => {
+async function drivePreStep(agent, turn) {
const accepted = createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: 'Start the task.' }] })
- return agent.ctx.waterfall('agent/pre-step', {
+ const decision = await agent.ctx.waterfall('agent/pre-step', {
agent, messages: [accepted], turn, step: 1, signal: new AbortController().signal,
modelSelection: { provider: 'fixture', model: 'capture' },
}, async () => ({ kind: 'enter', messages: [accepted] }))
+ return { accepted, decision }
}
-/** Plugin-authored contexts appended to the accepted user batch. */
-const stepTailMessages = decision => decision.messages.filter(message => message.source?.kind === 'dsh-ops:step-tail')
-
-/** The one-time full lesson, told from a per-violation notice by its contributor suffix. */
-const lesson = context => context.source?.kind === 'dsh-ops:step-tail' && context.source?.contributor === 'batching-guidance:lesson'
-
-/** The one-time lesson as delivered on the first accepted root run_code result. */
-const lessonContexts = async (ctx, agent, code = '// plan: one read\nconst r = await tools.ops_inspect_local_file({ path: "package.json" })\nreturn r.status') => {
- const run = await executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
- arguments: { description: 'Compliant fixture', code },
- callId: 'lesson-' + ++sequence, signal: new AbortController().signal })
- assert.equal(run.isError, false, JSON.stringify(run))
- return (run.additionalContexts ?? []).filter(lesson)
+/** Guidance appended to the accepted batch as plain user text; never the accepted message itself. */
+function guidanceOf({ accepted, decision }) {
+ return decision.messages.filter(message => message.id !== accepted.id && message.source?.kind === 'user')
+}
+/** The one-time full lesson, told from a per-violation notice by its first line. */
+function lessonMessage(message) {
+ return (message.content[0]?.text ?? '').startsWith('# Batch tool calls')
}
+/** Commit a delivery the way the host does, so the pre-step latch observes the durable message. */
+function commitGuidance(ctx, agent, messages) {
+ for (const message of messages) ctx.emit('session/event', agent.session, { type: 'user/message', data: message })
+}
+
+/** Join the text of a list of messages. */
+const textsOf = messages => messages.map(message => message.content.map(part => part.text ?? '').join('')).join('\n')
-await test('ops-ptc batchingGuidance teaches once on the first run_code result, never in the user batch', () => withTempDir('batching-teach', async cwd => {
+await test('ops-ptc batchingGuidance teaches once on the first pre-step as plain user text', () => withTempDir('batching-teach', async cwd => {
const { ctx, agent } = await setup(cwd, 'ops-ptc', { residentTools: true, dynamicTools: true,
batchingGuidance: true, alwaysLoaded: ['stat'], allowedTools: ['stat'] })
try {
await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
- // A user-role lesson reads as fresh user input, and the model answers the
- // lesson instead of the task (#929): the user batch stays free of guidance.
- assert.equal(stepTailMessages(await drivePreStep(agent, 1)).length, 0)
- // The lesson rides the first accepted root run_code tool result through the
- // same-step ephemeral inbox, which the host never logs as user history.
- const taught = async callId => {
- const run = await executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
- arguments: { description: 'Compliant fixture', code: '// plan: two checks\nconst [a, b] = await Promise.all([tools.ops_stat({ path: "x" }), tools.ops_stat({ path: "y" })])\nreturn [a.status, b.status]' },
- callId, signal: new AbortController().signal })
- assert.equal(run.isError, false, JSON.stringify(run))
- return (run.additionalContexts ?? []).filter(context => context.source?.kind === 'dsh-ops:step-tail' && context.source?.contributor === 'batching-guidance:lesson')
- }
- const first = await taught('batching-teach-1')
- assert.equal(first.length, 1, JSON.stringify(first))
- assert.match(JSON.stringify(first), /Batch tool calls/)
- assert.match(JSON.stringify(first), /not a user instruction or authorization/)
- // Teach once: a second root call never repeats the lesson.
- assert.equal((await taught('batching-teach-2')).length, 0, 'the lesson is spent after its one delivery')
- // Nothing re-enters the user batch once the lesson is delivered.
- assert.equal(stepTailMessages(await drivePreStep(agent, 2)).length, 0)
+ // The lesson is a plain user message on the first accepted batch: the same
+ // role, source and shape as the user's own instruction, with no envelope.
+ const first = await drivePreStep(agent, 1)
+ const guided = guidanceOf(first)
+ assert.equal(guided.length, 1, JSON.stringify(first.decision.messages))
+ assert.equal(lessonMessage(guided[0]), true)
+ assert.equal(textsOf(guided).includes('not a user instruction'), false, 'no plugin self-narration')
+ // The latch observes the durable commit, not the returned decision.
+ commitGuidance(ctx, agent, guided)
+ assert.equal(guidanceOf(await drivePreStep(agent, 2)).length, 0, 'the lesson is spent after its one durable delivery')
+ // A thin program queues a notice for the next pre-step; the tool result itself
+ // stays untouched, so nothing marks the guidance as plugin context.
+ const run = await executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
+ arguments: { description: 'Thin fixture', code: 'const r = await tools.ops_stat({ path: "a" })\nreturn r.status' },
+ callId: 'batching-teach-1', signal: new AbortController().signal })
+ assert.equal(run.isError, false, JSON.stringify(run))
+ assert.equal((run.additionalContexts ?? []).length, 0, 'guidance never rides the tool result')
+ const notice = guidanceOf(await drivePreStep(agent, 2))
+ assert.equal(notice.length, 1, JSON.stringify(notice))
+ assert.match(textsOf(notice), /did not open with a plan line/)
} finally { await shutdown(ctx) }
}))
@@ -226,11 +229,11 @@ await test('a loader-less ops-ptc row teaches only what it publishes', () => wit
batchingGuidance: true, alwaysLoaded: ['stat'], allowedTools: ['stat'] })
try {
await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
- // End to end through the ephemeral inbox: the scope publishes no loader, so the
+ // The first pre-step carries the lesson; the scope publishes no loader, so the
// lesson must not name one. This is the assertion that fails when the surface is dropped.
- const taught = await lessonContexts(ctx, agent, '// plan: read one path\nconst r = await tools.ops_stat({ path: "a" })\nreturn r.status')
+ const taught = guidanceOf(await drivePreStep(agent, 1))
assert.equal(taught.length, 1, JSON.stringify(taught))
- const text = JSON.stringify(taught)
+ const text = textsOf(taught)
assert.equal(text.includes('ops_load_sdk'), false, 'the unreachable loader is gone')
assert.match(text, /call what is published/, 'the direct-call step replaces it')
assert.match(text, /ops_stat/, 'the published API is listed instead')
@@ -240,11 +243,8 @@ await test('a loader-less ops-ptc row teaches only what it publishes', () => wit
} finally { await shutdown(ctx) }
}))
-/** The replaced Step 3 section of a taught loader-less lesson, as flat JSON text. */
-const step3Of = taught => {
- const lesson = JSON.stringify(taught)
- return lesson.slice(lesson.indexOf('call what is published'), lesson.indexOf('Trajectory 1'))
-}
+/** The replaced Step 3 section of a taught loader-less lesson, as plain text. */
+const step3Of = text => text.slice(text.indexOf('call what is published'), text.indexOf('Trajectory 1'))
await test('a read-only loader-less lesson and notice keep the mutating API out', () => withTempDir('batching-readonly-lesson', async cwd => {
const { ctx, agent } = await setup(cwd, 'ops-ptc', { residentTools: true, dynamicTools: false,
@@ -254,18 +254,19 @@ await test('a read-only loader-less lesson and notice keep the mutating API out'
// The row always loads the mutating API, so only the read-only policy can keep it
// out of the direct-call list: the surface is resolved at delivery time.
agent.session.mode = 'read-only'
- const taught = await lessonContexts(ctx, agent)
- assert.equal(taught.length, 1, JSON.stringify(taught))
- const step3 = step3Of(taught)
+ const first = await drivePreStep(agent, 1)
+ const step3 = step3Of(textsOf(guidanceOf(first)))
assert.ok(step3.length > 0, 'the direct-call section is present')
assert.equal(step3.includes('ops_edit_file'), false, 'the read-only surface drops the mutating API')
assert.match(step3, /ops_inspect_local_file/, 'the resident reader stays listed')
assert.match(step3, /rejects directories/, 'the exact-path note stays with the reader')
+ commitGuidance(ctx, agent, guidanceOf(first))
// The same surface narrows the bypass notice: no write API, the reader stays named.
const result = await executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
arguments: { description: 'shape fixture', code: 'const r = await tools.ops_bash({ description: "list", command: "ls -la" })\nreturn r.stdout.text' },
callId: 'readonly-lesson-' + ++sequence, signal: new AbortController().signal })
- const notice = JSON.stringify(result.additionalContexts ?? [])
+ assert.equal((result.additionalContexts ?? []).length, 0, 'the notice never rides the tool result')
+ const notice = textsOf(guidanceOf(await drivePreStep(agent, 1)))
assert.equal(notice.includes('ops_edit_file'), false, 'the notice keeps the mutating API out')
assert.match(notice, /ops_inspect_local_file/, 'the resident reader stays named')
} finally { await shutdown(ctx) }
@@ -278,9 +279,9 @@ await test('a writable loader-less lesson lists what its row always loads', () =
await waitFor(() => names(ctx, agent).includes(publicToolName('edit_file')))
// Without the read-only policy the same row teaches its whole resident list, which
// is what keeps the narrowing keyed on the policy instead of always on.
- const taught = await lessonContexts(ctx, agent)
+ const taught = guidanceOf(await drivePreStep(agent, 1))
assert.equal(taught.length, 1, JSON.stringify(taught))
- assert.match(step3Of(taught), /ops_edit_file/, 'a writable scope teaches what its row always loads')
+ assert.match(step3Of(textsOf(taught)), /ops_edit_file/, 'a writable scope teaches what its row always loads')
} finally { await shutdown(ctx) }
}))
@@ -289,40 +290,43 @@ await test('ops-ptc without batchingGuidance teaches nothing on the first turn',
batchingGuidance: false, alwaysLoaded: ['stat'], allowedTools: ['stat'] })
try {
await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
- assert.equal(stepTailMessages(await drivePreStep(agent, 1)).length, 0)
+ assert.equal(guidanceOf(await drivePreStep(agent, 1)).length, 0)
const run = await executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
arguments: { description: 'Thin fixture', code: 'const r = await tools.ops_stat({ path: "a" })\nreturn r.status' },
callId: 'batching-off-teach', signal: new AbortController().signal })
assert.equal(run.isError, false, JSON.stringify(run))
assert.equal((run.additionalContexts ?? []).length, 0, 'switch off: no listener, therefore no lesson and no notice')
+ assert.equal(guidanceOf(await drivePreStep(agent, 1)).length, 0, 'switch off: the next pre-step stays silent')
} finally { await shutdown(ctx) }
}))
-await test('the root run_code trigger answers on its own tool result', () => withTempDir('batching-trigger-live', async cwd => {
+await test('the root run_code trigger answers on the next pre-step', () => withTempDir('batching-trigger-live', async cwd => {
const { ctx, agent } = await setup(cwd, 'ops-ptc', { residentTools: true, dynamicTools: true,
batchingGuidance: true, alwaysLoaded: ['stat'], allowedTools: ['stat'] })
try {
await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
+ commitGuidance(ctx, agent, guidanceOf(await drivePreStep(agent, 1)))
const run = code => executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
arguments: { description: 'shape fixture', code }, callId: 'shape-' + ++sequence, signal: new AbortController().signal })
- const contexts = result => result.additionalContexts ?? []
- const text = result => JSON.stringify(contexts(result))
+ const nextText = async () => textsOf(guidanceOf(await drivePreStep(agent, 1)))
// A compliant program earns nothing, which is what keeps the notice meaningful.
const good = await run('// plan: stat one path; stat another\nconst [a, b] = await Promise.all([tools.ops_stat({ path: "a" }), tools.ops_stat({ path: "b" })])\nreturn { a, b }')
assert.equal(good.isError, false, JSON.stringify(good))
- assert.equal(contexts(good).filter(context => !lesson(context)).length, 0, 'a compliant program earns no notice')
- assert.equal(contexts(good).filter(lesson).length, 1, 'the one-time lesson rides the first root result')
+ assert.equal((good.additionalContexts ?? []).length, 0, 'the result itself carries no guidance')
+ assert.equal(await nextText(), '', 'a compliant program earns no notice')
// No plan line: the plan category speaks, and it says only that the comment is missing.
const thin = await run('const r = await tools.ops_stat({ path: "a" })\nreturn r.status')
assert.equal(thin.isError, false, JSON.stringify(thin))
- assert.match(text(thin), /did not open with a plan line/, 'the plan notice rides the root result')
- assert.doesNotMatch(JSON.stringify(contexts(thin).filter(context => !lesson(context))), /Promise\.all/, 'the plan notice stays about the comment')
+ const planNotice = await nextText()
+ assert.match(planNotice, /did not open with a plan line/, 'the plan notice rides the next pre-step')
+ assert.doesNotMatch(planNotice, /Promise\.all/, 'the plan notice stays about the comment')
// A shell listing is a bypass; resident file APIs are reachable without loading,
// so the notice still names them even though this pool could not load them.
const bypass = await run('const r = await tools.ops_bash({ description: "list", command: "ls -la" })\nreturn r.stdout.text')
- assert.match(text(bypass), /ops_inspect_local_file/, 'the notice names the resident file API')
- assert.doesNotMatch(text(bypass), /ops_bash/, 'the shell it just accused is not offered as the fix')
- // The trigger appends context and never rewrites the tool result itself.
+ const bypassNotice = await nextText()
+ assert.match(bypassNotice, /ops_inspect_local_file/, 'the notice names the resident file API')
+ assert.doesNotMatch(bypassNotice, /ops_bash/, 'the shell it just accused is not offered as the fix')
+ // The trigger queues text and never rewrites the tool result itself.
assert.equal(thin.value.result, 'completed', JSON.stringify(thin.value))
} finally { await shutdown(ctx) }
}))
@@ -332,13 +336,14 @@ await test('a read-only agent is never told to edit files through the notice', (
batchingGuidance: true, alwaysLoaded: ['stat'], allowedTools: ['stat', 'edit_file'] })
try {
await waitFor(() => names(ctx, agent).includes(publicToolName('stat')))
+ commitGuidance(ctx, agent, guidanceOf(await drivePreStep(agent, 1)))
// The policy is resolved per delivery, so a read-only session narrows the surface.
agent.session.mode = 'read-only'
const result = await executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code',
arguments: { description: 'shape fixture', code: 'const r = await tools.ops_bash({ description: "list", command: "ls -la" })\nreturn r.stdout.text' },
callId: 'readonly-' + ++sequence, signal: new AbortController().signal })
- // The lesson rides the same result; the notice is what this check is about.
- const text = JSON.stringify((result.additionalContexts ?? []).filter(context => !lesson(context)))
+ assert.equal((result.additionalContexts ?? []).length, 0)
+ const text = textsOf(guidanceOf(await drivePreStep(agent, 1)))
assert.doesNotMatch(text, /ops_edit_file/, 'a read-only agent is not taught to mutate')
assert.match(text, /ops_inspect_local_file/, 'the reachable file API stays named')
} finally { await shutdown(ctx) }