@twinsearth/w2m-dsh-plugin 1.2.6 → 1.3.0

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.6';
+const PLUGIN_VERSION = '1.3.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3771,6 +3773,15 @@ export async function apply(ctx, config = {}) {
         items: { type: 'string' },
         description: 'Which terminal conditions justify another attempt: expired, failed, partial, timeout. Omit to never retry.',
       },
+      depends_on: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Task ids this task waits for. The relay will not dispatch it until every dependency has settled; then it is offered automatically.',
+      },
+      assignee: {
+        type: 'string',
+        description: 'Machine id that must execute this task. An assignee is a restriction: no other machine is offered the work, and an unknown id is refused by name.',
+      },
     },
     output: jsonOutput,
     async execute(args, exec) {
@@ -4181,6 +4192,11 @@ export async function apply(ctx, config = {}) {
         // v1.2.4: the retry policy travels only when the caller asked for one, so a default dispatch stays byte-identical.
         ...(Number.isInteger(args?.max_attempts) && args.max_attempts > 1 ? { max_attempts: args.max_attempts } : {}),
         ...(Array.isArray(args?.retry_on) && args.retry_on.length > 0 ? { retry_on: args.retry_on } : {}),
+        // v1.2.7: graph edges and assignment travel only when declared, so a default dispatch stays byte-identical.
+        ...(Array.isArray(args?.depends_on) && args.depends_on.filter((id) => typeof id === 'string' && id !== '').length > 0
+          ? { depends_on: args.depends_on.filter((id) => typeof id === 'string' && id !== '') }
+          : {}),
+        ...(typeof args?.assignee === 'string' && args.assignee.trim() !== '' ? { assignee: args.assignee.trim() } : {}),
         created_by: cfg.machineName,
         // Only sent for broadcast; the relay ignores it otherwise, and the validation above already
         // refused the combination, so this cannot silently mean nothing.
@@ -4515,13 +4531,26 @@ 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;
-      const rawMachines = Array.isArray(aggregate.detail?.machines) ? aggregate.detail.machines : [];
-      const mapResults = rawMachines.map((machine) => {
+      // 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)
+        ? aggregate.detail.machines
+        : (Array.isArray(aggregate.machines) ? aggregate.machines : []);
+      // v1.2.7: only a machine that actually reported can claim a shard. An expired lease still carries an index, and counting
+      // it as "produced" would make a partial run look complete -- the exact failure the expected-index check exists to prevent.
+      const reportedMachines = rawMachines.filter((machine) => (machine?.envelope ?? machine?.result ?? null) !== null || typeof machine?.blob_sha256 === 'string' || typeof machine?.stdout_head === 'string' || Number.isFinite(machine?.stdout_bytes) || (typeof machine?.status === 'string' && machine.status !== '' && Number.isFinite(machine?.exit_code)));
+      const mapResults = reportedMachines.map((machine) => {
         const envelope = machine?.envelope ?? machine?.result ?? null;
-        const blobSha = typeof envelope?.blob_sha256 === 'string' ? envelope.blob_sha256 : null;
-        const inline = typeof envelope?.stdout_head === 'string' && envelope.stdout_head !== '' ? envelope.stdout_head : null;
+        const blobSha = typeof envelope?.blob_sha256 === 'string' ? envelope.blob_sha256
+          : (typeof machine?.blob_sha256 === 'string' ? machine.blob_sha256 : null);
+        const inline = typeof envelope?.stdout_head === 'string' && envelope.stdout_head !== '' ? envelope.stdout_head
+          : (typeof machine?.stdout_head === 'string' && machine.stdout_head !== '' ? machine.stdout_head : null);
         return {
           machine_id: machine?.machine_id ?? null,
+          // v1.2.7: the shard this result belongs to, so the reduce plan can tell "complete" from "the rest never reported".
+          index: Number.isInteger(machine?.index) ? machine.index : (Number.isInteger(envelope?.index) ? envelope.index : null),
           mode: blobSha === null ? 'inline' : 'blob',
           ...(inline === null ? {} : { stdout: inline }),
           ...(blobSha === null ? {} : { blob_sha256: blobSha }),
@@ -4529,7 +4558,12 @@ export async function apply(ctx, config = {}) {
       });
       const anyBlob = mapResults.some((entry) => entry.mode === 'blob');
       const reduce = anyBlob && reducerMachineId !== null
-        ? buildReducePlan({ results: mapResults, reducerMachineId })
+        ? buildReducePlan({
+            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,
+          })
         : null;
       const dataflowDegraded = reduce !== null && reduce.ok !== true;
 
@@ -4546,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 ?? [],
@@ -5571,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,
           });
         }
@@ -6601,6 +6642,10 @@ export async function apply(ctx, config = {}) {
         type: 'string',
         description: 'For send/ask: replay protection. A retry with the same key returns the first message instead of posting the same sentence twice.',
       },
+      reply_state: {
+        type: 'string',
+        description: 'For send/ask: answer the turn as "answered" or "refused". A refusal is a state the awaiter reads, not a wording it has to guess from.',
+      },
       timeout_ms: { type: 'number', description: 'For await: how long to wait before reporting a timeout (default 60000, capped at 300000). A timeout is a value, not an error.' },
     },
     output: jsonOutput,
@@ -6610,6 +6655,8 @@ export async function apply(ctx, config = {}) {
       const action = typeof args?.action === 'string' ? args.action : 'list';
       const sessionId = typeof args?.session_id === 'string' ? args.session_id.trim() : '';
       if (sessionId === '') throw new W2MError('W2M_CHAT_SESSION', 'W2M_CHAT_SESSION: session_id is required', { hint: 'chat is scoped to a conversation' });
+      // v1.2.7: expire stale turns on every entry, so `asks` reports the truth after downtime.
+      askStore.expireDue();
       if (action === 'asks') {
         // The persisted questions for this conversation, in the states they are in. A read, so it needs no relay.
         return JSON.stringify({ ok: true, action, session_id: sessionId, ...askStore.list({ sessionId }) });
@@ -6655,26 +6702,84 @@ export async function apply(ctx, config = {}) {
       if (typeof args?.reply_to === 'string' && args.reply_to.trim() !== '') addressing.reply_to = args.reply_to.trim();
 
       if (action === 'await') {
-        // Waiting for an ANSWER is a state machine, and a timeout is a value the caller reads rather than an exception
-        // that loses the question. The question stays in the flow, so it can still be answered later.
+        // v1.2.7: waiting is a persisted turn, not a poll loop.
+        //
+        // The question is written to the ask store when it is ASKED; await attaches to that record, so a restart in between
+        // does not lose the question or turn a late answer into silence. The event stream is tried first (the reply arrives
+        // when it is posted, not up to a poll interval later), and polling remains the fallback for a relay or proxy that
+        // cannot stream -- an old relay must not break awaiting.
         const target = typeof args?.reply_to === 'string' ? args.reply_to.trim() : '';
-        if (target === '') throw new W2MError('W2M_CHAT_AWAIT', 'W2M_CHAT_AWAIT: reply_to is required for await', { hint: 'pass the message_id returned by ask' });
+        if (target === '') throw new W2MError('W2M_CHAT_AWAIT', 'W2M_CHAT_AWAIT: reply_to is required for await', { hint: 'pass reply_to: <message_id of the question>' });
         const timeoutMs = Number.isFinite(args?.timeout_ms) ? Math.max(1000, Math.min(args.timeout_ms, 300000)) : 60000;
         const startedAt = Date.now();
+        askStore.expireDue();
+        let turn = askStore.list({ sessionId }).asks.find((ask) => (ask.state === 'open' || ask.state === 'timeout') && ask.message_id === target) ?? null;
+        if (turn === null) {
+          const opened = askStore.openAsk({ sessionId, messageId: target, timeoutMs });
+          turn = opened.ok === true ? opened.ask : null;
+        }
+        const ownMachineId = cfg.machineId ?? null;
+        const findReply = async () => {
+          const listed = await request({ rabbitUrl, token, signal: exec?.signal, method: 'GET', pathname: '/v1/fleet/messages', query: { session_id: sessionId, limit: 200 } });
+          const rows = Array.isArray(listed?.json?.messages) ? listed.json.messages : [];
+          return rows.find((message) => message.reply_to === target && message.machine_id !== ownMachineId) ?? null;
+        };
+        const finish = (replyMessage, via) => {
+          const verdict = replyMessage?.reply_state === 'refused' ? 'refused' : 'answered';
+          if (turn !== null) askStore.settle(turn.ask_id, verdict, { messageId: replyMessage?.message_id ?? null });
+          const recorded = turn === null ? null : (askStore.list({ sessionId }).asks.find((ask) => ask.ask_id === turn.ask_id) ?? null);
+          return JSON.stringify({ ok: true, action, state: verdict, via, reply_to: target, reply: replyMessage, replies: replyMessage === null ? [] : [replyMessage], ask: recorded });
+        };
+        // 1) stream first -- and RE-subscribe while the budget remains: a dropped stream is not the end of the wait.
+        let emptyStreams = 0;
+        while (Date.now() - startedAt < timeoutMs) {
+          const remaining = timeoutMs - (Date.now() - startedAt);
+          const controller = new AbortController();
+          const timer = setTimeout(() => controller.abort(), Math.min(remaining, 30000));
+          let reachable = false;
+          let gotEvent = false;
+          try {
+            const streamUrl = joinUrl(rabbitUrl, '/v1/fleet/messages/stream') + '?session_id=' + encodeURIComponent(sessionId);
+            const response = await fetch(streamUrl, { headers: { authorization: 'Bearer ' + token }, signal: controller.signal });
+            if (response.ok === true && response.body !== null) {
+              reachable = true;
+              const reader = response.body.getReader();
+              const decoder = new TextDecoder();
+              let buffer = '';
+              for (;;) {
+                const { value, done } = await reader.read();
+                if (done === true) break;
+                buffer += decoder.decode(value, { stream: true });
+                const parts = buffer.split('\n\n');
+                buffer = parts.pop() ?? '';
+                for (const part of parts) {
+                  const line = part.split('\n').find((entry) => entry.startsWith('data: '));
+                  if (line === undefined) continue;
+                  gotEvent = true;
+                  const reply = await findReply();
+                  if (reply !== null) return finish(reply, 'stream');
+                }
+              }
+            }
+          } catch (error) {
+            if (error?.name === 'AbortError' && Date.now() - startedAt >= timeoutMs) break;
+          } finally { clearTimeout(timer); }
+          if (reachable !== true) break; // a relay that will not stream at all: polling is the contract
+          emptyStreams = gotEvent === true ? 0 : emptyStreams + 1;
+          if (emptyStreams >= 2) break; // two streams that end immediately will not deliver this reply
+          await new Promise((resolve) => { setTimeout(resolve, 100); });
+        }
+        // 2) polling fallback
         for (;;) {
           throwIfAborted(exec?.signal);
-          const reply = await request({ rabbitUrl, token, signal: exec?.signal, method: 'GET', pathname: '/v1/fleet/messages', query: { session_id: sessionId, reply_to: target, limit: '10' } });
-          const found = Array.isArray(reply?.json?.messages) ? reply.json.messages : [];
-          if (found.length > 0) {
-            for (const open of askStore.list({ sessionId }).asks) {
-              if (open.state === 'open' && open.message_id === target) askStore.settle(open.ask_id, 'answered', { messageId: found[0]?.message_id ?? null });
-            }
-            return JSON.stringify({ ok: true, action, state: 'answered', reply_to: target, replies: found });
-          }
+          const reply = await findReply();
+          if (reply !== null) return finish(reply, 'poll');
           if (Date.now() - startedAt >= timeoutMs) {
-            return JSON.stringify({ ok: true, action, state: 'timeout', reply_to: target, waited_ms: Date.now() - startedAt, hint: 'the question is still in the flow and can be answered later' });
+            if (turn !== null) askStore.expire(turn.ask_id);
+            const recorded = turn === null ? null : (askStore.list({ sessionId }).asks.find((ask) => ask.ask_id === turn.ask_id) ?? null);
+            return JSON.stringify({ ok: true, action, state: 'timeout', reply_to: target, waited_ms: Date.now() - startedAt, ask: recorded, hint: 'the question stays in the flow and can still be answered later' });
           }
-          await new Promise((resolve) => { setTimeout(resolve, 1500); });
+          await new Promise((resolve) => { setTimeout(resolve, 1000); });
         }
       }
       if (action === 'send' || action === 'ask') {
@@ -6699,6 +6804,7 @@ export async function apply(ctx, config = {}) {
           ...addressing,
           ...(mentions.length === 0 ? {} : { mentions }),
           ...(typeof args?.idempotency_key === 'string' && args.idempotency_key.trim() !== '' ? { idempotency_key: args.idempotency_key.trim() } : { idempotency_key: 'spool-' + Date.now() + '-' + Math.random().toString(36).slice(2) }),
+            ...(typeof args?.reply_state === 'string' && (args.reply_state === 'answered' || args.reply_state === 'refused') ? { reply_state: args.reply_state } : {}),
         };
         let posted = null;
         try {
@@ -6715,9 +6821,23 @@ export async function apply(ctx, config = {}) {
           const code = posted?.json?.error?.code ?? posted?.error?.code ?? 'W2M_CHAT_SEND';
           throw new W2MError('W2M_CHAT_SEND', code + ': the message was refused', { reason_code: code, hint: 'quota, size and non-text each need a different answer' });
         }
+        let ask = null;
+        if (action === 'ask' && posted.json?.message?.message_id !== undefined) {
+          // v1.2.7: the question becomes a turn on disk the moment it is asked, so a later await (in this process or after a
+          // restart) settles the same record instead of opening a second one.
+          const opened = askStore.openAsk({
+            sessionId,
+            messageId: posted.json.message.message_id,
+            threadId: typeof args?.thread_id === 'string' ? args.thread_id : null,
+            to: typeof args?.to === 'string' ? args.to : null,
+            timeoutMs: Number.isFinite(args?.timeout_ms) ? args.timeout_ms : 60000,
+          });
+          if (opened.ok === true) ask = opened.ask;
+        }
         return JSON.stringify({
           ok: true, action, message: posted.json?.message ?? null, message_id: posted.json?.message?.message_id ?? null,
           encrypted: sealed !== null && sealed.ok === true,
+          ...(ask === null ? {} : { ask }),
           ...(posted.json?.deduped === true ? { deduped: true } : {}),
         });
       }
@@ -7030,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:
@@ -7069,6 +7249,11 @@ export async function apply(ctx, config = {}) {
           mode: row?.mode ?? null,
           status: row?.status ?? null,
           cancelled: row?.cancelled === true,
+          // v1.2.7: graph facts travel with each row so the board and the scheduler cannot disagree.
+          depends_on: Array.isArray(row?.depends_on) ? row.depends_on : [],
+          assignee: row?.assignee ?? null,
+          waiting_on: Array.isArray(row?.waiting_on) ? row.waiting_on : [],
+          lease_states: row?.lease_states ?? {},
           machines: Array.isArray(row?.leases)
             ? row.leases.map((lease) => lease?.machine_id ?? null).filter((id) => typeof id === "string")
             : [],