@clanker-code/pi-subagents 0.10.5

package/dist/schedule.js

@@ -0,0 +1,338 @@
+/**
+ * schedule.ts — `SubagentScheduler`: timer-driven dispatcher of scheduled subagents.
+ *
+ * Mirrors the engine shape of pi-cron-schedule/src/scheduler.ts:
+ *   - two-Map split (jobs = croner Cron, intervals = setInterval/setTimeout)
+ *   - addJob/removeJob/updateJob/scheduleJob/unscheduleJob/executeJob
+ *   - static parsers for cron / "+10m" / "5m" / ISO formats
+ *
+ * Differences vs pi-cron-schedule:
+ *   - Persistence is via ScheduleStore (PID-locked, session-scoped, atomic).
+ *   - `executeJob` calls `manager.spawn(..., { bypassQueue: true })` instead
+ *     of dispatching a user message — schedule fires bypass maxConcurrent so
+ *     a 5-minute interval can't be deferred behind 4 long-running agents.
+ *   - Result delivery is implicit: spawn → background completion → existing
+ *     steering-style `subagent-notification` path. No new delivery code.
+ */
+import { Cron } from "croner";
+import { nanoid } from "nanoid";
+import { resolveModel } from "./model-resolver.js";
+export class SubagentScheduler {
+    jobs = new Map();
+    intervals = new Map();
+    store;
+    pi;
+    ctx;
+    manager;
+    /** Start the scheduler: bind to a session's store and arm enabled jobs. */
+    start(pi, ctx, manager, store) {
+        this.pi = pi;
+        this.ctx = ctx;
+        this.manager = manager;
+        this.store = store;
+        for (const job of store.list()) {
+            if (job.enabled)
+                this.scheduleJob(job);
+        }
+    }
+    /** Stop all timers; drop refs. Safe to call repeatedly. */
+    stop() {
+        for (const cron of this.jobs.values())
+            cron.stop();
+        this.jobs.clear();
+        for (const t of this.intervals.values())
+            clearTimeout(t);
+        this.intervals.clear();
+        this.store = undefined;
+        this.pi = undefined;
+        this.ctx = undefined;
+        this.manager = undefined;
+    }
+    /** True if start() has bound a store and the scheduler is active. */
+    isActive() {
+        return this.store !== undefined;
+    }
+    list() {
+        return this.store?.list() ?? [];
+    }
+    /**
+     * Build a `ScheduledSubagent` from user input. Validates the schedule
+     * format and tags `scheduleType`. Throws on invalid input.
+     */
+    buildJob(input) {
+        const detected = SubagentScheduler.detectSchedule(input.schedule);
+        return {
+            id: nanoid(10),
+            name: input.name,
+            description: input.description,
+            schedule: detected.normalized,
+            scheduleType: detected.type,
+            intervalMs: detected.intervalMs,
+            subagent_type: input.subagent_type,
+            prompt: input.prompt,
+            model: input.model,
+            thinking: input.thinking,
+            max_turns: input.max_turns,
+            isolated: input.isolated,
+            isolation: input.isolation,
+            enabled: true,
+            createdAt: new Date().toISOString(),
+            runCount: 0,
+        };
+    }
+    /** Add a job, persist, and arm if enabled. Returns the stored job. */
+    addJob(input) {
+        const store = this.requireStore();
+        if (store.hasName(input.name)) {
+            throw new Error(`A scheduled job named "${input.name}" already exists.`);
+        }
+        const job = this.buildJob(input);
+        store.add(job);
+        if (job.enabled)
+            this.scheduleJob(job);
+        this.emit({ type: "added", job });
+        return job;
+    }
+    removeJob(id) {
+        const store = this.requireStore();
+        if (!store.get(id))
+            return false;
+        this.unscheduleJob(id);
+        const ok = store.remove(id);
+        if (ok)
+            this.emit({ type: "removed", jobId: id });
+        return ok;
+    }
+    /** Toggle / mutate a job. Re-arms based on the new `enabled` state. */
+    updateJob(id, patch) {
+        const store = this.requireStore();
+        const updated = store.update(id, patch);
+        if (!updated)
+            return undefined;
+        this.unscheduleJob(id);
+        if (updated.enabled)
+            this.scheduleJob(updated);
+        this.emit({ type: "updated", job: updated });
+        return updated;
+    }
+    /** Next-run time as ISO, or undefined if not currently armed. */
+    getNextRun(jobId) {
+        const cron = this.jobs.get(jobId);
+        if (cron)
+            return cron.nextRun()?.toISOString();
+        const job = this.store?.get(jobId);
+        if (!job?.enabled)
+            return undefined;
+        if (job.scheduleType === "once")
+            return job.schedule;
+        if (job.scheduleType === "interval" && job.intervalMs) {
+            // Before the first fire there's no `lastRun`, so fall back to "now" —
+            // accurate at create time (setInterval was just armed) and within
+            // intervalMs of correct in any pre-first-fire view.
+            const base = job.lastRun ? new Date(job.lastRun).getTime() : Date.now();
+            return new Date(base + job.intervalMs).toISOString();
+        }
+        return undefined;
+    }
+    // ── Scheduling primitives ────────────────────────────────────────────
+    scheduleJob(job) {
+        const store = this.store;
+        if (!store)
+            return;
+        try {
+            if (job.scheduleType === "interval" && job.intervalMs) {
+                const t = setInterval(() => this.executeJob(job.id), job.intervalMs);
+                this.intervals.set(job.id, t);
+            }
+            else if (job.scheduleType === "once") {
+                const target = new Date(job.schedule).getTime();
+                const delay = target - Date.now();
+                if (delay > 0) {
+                    const t = setTimeout(() => {
+                        this.executeJob(job.id);
+                        // Auto-disable one-shots after they fire (mirrors pi-cron-schedule)
+                        store.update(job.id, { enabled: false });
+                        const updated = store.get(job.id);
+                        if (updated)
+                            this.emit({ type: "updated", job: updated });
+                    }, delay);
+                    this.intervals.set(job.id, t);
+                }
+                else {
+                    // Past timestamp — disable, mark error, never fire
+                    store.update(job.id, { enabled: false, lastStatus: "error" });
+                    this.emit({ type: "error", jobId: job.id, error: `Scheduled time ${job.schedule} is in the past` });
+                }
+            }
+            else {
+                const cron = new Cron(job.schedule, () => this.executeJob(job.id));
+                this.jobs.set(job.id, cron);
+            }
+        }
+        catch (err) {
+            this.emit({ type: "error", jobId: job.id, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    unscheduleJob(id) {
+        const cron = this.jobs.get(id);
+        if (cron) {
+            cron.stop();
+            this.jobs.delete(id);
+        }
+        const t = this.intervals.get(id);
+        if (t) {
+            clearTimeout(t);
+            clearInterval(t);
+            this.intervals.delete(id);
+        }
+    }
+    /**
+     * Fire a job: persist running state, spawn (bypassing the concurrency
+     * queue), persist completion. Fire-and-forget: the timer tick returns
+     * immediately so other jobs keep firing.
+     */
+    executeJob(id) {
+        const store = this.store;
+        const pi = this.pi;
+        const ctx = this.ctx;
+        const manager = this.manager;
+        if (!store || !pi || !ctx || !manager)
+            return;
+        const job = store.get(id);
+        if (!job?.enabled)
+            return;
+        store.update(id, { lastStatus: "running" });
+        // Resolve model at fire time — registry contents may have changed since the
+        // job was created (auth added/removed). Fall back silently to spawn-default
+        // if resolution fails; the spawn path handles undefined model gracefully.
+        let resolvedModel;
+        if (job.model) {
+            const r = resolveModel(job.model, ctx.modelRegistry);
+            if (typeof r !== "string")
+                resolvedModel = r;
+        }
+        let agentId;
+        try {
+            agentId = manager.spawn(pi, ctx, job.subagent_type, job.prompt, {
+                description: job.description,
+                isBackground: true,
+                bypassQueue: true,
+                model: resolvedModel,
+                maxTurns: job.max_turns,
+                isolated: job.isolated,
+                thinkingLevel: job.thinking,
+                isolation: job.isolation,
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            store.update(id, { lastRun: new Date().toISOString(), lastStatus: "error" });
+            this.emit({ type: "error", jobId: id, error });
+            return;
+        }
+        this.emit({ type: "fired", jobId: id, agentId, name: job.name });
+        const record = manager.getRecord(agentId);
+        const finalize = (status) => {
+            const next = this.getNextRun(id);
+            const current = store.get(id);
+            store.update(id, {
+                lastRun: new Date().toISOString(),
+                lastStatus: status,
+                runCount: (current?.runCount ?? 0) + 1,
+                nextRun: next,
+            });
+        };
+        // AgentManager's promise resolves either way (its .catch returns ""), so we
+        // can't infer success/failure from the promise — read record.status instead.
+        // Terminal states: completed/steered = success; error/aborted/stopped = error.
+        if (record?.promise) {
+            record.promise
+                .then(() => {
+                const r = manager.getRecord(agentId);
+                const failed = r?.status === "error" || r?.status === "aborted" || r?.status === "stopped";
+                finalize(failed ? "error" : "success");
+            })
+                .catch(() => finalize("error"));
+        }
+        else {
+            // Spawn returned without a promise (defensive — bypassQueue path always sets one).
+            finalize("success");
+        }
+    }
+    emit(event) {
+        if (this.pi)
+            this.pi.events.emit("subagents:scheduled", event);
+    }
+    requireStore() {
+        if (!this.store)
+            throw new Error("Scheduler not started — no active session.");
+        return this.store;
+    }
+    // ── Format detection / parsers (statics — pure) ──────────────────────
+    /**
+     * Sniff a schedule string and tag its type. Throws on invalid input.
+     * Order matters: relative ("+10m") and interval ("5m") both match digit+unit;
+     * relative requires the leading "+" to disambiguate.
+     */
+    static detectSchedule(s) {
+        const trimmed = s.trim();
+        // "+10m" — relative one-shot
+        const rel = SubagentScheduler.parseRelativeTime(trimmed);
+        if (rel !== null)
+            return { type: "once", normalized: rel };
+        // "5m" — interval
+        const ivl = SubagentScheduler.parseInterval(trimmed);
+        if (ivl !== null)
+            return { type: "interval", intervalMs: ivl, normalized: trimmed };
+        // ISO timestamp — one-shot. Reject past timestamps upfront so we never
+        // create a dead-on-arrival record (scheduleJob's safety net still catches
+        // micro-races from `+0s`-style relatives).
+        if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+            const d = new Date(trimmed);
+            if (!Number.isNaN(d.getTime())) {
+                if (d.getTime() <= Date.now()) {
+                    throw new Error(`Scheduled time ${d.toISOString()} is in the past.`);
+                }
+                return { type: "once", normalized: d.toISOString() };
+            }
+        }
+        // Cron — 6-field
+        const cronCheck = SubagentScheduler.validateCronExpression(trimmed);
+        if (cronCheck.valid)
+            return { type: "cron", normalized: trimmed };
+        throw new Error(`Invalid schedule "${s}". Use 6-field cron (e.g. "0 0 9 * * 1" — 9am every Monday), interval ("5m"/"1h"), or one-shot ("+10m" / ISO).`);
+    }
+    /** 6-field cron — 'second minute hour dom month dow'. */
+    static validateCronExpression(expr) {
+        const fields = expr.trim().split(/\s+/);
+        if (fields.length !== 6) {
+            return {
+                valid: false,
+                error: `Cron must have 6 fields (second minute hour dom month dow), got ${fields.length}. Example: "0 0 9 * * 1" for 9am every Monday.`,
+            };
+        }
+        try {
+            // Croner validates by construction.
+            new Cron(expr, () => { });
+            return { valid: true };
+        }
+        catch (e) {
+            return { valid: false, error: e instanceof Error ? e.message : "Invalid cron expression" };
+        }
+    }
+    /** "+10s"/"+5m"/"+1h"/"+2d" → ISO timestamp. */
+    static parseRelativeTime(s) {
+        const m = s.match(/^\+(\d+)(s|m|h|d)$/);
+        if (!m)
+            return null;
+        const ms = parseInt(m[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+        return new Date(Date.now() + ms).toISOString();
+    }
+    /** "10s"/"5m"/"1h"/"2d" → milliseconds. */
+    static parseInterval(s) {
+        const m = s.match(/^(\d+)(s|m|h|d)$/);
+        if (!m)
+            return null;
+        return parseInt(m[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+    }
+}

package/dist/settings.d.ts

@@ -0,0 +1,135 @@
+import type { JoinMode } from "./types.js";
+import type { WidgetDisplayMode } from "./ui/agent-widget-tree.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;
+    /**
+     * When true, the effective model of each subagent spawn is validated
+     * against `enabledModels` from pi's settings — both global
+     * (`<agentDir>/settings.json`) and project-local (`<cwd>/.pi/settings.json`),
+     * with project overriding global (mirrors pi's SettingsManager deep-merge).
+     *
+     * scopeModels guards against runtime LLM choices, not user-level config.
+     * Out-of-scope handling reflects this:
+     *   - Caller-supplied via `Agent({ model: "..." })` (only when frontmatter
+     *     has no `model:`, since frontmatter is authoritative): hard error
+     *     returned to the orchestrator, listing the allowed models. The LLM
+     *     made an explicit out-of-scope choice and gets explicit feedback.
+     *   - Frontmatter-pinned: warning toast + the pinned model runs. The
+     *     agent's author/installer chose this; trust it.
+     *   - Parent-inherited (neither caller nor frontmatter sets a model):
+     *     warning toast + parent's model runs. The user chose the parent's
+     *     model when starting the session; trust it.
+     *
+     * No-op when pi's `enabledModels` is empty or absent — nothing to validate
+     * against. Defaults to false: subagents may use any model.
+     */
+    scopeModels?: boolean;
+    /**
+     * When true, the three built-in default agents (general-purpose, Explore, Plan)
+     * are not registered at startup. User-defined agents from .pi/agents/*.md are
+     * completely unaffected — only the hardcoded DEFAULT_AGENTS are suppressed.
+     * Defaults to false.
+     */
+    disableDefaultAgents?: boolean;
+    /**
+     * Which Agent tool description the LLM sees. "full" (default) is the rich
+     * Claude Code-style prompt; "compact" is a ~75% smaller version (one-line
+     * agent type list, terse usage notes) for small/local models where tool-spec
+     * tokens are expensive; "custom" reads `.pi/agent-tool-description.md`
+     * (project, falling back to `<agentDir>/agent-tool-description.md`) with
+     * `{{placeholder}}` substitution — a missing/empty file falls back to "full".
+     * The mode is read once at tool registration — changing it applies on the
+     * next pi session.
+     */
+    toolDescriptionMode?: ToolDescriptionMode;
+    /**
+     * How long (seconds) `get_subagent_result wait:true` blocks before returning
+     * the agent's current status instead of its result. Bounds the parent turn so
+     * a long-running subagent can't wedge it indefinitely; the caller re-invokes
+     * to keep waiting. Default 270 (4m30s) to stay under the typical 5-minute LLM
+     * prompt-cache window. Range 30–3600.
+     */
+    waitTimeoutSeconds?: number;
+    /**
+     * The keyboard shortcut that aborts the current turn AND auto-sends queued
+     * message(s) as the next turn (instead of Escape, which dumps the queue back
+     * into the editor for manual re-submit). Default "f9" — a distinct key on
+     * every terminal. Override with any KeyId (e.g. "shift+escape", "f8").
+     * Read at session start; a change applies on the next pi session.
+     * The PI_ABORT_RESEND_KEY env var, if set, takes precedence over this.
+     */
+    abortResendKey?: string;
+    /** How the live subagent widget renders recursive trees. Defaults to auto. */
+    widgetDisplayMode?: WidgetDisplayMode;
+}
+export type ToolDescriptionMode = "full" | "compact" | "custom";
+/** Default wait timeout for `get_subagent_result wait:true` (4.5 minutes). */
+export declare const DEFAULT_WAIT_TIMEOUT_SECONDS = 270;
+/** 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;
+    setScopeModels: (enabled: boolean) => void;
+    setDisableDefaultAgents: (b: boolean) => void;
+    setToolDescriptionMode: (mode: ToolDescriptionMode) => void;
+    setWaitTimeoutSeconds: (seconds: number) => void;
+    setAbortResendKey: (key: string) => void;
+    setWidgetDisplayMode: (mode: WidgetDisplayMode) => void;
+}
+/** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
+export type SettingsEmit = (event: string, payload: unknown) => void;
+/** Load merged settings: global provides defaults, project overrides. */
+export declare function loadSettings(cwd?: string): SubagentsSettings;
+/**
+ * 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 declare function saveSettings(s: SubagentsSettings, cwd?: string): boolean;
+/** Apply persisted settings to the in-memory state via caller-supplied setters. */
+export declare function applySettings(s: SubagentsSettings, appliers: SettingsAppliers): void;
+/**
+ * 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 declare function persistToastFor(successMsg: string, persisted: boolean): {
+    message: string;
+    level: "info" | "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 declare function applyAndEmitLoaded(appliers: SettingsAppliers, emit: SettingsEmit, cwd?: string): SubagentsSettings;
+/**
+ * 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 declare function saveAndEmitChanged(snapshot: SubagentsSettings, successMsg: string, emit: SettingsEmit, cwd?: string): {
+    message: string;
+    level: "info" | "warning";
+};

package/dist/settings.js

@@ -0,0 +1,168 @@
+// 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 "@earendil-works/pi-coding-agent";
+/** Default wait timeout for `get_subagent_result wait:true` (4.5 minutes). */
+export const DEFAULT_WAIT_TIMEOUT_SECONDS = 270;
+const VALID_JOIN_MODES = new Set(["async", "group", "smart"]);
+const VALID_TOOL_DESCRIPTION_MODES = new Set(["full", "compact", "custom"]);
+const VALID_WIDGET_DISPLAY_MODES = new Set(["auto", "rich", "compact"]);
+// 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;
+const WAIT_TIMEOUT_MIN = 30;
+const WAIT_TIMEOUT_MAX = 3600;
+/** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
+function sanitize(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const r = raw;
+    const out = {};
+    if (Number.isInteger(r.maxConcurrent) &&
+        r.maxConcurrent >= 1 &&
+        r.maxConcurrent <= MAX_CONCURRENT_CEILING) {
+        out.maxConcurrent = r.maxConcurrent;
+    }
+    if (Number.isInteger(r.defaultMaxTurns) &&
+        r.defaultMaxTurns >= 0 &&
+        r.defaultMaxTurns <= MAX_TURNS_CEILING) {
+        out.defaultMaxTurns = r.defaultMaxTurns;
+    }
+    if (Number.isInteger(r.graceTurns) &&
+        r.graceTurns >= 1 &&
+        r.graceTurns <= GRACE_TURNS_CEILING) {
+        out.graceTurns = r.graceTurns;
+    }
+    if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
+        out.defaultJoinMode = r.defaultJoinMode;
+    }
+    if (typeof r.schedulingEnabled === "boolean") {
+        out.schedulingEnabled = r.schedulingEnabled;
+    }
+    if (typeof r.scopeModels === "boolean") {
+        out.scopeModels = r.scopeModels;
+    }
+    if (typeof r.disableDefaultAgents === "boolean") {
+        out.disableDefaultAgents = r.disableDefaultAgents;
+    }
+    if (typeof r.toolDescriptionMode === "string" && VALID_TOOL_DESCRIPTION_MODES.has(r.toolDescriptionMode)) {
+        out.toolDescriptionMode = r.toolDescriptionMode;
+    }
+    if (Number.isInteger(r.waitTimeoutSeconds) &&
+        r.waitTimeoutSeconds >= WAIT_TIMEOUT_MIN &&
+        r.waitTimeoutSeconds <= WAIT_TIMEOUT_MAX) {
+        out.waitTimeoutSeconds = r.waitTimeoutSeconds;
+    }
+    if (typeof r.abortResendKey === "string" && r.abortResendKey.trim() !== "") {
+        out.abortResendKey = r.abortResendKey.trim();
+    }
+    if (typeof r.widgetDisplayMode === "string" && VALID_WIDGET_DISPLAY_MODES.has(r.widgetDisplayMode)) {
+        out.widgetDisplayMode = r.widgetDisplayMode;
+    }
+    return out;
+}
+function globalPath() {
+    return join(getAgentDir(), "subagents.json");
+}
+function projectPath(cwd) {
+    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) {
+    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 = process.cwd()) {
+    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, cwd = process.cwd()) {
+    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, appliers) {
+    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);
+    if (typeof s.scopeModels === "boolean")
+        appliers.setScopeModels(s.scopeModels);
+    if (typeof s.disableDefaultAgents === "boolean")
+        appliers.setDisableDefaultAgents(s.disableDefaultAgents);
+    if (s.toolDescriptionMode)
+        appliers.setToolDescriptionMode(s.toolDescriptionMode);
+    if (typeof s.waitTimeoutSeconds === "number")
+        appliers.setWaitTimeoutSeconds(s.waitTimeoutSeconds);
+    if (typeof s.abortResendKey === "string")
+        appliers.setAbortResendKey(s.abortResendKey);
+    if (s.widgetDisplayMode)
+        appliers.setWidgetDisplayMode(s.widgetDisplayMode);
+}
+/**
+ * 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, persisted) {
+    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, emit, cwd = process.cwd()) {
+    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, successMsg, emit, cwd = process.cwd()) {
+    const persisted = saveSettings(snapshot, cwd);
+    emit("subagents:settings_changed", { settings: snapshot, persisted });
+    return persistToastFor(successMsg, persisted);
+}

package/dist/skill-loader.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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).
+ */
+export interface PreloadedSkill {
+    name: string;
+    content: string;
+}
+export declare function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[];