@nredd/pi-session-kit 0.0.0-stage → 0.4.0

package/src/monitor/validate.ts

@@ -0,0 +1,59 @@
+/** Input validation for `monitor_start`: argv, name, match regex, timeout. */
+
+export const MAX_MONITORS = 5;
+export const DEFAULT_TIMEOUT_S = 3600;
+export const MAX_TIMEOUT_S = 86_400;
+export const MAX_NAME_LENGTH = 40;
+export const MAX_MATCH_LENGTH = 500;
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export interface StartParams {
+	argv: string[];
+	name: string;
+	match?: string;
+	wake?: boolean;
+	timeout_s?: number;
+}
+
+export interface ValidStart {
+	argv: string[];
+	name: string;
+	regex: RegExp | undefined;
+	wake: boolean;
+	timeoutMs: number;
+}
+
+export type Validation = { ok: true; value: ValidStart } | { ok: false; error: string };
+
+export function validateStart(input: StartParams, liveNames: ReadonlySet<string>, liveCount: number): Validation {
+	const { argv, name } = input;
+	if (!Array.isArray(argv) || argv.length === 0) return fail("argv must be a non-empty array");
+	if (argv.some((a) => typeof a !== "string" || a.includes("\0")))
+		return fail("argv entries must be strings without NUL");
+	if (argv[0]?.trim() === "") return fail("argv[0] must be a non-empty command");
+	if (typeof name !== "string" || name.length === 0 || name.length > MAX_NAME_LENGTH || !NAME_RE.test(name)) {
+		return fail(`name must match ${NAME_RE.source} and be at most ${MAX_NAME_LENGTH} characters`);
+	}
+	if (liveNames.has(name)) return fail(`a running monitor is already named "${name}"`);
+	if (liveCount >= MAX_MONITORS) return fail(`at most ${MAX_MONITORS} monitors can run at once; stop one first`);
+
+	let regex: RegExp | undefined;
+	if (input.match !== undefined && input.match !== "") {
+		if (input.match.length > MAX_MATCH_LENGTH) return fail(`match must be at most ${MAX_MATCH_LENGTH} characters`);
+		try {
+			regex = new RegExp(input.match);
+		} catch (error) {
+			return fail(`match is not a valid regex: ${(error as Error).message}`);
+		}
+	}
+
+	const timeoutS = input.timeout_s ?? DEFAULT_TIMEOUT_S;
+	if (!Number.isFinite(timeoutS) || timeoutS < 1 || timeoutS > MAX_TIMEOUT_S) {
+		return fail(`timeout_s must be between 1 and ${MAX_TIMEOUT_S}`);
+	}
+	return { ok: true, value: { argv, name, regex, wake: input.wake === true, timeoutMs: Math.round(timeoutS * 1000) } };
+}
+
+function fail(error: string): Validation {
+	return { ok: false, error };
+}

package/src/monitor/widget.ts

@@ -0,0 +1,75 @@
+/** One widget row per running monitor (TUI only). Renders live from the manager, never from copies. */
+
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { formatDuration } from "./messages.ts";
+import type { MonitorInfo } from "./types.ts";
+
+export const WIDGET_KEY = "session-kit:monitors";
+const TICK_MS = 1_000;
+
+export function formatRow(info: MonitorInfo, now: number, theme: Pick<Theme, "fg">): string {
+	const parts = [
+		theme.fg("success", "●"),
+		` ${theme.fg("accent", info.name)}`,
+		theme.fg("muted", `  ${info.id}  ${formatDuration(now - info.startedAt)}  ${info.lines} lines`),
+	];
+	if (info.match) parts.push(theme.fg("muted", `  match /${info.match}/`));
+	else if (info.wake) parts.push(theme.fg("muted", "  wake"));
+	return parts.join("");
+}
+
+export class MonitorWidget {
+	private ctx: ExtensionContext | undefined;
+	private visible = false;
+	private requestRender: (() => void) | undefined;
+	private timer: NodeJS.Timeout | undefined;
+
+	constructor(private readonly running: () => MonitorInfo[]) {}
+
+	/** Bind to the session's UI; a no-op outside the TUI. */
+	attach(ctx: ExtensionContext): void {
+		if (ctx.mode === "tui") this.ctx = ctx;
+	}
+
+	/** Show or hide the widget to match the manager, and repaint. */
+	refresh(): void {
+		const ctx = this.ctx;
+		if (!ctx) return;
+		const any = this.running().length > 0;
+		if (any && !this.visible) {
+			ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+				this.requestRender = () => tui.requestRender();
+				return {
+					render: (width: number) =>
+						this.running().map((info) => truncateToWidth(formatRow(info, Date.now(), theme), width, "…")),
+					invalidate() {},
+				};
+			});
+			this.visible = true;
+			this.startTicking();
+		} else if (!any && this.visible) {
+			this.hide();
+		}
+		this.requestRender?.();
+	}
+
+	/** Remove the widget and stop the timer. */
+	dispose(): void {
+		this.hide();
+		this.ctx = undefined;
+	}
+
+	private hide(): void {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = undefined;
+		if (this.visible) this.ctx?.ui.setWidget(WIDGET_KEY, undefined);
+		this.visible = false;
+		this.requestRender = undefined;
+	}
+
+	private startTicking(): void {
+		this.timer = setInterval(() => this.requestRender?.(), TICK_MS);
+		this.timer.unref();
+	}
+}

