@ymy88/pi-subagents 0.0.0-stage → 0.24.0

package/dist/completion-outbox.js

@@ -0,0 +1,104 @@
+/**
+ * completion-outbox.ts — When background completions reach the parent.
+ *
+ * Claude Code queues each completion and, after every tool batch, hands the
+ * model everything that queued up in one go: a busy parent sees what finished
+ * during the batch before its next model call, and nothing waits for a sibling.
+ * pi's steering queue would split those into one model call each under its
+ * default `one-at-a-time` mode, so the outbox holds them and sends ONE message
+ * at the boundary instead.
+ *
+ * - Parent busy: held until `turn_end`, which pi emits after the tool batch and
+ *   before it reads the steering queue.
+ * - Parent idle: sent after a short hold, so near-simultaneous completions
+ *   share a turn and `get_subagent_result` still gets a moment to consume one.
+ * - Parent turn aborted (Esc) or failed: held through it — pi clears its own
+ *   queues on Esc — and sent once the run has ended, starting a turn. Claude
+ *   Code keeps an agent's completion queued through Esc the same way and runs
+ *   it as soon as the interrupted turn stops.
+ */
+/** How long an idle parent's notification is held before it is sent. */
+export const NOTIFICATION_HOLD_MS = 200;
+export class CompletionOutbox {
+    send;
+    parentRunning;
+    items = [];
+    timer;
+    constructor(
+    /** Delivers one message as a steer that triggers a turn when the parent is idle. */
+    send, 
+    /** Whether the parent has a run in flight, so a `turn_end` is coming. */
+    parentRunning) {
+        this.send = send;
+        this.parentRunning = parentRunning;
+    }
+    /** A newer completion of the same agent (a resume) replaces its pending one. */
+    add(item) {
+        for (const id of item.ids)
+            this.cancel(id);
+        this.items.push(item);
+        if (!this.parentRunning())
+            this.arm();
+    }
+    /** The parent finished a turn: its tool batch is done, the next model call is not. */
+    onTurnEnd(stopReason) {
+        // An aborted turn ends its run; a failed one may be retried. Either way
+        // what is held waits for the next boundary or the run's end — sent now,
+        // it would sit in a queue pi is about to clear.
+        if (stopReason !== "aborted" && stopReason !== "error")
+            this.flush();
+    }
+    /** The agent's result was read: it must not also be notified. */
+    cancel(id) {
+        for (const item of this.items)
+            item.ids = item.ids.filter(i => i !== id);
+        this.items = this.items.filter(item => item.ids.length > 0);
+    }
+    /**
+     * Completions that landed after the run's last `turn_end` would otherwise wait for the next run.
+     * Called at `agent_end` and again at `agent_settled`: one can land while the ending run is still open.
+     */
+    onAgentEnd() {
+        if (this.items.length > 0)
+            this.arm();
+    }
+    dispose() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.items = [];
+    }
+    /** Not reset by later items: the first completion is never pushed back. */
+    arm() {
+        this.timer ??= setTimeout(() => {
+            this.timer = undefined;
+            this.flush();
+        }, NOTIFICATION_HOLD_MS);
+    }
+    flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        const items = this.items;
+        this.items = [];
+        const messages = items.map(item => item.build(item.ids));
+        if (messages.length === 0)
+            return;
+        // A send from a timer can outlive the session it was meant for (pi -p
+        // tearing down): pi throws on the stale context, and nothing is left to tell.
+        try {
+            this.send(combine(messages));
+        }
+        catch { /* stale context */ }
+    }
+}
+/** One message stays as it was built; several become one message with every agent's details. */
+function combine(messages) {
+    if (messages.length === 1)
+        return messages[0];
+    const [first, ...rest] = messages.flatMap(({ details: { others, ...own } }) => [own, ...(others ?? [])]);
+    return {
+        content: `${messages.length} background tasks finished.\n\n${messages.map(m => m.content).join("\n\n")}`,
+        details: { ...first, others: rest },
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** Extract text from a message content block array. */
+export declare function extractText(content: unknown[]): string;
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export declare function buildParentContext(ctx: ExtensionContext): string;

package/dist/context.js

@@ -0,0 +1,56 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+/** Extract text from a message content block array. */
+export function extractText(content) {
+    return content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text ?? "")
+        .join("\n");
+}
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export function buildParentContext(ctx) {
+    const entries = ctx.sessionManager.getBranch();
+    if (!entries || entries.length === 0)
+        return "";
+    const parts = [];
+    for (const entry of entries) {
+        if (entry.type === "message") {
+            const msg = entry.message;
+            if (msg.role === "user") {
+                const text = typeof msg.content === "string"
+                    ? msg.content
+                    : extractText(msg.content);
+                if (text.trim())
+                    parts.push(`[User]: ${text.trim()}`);
+            }
+            else if (msg.role === "assistant") {
+                const text = extractText(msg.content);
+                if (text.trim())
+                    parts.push(`[Assistant]: ${text.trim()}`);
+            }
+            // Skip toolResult messages — too verbose for context
+        }
+        else if (entry.type === "compaction") {
+            // Include compaction summaries — they're already condensed
+            if (entry.summary) {
+                parts.push(`[Summary]: ${entry.summary}`);
+            }
+        }
+    }
+    if (parts.length === 0)
+        return "";
+    return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}

package/dist/cross-extension-rpc.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cross-extension RPC handlers for the subagents extension.
+ *
+ * Exposes ping, spawn, stop, consume, and steer RPCs over the pi.events event bus,
+ * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
+ *
+ * @see docs/rpc.md — the caller-facing integration reference: spawn options
+ * (including the fields spawnTopLevel strips), every error string, the
+ * completion-notification race, and what protocol version 2 does not promise.
+ */
+import type { AgentRecord } from "./types.js";
+/** Minimal event bus interface needed by the RPC handlers. */
+export interface EventBus {
+    on(event: string, handler: (data: unknown) => void): () => void;
+    emit(event: string, data: unknown): void;
+}
+/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
+export type RpcReply<T = void> = {
+    success: true;
+    data?: T;
+} | {
+    success: false;
+    error: string;
+};
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export declare const PROTOCOL_VERSION = 2;
+/** Minimal AgentManager interface needed by the spawn/stop/consume RPCs. */
+export interface SpawnCapable {
+    spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+    /** Resolves once the spawned agent is running; rejects on a startup failure. */
+    awaitStartup(id: string): Promise<void>;
+    abort(id: string): boolean;
+    /**
+     * The record behind an id, for the stop handler's ownership check. Narrowed
+     * to the two fields `isTopLevelAgent` reads, so the RPC layer keeps its
+     * deliberately shallow view of the manager.
+     */
+    getRecord(id: string): Pick<AgentRecord, "parentAgentId" | "workflowId"> | undefined;
+    /**
+     * Mark a settled agent's result as read by the caller, suppressing the
+     * completion notification — what `get_subagent_result` does when it returns
+     * one. False when there is no such agent, or it has not settled yet.
+     */
+    consumeResult(id: string): boolean;
+    /**
+     * Deliver a message to a running or queued agent's conversation — what
+     * `steer_subagent` does. False when the agent is unknown or has settled.
+     */
+    steer(id: string, message: string): boolean;
+}
+export interface RpcDeps {
+    events: EventBus;
+    pi: unknown;
+    getCtx: () => unknown | undefined;
+    manager: SpawnCapable;
+}
+export interface RpcHandle {
+    unsubPing: () => void;
+    unsubSpawn: () => void;
+    unsubStop: () => void;
+    unsubConsume: () => void;
+    unsubSteer: () => void;
+}
+/**
+ * Register ping, spawn, stop, consume, and steer RPC handlers on the event bus.
+ * Returns unsub functions for cleanup.
+ */
+export declare function registerRpcHandlers(deps: RpcDeps): RpcHandle;

package/dist/cross-extension-rpc.js

@@ -0,0 +1,153 @@
+/**
+ * Cross-extension RPC handlers for the subagents extension.
+ *
+ * Exposes ping, spawn, stop, consume, and steer RPCs over the pi.events event bus,
+ * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
+ *
+ * @see docs/rpc.md — the caller-facing integration reference: spawn options
+ * (including the fields spawnTopLevel strips), every error string, the
+ * completion-notification race, and what protocol version 2 does not promise.
+ */
+import { isTopLevelAgent } from "./agent-manager.js";
+import { resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
+/**
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc(events, channel, fn) {
+    return events.on(channel, async (raw) => {
+        const params = raw;
+        try {
+            const data = await fn(params);
+            const reply = { success: true };
+            if (data !== undefined)
+                reply.data = data;
+            events.emit(`${channel}:reply:${params.requestId}`, reply);
+        }
+        catch (err) {
+            events.emit(`${channel}:reply:${params.requestId}`, {
+                success: false, error: err?.message ?? String(err),
+            });
+        }
+    });
+}
+/**
+ * Register ping, spawn, stop, consume, and steer RPC handlers on the event bus.
+ * Returns unsub functions for cleanup.
+ */
+export function registerRpcHandlers(deps) {
+    const { events, pi, getCtx, manager } = deps;
+    const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+        return { version: PROTOCOL_VERSION };
+    });
+    const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", async ({ type, prompt, options }) => {
+        const ctx = getCtx();
+        if (!ctx)
+            throw new Error("No active session");
+        // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
+        // forward serializable values, so options.model can be a string like
+        // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
+        // — same pattern the scheduler path already uses — so the spawned
+        // agent's auth lookup doesn't crash with "No API key found for
+        // undefined".
+        let normalizedOptions = options ?? {};
+        // `!= null` on purpose: a JSON-forwarding caller can serialize an unset
+        // field as null, and the runner reads `options.model ?? default`, so null
+        // means "inherit" — not an override to resolve or scope-check.
+        const override = normalizedOptions.model;
+        if (override != null) {
+            const { modelRegistry, cwd } = ctx;
+            // Names the override the same way in both messages below; an object
+            // override would otherwise interpolate as "[object Object]".
+            const label = typeof override === "string" ? override : `${override.provider}/${override.id}`;
+            if (!modelRegistry) {
+                throw new Error(`Model override "${label}" provided but ctx.modelRegistry is unavailable`);
+            }
+            let model = override;
+            if (typeof override === "string") {
+                const resolved = resolveModel(override, modelRegistry);
+                if (typeof resolved === "string") {
+                    // resolveModel returns a human-readable error string when the
+                    // input doesn't match any available model. Surface it instead of
+                    // silently falling back so the caller sees the auth/typo issue.
+                    throw new Error(resolved);
+                }
+                model = resolved;
+                normalizedOptions = { ...normalizedOptions, model: resolved };
+            }
+            // A model on the RPC payload is an orchestrator-level choice, exactly
+            // like Agent({ model }) — so it gets the Agent tool's hard error, never
+            // the frontmatter warn (#240). The check reads the RESOLVED model:
+            // resolveModel is fuzzy, so a bare "sonnet" can land on a provider the
+            // caller never named. Frontmatter-pinned and parent-inherited models are
+            // resolved later, in agent-runner, and keep warn-and-proceed.
+            const verdict = checkModelScope({
+                model,
+                cwd: cwd ?? process.cwd(),
+                modelRegistry,
+                callerSupplied: true,
+                agentLabel: type,
+                modelInput: label,
+            });
+            if (verdict.kind === "error")
+                throw new Error(verdict.message);
+        }
+        const id = manager.spawn(pi, ctx, type, prompt, normalizedOptions);
+        // With isolation: "worktree" the agent starts asynchronously — wait for
+        // it, so a strict-isolation failure is still an error envelope rather
+        // than an id for an agent that never ran.
+        await manager.awaitStartup(id);
+        return { id };
+    });
+    // Only the session's own agents are this RPC's to stop or steer. A nested
+    // child or a workflow's agent is owned by something that is *waiting on it*,
+    // and aborting or redirecting it out from under that owner turns another
+    // extension's request into a failed step here. Defence in depth rather than
+    // a live hole: no RPC hands out agent ids, so a caller has no ordinary way to
+    // name one it does not own — but the guard is cheap and the id may leak some
+    // other way. Same refuse-what-we-should-not-touch stance as `consume` below.
+    const assertOwned = (agentId) => {
+        const record = manager.getRecord(agentId);
+        if (!record)
+            throw new Error("Agent not found");
+        if (!isTopLevelAgent(record))
+            throw new Error("Agent is owned by another agent or workflow");
+    };
+    const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
+        assertOwned(agentId);
+        // Not "not found" — the lookup above already proved it exists. `abort`
+        // returns false only for a record that is neither running nor queued,
+        // which is an agent that has already finished.
+        if (!manager.abort(agentId))
+            throw new Error("Agent is not running");
+    });
+    // A caller that has already shown the model an agent's result — pi-tasks'
+    // TaskOutput is the one in practice — says so here, so the completion
+    // notification for that same result is not delivered on top of it and does
+    // not cost the parent a turn. Deliberately outside the ping version
+    // handshake: an extension built against protocol v2 simply never calls it.
+    const unsubConsume = handleRpc(events, "subagents:rpc:consume", ({ agentId }) => {
+        if (!manager.consumeResult(agentId))
+            throw new Error("Agent not found or still running");
+    });
+    // An extension that spawned an agent over the bus and then learns something
+    // that agent needs — a second CI failure on the head it is already fixing, a
+    // review that landed mid-run — can hand it over instead of spawning a second
+    // agent for the same work or dropping the fact. Outside the ping version
+    // handshake, like consume: additive and best-effort.
+    const unsubSteer = handleRpc(events, "subagents:rpc:steer", ({ agentId, message }) => {
+        if (typeof message !== "string" || message.trim().length === 0)
+            throw new Error("Steer message must be a non-empty string");
+        assertOwned(agentId);
+        if (!manager.steer(agentId, message))
+            throw new Error("Agent is not running");
+    });
+    return { unsubPing, unsubSpawn, unsubStop, unsubConsume, unsubSteer };
+}

