parawatch 0.0.0-stage → 0.1.0

package/dist/core/format.js

@@ -0,0 +1,261 @@
+export function ago(iso, now = Date.now()) {
+    if (!iso)
+        return "?";
+    const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.round(m / 60);
+    if (h < 48)
+        return `${h}h`;
+    return `${Math.round(h / 24)}d`;
+}
+export function view(opts = {}) {
+    const out = process.stdout;
+    const color = process.env.NO_COLOR ? false : process.env.FORCE_COLOR ? true : Boolean(out.isTTY);
+    const width = out.columns || Number(process.env.COLUMNS) || 120;
+    return { color, width: Math.max(50, width), wide: Boolean(opts.wide), all: Boolean(opts.all) };
+}
+const PLAIN = { color: false, width: 120, wide: false, all: false };
+const SGR = { bold: "1", dim: "2", red: "31", green: "32", yellow: "33", blue: "34", magenta: "35", cyan: "36" };
+function paint(v, s, ...codes) {
+    if (!v.color || !s || !codes.length)
+        return s;
+    return `\x1b[${codes.map((c) => SGR[c]).join(";")}m${s}\x1b[0m`;
+}
+function charWidth(cp) {
+    if (cp < 32 || (cp >= 0x7f && cp < 0xa0))
+        return 0;
+    if ((cp >= 0x300 && cp <= 0x36f) || (cp >= 0x200b && cp <= 0x200f) || (cp >= 0xfe00 && cp <= 0xfe0f))
+        return 0;
+    if ((cp >= 0x1100 && cp <= 0x115f) ||
+        (cp >= 0x2e80 && cp <= 0xa4cf) ||
+        (cp >= 0xac00 && cp <= 0xd7a3) ||
+        (cp >= 0xf900 && cp <= 0xfaff) ||
+        (cp >= 0xfe30 && cp <= 0xfe4f) ||
+        (cp >= 0xff00 && cp <= 0xff60) ||
+        (cp >= 0xffe0 && cp <= 0xffe6) ||
+        (cp >= 0x1f300 && cp <= 0x1faff) ||
+        (cp >= 0x20000 && cp <= 0x3fffd))
+        return 2;
+    return 1;
+}
+/** Columns a string takes in a terminal (CJK and emoji count as two). */
+export function textWidth(s) {
+    let w = 0;
+    for (const ch of s)
+        w += charWidth(ch.codePointAt(0));
+    return w;
+}
+/** Cut to at most `max` columns, ending with … when cut. */
+export function fit(s, max) {
+    if (max <= 0)
+        return "";
+    if (textWidth(s) <= max)
+        return s;
+    let w = 0;
+    let out = "";
+    for (const ch of s) {
+        const c = charWidth(ch.codePointAt(0));
+        if (w + c > max - 1)
+            break;
+        out += ch;
+        w += c;
+    }
+    return out + "…";
+}
+function pad(s, n) {
+    return s + " ".repeat(Math.max(0, n - textWidth(s)));
+}
+/** One line of plain text from an agent message: no markdown, no line breaks. */
+export function clean(s) {
+    return s
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/\*\*|`/g, "")
+        .replace(/^\s*(?:[-*>]|#+)\s+/gm, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+// ------------------------------------------------------------------ cards
+const KIND_LABEL = { decide: "decide", try: "try", block: "blocked", todo: "to do" };
+const KIND_PAINT = { decide: "yellow", try: "cyan", block: "red", todo: "blue" };
+/** When the matter came up: `since` when it is older than the card, else when the card opened. */
+export function cardStart(c) {
+    return c.since && c.since < c.openedAt ? c.since : c.openedAt;
+}
+/** Cards as aligned rows: id, kind, project, title, age. */
+export function cardRows(cards, v = PLAIN, now = Date.now(), indent = "") {
+    const idW = Math.max(3, ...cards.map((c) => c.id.length));
+    const projW = Math.min(16, Math.max(0, ...cards.map((c) => textWidth(c.project + (c.task ? `/${c.task}` : "")))));
+    const noteOf = (c) => (c.status === "answered" ? " · answered" : c.status === "closed" ? " · closed" : "");
+    const fixed = textWidth(indent) + idW + 2 + 7 + 2 + projW + 2 + 2 + 4;
+    const titleW = Math.min(v.width - fixed, Math.max(0, ...cards.map((c) => textWidth(c.title + noteOf(c)))));
+    return cards.map((c) => {
+        const proj = c.project + (c.task ? `/${c.task}` : "");
+        const age = ago(cardStart(c), now).padStart(4);
+        const note = noteOf(c);
+        const title = fit(c.title, titleW - textWidth(note));
+        const dim = c.status !== "open";
+        return [
+            indent,
+            paint(v, pad(c.id, idW), "bold"),
+            "  ",
+            paint(v, pad(KIND_LABEL[c.kind], 7), dim ? "dim" : KIND_PAINT[c.kind]),
+            "  ",
+            pad(fit(proj, projW), projW),
+            "  ",
+            paint(v, pad(title + note, titleW), ...(dim ? ["dim"] : [])),
+            "  ",
+            paint(v, age, "dim"),
+        ].join("");
+    });
+}
+export function cardLine(c, now = Date.now()) {
+    return cardRows([c], PLAIN, now)[0].trimEnd();
+}
+export function cardDetail(c) {
+    const out = [];
+    out.push(`${c.id} · ${KIND_LABEL[c.kind]} · ${c.project}${c.task ? ` [${c.task}]` : ""} · ${c.status}`);
+    out.push(c.title);
+    if (c.body)
+        out.push("", c.body);
+    if (c.options?.length) {
+        out.push("");
+        c.options.forEach((o, i) => out.push(`  ${i + 1}. ${o}${c.recommend === i + 1 ? "  (recommended)" : ""}`));
+    }
+    if (c.look)
+        out.push("", `Look at: ${c.look}`);
+    for (const o of c.open ?? [])
+        out.push(`Open: ${o}`);
+    for (const a of c.attach ?? [])
+        out.push(`Attached: ${a}`);
+    if (c.from || c.session)
+        out.push(`From: ${[c.from, c.session ? `session ${c.session.slice(0, 8)}` : ""].filter(Boolean).join(", ")}`);
+    out.push(`Opened: ${new Date(c.openedAt).toLocaleString()}${c.since ? `, first came up ${new Date(c.since).toLocaleDateString()}` : ""}`);
+    for (const a of c.answers) {
+        const choice = a.choice !== undefined ? ` chose ${a.choice}${c.options?.[a.choice - 1] ? ` (${c.options[a.choice - 1]})` : ""}` : "";
+        out.push("", `${a.by}${choice}${a.comment ? `: ${a.comment}` : ""}`);
+        for (const f of a.attach ?? [])
+            out.push(`  attached ${f}`);
+    }
+    for (const m of c.comments)
+        out.push(`${m.by}: ${m.text}`);
+    if (c.closeNote)
+        out.push("", `Closed: ${c.closeNote}`);
+    return out.join("\n");
+}
+export function inboxLine(i) {
+    const head = `[${i.card.project}] ${i.card.id} "${i.card.title}"`;
+    if (i.kind === "comment")
+        return `${head} comment: ${i.comment}`;
+    const parts = [];
+    if (i.choice !== undefined)
+        parts.push(`chose ${i.choice}${i.choiceText ? ` (${i.choiceText})` : ""}`);
+    if (i.comment)
+        parts.push(`said: ${i.comment}`);
+    if (i.attach?.length)
+        parts.push(`attached: ${i.attach.join(", ")}`);
+    return `${head} ${parts.join("; ")}`;
+}
+const STATE_MARK = {
+    working: "●",
+    waiting: "◐",
+    idle: "○",
+    done: "✓",
+    stalled: "!",
+    failed: "✗",
+    unknown: "?",
+};
+const STATE_PAINT = {
+    working: ["green"],
+    waiting: ["yellow"],
+    idle: ["dim"],
+    done: ["dim"],
+    stalled: ["red"],
+    failed: ["red"],
+    unknown: ["dim"],
+};
+const ENDED = new Set(["done", "idle"]);
+/** Finished subagents older than this fold into one "N finished" line. */
+const FOLD_AFTER_MS = 5 * 60_000;
+export const OTHER = "other";
+function whatText(r) {
+    if (r.error)
+        return `unreadable: ${r.error}`;
+    const a = clean(r.action ?? "");
+    if (r.state === "stalled")
+        return a ? `stalled · ${a}` : "stalled";
+    return a;
+}
+/** Runs grouped by project, children drawn as a tree under their parent, one terminal line each. */
+export function runsTree(runs, v = PLAIN, now = Date.now(), indent = "") {
+    const groups = new Map();
+    for (const r of runs) {
+        const k = r.project ?? OTHER;
+        if (!groups.has(k))
+            groups.set(k, []);
+        groups.get(k).push(r);
+    }
+    const names = [...groups.keys()].sort((a, b) => (a === OTHER ? 1 : b === OTHER ? -1 : a.localeCompare(b)));
+    // rows first, so every group shares one set of columns
+    const blocks = [];
+    for (const name of names) {
+        const rs = groups.get(name);
+        const ids = new Set(rs.map((r) => r.id));
+        const rows = [];
+        const walk = (r, prefix, cont) => {
+            rows.push({ prefix, run: r });
+            const kids = rs.filter((x) => x.parent === r.id);
+            const shown = v.all ? kids : kids.filter((k) => !(ENDED.has(k.state) && now - Date.parse(k.lastActivity ?? "") > FOLD_AFTER_MS));
+            const folded = kids.filter((k) => !shown.includes(k));
+            const items = [...shown];
+            if (folded.length)
+                items.push({ count: folded.length, newest: folded.map((k) => k.lastActivity ?? "").sort().pop() });
+            items.forEach((it, i) => {
+                const last = i === items.length - 1;
+                const p = cont + (last ? "└ " : "├ ");
+                const c = cont + (last ? "  " : "│ ");
+                if (it && "id" in it)
+                    walk(it, p, c);
+                else
+                    rows.push({ prefix: p, folded: it });
+            });
+        };
+        for (const r of rs.filter((r) => !r.parent || !ids.has(r.parent)))
+            walk(r, indent + "  ", indent + "  ");
+        blocks.push({ name, rows });
+    }
+    const all = blocks.flatMap((b) => b.rows);
+    const nameW = Math.min(Math.max(24, Math.floor(v.width * 0.4)), Math.max(12, ...all.map((row) => textWidth(row.prefix) + 2 + textWidth(row.run?.title ?? ""))));
+    const wideW = v.wide ? 24 : 0;
+    const out = [];
+    for (const { name, rows } of blocks) {
+        if (name === OTHER)
+            out.push(indent + paint(v, "other", "bold") + paint(v, "  not in a registered project", "dim"));
+        else
+            out.push(indent + paint(v, name, "bold"));
+        for (const row of rows) {
+            const lead = paint(v, row.prefix, "dim");
+            const room = nameW - textWidth(row.prefix) - 2;
+            if (row.folded) {
+                const label = `✓ ${row.folded.count} finished`;
+                out.push(lead + paint(v, pad(fit(label, room + 2), room + 2), "dim") + "  " + paint(v, ago(row.folded.newest, now).padStart(4), "dim"));
+                continue;
+            }
+            const r = row.run;
+            const ended = ENDED.has(r.state);
+            const titlePaint = r.role === "lead" ? ["bold"] : ended ? ["dim"] : [];
+            const mark = paint(v, STATE_MARK[r.state], ...STATE_PAINT[r.state]);
+            const title = paint(v, pad(fit(r.title, room), room), ...titlePaint);
+            const age = paint(v, ago(r.lastActivity, now).padStart(4), "dim");
+            const wide = v.wide ? "  " + paint(v, pad(`${r.kind === "subagent" ? r.model ?? "subagent" : r.runtime} ${r.id.slice(0, 8)}`, wideW - 2), "dim") : "";
+            const restW = v.width - nameW - 2 - 4 - wideW - 2;
+            const what = restW >= 8 ? "  " + paint(v, fit(whatText(r), restW), ...(r.error || r.state === "stalled" || r.state === "failed" ? ["red"] : ended ? ["dim"] : [])) : "";
+            out.push(`${lead}${mark} ${title}  ${age}${wide}${what}`.trimEnd());
+        }
+    }
+    return out.join("\n");
+}
+//# sourceMappingURL=format.js.map

package/dist/core/integrate.js

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { readInbox, inboxFrom } from "./ops.js";
+import { homeDir, readCursor, readEvents } from "./store.js";
+import { fold } from "./state.js";
+import { inboxLine } from "./format.js";
+export const BEGIN = "<!-- parawatch:begin -->";
+export const END = "<!-- parawatch:end -->";
+export function instructions(project) {
+    const p = project ?? "<project>";
+    return `${BEGIN}
+## Parawatch
+
+The human follows this work through \`parawatch\`. Use it instead of asking in chat. If a \`parawatch\` skill is available, follow it.
+
+- At the start of a session: \`parawatch claim --project ${p}\` (add \`--role lead\` if you lead this project).
+
+- Need a decision: \`parawatch ask --project ${p} "question" --option "..." --option "..." --recommend N --body "two or three lines"\`
+- Need the human to try something (a build, a video, a screen): \`parawatch try --project ${p} "title" --open <app or file> --attach <video or image> --look "what to look at"\`
+- Stuck until the human does something only they can do (install, sudo, sign in): \`parawatch block --project ${p} "what to do"\`
+- Something only the human can do, but nothing waits on it now: \`parawatch todo --project ${p} "what to do"\`
+- After opening a card, keep a background wait armed: \`parawatch wait --project ${p}\`. It prints the human's answers and exits; act on them, \`parawatch close <card> --note "what you did"\`, then arm it again.
+- A long job with no agent log (a bake, a benchmark): \`parawatch run start --project ${p} "title"\`, \`parawatch run note <id> "..."\`, \`parawatch run end <id>\`.
+- Never answer a card yourself. \`parawatch status\` shows everything that is open.
+${END}`;
+}
+/** Insert or replace the parawatch block in an instruction file. Returns true when the file changed. */
+export function writeInstructions(file, project) {
+    let text = "";
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const block = instructions(project);
+    let next;
+    const a = text.indexOf(BEGIN);
+    const b = text.indexOf(END);
+    if (a >= 0 && b > a)
+        next = text.slice(0, a) + block + text.slice(b + END.length);
+    else
+        next = text + (text && !text.endsWith("\n") ? "\n" : "") + (text ? "\n" : "") + block + "\n";
+    if (next === text)
+        return false;
+    fs.writeFileSync(file, next);
+    return true;
+}
+/**
+ * Claude Code hook: given the hook's JSON on stdin, return text to add to the turn
+ * when the human has answered something for this session's project. Peeks only;
+ * the agent's own `wait` still advances its cursor.
+ */
+export function hookContext(input, project) {
+    const events = readEvents();
+    const state = fold(events);
+    let name = project;
+    if (!name && input.session_id)
+        name = state.claims.find((c) => input.session_id.startsWith(c.session))?.project;
+    if (!name && input.cwd) {
+        for (const p of state.projects.values())
+            if (p.paths.some((x) => input.cwd === x || input.cwd.startsWith(x + "/")))
+                name = p.name;
+    }
+    if (!name)
+        return undefined;
+    const items = inboxFrom(events, readCursor(name), { project: name });
+    if (!items.length)
+        return undefined;
+    return [`Parawatch: the human answered ${items.length} card(s) for ${name} that you have not handled yet.`, ...items.map(inboxLine), `Act on them, then \`parawatch close <card>\`.`].join("\n");
+}
+/** Best-effort desktop notification. Never throws, never blocks. */
+/** The desktop app writes its pid here while it runs, so the CLI leaves notifications to it. */
+export function desktopPidPath() {
+    return path.join(homeDir(), "desktop.pid");
+}
+function desktopAppRunning() {
+    try {
+        const pid = Number(fs.readFileSync(desktopPidPath(), "utf8").trim());
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function notify(card) {
+    if (process.env.PARAWATCH_NOTIFY === "0")
+        return;
+    if (card.kind === "todo")
+        return; // a to-do waits in the panel
+    if (desktopAppRunning())
+        return; // the app notifies, with its own badge
+    const title = `parawatch · ${card.project}`;
+    const body = `${card.kind === "decide" ? "Decide" : card.kind === "try" ? "Try" : "Blocked"}: ${card.title}`;
+    try {
+        if (process.platform === "darwin") {
+            const esc = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+            spawn("osascript", ["-e", `display notification "${esc(body)}" with title "${esc(title)}"`], { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+        }
+        else if (process.platform === "linux") {
+            spawn("notify-send", [title, body], { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+        }
+    }
+    catch {
+        // no notifier available
+    }
+}
+export { readInbox };
+//# sourceMappingURL=integrate.js.map

package/dist/core/ops.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import { appendEvent, eventsPath, readCursor, readEvents, writeCursor } from "./store.js";
+import { fold, nextId } from "./state.js";
+import { CARD_KINDS, HUMAN } from "./types.js";
+export class UserError extends Error {
+}
+function cleanList(xs) {
+    const out = (xs ?? []).map((x) => x.trim()).filter(Boolean);
+    return out.length ? out : undefined;
+}
+function absPaths(xs) {
+    // attachments and things to open are kept as given when they look like URLs
+    return cleanList(xs)?.map((x) => (/^[a-z]+:\/\//i.test(x) ? x : path.resolve(x)));
+}
+export function addProject(name, paths) {
+    if (!/^[A-Za-z0-9._-]+$/.test(name))
+        throw new UserError(`project name "${name}" may only use letters, digits, . _ -`);
+    appendEvent(() => ({
+        type: "project.add",
+        project: { name, paths: paths.map((p) => path.resolve(p)), addedAt: new Date().toISOString() },
+    }));
+}
+export function removeProject(name) {
+    const s = fold(readEvents());
+    if (!s.projects.has(name))
+        throw new UserError(`no project named "${name}"`);
+    appendEvent(() => ({ type: "project.remove", name }));
+}
+/** A date or timestamp as ISO text; a bare date counts as local midnight. */
+export function parseWhen(s) {
+    const t = s.trim();
+    const d = /^\d{4}-\d{2}-\d{2}$/.test(t) ? new Date(`${t}T00:00:00`) : new Date(t);
+    if (Number.isNaN(d.getTime()))
+        throw new UserError(`"${s}" is not a date (use YYYY-MM-DD)`);
+    return d.toISOString();
+}
+/** The claimed name of a session (claims may hold an id prefix). */
+export function sessionTitle(claims, session) {
+    if (!session)
+        return undefined;
+    const c = claims.find((x) => session.startsWith(x.session) || x.session.startsWith(session));
+    return c?.title;
+}
+function checkKind(kind) {
+    if (!CARD_KINDS.includes(kind))
+        throw new UserError(`kind must be one of ${CARD_KINDS.join(", ")}`);
+    return kind;
+}
+export function openCard(input) {
+    if (!input.title.trim())
+        throw new UserError("a card needs a title");
+    if (!input.project.trim())
+        throw new UserError("a card needs --project");
+    const options = cleanList(input.options);
+    if (input.recommend !== undefined) {
+        if (!options)
+            throw new UserError("--recommend needs --option");
+        if (!Number.isInteger(input.recommend) || input.recommend < 1 || input.recommend > options.length) {
+            throw new UserError(`--recommend must be between 1 and ${options.length}`);
+        }
+    }
+    checkKind(input.kind);
+    const since = input.since?.trim() ? parseWhen(input.since) : undefined;
+    let id = "";
+    appendEvent((events) => {
+        id = nextId(events, "c");
+        const session = input.session?.trim() || undefined;
+        const from = input.from?.trim() || sessionTitle(fold(events).claims, session);
+        return {
+            type: "card.open",
+            card: {
+                id,
+                kind: input.kind,
+                project: input.project,
+                task: input.task || undefined,
+                title: input.title.trim(),
+                body: input.body?.trim() || undefined,
+                options,
+                recommend: input.recommend,
+                attach: absPaths(input.attach),
+                open: absPaths(input.open),
+                look: input.look?.trim() || undefined,
+                from,
+                session,
+                since,
+            },
+        };
+    });
+    const card = fold(readEvents()).cards.get(id);
+    if (!card)
+        throw new Error("card vanished right after it was written");
+    return card;
+}
+function requireCard(id) {
+    const card = fold(readEvents()).cards.get(id);
+    if (!card)
+        throw new UserError(`no card "${id}"`);
+    return card;
+}
+export function answerCard(id, a) {
+    const card = requireCard(id);
+    if (card.status === "closed")
+        throw new UserError(`card ${id} is already closed`);
+    if (a.choice === undefined && !a.comment?.trim() && !cleanList(a.attach)) {
+        throw new UserError("an answer needs --choice, --comment or --attach");
+    }
+    if (a.choice !== undefined) {
+        const n = card.options?.length ?? 0;
+        if (!Number.isInteger(a.choice) || a.choice < 1 || a.choice > n) {
+            throw new UserError(n ? `--choice must be between 1 and ${n}` : `card ${id} has no options`);
+        }
+    }
+    appendEvent(() => ({
+        type: "card.answer",
+        card: id,
+        by: a.by || HUMAN,
+        choice: a.choice,
+        comment: a.comment?.trim() || undefined,
+        attach: absPaths(a.attach),
+    }));
+}
+export function commentCard(id, text, by) {
+    requireCard(id);
+    if (!text.trim())
+        throw new UserError("a comment needs text");
+    appendEvent(() => ({ type: "card.comment", card: id, by, text: text.trim() }));
+}
+export function editCard(id, set) {
+    requireCard(id);
+    const clean = {};
+    if (set.kind !== undefined)
+        clean.kind = checkKind(set.kind);
+    if (set.title !== undefined) {
+        if (!set.title.trim())
+            throw new UserError("a card needs a title");
+        clean.title = set.title.trim();
+    }
+    // an empty value clears the field; null survives JSON where undefined would vanish
+    const cleared = null;
+    if (set.body !== undefined)
+        clean.body = set.body.trim() || cleared;
+    if (set.task !== undefined)
+        clean.task = set.task.trim() || cleared;
+    if (set.from !== undefined)
+        clean.from = set.from.trim() || cleared;
+    if (set.session !== undefined)
+        clean.session = set.session.trim() || cleared;
+    if (set.since !== undefined)
+        clean.since = set.since.trim() ? parseWhen(set.since) : cleared;
+    if (!Object.keys(clean).length)
+        throw new UserError("nothing to change");
+    appendEvent(() => ({ type: "card.edit", card: id, set: clean }));
+    return requireCard(id);
+}
+export function closeCard(id, note) {
+    const card = requireCard(id);
+    if (card.status === "closed")
+        return;
+    appendEvent(() => ({ type: "card.close", card: id, note: note?.trim() || undefined }));
+}
+export function startRun(r) {
+    let id = "";
+    appendEvent((events) => {
+        id = nextId(events, "r");
+        return { type: "run.start", run: { id, project: r.project, task: r.task, title: r.title, parent: r.parent } };
+    });
+    return id;
+}
+export function noteRun(id, text) {
+    if (!fold(readEvents()).runs.has(id))
+        throw new UserError(`no declared run "${id}"`);
+    appendEvent(() => ({ type: "run.note", run: id, text }));
+}
+export function endRun(id, status, note) {
+    if (!fold(readEvents()).runs.has(id))
+        throw new UserError(`no declared run "${id}"`);
+    appendEvent(() => ({ type: "run.end", run: id, status, note }));
+}
+export function claimSession(claim) {
+    if (claim.session.length < 6)
+        throw new UserError("give at least 6 characters of the session id");
+    appendEvent(() => ({ type: "run.claim", claim }));
+}
+/** Human answers and comments newer than `afterSeq`, on cards that are not closed. */
+export function inboxFrom(events, afterSeq, filter) {
+    const state = fold(events);
+    const out = [];
+    for (const ev of events) {
+        if (ev.seq <= afterSeq)
+            continue;
+        if (ev.type !== "card.answer" && ev.type !== "card.comment")
+            continue;
+        if (ev.by !== HUMAN)
+            continue;
+        const card = state.cards.get(ev.card);
+        if (!card || card.status === "closed")
+            continue;
+        if (filter.project && card.project !== filter.project)
+            continue;
+        if (filter.card && card.id !== filter.card)
+            continue;
+        if (ev.type === "card.answer") {
+            out.push({
+                seq: ev.seq,
+                at: ev.ts,
+                kind: "answer",
+                card,
+                by: ev.by,
+                choice: ev.choice,
+                choiceText: ev.choice !== undefined ? card.options?.[ev.choice - 1] : undefined,
+                comment: ev.comment,
+                attach: ev.attach,
+            });
+        }
+        else {
+            out.push({ seq: ev.seq, at: ev.ts, kind: "comment", card, by: ev.by, comment: ev.text });
+        }
+    }
+    return out;
+}
+export function consumerName(opts) {
+    return opts.as || opts.project || (opts.card ? `card-${opts.card}` : "default");
+}
+export function readInbox(consumer, filter, advance) {
+    const events = readEvents();
+    const items = inboxFrom(events, readCursor(consumer), filter);
+    const last = items[items.length - 1];
+    if (advance && last)
+        writeCursor(consumer, last.seq);
+    return items;
+}
+/**
+ * Block until the consumer has something in its inbox, or the timeout passes.
+ * Returns the items (cursor advanced) or [] on timeout.
+ */
+export async function waitInbox(consumer, filter, timeoutMs, pollMs = 1000) {
+    const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : Infinity;
+    let watcher;
+    let wake;
+    try {
+        const dir = path.dirname(eventsPath());
+        fs.mkdirSync(dir, { recursive: true });
+        watcher = fs.watch(dir, () => wake?.());
+    }
+    catch {
+        watcher = undefined; // polling alone still works
+    }
+    try {
+        for (;;) {
+            const items = readInbox(consumer, filter, true);
+            if (items.length)
+                return items;
+            const left = deadline - Date.now();
+            if (left <= 0)
+                return [];
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, Math.min(pollMs, left));
+                wake = () => {
+                    clearTimeout(t);
+                    resolve();
+                };
+            });
+            wake = undefined;
+        }
+    }
+    finally {
+        watcher?.close();
+    }
+}
+//# sourceMappingURL=ops.js.map