package/src/output.ts

@@ -0,0 +1,25 @@
+/** Command output that works in every pi mode, shared by `/diff` and `/stats`. */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export type Level = "info" | "warning" | "error";
+
+/**
+ * Show `text` where the mode can. `ctx.ui.notify` is a no-op in print and json mode (no UI), so print
+ * writes to stdout (errors to stderr) and json adds one display message of `customType` to the stream.
+ */
+export function say(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	customType: string,
+	text: string,
+	level: Level,
+): void {
+	if (ctx.mode === "print") {
+		(level === "info" ? process.stdout : process.stderr).write(`${text}\n`);
+	} else if (ctx.mode === "json") {
+		pi.sendMessage({ customType, content: text, display: true }, { triggerTurn: false });
+	} else {
+		ctx.ui.notify(text, level);
+	}
+}

package/src/rules/index.ts

@@ -0,0 +1,94 @@
+/**
+ * Path-scoped rules. `.pi/rules/*.md` (project) and `<agent dir>/rules/*.md` (user) carry a
+ * `paths:` frontmatter of globs relative to the cwd. The first time `read`/`edit`/`write` touches a
+ * matching file in a context window, the rule text is appended to that tool result. The system
+ * prompt is never touched, so prompt caching survives.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { KitConfig } from "../config.ts";
+import {
+	formatRules,
+	INJECTED_ENTRY,
+	type InjectedEntryData,
+	injectedKeys,
+	MAX_RULES_PER_TURN,
+	matchesRule,
+	parseRule,
+	type Rule,
+	relativeToCwd,
+	TOOLS_WITH_PATH,
+} from "./logic.ts";
+
+function agentDir(): string {
+	return process.env.PI_CODING_AGENT_DIR ?? path.join(homedir(), ".pi", "agent");
+}
+
+/** Load every rule in a directory; a missing directory or unreadable file is skipped. */
+export function loadRuleDir(dir: string, source: "project" | "user"): Rule[] {
+	let names: string[];
+	try {
+		names = readdirSync(dir)
+			.filter((n) => n.endsWith(".md"))
+			.sort();
+	} catch {
+		return [];
+	}
+	const rules: Rule[] = [];
+	for (const name of names) {
+		try {
+			const rule = parseRule(`${source}:${name}`, readFileSync(path.join(dir, name), "utf8"));
+			if (rule) rules.push(rule);
+		} catch {
+			// Unreadable file: ignore it, like a rule without `paths`.
+		}
+	}
+	return rules;
+}
+
+export function register(pi: ExtensionAPI, _config: KitConfig, userAgentDir = agentDir()): void {
+	let injected = new Set<string>();
+	let turnCount = 0;
+
+	const rebuild = (ctx: { sessionManager: { getBranch(): unknown[] } }) => {
+		injected = injectedKeys(ctx.sessionManager.getBranch());
+	};
+
+	pi.on("session_start", (_event, ctx) => rebuild(ctx));
+	pi.on("session_tree", (_event, ctx) => rebuild(ctx));
+	pi.on("session_compact", () => {
+		injected = new Set();
+	});
+	pi.on("turn_start", () => {
+		turnCount = 0;
+	});
+
+	pi.on("tool_result", (event, ctx) => {
+		if (event.isError || !TOOLS_WITH_PATH.has(event.toolName)) return;
+		const raw = event.input.path;
+		if (typeof raw !== "string") return;
+		const rel = relativeToCwd(raw, ctx.cwd);
+		if (rel === undefined) return;
+
+		const rules = [
+			...loadRuleDir(path.join(ctx.cwd, ".pi", "rules"), "project"),
+			...loadRuleDir(path.join(userAgentDir, "rules"), "user"),
+		];
+		const fresh: Rule[] = [];
+		for (const rule of rules) {
+			if (turnCount + fresh.length >= MAX_RULES_PER_TURN) break;
+			if (!injected.has(rule.id) && matchesRule(rule, rel)) fresh.push(rule);
+		}
+		if (fresh.length === 0) return;
+
+		for (const rule of fresh) {
+			injected.add(rule.id);
+			pi.appendEntry<InjectedEntryData>(INJECTED_ENTRY, { rule: rule.id });
+		}
+		turnCount += fresh.length;
+		return { content: [...event.content, { type: "text" as const, text: formatRules(fresh) }] };
+	});
+}

