@twinsearth/w2m-dsh-plugin 1.2.3 → 1.2.5

package/src/plugin/ask-store.mjs

@@ -0,0 +1,167 @@
+/**
+ * Open questions and their answers, on disk.
+ *
+ * ## Why a file, when the answer also arrives by chat
+ *
+ * An `await` that is answered while the asking process is being restarted has to survive the restart: the question is still
+ * the machine's question, and the answer is still an answer. Keeping the state in memory made the outcome depend on uptime.
+ *
+ * ## The two states that are easy to get wrong
+ *
+ * - **timeout is not final.** A late answer is recorded as `answered_after_timeout` rather than overwriting the timeout or
+ *   being dropped: the operator asked, something answered, and when it answered is a fact worth keeping.
+ * - **a settled question is never reopened.** `settle` on a decided ask returns the existing record with `settled: false`, so
+ *   two replies cannot race into one slot.
+ *
+ * Records are appended as JSON lines; `compact` rewrites atomically through a temporary file, which is the only writer of the
+ * whole file.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const ASK_STATE = Object.freeze(['open', 'answered', 'refused', 'timeout', 'answered_after_timeout']);
+
+/** The states that are still waiting for something. */
+export const OPEN_STATES = Object.freeze(['open']);
+
+/**
+ * @param {{now?: () => number, maxRecords?: number}} [options]
+ */
+export function createAskStore(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now();
+  const maxRecords = Number.isInteger(options.maxRecords) && options.maxRecords > 0 ? options.maxRecords : 2_000;
+  /** ask_id -> record */
+  const asks = new Map();
+  let seq = 0;
+  const file = typeof options.stateDir === 'string' && options.stateDir !== ''
+    ? join(options.stateDir, 'ask-store.jsonl')
+    : null;
+
+  /**
+   * Load whatever a previous process wrote. A malformed line is skipped rather than fatal: an unfinished write is the
+   * expected shape of a crash, and losing the whole store over the last line would be worse than losing the line.
+   */
+  if (file !== null) {
+    try {
+      const text = readFileSync(file, 'utf8');
+      for (const line of text.split('\n')) {
+        if (line.trim() === '') continue;
+        try { const record = JSON.parse(line); if (typeof record?.ask_id === 'string') asks.set(record.ask_id, record); } catch { /* one bad line */ }
+      }
+    } catch { /* no store yet */ }
+  }
+
+  /** Rewrite the file atomically: a reader never sees half a record. */
+  function persist() {
+    if (file === null) return;
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      const body = exportAll().map((record) => JSON.stringify(record)).join('\n') + '\n';
+      const temporary = file + '.tmp';
+      writeFileSync(temporary, body, 'utf8');
+      renameSync(temporary, file);
+    } catch { /* the in-memory store is still correct; persistence is best effort and says so by not throwing */ }
+  }
+
+  function openAsk(input = {}) {
+    const sessionId = typeof input.sessionId === 'string' && input.sessionId !== '' ? input.sessionId : null;
+    const messageId = typeof input.messageId === 'string' && input.messageId !== '' ? input.messageId : null;
+    if (sessionId === null || messageId === null) return { ok: false, code: 'ASK_BAD_INPUT' };
+    const askId = 'ask_' + (++seq) + '_' + now();
+    const record = {
+      ask_id: askId,
+      session_id: sessionId,
+      message_id: messageId,
+      thread_id: typeof input.threadId === 'string' ? input.threadId : null,
+      to: typeof input.to === 'string' ? input.to : null,
+      opened_at_ms: now(),
+      deadline_ms: now() + (Number.isFinite(input.timeoutMs) ? Math.max(1, input.timeoutMs) : 60_000),
+      state: 'open',
+      reply_message_id: null,
+      settled_at_ms: null,
+    };
+    asks.set(askId, record);
+    trim();
+    persist();
+    return { ok: true, ask: { ...record } };
+  }
+
+  function settle(askId, state, reply = {}) {
+    const record = asks.get(askId) ?? null;
+    if (record === null) return { ok: false, code: 'ASK_UNKNOWN', detail: { askId } };
+    if (!ASK_STATE.includes(state) || state === 'open') return { ok: false, code: 'ASK_BAD_STATE', detail: { state } };
+    if (record.state !== 'open' && record.state !== 'timeout') {
+      return { ok: true, ask: { ...record }, settled: false };
+    }
+    // A reply after the deadline is recorded as such: "answered late" and "answered" are different facts.
+    const late = record.state === 'timeout';
+    record.state = late ? 'answered_after_timeout' : state;
+    record.reply_message_id = typeof reply.messageId === 'string' ? reply.messageId : null;
+    record.settled_at_ms = now();
+    persist();
+    return { ok: true, ask: { ...record }, settled: true };
+  }
+
+  function expire(askId) {
+    const record = asks.get(askId) ?? null;
+    if (record === null) return { ok: false, code: 'ASK_UNKNOWN', detail: { askId } };
+    if (record.state !== 'open') return { ok: true, ask: { ...record }, expired: false };
+    record.state = 'timeout';
+    record.settled_at_ms = now();
+    persist();
+    return { ok: true, ask: { ...record }, expired: true };
+  }
+
+  function expireDue() {
+    const due = [];
+    for (const record of asks.values()) {
+      if (record.state === 'open' && record.deadline_ms <= now()) {
+        record.state = 'timeout';
+        record.settled_at_ms = now();
+        due.push(record.ask_id);
+      }
+    }
+    if (due.length > 0) persist();
+    return { ok: true, expired: due };
+  }
+
+  /** @param {{state?: string, sessionId?: string}} [filter] */
+  function list(filter = {}) {
+    const wanted = typeof filter.state === 'string' ? filter.state : null;
+    const session = typeof filter.sessionId === 'string' ? filter.sessionId : null;
+    return {
+      ok: true,
+      asks: [...asks.values()]
+        .filter((record) => (wanted === null || record.state === wanted) && (session === null || record.session_id === session))
+        .sort((a, b) => a.opened_at_ms - b.opened_at_ms)
+        .map((record) => ({ ...record })),
+    };
+  }
+
+  function restore(records) {
+    const restored = [];
+    for (const record of Array.isArray(records) ? records : []) {
+      const askId = typeof record?.ask_id === 'string' ? record.ask_id : null;
+      if (askId === null || !ASK_STATE.includes(record.state)) continue;
+      asks.set(askId, { ...record });
+      restored.push(askId);
+    }
+    persist();
+    return { ok: true, restored: restored.length };
+  }
+
+  /** The records that survive a restart, oldest first. */
+  function exportAll() {
+    return [...asks.values()].sort((a, b) => a.opened_at_ms - b.opened_at_ms).map((record) => ({ ...record }));
+  }
+
+  function trim() {
+    while (asks.size > maxRecords) {
+      const oldest = [...asks.values()].sort((a, b) => a.opened_at_ms - b.opened_at_ms)[0];
+      if (oldest === undefined) return;
+      asks.delete(oldest.ask_id);
+    }
+  }
+
+  return { openAsk, settle, expire, expireDue, list, restore, exportAll, _asks: asks };
+}

