protoagent 0.0.5 → 0.1.0

package/dist/skills.js

@@ -0,0 +1,229 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import YAML from 'yaml';
+import { registerDynamicHandler, registerDynamicTool, unregisterDynamicHandler, unregisterDynamicTool, } from './tools/index.js';
+import { setAllowedPathRoots } from './utils/path-validation.js';
+import { logger } from './utils/logger.js';
+const ACTIVATE_SKILL_TOOL_NAME = 'activate_skill';
+const VALID_SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_RESOURCE_FILES = 200;
+function getSkillRoots(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const homeDir = options.homeDir ?? os.homedir();
+    return [
+        { dir: path.join(homeDir, '.agents', 'skills'), source: 'user' },
+        { dir: path.join(homeDir, '.protoagent', 'skills'), source: 'user' },
+        { dir: path.join(homeDir, '.config', 'protoagent', 'skills'), source: 'user' },
+        { dir: path.join(cwd, '.agents', 'skills'), source: 'project' },
+        { dir: path.join(cwd, '.protoagent', 'skills'), source: 'project' },
+    ];
+}
+function parseFrontmatter(rawContent) {
+    const match = rawContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        throw new Error('SKILL.md must begin with YAML frontmatter delimited by --- lines.');
+    }
+    const document = YAML.parse(match[1]);
+    if (!document || typeof document !== 'object' || Array.isArray(document)) {
+        throw new Error('Frontmatter must parse to an object.');
+    }
+    return {
+        frontmatter: document,
+        body: match[2].trim(),
+    };
+}
+function isValidSkillName(name) {
+    return name.length >= 1 && name.length <= 64 && VALID_SKILL_NAME.test(name);
+}
+function normalizeMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value).filter(([, entryValue]) => typeof entryValue === 'string');
+    if (entries.length === 0)
+        return undefined;
+    return Object.fromEntries(entries);
+}
+function validateSkill(parsed, skillDir, source, location) {
+    const name = typeof parsed.frontmatter.name === 'string' ? parsed.frontmatter.name.trim() : '';
+    const description = typeof parsed.frontmatter.description === 'string'
+        ? parsed.frontmatter.description.trim()
+        : '';
+    const compatibility = typeof parsed.frontmatter.compatibility === 'string'
+        ? parsed.frontmatter.compatibility.trim()
+        : undefined;
+    const license = typeof parsed.frontmatter.license === 'string'
+        ? parsed.frontmatter.license.trim()
+        : undefined;
+    const allowedToolsValue = typeof parsed.frontmatter['allowed-tools'] === 'string'
+        ? parsed.frontmatter['allowed-tools'].trim()
+        : undefined;
+    if (!isValidSkillName(name)) {
+        throw new Error(`Skill name "${name}" is invalid.`);
+    }
+    if (path.basename(skillDir) !== name) {
+        throw new Error(`Skill name "${name}" must match directory name "${path.basename(skillDir)}".`);
+    }
+    if (!description || description.length > 1024) {
+        throw new Error('Skill description is required and must be 1-1024 characters.');
+    }
+    if (compatibility !== undefined && (compatibility.length === 0 || compatibility.length > 500)) {
+        throw new Error('Skill compatibility must be 1-500 characters when provided.');
+    }
+    return {
+        name,
+        description,
+        source,
+        location,
+        skillDir,
+        body: parsed.body,
+        compatibility,
+        license,
+        metadata: normalizeMetadata(parsed.frontmatter.metadata),
+        allowedTools: allowedToolsValue ? allowedToolsValue.split(/\s+/).filter(Boolean) : undefined,
+    };
+}
+async function loadSkillFromDirectory(skillDir, source) {
+    const location = path.join(skillDir, 'SKILL.md');
+    try {
+        const rawContent = await fs.readFile(location, 'utf8');
+        const parsed = parseFrontmatter(rawContent);
+        const skill = validateSkill(parsed, skillDir, source, location);
+        logger.debug(`Loaded skill: ${skill.name} (${source})`, { location });
+        return skill;
+    }
+    catch (error) {
+        logger.warn(`Skipping invalid skill at ${location}`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+async function discoverSkillsInRoot(root) {
+    let entries = [];
+    try {
+        entries = await fs.readdir(root.dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const loaded = await Promise.all(entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => loadSkillFromDirectory(path.join(root.dir, entry.name), root.source)));
+    return loaded.filter((skill) => skill !== null);
+}
+export async function loadSkills(options = {}) {
+    const roots = getSkillRoots(options);
+    const merged = new Map();
+    for (const root of roots) {
+        const skills = await discoverSkillsInRoot(root);
+        for (const skill of skills) {
+            if (merged.has(skill.name)) {
+                logger.warn(`Skill collision detected for "${skill.name}". Using ${skill.source}-level version.`, {
+                    location: skill.location,
+                });
+            }
+            merged.set(skill.name, skill);
+        }
+    }
+    return Array.from(merged.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+export function buildSkillsCatalogSection(skills) {
+    if (skills.length === 0)
+        return '';
+    const catalog = skills
+        .map((skill) => [
+        '  <skill>',
+        `    <name>${escapeXml(skill.name)}</name>`,
+        `    <description>${escapeXml(skill.description)}</description>`,
+        `    <location>${escapeXml(skill.location)}</location>`,
+        '  </skill>',
+    ].join('\n'))
+        .join('\n');
+    return `AVAILABLE SKILLS
+
+The following skills provide specialized instructions for specific tasks.
+When a task matches a skill's description, call the ${ACTIVATE_SKILL_TOOL_NAME} tool with the skill's name before proceeding.
+After activation, treat paths listed in the skill output as readable resources and resolve relative paths against the skill directory.
+
+<available_skills>
+${catalog}
+</available_skills>`;
+}
+async function listSkillResources(skillDir) {
+    const files = [];
+    async function walk(relativeDir) {
+        if (files.length >= MAX_RESOURCE_FILES)
+            return;
+        const absoluteDir = path.join(skillDir, relativeDir);
+        let entries = [];
+        try {
+            entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (files.length >= MAX_RESOURCE_FILES)
+                return;
+            const nextRelative = path.join(relativeDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(nextRelative);
+            }
+            else {
+                files.push(nextRelative.split(path.sep).join('/'));
+            }
+        }
+    }
+    await Promise.all(['scripts', 'references', 'assets'].map((dir) => walk(dir)));
+    return files.sort();
+}
+export async function activateSkill(skillName, options = {}) {
+    const skills = await loadSkills(options);
+    const skill = skills.find((entry) => entry.name === skillName);
+    if (!skill) {
+        return `Error: Unknown skill "${skillName}".`;
+    }
+    const resources = await listSkillResources(skill.skillDir);
+    const resourcesBlock = resources.length > 0
+        ? `<skill_resources>\n${resources.map((resource) => `  <file>${escapeXml(resource)}</file>`).join('\n')}\n</skill_resources>`
+        : '<skill_resources />';
+    return `<skill_content name="${escapeXml(skill.name)}">\n${skill.body}\n\nSkill directory: ${escapeXml(skill.skillDir)}\nRelative paths in this skill are relative to the skill directory. Use absolute paths in tool calls when needed.\n\n${resourcesBlock}\n</skill_content>`;
+}
+export async function initializeSkillsSupport(options = {}) {
+    const skills = await loadSkills(options);
+    await setAllowedPathRoots(skills.map((skill) => skill.skillDir));
+    if (skills.length === 0) {
+        unregisterDynamicTool(ACTIVATE_SKILL_TOOL_NAME);
+        unregisterDynamicHandler(ACTIVATE_SKILL_TOOL_NAME);
+        return [];
+    }
+    registerDynamicTool({
+        type: 'function',
+        function: {
+            name: ACTIVATE_SKILL_TOOL_NAME,
+            description: 'Load the full instructions for a discovered skill so you can follow it for the current task.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        enum: skills.map((skill) => skill.name),
+                        description: 'The exact skill name to activate.',
+                    },
+                },
+                required: ['name'],
+            },
+        },
+    });
+    registerDynamicHandler(ACTIVATE_SKILL_TOOL_NAME, async (args) => activateSkill(args.name, options));
+    return skills;
+}

package/dist/sub-agent.js

@@ -0,0 +1,103 @@
+/**
+ * Sub-agents — Spawn isolated child agent sessions.
+ *
+ * Sub-agents prevent context pollution by running tasks in a separate
+ * message history. The parent agent delegates a task, the sub-agent
+ * executes it with its own tool calls, and returns a summary.
+ *
+ * This is exposed as a `sub_agent` tool that the main agent can call.
+ */
+import crypto from 'node:crypto';
+import { handleToolCall, getAllTools } from './tools/index.js';
+import { generateSystemPrompt } from './system-prompt.js';
+import { logger } from './utils/logger.js';
+import { clearTodos } from './tools/todo.js';
+export const subAgentTool = {
+    type: 'function',
+    function: {
+        name: 'sub_agent',
+        description: 'Spawn an isolated sub-agent to handle a task without polluting the main conversation context. ' +
+            'Use this for independent subtasks like exploring a codebase, researching a question, or making changes to a separate area. ' +
+            'The sub-agent has access to the same tools but runs in its own conversation.',
+        parameters: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'A detailed description of the task for the sub-agent to complete.',
+                },
+                max_iterations: {
+                    type: 'number',
+                    description: 'Maximum tool-call iterations for the sub-agent. Defaults to 30.',
+                },
+            },
+            required: ['task'],
+        },
+    },
+};
+/**
+ * Run a sub-agent with its own isolated conversation.
+ * Returns the sub-agent's final text response.
+ */
+export async function runSubAgent(client, model, task, maxIterations = 30) {
+    const op = logger.startOperation('sub-agent');
+    const subAgentSessionId = `sub-agent-${crypto.randomUUID()}`;
+    const systemPrompt = await generateSystemPrompt();
+    const subSystemPrompt = `${systemPrompt}
+
+## Sub-Agent Mode
+
+You are running as a sub-agent. You were given a specific task by the parent agent.
+Complete the task thoroughly and return a clear, concise summary of what you did and found.
+Do NOT ask the user questions — work autonomously with the tools available.`;
+    const messages = [
+        { role: 'system', content: subSystemPrompt },
+        { role: 'user', content: task },
+    ];
+    try {
+        for (let i = 0; i < maxIterations; i++) {
+            const response = await client.chat.completions.create({
+                model,
+                messages,
+                tools: getAllTools(),
+                tool_choice: 'auto',
+            });
+            const message = response.choices[0]?.message;
+            if (!message)
+                break;
+            // Check for tool calls
+            if (message.tool_calls && message.tool_calls.length > 0) {
+                messages.push(message);
+                for (const toolCall of message.tool_calls) {
+                    const { name, arguments: argsStr } = toolCall.function;
+                    logger.debug(`Sub-agent tool call: ${name}`);
+                    try {
+                        const args = JSON.parse(argsStr);
+                        const result = await handleToolCall(name, args, { sessionId: subAgentSessionId });
+                        messages.push({
+                            role: 'tool',
+                            tool_call_id: toolCall.id,
+                            content: result,
+                        });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        messages.push({
+                            role: 'tool',
+                            tool_call_id: toolCall.id,
+                            content: `Error: ${msg}`,
+                        });
+                    }
+                }
+                continue;
+            }
+            // Plain text response — we're done
+            return message.content || '(sub-agent completed with no response)';
+        }
+        return '(sub-agent reached iteration limit)';
+    }
+    finally {
+        op.end();
+        clearTodos(subAgentSessionId);
+    }
+}

