deepseek-coordination 0.1.5 → 0.1.7

package/README.md

@@ -85,7 +85,7 @@ deepseek-coordination/
 ├─ tests/                          golden (Windows/POSIX/desktop injection), table conformance, encoding, plugin, permission, takeover, workflow suites
 │  ├─ conformance.ps1              command.txt and spec/verbs.tsv must describe the same surface (5 cases)
 │  ├─ takeover.test.mjs            byte-level format preservation, read windowing, eligibility (41 cases)
-│  ├─ workflow.test.mjs            phase gates, the user's choice, and the KV-cache invariant (30 cases)
+│  ├─ workflow.test.mjs            phase gates, the user's choice, and the KV-cache invariant (31 cases)
 │  ├─ smoke-desktop-sh.sh          what the POSIX desktop verbs actually inject (52 cases)
 │  └─ fake-xdotool, fake-wmctrl    recording stand-ins, so the desktop verbs can be verified with no X server
 └─ permission.json                 authorization data (an empty file in the repository; that is the initial state)
@@ -914,7 +914,7 @@ npm run test:all        # runs everything below, in order
 | Plugin | `node tests/plugin.test.mjs` | 13 | **13 passed, 0 failed** |
 | Takeover interceptions | `node tests/takeover.test.mjs` | 41 | **41 passed, 0 failed** |
 | Permission delegate | `node tests/permission.test.mjs` | 18 | **18 passed, 0 failed** |
-| Workflow | `node tests/workflow.test.mjs` | 30 | **30 passed, 0 failed** |
+| Workflow | `node tests/workflow.test.mjs` | 31 | **31 passed, 0 failed** |
 | Bundle resolution | `node tools/verify-bundle.mjs` | 16 | **16 passed, 0 failed** |
 | Package completeness | `node tools/verify-package.mjs` | 21 | **21 passed, 0 failed** |
 | Plugin load | `node tools/verify-plugin-load.mjs` | 30 | **30 passed, 0 failed** |
@@ -1068,10 +1068,11 @@ Copyright (c) 2026 Eloy Kim
 ```
 
 The licence file is pure ASCII, LF-terminated and BOM-free, consistent with the rest of the
-repository's encoding contracts. One earlier description needs correcting: it is **not** listed in
-`package.json`'s `files` whitelist (which has 20 entries; it includes `src/host/bin/dsh-os7.ps1` but
-neither `LICENSE` nor `README.zh-CN.md`), so the file stays in a checkout but is not distributed with
-the published package.
+repository's encoding contracts. An earlier description here claimed it was **not** distributed because it
+is not listed in `package.json`'s `files` whitelist. That was wrong, and the published tarball proves it:
+`npm pack deepseek-coordination@0.1.5` contains `package/LICENSE` **and** `package/README.zh-CN.md`, because
+npm always includes those two names regardless of `files`. The whitelist has 20 entries and includes
+`src/host/bin/dsh-os7.ps1`; the two files simply do not need to be in it.
 
 The verb contract and the specification documents are part of the source: a behaviour change should be
 reflected in `src/host/spec/verbs.tsv`, `src/host/command.txt` and `src/host/docs/os-spec.md`, not only

package/README.zh-CN.md

@@ -603,7 +603,7 @@ npm run test:all        # 按顺序跑下面全部
 | 插件 | `node tests/plugin.test.mjs` | 13 | **13 通过，0 失败** |
 | 接管拦截 | `node tests/takeover.test.mjs` | 41 | **41 通过，0 失败** |
 | 授权委托 | `node tests/permission.test.mjs` | 18 | **18 通过，0 失败** |
-| 工作流 | `node tests/workflow.test.mjs` | 30 | **30 通过，0 失败** |
+| 工作流 | `node tests/workflow.test.mjs` | 31 | **31 通过，0 失败** |
 | bundle 解析 | `node tools/verify-bundle.mjs` | 16 | **16 通过，0 失败** |
 | 打包完整性 | `node tools/verify-package.mjs` | 21 | **21 通过，0 失败** |
 | 插件装载 | `node tools/verify-plugin-load.mjs` | 30 | **30 通过，0 失败** |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepseek-coordination",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "description": "Cross-platform atomic OS-interaction surface for the DeepSeek Harness: one argument-stable verb set implemented natively on each OS, with byte-exact charset, BOM and line-ending handling.",
@@ -93,6 +93,7 @@
     "test:encoding": "powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File tests/encoding.ps1",
     "test:conformance": "powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File tests/conformance.ps1",
     "test:plugin": "node tests/plugin.test.mjs",
+    "test:activation": "node tests/activation.test.mjs",
     "test:takeover": "node tests/takeover.test.mjs",
     "test:permission": "node tests/permission.test.mjs",
     "test:workflow": "node tests/workflow.test.mjs",

package/src/permission/index.js

@@ -192,7 +192,12 @@ function nextRuleId(document) {
   return `r-${String(max + 1).padStart(4, '0')}`
 }
 
-export function apply(ctx, config = {}) {
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`. This row happens to ship with a config, so
+  // it never hit the fault — but the fix belongs here too, or a deployment that trims the row's config
+  // takes the consent delegate down with it.
+  const config = rawConfig ?? {}
   const path = permissionPathOf(config)
   const auditLimit = config.auditLimit ?? AUDIT_LIMIT
 

