@gotgenes/pi-subagents 1.0.0

package/dist/settings.js

@@ -0,0 +1,130 @@
+// 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";
+const VALID_JOIN_MODES = new Set(["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) {
+    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;
+    }
+    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);
+}
+/**
+ * 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[];

package/dist/skill-loader.js

@@ -0,0 +1,93 @@
+/**
+ * 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 { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
+export function preloadSkills(skillNames, cwd) {
+    return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+}
+function loadSkillContent(name, cwd) {
+    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, name) {
+    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, name) {
+    if (!existsSync(root))
+        return undefined;
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            continue;
+        let entries;
+        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/dist/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { AgentSession } from "@earendil-works/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 declare const DEFAULT_AGENT_NAMES: readonly ["general-purpose", "Explore", "Plan"];
+/** 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;
+    subagent_type: SubagentType;
+    prompt: string;
+    model?: string;
+    thinking?: ThinkingLevel;
+    max_turns?: number;
+    isolated?: boolean;
+    isolation?: IsolationMode;
+    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[];
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+/** Names of the three embedded default agents. */
+export const DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"];

package/dist/ui/agent-widget.d.ts

@@ -0,0 +1,134 @@
+/**
+ * agent-widget.ts — Persistent widget showing running/completed agents above the editor.
+ *
+ * Displays a tree of agents with animated spinners, live stats, and activity descriptions.
+ * Uses the callback form of setWidget for themed rendering.
+ */
+import type { AgentManager } from "../agent-manager.js";
+import type { AgentInvocation, SubagentType } from "../types.js";
+import { type LifetimeUsage, type SessionLike } from "../usage.js";
+/** Braille spinner frames for animated running indicator. */
+export declare const SPINNER: string[];
+/** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
+export declare const ERROR_STATUSES: Set<string>;
+export type Theme = {
+    fg(color: string, text: string): string;
+    bold(text: string): string;
+};
+export type UICtx = {
+    setStatus(key: string, text: string | undefined): void;
+    setWidget(key: string, content: undefined | ((tui: any, theme: Theme) => {
+        render(): string[];
+        invalidate(): void;
+    }), options?: {
+        placement?: "aboveEditor" | "belowEditor";
+    }): void;
+};
+/** Per-agent live activity state. */
+export interface AgentActivity {
+    activeTools: Map<string, string>;
+    toolUses: number;
+    responseText: string;
+    session?: SessionLike;
+    /** Current turn count. */
+    turnCount: number;
+    /** Effective max turns for this agent (undefined = unlimited). */
+    maxTurns?: number;
+    /** Lifetime usage breakdown — see LifetimeUsage docs. */
+    lifetimeUsage: LifetimeUsage;
+}
+/** Metadata attached to Agent tool results for custom rendering. */
+export interface AgentDetails {
+    displayName: string;
+    description: string;
+    subagentType: string;
+    toolUses: number;
+    tokens: string;
+    durationMs: number;
+    status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
+    /** Human-readable description of what the agent is currently doing. */
+    activity?: string;
+    /** Current spinner frame index (for animated running indicator). */
+    spinnerFrame?: number;
+    /** Short model name if different from parent (e.g. "haiku", "sonnet"). */
+    modelName?: string;
+    /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
+    tags?: string[];
+    /** Current turn count. */
+    turnCount?: number;
+    /** Effective max turns (undefined = unlimited). */
+    maxTurns?: number;
+    agentId?: string;
+    error?: string;
+}
+/** Format a token count compactly: "33.8k token", "1.2M token". */
+export declare function formatTokens(count: number): string;
+/**
+ * Token count with optional context-fill % and compaction-count annotations.
+ * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
+ * Compaction count rendered as `↻N` in dim.
+ *
+ *   "12.3k token"               — no annotations
+ *   "12.3k token (45%)"         — percent only
+ *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ↻2)"    — both
+ */
+export declare function formatSessionTokens(tokens: number, percent: number | null, theme: Theme, compactions?: number): string;
+/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+export declare function formatTurns(turnCount: number, maxTurns?: number | null): string;
+/** Format milliseconds as human-readable duration. */
+export declare function formatMs(ms: number): string;
+/** Format duration from start/completed timestamps. */
+export declare function formatDuration(startedAt: number, completedAt?: number): string;
+/** Get display name for any agent type (built-in or custom). */
+export declare function getDisplayName(type: SubagentType): string;
+/** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
+export declare function getPromptModeLabel(type: SubagentType): string | undefined;
+/** Mode label is not included — callers add it where they want it. */
+export declare function buildInvocationTags(invocation: AgentInvocation | undefined): {
+    modelName?: string;
+    tags: string[];
+};
+/** Build a human-readable activity string from currently-running tools or response text. */
+export declare function describeActivity(activeTools: Map<string, string>, responseText?: string): string;
+export declare class AgentWidget {
+    private manager;
+    private agentActivity;
+    private uiCtx;
+    private widgetFrame;
+    private widgetInterval;
+    /** Tracks how many turns each finished agent has survived. Key: agent ID, Value: turns since finished. */
+    private finishedTurnAge;
+    /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
+    private static readonly ERROR_LINGER_TURNS;
+    /** Whether the widget callback is currently registered with the TUI. */
+    private widgetRegistered;
+    /** Cached TUI reference from widget factory callback, used for requestRender(). */
+    private tui;
+    /** Last status bar text, used to avoid redundant setStatus calls. */
+    private lastStatusText;
+    constructor(manager: AgentManager, agentActivity: Map<string, AgentActivity>);
+    /** Set the UI context (grabbed from first tool execution). */
+    setUICtx(ctx: UICtx): void;
+    /**
+     * Called on each new turn (tool_execution_start).
+     * Ages finished agents and clears those that have lingered long enough.
+     */
+    onTurnStart(): void;
+    /** Ensure the widget update timer is running. */
+    ensureTimer(): void;
+    /** Check if a finished agent should still be shown in the widget. */
+    private shouldShowFinished;
+    /** Record an agent as finished (call when agent completes). */
+    markFinished(agentId: string): void;
+    /** Render a finished agent line. */
+    private renderFinishedLine;
+    /**
+     * Render the widget content. Called from the registered widget's render() callback,
+     * reading live state each time instead of capturing it in a closure.
+     */
+    private renderWidget;
+    /** Force an immediate widget update. */
+    update(): void;
+    dispose(): void;
+}