slidemind 0.3.20 → 0.4.0

package/src/cli/tasks.mjs

@@ -0,0 +1,246 @@
+// `slidemind tasks …` — the agent's side of durable tasks (contracts §1).
+//
+//   tasks list [<deck>] [--status pending] --json
+//   tasks request <deck> --kind <kind> --json      derive the subject, dedupe → { task, link, say } — returns at once
+//   tasks get <deck> <id> --json                   the answer; records that the caller received it
+//   tasks wait <deck> <id> [--timeout 45] --json   scripts only: saved answer first, bounded wait → { task, pending }
+//
+// An agent never waits: it ends its turn with `say`, and the user's pasted
+// message names `tasks get` (doc 21 → *Tasks and agent continuation*).
+//
+// Exit codes: 0 done (a pending wait is a successful read), 1 operational,
+// 2 blocked/busy/incompatible, 3 conflict/stale. One JSON value on stdout under
+// --json; diagnostics on stderr. The code lands on process.exitCode so bin's
+// post-command hooks still run.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { deckRoot as rootOf, planPageOwner, resolveWorkspace } from "../lib/deck-paths.mjs";
+import { resolveWorkspaceAdapter } from "../workspace/adapters.mjs";
+import { daemonRequest, ensureRunning, registerDeck, workspaceStatus } from "../workspace/lifecycle.mjs";
+import { askBlocker } from "../workspace/gate-client.mjs";
+import { sayLine, viewOf } from "../workspace/handback.mjs";
+import { browserUrl } from "./workspace-ui.mjs";
+import { listDecks } from "../workspace/registry.mjs";
+import { deriveTaskSubject } from "../workspace/task-actions.mjs";
+import { KINDS, getTask, listTasks, markPickedUp, requestTask, waitTask } from "../workspace/tasks.mjs";
+import { resolveDeckArg } from "./common.mjs";
+
+const EXIT_BY_CODE = {
+  deck_busy: 2,
+  workspace_sandboxed: 2,
+  deck_not_writable: 2,
+  workspace_unavailable: 2,
+  extension_missing: 2,
+  extension_incompatible: 2,
+  recovery_required: 2,
+  workspace_upgrade_required: 2,
+  stale_subject: 3,
+  local_conflict: 3,
+  unknown_task: 1,
+};
+
+function parse(rest) {
+  const flags = { json: false, status: null, kind: null, timeout: 45 };
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--json") flags.json = true;
+    else if (a === "--status") flags.status = rest[++i];
+    else if (a === "--kind") flags.kind = rest[++i];
+    else if (a === "--timeout") flags.timeout = Number(rest[++i]);
+    else if (a.startsWith("--")) throw usage(`unknown flag ${a}`);
+    else positional.push(a);
+  }
+  if (!Number.isFinite(flags.timeout) || flags.timeout < 0) throw usage("--timeout expects seconds");
+  return { flags, positional };
+}
+
+const usage = (msg) => Object.assign(new Error(msg), { code: "usage" });
+
+function emit(flags, payload, human) {
+  process.stdout.write(flags.json ? JSON.stringify(payload) + "\n" : human + "\n");
+}
+
+/** The registry entry for a deck path when it has one; the path alone otherwise. */
+function registered(deckRoot) {
+  let real = deckRoot;
+  try {
+    real = fs.realpathSync(deckRoot);
+  } catch {}
+  return listDecks({ hidden: true, limit: Infinity }).decks.find((d) => d.path === real) ?? { id: null, path: real };
+}
+
+const taskLine = (t, deck = "") => `${t.status.padEnd(10)} ${t.kind.padEnd(15)} ${t.id}${deck ? `  ${deck}` : ""}`;
+
+/** What a settled task says, in one human line (a superseded or dismissed task has no response). */
+function outcomeLine(t) {
+  if (t.status === "completed") return `${t.response?.action ?? "answered"} by ${t.response?.actor ?? "the user"}${t.response?.comment ? `:\n${t.response.comment}` : ""}`;
+  if (t.status === "superseded") return "superseded — the content changed; ask again about the current version";
+  if (t.status === "cancelled") return "dismissed by the user without an answer — ask them in chat how to go on";
+  return t.status;
+}
+
+/** The caller now holds the answer: record the receipt the workspace page reports. Best effort. */
+async function received(deckRoot, task) {
+  if (task?.status !== "completed" || task.pickedUpAt) return task;
+  try {
+    return await markPickedUp(deckRoot, task.id);
+  } catch (err) {
+    process.stderr.write(`slidemind: could not record that the answer was received (${err.message})\n`);
+    return task;
+  }
+}
+
+/**
+ * The page of the view the task is answered in, signing in whichever browser
+ * opens it, every time it is clicked; null when none is live. The agent pastes
+ * it for the user to click cold — it names the view, not the task, so a link
+ * from an earlier ask still opens the right place.
+ */
+export async function taskUrl(deckRoot, task) {
+  const s = await workspaceStatus();
+  if (!s.running) return null;
+  const entry = await registeredEntry(deckRoot);
+  return entry ? browserUrl({ deckId: entry.id, view: viewOf(task.kind) }) : null;
+}
+
+/** The deck's library entry (through the workspace when this process is sandboxed), or null with the reason on stderr. */
+async function registeredEntry(deckRoot) {
+  try {
+    return await registerDeck(deckRoot);
+  } catch (err) {
+    process.stderr.write(`slidemind: the workspace could not list ${deckRoot}: ${err.message}\n`);
+    return null;
+  }
+}
+
+/** Tell an open workspace page about the question (SSE); best effort, never opens a browser. */
+async function announce(deckRoot, task) {
+  const entry = await registeredEntry(deckRoot);
+  if (!entry?.id) return;
+  await daemonRequest(`/decks/${entry.id}/attention`, { method: "POST", body: { kind: task.kind, taskId: task.id }, timeoutMs: 3000 });
+}
+
+/** `tasks wait` as a long-poll on the daemon; null when it is not running or refuses. */
+async function waitViaDaemon(deckRoot, taskId, timeoutS) {
+  const s = await workspaceStatus();
+  if (!s.running) return null;
+  const entry = await registeredEntry(deckRoot);
+  if (!entry?.id) return null;
+  try {
+    const { status, body } = await daemonRequest(`/decks/${entry.id}/tasks/${encodeURIComponent(taskId)}/wait?timeout=${Math.round(timeoutS)}`, {
+      timeoutMs: (timeoutS + 15) * 1000,
+      // an edit session's token rides along: the answer to this task re-enters it instead of meeting deck_busy
+      headers: process.env.SLIDEMIND_OWNER ? { "X-Slidemind-Owner": process.env.SLIDEMIND_OWNER } : {},
+    });
+    if (status !== 200 || !body?.ok || !body.task) return null;
+    return { task: body.task, pending: !!body.pending };
+  } catch {
+    return null;
+  }
+}
+
+/** The task's subject, derived from the deck (task-actions.mjs) — never taken from the caller. */
+async function deriveSubject(deckRoot, kind) {
+  const owner = planPageOwner(resolveWorkspace(deckRoot));
+  let adapter = null;
+  if (owner.owner !== "core") {
+    // `"extension"` is the generic marker for "a pack owns this page, but the deck
+    // never said which" — it is not an id. Passing it through named a pack that
+    // cannot exist in the blocker ("install the 'extension' pack"); null gets the
+    // honest `no adapter id`, which is what the other three call sites do.
+    adapter = resolveWorkspaceAdapter(owner.owner === "extension" ? null : owner.owner);
+    if (adapter.blocker) throw Object.assign(new Error(adapter.blocker.message), { code: adapter.blocker.code });
+  }
+  return deriveTaskSubject({ deckRoot, adapter, kind });
+}
+
+export async function cmdTasks(rest) {
+  let flags;
+  try {
+    const parsed = parse(rest);
+    flags = parsed.flags;
+    const [sub, ...args] = parsed.positional;
+    const deckOf = (arg, what) => {
+      if (!arg) throw usage(`usage: slidemind tasks ${what}`);
+      return rootOf(resolveDeckArg(arg, { allowUnfinished: true }));
+    };
+    switch (sub) {
+      case "list": {
+        const decks = args[0] ? [registered(deckOf(args[0], "list [<deck>]"))] : listDecks().decks.filter((d) => !d.missing);
+        const tasks = [];
+        for (const d of decks) {
+          try {
+            for (const t of listTasks(d.path, { status: flags.status })) tasks.push({ ...t, deckId: d.id ?? null, deckPath: d.path });
+          } catch (err) {
+            process.stderr.write(`slidemind: ${d.path}: ${err.message}\n`);
+          }
+        }
+        emit(flags, { tasks }, tasks.map((t) => taskLine(t, t.deckPath)).join("\n") || "no tasks");
+        return;
+      }
+      case "request": {
+        const deck = deckOf(args[0], "request <deck> --kind <kind>");
+        if (!KINDS[flags.kind]) throw usage(`--kind must be one of ${Object.keys(KINDS).join(", ")}`);
+        const { adapterId, subject } = await deriveSubject(deck, flags.kind);
+        // The human answers in the workspace, so a question needs one to answer in
+        // and a link into it; without them it is a blocker, never a linkless task.
+        let task;
+        let existing;
+        let url;
+        try {
+          await ensureRunning();
+          await registerDeck(deck);
+          ({ task, existing } = await requestTask(deck, { kind: flags.kind, adapterId, subject }));
+          url = await taskUrl(deck, task);
+        } catch (err) {
+          const b = askBlocker(err, deck);
+          throw Object.assign(new Error(b.message), { code: b.code });
+        }
+        if (!url) {
+          const b = askBlocker(Object.assign(new Error("the workspace did not hand out a link to this deck (see above)"), { code: "workspace_unavailable" }), deck);
+          throw Object.assign(new Error(b.message), { code: b.code });
+        }
+        const say = sayLine(flags.kind, url);
+        // an open page shows the question at once; nothing opens a browser
+        await announce(deck, task).catch(() => {});
+        // `link` is the clickable one everywhere (`slidemind workspace` names it so too); `url` is kept for older callers
+        emit(flags, { task, existing, url, link: url, say }, `${existing ? "already open" : "requested"}: ${taskLine(task)}\nASK: ${url}\nSAY: ${say}\nEnd your turn now with the SAY line, word for word — do not wait or poll.`);
+        return;
+      }
+      case "get": {
+        const deck = deckOf(args[0], "get <deck> <id>");
+        const found = args[1] && getTask(deck, args[1]);
+        if (!found) throw Object.assign(new Error(`no task ${args[1] ?? "<id>"} on this deck`), { code: "unknown_task" });
+        const task = await received(deck, found);
+        emit(flags, { task }, `${taskLine(task)}\n${outcomeLine(task)}`);
+        return;
+      }
+      case "wait": {
+        const deck = deckOf(args[0], "wait <deck> <id> [--timeout 45]");
+        if (!args[1]) throw usage("usage: slidemind tasks wait <deck> <id>");
+        if (!getTask(deck, args[1])) throw Object.assign(new Error(`no task ${args[1]} on this deck`), { code: "unknown_task" });
+        // Through the running daemon when there is one, so the workspace page can
+        // SEE this wait (its "delivered" vs "tell your agent" wording rides on it);
+        // the file watcher is the fallback for a workspace that is not running.
+        const r = (await waitViaDaemon(deck, args[1], flags.timeout)) ?? (await waitTask(deck, args[1], { timeoutMs: flags.timeout * 1000 }));
+        if (!r.pending) r.task = await received(deck, r.task);
+        emit(flags, r, r.pending ? `still pending after ${flags.timeout}s: ${taskLine(r.task)}` : `${taskLine(r.task)}\n${outcomeLine(r.task)}`);
+        return;
+      }
+      default:
+        throw usage("usage: slidemind tasks <list|request|get|wait> …");
+    }
+  } catch (err) {
+    const code = err?.code ?? "error";
+    const exit = code === "usage" ? 1 : EXIT_BY_CODE[code] ?? 1;
+    if (flags?.json) {
+      process.stdout.write(JSON.stringify({ ok: false, error: { code, message: err.message, retryable: exit === 2 } }) + "\n");
+    } else {
+      process.stderr.write(`slidemind: ${err.message}\n`);
+    }
+    process.exitCode = exit;
+  }
+}