byterover-cli 0.4.0 → 1.0.0

package/dist/core/domain/cipher/agent/agent-info.js

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+/**
+ * Permission values for agent operations.
+ * - allow: Operation is permitted without asking
+ * - deny: Operation is blocked
+ * - ask: User must approve the operation
+ */
+export const PermissionValue = z.enum(['allow', 'deny', 'ask']);
+/**
+ * Agent mode determines how the agent can be used.
+ * - primary: Entry point agent (e.g., plan, cipher)
+ * - subagent: Can only be invoked by primary agents via TaskTool
+ * - all: Can be used as both primary and subagent
+ */
+export const AgentMode = z.enum(['primary', 'subagent', 'all']);
+/**
+ * Permission configuration for an agent.
+ * Controls what operations the agent is allowed to perform.
+ */
+export const AgentPermissionSchema = z.object({
+    /**
+     * Permission map for bash commands.
+     * Keys are command patterns (supports wildcards like 'git*', 'ls*').
+     * Value '*' applies to all commands not matched by other patterns.
+     * @default { '*': 'allow' }
+     */
+    bash: z.record(z.string(), PermissionValue).default({ '*': 'allow' }),
+    /**
+     * Permission for file editing operations (edit_file, write_file).
+     * @default 'allow'
+     */
+    edit: PermissionValue.default('allow'),
+});
+/**
+ * Agent information schema.
+ * Defines the configuration for a Cipher agent (modeled after OpenCode's Agent.Info).
+ */
+export const AgentInfoSchema = z.object({
+    /**
+     * Optional color for UI display (hex code like #RRGGBB).
+     */
+    color: z.string().optional(),
+    /**
+     * Human-readable description of when to use this agent.
+     * Displayed to LLM when selecting subagents via TaskTool.
+     */
+    description: z.string().optional(),
+    /**
+     * Whether this agent is hidden from user selection.
+     * Hidden agents can still be invoked programmatically.
+     * @default false
+     */
+    hidden: z.boolean().default(false),
+    /**
+     * Maximum number of LLM iterations for this agent.
+     * Overrides the default maxIterations from config.
+     */
+    maxIterations: z.number().int().positive().optional(),
+    /**
+     * Agent mode: primary, subagent, or all.
+     * - primary: Direct entry point for users
+     * - subagent: Invoked via TaskTool from primary agents
+     * - all: Can be used in both contexts
+     */
+    mode: AgentMode,
+    /**
+     * Optional model override for this agent.
+     * If not specified, uses the default model from agent config.
+     */
+    model: z
+        .object({
+        modelId: z.string(),
+        providerId: z.string().optional(),
+    })
+        .optional(),
+    /**
+     * Unique identifier for the agent.
+     * Used to reference the agent in TaskTool and registry.
+     */
+    name: z.string().min(1),
+    /**
+     * Whether this is a native (built-in) agent.
+     * Native agents are defined in code, not config files.
+     * @default true
+     */
+    native: z.boolean().default(true),
+    /**
+     * Permission configuration for this agent.
+     * Controls file editing and bash command access.
+     */
+    permission: AgentPermissionSchema.default({
+        bash: { '*': 'allow' },
+        edit: 'allow',
+    }),
+    /**
+     * Inline system prompt for this agent.
+     * Used when promptFile is not specified.
+     */
+    prompt: z.string().optional(),
+    /**
+     * Reference to a YAML prompt file in src/resources/prompts/.
+     * The file content will be used as the agent's system prompt.
+     * Takes precedence over inline `prompt` if both are specified.
+     */
+    promptFile: z.string().optional(),
+    /**
+     * LLM temperature for this agent.
+     * Controls randomness/creativity of responses.
+     */
+    temperature: z.number().min(0).max(2).optional(),
+    /**
+     * Tool enable/disable configuration.
+     * Keys are tool names, values are boolean (true = enabled, false = disabled).
+     * Supports wildcard '*' for all tools.
+     * Tools not listed inherit from parent/default configuration.
+     */
+    tools: z.record(z.string(), z.boolean()).default({}),
+});
+/**
+ * Default permission configuration for agents.
+ */
+export const DEFAULT_AGENT_PERMISSION = {
+    bash: { '*': 'allow' },
+    edit: 'allow',
+};
+/**
+ * Read-only permission configuration (for planning agents).
+ */
+export const READONLY_AGENT_PERMISSION = {
+    bash: {
+        '*': 'ask',
+        'cat*': 'allow',
+        'find*': 'allow',
+        'git*': 'allow',
+        'grep*': 'allow',
+        'head*': 'allow',
+        'ls*': 'allow',
+        'pwd*': 'allow',
+        'tail*': 'allow',
+        'tree*': 'allow',
+    },
+    edit: 'deny',
+};

