@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/agent/modes/codeact-mode.d.ts

@@ -0,0 +1,96 @@
+/**
+ * CodeAct Mode
+ *
+ * Mode where the LLM writes Python/TypeScript/shell as the universal action
+ * instead of calling discrete tools. Only `run_script` is exposed as a tool.
+ *
+ * Based on the CodeAct paradigm: "Code as Action"
+ * - Paper: https://arxiv.org/abs/2402.01030
+ * - Manus AI uses this as their primary execution model
+ *
+ * When enabled:
+ * 1. System prompt changes to encourage code generation
+ * 2. Only `run_script` + `view_file` + `search` tools are available
+ * 3. The LLM is instructed to solve tasks by writing executable scripts
+ * 4. Results from script execution feed back into the conversation
+ */
+export interface CodeActConfig {
+    /** Primary language for code generation */
+    language: 'python' | 'typescript' | 'javascript' | 'shell';
+    /** Whether to allow the LLM to install packages */
+    allowPackageInstall: boolean;
+    /** Maximum script execution time in ms */
+    scriptTimeout: number;
+    /** Use E2B cloud sandbox instead of Docker (if available) */
+    preferE2B: boolean;
+    /** Auto-persist scripts to workspace */
+    persistScripts: boolean;
+}
+export interface CodeActState {
+    enabled: boolean;
+    config: CodeActConfig;
+    executedScripts: number;
+    totalDuration: number;
+}
+export declare class CodeActMode {
+    private static instance;
+    private enabled;
+    private config;
+    private executedScripts;
+    private totalDuration;
+    private constructor();
+    static getInstance(): CodeActMode;
+    static resetInstance(): void;
+    /**
+     * Enable CodeAct mode
+     */
+    enable(config?: Partial<CodeActConfig>): void;
+    /**
+     * Disable CodeAct mode
+     */
+    disable(): void;
+    /**
+     * Toggle CodeAct mode
+     */
+    toggle(): boolean;
+    /**
+     * Check if CodeAct mode is active
+     */
+    isEnabled(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): CodeActConfig;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<CodeActConfig>): void;
+    /**
+     * Get the CodeAct system prompt supplement
+     */
+    getSystemPrompt(): string;
+    /**
+     * Filter tools for CodeAct mode — only allow script execution + file reading
+     */
+    filterTools<T extends {
+        function: {
+            name: string;
+        };
+    }>(tools: T[]): T[];
+    /**
+     * Record a script execution for stats
+     */
+    recordExecution(durationMs: number): void;
+    /**
+     * Get current state
+     */
+    getState(): CodeActState;
+    /**
+     * Get allowed tool names in CodeAct mode
+     */
+    getAllowedTools(): string[];
+}
+/**
+ * Convenience accessor
+ */
+export declare function getCodeActMode(): CodeActMode;

package/dist/agent/modes/codeact-mode.js

