@c4ccz/zero 1.0.0 → 1.0.1

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;
+}

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

@@ -0,0 +1,139 @@
+/**
+ * ZERO Configuration System
+ * Handles loading, validating, and managing ZERO configuration
+ *
+ * Sources:
+ * - gemini-cli: config with extensions
+ * - crush: JSON config with schema
+ * - opencode: configuration management
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ZeroConfig } from "../types.js";
+
+const CONFIG_FILE_NAME = "zero.config.json";
+const ZERO_DIR = ".zero";
+
+export const DEFAULT_CONFIG: ZeroConfig = {
+  version: 1,
+  defaultProvider: "openai",
+  defaultModel: "gpt-4o",
+  providers: {
+    openai: {
+      type: "openai",
+      apiKey: process.env.OPENAI_API_KEY,
+    },
+    anthropic: {
+      type: "anthropic",
+      apiKey: process.env.ANTHROPIC_API_KEY,
+    },
+    google: {
+      type: "google",
+      apiKey: process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY,
+    },
+    ollama: {
+      type: "ollama",
+      baseUrl: "http://localhost:11434/v1",
+    },
+  },
+  permissions: {
+    fileRead: "allow",
+    fileWrite: "ask",
+    shellExecution: "ask",
+    networkAccess: "ask",
+    mcpAccess: "allow",
+  },
+};
+
+export class ConfigManager {
+  private config: ZeroConfig;
+  private configPath: string;
+  private projectPath: string;
+
+  constructor(projectPath: string) {
+    this.projectPath = projectPath;
+    this.configPath = path.join(projectPath, CONFIG_FILE_NAME);
+    this.config = { ...DEFAULT_CONFIG };
+  }
+
+  /**
+   * Load configuration from file
+   */
+  async load(): Promise<ZeroConfig> {
+    try {
+      const data = await fs.readFile(this.configPath, "utf-8");
+      const loaded = JSON.parse(data);
+      this.config = { ...DEFAULT_CONFIG, ...loaded };
+    } catch {
+      // Use defaults if config file doesn't exist
+      this.config = { ...DEFAULT_CONFIG };
+    }
+
+    // Also check for .zero/ directory config
+    try {
+      const zeroDirConfig = path.join(this.projectPath, ZERO_DIR, "config.json");
+      const data = await fs.readFile(zeroDirConfig, "utf-8");
+      const loaded = JSON.parse(data);
+      this.config = { ...this.config, ...loaded };
+    } catch {}
+
+    return this.config;
+  }
+
+  /**
+   * Save configuration to file
+   */
+  async save(): Promise<void> {
+    await fs.writeFile(this.configPath, JSON.stringify(this.config, null, 2));
+  }
+
+  /**
+   * Get current configuration
+   */
+  get(): ZeroConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Update configuration
+   */
+  update(partial: Partial<ZeroConfig>): ZeroConfig {
+    this.config = { ...this.config, ...partial };
+    return this.config;
+  }
+
+  /**
+   * Get the ZERO data directory path
+   */
+  getDataDir(): string {
+    return path.join(this.projectPath, ZERO_DIR);
+  }
+
+  /**
+   * Initialize ZERO project structure
+   */
+  async init(): Promise<void> {
+    const zeroDir = this.getDataDir();
+    await fs.mkdir(zeroDir, { recursive: true });
+    await fs.mkdir(path.join(zeroDir, "sessions"), { recursive: true });
+    await fs.mkdir(path.join(zeroDir, "memory"), { recursive: true });
+    await fs.mkdir(path.join(zeroDir, "logs"), { recursive: true });
+
+    // Create default config
+    await this.save();
+
+    // Create .gitignore for .zero directory
+    const gitignore = path.join(zeroDir, ".gitignore");
+    try {
+      await fs.writeFile(gitignore, "sessions/\nmemory/\nlogs/\n*.log\n");
+    } catch {}
+  }
+
+  /**
+   * Resolve environment variables in config
+   */
+  resolveEnv(value: string): string {
+    return value.replace(/\$\{(\w+)\}/g, (_, key) => process.env[key] || "");
+  }
+}

package/packages/core/src/confirmation/message-bus.ts

