@alphacoder-v0/pi-loops 0.20.0 → 0.22.0

package/src/inbox.ts

@@ -9,7 +9,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { withFileLock, writeFileAtomic } from "./lock.ts";
-import { INBOX_TEXT_MAX_CHARS, capChars } from "./protocol.ts";
+import { INBOX_TEXT_MAX_CHARS, type FindingKind, capChars } from "./protocol.ts";
 import { newId } from "./store.ts";
 import { stamp } from "./schedule.ts";
 
@@ -18,25 +18,52 @@ export type InboxStatus = "new" | "claimed" | "dismissed";
 /** Past this the inbox drops its oldest triaged entries (docs/configuration.md). */
 export const INBOX_ROTATE_BYTES = 1_000_000;
 
+/**
+ * A finding, in memory and on disk: the ten fields of the contract first, in their order, then
+ * pi-loops' own, which no interface names and which a line may be missing. This is the one shape —
+ * a line of `inbox.jsonl` is `JSON.stringify` of this, and `pi-loops inbox --json` is the first ten
+ * fields of it.
+ */
 export interface InboxEntry {
 	id: string;
-	createdAt: string;
+	/** RFC 3339, carrying this machine's UTC offset (`stamp()`). */
+	created_at: string;
+	status: InboxStatus;
+	/**
+	 * `checkpoint` when the finding asks a person to decide (`protocol.findingKind`, read off the
+	 * text when the run's findings are appended), `news` otherwise. Checkpoints are listed first,
+	 * counted apart.
+	 */
+	kind: FindingKind;
 	/** Bounded origin label, e.g. "cron:check-issues" or "cron:cron-1a2b3c4d". */
 	source: string;
-	text: string;
-	runId: string;
-	jobId: string;
+	run_id: string;
 	cwd: string;
+	text: string;
+	/** true = passed the checker; false = checker dropped it (never appended); null = no checker / unreviewed. */
+	verified: boolean | null;
+	/**
+	 * Why a person dismissed it, when they said; null when they did not. A bare dismiss is silent; a
+	 * reason goes back to the loop that reported the finding, in its next run's prompt
+	 * (`Inbox.feedbackFor`).
+	 */
+	dismiss_reason: string | null;
+	job_id?: string;
 	/** Session that owned the loop when it reported; loops are machine-global here. */
-	sessionId?: string;
-	status: InboxStatus;
-	claimedBy?: string;
-	/** true = passed the checker; false = checker dropped it (never appended); undefined = no checker / unreviewed. */
-	verified?: boolean;
+	session_id?: string;
+	claimed_by?: string;
 	/** Checker's reason when it kept a finding, if it gave one. */
-	verifiedReason?: string;
+	verified_reason?: string;
+	/** When it was dismissed — what decides whether the loop's next run is shown the reason. */
+	dismissed_at?: string;
 }
 
