@deepseek-ai/dsh-tool-workflow 0.1.7-alpha.2 → 0.1.7-rc.2

package/README.i18n.yaml

@@ -1,6 +1,103 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/tool-workflow/README.md
-README.md: ce2804d2db83e410edb248332c517200dd6963dc
-README.zh.md: 2ef39745a74eb6ab899108613c8cc8ac396f1352
+/:
+  en: de1de2c83432e095
+  zh: facea56204dc9c76
+/deepseek-ai-dsh-tool-workflow:
+  en: b8980ef14abe1385
+  zh: 4052bf0c13f7917a
+/deepseek-ai-dsh-tool-workflow/summary:
+  en: c18878dbaecc42bb
+  zh: 360e2a13717bdb04
+/deepseek-ai-dsh-tool-workflow/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-workflow/use-this-package:
+  en: a0a9d655187f285d
+  zh: 230b4556fff9f08b
+/deepseek-ai-dsh-tool-workflow/use-this-package/calling-the-tool:
+  en: aeebba9469f0558d
+  zh: e2e74d4272e94201
+/deepseek-ai-dsh-tool-workflow/use-this-package/what-to-expect-during-a-run:
+  en: 19ec4f830edb8e1a
+  zh: 8579ae5274aca6de
+/deepseek-ai-dsh-tool-workflow/use-this-package/background-runs:
+  en: 3083f3f2657a46e3
+  zh: bca5cb741ea76798
+/deepseek-ai-dsh-tool-workflow/use-this-package/config:
+  en: 18d1067a480e072e
+  zh: cf27e51f0dec2f4d
+/deepseek-ai-dsh-tool-workflow/understand-the-implementation:
+  en: 18684e6da513cdb5
+  zh: bd4cdcabfe4722ec
+/deepseek-ai-dsh-tool-workflow/understand-the-implementation/design-concept:
+  en: 6d09119d1393c254
+  zh: a7cc03daa59650ec
+/deepseek-ai-dsh-tool-workflow/understand-the-implementation/run-lifecycle:
+  en: 8ea9ce564251249a
+  zh: a59b88cc14a25a1f
+/deepseek-ai-dsh-tool-workflow/understand-the-implementation/background-lifecycle:
+  en: 35950b2015800ec5
+  zh: 5ae6f5a5e53dc585
+/deepseek-ai-dsh-tool-workflow/understand-the-implementation/durable-session-records:
+  en: b491e7ab9590e625
+  zh: c0a2fb797eb1cca0
+/deepseek-ai-dsh-tool-workflow/understand-the-implementation/render-intent:
+  en: 389b3740ec1f5ac2
+  zh: 78430014f5e270e2
+/deepseek-ai-dsh-tool-workflow/understand-the-implementation/source-map:
+  en: 8a426c65b06a2320
+  zh: e2bb8f12252fbd4d
+/deepseek-ai-dsh-tool-workflow/further-exploration:
+  en: cf5f97e745586c05
+  zh: 32fa36224cde5d83
+/deepseek-ai-dsh-tool-workflow/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-tool-workflow/model-experience/system-prompt:
+  en: cf78b9dd5596495f
+  zh: bd44560f8c2435e8
+/deepseek-ai-dsh-tool-workflow/model-experience/system-prompt/what-the-model-sees:
+  en: 13411e342534174d
+  zh: 0991c63ac26ada3f
+/deepseek-ai-dsh-tool-workflow/model-experience/system-prompt/what-the-model-sees/workflow-guidance:
+  en: 214b61fe5bdb1097
+  zh: 2358fc753d21f12c
+/deepseek-ai-dsh-tool-workflow/model-experience/system-prompt/token-effect:
+  en: dab67480bfde6224
+  zh: 85bbf18da3767aa7
+/deepseek-ai-dsh-tool-workflow/model-experience/system-prompt/kv-cache-effect:
+  en: 13e7c6007bf6b5dc
+  zh: 1690c361c6f07ba4
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-schema:
+  en: e4c7376d4f29dbd5
+  zh: 6b7a9eaf69c9ea53
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-schema/what-the-model-sees:
+  en: 5af871e5bc1126c7
+  zh: 07b5e2b37c766a7e
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-schema/token-effect:
+  en: 2038bdeb03f99195
+  zh: 90959fa2708b910f
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-schema/kv-cache-effect:
+  en: e01353abf883d9ba
+  zh: 3c9e5d6bd7f4e831
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-call-history-and-result:
+  en: 9717b983b6a857e3
+  zh: 611a2dadf7c0c706
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-call-history-and-result/what-the-model-sees:
+  en: acd5e87161ced588
+  zh: 5ffe85926ee1b88d
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-call-history-and-result/token-effect:
+  en: 88cfc89c7dc19dbb
+  zh: 75e674844f311937
+/deepseek-ai-dsh-tool-workflow/model-experience/tool-call-history-and-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/deepseek-ai-dsh-tool-workflow/known-limitations-and-deferred-work:
+  en: 28e362db0d4d929f
+  zh: d2b1a4da09f55a42
+/deepseek-ai-dsh-tool-workflow/known-limitations-and-deferred-work/dev-note:
+  en: 9e9abf9ef01e719a
+  zh: df286968b39ec955

