@clanker-code/pi-subagents 0.10.5

package/RELEASE.md

@@ -0,0 +1,39 @@
+# Release Process
+
+1. **Prepare changes**
+   - Ensure all work is on `master` and CI/tests pass:
+     ```bash
+     npm run lint
+     npm run typecheck
+     npm test
+     npm run build
+     ```
+
+2. **Update documentation**
+   - Bump `version` in `package.json`.
+   - Add a dated `[x.y.z]` section to `CHANGELOG.md` under `[Unreleased]`.
+   - **Update `README.md` to describe any new or changed user-facing features.**
+
+3. **Commit and push**
+   ```bash
+   git add package.json CHANGELOG.md README.md
+   git commit -m "chore(release): bump version to x.y.z"
+   git push
+   ```
+
+4. **Create a GitHub release**
+   - Tag the commit matching the version:
+     ```bash
+     git tag vX.Y.Z
+     git push origin vX.Y.Z
+     ```
+   - Open the [GitHub releases page](https://github.com/clankercode/pi-subagents/releases) and create a new release for the tag.
+   - Copy the relevant `[x.y.z]` section from `CHANGELOG.md` into the release notes.
+   - Highlight any breaking changes, fork-specific features, or upgrade notes.
+
+5. **Publish to npm**
+   ```bash
+   npm publish
+   ```
+
+> Note: `prepublishOnly` already runs lint, typecheck, tests, and build before publishing.

package/dist/abort-resend.d.ts

@@ -0,0 +1,35 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/**
+ * Register a keyboard shortcut that aborts the current streaming turn and
+ * auto-sends any queued follow-up message(s) as the next turn — instead of the
+ * default Escape behavior (restore the queue into the editor for editing).
+ *
+ * Key precedence: PI_ABORT_RESEND_KEY env var > the `abortResendKey` setting >
+ * "f9" (the default — a distinct key on every terminal; shift+escape is
+ * indistinguishable from escape on terminals that don't negotiate the kitty
+ * keyboard protocol).
+ *
+ * This is a workaround for a core-harness behavior: Escape always calls
+ * `restoreQueuedMessagesToEditor({ abort: true })`, putting queued messages back
+ * in the editor. There is no extension API to flush the internal queue as a turn
+ * atomically. This shortcut reads the text that abort just restored into the
+ * editor, clears it, and re-injects it as a fresh turn.
+ *
+ * Mechanics:
+ *  1. `ctx.abort()` is synchronous: it calls restoreQueuedMessagesToEditor which
+ *     sets the editor text, THEN agent.abort(). So getEditorText() right after
+ *     captures the restored queue.
+ *  2. `pi.sendUserMessage(text, { deliverAs: "steer" })` injects into a fresh turn.
+ *     MUST be awaited with try/catch — an unhandled rejection would discard the
+ *     text silently after the editor has already been cleared, losing the message.
+ *
+ * State handling:
+ *  - idle                       → no-op (preserves any editor draft)
+ *  - streaming, nothing queued  → plain abort (preserves editor draft)
+ *  - streaming, queued messages → abort + clear restored text + resend as steer
+ *
+ * The shortcut is registered once at session start, so changing the setting
+ * applies on the next pi session (consistent with schedulingEnabled /
+ * toolDescriptionMode).
+ */
+export declare function registerAbortResend(pi: ExtensionAPI, settingKey?: string): void;

package/dist/abort-resend.js

@@ -0,0 +1,71 @@
+/**
+ * Register a keyboard shortcut that aborts the current streaming turn and
+ * auto-sends any queued follow-up message(s) as the next turn — instead of the
+ * default Escape behavior (restore the queue into the editor for editing).
+ *
+ * Key precedence: PI_ABORT_RESEND_KEY env var > the `abortResendKey` setting >
+ * "f9" (the default — a distinct key on every terminal; shift+escape is
+ * indistinguishable from escape on terminals that don't negotiate the kitty
+ * keyboard protocol).
+ *
+ * This is a workaround for a core-harness behavior: Escape always calls
+ * `restoreQueuedMessagesToEditor({ abort: true })`, putting queued messages back
+ * in the editor. There is no extension API to flush the internal queue as a turn
+ * atomically. This shortcut reads the text that abort just restored into the
+ * editor, clears it, and re-injects it as a fresh turn.
+ *
+ * Mechanics:
+ *  1. `ctx.abort()` is synchronous: it calls restoreQueuedMessagesToEditor which
+ *     sets the editor text, THEN agent.abort(). So getEditorText() right after
+ *     captures the restored queue.
+ *  2. `pi.sendUserMessage(text, { deliverAs: "steer" })` injects into a fresh turn.
+ *     MUST be awaited with try/catch — an unhandled rejection would discard the
+ *     text silently after the editor has already been cleared, losing the message.
+ *
+ * State handling:
+ *  - idle                       → no-op (preserves any editor draft)
+ *  - streaming, nothing queued  → plain abort (preserves editor draft)
+ *  - streaming, queued messages → abort + clear restored text + resend as steer
+ *
+ * The shortcut is registered once at session start, so changing the setting
+ * applies on the next pi session (consistent with schedulingEnabled /
+ * toolDescriptionMode).
+ */
+export function registerAbortResend(pi, settingKey) {
+    const ABORT_RESEND_SHORTCUT = (process.env.PI_ABORT_RESEND_KEY ?? settingKey ?? "f9");
+    pi.registerShortcut(ABORT_RESEND_SHORTCUT, {
+        description: "Abort current turn and auto-send queued message(s) as the next turn",
+        handler: async (ctx) => {
+            // Idle: nothing to abort; leave any editor draft untouched.
+            if (ctx.isIdle())
+                return;
+            // Snapshot whether anything is queued BEFORE abort — abort clears the
+            // internal queue and restores it to the editor, so hasPendingMessages()
+            // would read false afterwards.
+            const hadQueued = ctx.hasPendingMessages();
+            // Abort restores queued messages to the editor synchronously, then aborts.
+            ctx.abort();
+            // No queued message → this was a plain abort; preserve the editor draft.
+            if (!hadQueued)
+                return;
+            // Read the text abort just restored into the editor, clear it, and re-inject
+            // as a fresh turn. MUST await + try/catch so errors surface rather than
+            // silently swallowing the queued text (an unhandled rejection from inside
+            // the non-awaited sendUserMessage call would discard the text after the
+            // editor has already been cleared by restoreQueuedMessagesToEditor).
+            const text = ctx.ui.getEditorText().trim();
+            ctx.ui.setEditorText("");
+            if (text) {
+                try {
+                    await pi.sendUserMessage(text, { deliverAs: "steer" });
+                }
+                catch (err) {
+                    console.error("[abort-resend] sendUserMessage failed:", err);
+                    // Fall back to putting the text back in the editor so the user can
+                    // re-submit manually.
+                    ctx.ui.setEditorText(text);
+                }
+            }
+        },
+    });
+}

package/dist/agent-details.d.ts

@@ -0,0 +1,17 @@
+import type { AgentActivity, AgentDetails } from "./ui/agent-widget.js";
+import type { LifetimeUsage } from "./usage.js";
+/** Format an agent's lifetime token total, or "" when zero. */
+export declare function formatLifetimeTokens(o: {
+    lifetimeUsage: LifetimeUsage;
+}): string;
+/** Build AgentDetails from a base plus record-specific fields. */
+export declare function buildDetails(base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">, record: {
+    toolUses: number;
+    startedAt: number;
+    completedAt?: number;
+    status: string;
+    error?: string;
+    id?: string;
+    session?: any;
+    lifetimeUsage: LifetimeUsage;
+}, activity?: AgentActivity, overrides?: Partial<AgentDetails>): AgentDetails;

