@twinsearth/w2m-dsh-plugin 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.0] — 2026-10-15
+
+**`w2m_approvals`: the approval chain is reachable by an operator, not only by the suite.**
+
+The tenth tool. `action: "list"` reads the queue, `approve` and `reject` settle one request by `approval_id`.
+Until now the chain from 0.25.0 was **closed in code and testable end to end while no operator could reach
+it**; this is the tool that opens it.
+
+### Every row says whether *you* may act, and why not when you may not
+
+A list filtered to what the caller may answer would be shorter and would **make the fleet look idle at the
+moment it is most blocked.** `listFor` already returns each row with `may_act` and `why_not`; the tool passes
+them through instead of hiding work above the caller's authority.
+
+### `actor_level` is a parameter, and that is deliberate
+
+The machine's own `actorAuthorityLevel` says what it may **dispatch as**. An approver's level is a fact about
+the person answering, and a decision made on the dispatcher's level would let a machine approve its own
+escalations. Passing it explicitly is what keeps `APPROVAL_SELF_APPROVAL` meaningful rather than incidental.
+
+**Settling without a level is refused** (`W2M_APPROVAL_LEVEL`) rather than defaulted, so a decision is never
+attributed to a level nobody supplied. Listing **without** a level still works and says so: `level_known:
+false`, with a note explaining that the queue is visible but whether any of it is answerable is not known —
+**knowing what is waiting does not require the authority to answer it, and a queue only its supervisors can
+see is a queue that stays full.**
+
+### The note on every settle, because a reader will assume otherwise
+
+> *"the request is settled; the dispatch did not run and must be attempted again"*
+
+Approval means the next attempt is allowed, not that anything already happened. A tool that settled quietly
+would leave its caller waiting for a result that is never coming.
+
+### Three defects of mine, all caught by the suite or by checking
+
+* I called a `json(...)` helper **that does not exist in this file** — every tool returns `JSON.stringify(...)`.
+  `node --check` passed, so only reading the surrounding code found it.
+* I referenced `AUTHORITY_MAX` without importing it.
+* I omitted `presentCall`, which `ALLOWED_DEF_KEYS` requires and which the registration-shape test pins. It now
+  labels a list as a `read` and a settle as a `write`, because **calling a queue inspection a write would
+  misrepresent the common case.**
+
+Four tool-count assertions said "exactly nine" and named the nine; they now say ten and name the ten. The
+comment beside one of them already recorded the lesson from a previous version — that a **count** was once the
+wrong property and the **message** was the right one. This time the count *was* the property.
+
+**7 new tests, 0 failures.**
+
 ## [0.25.0] — 2026-10-15
 
 **The chain is closed: dispatch → gate → queue → decision. The plugin builds a queue, and an escalation is a real entry an approver can find.**

package/README.md

@@ -39,7 +39,7 @@ So the cross-machine capability has to be built. This is that build.
                        ▼
    ┌──────────────────────────────────┐        ┌──────────────────────────┐
    │  Windows · DSH session           │        │  macOS · DSH session     │
-   │   w2m plugin (9 tools)           │        │   w2m plugin (9 tools)   │
+   │   w2m plugin (10 tools)          │        │   w2m plugin (10 tools)  │
    │        │                         │        │        │                 │
    │   Localside agent                │        │   Localside agent        │
    │    · three anchors               │        │    · three anchors       │
