@oh-my-pi/pi-coding-agent 15.13.3 → 16.0.0

package/src/advisor/runtime.ts

@@ -0,0 +1,248 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { estimateTokens } from "@oh-my-pi/pi-agent-core/compaction";
+import { logger } from "@oh-my-pi/pi-utils";
+import { formatSessionHistoryMarkdown } from "../session/session-history-format";
+
+/** Minimal slice of `Agent` the runtime drives — satisfied by pi-agent-core `Agent`. */
+export interface AdvisorAgent {
+	prompt(input: string): Promise<void>;
+	abort(reason?: unknown): void;
+	reset(): void;
+	readonly state: { messages: AgentMessage[] };
+}
+
+export interface AdvisorRuntimeHost {
+	/** Live primary transcript (use `agent.state.messages`). */
+	snapshotMessages(): AgentMessage[];
+	/** Surface one advice note to the primary (enqueues into the session YieldQueue). */
+	enqueueAdvice(note: string, severity?: "nit" | "concern" | "blocker"): void;
+	/**
+	 * Pre-prompt context maintenance for the advisor's own append-only context.
+	 * Promotes the advisor model to a larger sibling when its context nears the
+	 * window (mirroring the primary's promote-first policy) and resolves `true`
+	 * when the advisor should re-prime — reset and replay the current
+	 * primary-bounded transcript — because promotion did not free enough room.
+	 * Optional: hosts that omit it get no maintenance (context only shrinks when
+	 * the primary's next compaction triggers {@link AdvisorRuntime.reset}).
+	 */
+	maintainContext?(incomingTokens: number): Promise<boolean>;
+}
+
+interface PendingDelta {
+	text: string;
+	turns: number;
+}
+
+interface CatchupWaiter {
+	threshold: number;
+	resolve: () => void;
+	finish: () => void;
+	timer?: NodeJS.Timeout;
+}
+
+export class AdvisorRuntime {
+	#lastCount = 0;
+	#pending: PendingDelta[] = [];
+	#busy = false;
+	#backlog = 0;
+	#consecutiveFailures = 0;
+	#latestMessages?: AgentMessage[];
+	#waiters: CatchupWaiter[] = [];
+	disposed = false;
+
+	constructor(
+		private readonly agent: AdvisorAgent,
+		private readonly host: AdvisorRuntimeHost,
+		private readonly retryDelayMs = 1000,
+	) {}
+
+	get backlog(): number {
+		return this.#backlog;
+	}
+
+	onTurnEnd(messages?: AgentMessage[]): void {
+		if (this.disposed) return;
+		const all = messages ?? this.host.snapshotMessages();
+		this.#latestMessages = all;
+		const render = this.#renderDelta(all);
+		if (render) {
+			this.#pending.push({ text: render, turns: 1 });
+			this.#backlog++;
+			this.#notifyWaiters();
+			void this.#drain();
+		}
+	}
+
+	waitForCatchup(maxMs: number, threshold: number, signal?: AbortSignal): Promise<void> {
+		if (this.disposed || signal?.aborted || this.#backlog < threshold) return Promise.resolve();
+		const { promise, resolve } = Promise.withResolvers<void>();
+		let waiter!: CatchupWaiter;
+		const finish = (): void => {
+			const idx = this.#waiters.indexOf(waiter);
+			if (idx >= 0) this.#waiters.splice(idx, 1);
+			clearTimeout(waiter.timer);
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		};
+		waiter = { threshold, resolve, finish, timer: setTimeout(finish, maxMs) };
+		this.#waiters.push(waiter);
+		signal?.addEventListener("abort", finish, { once: true });
+		if (signal?.aborted) {
+			finish();
+		}
+		return promise;
+	}
+
+	dispose(): void {
+		this.disposed = true;
+		this.#pending = [];
+		this.#backlog = 0;
+		this.#consecutiveFailures = 0;
+		this.#wakeAllWaiters();
+		try {
+			this.agent.abort("advisor disposed");
+		} catch {}
+	}
+
+	#resetAdvisorContext(clearBacklog: boolean, wakeWaiters: boolean): void {
+		this.#lastCount = 0;
+		this.#pending = [];
+		this.#consecutiveFailures = 0;
+		if (clearBacklog) {
+			this.#backlog = 0;
+		}
+		if (wakeWaiters) {
+			this.#wakeAllWaiters();
+		}
+		try {
+			this.agent.reset();
+		} catch {}
+		try {
+			this.agent.abort("advisor reset");
+		} catch {}
+	}
+
+	/**
+	 * Re-prime the advisor after a history rewrite (compaction, session
+	 * switch/resume, branch). Clears the advisor's own (non-persisted) context
+	 * and rewinds the cursor to 0 so the NEXT turn replays the full current —
+	 * post-compaction — transcript, giving the advisor fresh context instead of
+	 * leaving it blind to everything before the rewrite.
+	 */
+	reset(): void {
+		this.#resetAdvisorContext(true, true);
+	}
+
+	/**
+	 * Seed the cursor to the current transcript length when the advisor is enabled
+	 * mid-session. Prevents the next turn from replaying the entire history to the
+	 * advisor (which would be expensive and likely stale).
+	 */
+	seedTo(count: number): void {
+		this.#lastCount = count;
+		this.#pending = [];
+		this.#backlog = 0;
+		this.#consecutiveFailures = 0;
+		this.#wakeAllWaiters();
+	}
+
+	#renderDelta(messages?: AgentMessage[]): string | null {
+		const all = messages ?? this.#latestMessages ?? this.host.snapshotMessages();
+		if (all.length < this.#lastCount) {
+			this.#lastCount = all.length;
+			return null;
+		}
+		const delta = all
+			.slice(this.#lastCount)
+			.filter(m => !(m.role === "custom" && (m as { customType?: string }).customType === "advisor"));
+		this.#lastCount = all.length;
+		if (delta.length === 0) return null;
+		const md = formatSessionHistoryMarkdown(delta, { includeThinking: true, includeToolIntent: true });
+		return md.trim() ? md : null;
+	}
+
+	#notifyWaiters(): void {
+		for (let i = this.#waiters.length - 1; i >= 0; i--) {
+			const w = this.#waiters[i];
+			if (this.#backlog < w.threshold) {
+				w.finish();
+			}
+		}
+	}
+
+	#wakeAllWaiters(): void {
+		for (const w of [...this.#waiters]) {
+			w.finish();
+		}
+	}
+
+	async #drain(): Promise<void> {
+		if (this.#busy) return;
+		this.#busy = true;
+		try {
+			while (!this.disposed && this.#pending.length) {
+				const popped = this.#pending.splice(0);
+				const candidateBatch = popped.map(b => b.text).join("\n\n---\n\n");
+				const turnsCovered = popped.reduce((sum, b) => sum + b.turns, 0);
+				const incomingTokens = estimateTokens({
+					role: "user",
+					content: candidateBatch,
+					timestamp: Date.now(),
+				});
+
+				let shouldReprime = false;
+				if (this.host.maintainContext) {
+					try {
+						shouldReprime = await this.host.maintainContext(incomingTokens);
+					} catch (err) {
+						logger.debug("advisor context maintenance failed", { err: String(err) });
+					}
+				}
+
+				let batch: string | null;
+				let finalTurns: number;
+				if (shouldReprime) {
+					// Promotion could not fit the advisor's context — re-prime.
+					const newTurns = this.#pending.reduce((sum, b) => sum + b.turns, 0);
+					this.#resetAdvisorContext(false, false);
+					batch = this.#renderDelta(this.#latestMessages);
+					finalTurns = turnsCovered + newTurns;
+				} else {
+					batch = candidateBatch;
+					finalTurns = turnsCovered;
+				}
+
+				if (this.disposed || batch === null) {
+					this.#backlog = Math.max(0, this.#backlog - finalTurns);
+					this.#notifyWaiters();
+					continue;
+				}
+
+				let success = false;
+				try {
+					await this.agent.prompt(batch);
+					success = true;
+					this.#consecutiveFailures = 0;
+				} catch (err) {
+					logger.debug("advisor turn failed", { err: String(err) });
+					this.#consecutiveFailures++;
+					if (this.#consecutiveFailures >= 3) {
+						logger.warn("advisor failed consecutively 3 times; dropping backlog to prevent stall");
+						this.#consecutiveFailures = 0;
+						success = true;
+					} else {
+						this.#pending.unshift({ text: batch, turns: finalTurns });
+						await Bun.sleep(this.retryDelayMs);
+					}
+				}
+
+				if (success) {
+					this.#backlog = Math.max(0, this.#backlog - finalTurns);
+					this.#notifyWaiters();
+				}
+			}
+		} finally {
+			this.#busy = false;
+		}
+	}
+}

