@twinsearth/w2m-dsh-plugin 1.2.1 → 1.2.3

package/src/plugin/tools.mjs

@@ -183,6 +183,10 @@ import {
 // v1.1.17 chat: the host route behind the composer's fleet-chat panel. The relay side and the
 // `w2m_chat` tool shipped first; this is the browser-facing half that was still missing.
 import { registerChatRoutes } from './fleet-chat-route.mjs';
+import { createFleetCouncil, fleetCouncilThread } from './council-fleet.mjs';
+import { renderMemoryView } from './memory-view.mjs';
+import { schemaProblems } 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
 // module header for why a discovered device is a candidate to *ask* and never an authorisation.
 import { createDiscoverySource } from './mdns-discover.mjs';
@@ -220,7 +224,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.1';
+const PLUGIN_VERSION = '1.2.3';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -553,6 +557,15 @@ function createDefineTool(real) {
       parameters[key] = normaliseParameter(name, key, decl);
     }
 
+    // v1.2.3: DSH refuses an object parameter that does not state additionalProperties explicitly, and it
+    // refuses it at MOUNT time -- in the profile of whoever installed the build. That is the failure the packed
+    // artifact hit in a real host while this repository tests were green, so the rule is enforced here, where
+    // every tool already passes through.
+    const schemaProblemsFound = schemaProblems({ type: 'object', properties: parameters, additionalProperties: false }, name);
+    if (schemaProblemsFound.length > 0) {
+      throw new TypeError(schemaProblemsFound.map((problem) => problem.path + ': ' + problem.why).join('; '));
+    }
+
     return { ...definition, parameters };
   };
 
