@pi-unipi/subagents 0.1.0

package/src/agent-runner.ts

@@ -0,0 +1,306 @@
+/**
+ * @pi-unipi/subagents — Agent runner
+ *
+ * Creates sessions, runs agents, collects results.
+ * Forwards abort signals for ESC propagation.
+ */
+
+import type { Model } from "@mariozechner/pi-ai";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  type AgentSession,
+  type AgentSessionEvent,
+  createAgentSession,
+  DefaultResourceLoader,
+  type ExtensionAPI,
+  getAgentDir,
+  SessionManager,
+  SettingsManager,
+} from "@mariozechner/pi-coding-agent";
+import type { AgentConfig, AgentType, ThinkingLevel } from "./types.js";
+
+/** Tools excluded from subagents to prevent nesting. */
+const EXCLUDED_TOOL_NAMES = ["Agent", "get_result"];
+
+/** All known built-in tool names. */
+const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+/** Default max turns. undefined = unlimited. */
+let defaultMaxTurns: number | undefined;
+
+export function getDefaultMaxTurns(): number | undefined {
+  return defaultMaxTurns;
+}
+
+export function setDefaultMaxTurns(n: number | undefined): void {
+  defaultMaxTurns = n == null || n === 0 ? undefined : Math.max(1, n);
+}
+
+/** Grace turns after soft limit. */
+let graceTurns = 5;
+
+export function getGraceTurns(): number {
+  return graceTurns;
+}
+
+export function setGraceTurns(n: number): void {
+  graceTurns = Math.max(1, n);
+}
+
+/** Tool activity info. */
+export interface ToolActivity {
+  type: "start" | "end";
+  toolName: string;
+}
+
+/** Options for running an agent. */
+export interface RunOptions {
+  pi: ExtensionAPI;
+  model?: Model<any>;
+  maxTurns?: number;
+  signal?: AbortSignal;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  cwd?: string;
+  onToolActivity?: (activity: ToolActivity) => void;
+  onTextDelta?: (delta: string, fullText: string) => void;
+  onSessionCreated?: (session: AgentSession) => void;
+  onTurnEnd?: (turnCount: number) => void;
+}
+
+/** Result from running an agent. */
+export interface RunResult {
+  responseText: string;
+  session: AgentSession;
+  aborted: boolean;
+  steered: boolean;
+}
+
+/** Collect last assistant message text. */
+function collectResponseText(session: AgentSession) {
+  let text = "";
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "message_start") {
+      text = "";
+    }
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+      text += event.assistantMessageEvent.delta;
+    }
+  });
+  return { getText: () => text, unsubscribe };
+}
+
+/** Get last assistant text from session history. */
+function getLastAssistantText(session: AgentSession): string {
+  for (let i = session.messages.length - 1; i >= 0; i--) {
+    const msg = session.messages[i];
+    if (msg.role !== "assistant") continue;
+    const text = msg.content
+      .filter((c): c is { type: "text"; text: string } => c.type === "text")
+      .map((c) => c.text)
+      .join("")
+      .trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+/** Wire abort signal to session. */
+function forwardAbortSignal(session: AgentSession, signal?: AbortSignal): () => void {
+  if (!signal) return () => {};
+  const onAbort = () => session.abort();
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}
+
+/** Get tool names for agent type. */
+function getToolNamesForType(type: AgentType, config?: AgentConfig): string[] {
+  if (config?.builtinToolNames?.length) {
+    return [...config.builtinToolNames];
+  }
+  return [...BUILTIN_TOOL_NAMES];
+}
+
+/** Resolve model from config. */
+function resolveDefaultModel(
+  parentModel: Model<any> | undefined,
+  configModel?: string,
+): Model<any> | undefined {
+  // For now, just use parent model. Full model resolution requires registry.
+  return parentModel;
+}
+
+/**
+ * Run an agent session.
+ */
+export async function runAgent(
+  ctx: ExtensionContext,
+  type: AgentType,
+  prompt: string,
+  options: RunOptions,
+): Promise<RunResult> {
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+
+  // Build system prompt
+  const agentConfig = options as any; // Will be properly typed later
+  const parentSystemPrompt = ctx.getSystemPrompt();
+
+  let systemPrompt: string;
+  if (options.isolated) {
+    systemPrompt = `You are a ${type} agent. Follow the task instructions precisely. Do not ask questions.`;
+  } else {
+    systemPrompt = parentSystemPrompt + `\n\nYou are a ${type} agent. Follow the task instructions precisely.`;
+  }
+
+  // Get tool names
+  let toolNames = getToolNamesForType(type);
+
+  // Create resource loader
+  const agentDir = getAgentDir();
+  const loader = new DefaultResourceLoader({
+    cwd: effectiveCwd,
+    agentDir,
+    noExtensions: options.isolated,
+    noSkills: options.isolated,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    systemPromptOverride: () => systemPrompt,
+    appendSystemPromptOverride: () => [],
+  });
+  await loader.reload();
+
+  // Resolve model
+  const model = options.model ?? resolveDefaultModel(ctx.model);
+
+  // Create session
+  const sessionOpts: Parameters<typeof createAgentSession>[0] = {
+    cwd: effectiveCwd,
+    agentDir,
+    sessionManager: SessionManager.inMemory(effectiveCwd),
+    settingsManager: SettingsManager.create(effectiveCwd, agentDir),
+    modelRegistry: ctx.modelRegistry,
+    model,
+    tools: toolNames,
+    resourceLoader: loader,
+  };
+  if (options.thinkingLevel) {
+    sessionOpts.thinkingLevel = options.thinkingLevel;
+  }
+
+  const { session } = await createAgentSession(sessionOpts);
+
+  // Filter out our tools to prevent nesting
+  const activeTools = session.getActiveToolNames().filter((t) => {
+    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
+    return true;
+  });
+  session.setActiveToolsByName(activeTools);
+
+  // Bind extensions
+  await session.bindExtensions({
+    onError: (err) => {
+      options.onToolActivity?.({
+        type: "end",
+        toolName: `extension-error:${err.extensionPath}`,
+      });
+    },
+  });
+
+  options.onSessionCreated?.(session);
+
+  // Track turns
+  let turnCount = 0;
+  const maxTurns = options.maxTurns ?? defaultMaxTurns;
+  let softLimitReached = false;
+  let aborted = false;
+
+  let currentMessageText = "";
+  const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "turn_end") {
+      turnCount++;
+      options.onTurnEnd?.(turnCount);
+      if (maxTurns != null) {
+        if (!softLimitReached && turnCount >= maxTurns) {
+          softLimitReached = true;
+          session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
+        } else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
+          aborted = true;
+          session.abort();
+        }
+      }
+    }
+    if (event.type === "message_start") {
+      currentMessageText = "";
+    }
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+      currentMessageText += event.assistantMessageEvent.delta;
+      options.onTextDelta?.(event.assistantMessageEvent.delta, currentMessageText);
+    }
+    if (event.type === "tool_execution_start") {
+      options.onToolActivity?.({ type: "start", toolName: event.toolName });
+    }
+    if (event.type === "tool_execution_end") {
+      options.onToolActivity?.({ type: "end", toolName: event.toolName });
+    }
+  });
+
+  const collector = collectResponseText(session);
+  const cleanupAbort = forwardAbortSignal(session, options.signal);
+
+  try {
+    await session.prompt(prompt);
+  } finally {
+    unsubTurns();
+    collector.unsubscribe();
+    cleanupAbort();
+  }
+
+  const responseText = collector.getText().trim() || getLastAssistantText(session);
+  return { responseText, session, aborted, steered: softLimitReached };
+}
+
+/**
+ * Get conversation text from a session.
+ */
+export function getAgentConversation(session: AgentSession): string {
+  const parts: string[] = [];
+
+  for (const msg of session.messages) {
+    if (msg.role === "user") {
+      const content = msg.content;
+      const text = typeof content === "string"
+        ? content
+        : content
+            .filter((c): c is { type: "text"; text: string } => c.type === "text")
+            .map((c) => c.text)
+            .join("");
+      if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+    } else if (msg.role === "assistant") {
+      const textParts: string[] = [];
+      const toolCalls: string[] = [];
+      const content = msg.content;
+      if (typeof content !== "string") {
+        for (const c of content) {
+          if (c.type === "text" && c.text) textParts.push(c.text);
+          else if (c.type === "toolCall") toolCalls.push(`  Tool: ${(c as any).name ?? "unknown"}`);
+        }
+      }
+      if (textParts.length > 0) parts.push(`[Assistant]: ${textParts.join("\n")}`);
+      if (toolCalls.length > 0) parts.push(`[Tool Calls]:\n${toolCalls.join("\n")}`);
+    } else if (msg.role === "toolResult") {
+      const content = msg.content;
+      const text = typeof content === "string"
+        ? content
+        : content
+            .filter((c): c is { type: "text"; text: string } => c.type === "text")
+            .map((c) => c.text)
+            .join("");
+      const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+      parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+    }
+  }
+
+  return parts.join("\n\n");
+}

