@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/follow-up-queue.mjs

@@ -0,0 +1,211 @@
+/** Durable FIFO follow-up queue helpers. */
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import { newFollowUpId } from "./ids.mjs";
+import { truncate } from "./heuristics.mjs";
+import { withViewLockSync } from "./locks.mjs";
+import * as P from "./paths.mjs";
+
+/**
+ * Run a queue mutation under the view lock, translating any failure (lock
+ * unavailable, fs errors inside the mutation) into {ok:false} so callers on
+ * the {ok} convention never see a throw (issue #33).
+ * @template T
+ * @param {string} root
+ * @param {string} viewId
+ * @param {() => T} fn
+ * @returns {T | { ok: false, error: string }}
+ */
+function lockedQueueOp(root, viewId, fn) {
+	try {
+		return withViewLockSync(root, viewId, "queue", fn);
+	} catch (err) {
+		return { ok: false, error: `follow-up queue lock unavailable: ${err instanceof Error ? err.message : String(err)}` };
+	}
+}
+
+/** @param {string} viewId @param {number} [now] @returns {import("./types.mjs").FollowUpQueue} */
+export function emptyFollowUpQueue(viewId, now = Date.now()) {
+	return { version: 1, viewId, nextSeq: 1, updatedAt: now, items: [] };
+}
+
+/** @param {string} root @param {string} viewId */
+export function readFollowUpQueue(root, viewId) {
+	return normalizeQueue(readJson(P.followUpQueuePath(root, viewId), null), viewId);
+}
+
+/** @param {string} root @param {import("./types.mjs").FollowUpQueue} queue */
+export function writeFollowUpQueue(root, queue) {
+	const normalized = normalizeQueue(queue, queue.viewId);
+	normalized.updatedAt = Date.now();
+	atomicWriteJson(P.followUpQueuePath(root, normalized.viewId), normalized);
+	return normalized;
+}
+
+/** @param {import("./types.mjs").FollowUpQueue} queue @returns {import("./types.mjs").FollowUpSummary} */
+export function summarizeFollowUpQueue(queue) {
+	const q = normalizeQueue(queue, queue?.viewId ?? "");
+	const queued = q.items.filter((i) => i.status === "queued");
+	const claimed = q.items.filter((i) => i.status === "claimed");
+	const last = [...queued].sort((a, b) => b.createdAt - a.createdAt)[0] ?? null;
+	return {
+		queuedCount: queued.length,
+		claimedCount: claimed.length,
+		lastQueuedAt: last?.createdAt ?? null,
+		lastQueuedPreview: last ? truncate(last.text, 120) : null,
+	};
+}
+
+/** @param {string} root @param {string} viewId @param {string} text @param {{ kind?: import("./types.mjs").FollowUpKind, source?: string, delivery?: "auto"|"now"|"queue" }} [opts] */
+export function enqueueFollowUp(root, viewId, text, opts = {}) {
+	const clean = String(text || "").trim();
+	if (!clean) return { ok: false, error: "Empty follow-up" };
+	return lockedQueueOp(root, viewId, () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const now = Date.now();
+		const item = {
+			id: newFollowUpId(),
+			seq: queue.nextSeq,
+			viewId,
+			kind: opts.kind ?? "reply",
+			text: clean,
+			createdAt: now,
+			updatedAt: now,
+			status: "queued",
+			source: opts.source ?? "user",
+			delivery: opts.delivery ?? "auto",
+			runId: null,
+			claimedAt: null,
+			completedAt: null,
+			attempts: 0,
+			error: null,
+		};
+		queue.nextSeq += 1;
+		queue.items.push(item);
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null }} [opts] */
+export function claimNextFollowUp(root, viewId, opts = {}) {
+	return lockedQueueOp(root, viewId, () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const item = queue.items.filter((i) => i.status === "queued").sort((a, b) => a.seq - b.seq)[0];
+		if (!item) return { ok: false, error: "No queued follow-up" };
+		item.status = "claimed";
+		item.claimedAt = Date.now();
+		item.updatedAt = item.claimedAt;
+		item.attempts = (item.attempts ?? 0) + 1;
+		item.runId = opts.runId ?? item.runId ?? null;
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId @param {{ runId?: string|null }} [opts] */
+export function completeFollowUp(root, viewId, itemId, opts = {}) {
+	return updateItem(root, viewId, itemId, (item) => {
+		item.status = "completed";
+		item.completedAt = Date.now();
+		item.updatedAt = item.completedAt;
+		if (opts.runId) item.runId = opts.runId;
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId @param {string} error */
+export function failFollowUp(root, viewId, itemId, error) {
+	return updateItem(root, viewId, itemId, (item) => {
+		item.status = "failed";
+		item.error = String(error || "Follow-up failed");
+		item.updatedAt = Date.now();
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId */
+export function releaseFollowUp(root, viewId, itemId) {
+	return updateItem(root, viewId, itemId, (item) => {
+		item.status = "queued";
+		item.claimedAt = null;
+		item.updatedAt = Date.now();
+	});
+}
+
+/** @param {string} root @param {string} viewId */
+export function removeLastFollowUp(root, viewId) {
+	return lockedQueueOp(root, viewId, () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const queued = queue.items.filter((i) => i.status === "queued").sort((a, b) => b.seq - a.seq);
+		const last = queued[0];
+		if (!last) return { ok: false, error: "No queued follow-up" };
+		last.status = "cancelled";
+		last.updatedAt = Date.now();
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item: last, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId */
+export function clearQueuedFollowUps(root, viewId) {
+	return lockedQueueOp(root, viewId, () => {
+		const queue = readFollowUpQueue(root, viewId);
+		let cancelled = 0;
+		for (const item of queue.items) {
+			if (item.status === "queued") {
+				item.status = "cancelled";
+				item.updatedAt = Date.now();
+				cancelled += 1;
+			}
+		}
+		writeFollowUpQueue(root, queue);
+		return { ok: true, cancelled, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {string} root @param {string} viewId @param {string} itemId @param {(item: import("./types.mjs").FollowUpItem) => void} mutate */
+function updateItem(root, viewId, itemId, mutate) {
+	return lockedQueueOp(root, viewId, () => {
+		const queue = readFollowUpQueue(root, viewId);
+		const item = queue.items.find((i) => i.id === itemId);
+		if (!item) return { ok: false, error: "Unknown follow-up" };
+		mutate(item);
+		writeFollowUpQueue(root, queue);
+		return { ok: true, item, summary: summarizeFollowUpQueue(queue) };
+	});
+}
+
+/** @param {any} queue @param {string} viewId @returns {import("./types.mjs").FollowUpQueue} */
+function normalizeQueue(queue, viewId) {
+	const base = emptyFollowUpQueue(viewId || queue?.viewId || "");
+	if (!queue || typeof queue !== "object") return base;
+	const items = Array.isArray(queue.items) ? queue.items.map((item, idx) => normalizeItem(item, viewId, idx + 1)) : [];
+	return {
+		version: 1,
+		viewId: typeof queue.viewId === "string" ? queue.viewId : base.viewId,
+		nextSeq: Math.max(Number(queue.nextSeq ?? 1) || 1, items.reduce((m, i) => Math.max(m, i.seq + 1), 1)),
+		updatedAt: Number(queue.updatedAt ?? Date.now()) || Date.now(),
+		items,
+	};
+}
+
+/** @param {any} item @param {string} viewId @param {number} seq */
+function normalizeItem(item, viewId, seq) {
+	const now = Date.now();
+	const status = ["queued", "claimed", "completed", "failed", "cancelled"].includes(item?.status) ? item.status : "queued";
+	return {
+		id: typeof item?.id === "string" ? item.id : newFollowUpId(),
+		seq: Number(item?.seq ?? seq) || seq,
+		viewId: typeof item?.viewId === "string" ? item.viewId : viewId,
+		kind: ["reply", "plan_request", "plan_approval", "plan_change"].includes(item?.kind) ? item.kind : "reply",
+		text: String(item?.text ?? ""),
+		createdAt: Number(item?.createdAt ?? now) || now,
+		updatedAt: Number(item?.updatedAt ?? now) || now,
+		status,
+		source: typeof item?.source === "string" ? item.source : "user",
+		delivery: ["auto", "now", "queue"].includes(item?.delivery) ? item.delivery : "auto",
+		runId: typeof item?.runId === "string" ? item.runId : null,
+		claimedAt: Number.isFinite(item?.claimedAt) ? item.claimedAt : null,
+		completedAt: Number.isFinite(item?.completedAt) ? item.completedAt : null,
+		attempts: Number(item?.attempts ?? 0) || 0,
+		error: typeof item?.error === "string" ? item.error : null,
+	};
+}

package/packages/board/src/core/foreground-preview-cache.mjs

@@ -0,0 +1,117 @@
+/**
+ * Process-local read-your-writes cache for foreground state projections
+ * (issue #113).
+ *
+ * Foreground turns are mirrored into state.json through the detached View
+ * State Coordinator: `message_end` sets `latestAssistantPreview` /
+ * `lastAgentActivityAt` and fires a fire-and-forget `sync_foreground` command;
+ * the coordinator journals + fsyncs before materializing the file. The next
+ * event (`agent_end`, ~7ms later) rebuilds its in-memory status from the
+ * still-stale state.json, derives the "Needs instructions" fallback summary and
+ * overwrites the fresher projection that was still in flight.
+ *
+ * This cache restores read-your-writes for the two fields whose legitimate
+ * transitions are "empty → non-empty" and "old non-empty → new non-empty",
+ * keyed on `lastAgentActivityAt` as the freshness signal (message_end stamps
+ * it with `now`):
+ *
+ * - `remember` keeps the strictly-freshest projection: an entry whose
+ *   timestamp is older than the stored one never degrades it (the stale
+ *   agent_end rebuild must not clobber a newer in-flight message_end value);
+ *   an older or timestampless projection only fills gaps.
+ * - `backfill` adopts BOTH cached fields when the cached timestamp is strictly
+ *   newer than the rebuilt status's (including a timestampless/legacy
+ *   rebuild) — the disk snapshot is stale. Otherwise it fills only empty
+ *   fields: the materialized file stays authoritative when it is newer or
+ *   equally aged, so a value another writer persisted is never resurrected
+ *   over by an older cached one.
+ *
+ * Module-level by necessity: `serviceFor()` creates a new service instance per
+ * call (src/index.ts), so a per-instance cache would be discarded between
+ * events.
+ */
+
+/** @typedef {{ latestAssistantPreview: string, lastAgentActivityAt: number|null }} KnownForegroundFields */
+
+/**
+ * @returns {{
+ *   remember: (viewId: string, projection: { latestAssistantPreview?: unknown, lastAgentActivityAt?: unknown }) => void,
+ *   backfill: (viewId: string, status: { latestAssistantPreview?: unknown, lastAgentActivityAt?: unknown }) => boolean,
+ *   forget: (viewId: string) => boolean,
+ *   clear: () => void,
+ *   size: () => number,
+ * }}
+ */
+export function createForegroundPreviewCache() {
+	/** @type {Map<string, KnownForegroundFields>} */
+	const known = new Map();
+
+	function remember(viewId, projection) {
+		if (!viewId || !projection) return;
+		const preview = projection.latestAssistantPreview;
+		const activityAt = projection.lastAgentActivityAt;
+		const hasPreview = typeof preview === "string" && preview.length > 0;
+		const hasActivity = activityAt != null;
+		if (!hasPreview && !hasActivity) return;
+		const entry = known.get(viewId) ?? { latestAssistantPreview: "", lastAgentActivityAt: null };
+		const isNewer = hasActivity && (entry.lastAgentActivityAt == null || activityAt > entry.lastAgentActivityAt);
+		if (isNewer) {
+			// A strictly fresher projection wins wholesale; an empty preview still
+			// never overwrites a known non-empty one.
+			if (hasPreview) entry.latestAssistantPreview = preview;
+			entry.lastAgentActivityAt = activityAt;
+		} else {
+			// Older or timestampless: gap-fill only, never degrade the entry.
+			if (hasPreview && !entry.latestAssistantPreview) entry.latestAssistantPreview = preview;
+			if (hasActivity && entry.lastAgentActivityAt == null) entry.lastAgentActivityAt = activityAt;
+		}
+		known.set(viewId, entry);
+	}
+
+	function backfill(viewId, status) {
+		if (!viewId || !status) return false;
+		const entry = known.get(viewId);
+		if (!entry) return false;
+		const statusAt = status.lastAgentActivityAt ?? null;
+		let changed = false;
+		if (entry.lastAgentActivityAt != null && (statusAt == null || entry.lastAgentActivityAt > statusAt)) {
+			// The disk rebuild is a stale snapshot (or a timestampless legacy row):
+			// the freshest value this process projected wins wholesale.
+			if (entry.latestAssistantPreview && status.latestAssistantPreview !== entry.latestAssistantPreview) {
+				status.latestAssistantPreview = entry.latestAssistantPreview;
+				changed = true;
+			}
+			if (statusAt !== entry.lastAgentActivityAt) {
+				status.lastAgentActivityAt = entry.lastAgentActivityAt;
+				changed = true;
+			}
+			return changed;
+		}
+		if (entry.latestAssistantPreview && !status.latestAssistantPreview) {
+			status.latestAssistantPreview = entry.latestAssistantPreview;
+			changed = true;
+		}
+		if (entry.lastAgentActivityAt != null && statusAt == null) {
+			status.lastAgentActivityAt = entry.lastAgentActivityAt;
+			changed = true;
+		}
+		return changed;
+	}
+
+	function forget(viewId) {
+		return known.delete(viewId);
+	}
+
+	function clear() {
+		known.clear();
+	}
+
+	function size() {
+		return known.size;
+	}
+
+	return { remember, backfill, forget, clear, size };
+}
+
+/** Shared cache used by the runtime service (module-level: see module doc). */
+export const foregroundPreviewCache = createForegroundPreviewCache();

package/packages/board/src/core/foreground-projection-cache.mjs

@@ -0,0 +1,99 @@
+/**
+ * Process-local read-your-writes cache for foreground status projections
+ * (issue #225).
+ *
+ * `syncRowEvent` rebuilds its status from `state.json` on every event, while
+ * `writeForegroundState` is fire-and-forget: two events can have two
+ * `sync_foreground` commands in flight, and an older projection can materialize
+ * last. Because the rebuilt status carries no freshness signal, the next event
+ * reduces onto the stale state and writes it back — a cleared question comes
+ * back as `needs_input` until a terminal event lands.
+ *
+ * This cache stores the freshest whitelisted status fields with a strictly
+ * increasing per-view stamp (`nextStamp`), so a disk rebuild that is older than
+ * the last write is corrected before the new event is reduced.
+ *
+ * Module-level by necessity: `serviceFor()` creates a new service instance per
+ * call (src/index.ts), so a per-instance cache would be discarded between
+ * events.
+ */
+
+/** Fields a cached snapshot may restore on a stale rebuild. */
+const CACHED_FIELDS = [
+	"semanticState",
+	"processState",
+	"summary",
+	"currentTool",
+	"question",
+	"pendingQuestions",
+	"error",
+	"lastActivityAt",
+	"latestAssistantPreview",
+	"lastAgentActivityAt",
+];
+
+/** @param {any} value */
+function cloneValue(value) {
+	if (value === null || typeof value !== "object") return value;
+	return JSON.parse(JSON.stringify(value));
+}
+
+/** @param {any} status */
+function snapshot(status) {
+	/** @type {Record<string, unknown>} */
+	const fields = {};
+	for (const key of CACHED_FIELDS) fields[key] = cloneValue(status?.[key]);
+	return fields;
+}
+
+export function createForegroundProjectionCache() {
+	/** @type {Map<string, { stamp: number, fields: Record<string, unknown> }>} */
+	const known = new Map();
+	/** @type {Map<string, number>} */
+	const stamps = new Map();
+
+	function nextStamp(viewId) {
+		const stamp = Math.max(Date.now(), (stamps.get(viewId) ?? 0) + 1);
+		stamps.set(viewId, stamp);
+		return stamp;
+	}
+
+	function remember(viewId, status, stamp) {
+		if (!viewId || !status || typeof stamp !== "number" || !Number.isFinite(stamp)) return;
+		known.set(viewId, { stamp, fields: snapshot(status) });
+	}
+
+	function adopt(viewId, status) {
+		if (!viewId || !status) return false;
+		const entry = known.get(viewId);
+		if (!entry) return false;
+		const at = typeof status.updatedAt === "number" ? status.updatedAt : 0;
+		if (entry.stamp <= at) return false;
+		for (const key of CACHED_FIELDS) status[key] = cloneValue(entry.fields[key]);
+		status.updatedAt = entry.stamp;
+		return true;
+	}
+
+	function forget(viewId) {
+		stamps.delete(viewId);
+		return known.delete(viewId);
+	}
+
+	function clear() {
+		known.clear();
+		stamps.clear();
+	}
+
+	function size() {
+		return known.size;
+	}
+
+	return { nextStamp, remember, adopt, forget, clear, size };
+}
+
+/**
+ * Shared cache used by the runtime service (module-level: see module doc).
+ * Keyed by view id only, matching the preview cache: production view ids are generated
+ * and never reused, and tests clear the cache per case.
+ */
+export const foregroundProjectionCache = createForegroundProjectionCache();

package/packages/board/src/core/frame-witness-update.mjs

@@ -0,0 +1,35 @@
+/**
+ * Coalesce host.json frame-witness summary writes only. S/F/A protocol records
+ * stay synchronous; this scheduler controls only the secondary host summary.
+ */
+export function createFrameWitnessSummaryScheduler({
+	delayMs = 100,
+	publish,
+	setTimeoutFn = globalThis.setTimeout,
+	clearTimeoutFn = globalThis.clearTimeout,
+}) {
+	if (typeof publish !== "function") throw new TypeError("publish is required");
+	let timer = null;
+	const cancel = () => {
+		if (timer === null) return;
+		clearTimeoutFn(timer);
+		timer = null;
+	};
+	const flush = () => {
+		cancel();
+		publish();
+	};
+	const schedule = () => {
+		if (timer !== null) return;
+		if (delayMs <= 0) {
+			publish();
+			return;
+		}
+		timer = setTimeoutFn(() => {
+			timer = null;
+			publish();
+		}, delayMs);
+		timer.unref?.();
+	};
+	return { schedule, flush, cancel };
+}