@by-lua/lspec-subagents 1.0.1

package/install.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# lspec-subagents — Instalador
+# Uso: curl -fsSL https://raw.githubusercontent.com/by-lua/lspec-subagents/main/install.sh | bash
+# Alternativa npm: curl -fsSL https://raw.githubusercontent.com/by-lua/lspec-subagents/main/install.sh | bash -s npm
+# Requer: git, pi (PI.dev)
+
+set -uo pipefail
+
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+REPO="https://github.com/by-lua/lspec-subagents.git"
+PI_AGENTS_DIR="$HOME/.pi/agents"
+PI_AGENT_DIR="$HOME/.pi/agent"
+
+echo ""
+echo -e "${BLUE}╔════════════════════════════════╗${NC}"
+echo -e "${BLUE}║  lspec-subagents — Instalador  ║${NC}"
+echo -e "${BLUE}╚════════════════════════════════╝${NC}"
+echo ""
+
+if ! command -v pi &>/dev/null; then
+    echo -e "${RED}✗ PI não encontrado. Instale em https://pi.dev${NC}"
+    exit 1
+fi
+
+# ── Passo 0: Remover extensões conflitantes ──
+echo -e "${BLUE}→ Removendo extensões conflitantes...${NC}"
+pi remove "npm:@tintinweb/pi-subagents" 2>/dev/null && echo -e "  ${YELLOW}⊘${NC} Removido npm:@tintinweb/pi-subagents (conflito)"
+pi remove "git:github.com/by-lua/lspec-subagents" 2>/dev/null
+pi remove "npm:@by-lua/lspec-subagents" 2>/dev/null
+
+# ── Passo 1: Instalar extensão via npm ──
+echo -e "${BLUE}→ Instalando @by-lua/lspec-subagents via npm...${NC}"
+pi install "npm:@by-lua/lspec-subagents" 2>/dev/null
+echo -e "  ${GREEN}✓${NC} Extensão instalada (9 agentes L-Spec + /agents)"
+
+# ── Passo 2: Clonar e copiar .md de agentes ──
+echo -e "${BLUE}→ Copiando agent .md files...${NC}"
+REPO_DIR="$(mktemp -d)"
+git clone --depth 1 "$REPO" "$REPO_DIR" 2>/dev/null || {
+    echo -e "${RED}✗ Erro ao clonar. Git instalado?${NC}"; rm -rf "$REPO_DIR"; exit 1; }
+
+mkdir -p "$PI_AGENTS_DIR" "$PI_AGENT_DIR"
+
+agent_count=0
+for agent_file in "$REPO_DIR"/.pi/agents/*.md; do
+    [[ -f "$agent_file" ]] || continue
+    agent_name=$(basename "$agent_file")
+    cp "$agent_file" "$PI_AGENTS_DIR/$agent_name"
+    echo -e "  ${GREEN}✓${NC} agents/$agent_name"
+    ((agent_count++))
+done
+
+# Copiar config de modelos (não sobrescreve se já existe)
+if [[ -f "$REPO_DIR/lspec-model-config.example.json" ]]; then
+    if [[ ! -f "$PI_AGENT_DIR/lspec-model-config.json" ]]; then
+        cp "$REPO_DIR/lspec-model-config.example.json" "$PI_AGENT_DIR/lspec-model-config.json"
+        echo -e "  ${GREEN}✓${NC} lspec-model-config.json (criado com defaults)"
+    else
+        echo -e "  ${BLUE}⊘${NC} lspec-model-config.json (já existe, mantido)"
+    fi
+fi
+
+echo ""
+echo -e "${GREEN}✓ lspec-subagents instalado!${NC} ($agent_count .md agents | extensão @by-lua/lspec-subagents)"
+echo ""
+echo "Agentes: orchestrator | explorer | librarian | oracle | designer | fixer | observer | council | councillor"
+echo "Extensão: pi install npm:@by-lua/lspec-subagents"
+echo "Config:   ~/.pi/agent/lspec-model-config.json"
+echo "Atualizar: curl -fsSL https://raw.githubusercontent.com/by-lua/lspec-subagents/main/update.sh | bash"
+echo "Desinstalar: curl -fsSL https://raw.githubusercontent.com/by-lua/lspec-subagents/main/uninstall.sh | bash"
+echo ""
+rm -rf "$REPO_DIR"

package/lspec-model-config.example.json

@@ -0,0 +1,17 @@
+{
+  "_note": "L-Spec Model Config — centralized model assignment for all subagents.",
+  "_docs": "Place this file at .pi/lspec-model-config.json (project) or ~/.pi/agent/lspec-model-config.json (global).",
+  "_override_order": "project > global > embedded defaults",
+  "_usage": "Each entry maps an agent role to a model string. Format: 'provider/modelId' or just 'modelId'. Mix and match providers freely.",
+  "agents": {
+    "orchestrator": "claude-sonnet-4",
+    "explorer": "gpt-4o-mini",
+    "librarian": "claude-sonnet-4",
+    "oracle": "claude-opus-4",
+    "designer": "claude-sonnet-4",
+    "fixer": "codex",
+    "observer": "gpt-4o-mini",
+    "council": "claude-opus-4",
+    "councillor": "grok-2"
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@by-lua/lspec-subagents",
+  "version": "1.0.1",
+  "description": "L-Spec Subagents \u2014 9 specialized agents for PI.dev with centralized model config (inspired by oh-my-opencode-slim). Forked from @tintinweb/pi-subagents.",
+  "author": "Lua <noelia.assis@by-lua.com> (https://github.com/by-lua)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/by-lua/lspec-subagents.git"
+  },
+  "homepage": "https://github.com/by-lua/lspec-subagents#readme",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "subagent",
+    "agent",
+    "autonomous",
+    "lspec",
+    "sdd"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-ai": ">=0.70.5",
+    "@mariozechner/pi-coding-agent": ">=0.70.5",
+    "@mariozechner/pi-tui": ">=0.70.5"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "croner": "^10.0.1",
+    "nanoid": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ test/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.18"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "image": "https://raw.githubusercontent.com/lua/lspec-subagents/main/media/screenshot.png"
+  }
+}

package/src/agent-manager.ts

@@ -0,0 +1,483 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Model } from "@mariozechner/pi-ai";
+import type { AgentSession, ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import { addUsage } from "./usage.js";
+import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
+
+export type OnAgentComplete = (record: AgentRecord) => void;
+export type OnAgentStart = (record: AgentRecord) => void;
+export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
+export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
+
+/** Default max concurrent background agents. */
+const DEFAULT_MAX_CONCURRENT = 4;
+
+interface SpawnArgs {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  type: SubagentType;
+  prompt: string;
+  options: SpawnOptions;
+}
+
+interface SpawnOptions {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  isBackground?: boolean;
+  /**
+   * Skip the maxConcurrent queue check for this spawn — start immediately even
+   * if the configured concurrency limit would otherwise queue it. Used by the
+   * scheduler so a fired job can't be deferred past its trigger window.
+   */
+  bypassQueue?: boolean;
+  /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
+  isolation?: IsolationMode;
+  /** Resolved invocation snapshot captured for UI display. */
+  invocation?: AgentInvocation;
+  /** Parent abort signal — when aborted, the subagent is also stopped. */
+  signal?: AbortSignal;
+  /** Called on tool start/end with activity info (for streaming progress to UI). */
+  onToolActivity?: (activity: ToolActivity) => void;
+  /** Called on streaming text deltas from the assistant response. */
+  onTextDelta?: (delta: string, fullText: string) => void;
+  /** Called when the agent session is created (for accessing session stats). */
+  onSessionCreated?: (session: AgentSession) => void;
+  /** Called at the end of each agentic turn with the cumulative count. */
+  onTurnEnd?: (turnCount: number) => void;
+  /** Called once per assistant message_end with that message's usage delta. */
+  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  /** Called when the session successfully compacts. */
+  onCompaction?: (info: CompactionInfo) => void;
+}
+
+export class AgentManager {
+  private agents = new Map<string, AgentRecord>();
+  private cleanupInterval: ReturnType<typeof setInterval>;
+  private onComplete?: OnAgentComplete;
+  private onStart?: OnAgentStart;
+  private onCompact?: OnAgentCompact;
+  private maxConcurrent: number;
+
+  /** Queue of background agents waiting to start. */
+  private queue: { id: string; args: SpawnArgs }[] = [];
+  /** Number of currently running background agents. */
+  private runningBackground = 0;
+
+  constructor(
+    onComplete?: OnAgentComplete,
+    maxConcurrent = DEFAULT_MAX_CONCURRENT,
+    onStart?: OnAgentStart,
+    onCompact?: OnAgentCompact,
+  ) {
+    this.onComplete = onComplete;
+    this.onStart = onStart;
+    this.onCompact = onCompact;
+    this.maxConcurrent = maxConcurrent;
+    // Cleanup completed agents after 10 minutes (but keep sessions for resume)
+    this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    this.cleanupInterval.unref();
+  }
+
+  /** Update the max concurrent background agents limit. */
+  setMaxConcurrent(n: number) {
+    this.maxConcurrent = Math.max(1, n);
+    // Start queued agents if the new limit allows
+    this.drainQueue();
+  }
+
+  getMaxConcurrent(): number {
+    return this.maxConcurrent;
+  }
+
+  /**
+   * Spawn an agent and return its ID immediately (for background use).
+   * If the concurrency limit is reached, the agent is queued.
+   */
+  spawn(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: SubagentType,
+    prompt: string,
+    options: SpawnOptions,
+  ): string {
+    const id = randomUUID().slice(0, 17);
+    const abortController = new AbortController();
+    const record: AgentRecord = {
+      id,
+      type,
+      description: options.description,
+      status: options.isBackground ? "queued" : "running",
+      toolUses: 0,
+      startedAt: Date.now(),
+      abortController,
+      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+      compactionCount: 0,
+      invocation: options.invocation,
+    };
+    this.agents.set(id, record);
+
+    const args: SpawnArgs = { pi, ctx, type, prompt, options };
+
+    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
+      // Queue it — will be started when a running agent completes
+      this.queue.push({ id, args });
+      return id;
+    }
+
+    // startAgent can throw (e.g. strict worktree-isolation failure) — clean
+    // up the record so callers don't see an orphan in `listAgents()`.
+    try {
+      this.startAgent(id, record, args);
+    } catch (err) {
+      this.agents.delete(id);
+      throw err;
+    }
+    return id;
+  }
+
+  /** Actually start an agent (called immediately or from queue drain). */
+  private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
+    // Worktree isolation: try to create a temporary git worktree. Strict —
+    // fail loud if not possible (no silent fallback to main tree). Done
+    // BEFORE state mutation so a throw doesn't leave the record half-running.
+    let worktreeCwd: string | undefined;
+    if (options.isolation === "worktree") {
+      const wt = createWorktree(ctx.cwd, id);
+      if (!wt) {
+        throw new Error(
+          'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+          'Initialize git and commit at least once, or omit `isolation`.',
+        );
+      }
+      record.worktree = wt;
+      worktreeCwd = wt.path;
+    }
+
+    record.status = "running";
+    record.startedAt = Date.now();
+    if (options.isBackground) this.runningBackground++;
+    this.onStart?.(record);
+
+    // Wire parent abort signal to stop the subagent when the parent is interrupted
+    let detachParentSignal: (() => void) | undefined;
+    if (options.signal) {
+      const onParentAbort = () => this.abort(id);
+      options.signal.addEventListener("abort", onParentAbort, { once: true });
+      detachParentSignal = () => options.signal!.removeEventListener("abort", onParentAbort);
+    }
+    const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
+
+    const promise = runAgent(ctx, type, prompt, {
+      pi,
+      agentId: id,
+      model: options.model,
+      maxTurns: options.maxTurns,
+      isolated: options.isolated,
+      inheritContext: options.inheritContext,
+      thinkingLevel: options.thinkingLevel,
+      cwd: worktreeCwd,
+      signal: record.abortController!.signal,
+      onToolActivity: (activity) => {
+        if (activity.type === "end") record.toolUses++;
+        options.onToolActivity?.(activity);
+      },
+      onTurnEnd: options.onTurnEnd,
+      onTextDelta: options.onTextDelta,
+      onAssistantUsage: (usage) => {
+        addUsage(record.lifetimeUsage, usage);
+        options.onAssistantUsage?.(usage);
+      },
+      onCompaction: (info) => {
+        record.compactionCount++;
+        this.onCompact?.(record, info);
+        options.onCompaction?.(info);
+      },
+      onSessionCreated: (session) => {
+        record.session = session;
+        // Flush any steers that arrived before the session was ready
+        if (record.pendingSteers?.length) {
+          for (const msg of record.pendingSteers) {
+            session.steer(msg).catch(() => {});
+          }
+          record.pendingSteers = undefined;
+        }
+        options.onSessionCreated?.(session);
+      },
+    })
+      .then(({ responseText, session, aborted, steered }) => {
+        // Don't overwrite status if externally stopped via abort()
+        if (record.status !== "stopped") {
+          record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+        }
+        record.result = responseText;
+        record.session = session;
+        record.completedAt ??= Date.now();
+
+        detach();
+
+        // Final flush of streaming output file
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
+        // Clean up worktree if used
+        if (record.worktree) {
+          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          record.worktreeResult = wtResult;
+          if (wtResult.hasChanges && wtResult.branch) {
+            record.result = (record.result ?? "") +
+              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+          }
+        }
+
+        if (options.isBackground) {
+          this.runningBackground--;
+          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+          this.drainQueue();
+        }
+        return responseText;
+      })
+      .catch((err) => {
+        // Don't overwrite status if externally stopped via abort()
+        if (record.status !== "stopped") {
+          record.status = "error";
+        }
+        record.error = err instanceof Error ? err.message : String(err);
+        record.completedAt ??= Date.now();
+
+        detach();
+
+        // Final flush of streaming output file on error
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
+        // Best-effort worktree cleanup on error
+        if (record.worktree) {
+          try {
+            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            record.worktreeResult = wtResult;
+          } catch { /* ignore cleanup errors */ }
+        }
+
+        if (options.isBackground) {
+          this.runningBackground--;
+          this.onComplete?.(record);
+          this.drainQueue();
+        }
+        return "";
+      });
+
+    record.promise = promise;
+  }
+
+  /** Start queued agents up to the concurrency limit. */
+  private drainQueue() {
+    while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
+      const next = this.queue.shift()!;
+      const record = this.agents.get(next.id);
+      if (!record || record.status !== "queued") continue;
+      try {
+        this.startAgent(next.id, record, next.args);
+      } catch (err) {
+        // Late failure (e.g. strict worktree-isolation) — surface on the record
+        // so the user/agent can see it via /agents, then keep draining.
+        record.status = "error";
+        record.error = err instanceof Error ? err.message : String(err);
+        record.completedAt = Date.now();
+        this.onComplete?.(record);
+      }
+    }
+  }
+
+  /**
+   * Spawn an agent and wait for completion (foreground use).
+   * Foreground agents bypass the concurrency queue.
+   */
+  async spawnAndWait(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: SubagentType,
+    prompt: string,
+    options: Omit<SpawnOptions, "isBackground">,
+  ): Promise<AgentRecord> {
+    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+    const record = this.agents.get(id)!;
+    await record.promise;
+    return record;
+  }
+
+  /**
+   * Resume an existing agent session with a new prompt.
+   */
+  async resume(
+    id: string,
+    prompt: string,
+    signal?: AbortSignal,
+  ): Promise<AgentRecord | undefined> {
+    const record = this.agents.get(id);
+    if (!record?.session) return undefined;
+
+    record.status = "running";
+    record.startedAt = Date.now();
+    record.completedAt = undefined;
+    record.result = undefined;
+    record.error = undefined;
+
+    try {
+      const responseText = await resumeAgent(record.session, prompt, {
+        onToolActivity: (activity) => {
+          if (activity.type === "end") record.toolUses++;
+        },
+        onAssistantUsage: (usage) => {
+          addUsage(record.lifetimeUsage, usage);
+        },
+        onCompaction: (info) => {
+          record.compactionCount++;
+          this.onCompact?.(record, info);
+        },
+        signal,
+      });
+      record.status = "completed";
+      record.result = responseText;
+      record.completedAt = Date.now();
+    } catch (err) {
+      record.status = "error";
+      record.error = err instanceof Error ? err.message : String(err);
+      record.completedAt = Date.now();
+    }
+
+    return record;
+  }
+
+  getRecord(id: string): AgentRecord | undefined {
+    return this.agents.get(id);
+  }
+
+  listAgents(): AgentRecord[] {
+    return [...this.agents.values()].sort(
+      (a, b) => b.startedAt - a.startedAt,
+    );
+  }
+
+  abort(id: string): boolean {
+    const record = this.agents.get(id);
+    if (!record) return false;
+
+    // Remove from queue if queued
+    if (record.status === "queued") {
+      this.queue = this.queue.filter(q => q.id !== id);
+      record.status = "stopped";
+      record.completedAt = Date.now();
+      return true;
+    }
+
+    if (record.status !== "running") return false;
+    record.abortController?.abort();
+    record.status = "stopped";
+    record.completedAt = Date.now();
+    return true;
+  }
+
+  /** Dispose a record's session and remove it from the map. */
+  private removeRecord(id: string, record: AgentRecord): void {
+    record.session?.dispose?.();
+    record.session = undefined;
+    this.agents.delete(id);
+  }
+
+  private cleanup() {
+    const cutoff = Date.now() - 10 * 60_000;
+    for (const [id, record] of this.agents) {
+      if (record.status === "running" || record.status === "queued") continue;
+      if ((record.completedAt ?? 0) >= cutoff) continue;
+      this.removeRecord(id, record);
+    }
+  }
+
+  /**
+   * Remove all completed/stopped/errored records immediately.
+   * Called on session start/switch so tasks from a prior session don't persist.
+   */
+  clearCompleted(): void {
+    for (const [id, record] of this.agents) {
+      if (record.status === "running" || record.status === "queued") continue;
+      this.removeRecord(id, record);
+    }
+  }
+
+  /** Whether any agents are still running or queued. */
+  hasRunning(): boolean {
+    return [...this.agents.values()].some(
+      r => r.status === "running" || r.status === "queued",
+    );
+  }
+
+  /** Abort all running and queued agents immediately. */
+  abortAll(): number {
+    let count = 0;
+    // Clear queued agents first
+    for (const queued of this.queue) {
+      const record = this.agents.get(queued.id);
+      if (record) {
+        record.status = "stopped";
+        record.completedAt = Date.now();
+        count++;
+      }
+    }
+    this.queue = [];
+    // Abort running agents
+    for (const record of this.agents.values()) {
+      if (record.status === "running") {
+        record.abortController?.abort();
+        record.status = "stopped";
+        record.completedAt = Date.now();
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /** Wait for all running and queued agents to complete (including queued ones). */
+  async waitForAll(): Promise<void> {
+    // Loop because drainQueue respects the concurrency limit — as running
+    // agents finish they start queued ones, which need awaiting too.
+    while (true) {
+      this.drainQueue();
+      const pending = [...this.agents.values()]
+        .filter(r => r.status === "running" || r.status === "queued")
+        .map(r => r.promise)
+        .filter(Boolean);
+      if (pending.length === 0) break;
+      await Promise.allSettled(pending);
+    }
+  }
+
+  dispose() {
+    clearInterval(this.cleanupInterval);
+    // Clear queue
+    this.queue = [];
+    for (const record of this.agents.values()) {
+      record.session?.dispose();
+    }
+    this.agents.clear();
+    // Prune any orphaned git worktrees (crash recovery)
+    try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
+  }
+}