@diousk/pi-subagents-fast 0.20.0

package/dist/enabled-models.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Reads `enabledModels` from pi's settings (global `<agentDir>/settings.json`
+ * + project-local `<cwd>/.pi/settings.json`, project wins) and resolves
+ * entries to concrete `provider/modelId` keys for scope validation.
+ *
+ * **Project overrides global**, mirroring pi's own `SettingsManager`
+ * deep-merge behavior and matching the precedence we use for our own
+ * `subagents.json` settings (see `src/settings.ts:loadSettings`). If
+ * project file has `enabledModels` set, it wholly replaces global's
+ * (array fields are replaced, not concatenated).
+ *
+ * **Limited subset of upstream's resolveModelScope.** We support exact
+ * `provider/modelId` matching only. Upstream (pi-coding-agent's
+ * `core/model-resolver.ts`) additionally supports glob patterns
+ * (`*sonnet*`, `anthropic/*`), bare model IDs without provider, and
+ * thinking-level suffixes (`provider/*:high`). Those forms are silently
+ * ignored here.
+ *
+ * In practice, pi's `/scoped-models` picker writes exact `provider/modelId`
+ * entries, so the limitation is invisible for users who configure scope
+ * through pi's UI. Hand-edited settings using globs or bare IDs will
+ * produce an empty allowed set (scope check becomes a no-op).
+ *
+ * Example:
+ *   enabledModels = ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"]
+ *   → resolves to { "anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6" }
+ */
+/** Minimal registry shape — only the methods resolveEnabledModels actually calls. */
+export interface ModelRegistryRef {
+    getAll(): unknown[];
+    getAvailable?(): unknown[];
+}
+/**
+ * Read enabledModels from pi's settings — project-local overrides global.
+ * Mirrors pi's SettingsManager deep-merge for the `enabledModels` field
+ * (and matches our own loadSettings precedence in src/settings.ts).
+ * Returns undefined when neither file has the field.
+ */
+export declare function readEnabledModels(cwd: string): string[] | undefined;
+export declare function resolveEnabledModels(patterns: string[] | undefined, registry: ModelRegistryRef, cwd?: string): Set<string> | undefined;
+/**
+ * True when `model` is in the allowed set. Centralizes the key format
+ * (`provider/id` lowercase) so callers don't have to reproduce it —
+ * both set-building (resolveExact) and lookup go through `modelKey`.
+ */
+export declare function isModelInScope(model: {
+    provider: string;
+    id: string;
+}, allowed: Set<string>): boolean;

package/dist/enabled-models.js