package/dist/core/domain/cipher/agent/agent-registry.d.ts

@@ -0,0 +1,96 @@
+import { AgentInfo } from './agent-info.js';
+/**
+ * Built-in agent names.
+ * These constants ensure type safety and prevent typos.
+ */
+export declare const AgentName: {
+    /** Default primary agent with full capabilities */
+    readonly CIPHER: "cipher";
+    /** Subagent for creating/updating knowledge topics */
+    readonly CURATE: "curate";
+    /** Subagent for context tree explore and knowledge discovery */
+    readonly EXPLORE: "explore";
+    /** Primary agent for orchestrating curation workflow */
+    readonly PLAN: "plan";
+};
+export type KnownAgent = (typeof AgentName)[keyof typeof AgentName];
+/**
+ * AgentRegistry - Singleton registry for managing agent definitions.
+ *
+ * Provides methods to:
+ * - Get agent by name
+ * - List all agents
+ * - List agents by mode (primary, subagent)
+ * - Register custom agents
+ */
+export declare class AgentRegistry {
+    private static instance;
+    private agents;
+    private constructor();
+    /**
+     * Get the singleton instance of AgentRegistry.
+     */
+    static getInstance(): AgentRegistry;
+    /**
+     * Reset the singleton instance (for testing).
+     */
+    static reset(): void;
+    /**
+     * Get an agent by name.
+     * @param name - Agent name
+     * @returns Agent info or undefined if not found
+     */
+    get(name: string): AgentInfo | undefined;
+    /**
+     * Get agent names as a formatted list for display.
+     * @returns Formatted string of agent names and descriptions
+     */
+    getSubagentDescriptions(): string;
+    /**
+     * Check if an agent exists.
+     * @param name - Agent name
+     * @returns true if agent exists
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered agents.
+     * @returns Array of agent info objects
+     */
+    list(): AgentInfo[];
+    /**
+     * List agents by mode.
+     * @param mode - Agent mode to filter by
+     * @returns Array of agents matching the mode
+     */
+    listByMode(mode: 'all' | 'primary' | 'subagent'): AgentInfo[];
+    /**
+     * List primary agents available for direct user interaction.
+     * Returns agents that can be used as entry points (mode: 'primary' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of primary agent info objects
+     */
+    listPrimaryAgents(): AgentInfo[];
+    /**
+     * List subagents available for TaskTool.
+     * Returns agents that can be invoked as subagents (mode: 'subagent' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of subagent info objects
+     */
+    listSubagents(): AgentInfo[];
+    /**
+     * Register a custom agent.
+     * @param agent - Agent info to register
+     * @throws Error if agent with same name already exists (unless overwrite is true)
+     */
+    register(agent: AgentInfo, overwrite?: boolean): void;
+    /**
+     * Unregister an agent.
+     * @param name - Agent name to remove
+     * @returns true if agent was removed, false if not found
+     */
+    unregister(name: string): boolean;
+}
+/**
+ * Convenience function to get the AgentRegistry instance.
+ */
+export declare function getAgentRegistry(): AgentRegistry;

package/dist/core/domain/cipher/agent/agent-registry.js

