@compilr-dev/agents 0.0.1

package/dist/memory/types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Project Memory Types
+ *
+ * Types for project-level instruction loading from markdown files.
+ * Supports various LLM-specific naming conventions (CLAUDE.md, GEMINI.md, etc.)
+ * as well as generic names (PROJECT.md, INSTRUCTIONS.md, AI.md).
+ */
+/**
+ * LLM provider name for memory file discovery.
+ *
+ * Common values: 'claude', 'gemini', 'openai', 'gpt', 'copilot', 'cursor', 'codeium', 'anthropic'
+ *
+ * Can be any string to support custom providers - patterns will be generated
+ * automatically (e.g., 'myai' -> MYAI.md, .myai.md, .myai/instructions.md)
+ */
+export type LLMProviderName = string;
+/**
+ * A loaded memory file with its content and metadata
+ */
+export interface MemoryFile {
+    /** Absolute path to the file */
+    path: string;
+    /** File content */
+    content: string;
+    /** Relative path from the search root */
+    relativePath: string;
+    /** The pattern that matched this file */
+    matchedPattern: string;
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp */
+    modifiedAt: Date;
+}
+/**
+ * Result of loading project memory
+ */
+export interface ProjectMemory {
+    /** All loaded memory files */
+    files: MemoryFile[];
+    /** Combined content from all files */
+    content: string;
+    /** The root directory where search started */
+    rootDir: string;
+    /** Total token estimate (rough: chars / 4) */
+    estimatedTokens: number;
+}
+/**
+ * File pattern configuration for discovery
+ */
+export interface FilePattern {
+    /** Glob pattern or exact filename */
+    pattern: string;
+    /** Priority (lower = higher priority, loaded first) */
+    priority: number;
+    /** Description of what this pattern matches */
+    description?: string;
+}
+/**
+ * Strategy for combining multiple memory files
+ */
+export type CombineStrategy = 'concat' | 'priority' | 'dedupe';
+/**
+ * Options for ProjectMemoryLoader
+ */
+export interface ProjectMemoryOptions {
+    /**
+     * LLM provider name(s) to search for
+     * E.g., 'claude' will search for CLAUDE.md, .claude.md, .claude/instructions.md
+     * Can be a single provider or array for multi-provider support
+     * @default 'claude'
+     */
+    providers?: LLMProviderName | LLMProviderName[];
+    /**
+     * Whether to include generic memory files (PROJECT.md, INSTRUCTIONS.md, AI.md)
+     * @default true
+     */
+    includeGeneric?: boolean;
+    /**
+     * Additional custom file patterns to search for
+     */
+    customPatterns?: FilePattern[];
+    /**
+     * Whether to search parent directories up to the root
+     * @default true
+     */
+    searchParents?: boolean;
+    /**
+     * Maximum number of parent directories to traverse
+     * @default 10
+     */
+    maxParentDepth?: number;
+    /**
+     * Stop searching parents when finding a git root (.git directory)
+     * @default true
+     */
+    stopAtGitRoot?: boolean;
+    /**
+     * Strategy for combining multiple memory files
+     * @default 'concat'
+     */
+    combineStrategy?: CombineStrategy;
+    /**
+     * Separator to use between files when combining
+     * @default '\n\n---\n\n'
+     */
+    separator?: string;
+    /**
+     * Maximum total content size in characters
+     * Files are loaded in priority order until limit is reached
+     * @default 100000 (100KB)
+     */
+    maxContentSize?: number;
+    /**
+     * Whether to include file path headers in combined content
+     * @default true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Header format template. Use {path} for file path, {relativePath} for relative path
+     * @default '# From: {relativePath}\n\n'
+     */
+    headerFormat?: string;
+    /**
+     * File encoding
+     * @default 'utf-8'
+     */
+    encoding?: BufferEncoding;
+}
+/**
+ * Event types for ProjectMemoryLoader
+ */
+export type ProjectMemoryEventType = 'memory:search_start' | 'memory:file_found' | 'memory:file_loaded' | 'memory:file_skipped' | 'memory:search_complete' | 'memory:error';
+/**
+ * Events emitted during memory loading
+ */
+export type ProjectMemoryEvent = {
+    type: 'memory:search_start';
+    rootDir: string;
+    patterns: string[];
+} | {
+    type: 'memory:file_found';
+    path: string;
+    pattern: string;
+} | {
+    type: 'memory:file_loaded';
+    file: MemoryFile;
+} | {
+    type: 'memory:file_skipped';
+    path: string;
+    reason: string;
+} | {
+    type: 'memory:search_complete';
+    memory: ProjectMemory;
+} | {
+    type: 'memory:error';
+    error: Error;
+    path?: string;
+};
+/**
+ * Event handler for project memory events
+ */
+export type ProjectMemoryEventHandler = (event: ProjectMemoryEvent) => void;
+/**
+ * Result of checking for memory files without loading content
+ */
+export interface MemoryDiscoveryResult {
+    /** Paths to discovered memory files */
+    paths: string[];
+    /** Whether any memory files were found */
+    found: boolean;
+    /** The patterns that matched */
+    matchedPatterns: string[];
+}
+/**
+ * Built-in provider patterns
+ */
+export interface ProviderPatterns {
+    /** Provider name */
+    provider: LLMProviderName;
+    /** File patterns for this provider (ordered by priority) */
+    patterns: FilePattern[];
+}