package/dist/agent-details.js

@@ -0,0 +1,22 @@
+import { formatTokens } from "./ui/agent-widget.js";
+import { getLifetimeTotal } from "./usage.js";
+/** Format an agent's lifetime token total, or "" when zero. */
+export function formatLifetimeTokens(o) {
+    const t = getLifetimeTotal(o.lifetimeUsage);
+    return t > 0 ? formatTokens(t) : "";
+}
+/** Build AgentDetails from a base plus record-specific fields. */
+export function buildDetails(base, record, activity, overrides) {
+    return {
+        ...base,
+        toolUses: record.toolUses,
+        tokens: formatLifetimeTokens(record),
+        turnCount: activity?.turnCount,
+        maxTurns: activity?.maxTurns,
+        durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
+        status: record.status,
+        agentId: record.id,
+        error: record.error,
+        ...overrides,
+    };
+}

package/dist/agent-manager.d.ts

@@ -0,0 +1,132 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ToolActivity } from "./agent-runner.js";
+import { type AgentInvocation, type AgentRecord, type IsolationMode, type SubagentType, type ThinkingLevel } from "./types.js";
+export type OnAgentComplete = (record: AgentRecord) => void;
+export type OnAgentStart = (record: AgentRecord) => void;
+export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
+export type CompactionInfo = {
+    reason: "manual" | "threshold" | "overflow";
+    tokensBefore: number;
+};
+interface SpawnOptions {
+    description: string;
+    model?: Model<any>;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    isBackground?: boolean;
+    /**
+     * Skip the maxConcurrent queue check for this spawn — start immediately even
+     * if the configured concurrency limit would otherwise queue it. Used by the
+     * scheduler so a fired job can't be deferred past its trigger window.
+     */
+    bypassQueue?: boolean;
+    /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
+    isolation?: IsolationMode;
+    /**
+     * Working directory for the agent (absolute path). Default: parent session
+     * cwd. The agent's tools operate here, but .pi config (extensions, skills,
+     * settings, memory) still loads from the parent session's project — the
+     * target directory's `.pi` extensions never execute. With isolation:
+     * "worktree", the worktree is created FROM this directory and the result
+     * branch lands in that repo.
+     */
+    cwd?: string;
+    /** Resolved invocation snapshot captured for UI display. */
+    invocation?: AgentInvocation;
+    /** Recursive subagent depth. Parent/orchestrator is 0; spawned agents are 1..4. */
+    depth?: number;
+    /** Parent subagent id when spawned recursively from another subagent. */
+    parentAgentId?: string;
+    /** Parent abort signal — when aborted, the subagent is also stopped. */
+    signal?: AbortSignal;
+    /** Called on tool start/end with activity info (for streaming progress to UI). */
+    onToolActivity?: (activity: ToolActivity) => void;
+    /** Called on streaming text deltas from the assistant response. */
+    onTextDelta?: (delta: string, fullText: string) => void;
+    /** Called when the agent session is created (for accessing session stats). */
+    onSessionCreated?: (session: AgentSession) => void;
+    /** Called at the end of each agentic turn with the cumulative count. */
+    onTurnEnd?: (turnCount: number) => void;
+    /** Called once per assistant message_end with that message's usage delta. */
+    onAssistantUsage?: (usage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    }) => void;
+    /** Called when the session successfully compacts. */
+    onCompaction?: (info: CompactionInfo) => void;
+}
+interface ResumeOptions {
+    signal?: AbortSignal;
+    onToolActivity?: (activity: ToolActivity) => void;
+    onAssistantUsage?: (usage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    }) => void;
+    onCompaction?: (info: CompactionInfo) => void;
+}
+export declare class AgentManager {
+    private agents;
+    private cleanupInterval;
+    private onComplete?;
+    private onStart?;
+    private onCompact?;
+    private maxConcurrent;
+    /** Base repos worktrees were created from — so dispose() can prune them all,
+     *  not just the parent repo (caller-supplied cwd can target other repos). */
+    private worktreeRepos;
+    /** Queue of background agents waiting to start. */
+    private queue;
+    /** Number of currently running background agents. */
+    private runningBackground;
+    constructor(onComplete?: OnAgentComplete, maxConcurrent?: number, onStart?: OnAgentStart, onCompact?: OnAgentCompact);
+    /** Update the max concurrent background agents limit. */
+    setMaxConcurrent(n: number): void;
+    getMaxConcurrent(): number;
+    /**
+     * Spawn an agent and return its ID immediately (for background use).
+     * If the concurrency limit is reached, the agent is queued.
+     */
+    spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions): string;
+    /** Actually start an agent (called immediately or from queue drain). */
+    private startAgent;
+    /** Start queued agents up to the concurrency limit. */
+    private drainQueue;
+    /**
+     * Spawn an agent and wait for completion (foreground use).
+     * Foreground agents bypass the concurrency queue.
+     */
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">): Promise<AgentRecord>;
+    /** Resume an existing agent session in the background. */
+    resume(id: string, prompt: string, signalOrOptions?: AbortSignal | ResumeOptions): AgentRecord | undefined;
+    getRecord(id: string): AgentRecord | undefined;
+    listAgents(): AgentRecord[];
+    abort(id: string): boolean;
+    /** Dispose a record's session and remove it from the map. */
+    private removeRecord;
+    private cleanup;
+    /**
+     * Remove all completed/stopped/errored records immediately.
+     * Called on session start/switch so tasks from a prior session don't persist.
+     */
+    clearCompleted(): void;
+    /** Whether any agents are still running or queued. */
+    hasRunning(): boolean;
+    /** Abort all running and queued agents immediately. */
+    abortAll(): number;
+    /** Wait for all running and queued agents to complete (including queued ones). */
+    waitForAll(): Promise<void>;
+    dispose(): void;
+}
+export {};