pi-open-agents 0.1.0

package/src/tui/tools.ts

@@ -0,0 +1,147 @@
+/**
+ * Programmatic tools for agent switching.
+ *
+ * Registers:
+ * - set_agent: LLM-callable tool to switch agents
+ * - search_agents: LLM-callable tool to search agents
+ *
+ * These tools can access all agents (including hidden ones),
+ * bypassing the TUI mode-based filtering.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { AgentDefinition } from "../types.ts";
+import { selectableAgents } from "../discovery/loader.ts";
+import type { AgentManager } from "../primary/manager.ts";
+import { updateBanner } from "./banner.ts";
+
+/**
+ * Register the set_agent and search_agents tools.
+ */
+export function registerAgentTools(manager: AgentManager, pi: ExtensionAPI): void {
+  // ─── set_agent tool ─────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "set_agent",
+    label: "Set Agent",
+    description:
+      "Switch to a different agent mode programmatically. Use this when the current task requires a different set of tools or specialized behavior.",
+    parameters: Type.Object({
+      agent: Type.String({ description: "Name of the agent to switch to" }),
+      reason: Type.Optional(Type.String({ description: "Reason for switching agents" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
+      const { agent: name, reason } = params;
+
+      const agent = manager.getAgent(name);
+      if (!agent) {
+        const available = manager.getAgents().map((a) => a.name).join(", ") || "(none defined)";
+        throw new Error(`Unknown agent "${name}". Available: ${available}`);
+      }
+
+      const success = await manager.apply(name, pi, ctx);
+      if (!success) {
+        throw new Error(`Failed to apply agent "${name}"`);
+      }
+
+      const msg = reason ? `Switched to agent "${name}". Reason: ${reason}` : `Switched to agent "${name}"`;
+      ctx.ui.notify(msg, "info");
+      updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+
+      return {
+        content: [{ type: "text", text: msg }],
+        details: { agent: name, reason },
+      };
+    },
+  });
+
+  // ─── search_agents tool ─────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "search_agents",
+    label: "Search Agents",
+    description:
+      "Search available agents by name, description, or body content. Returns ranked results with relevance scores and matching snippets.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query to match against agent name, description, or body content" }),
+      limit: Type.Optional(Type.Number({ description: "Maximum number of results to return (default: 5)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx: ExtensionContext) {
+      const { query, limit = 5 } = params;
+      const agents = manager.getAgents();
+      const results = rankAgents(agents, query).slice(0, limit);
+
+      if (results.length === 0) {
+        return {
+          content: [{ type: "text", text: `No agents found matching "${query}".` }],
+          details: { query, results: [] },
+        };
+      }
+
+      const lines = results.map((r, i) => {
+        const active = manager.isActive(r.name) ? " [ACTIVE]" : "";
+        let line = `${i + 1}. ${r.name}${active} (score: ${r.score})`;
+        if (r.agent.description) line += `\n   Description: ${r.agent.description}`;
+        if (r.agent.model) line += `\n   Model: ${r.agent.model}`;
+        if (r.snippets.length > 0) {
+          line += `\n   Matches: ${r.snippets.slice(0, 2).join(" | ")}`;
+        }
+        return line;
+      });
+
+      const text = `Found ${results.length} agent(s) matching "${query}":\n\n${lines.join("\n\n")}`;
+
+      return {
+        content: [{ type: "text", text }],
+        details: { query, totalResults: results.length, results },
+      };
+    },
+  });
+}
+
+// ─── Agent Ranking ───────────────────────────────────────────────────────────
+
+interface RankedAgent {
+  name: string;
+  agent: AgentDefinition;
+  score: number;
+  snippets: string[];
+}
+
+function rankAgents(agents: AgentDefinition[], query: string): RankedAgent[] {
+  const q = query.toLowerCase();
+  const results: RankedAgent[] = [];
+
+  for (const agent of agents) {
+    let score = 0;
+
+    if (agent.name.toLowerCase() === q) score += 100;
+    else if (agent.name.toLowerCase().includes(q)) score += 50;
+
+    if (agent.description?.toLowerCase().includes(q)) score += 30;
+    if (agent.model?.toLowerCase().includes(q)) score += 20;
+
+    const bodyLower = agent.prompt.toLowerCase();
+    const bodyMatches = (bodyLower.match(new RegExp(q, "g")) || []).length;
+    score += Math.min(bodyMatches * 5, 25);
+
+    if (score < 1) continue;
+
+    const snippets: string[] = [];
+    if (agent.description) {
+      const idx = agent.description.toLowerCase().indexOf(q);
+      if (idx !== -1) snippets.push(agent.description.slice(0, 80));
+    }
+    const bodyIdx = bodyLower.indexOf(q);
+    if (bodyIdx !== -1) {
+      const start = Math.max(0, bodyIdx - 20);
+      const end = Math.min(agent.prompt.length, bodyIdx + q.length + 20);
+      snippets.push(agent.prompt.slice(start, end).replace(/\n/g, " "));
+    }
+
+    results.push({ name: agent.name, agent, score, snippets });
+  }
+
+  return results.sort((a, b) => b.score - a.score);
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Core type definitions for pi-open-agents.
+ *
+ * AgentDefinition is the unified superset of OpenCode and pi agent formats.
+ * Every .md agent file — regardless of source path or frontmatter dialect —
+ * is parsed into this single type.
+ */
+
+// ─── Enums ───────────────────────────────────────────────────────────────────
+
+export type AgentMode = "primary" | "subagent" | "all";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export type SystemPromptMode = "append" | "replace" | "replace-all";
+
+export type PermissionAction = "allow" | "deny" | "ask";
+
+export type AgentSource = "global" | "project";
+
+export const THINKING_LEVELS: readonly ThinkingLevel[] = [
+  "off", "minimal", "low", "medium", "high", "xhigh",
+] as const;
+
+export const SYSTEM_PROMPT_MODES: readonly SystemPromptMode[] = [
+  "append", "replace", "replace-all",
+] as const;
+
+export const AGENT_MODES: readonly AgentMode[] = [
+  "primary", "subagent", "all",
+] as const;
+
+export const PERMISSION_ACTIONS: readonly PermissionAction[] = [
+  "allow", "deny", "ask",
+] as const;
+
+// ─── Permission ──────────────────────────────────────────────────────────────
+
+/**
+ * Permission config as written in frontmatter.
+ *
+ * Simple form (string per tool):
+ *   bash: allow
+ *
+ * Pattern form (nested object):
+ *   edit:
+ *     "*.env": deny
+ *     "*.md": allow
+ */
+export type PermissionConfig = Record<string, PermissionAction | Record<string, PermissionAction>>;
+
+/**
+ * Flattened permission rule after parsing.
+ * Evaluation is last-match-wins (like CSS specificity).
+ */
+export interface PermissionRule {
+  /** Tool or permission category, e.g. "bash", "edit", "read" */
+  permission: string;
+  /** Glob pattern for the argument, e.g. "*.env", "*" */
+  pattern: string;
+  /** Action to take */
+  action: PermissionAction;
+}
+
+// ─── Agent Definition ────────────────────────────────────────────────────────
+
+/**
+ * The unified agent definition — superset of OpenCode and pi formats.
+ *
+ * Fields are grouped by purpose. OpenCode-compatible fields are marked (OC),
+ * pi-specific extensions are marked (PI).
+ */
+export interface AgentDefinition {
+  // === Identity ===
+  name: string;
+  description?: string;
+  /** (OC) Controls visibility: primary = user-selectable, subagent = delegation only, all = both */
+  mode: AgentMode;
+  /** (OC) Hide from TUI selectors, keep programmatic access */
+  hidden: boolean;
+  /** (OC) UI accent color */
+  color?: string;
+  /** (OC) Remove agent entirely */
+  disable: boolean;
+
+  // === Model ===
+  /** "provider/model-id" */
+  model?: string;
+  /** (OC) Model variant name, e.g. "thinking" */
+  variant?: string;
+  /** (OC) Generation temperature */
+  temperature?: number;
+  /** (OC) Generation top_p */
+  topP?: number;
+
+  // === Execution Control ===
+  /** (PI) Reasoning effort level */
+  thinking: ThinkingLevel;
+  /** (OC) Max agentic iterations before forced text-only */
+  steps?: number;
+  /** (PI) How agent body interacts with system prompt */
+  systemPrompt: SystemPromptMode;
+
+  // === Tools & Permissions ===
+  /** (OC) Permission rules for tool usage */
+  permission?: PermissionConfig;
+  /** (PI) Simple tool whitelist (converted to permission if no permission block) */
+  tools?: string[];
+
+  // === Subagent Controls ===
+  /** (PI) Maximum recursion depth when spawning subagents */
+  maxDepth: number;
+  /** (PI) Which subagents this agent is allowed to spawn */
+  allowedAgents?: string[];
+  /** (PI) Per-agent skill loading with wildcard support */
+  skills?: string[];
+
+  // === Content & Metadata ===
+  /** Markdown body (content after frontmatter) */
+  prompt: string;
+  /** Discovery origin */
+  source: AgentSource;
+  /** Absolute path to the .md file */
+  filePath: string;
+}
+
+// ─── Loading Results ─────────────────────────────────────────────────────────
+
+export interface AgentLoadWarning {
+  filePath: string;
+  message: string;
+}
+
+export interface AgentLoadResult {
+  agents: AgentDefinition[];
+  warnings: AgentLoadWarning[];
+}
+
+// ─── Filesystem Abstraction (for testing) ────────────────────────────────────
+
+export interface AgentFs {
+  listFiles(dir: string): Promise<string[]>;
+  readFile(filePath: string): Promise<string>;
+  exists(dir: string): Promise<boolean>;
+}
+
+// ─── Model Reference ─────────────────────────────────────────────────────────
+
+export interface ModelRef {
+  provider: string;
+  modelId: string;
+}

package/src/utils/format.ts

@@ -0,0 +1,99 @@
+/**
+ * Format utilities for subagent TUI rendering and output.
+ *
+ * Extracted from tool-args.ts and subagent-render.ts (pi-subagents reference).
+ */
+
+import { homedir } from "node:os";
+
+/**
+ * Truncate text with ellipsis.
+ */
+export function preview(text: string, length: number): string {
+  return text.length > length ? `${text.slice(0, length)}...` : text;
+}
+
+/**
+ * Shorten a file path by replacing the home directory with ~.
+ */
+export function shortenPath(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const home = homedir();
+  return value.startsWith(`${home}/`) ? `~/${value.slice(home.length + 1)}` : value;
+}
+
+/**
+ * Type-safe string extraction from a record.
+ */
+export function stringArg(args: Record<string, unknown>, key: string): string | undefined {
+  const value = args[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Type-safe number extraction from a record.
+ */
+export function numberArg(args: Record<string, unknown>, key: string): number | undefined {
+  const value = args[key];
+  return typeof value === "number" ? value : undefined;
+}
+
+/**
+ * Escape XML special characters.
+ */
+export function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Format a token count compactly (e.g. 1500 → "1.5k", 2000000 → "2m").
+ */
+export function formatTokens(value: number): string {
+  if (Math.abs(value) >= 1_000_000) return `${Number((value / 1_000_000).toFixed(1))}m`;
+  if (Math.abs(value) >= 1_000) return `${Number((value / 1_000).toFixed(1))}k`;
+  return String(value);
+}
+
+/**
+ * Sanitize a string for use as a filename component.
+ */
+export function safeFilePart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_");
+}
+
+/**
+ * Get byte length of a UTF-8 string.
+ */
+export function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+/**
+ * Keep the tail of a string within a byte budget.
+ */
+export function keepTailByBytes(text: string, maxBytes: number): string {
+  let kept = text;
+  while (byteLength(kept) > maxBytes) kept = kept.slice(1);
+  return kept;
+}
+
+/**
+ * Truncate content from the head, keeping the tail.
+ * Returns undefined if no truncation needed.
+ */
+export function truncateHeadContent(
+  text: string,
+  maxBytes: number,
+  maxLines: number,
+): string | undefined {
+  const lines = text.split("\n");
+  if (byteLength(text) <= maxBytes && lines.length <= maxLines) return undefined;
+
+  const lineLimited = lines.length > maxLines ? lines.slice(-maxLines).join("\n") : text;
+  return keepTailByBytes(lineLimited, maxBytes);
+}