dsh-parallel-tools-prompt 0.0.0-stage → 0.2.1-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lloydzhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# dsh-parallel-tools-prompt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+独立 DeepSeek Harness host-only 插件：用稳定的依赖感知提示，引导模型把当前已就绪、互不依赖的必要工具调用放在同一响应里，减少不必要的模型—工具往返。
+
+**不是 DAG 执行器，也不是费用优化保证。** 不新增模型请求、不增加工具、不更改宿主安全分类、权限或调度器。效果取决于模型遵循度、任务依赖与运行环境，尚未做付费前向 A/B。
+
+## 行为
+
+- 默认只作用于创建/恢复时的 `standard` 根 Agent；跳过子智能体、PTC、minimal、creator 等非目标会话。
+- 使用公开 `agent/created`、`agents.roots()`、session projection 与 `systemPrompt.section()`，不替换 preset。
+- 固定 section 名称 `parallel-tools:guidance`、order 1050、禁止插值；不注入时间戳、工具列表或每轮变化的数据。
+- 同一 Agent 幂等注册；插件卸载与 Agent 释放都清理 section。插件重载时为仍存活的目标根 Agent 补挂 section；源码更新建议重启宿主加载新模块。
+- bundle 默认开启 `contextReminder`：通过公开 `agent.inject()` 在下一步骤边界注入一次带 `[parallel-tools:scheduling]` 标记的对话提醒，强调提前规划就绪批次以减少模型往返。直接使用插件时此选项默认关闭。提醒进入会话历史，卸载不会删除；已持久化标记用于避免重复注入。这不是每轮重复提醒，也不保证长期遵循。
+- 单次调用合理时仍单次；路径、ID等参数必须已知；读后写、共享文件冲突、权限审批保持依赖顺序。不发明batch工具或额外规划轮次。
+- 同轮多个工具调用不代表真正同时执行；执行并发仍由DSH调度器决定。
+
+## 版本、依赖与发布
+
+插件版本 `0.2.1-rc.1` 跟随 DSH 的 `0.2.1` 版本线，RC 序号独立递增，不等于宿主 RC 序号。最低宿主要求 `>=0.2.1-rc.3`，Node.js `>=24.9.0`。开发锁文件以 RC.5 为基线；RC.3 的相关接口已做源码比对，完整插件测试本次运行在 RC.5 依赖上，不冒充两套运行验收。
+
+宿主库以 peerDependencies 声明，同时列入 devDependencies 供构建测试：Cordis `4.0.5`、Schemastery `3.18.5`、DSH agent/llm/preset-registry/session-projection/system-prompt 使用 `^0.2.1-rc.3`。不将宿主服务打包为普通运行依赖，避免重复服务身份。semver caret 不跨 `0.3`，也不自动接纳不同版本号的预发布版本。
+
+建议使用 `npm ci` 配合 npm lock，避免交替更新两种锁文件。包发布白名单包含构建产物、bundle patch、README、许可证与分析脚本，不包含测试、原始会话或调试捕获。`prepack` 自动构建；预发布默认 `next` tag。确认版本未占用后由维护者执行 `npm publish`；已发布版本不能覆盖。
+
+## 开发与安装
+
+尚未发布 npm；已在本地 Web profile 链接安装并进行人工观察。一次探索任务出现连续多调用批次，但模型同时发生切换，不能据此归因于插件或宣称 token/费用节省。
+
+```sh
+npm ci
+npm run build
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+确认愿意启用后，手动安装本目录到目标 profile，例如 `dsh plugin --profile web add .`；Desktop 选择 `--profile desktop`。本插件没有客户端 UI，不需要 `dsh.client`。
+
+直接调用插件默认 `enabled: false`；bundle显式配置 `enabled: true`，安装bundle即选择启用。配置：
+
+```yaml
+enabled: true
+contextReminder: true
+presetIds: [standard]
+```
+
+**注意：profile 的 `cordis.patch.yml` 覆盖本插件时，`config` 是整体替换、不与 bundle 默认值深合并。** 覆盖项必须写全需要的字段（至少 `enabled: true`、`presetIds`），否则 `enabled` 回落为默认 `false`，插件静默不注入。验收方式：新会话的 `system/message` 中应出现 `Tool-call scheduling:`。
+
+`presetIds` 是精确ID列表，不是正则。自定义目标仅适用于原生工具调用preset；不要把PTC加入以免对专用执行模式施加不合适的指导。根会话fork可以保留历史parentSession，不会仅因此被当作子智能体。
+
+卸载会释放注册；已有模型历史中的旧指令不会被改写或删除。若宿主需要重新投影系统提示，生效边界由宿主管理；稳妥方式是重启后继续原会话。首次安装可能改变system前缀并影响一次缓存复用；不能保证零缓存影响。
+
+## 参考与验证边界
+
+主要借鉴 [bash-agent #99](https://github.com/lloydzhou/bash-agent/issues/99) 的就绪批次思路及 [#100](https://github.com/lloydzhou/bash-agent/issues/100) 对实测/离线估算的讨论；同时参考 [Anthropic并行调用指南](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use)、[LLMCompiler](https://github.com/SqueezeAILab/LLMCompiler) 和 [Superpowers并行委派skill](https://github.com/obra/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md)。本插件提示词为针对DSH自行编写的简短文本，不移植其执行器或照搬专用工具调用格式。
+
+LLMCompiler收益来自框架与调度；bash-agent历史DAG合并收益是离线估算；这些都不是本插件的实测收益。生命周期测试只证明接入/清理正确，不证明模型更快、更省。
+
+## 临时 LLM 提示调试
+
+默认 `debugEnabled: false`。调试模式在公开 `llm/stream` 边界记录归一化请求中的完整系统/开发者提示，不是最终HTTP报文；后续适配器仍可能变换它。仅指定会话命中，日志不收集用户/工具结果正文、认证头、工具参数schema或endpoint。系统提示本身也可能包含内部路径和秘密，请将日志视为敏感数据，不提交仓库或上传公开issue。
+
+配置 `debugEnabled: true`、精确的 `debugSessionId`、绝对路径 `debugOutputDir` 和 `debugMaxCalls`（默认3，上限10）。输出目录须当前用户所有且权限0700；其中放一个私有普通文件 `enabled` 才会开始捕获。关闭配置或移走此标记后停止捕获，单进程达到次数上限也会停止；默认模式不写文件。新代码首次加载需重启宿主。调试结束须移走标记并关闭配置，避免重启重新开始捕获。
+
+## 评估建议
+
+主指标是每完成任务的模型响应/尝试数量，而不是工具调用总数。固定任务、模型、reasoning、权限、工作目录与工具；对比输出tokens、正确率、重试/失败及wall time；报告配对分布、中位数、IQR，单独标记首次提示变化的缓存成本。
+
+离线分析仅对显式指定的日志文件运行，不默认扫描个人会话目录，不输出内容或路径：
+
+```sh
+node scripts/analyze-session.mjs --help
+node scripts/analyze-session.mjs /path/to/session.v4.jsonl.zstd
+```
+
+按assistant/message中的tool-call块计算批量率和calls/response均值、中位数；`assistant/attempt`与`tool/call`另计，不当作远端计费API调用。输出tokens同时报告已知总量与未知响应数量。日志中的继承/seed事件会计入，重复输入文件不去重；不能据此推断实际并发、LLM耗时或因果收益。zstd压缩及展开数据各限64MiB。更详细口径见脚本帮助和测试。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# Installing/enabling this bundle is the explicit opt-in. Direct plugin use
+# defaults to enabled:false. No preset replacement or scheduler changes.
+- insert:
+    - id: parallel-tools-prompt
+      name: dsh-parallel-tools-prompt
+      config:
+        enabled: true
+        contextReminder: true
+        presetIds: [standard]

package/lib/debug.d.ts

@@ -0,0 +1,26 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Explicit opt-in for a temporary, sensitive normalized-prompt capture. */
+export interface PromptDebugOptions {
+    enabled?: boolean;
+    /** Exact identity; no wildcard, prefix, child-session, or global matching. */
+    sessionId: string;
+    /** Operator-created, owned 0700 directory containing a regular `enabled` file. */
+    outputDir: string;
+    /** Maximum enabled matching calls attempted by this installation (default 3, maximum 10). */
+    maxCalls?: number;
+}
+/**
+ * Install optional public llm/stream observation. Disabled by default. The
+ * operator must create outputDir with mode 0700 and its `enabled` sentinel;
+ * absence creates nothing. Removing the sentinel disables subsequent captures
+ * without restart (already-written captures remain sensitive). Never mkdir or
+ * chmod a user path. Reject a whole capture over 2 MiB, never truncate it.
+ *
+ * This is normalized input at this middleware's position, NOT the final HTTP
+ * request; later middleware/adapters may transform it. System/developer text
+ * itself can contain secrets. No user/assistant/tool text, schemas, headers,
+ * credentials, endpoints or standard logging are included. The untouched stream
+ * is returned directly; no extra model calls or stream consumption occur.
+ */
+export declare function installPromptDebug(ctx: Context, options: PromptDebugOptions): () => void;
+//# sourceMappingURL=debug.d.ts.map

package/lib/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAMnD,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAuED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI,CA2CxF"}

package/lib/debug.js

@@ -0,0 +1,136 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, parse, resolve, sep } from 'node:path';
+const MAX_BYTES = 2 * 1024 * 1024;
+const PROCESS_LIMIT = 10;
+// A reload or a second installation cannot reset the process-wide allowance.
+const BUDGET_KEY = Symbol.for('dsh-parallel-tools-prompt.prompt-debug.budget.v1');
+const budgets = globalThis;
+function safeId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._/-]{0,159}$/.test(value)
+        ? value : undefined;
+}
+/** Reject symlinks in every component, not just the final output directory. */
+function privateDirectory(path) {
+    let current = parse(path).root;
+    for (const component of path.slice(current.length).split(sep).filter(Boolean)) {
+        current = join(current, component);
+        const stat = lstatSync(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('unsafe directory');
+    }
+    const stat = lstatSync(path);
+    if (process.getuid === undefined || stat.uid !== process.getuid() || (stat.mode & 0o777) !== 0o700) {
+        throw new Error('non-private directory');
+    }
+    return stat;
+}
+function enabled(path) {
+    const stat = lstatSync(join(path, 'enabled'));
+    return stat.isFile() && !stat.isSymbolicLink() && stat.uid === process.getuid?.();
+}
+function capture(options) {
+    let textBytes = 0;
+    const text = (value) => {
+        if (typeof value !== 'string')
+            throw new Error('unsupported prompt shape');
+        textBytes += Buffer.byteLength(value, 'utf8');
+        if (textBytes > MAX_BYTES)
+            throw new Error('capture too large');
+        return value;
+    };
+    const messages = [];
+    for (const message of options.messages) {
+        // Developer is not currently in dsh-llm's role union; accept its textual
+        // shape defensively, without copying any arbitrary message properties.
+        const role = message.role;
+        if (role !== 'system' && role !== 'developer')
+            continue;
+        const blocks = [];
+        for (const block of message.content) {
+            if (block.type === 'text')
+                blocks.push(text(block.text));
+        }
+        messages.push({ role, text: blocks });
+    }
+    const names = (options.tools ?? []).map(tool => safeId(tool.name));
+    const record = {
+        format: 'normalized-prompt-debug-v1',
+        boundary: 'llm/stream normalized GenerateOptions; before provider adapter; NOT final HTTP payload',
+        provider: safeId(options.provider),
+        model: safeId(options.model),
+        purpose: options.purpose === 'compaction' || options.purpose === 'session-title' ? options.purpose : undefined,
+        system: options.system === undefined ? undefined : text(options.system),
+        messages,
+        tools: { count: names.length, names: names.filter((name) => name !== undefined) },
+        // GenerateOptions has no tool_choice / parallel_tool_calls vocabulary.
+        // Never inspect unknown extensions, headers, URLs, or raw request objects.
+    };
+    const serialized = JSON.stringify(record, null, 2) + '\n';
+    if (Buffer.byteLength(serialized, 'utf8') > MAX_BYTES)
+        throw new Error('capture too large');
+    return serialized;
+}
+/**
+ * Install optional public llm/stream observation. Disabled by default. The
+ * operator must create outputDir with mode 0700 and its `enabled` sentinel;
+ * absence creates nothing. Removing the sentinel disables subsequent captures
+ * without restart (already-written captures remain sensitive). Never mkdir or
+ * chmod a user path. Reject a whole capture over 2 MiB, never truncate it.
+ *
+ * This is normalized input at this middleware's position, NOT the final HTTP
+ * request; later middleware/adapters may transform it. System/developer text
+ * itself can contain secrets. No user/assistant/tool text, schemas, headers,
+ * credentials, endpoints or standard logging are included. The untouched stream
+ * is returned directly; no extra model calls or stream consumption occur.
+ */
+export function installPromptDebug(ctx, options) {
+    const maxCalls = options.maxCalls ?? 3;
+    if (options.enabled !== true || typeof options.sessionId !== 'string' || options.sessionId.trim() === ''
+        || typeof options.outputDir !== 'string' || !isAbsolute(options.outputDir)
+        || !Number.isInteger(maxCalls) || maxCalls < 1 || maxCalls > PROCESS_LIMIT)
+        return () => { };
+    const outputDir = resolve(options.outputDir);
+    const sessionId = options.sessionId;
+    let calls = 0;
+    return ctx.on('llm/stream', (request, next) => {
+        try {
+            const budget = budgets[BUDGET_KEY] ??= { attempts: 0 };
+            if (request.sessionId === sessionId && calls < maxCalls && budget.attempts < PROCESS_LIMIT) {
+                const directory = privateDirectory(outputDir);
+                if (enabled(outputDir)) {
+                    // Reserve before serializing/writing, including failures. All capture
+                    // work is synchronous, so concurrent calls cannot overshoot either cap.
+                    calls++;
+                    budget.attempts++;
+                    const data = capture(request);
+                    if (enabled(outputDir)) {
+                        const current = privateDirectory(outputDir);
+                        if (current.dev !== directory.dev || current.ino !== directory.ino)
+                            throw new Error('directory changed');
+                        const path = join(outputDir, `prompt-${process.pid}-${randomUUID()}.json`);
+                        const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+                        try {
+                            const file = fstatSync(fd);
+                            const after = privateDirectory(outputDir);
+                            if (!file.isFile() || file.nlink !== 1 || file.uid !== process.getuid?.()
+                                || (file.mode & 0o777) !== 0o600 || after.dev !== directory.dev || after.ino !== directory.ino) {
+                                throw new Error('unsafe capture file');
+                            }
+                            if (enabled(outputDir))
+                                writeFileSync(fd, data, 'utf8');
+                        }
+                        finally {
+                            closeSync(fd);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Debugging must never fail a model call or log prompt-bearing errors.
+        }
+        return next();
+    });
+}
+//# sourceMappingURL=debug.js.map

package/lib/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { PARALLEL_TOOLS_PROMPT, SECTION_NAME, SECTION_ORDER } from './prompt.js';
+export declare const name = "parallel-tools-prompt";
+export declare const inject: string[];
+/** Stable marker so a reload never injects the reminder twice into one session. */
+export declare const CONTEXT_MARKER = "[parallel-tools:scheduling]";
+export declare const CONTEXT_REMINDER = "[parallel-tools:scheduling] Every response: before answering, check what else the current subgoal already has ready and issue ALL ready, independent tool calls together in this one response \u2014 same-tool calls on different targets, parallel reads, independent searches and checks. Each response is one model round trip; issuing ready work one call at a time spends one round trip per call. Hold a call only for real dependencies: its arguments need an earlier result, read-before-edit, shared-file or approval ordering. A single call is fine when nothing else is ready; never invent calls to fill a batch.";
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    debugEnabled: z<boolean, boolean, "defined">;
+    debugSessionId: z<string, string, "defined">;
+    debugOutputDir: z<string, string, "defined">;
+    debugMaxCalls: z<number, number, "defined">;
+    enabled: z<boolean, boolean, "defined">;
+    contextReminder: z<boolean, boolean, "defined">;
+    presetIds: z<string[], string[], "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    debugEnabled: z<boolean, boolean, "defined">;
+    debugSessionId: z<string, string, "defined">;
+    debugOutputDir: z<string, string, "defined">;
+    debugMaxCalls: z<number, number, "defined">;
+    enabled: z<boolean, boolean, "defined">;
+    contextReminder: z<boolean, boolean, "defined">;
+    presetIds: z<string[], string[], "defined">;
+}>>, "plain">;
+export type Config = ReturnType<typeof Config>;
+/** Host-only: new/resumed agent lifecycles plus reload-time re-attachment. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAMnD,OAAO,CAAC,MAAM,0BAA0B,CAAC;AAIzC,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjF,eAAO,MAAM,IAAI,0BAA0B,CAAC;AAC5C,eAAO,MAAM,MAAM,UAAmD,CAAC;AAEvE,mFAAmF;AACnF,eAAO,MAAM,cAAc,gCAAgC,CAAC;AAC5D,eAAO,MAAM,gBAAgB,qmBAAslB,CAAC;AAEpnB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;aAejB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AA4D/C,8EAA8E;AAC9E,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAiCxD"}

package/lib/index.js

@@ -0,0 +1,113 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import z from '@deepseek-ai/schemastery';
+import { PARALLEL_TOOLS_PROMPT, SECTION_NAME, SECTION_ORDER } from './prompt.js';
+import { installPromptDebug } from './debug.js';
+export { PARALLEL_TOOLS_PROMPT, SECTION_NAME, SECTION_ORDER } from './prompt.js';
+export const name = 'parallel-tools-prompt';
+export const inject = ['agents', 'systemPrompt', 'sessionProjections'];
+/** Stable marker so a reload never injects the reminder twice into one session. */
+export const CONTEXT_MARKER = '[parallel-tools:scheduling]';
+export const CONTEXT_REMINDER = `${CONTEXT_MARKER} Every response: before answering, check what else the current subgoal already has ready and issue ALL ready, independent tool calls together in this one response — same-tool calls on different targets, parallel reads, independent searches and checks. Each response is one model round trip; issuing ready work one call at a time spends one round trip per call. Hold a call only for real dependencies: its arguments need an earlier result, read-before-edit, shared-file or approval ordering. A single call is fine when nothing else is ready; never invent calls to fill a batch.`;
+export const Config = z.object({
+    debugEnabled: z.boolean().default(false).description('Capture normalized LLM system prompts locally, only with an explicit session and enable sentinel. Sensitive: disable after diagnosis.'),
+    debugSessionId: z.string().default(''),
+    debugOutputDir: z.string().default(''),
+    debugMaxCalls: z.natural().min(1).max(10).default(3),
+    enabled: z.boolean().default(false).description('Enable static tool-call scheduling guidance. The bundle explicitly opts in; direct plugin use is disabled by default.'),
+    contextReminder: z.boolean().default(false).description('Additionally inject a one-time scheduling reminder as model-facing conversation context at the next step boundary. Persists in the session transcript; survives reloads without duplication.'),
+    presetIds: z.array(z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/))
+        .max(32).default(['standard']).description('Exact preset IDs to target at agent creation. Root agents only; use native-tool presets, not PTC. An empty list disables all targets.'),
+});
+/**
+ * Attach or re-attach the guidance section to one already-eligible live agent.
+ * Idempotent via the registration guard; shared by `agent/created` and
+ * reload-time catch-up, so a plugin reload cannot silently drop guidance from
+ * agents that survive it (the old instance's disposal removed its sections).
+ */
+function attach(ctx, agent, config, presetIds, registrations, active) {
+    if (registrations.has(agent))
+        return;
+    const { header } = agent.session;
+    // Durable child metadata survives resume; live ownership covers children
+    // without that metadata. parentSession is fork lineage, NOT a parent Agent.
+    if (header.origin === 'subagent' || (header.delegationDepth ?? 0) > 0)
+        return;
+    if (!ctx.agents.roots().includes(agent))
+        return;
+    const preset = ctx.sessionProjections.stateOf(agent.session, 'agentPreset')
+        ?? header.agentPreset;
+    if (preset === undefined || !presetIds.has(preset))
+        return;
+    // Conversation-level reminder: rides model-facing context at the nearest step
+    // boundary and persists in the transcript, so it stays proximal to generation.
+    // The transcript scan keeps reloads from stacking duplicate reminders.
+    if (config.contextReminder) {
+        try {
+            const already = agent.session.snapshotEvents().some(event => event.type === 'user/message' && JSON.stringify(event.data?.content ?? '').includes(CONTEXT_MARKER));
+            if (!already) {
+                agent.inject(createUserMessage({
+                    content: [{ type: 'text', text: CONTEXT_REMINDER }],
+                    source: { kind: 'user' },
+                }));
+            }
+        }
+        catch { /* reminder must never break attach */ }
+    }
+    const registration = {};
+    // Returning the disposer is essential: ctx.effect does not implicitly adopt
+    // arbitrary registrations executed inside its callback on another fiber.
+    registration.release = agent.ctx.effect(() => {
+        const disposeSection = agent.ctx.systemPrompt.section({
+            name: SECTION_NAME,
+            order: SECTION_ORDER,
+            interpolate: false,
+            text: PARALLEL_TOOLS_PROMPT,
+        });
+        return () => {
+            try {
+                return disposeSection();
+            }
+            finally {
+                registrations.delete(agent);
+                active.delete(registration);
+            }
+        };
+    });
+    registrations.set(agent, registration);
+    active.add(registration);
+}
+/** Host-only: new/resumed agent lifecycles plus reload-time re-attachment. */
+export function apply(ctx, config) {
+    if (config.debugEnabled) {
+        installPromptDebug(ctx, { enabled: true, sessionId: config.debugSessionId,
+            outputDir: config.debugOutputDir, maxCalls: config.debugMaxCalls });
+    }
+    if (!config.enabled)
+        return;
+    const presetIds = new Set(config.presetIds);
+    const registrations = new WeakMap();
+    const active = new Set();
+    // Agent contexts are not children of this plugin's fiber. Explicitly give the
+    // plugin ownership of their effect disposers as well as agent-local ownership.
+    ctx.effect(() => async () => {
+        for (const registration of [...active])
+            await registration.release?.();
+        active.clear();
+    });
+    ctx.on('agent/created', ({ agent }) => {
+        attach(ctx, agent, config, presetIds, registrations, active);
+    });
+    // A plugin reload disposes the previous instance's section registrations, and
+    // the host does not replay `agent/created` for agents that stay alive. Attach
+    // to currently live eligible roots so guidance survives reloads; the guard
+    // keeps this idempotent for agents that were never affected.
+    ctx.effect(() => {
+        // Runs once at apply/reload time: re-attach to agents that survived the
+        // previous instance's disposal. The no-op disposer satisfies the effect
+        // contract; per-agent cleanup is owned by each registration instead.
+        for (const agent of ctx.agents.roots())
+            attach(ctx, agent, config, presetIds, registrations, active);
+        return () => { };
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/prompt.d.ts

@@ -0,0 +1,5 @@
+/** Stable prompt bytes: no runtime interpolation, tool inventory, or per-turn state. */
+export declare const SECTION_NAME = "parallel-tools:guidance";
+export declare const SECTION_ORDER = 1050;
+export declare const PARALLEL_TOOLS_PROMPT = "Tool-call scheduling:\n- Before each response, briefly check what else the current subgoal already has ready: same-tool calls on different targets, parallel reads, independent searches and checks. Issue every ready, independent call together in THIS response.\n- Hold a call only when its arguments depend on an earlier result, or ordering is required (read-before-edit, shared file, approval flow). A later combined decision does not make independent collection sequential.\n- A single call is correct when nothing else is ready; never invent or duplicate calls to fill a batch. Keep scheduling internal: no planning-only turn, no shell wrappers or delegation just to simulate batching.\n- Several calls in one response do not force simultaneous execution; the host scheduler, permissions, and all safety rules still apply.";
+//# sourceMappingURL=prompt.d.ts.map

package/lib/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,eAAO,MAAM,YAAY,4BAA4B,CAAC;AACtD,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,eAAO,MAAM,qBAAqB,6zBAIsG,CAAC"}

package/lib/prompt.js

@@ -0,0 +1,9 @@
+/** Stable prompt bytes: no runtime interpolation, tool inventory, or per-turn state. */
+export const SECTION_NAME = 'parallel-tools:guidance';
+export const SECTION_ORDER = 1050;
+export const PARALLEL_TOOLS_PROMPT = `Tool-call scheduling:
+- Before each response, briefly check what else the current subgoal already has ready: same-tool calls on different targets, parallel reads, independent searches and checks. Issue every ready, independent call together in THIS response.
+- Hold a call only when its arguments depend on an earlier result, or ordering is required (read-before-edit, shared file, approval flow). A later combined decision does not make independent collection sequential.
+- A single call is correct when nothing else is ready; never invent or duplicate calls to fill a batch. Keep scheduling internal: no planning-only turn, no shell wrappers or delegation just to simulate batching.
+- Several calls in one response do not force simultaneous execution; the host scheduler, permissions, and all safety rules still apply.`;
+//# sourceMappingURL=prompt.js.map

package/lib/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,CAAC,MAAM,YAAY,GAAG,yBAAyB,CAAC;AACtD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAElC,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;wIAImG,CAAC"}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "dsh-parallel-tools-prompt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1-rc.2",
+  "description": "Plan ready tool-call batches to reduce model round trips in DeepSeek Harness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lloydzhou/dsh-parallel-tools-prompt.git"
+  },
+  "homepage": "https://github.com/lloydzhou/dsh-parallel-tools-prompt#readme",
+  "bugs": {
+    "url": "https://github.com/lloydzhou/dsh-parallel-tools-prompt/issues"
+  },
+  "publishConfig": { "access": "public", "tag": "next" },
+  "type": "module",
+  "license": "MIT",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib", "cordis.patch.yml", "README.md", "LICENSE", "scripts/analyze-session.mjs"],
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": ">=0.2.1-rc.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/schemastery": "3.18.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-agent-preset-registry": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-session-projection": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/schemastery": "3.18.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-agent-preset-registry": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-session-projection": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-scope": "^0.2.1-rc.3",
+    "@deepseek-ai/cordis-plugin-include": "1.0.10",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.6",
+    "@types/node": "^24.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "js-yaml": "^4.1.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/scripts/analyze-session.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Read-only descriptive metrics for explicitly named DSH session logs.
+ * No session discovery, network, content output, replay, or deduplication.
+ * Counts include inherited/seed events and repeated input files. These are NOT
+ * billed API counts, concurrency measurements, LLM latency, or causal savings.
+ * JSONL is read with readline; zstd is synchronous and limited to 64 MiB both
+ * compressed and expanded. Requires Node's built-in zstd support (Node >=24.9).
+ * Only the event envelope and metric-bearing fields are validated, not the full
+ * extensible DSH schema. Unknown event types are counted but otherwise ignored.
+ */
+import { open } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { Readable } from 'node:stream';
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { zstdDecompressSync } from 'node:zlib';
+
+const MAX_ZSTD_BYTES = 64 * 1024 * 1024;
+const HELP = `Usage: node scripts/analyze-session.mjs FILE.jsonl [FILE.jsonl.zstd ...]
+Explicit files only; no default scan, network, writes, or content/path output.
+Outputs per-file (1-based fileIndex) and pooled aggregate JSON metrics.
+Batch sizes come only from assistant/message content tool-call blocks.
+Tool execution events (tool/call) and assistant/attempt events are separate.
+Multi-call proportion uses tool-bearing responses as its denominator.
+Missing denominators and unreported output-token totals are null, not zero.
+Raw log counts include inherited history and repeated files; no deduplication.
+Not billed API counts, actual concurrency, LLM latency, or causal A/B savings.
+JSONL streams via readline. Zstd buffers synchronously: 64 MiB input/output cap.
+Unknown events are ignored for metrics; this is not full schema validation.
+`;
+
+class InputError extends Error {}
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const count = value => Number.isSafeInteger(value) && value >= 0;
+function requireValid(condition) {
+  if (!condition) throw new InputError('invalid event structure');
+}
+function accumulator() {
+  return {
+    eventCount: 0, modelResponseEvents: 0, modelAttemptEvents: 0,
+    toolExecutionEvents: 0, toolResultEvents: 0, toolCallBlocks: 0,
+    toolBearingResponses: 0, multiCallResponses: 0,
+    knownResponseCount: 0, unknownResponseCount: 0, reportedTotal: 0,
+    batchSizes: new Map(),
+  };
+}
+function add(state, event) {
+  requireValid(object(event) && typeof event.type === 'string' && event.type.length > 0);
+  if (event.type === 'session') {
+    requireValid(count(event.version) && typeof event.id === 'string' && count(event.createdAt));
+    return;
+  }
+  requireValid(object(event.data) && count(event.seq) && count(event.time));
+  state.eventCount++;
+  const { data } = event;
+  if (event.type === 'assistant/message') {
+    requireValid(object(data.message) && data.message.role === 'assistant' && Array.isArray(data.message.content));
+    let calls = 0;
+    for (const block of data.message.content) {
+      requireValid(object(block) && typeof block.type === 'string');
+      if (block.type === 'tool-call') {
+        requireValid(typeof block.id === 'string' && typeof block.name === 'string' && typeof block.arguments === 'string');
+        calls++;
+      }
+    }
+    state.modelResponseEvents++;
+    state.toolCallBlocks += calls;
+    if (calls > 0) {
+      state.toolBearingResponses++;
+      if (calls > 1) state.multiCallResponses++;
+      state.batchSizes.set(calls, (state.batchSizes.get(calls) ?? 0) + 1);
+    }
+    if (data.usage !== undefined) requireValid(object(data.usage));
+    const tokens = data.usage?.outputTokens;
+    if (tokens === undefined) state.unknownResponseCount++;
+    else {
+      requireValid(count(tokens));
+      state.knownResponseCount++;
+      state.reportedTotal += tokens;
+      requireValid(Number.isSafeInteger(state.reportedTotal));
+    }
+  } else if (event.type === 'assistant/attempt') {
+    requireValid(Array.isArray(data.stream));
+    state.modelAttemptEvents++;
+  } else if (event.type === 'tool/call') {
+    requireValid(typeof data.callId === 'string' && typeof data.name === 'string' && typeof data.arguments === 'string');
+    state.toolExecutionEvents++;
+  } else if (event.type === 'tool/result') {
+    requireValid(object(data.message) && data.message.role === 'tool');
+    state.toolResultEvents++;
+  }
+}
+function finish(state) {
+  const { batchSizes, knownResponseCount, unknownResponseCount, reportedTotal, ...metrics } = state;
+  const n = state.toolBearingResponses;
+  let median = null;
+  if (n) {
+    const left = Math.floor((n - 1) / 2);
+    const right = Math.floor(n / 2);
+    let seen = 0;
+    let sum = 0;
+    for (const [size, frequency] of [...batchSizes].sort((a, b) => a[0] - b[0])) {
+      if (left >= seen && left < seen + frequency) sum += size;
+      if (right >= seen && right < seen + frequency) sum += size;
+      seen += frequency;
+    }
+    median = sum / 2;
+  }
+  return {
+    ...metrics,
+    multiCallResponseProportion: n ? state.multiCallResponses / n : null,
+    meanCallsPerToolBearingResponse: n ? state.toolCallBlocks / n : null,
+    medianCallsPerToolBearingResponse: median,
+    outputTokens: { reportedTotal: knownResponseCount ? reportedTotal : null, knownResponseCount, unknownResponseCount },
+  };
+}
+
+/** Pure metrics over iterable public SessionEvent objects (optional session header). */
+export function analyzeEvents(events) {
+  const state = accumulator();
+  for (const event of events) add(state, event);
+  return finish(state);
+}
+
+async function inputStream(file) {
+  if (!file.endsWith('.jsonl') && !file.endsWith('.zstd')) throw new InputError('expected .jsonl or .zstd file');
+  const handle = await open(file, 'r');
+  let transferred = false;
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new InputError('expected a regular file');
+    if (file.endsWith('.zstd')) {
+      if (stat.size > MAX_ZSTD_BYTES) throw new InputError('zstd input exceeds 64 MiB limit');
+      const compressed = await handle.readFile();
+      if (compressed.length > MAX_ZSTD_BYTES) throw new InputError('zstd input exceeds 64 MiB limit');
+      let decoded;
+      try { decoded = zstdDecompressSync(compressed, { maxOutputLength: MAX_ZSTD_BYTES }); }
+      catch { throw new InputError('invalid zstd or expanded data exceeds 64 MiB limit'); }
+      return Readable.from([decoded]);
+    }
+    // The verified handle is reused: no second path lookup or implicit scanning.
+    const stream = handle.createReadStream({ autoClose: true });
+    transferred = true;
+    return stream;
+  } finally {
+    if (!transferred) await handle.close();
+  }
+}
+
+/** Analyze only supplied files; never include their names or content in results/errors. */
+export async function analyzeFiles(files) {
+  if (!Array.isArray(files) || !files.length) throw new InputError('supply at least one explicit session file');
+  const aggregate = accumulator();
+  const results = [];
+  for (const [index, file] of files.entries()) {
+    let lineNumber = 0;
+    let input;
+    let lines;
+    const local = accumulator();
+    try {
+      input = await inputStream(file);
+      lines = createInterface({ input, crlfDelay: Infinity });
+      for await (const line of lines) {
+        lineNumber++;
+        if (!line.trim()) continue;
+        let event;
+        try { event = JSON.parse(line); }
+        catch { throw new InputError('malformed JSON'); }
+        add(local, event);
+        add(aggregate, event);
+      }
+    } catch (error) {
+      const reason = error instanceof InputError ? error.message : 'unable to read session';
+      throw new InputError(`file ${index + 1}${lineNumber ? `, line ${lineNumber}` : ''}: ${reason}`);
+    } finally {
+      lines?.close();
+      input?.destroy();
+    }
+    results.push({ fileIndex: index + 1, metrics: finish(local) });
+  }
+  return { files: results, aggregate: finish(aggregate) };
+}
+
+async function main(args) {
+  if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+    process.stdout.write(HELP);
+    return;
+  }
+  try {
+    if (args.some(arg => arg.startsWith('-'))) throw new InputError('unknown option; use --help (prefix dash-leading paths with ./)');
+    process.stdout.write(`${JSON.stringify(await analyzeFiles(args), null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`analyze-session: ${error instanceof InputError ? error.message : 'analysis failed'}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  await main(process.argv.slice(2));
+}