@@ -0,0 +1,187 @@
+/**
+ * CodeAct Mode
+ *
+ * Mode where the LLM writes Python/TypeScript/shell as the universal action
+ * instead of calling discrete tools. Only `run_script` is exposed as a tool.
+ *
+ * Based on the CodeAct paradigm: "Code as Action"
+ * - Paper: https://arxiv.org/abs/2402.01030
+ * - Manus AI uses this as their primary execution model
+ *
+ * When enabled:
+ * 1. System prompt changes to encourage code generation
+ * 2. Only `run_script` + `view_file` + `search` tools are available
+ * 3. The LLM is instructed to solve tasks by writing executable scripts
+ * 4. Results from script execution feed back into the conversation
+ */
+import { logger } from '../../utils/logger.js';
+// ============================================================================
+// Defaults
+// ============================================================================
+const DEFAULT_CODEACT_CONFIG = {
+    language: 'python',
+    allowPackageInstall: true,
+    scriptTimeout: 120000,
+    preferE2B: false,
+    persistScripts: true,
+};
+/**
+ * Tools allowed in CodeAct mode.
+ * All other tools are filtered out.
+ */
+const CODEACT_ALLOWED_TOOLS = new Set([
+    'run_script',
+    'view_file',
+    'search',
+    'list_directory',
+    'create_file',
+    'str_replace_editor',
+    'bash',
+]);
+// ============================================================================
+// CodeAct System Prompt
+// ============================================================================
+const CODEACT_SYSTEM_PROMPT = `You are operating in CodeAct mode. In this mode, you solve tasks by writing and executing code rather than using individual tool calls.
+
+## Rules
+1. Write complete, self-contained scripts to accomplish tasks
+2. Use the \`run_script\` tool to execute your code
+3. Read script output to verify results and iterate if needed
+4. You may use \`view_file\` and \`search\` to understand the codebase first
+5. For file modifications, write a script that reads, transforms, and writes the file
+
+## Preferred Language: {{LANGUAGE}}
+
+## Tips
+- Break complex tasks into sequential scripts
+- Print clear output to verify each step
+- Handle errors in your scripts
+- Use the filesystem as working memory (write intermediate results to files)
+- You can install packages if needed (pip install / npm install)
+
+## Example
+Instead of calling a "grep" tool, write:
+\`\`\`python
+import subprocess
+result = subprocess.run(["grep", "-r", "TODO", "src/"], capture_output=True, text=True)
+print(result.stdout)
+\`\`\`
+`;
+// ============================================================================
+// CodeAct Mode Manager (Singleton)
+// ============================================================================
+export class CodeActMode {
+    static instance = null;
+    enabled = false;
+    config;
+    executedScripts = 0;
+    totalDuration = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CODEACT_CONFIG, ...config };
+    }
+    static getInstance() {
+        if (!CodeActMode.instance) {
+            CodeActMode.instance = new CodeActMode();
+        }
+        return CodeActMode.instance;
+    }
+    static resetInstance() {
+        CodeActMode.instance = null;
+    }
+    /**
+     * Enable CodeAct mode
+     */
+    enable(config) {
+        if (config) {
+            this.config = { ...this.config, ...config };
+        }
+        this.enabled = true;
+        this.executedScripts = 0;
+        this.totalDuration = 0;
+        logger.info(`CodeAct mode enabled (language: ${this.config.language})`);
+    }
+    /**
+     * Disable CodeAct mode
+     */
+    disable() {
+        this.enabled = false;
+        logger.info('CodeAct mode disabled');
+    }
+    /**
+     * Toggle CodeAct mode
+     */
+    toggle() {
+        if (this.enabled) {
+            this.disable();
+        }
+        else {
+            this.enable();
+        }
+        return this.enabled;
+    }
+    /**
+     * Check if CodeAct mode is active
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get the CodeAct system prompt supplement
+     */
+    getSystemPrompt() {
+        if (!this.enabled)
+            return '';
+        return CODEACT_SYSTEM_PROMPT.replace('{{LANGUAGE}}', this.config.language);
+    }
+    /**
+     * Filter tools for CodeAct mode — only allow script execution + file reading
+     */
+    filterTools(tools) {
+        if (!this.enabled)
+            return tools;
+        return tools.filter(t => CODEACT_ALLOWED_TOOLS.has(t.function.name));
+    }
+    /**
+     * Record a script execution for stats
+     */
+    recordExecution(durationMs) {
+        this.executedScripts++;
+        this.totalDuration += durationMs;
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return {
+            enabled: this.enabled,
+            config: { ...this.config },
+            executedScripts: this.executedScripts,
+            totalDuration: this.totalDuration,
+        };
+    }
+    /**
+     * Get allowed tool names in CodeAct mode
+     */
+    getAllowedTools() {
+        return [...CODEACT_ALLOWED_TOOLS];
+    }
+}
+/**
+ * Convenience accessor
+ */
+export function getCodeActMode() {
+    return CodeActMode.getInstance();
+}
+//# sourceMappingURL=codeact-mode.js.map

package/dist/agent/modes/codeact-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeact-mode.js","sourceRoot":"","sources":["../../../src/agent/modes/codeact-mode.ts"],"names":[],"mappings":"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"}