package/src/plugin/schema-spec.mjs

@@ -47,3 +47,36 @@ export function schemaProblems(schema, name = 'tool') {
     .map(({ path }) => ({ path: path + '.additionalProperties', why: 'an object parameter must state additionalProperties: true or false' }))
     .map((problem) => ({ ...problem, path: name + '.' + problem.path }));
 }
+
+
+/** Keys a parameter declaration may carry. Anything else is a typo or a parameter nested by accident. */
+const PARAM_KEYS = new Set(['type', 'items', 'description', 'default', 'required', 'enum', 'properties', 'additionalProperties', 'oneOf', 'anyOf']);
+
+/**
+ * Parameters nested inside another parameter's declaration.
+ *
+ * This is the shape that shipped in the 1.2.4 build: a parameter block pasted inside its predecessor. Every local schema check
+ * was green, and the real host refused the whole entry ("parameters.poll_ms.reducer_machine_id is not supported by the value
+ * schema DSL") -- because to JavaScript it is a perfectly good object.
+ *
+ * @param {Record<string, object>} parameters
+ * @param {string} [name]
+ * @returns {Array<{path: string, why: string}>}
+ */
+export function strayParameterProblems(parameters, name = 'tool') {
+  const problems = [];
+  for (const [key, decl] of Object.entries(parameters ?? {})) {
+    if (decl === null || typeof decl !== 'object') continue;
+    for (const nested of Object.keys(decl)) {
+      if (PARAM_KEYS.has(nested)) continue;
+      const looksLikeParameter = decl[nested] !== null && typeof decl[nested] === 'object' && typeof decl[nested].type === 'string';
+      if (looksLikeParameter) {
+        problems.push({
+          path: name + '.parameters.' + key + '.' + nested,
+          why: 'a parameter declaration is nested inside another parameter; move it to the parameters object',
+        });
+      }
+    }
+  }
+  return problems;
+}

