@lumenflow/core 1.0.0

package/dist/core/tool-runner.js

@@ -0,0 +1,393 @@
+/**
+ * @file tool-runner.mjs
+ * @description Unified tool execution layer integrating all core components (WU-1398)
+ *
+ * This module provides a higher-order function pattern for executing tools with:
+ * - Input validation via Zod schemas (tool.schemas.ts)
+ * - Worktree context detection (worktree-guard.mjs)
+ * - Scope validation against code_paths (scope-checker.mjs)
+ * - Audit logging for telemetry (.beacon/telemetry/tools.ndjson)
+ * - Consistent error handling with agent-friendly messages
+ *
+ * Usage:
+ *   import { runTool, ToolRunner, createToolConfig } from './tool-runner.js';
+ *
+ *   // Direct invocation
+ *   const result = await runTool(toolDefinition, { arg: 'value' });
+ *
+ *   // Registry-based invocation
+ *   const runner = new ToolRunner();
+ *   runner.register(myTool);
+ *   const result = await runner.run('tool:name', { arg: 'value' });
+ *
+ * @see tools/lib/core/tool.schemas.ts - Zod schemas for tool I/O
+ * @see tools/lib/core/worktree-guard.mjs - WU context detection
+ * @see tools/lib/core/scope-checker.mjs - Code path validation
+ */
+import { TOOL_ERROR_CODES, PERMISSION_LEVELS, TOOL_STATUS, DEFAULT_TOOL_TIMEOUT_MS, } from './tool.constants.js';
+import { validateToolInput, createErrorOutput } from './tool.schemas.js';
+import { getWUContext, assertWorktreeRequired } from './worktree-guard.js';
+import { getActiveScope, isPathInScope } from './scope-checker.js';
+/**
+ * Default configuration values for tool runner
+ */
+export const RUNNER_DEFAULTS = {
+    /** Default timeout for tool execution in milliseconds */
+    TIMEOUT_MS: DEFAULT_TOOL_TIMEOUT_MS,
+    /** Enable audit logging by default */
+    ENABLE_AUDIT_LOG: true,
+    /** Default: read tools don't require worktree */
+    REQUIRES_WORKTREE: false,
+    /** Default: read tools don't require scope check */
+    REQUIRES_SCOPE: false,
+};
+/**
+ * Create tool configuration with sensible defaults
+ *
+ * @param {object} tool - Tool definition
+ * @param {object} options - Configuration overrides
+ * @returns {object} Merged configuration
+ */
+export function createToolConfig(tool, options = {}) {
+    const isWriteOperation = tool.metadata.permission === PERMISSION_LEVELS.WRITE ||
+        tool.metadata.permission === PERMISSION_LEVELS.ADMIN;
+    return {
+        requiresWorktree: options.requiresWorktree ?? isWriteOperation,
+        requiresScope: options.requiresScope ?? isWriteOperation,
+        enableAuditLog: options.enableAuditLog ?? RUNNER_DEFAULTS.ENABLE_AUDIT_LOG,
+        timeoutMs: options.timeoutMs ?? RUNNER_DEFAULTS.TIMEOUT_MS,
+    };
+}
+/**
+ * Extract file path from tool input if present
+ *
+ * @param {object} input - Tool input
+ * @returns {string|null} File path or null
+ */
+function extractFilePath(input) {
+    // Common field names for file paths
+    const pathFields = ['path', 'filePath', 'file', 'targetPath'];
+    for (const field of pathFields) {
+        if (typeof input[field] === 'string') {
+            return input[field];
+        }
+    }
+    return null;
+}
+/**
+ * Create default dependencies using real implementations
+ *
+ * @returns {object} Default dependency implementations
+ */
+function createDefaultDependencies() {
+    return {
+        getWUContext,
+        getActiveScope,
+        isPathInScope,
+        assertWorktreeRequired,
+        logAudit: createAuditLogger(),
+    };
+}
+/**
+ * Create audit logger function
+ *
+ * @returns {Function} Audit logging function
+ */
+function createAuditLogger() {
+    return (entry) => {
+        // Write to NDJSON telemetry file
+        // Implementation deferred - currently no-op for testing
+        // Will integrate with .beacon/telemetry/tools.ndjson in future WU
+        void entry;
+    };
+}
+/**
+ * Generate helpful suggestions for validation errors
+ *
+ * @param {object} tool - Tool definition
+ * @param {object} zodError - Zod validation error
+ * @returns {string[]} Array of suggestions
+ */
+function generateValidationHints(tool, zodError) {
+    const hints = [];
+    // Add field-specific hints
+    for (const issue of zodError.issues) {
+        const path = issue.path.join('.');
+        hints.push(`Field '${path}': ${issue.message}`);
+    }
+    // Add general help hint
+    hints.push(`Run with --help to see valid arguments for ${tool.metadata.name}`);
+    return hints;
+}
+/**
+ * Run a tool with full validation and guards
+ *
+ * @param {object} tool - Tool definition (metadata, inputSchema, execute)
+ * @param {object} input - Tool input arguments
+ * @param {object} options - Execution options
+ * @param {object} options.dependencies - Injected dependencies (for testing)
+ * @param {object} options.config - Configuration overrides
+ * @param {object} options.context - Execution context (sessionId, etc.)
+ * @returns {Promise<object>} Tool output (success/failure with data/error)
+ */
+export async function runTool(tool, input, options = {}) {
+    const startTime = Date.now();
+    const startedAt = new Date().toISOString();
+    // Merge dependencies with defaults
+    const deps = {
+        ...createDefaultDependencies(),
+        ...options.dependencies,
+    };
+    // Create configuration
+    const config = createToolConfig(tool, options.config);
+    // Get WU context for audit logging
+    let wuContext = null;
+    try {
+        wuContext = await deps.getWUContext();
+    }
+    catch {
+        // Context retrieval failure is non-fatal
+        wuContext = null;
+    }
+    // Build execution metadata
+    const metadata = {
+        startedAt,
+        durationMs: 0,
+    };
+    // Helper to create audit log entry
+    const createAuditEntry = (status, output, error) => ({
+        tool: tool.metadata.name,
+        status,
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs: Date.now() - startTime,
+        input,
+        output,
+        error,
+        context: wuContext
+            ? {
+                wuId: wuContext.wuId,
+                lane: wuContext.lane,
+                worktreePath: wuContext.worktreePath,
+            }
+            : {},
+    });
+    try {
+        // Step 1: Validate input schema
+        const validation = validateToolInput(input, tool.inputSchema);
+        if (!validation.success) {
+            const validationError = validation;
+            const errorOutput = createErrorOutput({
+                code: TOOL_ERROR_CODES.SCHEMA_VALIDATION_FAILED,
+                message: `Input validation failed for ${tool.metadata.name}`,
+                details: { issues: validationError.error.issues },
+                tryNext: generateValidationHints(tool, validationError.error),
+            }, metadata);
+            if (config.enableAuditLog) {
+                deps.logAudit(createAuditEntry(TOOL_STATUS.FAILED, null, errorOutput.error));
+            }
+            return errorOutput;
+        }
+        // Narrow validation to success case
+        const validatedInput = validation;
+        // Step 2: Check worktree requirement
+        if (config.requiresWorktree) {
+            try {
+                await deps.assertWorktreeRequired({
+                    operation: tool.metadata.name,
+                });
+            }
+            catch (err) {
+                const errMessage = err instanceof Error ? err.message : String(err);
+                const errorOutput = createErrorOutput({
+                    code: TOOL_ERROR_CODES.PERMISSION_DENIED,
+                    message: errMessage,
+                    tryNext: [
+                        'Claim a WU first: pnpm wu:claim --id WU-XXX --lane "Your Lane"',
+                        'Then change to the worktree directory',
+                    ],
+                }, metadata);
+                if (config.enableAuditLog) {
+                    deps.logAudit(createAuditEntry(TOOL_STATUS.FAILED, null, errorOutput.error));
+                }
+                return errorOutput;
+            }
+        }
+        // Step 3: Check scope for write operations with file paths
+        if (config.requiresScope) {
+            const filePath = extractFilePath(validatedInput.data);
+            if (filePath) {
+                const scope = await deps.getActiveScope();
+                // If we have a scope, validate the path
+                if (scope &&
+                    !deps.isPathInScope(filePath, scope)) {
+                    const errorOutput = createErrorOutput({
+                        code: TOOL_ERROR_CODES.PERMISSION_DENIED,
+                        message: `Path '${filePath}' is outside WU scope for ${scope.wuId}`,
+                        details: {
+                            path: filePath,
+                            allowedPaths: scope.code_paths,
+                        },
+                        tryNext: [
+                            `Only modify files matching: ${scope.code_paths.join(', ')}`,
+                            'Update WU code_paths if this file should be in scope',
+                        ],
+                    }, metadata);
+                    if (config.enableAuditLog) {
+                        deps.logAudit(createAuditEntry(TOOL_STATUS.FAILED, null, errorOutput.error));
+                    }
+                    return errorOutput;
+                }
+            }
+        }
+        // Step 4: Execute the tool
+        const result = (await tool.execute(validatedInput.data, options.context));
+        // Step 5: Validate output if schema defined
+        if (tool.outputSchema && result.success && result.data) {
+            const outputValidation = validateToolInput(result.data, tool.outputSchema);
+            if (!outputValidation.success) {
+                const outputValidationError = outputValidation;
+                const errorOutput = createErrorOutput({
+                    code: TOOL_ERROR_CODES.INVALID_OUTPUT,
+                    message: `Tool ${tool.metadata.name} produced invalid output`,
+                    details: { issues: outputValidationError.error.issues },
+                }, { ...metadata, durationMs: Date.now() - startTime });
+                if (config.enableAuditLog) {
+                    deps.logAudit(createAuditEntry(TOOL_STATUS.FAILED, null, errorOutput.error));
+                }
+                return errorOutput;
+            }
+        }
+        // Add metadata to result
+        const resultMetadata = result.metadata || {};
+        const finalResult = {
+            ...result,
+            metadata: {
+                ...resultMetadata,
+                ...metadata,
+                durationMs: Date.now() - startTime,
+            },
+        };
+        // Log successful execution
+        if (config.enableAuditLog) {
+            deps.logAudit(createAuditEntry(TOOL_STATUS.SUCCESS, finalResult, null));
+        }
+        return finalResult;
+    }
+    catch (err) {
+        // Handle unexpected execution errors
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const errorStack = err instanceof Error ? err.stack : undefined;
+        const errorOutput = createErrorOutput({
+            code: TOOL_ERROR_CODES.EXECUTION_FAILED,
+            message: errorMessage,
+            stack: errorStack,
+            tryNext: ['Check tool input and try again', 'Report issue if problem persists'],
+        }, { ...metadata, durationMs: Date.now() - startTime });
+        if (config.enableAuditLog) {
+            deps.logAudit(createAuditEntry(TOOL_STATUS.FAILED, null, errorOutput.error));
+        }
+        return errorOutput;
+    }
+}
+/**
+ * Tool registry and runner class
+ *
+ * Provides a registry for tool definitions and a unified execution interface.
+ */
+export class ToolRunner {
+    #tools = new Map();
+    #config;
+    #dependencies;
+    /**
+     * Create a new ToolRunner instance
+     *
+     * @param {object} options - Runner options
+     * @param {boolean} options.enableAuditLog - Enable audit logging
+     * @param {number} options.timeoutMs - Default timeout
+     * @param {object} options.dependencies - Injected dependencies
+     */
+    constructor(options = {}) {
+        this.#config = {
+            enableAuditLog: options.enableAuditLog ?? RUNNER_DEFAULTS.ENABLE_AUDIT_LOG,
+            timeoutMs: options.timeoutMs ?? RUNNER_DEFAULTS.TIMEOUT_MS,
+        };
+        this.#dependencies = options.dependencies || createDefaultDependencies();
+    }
+    /**
+     * Register a tool definition
+     *
+     * @param {object} tool - Tool definition
+     * @throws {Error} If tool with same name already registered
+     */
+    register(tool) {
+        const name = tool.metadata.name;
+        if (this.#tools.has(name)) {
+            throw new Error(`Tool '${name}' is already registered`);
+        }
+        this.#tools.set(name, tool);
+    }
+    /**
+     * Check if a tool is registered
+     *
+     * @param {string} name - Tool name
+     * @returns {boolean} True if tool exists
+     */
+    hasTool(name) {
+        return this.#tools.has(name);
+    }
+    /**
+     * Run a registered tool by name
+     *
+     * @param {string} name - Tool name
+     * @param {object} input - Tool input
+     * @param {object} options - Execution options
+     * @returns {Promise<object>} Tool output
+     */
+    async run(name, input, options = {}) {
+        const tool = this.#tools.get(name);
+        if (!tool) {
+            return createErrorOutput({
+                code: TOOL_ERROR_CODES.TOOL_NOT_FOUND,
+                message: `Tool '${name}' not found in registry`,
+                tryNext: ['Check tool name spelling', 'Use runner.listTools() to see available tools'],
+            });
+        }
+        return runTool(tool, input, {
+            ...options,
+            dependencies: this.#dependencies,
+            config: { ...this.#config, ...options.config },
+        });
+    }
+    /**
+     * Get runner configuration
+     *
+     * @returns {object} Current configuration
+     */
+    getConfig() {
+        return { ...this.#config };
+    }
+    /**
+     * List all registered tools
+     *
+     * @param {object} options - Filter options
+     * @param {string} options.domain - Filter by domain
+     * @returns {object[]} Array of tool metadata
+     */
+    listTools(options = {}) {
+        const tools = [];
+        for (const tool of this.#tools.values()) {
+            if (options.domain && tool.metadata.domain !== options.domain) {
+                continue;
+            }
+            tools.push({
+                name: tool.metadata.name,
+                description: tool.metadata.description,
+                domain: tool.metadata.domain,
+                permission: tool.metadata.permission,
+                version: tool.metadata.version,
+            });
+        }
+        return tools;
+    }
+}

package/dist/core/tool.constants.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file tool.constants.ts
+ * @description Shared constants for tool abstraction layer (WU-1394)
+ *
+ * Provides domain enums, error codes, and permission levels for unified
+ * tool system. Used by tool registry, audit logging, and provider adapters.
+ */
+/**
+ * Tool domain categories for classification and routing
+ */
+export declare const TOOL_DOMAINS: {
+    /** Work Unit lifecycle operations (claim, done, block, etc.) */
+    readonly WU: "wu";
+    /** Git operations (commit, push, merge, etc.) */
+    readonly GIT: "git";
+    /** File system operations (read, write, delete, etc.) */
+    readonly FILE: "file";
+    /** Code exploration and search (grep, glob, find, etc.) */
+    readonly EXPLORE: "explore";
+    /** Testing operations (run tests, coverage, etc.) */
+    readonly TEST: "test";
+    /** Database operations (migrations, queries, etc.) */
+    readonly DB: "db";
+    /** Security operations (auth, permissions, audit, etc.) */
+    readonly SECURITY: "security";
+    /** Initiative management operations */
+    readonly INITIATIVE: "initiative";
+    /** Metrics and reporting operations */
+    readonly METRICS: "metrics";
+    /** Orchestration operations (status, suggest, etc.) */
+    readonly ORCHESTRATION: "orchestration";
+    /** Documentation operations (linting, validation, etc.) */
+    readonly DOCS: "docs";
+    /** General utility operations */
+    readonly UTIL: "util";
+};
+export type ToolDomain = (typeof TOOL_DOMAINS)[keyof typeof TOOL_DOMAINS];
+/**
+ * Permission levels for access control
+ */
+export declare const PERMISSION_LEVELS: {
+    /** Read-only operations (no state changes) */
+    readonly READ: "read";
+    /** Write operations (modifies state) */
+    readonly WRITE: "write";
+    /** Administrative operations (destructive, requires elevated access) */
+    readonly ADMIN: "admin";
+};
+export type PermissionLevel = (typeof PERMISSION_LEVELS)[keyof typeof PERMISSION_LEVELS];
+/**
+ * Tool error codes (extends existing ErrorCodes from error-handler.mjs)
+ */
+export declare const TOOL_ERROR_CODES: {
+    /** Tool not found in registry */
+    readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
+    /** Invalid tool input schema */
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    /** Invalid tool output schema */
+    readonly INVALID_OUTPUT: "INVALID_OUTPUT";
+    /** Tool execution failed */
+    readonly EXECUTION_FAILED: "EXECUTION_FAILED";
+    /** Permission denied for tool operation */
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    /** Tool timeout */
+    readonly TIMEOUT: "TIMEOUT";
+    /** Tool not available in current context */
+    readonly NOT_AVAILABLE: "NOT_AVAILABLE";
+    /** Schema validation failed */
+    readonly SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED";
+    /** Missing required argument */
+    readonly MISSING_ARGUMENT: "MISSING_ARGUMENT";
+    /** Invalid argument type */
+    readonly INVALID_ARGUMENT_TYPE: "INVALID_ARGUMENT_TYPE";
+    /** Tool already registered */
+    readonly DUPLICATE_TOOL: "DUPLICATE_TOOL";
+    /** Provider adapter error */
+    readonly PROVIDER_ERROR: "PROVIDER_ERROR";
+};
+export type ToolErrorCode = (typeof TOOL_ERROR_CODES)[keyof typeof TOOL_ERROR_CODES];
+/**
+ * Tool execution status values
+ */
+export declare const TOOL_STATUS: {
+    /** Tool execution pending */
+    readonly PENDING: "pending";
+    /** Tool currently executing */
+    readonly RUNNING: "running";
+    /** Tool execution completed successfully */
+    readonly SUCCESS: "success";
+    /** Tool execution failed */
+    readonly FAILED: "failed";
+    /** Tool execution timed out */
+    readonly TIMEOUT: "timeout";
+    /** Tool execution cancelled */
+    readonly CANCELLED: "cancelled";
+};
+export type ToolStatus = (typeof TOOL_STATUS)[keyof typeof TOOL_STATUS];
+/**
+ * Default timeout for tool execution (milliseconds)
+ */
+export declare const DEFAULT_TOOL_TIMEOUT_MS = 30000;
+/**
+ * Maximum number of retries for transient failures
+ */
+export declare const MAX_TOOL_RETRIES = 3;

package/dist/core/tool.constants.js

@@ -0,0 +1,101 @@
+/**
+ * @file tool.constants.ts
+ * @description Shared constants for tool abstraction layer (WU-1394)
+ *
+ * Provides domain enums, error codes, and permission levels for unified
+ * tool system. Used by tool registry, audit logging, and provider adapters.
+ */
+/**
+ * Tool domain categories for classification and routing
+ */
+export const TOOL_DOMAINS = {
+    /** Work Unit lifecycle operations (claim, done, block, etc.) */
+    WU: 'wu',
+    /** Git operations (commit, push, merge, etc.) */
+    GIT: 'git',
+    /** File system operations (read, write, delete, etc.) */
+    FILE: 'file',
+    /** Code exploration and search (grep, glob, find, etc.) */
+    EXPLORE: 'explore',
+    /** Testing operations (run tests, coverage, etc.) */
+    TEST: 'test',
+    /** Database operations (migrations, queries, etc.) */
+    DB: 'db',
+    /** Security operations (auth, permissions, audit, etc.) */
+    SECURITY: 'security',
+    /** Initiative management operations */
+    INITIATIVE: 'initiative',
+    /** Metrics and reporting operations */
+    METRICS: 'metrics',
+    /** Orchestration operations (status, suggest, etc.) */
+    ORCHESTRATION: 'orchestration',
+    /** Documentation operations (linting, validation, etc.) */
+    DOCS: 'docs',
+    /** General utility operations */
+    UTIL: 'util',
+};
+/**
+ * Permission levels for access control
+ */
+export const PERMISSION_LEVELS = {
+    /** Read-only operations (no state changes) */
+    READ: 'read',
+    /** Write operations (modifies state) */
+    WRITE: 'write',
+    /** Administrative operations (destructive, requires elevated access) */
+    ADMIN: 'admin',
+};
+/**
+ * Tool error codes (extends existing ErrorCodes from error-handler.mjs)
+ */
+export const TOOL_ERROR_CODES = {
+    /** Tool not found in registry */
+    TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
+    /** Invalid tool input schema */
+    INVALID_INPUT: 'INVALID_INPUT',
+    /** Invalid tool output schema */
+    INVALID_OUTPUT: 'INVALID_OUTPUT',
+    /** Tool execution failed */
+    EXECUTION_FAILED: 'EXECUTION_FAILED',
+    /** Permission denied for tool operation */
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    /** Tool timeout */
+    TIMEOUT: 'TIMEOUT',
+    /** Tool not available in current context */
+    NOT_AVAILABLE: 'NOT_AVAILABLE',
+    /** Schema validation failed */
+    SCHEMA_VALIDATION_FAILED: 'SCHEMA_VALIDATION_FAILED',
+    /** Missing required argument */
+    MISSING_ARGUMENT: 'MISSING_ARGUMENT',
+    /** Invalid argument type */
+    INVALID_ARGUMENT_TYPE: 'INVALID_ARGUMENT_TYPE',
+    /** Tool already registered */
+    DUPLICATE_TOOL: 'DUPLICATE_TOOL',
+    /** Provider adapter error */
+    PROVIDER_ERROR: 'PROVIDER_ERROR',
+};
+/**
+ * Tool execution status values
+ */
+export const TOOL_STATUS = {
+    /** Tool execution pending */
+    PENDING: 'pending',
+    /** Tool currently executing */
+    RUNNING: 'running',
+    /** Tool execution completed successfully */
+    SUCCESS: 'success',
+    /** Tool execution failed */
+    FAILED: 'failed',
+    /** Tool execution timed out */
+    TIMEOUT: 'timeout',
+    /** Tool execution cancelled */
+    CANCELLED: 'cancelled',
+};
+/**
+ * Default timeout for tool execution (milliseconds)
+ */
+export const DEFAULT_TOOL_TIMEOUT_MS = 30000; // 30 seconds
+/**
+ * Maximum number of retries for transient failures
+ */
+export const MAX_TOOL_RETRIES = 3;