agentbox-app 0.1.6

package/mcp/core/work.mjs

@@ -0,0 +1,377 @@
+// Work items across every product: the unified queue.
+//
+// The substrate is deliberately thin. It knows how to hold an item, hand it to
+// exactly one worker, and let go when that worker dies. It does NOT know what
+// work is worth doing, what a milestone is, when to ask the founder, or whether
+// a category has earned the right to act without asking. Every one of those is
+// going to be rewritten several times as the surface above learns what it
+// actually needs, and a substrate that had opinions about them would have to be
+// rewritten alongside.
+//
+// The heartbeat lives here rather than in a tool, and that is a load-bearing
+// choice. A heartbeat tool would depend on the model remembering to call it
+// during work that is, by definition, absorbing its attention; it would forget,
+// and a healthy worker would lose its claim mid-task, which is the worst version
+// of this failure. Instead the SERVER PROCESS beats while it holds anything. The
+// process lives exactly as long as the agent session that spawned it, so:
+// session dies, child dies, beating stops, lease lapses, the item comes back.
+// Liveness for free, and nothing to remember.
+
+import path from 'node:path';
+import { listProjects } from '../../main/store/project.mjs';
+import {
+  readWorkItems, readWorkItem, createWorkItem, updateWorkItem,
+  claimWorkItem, heartbeatWorkItem, releaseWorkItem, LEASE_MS,
+} from '../../main/store/work-items.mjs';
+import { matchesFilter } from '../../shared/work-items.mjs';
+import { unleaked } from '../../shared/agents.mjs';
+import {
+  parkPendingWrite, readPendingWrites, collectPendingWrites,
+} from '../../main/store/pending-writes.mjs';
+import { resolveProduct } from './account.mjs';
+import { nameSlug } from '../../shared/product-name.mjs';
+
+// The log prefix, named from the one place the app is named. It was a literal
+// for as long as this server lived in another product's repo.
+const LOG = `[${nameSlug}-store]`;
+
+// Beat at a third of the lease, so two consecutive misses (a busy event loop, a
+// slow disk) still leave a full beat of margin before anything lapses.
+const HEARTBEAT_MS = Math.floor(LEASE_MS / 3);
+
+/** Every work item across every product, newest activity first. */
+export function listWorkItems({ product = null, status = null, kind = null, labels = null, includeDone = false, now = Date.now() } = {}) {
+  const projects = product ? [resolveProduct(product)] : listProjects();
+  const out = [];
+
+  for (const p of projects) {
+    let items = [];
+    try { items = readWorkItems(p.dir, now); } catch { continue; } // a product with no ledger has no work
+    for (const item of items) {
+      if (!includeDone && item.status === 'done') continue;
+      if (status && item.status !== status) continue;
+      if (!matchesFilter(item, { kind, labels })) continue;
+      out.push({ ...item, product: p.id, productName: p.name });
+    }
+  }
+  return out.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+/** Find which product owns an id, so callers do not have to track it. */
+function locate(id, { product = null } = {}) {
+  if (product) {
+    const p = resolveProduct(product);
+    const item = readWorkItem(p.dir, id);
+    if (!item) throw new Error(`no work item ${id} in ${p.name}`);
+    return { project: p, item };
+  }
+  for (const p of listProjects()) {
+    let item = null;
+    try { item = readWorkItem(p.dir, id); } catch { continue; }
+    if (item) return { project: p, item };
+  }
+  throw new Error(`no work item ${id} in any product`);
+}
+
+// THE WORDS AN AGENT SENDS, WITH A LEAKED TOOL CALL CUT OFF THEM.
+//
+// `unleaked` holds what leaks and the row it cost. It is applied here, at the
+// boundary where an agent's text arrives, and NOT in the store: the store also
+// holds what she typed, and her words are hers whatever they contain. The pane
+// cuts it again on the way out, because the rows that already carry it are
+// still on her screen.
+const WORDS = ['result', 'note', 'body', 'title', 'label'];
+
+function saidPlainly(fields, source) {
+  if (source === 'founder' || !fields) return fields;
+  const out = { ...fields };
+  for (const f of WORDS) {
+    if (typeof out[f] === 'string') out[f] = unleaked(out[f]);
+  }
+  return out;
+}
+
+export function createItem(product, fields = {}, { source = 'agent' } = {}) {
+  const p = resolveProduct(product);
+  const item = createWorkItem(p.dir, saidPlainly(fields, source), { source });
+  return { ...item, product: p.id, productName: p.name };
+}
+
+export function updateItem(id, patch, { product = null, epoch = null, source = 'agent' } = {}) {
+  const { project } = locate(id, { product });
+  const item = updateWorkItem(project.dir, id, saidPlainly(patch, source), { epoch, source });
+  return { ...item, product: project.id, productName: project.name };
+}
+
+/*
+ * ONLY SHE CLOSES A ROW SHE WROTE, UNLESS SHE SAID TO (w-e372d22a99).
+ *
+ * Her words, 2026-09-27: "If I ask for something, its job is to return it back.
+ * Only when I request it, 'Close it,' or say, 'All right, I'm done with this,'
+ * or something like that, should it close it."
+ *
+ * Until then a worker answered her ask and set it done in the same call, and
+ * the row wore "Closed" from then on. On the row she reported, w-3384aa9e5c, a
+ * worker claimed at 19:45:20 and closed at 19:46:09. She could not find it, and
+ * found it in Closed. Measured across her store that night: 43 of her rows had
+ * been closed by an agent against 361 closed by her.
+ *
+ * So a `done` on a row labelled `founder` needs HER WORDS asking for it, quoted
+ * in `closeBecause` and found in what she wrote on the row. Without them the
+ * rest of the write lands and the row stays open: the answer reaches her inbox
+ * as an answer (`answeredHerAsk`, list-rules.ts), and `awaitingHer`
+ * (supervisor.mjs) keeps a second worker off it until she speaks. The quote is
+ * checked for being hers, not for meaning close; that judgement is the
+ * worker's, and the quote is what makes it one it has to make on purpose.
+ *
+ * A run of a repeating task is not her ask. She set the task up to run daily
+ * and close quietly when there is nothing to say, so `repeat:` rows keep that.
+ */
+const plainly = (s) => String(s ?? '')
+  .toLowerCase()
+  .replace(/[‘’]/g, "'")
+  .replace(/[“”]/g, '"')
+  .replace(/\s+/g, ' ')
+  .trim();
+
+export function herRow(item) {
+  const labels = item?.labels ?? [];
+  return labels.includes('founder') && !labels.some((l) => String(l).startsWith('repeat:'));
+}
+
+export function saidToClose(item, words) {
+  const quote = plainly(words).replace(/^["'\s]+|["'.,!?\s]+$/g, '');
+  if (quote.length < 4) return false;
+  return [item?.answer, item?.body, item?.title].some((t) => plainly(t).includes(quote));
+}
+
+const LEFT_OPEN = 'The row was left OPEN. The founder wrote it, and only she closes her own rows unless she asked you to: everything else you sent was written, and your answer reaches her inbox as an answer. If she did ask you to close it, send status done again with closeBecause set to her exact words asking for it.';
+
+/**
+ * What a refused write is told about itself. The sentence matters as much as
+ * the file: the session that lost a night's work read "claim it first", had no
+ * reason to think anything had survived, and ended its turn.
+ */
+function carried(parked) {
+  if (!parked) return ' Your write could NOT be parked, so re-send it once you hold the claim.';
+  return ` YOUR WRITE WAS NOT LOST: it is parked at ${parked.relPath} inside the product folder, and the next session to claim ${parked.item} is handed it. If this session should still be the one to say it, claim the item again and send it again.`;
+}
+
+/** What the session taking the row over is told at the moment it takes it. */
+function pendingNotice(pending) {
+  const n = pending.length;
+  return `${n} write${n === 1 ? '' : 's'} to this row ${n === 1 ? 'was' : 'were'} refused when an earlier session lost its claim, and ${n === 1 ? 'it is' : 'they are'} waiting in \`pending\`. Nobody has seen ${n === 1 ? 'it' : 'them'}: not the founder, not the row. Read ${n === 1 ? 'it' : 'them'}, decide what is still true, and carry that into your own note or result. Your first write to this row files ${n === 1 ? 'it' : 'them'} as delivered.`;
+}
+
+/**
+ * A registry of the claims THIS server process holds, and the timer that keeps
+ * them alive. Purely in-memory, and that is correct: it describes this process's
+ * liveness, and it is supposed to vanish when the process does.
+ */
+export function createClaimRegistry({ heartbeatMs = HEARTBEAT_MS, holder } = {}) {
+  // `live` is the difference between holding the row and merely still being
+  // allowed to speak on it. A finished row gives its claim straight back, so
+  // nothing waits on a lease for work that is over, but the session keeps its
+  // epoch: the founder replies to finished rows constantly, and the session she
+  // is replying to has to be able to answer her.
+  const held = new Map(); // workItemId -> { dir, epoch, pending, live }
+  let timer = null;
+  const liveCount = () => [...held.values()].filter((h) => h.live).length;
+
+  const beat = () => {
+    for (const [id, { dir, epoch, live }] of held) {
+      if (!live) continue;
+      try {
+        heartbeatWorkItem(dir, id, { epoch, holder });
+      } catch (err) {
+        // A failed beat is not fatal: the lease still has two beats of margin,
+        // and the next one may well succeed. Losing the claim is the correct
+        // outcome if they all keep failing.
+        console.error(`${LOG} heartbeat failed for ${id}: ${err?.message ?? err}`);
+      }
+    }
+  };
+
+  const ensureTimer = () => {
+    if (timer || !liveCount()) return;
+    timer = setInterval(beat, heartbeatMs);
+    // Never keep the process alive just to beat: if the agent session is done,
+    // this server should exit, and the lapse is exactly the signal we want.
+    timer.unref?.();
+  };
+
+  const stopTimer = () => {
+    if (timer && !liveCount()) { clearInterval(timer); timer = null; }
+  };
+
+  // Park a refused write in the product that owns the row. The lookup can fail
+  // (an id that belongs to no product at all), and a failure to park must never
+  // hide the refusal itself, so it degrades to a null and the caller still
+  // throws.
+  const parkIn = (dir, id, patch, epoch, reason) => {
+    try {
+      return parkPendingWrite(dir, id, patch, { holder, epoch, reason });
+    } catch (err) {
+      console.error(`${LOG} could not park a refused write for ${id}: ${err?.message ?? err}`);
+      return null;
+    }
+  };
+
+  const park = (id, patch, reason) => {
+    let dir = null;
+    try { dir = locate(id).project.dir; } catch { return null; }
+    return parkIn(dir, id, patch, null, reason);
+  };
+
+  const registry = {
+    holder,
+    async claim({ product = null, id = null, filter = null }) {
+      // A claim by id can address any product; a filtered pull walks products in
+      // order until one yields, so a worker with nothing specific to do gets the
+      // first available item anywhere rather than nothing.
+      const projects = product ? [resolveProduct(product)] : (id ? [locate(id).project] : listProjects());
+
+      for (const p of projects) {
+        const result = await claimWorkItem(p.dir, { id, filter, holder });
+        if (result.claimed) {
+          // A write an earlier session had refused is handed over HERE, at the
+          // moment the row changes hands, because that is the only moment a
+          // session can be told something without having to remember to look.
+          const pending = readPendingWrites(p.dir, result.item.id);
+          held.set(result.item.id, { dir: p.dir, epoch: result.epoch, pending: pending.length > 0, live: true });
+          ensureTimer();
+          return {
+            ...result,
+            item: { ...result.item, product: p.id, productName: p.name },
+            ...(pending.length ? { pending, pendingNotice: pendingNotice(pending) } : {}),
+          };
+        }
+        // Asking for a specific id and being refused is an answer, not a reason
+        // to go looking in other products.
+        if (id) return result;
+      }
+      return { claimed: false, reason: 'nothing available in any product' };
+    },
+
+    /**
+     * Finish or update an item this process holds, under its own epoch.
+     *
+     * A refused write is PARKED rather than dropped. Both refusals are covered
+     * and they fail differently: not holding the claim throws here, while a
+     * claim that lapsed and was taken by somebody else does not throw at all —
+     * the line is appended and the fold quietly skips it, so the caller gets
+     * back an item that looks fine and is missing every word it just wrote.
+     * That second one is the quieter of the two and it reads the same to the
+     * founder: a message that was never there.
+     *
+     * NOT HOLDING THE ROW IS NOW A REASON TO TAKE IT, NOT A REASON TO REFUSE.
+     * The refusal was written for the case it almost never caught. Measured
+     * across the 119 writes parked on the founder's store since 24 August 2026:
+     * 99 were a session writing before it had claimed, and 12 were a session
+     * writing again after finishing the row, which drops the claim from this
+     * map. In all 111 the row was free to this session or already its own, and
+     * the message was parked anyway, so 211,573 characters of finished agent
+     * writing missed the row on the first attempt and the founder watched
+     * sessions sit out a lease to say something they had already written. So a
+     * write on a row we are not holding tries the claim first, and only parks
+     * when the claim is genuinely refused, which means somebody else is on it.
+     */
+    async update(id, patch) {
+      let holding = held.get(id);
+      if (!holding?.live) {
+        let taken = null;
+        try { taken = await registry.claim({ id }); } catch { /* an id in no product: park below */ }
+        const fresh = held.get(id);
+        if (fresh?.live) holding = fresh;
+        else if (!holding) {
+          // Nobody handed it over and we have no standing on it, so this is the
+          // refusal the fence exists for: somebody else is working the row.
+          const why = taken?.heldBy
+            ? `${id} is held by ${taken.heldBy}`
+            : `${holder} could not take ${id} (${taken?.reason ?? 'no such work item'})`;
+          const parked = park(id, patch, `${holder} was not holding ${id} when it wrote`);
+          throw new Error(`${why}, so this write could not be made.${carried(parked)}`);
+        }
+        // Otherwise the row was finished by this session and the claim is back
+        // on the shelf. We still own the epoch, so we may still speak, and the
+        // fence below still catches the case where somebody else took over.
+      }
+
+      const { closeBecause, ...asked } = patch;
+      let leftOpen = false;
+      if (asked.status === 'done') {
+        const before = readWorkItem(holding.dir, id);
+        if (herRow(before) && !saidToClose(before, closeBecause)) {
+          delete asked.status;
+          leftOpen = true;
+        }
+      }
+      patch = asked;
+      let item = Object.keys(patch).length
+        ? updateWorkItem(holding.dir, id, patch, { epoch: holding.epoch })
+        : readWorkItem(holding.dir, id);
+
+      // The fence. A claim epoch above ours means the row changed hands while
+      // we were working and the fold has just discarded the line we appended.
+      if (item && item.epoch > holding.epoch) {
+        held.delete(id);
+        stopTimer();
+        const parked = parkIn(holding.dir, id, patch, holding.epoch,
+          `claim lapsed: ${holder} wrote under epoch ${holding.epoch}, the row is now on epoch ${item.epoch}`);
+        throw new Error(`the claim on ${id} lapsed while this session worked and the row is now on epoch ${item.epoch}, so the store discarded this write.${carried(parked)}`);
+      }
+
+      // We were handed somebody else's message when we claimed, and we have now
+      // spoken on this row, so it is ours to have carried and must not be handed
+      // to a third session as if it were still waiting.
+      if (holding.pending) {
+        collectPendingWrites(holding.dir, id, { by: holder });
+        holding.pending = false;
+      }
+
+      // FINISHING A ROW GIVES THE CLAIM BACK NOW, not in five minutes. It used
+      // to drop the row from this map and leave the claim line standing, so the
+      // ledger went on reading "held by <this session>" for a full lease after
+      // the work was over: the founder's next reply could not be answered, and
+      // a session that tried was refused by its own name. The entry stays, and
+      // it is the epoch that keeps this session able to answer her.
+      if (item?.status === 'done' && holding.live) {
+        try { releaseWorkItem(holding.dir, id, { epoch: holding.epoch }); }
+        catch (err) { console.error(`${LOG} could not give back the claim on ${id}: ${err?.message ?? err}`); }
+        holding.live = false;
+        stopTimer();
+      }
+      // Left open, the claim still goes back now, for the same reason as a
+      // finish: the work is over and her reply must find the row free. The
+      // release is what puts the status back to open.
+      if (leftOpen) {
+        if (holding.live) {
+          try { item = releaseWorkItem(holding.dir, id, { epoch: holding.epoch }); }
+          catch (err) { console.error(`${LOG} could not give back the claim on ${id}: ${err?.message ?? err}`); }
+          holding.live = false;
+          stopTimer();
+        }
+        return { ...item, leftOpen: LEFT_OPEN };
+      }
+      return item;
+    },
+
+    release(id) {
+      const holding = held.get(id);
+      if (!holding?.live) throw new Error(`this session does not hold ${id}`);
+      const item = releaseWorkItem(holding.dir, id, { epoch: holding.epoch });
+      held.delete(id);
+      stopTimer();
+      return item;
+    },
+
+    holding: () => [...held.entries()].filter(([, h]) => h.live).map(([id]) => id),
+    // Test seams; not part of normal use.
+    _beat: beat,
+    _stop: () => { if (timer) clearInterval(timer); timer = null; held.clear(); },
+  };
+
+  return registry;
+}
+
+export { LEASE_MS, HEARTBEAT_MS };

package/mcp/stdio.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// The stdio transport. Deliberately the thinnest file in the build: everything
+// it knows is how to hand mcp/tools.mjs to a pipe, so the day the app wants HTTP
+// instead, the sibling file that does it changes nothing else.
+//
+// Run it directly:  STORE_ACCOUNT_ID=<id> node mcp/stdio.mjs
+// Register it:      claude mcp add <name> -- node /path/to/mcp/stdio.mjs
+//
+// THE SERVER IS NAMED FROM shared/product-name.mjs AND NOWHERE ELSE, which is
+// the same rule the rest of the app already follows. It used to be a literal
+// string, because this server was lifted out of another product, and that
+// product's name reached every worker as its tool prefix and every brief that
+// had to name a tool.
+//
+// One rule this file exists to enforce: STDOUT BELONGS TO THE PROTOCOL. A stray
+// console.log anywhere in the server corrupts the JSON-RPC stream and the client
+// sees a parse error rather than whatever was printed, so logging goes to
+// stderr, and console.log is rebound below so that a careless one downstream
+// cannot take the server down.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildTools } from './tools.mjs';
+import { NAME, Name, nameSlug } from '../shared/product-name.mjs';
+
+const LOG = `[${nameSlug}-store]`;
+
+console.log = (...args) => console.error(LOG, ...args);
+
+async function main() {
+  const { account, tools, claims } = buildTools();
+
+  const server = new McpServer(
+    { name: nameSlug, version: '1.0.0' },
+    {
+      instructions: [
+        `${Name} is this founder's product store: several products at once, each with its documents, personas, transcripts, reports, and designs, plus the skills describing how that work is done well.`,
+        'It holds the thinking, not the software. Product code lives in ordinary git checkouts (each product\'s repoPath), which you work in with your own tools.',
+        'Several sessions may be running against this store at the same time, so claim a work item before acting on it.',
+      ].join(' '),
+    },
+  );
+
+  for (const tool of tools) {
+    server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, tool.run);
+  }
+
+  // Give held work items back promptly on a clean exit instead of making the
+  // next worker wait out a full lease. Best effort by design: the lease is the
+  // guarantee, and this is only the courtesy that makes the common case fast.
+  const goodbye = () => {
+    for (const id of claims.holding()) {
+      try { claims.release(id); } catch { /* the lease will handle it */ }
+    }
+    process.exit(0);
+  };
+  process.on('SIGINT', goodbye);
+  process.on('SIGTERM', goodbye);
+
+  await server.connect(new StdioServerTransport());
+  console.error(`${LOG} serving account ${account.accountId} from ${account.root} (${tools.length} tools) for ${NAME}`);
+}
+
+main().catch((err) => {
+  // A startup failure is almost always configuration (no account, wrong
+  // STORE_HOME), so it must be readable on stderr rather than a stack trace
+  // the client swallows.
+  console.error(`${LOG} failed to start: ${err?.message ?? err}`);
+  process.exit(1);
+});