@compilr-dev/agents 0.0.1

package/dist/permissions/manager.js

@@ -0,0 +1,379 @@
+/**
+ * PermissionManager - Manages tool-level permissions
+ *
+ * Provides fine-grained control over which tools can execute and when
+ * user approval is required.
+ *
+ * @example
+ * ```typescript
+ * const permissions = new PermissionManager({
+ *   defaultLevel: 'always',
+ *   rules: [
+ *     { toolName: 'bash', level: 'once', description: 'Shell commands' },
+ *     { toolName: 'write_file', level: 'session', description: 'File writes' },
+ *     { toolName: 'delete_*', level: 'deny', description: 'Delete operations' },
+ *   ],
+ *   onPermissionRequest: async (request) => {
+ *     return await askUser(`Allow ${request.toolName}?`);
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Default permission rules for commonly dangerous tools
+ */
+const DEFAULT_PERMISSION_RULES = [
+    {
+        toolName: 'bash',
+        level: 'once',
+        description: 'Execute shell commands',
+        tags: ['shell', 'dangerous'],
+    },
+    {
+        toolName: 'write_file',
+        level: 'session',
+        description: 'Write to files',
+        tags: ['filesystem'],
+    },
+    {
+        toolName: 'edit',
+        level: 'session',
+        description: 'Edit files',
+        tags: ['filesystem'],
+    },
+];
+/**
+ * Default preview generator that formats tool input for display
+ */
+function defaultPreviewGenerator(toolName, input) {
+    // Generate previews for common tools
+    switch (toolName) {
+        case 'bash': {
+            const command = input.command;
+            if (typeof command === 'string') {
+                return `Execute: ${command.slice(0, 200)}${command.length > 200 ? '...' : ''}`;
+            }
+            break;
+        }
+        case 'write_file':
+        case 'writeFile': {
+            const path = input.path ?? input.file_path;
+            if (typeof path === 'string') {
+                return `Write to: ${path}`;
+            }
+            break;
+        }
+        case 'edit': {
+            const path = input.path ?? input.file_path;
+            if (typeof path === 'string') {
+                return `Edit: ${path}`;
+            }
+            break;
+        }
+        case 'read_file':
+        case 'readFile': {
+            const path = input.path ?? input.file_path;
+            if (typeof path === 'string') {
+                return `Read: ${path}`;
+            }
+            break;
+        }
+    }
+    // Generic preview: show first property
+    const keys = Object.keys(input);
+    if (keys.length > 0) {
+        const firstKey = keys[0];
+        const firstValue = input[firstKey];
+        const valueStr = typeof firstValue === 'string'
+            ? firstValue.slice(0, 100)
+            : JSON.stringify(firstValue).slice(0, 100);
+        return `${toolName}: ${firstKey}=${valueStr}${String(firstValue).length > 100 ? '...' : ''}`;
+    }
+    return undefined;
+}
+/**
+ * Convert a tool name pattern to a RegExp
+ * Supports wildcards: * matches any characters
+ */
+function patternToRegex(pattern) {
+    // Escape special regex characters except *
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    // Convert * to .*
+    const regexStr = escaped.replace(/\*/g, '.*');
+    return new RegExp(`^${regexStr}$`);
+}
+/**
+ * PermissionManager handles tool-level permission checks
+ */
+export class PermissionManager {
+    enabled;
+    defaultLevel;
+    rules = new Map();
+    wildcardRules = [];
+    handler;
+    previewGenerator;
+    eventHandlers = new Set();
+    /**
+     * Track session-level permissions that have been granted
+     */
+    sessionGrants = new Set();
+    constructor(options = {}) {
+        this.enabled = options.enabled ?? true;
+        this.defaultLevel = options.defaultLevel ?? 'always';
+        this.handler = options.onPermissionRequest;
+        this.previewGenerator = options.previewGenerator ?? defaultPreviewGenerator;
+        // Add default rules if requested
+        if (options.includeDefaults) {
+            for (const rule of DEFAULT_PERMISSION_RULES) {
+                this.addRule(rule);
+            }
+        }
+        // Add custom rules
+        if (options.rules) {
+            for (const rule of options.rules) {
+                this.addRule(rule);
+            }
+        }
+    }
+    /**
+     * Add a permission rule
+     */
+    addRule(rule) {
+        if (rule.toolName.includes('*')) {
+            // Wildcard pattern
+            this.wildcardRules.push({
+                pattern: patternToRegex(rule.toolName),
+                rule,
+            });
+        }
+        else {
+            // Exact match
+            this.rules.set(rule.toolName, rule);
+        }
+        return this;
+    }
+    /**
+     * Remove a permission rule by tool name
+     */
+    removeRule(toolName) {
+        if (toolName.includes('*')) {
+            const index = this.wildcardRules.findIndex((wr) => wr.rule.toolName === toolName);
+            if (index >= 0) {
+                this.wildcardRules.splice(index, 1);
+                return true;
+            }
+            return false;
+        }
+        return this.rules.delete(toolName);
+    }
+    /**
+     * Get a permission rule by tool name
+     */
+    getRule(toolName) {
+        // Check exact match first
+        const exact = this.rules.get(toolName);
+        if (exact)
+            return exact;
+        // Check wildcard patterns
+        for (const { pattern, rule } of this.wildcardRules) {
+            if (pattern.test(toolName)) {
+                return rule;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get all permission rules
+     */
+    getAllRules() {
+        const exact = Array.from(this.rules.values());
+        const wildcards = this.wildcardRules.map((wr) => wr.rule);
+        return [...exact, ...wildcards];
+    }
+    /**
+     * Check if a tool has permission to execute
+     *
+     * @param toolName - Name of the tool
+     * @param input - Tool input arguments
+     * @returns Permission check result
+     */
+    async check(toolName, input) {
+        // If disabled, always allow
+        if (!this.enabled) {
+            return { allowed: true, level: 'always', askedUser: false };
+        }
+        // Find matching rule
+        const rule = this.getRule(toolName);
+        const level = rule?.level ?? this.defaultLevel;
+        // Handle based on permission level
+        switch (level) {
+            case 'always':
+                this.emit({ type: 'permission:granted', toolName, level, input, rule });
+                return { allowed: true, level, askedUser: false, rule };
+            case 'deny':
+                this.emit({ type: 'permission:denied', toolName, level, input, rule });
+                return {
+                    allowed: false,
+                    level,
+                    askedUser: false,
+                    rule,
+                    reason: rule?.description ?? `Tool '${toolName}' is denied`,
+                };
+            case 'session': {
+                // Check if already granted this session
+                if (this.sessionGrants.has(toolName)) {
+                    this.emit({ type: 'permission:granted', toolName, level, input, rule });
+                    return { allowed: true, level, askedUser: false, rule };
+                }
+                // Ask for permission
+                const allowed = await this.askPermission(toolName, input, level, rule);
+                if (allowed) {
+                    this.sessionGrants.add(toolName);
+                    this.emit({ type: 'permission:session_granted', toolName, level, input, rule });
+                }
+                else {
+                    this.emit({ type: 'permission:denied', toolName, level, input, rule });
+                }
+                return {
+                    allowed,
+                    level,
+                    askedUser: true,
+                    rule,
+                    reason: allowed ? undefined : 'User denied permission',
+                };
+            }
+            case 'once': {
+                // Always ask for permission
+                const allowed = await this.askPermission(toolName, input, level, rule);
+                if (allowed) {
+                    this.emit({ type: 'permission:granted', toolName, level, input, rule });
+                }
+                else {
+                    this.emit({ type: 'permission:denied', toolName, level, input, rule });
+                }
+                return {
+                    allowed,
+                    level,
+                    askedUser: true,
+                    rule,
+                    reason: allowed ? undefined : 'User denied permission',
+                };
+            }
+        }
+    }
+    /**
+     * Check and handle permission, returning whether to proceed
+     *
+     * Convenience method that combines check() with handling
+     */
+    async checkAndProceed(toolName, input) {
+        const result = await this.check(toolName, input);
+        return { proceed: result.allowed, result };
+    }
+    /**
+     * Ask the user for permission
+     */
+    async askPermission(toolName, input, level, rule) {
+        // If no handler, default to allow
+        if (!this.handler) {
+            return true;
+        }
+        const preview = this.previewGenerator(toolName, input);
+        const request = {
+            toolName,
+            input,
+            level,
+            description: rule?.description,
+            preview,
+        };
+        this.emit({ type: 'permission:asked', toolName, level, input, rule });
+        return this.handler(request);
+    }
+    /**
+     * Grant session-level permission for a tool
+     *
+     * This allows the tool to execute for the remainder of the session
+     * without asking again.
+     */
+    grantSession(toolName) {
+        this.sessionGrants.add(toolName);
+    }
+    /**
+     * Revoke session-level permission for a tool
+     */
+    revokeSession(toolName) {
+        return this.sessionGrants.delete(toolName);
+    }
+    /**
+     * Clear all session-level permissions
+     */
+    clearSessionGrants() {
+        this.sessionGrants.clear();
+    }
+    /**
+     * Get all tools with session-level permission
+     */
+    getSessionGrants() {
+        return Array.from(this.sessionGrants);
+    }
+    /**
+     * Check if a tool has session-level permission
+     */
+    hasSessionGrant(toolName) {
+        return this.sessionGrants.has(toolName);
+    }
+    /**
+     * Set the permission level for a tool
+     *
+     * Convenience method for adding/updating a rule
+     */
+    setLevel(toolName, level, description) {
+        const existing = this.rules.get(toolName);
+        this.addRule({
+            toolName,
+            level,
+            description: description ?? existing?.description,
+            tags: existing?.tags,
+        });
+        return this;
+    }
+    /**
+     * Get the effective permission level for a tool
+     */
+    getLevel(toolName) {
+        const rule = this.getRule(toolName);
+        return rule?.level ?? this.defaultLevel;
+    }
+    /**
+     * Register an event handler
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /**
+     * Emit an event
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+    /**
+     * Get the number of rules
+     */
+    get size() {
+        return this.rules.size + this.wildcardRules.length;
+    }
+    /**
+     * Check if permissions are enabled
+     */
+    get isEnabled() {
+        return this.enabled;
+    }
+}

package/dist/permissions/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Tool-level permissions - Explicit approval for specific tools
+ *
+ * Permissions provide fine-grained control over which tools can execute
+ * and when user approval is required.
+ */
+/**
+ * Permission levels for tool execution
+ *
+ * - 'always': Tool can execute without asking (trusted tools)
+ * - 'session': Ask once per session, then allow for remainder
+ * - 'once': Ask every time the tool is invoked
+ * - 'deny': Never allow execution (blocked tools)
+ */
+export type PermissionLevel = 'always' | 'session' | 'once' | 'deny';
+/**
+ * Permission rule for a specific tool
+ */
+export interface ToolPermission {
+    /**
+     * Tool name or pattern (supports wildcards like 'bash*', '*_file')
+     */
+    toolName: string;
+    /**
+     * Permission level for this tool
+     */
+    level: PermissionLevel;
+    /**
+     * Human-readable description of why permission is needed
+     */
+    description?: string;
+    /**
+     * Tags for grouping permissions
+     */
+    tags?: string[];
+}
+/**
+ * Permission request passed to the handler
+ */
+export interface PermissionRequest {
+    /**
+     * Name of the tool requesting permission
+     */
+    toolName: string;
+    /**
+     * Input arguments for the tool
+     */
+    input: Record<string, unknown>;
+    /**
+     * Permission level that triggered the request
+     */
+    level: PermissionLevel;
+    /**
+     * Description of why permission is needed
+     */
+    description?: string;
+    /**
+     * Formatted preview of what the tool will do
+     */
+    preview?: string;
+}
+/**
+ * Result of a permission check
+ */
+export interface PermissionCheckResult {
+    /**
+     * Whether execution is allowed
+     */
+    allowed: boolean;
+    /**
+     * The permission level that applied
+     */
+    level: PermissionLevel;
+    /**
+     * Whether user confirmation was required
+     */
+    askedUser: boolean;
+    /**
+     * The tool permission rule that matched (if any)
+     */
+    rule?: ToolPermission;
+    /**
+     * Reason for denial (if not allowed)
+     */
+    reason?: string;
+}
+/**
+ * Handler called when permission is needed
+ *
+ * @param request - Information about the permission request
+ * @returns true to allow execution, false to deny
+ *
+ * @example
+ * ```typescript
+ * const handler: PermissionHandler = async (request) => {
+ *   // Show UI prompt to user
+ *   const allowed = await showConfirmDialog(
+ *     `Allow ${request.toolName}?`,
+ *     request.description
+ *   );
+ *   return allowed;
+ * };
+ * ```
+ */
+export type PermissionHandler = (request: PermissionRequest) => boolean | Promise<boolean>;
+/**
+ * Preview generator for permission requests
+ *
+ * @param toolName - Name of the tool
+ * @param input - Tool input arguments
+ * @returns Human-readable preview of the operation
+ */
+export type PreviewGenerator = (toolName: string, input: Record<string, unknown>) => string | undefined;
+/**
+ * Configuration for the PermissionManager
+ */
+export interface PermissionManagerOptions {
+    /**
+     * Enable permission checking (default: true)
+     */
+    enabled?: boolean;
+    /**
+     * Default permission level for tools not explicitly configured
+     * @default 'always'
+     */
+    defaultLevel?: PermissionLevel;
+    /**
+     * Handler called when permission is needed (for 'session' and 'once' levels)
+     */
+    onPermissionRequest?: PermissionHandler;
+    /**
+     * Tool-specific permission rules
+     */
+    rules?: ToolPermission[];
+    /**
+     * Custom preview generator for permission requests
+     */
+    previewGenerator?: PreviewGenerator;
+    /**
+     * Whether to include default permission rules for dangerous tools
+     * @default false
+     */
+    includeDefaults?: boolean;
+}
+/**
+ * Event types for permission operations
+ */
+export type PermissionEventType = 'permission:granted' | 'permission:denied' | 'permission:asked' | 'permission:session_granted';
+/**
+ * Permission event payload
+ */
+export interface PermissionEvent {
+    type: PermissionEventType;
+    toolName: string;
+    level: PermissionLevel;
+    input?: Record<string, unknown>;
+    rule?: ToolPermission;
+}
+/**
+ * Event handler for permission events
+ */
+export type PermissionEventHandler = (event: PermissionEvent) => void;

package/dist/permissions/types.js

@@ -0,0 +1,7 @@
+/**
+ * Tool-level permissions - Explicit approval for specific tools
+ *
+ * Permissions provide fine-grained control over which tools can execute
+ * and when user approval is required.
+ */
+export {};

package/dist/providers/claude.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ClaudeProvider - Anthropic Claude API implementation
+ *
+ * @example
+ * ```typescript
+ * const provider = new ClaudeProvider({
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ * });
+ *
+ * const agent = new Agent({ provider });
+ * ```
+ */
+import type { LLMProvider, Message, ChatOptions, StreamChunk } from './types.js';
+/**
+ * Configuration for ClaudeProvider
+ */
+export interface ClaudeProviderConfig {
+    /**
+     * Anthropic API key
+     */
+    apiKey: string;
+    /**
+     * Default model to use
+     * @default 'claude-sonnet-4-20250514'
+     */
+    model?: string;
+    /**
+     * Base URL for API (useful for proxies)
+     */
+    baseURL?: string;
+    /**
+     * Default max tokens
+     * @default 4096
+     */
+    maxTokens?: number;
+}
+/**
+ * ClaudeProvider implements LLMProvider for Anthropic's Claude API
+ */
+export declare class ClaudeProvider implements LLMProvider {
+    readonly name = "claude";
+    private readonly client;
+    private readonly defaultModel;
+    private readonly defaultMaxTokens;
+    constructor(config: ClaudeProviderConfig);
+    /**
+     * Send messages and stream the response
+     */
+    chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Count tokens in messages (not yet available in SDK v0.30)
+     *
+     * Note: Token counting API is available via Anthropic's beta endpoints
+     * but not yet exposed in the stable SDK. For now, this provides an
+     * approximation based on character count.
+     */
+    countTokens(messages: Message[]): Promise<number>;
+    /**
+     * Convert our Message format to Anthropic's format
+     */
+    private convertMessages;
+    /**
+     * Convert content to Anthropic's content block format
+     */
+    private convertContent;
+    /**
+     * Convert our ToolDefinition to Anthropic's Tool format
+     */
+    private convertTools;
+    /**
+     * Convert thinking config to Anthropic API format
+     */
+    private convertThinking;
+    /**
+     * Process a stream event into StreamChunks
+     */
+    private processEvent;
+    /**
+     * Process a content block delta event
+     */
+    private processDelta;
+    /**
+     * Map Anthropic SDK errors to ProviderError
+     */
+    private mapError;
+}
+/**
+ * Create a ClaudeProvider with API key from environment
+ */
+export declare function createClaudeProvider(config?: Partial<ClaudeProviderConfig>): ClaudeProvider;