package/src/config.ts

@@ -0,0 +1,128 @@
+/**
+ * @pi-unipi/subagents — Config management
+ *
+ * Loads config from ~/.unipc/config/subagents.json (global)
+ * and <workspace>/.unipi/config/subagents.json (override).
+ * Auto-generates on first run. Repairs corrupted files.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { SubagentsConfig } from "./types.js";
+
+const DEFAULT_CONFIG: SubagentsConfig = {
+  maxConcurrent: 4,
+  enabled: true,
+  types: {
+    explore: { enabled: true },
+    work: { enabled: true },
+  },
+};
+
+/** Get global config path: ~/.unipi/config/subagents.json */
+function getGlobalConfigPath(): string {
+  return join(homedir(), ".unipi", "config", "subagents.json");
+}
+
+/** Get workspace config path: <cwd>/.unipi/config/subagents.json */
+function getWorkspaceConfigPath(cwd: string): string {
+  return join(cwd, ".unipi", "config", "subagents.json");
+}
+
+/** Ensure directory exists. */
+function ensureDir(filePath: string): void {
+  const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/** Write config atomically (write then rename). */
+function writeConfigAtomic(filePath: string, config: SubagentsConfig): void {
+  const tmpPath = filePath + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+  renameSync(tmpPath, filePath);
+}
+
+/** Load and parse config from a path. Returns null on failure. */
+function loadConfigFromPath(filePath: string): SubagentsConfig | null {
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    // Basic validation
+    if (typeof parsed !== "object" || parsed === null) return null;
+    return parsed as SubagentsConfig;
+  } catch {
+    return null;
+  }
+}
+
+/** Repair corrupted config: rename to .bak and generate fresh. */
+function repairCorrupted(filePath: string): SubagentsConfig {
+  const backupPath = filePath + ".bak";
+  try {
+    renameSync(filePath, backupPath);
+  } catch {
+    // If rename fails, just overwrite
+  }
+  writeConfigAtomic(filePath, DEFAULT_CONFIG);
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Initialize config on extension start.
+ * - If missing: generate with defaults
+ * - If corrupted: rename to .bak, generate fresh
+ * - If valid: load
+ */
+export function initConfig(cwd: string): SubagentsConfig {
+  const globalPath = getGlobalConfigPath();
+
+  // Ensure global config dir exists
+  ensureDir(globalPath);
+
+  // Load or create global config
+  let globalConfig = loadConfigFromPath(globalPath);
+  if (globalConfig === null) {
+    globalConfig = repairCorrupted(globalPath);
+  }
+
+  // Load workspace override if exists
+  const workspacePath = getWorkspaceConfigPath(cwd);
+  const workspaceConfig = loadConfigFromPath(workspacePath);
+
+  if (workspaceConfig) {
+    // Merge: workspace overrides global on any field present
+    return {
+      ...globalConfig,
+      ...workspaceConfig,
+      types: {
+        ...globalConfig.types,
+        ...workspaceConfig.types,
+      },
+    };
+  }
+
+  return globalConfig;
+}
+
+/**
+ * Save global config.
+ */
+export function saveGlobalConfig(config: SubagentsConfig): void {
+  const globalPath = getGlobalConfigPath();
+  ensureDir(globalPath);
+  writeConfigAtomic(globalPath, config);
+}
+
+/**
+ * Save workspace config.
+ */
+export function saveWorkspaceConfig(cwd: string, config: SubagentsConfig): void {
+  const workspacePath = getWorkspaceConfigPath(cwd);
+  ensureDir(workspacePath);
+  writeConfigAtomic(workspacePath, config);
+}

package/src/custom-agents.ts

@@ -0,0 +1,106 @@
+/**
+ * @pi-unipi/subagents — Custom agent loader
+ *
+ * Discovers agent types from:
+ * - <workspace>/.unipc/config/agents/*.md (project, highest priority)
+ * - ~/.unipc/config/agents/*.md (global)
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import type { AgentConfig } from "./types.js";
+
+/** Get project agents directory. */
+function getProjectAgentsDir(cwd: string): string {
+  return join(cwd, ".unipc", "config", "agents");
+}
+
+/** Get global agents directory. */
+function getGlobalAgentsDir(): string {
+  return join(homedir(), ".unipc", "config", "agents");
+}
+
+/** All known built-in tool names. */
+const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+/**
+ * Load a single agent from a .md file.
+ */
+function loadAgentFromFile(filePath: string, source: "project" | "global"): AgentConfig | null {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    if (!frontmatter || typeof frontmatter !== "object") {
+      return null;
+    }
+
+    const name = filePath.split("/").pop()?.replace(/\.md$/, "") ?? "unknown";
+
+    // Parse tools from comma-separated string
+    const toolsStr = (frontmatter as any).tools as string | undefined;
+    const builtinToolNames = toolsStr
+      ? toolsStr.split(",").map((t) => t.trim()).filter((t) => BUILTIN_TOOL_NAMES.includes(t))
+      : [...BUILTIN_TOOL_NAMES];
+
+    return {
+      name,
+      displayName: (frontmatter as any).display_name as string | undefined,
+      description: ((frontmatter as any).description as string) ?? `${name} agent`,
+      builtinToolNames,
+      disallowedTools: ((frontmatter as any).disallowed_tools as string | undefined)
+        ?.split(",")
+        .map((t) => t.trim()),
+      extensions: (frontmatter as any).extensions !== false,
+      skills: (frontmatter as any).skills !== false,
+      model: (frontmatter as any).model as string | undefined,
+      thinking: (frontmatter as any).thinking as any,
+      maxTurns: (frontmatter as any).max_turns as number | undefined,
+      systemPrompt: body.trim(),
+      promptMode: ((frontmatter as any).prompt_mode as "replace" | "append") ?? "replace",
+      inheritContext: (frontmatter as any).inherit_context as boolean | undefined,
+      runInBackground: (frontmatter as any).run_in_background as boolean | undefined,
+      isolated: (frontmatter as any).isolated as boolean | undefined,
+      enabled: (frontmatter as any).enabled !== false,
+      source,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load all custom agents from project and global directories.
+ * Project agents override global agents with the same name.
+ */
+export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+  const agents = new Map<string, AgentConfig>();
+
+  // Load global agents first
+  const globalDir = getGlobalAgentsDir();
+  if (existsSync(globalDir)) {
+    const files = readdirSync(globalDir).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      const agent = loadAgentFromFile(join(globalDir, file), "global");
+      if (agent) {
+        agents.set(agent.name, agent);
+      }
+    }
+  }
+
+  // Load project agents (overrides global)
+  const projectDir = getProjectAgentsDir(cwd);
+  if (existsSync(projectDir)) {
+    const files = readdirSync(projectDir).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      const agent = loadAgentFromFile(join(projectDir, file), "project");
+      if (agent) {
+        agents.set(agent.name, agent);
+      }
+    }
+  }
+
+  return agents;
+}

