slidemind 0.3.19 → 0.4.0

package/src/workspace/tasks.mjs

@@ -0,0 +1,507 @@
+// Durable, content-bound tasks (contracts.md §4).
+//
+// A task is a request the agent leaves for the human ("approve this plan",
+// "review this preview") and the human's answer, bound to the EXACT content it
+// was asked about (`subject.hash`). It lives in the deck
+// (`state/workspace-tasks.json`) and survives agent exit, daemon restart and a
+// closed terminal; it never starts or resumes an agent.
+//
+// Every mutation runs inside `runDeckOperation` (operations.mjs): one deck lock,
+// one in-process queue, one durable intent. The response transaction is
+//
+//   write intent → invoke the authoritative action → write evidence
+//   → mark completed → clear intent
+//
+// so a crash in the middle is found by the next writer. Recovery completes the
+// task ONLY when the caller can show evidence for that exact operation and
+// subject (`verify`); otherwise it stays pending. Nobody manufactures an
+// approval from a half-written transaction.
+
+import { createHash, randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolveWorkspace, statePath } from "../lib/deck-paths.mjs";
+import { readOperationIntent, runDeckOperation } from "./operations.mjs";
+import { coded, writeJsonAtomic } from "./registry.mjs";
+
+export const TASKS_FILE = "workspace-tasks.json";
+export const SCHEMA_VERSION = 1;
+export const RESPONSE_KIND = "task-response";
+
+/** kind → allowed actions; pinned by test/fixtures/workspace/task/cases.json. */
+export const KINDS = {
+  "plan-edit": ["done"],
+  "plan-approval": ["approve", "request-changes"],
+  "preview-review": ["approve", "comment"],
+  "sync-conflict": ["resolve"],
+};
+export const STATUSES = ["pending", "completed", "superseded", "cancelled"];
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SHA = /^sha256:[a-f0-9]{64}$/;
+const ACTION = /^[a-z][a-z0-9-]{0,31}$/;
+const ID_LIKE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const MAX_COMMENT = 16 * 1024;
+
+const nowIso = () => new Date().toISOString();
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const notifier = new EventEmitter();
+notifier.setMaxListeners(0);
+
+// ---------------------------------------------------------------------------
+// subject hash
+// ---------------------------------------------------------------------------
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (isObj(value)) {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** `sha256:<hex>` of a string (UTF-8 bytes) or of a JSON value (canonical, sorted keys). */
+export function taskSubject(content) {
+  const bytes = typeof content === "string" || Buffer.isBuffer(content) ? content : canonical(content);
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+// ---------------------------------------------------------------------------
+// validation (the fixtures' bad-* files are the oracle)
+// ---------------------------------------------------------------------------
+
+function invalid(msg) {
+  return coded("validation_failed", msg);
+}
+
+export function validateTask(task) {
+  if (!isObj(task)) throw invalid("task is not an object");
+  if (!UUID.test(task.id ?? "")) throw invalid(`task id ${JSON.stringify(task.id)} is not a UUID`);
+  if (!KINDS[task.kind]) throw invalid(`unknown task kind ${JSON.stringify(task.kind)}`);
+  if (typeof task.adapterId !== "string" || !ID_LIKE.test(task.adapterId)) throw invalid("adapterId is malformed");
+  if (!isObj(task.subject) || !SHA.test(task.subject.hash ?? "")) throw invalid("subject.hash is not sha256:<hex>");
+  if (task.subject.remoteETag !== null && typeof task.subject.remoteETag !== "string") throw invalid("subject.remoteETag must be null or a string");
+  if (task.subject.requestedHash !== undefined && !SHA.test(task.subject.requestedHash)) throw invalid("subject.requestedHash is not sha256:<hex>");
+  if (task.subject.followed !== undefined && (!Array.isArray(task.subject.followed) || !task.subject.followed.every((h) => SHA.test(h)))) throw invalid("subject.followed is not a list of sha256:<hex>");
+  if (!STATUSES.includes(task.status)) throw invalid(`unknown task status ${JSON.stringify(task.status)}`);
+  for (const k of ["createdAt", "updatedAt"]) {
+    if (typeof task[k] !== "string" || Number.isNaN(Date.parse(task[k]))) throw invalid(`${k} is not a date`);
+  }
+  if (!Array.isArray(task.actions) || task.actions.length === 0) throw invalid("actions is empty");
+  for (const a of task.actions) {
+    if (!KINDS[task.kind].includes(a)) throw invalid(`action ${JSON.stringify(a)} is not one of ${task.kind}'s`);
+  }
+  if (task.response !== null) {
+    const r = task.response;
+    if (!isObj(r) || !UUID.test(r.operationId ?? "") || !task.actions.includes(r.action)) throw invalid("response is malformed");
+    if (typeof r.at !== "string" || typeof r.actor !== "string") throw invalid("response is malformed");
+  }
+  if (task.evidence !== null && (!isObj(task.evidence) || !SHA.test(task.evidence.hash ?? ""))) {
+    throw invalid("evidence must be null or carry the exact content hash");
+  }
+  if (task.status === "completed" && (!task.response || !task.evidence)) throw invalid("a completed task needs response and evidence");
+  if (task.pickedUpAt !== undefined && (typeof task.pickedUpAt !== "string" || Number.isNaN(Date.parse(task.pickedUpAt)))) throw invalid("pickedUpAt is not a date");
+  return task;
+}
+
+export function validateStore(store) {
+  if (!isObj(store) || store.schemaVersion !== SCHEMA_VERSION || !Array.isArray(store.tasks)) {
+    throw coded("recovery_required", `${TASKS_FILE} is not a v${SCHEMA_VERSION} task store; inspect it before mutating this deck.`);
+  }
+  store.tasks.forEach(validateTask);
+  return store;
+}
+
+function validateRespondRequest(req) {
+  if (!isObj(req)) throw invalid("respond request is not an object");
+  if (!UUID.test(req.operationId ?? "")) throw invalid("operationId is not a UUID");
+  if (!SHA.test(req.expectedHash ?? "")) throw invalid("expectedHash is not sha256:<hex>");
+  if (typeof req.action !== "string" || !ACTION.test(req.action)) throw invalid("action is malformed");
+  if (req.payload !== undefined && req.payload !== null && !isObj(req.payload)) throw invalid("payload must be an object");
+  if (typeof req.actor !== "string" || !req.actor) throw invalid("actor is required");
+  const comment = req.payload?.comment;
+  if (comment !== undefined && comment !== null && (typeof comment !== "string" || comment.length > MAX_COMMENT)) {
+    throw invalid("comment must be a string under 16 KiB");
+  }
+  return req;
+}
+
+// ---------------------------------------------------------------------------
+// store
+// ---------------------------------------------------------------------------
+
+const ws = (deckRoot) => resolveWorkspace(path.resolve(deckRoot));
+export const tasksPath = (deckRoot) => statePath(ws(deckRoot), TASKS_FILE);
+
+function readStore(deckRoot) {
+  let raw;
+  try {
+    raw = fs.readFileSync(tasksPath(deckRoot), "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return { schemaVersion: SCHEMA_VERSION, receiptsSince: nowIso(), tasks: [] };
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw coded("recovery_required", `${TASKS_FILE} is unreadable; it is kept on disk for recovery.`);
+  }
+  return adoptReceipts(validateStore(parsed));
+}
+
+/**
+ * Receipts (`pickedUpAt`) arrived with the gates asking through the workspace.
+ * A store written before them holds answers an agent already acted on through
+ * `tasks wait` / `tasks get`: they count as received, or the first gate run
+ * would hand last week's comments over again. In memory on every read; the
+ * next write persists it with `receiptsSince`, after which a missing receipt
+ * means exactly "nobody has this answer yet".
+ */
+function adoptReceipts(store) {
+  if (store.receiptsSince) return store;
+  store.receiptsSince = nowIso();
+  for (const t of store.tasks) if (t.status === "completed" && !t.pickedUpAt) t.pickedUpAt = t.updatedAt;
+  return store;
+}
+
+function writeStore(deckRoot, store) {
+  const file = tasksPath(deckRoot);
+  // a brand-new store starts with receipts on: every answer in it is tracked
+  store.receiptsSince ??= nowIso();
+  writeJsonAtomic(file, validateStore(store));
+  notifier.emit(file);
+}
+
+export function listTasks(deckRoot, { status = null } = {}) {
+  const tasks = readStore(deckRoot).tasks;
+  return (status ? tasks.filter((t) => t.status === status) : tasks).slice().sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+export function getTask(deckRoot, id) {
+  return readStore(deckRoot).tasks.find((t) => t.id === id) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// recovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Settle an interrupted response transaction. Runs as `runDeckOperation`'s
+ * recoverer, so it is synchronous and answers truthy only when the deck is
+ * consistent again.
+ *
+ * `verify(task, response)` is the caller's check against the authoritative
+ * gate record (plan-review.json, context.json, …): it returns the evidence
+ * `{ record, hash, remoteETag }` when the action landed for exactly this
+ * subject, else null. Without evidence the task stays pending; the action is
+ * never repeated here.
+ */
+export function taskRecoverer(deckRoot, { verify = null } = {}) {
+  return (intent) => {
+    if (intent?.kind !== RESPONSE_KIND) return false;
+    const { taskId, response } = intent.notes ?? {};
+    if (!taskId || !response) return true; // nothing was invoked yet; the intent is just a claim
+    const store = readStore(deckRoot);
+    const task = store.tasks.find((t) => t.id === taskId);
+    if (!task) return true;
+    if (task.status === "completed" && task.response?.operationId === response.operationId) return true;
+    if (task.status !== "pending") return true;
+    if (!verify) return false; // the action may have landed; only its gate record can say — refuse until someone checks
+    const evidence = verify(task, response);
+    if (evidence && evidence.hash === task.subject.hash) {
+      complete(task, response, evidence);
+      writeStore(deckRoot, store);
+    }
+    return true;
+  };
+}
+
+/** Explicit recovery pass (the daemon calls it before the first mutation after start). */
+export function recoverTasks(deckRoot, { verify = null } = {}) {
+  const pending = readOperationIntent(ws(deckRoot));
+  if (!pending) return { recovered: false };
+  if (pending.malformed) throw coded("recovery_required", "workspace-operation.json is unreadable");
+  if (pending.intent.kind !== RESPONSE_KIND) throw coded("recovery_required", `operation ${pending.intent.id} (${pending.intent.kind}) is not a task transaction`, { intent: pending.intent });
+  // The wrapper runs the recoverer under the lock and clears the intent.
+  return runDeckOperation(ws(deckRoot), { kind: "task-recovery", recover: taskRecoverer(deckRoot, { verify }) }, () => ({ recovered: true }));
+}
+
+function complete(task, response, evidence) {
+  task.response = response;
+  task.evidence = { record: evidence.record ?? null, hash: evidence.hash, remoteETag: evidence.remoteETag ?? null };
+  task.status = "completed";
+  task.updatedAt = nowIso();
+}
+
+// ---------------------------------------------------------------------------
+// mutations
+// ---------------------------------------------------------------------------
+
+/**
+ * Ask for a task, or find the identical one. Dedup key is kind + adapterId +
+ * subject.hash: the same content asked twice is one task. A different
+ * `remoteETag` for identical content refreshes provenance on the existing task
+ * and is still `existing: true` — a remote version is never a new subject.
+ *
+ * A new subject SUPERSEDES the pending tasks of the same kind: their content has
+ * moved on, so they are questions about something that no longer exists.
+ */
+export async function requestTask(deckRoot, { kind, subject, adapterId, actions = KINDS[kind] }, { owner, verify } = {}) {
+  const draft = validateTask({
+    id: randomUUID(),
+    kind,
+    adapterId,
+    subject: { hash: subject?.hash, remoteETag: subject?.remoteETag ?? null },
+    status: "pending",
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+    actions,
+    response: null,
+    evidence: null,
+  });
+  return runDeckOperation(ws(deckRoot), { kind: "task-request", owner, recover: taskRecoverer(deckRoot, { verify }) }, () => {
+    const store = readStore(deckRoot);
+    const existing = store.tasks.find(
+      (t) => t.status === "pending" && t.kind === kind && t.adapterId === adapterId && t.subject.hash === draft.subject.hash,
+    );
+    if (existing) {
+      if (existing.subject.remoteETag !== draft.subject.remoteETag) {
+        existing.subject.remoteETag = draft.subject.remoteETag;
+        existing.updatedAt = nowIso();
+        writeStore(deckRoot, store);
+      }
+      return { task: existing, existing: true };
+    }
+    // A newer ask about the same thing voids the older ones. An identical subject
+    // returned above, so every other pending task of this kind asks about content
+    // that has moved on — and three live "approve the plan" cards are one question
+    // asked three times, which no one can answer three times. The response is left
+    // alone (null): superseding is not an answer.
+    const stale = store.tasks.filter((t) => t.status === "pending" && t.kind === kind && t.adapterId === adapterId);
+    for (const t of stale) {
+      t.status = "superseded";
+      t.updatedAt = nowIso();
+    }
+    store.tasks.push(draft);
+    writeStore(deckRoot, store);
+    return { task: draft, existing: false, superseded: stale.map((t) => t.id) };
+  });
+}
+
+/**
+ * The response transaction. `invoke(task, response)` is the authoritative
+ * action (approve the plan, record the comments) and returns `{ evidence }`
+ * with the exact content hash; it runs under the deck lock with the durable
+ * intent already on disk.
+ *
+ * Refuses `stale_subject` (expectedHash is not the task's), `validation_failed`
+ * (unknown action, malformed body, or an operationId reused with another body).
+ * A repeated operationId with the same body answers the recorded result and
+ * does not invoke again. `invoke` may answer `{ blocked: { code, message,
+ * details } }` instead of evidence when it wrote nothing: that is a refusal
+ * with the intent cleared, not a half-done transaction.
+ */
+/**
+ * What the human said, as one string on the task record: a single `comment`,
+ * or a gate's batch of `comments` (objects with text and an anchor, or plain
+ * strings) joined one per paragraph — so `tasks get` shows it without the gate's
+ * own state file.
+ */
+export function commentOf(payload = {}) {
+  if (typeof payload?.comment === "string" && payload.comment.trim()) return payload.comment;
+  const list = Array.isArray(payload?.comments) ? payload.comments : [];
+  const lines = list
+    .map((c) => {
+      if (typeof c === "string") return c.trim();
+      if (!c || typeof c.text !== "string") return "";
+      const where = c.scope === "story" ? "Whole story" : c.slideIndex != null ? `Slide ${c.slideIndex}` : c.jsxPath ? String(c.jsxPath).replace(/^slides\//, "").replace(/\.jsx$/, "") : "";
+      return (where ? `[${where}] ` : "") + c.text.trim();
+    })
+    .filter(Boolean);
+  return lines.length ? lines.join("\n\n") : null;
+}
+
+export async function respondTask(deckRoot, id, request, { invoke, owner, verify } = {}) {
+  const req = validateRespondRequest(request);
+  if (typeof invoke !== "function") throw new Error("respondTask needs the authoritative invoke");
+  const response = {
+    operationId: req.operationId,
+    action: req.action,
+    at: nowIso(),
+    actor: req.actor,
+    comment: commentOf(req.payload),
+    ...(req.selfDeclared === true ? { selfDeclared: true } : {}),
+  };
+  return runDeckOperation(
+    ws(deckRoot),
+    { operationId: req.operationId, kind: RESPONSE_KIND, expected: { taskId: id, hash: req.expectedHash }, owner, recover: taskRecoverer(deckRoot, { verify }) },
+    async (op) => {
+      const store = readStore(deckRoot);
+      const task = store.tasks.find((t) => t.id === id);
+      // Refusals before the action: nothing ran, so the intent must not outlive
+      // this call — returned, not thrown, and rethrown outside the operation.
+      if (!task) return { refused: coded("stale_subject", `no task ${id} on this deck`) };
+      const recorded = task.response?.operationId === req.operationId ? task.response : null;
+      if (recorded) {
+        if (recorded.action !== req.action || (recorded.comment ?? null) !== commentOf(req.payload)) {
+          return { refused: invalid(`operation ${req.operationId} was already recorded with a different body`) };
+        }
+        return { task, result: task.evidence, replayed: true };
+      }
+      if (task.status !== "pending") return { refused: coded("stale_subject", `task ${id} is ${task.status}`) };
+      if (task.subject.hash !== req.expectedHash && !(task.subject.followed ?? []).includes(req.expectedHash)) {
+        return { refused: coded("stale_subject", "the content changed since this task was requested; reload and decide again", { current: task.subject.hash }) };
+      }
+      if (!task.actions.includes(req.action)) return { refused: invalid(`${req.action} is not an action of this task (${task.actions.join(", ")})`) };
+      op.note({ taskId: id, response });
+      const { evidence, blocked } = (await invoke(task, response, { token: op.token })) ?? {};
+      // Nothing ran (stale subject, invalid plan, shared approval): refused with the intent cleared.
+      if (isObj(blocked)) return { refused: coded(blocked.code ?? "blocked", blocked.message ?? "the action did not run", blocked.details ? { details: blocked.details } : {}) };
+      if (!isObj(evidence) || evidence.hash !== task.subject.hash) {
+        throw coded("validation_failed", "the action returned no evidence for the exact subject; the task stays pending", { evidence: evidence ?? null });
+      }
+      complete(task, response, evidence);
+      writeStore(deckRoot, store);
+      return { task, result: task.evidence, replayed: false };
+    },
+  ).then((out) => {
+    if (out.refused) throw out.refused;
+    return out;
+  });
+}
+
+function setStatus(deckRoot, id, status, owner) {
+  return runDeckOperation(ws(deckRoot), { kind: `task-${status}`, owner, recover: taskRecoverer(deckRoot) }, () => {
+    const store = readStore(deckRoot);
+    const task = store.tasks.find((t) => t.id === id);
+    if (!task) throw coded("stale_subject", `no task ${id} on this deck`);
+    if (task.status === "pending") {
+      task.status = status;
+      task.updatedAt = nowIso();
+      writeStore(deckRoot, store);
+    }
+    return task;
+  });
+}
+
+/**
+ * The agent has the answer: the gate command printed it. The receipt is what
+ * lets the page say "your agent picked it up" instead of guessing, and what
+ * tells a later gate run that an answer was already handed over (a comments
+ * round it has seen is not handed over twice). Completed tasks only; idempotent.
+ */
+export function markPickedUp(deckRoot, id, { owner } = {}) {
+  return runDeckOperation(ws(deckRoot), { kind: "task-picked-up", owner, recover: taskRecoverer(deckRoot) }, () => {
+    const store = readStore(deckRoot);
+    const task = store.tasks.find((t) => t.id === id);
+    if (!task) throw coded("stale_subject", `no task ${id} on this deck`);
+    if (task.status === "completed" && !task.pickedUpAt) {
+      task.pickedUpAt = nowIso();
+      writeStore(deckRoot, store);
+    }
+    return task;
+  });
+}
+
+/** The content moved on; the question is void. Pending only — an answer is never un-given. */
+export const supersedeTask = (deckRoot, id, { owner } = {}) => setStatus(deckRoot, id, "superseded", owner);
+export const cancelTask = (deckRoot, id, { owner } = {}) => setStatus(deckRoot, id, "cancelled", owner);
+
+/**
+ * The plan page saved an edit on top of exactly the version a pending plan
+ * task asks about: the person answering is the person editing, so the question
+ * follows the edit instead of going stale. Only tasks whose subject is `from`
+ * move; a task about any other version is left to supersede as before. The
+ * version the agent asked about stays on the task as `subject.requestedHash`.
+ */
+export const PLAN_TASK_KINDS = ["plan-edit", "plan-approval"];
+export function followPlanEdit(deckRoot, { from, to }, { owner } = {}) {
+  if (!SHA.test(String(from)) || !SHA.test(String(to)) || from === to) return Promise.resolve([]);
+  return runDeckOperation(ws(deckRoot), { kind: "task-follow-edit", owner, recover: taskRecoverer(deckRoot) }, () => {
+    const store = readStore(deckRoot);
+    const moved = store.tasks.filter((t) => t.status === "pending" && PLAN_TASK_KINDS.includes(t.kind) && t.subject.hash === from);
+    for (const t of moved) {
+      // what the agent asked about, kept once: an answered task whose hash is
+      // not its requestedHash tells the agent to re-read the plan before acting
+      t.subject.requestedHash ??= from;
+      // every version it moved through, so an answer clicked on a card drawn
+      // a save ago still lands (it answers for the page's own edits, and nothing else)
+      t.subject.followed = [...(t.subject.followed ?? []), from].slice(-50);
+      t.subject.hash = to;
+      t.updatedAt = nowIso();
+    }
+    if (moved.length) writeStore(deckRoot, store);
+    return moved.map((t) => t.id);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// wait
+// ---------------------------------------------------------------------------
+
+/**
+ * `{ task, pending }`: the saved answer first, else a bounded wait for one.
+ * In-process writers wake it directly; another process (the daemon while the
+ * agent waits, or the reverse) is seen through a watch on `state/`. The wait
+ * is advisory: on wake it re-reads the store, never trusts the event.
+ */
+export async function waitTask(deckRoot, id, { timeoutMs = 45_000, signal = null } = {}) {
+  const check = () => {
+    const task = getTask(deckRoot, id);
+    if (!task) throw coded("stale_subject", `no task ${id} on this deck`);
+    return task;
+  };
+  const first = check();
+  if (first.status !== "pending") return { task: first, pending: false };
+  if (timeoutMs <= 0) return { task: first, pending: true };
+  const file = tasksPath(deckRoot);
+  return new Promise((resolve, reject) => {
+    let watcher = null;
+    const done = (fn) => {
+      clearTimeout(timer);
+      notifier.off(file, wake);
+      signal?.removeEventListener("abort", onAbort);
+      watcher?.close();
+      fn();
+    };
+    const wake = () => {
+      let task;
+      try {
+        task = check();
+      } catch (err) {
+        return done(() => reject(err));
+      }
+      if (task.status !== "pending") done(() => resolve({ task, pending: false }));
+    };
+    // `check()` throws when the deck's task store went away under us (trashed from
+    // the page, recovery_required). These two callbacks run OUTSIDE the executor, so
+    // the throw would not reject the promise — it would be an uncaughtException and
+    // take the daemon down. Settle through the promise like `wake` does.
+    const give = (fn) => {
+      let task;
+      try {
+        task = check();
+      } catch (err) {
+        return done(() => reject(err));
+      }
+      done(() => fn(task));
+    };
+    const onAbort = () => give((task) => resolve({ task, pending: true }));
+    const timer = setTimeout(() => give((task) => resolve({ task, pending: true })), timeoutMs);
+    notifier.on(file, wake);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      // ponytail: directory watch (the atomic rename replaces the file's inode); polling fallback if a platform drops events.
+      watcher = fs.watch(path.dirname(file), () => wake());
+      watcher.on("error", () => {});
+    } catch {
+      watcher = null;
+    }
+  });
+}