agent-inbox.mjs
Rama main · réplica de lectura del repositorio original.
#!/usr/bin/env node
/**
* agent-inbox.mjs — a tiny bridge between *looking at* the pipeline and
* *acting on* it.
*
* career-ops is driven from an AI session, but there's no durable place to drop
* a request when you're not in one — e.g. while glancing at the tracker (or a
* dashboard) you think "evaluate this URL" or "draft a follow-up for #7". This
* is that place: an append-only queue the agent drains at the start of a
* session.
*
* data/agent-inbox.md
* - [ ] <stamp> — <request> (pending)
* - [x] <stamp> — <request> → result: <one line> (resolved)
*
* Fully local-first and human-in-the-loop: nothing here auto-submits. Queued
* items are *intents* for the agent to action and the user to review. Markdown
* checklist, no database, no server, no dependencies — edit it by hand or via
* this CLI, and any tool (a dashboard, a script, cron) can append to it. The
* protocol an agent follows is documented in modes/agent-inbox.md.
*
* Item numbers are *file positions*, not positions in the pending list: `add`
* only ever appends, so a number never changes meaning once printed. `list`
* therefore shows gaps as items get resolved (2, 4, 5) — the gaps are the
* receipt that something was already handled, and a whole batch of resolves can
* be read off a single `list` without drifting.
*
* Usage:
* node agent-inbox.mjs add "evaluate https://acme.com/jobs/42"
* node agent-inbox.mjs list [--all] # pending only, or every item
* node agent-inbox.mjs resolve 1 [--expect "Acme"] [--result "scored 4.3 — report 012"]
*/
import {
readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync,
openSync, fstatSync, readSync, closeSync, realpathSync, statSync,
} from 'fs';
import { dirname } from 'path';
import { withPipelineLock } from './pipeline-lock.mjs';
import { writeFileAtomic } from './tracker-utils.mjs';
import { localToday } from './lib/local-today.mjs';
const PATH = process.env.CAREER_OPS_INBOX || 'data/agent-inbox.md';
const HEADER = [
'# Agent Inbox',
'',
'> **Agent protocol:** at the start of a career-ops session, read this file.',
'> Run each unchecked item top-to-bottom. After each, mark it `[x]` and append',
'> `→ result: <one line>`. Items that need live user input (a mock, a paste, a',
'> decision) → ask the user to start them instead of running them.',
'>',
'> Nothing here auto-submits — queued items are *intents* for you to action and',
'> the user to review. Appended by hand, by a dashboard, or by agent-inbox.mjs.',
'',
].join('\n');
// Local date and time, the clock the person queuing the item is looking at.
// toISOString() is UTC, and this stamp carries no zone marker, so a request
// queued at 10:30 on the 18th east of Greenwich read "2026-08-17 20:30".
function stamp(now = new Date()) {
const p = (n) => String(n).padStart(2, '0');
return `${localToday(now)} ${p(now.getHours())}:${p(now.getMinutes())}`;
}
function ensureGitignored() {
// The inbox is personal data. On installs whose .gitignore predates this
// feature, make sure the default path is ignored so a first `add` can't
// accidentally commit it. Only manages the default, non-overridden path.
if (process.env.CAREER_OPS_INBOX || PATH !== 'data/agent-inbox.md') return;
try {
if (!existsSync('.gitignore')) return; // not a git checkout we should touch
const text = readFileSync('.gitignore', 'utf8');
if (text.split('\n').some((l) => l.trim() === PATH)) return; // already ignored
writeFileSync('.gitignore', text.replace(/\s*$/, '') + `\n${PATH}\n`);
} catch { /* best effort — never block queuing on this */ }
}
function oneLine(s) {
// markdown-checklist-safe: collapse to a single bullet line
return String(s ?? '').replace(/\s*\n\s*/g, ' ').trim();
}
// MUST be called with the queue lock held — see add(). Creating the file is
// only half of it; the file is not usable until the header is IN it, and that
// is two syscalls, not one.
function ensureFile() {
if (existsSync(PATH)) return;
ensureGitignored();
mkdirSync(dirname(PATH), { recursive: true });
// 'wx': atomic create-exclusive. Two concurrent first-time `add` calls can
// both pass the existsSync check above before either writes; without an
// exclusive flag, the second writeFileSync (default 'w', which truncates)
// lands after the first has already appended its item and wipes it back to
// just the header. 'wx' makes only one of them win the create — the loser
// gets EEXIST and does nothing, same as if it had seen existsSync === true.
//
// 'wx' settles the two-creator case and nothing else. It makes the CREATE
// atomic, not the INITIALISATION: writeFileSync is open() then write(), and
// between those two syscalls the file EXISTS and is ZERO BYTES. Measured on
// Windows, a second process polling existsSync and stat-ing the moment the
// file appeared saw it at 0 bytes in 303 of 400 rounds.
//
// So there is a third participant the exclusive flag cannot see: a writer
// that arrives INSIDE that window, finds existsSync === true, skips creation,
// and appends — into a file this call is about to overwrite from offset 0.
// Its item is gone, with no error anywhere; the write below simply lands on
// top of it. That is why the caller holds the lock across this function
// rather than around the append alone.
try {
writeFileSync(PATH, HEADER, { flag: 'wx' });
} catch (err) {
if (err?.code !== 'EEXIST') throw err;
}
}
// Whether appending to `path` needs a leading newline first, i.e. the file is
// non-empty and doesn't already end in one. Reads only the last byte instead
// of the whole file — the full-file read this replaced was only ever used to
// check one byte.
function needsLeadingNewline(path) {
const fd = openSync(path, 'r');
try {
const size = fstatSync(fd).size;
if (size === 0) return false;
const buf = Buffer.alloc(1);
readSync(fd, buf, 0, 1, size - 1);
return buf[0] !== 0x0a; // '\n'
} finally {
closeSync(fd);
}
}
// Parse the checklist into items, in file order. `num` is the stable 1-based
// item number used by `list` and `resolve` — it is the position in the FULL
// list, so resolving an item never renumbers the others.
function parseItems() {
if (!existsSync(PATH)) return [];
const items = [];
readFileSync(PATH, 'utf8').split('\n').forEach((line, i) => {
const m = /^- \[([ xX])\]\s*(.*)$/.exec(line.trim());
if (m) items.push({ num: items.length + 1, line: i, done: m[1].toLowerCase() === 'x', text: m[2] });
});
return items;
}
function opt(name, def = '') {
const i = process.argv.indexOf('--' + name);
if (i < 0) return def;
const v = process.argv[i + 1];
return v && !v.startsWith('--') ? v : def;
}
// Every value given for a repeatable flag, in argv order. An occurrence with no
// value yields '' rather than being dropped, so the caller can reject it:
// opt() reads only the first occurrence and would never see a later bare one.
function optAll(name) {
const values = [];
process.argv.forEach((arg, i) => {
if (arg !== '--' + name) return;
const v = process.argv[i + 1];
values.push(v && !v.startsWith('--') ? v : '');
});
return values;
}
async function add() {
const text = oneLine(process.argv.slice(3).join(' '));
if (!text) fail('add needs a request, e.g. node agent-inbox.mjs add "evaluate https://..."');
// Append rather than rewrite. This is the queue's concurrent path — anything
// running in the background can drop an item in — and a read-whole-file /
// write-whole-file cycle loses every request that lands between the two. With
// 30 concurrent `add` calls, half the queue vanished silently.
//
// POSIX guarantees an O_APPEND write is atomic below PIPE_BUF, and one
// checklist line is far under it, so concurrent appends interleave instead of
// clobbering. WINDOWS IS NOT POSIX, and that is the whole reason for the lock
// below: with 30 concurrent adds on windows-latest this dropped exactly one
// item (#2777), silently, which is the same failure this function exists to
// remove — it just moved to the one platform the guarantee does not cover.
//
// The lock is the repo's existing one rather than a second mechanism: the
// same `withPipelineLock` that scan.mjs uses for scan-history appends. Two
// lock implementations would drift, and the append is short enough that
// serializing it costs nothing next to spawning the process that calls it.
//
// Checking the last byte still happens INSIDE the lock: it decides whether a
// separating newline is needed, and reading it outside would race with
// another writer's append between the check and the write.
//
// timeoutMs is raised from the shared 8s default because this queue's whole
// point is bursty concurrent writers (a dashboard, a script, cron all drop
// items at once), and lock acquisition is a retry lottery, not a fair queue.
// Serving N herded waiters is the coupon-collector problem: ~N·H(N) rounds,
// so 30 concurrent adds need ~120 rounds while 8000/80 = 100 only affords
// ~100. On the slow, contended windows-latest runner that shortfall makes one
// waiter time out and its item is LOST, the exact #2777 drop, reappearing as
// a loud LockTimeoutError instead of a silent overwrite. Jitter in
// pipeline-lock.mjs cuts the collision rate ~6x but is explicitly "not a
// cure"; the fit-for-purpose budget for a burst-write queue is the contained
// fix. 30s gives ~375 rounds of headroom, well past the herd's worst case,
// while the critical section itself is a single sub-millisecond append.
//
// ensureFile() is INSIDE the lock, not before it. Seeding the file is a
// check-create-initialise sequence, and run unlocked it loses items the same
// way the unlocked append did: a writer that observes the file between the
// creator's open() and its write() sees a zero-byte file, appends into it,
// and has its line overwritten when the header lands at offset 0. Every
// writer exits 0 and the queue is left perfectly well-formed, one item
// shorter — the silent drop the lock was added to end, one step earlier in
// the same function.
//
// Holding the lock across the seed makes the window unreachable rather than
// narrow: no writer can observe the file until the creator has released, and
// the creator writes the header before it releases. 'wx' above stays as the
// guard against writers that are not this function.
await withPipelineLock(PATH, () => {
ensureFile();
const separator = needsLeadingNewline(PATH) ? '\n' : '';
appendFileSync(PATH, `${separator}- [ ] ${stamp()} — ${text}\n`);
}, { timeoutMs: 30_000 });
process.stdout.write(`Queued: ${text}\n`);
}
function list() {
const all = process.argv.includes('--all');
const parsed = parseItems();
const items = parsed.filter((it) => all || !it.done);
if (!items.length) return process.stdout.write(all ? 'Inbox is empty.\n' : 'No pending items.\n');
items.forEach((it) => {
process.stdout.write(`${String(it.num).padStart(2)}. [${it.done ? 'x' : ' '}] ${it.text}\n`);
});
// Explain the gaps rather than let them read as a display bug.
if (items.length < parsed.length) {
process.stdout.write(
`\n(${parsed.length - items.length} resolved item(s) hidden — numbers are stable file positions, so gaps are expected. \`list --all\` shows everything.)\n`,
);
}
}
async function resolve() {
const n = Number(process.argv[3]);
if (!Number.isInteger(n) || n < 1) fail('resolve needs a 1-based item number (see `list`)');
const outcome = await withPipelineLock(PATH, () => {
// The item snapshot, line lookup, and rewrite are one transaction. An
// add between the old read and write was acknowledged, then overwritten by
// this stale snapshot even though add itself correctly held this same lock.
// Number inside the critical section too, so the selected item and the
// rewritten line always come from one locked view.
//
// Number against the FULL item list, not the pending subset. `add` only ever
// appends, so an item's position is stable for the life of the file and a
// batch of resolves read off one `list` stays correct. Numbering against the
// pending view instead made each resolve shift every higher number down by
// one — silently stamping later results onto the wrong items.
const items = parseItems();
const target = items[n - 1];
if (!target) {
const pending = items.filter((it) => !it.done).length;
return { error: `no item #${n} — inbox has ${items.length} item(s), ${pending} pending. Run \`list --all\`.` };
}
// Already-resolved is an error, not a silent re-stamp: it is what a stale
// number from an older `list` most often lands on.
if (target.done) return { error: `item #${n} is already resolved — refusing to overwrite it:\n #${n}: ${target.text}` };
// Optional caller-side guard: abort unless the target says what the caller
// thinks it says. Catches "right command, wrong target" generally.
// Every --expect given must hold, and every one must carry a value: a bare
// --expect anywhere on the line is a guard the caller meant to set and did
// not, so it fails instead of being skipped behind an earlier valid one.
const expects = optAll('expect');
if (expects.includes('')) return { error: '--expect needs a substring, e.g. --expect "Dana-Farber"' };
const missing = expects.find((expect) => !target.text.toLowerCase().includes(expect.toLowerCase()));
if (missing !== undefined) {
return { error: `item #${n} does not contain --expect ${JSON.stringify(missing)} — refusing to resolve:\n #${n}: ${target.text}` };
}
const result = oneLine(opt('result'));
const lines = readFileSync(PATH, 'utf8').split('\n');
let updated = lines[target.line].replace('[ ]', '[x]');
if (result && !/→ result:/.test(updated)) updated += ` → result: ${result}`;
lines[target.line] = updated;
// Replace, don't rewrite in place. The lock serialises writers, but `list`
// and anything reading the file by hand do not take it, and writeFileSync
// truncates before it writes: a reader in that window, or a crash inside
// it, sees a queue with items missing. A same-directory temp file renamed
// over the original is the repo's existing helper for exactly this.
//
// A rename replaces the directory entry it is given and installs a new
// file, so two things the in-place write got for free have to be asked
// for: write THROUGH a symlinked inbox (rename over the link would swap it
// for a regular file and leave its target stale), and keep the queue's
// permissions (a 0600 inbox must not come back 0644 under the umask).
const real = realpathSync(PATH);
writeFileAtomic(real, lines.join('\n'), { mode: statSync(real).mode & 0o7777 });
return { target };
}, { timeoutMs: 30_000 });
// Fail only after withPipelineLock has released. process.exit() inside the
// callback would bypass the lock's finally block and strand the directory.
if (outcome.error) fail(outcome.error);
process.stdout.write(`Resolved #${n}: ${outcome.target.text}\n`);
}
function fail(msg) {
process.stderr.write(`agent-inbox.mjs: ${msg}\n`);
process.exit(1);
}
const USAGE =
'Usage:\n' +
' node agent-inbox.mjs add "evaluate https://acme.com/jobs/42"\n' +
' node agent-inbox.mjs list [--all]\n' +
' node agent-inbox.mjs resolve <n> [--expect "substring"] [--result "..."]\n' +
'\n' +
'Numbers are stable file positions: `list` shows gaps once items are\n' +
'resolved, and a batch of resolves read off one `list` stays correct.\n' +
'--expect aborts unless the target item contains that substring.\n';
const cmd = process.argv[2];
if (cmd === 'add') await add();
else if (cmd === 'list') list();
else if (cmd === 'resolve') await resolve();
else if (cmd === undefined || cmd === '--help' || cmd === '-h') process.stdout.write(USAGE);
else {
// A word that is not a subcommand (`ad` for `add`) queued nothing, so it must
// not exit 0: the callers that check the status read 0 as "queued".
process.stderr.write(`agent-inbox.mjs: unknown command "${cmd}"\n${USAGE}`);
process.exit(1);
}