package/dist/memory/types.js

@@ -0,0 +1,8 @@
+/**
+ * Project Memory Types
+ *
+ * Types for project-level instruction loading from markdown files.
+ * Supports various LLM-specific naming conventions (CLAUDE.md, GEMINI.md, etc.)
+ * as well as generic names (PROJECT.md, INSTRUCTIONS.md, AI.md).
+ */
+export {};

package/dist/messages/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Message utilities
+ */
+import type { Message, ContentBlock, TextBlock, ToolUseBlock, ToolResultBlock } from '../providers/types.js';
+/**
+ * Create a user message
+ */
+export declare function userMessage(content: string): Message;
+/**
+ * Create an assistant message
+ */
+export declare function assistantMessage(content: string | ContentBlock[]): Message;
+/**
+ * Create a system message
+ */
+export declare function systemMessage(content: string): Message;
+/**
+ * Create a text content block
+ */
+export declare function textBlock(text: string): TextBlock;
+/**
+ * Create a tool use content block
+ */
+export declare function toolUseBlock(id: string, name: string, input: Record<string, unknown>): ToolUseBlock;
+/**
+ * Create a tool result content block
+ */
+export declare function toolResultBlock(toolUseId: string, content: string, isError?: boolean): ToolResultBlock;
+/**
+ * Extract text content from a message
+ */
+export declare function getTextContent(message: Message): string;
+/**
+ * Extract tool uses from a message
+ */
+export declare function getToolUses(message: Message): ToolUseBlock[];
+/**
+ * Check if a message contains tool uses
+ */
+export declare function hasToolUses(message: Message): boolean;
+/**
+ * Extract tool results from a message
+ */
+export declare function getToolResults(message: Message): ToolResultBlock[];
+/**
+ * Validation result for tool use/result pairing
+ */
+export interface ToolPairingValidation {
+    valid: boolean;
+    errors: string[];
+    orphanedResults: string[];
+    missingResults: string[];
+}
+/**
+ * Validate that tool_result blocks have matching tool_use blocks.
+ * This prevents API errors like "Tool result block missing corresponding tool_use block"
+ *
+ * @param messages - Array of messages to validate
+ * @returns Validation result with details about any mismatches
+ */
+export declare function validateToolUseResultPairing(messages: Message[]): ToolPairingValidation;
+/**
+ * Ensure a message has content field (even if empty).
+ * Some APIs (like xAI) require content to be present even when tool_calls exist.
+ *
+ * This function handles messages from external sources that might not strictly
+ * conform to our Message type (e.g., API responses with missing content).
+ *
+ * @param message - Message to normalize (may have missing content from external APIs)
+ * @returns Message with guaranteed content field
+ */
+export declare function ensureMessageContent(message: Message | {
+    role: string;
+    content?: string | ContentBlock[] | null;
+}): Message;
+/**
+ * Normalize all messages to ensure content fields are present.
+ *
+ * @param messages - Array of messages to normalize
+ * @returns Normalized messages
+ */
+export declare function normalizeMessages(messages: Message[]): Message[];