@@ -293,15 +293,16 @@ Then give it the relay URL in that profile's `cordis.patch.yml` — or leave
 >        got "@twinsearth/w2m-dsh-plugin/tools"), skipping
 > ```
 >
-> That is a silent failure by construction — the install looks right, nine tools appear, and
+> That is a silent failure by construction — the install looks right, ten tools appear, and
 > `w2m_status` reports `paired: false` and a null `rabbitUrl` because none of your values were ever
 > applied. It is not hypothetical: this row's expected name moved from the `/tools` subpath to the
 > package root in v0.5.4 (see `cordis.patch.yml`'s header for why), and every override that still
 > asserted the old subpath stopped being applied on upgrade. `id` already identifies the row, so the
 > safest `name:` is no `name:` at all.
 
-Restart DSH. You should see nine tools: `w2m_devices`, `w2m_run`, `w2m_wait`,
-`w2m_report`, `w2m_status`, `w2m_update`, `w2m_history`, `w2m_stats`, `w2m_memory`.
+Restart DSH. You should see ten tools: `w2m_devices`, `w2m_run`, `w2m_wait`,
+`w2m_report`, `w2m_status`, `w2m_update`, `w2m_history`, `w2m_stats`, `w2m_memory`,
+`w2m_approvals`.
 
 > `dsh` may not be on your `PATH`. On a packaged install it lives under
 > `resources/runtime/cli/bin/`. If `dsh` is not found, call it by path.
@@ -584,7 +585,7 @@ a product.
 |---|---|---|
 | relay | 142 | pairing, auth, SSE with `ready`-first and `seq` replay, leases with heartbeat renewal and expiry, dedupe, all **nine** aggregation states plus `pending`/`refused`, report generation, operator token, rate limiting, persistence and restart recovery, TLS, and the lost-offer recovery path |
 | agent | 129 | allow-list allow/deny, timeout, output truncation, exit codes, anchors on clean and dirty trees, four concurrent fingerprint computations, spool, a 40-case URL join matrix, cursor lifecycle across relay restarts, and the bundled-runtime resolver |
-| tools | 89 | nine tools registered, schemas, typed errors, polling, operator-token enforcement (no request is sent without it), sub-path endpoints, and the credential canaries |
+| tools | 89 | ten tools registered, schemas, typed errors, polling, operator-token enforcement (no request is sent without it), sub-path endpoints, and the credential canaries |
 | broadcast | 19 | exactly one executor, the rest `observing`; observers excluded from every aggregation step so a machine that did not run is never counted as agreeing |
 | claims | 19 | the document claims themselves: the version, the bundle patch, the tool list, every documented tarball URL, and the CHANGELOG's shape |
 | fleet-target | 37 | the composer's target selection, and the `executor_machine_id` narrowing that overrides it |
@@ -712,7 +713,7 @@ the plugin:
 
 ```bash
 node scripts/check-entrypoints.mjs   # imports lib/tools.js, the exact specifier cordis.patch.yml mounts
