agentbox-app 0.1.6

package/main/repeats.mjs

@@ -0,0 +1,261 @@
+// The rule store: the only writer of <product>/repeats.jsonl.
+//
+// A repeating task is a RULE, never a work item, so it never runs, is never
+// claimed, and cannot be finished by a worker. Its runs are ordinary work items
+// and go through the store's modules like everything else.
+//
+// The file is append-only and folded newest-wins, the same shape as
+// dashboard.jsonl, and it is read WHOLE. That is the point rather than a
+// detail: the work-item ledger is read from a trailing 8 MiB window, and the
+// fold applies only the fields present in surviving lines, so a long-lived
+// template kept there would eventually lose the rule itself and stop repeating
+// with no symptom at all.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  DAY_NAMES, foldRepeats, isOwed, isRepeatRule, occurrenceId, periodKey, repeatLabel,
+} from '../shared/repeats.mjs';
+import { machineryPath } from './store/home.mjs';
+import { NAME } from '../shared/product-name.mjs';
+
+const FILE = 'repeats.jsonl';
+
+// What a refused rule is called when we say we cannot keep it. A weekly rule
+// whose day is missing used to print "every week at 08:00", which names the one
+// part that was fine and hides the part that was not.
+function describeRule({ every, at, on }) {
+  if (every === 'week') {
+    const day = DAY_NAMES[on] ?? 'no day';
+    return `every week on ${day} at ${at}`;
+  }
+  return `every ${every} at ${at}`;
+}
+
+// How many periods in a row may be superseded before the founder is told.
+const MISSES_BEFORE_ALERT = 3;
+
+// The protocol goes FIRST in an occurrence's body, ahead of her words. An
+// over-long body keeps its prefix and cuts its suffix, so a protocol written
+// last can be truncated away entirely, and a worker that never saw it cannot
+// know that a quiet finish has to be marked.
+export const OCCURRENCE_PROTOCOL = [
+  'THIS IS ONE RUN OF A REPEATING TASK. It runs again tomorrow whatever happens',
+  'here, so this run does not have to carry the future.',
+  '',
+  'FINISH ONE OF TWO WAYS.',
+  '',
+  'Nothing she needs to know: update this item with status done AND labels',
+  '["founder", "<REPEAT_LABEL>", "clean"] IN THE SAME CALL. Labels REPLACE the',
+  'array rather than merging, so send all three. The clean label is what keeps a',
+  'quiet run out of her inbox, and no result is needed: that is what clean means.',
+  '',
+  'Anything she needs to know: finish normally, with a result saying what you',
+  'found, and do NOT set the clean label. It reaches her inbox, which is the',
+  'point of running this every day. Anything that deserves its own life gets',
+  'filed as its own item.',
+  '',
+  'If you are unsure which of the two this is, it is the second one. This is the',
+  `only place in ${NAME} where finishing quietly hides something, so the marker is`,
+  'required to hide, never to show.',
+  '',
+  'HER INSTRUCTION FOLLOWS.',
+].join('\n');
+
+export class Repeats {
+  constructor(storeModules) {
+    this.modules = storeModules;
+  }
+
+  // In the app's home, not the product folder: a repeat rule is our record of
+  // what to run, not one of her documents (main/store/home.mjs).
+  filePath(productDir) {
+    return machineryPath(productDir, FILE);
+  }
+
+  _read(productDir) {
+    let raw = '';
+    try {
+      raw = fs.readFileSync(this.filePath(productDir), 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return [];
+      throw err;
+    }
+    return raw.split('\n').filter(Boolean).map((line) => {
+      // A torn line is skipped rather than thrown on, the way every other fold
+      // in this store treats one.
+      try { return JSON.parse(line); } catch { return null; }
+    });
+  }
+
+  _append(productDir, id, patch, now = Date.now()) {
+    fs.appendFileSync(this.filePath(productDir), `${JSON.stringify({ id, ts: now, patch })}\n`);
+  }
+
+  list(productDir, now = Date.now()) {
+    return [...foldRepeats(this._read(productDir), now).values()];
+  }
+
+  get(productDir, id, now = Date.now()) {
+    return foldRepeats(this._read(productDir), now).get(id) ?? null;
+  }
+
+  // `engine` AND `model` ARE HER PICK ON THE RULE, and the runs carry them
+  // (`serve` below). They are optional and absent by default, which is every
+  // rule on her disk: a rule that names neither behaves exactly as it did, and
+  // its runs go to the workspace default like any unmarked row. Whether either
+  // word may be written at all is decided at the door, by
+  // `Supervisor#engineOffered` and `#modelOffered`, so a rule cannot be marked
+  // for an engine this Mac never offered her.
+  setRule(productDir, {
+    title, body, priority = 5, every = 'day', at, on, engine, model,
+  }, now = Date.now()) {
+    // Refused here rather than stored and ignored later: a rule that cannot be
+    // kept has to fail while she is still looking at what she typed.
+    //
+    // `on` is validated AND stored. It was in neither, so a weekly rule was
+    // checked without the day that makes it weekly, and no weekly rule ever
+    // survived this line (hers). The refusal says which day is missing now,
+    // because "every week at 08:00" reads like a bug in the clock.
+    if (!title || !String(title).trim()) throw new Error('a repeating task needs a title');
+    if (!isRepeatRule({ every, at, on })) throw new Error(`not a schedule ${NAME} can keep: ${describeRule({ every, at, on })}`);
+    const id = `r-${crypto.randomBytes(5).toString('hex')}`;
+    this._append(productDir, id, {
+      title: String(title).trim(), body, priority, every, at,
+      ...(every === 'week' ? { on } : {}),
+      ...(engine ? { engine: String(engine) } : {}),
+      ...(model ? { model: String(model) } : {}),
+      createdAt: now, served: '', misses: 0, alerted: 0,
+    }, now);
+    return this.get(productDir, id, now);
+  }
+
+  patchRule(productDir, id, patch, now = Date.now()) {
+    // `on` joins the other two: changing a daily rule to a Thursday one sends
+    // every, at AND on, and checking the first two alone refused the change for
+    // the same reason a new weekly rule was refused (hers).
+    if (('at' in patch || 'every' in patch || 'on' in patch)) {
+      const current = this.get(productDir, id, now);
+      if (!current) throw new Error(`no such repeating task: ${id}`);
+      const next = {
+        every: patch.every ?? current.every,
+        at: patch.at ?? current.at,
+        on: patch.on ?? current.on,
+      };
+      if (!isRepeatRule(next)) throw new Error(`not a schedule ${NAME} can keep: ${describeRule(next)}`);
+    }
+    this._append(productDir, id, patch, now);
+    return this.get(productDir, id, now);
+  }
+
+  // Ending one is a small durable fact rather than an archive, so it does not
+  // collide with what `done` means on a work item.
+  endRule(productDir, id, now = Date.now()) {
+    return this.patchRule(productDir, id, { endedAt: now }, now);
+  }
+
+  // The rules whose current period has not been served. Never more than one
+  // period per rule: there is no queue of missed firings, only a condition that
+  // is currently false, which is why three days away costs one run.
+  due(productDir, now = Date.now()) {
+    return this.list(productDir, now)
+      .filter((rule) => isOwed(rule, now))
+      .map((rule) => ({ rule, key: periodKey(rule, now) }));
+  }
+
+  /**
+   * Serve one period. ONE short locked step of local reads and appends: create
+   * the occurrence if its id is absent, supersede an unfinished predecessor,
+   * then move the watermark.
+   *
+   * Nothing slow happens inside the lock. The session is spawned by the caller
+   * afterwards, and claimWorkItem is never called here because it takes the
+   * same lock and this one is not reentrant.
+   *
+   * The order is create-then-mark, so a crash between them retries into a
+   * create that finds the id present and does nothing, rather than running the
+   * work twice.
+   */
+  async serve(productDir, ruleId, key, now = Date.now()) {
+    const { workItemsDisk, lock } = this.modules;
+    return lock.withProjectLock(productDir, async () => {
+      const rule = this.get(productDir, ruleId, now);
+      const nothing = { occurrenceId: null, created: false, superseded: null, misses: rule?.misses ?? 0, alert: null };
+      if (!rule || rule.endedAt || !isRepeatRule(rule)) return nothing;
+
+      const id = occurrenceId(ruleId, key);
+      let superseded = null;
+      let misses = rule.misses ?? 0;
+
+      // The predecessor's state is re-read HERE, inside the lock. A worker
+      // finishing between the tick's read and this write is the ordinary case,
+      // and superseding a run that has just succeeded reports a failure that
+      // never happened.
+      //
+      // Never the item we are about to create: a rule whose watermark was
+      // refused could otherwise be asked to serve the same period twice and
+      // supersede its own live run.
+      if (rule.lastOccurrence && rule.lastOccurrence !== id) {
+        const prev = workItemsDisk.readWorkItem(productDir, rule.lastOccurrence, now);
+        if (prev && (prev.status === 'open' || prev.status === 'claimed')) {
+          workItemsDisk.updateWorkItem(productDir, prev.id, {
+            status: 'done',
+            result: 'This run did not finish before the next one was due, so it was superseded.',
+          }, { source: 'system', now });
+          superseded = prev.id;
+          misses += 1;
+        } else if (prev && prev.status === 'done') {
+          misses = 0;
+        }
+      }
+
+      const { created } = workItemsDisk.createWorkItemIfAbsent(productDir, id, {
+        title: `${rule.title} · ${dayStamp(key)}`,
+        body: `${OCCURRENCE_PROTOCOL.replace('<REPEAT_LABEL>', repeatLabel(ruleId))}\n\n${rule.body ?? rule.title}`,
+        kind: 'directive',
+        priority: rule.priority ?? 5,
+        labels: ['founder', repeatLabel(ruleId)],
+        // WHICH CODING AGENT AND WHICH MODEL, off the rule, at the moment the
+        // run is made. A run is an ordinary work item, so this is the same pair
+        // `composeItem` writes for a task she types by hand and it is read by
+        // the same `engineFor` -- the occurrence needs no rule-shaped special
+        // case anywhere downstream. Absent on a rule that names neither, which
+        // is every rule on her disk today.
+        ...(rule.engine ? { engine: rule.engine } : {}),
+        ...(rule.model ? { model: rule.model } : {}),
+      }, { source: 'system', now });
+
+      // Told once per streak, and that is a durable fact rather than an
+      // intention: a crash after filing cannot file it twice, and one before it
+      // cannot lose it.
+      const alertNeeded = misses >= MISSES_BEFORE_ALERT && misses > (rule.alerted ?? 0);
+      this._append(productDir, ruleId, {
+        served: key,
+        lastOccurrence: id,
+        misses,
+        ...(alertNeeded ? { alerted: misses } : {}),
+      }, now);
+
+      return { occurrenceId: id, created, superseded, misses, alert: alertNeeded ? missedKeys(key, misses) : null };
+    }, { label: `repeat ${ruleId}` });
+  }
+}
+
+function dayStamp(key) {
+  const [y, m, d] = key.split('-').map(Number);
+  return new Date(y, m - 1, d).toLocaleDateString(undefined, { weekday: 'short', month: 'short', day: 'numeric' });
+}
+
+// The period keys the misses covered, oldest first, for the alert's wording.
+function missedKeys(currentKey, misses) {
+  const [y, m, d] = currentKey.split('-').map(Number);
+  const keys = [];
+  for (let back = misses; back >= 1; back--) {
+    const day = new Date(y, m - 1, d - back);
+    const mm = String(day.getMonth() + 1).padStart(2, '0');
+    const dd = String(day.getDate()).padStart(2, '0');
+    keys.push(`${day.getFullYear()}-${mm}-${dd}`);
+  }
+  return keys;
+}

package/main/row-label.mjs

@@ -0,0 +1,185 @@
+// THE NAME ON THE ROW, WRITTEN RATHER THAN TAKEN FROM HER FIRST SENTENCE.
+//
+// A message she dictates keeps its first line as its title, verbatim and
+// forever (renderer/src/message-split.ts). Measured on her Agentbox store the day
+// she asked: 214 of the 330 items are hers, median title 84 characters, 145 over
+// 60, 37 cut off mid sentence with an ellipsis, and 76 opening with "I", "I've
+// been", "Can you" or "We". Eleven of those down a column is eleven rows that
+// look like one row.
+//
+// THERE IS NOTHING TO EXTRACT FROM CLAUDE CODE, which is the first thing this
+// had to find out. Claude Code does generate a short name for a session and it
+// writes it to the terminal tab; it never puts it on disk. Measured 2026-09-03:
+// ZERO of her 3,126 transcript files written since 20 August carry a `summary`
+// row, and main/agent-sessions.mjs found the same over 495 files on 08-29. So
+// the name is not read from anywhere. It is written, here, by the same kind of
+// call Claude Code makes: one small fast model, one message, one line back.
+//
+// AND IT IS WRITTEN FROM WHERE THE THREAD STANDS, NOT FROM ITS FIRST MESSAGE.
+// This is the difference she was shown and the one she picked. Titled from its
+// opening line alone came back "Fix onboarding and theme visibility", which was
+// true the day she wrote it and by then the row was about landing five
+// branches; given the last thing written on the row as well, the same call said
+// "Landing branches for app fixes". Her threads run for days, so a name fixed
+// at the first message goes stale the way rule 8 of her instructions is about,
+// and this is the same failure arriving from the other side.
+//
+// WHY THE APP DOES THIS AND NOT THE WORKER. It was written into briefs/worker.md
+// first and taken straight back out: the brief is pasted into every session and
+// tests/the-brief-only-says-what-applies.mjs holds it under 6,000 characters,
+// which it was 33 characters short of. A rule every worker must remember is also
+// a rule most of them will not, and the row she is looking at right now may have
+// no worker on it at all. Doing it here names every row on every product with
+// nothing for anyone to remember.
+//
+// The write goes to `label`, never to `title`. The title is hers, the fold makes
+// her outrank us on it, and she still reads her own words the moment she opens
+// the row (shared/work-items.mjs).
+
+import { spawn } from 'node:child_process';
+
+/**
+ * The model this runs on. Small and fast on purpose: this is a naming call, it
+ *  happens on a timer, and it must never be worth thinking about. Measured
+ *  through the CLI on 2026-09-03 over ten of her real rows: 14.1s median a call,
+ *  nearly all of it the CLI starting a session rather than the model working. */
+export const NAME_MODEL = 'claude-haiku-4-5-20251001';
+
+/**
+ * How long one naming call may take before it is abandoned. Generous against
+ *  the 14.1s median because a slow one costs nothing: the row keeps the name it
+ *  already had, or her title, and the next tick tries again. */
+export const NAME_TIMEOUT_MS = 90_000;
+
+/**
+ * What a name may be. Long enough for "Landing branches for app fixes", short
+ *  enough that it can never be the thing that makes a row clip: the row draws
+ *  one line and the summary budget beside it is 112. */
+export const NAME_MAX = 64;
+
+/**
+ * A row nobody is going to look at again does not get named. `done` is the
+ *  archive; everything else is a row that can still appear in a list. */
+const LIVE = new Set(['open', 'claimed', 'blocked']);
+
+/**
+ * The newest moment anything about this row's CONTENT changed. Deliberately not
+ *  `updatedAt`: a heartbeat, a claim and a release all move that, and renaming a
+ *  row every time a worker touches it would spend a call a minute on a busy row
+ *  and change the words under her while she reads them. */
+export function contentTouchedAt(item) {
+  const w = item?.wrote ?? {};
+  let last = 0;
+  for (const field of ['title', 'body', 'result', 'answer']) {
+    const ts = w[field]?.ts ?? 0;
+    if (ts > last) last = ts;
+  }
+  return last;
+}
+
+/**
+ * PURE. Does this row want naming?
+ *
+ * Three ways to say no, and the third is the one that keeps this cheap:
+ *   - it is done, so nobody is scanning for it,
+ *   - it has nothing to name from, which is a row with no words on it yet,
+ *   - its label is already at least as new as the newest thing said on the row.
+ *
+ * A row whose label we wrote and whose content has not moved since is finished
+ * business forever, so a store that has settled costs nothing per tick.
+ */
+export function wantsName(item) {
+  if (!item || !LIVE.has(item.status)) return false;
+  if (!String(item.title ?? '').trim() && !String(item.body ?? '').trim()) return false;
+  const wroteAt = item.wrote?.label?.ts ?? 0;
+  if (!String(item.label ?? '').trim()) return true;
+  return wroteAt < contentTouchedAt(item);
+}
+
+/**
+ * PURE. The one message the naming call gets. Her words first, then the last
+ *  thing written on the row, which is what makes the name describe the thread
+ *  rather than its opening line. Truncated hard: a name does not get better for
+ *  having read six thousand words, and this is spawned on a timer. */
+export function namePrompt(item) {
+  const cut = (s, n) => String(s ?? '').replace(/\r/g, '').trim().slice(0, n);
+  const latest = cut(item?.result || item?.note, 700);
+  return [
+    'Here is a work thread: the message that opened it, and the latest thing',
+    'written on it. Write a short name for the thread AS IT STANDS NOW: 3 to 7',
+    'words, sentence case, no quotes, no trailing punctuation, naming the thing',
+    'being worked on rather than restating the sentence. Reply with the name and',
+    'nothing else.',
+    '',
+    '--- opened with ---',
+    cut(item?.title, 300),
+    cut(item?.body, 1200),
+    '--- latest ---',
+    latest || '(nothing written yet)',
+    '---',
+  ].join('\n');
+}
+
+/**
+ * PURE. What comes back from a model is not a name until this has had it.
+ *
+ * A one-line reply is the contract and most of the time it is what arrives. The
+ * rest of this is what happens when it does not: a preamble, a quoted name, a
+ * trailing full stop, or a paragraph explaining the choice. Anything that fails
+ * every rule returns '' and the row keeps the name it had, which is always safe
+ * because the fallback is her own title.
+ */
+export function cleanName(text) {
+  const first = String(text ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)[0] ?? '';
+  const bare = first
+    .replace(/^["'`“”‘’]+|["'`“”‘’]+$/g, '')
+    .replace(/^(?:title|name)\s*[:\-–]\s*/i, '')
+    .replace(/[.。]+$/, '')
+    .trim();
+  if (!bare || bare.length > NAME_MAX) return '';
+  // A reply that runs on is a model that answered a different question, and a
+  // chatty one clears the character cap easily. The prompt asks for three to
+  // seven words, so eight is one word of slack and anything past it is not the
+  // thing that was asked for.
+  if (bare.split(/\s+/).length > 8) return '';
+  return bare;
+}
+
+/**
+ * Name one row. Resolves to a clean name, or to '' for every failure there is:
+ * the binary missing, a non-zero exit, a timeout, an empty reply, a reply that
+ * is not a name. Never throws and never rejects, because this is called from a
+ * timer whose only correct behaviour on failure is to leave the row alone.
+ */
+export function nameRow(item, { claudeBin, model = NAME_MODEL, timeoutMs = NAME_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    if (!claudeBin) return resolve('');
+    let child;
+    try {
+      child = spawn(claudeBin, ['-p', namePrompt(item), '--model', model], {
+        // Somewhere that is nobody's project. A naming call must not pick up a
+        // CLAUDE.md, a settings file or a hook from whatever folder it lands in.
+        cwd: '/tmp',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch {
+      return resolve('');
+    }
+    let out = '';
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(''), timeoutMs);
+    child.stdout.on('data', (d) => { out += d.toString(); if (out.length > 4000) finish(cleanName(out)); });
+    child.on('error', () => finish(''));
+    child.on('close', (code) => finish(code === 0 ? cleanName(out) : ''));
+  });
+}

package/main/screen-detail.mjs

@@ -0,0 +1,44 @@
+// WHICH SET OF PICTURES A SCREEN GETS., 2026-08-22.
+//
+// Kept out of main.mjs and free of Electron, like zoom-keys.mjs, so the rule can
+// be tested against made-up displays instead of against whatever monitor the
+// machine running the tests happens to have.
+//
+// WHY THE BUILT-IN PANEL AND NOT A WIDTH. Three numbers were on the table and
+// two of them lie:
+//
+//   - device pixels across the screen: her laptop reports 3420 and the 34" is
+//     3440. A 20px gap is not a signal.
+//   - devicePixelRatio in the window: she runs the app at 120% zoom, so the
+//     laptop reads 2.4 and the 34" would read 1.2. Correct today and it flips
+//     the moment she presses Cmd+minus a few times, because Chromium folds page
+//     zoom into that number.
+//   - the display's own scaleFactor and `internal` flag, which the main process
+//     reads off the window server. Neither moves when the page zooms.
+//
+// So: the built-in panel of a Retina laptop is the small dense screen, and
+// everything plugged into it is the big one. That is her sentence, not a
+// threshold anybody has to defend later. Measured on her machine 2026-08-22
+// through the running app: one display, `internal: true`, `scaleFactor: 2`,
+// 1710x1107 points, window zoom 1.2.
+
+/** @typedef {'soft' | 'sharp'} ScreenDetail */
+
+/**
+ * Which picture set a display should paint.
+ *
+ * Anything unrecognisable answers 'sharp', because the sharp set is what every
+ * screen got before this existed and an unreadable display is not a reason to
+ * quietly downgrade one. `internal` is undefined on some platforms; that is a
+ * 'sharp' too, for the same reason.
+ *
+ * @param {{ internal?: boolean, scaleFactor?: number } | null | undefined} display
+ * @returns {ScreenDetail}
+ */
+export function screenDetailFor(display) {
+  if (!display || typeof display !== 'object') return 'sharp';
+  if (display.internal !== true) return 'sharp';
+  const s = display.scaleFactor;
+  if (typeof s !== 'number' || !Number.isFinite(s)) return 'sharp';
+  return s >= 2 ? 'soft' : 'sharp';
+}