@twinsearth/w2m-dsh-plugin 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to this project are documented here.
 
+## [1.0.5] — 2026-10-17
+
+**DSH-GPW ships as an optional sub-plugin, and the reason it never activated is fixed.**
+
+### What DSH-GPW is
+
+**Global Permission Watchdog.** It answers permission requests on the `approval/request` waterfall with a hard global
+budget: **at most 10 auto-approvals per rolling 60 s, at least 3000 ms apart.** Past either limit it returns
+`next()` -- *"no opinion"* -- so the request falls through to the human prompt **and waits**. It never refuses, and
+it never changes what is being asked.
+
+### Optional means optional, which decides where it lives
+
+The package declares **one** `dsh.bundle.patch`, and that is what makes the w2m plugin mount itself on install. **A
+second plugin in the same patch would mount for everyone**, and this one changes how permissions are answered -- that
+is an operator's decision, not a default.
+
+So it is exposed as `@twinsearth/w2m-dsh-plugin/gpw` and mounted by one explicit row:
+
+    - insert:
+        - id: dsh-gpw
+          name: '@twinsearth/w2m-dsh-plugin/gpw'
+
+**`insert:` is required and the reason is recorded in this package's own patch file**: no earlier layer creates a
+`dsh-gpw` row, and a bare `- id:` patch aimed at a nonexistent row is **skipped silently**. Removing the row
+disables it again.
+
+**It is deliberately not re-exported from `lib/index.js`.** A permission-answering plugin must not arrive because
+someone installed a fleet tool.
+
+### The defect that kept it from ever activating
+
+The standalone copy declared:
+
+    export const inject = { required: ['approval'] };
+
+**The host reads `inject` as an array of service names.** Measured across the shipped tree: **283 array-shaped
+declarations, 0 object-shaped.** So the host took the object's *key* and waited for a service literally named
+`required`:
+
+    pending (waiting for service: required)
+
+-- indefinitely, and the client reported the component as `等待依赖`. It is now `['approval']`, and `approval`
+does exist: `@deepseek-ai/dsh-base`'s patch mounts `@deepseek-ai/dsh-user-approval` as id `approval`.
+
+**The error message named its own cause**, which is why this took one measurement instead of an investigation: it
+said `required`, and `required` is the key.
+
+### What is verified, and what is not
+
+**Verified:** `lib/gpw.js` loads; `name` is `dsh-gpw`; `inject` is an array; `apply` is a function;
+`approval/request` and `allowed-once` both exist in the host (9 and 22 files respectively).
+
+**Not verified: that it mounts and intercepts.** That needs a live host with the row added. The observable evidence
+after a restart is its own startup line --
+
+    approval-ratelimit: active -- at most 10 auto-approvals per 60 s, at least 3000 ms apart, process-wide
+
+-- **and then the periodic counted line, without which "mounted and working" and "mounted and doing nothing" look
+identical.** That distinction is the reason those counters exist.
+
 ## [1.0.4] — 2026-10-17
 
 **The description described a different package, and it is the only thing many readers see.**

package/lib/gpw.js