package/dist/messages/index.js

@@ -0,0 +1,155 @@
+/**
+ * Message utilities
+ */
+/**
+ * Create a user message
+ */
+export function userMessage(content) {
+    return { role: 'user', content };
+}
+/**
+ * Create an assistant message
+ */
+export function assistantMessage(content) {
+    return { role: 'assistant', content };
+}
+/**
+ * Create a system message
+ */
+export function systemMessage(content) {
+    return { role: 'system', content };
+}
+/**
+ * Create a text content block
+ */
+export function textBlock(text) {
+    return { type: 'text', text };
+}
+/**
+ * Create a tool use content block
+ */
+export function toolUseBlock(id, name, input) {
+    return { type: 'tool_use', id, name, input };
+}
+/**
+ * Create a tool result content block
+ */
+export function toolResultBlock(toolUseId, content, isError = false) {
+    return { type: 'tool_result', toolUseId, content, isError };
+}
+/**
+ * Extract text content from a message
+ */
+export function getTextContent(message) {
+    if (typeof message.content === 'string') {
+        return message.content;
+    }
+    return message.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+}
+/**
+ * Extract tool uses from a message
+ */
+export function getToolUses(message) {
+    if (typeof message.content === 'string') {
+        return [];
+    }
+    return message.content.filter((block) => block.type === 'tool_use');
+}
+/**
+ * Check if a message contains tool uses
+ */
+export function hasToolUses(message) {
+    return getToolUses(message).length > 0;
+}
+/**
+ * Extract tool results from a message
+ */
+export function getToolResults(message) {
+    if (typeof message.content === 'string') {
+        return [];
+    }
+    return message.content.filter((block) => block.type === 'tool_result');
+}
+/**
+ * Validate that tool_result blocks have matching tool_use blocks.
+ * This prevents API errors like "Tool result block missing corresponding tool_use block"
+ *
+ * @param messages - Array of messages to validate
+ * @returns Validation result with details about any mismatches
+ */
+export function validateToolUseResultPairing(messages) {
+    const toolUseIds = new Set();
+    const toolResultIds = new Set();
+    const errors = [];
+    // Collect all tool_use IDs and tool_result IDs
+    for (const message of messages) {
+        if (typeof message.content === 'string')
+            continue;
+        for (const block of message.content) {
+            if (block.type === 'tool_use') {
+                if (toolUseIds.has(block.id)) {
+                    errors.push(`Duplicate tool_use ID: ${block.id}`);
+                }
+                toolUseIds.add(block.id);
+            }
+            else if (block.type === 'tool_result') {
+                if (toolResultIds.has(block.toolUseId)) {
+                    errors.push(`Duplicate tool_result for ID: ${block.toolUseId}`);
+                }
+                toolResultIds.add(block.toolUseId);
+            }
+        }
+    }
+    // Find orphaned results (results without matching use)
+    const orphanedResults = [];
+    for (const resultId of toolResultIds) {
+        if (!toolUseIds.has(resultId)) {
+            orphanedResults.push(resultId);
+            errors.push(`Tool result '${resultId}' has no matching tool_use block`);
+        }
+    }
+    // Find missing results (uses without matching result) - only for completed conversations
+    const missingResults = [];
+    for (const useId of toolUseIds) {
+        if (!toolResultIds.has(useId)) {
+            missingResults.push(useId);
+            // Note: This is not always an error - the last tool_use may not have a result yet
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        orphanedResults,
+        missingResults,
+    };
+}
+/**
+ * Ensure a message has content field (even if empty).
+ * Some APIs (like xAI) require content to be present even when tool_calls exist.
+ *
+ * This function handles messages from external sources that might not strictly
+ * conform to our Message type (e.g., API responses with missing content).
+ *
+ * @param message - Message to normalize (may have missing content from external APIs)
+ * @returns Message with guaranteed content field
+ */
+export function ensureMessageContent(message) {
+    // Check for undefined/null from external sources
+    const rawContent = message.content;
+    if (rawContent === undefined || rawContent === null) {
+        return { role: message.role, content: '' };
+    }
+    return message;
+}
+/**
+ * Normalize all messages to ensure content fields are present.
+ *
+ * @param messages - Array of messages to normalize
+ * @returns Normalized messages
+ */
+export function normalizeMessages(messages) {
+    return messages.map(ensureMessageContent);
+}

package/dist/permissions/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Permissions module - Tool-level permission management
+ */
+export { PermissionManager } from './manager.js';
+export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './types.js';

package/dist/permissions/index.js

@@ -0,0 +1,4 @@
+/**
+ * Permissions module - Tool-level permission management
+ */
+export { PermissionManager } from './manager.js';

package/dist/permissions/manager.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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}?`);
+ *   },
+ * });
+ * ```
+ */
+import type { PermissionLevel, ToolPermission, PermissionCheckResult, PermissionManagerOptions, PermissionEventHandler } from './types.js';
+/**
+ * PermissionManager handles tool-level permission checks
+ */
+export declare class PermissionManager {
+    private readonly enabled;
+    private readonly defaultLevel;
+    private readonly rules;
+    private readonly wildcardRules;
+    private readonly handler?;
+    private readonly previewGenerator;
+    private readonly eventHandlers;
+    /**
+     * Track session-level permissions that have been granted
+     */
+    private readonly sessionGrants;
+    constructor(options?: PermissionManagerOptions);
+    /**
+     * Add a permission rule
+     */
+    addRule(rule: ToolPermission): this;
+    /**
+     * Remove a permission rule by tool name
+     */
+    removeRule(toolName: string): boolean;
+    /**
+     * Get a permission rule by tool name
+     */
+    getRule(toolName: string): ToolPermission | undefined;
+    /**
+     * Get all permission rules
+     */
+    getAllRules(): ToolPermission[];
+    /**
+     * Check if a tool has permission to execute
+     *
+     * @param toolName - Name of the tool
+     * @param input - Tool input arguments
+     * @returns Permission check result
+     */
+    check(toolName: string, input: Record<string, unknown>): Promise<PermissionCheckResult>;
+    /**
+     * Check and handle permission, returning whether to proceed
+     *
+     * Convenience method that combines check() with handling
+     */
+    checkAndProceed(toolName: string, input: Record<string, unknown>): Promise<{
+        proceed: boolean;
+        result: PermissionCheckResult;
+    }>;
+    /**
+     * Ask the user for permission
+     */
+    private askPermission;
+    /**
+     * Grant session-level permission for a tool
+     *
+     * This allows the tool to execute for the remainder of the session
+     * without asking again.
+     */
+    grantSession(toolName: string): void;
+    /**
+     * Revoke session-level permission for a tool
+     */
+    revokeSession(toolName: string): boolean;
+    /**
+     * Clear all session-level permissions
+     */
+    clearSessionGrants(): void;
+    /**
+     * Get all tools with session-level permission
+     */
+    getSessionGrants(): string[];
+    /**
+     * Check if a tool has session-level permission
+     */
+    hasSessionGrant(toolName: string): boolean;
+    /**
+     * Set the permission level for a tool
+     *
+     * Convenience method for adding/updating a rule
+     */
+    setLevel(toolName: string, level: PermissionLevel, description?: string): this;
+    /**
+     * Get the effective permission level for a tool
+     */
+    getLevel(toolName: string): PermissionLevel;
+    /**
+     * Register an event handler
+     */
+    onEvent(handler: PermissionEventHandler): () => void;
+    /**
+     * Emit an event
+     */
+    private emit;
+    /**
+     * Get the number of rules
+     */
+    get size(): number;
+    /**
+     * Check if permissions are enabled
+     */
+    get isEnabled(): boolean;
+}