@esso0428/pi-subagents 0.15.0

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/status-note.d.ts

@@ -0,0 +1,13 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export declare function getStatusNote(status: string): string;

package/dist/status-note.js

@@ -0,0 +1,24 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export function getStatusNote(status) {
+    switch (status) {
+        case "stopped":
+            return " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+        case "aborted":
+            return " (aborted — hit the turn limit before completion; output may be incomplete)";
+        case "steered":
+            return " (wrapped up at the turn limit — output may be partial)";
+        default:
+            return "";
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * 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[];
+    /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
+     * Presence of any entry flips extension tools to an explicit allowlist. */
+    extSelectors?: 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;
+    /** Extension-name denylist applied after the `extensions:` include set. Exclude wins.
+     * Plain canonical names only (case-insensitive); no paths, no wildcard. */
+    excludeExtensions?: string[];
+    /** true = inherit all, string[] = only listed, false = none */
+    skills: true | string[] | false;
+    model?: string;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    /** Persist this subagent as a normal pi session instead of keeping it in memory only. */
+    persistSession?: boolean;
+    /** Write the subagent's .output transcript. Defaults to true; false suppresses only that transcript. */
+    outputTranscript?: boolean;
+    /** Optional session directory used when persistSession is true. Omitted = pi's normal session location. */
+    sessionDir?: string;
+    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';
+/**
+ * Display mode for the persistent above-editor agent widget.
+ * - `all`: show every agent (foreground + background).
+ * - `background`: hide foreground agents (they already render inline as the
+ *   Agent tool result, #118); show background/queued/scheduled/RPC.
+ * - `off`: hide the widget entirely.
+ */
+export type WidgetMode = 'all' | 'background' | 'off';
+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;
+        baseSha: string;
+        workPath: 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;
+    /**
+     * Whether this agent was spawned to run in the background. Tri-state, set at
+     * spawn from `SpawnOptions.isBackground`: `true` = background, `false` =
+     * foreground (has an inline Agent tool-result surface), `undefined` = the
+     * caller never declared it (e.g. a cross-extension RPC spawn, which is detached
+     * and has no inline surface). The widget's background-only filter keys off this
+     * — and excludes only explicit `false`, so `undefined` agents stay visible.
+     * Reliable across ALL spawn paths, unlike the UI-only `invocation` snapshot,
+     * which only the Agent-tool path populates.
+     */
+    isBackground?: boolean;
+    /** 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,160 @@
+/**
+ * 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, WidgetMode } 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;
+}
+/** Apply foreground styling while restoring it after nested foreground/full ANSI resets. */
+export declare function fgPreservingNestedStyles(theme: Theme, color: string, text: string): 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;
+    /**
+     * Read live at render time. Selects which agents the widget shows — see
+     * `WidgetMode`. Defaults to `"all"` when a caller supplies no policy; the
+     * extension supplies one defaulting to `"background"`.
+     */
+    private mode;
+    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>, 
+    /**
+     * Read live at render time. Selects which agents the widget shows — see
+     * `WidgetMode`. Defaults to `"all"` when a caller supplies no policy; the
+     * extension supplies one defaulting to `"background"`.
+     */
+    mode?: () => WidgetMode);
+    /**
+     * Agents eligible for the widget, per the current `WidgetMode`:
+     *   - `off`: none (the widget's existing empty-state path hides it entirely).
+     *   - `background`: drop only agents *known* to be foreground
+     *     (`isBackground === false`); keep everything else — background, queued,
+     *     scheduled, or RPC-spawned (`undefined`). Keying off the `isBackground`
+     *     record flag rather than the UI-only `invocation` snapshot (which only the
+     *     Agent-tool path sets), and excluding rather than allow-listing, means
+     *     only proven-foreground runs drop out — nothing else silently vanishes.
+     *   - `all`: every agent.
+     */
+    private widgetAgents;
+    /** 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;
+}