@pi-unipi/subagents 0.1.0

package/src/index.ts

@@ -0,0 +1,323 @@
+/**
+ * @pi-unipi/subagents — Extension entry
+ *
+ * Tools: Agent, get_result
+ * ESC propagation: all children abort on parent ESC
+ */
+
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { AgentManager } from "./agent-manager.js";
+import { initConfig, saveGlobalConfig } from "./config.js";
+import { type AgentActivity, type AgentRecord, BUILTIN_TYPES } from "./types.js";
+import { AgentWidget } from "./widget.js";
+
+/** Format tokens safely. */
+function safeFormatTokens(session: any): string {
+  if (!session) return "";
+  try {
+    const stats = session.getSessionStats();
+    const total = stats.tokens?.total ?? 0;
+    if (total >= 1_000_000) return `${(total / 1_000_000).toFixed(1)}M`;
+    if (total >= 1_000) return `${(total / 1_000).toFixed(1)}k`;
+    return `${total}`;
+  } catch {
+    return "";
+  }
+}
+
+/** Build result text. */
+function textResult(msg: string, details?: any) {
+  return { content: [{ type: "text" as const, text: msg }], details };
+}
+
+export default function (pi: ExtensionAPI) {
+  // Initialize config
+  const config = initConfig(process.cwd());
+  if (!config.enabled) return;
+
+  // Activity tracking for widget
+  const agentActivity = new Map<string, AgentActivity>();
+
+  // Create manager with completion callback
+  const manager = new AgentManager(
+    (record) => {
+      // On complete: clean up activity, emit event
+      agentActivity.delete(record.id);
+      widget.markFinished(record.id);
+      widget.update();
+
+      pi.events.emit("subagents:completed", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        status: record.status,
+        result: record.result,
+        error: record.error,
+      });
+    },
+    config.maxConcurrent,
+    (record) => {
+      // On start: emit event
+      pi.events.emit("subagents:started", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+      });
+    },
+  );
+
+  // Create widget
+  const widget = new AgentWidget(manager, agentActivity);
+
+  // ESC propagation: abort all agents on session shutdown
+  pi.on("session_shutdown", async () => {
+    manager.abortAll();
+    manager.dispose();
+  });
+
+  // Wire UI context for widget
+  pi.on("tool_execution_start", async (_event, ctx) => {
+    widget.setUICtx(ctx.ui);
+    widget.update();
+  });
+
+  // Create activity tracker
+  function createActivityTracker(maxTurns?: number) {
+    const state: AgentActivity = {
+      activeTools: new Map(),
+      toolUses: 0,
+      turnCount: 1,
+      maxTurns,
+      tokens: "",
+      responseText: "",
+    };
+
+    const callbacks = {
+      onToolActivity: (activity: { type: "start" | "end"; toolName: string }) => {
+        if (activity.type === "start") {
+          state.activeTools.set(activity.toolName + "_" + Date.now(), activity.toolName);
+        } else {
+          for (const [key, name] of state.activeTools) {
+            if (name === activity.toolName) {
+              state.activeTools.delete(key);
+              break;
+            }
+          }
+          state.toolUses++;
+        }
+        widget.update();
+      },
+      onTextDelta: (_delta: string, fullText: string) => {
+        state.responseText = fullText;
+        widget.update();
+      },
+      onTurnEnd: (turnCount: number) => {
+        state.turnCount = turnCount;
+        widget.update();
+      },
+      onSessionCreated: (session: any) => {
+        state.session = session;
+        state.tokens = safeFormatTokens(session);
+        widget.update();
+      },
+    };
+
+    return { state, callbacks };
+  }
+
+  // ---- Agent tool ----
+
+  const builtinTypes = BUILTIN_TYPES.join(", ");
+
+  pi.registerTool(
+    defineTool({
+      name: "Agent",
+      label: "Agent",
+      description: `Launch a sub-agent for parallel work.
+
+Available agent types: ${builtinTypes}
+Custom types can be defined in .unipi/config/agents/<name>.md
+
+Guidelines:
+- Use "explore" for parallel file reads
+- Use "work" for parallel file writes (transparent locking)
+- Use run_in_background for work you don't need immediately
+- ESC kills all running agents immediately
+- Agents inherit the parent model by default`,
+      parameters: Type.Object({
+        type: Type.String({
+          description: `Agent type: ${builtinTypes}, or custom type from .unipc/config/agents/*.md`,
+        }),
+        prompt: Type.String({
+          description: "The task for the agent to perform.",
+        }),
+        description: Type.String({
+          description: "A short (3-5 word) description of the task.",
+        }),
+        run_in_background: Type.Optional(
+          Type.Boolean({
+            description: "Run in background. Returns agent ID immediately.",
+          }),
+        ),
+        max_turns: Type.Optional(
+          Type.Number({
+            description: "Max agentic turns before stopping.",
+            minimum: 1,
+          }),
+        ),
+      }),
+
+      execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+        widget.setUICtx(ctx.ui);
+
+        const type = params.type as string;
+        const prompt = params.prompt as string;
+        const description = params.description as string;
+        const runInBackground = params.run_in_background as boolean | undefined;
+        const maxTurns = params.max_turns as number | undefined;
+
+        // Create activity tracker
+        const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(maxTurns);
+
+        if (runInBackground) {
+          // Background execution
+          const id = manager.spawn(pi, ctx, type, prompt, {
+            description,
+            maxTurns,
+            isBackground: true,
+            ...bgCallbacks,
+          });
+
+          agentActivity.set(id, bgState);
+          widget.ensureTimer();
+          widget.update();
+
+          const record = manager.getRecord(id);
+          const isQueued = record?.status === "queued";
+
+          return textResult(
+            `Agent ${isQueued ? "queued" : "started"} in background.\n` +
+              `ID: ${id}\n` +
+              `Type: ${type}\n` +
+              `Description: ${description}\n` +
+              (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
+              `\nYou will be notified when this agent completes.\n` +
+              `Use get_result to retrieve full results.`,
+            { status: "background", agentId: id },
+          );
+        }
+
+        // Foreground execution
+        let spinnerFrame = 0;
+        const startedAt = Date.now();
+        let fgId: string | undefined;
+
+        const streamUpdate = () => {
+          onUpdate?.({
+            content: [{ type: "text", text: `${bgState.toolUses} tool uses...` }],
+            details: {
+              status: "running",
+              toolUses: bgState.toolUses,
+              tokens: bgState.tokens,
+              turnCount: bgState.turnCount,
+              maxTurns: bgState.maxTurns,
+              durationMs: Date.now() - startedAt,
+              activity: bgState.responseText
+                ? bgState.responseText.split("\n").pop()?.trim().slice(0, 60)
+                : "thinking…",
+              spinnerFrame: spinnerFrame % 10,
+            },
+          });
+        };
+
+        const spinnerInterval = setInterval(() => {
+          spinnerFrame++;
+          streamUpdate();
+        }, 80);
+
+        streamUpdate();
+
+        const record = await manager.spawnAndWait(pi, ctx, type, prompt, {
+          description,
+          maxTurns,
+          ...bgCallbacks,
+        });
+
+        clearInterval(spinnerInterval);
+
+        if (fgId) {
+          agentActivity.delete(fgId);
+          widget.markFinished(fgId);
+        }
+
+        const tokenText = safeFormatTokens(bgState.session);
+        const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+
+        if (record.status === "error") {
+          return textResult(`Agent failed: ${record.error}`);
+        }
+
+        return textResult(
+          `Agent completed in ${(durationMs / 1000).toFixed(1)}s (${record.toolUses} tool uses${tokenText ? `, ${tokenText} tokens` : ""}).\n\n` +
+            (record.result?.trim() || "No output."),
+        );
+      },
+    }),
+  );
+
+  // ---- get_result tool ----
+
+  pi.registerTool(
+    defineTool({
+      name: "get_result",
+      label: "Get Agent Result",
+      description: "Check status and retrieve results from a background agent.",
+      parameters: Type.Object({
+        agent_id: Type.String({
+          description: "The agent ID to check.",
+        }),
+        wait: Type.Optional(
+          Type.Boolean({
+            description: "Wait for completion. Default: false.",
+          }),
+        ),
+      }),
+      execute: async (_toolCallId, params) => {
+        const record = manager.getRecord(params.agent_id as string);
+        if (!record) {
+          return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
+        }
+
+        if (params.wait && record.status === "running" && record.promise) {
+          record.resultConsumed = true;
+          await record.promise;
+        }
+
+        const duration = record.completedAt
+          ? `${((record.completedAt - record.startedAt) / 1000).toFixed(1)}s`
+          : "running";
+
+        let output =
+          `Agent: ${record.id}\n` +
+          `Type: ${record.type} | Status: ${record.status} | Tool uses: ${record.toolUses} | Duration: ${duration}\n` +
+          `Description: ${record.description}\n\n`;
+
+        if (record.status === "running") {
+          output += "Agent is still running. Use wait: true or check back later.";
+        } else if (record.status === "error") {
+          output += `Error: ${record.error}`;
+        } else {
+          output += record.result?.trim() || "No output.";
+        }
+
+        if (record.status !== "running" && record.status !== "queued") {
+          record.resultConsumed = true;
+        }
+
+        return textResult(output);
+      },
+    }),
+  );
+}