package/README.md

@@ -29,7 +29,7 @@ The `workflow` tool runs a model-authored orchestration script that fans work ou
 
 ### Calling the tool
 
-The model submits three parameters plus one flag: `meta` (required identity data: `name`, `description`, and optional `whenToUse` and `phases`), `script` (required plain JavaScript body — no `export const meta` statement; the tool description carries the complete authoring contract), `args` (optional JSON object exposed to the script as the `args` global; wrap a bare list in a field so the wire schema stays honest), and `run_in_background` (optional; present only while `enableRunInBackground` holds).
+The model submits three parameters plus one flag: `meta` (required identity data: `name`, `description`, and optional `whenToUse` and `phases`), `script` (required plain JavaScript body — no `export const meta` statement; its parameter description carries the body rules and the tool description carries the hook contract), `args` (optional JSON object exposed to the script as the `args` global; wrap a bare list in a field so the wire schema stays honest), and `run_in_background` (optional; present only while `enableRunInBackground` holds).
 
 A foreground success returns the envelope `{ kind: 'foreground', runId, agentsStarted, result }`, rendered to the model as `workflow "<name>" completed (<count> agent<optional-s>).` followed by `Return value:` and the pretty-printed JSON. A workflow that cannot start — a script parse or meta validation failure — returns an error the model can correct from. Cancellation and execution failures return `Error: workflow run was cancelled` or `Error: workflow run failed: <error>`; partial output is never reported as success.
 

package/README.zh.md

@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 调用工具
 
-模型提交三个参数外加一个开关：`meta`（必需的身份数据：`name`、`description`，以及可选的 `whenToUse` 与 `phases`）、`script`（必需的纯 JavaScript 脚本体——不含 `export const meta` 语句；工具描述携带完整的编写约定）、`args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态），以及 `run_in_background`（可选；仅在 `enableRunInBackground` 生效时存在）。
+模型提交三个参数外加一个开关：`meta`（必需的身份数据：`name`、`description`，以及可选的 `whenToUse` 与 `phases`）、`script`（必需的纯 JavaScript 脚本体——不含 `export const meta` 语句；其参数描述携带脚本体规则，工具描述携带钩子约定）、`args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态），以及 `run_in_background`（可选；仅在 `enableRunInBackground` 生效时存在）。
 
 前台成功返回包络 `{ kind: 'foreground', runId, agentsStarted, result }`，向模型渲染为 `workflow "<name>" completed (<count> agent<optional-s>).`，后接 `Return value:` 与美化打印的 JSON。无法启动的工作流——脚本解析或 meta 校验失败——返回模型可以修正的错误。取消与执行失败返回 `Error: workflow run was cancelled` 或 `Error: workflow run failed: <error>`；部分输出绝不会被报告为成功。
 

