@tintinweb/pi-subagents 0.4.0 → 0.4.3

package/dist/default-agents.js

@@ -0,0 +1,126 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+export const DEFAULT_AGENTS = new Map([
+    [
+        "general-purpose",
+        {
+            name: "general-purpose",
+            displayName: "Agent",
+            description: "General-purpose agent for complex, multi-step tasks",
+            // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
+            extensions: true,
+            skills: true,
+            systemPrompt: "",
+            promptMode: "append",
+            inheritContext: false,
+            runInBackground: false,
+            isolated: false,
+            isDefault: true,
+        },
+    ],
+    [
+        "Explore",
+        {
+            name: "Explore",
+            displayName: "Explore",
+            description: "Fast codebase exploration agent (read-only)",
+            builtinToolNames: READ_ONLY_TOOLS,
+            extensions: true,
+            skills: true,
+            model: "anthropic/claude-haiku-4-5-20251001",
+            systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise`,
+            promptMode: "replace",
+            inheritContext: false,
+            runInBackground: false,
+            isolated: false,
+            isDefault: true,
+        },
+    ],
+    [
+        "Plan",
+        {
+            name: "Plan",
+            displayName: "Plan",
+            description: "Software architect for implementation planning (read-only)",
+            builtinToolNames: READ_ONLY_TOOLS,
+            extensions: true,
+            skills: true,
+            systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a software architect and planning specialist.
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+# Planning Process
+1. Understand requirements
+2. Explore thoroughly (read files, find patterns, understand architecture)
+3. Design solution based on your assigned perspective
+4. Detail the plan with step-by-step implementation strategy
+
+# Requirements
+- Consider trade-offs and architectural decisions
+- Identify dependencies and sequencing
+- Anticipate potential challenges
+- Follow existing patterns where appropriate
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+
+# Output Format
+- Use absolute file paths
+- Do not use emojis
+- End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- /absolute/path/to/file.ts - [Brief reason]`,
+            promptMode: "replace",
+            inheritContext: false,
+            runInBackground: false,
+            isolated: false,
+            isDefault: true,
+        },
+    ],
+]);

package/dist/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+import type { ExtensionAPI } from "@mariozechner/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,13 @@
+/**
+ * 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 "@mariozechner/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;