@diousk/pi-subagents-fast 0.20.0

package/dist/mention.d.ts

@@ -0,0 +1,81 @@
+/**
+ * mention.ts — the `@handle` grammar for messaging a subagent from the prompt.
+ *
+ * Claude Code lets you type `@code-review take another look` at the prompt and
+ * routes the message to that agent instead of the main model. Its grammar is
+ * reproduced here so the two behave identically:
+ *
+ *   - suggestions fire on `@` at the start of the input or after whitespace,
+ *     followed by `[\w-]*` (so `@src/foo.ts` is a file, never an agent);
+ *   - a send is recognized only at the START of the input, and only with a
+ *     non-empty message after the handle. That is why a bare `@code-review`
+ *     goes to the main model rather than anywhere near the agent.
+ *
+ * A record's own identity is a UUID plus a deliberately non-unique description,
+ * neither of which is typeable, so the handle is derived from the agent type.
+ * Colliding handles are numbered (`explore`, `explore-2`), which is also what
+ * Claude Code's `allocateName` does — it recycles a name only once the task
+ * behind it is gone. Its SendMessage prompt describes the *registry* as
+ * latest-wins, which is a different thing and not how names are allocated.
+ */
+/**
+ * Suggestion trigger: `@` at a token boundary plus the partial handle typed so
+ * far. Ported from Claude Code, including the CJK sentence-ending punctuation
+ * it accepts as a boundary.
+ */
+export declare const MENTION_TRIGGER: RegExp;
+/** Whether `@handle` names the main conversation rather than any subagent. */
+export declare function isReservedHandle(handle: string): boolean;
+/** Slug of an agent type or name, restricted to the `[\w-]` the grammar allows. */
+export declare function handleBase(type: string): string;
+/**
+ * `base`, else `base-2`, `base-3`, … — the first form that is neither `taken`
+ * nor reserved. Callers pass one shared `taken` set covering type-derived
+ * handles and model-supplied aliases alike, so the two can never collide.
+ */
+export declare function assignHandle(base: string, taken: ReadonlySet<string>): string;
+/**
+ * Map a typed handle back to a registered agent type, so `@explore fix it`
+ * reaches the Explore agent even when no instance has ever run. `handleBase` is
+ * the single source of truth in both directions, so a type is addressable by
+ * exactly the handle its instances would be given.
+ */
+export declare function resolveHandleToType(handle: string, types: readonly string[]): string | undefined;
+/**
+ * Claude Code documents `@agent-<name>` as the form you type by hand when the
+ * picker isn't involved. Accepted here as an exact synonym: the caller tries the
+ * handle as written first, so an agent genuinely called `agent-foo` still wins
+ * over `@agent-` + `foo`, and only falls back to this when that finds nothing.
+ * Returns undefined when the prefix is absent or is the whole handle.
+ */
+export declare function stripAgentPrefix(handle: string): string | undefined;
+/**
+ * A spawn needs the short description every agent surface renders. A mention
+ * carries no separate label, so the message itself becomes one: first line,
+ * whitespace collapsed, clipped to roughly the 3-5 words the Agent tool asks of
+ * the model.
+ */
+export declare function describeMention(message: string): string;
+/**
+ * What Claude Code sends the main model when a mention names an agent it could
+ * start. Its `@agent-<type>` mention is not a spawn at all: it becomes an
+ * `agent_mention` attachment, which renders to a synthetic `isMeta` user
+ * message placed after the user's own untouched text — no tool forcing, no
+ * allowed-tools narrowing, and the Task tool is not even named. The model reads
+ * this and calls the tool itself.
+ *
+ * Ported verbatim from the 2.1.233 bundle's attachment renderer, trailing space
+ * before the closing newline included, so the wording the model was trained
+ * against is the wording it gets. The one substitution is ours: pi's equivalent
+ * of Task is the `Agent` tool, and the agent listing that teaches valid
+ * `subagent_type` values is the tool spec rather than a separate attachment.
+ */
+export declare function agentMentionReminder(type: string): string;
+/**
+ * Split `@handle message` into its parts, or null when the text isn't a send —
+ * a bare handle, a leading file path, or a mention that isn't at the start.
+ */
+export declare function parseMention(text: string): {
+    handle: string;
+    message: string;
+} | null;

package/dist/mention.js

