profclaw 2.0.0 → 2.3.0

package/dist/agents/orchestrator.js

@@ -0,0 +1,495 @@
+/**
+ * Multi-Agent Orchestrator
+ *
+ * Enables spawning, managing, and merging results from sub-agents.
+ * Supports orchestration patterns:
+ *   - Fan-out: N parallel workers + 1 synthesizer
+ *   - Pipeline: sequential agent chain (A -> B -> C)
+ *   - Debate: 2+ agents argue, 1 judges
+ *
+ * Each sub-agent gets an isolated session with scoped tool access.
+ * Parent can set token budgets, timeouts, and tool policies per child.
+ */
+import { randomUUID } from 'node:crypto';
+import { createContextualLogger } from '../utils/logger.js';
+const log = createContextualLogger('Orchestrator');
+// Active orchestrations for cancellation
+const activeOrchestrations = new Map();
+/**
+ * Run a sub-agent in an isolated session.
+ */
+async function runSubAgent(config, contextInput, signal) {
+    const startTime = Date.now();
+    try {
+        const { executeAgenticChat } = await import('../chat/agentic-executor.js');
+        const { createChatToolHandler } = await import('../chat/tool-handler.js');
+        const conversationId = `orchestrator-${config.id}-${randomUUID()}`;
+        const toolHandler = await createChatToolHandler({
+            conversationId,
+            securityMode: 'full',
+        });
+        // Filter tools if restricted
+        const allTools = toolHandler.getTools();
+        const tools = config.allowedTools?.length
+            ? allTools.filter((t) => config.allowedTools.includes(t.name))
+            : allTools;
+        // Build the prompt - inject pipeline context if provided
+        let fullPrompt = config.prompt;
+        if (contextInput) {
+            fullPrompt = `Context from previous step:\n${contextInput}\n\nYour task:\n${config.prompt}`;
+        }
+        const response = await Promise.race([
+            executeAgenticChat({
+                conversationId,
+                messages: [{
+                        id: randomUUID(),
+                        role: 'user',
+                        content: fullPrompt,
+                        timestamp: new Date().toISOString(),
+                    }],
+                systemPrompt: config.systemPrompt || 'You are a focused AI agent working on a specific sub-task. Be concise and thorough.',
+                model: config.model,
+                effort: config.effort || 'medium',
+                toolHandler,
+                tools: tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                })),
+            }),
+            new Promise((_, reject) => {
+                const timeout = config.timeoutMs || 300000;
+                const timer = setTimeout(() => reject(new Error(`Sub-agent "${config.name}" timed out after ${timeout}ms`)), timeout);
+                signal?.addEventListener('abort', () => {
+                    clearTimeout(timer);
+                    reject(new Error(`Sub-agent "${config.name}" cancelled`));
+                });
+            }),
+        ]);
+        return {
+            agentId: config.id,
+            agentName: config.name,
+            success: true,
+            output: response.content,
+            durationMs: Date.now() - startTime,
+            tokensUsed: response.usage?.totalTokens,
+        };
+    }
+    catch (error) {
+        return {
+            agentId: config.id,
+            agentName: config.name,
+            success: false,
+            output: '',
+            error: error instanceof Error ? error.message : String(error),
+            durationMs: Date.now() - startTime,
+        };
+    }
+}
+/**
+ * Execute a fan-out orchestration: run N agents in parallel, then synthesize.
+ */
+async function executeFanOut(config, signal) {
+    const startTime = Date.now();
+    // Run all agents in parallel
+    const results = await Promise.allSettled(config.agents.map((agent) => runSubAgent(agent, undefined, signal)));
+    const agentResults = results.map((r, i) => {
+        if (r.status === 'fulfilled')
+            return r.value;
+        return {
+            agentId: config.agents[i].id,
+            agentName: config.agents[i].name,
+            success: false,
+            output: '',
+            error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+            durationMs: Date.now() - startTime,
+        };
+    });
+    // Synthesize results
+    let finalOutput = '';
+    if (config.synthesizerPrompt) {
+        const synthesisInput = agentResults
+            .filter((r) => r.success)
+            .map((r) => `[${r.agentName}]:\n${r.output}`)
+            .join('\n\n---\n\n');
+        const synthesisResult = await runSubAgent({
+            id: 'synthesizer',
+            name: 'Synthesizer',
+            prompt: `${config.synthesizerPrompt}\n\nResults from ${agentResults.filter((r) => r.success).length} agents:\n\n${synthesisInput}`,
+            model: config.agents[0]?.model,
+            effort: 'medium',
+        }, undefined, signal);
+        agentResults.push(synthesisResult);
+        finalOutput = synthesisResult.output;
+    }
+    else {
+        finalOutput = agentResults
+            .filter((r) => r.success)
+            .map((r) => `## ${r.agentName}\n${r.output}`)
+            .join('\n\n');
+    }
+    const totalTokens = agentResults.reduce((sum, r) => sum + (r.tokensUsed || 0), 0);
+    return {
+        id: config.id,
+        pattern: 'fan_out',
+        success: agentResults.some((r) => r.success),
+        agentResults,
+        finalOutput,
+        totalDurationMs: Date.now() - startTime,
+        totalTokens,
+    };
+}
+/**
+ * Execute a pipeline orchestration: A -> B -> C
+ * Output of each agent becomes context for the next.
+ */
+async function executePipeline(config, signal) {
+    const startTime = Date.now();
+    const agentResults = [];
+    let lastOutput = '';
+    for (const agent of config.agents) {
+        if (signal.aborted)
+            break;
+        const result = await runSubAgent(agent, lastOutput || undefined, signal);
+        agentResults.push(result);
+        if (!result.success && config.failFast) {
+            return {
+                id: config.id,
+                pattern: 'pipeline',
+                success: false,
+                agentResults,
+                finalOutput: '',
+                totalDurationMs: Date.now() - startTime,
+                totalTokens: agentResults.reduce((sum, r) => sum + (r.tokensUsed || 0), 0),
+                error: `Pipeline failed at step "${agent.name}": ${result.error}`,
+            };
+        }
+        if (result.success) {
+            lastOutput = result.output;
+        }
+    }
+    return {
+        id: config.id,
+        pattern: 'pipeline',
+        success: agentResults.some((r) => r.success),
+        agentResults,
+        finalOutput: lastOutput,
+        totalDurationMs: Date.now() - startTime,
+        totalTokens: agentResults.reduce((sum, r) => sum + (r.tokensUsed || 0), 0),
+    };
+}
+/**
+ * Execute a debate orchestration: agents argue, judge decides.
+ */
+async function executeDebate(config, signal) {
+    const startTime = Date.now();
+    // Run debaters in parallel
+    const debaterResults = await Promise.allSettled(config.agents.map((agent) => runSubAgent(agent, undefined, signal)));
+    const agentResults = debaterResults.map((r, i) => {
+        if (r.status === 'fulfilled')
+            return r.value;
+        return {
+            agentId: config.agents[i].id,
+            agentName: config.agents[i].name,
+            success: false,
+            output: '',
+            error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+            durationMs: Date.now() - startTime,
+        };
+    });
+    // Judge the debate
+    let finalOutput = '';
+    if (config.judgePrompt) {
+        const debateInput = agentResults
+            .filter((r) => r.success)
+            .map((r) => `[${r.agentName}] argues:\n${r.output}`)
+            .join('\n\n---\n\n');
+        const judgeResult = await runSubAgent({
+            id: 'judge',
+            name: 'Judge',
+            prompt: `${config.judgePrompt}\n\nArguments:\n\n${debateInput}`,
+            model: config.agents[0]?.model,
+            effort: 'high',
+        }, undefined, signal);
+        agentResults.push(judgeResult);
+        finalOutput = judgeResult.output;
+    }
+    else {
+        finalOutput = agentResults.filter((r) => r.success).map((r) => r.output).join('\n\n');
+    }
+    return {
+        id: config.id,
+        pattern: 'debate',
+        success: agentResults.some((r) => r.success),
+        agentResults,
+        finalOutput,
+        totalDurationMs: Date.now() - startTime,
+        totalTokens: agentResults.reduce((sum, r) => sum + (r.tokensUsed || 0), 0),
+    };
+}
+// Public API
+/**
+ * Execute an orchestration.
+ */
+export async function orchestrate(config) {
+    const abortController = new AbortController();
+    activeOrchestrations.set(config.id, abortController);
+    // Overall timeout
+    let timeoutHandle;
+    if (config.timeoutMs) {
+        timeoutHandle = setTimeout(() => abortController.abort(), config.timeoutMs);
+    }
+    log.info(`Starting orchestration: ${config.name} (${config.pattern}) with ${config.agents.length} agents`);
+    try {
+        let result;
+        switch (config.pattern) {
+            case 'fan_out':
+                result = await executeFanOut(config, abortController.signal);
+                break;
+            case 'pipeline':
+                result = await executePipeline(config, abortController.signal);
+                break;
+            case 'debate':
+                result = await executeDebate(config, abortController.signal);
+                break;
+            case 'custom':
+                // Custom: just run all in parallel (same as fan_out without synthesis)
+                result = await executeFanOut({ ...config, synthesizerPrompt: undefined }, abortController.signal);
+                break;
+            default:
+                throw new Error(`Unknown orchestration pattern: ${config.pattern}`);
+        }
+        log.info(`Orchestration complete: ${config.name} - ${result.success ? 'success' : 'failed'} in ${result.totalDurationMs}ms (${result.totalTokens} tokens)`);
+        return result;
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        activeOrchestrations.delete(config.id);
+    }
+}
+/**
+ * Cancel a running orchestration.
+ */
+export function cancelOrchestration(id) {
+    const controller = activeOrchestrations.get(id);
+    if (controller) {
+        controller.abort();
+        activeOrchestrations.delete(id);
+        log.info(`Cancelled orchestration: ${id}`);
+        return true;
+    }
+    return false;
+}
+/**
+ * List active orchestrations.
+ */
+export function listActiveOrchestrations() {
+    return [...activeOrchestrations.keys()];
+}
+const DEFAULT_ORCHESTRATOR_CONFIG = {
+    maxConcurrent: 3,
+    timeoutMs: 300_000,
+};
+// Singleton instance
+let _instance;
+/**
+ * Class-based orchestrator for fan-out parallel sub-agent tasks.
+ *
+ * The caller provides an `apiCall` function that wraps the actual LLM API —
+ * following the same injected-client pattern used by ContextCompactor.
+ *
+ * Usage:
+ * ```ts
+ * const orch = getAgentOrchestrator({ maxConcurrent: 2 });
+ * const results = await orch.dispatch([
+ *   { description: 'Summarise file A', prompt: '...' },
+ *   { description: 'Summarise file B', prompt: '...' },
+ * ], myApiCall);
+ * console.log(orch.synthesize(results));
+ * ```
+ */
+export class AgentOrchestrator {
+    tasks = new Map();
+    config;
+    /** Number of tasks currently in the 'running' state. */
+    running = 0;
+    /** Cancelled task IDs — checked before executing. */
+    cancelled = new Set();
+    constructor(config) {
+        this.config = { ...DEFAULT_ORCHESTRATOR_CONFIG, ...config };
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Dispatch multiple sub-tasks in parallel, respecting `maxConcurrent`.
+     * Resolves when every task has either completed, failed, or timed out.
+     */
+    async dispatch(taskDefs, apiCall) {
+        // Build task objects
+        const newTasks = taskDefs.map((def) => ({
+            id: randomUUID(),
+            description: def.description,
+            prompt: def.prompt,
+            status: 'pending',
+            tokensUsed: 0,
+        }));
+        for (const task of newTasks) {
+            this.tasks.set(task.id, task);
+        }
+        // Semaphore: release a "slot" whenever a task finishes so the next one starts.
+        const queue = [...newTasks];
+        const workers = [];
+        const next = () => {
+            const task = queue.shift();
+            if (!task)
+                return Promise.resolve();
+            if (this.cancelled.has(task.id)) {
+                task.status = 'failed';
+                task.error = 'Task was cancelled before it started';
+                return next();
+            }
+            this.running++;
+            return this.runTask(task, apiCall).then(() => {
+                this.running--;
+                return next();
+            });
+        };
+        // Seed up to maxConcurrent workers.
+        const concurrency = Math.min(this.config.maxConcurrent, newTasks.length);
+        for (let i = 0; i < concurrency; i++) {
+            workers.push(next());
+        }
+        await Promise.all(workers);
+        return newTasks;
+    }
+    /**
+     * Run a single sub-agent task with timeout and cancellation support.
+     * Mutates `task` in place and returns it.
+     */
+    async runTask(task, apiCall) {
+        if (this.cancelled.has(task.id)) {
+            task.status = 'failed';
+            task.error = 'Task was cancelled';
+            task.completedAt = Date.now();
+            return task;
+        }
+        task.status = 'running';
+        task.startedAt = Date.now();
+        const timeoutMs = this.config.timeoutMs;
+        try {
+            const result = await Promise.race([
+                apiCall(task.prompt),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Task "${task.description}" timed out after ${timeoutMs}ms`)), timeoutMs)),
+            ]);
+            // Re-check cancellation — task may have been cancelled while the API call was in flight.
+            if (this.cancelled.has(task.id)) {
+                task.status = 'failed';
+                task.error = 'Task was cancelled';
+            }
+            else {
+                task.status = 'completed';
+                task.result = result;
+            }
+        }
+        catch (error) {
+            task.status = 'failed';
+            task.error = error instanceof Error ? error.message : String(error);
+            log.warn(`Sub-agent task failed: ${task.description} — ${task.error}`);
+        }
+        finally {
+            task.completedAt = Date.now();
+        }
+        return task;
+    }
+    /**
+     * Return a snapshot of all tasks tracked by this orchestrator.
+     */
+    getStatus() {
+        return [...this.tasks.values()];
+    }
+    /**
+     * Mark a task as cancelled.  If it is still pending it will be skipped
+     * entirely; if it is already running the next post-API-call check will
+     * mark it failed.
+     */
+    cancel(taskId) {
+        this.cancelled.add(taskId);
+        const task = this.tasks.get(taskId);
+        if (task && task.status === 'pending') {
+            task.status = 'failed';
+            task.error = 'Task was cancelled';
+            task.completedAt = Date.now();
+            log.info(`Cancelled pending task: ${taskId}`);
+        }
+    }
+    /**
+     * Build a markdown summary of completed task results.
+     *
+     * ```markdown
+     * ## Task Results
+     * ### 1. Summarise file A ✓
+     * <result text>
+     * ### 2. Summarise file B ✗
+     * Error: timed out after 300000ms
+     * ```
+     */
+    synthesize(tasks) {
+        const lines = ['## Task Results', ''];
+        tasks.forEach((task, index) => {
+            const marker = task.status === 'completed' ? '✓' : '✗';
+            lines.push(`### ${index + 1}. ${task.description} ${marker}`);
+            if (task.status === 'completed' && task.result) {
+                lines.push(task.result);
+            }
+            else if (task.status === 'failed') {
+                lines.push(`Error: ${task.error ?? 'Unknown error'}`);
+            }
+            else {
+                lines.push(`Status: ${task.status}`);
+            }
+            lines.push('');
+        });
+        return lines.join('\n').trimEnd();
+    }
+    /**
+     * Wait until all currently-tracked tasks have left the 'pending' or
+     * 'running' state, or until the optional `timeoutMs` elapses.
+     *
+     * Resolves with the current task snapshot once settled.
+     */
+    async waitAll(timeoutMs) {
+        const poll = () => [...this.tasks.values()].every((t) => t.status === 'completed' || t.status === 'failed');
+        if (poll())
+            return this.getStatus();
+        const deadline = timeoutMs ? Date.now() + timeoutMs : Infinity;
+        const INTERVAL = 50;
+        return new Promise((resolve) => {
+            const check = () => {
+                if (poll()) {
+                    resolve(this.getStatus());
+                    return;
+                }
+                if (Date.now() >= deadline) {
+                    resolve(this.getStatus());
+                    return;
+                }
+                setTimeout(check, INTERVAL);
+            };
+            setTimeout(check, INTERVAL);
+        });
+    }
+}
+/**
+ * Return a lazily-created singleton `AgentOrchestrator`.
+ * Pass `config` on first call to customise defaults; subsequent calls with
+ * a different config will replace the singleton.
+ */
+export function getAgentOrchestrator(config) {
+    if (!_instance || config) {
+        _instance = new AgentOrchestrator(config);
+    }
+    return _instance;
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/agents/permissions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Permission Dialog System
+ *
+ * Manages per-session tool permissions with configurable rules.
+ * Dangerous tools always prompt; cautious tools prompt once then remember;
+ * safe tools (or unknown tools) are auto-allowed.
+ */
+export type PermissionLevel = 'safe' | 'cautious' | 'dangerous';
+export type PermissionResponse = 'allow' | 'deny' | 'always_allow' | 'always_deny';
+export interface PermissionRule {
+    toolName: string;
+    level: PermissionLevel;
+    reason: string;
+}
+export interface PermissionState {
+    /** Tools permanently allowed for this session */
+    autoAllow: Set<string>;
+    /** Tools permanently denied for this session */
+    autoDeny: Set<string>;
+}
+export interface PermissionCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+export declare const DEFAULT_PERMISSION_RULES: PermissionRule[];
+type PromptCallback = (toolName: string, args: unknown, rule: PermissionRule) => Promise<PermissionResponse>;
+export declare class PermissionManager {
+    private state;
+    private rules;
+    private promptCallback?;
+    constructor(rules?: PermissionRule[]);
+    /**
+     * Register the interactive prompt callback.
+     * Without this, all tools (including dangerous ones) are allowed — non-interactive mode.
+     */
+    setPromptCallback(cb: PromptCallback): void;
+    /**
+     * Check whether a tool call is permitted.
+     *
+     * Resolution order:
+     * 1. autoAllow set  → allowed immediately
+     * 2. autoDeny set   → denied immediately
+     * 3. No rule / safe → allowed
+     * 4. cautious/dangerous → invoke promptCallback
+     *    - allow       → allow once
+     *    - deny        → deny once
+     *    - always_allow → add to autoAllow, allow
+     *    - always_deny  → add to autoDeny, deny
+     * 5. No callback registered → allow (non-interactive)
+     */
+    check(toolName: string, args?: unknown): Promise<PermissionCheckResult>;
+    /**
+     * Return the permission level for a tool, or 'safe' if no rule exists.
+     */
+    getLevel(toolName: string): PermissionLevel;
+    /**
+     * Clear session-level autoAllow/autoDeny sets.
+     * Useful when starting a fresh session without constructing a new manager.
+     */
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=permissions.d.ts.map

package/dist/agents/permissions.js

@@ -0,0 +1,138 @@
+/**
+ * Permission Dialog System
+ *
+ * Manages per-session tool permissions with configurable rules.
+ * Dangerous tools always prompt; cautious tools prompt once then remember;
+ * safe tools (or unknown tools) are auto-allowed.
+ */
+import { createContextualLogger } from '../utils/logger.js';
+const log = createContextualLogger('PermissionManager');
+// ---------------------------------------------------------------------------
+// Default rules
+// ---------------------------------------------------------------------------
+export const DEFAULT_PERMISSION_RULES = [
+    // Dangerous — always ask
+    { toolName: 'bash', level: 'dangerous', reason: 'Executes arbitrary shell commands' },
+    { toolName: 'exec', level: 'dangerous', reason: 'Executes arbitrary shell commands' },
+    { toolName: 'delete_file', level: 'dangerous', reason: 'Permanently deletes files' },
+    { toolName: 'git_push', level: 'dangerous', reason: 'Pushes changes to remote repository' },
+    {
+        toolName: 'git_force_push',
+        level: 'dangerous',
+        reason: 'Force pushes, potentially losing remote changes',
+    },
+    // Cautious — ask first time, then remember
+    { toolName: 'write_file', level: 'cautious', reason: 'Modifies files on disk' },
+    { toolName: 'patch_file', level: 'cautious', reason: 'Modifies files on disk' },
+    { toolName: 'move_file', level: 'cautious', reason: 'Moves/renames files' },
+    { toolName: 'git_commit', level: 'cautious', reason: 'Creates git commits' },
+    { toolName: 'git_branch', level: 'cautious', reason: 'Creates/switches git branches' },
+    // Safe — auto-allow (read_file, search_files, git_status, git_diff, etc.)
+];
+export class PermissionManager {
+    state;
+    rules;
+    promptCallback;
+    constructor(rules = DEFAULT_PERMISSION_RULES) {
+        this.state = {
+            autoAllow: new Set(),
+            autoDeny: new Set(),
+        };
+        this.rules = new Map();
+        for (const rule of rules) {
+            this.rules.set(rule.toolName, rule);
+        }
+    }
+    /**
+     * Register the interactive prompt callback.
+     * Without this, all tools (including dangerous ones) are allowed — non-interactive mode.
+     */
+    setPromptCallback(cb) {
+        this.promptCallback = cb;
+    }
+    /**
+     * Check whether a tool call is permitted.
+     *
+     * Resolution order:
+     * 1. autoAllow set  → allowed immediately
+     * 2. autoDeny set   → denied immediately
+     * 3. No rule / safe → allowed
+     * 4. cautious/dangerous → invoke promptCallback
+     *    - allow       → allow once
+     *    - deny        → deny once
+     *    - always_allow → add to autoAllow, allow
+     *    - always_deny  → add to autoDeny, deny
+     * 5. No callback registered → allow (non-interactive)
+     */
+    async check(toolName, args) {
+        // 1. Session-level auto-allow
+        if (this.state.autoAllow.has(toolName)) {
+            log.debug('Tool auto-allowed (session rule)', { tool: toolName });
+            return { allowed: true };
+        }
+        // 2. Session-level auto-deny
+        if (this.state.autoDeny.has(toolName)) {
+            log.info('Tool auto-denied (session rule)', { tool: toolName });
+            return { allowed: false, reason: `Tool "${toolName}" has been denied for this session` };
+        }
+        // 3. Look up permission rule
+        const rule = this.rules.get(toolName);
+        if (!rule || rule.level === 'safe') {
+            return { allowed: true };
+        }
+        // 4. cautious or dangerous — need user confirmation
+        if (!this.promptCallback) {
+            // Non-interactive mode: allow but log
+            log.warn('No prompt callback registered — allowing tool in non-interactive mode', {
+                tool: toolName,
+                level: rule.level,
+            });
+            return { allowed: true };
+        }
+        log.debug('Prompting user for permission', { tool: toolName, level: rule.level });
+        let response;
+        try {
+            response = await this.promptCallback(toolName, args, rule);
+        }
+        catch (error) {
+            log.error('[PermissionManager] Prompt callback threw', {
+                tool: toolName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Fail-safe: deny on callback error
+            return { allowed: false, reason: 'Permission prompt failed' };
+        }
+        switch (response) {
+            case 'allow':
+                log.debug('User allowed tool (once)', { tool: toolName });
+                return { allowed: true };
+            case 'deny':
+                log.info('User denied tool (once)', { tool: toolName });
+                return { allowed: false, reason: `User denied "${toolName}"` };
+            case 'always_allow':
+                this.state.autoAllow.add(toolName);
+                log.info('User always-allowed tool for session', { tool: toolName });
+                return { allowed: true };
+            case 'always_deny':
+                this.state.autoDeny.add(toolName);
+                log.info('User always-denied tool for session', { tool: toolName });
+                return { allowed: false, reason: `User permanently denied "${toolName}" for this session` };
+        }
+    }
+    /**
+     * Return the permission level for a tool, or 'safe' if no rule exists.
+     */
+    getLevel(toolName) {
+        return this.rules.get(toolName)?.level ?? 'safe';
+    }
+    /**
+     * Clear session-level autoAllow/autoDeny sets.
+     * Useful when starting a fresh session without constructing a new manager.
+     */
+    reset() {
+        this.state.autoAllow.clear();
+        this.state.autoDeny.clear();
+        log.debug('PermissionManager session state reset');
+    }
+}
+//# sourceMappingURL=permissions.js.map