package/src/rules/logic.ts

@@ -0,0 +1,96 @@
+/** Pure logic for path-scoped rules: parsing, path resolution, glob matching, injection text. */
+
+import { homedir } from "node:os";
+import path from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export const MAX_RULES_PER_TURN = 8;
+export const MAX_RULE_BYTES = 4096;
+export const INJECTED_ENTRY = "session-kit:rule-injected";
+export const TOOLS_WITH_PATH = new Set(["read", "edit", "write"]);
+
+export interface Rule {
+	/** Stable id, `project:<file>` or `user:<file>`. */
+	id: string;
+	globs: string[];
+	body: string;
+}
+
+export interface InjectedEntryData {
+	rule: string;
+}
+
+/** Parse a rule file. Returns undefined when it has no usable `paths`, an empty body or bad YAML. */
+export function parseRule(id: string, content: string): Rule | undefined {
+	let parsed: { frontmatter: Record<string, unknown>; body: string };
+	try {
+		parsed = parseFrontmatter(content);
+	} catch {
+		return undefined;
+	}
+	const raw = parsed.frontmatter.paths;
+	const list = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw : [];
+	const globs = list.filter((g): g is string => typeof g === "string" && g.trim() !== "").map((g) => g.trim());
+	const body = parsed.body.trim();
+	if (globs.length === 0 || body === "") return undefined;
+	return { id, globs, body };
+}
+
+/** Touched path relative to `cwd` with `/` separators; undefined when outside `cwd`. */
+export function relativeToCwd(raw: string, cwd: string, home = homedir()): string | undefined {
+	let p = raw.startsWith("@") ? raw.slice(1) : raw;
+	if (p === "~") p = home;
+	else if (p.startsWith("~/")) p = path.join(home, p.slice(2));
+	const rel = path.relative(cwd, path.resolve(cwd, p));
+	if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return undefined;
+	return rel.split(path.sep).join("/");
+}
+
+export function matchesRule(rule: Rule, relPath: string): boolean {
+	return rule.globs.some((glob) => {
+		try {
+			return path.posix.matchesGlob(relPath, glob);
+		} catch {
+			return false;
+		}
+	});
+}
+
+/** Longest prefix of `text` within `maxBytes` UTF-8 bytes, cut on a code point boundary. */
+export function truncateUtf8(text: string, maxBytes: number): string {
+	let bytes = 0;
+	let end = 0;
+	for (const char of text) {
+		bytes += Buffer.byteLength(char);
+		if (bytes > maxBytes) break;
+		end += char.length;
+	}
+	return text.slice(0, end);
+}
+
+/** One rule's appended block: label + body (+ truncation notice), never over `maxBytes` UTF-8 bytes. */
+export function formatRule(rule: Rule, maxBytes = MAX_RULE_BYTES): string {
+	const head = `\n\n[pi-session-kit rule: ${rule.id}]\n`;
+	const full = head + rule.body;
+	if (Buffer.byteLength(full) <= maxBytes) return full;
+	const notice = `\n[rule truncated at ${maxBytes} bytes]`;
+	const budget = Math.max(0, maxBytes - Buffer.byteLength(head) - Buffer.byteLength(notice));
+	return head + truncateUtf8(rule.body, budget).trimEnd() + notice;
+}
+
+export function formatRules(rules: readonly Rule[]): string {
+	return rules.map((r) => formatRule(r)).join("");
+}
+
+/** Rule ids still active on a branch: injections after the newest compaction. */
+export function injectedKeys(entries: readonly unknown[]): Set<string> {
+	const keys = new Set<string>();
+	for (const entry of entries) {
+		const e = entry as { type?: string; customType?: string; data?: Partial<InjectedEntryData> };
+		if (e?.type === "compaction") keys.clear();
+		else if (e?.type === "custom" && e.customType === INJECTED_ENTRY) {
+			if (typeof e.data?.rule === "string") keys.add(e.data.rule);
+		}
+	}
+	return keys;
+}