-node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 9 tools
+node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 10 tools
 ```
 
 **Not verified:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/src/plugin/tools.mjs

@@ -129,7 +129,7 @@ import { gateDispatch, approvalRequestFor, raiseApproval } from '../agent/permis
 // v0.24.0: the queue an escalation is raised into. Imported from `src/`, never from `scripts/` -- a
 // `src/` module reaching above itself breaks the published package (see CHANGELOG 0.23.0).
 import { createApprovalIndex } from '../agent/approval-index.mjs';
-import { isAuthorityLevel } from '../agent/authority.mjs';
+import { AUTHORITY_MAX, isAuthorityLevel } from '../agent/authority.mjs';
 // v0.6.0: the device keypair and the offer's key distribution (`docs/P2P-CRYPTO.md` §4). Imported
 // rather than reimplemented: the dispatcher and the executor have to derive the *same* keys, and two
 // implementations of a handshake are two chances to disagree about it.
@@ -193,7 +193,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 = '0.25.0';
+const PLUGIN_VERSION = '0.26.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -5088,6 +5088,131 @@ export async function apply(ctx, config = {}) {
       rawInput: {},
     }),
   }));
+
+  /**
+   * v0.25.0: the tool that makes the approval chain reachable by an operator.
+   *
+   * ## Why it reports refusals instead of hiding them
+   *
+   * Every row carries `may_act` and, when false, `why_not`. A list filtered down to what the caller may
+   * answer would be shorter and **would make the fleet look idle at the moment it is most blocked** — the
+   * work above their authority is exactly the work they most need to know exists.
+   *
+   * ## Why `actor_level` is a parameter and not read from config
+   *
+   * This machine's own `actorAuthorityLevel` says what it may *dispatch as*. An approver's level is a fact
+   * about the person answering, and a decision made on the dispatcher's level would let a machine approve its
+   * own escalations — which the index already refuses by name (`APPROVAL_SELF_APPROVAL`) when the ids match.
+   * Making it explicit keeps that refusal meaningful rather than incidental.
+   */
+  ctx.tools.register(defineTool({
+    name: 'w2m_approvals',
+    description:
+      'List and settle the dispatches that are waiting for an approver. A dispatch whose actor level is ' +
+      'exactly one band below what it needs is QUEUED rather than refused, and this is where that queue is ' +
+      'read and answered. Every row reports whether YOU may act on it and why not if you may not, so work ' +
+      'above your authority is visible rather than filtered away. Settling a request does not run the ' +
+      'dispatch: approval means the next attempt is allowed, not that anything already happened.',
+    parameters: {
+      action: {
+        type: 'string',
+        enum: ['list', 'approve', 'reject'],
+        description: 'list (default) shows the queue; approve and reject settle one request by approval_id.',
+        default: 'list',
+      },
+      approval_id: {
+        type: 'string',
+        description: 'Which request to settle. Required for approve and reject.',
+      },
+      actor_id: {
+        type: 'string',
+        description: 'Who is answering. Defaults to this machine\'s name; it is recorded on the decision, and it is what makes a self-approval refusable.',
+      },
+      actor_level: {
+        type: 'number',
+        description: 'The authority level of the person answering, 0..100. Required to approve or reject: an approver with no level cannot be placed relative to the request, and the index refuses rather than guessing one.',
+      },
+      include_settled: {
+        type: 'boolean',
+        description: 'Also show recently settled requests. They are kept briefly as receipts, so a supervisor returning to a busy queue can tell "already dealt with" from "never seen".',
+        default: false,
+      },
+    },
+    output: jsonOutput,
+    presentCall: (args) => ({
+      card: 'generic',
+      title: `w2m approvals ${typeof args?.action === 'string' ? args.action : 'list'}`,
+      // Only `approve` and `reject` change anything; a list is a read. Labelling the whole tool 'write' would
+      // make the common case -- looking at the queue -- read as an action.
+      kind: args?.action === 'approve' || args?.action === 'reject' ? 'write' : 'read',
+      rawInput: {},
+    }),
+    async execute(args, exec) {
+      throwIfAborted(exec?.signal);
+      const action = typeof args?.action === 'string' ? args.action : 'list';
+      const queue = approvalQueue();
+
+      if (action === 'approve' || action === 'reject') {
+        const approvalId = typeof args?.approval_id === 'string' ? args.approval_id.trim() : '';
+        if (approvalId === '') {
+          throw new W2MError('W2M_APPROVAL_ID', 'W2M_APPROVAL_ID: settling a request needs `approval_id`', {
+            hint: 'call w2m_approvals with action="list" to see the pending ids',
+          });
+        }
+        if (!isAuthorityLevel(args?.actor_level)) {
+          // Refused rather than defaulted, and refused HERE rather than left to the index, so the message can
+          // say what to do about it. A decision attributed to a level nobody supplied is a decision nobody
+          // can audit.
+          throw new W2MError(
+            'W2M_APPROVAL_LEVEL',
+            'W2M_APPROVAL_LEVEL: `actor_level` must be an integer 0..' + AUTHORITY_MAX + ' to settle a request',
+            { hint: 'an approver with no level cannot be placed relative to the request it is answering' },
+          );
+        }
+        const actor = { id: typeof args?.actor_id === 'string' && args.actor_id.trim() !== '' ? args.actor_id.trim() : cfg.machineName, level: args.actor_level };
+        const outcome = action === 'approve' ? 'approved' : 'rejected';
+        const result = queue.decide(approvalId, actor, outcome);
+        return JSON.stringify({
+          ok: result.ok === true,
+          action,
+          approval_id: approvalId,
+          settled: result.ok === true ? outcome : null,
+          reason_code: result.reason_code ?? null,
+          detail: result.detail ?? null,
+          acted_by: actor,
+          // Said every time, because a reader who assumes approval ran the dispatch will wait for a result
+          // that is never coming.
+          note: result.ok === true
+            ? 'the request is settled; the dispatch did not run and must be attempted again'
+            : 'the decision was refused; the request is unchanged and still waiting',
+        });
+      }
+
+      const actor = {
+        id: typeof args?.actor_id === 'string' && args.actor_id.trim() !== '' ? args.actor_id.trim() : cfg.machineName,
+        level: isAuthorityLevel(args?.actor_level) ? args.actor_level : null,
+      };
+      // An actor with no level still gets the list: knowing what is waiting does not require the authority to
+      // answer it, and a queue only its supervisors can see is a queue that stays full.
+      const rows = queue.listFor(
+        actor.level === null ? { id: actor.id, level: 0 } : actor,
+        { includeSettled: args?.include_settled === true },
+      );
+      const summary = queue.summary(actor.level === null ? { id: actor.id, level: 0 } : actor);
+      return JSON.stringify({
+        ok: true,
+        action: 'list',
+        as: actor,
+        level_known: actor.level !== null,
+        summary,
+        count: rows.length,
+        rows,
+        note: actor.level === null
+          ? 'no actor_level was supplied, so may_act is reported as if the level were 0: the queue is visible, but whether you may answer any of it is not known'
+          : 'may_act reflects the actor_level supplied',
+      });
+    },
+  }));
 }
 
 /**