zero-ai-cli 1.0.0

package/packages/core/src/agent/engine.ts

@@ -0,0 +1,266 @@
+/**
+ * ZERO Agent Engine
+ * Core agent loop implementation combining best patterns from:
+ * - goose: sub-agent orchestration
+ * - gemini-cli: ReAct loop with tool execution
+ * - pi: multi-agent orchestrator
+ * - cline: tool approval flow
+ */
+
+import type {
+  AgentConfig,
+  AgentResult,
+  ChatOptions,
+  LLMClient,
+  Message,
+  MessageContent,
+  ToolCallContent,
+  ToolDefinition,
+  ToolResult,
+  TokenUsage,
+  PermissionHandler,
+  SessionState,
+} from "../types.js";
+
+export interface AgentEngineOptions {
+  config: AgentConfig;
+  client: LLMClient;
+  tools: Map<string, ToolDefinition>;
+  permissionHandler: PermissionHandler;
+  workingDirectory: string;
+  sessionId: string;
+  onStateChange?: (state: SessionState) => void;
+  onMessage?: (message: Message) => void;
+}
+
+export class AgentEngine {
+  private config: AgentConfig;
+  private client: LLMClient;
+  private tools: Map<string, ToolDefinition>;
+  private permissionHandler: PermissionHandler;
+  private workingDirectory: string;
+  private sessionId: string;
+  private messages: Message[] = [];
+  private totalUsage: TokenUsage = { inputTokens: 0, outputTokens: 0 };
+  private turnCount = 0;
+  private aborted = false;
+  private abortController = new AbortController();
+  private onStateChange?: (state: SessionState) => void;
+  private onMessage?: (message: Message) => void;
+
+  constructor(options: AgentEngineOptions) {
+    this.config = options.config;
+    this.client = options.client;
+    this.tools = options.tools;
+    this.permissionHandler = options.permissionHandler;
+    this.workingDirectory = options.workingDirectory;
+    this.sessionId = options.sessionId;
+    this.onStateChange = options.onStateChange;
+    this.onMessage = options.onMessage;
+  }
+
+  /**
+   * Run the agent loop with a user message
+   */
+  async run(userMessage: string): Promise<AgentResult> {
+    const startTime = Date.now();
+    this.aborted = false;
+    this.turnCount = 0;
+
+    // Add user message
+    const userMsg: Message = {
+      id: this.generateId(),
+      role: "user",
+      content: [{ type: "text", text: userMessage }],
+      timestamp: Date.now(),
+    };
+    this.messages.push(userMsg);
+    this.onMessage?.(userMsg);
+
+    try {
+      // Agent loop (ReAct pattern)
+      while (this.turnCount < this.config.maxTurns && !this.aborted) {
+        this.turnCount++;
+        this.updateState({ status: "running", currentAgent: this.config.name, tokenUsage: this.totalUsage });
+
+        // Get available tools for this agent
+        const availableTools = this.getAvailableTools();
+
+        // Call LLM
+        const chatOptions: ChatOptions = {
+          tools: availableTools.length > 0 ? availableTools : undefined,
+          systemPrompt: this.config.systemPrompt,
+        };
+
+        const response = await this.client.chat(this.messages, chatOptions);
+
+        // Track usage
+        this.totalUsage.inputTokens += response.usage.inputTokens;
+        this.totalUsage.outputTokens += response.usage.outputTokens;
+
+        // Add assistant message
+        const assistantMsg: Message = {
+          id: this.generateId(),
+          role: "assistant",
+          content: response.content,
+          timestamp: Date.now(),
+          metadata: { model: response.model, usage: response.usage },
+        };
+        this.messages.push(assistantMsg);
+        this.onMessage?.(assistantMsg);
+
+        // Check if we should stop
+        if (response.stopReason === "end_turn" || response.stopReason === "max_tokens") {
+          break;
+        }
+
+        // Process tool calls
+        if (response.stopReason === "tool_use") {
+          const toolCalls = response.content.filter(
+            (c): c is ToolCallContent => c.type === "tool_call"
+          );
+
+          for (const toolCall of toolCalls) {
+            const result = await this.executeTool(toolCall);
+            const toolResultMsg: Message = {
+              id: this.generateId(),
+              role: "tool",
+              content: [{
+                type: "tool_result",
+                id: toolCall.id,
+                name: toolCall.name,
+                result: result.output,
+                error: result.error,
+              }],
+              timestamp: Date.now(),
+            };
+            this.messages.push(toolResultMsg);
+            this.onMessage?.(toolResultMsg);
+          }
+        }
+      }
+
+      const duration = Date.now() - startTime;
+      const result: AgentResult = {
+        success: !this.aborted,
+        messages: this.messages,
+        tokenUsage: this.totalUsage,
+        duration,
+      };
+
+      this.updateState({ status: "completed", tokenUsage: this.totalUsage });
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.updateState({ status: "error", tokenUsage: this.totalUsage, error: errorMessage });
+      return {
+        success: false,
+        messages: this.messages,
+        tokenUsage: this.totalUsage,
+        duration,
+        error: errorMessage,
+      };
+    }
+  }
+
+  /**
+   * Execute a single tool call with permission checking
+   */
+  private async executeTool(toolCall: ToolCallContent): Promise<ToolResult> {
+    const tool = this.tools.get(toolCall.name);
+
+    if (!tool) {
+      return {
+        success: false,
+        output: "",
+        error: `Tool "${toolCall.name}" not found`,
+      };
+    }
+
+    // Check permissions if tool requires approval
+    if (tool.requiresApproval) {
+      this.updateState({ status: "waiting_approval", tokenUsage: this.totalUsage });
+
+      const decision = await this.permissionHandler({
+        type: this.getPermissionType(tool.category),
+        resource: toolCall.name,
+        details: JSON.stringify(toolCall.arguments),
+      });
+
+      if (decision === "deny") {
+        return {
+          success: false,
+          output: "",
+          error: "Permission denied by user",
+        };
+      }
+
+      this.updateState({ status: "running", tokenUsage: this.totalUsage });
+    }
+
+    // Execute the tool
+    try {
+      const result = await tool.handler(toolCall.arguments, {
+        sessionId: this.sessionId,
+        workingDirectory: this.workingDirectory,
+        permissions: {
+          fileRead: "allow",
+          fileWrite: tool.requiresApproval ? "allow" : "ask",
+          shellExecution: tool.requiresApproval ? "allow" : "ask",
+          networkAccess: "allow",
+          mcpAccess: "allow",
+        },
+        abortSignal: this.abortController.signal,
+      });
+      return result;
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Get tools available to this agent
+   */
+  private getAvailableTools(): ToolDefinition[] {
+    return this.config.tools
+      .map((name) => this.tools.get(name))
+      .filter((t): t is ToolDefinition => t !== undefined);
+  }
+
+  private getPermissionType(category: string): "file_read" | "file_write" | "shell" | "network" | "mcp" {
+    switch (category) {
+      case "file": return "file_write";
+      case "shell": return "shell";
+      case "web": return "network";
+      case "mcp": return "mcp";
+      default: return "file_read";
+    }
+  }
+
+  abort(): void {
+    this.aborted = true;
+    this.abortController.abort();
+  }
+
+  getMessages(): Message[] {
+    return [...this.messages];
+  }
+
+  private updateState(partial: Partial<SessionState>): void {
+    this.onStateChange?.({
+      status: partial.status ?? "idle",
+      currentAgent: partial.currentAgent ?? this.config.name,
+      tokenUsage: partial.tokenUsage ?? this.totalUsage,
+      error: partial.error,
+    });
+  }
+
+  private generateId(): string {
+    return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+  }
+}

package/packages/core/src/agent/registry-tools.ts

@@ -0,0 +1,58 @@
+/**
+ * ZERO Tool Registry
+ * Manages all available tools for agents
+ */
+
+import type { ToolDefinition, ToolCategory } from "../types.js";
+
+export class ToolRegistry {
+  private tools = new Map<string, ToolDefinition>();
+
+  register(tool: ToolDefinition): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  unregister(name: string): void {
+    this.tools.delete(name);
+  }
+
+  get(name: string): ToolDefinition | undefined {
+    return this.tools.get(name);
+  }
+
+  getAll(): ToolDefinition[] {
+    return Array.from(this.tools.values());
+  }
+
+  getByCategory(category: ToolCategory): ToolDefinition[] {
+    return this.getAll().filter((t) => t.category === category);
+  }
+
+  getMap(): Map<string, ToolDefinition> {
+    return new Map(this.tools);
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  names(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * Load all built-in tools
+   */
+  loadBuiltins(): void {
+    const builtins = getBuiltinTools();
+    for (const tool of builtins) {
+      this.register(tool);
+    }
+  }
+}
+
+// Lazy import to avoid circular deps - tools are loaded at runtime
+function getBuiltinTools(): ToolDefinition[] {
+  // Will be populated by the tools/index.ts
+  return [];
+}

package/packages/core/src/agent/registry.ts

@@ -0,0 +1,213 @@
+/**
+ * ZERO Agent Registry
+ * Manages multiple agents with orchestration capabilities
+ * Inspired by: goose (sub-agents), pi (orchestrator), gemini-cli (a2a)
+ */
+
+import type { AgentConfig, AgentResult, LLMClient, PermissionHandler, ToolDefinition } from "../types.js";
+import { AgentEngine } from "./engine.js";
+
+export interface AgentRegistryOptions {
+  clientFactory: (model: string) => LLMClient;
+  tools: Map<string, ToolDefinition>;
+  permissionHandler: PermissionHandler;
+  workingDirectory: string;
+  sessionId: string;
+}
+
+export class AgentRegistry {
+  private agents = new Map<string, AgentConfig>();
+  private clientFactory: (model: string) => LLMClient;
+  private tools: Map<string, ToolDefinition>;
+  private permissionHandler: PermissionHandler;
+  private workingDirectory: string;
+  private sessionId: string;
+
+  constructor(options: AgentRegistryOptions) {
+    this.clientFactory = options.clientFactory;
+    this.tools = options.tools;
+    this.permissionHandler = options.permissionHandler;
+    this.workingDirectory = options.workingDirectory;
+    this.sessionId = options.sessionId;
+  }
+
+  register(config: AgentConfig): void {
+    this.agents.set(config.id, config);
+  }
+
+  unregister(id: string): void {
+    this.agents.delete(id);
+  }
+
+  get(id: string): AgentConfig | undefined {
+    return this.agents.get(id);
+  }
+
+  list(): AgentConfig[] {
+    return Array.from(this.agents.values());
+  }
+
+  /**
+   * Create an engine for a specific agent
+   */
+  createEngine(agentId: string, options?: {
+    onStateChange?: AgentEngine extends { onStateChange: infer T } ? T : never;
+    onMessage?: AgentEngine extends { onMessage: infer T } ? T : never;
+  }): AgentEngine {
+    const config = this.agents.get(agentId);
+    if (!config) {
+      throw new Error(`Agent "${agentId}" not found in registry`);
+    }
+
+    const client = this.clientFactory(config.model);
+
+    return new AgentEngine({
+      config,
+      client,
+      tools: this.tools,
+      permissionHandler: this.permissionHandler,
+      workingDirectory: this.workingDirectory,
+      sessionId: this.sessionId,
+    });
+  }
+
+  /**
+   * Orchestrate a task across multiple agents
+   * The orchestrator agent delegates to sub-agents as needed
+   */
+  async orchestrate(orchestratorId: string, task: string): Promise<AgentResult> {
+    const orchestrator = this.agents.get(orchestratorId);
+    if (!orchestrator) {
+      throw new Error(`Orchestrator agent "${orchestratorId}" not found`);
+    }
+
+    // Create delegation tools for sub-agents
+    const delegateTools = new Map(this.tools);
+
+    // Add a "delegate" tool that lets the orchestrator call sub-agents
+    if (orchestrator.subAgents && orchestrator.subAgents.length > 0) {
+      const delegateTool: ToolDefinition = {
+        name: "delegate_to_agent",
+        description: `Delegate a sub-task to another agent. Available agents: ${orchestrator.subAgents.join(", ")}`,
+        parameters: {
+          agentId: {
+            type: "string",
+            description: "ID of the agent to delegate to",
+            required: true,
+            enum: orchestrator.subAgents,
+          },
+          task: {
+            type: "string",
+            description: "The task to delegate",
+            required: true,
+          },
+        },
+        category: "system",
+        requiresApproval: false,
+        handler: async (args) => {
+          const subAgentId = args.agentId as string;
+          const subTask = args.task as string;
+          const subConfig = this.agents.get(subAgentId);
+
+          if (!subConfig) {
+            return { success: false, output: "", error: `Agent "${subAgentId}" not found` };
+          }
+
+          const subEngine = this.createEngine(subAgentId);
+          const result = await subEngine.run(subTask);
+
+          return {
+            success: result.success,
+            output: result.messages
+              .filter((m) => m.role === "assistant")
+              .map((m) => m.content.filter((c) => c.type === "text").map((c) => "text" in c ? c.text : "").join(""))
+              .join("\n"),
+            data: {
+              tokenUsage: result.tokenUsage,
+              duration: result.duration,
+            },
+          };
+        },
+      };
+
+      delegateTools.set("delegate_to_agent", delegateTool);
+    }
+
+    const engine = new AgentEngine({
+      config: orchestrator,
+      client: this.clientFactory(orchestrator.model),
+      tools: delegateTools,
+      permissionHandler: this.permissionHandler,
+      workingDirectory: this.workingDirectory,
+      sessionId: this.sessionId,
+    });
+
+    return engine.run(task);
+  }
+}
+
+// ============================================================================
+// Built-in Agent Configurations
+// ============================================================================
+
+export const DEFAULT_AGENTS: AgentConfig[] = [
+  {
+    id: "coder",
+    name: "Coder",
+    description: "Primary coding agent that handles file editing, code generation, and refactoring",
+    systemPrompt: `You are ZERO, an expert AI coding assistant. You help users with software development tasks.
+
+Your capabilities:
+- Read, write, and edit files
+- Execute shell commands
+- Search codebases
+- Use git for version control
+- Delegate to specialized sub-agents when needed
+
+Guidelines:
+- Always read relevant files before making changes
+- Write clean, well-documented code
+- Follow the existing code style and patterns
+- Test your changes when possible
+- Explain your reasoning when asked`,
+    tools: [
+      "read_file", "write_file", "edit_file", "list_directory",
+      "search_files", "search_code", "execute_shell",
+      "git_status", "git_diff", "git_commit",
+    ],
+    maxTurns: 50,
+    model: "default",
+    subAgents: ["reviewer", "researcher"],
+  },
+  {
+    id: "reviewer",
+    name: "Code Reviewer",
+    description: "Specialized agent for code review and quality analysis",
+    systemPrompt: `You are ZERO's code review specialist. You analyze code for:
+- Bugs and potential issues
+- Security vulnerabilities
+- Performance problems
+- Code style and best practices
+- Test coverage gaps
+
+Provide clear, actionable feedback with specific line references.`,
+    tools: ["read_file", "search_code", "search_files", "list_directory", "git_diff"],
+    maxTurns: 20,
+    model: "default",
+  },
+  {
+    id: "researcher",
+    name: "Researcher",
+    description: "Agent specialized in searching documentation and web resources",
+    systemPrompt: `You are ZERO's research specialist. You help find:
+- Documentation for libraries and frameworks
+- Solutions to error messages
+- Best practices and design patterns
+- API references and examples
+
+Always provide sources and links when available.`,
+    tools: ["search_files", "search_code", "read_file", "web_search", "web_fetch"],
+    maxTurns: 15,
+    model: "default",
+  },
+];

package/packages/core/src/commands/index.ts

@@ -0,0 +1,116 @@
+/**
+ * ZERO Custom Commands System
+ * Adapted from: crush (Charm/Go) - MIT
+ *
+ * Loads custom commands from markdown files with YAML frontmatter.
+ * Supports user, project, and MCP-sourced commands.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { parseFrontmatter } from "../agent/config-loader.js";
+
+export interface CommandArgument {
+  id: string;
+  title: string;
+  description: string;
+  required: boolean;
+}
+
+export interface CustomCommand {
+  id: string;
+  name: string;
+  description: string;
+  content: string;
+  arguments: CommandArgument[];
+  source: "user" | "project" | "mcp";
+}
+
+/**
+ * Load custom commands from a directory of markdown files
+ */
+export async function loadCommandsFromDir(dirPath: string, source: "user" | "project" = "project"): Promise<CustomCommand[]> {
+  const commands: CustomCommand[] = [];
+
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+
+      try {
+        const filePath = path.join(dirPath, entry.name);
+        const content = await fs.readFile(filePath, "utf-8");
+        const { frontmatter, body } = parseFrontmatter(content);
+
+        const name = (frontmatter.name as string) || path.basename(entry.name, ".md");
+        const description = (frontmatter.description as string) || "";
+
+        // Parse arguments from frontmatter
+        const args: CommandArgument[] = [];
+        const rawArgs = frontmatter.arguments as any;
+        if (Array.isArray(rawArgs)) {
+          for (const arg of rawArgs) {
+            args.push({
+              id: arg.id || arg.name,
+              title: arg.title || arg.id || arg.name,
+              description: arg.description || "",
+              required: arg.required !== false,
+            });
+          }
+        }
+
+        commands.push({
+          id: `${source}:${name}`,
+          name,
+          description,
+          content: body.trim(),
+          arguments: args,
+          source,
+        });
+      } catch {}
+    }
+  } catch {}
+
+  return commands;
+}
+
+/**
+ * Load all commands from standard locations
+ */
+export async function loadAllCommands(workingDir: string): Promise<CustomCommand[]> {
+  const commands: CustomCommand[] = [];
+
+  // Project commands: .zero/commands/
+  const projectCmds = await loadCommandsFromDir(
+    path.join(workingDir, ".zero", "commands"),
+    "project"
+  );
+  commands.push(...projectCmds);
+
+  // User commands: ~/.config/zero/commands/
+  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+  if (homeDir) {
+    const userCmds = await loadCommandsFromDir(
+      path.join(homeDir, ".config", "zero", "commands"),
+      "user"
+    );
+    commands.push(...userCmds);
+  }
+
+  return commands;
+}
+
+/**
+ * Execute a custom command by substituting arguments
+ */
+export function executeCommand(command: CustomCommand, args: Record<string, string>): string {
+  let content = command.content;
+
+  // Replace $ARG_NAME patterns with values
+  for (const [key, value] of Object.entries(args)) {
+    content = content.replace(new RegExp(`\\$${key.toUpperCase()}`, "g"), value);
+  }
+
+  return content;
+}