@@ -0,0 +1,206 @@
+/**
+ * ZERO Message Bus
+ * Adapted from: qwen-code (Alibaba) - MIT
+ *
+ * Event-driven message bus for tool confirmations and hook execution.
+ * Supports request-response patterns with correlation IDs.
+ */
+
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+
+export enum MessageBusType {
+  TOOL_CONFIRMATION_REQUEST = "tool-confirmation-request",
+  TOOL_CONFIRMATION_RESPONSE = "tool-confirmation-response",
+  TOOL_EXECUTION_SUCCESS = "tool-execution-success",
+  TOOL_EXECUTION_FAILURE = "tool-execution-failure",
+  HOOK_EXECUTION_REQUEST = "hook-execution-request",
+  HOOK_EXECUTION_RESPONSE = "hook-execution-response",
+}
+
+export interface ToolConfirmationRequest {
+  type: MessageBusType.TOOL_CONFIRMATION_REQUEST;
+  toolName: string;
+  toolArgs: Record<string, unknown>;
+  correlationId: string;
+  details?: SerializableConfirmationDetails;
+}
+
+export interface ToolConfirmationResponse {
+  type: MessageBusType.TOOL_CONFIRMATION_RESPONSE;
+  correlationId: string;
+  confirmed: boolean;
+  payload?: unknown;
+  requiresUserConfirmation?: boolean;
+}
+
+export type SerializableConfirmationDetails =
+  | {
+      type: "info";
+      title: string;
+      prompt: string;
+      urls?: string[];
+    }
+  | {
+      type: "edit";
+      title: string;
+      fileName: string;
+      filePath: string;
+      fileDiff: string;
+      originalContent: string | null;
+      newContent: string;
+    }
+  | {
+      type: "exec";
+      title: string;
+      command: string;
+      rootCommand: string;
+    }
+  | {
+      type: "mcp";
+      title: string;
+      serverName: string;
+      toolName: string;
+    };
+
+export interface ToolExecutionSuccess<T = unknown> {
+  type: MessageBusType.TOOL_EXECUTION_SUCCESS;
+  toolName: string;
+  result: T;
+}
+
+export interface ToolExecutionFailure {
+  type: MessageBusType.TOOL_EXECUTION_FAILURE;
+  toolName: string;
+  error: Error;
+}
+
+export interface HookExecutionRequest {
+  type: MessageBusType.HOOK_EXECUTION_REQUEST;
+  eventName: string;
+  input: Record<string, unknown>;
+  correlationId: string;
+  signal?: AbortSignal;
+}
+
+export interface HookExecutionResponse {
+  type: MessageBusType.HOOK_EXECUTION_RESPONSE;
+  correlationId: string;
+  success: boolean;
+  output?: Record<string, unknown>;
+  error?: Error;
+}
+
+export type Message =
+  | ToolConfirmationRequest
+  | ToolConfirmationResponse
+  | ToolExecutionSuccess
+  | ToolExecutionFailure
+  | HookExecutionRequest
+  | HookExecutionResponse;
+
+export class MessageBus extends EventEmitter {
+  private isValidMessage(message: Message): boolean {
+    if (!message || !message.type) {
+      return false;
+    }
+
+    if (
+      message.type === MessageBusType.TOOL_CONFIRMATION_REQUEST &&
+      !("correlationId" in message)
+    ) {
+      return false;
+    }
+
+    return true;
+  }
+
+  async publish(message: Message): Promise<void> {
+    try {
+      if (!this.isValidMessage(message)) {
+        throw new Error(`Invalid message structure: ${JSON.stringify(message)}`);
+      }
+
+      if (message.type === MessageBusType.TOOL_CONFIRMATION_REQUEST) {
+        // Auto-confirm by default
+        this.emit(MessageBusType.TOOL_CONFIRMATION_RESPONSE, {
+          type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+          correlationId: message.correlationId,
+          confirmed: true,
+        });
+      } else {
+        this.emit(message.type, message);
+      }
+    } catch (error) {
+      this.emit("error", error);
+    }
+  }
+
+  subscribe<T extends Message>(
+    type: T["type"],
+    listener: (message: T) => void
+  ): void {
+    this.on(type, listener);
+  }
+
+  unsubscribe<T extends Message>(
+    type: T["type"],
+    listener: (message: T) => void
+  ): void {
+    this.off(type, listener);
+  }
+
+  /**
+   * Request-response pattern: Publish a message and wait for a correlated response
+   */
+  async request<TRequest extends Message, TResponse extends Message>(
+    request: Omit<TRequest, "correlationId">,
+    responseType: TResponse["type"],
+    timeoutMs: number = 60000,
+    signal?: AbortSignal
+  ): Promise<TResponse> {
+    const correlationId = randomUUID();
+
+    return new Promise<TResponse>((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new Error("Request aborted"));
+        return;
+      }
+
+      const timeoutId = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Request timed out waiting for ${responseType}`));
+      }, timeoutMs);
+
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        this.unsubscribe(responseType, responseHandler);
+        if (signal) {
+          signal.removeEventListener("abort", abortHandler);
+        }
+      };
+
+      const abortHandler = () => {
+        cleanup();
+        reject(new Error("Request aborted"));
+      };
+
+      if (signal) {
+        signal.addEventListener("abort", abortHandler, { once: true });
+      }
+
+      const responseHandler = (response: TResponse) => {
+        if (
+          "correlationId" in response &&
+          response.correlationId === correlationId
+        ) {
+          cleanup();
+          resolve(response);
+        }
+      };
+
+      this.subscribe<TResponse>(responseType, responseHandler);
+      this.publish({ ...request, correlationId } as TRequest);
+    });
+  }
+}