@twinsearth/w2m-dsh-plugin 1.2.7 → 1.3.1

package/src/agent/agent.mjs

@@ -23,8 +23,9 @@
 
 import { Readable } from 'node:stream';
 import { access, constants as fsConstants } from 'node:fs/promises';
-import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { randomUUID , sign as signBytes } from 'node:crypto';
 
 import {
@@ -3027,6 +3028,58 @@ export function createAgent(options) {
       // never allowed to ask for, and the plugin's pre-flight refuses the dispatch as a whole for the
       // same reason. The refusal names the stage index, because "this chain is not allowed" is not
       // actionable without knowing which stage.
+      /**
+       * v1.2.10: a reduce task carries the artifacts it consumes, and the machine fetches them BEFORE the reduce command runs.
+       *
+       * The list is the caller's completeness decision (the relay validated its shape, never its truth), and the bytes are
+       * content-addressed, so the fetch verifies nothing less than the hash already did. A failed fetch refuses the whole task:
+       * a reduce that ran on half the inputs would produce a confident wrong answer, which is the failure this feature exists to
+       * make impossible.
+       */
+      let reduceEnv = null;
+      if (Array.isArray(offer.reduce_inputs) && offer.reduce_inputs.length > 0) {
+        try {
+          const inputDir = mkdtempSync(join(tmpdir(), 'w2m-reduce-'));
+          const manifest = [];
+          for (const artifact of offer.reduce_inputs) {
+            const response = await fetch(rabbitUrl + '/v1/fleet/blobs/' + encodeURIComponent(artifact.sha256), {
+              headers: token() ? { authorization: 'Bearer ' + token() } : {},
+            });
+            if (response.status !== 200) {
+              throw new Error('blob ' + artifact.sha256 + ' -> HTTP ' + response.status);
+            }
+            const body = Buffer.from(await response.arrayBuffer());
+            const file = join(inputDir, String(artifact.machine_id).replace(/[^A-Za-z0-9._-]/g, '_') + '.bin');
+            writeFileSync(file, body);
+            manifest.push({ machine_id: artifact.machine_id, sha256: artifact.sha256, bytes: body.length, file });
+          }
+          const manifestPath = join(inputDir, 'manifest.json');
+          writeFileSync(manifestPath, JSON.stringify({ reduce_of: offer.reduce_of ?? null, inputs: manifest }, null, 2));
+          reduceEnv = {
+            W2M_REDUCE_INPUTS_DIR: inputDir,
+            W2M_REDUCE_MANIFEST: manifestPath,
+            W2M_REDUCE_OF: String(offer.reduce_of ?? ''),
+          };
+        } catch (error) {
+          log('warn', offer.task_id + ': reduce input fetch failed', { error: error?.message ?? String(error) });
+          await finish({
+            offer,
+            cwdRel,
+            commandArgv,
+            anchorsBefore,
+            anchorsAfter: null,
+            execution: null,
+            status: 'refused',
+            refusalReason: 'REDUCE_INPUT_FETCH_FAILED',
+            warnings,
+            startedAt,
+            endedAt: new Date().toISOString(),
+            protocolViolations: ['reduce inputs could not be fetched: ' + (error?.message ?? String(error))],
+          });
+          return;
+        }
+      }
+
       for (const stage of plannedStages) {
         const stageAllowed = matchAllowedCommand(stage.command_argv, allowedCommands);
         if (stageAllowed.allowed) continue;
@@ -3120,6 +3173,7 @@ export function createAgent(options) {
           W2M_MODE: String(offer.mode ?? ''),
           W2M_MACHINE_ID: String(offer.machine_id ?? ''),
           W2M_MACHINE_NAME: String(offer.machine_name ?? ''),
+          ...(reduceEnv ?? {}),
         };
         const ran = await runArgv(stage.command_argv, {
           cwd: stageCwdOutcome.cwd,

package/src/plugin/merge-hint.mjs

@@ -0,0 +1,35 @@
+/**
+ * The merge hint: what a reader of a shared memory document should do about a conflict.
+ *
+ * A 409 from the memory CAS already carries `behind_by`, `unread_records` and a sample. The reader still has to decide what
+ * "behind by 3" means for the thing they are about to write. This turns those numbers into a named next step -- re-read, compare,
+ * then append with the current revision -- and never merges automatically: an automatic merge would write records the caller has
+ * not seen. Pure: it reads the refusal the relay already sent.
+ */
+export const MERGE_UP_TO_DATE = 'up-to-date';
+export const MERGE_RE_READ = 're-read-then-append';
+
+/**
+ * @param {{conflict?: object|null}} input `conflict` is the 409 detail: { behind_by, unread_records, sample }.
+ * @returns {{state: string, behind_by: number, unread: number, sample_count: number, next: string}}
+ */
+export function renderMergeHint(input = {}) {
+  const conflict = input.conflict ?? null;
+  if (conflict === null || typeof conflict !== 'object') {
+    return { state: MERGE_UP_TO_DATE, behind_by: 0, unread: 0, sample_count: 0, next: 'append normally' };
+  }
+  const behindBy = Number.isInteger(conflict.behind_by) && conflict.behind_by > 0 ? conflict.behind_by : 0;
+  const unread = Array.isArray(conflict.unread_records) ? conflict.unread_records.length
+    : (Number.isInteger(conflict.unread) && conflict.unread > 0 ? conflict.unread : 0);
+  const sample = Array.isArray(conflict.sample) ? conflict.sample : [];
+  if (behindBy === 0 && unread === 0) {
+    return { state: MERGE_UP_TO_DATE, behind_by: 0, unread: 0, sample_count: 0, next: 'append normally' };
+  }
+  return {
+    state: MERGE_RE_READ,
+    behind_by: behindBy,
+    unread,
+    sample_count: sample.length,
+    next: 're-read the document, compare the records listed here, then append with the current revision -- do not merge unseen records',
+  };
+}

package/src/plugin/tools.mjs

@@ -186,6 +186,7 @@ import {
 import { registerChatRoutes } from './fleet-chat-route.mjs';
 import { createFleetCouncil, fleetCouncilThread } from './council-fleet.mjs';
 import { renderMemoryView } from './memory-view.mjs';
+import { renderMergeHint } from './merge-hint.mjs';
 import { buildBoard } from './task-graph.mjs';
 import { verifyEnvelopeSignature } from '../util/envelope-signature.mjs';
 import { createAskStore } from './ask-store.mjs';
@@ -233,6 +234,7 @@ async function writeChatSpool(stateDir, entries) {
 }
 
 import { buildReducePlan } from '../util/dataflow.mjs';
+import { suggestReduce } from '../util/reduce-suggestion.mjs';
 import { schemaProblems, strayParameterProblems } from './schema-spec.mjs';
 import { listIntents, resolveIntent } from './intents.mjs';
 // v0.7.0: the LAN hint layer. Imported here and used in exactly one place (`w2m_devices`); see the
@@ -272,7 +274,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.2.7';
+const PLUGIN_VERSION = '1.3.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -4529,6 +4531,8 @@ export async function apply(ctx, config = {}) {
       const reducerMachineId = typeof args?.reducer_machine_id === 'string' && args.reducer_machine_id.trim() !== ''
         ? args.reducer_machine_id.trim()
         : null;
+      // v1.2.9: the task's own shard count is the completeness contract, used by both the plan and the suggestion.
+      const expectedIndexTotal = Number.isInteger(body?.task?.index_total) ? body.task.index_total : null;
       // v1.2.7: the relay publishes machine facts directly on the aggregate; `detail.machines` is a test/report shape that the
       // real /v1/tasks response does not carry. Reading only the latter made the reduce plan silently unreachable in production.
       const rawMachines = Array.isArray(aggregate.detail?.machines)
@@ -4558,7 +4562,7 @@ export async function apply(ctx, config = {}) {
             results: mapResults,
             reducerMachineId,
             // v1.2.7: the task's own shard count is the completeness contract; absent it, the old "just what arrived" plan stands.
-            expectedIndexTotal: Number.isInteger(body?.task?.index_total) ? body.task.index_total : null,
+            expectedIndexTotal,
           })
         : null;
       const dataflowDegraded = reduce !== null && reduce.ok !== true;
@@ -4576,6 +4580,11 @@ export async function apply(ctx, config = {}) {
           ...(badSignature > 0 ? { signature_warning: 'bad_signature' } : {}),
           ...(badSignature === 0 && unsigned > 0 ? { signature_warning: 'unsigned' } : {}),
           ...(reduce === null ? {} : { reduce }),
+          /**
+           * v1.2.9: complete-or-not, the candidate reducers, and the literal next step. This is a SUGGESTION: the tool does not
+           * dispatch the reduce, because choosing a machine to run a command is the caller's decision everywhere else in the fleet.
+           */
+          reduce_suggestion: suggestReduce({ machines: rawMachines, reducerMachineId, expectedIndexTotal }),
           ...(dataflowDegraded ? { dataflow_degraded: true } : {}),
           counts: aggregate.detail?.counts ?? null,
           differences: aggregate.detail?.differences ?? [],
@@ -5601,6 +5610,8 @@ export async function apply(ctx, config = {}) {
             doc,
             status: appended?.status ?? 0,
             code: appended?.json?.error?.code ?? appended?.error?.code ?? 'W2M_MEMORY_APPEND',
+        // v1.2.11: turn the 409's numbers into the next step a reader can actually take.
+        merge_hint: renderMergeHint({ conflict: appended?.json?.detail ?? appended?.json?.error?.detail ?? null }),
             detail: appended?.json?.detail ?? null,
           });
         }
@@ -7139,6 +7150,66 @@ export async function apply(ctx, config = {}) {
     },
   }));
 
+
+  ctx.tools.register(defineTool({
+    name: 'w2m_reduce',
+    description:
+      'Dispatch a reduce task for a finished map task. Refuses unless every declared shard reported as a blob and the named reducer is a machine that reported: the relay never picks a reducer, and this tool never invents one.',
+    parameters: {
+      task_id: { type: 'string', required: true, description: 'The map task whose results are being reduced.' },
+      reducer_machine_id: { type: 'string', required: true, description: 'The machine that must run the reduce; it must have reported a shard.' },
+      reduce_argv: { type: 'array', items: { type: 'string' }, required: true, description: 'The reduce command as argv, run with W2M_REDUCE_MANIFEST set.' },
+      timeout_ms: { type: 'number', description: 'Wall-clock budget for the reduce task (default 300000, cap 3600000).' },
+      cwd_rel: { type: 'string', description: 'Working directory relative to the project (default ".").' },
+    },
+    output: jsonOutput,
+    presentCall: (args) => ({ card: 'generic', title: 'w2m reduce ' + (typeof args?.task_id === 'string' ? args.task_id : ''), kind: 'write', rawInput: {} }),
+    async execute(args, exec) {
+      throwIfAborted(exec?.signal);
+      const base = requireRabbit(cfg);
+      const taskId = typeof args?.task_id === 'string' ? args.task_id.trim() : '';
+      const reducerMachineId = typeof args?.reducer_machine_id === 'string' ? args.reducer_machine_id.trim() : '';
+      const reduceArgv = Array.isArray(args?.reduce_argv) ? args.reduce_argv.filter((part) => typeof part === 'string' && part !== '') : [];
+      if (taskId === '') throw new W2MError('W2M_REDUCE_TASK', 'W2M_REDUCE_TASK: task_id is required');
+      if (reducerMachineId === '') throw new W2MError('W2M_REDUCE_REDUCER', 'W2M_REDUCE_REDUCER: reducer_machine_id is required');
+      if (reduceArgv.length === 0) throw new W2MError('W2M_REDUCE_ARGV', 'W2M_REDUCE_ARGV: reduce_argv must be a non-empty string array');
+      const deviceToken = await resolveToken(cfg);
+      const operatorToken = requireOperatorToken(cfg);
+      const viewed = await request({ rabbitUrl: base, token: deviceToken, signal: exec?.signal, method: 'GET', pathname: '/v1/tasks/' + encodeURIComponent(taskId) });
+      if (viewed?.ok !== true) throw new W2MError('W2M_REDUCE_READ', 'W2M_REDUCE_READ: the relay refused the task read');
+      const body = viewed.json ?? {};
+      const aggregate = body.aggregate ?? {};
+      const machines = Array.isArray(aggregate.machines) ? aggregate.machines : (Array.isArray(aggregate.detail?.machines) ? aggregate.detail.machines : []);
+      const expectedIndexTotal = Number.isInteger(body?.task?.index_total) ? body.task.index_total : null;
+      const suggestion = suggestReduce({ machines, reducerMachineId, expectedIndexTotal });
+      if (suggestion.ready !== true) {
+        const code = suggestion?.plan?.code ?? 'NOT_READY';
+        throw new W2MError('W2M_REDUCE_NOT_READY', 'W2M_REDUCE_NOT_READY: ' + code + ' -- refusing to reduce over incomplete data', {
+          reason_code: code, detail: suggestion?.plan?.detail ?? null, missing: suggestion?.missing ?? [],
+        });
+      }
+      const inputs = suggestion.plan.inputs.filter((entry) => entry.mode === 'blob').map((entry) => ({ machine_id: entry.machine_id, sha256: entry.sha256 }));
+      if (inputs.length !== suggestion.plan.inputs.length) throw new W2MError('W2M_REDUCE_INLINE_INPUT', 'W2M_REDUCE_INLINE_INPUT: an inline result cannot be carried to another machine');
+      const timeoutMs = Math.min(Math.max(Number.isFinite(args?.timeout_ms) ? Math.floor(args.timeout_ms) : 300_000, 1_000), 3_600_000);
+      const dispatched = await request({
+        rabbitUrl: base, token: operatorToken, signal: exec?.signal, method: 'POST', pathname: '/v1/task',
+        body: {
+          mode: 'broadcast', executor_machine_id: reducerMachineId, command_argv: reduceArgv,
+          cwd_rel: typeof args?.cwd_rel === 'string' && args.cwd_rel !== '' ? args.cwd_rel : '.',
+          index_total: 1, timeout_ms: timeoutMs, write: false,
+          requirements: { toolchain: {}, platform: [] },
+          compare_policy: { strip_ansi: true, normalize_crlf: true, strip_trailing_blank_lines: true, redact: [] },
+          reduce_of: taskId, reduce_inputs: inputs,
+        },
+      });
+      if (dispatched?.ok !== true) {
+        const code = dispatched?.json?.error?.code ?? dispatched?.error?.code ?? 'W2M_REDUCE_DISPATCH';
+        throw new W2MError('W2M_REDUCE_DISPATCH', 'W2M_REDUCE_DISPATCH: ' + code + ': the reduce was refused', { reason_code: code });
+      }
+      return JSON.stringify({ ok: true, action: 'reduce', reduce_task_id: dispatched.json?.task_id ?? null, reduce_of: taskId, reducer_machine_id: reducerMachineId, inputs: inputs.length });
+    },
+  }));
+
   ctx.tools.register(defineTool({
     name: 'w2m_tasks',
     description: