byterover-cli 0.2.1 → 0.3.1

package/dist/infra/cipher/tools/policy-engine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Policy Engine Implementation.
+ *
+ * Rule-based ALLOW/DENY decisions for tool execution.
+ * Designed for autonomous execution without user confirmation.
+ *
+ * Rules are evaluated in order - first matching rule wins.
+ * If no rule matches, the default decision is used.
+ */
+import type { IPolicyEngine, PolicyDecision, PolicyEvaluationResult, PolicyRule } from '../../../core/interfaces/cipher/i-policy-engine.js';
+/**
+ * Configuration options for PolicyEngine.
+ */
+export interface PolicyEngineConfig {
+    /**
+     * Default decision when no rule matches.
+     * @default 'ALLOW'
+     */
+    defaultDecision?: PolicyDecision;
+}
+/**
+ * Policy Engine implementation.
+ *
+ * Evaluates tool execution requests against a set of rules.
+ * Rules are evaluated in order - first matching rule wins.
+ */
+export declare class PolicyEngine implements IPolicyEngine {
+    private readonly defaultDecision;
+    private rules;
+    /**
+     * Create a new PolicyEngine.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config?: PolicyEngineConfig);
+    /**
+     * Add a policy rule.
+     * Rules are evaluated in the order they are added.
+     *
+     * @param rule - The policy rule to add
+     */
+    addRule(rule: PolicyRule): void;
+    /**
+     * Add multiple policy rules at once.
+     *
+     * @param rules - The policy rules to add
+     */
+    addRules(rules: PolicyRule[]): void;
+    /**
+     * Evaluate a tool execution request against policy rules.
+     *
+     * Rules are evaluated in order. First matching rule wins.
+     * If no rule matches, returns the default decision.
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Arguments for the tool
+     * @returns Policy evaluation result with decision and reason
+     */
+    evaluate(toolName: string, args: Record<string, unknown>): PolicyEvaluationResult;
+    /**
+     * Get all registered policy rules.
+     *
+     * @returns Read-only array of policy rules
+     */
+    getRules(): readonly PolicyRule[];
+    /**
+     * Remove a policy rule by name.
+     *
+     * @param name - The name of the rule to remove
+     */
+    removeRule(name: string): void;
+    /**
+     * Check if a tool name matches a pattern.
+     *
+     * @param toolName - The tool name to check
+     * @param pattern - The pattern to match against
+     * @returns True if the tool name matches the pattern
+     */
+    private matchesPattern;
+}

package/dist/infra/cipher/tools/policy-engine.js

@@ -0,0 +1,110 @@
+/**
+ * Policy Engine Implementation.
+ *
+ * Rule-based ALLOW/DENY decisions for tool execution.
+ * Designed for autonomous execution without user confirmation.
+ *
+ * Rules are evaluated in order - first matching rule wins.
+ * If no rule matches, the default decision is used.
+ */
+/**
+ * Policy Engine implementation.
+ *
+ * Evaluates tool execution requests against a set of rules.
+ * Rules are evaluated in order - first matching rule wins.
+ */
+export class PolicyEngine {
+    defaultDecision;
+    rules = [];
+    /**
+     * Create a new PolicyEngine.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config = {}) {
+        this.defaultDecision = config.defaultDecision ?? 'ALLOW';
+    }
+    /**
+     * Add a policy rule.
+     * Rules are evaluated in the order they are added.
+     *
+     * @param rule - The policy rule to add
+     */
+    addRule(rule) {
+        this.rules.push(rule);
+    }
+    /**
+     * Add multiple policy rules at once.
+     *
+     * @param rules - The policy rules to add
+     */
+    addRules(rules) {
+        for (const rule of rules) {
+            this.addRule(rule);
+        }
+    }
+    /**
+     * Evaluate a tool execution request against policy rules.
+     *
+     * Rules are evaluated in order. First matching rule wins.
+     * If no rule matches, returns the default decision.
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Arguments for the tool
+     * @returns Policy evaluation result with decision and reason
+     */
+    evaluate(toolName, args) {
+        for (const rule of this.rules) {
+            // Check if tool pattern matches
+            if (!this.matchesPattern(toolName, rule.toolPattern)) {
+                continue;
+            }
+            // Check condition if present
+            if (rule.condition && !rule.condition(toolName, args)) {
+                continue;
+            }
+            // Rule matches - return its decision
+            return {
+                decision: rule.decision,
+                reason: rule.reason,
+                rule,
+            };
+        }
+        // No rule matched - return default decision
+        return {
+            decision: this.defaultDecision,
+            reason: 'No matching rule, using default policy',
+        };
+    }
+    /**
+     * Get all registered policy rules.
+     *
+     * @returns Read-only array of policy rules
+     */
+    getRules() {
+        return this.rules;
+    }
+    /**
+     * Remove a policy rule by name.
+     *
+     * @param name - The name of the rule to remove
+     */
+    removeRule(name) {
+        this.rules = this.rules.filter((r) => r.name !== name);
+    }
+    /**
+     * Check if a tool name matches a pattern.
+     *
+     * @param toolName - The tool name to check
+     * @param pattern - The pattern to match against
+     * @returns True if the tool name matches the pattern
+     */
+    matchesPattern(toolName, pattern) {
+        if (typeof pattern === 'string') {
+            // Exact match or wildcard
+            return toolName === pattern || pattern === '*';
+        }
+        // Regex pattern
+        return pattern.test(toolName);
+    }
+}

package/dist/infra/cipher/tools/tool-invocation-queue.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Tool Invocation Queue System
+ *
+ * Manages queuing and execution of tool invocations with:
+ * - Priority-based ordering
+ * - Concurrent execution with configurable limits
+ * - Queue state management
+ * - Batch execution support
+ */
+import type { ToolInvocation, ToolInvocationResult } from './tool-invocation.js';
+/**
+ * Priority levels for tool invocations
+ */
+export declare enum ToolInvocationPriority {
+    /**
+     * Critical priority - Execute immediately
+     */
+    CRITICAL = "CRITICAL",
+    /**
+     * High priority - Execute before normal
+     */
+    HIGH = "HIGH",
+    /**
+     * Low priority - Execute after normal
+     */
+    LOW = "LOW",
+    /**
+     * Normal priority - Default priority
+     */
+    NORMAL = "NORMAL"
+}
+/**
+ * Queued invocation with priority and metadata
+ */
+export interface QueuedInvocation {
+    /**
+     * The tool invocation
+     */
+    invocation: ToolInvocation;
+    /**
+     * Priority level
+     */
+    priority: ToolInvocationPriority;
+    /**
+     * Timestamp when queued
+     */
+    queuedAt: number;
+}
+/**
+ * Configuration for queue execution
+ */
+export interface QueueExecutionConfig {
+    /**
+     * Maximum number of concurrent executions
+     * @default 5
+     */
+    maxConcurrent?: number;
+    /**
+     * Whether to stop on first error
+     * @default false
+     */
+    stopOnError?: boolean;
+}
+/**
+ * Result from queue execution
+ */
+export interface QueueExecutionResult {
+    /**
+     * Number of completed executions
+     */
+    completed: number;
+    /**
+     * Duration of queue execution in milliseconds
+     */
+    durationMs: number;
+    /**
+     * Number of failed executions
+     */
+    failed: number;
+    /**
+     * Individual invocation results
+     */
+    results: Map<string, ToolInvocationResult>;
+    /**
+     * Number of skipped executions (due to stopOnError)
+     */
+    skipped: number;
+}
+/**
+ * Default execution configuration
+ */
+export declare const DEFAULT_QUEUE_EXECUTION_CONFIG: Required<QueueExecutionConfig>;
+/**
+ * Tool invocation queue for managing concurrent tool execution
+ *
+ * Features:
+ * - Priority-based ordering
+ * - Configurable concurrency limits
+ * - Batch execution with error handling
+ * - Queue state management
+ */
+export declare class ToolInvocationQueue {
+    /**
+     * Execution configuration
+     */
+    private readonly config;
+    /**
+     * Currently executing invocations
+     */
+    private readonly executing;
+    /**
+     * Queue of pending invocations
+     */
+    private readonly queue;
+    /**
+     * Create a new tool invocation queue
+     *
+     * @param config - Execution configuration
+     */
+    constructor(config?: QueueExecutionConfig);
+    /**
+     * Add an invocation to the queue
+     *
+     * @param invocation - Tool invocation to queue
+     * @param priority - Priority level (default: NORMAL)
+     * @returns True if added, false if already queued
+     */
+    add(invocation: ToolInvocation, priority?: ToolInvocationPriority): boolean;
+    /**
+     * Add multiple invocations to the queue
+     *
+     * @param invocations - Array of invocations with optional priority
+     * @returns Number of invocations added
+     */
+    addBatch(invocations: Array<{
+        invocation: ToolInvocation;
+        priority?: ToolInvocationPriority;
+    }>): number;
+    /**
+     * Clear all queued invocations
+     *
+     * Does not affect currently executing invocations.
+     * For autonomous mode, invocations are simply removed without status change.
+     *
+     * @returns Number of invocations cleared
+     */
+    clear(): number;
+    /**
+     * Execute all queued invocations
+     *
+     * Executes invocations with concurrency limit and priority ordering.
+     *
+     * @returns Execution result with stats and individual results
+     */
+    execute(): Promise<QueueExecutionResult>;
+    /**
+     * Get number of currently executing invocations
+     */
+    getExecutingCount(): number;
+    /**
+     * Get number of queued invocations
+     */
+    getQueuedCount(): number;
+    /**
+     * Check if invocation is queued
+     *
+     * @param invocationId - ID to check
+     * @returns True if queued
+     */
+    isQueued(invocationId: string): boolean;
+    /**
+     * Peek at next invocation without removing it
+     *
+     * @returns Next invocation or undefined if queue is empty
+     */
+    peek(): ToolInvocation | undefined;
+    /**
+     * Remove a queued invocation from the queue.
+     *
+     * For autonomous mode, invocations are simply removed without status change.
+     * The invocation remains in SCHEDULED state but will not be executed.
+     *
+     * @param invocationId - ID of invocation to remove
+     * @returns True if removed, false if not found
+     */
+    remove(invocationId: string): boolean;
+    /**
+     * Sort queue by priority and queue time
+     */
+    private sortQueue;
+}

package/dist/infra/cipher/tools/tool-invocation-queue.js

@@ -0,0 +1,254 @@
+/**
+ * Tool Invocation Queue System
+ *
+ * Manages queuing and execution of tool invocations with:
+ * - Priority-based ordering
+ * - Concurrent execution with configurable limits
+ * - Queue state management
+ * - Batch execution support
+ */
+import { ToolInvocationStatus } from './tool-invocation.js';
+/**
+ * Priority levels for tool invocations
+ */
+export var ToolInvocationPriority;
+(function (ToolInvocationPriority) {
+    /**
+     * Critical priority - Execute immediately
+     */
+    ToolInvocationPriority["CRITICAL"] = "CRITICAL";
+    /**
+     * High priority - Execute before normal
+     */
+    ToolInvocationPriority["HIGH"] = "HIGH";
+    /**
+     * Low priority - Execute after normal
+     */
+    ToolInvocationPriority["LOW"] = "LOW";
+    /**
+     * Normal priority - Default priority
+     */
+    ToolInvocationPriority["NORMAL"] = "NORMAL";
+})(ToolInvocationPriority || (ToolInvocationPriority = {}));
+/**
+ * Priority ordering for queue sorting
+ */
+const PRIORITY_ORDER = {
+    [ToolInvocationPriority.CRITICAL]: 0,
+    [ToolInvocationPriority.HIGH]: 1,
+    [ToolInvocationPriority.LOW]: 3,
+    [ToolInvocationPriority.NORMAL]: 2,
+};
+/**
+ * Default execution configuration
+ */
+export const DEFAULT_QUEUE_EXECUTION_CONFIG = {
+    maxConcurrent: 5,
+    stopOnError: false,
+};
+/**
+ * Tool invocation queue for managing concurrent tool execution
+ *
+ * Features:
+ * - Priority-based ordering
+ * - Configurable concurrency limits
+ * - Batch execution with error handling
+ * - Queue state management
+ */
+export class ToolInvocationQueue {
+    /**
+     * Execution configuration
+     */
+    config;
+    /**
+     * Currently executing invocations
+     */
+    executing = new Map();
+    /**
+     * Queue of pending invocations
+     */
+    queue = [];
+    /**
+     * Create a new tool invocation queue
+     *
+     * @param config - Execution configuration
+     */
+    constructor(config) {
+        this.config = {
+            ...DEFAULT_QUEUE_EXECUTION_CONFIG,
+            ...config,
+        };
+    }
+    /**
+     * Add an invocation to the queue
+     *
+     * @param invocation - Tool invocation to queue
+     * @param priority - Priority level (default: NORMAL)
+     * @returns True if added, false if already queued
+     */
+    add(invocation, priority = ToolInvocationPriority.NORMAL) {
+        // Check if already queued or executing
+        if (this.isQueued(invocation.id) || this.executing.has(invocation.id)) {
+            return false;
+        }
+        // Add to queue
+        this.queue.push({
+            invocation,
+            priority,
+            queuedAt: Date.now(),
+        });
+        // Sort queue by priority
+        this.sortQueue();
+        return true;
+    }
+    /**
+     * Add multiple invocations to the queue
+     *
+     * @param invocations - Array of invocations with optional priority
+     * @returns Number of invocations added
+     */
+    addBatch(invocations) {
+        let added = 0;
+        for (const { invocation, priority } of invocations) {
+            if (this.add(invocation, priority)) {
+                added++;
+            }
+        }
+        return added;
+    }
+    /**
+     * Clear all queued invocations
+     *
+     * Does not affect currently executing invocations.
+     * For autonomous mode, invocations are simply removed without status change.
+     *
+     * @returns Number of invocations cleared
+     */
+    clear() {
+        const count = this.queue.length;
+        // Simply clear the queue (no status change needed for autonomous mode)
+        this.queue.length = 0;
+        return count;
+    }
+    /**
+     * Execute all queued invocations
+     *
+     * Executes invocations with concurrency limit and priority ordering.
+     *
+     * @returns Execution result with stats and individual results
+     */
+    async execute() {
+        const startTime = Date.now();
+        const results = new Map();
+        let completed = 0;
+        let failed = 0;
+        let skipped = 0;
+        let shouldStop = false;
+        // Execute in batches based on concurrency limit
+        while (this.queue.length > 0 && !shouldStop) {
+            // Take up to maxConcurrent invocations from queue
+            const batch = this.queue.splice(0, this.config.maxConcurrent);
+            // Mark as executing
+            for (const { invocation } of batch) {
+                this.executing.set(invocation.id, invocation);
+            }
+            // Execute batch concurrently
+            // eslint-disable-next-line no-await-in-loop
+            const batchResults = await Promise.all(batch.map(async ({ invocation }) => {
+                const result = await invocation.execute();
+                this.executing.delete(invocation.id);
+                return { invocationId: invocation.id, result };
+            }));
+            // Process batch results
+            for (const { invocationId, result } of batchResults) {
+                results.set(invocationId, result);
+                if (result.status === ToolInvocationStatus.COMPLETED) {
+                    completed++;
+                }
+                else if (result.status === ToolInvocationStatus.ERROR) {
+                    failed++;
+                    // Stop on error if configured
+                    if (this.config.stopOnError) {
+                        shouldStop = true;
+                        break;
+                    }
+                }
+            }
+        }
+        // Count skipped invocations (remaining in queue when stopOnError triggered)
+        if (shouldStop) {
+            skipped = this.queue.length;
+            // Simply clear remaining (no status change needed for autonomous mode)
+            this.queue.length = 0;
+        }
+        return {
+            completed,
+            durationMs: Date.now() - startTime,
+            failed,
+            results,
+            skipped,
+        };
+    }
+    /**
+     * Get number of currently executing invocations
+     */
+    getExecutingCount() {
+        return this.executing.size;
+    }
+    /**
+     * Get number of queued invocations
+     */
+    getQueuedCount() {
+        return this.queue.length;
+    }
+    /**
+     * Check if invocation is queued
+     *
+     * @param invocationId - ID to check
+     * @returns True if queued
+     */
+    isQueued(invocationId) {
+        return this.queue.some((q) => q.invocation.id === invocationId);
+    }
+    /**
+     * Peek at next invocation without removing it
+     *
+     * @returns Next invocation or undefined if queue is empty
+     */
+    peek() {
+        return this.queue[0]?.invocation;
+    }
+    /**
+     * Remove a queued invocation from the queue.
+     *
+     * For autonomous mode, invocations are simply removed without status change.
+     * The invocation remains in SCHEDULED state but will not be executed.
+     *
+     * @param invocationId - ID of invocation to remove
+     * @returns True if removed, false if not found
+     */
+    remove(invocationId) {
+        // Find in queue
+        const index = this.queue.findIndex((q) => q.invocation.id === invocationId);
+        if (index === -1) {
+            return false;
+        }
+        // Remove from queue (no status change needed for autonomous mode)
+        this.queue.splice(index, 1);
+        return true;
+    }
+    /**
+     * Sort queue by priority and queue time
+     */
+    sortQueue() {
+        this.queue.sort((a, b) => {
+            // First sort by priority
+            const priorityDiff = PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority];
+            if (priorityDiff !== 0) {
+                return priorityDiff;
+            }
+            // Then by queue time (FIFO within same priority)
+            return a.queuedAt - b.queuedAt;
+        });
+    }
+}