package/src/prompts.ts

@@ -0,0 +1,39 @@
+/**
+ * @pi-unipi/subagents — System prompt builder
+ */
+
+import type { AgentConfig } from "./types.js";
+
+/**
+ * Build system prompt for an agent.
+ */
+export function buildAgentPrompt(
+  config: AgentConfig,
+  cwd: string,
+  env: { isGitRepo: boolean; branch: string; platform: string },
+  parentSystemPrompt: string,
+): string {
+  if (config.promptMode === "append") {
+    // Append mode: parent prompt + agent additions
+    return [
+      parentSystemPrompt,
+      "",
+      "---",
+      "",
+      `## Agent Role: ${config.displayName ?? config.name}`,
+      config.systemPrompt,
+    ].join("\n");
+  }
+
+  // Replace mode: standalone prompt
+  return [
+    `# ${config.displayName ?? config.name}`,
+    "",
+    config.systemPrompt,
+    "",
+    "---",
+    "",
+    `Working directory: ${cwd}`,
+    `Git: ${env.isGitRepo ? `${env.branch} on ${env.platform}` : "not a git repo"}`,
+  ].join("\n");
+}

package/src/skills/explore/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: explore
+description: "Fast parallel codebase exploration"
+---
+
+# Explore Agent
+
+Read-only agent for fast parallel codebase exploration.
+
+## Capabilities
+
+- Read files
+- Search with grep, find, ls
+- Run bash commands (read-only)
+
+## Constraints
+
+- Cannot write or edit files
+- Cannot modify the codebase
+- Report findings only
+
+## Usage
+
+Spawn multiple explore agents to read different parts of the codebase in parallel.
+
+```
+Agent({
+  type: "explore",
+  prompt: "Find all files related to authentication",
+  description: "Find auth files"
+})
+```