package/src/plugin/index.js

@@ -27,7 +27,11 @@ export const name = 'dsh-os'
 /** The plugin is inert without the tool registry. */
 export const inject = ['tools']
 
-export function apply(ctx, config = {}) {
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`. Every entry point in this package guards the
+  // same way, so a row whose config is trimmed degrades to defaults instead of failing to activate.
+  const config = rawConfig ?? {}
   const timeoutMs = config.timeoutMs ?? 120000
 
   ctx.tools.register({

package/src/plugin/invoke.js

@@ -113,7 +113,11 @@ export const DEFAULT_SCRIPT_DIR = 'src/host/bin'
  * DSH_OS_POWERSHELL still overrides the executable. `'auto'` uses 7.6 only when both the artefact and
  * a pwsh executable are present, and falls back to 5.1 otherwise.
  */
-export function resolveInvocation(config = {}) {
+export function resolveInvocation(rawConfig) {
+  // `?? {}` rather than a default parameter. Cordis passes a row's config through as `null` when the row
+  // declares none, and a default parameter only fires for `undefined` — so `config.scriptPath` on that
+  // null threw and the plugin row failed to activate. Every caller may pass null.
+  const config = rawConfig ?? {}
   const explicit = config.scriptPath ? [config.scriptPath] : []
   const dir = config.scriptPath
     ? dirname(config.scriptPath)
@@ -192,7 +196,8 @@ export function resolveInvocation(config = {}) {
 }
 
 /** The directory an invocation would search, for error messages that name a real path. */
-export function searchedDirectory(config = {}) {
+export function searchedDirectory(rawConfig) {
+  const config = rawConfig ?? {}
   return config.scriptPath ?? join(PKG_ROOT, config.scriptDir ?? DEFAULT_SCRIPT_DIR)
 }
 

package/src/plugin/settings.js

@@ -110,9 +110,15 @@ export function writeSettings(file, settings) {
  * second one is evidence that the feature works.
  */
 export class SettingsService {
-  constructor(ctx, config = {}) {
+  constructor(ctx, config) {
     this.ctx = ctx
-    this.file = config.settingsPath ?? settingsPath()
+    // `config ?? {}` rather than a default parameter: Cordis passes the row's config as `null` when the
+    // row declares none, and a default parameter does not fire for null. This is exactly what made the
+    // shipped 0.1.5 fail to activate with "Cannot read properties of null (reading 'settingsPath')".
+    const resolved = config ?? {}
+    this.file = typeof resolved.settingsPath === 'string' && resolved.settingsPath.trim() !== ''
+      ? resolved.settingsPath
+      : settingsPath()
     this.settings = readSettings(this.file)
     this.activity = []
     this.listeners = new Set()
@@ -312,8 +318,11 @@ export function makeSettingsRoutes(service) {
  */
 export const name = 'dsh-os-settings'
 
-export function apply(ctx, config = {}) {
-  const service = new SettingsService(ctx, config)
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`. This row ships WITHOUT a config, which is
+  // what made the shipped 0.1.5 fail with "Cannot read properties of null (reading 'settingsPath')".
+  const service = new SettingsService(ctx, rawConfig ?? {})
 
   // `ctx.provide` REGISTERS the service and returns a disposer; `ctx.set` only overwrites the value of a
   // service that was already provided, and calling it first throws

package/src/plugin/takeover.js

@@ -388,7 +388,11 @@ function eligible(tool, args) {
   }
 }
 