+/** The fields a finding is, in their order — CONTRACT.md §2.2 and docs/downstream.md §3. */
+export const FINDING_FIELDS = ["id", "created_at", "status", "kind", "source", "run_id", "cwd", "text", "verified", "dismiss_reason"] as const;
+
+/** Reasons longer than a finding are a paragraph, and the prompt they go into is capped. */
+const DISMISS_REASON_MAX_CHARS = INBOX_TEXT_MAX_CHARS;
+
 export class Inbox {
 	readonly file: string;
 	private readonly lockPath: string;
@@ -46,14 +73,24 @@ export class Inbox {
 		this.lockPath = path.join(dir, "inbox.lock");
 	}
 
-	async append(entry: Omit<InboxEntry, "id" | "createdAt" | "status">): Promise<InboxEntry> {
+	async append(entry: Omit<InboxEntry, "id" | "created_at" | "status" | "kind" | "verified" | "dismiss_reason"> & Partial<Pick<InboxEntry, "kind" | "verified">>): Promise<InboxEntry> {
+		// Built in `FINDING_FIELDS` order, then pi-loops' own: the line is this object as it stands.
 		const full: InboxEntry = {
 			id: newId("inb"), // inb-<32 hex>, the shape every other id in pi-loops has
-			createdAt: stamp(),
-			...entry,
+			created_at: stamp(),
+			status: "new",
+			kind: entry.kind ?? "news",
 			source: capChars(entry.source, 80),
+			run_id: entry.run_id,
+			cwd: entry.cwd,
 			text: capChars(entry.text.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS),
-			status: "new",
+			verified: entry.verified ?? null,
+			dismiss_reason: null,
+			job_id: entry.job_id,
+			session_id: entry.session_id,
+			claimed_by: entry.claimed_by,
+			verified_reason: entry.verified_reason,
+			dismissed_at: entry.dismissed_at,
 		};
 		fs.mkdirSync(path.dirname(this.file), { recursive: true });
 		// Under the same lock as the triage rewrites: findings are appended by every pi window, the
@@ -62,7 +99,7 @@ export class Inbox {
 		// The lock is awaited, never spun on: a leftover lock directory from a killed process would
 		// otherwise block this process's event loop for the whole stale window.
 		await withFileLock(this.lockPath, () => {
-			fs.appendFileSync(this.file, `${JSON.stringify(toDisk(full))}\n`, "utf8");
+			fs.appendFileSync(this.file, `${JSON.stringify(full)}\n`, "utf8");
 			this.rotate();
 		});
 		return full;
@@ -103,7 +140,7 @@ export class Inbox {
 		for (const line of text.split("\n")) {
 			if (!line.trim()) continue;
 			try {
-				const e = fromDisk(JSON.parse(line));
+				const e = readFinding(JSON.parse(line));
 				if (e && typeof e.id === "string" && typeof e.text === "string") out.push(e);
 			} catch {
 				/* skip corrupt line */
@@ -112,8 +149,14 @@ export class Inbox {
 		return out;
 	}
 
+	/**
+	 * What is waiting, in triage order: the checkpoints first — a decision a person owes — then the
+	 * news, each group in the order it arrived. `/inbox` numbers this list and `claim`/`dismiss`
+	 * resolve numbers against it, so the order is decided once, here.
+	 */
 	listNew(): InboxEntry[] {
-		return this.list().filter((e) => e.status === "new");
+		const fresh = this.list().filter((e) => e.status === "new");
+		return [...fresh.filter((e) => e.kind === "checkpoint"), ...fresh.filter((e) => e.kind !== "checkpoint")];
 	}
 
 	/** Count of new entries; 0 on any error (badge path must never throw). */
@@ -125,13 +168,28 @@ export class Inbox {
 		}
 	}
 
-	async setStatus(id: string, status: InboxStatus, claimedBy?: string): Promise<InboxEntry | undefined> {
+	/** How many of the new entries are checkpoints; 0 on any error, like `newCount`. */
+	decisionCount(): number {
+		try {
+			return this.listNew().filter((e) => e.kind === "checkpoint").length;
+		} catch {
+			return 0;
+		}
+	}
+
+	/** `reason` is only read for a dismiss: what the person said, kept for the loop's next run. */
+	async setStatus(id: string, status: InboxStatus, claimedBy?: string, reason?: string): Promise<InboxEntry | undefined> {
 		return withFileLock(this.lockPath, () => {
 			const entries = this.list();
 			const entry = entries.find((e) => e.id === id);
 			if (!entry) return undefined;
 			entry.status = status;
-			if (claimedBy) entry.claimedBy = claimedBy;
+			if (claimedBy) entry.claimed_by = claimedBy;
+			if (status === "dismissed") {
+				entry.dismissed_at = stamp();
+				const why = reason?.replace(/\s+/g, " ").trim();
+				if (why) entry.dismiss_reason = capChars(why, DISMISS_REASON_MAX_CHARS);
+			}
 			this.rewrite(entries);
 			return entry;
 		});
@@ -141,10 +199,12 @@ export class Inbox {
 	async dismissAllNew(match?: (entry: InboxEntry) => boolean): Promise<number> {
 		return withFileLock(this.lockPath, () => {
 			const entries = this.list();
+			const at = stamp();
 			let changed = 0;
 			for (const e of entries) {
 				if (e.status === "new" && (!match || match(e))) {
 					e.status = "dismissed";
+					e.dismissed_at = at;
 					changed++;
 				}
 			}
@@ -153,35 +213,30 @@ export class Inbox {
 		});
 	}
 
+	/**
+	 * What a person told one loop by dismissing its findings with a reason, since `since` (the start
+	 * of the loop's previous run: everything before it was already shown to that run). Oldest first.
+	 * A dismiss without a reason is not feedback — "not interesting" is not something the next run can
+	 * act on, and the person did not ask it to — so it is not here. A reason dismissed before pi-loops
+	 * stamped `dismissed_at` has no time to compare and is left out too.
+	 */
+	feedbackFor(jobId: string, since?: string): InboxEntry[] {
+		const after = since ? Date.parse(since) : Number.NEGATIVE_INFINITY;
+		return this.list().filter((e) => e.job_id === jobId && e.status === "dismissed" && !!e.dismiss_reason && !!e.dismissed_at && Date.parse(e.dismissed_at) > after);
+	}
+
 	private rewrite(entries: InboxEntry[]): void {
-		writeFileAtomic(this.file, entries.map((e) => JSON.stringify(toDisk(e))).join("\n") + (entries.length ? "\n" : ""));
+		writeFileAtomic(this.file, entries.map((e) => JSON.stringify(e)).join("\n") + (entries.length ? "\n" : ""));
 	}
 }
 
 /**
- * On disk the record shape is `{id, created_at, source, text, trace_id, session_id,
- * status}` — plus pi-loops' extras (`job_id`, `cwd`, `claimed_by`, `verified`, `verified_reason`),
- * so a reader of that shape can consume it. Lines written by pi-loops ≤ 0.1.2 (camelCase)
- * are still understood.
+ * A line as an entry. For a line this version wrote it is the identity; the two older shapes it
+ * still reads are pi-loops ≤ 0.1.2 (camelCase throughout) and the shape written until 0.21.0
+ * (`trace_id` for the run id, absent optional keys, no `kind` on news). A line in either is
+ * rewritten in this shape the next time its status changes.
  */
-function toDisk(e: InboxEntry): Record<string, unknown> {
-	return {
-		id: e.id,
-		created_at: e.createdAt,
-		source: e.source,
-		text: e.text,
-		trace_id: e.runId,
-		session_id: e.sessionId ?? null,
-		status: e.status,
-		job_id: e.jobId,
-		cwd: e.cwd,
-		...(e.claimedBy !== undefined ? { claimed_by: e.claimedBy } : {}),
-		...(e.verified !== undefined ? { verified: e.verified } : {}),
-		...(e.verifiedReason !== undefined ? { verified_reason: e.verifiedReason } : {}),
-	};
-}
-
-function fromDisk(raw: any): InboxEntry | undefined {
+function readFinding(raw: any): InboxEntry | undefined {
 	if (!raw || typeof raw !== "object") return undefined;
 	const pick = <T>(...keys: string[]): T | undefined => {
 		for (const k of keys) if (raw[k] !== undefined && raw[k] !== null) return raw[k] as T;
@@ -190,17 +245,20 @@ function fromDisk(raw: any): InboxEntry | undefined {
 	const status = pick<string>("status");
 	return {
 		id: String(raw.id ?? ""),
-		createdAt: pick<string>("created_at", "createdAt") ?? "",
+		created_at: pick<string>("created_at", "createdAt") ?? "",
+		status: status === "claimed" || status === "dismissed" ? status : "new",
+		kind: raw.kind === "checkpoint" ? "checkpoint" : "news",
 		source: pick<string>("source") ?? "",
-		text: String(raw.text ?? ""),
-		runId: pick<string>("trace_id", "runId") ?? "",
-		jobId: pick<string>("job_id", "jobId") ?? "",
+		run_id: pick<string>("run_id", "trace_id", "runId") ?? "",
 		cwd: pick<string>("cwd") ?? "",
-		sessionId: pick<string>("session_id", "sessionId"),
-		status: status === "claimed" || status === "dismissed" ? status : "new",
-		claimedBy: pick<string>("claimed_by", "claimedBy"),
-		verified: pick<boolean>("verified"),
-		verifiedReason: pick<string>("verified_reason", "verifiedReason"),
+		text: String(raw.text ?? ""),
+		verified: pick<boolean>("verified") ?? null,
+		dismiss_reason: pick<string>("dismiss_reason") ?? null,
+		job_id: pick<string>("job_id", "jobId"),
+		session_id: pick<string>("session_id", "sessionId"),
+		claimed_by: pick<string>("claimed_by", "claimedBy"),
+		verified_reason: pick<string>("verified_reason", "verifiedReason"),
+		dismissed_at: pick<string>("dismissed_at"),
 	};
 }
 
@@ -222,11 +280,16 @@ export function belongsToProject(entry: InboxEntry, cwd: string, sameProject: (a
 	return !entry.cwd || sameProject(entry.cwd, cwd);
 }
 
-/** Resolve "<n>" (1-based in the new list) or an id / unique id prefix. */
-export function resolveInboxRef(entries: InboxEntry[], ref: string): InboxEntry | undefined {
+/**
+ * Resolve an id or a unique id prefix — and, with `ordinals: true`, "<n>", the 1-based position in
+ * `entries`. A number is a position in a list the caller printed, so only a caller that printed one
+ * may ask for it (`/inbox`, which numbers what it shows); everywhere else a finding is named by its
+ * id, and an all-digit ref resolves to nothing, as an unknown id does.
+ */
+export function resolveInboxRef(entries: InboxEntry[], ref: string, opts?: { ordinals?: boolean }): InboxEntry | undefined {
 	const trimmed = ref.trim();
 	if (!trimmed) return undefined;
-	if (/^\d+$/.test(trimmed)) return entries[Number(trimmed) - 1];
+	if (/^\d+$/.test(trimmed)) return opts?.ordinals ? entries[Number(trimmed) - 1] : undefined;
 	const matches = entries.filter((e) => e.id === trimmed || e.id.startsWith(trimmed));
 	return matches.length === 1 ? matches[0] : undefined;
 }

package/src/job-signal.ts

@@ -0,0 +1,78 @@
+/**
+ * What a loop's runs came to: findings filed, and what a person did with them.
+ *
+ * `/cron cost` has always said what a loop spends; nothing said whether anyone wanted what it
+ * bought. A loop whose every finding is dismissed is noise at whatever price, and a loop that has
+ * found nothing for a month is either watching a quiet thing or watching the wrong one. Both are
+ * questions about the run log and the inbox together, answerable without a scheduler or a clock —
+ * the shape of `job-health.ts`, for the other half of "is this loop worth keeping".
+ */
+import type { InboxEntry } from "./inbox.ts";
+import type { RunRecord } from "./store.ts";
+
+export interface LoopSignal {
+	/** Runs that finished in the window (failed ones included: they cost, and they are what `quiet` is measured against). */
+	runs: number;
+	/** Findings that reached the inbox in the window, from the run log. */
+	findings: number;
+	/** Of the findings the inbox still holds from this window: claimed, dismissed, and dismissed with a reason. */
+	claimed: number;
+	dismissed: number;
+	dismissedWithReason: number;
+	/** Consecutive finished runs, newest backwards over the whole log, that found nothing. Not bounded by the window. */
+	quiet: number;
+}
+
+/** How long the `/cron` listing looks back. Long enough for a weekly loop to have a few runs in it. */
+export const SIGNAL_WINDOW_MS = 30 * 86_400_000;
+/** From here `/cron` marks a loop `quiet ×N`: three empty runs is where a loop stops looking merely between events. */
+export const QUIET_MARK_AFTER = 3;
+
+/**
+ * `runs` is the run log, any order; `inbox` the whole inbox. Both are filtered here so a caller can
+ * hand over what it already loaded. `sinceMs` bounds the counts; `quiet` is counted from the newest
+ * run backwards regardless of it, because a streak is a streak whenever it started.
+ */
+export function loopSignal(jobId: string, runs: RunRecord[], inbox: InboxEntry[], sinceMs: number): LoopSignal {
+	const own = runs.filter((r) => r.jobId === jobId);
+	const at = (iso: string) => Date.parse(iso);
+	const inWindow = own.filter((r) => {
+		const t = at(r.finishedAt || r.startedAt);
+		return Number.isFinite(t) && t >= sinceMs;
+	});
+	const findings = inWindow.reduce((n, r) => n + (r.findings ?? 0), 0);
+	let claimed = 0;
+	let dismissed = 0;
+	let dismissedWithReason = 0;
+	for (const e of inbox) {
+		if (e.job_id !== jobId) continue;
+		const t = at(e.created_at);
+		if (!Number.isFinite(t) || t < sinceMs) continue;
+		if (e.status === "claimed") claimed++;
+		else if (e.status === "dismissed") {
+			dismissed++;
+			if (e.dismiss_reason) dismissedWithReason++;
+		}
+	}
+	// The log is appended in finishing order, so the tail is the newest; sort anyway in case a
+	// caller merged two sources. A run that failed found nothing, and counts toward the streak:
+	// a loop that has been erroring for a week is quiet in the sense that matters here too, and
+	// `job-health.ts` already says why.
+	const ordered = [...own].sort((a, b) => at(a.finishedAt || a.startedAt) - at(b.finishedAt || b.startedAt));
+	let quiet = 0;
+	for (let i = ordered.length - 1; i >= 0 && (ordered[i].findings ?? 0) === 0; i--) quiet++;
+	return { runs: inWindow.length, findings, claimed, dismissed, dismissedWithReason, quiet };
+}
+
+/**
+ * `9 findings · 2 claimed · 7 dismissed` — the counts a person reads a loop's worth off. Nothing
+ * when no finding was filed: a loop that found nothing has nothing to be judged by yet, and
+ * `quiet ×N` says that part.
+ */
+export function signalSummary(s: LoopSignal): string | undefined {
+	if (!s.findings) return undefined;
+	const parts = [`${s.findings} finding${s.findings === 1 ? "" : "s"}`];
+	if (s.claimed) parts.push(`${s.claimed} claimed`);
+	if (s.dismissed) parts.push(`${s.dismissed} dismissed${s.dismissedWithReason ? ` (${s.dismissedWithReason} with a reason)` : ""}`);
+	return parts.join(" · ");
+}