package/src/shared.ts

@@ -0,0 +1,177 @@
+/**
+ * Coordination shared by `/goal` and `/loop`. Everything here is keyed by the `pi` object of one
+ * extension runtime, never a module global, so two sessions in one process (or two tmux panes)
+ * cannot see each other.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isChildSession } from "./child.ts";
+
+/** `customType` of the session entry pi-plan-mode persists on every state change. */
+export const PLAN_STATE_ENTRY = "plan-mode-state";
+
+interface EntryLike {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+}
+
+/**
+ * Whether Plan mode is on, from the latest `plan-mode-state` entry of a branch.
+ *
+ * pi-plan-mode exposes no "active" event or getter; its persisted state entry (`data.enabled`) is
+ * the only external signal, and it is appended synchronously on every transition.
+ */
+export function isPlanModeActive(entries: readonly EntryLike[]): boolean {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry?.type !== "custom" || entry.customType !== PLAN_STATE_ENTRY) continue;
+		const data = entry.data;
+		return typeof data === "object" && data !== null && (data as { enabled?: unknown }).enabled === true;
+	}
+	return false;
+}
+
+/**
+ * Whether Plan mode was switched ON after the last `marker` entry of a branch, even if it has
+ * been switched off again since. An idle goal sees no events while the user runs `/plan start`
+ * then `/plan exit`; this finds that excursion afterwards.
+ */
+export function planModeEnteredSince(entries: readonly EntryLike[], marker: string): boolean {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry?.type !== "custom") continue;
+		if (entry.customType === marker) return false;
+		if (entry.customType === PLAN_STATE_ENTRY && (entry.data as { enabled?: unknown } | null)?.enabled === true)
+			return true;
+	}
+	return false;
+}
+
+/** Plan mode for the current branch of `ctx`'s session. */
+export function planModeActive(ctx: ExtensionContext): boolean {
+	return isPlanModeActive(ctx.sessionManager.getBranch() as readonly EntryLike[]);
+}
+
+/** In-process state `/goal` and `/loop` agree on. */
+export interface Coordination {
+	/** A goal is active: loop ticks must not fire. */
+	goalActive: boolean;
+	/** Router-owned quota jobs still parked; clearing them never auto-resumes kit work. */
+	quotaParked: Set<string>;
+	/** Reconcile an idle Plan-mode excursion before another feature handles a command. */
+	reconcilePlanMode?: (ctx: ExtensionContext) => void;
+}
+
+const COORDINATION = new WeakMap<object, Coordination>();
+
+/** The coordination record of one `pi` runtime. */
+export function coordination(pi: object): Coordination {
+	let state = COORDINATION.get(pi);
+	if (!state) {
+		state = { goalActive: false, quotaParked: new Set() };
+		COORDINATION.set(pi, state);
+	}
+	return state;
+}
+
+/** Quota admission is distinct from a recoverable provider error. */
+export type QuotaPause = "quota parked" | "quota refused";
+
+interface QuotaWatch {
+	listeners: Set<(reason: QuotaPause, ctx: ExtensionContext) => void>;
+}
+
+const QUOTA_WATCHES = new WeakMap<object, QuotaWatch>();
+
+/**
+ * Watch real pi-subagents admission, once per kit runtime. Parking happens before
+ * an Agent record exists: `subagents:scheduled`, not `subagents:created`, owns it.
+ * Pause immediately on additions/reparks and direct admission refusal. Removing,
+ * disabling or firing a job releases the resume guard, but NEVER resumes work.
+ * The current in-flight turn is allowed to finish; no new goal or loop turn starts.
+ */
+export function watchQuota(pi: ExtensionAPI, onQuota: (reason: QuotaPause, ctx: ExtensionContext) => void): void {
+	let watch = QUOTA_WATCHES.get(pi);
+	if (!watch) {
+		watch = { listeners: new Set() };
+		QUOTA_WATCHES.set(pi, watch);
+		const listeners = watch.listeners;
+		const shared = coordination(pi);
+		let ctx: ExtensionContext | undefined;
+		let detach: (() => void) | undefined;
+		const pause = (reason: QuotaPause): void => {
+			if (ctx && !isChildSession(pi)) for (const listener of listeners) listener(reason, ctx);
+		};
+		pi.on("session_start", (_event, context) => {
+			detach?.();
+			detach = undefined;
+			shared.quotaParked.clear();
+			ctx = context;
+			if (isChildSession(pi)) return;
+			detach = pi.events.on("subagents:scheduled", (raw) => {
+				if (!raw || typeof raw !== "object") return;
+				const event = raw as { type?: unknown; jobId?: unknown; job?: unknown };
+				if (event.type === "removed" || event.type === "fired" || event.type === "error") {
+					if (typeof event.jobId === "string") shared.quotaParked.delete(event.jobId);
+					return;
+				}
+				if (event.type !== "added" && event.type !== "updated") return;
+				if (!event.job || typeof event.job !== "object") return;
+				const job = event.job as { id?: unknown; quotaParked?: unknown; enabled?: unknown; lastStatus?: unknown };
+				if (typeof job.id !== "string") return;
+				if (job.quotaParked === true && job.enabled === true && job.lastStatus !== "running") {
+					shared.quotaParked.add(job.id);
+					pause("quota parked");
+				} else shared.quotaParked.delete(job.id);
+			});
+		});
+		pi.on("before_agent_start", (_event, context) => {
+			ctx = context;
+		});
+		pi.on("tool_execution_end", (event, context) => {
+			ctx = context;
+			if (event.toolName !== "Agent" || !event.isError || isChildSession(pi)) return;
+			// The admission client has no refusal event. Match its canonical error,
+			// not arbitrary quota-looking tool output or provider retry messages.
+			const text = event.result.content
+				.filter((block: { type?: string }) => block.type === "text")
+				.map((block: { text?: string }) => block.text)
+				.join("\n");
+			if (/Subscription quota for .+ is exhausted; it resets at .+\. The agent was not started\./.test(text))
+				pause("quota refused");
+		});
+		pi.on("session_shutdown", () => {
+			detach?.();
+			detach = undefined;
+			ctx = undefined;
+			shared.quotaParked.clear();
+		});
+	}
+	watch.listeners.add(onQuota);
+}
+
+/** How a run ended when nobody continued it. */
+export type StopOutcome = "aborted" | "error";
+
+/**
+ * Report runs that ended in `aborted` or `error` once pi has truly stopped.
+ *
+ * `agent_before_settle` is too early: pi may still auto-retry, or another handler (the
+ * subscription router's quota recovery) may continue the run. So the outcome is only recorded
+ * there, forgotten when a new turn starts, and reported from `agent_settled`.
+ */
+export function watchStops(pi: ExtensionAPI, onStop: (outcome: StopOutcome, ctx: ExtensionContext) => void): void {
+	let pending: StopOutcome | undefined;
+	pi.on("agent_before_settle", (event) => {
+		pending = !event.continue && event.outcome !== "completed" ? event.outcome : undefined;
+	});
+	pi.on("turn_start", () => {
+		pending = undefined;
+	});
+	pi.on("agent_settled", (_event, ctx) => {
+		const outcome = pending;
+		pending = undefined;
+		if (outcome) onStop(outcome, ctx);
+	});
+}