package/dist/agent/multi-agent/agent-memory-integration.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Subagent Persistent Memory Integration (CC14)
+ *
+ * Provides filesystem-based persistent memory for sub-agents.
+ * Memory persists across sessions in ~/.codebuddy/agent-memory/<name>/
+ * or .codebuddy/agent-memory/<name>/ (project-local).
+ *
+ * Advanced enterprise architecture for agent memory: user|project|local scopes.
+ */
+/** Memory scope determines storage location */
+export type AgentMemoryScope = 'user' | 'project' | 'local';
+export interface AgentMemoryOptions {
+    /** Agent name/nickname */
+    agentName: string;
+    /** Memory scope */
+    scope: AgentMemoryScope;
+    /** Project root (for 'project' and 'local' scopes) */
+    projectRoot?: string;
+}
+/**
+ * Read the agent's persistent MEMORY.md file.
+ * Returns empty string if no memory exists yet.
+ */
+export declare function readAgentMemory(options: AgentMemoryOptions): string;
+/**
+ * Write content to the agent's persistent MEMORY.md file.
+ * Creates the directory if it doesn't exist.
+ */
+export declare function writeAgentMemory(options: AgentMemoryOptions, content: string): void;
+/**
+ * Append a summary to the agent's memory file.
+ * Used at the end of a sub-agent's execution to persist learnings.
+ */
+export declare function appendAgentMemory(options: AgentMemoryOptions, summary: string): void;
+/**
+ * Build a context injection string from an agent's persistent memory.
+ * Returns empty string if no memory exists.
+ */
+export declare function buildAgentMemoryContext(options: AgentMemoryOptions): string;
+/**
+ * List all agents that have persistent memory in a given scope.
+ */
+export declare function listAgentMemories(scope: AgentMemoryScope, projectRoot?: string): string[];

package/dist/agent/multi-agent/agent-memory-integration.js