@@ -0,0 +1,145 @@
+/**
+ * Reads `enabledModels` from pi's settings (global `<agentDir>/settings.json`
+ * + project-local `<cwd>/.pi/settings.json`, project wins) and resolves
+ * entries to concrete `provider/modelId` keys for scope validation.
+ *
+ * **Project overrides global**, mirroring pi's own `SettingsManager`
+ * deep-merge behavior and matching the precedence we use for our own
+ * `subagents.json` settings (see `src/settings.ts:loadSettings`). If
+ * project file has `enabledModels` set, it wholly replaces global's
+ * (array fields are replaced, not concatenated).
+ *
+ * **Limited subset of upstream's resolveModelScope.** We support exact
+ * `provider/modelId` matching only. Upstream (pi-coding-agent's
+ * `core/model-resolver.ts`) additionally supports glob patterns
+ * (`*sonnet*`, `anthropic/*`), bare model IDs without provider, and
+ * thinking-level suffixes (`provider/*:high`). Those forms are silently
+ * ignored here.
+ *
+ * In practice, pi's `/scoped-models` picker writes exact `provider/modelId`
+ * entries, so the limitation is invisible for users who configure scope
+ * through pi's UI. Hand-edited settings using globs or bare IDs will
+ * produce an empty allowed set (scope check becomes a no-op).
+ *
+ * Example:
+ *   enabledModels = ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"]
+ *   → resolves to { "anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6" }
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+/** Paths to pi's settings.json files: [project, global] (project takes precedence). */
+function settingsPaths(cwd) {
+    return [
+        join(cwd, ".pi", "settings.json"),
+        join(getAgentDir(), "settings.json"),
+    ];
+}
+/** Read `enabledModels` from a single settings.json file. Undefined when missing or absent. */
+function readField(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (Array.isArray(raw?.enabledModels))
+            return raw.enabledModels;
+    }
+    catch {
+        /* corrupt file — silent */
+    }
+    return undefined;
+}
+/**
+ * Read enabledModels from pi's settings — project-local overrides global.
+ * Mirrors pi's SettingsManager deep-merge for the `enabledModels` field
+ * (and matches our own loadSettings precedence in src/settings.ts).
+ * Returns undefined when neither file has the field.
+ */
+export function readEnabledModels(cwd) {
+    const [project, global] = settingsPaths(cwd);
+    return readField(project) ?? readField(global);
+}
+/**
+ * Resolve enabledModels patterns → Set<"provider/modelId"> (lowercase keys).
+ *
+ * Only exact `provider/modelId` patterns are matched (case-insensitive).
+ * Patterns without a slash, with glob characters, or with a `:thinking`
+ * suffix are silently dropped. See module-level docstring for rationale.
+ *
+ * Cache: keyed on JSON.stringify(patterns) + mtime/size of *both*
+ * project and global settings.json files. Re-resolves when either file
+ * changes or the patterns argument differs.
+ *
+ * Returns undefined when no patterns are provided or no patterns match
+ * (scope check becomes a no-op at the call site).
+ */
+// Module-level cache — invalidated when either settings.json changes or patterns differ.
+let cachedAllowed;
+let cachedHash = "";
+let cachedPatternsKey = "";
+/** mtime+size hash of one file, or "missing" if absent. */
+function hashOf(path) {
+    try {
+        const s = statSync(path);
+        return `${s.mtimeMs}-${s.size}`;
+    }
+    catch {
+        return "missing";
+    }
+}
+export function resolveEnabledModels(patterns, registry, cwd = process.cwd()) {
+    // Fast path: check cache (stat both project and global settings.json files)
+    const patternsKey = JSON.stringify(patterns);
+    const [project, global] = settingsPaths(cwd);
+    const fileHash = `${hashOf(project)};${hashOf(global)}`;
+    if (fileHash === cachedHash && patternsKey === cachedPatternsKey) {
+        return cachedAllowed;
+    }
+    // Cache miss — resolve
+    if (!patterns || patterns.length === 0) {
+        cachedHash = fileHash;
+        cachedPatternsKey = patternsKey;
+        cachedAllowed = undefined;
+        return undefined;
+    }
+    const available = (registry.getAvailable?.() ?? registry.getAll());
+    const allowed = new Set();
+    for (const pattern of patterns) {
+        const trimmed = pattern.trim();
+        if (!trimmed)
+            continue; // skip empty/whitespace
+        resolveExact(trimmed, available, allowed);
+    }
+    const result = allowed.size > 0 ? allowed : undefined;
+    cachedHash = fileHash;
+    cachedPatternsKey = patternsKey;
+    cachedAllowed = result;
+    return result;
+}
+/**
+ * True when `model` is in the allowed set. Centralizes the key format
+ * (`provider/id` lowercase) so callers don't have to reproduce it —
+ * both set-building (resolveExact) and lookup go through `modelKey`.
+ */
+export function isModelInScope(model, allowed) {
+    return allowed.has(modelKey(model));
+}
+/** Canonical lowercase `provider/id` key for the allowed set. */
+function modelKey(model) {
+    return `${model.provider}/${model.id}`.toLowerCase();
+}
+/**
+ * Resolve exact model pattern. Example: "google/gemma-4-31b-it".
+ */
+function resolveExact(pattern, available, allowed) {
+    // "provider/modelId" — exact (colon is part of id, not split)
+    const slashIdx = pattern.indexOf("/");
+    if (slashIdx === -1)
+        return; // bare modelId not supported
+    const provider = pattern.slice(0, slashIdx).toLowerCase();
+    const modelId = pattern.slice(slashIdx + 1).toLowerCase();
+    const exact = available.find(m => m.provider.toLowerCase() === provider && m.id.toLowerCase() === modelId);
+    if (exact) {
+        allowed.add(modelKey(exact));
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { EnvInfo } from "./types.js";
+export declare function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo>;

package/dist/env.js

@@ -0,0 +1,28 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+export async function detectEnv(pi, cwd) {
+    let isGitRepo = false;
+    let branch = "";
+    try {
+        const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
+        isGitRepo = result.code === 0 && result.stdout.trim() === "true";
+    }
+    catch {
+        // Not a git repo or git not installed
+    }
+    if (isGitRepo) {
+        try {
+            const result = await pi.exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
+            branch = result.code === 0 ? result.stdout.trim() : "unknown";
+        }
+        catch {
+            branch = "unknown";
+        }
+    }
+    return {
+        isGitRepo,
+        branch,
+        platform: process.platform,
+    };
+}

package/dist/group-join.d.ts

@@ -0,0 +1,32 @@
+/**
+ * group-join.ts — Manages grouped background agent completion notifications.
+ *
+ * Instead of each agent individually nudging the main agent on completion,
+ * agents in a group are held until all complete (or a timeout fires),
+ * then a single consolidated notification is sent.
+ */
+import type { AgentRecord } from "./types.js";
+export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
+export declare class GroupJoinManager {
+    private deliverCb;
+    private groupTimeout;
+    private groups;
+    private agentToGroup;
+    constructor(deliverCb: DeliveryCallback, groupTimeout?: number);
+    /** Register a group of agent IDs that should be joined. */
+    registerGroup(groupId: string, agentIds: string[]): void;
+    /**
+     * Called when an agent completes.
+     * Returns:
+     * - 'pass'      — agent is not grouped, caller should send individual nudge
+     * - 'held'      — result held, waiting for group completion
+     * - 'delivered'  — this completion triggered the group notification
+     */
+    onAgentComplete(record: AgentRecord): 'delivered' | 'held' | 'pass';
+    private onTimeout;
+    private deliver;
+    private cleanupGroup;
+    /** Check if an agent is in a group. */
+    isGrouped(agentId: string): boolean;
+    dispose(): void;
+}

package/dist/group-join.js

@@ -0,0 +1,116 @@
+/**
+ * group-join.ts — Manages grouped background agent completion notifications.
+ *
+ * Instead of each agent individually nudging the main agent on completion,
+ * agents in a group are held until all complete (or a timeout fires),
+ * then a single consolidated notification is sent.
+ */
+/** Default timeout: 30s after first completion in a group. */
+const DEFAULT_TIMEOUT = 30_000;
+/** Straggler re-batch timeout: 15s. */
+const STRAGGLER_TIMEOUT = 15_000;
+export class GroupJoinManager {
+    deliverCb;
+    groupTimeout;
+    groups = new Map();
+    agentToGroup = new Map();
+    constructor(deliverCb, groupTimeout = DEFAULT_TIMEOUT) {
+        this.deliverCb = deliverCb;
+        this.groupTimeout = groupTimeout;
+    }
+    /** Register a group of agent IDs that should be joined. */
+    registerGroup(groupId, agentIds) {
+        const group = {
+            groupId,
+            agentIds: new Set(agentIds),
+            completedRecords: new Map(),
+            delivered: false,
+            isStraggler: false,
+        };
+        this.groups.set(groupId, group);
+        for (const id of agentIds) {
+            this.agentToGroup.set(id, groupId);
+        }
+    }
+    /**
+     * Called when an agent completes.
+     * Returns:
+     * - 'pass'      — agent is not grouped, caller should send individual nudge
+     * - 'held'      — result held, waiting for group completion
+     * - 'delivered'  — this completion triggered the group notification
+     */
+    onAgentComplete(record) {
+        const groupId = this.agentToGroup.get(record.id);
+        if (!groupId)
+            return 'pass';
+        const group = this.groups.get(groupId);
+        if (!group || group.delivered)
+            return 'pass';
+        group.completedRecords.set(record.id, record);
+        // All done — deliver immediately
+        if (group.completedRecords.size >= group.agentIds.size) {
+            this.deliver(group, false);
+            return 'delivered';
+        }
+        // First completion in this batch — start timeout
+        if (!group.timeoutHandle) {
+            const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
+            group.timeoutHandle = setTimeout(() => {
+                this.onTimeout(group);
+            }, timeout);
+        }
+        return 'held';
+    }
+    onTimeout(group) {
+        if (group.delivered)
+            return;
+        group.timeoutHandle = undefined;
+        // Partial delivery — some agents still running
+        const remaining = new Set();
+        for (const id of group.agentIds) {
+            if (!group.completedRecords.has(id))
+                remaining.add(id);
+        }
+        // Clean up agentToGroup for delivered agents (they won't complete again)
+        for (const id of group.completedRecords.keys()) {
+            this.agentToGroup.delete(id);
+        }
+        // Deliver what we have
+        this.deliverCb([...group.completedRecords.values()], true);
+        // Set up straggler group for remaining agents
+        group.completedRecords.clear();
+        group.agentIds = remaining;
+        group.isStraggler = true;
+        // Timeout will be started when the next straggler completes
+    }
+    deliver(group, partial) {
+        if (group.timeoutHandle) {
+            clearTimeout(group.timeoutHandle);
+            group.timeoutHandle = undefined;
+        }
+        group.delivered = true;
+        this.deliverCb([...group.completedRecords.values()], partial);
+        this.cleanupGroup(group.groupId);
+    }
+    cleanupGroup(groupId) {
+        const group = this.groups.get(groupId);
+        if (!group)
+            return;
+        for (const id of group.agentIds) {
+            this.agentToGroup.delete(id);
+        }
+        this.groups.delete(groupId);
+    }
+    /** Check if an agent is in a group. */
+    isGrouped(agentId) {
+        return this.agentToGroup.has(agentId);
+    }
+    dispose() {
+        for (const group of this.groups.values()) {
+            if (group.timeoutHandle)
+                clearTimeout(group.timeoutHandle);
+        }
+        this.groups.clear();
+        this.agentToGroup.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
+ *
+ * Tools:
+ *   Agent             — LLM-callable: spawn a sub-agent
+ *   get_subagent_result  — LLM-callable: check background agent status/result
+ *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *
+ * Commands:
+ *   /agents                 — Interactive agent management menu
+ */
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container } from "@earendil-works/pi-tui";
+import { type AgentConfig } from "./types.js";
+import { type Theme } from "./ui/agent-widget.js";
+import { FOREIGN_WORKFLOW_TOOL_NAMES } from "./workflow/collisions.js";
+import { WORKFLOW_ENTRY_TYPE, type WorkflowEntryData, workflowEntryData } from "./workflow/entry.js";
+export declare function renderRunningAgentStatus(frame: string, statsText: string, activity: string, theme: Pick<Theme, "fg">): Container;
+/**
+ * Format an agent's tool scope for the Agent tool description.
+ *
+ * This suffix describes BUILT-IN scope only — extension tools are resolved when
+ * the agent runs (extensions can register asynchronously), so they cannot be
+ * enumerated while the description is being built. That is why an agent with
+ * `tools: "*, ext:mcp/search"` renders "*" and always has.
+ *
+ * Two distinctions matter, both of them capability claims the orchestrator acts on:
+ *
+ * - absent vs empty. `builtinToolNames: undefined` means the agent never narrowed
+ *   its tools (the shipped defaults); `[]` is what `tools: none` and an `ext:`-only
+ *   `tools:` parse to, and the runtime really does hand those agents no built-ins.
+ *   Rendering both "*" tells the orchestrator a tool-less agent can run `bash`.
+ * - empty-with-extensions vs empty-without. Zero built-ins does NOT imply zero
+ *   tools: `tools: none` alongside `extensions:` still surfaces every extension
+ *   tool (see test/fixtures/.pi/agents/tools-none.md, which expects three). Calling
+ *   that "none" understates the agent instead of overstating it — better, but still
+ *   wrong, and it would route work away from the only agent able to do it. "none"
+ *   is therefore reserved for agents that genuinely can call nothing: `isolated`
+ *   agents and those with `extensions: false`.
+ */
+export declare function formatToolsSuffix(cfg: AgentConfig | undefined): string;
+/** CLI flag that runs a workflow script at session start. */
+export declare const WORKFLOW_FILE_FLAG = "subagents-workflow-file";
+/**
+ * Re-exported from where they now live, because this is where they were
+ * defined and a consumer (or a test) that matched a session entry on
+ * {@link WORKFLOW_ENTRY_TYPE} imports it from here.
+ */
+export { FOREIGN_WORKFLOW_TOOL_NAMES, WORKFLOW_ENTRY_TYPE, type WorkflowEntryData, workflowEntryData };
+export default function (pi: ExtensionAPI): void;