ultimate-pi 0.3.1 → 0.4.1

package/.pi/extensions/lib/harness-subagents/vendored/settings.ts

@@ -0,0 +1,210 @@
+// Persistence for pi-subagents operational settings.
+// - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
+// - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import type { JoinMode } from "./types.js";
+
+export interface SubagentsSettings {
+	maxConcurrent?: number;
+	/**
+	 * 0 = unlimited — the extension's single source of truth for that convention:
+	 * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
+	 * `/agents` → Settings input prompt explicitly says "0 = unlimited".
+	 */
+	defaultMaxTurns?: number;
+	graceTurns?: number;
+	defaultJoinMode?: JoinMode;
+	/**
+	 * Master switch for the schedule subagent feature. Defaults to `true`.
+	 * When `false`: the `Agent` tool's `schedule` param + its guideline are
+	 * stripped from the tool spec at registration (zero LLM-context cost), the
+	 * scheduler doesn't bind to the session, and the `/agents → Scheduled jobs`
+	 * menu entry is hidden. Schema-level removal applies at extension load
+	 * (next pi session); runtime menu/runtime-fire short-circuit is immediate.
+	 */
+	schedulingEnabled?: boolean;
+}
+
+/** Setter hooks used by applySettings to wire persisted values into in-memory state. */
+export interface SettingsAppliers {
+	setMaxConcurrent: (n: number) => void;
+	setDefaultMaxTurns: (n: number) => void;
+	setGraceTurns: (n: number) => void;
+	setDefaultJoinMode: (mode: JoinMode) => void;
+	setSchedulingEnabled: (b: boolean) => void;
+}
+
+/** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
+export type SettingsEmit = (event: string, payload: unknown) => void;
+
+const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>([
+	"async",
+	"group",
+	"smart",
+]);
+
+// Sanity ceilings — prevent hand-edited configs from asking for values that
+// make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
+// that any realistic power-user setting passes through.
+const MAX_CONCURRENT_CEILING = 1024;
+const MAX_TURNS_CEILING = 10_000;
+const GRACE_TURNS_CEILING = 1_000;
+
+/** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
+function sanitize(raw: unknown): SubagentsSettings {
+	if (!raw || typeof raw !== "object") return {};
+	const r = raw as Record<string, unknown>;
+	const out: SubagentsSettings = {};
+	if (
+		Number.isInteger(r.maxConcurrent) &&
+		(r.maxConcurrent as number) >= 1 &&
+		(r.maxConcurrent as number) <= MAX_CONCURRENT_CEILING
+	) {
+		out.maxConcurrent = r.maxConcurrent as number;
+	}
+	if (
+		Number.isInteger(r.defaultMaxTurns) &&
+		(r.defaultMaxTurns as number) >= 0 &&
+		(r.defaultMaxTurns as number) <= MAX_TURNS_CEILING
+	) {
+		out.defaultMaxTurns = r.defaultMaxTurns as number;
+	}
+	if (
+		Number.isInteger(r.graceTurns) &&
+		(r.graceTurns as number) >= 1 &&
+		(r.graceTurns as number) <= GRACE_TURNS_CEILING
+	) {
+		out.graceTurns = r.graceTurns as number;
+	}
+	if (
+		typeof r.defaultJoinMode === "string" &&
+		VALID_JOIN_MODES.has(r.defaultJoinMode)
+	) {
+		out.defaultJoinMode = r.defaultJoinMode as JoinMode;
+	}
+	if (typeof r.schedulingEnabled === "boolean") {
+		out.schedulingEnabled = r.schedulingEnabled;
+	}
+	return out;
+}
+
+function globalPath(): string {
+	return join(getAgentDir(), "subagents.json");
+}
+
+function projectPath(cwd: string): string {
+	return join(cwd, ".pi", "subagents.json");
+}
+
+/**
+ * Read a settings file. Missing file is silent (returns `{}`). A file that
+ * exists but can't be parsed emits a warning to stderr so users aren't
+ * silently reverted to defaults — and still returns `{}` so startup proceeds.
+ */
+function readSettingsFile(path: string): SubagentsSettings {
+	if (!existsSync(path)) return {};
+	try {
+		return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		console.warn(
+			`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`,
+		);
+		return {};
+	}
+}
+
+/** Load merged settings: global provides defaults, project overrides. */
+export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+	return {
+		...readSettingsFile(globalPath()),
+		...readSettingsFile(projectPath(cwd)),
+	};
+}
+
+/**
+ * Write project-local settings. Global is never touched from code.
+ * Returns `true` on success, `false` if the write (or mkdir) failed so the
+ * caller can surface a warning — persistence isn't fatal but isn't silent.
+ */
+export function saveSettings(
+	s: SubagentsSettings,
+	cwd: string = process.cwd(),
+): boolean {
+	const path = projectPath(cwd);
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, JSON.stringify(s, null, 2), "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Apply persisted settings to the in-memory state via caller-supplied setters. */
+export function applySettings(
+	s: SubagentsSettings,
+	appliers: SettingsAppliers,
+): void {
+	if (typeof s.maxConcurrent === "number")
+		appliers.setMaxConcurrent(s.maxConcurrent);
+	if (typeof s.defaultMaxTurns === "number")
+		appliers.setDefaultMaxTurns(s.defaultMaxTurns);
+	if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
+	if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
+	if (typeof s.schedulingEnabled === "boolean")
+		appliers.setSchedulingEnabled(s.schedulingEnabled);
+}
+
+/**
+ * Format the user-facing toast for a settings mutation. Pure function —
+ * routes the success/failure of `saveSettings` into the right message + level
+ * so the UI layer (index.ts) stays a thin wire between input and notification.
+ */
+export function persistToastFor(
+	successMsg: string,
+	persisted: boolean,
+): { message: string; level: "info" | "warning" } {
+	return persisted
+		? { message: successMsg, level: "info" }
+		: {
+				message: `${successMsg} (session only; failed to persist)`,
+				level: "warning",
+			};
+}
+
+/**
+ * Load merged settings, apply them to in-memory state, and emit the
+ * `subagents:settings_loaded` lifecycle event. Returns the loaded settings so
+ * callers can log/inspect. Extension init wires this once.
+ */
+export function applyAndEmitLoaded(
+	appliers: SettingsAppliers,
+	emit: SettingsEmit,
+	cwd: string = process.cwd(),
+): SubagentsSettings {
+	const settings = loadSettings(cwd);
+	applySettings(settings, appliers);
+	emit("subagents:settings_loaded", { settings });
+	return settings;
+}
+
+/**
+ * Persist a settings snapshot, emit the `subagents:settings_changed` event
+ * (regardless of persist outcome so listeners see the in-memory change), and
+ * return the toast the UI should display. Event payload carries the `persisted`
+ * flag so listeners can react to write failures.
+ */
+export function saveAndEmitChanged(
+	snapshot: SubagentsSettings,
+	successMsg: string,
+	emit: SettingsEmit,
+	cwd: string = process.cwd(),
+): { message: string; level: "info" | "warning" } {
+	const persisted = saveSettings(snapshot, cwd);
+	emit("subagents:settings_changed", { settings: snapshot, persisted });
+	return persistToastFor(successMsg, persisted);
+}

package/.pi/extensions/lib/harness-subagents/vendored/skill-loader.ts

@@ -0,0 +1,108 @@
+/**
+ * skill-loader.ts — Preload named skills.
+ *
+ * Roots, in precedence order:
+ *   - <cwd>/.pi/skills           (project, Pi's standard)
+ *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
+ *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
+ *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
+ *   - ~/.pi/skills               (legacy global, pre-Pi)
+ *
+ * Layout per root:
+ *   - <root>/<name>.md            (flat file at the top level)
+ *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
+ *
+ * Recursion skips dotfile entries and node_modules. A directory that itself contains
+ * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
+ *
+ * Symlinks are rejected for security (deviation from Pi, which follows them).
+ */
+
+import type { Dirent } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
+
+export interface PreloadedSkill {
+	name: string;
+	content: string;
+}
+
+export function preloadSkills(
+	skillNames: string[],
+	cwd: string,
+): PreloadedSkill[] {
+	return skillNames.map((name) => ({
+		name,
+		content: loadSkillContent(name, cwd),
+	}));
+}
+
+function loadSkillContent(name: string, cwd: string): string {
+	if (isUnsafeName(name)) {
+		return `(Skill "${name}" skipped: name contains path traversal characters)`;
+	}
+	const roots = [
+		join(cwd, ".pi", "skills"), // project — Pi standard
+		join(cwd, ".agents", "skills"), // project — Agent Skills spec
+		join(getAgentDir(), "skills"), // user — Pi standard
+		join(homedir(), ".agents", "skills"), // user — Agent Skills spec
+		join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
+	];
+	for (const root of roots) {
+		const content = findInRoot(root, name);
+		if (content !== undefined) return content;
+	}
+	return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
+}
+
+function findInRoot(root: string, name: string): string | undefined {
+	if (isSymlink(root)) return undefined; // reject symlinked roots entirely
+	const flat = safeReadFile(join(root, `${name}.md`))?.trim();
+	if (flat !== undefined) return flat;
+	return findSkillDirectory(root, name);
+}
+
+/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
+function findSkillDirectory(root: string, name: string): string | undefined {
+	if (!existsSync(root)) return undefined;
+	const queue: string[] = [root];
+
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === undefined) continue;
+
+		let entries: Dirent<string>[];
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+
+		// Deterministic byte-order traversal — locale-independent.
+		entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+			// Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
+			const path = join(current, entry.name);
+			const skillMd = join(path, "SKILL.md");
+			const isSkillDir = existsSync(skillMd);
+
+			if (isSkillDir) {
+				if (entry.name === name) {
+					const content = safeReadFile(skillMd)?.trim();
+					if (content !== undefined) return content;
+				}
+				continue; // Pi rule: skills don't nest — don't descend into a skill dir
+			}
+
+			queue.push(path);
+		}
+	}
+	return undefined;
+}