@@ -0,0 +1,123 @@
+/**
+ * Subagent Persistent Memory Integration (CC14)
+ *
+ * Provides filesystem-based persistent memory for sub-agents.
+ * Memory persists across sessions in ~/.codebuddy/agent-memory/<name>/
+ * or .codebuddy/agent-memory/<name>/ (project-local).
+ *
+ * Advanced enterprise architecture for agent memory: user|project|local scopes.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../../utils/logger.js';
+// ============================================================================
+// Path Resolution
+// ============================================================================
+/**
+ * Get the memory directory for a given agent and scope.
+ */
+function getMemoryDir(options) {
+    const safeName = options.agentName.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+    switch (options.scope) {
+        case 'user': {
+            const home = process.env.HOME || process.env.USERPROFILE || '';
+            return path.join(home, '.codebuddy', 'agent-memory', safeName);
+        }
+        case 'project': {
+            const root = options.projectRoot || process.cwd();
+            return path.join(root, '.codebuddy', 'agent-memory', safeName);
+        }
+        case 'local': {
+            // Local scope: project-scoped but in a temp-like location
+            const root = options.projectRoot || process.cwd();
+            return path.join(root, '.codebuddy', 'agent-memory', safeName);
+        }
+        default:
+            return path.join(process.cwd(), '.codebuddy', 'agent-memory', safeName);
+    }
+}
+/**
+ * Ensure the memory directory exists.
+ */
+function ensureMemoryDir(memDir) {
+    if (!fs.existsSync(memDir)) {
+        fs.mkdirSync(memDir, { recursive: true });
+    }
+}
+// ============================================================================
+// Read / Write
+// ============================================================================
+/**
+ * Read the agent's persistent MEMORY.md file.
+ * Returns empty string if no memory exists yet.
+ */
+export function readAgentMemory(options) {
+    const memDir = getMemoryDir(options);
+    const memFile = path.join(memDir, 'MEMORY.md');
+    if (!fs.existsSync(memFile)) {
+        return '';
+    }
+    try {
+        return fs.readFileSync(memFile, 'utf-8');
+    }
+    catch (err) {
+        logger.debug(`Failed to read agent memory for ${options.agentName}: ${err}`);
+        return '';
+    }
+}
+/**
+ * Write content to the agent's persistent MEMORY.md file.
+ * Creates the directory if it doesn't exist.
+ */
+export function writeAgentMemory(options, content) {
+    const memDir = getMemoryDir(options);
+    const memFile = path.join(memDir, 'MEMORY.md');
+    try {
+        ensureMemoryDir(memDir);
+        fs.writeFileSync(memFile, content, 'utf-8');
+        logger.debug(`Agent memory written for ${options.agentName} (${content.length} chars)`);
+    }
+    catch (err) {
+        logger.debug(`Failed to write agent memory for ${options.agentName}: ${err}`);
+    }
+}
+/**
+ * Append a summary to the agent's memory file.
+ * Used at the end of a sub-agent's execution to persist learnings.
+ */
+export function appendAgentMemory(options, summary) {
+    const existing = readAgentMemory(options);
+    const timestamp = new Date().toISOString().split('T')[0];
+    const entry = `\n## ${timestamp}\n\n${summary}\n`;
+    writeAgentMemory(options, existing + entry);
+}
+/**
+ * Build a context injection string from an agent's persistent memory.
+ * Returns empty string if no memory exists.
+ */
+export function buildAgentMemoryContext(options) {
+    const memory = readAgentMemory(options);
+    if (!memory.trim())
+        return '';
+    return `<agent_memory scope="${options.scope}" agent="${options.agentName}">\n${memory.trim()}\n</agent_memory>`;
+}
+/**
+ * List all agents that have persistent memory in a given scope.
+ */
+export function listAgentMemories(scope, projectRoot) {
+    // Use a placeholder agent name and go up one directory to get the base
+    const opts = { agentName: '_placeholder_', scope, projectRoot };
+    const baseDir = path.dirname(getMemoryDir(opts));
+    if (!fs.existsSync(baseDir))
+        return [];
+    try {
+        return fs.readdirSync(baseDir).filter(name => {
+            const memFile = path.join(baseDir, name, 'MEMORY.md');
+            return fs.existsSync(memFile);
+        });
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=agent-memory-integration.js.map

package/dist/agent/multi-agent/agent-memory-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory-integration.js","sourceRoot":"","sources":["../../../src/agent/multi-agent/agent-memory-integration.ts"],"names":[],"mappings":"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"}

package/dist/agent/multi-agent/agent-roles.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent Roles — Configuration-driven agent behavior presets
+ *
+ * Three built-in roles:
+ *   - default: Standard agent behavior, all tools available
+ *   - explorer: Read-only codebase Q&A, fast responses
+ *   - worker: Execution focus with file ownership, sequential
+ *
+ * Roles are TOML config overlays applied at session-flag precedence.
+ * Custom roles can be defined in .codebuddy/roles/.
+ *
+ * Inspired by OpenAI Codex CLI's agent/role.rs
+ */
+export interface AgentRoleConfig {
+    /** Role name */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** System prompt injection for this role */
+    systemPrompt: string;
+    /** Allowed tool names (empty = all allowed) */
+    allowedTools: string[];
+    /** Blocked tool names */
+    blockedTools: string[];
+    /** Whether the agent can spawn sub-agents */
+    canSpawnAgents: boolean;
+    /** Suggested model override (null = inherit from parent) */
+    model: string | null;
+    /** Reasoning effort override */
+    reasoningEffort: 'low' | 'medium' | 'high' | null;
+    /** Whether this role is read-only */
+    readOnly: boolean;
+}
+/**
+ * Get a role config by name.
+ */
+export declare function getRole(name: string): AgentRoleConfig | undefined;
+/**
+ * Register a custom role.
+ */
+export declare function registerRole(config: AgentRoleConfig): void;
+/**
+ * List all available roles.
+ */
+export declare function listRoles(): AgentRoleConfig[];
+/**
+ * Check if a tool is allowed for a given role.
+ */
+export declare function isToolAllowedForRole(role: AgentRoleConfig, toolName: string): boolean;
+/**
+ * Load custom roles from .codebuddy/roles/ directory.
+ */
+export declare function loadCustomRoles(cwd?: string): number;
+/**
+ * Get the built-in role names.
+ */
+export declare function getBuiltinRoleNames(): string[];

package/dist/agent/multi-agent/agent-roles.js

@@ -0,0 +1,153 @@
+/**
+ * Agent Roles — Configuration-driven agent behavior presets
+ *
+ * Three built-in roles:
+ *   - default: Standard agent behavior, all tools available
+ *   - explorer: Read-only codebase Q&A, fast responses
+ *   - worker: Execution focus with file ownership, sequential
+ *
+ * Roles are TOML config overlays applied at session-flag precedence.
+ * Custom roles can be defined in .codebuddy/roles/.
+ *
+ * Inspired by OpenAI Codex CLI's agent/role.rs
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../../utils/logger.js';
+// ============================================================================
+// Built-in Roles
+// ============================================================================
+const EXPLORER_ROLE = {
+    name: 'explorer',
+    description: 'Read-only codebase explorer. Fast, authoritative answers about code structure.',
+    systemPrompt: `You are a codebase explorer agent. Your job is to quickly answer questions about the codebase structure, dependencies, and patterns.
+
+Rules:
+- Use ONLY read and search tools (grep, glob, read_file, tree, find_references)
+- Do NOT modify any files
+- Do NOT run shell commands
+- Be fast and authoritative — your answers should be trusted without additional verification
+- When asked about multiple files, read them in parallel
+- Provide specific file paths and line numbers in your answers`,
+    allowedTools: [
+        'read_file', 'view_file', 'file_read', 'grep', 'glob',
+        'list_files', 'search_files', 'find_references', 'tree',
+        'get_file_info', 'codebase_map', 'code_graph',
+        'knowledge_search', 'knowledge_list',
+    ],
+    blockedTools: [],
+    canSpawnAgents: false,
+    model: null,
+    reasoningEffort: 'low',
+    readOnly: true,
+};
+const WORKER_ROLE = {
+    name: 'worker',
+    description: 'Execution worker. Focused on implementing changes with explicit file ownership.',
+    systemPrompt: `You are a worker agent assigned to implement specific changes.
+
+Rules:
+- Focus only on the files and tasks explicitly assigned to you
+- Do NOT modify files outside your assignment
+- You are not alone — other agents may be editing other files simultaneously
+- Do NOT revert edits made by other agents
+- Run tests after making changes to verify correctness
+- Call terminate when your assigned task is complete`,
+    allowedTools: [], // all tools
+    blockedTools: ['spawn_agent'], // workers don't spawn
+    canSpawnAgents: false,
+    model: null,
+    reasoningEffort: 'medium',
+    readOnly: false,
+};
+const DEFAULT_ROLE = {
+    name: 'default',
+    description: 'Standard agent with full capabilities.',
+    systemPrompt: '',
+    allowedTools: [],
+    blockedTools: [],
+    canSpawnAgents: true,
+    model: null,
+    reasoningEffort: null,
+    readOnly: false,
+};
+/** Registry of all known roles */
+const roleRegistry = new Map([
+    ['default', DEFAULT_ROLE],
+    ['explorer', EXPLORER_ROLE],
+    ['worker', WORKER_ROLE],
+]);
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Get a role config by name.
+ */
+export function getRole(name) {
+    return roleRegistry.get(name);
+}
+/**
+ * Register a custom role.
+ */
+export function registerRole(config) {
+    roleRegistry.set(config.name, config);
+    logger.debug(`Agent role registered: ${config.name}`);
+}
+/**
+ * List all available roles.
+ */
+export function listRoles() {
+    return [...roleRegistry.values()];
+}
+/**
+ * Check if a tool is allowed for a given role.
+ */
+export function isToolAllowedForRole(role, toolName) {
+    // Blocked tools always blocked
+    if (role.blockedTools.length > 0 && role.blockedTools.includes(toolName)) {
+        return false;
+    }
+    // If allowedTools is non-empty, whitelist only those
+    if (role.allowedTools.length > 0) {
+        return role.allowedTools.includes(toolName);
+    }
+    return true;
+}
+/**
+ * Load custom roles from .codebuddy/roles/ directory.
+ */
+export function loadCustomRoles(cwd = process.cwd()) {
+    const rolesDir = path.join(cwd, '.codebuddy', 'roles');
+    if (!fs.existsSync(rolesDir))
+        return 0;
+    let loaded = 0;
+    try {
+        const files = fs.readdirSync(rolesDir).filter(f => f.endsWith('.json'));
+        for (const file of files) {
+            try {
+                const content = fs.readFileSync(path.join(rolesDir, file), 'utf-8');
+                const config = JSON.parse(content);
+                if (config.name) {
+                    registerRole({
+                        ...DEFAULT_ROLE,
+                        ...config,
+                        name: config.name,
+                    });
+                    loaded++;
+                }
+            }
+            catch (err) {
+                logger.debug(`Failed to load role ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch { /* directory read failed */ }
+    return loaded;
+}
+/**
+ * Get the built-in role names.
+ */
+export function getBuiltinRoleNames() {
+    return ['default', 'explorer', 'worker'];
+}
+//# sourceMappingURL=agent-roles.js.map

package/dist/agent/multi-agent/agent-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roles.js","sourceRoot":"","sources":["../../../src/agent/multi-agent/agent-roles.ts"],"names":[],"mappings":"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"}