package/dist/system-prompt.js

@@ -0,0 +1,131 @@
+/**
+ * System prompt generation.
+ *
+ * Builds a dynamic system prompt that includes:
+ *  - Role and behavioural instructions
+ *  - Working directory and project structure
+ *  - Tool descriptions (auto-generated from tool schemas)
+ *  - Skills catalog (loaded progressively from skill directories)
+ *  - Guidelines for file operations, TODO tracking, etc.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getAllTools } from './tools/index.js';
+import { buildSkillsCatalogSection, initializeSkillsSupport } from './skills.js';
+/** Build a filtered directory tree (depth 3, excludes noise). */
+async function buildDirectoryTree(dirPath = '.', depth = 0, maxDepth = 3) {
+    if (depth > maxDepth)
+        return '';
+    const indent = '  '.repeat(depth);
+    let tree = '';
+    try {
+        const fullPath = path.resolve(dirPath);
+        const entries = await fs.readdir(fullPath, { withFileTypes: true });
+        const filtered = entries.filter((e) => {
+            const n = e.name;
+            return !n.startsWith('.') && !['node_modules', 'dist', 'build', 'coverage', '__pycache__', '.git'].includes(n) && !n.endsWith('.log');
+        });
+        for (const entry of filtered.slice(0, 20)) {
+            if (entry.isDirectory()) {
+                tree += `${indent}${entry.name}/\n`;
+                tree += await buildDirectoryTree(path.join(dirPath, entry.name), depth + 1, maxDepth);
+            }
+            else {
+                tree += `${indent}${entry.name}\n`;
+            }
+        }
+        if (filtered.length > 20) {
+            tree += `${indent}... (${filtered.length - 20} more)\n`;
+        }
+    }
+    catch {
+        // Can't read directory — skip
+    }
+    return tree;
+}
+/** Auto-generate tool descriptions from their JSON schemas. */
+function generateToolDescriptions() {
+    return getAllTools()
+        .map((tool, i) => {
+        const fn = tool.function;
+        const params = fn.parameters;
+        const required = params.required || [];
+        const props = Object.keys(params.properties || {});
+        const paramList = props
+            .map((p) => `${p}${required.includes(p) ? ' (required)' : ' (optional)'}`)
+            .join(', ');
+        return `${i + 1}. ${fn.name} — ${fn.description}\n   Parameters: ${paramList || 'none'}`;
+    })
+        .join('\n\n');
+}
+/** Generate the complete system prompt. */
+export async function generateSystemPrompt() {
+    const cwd = process.cwd();
+    const projectName = path.basename(cwd);
+    const tree = await buildDirectoryTree();
+    const skills = await initializeSkillsSupport();
+    const toolDescriptions = generateToolDescriptions();
+    const skillsSection = buildSkillsCatalogSection(skills);
+    return `You are ProtoAgent, a coding assistant with file system and shell command capabilities.
+Your job is to help the user complete coding tasks in their project.
+
+PROJECT CONTEXT
+
+Working Directory: ${cwd}
+Project Name: ${projectName}
+
+PROJECT STRUCTURE:
+${tree}
+
+AVAILABLE TOOLS
+
+${toolDescriptions}
+${skillsSection ? `\n${skillsSection}\n` : ''}
+GUIDELINES
+
+OUTPUT FORMAT:
+- You are running in a terminal. Be concise. Optimise for scannability.
+- Use **bold** for important terms, *italic* for references.
+- Use Markdown tables to present structured data — they render with full box-drawing borders.
+- Use flat bullet lists with emojis to communicate information densely (e.g. ✅ done, ❌ failed, 📁 file, 🔍 searching).
+- NEVER use nested indentation. Keep all lists flat — one level only.
+- Markdown links [text](url) are NOT supported — just write URLs inline.
+
+SUBAGENT STRATEGY:
+Delegate work to specialized subagents aggressively. They excel at focused, parallel tasks.
+- **When to use subagents**: Any task involving deep research, broad codebase exploration, complex analysis, or multi-step investigations.
+- **Parallelizable tasks**: When a request can be split into independent subtasks, strongly prefer delegating those pieces to subagents so they can run concurrently.
+- **Parallel work**: Launch multiple subagents simultaneously for independent tasks (e.g., search different parts of codebase, investigate different issues).
+- **Thorough context**: Always provide subagents with complete task descriptions, relevant background, and specific success criteria. Be explicit about what "done" looks like.
+- **Trust the delegation**: Subagents have access to the same tools and can work autonomously. Don't re-do their work in your main context.
+- **Examples of good delegation**:
+  - Complex codebase exploration → Use Explore agent with "very thorough" or "medium" setting
+  - Cross-file code searches → Launch Bash agent for grep/find operations in parallel
+  - Architecture/design planning → Use Plan agent to explore codebase and design approach
+  - Multi-step debugging → Use general-purpose agent for systematic investigation
+
+WORKFLOW:
+- Before making tool calls, briefly explain what you're about to do and why.
+- Always read files before editing them.
+- Prefer edit_file over write_file for existing files.
+- Use TODO tracking (todo_write / todo_read) by default for almost all work. The only exceptions are when the user explicitly asks you not to use TODOs, or when the task is truly trivial and can be completed in a single obvious step.
+- Start by creating or refreshing the TODO list before doing substantive work, then keep it current throughout the task: mark items in_progress/completed as you go, and read it back whenever you need to check or communicate progress.
+- When you update the TODO list, always write the full latest list so the user can see the current plan and status clearly in the tool output.
+- Search first when you need to find something — use search_files or bash with grep/find, or delegate to a subagent for thorough exploration.
+- Shell commands: safe commands (ls, grep, git status, etc.) run automatically. Other commands require user approval.
+- **Diligence**: Don't cut corners. Verify assumptions before acting. Read related code. Test changes where possible. Leave the codebase better than you found it.
+
+FILE OPERATIONS:
+- ALWAYS use read_file before editing to get exact content.
+- NEVER write over existing files unless explicitly asked — use edit_file instead.
+- Create parent directories before creating files in them.
+- Use bash for package management, git, building, testing, etc.
+- When running interactive commands, add flags to avoid prompts (--yes, --template, etc.)
+
+IMPLEMENTATION STANDARDS:
+- **Thorough investigation**: Before implementing, understand the existing codebase, patterns, and related systems.
+- **Completeness**: Ensure implementations are complete and tested, not partial or left in a broken state.
+- **Code quality**: Follow existing code style and conventions. Make changes that fit naturally into the codebase.
+- **Documentation**: Update relevant documentation and comments if the code isn't self-evident.
+- **No half measures**: If a task requires 3 steps to do properly, do all 3 steps. Don't leave TODOs for later work unless explicitly scoped that way.`;
+}