package/lib/index.js

@@ -133,26 +133,19 @@ function createWorkflowRecorder(ctx) {
 	};
 }
 /**
-* The script-authoring contract, embedded in the tool description. This IS the
-* model-facing spec: the meta block, the hooks and their exact semantics, and
-* the supported schema subset. The closing execution sentence follows the
-* composition: only a background-enabled tool describes `run_in_background`.
+* The script-authoring contract, embedded in the tool description: the hooks,
+* their exact semantics, and the supported schema subset. Parameter-level
+* rules live in the parameter descriptions.
 */
 const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.
 
-The workflow's identity rides the \`meta\` parameter as JSON: required \`name\` (short kebab-case) and \`description\` strings, optional \`whenToUse\` string and \`phases\` array (\`{title, detail?, provider?, model?}\`). The \`script\` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO \`export const meta\` statement — meta is a parameter, not code), running with top-level await; end with \`return <value>\` — the value must be JSON-serializable and is this tool's result.
-
 Script-body hooks:
-- \`agent(prompt, opts?): Promise<any>\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), and independent \`provider\`/\`model\` LLM target overrides (either may be provided alone). Anything else (\`effort\`/\`isolation\`/\`agentType\`) is rejected loudly.
-- \`pipeline(items, ...stages): Promise<any[]>\` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives \`(prev, item, index)\`. An ordinary stage throw drops that ITEM to \`null\` and skips its remaining stages.
+- \`agent(prompt, opts?): Promise<any>\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), and independent \`provider\`/\`model\` LLM target overrides.
+- \`pipeline(items, ...stages): Promise<any[]>\` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives \`(prev, item, index)\`. A stage throw drops that ITEM to \`null\` and skips its remaining stages.
 - \`parallel(thunks): Promise<any[]>\` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to \`null\`.
 - \`phase(title)\` — start a progress phase; \`log(message)\` — narrate progress; \`args\` — the tool call's \`args\` input, verbatim.
 
-Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`.
-
-Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them.`;
-const FOREGROUND_ONLY_CLOSING = " The run executes in the foreground: this call returns when the whole script finishes.";
-const BACKGROUND_CLOSING = " The run executes in the foreground by default: this call returns when the whole script finishes. Set `run_in_background: true` for a long run: the call returns a job id immediately, the run keeps orchestrating in the background, and its return value arrives with the job's completion notice (check on it with `job_output`, stop it with `job_kill`).";
+Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) end the whole script instead of producing \`null\`. The script has no filesystem, network, timer, or Node.js APIs; the agents do the work.`;
 /** The pending-state card: a generic card titled by the workflow's meta name. */
 function presentWorkflowCall(args) {
 	return {
@@ -274,18 +267,18 @@ function apply(ctx, config) {
 	});
 	ctx.tools.register(defineTool({
 		name: toolName,
-		description: DESCRIPTION + (enableRunInBackground ? BACKGROUND_CLOSING : FOREGROUND_ONLY_CLOSING),
+		description: DESCRIPTION,
 		parameters: {
 			script: {
 				type: "string",
 				required: true,
-				description: "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."
+				description: "The plain JavaScript body, not TypeScript and without an `export const meta` statement; top-level await is allowed. End with `return <value>`; the JSON-serializable value is this tool's result."
 			},
 			meta: {
 				type: "object",
 				additionalProperties: true,
 				required: true,
-				description: "The workflow identity block (plain JSON — never code).",
+				description: "The workflow identity as plain JSON, not code.",
 				properties: {
 					name: {
 						type: "string",

package/lib/types/index.js

@@ -91,26 +91,19 @@ function createWorkflowRecorder(ctx) {
     };
 }
 /**
- * The script-authoring contract, embedded in the tool description. This IS the
- * model-facing spec: the meta block, the hooks and their exact semantics, and
- * the supported schema subset. The closing execution sentence follows the
- * composition: only a background-enabled tool describes `run_in_background`.
+ * The script-authoring contract, embedded in the tool description: the hooks,
+ * their exact semantics, and the supported schema subset. Parameter-level
+ * rules live in the parameter descriptions.
  */
 const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.
 
-The workflow's identity rides the \`meta\` parameter as JSON: required \`name\` (short kebab-case) and \`description\` strings, optional \`whenToUse\` string and \`phases\` array (\`{title, detail?, provider?, model?}\`). The \`script\` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO \`export const meta\` statement — meta is a parameter, not code), running with top-level await; end with \`return <value>\` — the value must be JSON-serializable and is this tool's result.
-
 Script-body hooks:
-- \`agent(prompt, opts?): Promise<any>\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), and independent \`provider\`/\`model\` LLM target overrides (either may be provided alone). Anything else (\`effort\`/\`isolation\`/\`agentType\`) is rejected loudly.
-- \`pipeline(items, ...stages): Promise<any[]>\` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives \`(prev, item, index)\`. An ordinary stage throw drops that ITEM to \`null\` and skips its remaining stages.
+- \`agent(prompt, opts?): Promise<any>\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), and independent \`provider\`/\`model\` LLM target overrides.
+- \`pipeline(items, ...stages): Promise<any[]>\` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives \`(prev, item, index)\`. A stage throw drops that ITEM to \`null\` and skips its remaining stages.
 - \`parallel(thunks): Promise<any[]>\` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to \`null\`.
 - \`phase(title)\` — start a progress phase; \`log(message)\` — narrate progress; \`args\` — the tool call's \`args\` input, verbatim.
 
-Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`.
-
-Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them.`;
-const FOREGROUND_ONLY_CLOSING = ' The run executes in the foreground: this call returns when the whole script finishes.';
-const BACKGROUND_CLOSING = ' The run executes in the foreground by default: this call returns when the whole script finishes. Set `run_in_background: true` for a long run: the call returns a job id immediately, the run keeps orchestrating in the background, and its return value arrives with the job\'s completion notice (check on it with `job_output`, stop it with `job_kill`).';
+Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) end the whole script instead of producing \`null\`. The script has no filesystem, network, timer, or Node.js APIs; the agents do the work.`;
 /** The pending-state card: a generic card titled by the workflow's meta name. */
 function presentWorkflowCall(args) {
     return {
@@ -251,18 +244,19 @@ export function apply(ctx, config) {
     });
     ctx.tools.register(defineTool({
         name: toolName,
-        description: DESCRIPTION + (enableRunInBackground ? BACKGROUND_CLOSING : FOREGROUND_ONLY_CLOSING),
+        description: DESCRIPTION,
         parameters: {
             script: {
                 type: 'string',
                 required: true,
-                description: 'The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`).',
+                description: 'The plain JavaScript body, not TypeScript and without an `export const meta` statement; top-level await is allowed. '
+                    + 'End with `return <value>`; the JSON-serializable value is this tool\'s result.',
             },
             meta: {
                 type: 'object',
                 additionalProperties: true,
                 required: true,
-                description: 'The workflow identity block (plain JSON — never code).',
+                description: 'The workflow identity as plain JSON, not code.',
                 properties: {
                     name: { type: 'string', required: true, description: 'Short kebab-case workflow name.' },
                     description: { type: 'string', required: true, description: 'One-line description of what the workflow does.' },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-workflow",
   "description": "Model-facing workflow tool: run a JavaScript orchestration script over ctx.workflowEngine",
-  "version": "0.1.7-alpha.2",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -37,34 +37,34 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-jobs": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.7-alpha.2",
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-workflow": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-agent": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-workflow": "0.1.7-rc.2"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "~3.18.4"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-agent": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-jobs": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-jobs-local": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-subagent": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-tool-jobs": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-workflow-ptc": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-workflow": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-jobs-local": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tool-jobs": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-workflow": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-workflow-ptc": "0.1.7-rc.2"
   }
 }