-export function apply(ctx, config = {}) {
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`, so the first property read threw and the
+  // row never activated. This row is shipped WITHOUT a config, so it hit exactly that.
+  const config = rawConfig ?? {}
   const toolTimeoutMs = config.timeoutMs ?? 120000
   // Mirrors the `tool-fs` row's `readLimit` (2000 by default): the interception must not quietly apply
   // a different window size than the built-in it replaced.

package/src/plugin/workflow.js

@@ -1199,20 +1199,31 @@ export function workflowSectionText() {
  * The tool description.
  *
  * This is now the ONLY discovery path, because the prompt section is a frozen constant and cannot carry
- * guidance. It is in the tool catalog, which sits inside the cached prefix and is sent once — so clarity
- * here is cheaper than brevity, but it still has to be short enough not to bloat the prefix.
+ * guidance. Two consequences it has to honour, and the first version of this text failed the first one:
+ *
+ *   1. it must NAME the tool. The earlier text said "Four calls:" and then listed `start` / `plan` /
+ *      `choose` / `run`, which reads as four tool names — a model following it would call tools that do not
+ *      exist. Caught by verifying the packed tarball rather than the checkout.
+ *   2. every call in the shortest path is spelled as `workflow_plan(action: "...")`, so the model never has
+ *      to guess how the pieces fit together. The per-phase guidance is deliberately not here: it travels in
+ *      each result's `next` field, which is appended history and therefore costs the cache nothing.
+ *
+ * It lives in the tool catalog, inside the cached prefix, sent once and unchanged for the session.
  */
 const TOOL_DESCRIPTION = [
-  'Intent-first workflow: agree on what is wanted and how it will be done, before doing it. Use it when a',
-  'request is more than one obvious step, or when you would have to guess the user\'s intent, their',
-  'preferred approach, or where the work belongs. Four calls:',
-  '"start" (the prompt verbatim, plus 1-3 questions about intent OR the assumptions you are making) ->',
-  '"plan" (approach and process, at least two alternatives with pros and cons, your recommendation) ->',
-  '"choose" (ASKS THE USER; you cannot answer it for them) ->',
-  '"run" (execute the chosen option; add "outcome" to close the workflow in the same call).',
-  'Then "note" for a decision, "checkpoint" at a boundary. Long documents go to files and only a line',
-  'returns, so the conversation stays small; results list the files. A step out of order is refused, and the',
-  'refusal names the phase to record first. Every result carries "next", the one call to make. Also "status", "reset".',
+  'workflow_plan: agree on what is wanted and how it will be done, before doing it. Use it when a request is',
+  'more than one obvious step, or when you would have to guess the user\'s intent, their preferred approach,',
+  'or where the work belongs. Call it four times:',
+  '1. workflow_plan(action: "start") — the user\'s prompt verbatim, plus 1-3 questions about intent OR the',
+  'assumptions you are making.',
+  '2. workflow_plan(action: "plan") — the approach and process, at least two alternatives with pros and cons,',
+  'and which one you recommend.',
+  '3. workflow_plan(action: "choose") — ASKS THE USER; their answer is recorded and you cannot answer it for them.',
+  '4. workflow_plan(action: "run") — execute the chosen option; add "outcome" to close the workflow in this call.',
+  'Each result carries "next", the one call to make. Then workflow_plan(action: "note") for a decision, or',
+  '"checkpoint" at a boundary. Long documents go to files and only a line comes back, so the conversation stays',
+  'small; results list the files. A step out of order is refused, and the refusal names the phase to record',
+  'first. Also available: "status", "reset".',
 ].join(' ')
 
 const QUESTION_SCHEMA = {
@@ -1394,12 +1405,17 @@ export function workflowToolDefinition(handlers) {
   }
 }
 
-export function apply(ctx, config = {}) {
-  const root = typeof config.workflowRoot === 'string' && config.workflowRoot.trim() !== ''
-    ? config.workflowRoot
+export function apply(ctx, config) {
+  // `config ?? {}` rather than a `config = {}` default parameter, because the two are NOT equivalent:
+  // a default parameter only fires for `undefined`, and Cordis hands the row's config through as `null`
+  // when the row declares none. The shipped 0.1.5 read `config.workflowRoot` off that null and the row
+  // failed to activate with "Cannot read properties of null".
+  const resolved = config ?? {}
+  const root = typeof resolved.workflowRoot === 'string' && resolved.workflowRoot.trim() !== ''
+    ? resolved.workflowRoot
     : workflowRoot()
-  const autoCompact = config.autoCompact !== false
-  const maxCheckpoints = Number.isInteger(config.maxCheckpoints) && config.maxCheckpoints > 0 ? config.maxCheckpoints : 20
+  const autoCompact = resolved.autoCompact !== false
+  const maxCheckpoints = Number.isInteger(resolved.maxCheckpoints) && resolved.maxCheckpoints > 0 ? resolved.maxCheckpoints : 20
 
   // The engine's own automatic compaction is named in the checkpoint result rather than invoked: this
   // plugin holds no session handle, and a call into a service whose context contract is not published
@@ -1435,14 +1451,28 @@ export function apply(ctx, config = {}) {
 
   if (typeof ctx.tools?.register === 'function') ctx.tools.register(workflowToolDefinition(handlers))
 
-  // The prompt half is registered only when the registry is present, so a deployment without it loses
-  // the section rather than the feature. The text is a constant: no state is read, nothing is looked up,
-  // and the model's cached prefix survives every phase of every workflow. See SECTION_TEXT.
-  if (typeof ctx.systemPrompt?.section === 'function') {
-    ctx.systemPrompt.section({
-      name: 'dsh-os:workflow',
-      order: sectionOrder(ctx.systemPrompt),
-      text: SECTION_TEXT,
+  // The prompt half is registered through `ctx.inject`, NOT by reading `ctx.systemPrompt` directly.
+  //
+  // Reading it directly is what broke the shipped 0.1.5: Cordis resolves a service property through an
+  // enforcing proxy, so an undeclared service does not read as `undefined` — it THROWS
+  //   Error: cannot get property "systemPrompt" without inject
+  // and a guard of the form `typeof ctx.systemPrompt?.section === 'function'` never gets to run, because
+  // the property access itself is the throw. The row then failed to activate entirely, losing the tool
+  // as well as the section.
+  //
+  // `ctx.inject` is the first-party pattern for an optional service (`dsh-tool-fs` registers its image
+  // tool the same way): the callback runs when the service is present and unwinds when it goes away, and
+  // a deployment without a system prompt keeps the tool instead of losing everything.
+  //
+  // The text is a constant: no state is read, nothing is looked up, and the model's cached prefix
+  // survives every phase of every workflow. See SECTION_TEXT.
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['systemPrompt'], (scoped) => {
+      scoped.systemPrompt.section({
+        name: 'dsh-os:workflow',
+        order: sectionOrder(scoped.systemPrompt),
+        text: SECTION_TEXT,
+      })
     })
   }