@@ -0,0 +1,131 @@
+/**
+ * mention.ts — the `@handle` grammar for messaging a subagent from the prompt.
+ *
+ * Claude Code lets you type `@code-review take another look` at the prompt and
+ * routes the message to that agent instead of the main model. Its grammar is
+ * reproduced here so the two behave identically:
+ *
+ *   - suggestions fire on `@` at the start of the input or after whitespace,
+ *     followed by `[\w-]*` (so `@src/foo.ts` is a file, never an agent);
+ *   - a send is recognized only at the START of the input, and only with a
+ *     non-empty message after the handle. That is why a bare `@code-review`
+ *     goes to the main model rather than anywhere near the agent.
+ *
+ * A record's own identity is a UUID plus a deliberately non-unique description,
+ * neither of which is typeable, so the handle is derived from the agent type.
+ * Colliding handles are numbered (`explore`, `explore-2`), which is also what
+ * Claude Code's `allocateName` does — it recycles a name only once the task
+ * behind it is gone. Its SendMessage prompt describes the *registry* as
+ * latest-wins, which is a different thing and not how names are allocated.
+ */
+/**
+ * Suggestion trigger: `@` at a token boundary plus the partial handle typed so
+ * far. Ported from Claude Code, including the CJK sentence-ending punctuation
+ * it accepts as a boundary.
+ */
+export const MENTION_TRIGGER = /(^|[\s。、？！])@([\w-]*)$/;
+/** Send grammar: leading `@handle`, then a non-empty message. */
+const MENTION_SEND = /^@([\w-]+)\s+([\s\S]+)$/;
+/**
+ * Upper bound on a handle, matching Claude Code's `dSS`. Nothing here generates
+ * a name this long, but an agent type or a model-supplied name can be arbitrary
+ * text, and an unbounded handle would wrap the suggestion popup.
+ */
+const MAX_HANDLE_LENGTH = 64;
+/**
+ * Handles that address something other than a subagent, and so can never be
+ * allocated to one. Claude Code reserves exactly this name (`Vq = "main"`),
+ * refusing it at spawn and routing it to the main conversation instead.
+ */
+const RESERVED_HANDLES = new Set(["main"]);
+/** Whether `@handle` names the main conversation rather than any subagent. */
+export function isReservedHandle(handle) {
+    return RESERVED_HANDLES.has(handle.toLowerCase());
+}
+/** Slug of an agent type or name, restricted to the `[\w-]` the grammar allows. */
+export function handleBase(type) {
+    const slug = type.toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_HANDLE_LENGTH)
+        // The slice can land mid-run and leave the trailing hyphen back.
+        .replace(/-+$/, "");
+    return slug || "agent";
+}
+/**
+ * `base`, else `base-2`, `base-3`, … — the first form that is neither `taken`
+ * nor reserved. Callers pass one shared `taken` set covering type-derived
+ * handles and model-supplied aliases alike, so the two can never collide.
+ */
+export function assignHandle(base, taken) {
+    let candidate = base;
+    let n = 1;
+    while (taken.has(candidate) || RESERVED_HANDLES.has(candidate)) {
+        n++;
+        candidate = `${base}-${n}`;
+    }
+    return candidate;
+}
+/**
+ * Map a typed handle back to a registered agent type, so `@explore fix it`
+ * reaches the Explore agent even when no instance has ever run. `handleBase` is
+ * the single source of truth in both directions, so a type is addressable by
+ * exactly the handle its instances would be given.
+ */
+export function resolveHandleToType(handle, types) {
+    const wanted = handle.toLowerCase();
+    // A type slugging to a reserved name is unaddressable rather than shadowing
+    // it — `assignHandle` refuses that name too, so its instances never hold one.
+    if (RESERVED_HANDLES.has(wanted))
+        return undefined;
+    return types.find(type => handleBase(type) === wanted);
+}
+/**
+ * Claude Code documents `@agent-<name>` as the form you type by hand when the
+ * picker isn't involved. Accepted here as an exact synonym: the caller tries the
+ * handle as written first, so an agent genuinely called `agent-foo` still wins
+ * over `@agent-` + `foo`, and only falls back to this when that finds nothing.
+ * Returns undefined when the prefix is absent or is the whole handle.
+ */
+export function stripAgentPrefix(handle) {
+    const rest = /^agent-(.+)$/i.exec(handle)?.[1];
+    return rest || undefined;
+}
+/**
+ * A spawn needs the short description every agent surface renders. A mention
+ * carries no separate label, so the message itself becomes one: first line,
+ * whitespace collapsed, clipped to roughly the 3-5 words the Agent tool asks of
+ * the model.
+ */
+export function describeMention(message) {
+    const oneLine = message.split("\n", 1)[0].replace(/\s+/g, " ").trim();
+    return oneLine.length > 40 ? `${oneLine.slice(0, 39).trimEnd()}…` : oneLine;
+}
+/**
+ * What Claude Code sends the main model when a mention names an agent it could
+ * start. Its `@agent-<type>` mention is not a spawn at all: it becomes an
+ * `agent_mention` attachment, which renders to a synthetic `isMeta` user
+ * message placed after the user's own untouched text — no tool forcing, no
+ * allowed-tools narrowing, and the Task tool is not even named. The model reads
+ * this and calls the tool itself.
+ *
+ * Ported verbatim from the 2.1.233 bundle's attachment renderer, trailing space
+ * before the closing newline included, so the wording the model was trained
+ * against is the wording it gets. The one substitution is ours: pi's equivalent
+ * of Task is the `Agent` tool, and the agent listing that teaches valid
+ * `subagent_type` values is the tool spec rather than a separate attachment.
+ */
+export function agentMentionReminder(type) {
+    return `<system-reminder>\nThe user has expressed a desire to invoke the agent "${type}". Please invoke the agent appropriately, passing in the required context to it. \n</system-reminder>`;
+}
+/**
+ * Split `@handle message` into its parts, or null when the text isn't a send —
+ * a bare handle, a leading file path, or a mention that isn't at the start.
+ */
+export function parseMention(text) {
+    const match = MENTION_SEND.exec(text);
+    if (!match)
+        return null;
+    const message = match[2].trim();
+    return message ? { handle: match[1], message } : null;
+}