@@ -0,0 +1,10 @@
+/**
+ * Package-facing entry for DSH-GPW: `@twinsearth/w2m-dsh-plugin/gpw`.
+ *
+ * The documented subpath a profile row names to enable the watchdog. A seam, not a second implementation -- the code
+ * lives in `src/plugin/gpw.mjs`, which is where it is readable.
+ *
+ * **It is deliberately not re-exported from `lib/index.js`.** The package root is what installs by default, and a
+ * permission-answering plugin must not arrive because someone installed a fleet tool.
+ */
+export { apply, inject, name } from '../src/plugin/gpw.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "main": "lib/index.js",
@@ -16,7 +16,8 @@
     "./rabbit": "./bin/w2m-rabbit.mjs",
     "./localside": "./bin/w2m-localside.mjs",
     "./stun": "./bin/w2m-stun.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./gpw": "./lib/gpw.js"
   },
   "files": [
     "mcp.json",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/plugin/gpw.mjs

@@ -0,0 +1,205 @@
+/**
+ * DSH-GPW -- Global Permission Watchdog (v1.0.5), shipped as an OPTIONAL sub-plugin of @twinsearth/w2m-dsh-plugin.
+ *
+ * ## What it does, in one paragraph
+ *
+ * It answers permission requests on the `approval/request` waterfall with a hard global budget: **at most 10
+ * auto-approvals per rolling 60 s, at least 3000 ms apart.** Anything past either limit returns `next()`, which is
+ * *"no opinion"* -- the request falls through to the human prompt and **waits**. It never refuses, and it never
+ * changes what is being asked; it only decides who answers and how fast.
+ *
+ * ## Why the budget exists
+ *
+ * Every auto-approval is a permission decision made without a human reading it. A watchdog with no ceiling is a
+ * plugin that grants everything and is indistinguishable from one that is working correctly -- the failure mode this
+ * repository has recorded seven times. The two counters it logs (`allowedTotal`, `deferredTotal`) exist so that
+ * "mounted and doing nothing" and "mounted and working" look different.
+ *
+ * ## How it is enabled -- it is NOT on by default
+ *
+ * Installing this package does **not** mount the watchdog: its own `dsh.bundle.patch` mounts only the w2m plugin.
+ * To enable it, add ONE `insert:` to the profile's `cordis.patch.yml`:
+ *
+ *     - insert:
+ *         - id: dsh-gpw
+ *           name: '@twinsearth/w2m-dsh-plugin/gpw'
+ *           config:
+ *             maxPerWindow: 10      # optional; these are the defaults
+ *             windowMs: 60000
+ *             minGapMs: 3000
+ *
+ * `insert:` is required: no earlier layer creates a `dsh-gpw` row, and a bare `- id:` patch aimed at a
+ * non-existent row is skipped **silently**. Remove the row to disable it again -- no other change is needed.
+ *
+ * ## Its dependency, and the bug that shipped in the standalone copy
+ *
+ * `inject = ['approval']`. The first version of this module declared `{ required: ['approval'] }`; the host reads
+ * `inject` as an array (**283 array-shaped declarations across the shipped tree, 0 object-shaped**), so it waited
+ * for a service named `required` and stayed `pending (waiting for service: required)` forever. `approval` itself
+ * exists: `@deepseek-ai/dsh-base`'s patch mounts `@deepseek-ai/dsh-user-approval` as id `approval`.
+ *
+ * ## Provenance
+ *
+ * Written as a standalone package `dsh-approval-ratelimit@1.0.0`, then folded in here so a fleet operator installs
+ * one thing. The logic is unchanged apart from the name and the `inject` fix; every comment explaining a decision is
+ * the original.
+ */
+
+/** @type {import('node:timers').Timeout | null} */
+let logTimer = null;
+
+export const name = 'dsh-gpw';
+
+export const inject = ['approval'];
+
+/**
+ * @param {object} ctx Cordis context.
+ * @param {object} [config]
+ * @param {number} [config.maxPerWindow] Auto-approvals allowed per rolling window. Default 10.
+ * @param {number} [config.windowMs] Window length in ms. Default 60000.
+ * @param {number} [config.minGapMs] Minimum gap between two auto-approvals, in ms. Default 3000.
+ */
+export function apply(ctx, config = {}) {
+  const maxPerWindow = positiveInt(config.maxPerWindow, 10);
+  const windowMs = positiveInt(config.windowMs, 60_000);
+  const minGapMs = positiveInt(config.minGapMs, 3_000);
+
+  /** Timestamps of the auto-approvals inside the current window, oldest first. */
+  const approvals = [];
+  /** Timestamp of the most recent auto-approval, or null. */
+  let lastApprovalAt = null;
+  /** Counters for the periodic line, so the operator can see this thing working. */
+  let deferredTotal = 0;
+  let allowedTotal = 0;
+
+  /**
+   * Drop approvals that have aged out of the window.
+   *
+   * A rolling window is the requirement; a fixed one would allow a burst of `2 * maxPerWindow`
+   * straddling a boundary (ten at the end of one minute, ten at the start of the next).
+   *
+   * @param {number} now
+   */
+  function prune(now) {
+    const cutoff = now - windowMs;
+    while (approvals.length > 0 && approvals[0] <= cutoff) approvals.shift();
+  }
+
+  /**
+   * Decide one request, without ever rejecting.
+   *
+   * @param {number} now
+   * @returns {{ allow: boolean, reason: string, inWindow: number }}
+   */
+  function decide(now) {
+    prune(now);
+    if (lastApprovalAt !== null && now - lastApprovalAt < minGapMs) {
+      return {
+        allow: false,
+        reason: `only ${now - lastApprovalAt} ms since the last auto-approval (needs ${minGapMs} ms)`,
+        inWindow: approvals.length,
+      };
+    }
+    if (approvals.length >= maxPerWindow) {
+      return {
+        allow: false,
+        reason: `${approvals.length} auto-approvals already in the last ${Math.round(windowMs / 1000)} s (limit ${maxPerWindow})`,
+        inWindow: approvals.length,
+      };
+    }
+    return { allow: true, reason: 'within both limits', inWindow: approvals.length };
+  }
+
+  /**
+   * One line per window of real activity, so a silent plugin and a broken plugin look different.
+   *
+   * The failure mode this guards against is the one this whole session keeps meeting: a component
+   * that is mounted, doing nothing, and indistinguishable from a healthy one. `allowedTotal` and
+   * `deferredTotal` are the two numbers that tell them apart.
+   */
+  function startReporter() {
+    if (logTimer !== null) return () => {};
+    logTimer = setInterval(() => {
+      if (allowedTotal === 0 && deferredTotal === 0) return;
+      ctx.logger?.info?.(
+        `approval-ratelimit: ${allowedTotal} auto-approved, ${deferredTotal} deferred to the human `
+        + `(limit ${maxPerWindow}/${Math.round(windowMs / 1000)}s, gap ${minGapMs}ms, ${approvals.length} in the current window)`,
+      );
+    }, windowMs);
+    logTimer.unref?.();
+    return () => {
+      if (logTimer !== null) {
+        clearInterval(logTimer);
+        logTimer = null;
+      }
+    };
+  }
+
+  /**
+   * The answerer.
+   *
+   * Registered on the `approval/request` waterfall. Returning `'allowed-once'` grants this one
+   * request; returning `next()` is "no opinion" and hands the decision to whoever answers next --
+   * which is the human prompt, and it *waits* there rather than being refused.
+   */
+  const disposeListener = ctx.on('approval/request', (request, next) => {
+    const now = Date.now();
+    const verdict = decide(now);
+    if (!verdict.allow) {
+      deferredTotal += 1;
+      // Debug, not warn: deferring is the designed behaviour of this plugin, and warning about the
+      // normal path trains an operator to ignore the line that would matter.
+      ctx.logger?.debug?.(
+        `approval-ratelimit: deferring to the human -- ${verdict.reason}`
+        + (request?.toolName ? ` (tool ${request.toolName})` : ''),
+      );
+      return next();
+    }
+    approvals.push(now);
+    lastApprovalAt = now;
+    allowedTotal += 1;
+    ctx.logger?.info?.(
+      `approval-ratelimit: auto-approved (${approvals.length}/${maxPerWindow} in the current window)`
+      + (request?.toolName ? ` tool ${request.toolName}` : '')
+      + (request?.reason ? ` -- ${request.reason}` : ''),
+    );
+    return 'allowed-once';
+  });
+
+  const stopReporter = startReporter();
+
+  // Reversible: the host owns this effect, so an unload removes the answerer and the timer with it.
+  // A listener that outlived its plugin would keep approving requests with nobody watching.
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => () => {
+      disposeListener?.();
+      stopReporter();
+    });
+  } else {
+    // No effect seam: say so rather than pretending the cleanup is guaranteed.
+    ctx.logger?.warn?.(
+      'approval-ratelimit: the context provides no ctx.effect, so the answerer and its reporter '
+      + 'cannot be released on unload',
+    );
+  }
+
+  ctx.logger?.info?.(
+    `approval-ratelimit: active -- at most ${maxPerWindow} auto-approvals per ${Math.round(windowMs / 1000)} s, `
+    + `at least ${minGapMs} ms apart, process-wide; everything else waits for the human`,
+  );
+}
+
+/**
+ * Coerce a config value to a positive integer, falling back to the default.
+ *
+ * A misconfigured limit must not silently become "0", which would disable the plugin while looking
+ * like it was on -- and must not become a non-finite number, which would break the comparison.
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function positiveInt(value, fallback) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return fallback;
+  return Math.floor(value);
+}

package/src/plugin/tools.mjs

@@ -208,7 +208,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.0.4';
+const PLUGIN_VERSION = '1.0.5';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;