@@ -0,0 +1,254 @@
+import { ToolName } from '../tools/constants.js';
+import { AgentInfoSchema, DEFAULT_AGENT_PERMISSION, READONLY_AGENT_PERMISSION, } from './agent-info.js';
+/**
+ * Built-in agent names.
+ * These constants ensure type safety and prevent typos.
+ */
+export const AgentName = {
+    /** Default primary agent with full capabilities */
+    CIPHER: 'cipher',
+    /** Subagent for creating/updating knowledge topics */
+    CURATE: 'curate',
+    /** Subagent for context tree explore and knowledge discovery */
+    EXPLORE: 'explore',
+    /** Primary agent for orchestrating curation workflow */
+    PLAN: 'plan',
+};
+/**
+ * Tools available to the Query subagent.
+ * Read-only tools for context tree exploration.
+ */
+const EXPLORE_AGENT_TOOLS = {
+    [ToolName.BASH_EXEC]: false,
+    [ToolName.CREATE_KNOWLEDGE_TOPIC]: false,
+    [ToolName.CURATE]: false,
+    [ToolName.EDIT_FILE]: false,
+    [ToolName.GLOB_FILES]: true,
+    [ToolName.GREP_CONTENT]: true,
+    [ToolName.LIST_DIRECTORY]: true,
+    [ToolName.READ_FILE]: true,
+    [ToolName.WRITE_FILE]: false,
+};
+/**
+ * Tools available to the Curate subagent.
+ * Context building and modification tools.
+ */
+const CURATE_AGENT_TOOLS = {
+    [ToolName.BASH_EXEC]: false,
+    [ToolName.CURATE]: true,
+    [ToolName.EDIT_FILE]: false,
+    [ToolName.GLOB_FILES]: true,
+    [ToolName.GREP_CONTENT]: true,
+    [ToolName.LIST_DIRECTORY]: true,
+    [ToolName.READ_FILE]: true,
+    [ToolName.SPEC_ANALYZE]: true,
+    [ToolName.WRITE_FILE]: false,
+};
+/**
+ * Tools available to the Plan agent.
+ * Read-only tools plus TaskTool for delegation.
+ */
+const PLAN_AGENT_TOOLS = {
+    // TaskTool for subagent delegation (will be added when registered)
+    task: true,
+    [ToolName.BASH_EXEC]: false,
+    [ToolName.CREATE_KNOWLEDGE_TOPIC]: false,
+    [ToolName.CURATE]: false,
+    [ToolName.EDIT_FILE]: false,
+    [ToolName.GLOB_FILES]: true,
+    [ToolName.GREP_CONTENT]: true,
+    [ToolName.LIST_DIRECTORY]: true,
+    [ToolName.READ_FILE]: true,
+    [ToolName.WRITE_FILE]: false,
+};
+/**
+ * Built-in agent definitions.
+ * These are the native agents available in the system.
+ */
+const BUILT_IN_AGENTS = {
+    /**
+     * Cipher Agent - Default primary agent with full capabilities.
+     * Used for general-purpose tasks.
+     */
+    [AgentName.CIPHER]: AgentInfoSchema.parse({
+        description: 'Default agent with full capabilities for general-purpose tasks.',
+        hidden: false,
+        mode: 'primary',
+        name: AgentName.CIPHER,
+        native: true,
+        permission: DEFAULT_AGENT_PERMISSION,
+        promptFile: 'system-prompt.yml',
+        tools: {}, // All tools enabled by default
+    }),
+    /**
+     * Curate Agent - Subagent for creating/updating knowledge topics.
+     * Handles the actual context tree modification.
+     */
+    [AgentName.CURATE]: AgentInfoSchema.parse({
+        description: 'Agent for creating and updating knowledge topics in the context tree. Use this to curate context after gathering information.',
+        hidden: false,
+        mode: 'subagent',
+        name: AgentName.CURATE,
+        native: true,
+        permission: {
+            bash: { '*': 'deny' },
+            edit: 'deny', // Only uses curate tool, not general file editing
+        },
+        promptFile: 'curate.yml',
+        tools: CURATE_AGENT_TOOLS,
+    }),
+    /**
+     * Query Agent - Subagent for context tree retrieval.
+     * Specialized for searching and retrieving information from the context tree.
+     */
+    [AgentName.EXPLORE]: AgentInfoSchema.parse({
+        description: 'Specialized agent for context tree retrieval and knowledge discovery. Use this to search and retrieve relevant information from the context tree.',
+        hidden: false,
+        mode: 'subagent',
+        name: AgentName.EXPLORE,
+        native: true,
+        permission: {
+            bash: { '*': 'deny' },
+            edit: 'deny',
+        },
+        promptFile: 'explore.yml',
+        tools: EXPLORE_AGENT_TOOLS,
+    }),
+    /**
+     * Plan Agent - Primary agent for orchestrating curation workflow.
+     * Uses TaskTool to delegate to Query and Curate subagents.
+     */
+    [AgentName.PLAN]: AgentInfoSchema.parse({
+        description: 'Planning agent that orchestrates context exploration and curation. Analyzes requests and delegates to explore and curate subagents.',
+        hidden: false,
+        mode: 'primary',
+        name: AgentName.PLAN,
+        native: true,
+        permission: READONLY_AGENT_PERMISSION,
+        promptFile: 'plan.yml',
+        tools: PLAN_AGENT_TOOLS,
+    }),
+};
+/**
+ * AgentRegistry - Singleton registry for managing agent definitions.
+ *
+ * Provides methods to:
+ * - Get agent by name
+ * - List all agents
+ * - List agents by mode (primary, subagent)
+ * - Register custom agents
+ */
+export class AgentRegistry {
+    static instance = null;
+    agents;
+    constructor() {
+        this.agents = new Map();
+        // Register built-in agents
+        for (const [name, agent] of Object.entries(BUILT_IN_AGENTS)) {
+            this.agents.set(name, agent);
+        }
+    }
+    /**
+     * Get the singleton instance of AgentRegistry.
+     */
+    static getInstance() {
+        if (!AgentRegistry.instance) {
+            AgentRegistry.instance = new AgentRegistry();
+        }
+        return AgentRegistry.instance;
+    }
+    /**
+     * Reset the singleton instance (for testing).
+     */
+    static reset() {
+        AgentRegistry.instance = null;
+    }
+    /**
+     * Get an agent by name.
+     * @param name - Agent name
+     * @returns Agent info or undefined if not found
+     */
+    get(name) {
+        return this.agents.get(name);
+    }
+    /**
+     * Get agent names as a formatted list for display.
+     * @returns Formatted string of agent names and descriptions
+     */
+    getSubagentDescriptions() {
+        return this.listSubagents()
+            .map((agent) => `- ${agent.name}: ${agent.description || 'No description'}`)
+            .join('\n');
+    }
+    /**
+     * Check if an agent exists.
+     * @param name - Agent name
+     * @returns true if agent exists
+     */
+    has(name) {
+        return this.agents.has(name);
+    }
+    /**
+     * List all registered agents.
+     * @returns Array of agent info objects
+     */
+    list() {
+        return [...this.agents.values()];
+    }
+    /**
+     * List agents by mode.
+     * @param mode - Agent mode to filter by
+     * @returns Array of agents matching the mode
+     */
+    listByMode(mode) {
+        return this.list().filter((agent) => {
+            if (mode === 'all')
+                return true;
+            return agent.mode === mode || agent.mode === 'all';
+        });
+    }
+    /**
+     * List primary agents available for direct user interaction.
+     * Returns agents that can be used as entry points (mode: 'primary' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of primary agent info objects
+     */
+    listPrimaryAgents() {
+        return this.list().filter((agent) => !agent.hidden && (agent.mode === 'primary' || agent.mode === 'all'));
+    }
+    /**
+     * List subagents available for TaskTool.
+     * Returns agents that can be invoked as subagents (mode: 'subagent' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of subagent info objects
+     */
+    listSubagents() {
+        return this.list().filter((agent) => !agent.hidden && (agent.mode === 'subagent' || agent.mode === 'all'));
+    }
+    /**
+     * Register a custom agent.
+     * @param agent - Agent info to register
+     * @throws Error if agent with same name already exists (unless overwrite is true)
+     */
+    register(agent, overwrite = false) {
+        const validated = AgentInfoSchema.parse(agent);
+        if (this.agents.has(validated.name) && !overwrite) {
+            throw new Error(`Agent '${validated.name}' already exists. Use overwrite=true to replace.`);
+        }
+        this.agents.set(validated.name, validated);
+    }
+    /**
+     * Unregister an agent.
+     * @param name - Agent name to remove
+     * @returns true if agent was removed, false if not found
+     */
+    unregister(name) {
+        return this.agents.delete(name);
+    }
+}
+/**
+ * Convenience function to get the AgentRegistry instance.
+ */
+export function getAgentRegistry() {
+    return AgentRegistry.getInstance();
+}