package/src/file-lock.ts

@@ -0,0 +1,102 @@
+/**
+ * @pi-unipi/subagents — Per-file transparent locking
+ *
+ * Agents never see lock errors. Write tool queues internally.
+ * Per-file granularity: locking src/auth.ts doesn't block src/login.ts.
+ */
+
+import type { FileLockEntry } from "./types.js";
+
+export class FileLock {
+  /** Active locks by file path. */
+  private locks = new Map<string, FileLockEntry>();
+  /** Queue of waiting acquires per file path. */
+  private queues = new Map<string, Array<() => void>>();
+
+  /**
+   * Acquire a lock on a file. Blocks until available.
+   * Returns a release function.
+   *
+   * @param filePath - Absolute path to the file
+   * @param agentId - ID of the agent requesting the lock
+   * @returns Release function — call when done writing
+   */
+  async acquire(filePath: string, agentId: string): Promise<() => void> {
+    // Wait for existing lock
+    while (this.locks.has(filePath)) {
+      await new Promise<void>((resolve) => {
+        const queue = this.queues.get(filePath) ?? [];
+        queue.push(resolve);
+        this.queues.set(filePath, queue);
+      });
+    }
+
+    // Create lock entry
+    let releaseFn: () => void;
+    const promise = new Promise<void>((resolve) => {
+      releaseFn = () => {
+        this.locks.delete(filePath);
+        resolve();
+        // Wake next waiter
+        const queue = this.queues.get(filePath);
+        if (queue && queue.length > 0) {
+          const next = queue.shift()!;
+          next();
+        }
+      };
+    });
+
+    const entry: FileLockEntry = {
+      agentId,
+      filePath,
+      promise,
+      release: releaseFn!,
+    };
+
+    this.locks.set(filePath, entry);
+    return releaseFn!;
+  }
+
+  /**
+   * Check if a file is currently locked.
+   */
+  isLocked(filePath: string): boolean {
+    return this.locks.has(filePath);
+  }
+
+  /**
+   * Get the agent that holds a lock on a file.
+   */
+  getHolder(filePath: string): string | undefined {
+    return this.locks.get(filePath)?.agentId;
+  }
+
+  /**
+   * Get count of locked files.
+   */
+  get lockCount(): number {
+    return this.locks.size;
+  }
+
+  /**
+   * Release all locks held by an agent (on abort).
+   */
+  releaseAll(agentId: string): void {
+    for (const [filePath, entry] of this.locks) {
+      if (entry.agentId === agentId) {
+        entry.release();
+      }
+    }
+  }
+
+  /**
+   * Clear all locks (on shutdown).
+   */
+  clear(): void {
+    for (const entry of this.locks.values()) {
+      entry.release();
+    }
+    this.locks.clear();
+    this.queues.clear();
+  }
+}