package/src/plugin/task-graph.mjs

@@ -0,0 +1,147 @@
+/**
+ * The dependency graph of a fleet's tasks, as pure functions.
+ *
+ * ## Why this is separate from the relay's own validation
+ *
+ * The relay refuses a graph it cannot store (unknown prerequisite, cycle, a self-edge), but that is one call at one moment.
+ * A reader looking at a task board asks a different question: of the tasks I can see, which are READY, which are WAITING on
+ * something that is still running, and which are BLOCKED because a prerequisite failed or was cancelled? That question
+ * depends on the tasks' current states, so it is answered here, over whatever list the reader has.
+ *
+ * ## The rule that makes "blocked" honest
+ *
+ * A prerequisite that is missing from the visible list is treated as WAITING, never as ready: the list may be truncated by a
+ * limit, and inferring "no dependency" from "not in this page" is how a board would show work as available that is not.
+ */
+export const TASK_GRAPH_REFUSAL = Object.freeze({
+  UNKNOWN_NODE: 'GRAPH_UNKNOWN_NODE',
+  CYCLE: 'GRAPH_CYCLE',
+  BAD_NODE: 'GRAPH_BAD_NODE',
+});
+
+const DONE = new Set(['completed', 'done']);
+const FAILED = new Set(['failed', 'cancelled', 'refused']);
+// States that mean the task is already in flight. It is not 'ready': ready means work that can be STARTED.
+const ACTIVE = new Set(['running', 'queued', 'offered', 'preparing', 'finalizing']);
+
+/**
+ * @param {{nodes?: Array<{task_id?: string, depends_on?: string[]}>}} input
+ * @returns {{ok: true, nodes: Map<string, string[]>} | {ok: false, code: string, detail: object}}
+ */
+export function buildGraph({ nodes = [] } = {}) {
+  if (!Array.isArray(nodes)) return { ok: false, code: TASK_GRAPH_REFUSAL.BAD_NODE, detail: {} };
+  const map = new Map();
+  for (const node of nodes) {
+    const id = typeof node?.task_id === 'string' && node.task_id !== '' ? node.task_id : null;
+    if (id === null) return { ok: false, code: TASK_GRAPH_REFUSAL.BAD_NODE, detail: { node } };
+    const deps = Array.isArray(node.depends_on) ? node.depends_on.filter((dep) => typeof dep === 'string' && dep !== '') : [];
+    map.set(id, deps);
+  }
+  return { ok: true, nodes: map };
+}
+
+/**
+ * A stable topological order, or the cycle that prevents one.
+ *
+ * Ties are broken by id so the same graph renders in the same order on every machine -- a board that reshuffles between two
+ * reads looks like it is changing.
+ *
+ * @param {Map<string, string[]>} graph
+ * @returns {{ok: true, order: string[]} | {ok: false, code: string, detail: {cycle: string[]}}}
+ */
+export function topoOrder(graph) {
+  const indegree = new Map();
+  const dependents = new Map();
+  for (const id of graph.keys()) {
+    indegree.set(id, 0);
+    dependents.set(id, []);
+  }
+  for (const [id, deps] of graph.entries()) {
+    for (const dep of deps) {
+      // A prerequisite OUTSIDE this page is not an edge in it. The relay refuses an unknown prerequisite when the task is
+      // created, so a missing one here means the reader's list is truncated -- and treating that as a broken graph would
+      // make an ordinary limited read report a cycle.
+      if (!graph.has(dep)) continue;
+      indegree.set(id, (indegree.get(id) ?? 0) + 1);
+      if (!dependents.has(dep)) dependents.set(dep, []);
+      dependents.get(dep).push(id);
+    }
+  }
+  const ready = [...indegree.entries()].filter(([, count]) => count === 0).map(([id]) => id).sort();
+  const order = [];
+  while (ready.length > 0) {
+    const id = ready.shift();
+    order.push(id);
+    for (const next of (dependents.get(id) ?? []).slice().sort()) {
+      indegree.set(next, indegree.get(next) - 1);
+      if (indegree.get(next) === 0) { ready.push(next); ready.sort(); }
+    }
+  }
+  if (order.length !== graph.size) {
+    const remaining = [...graph.keys()].filter((id) => !order.includes(id));
+    return { ok: false, code: TASK_GRAPH_REFUSAL.CYCLE, detail: { cycle: remaining } };
+  }
+  return { ok: true, order };
+}
+
+/**
+ * Classify one task against the states of the tasks a reader can see.
+ *
+ * @param {{task_id: string, depends_on?: string[], status?: string, statuses?: Map<string, string>}} input
+ * @returns {'ready'|'waiting'|'blocked'|'done'|'active'|'unknown'}
+ */
+export function classifyTask({ task_id, depends_on = [], status = null, statuses = new Map() } = {}) {
+  if (typeof task_id !== 'string' || task_id === '') return 'unknown';
+  if (typeof status === 'string' && DONE.has(status)) return 'done';
+  if (typeof status === 'string' && FAILED.has(status)) return 'blocked';
+  let waiting = false;
+  for (const dep of depends_on) {
+    const depStatus = statuses.get(dep);
+    if (depStatus === undefined) { waiting = true; continue; }
+    if (FAILED.has(depStatus)) return 'blocked';
+    if (!DONE.has(depStatus)) waiting = true;
+  }
+  if (waiting) return 'waiting';
+  // In flight ONLY once its prerequisites are satisfied: a queued task behind a failed prerequisite is blocked, not active.
+  if (typeof status === 'string' && ACTIVE.has(status)) return 'active';
+  return 'ready';
+}
+
+/**
+ * The whole board, in one pass: every visible task classified, and the readies in dependency order.
+ *
+ * @param {{tasks?: Array<{task_id?: string, depends_on?: string[], status?: string}>}} input
+ * @returns {{ok: true, by_task: Record<string, string>, ready: string[], waiting: string[], blocked: string[], done: string[], active: string[], order: string[]} |
+ *           {ok: false, code: string, detail: object}}
+ */
+export function buildBoard({ tasks = [] } = {}) {
+  const built = buildGraph({ nodes: tasks });
+  if (built.ok !== true) return built;
+  const statuses = new Map();
+  for (const task of tasks) {
+    const id = typeof task?.task_id === 'string' ? task.task_id : null;
+    if (id !== null) statuses.set(id, typeof task?.status === 'string' ? task.status : 'unknown');
+  }
+  const byTask = {};
+  const buckets = { ready: [], waiting: [], blocked: [], done: [], active: [] };
+  for (const [id, deps] of built.nodes.entries()) {
+    const kind = classifyTask({ task_id: id, depends_on: deps, status: statuses.get(id), statuses });
+    byTask[id] = kind;
+    if (kind === 'done') buckets.done.push(id);
+    else if (kind === 'active') buckets.active.push(id);
+    else if (kind === 'blocked') buckets.blocked.push(id);
+    else if (kind === 'waiting') buckets.waiting.push(id);
+    else buckets.ready.push(id);
+  }
+  const order = topoOrder(built.nodes);
+  return {
+    ok: true,
+    by_task: byTask,
+    ready: buckets.ready.sort(),
+    waiting: buckets.waiting.sort(),
+    blocked: buckets.blocked.sort(),
+    done: buckets.done.sort(),
+    active: buckets.active.sort(),
+    order: order.ok === true ? order.order : [],
+  };
+}