package/dist/core/domain/cipher/agent/index.d.ts

@@ -1,7 +1,10 @@
 /**
  * Agent Module
  *
- * Exports agent state management types and classes.
+ * Exports agent state management types and classes,
+ * as well as the multi-agent system components.
  */
+export { AgentInfo, AgentInfoSchema, AgentMode, AgentPermission, AgentPermissionSchema, DEFAULT_AGENT_PERMISSION, PermissionValue, READONLY_AGENT_PERMISSION, } from './agent-info.js';
+export { AgentName, AgentRegistry, getAgentRegistry, KnownAgent, } from './agent-registry.js';
 export { AgentStateMachine } from './agent-state-machine.js';
 export { AgentExecutionContext, AgentState, TerminationReason } from './agent-state.js';

package/dist/core/domain/cipher/agent/index.js

@@ -1,7 +1,13 @@
 /**
  * Agent Module
  *
- * Exports agent state management types and classes.
+ * Exports agent state management types and classes,
+ * as well as the multi-agent system components.
  */
+// Multi-agent system (agent-info.js)
+export { AgentInfoSchema, AgentMode, AgentPermissionSchema, DEFAULT_AGENT_PERMISSION, PermissionValue, READONLY_AGENT_PERMISSION, } from './agent-info.js';
+// Multi-agent system (agent-registry.js)
+export { AgentName, AgentRegistry, getAgentRegistry, } from './agent-registry.js';
+// State management
 export { AgentStateMachine } from './agent-state-machine.js';
 export { AgentState, TerminationReason } from './agent-state.js';