package/src/skills/work/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: work
+description: "Parallel file writes with transparent locking"
+---
+
+# Work Agent
+
+Read-write agent for parallel file modifications.
+
+## Capabilities
+
+- Read files
+- Write and edit files
+- Run bash commands
+- Search with grep, find, ls
+
+## File Locking
+
+When writing a file, the lock is acquired automatically. If another agent holds the lock, your write waits transparently — you won't see errors.
+
+- Per-file granularity: locking `src/auth.ts` doesn't block `src/login.ts`
+- Locks release automatically when the write completes
+- On abort, all locks are released
+
+## Constraints
+
+- Cannot spawn sub-agents (prevents nesting)
+- Cannot modify other agents' locked files (waits instead)
+
+## Usage
+
+Spawn work agents to modify different files in parallel.
+
+```
+Agent({
+  type: "work",
+  prompt: "Refactor src/auth.ts to use async/await",
+  description: "Refactor auth module"
+})
+```

package/src/types.ts

@@ -0,0 +1,86 @@
+/**
+ * @pi-unipi/subagents — Type definitions
+ */
+
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+
+export type { ThinkingLevel };
+
+/** Agent type name: built-in or user-defined. */
+export type AgentType = string;
+
+/** Built-in agent type names. */
+export const BUILTIN_TYPES = ["explore", "work"] as const;
+
+/** Memory scope for persistent agent memory. */
+export type MemoryScope = "user" | "project" | "local";
+
+/** Unified agent configuration. */
+export interface AgentConfig {
+  name: string;
+  displayName?: string;
+  description: string;
+  builtinToolNames?: string[];
+  disallowedTools?: string[];
+  extensions: true | string[] | false;
+  skills: true | string[] | false;
+  model?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  systemPrompt: string;
+  promptMode: "replace" | "append";
+  inheritContext?: boolean;
+  runInBackground?: boolean;
+  isolated?: boolean;
+  memory?: MemoryScope;
+  isDefault?: boolean;
+  enabled?: boolean;
+  source?: "builtin" | "project" | "global";
+}
+
+/** Agent record — tracks a running agent. */
+export interface AgentRecord {
+  id: string;
+  type: AgentType;
+  description: string;
+  status: "queued" | "running" | "completed" | "aborted" | "stopped" | "error";
+  result?: string;
+  error?: string;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+  session?: AgentSession;
+  abortController?: AbortController;
+  promise?: Promise<string>;
+  /** Set when result consumed via get_result — suppresses notification. */
+  resultConsumed?: boolean;
+  /** Files locked by this agent. */
+  lockedFiles: Set<string>;
+}
+
+/** File lock entry. */
+export interface FileLockEntry {
+  agentId: string;
+  filePath: string;
+  promise: Promise<void>;
+  release: () => void;
+}
+
+/** Extension config. */
+export interface SubagentsConfig {
+  maxConcurrent: number;
+  enabled: boolean;
+  types: Record<string, { enabled?: boolean }>;
+}
+
+/** Agent activity for widget display. */
+export interface AgentActivity {
+  activeTools: Map<string, string>;
+  toolUses: number;
+  turnCount: number;
+  maxTurns?: number;
+  tokens: string;
+  responseText: string;
+  session?: AgentSession;
+}