package/dist/custom-agents.d.ts

@@ -0,0 +1,77 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/, plus the shared .agents/agents/ workspace) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations, plus any installed pi package that declares them (see package-resources.ts).
+ */
+import type { AgentConfig } from "./types.js";
+/** Answers whether a `!` entry in some package manifest excludes this path. */
+type Excluder = (path: string) => boolean;
+/**
+ * Overrides for the package tier. The gate and project-trust state normally come
+ * from the session values in package-resources.ts, so these exist for tests and
+ * for a caller that has to pin a scan it already performed.
+ */
+export interface LoadCustomAgentsOptions {
+    /** Explicit package directories, bypassing discovery. */
+    packageDirs?: string[];
+    /** Explicit package files, bypassing discovery. */
+    packageFiles?: string[];
+    /** Explicit `!` exclusion predicate, bypassing discovery. */
+    packageExcluded?: Excluder;
+}
+/**
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project:   <cwd>/.pi/agents/*.md (authoritative — also where /agents writes)
+ *   2. Workspace: <cwd>/.agents/agents/*.md (shared cross-tool .agents workspace, read-only)
+ *   3. Global:    $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
+ *   4. Package:   paths declared by an installed pi package (read-only)
+ *
+ * Project-level agents override global ones with the same name. On a name clash
+ * between the two project locations, .pi/agents wins — .pi stays the project
+ * authority; .agents/agents is an additional read location.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ *
+ * Package agents load *first*, so everything the user or project wrote outranks
+ * them. That is what makes them safe to adopt: a package can offer a `reviewer`,
+ * and a `.pi/agents/reviewer.md` silently takes it back. It mirrors pi's own
+ * resource precedence, where package-provided skills rank below every user and
+ * project one, and Claude Code's, where a plugin agent is the lowest tier.
+ *
+ * An agent's type comes from its frontmatter `name:`, falling back to the
+ * filename — Claude Code's rule, where "the filename doesn't have to match".
+ * Because the type is now declared rather than derived from a unique path, two
+ * files can claim the same one; the later load wins, as it always has for a
+ * filename clash, and `warnSkippedOverride` reports the substitution.
+ */
+export declare function loadCustomAgents(cwd: string, strict?: boolean, opts?: LoadCustomAgentsOptions): Map<string, AgentConfig>;
+/**
+ * Read and parse one agent file, or warn and return undefined for the caller to
+ * skip. One bad file must not take the whole extension down with it — an
+ * unparseable `.md` used to abort activation, so pi exited before the TUI.
+ *
+ * The path is as much of the fix as the recovery: a bare YAML error ("line 2,
+ * column 14") is unactionable when agents come from three directories at once,
+ * and the only other symptom is `Unknown agent type`, which reads like a typo.
+ *
+ * Under `strict` the same failure rethrows, still naming the path, so callers
+ * that opted into failing closed stop rather than run a substituted agent.
+ */
+/**
+ * Parse an agent file's frontmatter, tolerating a leading UTF-8 BOM.
+ *
+ * Editors across the Windows/CJK world write UTF-8 with a BOM by default, and
+ * pi's parser did not look past one before 0.84.3: the fence never matched, so
+ * the frontmatter came back empty and the *whole file* — YAML and all — became
+ * the body. An agent authored that way silently lost every field. `tools: none`
+ * going missing is the sharp edge: the agent registers with the default
+ * toolset rather than none, which is a wider grant than its author wrote.
+ *
+ * Stripped here rather than detected per pi version, because this is the only
+ * place agent files are read and the BOM is a file-encoding artifact, not
+ * content — normalising it at the boundary keeps one behaviour across the whole
+ * supported peer range instead of forking on what happens to be installed.
+ */
+export declare function parseAgentFrontmatter<T extends Record<string, unknown>>(content: string): {
+    frontmatter: T;
+    body: string;
+};
+export {};