package/dist/tools/bash.js

@@ -0,0 +1,178 @@
+/**
+ * bash tool — Execute shell commands with security controls.
+ *
+ * Three-tier security model:
+ *  1. Hard-blocked dangerous commands (cannot be overridden)
+ *  2. Auto-approved safe commands (read-only / info commands)
+ *  3. Everything else requires user approval
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { requestApproval } from '../utils/approval.js';
+import { logger } from '../utils/logger.js';
+import { getWorkingDirectory, validatePath } from '../utils/path-validation.js';
+export const bashTool = {
+    type: 'function',
+    function: {
+        name: 'bash',
+        description: 'Execute a shell command. Safe commands (ls, grep, git status, etc.) run automatically. ' +
+            'Other commands require user approval. Some dangerous commands are blocked entirely.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'The shell command to execute.' },
+                timeout_ms: { type: 'number', description: 'Timeout in milliseconds. Defaults to 30000 (30s).' },
+            },
+            required: ['command'],
+        },
+    },
+};
+// Hard-blocked commands — these CANNOT be run, even with --dangerously-accept-all
+const DANGEROUS_PATTERNS = [
+    'rm -rf /',
+    'sudo',
+    'su ',
+    'chmod 777',
+    'dd if=',
+    'mkfs',
+    'fdisk',
+    'format c:',
+];
+// Auto-approved safe commands — read-only / informational
+const SAFE_COMMANDS = [
+    'pwd', 'whoami', 'date',
+    'git status', 'git log', 'git diff', 'git branch', 'git show', 'git remote',
+    'npm list', 'npm ls', 'yarn list',
+    'node --version', 'npm --version', 'python --version', 'python3 --version',
+];
+const SHELL_CONTROL_PATTERN = /(^|[^\\])(?:;|&&|\|\||\||>|<|`|\$\(|\*|\?)/;
+const UNSAFE_BASH_TOKENS = new Set(['cat', 'head', 'tail', 'grep', 'rg', 'find', 'awk', 'sed', 'sort', 'uniq', 'cut', 'wc', 'tree', 'file', 'dir', 'ls', 'echo', 'which', 'type']);
+function isDangerous(command) {
+    const lower = command.toLowerCase().trim();
+    return DANGEROUS_PATTERNS.some((p) => lower.includes(p));
+}
+function hasShellControlOperators(command) {
+    return SHELL_CONTROL_PATTERN.test(command);
+}
+function tokenizeCommand(command) {
+    const tokens = command.match(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\S+/g);
+    return tokens && tokens.length > 0 ? tokens : null;
+}
+function stripOuterQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function looksLikePath(token) {
+    if (!token)
+        return false;
+    if (token === '.' || token === '..')
+        return true;
+    if (token.startsWith('/') || token.startsWith('./') || token.startsWith('../') || token.startsWith('~/')) {
+        return true;
+    }
+    return token.includes(path.sep) || /\.[A-Za-z0-9_-]+$/.test(token);
+}
+async function validateCommandPaths(tokens) {
+    for (let index = 1; index < tokens.length; index++) {
+        const token = stripOuterQuotes(tokens[index]);
+        if (!looksLikePath(token))
+            continue;
+        if (token.startsWith('~'))
+            return false;
+        try {
+            await validatePath(token);
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+async function isSafe(command) {
+    const trimmed = command.trim();
+    if (!trimmed || hasShellControlOperators(trimmed)) {
+        return false;
+    }
+    const tokens = tokenizeCommand(trimmed);
+    if (!tokens) {
+        return false;
+    }
+    const firstWord = trimmed.split(/\s+/)[0];
+    if (UNSAFE_BASH_TOKENS.has(firstWord)) {
+        return false;
+    }
+    const matchedSafeCommand = SAFE_COMMANDS.some((safe) => {
+        if (safe.includes(' ')) {
+            return trimmed === safe || trimmed.startsWith(`${safe} `);
+        }
+        return firstWord === safe;
+    });
+    if (!matchedSafeCommand) {
+        return false;
+    }
+    return validateCommandPaths(tokens);
+}
+export async function runBash(command, timeoutMs = 30_000, sessionId) {
+    // Layer 1: hard block
+    if (isDangerous(command)) {
+        return `Error: Command blocked for safety. "${command}" contains a dangerous pattern that cannot be executed.`;
+    }
+    // Layer 2: safe commands skip approval
+    if (!(await isSafe(command))) {
+        // Layer 3: interactive approval
+        const approved = await requestApproval({
+            id: `bash-${Date.now()}`,
+            type: 'shell_command',
+            description: `Run command: ${command}`,
+            detail: `Working directory: ${getWorkingDirectory()}\nCommand: ${command}`,
+            sessionId,
+            sessionScopeKey: `shell:${command}`,
+        });
+        if (!approved) {
+            return `Command cancelled by user: ${command}`;
+        }
+    }
+    logger.debug(`Executing: ${command}`);
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const child = spawn(command, [], {
+            shell: true,
+            cwd: process.cwd(),
+            env: { ...process.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        child.stdout?.on('data', (data) => { stdout += data.toString(); });
+        child.stderr?.on('data', (data) => { stderr += data.toString(); });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 2000);
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                resolve(`Command timed out after ${timeoutMs / 1000}s.\nPartial stdout:\n${stdout.slice(0, 5000)}\nPartial stderr:\n${stderr.slice(0, 2000)}`);
+                return;
+            }
+            // Truncate very long output
+            const maxLen = 50_000;
+            const truncatedStdout = stdout.length > maxLen
+                ? stdout.slice(0, maxLen) + `\n... (output truncated, ${stdout.length} chars total)`
+                : stdout;
+            if (code === 0) {
+                resolve(truncatedStdout || '(command completed successfully with no output)');
+            }
+            else {
+                resolve(`Command exited with code ${code}.\nstdout:\n${truncatedStdout}\nstderr:\n${stderr.slice(0, 5000)}`);
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve(`Error executing command: ${err.message}`);
+        });
+    });
+}