@@ -3390,6 +3403,10 @@ export async function apply(ctx, config = {}) {
    */
   const councilSessions = createCouncilSessions();
 
+  /** v1.2.2: the machine-wide council. Ballots arrive as chat messages, so this is state + arithmetic; the transport is
+   * the fleet chat itself (thread `council-<id>`), which already carries `to` / `thread_id` / `reply_to` since 1.2.1. */
+  const fleetCouncil = createFleetCouncil({});
+
   // v0.6.1: the two browser routes behind the composer's target control. Additive and optional: a
   // host without `connection.fetch` still gets every tool, and `w2m_status` reports the absence  -   // which is the honest place for it, since a host that has no Connection at all is simply not a web
   // composition and does not need a warning on every headless run.
@@ -5234,7 +5251,7 @@ export async function apply(ctx, config = {}) {
        */
       action: {
         type: 'string',
-        enum: ['read', 'publish', 'pull', 'latest', 'diff', 'merge'],
+        enum: ['read', 'publish', 'pull', 'latest', 'diff', 'merge', 'append'],
         description:
           'read (default) = answer from memory. publish = upload the curated collective memory '
           + '(`fleet-memory.md`) to the relay as a content-addressed blob and return its SHA-256. latest = ask the '
@@ -5252,6 +5269,19 @@ export async function apply(ctx, config = {}) {
           + 'relay but belongs to another fleet is reported as not found, exactly like a hash that was never '
           + 'stored -- a distinguishable refusal would confirm to a prober which hashes this relay holds.',
       },
+      records: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'For action="append": one append-only record per string. Appending is the unit of change, so two machines ' +
+          'can add records without one overwriting the other document.',
+      },
+      if_revision: {
+        type: 'number',
+        description:
+          'For action="append": the revision you read. A stale value is refused with 409 and the records you have not ' +
+          'read, because applying it on top of something you never saw is a silent overwrite.',
+      },
       scope: {
         type: 'string',
         enum: ['local', 'fleet'],
@@ -5340,6 +5370,64 @@ export async function apply(ctx, config = {}) {
     async execute(args, exec) {
       throwIfAborted(exec?.signal);
 
+      /**
+       * v1.2.2: append records to the shared memory under compare-and-swap.
+       *
+       * A 409 is returned AS-IS, with the revision and what the caller has not read. Retrying here would turn a visible
+       * conflict into a silent overwrite, which is the whole reason the relay keeps a revision instead of merging.
+       */
+      if (typeof args?.action === 'string' && args.action === 'append') {
+        const doc = typeof args?.scope === 'string' && args.scope.trim() !== '' ? args.scope.trim() : 'fleet';
+        const incoming = Array.isArray(args?.records)
+          ? args.records
+          : (typeof args?.records === 'string' ? [args.records] : []);
+        const records = incoming.filter((entry) => typeof entry === 'string' && entry.trim() !== '');
+        if (records.length === 0) {
+          throw new W2MError('W2M_MEMORY_APPEND', 'W2M_MEMORY_APPEND: records is required for append', {
+            hint: 'pass records: ["a fact the fleet should keep", ...]',
+          });
+        }
+        const appendUrl = cfg.rabbitUrl ?? null;
+        if (appendUrl === null) {
+          throw new W2MError('W2M_NO_RELAY', 'W2M_NO_RELAY: no relay is configured, so shared memory cannot be written', {
+            hint: 'set rabbitUrl in the profile patch',
+          });
+        }
+        const appendToken = await resolveToken(cfg);
+        if (appendToken === null) {
+          throw new W2MError('W2M_NO_TOKEN', 'W2M_NO_TOKEN: this machine has no device token, so shared memory cannot be written', {
+            hint: 'pair this machine first, then retry',
+          });
+        }
+        const appendBody = { records };
+        if (Number.isInteger(args?.if_revision)) appendBody.if_revision = args.if_revision;
+        const appended = await request({
+          rabbitUrl: appendUrl,
+          token: appendToken,
+          method: 'PUT',
+          pathname: '/v1/fleet/memory/' + encodeURIComponent(doc),
+          body: appendBody,
+          signal: exec?.signal,
+        });
+        if (appended?.ok !== true) {
+          return JSON.stringify({
+            ok: false,
+            action: 'append',
+            doc,
+            status: appended?.status ?? 0,
+            code: appended?.json?.error?.code ?? appended?.error?.code ?? 'W2M_MEMORY_APPEND',
+            detail: appended?.json?.detail ?? null,
+          });
+        }
+        return JSON.stringify({
+          ok: true,
+          action: 'append',
+          doc,
+          revision: appended.json?.revision ?? null,
+          appended: appended.json?.appended ?? 0,
+        });
+      }
+
       /**
        * v1.0.7 (#1c): publish the collective memory as a content-addressed blob.
        *
@@ -6096,6 +6184,7 @@ export async function apply(ctx, config = {}) {
           truncated: current.truncated,
           status_tally: tally(current.records),
           records: current.records,
+          view: renderMemoryView(current.records),
           ...(previous === null
             ? {}
             : {
@@ -6414,6 +6503,44 @@ export async function apply(ctx, config = {}) {
     },
   }));
 
+  /**
+   * v1.2.2: structured intents -- the deterministic half of "say it in words, run it on the machine".
+   *
+   * The caller is the model, and it turns language into one of a CLOSED set of intents; this tool maps that intent to an
+   * allow-listed argv or refuses it by name. Free text is deliberately not interpreted here: a remote machine runs an
+   * allow-list, and a model inventing a command on its behalf is exactly what the list exists to stop.
+   */
+  ctx.tools.register(defineTool({
+    name: 'w2m_intent',
+    description:
+      'Map a structured intent to an allow-listed command. Actions: run-tests, node-version, git-status, git-head, ' +
+      'fleet-facts, shard-probe. Unknown actions and unknown parameters are refused by name rather than guessed, and a ' +
+      'command the machine allow-list does not carry is refused with the list it checked.',
+    parameters: {
+      action: { type: 'string', description: 'The catalog action; call with action:"list" to read the catalog.' },
+      params: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Action parameters, for example { n: 3 } for shard-probe.',
+      },
+    },
+    output: jsonOutput,
+    presentCall: (args) => ({ card: 'generic', title: 'w2m intent ' + (typeof args?.action === 'string' ? args.action : '?'), kind: 'read', rawInput: {} }),
+    async execute(args, exec) {
+      throwIfAborted(exec?.signal);
+      const action = typeof args?.action === 'string' ? args.action.trim() : '';
+      if (action === '' || action === 'list') {
+        return JSON.stringify({ ok: true, action: 'list', intents: listIntents() });
+      }
+      const resolved = resolveIntent({ action, params: args?.params }, { allowedCommands: cfg.allowedCommands ?? null });
+      if (resolved.ok !== true) {
+        return JSON.stringify({ ok: false, action, code: resolved.code, detail: resolved.detail ?? null, hint: resolved.hint });
+      }
+      return JSON.stringify({ ok: true, action, argv: resolved.argv, command: resolved.command, risk: resolved.risk });
+    },
+  }));
+
+
   /**
    * v0.37.0: the eleventh tool -- a question put to a council, and the outcome read back with its dissent.
    *
@@ -6443,7 +6570,7 @@ export async function apply(ctx, config = {}) {
     parameters: {
       action: {
         type: 'string',
-        enum: ['open', 'advance', 'assign', 'argue', 'vote', 'decide', 'record', 'state', 'decision', 'list'],
+        enum: ['open', 'advance', 'assign', 'argue', 'vote', 'decide', 'record', 'state', 'decision', 'list', 'fleet-open', 'fleet-vote', 'fleet-decide', 'fleet-state', 'fleet-list'],
         description: 'What to do. "open" starts a council, "state" reports one mid-flight, "decision" reads a sealed one back with its dissent.',
         default: 'state',
       },
@@ -6474,6 +6601,59 @@ export async function apply(ctx, config = {}) {
       const action = typeof args?.action === 'string' ? args.action : 'state';
       const id = typeof args?.council_id === 'string' ? args.council_id : null;
 
+      // v1.2.2: the FLEET council. Same decision rule as the single-machine one (reproducible weights, a tie is a
+      // refusal); the difference is transport -- ballots are chat messages on `council-<id>`, so every machine can read
+      // the same ballots and recount to the same outcome.
+      if (typeof action === 'string' && action.startsWith('fleet-')) {
+        const threadId = fleetCouncilThread(id);
+        if (action === 'fleet-open') {
+          const opened = fleetCouncil.open({ councilId: id, question: typeof args?.question === 'string' ? args.question : '', openedByMachineId: 'local' });
+          return JSON.stringify({ ok: opened.ok, action, council_id: id, thread_id: threadId, reason_code: opened.code ?? null, council: opened.council ?? null });
+        }
+        if (action === 'fleet-vote') {
+          const voted = fleetCouncil.vote({
+            councilId: id,
+            machineId: typeof args?.participant === 'string' && args.participant !== '' ? args.participant : 'local',
+            choice: args?.choice,
+            reason: args?.reason ?? null,
+            authority: args?.authority ?? null,
+            reputation: args?.reputation ?? null,
+          });
+          return JSON.stringify({ ok: voted.ok, action, council_id: id, thread_id: threadId, reason_code: voted.code ?? null, council: voted.council ?? null });
+        }
+        if (action === 'fleet-decide') {
+          const decided = fleetCouncil.decide({ councilId: id });
+          // The decision travels as an append-only memory record: a decision that exists only in one process memory
+          // is a decision nobody can audit later. Writing it is best-effort -- the outcome is returned either way and
+          // `trail` says which happened, rather than implying the record exists when it does not.
+          let trail = 'not-written';
+          if (decided.ok === true && decided.council?.decision != null) {
+            try {
+              const trailUrl = cfg?.rabbitUrl ?? null;
+              const trailToken = trailUrl === null ? null : await resolveToken(cfg);
+              if (trailUrl !== null && typeof trailToken === 'string' && trailToken !== '') {
+                const decision = decided.council.decision;
+                const line = 'council ' + String(id) + ': ' + String(decision.choice) + ' (weight ' + String(decision.weight) + ', '
+                  + String(decided.council.ballots.length) + ' ballot(s))';
+                const appended = await request({
+                  rabbitUrl: trailUrl, token: trailToken, method: 'PUT',
+                  pathname: '/v1/fleet/memory/fleet', body: { records: [line] }, signal: exec?.signal,
+                });
+                trail = appended?.ok === true ? 'appended' : 'refused';
+              }
+            } catch {
+              trail = 'error';
+            }
+          }
+          return JSON.stringify({ ok: decided.ok, action, council_id: id, thread_id: threadId, reason_code: decided.code ?? null, detail: decided.detail ?? null, trail, council: decided.council ?? null });
+        }
+        if (action === 'fleet-list') {
+          return JSON.stringify({ ok: true, action, ...fleetCouncil.list() });
+        }
+        const read = fleetCouncil.state({ councilId: id });
+        return JSON.stringify({ ok: read.ok, action, council_id: id, thread_id: threadId, reason_code: read.code ?? null, council: read.council ?? null });
+      }
+
       if (action === 'list') {
         return JSON.stringify({ ok: true, action, ...councilSessions.ids(), phases: PHASES, roles: [...ROLES] });
       }

package/src/relay/fleet-memory.mjs

@@ -0,0 +1,85 @@
+/**
+ * Shared fleet memory: an append-only record log with compare-and-swap.
+ *
+ * ## What this is for
+ *
+ * The fleet memory was read/publish only. Two machines writing meant last-writer-wins over a whole document, so a record
+ * added by one could vanish because the other had an older copy. Here the unit of change is a RECORD and the guard is a
+ * revision number: a writer says which revision it saw, and a stale one is refused with the current revision and a diff
+ * summary instead of being applied on top of something it never read.
+ *
+ * ## Refusals are values
+ *
+ * `REVISION_CONFLICT` is a normal answer, not an error: the caller re-reads, decides, and retries. Automatic retry is
+ * deliberately NOT implemented here -- retrying in the transport would turn a visible conflict into a silent overwrite.
+ */
+export class FleetMemoryConflict extends Error {}
+
+/**
+ * @param {{now?: () => number, maxRecords?: number}} [options]
+ */
+export function createFleetMemory(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now();
+  const maxRecords = Number.isInteger(options.maxRecords) && options.maxRecords > 0 ? options.maxRecords : 10_000;
+  /** doc -> { revision, records: [{ at_ms, author_machine_id, text }] } */
+  const docs = new Map();
+
+  const stateOf = (doc) => docs.get(doc) ?? { revision: 0, records: [] };
+
+  /**
+   * @param {string} doc
+   * @returns {{ok: true, revision: number, records: object[], count: number}}
+   */
+  function get(doc) {
+    const state = stateOf(doc);
+    return { ok: true, revision: state.revision, records: state.records.map((r) => ({ ...r })), count: state.records.length };
+  }
+
+  /**
+   * Append records, guarded by the revision the caller saw.
+   *
+   * @param {{doc: string, if_revision?: number|null, author_machine_id: string, records: string[]}} input
+   * @returns {{ok: true, revision: number, appended: number} |
+   *           {ok: false, code: string, detail?: object}}
+   */
+  function append(input) {
+    const doc = typeof input?.doc === 'string' && input.doc.trim() !== '' ? input.doc.trim() : null;
+    if (doc === null) return { ok: false, code: 'BAD_DOC' };
+    const author = typeof input?.author_machine_id === 'string' && input.author_machine_id !== '' ? input.author_machine_id : null;
+    if (author === null) return { ok: false, code: 'BAD_AUTHOR' };
+    const incoming = Array.isArray(input?.records) ? input.records : null;
+    if (incoming === null) return { ok: false, code: 'NO_RECORDS' };
+    const texts = incoming.filter((r) => typeof r === 'string' && r.trim() !== '');
+    if (texts.length === 0) return { ok: false, code: 'NO_RECORDS' };
+    if (texts.length !== incoming.length) return { ok: false, code: 'BAD_RECORD' };
+
+    const state = stateOf(doc);
+    const seen = Number.isInteger(input?.if_revision) ? input.if_revision : null;
+    if (seen !== null && seen !== state.revision) {
+      // The diff is what the caller needs to decide: how far ahead the document is, and what it has not read yet.
+      const missing = state.records.slice(Math.max(0, seen < 0 ? 0 : seen));
+      return {
+        ok: false,
+        code: 'REVISION_CONFLICT',
+        detail: {
+          if_revision: seen,
+          revision: state.revision,
+          behind_by: state.revision - seen,
+          unread_records: missing.length,
+          sample: missing.slice(0, 3).map((r) => ({ author: r.author_machine_id, text: r.text.slice(0, 80) })),
+        },
+      };
+    }
+    if (state.records.length + texts.length > maxRecords) {
+      return { ok: false, code: 'MEMORY_FULL', detail: { count: state.records.length, maxRecords } };
+    }
+
+    const at = now();
+    const added = texts.map((text) => ({ at_ms: at, author_machine_id: author, text }));
+    const next = { revision: state.revision + 1, records: [...state.records, ...added] };
+    docs.set(doc, next);
+    return { ok: true, revision: next.revision, appended: added.length };
+  }
+
+  return { get, append, _docs: docs };
+}

package/src/relay/server.mjs

@@ -22,7 +22,8 @@ import {
   RabbitState,
   rfc3339,
 } from './state.mjs';
-import { createFleetMessages } from './fleet-messages.mjs';
+import { createFleetMessages } from './fleet-messages.mjs';
+import { createFleetMemory } from './fleet-memory.mjs';
 import { createJoinChallenges } from './join-challenge.mjs';
 import { createAdmission } from './admission.mjs';
 import { Persistence } from './persistence.mjs';
@@ -1045,6 +1046,7 @@ export class RelayServer {
     // speak as another. The refusal codes from the store are passed through unchanged (FLEET_QUOTA_EXCEEDED included)
     // because a caller that cannot tell "too big" from "over quota" from "not text" cannot tell the operator what to do.
     this.fleetMessages ??= createFleetMessages({ now: () => this.state.nowMs() });
+    this.fleetMemory ??= createFleetMemory({ now: () => this.state.nowMs() });
 
     if (method === 'POST' && path === '/v1/fleet/messages') {
       const body = takeJson();
@@ -1115,6 +1117,37 @@ export class RelayServer {
       });
     }
 
+    // v1.2.2: shared memory writes. Compare-and-swap on a revision, because two machines appending to one document is
+    // otherwise last-writer-wins over the whole thing -- a record one machine added would vanish because the other had an
+    // older copy. A stale writer gets 409 and the records it has not read; it is NOT retried here, because retrying in
+    // the transport turns a visible conflict into a silent overwrite.
+    if (path.startsWith('/v1/fleet/memory/')) {
+      const doc = decodeURIComponent(path.slice('/v1/fleet/memory/'.length));
+      if (doc === '') throw new ProtocolError('BAD_REQUEST', 'memory doc is required', { method, path });
+      this.fleetMemory ??= createFleetMemory({ now: () => this.state.nowMs() });
+      if (method === 'GET') {
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...this.fleetMemory.get(doc) });
+      }
+      if (method === 'PUT') {
+        const body = takeJson();
+        const appended = this.fleetMemory.append({
+          doc,
+          if_revision: Number.isInteger(body.if_revision) ? body.if_revision : null,
+          author_machine_id: device.machine_id,
+          records: Array.isArray(body.records) ? body.records : (typeof body.text === 'string' ? [body.text] : []),
+        });
+        if (appended.ok !== true) {
+          const status = appended.code === 'REVISION_CONFLICT' ? 409 : 400;
+          return sendJson(res, status, {
+            protocol_version: PROTOCOL_VERSION, ok: false,
+            error: { code: appended.code }, detail: appended.detail ?? null,
+          });
+        }
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...appended });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'memory accepts GET or PUT', { method, path });
+    }
+
     throw new ProtocolError('NOT_FOUND', `no route for ${method} ${path}`, { method, path });
   }