package/src/widget.ts

@@ -0,0 +1,123 @@
+/**
+ * @pi-unipi/subagents — Live widget
+ *
+ * Shows running agents above the editor.
+ * Adapted from pi-subagents.
+ */
+
+import type { AgentManager } from "./agent-manager.js";
+import type { AgentActivity } from "./types.js";
+
+/** Spinner frames (braille). */
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Format token count. */
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return `${n}`;
+}
+
+/** Format duration. */
+function formatMs(ms: number): string {
+  if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
+  if (ms >= 1_000) return `${(ms / 1_000).toFixed(1)}s`;
+  return `${ms}ms`;
+}
+
+/** Format turns. */
+function formatTurns(turn: number, max?: number): string {
+  return max ? `⟳${turn}≤${max}` : `⟳${turn}`;
+}
+
+/** Describe current activity from active tools. */
+function describeActivity(activeTools: Map<string, string>, responseText: string): string {
+  if (activeTools.size > 0) {
+    const names = [...new Set(activeTools.values())];
+    return names.join(", ") + "…";
+  }
+  if (responseText) {
+    const lastLine = responseText.split("\n").pop()?.trim() ?? "";
+    if (lastLine.length > 0) return lastLine.slice(0, 60) + (lastLine.length > 60 ? "…" : "");
+  }
+  return "thinking…";
+}
+
+export class AgentWidget {
+  private manager: AgentManager;
+  private activity: Map<string, AgentActivity>;
+  private spinnerFrame = 0;
+  private timer?: ReturnType<typeof setInterval>;
+  private uiCtx?: any;
+
+  constructor(manager: AgentManager, activity: Map<string, AgentActivity>) {
+    this.manager = manager;
+    this.activity = activity;
+  }
+
+  setUICtx(ctx: any) {
+    this.uiCtx = ctx;
+  }
+
+  ensureTimer() {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER.length;
+      this.render();
+    }, 80);
+  }
+
+  markFinished(_id: string) {
+    // Check if any agents still running
+    if (!this.manager.hasRunning()) {
+      if (this.timer) {
+        clearInterval(this.timer);
+        this.timer = undefined;
+      }
+    }
+  }
+
+  update() {
+    this.render();
+  }
+
+  private render() {
+    const agents = this.manager.listAgents();
+    const running = agents.filter((a) => a.status === "running" || a.status === "queued");
+
+    if (running.length === 0) {
+      // Clear widget
+      this.uiCtx?.setIndicator?.("");
+      return;
+    }
+
+    const lines: string[] = [];
+    const frame = SPINNER[this.spinnerFrame];
+
+    for (const agent of running) {
+      const act = this.activity.get(agent.id);
+      const toolCount = agent.toolUses;
+      const tokens = act?.tokens ?? "";
+      const duration = formatMs(Date.now() - agent.startedAt);
+      const activity = act ? describeActivity(act.activeTools, act.responseText) : "starting…";
+
+      const parts: string[] = [];
+      if (act?.turnCount) parts.push(formatTurns(act.turnCount, act.maxTurns));
+      if (toolCount > 0) parts.push(`${toolCount} tool uses`);
+      if (tokens) parts.push(tokens);
+      parts.push(duration);
+
+      lines.push(
+        `${frame} ${agent.type}  ${agent.description}  ·  ${parts.join(" · ")}`,
+        `  ⎿  ${activity}`,
+      );
+    }
+
+    const queued = agents.filter((a) => a.status === "queued").length;
+    if (queued > 0) {
+      lines.push(`  ${queued} queued`);
+    }
+
+    this.uiCtx?.setIndicator?.(lines.join("\n"));
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}