package/.pi/extensions/lib/harness-subagents/vendored/types.ts

@@ -0,0 +1,187 @@
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { LifetimeUsage } from "./usage.js";
+
+export type { ThinkingLevel };
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+export type SubagentType = string;
+
+/** Names of the three embedded default agents. */
+export const DEFAULT_AGENT_NAMES = [
+	"general-purpose",
+	"Explore",
+	"Plan",
+] as const;
+
+/** Memory scope for persistent agent memory. */
+export type MemoryScope = "user" | "project" | "local";
+
+/** Isolation mode for agent execution. */
+export type IsolationMode = "worktree";
+
+/** Unified agent configuration — used for both default and user-defined agents. */
+export interface AgentConfig {
+	name: string;
+	displayName?: string;
+	description: string;
+	builtinToolNames?: string[];
+	/** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
+	disallowedTools?: string[];
+	/** true = inherit all, string[] = only listed, false = none */
+	extensions: true | string[] | false;
+	/** true = inherit all, string[] = only listed, false = none */
+	skills: true | string[] | false;
+	model?: string;
+	thinking?: ThinkingLevel;
+	maxTurns?: number;
+	systemPrompt: string;
+	promptMode: "replace" | "append";
+	/** Default for spawn: fork parent conversation. undefined = caller decides. */
+	inheritContext?: boolean;
+	/** Default for spawn: run in background. undefined = caller decides. */
+	runInBackground?: boolean;
+	/** Default for spawn: no extension tools. undefined = caller decides. */
+	isolated?: boolean;
+	/** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
+	memory?: MemoryScope;
+	/** Isolation mode — "worktree" runs the agent in a temporary git worktree */
+	isolation?: IsolationMode;
+	/** true = this is an embedded default agent (informational) */
+	isDefault?: boolean;
+	/** false = agent is hidden from the registry */
+	enabled?: boolean;
+	/** Where this agent was loaded from */
+	source?: "default" | "project" | "global";
+}
+
+export type JoinMode = "async" | "group" | "smart";
+
+export interface AgentRecord {
+	id: string;
+	type: SubagentType;
+	description: string;
+	status:
+		| "queued"
+		| "running"
+		| "completed"
+		| "steered"
+		| "aborted"
+		| "stopped"
+		| "error";
+	result?: string;
+	error?: string;
+	toolUses: number;
+	startedAt: number;
+	completedAt?: number;
+	session?: AgentSession;
+	abortController?: AbortController;
+	promise?: Promise<string>;
+	groupId?: string;
+	joinMode?: JoinMode;
+	/** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
+	resultConsumed?: boolean;
+	/** Steering messages queued before the session was ready. */
+	pendingSteers?: string[];
+	/** Worktree info if the agent is running in an isolated worktree. */
+	worktree?: { path: string; branch: string };
+	/** Worktree cleanup result after agent completion. */
+	worktreeResult?: { hasChanges: boolean; branch?: string };
+	/** The tool_use_id from the original Agent tool call. */
+	toolCallId?: string;
+	/** Path to the streaming output transcript file. */
+	outputFile?: string;
+	/** Cleanup function for the output file stream subscription. */
+	outputCleanup?: () => void;
+	/**
+	 * Lifetime usage breakdown, accumulated via `message_end` events. Survives
+	 * compaction. Total = input + output + cacheWrite (cacheRead deliberately
+	 * excluded — see issue #38). Initialized to zeros at spawn.
+	 */
+	lifetimeUsage: LifetimeUsage;
+	/** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
+	compactionCount: number;
+	/** Resolved spawn params, captured for UI display. Fixed at spawn time. */
+	invocation?: AgentInvocation;
+}
+
+export interface AgentInvocation {
+	/** Short display name, e.g. "haiku" — only set when different from parent. */
+	modelName?: string;
+	thinking?: ThinkingLevel;
+	maxTurns?: number;
+	isolated?: boolean;
+	inheritContext?: boolean;
+	runInBackground?: boolean;
+	isolation?: IsolationMode;
+}
+
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+	id: string;
+	description: string;
+	status: string;
+	toolUses: number;
+	turnCount: number;
+	maxTurns?: number;
+	totalTokens: number;
+	durationMs: number;
+	outputFile?: string;
+	error?: string;
+	resultPreview: string;
+	/** Additional agents in a group notification. */
+	others?: NotificationDetails[];
+}
+
+export interface EnvInfo {
+	isGitRepo: boolean;
+	branch: string;
+	platform: string;
+}
+
+/**
+ * A subagent spawn registered to fire on a schedule.
+ *
+ * Stored at `<cwd>/.pi/subagent-schedules/<sessionId>.json`. Session-scoped:
+ * survives `/resume` but resets on `/new`, mirroring pi-chonky-tasks.
+ */
+export interface ScheduledSubagent {
+	id: string;
+	/** Unique within store. Defaults to `description`. */
+	name: string;
+	description: string;
+	/** Raw user input — cron expr | "+10m" | ISO | "5m". */
+	schedule: string;
+	scheduleType: "cron" | "once" | "interval";
+	/** Computed at create time for interval/once. */
+	intervalMs?: number;
+
+	// spawn params (subset of Agent tool params; no inherit_context, no resume)
+	subagent_type: SubagentType;
+	prompt: string;
+	model?: string;
+	thinking?: ThinkingLevel;
+	max_turns?: number;
+	isolated?: boolean;
+	isolation?: IsolationMode;
+
+	// state
+	enabled: boolean;
+	/** ISO timestamp. */
+	createdAt: string;
+	lastRun?: string;
+	lastStatus?: "success" | "error" | "running";
+	/** Refreshed on every fire and on store load. */
+	nextRun?: string;
+	runCount: number;
+}
+
+export interface ScheduleStoreData {
+	/** For future migrations. */
+	version: 1;
+	jobs: ScheduledSubagent[];
+}