package/dist/model-resolver.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+export interface ModelEntry {
+    id: string;
+    name: string;
+    provider: string;
+}
+export interface ModelRegistry {
+    find(provider: string, modelId: string): any;
+    getAll(): any[];
+    getAvailable?(): any[];
+}
+/**
+ * Both display forms of a model. The short one goes on tight rows (the widget,
+ * the Agent tool result), the canonical one where there is room to disambiguate
+ * two providers serving a similarly-named model (the conversation viewer).
+ *
+ * One function, because `index.ts` labels the model it resolved before the run
+ * and `agent-manager.ts` relabels it from the live session afterwards — the two
+ * must agree or the label would visibly change the moment the session starts.
+ */
+export declare function describeModel(model: {
+    provider: string;
+    id: string;
+    name?: string;
+}): {
+    modelName: string;
+    modelId: string;
+};
+/**
+ * Resolve a model string to a Model instance.
+ * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.
+ * Returns the Model on success, or an error message string on failure.
+ */
+export declare function resolveModel(input: string, registry: ModelRegistry): any | string;

package/dist/model-resolver.js

@@ -0,0 +1,95 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+/**
+ * Both display forms of a model. The short one goes on tight rows (the widget,
+ * the Agent tool result), the canonical one where there is room to disambiguate
+ * two providers serving a similarly-named model (the conversation viewer).
+ *
+ * One function, because `index.ts` labels the model it resolved before the run
+ * and `agent-manager.ts` relabels it from the live session afterwards — the two
+ * must agree or the label would visibly change the moment the session starts.
+ */
+export function describeModel(model) {
+    return {
+        modelName: (model.name ?? model.id).replace(/^Claude\s+/i, "").toLowerCase(),
+        modelId: `${model.provider}/${model.id}`,
+    };
+}
+/**
+ * Resolve a model string to a Model instance.
+ * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.
+ * Returns the Model on success, or an error message string on failure.
+ */
+export function resolveModel(input, registry) {
+    // Available models (those with auth configured)
+    const all = (registry.getAvailable?.() ?? registry.getAll());
+    const availableSet = new Set(all.map(m => `${m.provider}/${m.id}`.toLowerCase()));
+    // 1. Exact match: "provider/modelId" — only if available (has auth)
+    const slashIdx = input.indexOf("/");
+    if (slashIdx !== -1) {
+        const provider = input.slice(0, slashIdx);
+        const modelId = input.slice(slashIdx + 1);
+        if (availableSet.has(input.toLowerCase())) {
+            const found = registry.find(provider, modelId);
+            if (found)
+                return found;
+        }
+    }
+    // 2. Fuzzy match against available models. Normalize separators so cosmetic
+    // punctuation differences still match — e.g. "claude-haiku-4.5" and
+    // "claude-haiku-4-5" (dot vs dash in the version) resolve to the same model.
+    const normalize = (s) => s.toLowerCase().replace(/\./g, "-");
+    const query = normalize(input);
+    // Score each model: prefer exact id match > id contains > name contains > provider+id contains
+    let bestMatch;
+    let bestScore = 0;
+    for (const m of all) {
+        const id = normalize(m.id);
+        const name = normalize(m.name);
+        const full = normalize(`${m.provider}/${m.id}`);
+        let score = 0;
+        if (id === query || full === query) {
+            score = 100; // exact
+        }
+        else if (id.includes(query) || full.includes(query)) {
+            score = 60 + (query.length / id.length) * 30; // substring, prefer tighter matches
+        }
+        else if (name.includes(query)) {
+            score = 40 + (query.length / name.length) * 20;
+        }
+        else if (
+        // A trailing date-stamp token (e.g. "20251001") is optional, so a
+        // date-pinned config like "claude-haiku-4-5-20251001" still matches an
+        // undated registry id like "claude-haiku-4-5".
+        query
+            .split(/[\s\-/]+/)
+            .every(part => /^\d{8}$/.test(part) || id.includes(part) || name.includes(part) || m.provider.toLowerCase().includes(part))) {
+            score = 20; // all parts present somewhere
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestMatch = m;
+        }
+    }
+    if (bestMatch && bestScore >= 20) {
+        const found = registry.find(bestMatch.provider, bestMatch.id);
+        if (found)
+            return found;
+    }
+    // 3. Provider fallback: a "provider/modelId" query that didn't match under the
+    // named provider (exact or fuzzy above) retries against all providers. The
+    // named provider is preferred when present; this only kicks in when it isn't,
+    // so the same model from another provider beats falling back to "inherit".
+    if (slashIdx !== -1) {
+        const bare = resolveModel(input.slice(slashIdx + 1), registry);
+        if (typeof bare !== "string")
+            return bare;
+    }
+    // 4. No match — list available models
+    const modelList = all
+        .map(m => `  ${m.provider}/${m.id}`)
+        .sort()
+        .join("\n");
+    return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}

