@zhuxixi/pi-agent-board 0.3.0

package/src/core/store.mjs

@@ -0,0 +1,308 @@
+/**
+ * High-level store operations over the agent-board layout (see paths.mjs).
+ * Roster/meta/state/status read+write, row listing, and view creation/recovery.
+ * Used by the extension, the runner, and tests. Pure node, no Pi imports.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { atomicWriteJson, ensureDir, readJson } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+import { isAlive } from "./pid.mjs";
+import { readDiagnosticSummary } from "./diagnostics.mjs";
+import { readEvidence, summarizeEvidence } from "./evidence.mjs";
+import { readFollowUpQueue, summarizeFollowUpQueue } from "./follow-up-queue.mjs";
+import { readSteering, summarizeSteering } from "./steering.mjs";
+
+/** @typedef {import("./types.mjs").Roster} Roster */
+/** @typedef {import("./types.mjs").ViewMeta} ViewMeta */
+/** @typedef {import("./types.mjs").ViewState} ViewState */
+/** @typedef {import("./types.mjs").RunStatus} RunStatus */
+/** @typedef {import("./types.mjs").HostStatus} HostStatus */
+/** @typedef {import("./types.mjs").LaunchPrefs} LaunchPrefs */
+
+const META_VERSION = 1;
+
+// ---- roster ---------------------------------------------------------------
+
+/** @param {string} root @returns {Roster} */
+export function readRoster(root) {
+	return readJson(P.rosterPath(root), { version: 1, views: [] });
+}
+
+/** @param {string} root @param {Roster} roster */
+export function writeRoster(root, roster) {
+	atomicWriteJson(P.rosterPath(root), roster);
+}
+
+/** @param {string} root @param {string} viewId */
+export function addToRoster(root, viewId) {
+	const roster = readRoster(root);
+	if (!roster.views.includes(viewId)) {
+		roster.views.push(viewId);
+		writeRoster(root, roster);
+	}
+}
+
+/** @param {string} root @param {string} viewId */
+export function removeFromRoster(root, viewId) {
+	const roster = readRoster(root);
+	const next = roster.views.filter((v) => v !== viewId);
+	if (next.length !== roster.views.length) {
+		roster.version = roster.version ?? 1;
+		writeRoster(root, { version: roster.version, views: next });
+	}
+}
+
+/** @param {string} root @returns {LaunchPrefs} */
+export function readLaunchPrefs(root) {
+	return readJson(P.launchPrefsPath(root), {
+		version: 1,
+		cwd: null,
+		model: null,
+		thinkingLevel: null,
+		screenLogRetentionDays: null,
+		screenLogMaxSize: null,
+	});
+}
+
+/** @param {string} root @param {Partial<LaunchPrefs>} prefs */
+export function writeLaunchPrefs(root, prefs) {
+	atomicWriteJson(P.launchPrefsPath(root), {
+		version: 1,
+		cwd: prefs.cwd ?? null,
+		model: prefs.model ?? null,
+		thinkingLevel: prefs.thinkingLevel ?? null,
+		screenLogRetentionDays: prefs.screenLogRetentionDays ?? null,
+		screenLogMaxSize: prefs.screenLogMaxSize ?? null,
+	});
+}
+
+// ---- meta / state / status ------------------------------------------------
+
+/** @param {string} root @param {string} viewId @returns {ViewMeta|null} */
+export function readMeta(root, viewId) {
+	return readJson(P.metaPath(root, viewId), /** @type {ViewMeta|null} */ (null));
+}
+
+/** @param {string} root @param {ViewMeta} meta */
+export function writeMeta(root, meta) {
+	meta.updatedAt = Date.now();
+	atomicWriteJson(P.metaPath(root, meta.id), meta);
+}
+
+/** @param {string} root @param {string} viewId @returns {ViewState|null} */
+export function readState(root, viewId) {
+	return readJson(P.statePath(root, viewId), /** @type {ViewState|null} */ (null));
+}
+
+/** @param {string} root @param {ViewState} state */
+export function writeState(root, state) {
+	atomicWriteJson(P.statePath(root, state.viewId), state);
+}
+
+/** @param {string} root @param {string} viewId @param {string} runId @returns {RunStatus|null} */
+export function readStatus(root, viewId, runId) {
+	return readJson(P.statusPath(root, viewId, runId), /** @type {RunStatus|null} */ (null));
+}
+
+/** @param {string} root @param {RunStatus} status */
+export function writeStatus(root, status) {
+	atomicWriteJson(P.statusPath(root, status.viewId, status.runId), status);
+}
+
+/** @param {string} root @param {string} viewId @returns {HostStatus|null} */
+export function readHost(root, viewId) {
+	return readJson(P.hostPath(root, viewId), /** @type {HostStatus|null} */ (null));
+}
+
+/** @param {string} root @param {HostStatus} host */
+export function writeHost(root, host) {
+	atomicWriteJson(P.hostPath(root, host.viewId), host);
+}
+
+/** @param {string} root @param {string} viewId @param {number|null} pid */
+export function writeHostPid(root, viewId, pid) {
+	atomicWriteJson(P.hostPidPath(root, viewId), { pid, at: Date.now() });
+}
+
+/** @param {string} root @param {string} viewId @returns {number|null} */
+export function readHostPid(root, viewId) {
+	return readJson(P.hostPidPath(root, viewId), { pid: null }).pid ?? null;
+}
+
+/** @param {string} root @param {string} viewId @param {string} runId @param {number|null} pid */
+export function writePid(root, viewId, runId, pid) {
+	atomicWriteJson(P.pidPath(root, viewId, runId), { pid, at: Date.now() });
+}
+
+/** @param {string} root @param {string} viewId @param {string} runId @returns {number|null} */
+export function readPid(root, viewId, runId) {
+	return readJson(P.pidPath(root, viewId, runId), { pid: null }).pid ?? null;
+}
+
+// ---- listing / loading ----------------------------------------------------
+
+/** @param {string} root @param {string} viewId @returns {string[]} run ids, newest first by mtime. */
+export function listRunIds(root, viewId) {
+	const dir = P.runsDir(root, viewId);
+	if (!existsSync(dir)) return [];
+	try {
+		return readdirSync(dir)
+			.filter((name) => {
+				try {
+					return statSync(P.runDir(root, viewId, name)).isDirectory();
+				} catch {
+					return false;
+				}
+			})
+			.sort((a, b) => mtime(P.runDir(root, viewId, b)) - mtime(P.runDir(root, viewId, a)));
+	} catch {
+		return [];
+	}
+}
+
+/** @param {string} dir */
+function mtime(dir) {
+	try {
+		return statSync(dir).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * A merged dashboard row: meta + derived state. `state` may be null for a never-run row.
+ * @typedef {Object} Row
+ * @property {ViewMeta} meta
+ * @property {ViewState|null} state
+ * @property {boolean} alive  Whether the row's current run pid/foreground activity is alive.
+ * @property {boolean} hostAlive Whether a PTY host/socket is alive and attachable.
+ * @property {HostStatus|null} host
+ * @property {import("./types.mjs").ReviewSummary} [review]
+ * @property {import("./types.mjs").DiagnosticSummary} [diagnostics]
+ * @property {import("./types.mjs").FollowUpSummary} [followUps]
+ * @property {import("./types.mjs").SteeringSummary} [steering]
+ */
+
+/** @param {string} root @param {string} viewId @returns {Row|null} */
+export function loadRow(root, viewId) {
+	const meta = readMeta(root, viewId);
+	if (!meta) return null;
+	const state = readState(root, viewId);
+	const summaries = readViewArtifactSummaries(root, viewId);
+	const enrichedState = state ? { ...state, ...summaries } : state;
+	let alive = false;
+	if (enrichedState?.currentRunId) {
+		const pid = readPid(root, viewId, enrichedState.currentRunId);
+		alive = isAlive(pid);
+	}
+	// A managed session can also be active in the foreground after the user attaches
+	// and types a follow-up. In that path there is no detached runner pid for us to
+	// poll, but foreground extension events mirror processState into state.json.
+	if (!alive && enrichedState?.processState === "alive") alive = true;
+	const host = readHost(root, viewId);
+	const hostPid = host?.runnerPid ?? readHostPid(root, viewId);
+	const hostAlive = Boolean(host && (host.state === "alive" || host.state === "starting") && isAlive(hostPid));
+	return { meta, state: enrichedState, alive, hostAlive, host, ...summaries };
+}
+
+/** @param {string} root @param {string} viewId */
+export function readViewArtifactSummaries(root, viewId) {
+	const review = summarizeEvidence(readEvidence(root, viewId));
+	const diagnostics = readDiagnosticSummary(root, viewId);
+	const followUps = summarizeFollowUpQueue(readFollowUpQueue(root, viewId));
+	const steering = summarizeSteering(readSteering(root, viewId));
+	return { review, diagnostics, followUps, steering };
+}
+
+/**
+ * Load every non-archived row referenced by the roster.
+ * @param {string} root
+ * @param {{ includeArchived?: boolean }} [opts]
+ * @returns {Row[]}
+ */
+export function listRows(root, opts = {}) {
+	const roster = readRoster(root);
+	/** @type {Row[]} */
+	const rows = [];
+	for (const viewId of roster.views) {
+		// Archived short-circuit: archived rows are invisible on the dashboard, so
+		// never pay for their artifact files (state/evidence/host/diagnostics...).
+		// meta.json is the single authoritative source of the archived flag.
+		const meta = readMeta(root, viewId);
+		if (!meta) continue;
+		if (meta.archived && !opts.includeArchived) continue;
+		const row = loadRow(root, viewId);
+		if (!row) continue;
+		if (row.meta.archived && !opts.includeArchived) continue;
+		rows.push(row);
+	}
+	return rows;
+}
+
+// ---- creation -------------------------------------------------------------
+
+/**
+ * Create a new managed view (row) and persist meta + roster + an initial queued state.
+ * Does not launch anything — the caller launches a run afterward.
+ * @param {string} root
+ * @param {{
+ *   id: string, name: string, cwd: string, repoCwd?: string, repoRoot?: string|null,
+ *   worktreeMode?: import("./types.mjs").WorktreeMode, worktreePath?: string|null,
+ *   defaultModel?: string|null,
+ *   defaultThinking?: "off"|"minimal"|"low"|"medium"|"high"|"xhigh"|null,
+ *   writeCapable?: boolean,
+ *   sessionFile?: string,
+ * }} opts
+ * @returns {ViewMeta}
+ */
+export function createView(root, opts) {
+	ensureDir(P.sessionsDir(root));
+	const now = Date.now();
+	/** @type {ViewMeta} */
+	const meta = {
+		version: META_VERSION,
+		id: opts.id,
+		name: opts.name,
+		cwd: opts.cwd,
+		repoCwd: opts.repoCwd ?? opts.cwd,
+		repoRoot: opts.repoRoot ?? null,
+		sessionFile: opts.sessionFile ?? P.sessionFilePath(root, opts.id),
+		createdAt: now,
+		updatedAt: now,
+		pinned: false,
+		kind: "pi-session",
+		defaultModel: opts.defaultModel ?? null,
+		defaultThinking: opts.defaultThinking ?? null,
+		worktreeMode: opts.worktreeMode ?? "off",
+		worktreePath: opts.worktreePath ?? null,
+		writeCapable: opts.writeCapable ?? true,
+		archived: false,
+		source: "agent-board",
+	};
+	ensureDir(P.viewDir(root, meta.id));
+	writeMeta(root, meta);
+	/** @type {ViewState} */
+	const state = {
+		version: 1,
+		viewId: meta.id,
+		currentRunId: null,
+		semanticState: "queued",
+		processState: "exited",
+		summary: "Queued",
+		lastActivityAt: now,
+		updatedAt: now,
+		needsInput: false,
+		hasError: false,
+		latestAssistantPreview: "",
+		latestTool: null,
+		question: null,
+		pendingQuestions: [],
+		error: null,
+		lastVisitedAt: null,
+		lastAgentActivityAt: null,
+		autoState: null,
+	};
+	writeState(root, state);
+	addToRoster(root, meta.id);
+	return meta;
+}

package/src/core/title.mjs

@@ -0,0 +1,43 @@
+/** Title-generation helpers for session names. */
+
+/** Default cheap model for session titles. Override via $AGENT_BOARD_TITLE_MODEL. */
+export const DEFAULT_TITLE_MODEL = "openai-codex/gpt-5.5";
+
+/** Default thinking level for session titles. Override via $AGENT_BOARD_TITLE_THINKING_LEVEL. */
+export const DEFAULT_TITLE_THINKING_LEVEL = "low";
+
+/**
+ * Prompt for a short session title derived from the user's initial task.
+ * @param {string} taskPrompt
+ */
+export function titlePrompt(taskPrompt) {
+	return [
+		"Write a concise title for this coding task.",
+		"Rules:",
+		"- 3 or 4 words max",
+		"- plain text only",
+		"- no quotes",
+		"- no markdown",
+		"- describe the task, not the format",
+		"",
+		`Task: ${String(taskPrompt || "").trim()}`,
+	].join("\n");
+}
+
+/**
+ * Normalize a model-generated title into a compact dashboard label.
+ * @param {string|null|undefined} text
+ * @param {string} fallback
+ * @param {number} [maxWords]
+ */
+export function normalizeGeneratedTitle(text, fallback, maxWords = 4) {
+	const cleaned = String(text || "")
+		.replace(/^\s*(title\s*:\s*)?/i, "")
+		.replace(/^['"`\-–—•*\s]+|['"`\-–—•*\s]+$/g, "")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (!cleaned) return fallback;
+	const words = cleaned.split(/\s+/).filter(Boolean).slice(0, maxWords);
+	const compact = words.join(" ").replace(/[.,;:!?]+$/g, "").trim();
+	return compact || fallback;
+}