create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/fleet-conversation-route.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// WP-4 (docs/fleet-session-lists-hub-search-2026-11-01.html §5 D-6 exception, §6.2, §6.3, §8 WP-4,
+// §9 S-13): the PE conversations route SPEC, and its registration into WP-1's FLEET_LIST_ROUTES map.
+//
+// Mirrors lib/fleet-session-list-routes.js (WP-2): the spec is plain data and lib/fleet-session-lists.js
+// `fleetRouted()` owns every hard rule (D-2 fan-out, D-4 dedup, D-6 envelope, D-8 stale-if-error,
+// D-10 provenance). This module only says, for `GET /api/conversations`:
+//   - `rowsKey: null` — the LOCAL body IS the array today (`listReadResponse`, api-prompts.js:747-756),
+//     so the fleet body is the D-6 EXCEPTION `{ conversations: merged, machines, partial }` and the
+//     non-fleet body is left byte-for-byte alone;
+//   - how a row is keyed for dedup;
+//   - D-9's conversation order (last_message_at desc, then id asc);
+//   - D-8 eligibility (`lastGood: true`, unfiltered = no `search`).
+//
+// Registering is a module-load side effect (`registerFleetConversationRoute()` at the bottom) so
+// api-prompts.js only has to `require()` this file before it reads the map.
+
+const { FLEET_LIST_ROUTES } = require('./fleet-session-lists');
+
+const CONVERSATIONS_ROUTE = 'GET /api/conversations';
+
+/** The route's own default limit (`/conversations?limit=100` is what the PE pane asks for). */
+const DEFAULT_CONVERSATIONS_LIMIT = 100;
+
+/**
+ * D-4 for this route: the conversation row id. A conversation row carries it as `session_id`
+ * (canonical list) or `ctm_session_id`; a row with neither is unkeyed and never merged.
+ */
+function conversationRowId(row) {
+  return String((row && (row.session_id || row.ctm_session_id)) || '');
+}
+
+/** `last_message_at` is an ISO string on the canonical query, and may be an epoch number; a value
+ *  that parses to neither sorts LAST (never mistaken for "just now"). */
+function conversationTime(value) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : NaN;
+  return Date.parse(String(value == null ? '' : value));
+}
+
+/** D-9: last_message_at desc (NaN last), then `ctm_session_id || session_id` asc — the merge order
+ *  equals single-DB order, and it is total, so the merged list is deterministic across machines. */
+function compareConversations(a, b) {
+  const ta = conversationTime(a && a.last_message_at);
+  const tb = conversationTime(b && b.last_message_at);
+  const aMissing = Number.isNaN(ta);
+  const bMissing = Number.isNaN(tb);
+  if (aMissing !== bMissing) return aMissing ? 1 : -1;
+  if (!aMissing && ta !== tb) return tb - ta;
+  const ia = String((a && (a.ctm_session_id || a.session_id)) || '');
+  const ib = String((b && (b.ctm_session_id || b.session_id)) || '');
+  return ia < ib ? -1 : ia > ib ? 1 : 0;
+}
+
+/**
+ * §6.2/§6.3: GET /api/conversations.
+ *
+ * `limitOf` is the route's own limit rule — `parseInt(limit || '100', 10)`, defaulting to 100 for a
+ * missing/unparseable/non-positive value.
+ *
+ * `lastGood: true` + `unfiltered` (no `search`) = D-8's cache eligibility: an unfiltered
+ * conversation list is the same query for every caller, so a down box's last good rows may be
+ * re-served as `stale`. A search result is query-keyed and never cached.
+ */
+const conversationsFleetSpec = {
+  rowsKey: null,
+  fleetRowsKey: 'conversations',
+  rowId: conversationRowId,
+  limitOf: (url) => {
+    const n = parseInt(url.searchParams.get('limit') || String(DEFAULT_CONVERSATIONS_LIMIT), 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_CONVERSATIONS_LIMIT;
+  },
+  select: (rows, { limit }) => (Array.isArray(rows) ? rows.slice() : []).sort(compareConversations).slice(0, limit),
+  lastGood: true,
+  unfiltered: (url) => !url.searchParams.get('search'),
+};
+
+/**
+ * Fill FLEET_LIST_ROUTES (§6.2/§7). Idempotent — assigning the same spec object again is a no-op —
+ * and called once at module load, so a plain `require()` of this file is enough for the router
+ * wiring and for the §7 census gate (tests-integration/fleet-session-lists-census.test.js).
+ */
+function registerFleetConversationRoute() {
+  FLEET_LIST_ROUTES[CONVERSATIONS_ROUTE] = conversationsFleetSpec;
+  return FLEET_LIST_ROUTES;
+}
+
+registerFleetConversationRoute();
+
+module.exports = {
+  CONVERSATIONS_ROUTE,
+  DEFAULT_CONVERSATIONS_LIMIT,
+  conversationRowId,
+  compareConversations,
+  conversationsFleetSpec,
+  registerFleetConversationRoute,
+};

package/template/coding-task-manager/lib/fleet-fanout.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// S-6 (docs/fleet-session-lists-hub-search-2026-11-01.html §5 D-5, §8 WP-1): the ONE scatter-gather
+// shared by the agent pool search (lib/session-context-locator.js `searchMembers`) and the fleet
+// session lists (lib/fleet-session-lists.js). A LEAF module on purpose: it requires nothing, so
+// both callers can depend on it without forming a module cycle (dependency-lint `cycles: 0`).
+
+/**
+ * S-6: the scatter-gather. ONE request per member, all in flight at once, under ONE deadline.
+ * Every member starts `timeout`; the fan-out settles at `d.deadlineMs` or as soon as every member
+ * has answered, whichever is first, and snapshots its three outputs on settle — a member that
+ * answers late changes nothing. A thrown/rejected `forward` is a per-member `error`, never thrown.
+ *
+ * @param {object[]} machines  dialable machine rows
+ * @param {{pathname:string, search:string, parse:(result)=>({error:true,status:string}|{error:false,rows:object[],body:object})}} request
+ * @param {{forward:Function, setTimeoutFn:Function, clearTimeoutFn:Function, deadlineMs:number, label:(machine)=>string}} d
+ *   `label` names a member (callers pass lib/session-context-locator.js `machineLabel`; it is a
+ *   parameter so this leaf module requires nothing and no module cycle can form).
+ * @returns {Promise<{lists:object[], statuses:Map<string,string>, counts:Map<string,number>}>} never rejects
+ */
+function fanOutMembers(machines, request, d) {
+  const list = Array.isArray(machines) ? machines : [];
+  const { pathname, search, parse } = request || {};
+  const label = typeof d.label === 'function' ? d.label : ((machine) => String((machine && machine.instanceId) || ''));
+  const statuses = new Map();
+  const counts = new Map();
+  const lists = [];
+  if (!list.length) return Promise.resolve({ lists, statuses, counts });
+  return new Promise((resolve) => {
+    let settled = false;
+    let pending = list.length;
+    let timer = null;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      if (timer) d.clearTimeoutFn(timer);
+      // Snapshot: a late answer after the deadline must not rewrite what we already reported.
+      resolve({ lists: lists.slice(), statuses: new Map(statuses), counts: new Map(counts) });
+    };
+    timer = d.setTimeoutFn(() => settle(), d.deadlineMs);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+    // Every member answering before the deadline ends the fan-out at once (no gratuitous 2 s wait).
+    const note = () => {
+      pending -= 1;
+      if (pending === 0) settle();
+    };
+    for (const machine of list) {
+      statuses.set(machine.instanceId, 'timeout');
+      Promise.resolve()
+        .then(() => d.forward({ machine, pathname, search, method: 'GET' }))
+        .then((result) => {
+          const parsed = parse(result);
+          if (parsed.error) {
+            statuses.set(machine.instanceId, parsed.status);
+            note();
+            return;
+          }
+          statuses.set(machine.instanceId, 'ok');
+          counts.set(machine.instanceId, parsed.rows.length);
+          lists.push({
+            machine_id: String(machine.instanceId || ''),
+            machine_name: label(machine),
+            owner: false, // D-10/R-7: a fanned-out member is never the owner of the caller's copy
+            rows: parsed.rows,
+            body: parsed.body,
+          });
+          note();
+        })
+        .catch(() => {
+          /* HANDLE: one member's failure is a per-machine status, never thrown past the caller */
+          statuses.set(machine.instanceId, 'error');
+          note();
+        });
+    }
+  });
+}
+
+module.exports = { fanOutMembers };