package/src/advisor/watchdog.ts

@@ -0,0 +1,83 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { expandAtImports } from "../discovery/at-imports";
+import { repo } from "../utils/git";
+
+/**
+ * Discover and load WATCHDOG.md files walking up from cwd, project .omp folder, and user agent dir.
+ * Returns formatted watchdog file blocks ready to be appended to the advisor system prompt.
+ */
+export async function discoverWatchdogFiles(cwd: string, agentDir?: string): Promise<string[]> {
+	const home = os.homedir();
+	const resolvedAgentDir = agentDir ?? getAgentDir();
+	const userPath = resolvedAgentDir ? path.resolve(resolvedAgentDir, "WATCHDOG.md") : null;
+	let repoRoot: string | null = null;
+	try {
+		repoRoot = await repo.root(cwd);
+	} catch (err) {
+		logger.debug("Failed to resolve git root for watchdog discovery", { err: String(err) });
+	}
+
+	const candidates = new Set<string>();
+
+	// 1. User level: ~/.omp/WATCHDOG.md (or active profile agent dir)
+	if (resolvedAgentDir) {
+		candidates.add(path.resolve(resolvedAgentDir, "WATCHDOG.md"));
+	}
+
+	// 2. Project levels (both standalone and native config .omp/): walk up from cwd to repoRoot / home
+	let current = cwd;
+	while (true) {
+		candidates.add(path.resolve(current, ".omp", "WATCHDOG.md"));
+		candidates.add(path.resolve(current, "WATCHDOG.md"));
+
+		if (current === (repoRoot ?? home)) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+
+	const items: Array<{ path: string; content: string; level: "user" | "project"; depth: number }> = [];
+
+	for (const candidate of candidates) {
+		try {
+			const content = await Bun.file(candidate).text();
+			const expanded = await expandAtImports(content, candidate);
+			const parent = path.dirname(candidate);
+			const baseName = parent.split(path.sep).pop() ?? "";
+
+			const isUser = userPath !== null && candidate === userPath;
+			const ownerDir = baseName === ".omp" ? path.dirname(parent) : parent;
+			const ownerBaseName = ownerDir.split(path.sep).pop() ?? "";
+
+			if (isUser || !ownerBaseName.startsWith(".") || baseName === ".omp") {
+				const relative = path.relative(cwd, ownerDir);
+				const depth = relative === "" ? 0 : relative.split(path.sep).filter(Boolean).length;
+				items.push({
+					path: candidate,
+					content: expanded,
+					level: isUser ? "user" : "project",
+					depth,
+				});
+			}
+		} catch (err) {
+			if (!isEnoent(err)) {
+				logger.warn("Failed to read WATCHDOG.md candidate", { path: candidate, error: String(err) });
+			}
+		}
+	}
+
+	// Sort files so that user level comes first, then project level sorted by depth (descending).
+	// This means user-level rules are first, then project-level rules from ancestor directories down to the leaf directory (depth 0 is last/most prominent).
+	items.sort((a, b) => {
+		if (a.level !== b.level) {
+			return a.level === "user" ? -1 : 1;
+		}
+		return b.depth - a.depth;
+	});
+
+	return items.map(item => {
+		return `Especially pay attention to:\n<attention>\n${item.content}\n</attention>`;
+	});
+}

package/src/config/model-roles.ts

@@ -5,7 +5,17 @@
 import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
 import type { Settings } from "./settings";
 
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "designer" | "commit" | "title" | "task";
+export type ModelRole =
+	| "default"
+	| "smol"
+	| "slow"
+	| "vision"
+	| "plan"
+	| "designer"
+	| "commit"
+	| "title"
+	| "task"
+	| "advisor";
 
 export interface ModelRoleInfo {
 	tag?: string;
@@ -25,6 +35,7 @@ export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
 	commit: { tag: "COMMIT", name: "Commit", color: "dim" },
 	title: { tag: "TITLE", name: "Title", color: "dim", hidden: true },
 	task: { tag: "TASK", name: "Subtask", color: "muted" },
+	advisor: { tag: "ADVISOR", name: "Advisor", color: "accent" },
 };
 
 export const MODEL_ROLE_IDS: ModelRole[] = [
@@ -37,6 +48,7 @@ export const MODEL_ROLE_IDS: ModelRole[] = [
 	"commit",
 	"title",
 	"task",
+	"advisor",
 ];
 
 export type RoleInfo = ModelRoleInfo;

package/src/config/settings-schema.ts

@@ -106,7 +106,7 @@ export const TAB_METADATA: Record<SettingTab, { label: string; icon: `tab.${stri
  */
 export const TAB_GROUPS: Record<SettingTab, readonly string[]> = {
 	appearance: ["Theme", "Status Line", "Display", "Images"],
-	model: ["Thinking", "Sampling", "Prompt", "Retry & Fallback"],
+	model: ["Thinking", "Sampling", "Prompt", "Retry & Fallback", "Advisor"],
 	interaction: [
 		"Input",
 		"Approvals",
@@ -381,6 +381,39 @@ export const SETTINGS_SCHEMA = {
 			description: "Keep the display from idle-sleeping while a session is open (caffeinate -d)",
 		},
 	},
+	"advisor.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "model",
+			group: "Advisor",
+			label: "Enable Advisor",
+			description:
+				"Pair a second model (assigned to the 'advisor' role) that passively reviews each turn and injects notes.",
+		},
+	},
+	"advisor.subagents": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "model",
+			group: "Advisor",
+			label: "Advisor for Subagents",
+			description: "Also enable the advisor on spawned task/eval subagents.",
+		},
+	},
+	"advisor.syncBacklog": {
+		type: "enum",
+		values: ["off", "1", "3", "5"] as const,
+		default: "off",
+		ui: {
+			tab: "model",
+			group: "Advisor",
+			label: "Advisor Sync Backlog",
+			description:
+				"Pause the main agent for up to 30 seconds if the advisor falls behind by this many turns. Off disables catch-up delays.",
+		},
+	},
 	shellPath: { type: "string", default: undefined },
 
 	extensions: { type: "array", default: EMPTY_STRING_ARRAY },
@@ -1734,14 +1767,16 @@ export const SETTINGS_SCHEMA = {
 			"harmony",
 			"pi",
 			"qwen3",
+			"gemini",
+			"gemma",
 		] as const,
 		default: "auto",
 		ui: {
 			tab: "context",
 			group: "Experimental",
-			label: "Tool Call Format",
+			label: "Tool Calling Mode",
 			description:
-				"Controls how tools are exposed to the model. Auto uses native tool calls unless the selected model is marked as not supporting tools, then falls back to GLM-style in-band tool calls. Native forces provider-native tools; the other values force the named in-band syntax. Applies on session start.",
+				"Controls how tools are exposed to the model. Auto uses provider-native tool calls unless the selected model is marked as not supporting them, then falls back to the GLM owned dialect. Native forces provider-native tools; the other values force the named owned dialect. Applies on session start.",
 			options: [
 				{
 					value: "auto",
@@ -1756,8 +1791,10 @@ export const SETTINGS_SCHEMA = {
 				{ value: "anthropic", label: "Anthropic", description: "Use Anthropic-style in-band tool calls." },
 				{ value: "deepseek", label: "DeepSeek", description: "Use DeepSeek-style in-band tool calls." },
 				{ value: "harmony", label: "Harmony", description: "Use Harmony-style in-band tool calls." },
-				{ value: "pi", label: "Pi", description: "Use Pi-style in-band tool calls." },
-				{ value: "qwen3", label: "Qwen3", description: "Use Qwen3-style in-band tool calls." },
+				{ value: "pi", label: "Pi", description: "Use the Pi owned dialect." },
+				{ value: "qwen3", label: "Qwen3", description: "Use the Qwen3 owned dialect." },
+				{ value: "gemini", label: "Gemini", description: "Use the Gemini owned dialect." },
+				{ value: "gemma", label: "Gemma", description: "Use the Gemma owned dialect." },
 			],
 		},
 	},