package/dist/model-scope.d.ts

@@ -0,0 +1,49 @@
+/**
+ * model-scope.ts — `scopeModels` policy, shared by the top-level Agent tool and
+ * the nested delegation tools so a nested spawn can't escape the allowlist the
+ * top-level path enforces.
+ *
+ * State lives here (rather than in an index.ts closure) for the same reason
+ * `disableDefaults` lives in agent-types.ts: both entry points need it.
+ */
+import { type ModelRegistryRef } from "./enabled-models.js";
+export declare function isScopeModelsEnabled(): boolean;
+export declare function setScopeModelsEnabled(enabled: boolean): void;
+export type ModelScopeVerdict = 
+/** In scope, or nothing to validate against (feature off / no allowlist). */
+{
+    kind: "ok";
+}
+/** Caller-supplied out-of-scope choice — refuse the spawn with this message. */
+ | {
+    kind: "error";
+    message: string;
+}
+/** Frontmatter-pinned or parent-inherited — proceed, but tell the user. */
+ | {
+    kind: "warn";
+    message: string;
+};
+/**
+ * Check the effective resolved model against the user's enabledModels list.
+ *
+ * scopeModels guards against *runtime* LLM choices, not user-level config:
+ *   - Caller-supplied out-of-scope → hard error (the orchestrator made an explicit
+ *     out-of-scope choice; surface it so it picks differently).
+ *   - Frontmatter-pinned or parent-inherited out-of-scope → warn but proceed (the
+ *     user authored/installed this agent or chose the parent's model; trust it).
+ */
+export declare function checkModelScope(args: {
+    model: {
+        provider: string;
+        id: string;
+    } | undefined;
+    cwd: string;
+    modelRegistry: ModelRegistryRef;
+    /** True when the model came from the tool call rather than frontmatter. */
+    callerSupplied: boolean;
+    /** Display name used in the warning toast. */
+    agentLabel: string;
+    /** The raw `model:` input, when there was one. */
+    modelInput?: string;
+}): ModelScopeVerdict;

package/dist/model-scope.js

@@ -0,0 +1,48 @@
+/**
+ * model-scope.ts — `scopeModels` policy, shared by the top-level Agent tool and
+ * the nested delegation tools so a nested spawn can't escape the allowlist the
+ * top-level path enforces.
+ *
+ * State lives here (rather than in an index.ts closure) for the same reason
+ * `disableDefaults` lives in agent-types.ts: both entry points need it.
+ */
+import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
+/**
+ * When enabled, subagent model choices are validated against `enabledModels`
+ * from pi's settings — both global `<agentDir>/settings.json` and project-local
+ * `<cwd>/.pi/settings.json` (project overrides global). Off by default; opt-in
+ * via `/agents → Settings`. See the SubagentsSettings.scopeModels docstring for
+ * the hard-error vs warn-and-proceed policy and its rationale.
+ */
+let scopeModelsEnabled = false;
+export function isScopeModelsEnabled() { return scopeModelsEnabled; }
+export function setScopeModelsEnabled(enabled) { scopeModelsEnabled = enabled; }
+/**
+ * Check the effective resolved model against the user's enabledModels list.
+ *
+ * scopeModels guards against *runtime* LLM choices, not user-level config:
+ *   - Caller-supplied out-of-scope → hard error (the orchestrator made an explicit
+ *     out-of-scope choice; surface it so it picks differently).
+ *   - Frontmatter-pinned or parent-inherited out-of-scope → warn but proceed (the
+ *     user authored/installed this agent or chose the parent's model; trust it).
+ */
+export function checkModelScope(args) {
+    const { model, cwd, modelRegistry, callerSupplied, agentLabel, modelInput } = args;
+    if (!scopeModelsEnabled || !model)
+        return { kind: "ok" };
+    const allowed = resolveEnabledModels(readEnabledModels(cwd), modelRegistry, cwd);
+    if (!allowed || isModelInScope(model, allowed))
+        return { kind: "ok" };
+    if (callerSupplied) {
+        const list = [...allowed].sort().map(m => `  ${m}`).join("\n");
+        return {
+            kind: "error",
+            message: `Model not in scope: "${modelInput}".\n\nAllowed models (from enabledModels):\n${list}`,
+        };
+    }
+    const modelLabel = modelInput ?? `${model.provider}/${model.id}`;
+    return {
+        kind: "warn",
+        message: `Agent "${agentLabel}" using out-of-scope model "${modelLabel}"`,
+    };
+}

package/dist/nested-tools.d.ts

@@ -0,0 +1,55 @@
+import type { Model } from "@earendil-works/pi-ai";
+import { type AgentSession, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "./types.js";
+export declare function getMaxSubagentDepth(): number;
+export declare function setMaxSubagentDepth(n: number): void;
+interface NestedSpawnOptions {
+    description: string;
+    model?: Model<any>;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    isBackground?: boolean;
+    isolation?: IsolationMode;
+    invocation?: AgentInvocation;
+    signal?: AbortSignal;
+    onAssistantUsage?: (usage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    }) => void;
+    onSessionCreated?: (session: AgentSession) => void;
+    depth: number;
+    parentAgentId: string;
+    maxSubagentDepth: number;
+    configCwd?: string;
+    rootSessionId?: string;
+}
+export interface NestedAgentManager {
+    spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: string, prompt: string, options: NestedSpawnOptions): string;
+    /** Resolves once the spawned agent is running; rejects on a startup failure. */
+    awaitStartup(id: string): Promise<void>;
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: string, prompt: string, options: Omit<NestedSpawnOptions, "isBackground">, 
+    /** Fires synchronously after spawn, before the session exists — where the transcript is attached. */
+    onSpawned?: (id: string) => void): Promise<{
+        id: string;
+        record: AgentRecord;
+    }>;
+    getRecord(id: string): AgentRecord | undefined;
+    resume(id: string, prompt: string, signal?: AbortSignal): Promise<AgentRecord | undefined>;
+}
+export interface NestedToolContext {
+    manager: NestedAgentManager;
+    pi: ExtensionAPI;
+    parentAgentId: string;
+    depth: number;
+    maxSubagentDepth: number;
+    /** "all" = any enabled agent; string[] = only those types. Never empty. */
+    allowedSubagents: "all" | string[];
+    /** Root used for agent/config discovery; may differ from the agent's working directory. */
+    configCwd: string;
+}
+/** Build child-safe orchestration tools scoped to one parent agent instance. */
+export declare function createNestedSubagentTools(context: NestedToolContext): ToolDefinition[];
+export {};