profclaw 0.0.1-beta.1

package/dist/chat/execution/workflows/executor.js

@@ -0,0 +1,259 @@
+// Map from executionId -> AbortController for cancellation
+const activeExecutions = new Map();
+/**
+ * Interpolate {{variableName}} placeholders in a string value.
+ * Supports dot notation for nested access: {{step1.output.field}}
+ */
+function interpolateString(template, variables) {
+    return template.replace(/\{\{([^}]+)\}\}/g, (_match, key) => {
+        const trimmed = key.trim();
+        const parts = trimmed.split('.');
+        let value = variables;
+        for (const part of parts) {
+            if (value !== null && typeof value === 'object') {
+                value = value[part];
+            }
+            else {
+                value = undefined;
+                break;
+            }
+        }
+        if (value === undefined || value === null) {
+            return '';
+        }
+        if (typeof value === 'object') {
+            return JSON.stringify(value);
+        }
+        return String(value);
+    });
+}
+/**
+ * Recursively interpolate {{variable}} placeholders in any value.
+ * Handles strings, arrays, and plain objects.
+ */
+function interpolateValue(value, variables) {
+    if (typeof value === 'string') {
+        return interpolateString(value, variables);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => interpolateValue(item, variables));
+    }
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = interpolateValue(v, variables);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Evaluate a simple boolean condition against variables.
+ * Supports: {{var}} === value, {{var}} !== value, {{var}} (truthy check)
+ */
+function evaluateCondition(condition, variables) {
+    const interpolated = interpolateString(condition, variables);
+    // Handle strict equality: lhs === rhs
+    const strictEqMatch = interpolated.match(/^(.+?)\s*===\s*(.+)$/);
+    if (strictEqMatch) {
+        const lhs = strictEqMatch[1].trim().replace(/^["']|["']$/g, '');
+        const rhs = strictEqMatch[2].trim().replace(/^["']|["']$/g, '');
+        return lhs === rhs;
+    }
+    // Handle strict inequality: lhs !== rhs
+    const strictNeqMatch = interpolated.match(/^(.+?)\s*!==\s*(.+)$/);
+    if (strictNeqMatch) {
+        const lhs = strictNeqMatch[1].trim().replace(/^["']|["']$/g, '');
+        const rhs = strictNeqMatch[2].trim().replace(/^["']|["']$/g, '');
+        return lhs !== rhs;
+    }
+    // Truthy check
+    const trimmed = interpolated.trim();
+    return trimmed !== '' && trimmed !== 'false' && trimmed !== '0' && trimmed !== 'null';
+}
+/**
+ * Extract a value from a ToolResult using the captureOutput path.
+ * Checks result.output (string), result.data (object), then the entire result.
+ */
+function extractOutput(result, captureOutput) {
+    if (captureOutput === 'output')
+        return result.output;
+    if (captureOutput === 'data')
+        return result.data;
+    if (captureOutput === 'success')
+        return result.success;
+    // Try nested path on data
+    if (result.data !== undefined && result.data !== null && typeof result.data === 'object') {
+        const parts = captureOutput.split('.');
+        let value = result.data;
+        for (const part of parts) {
+            if (value !== null && typeof value === 'object') {
+                value = value[part];
+            }
+            else {
+                value = undefined;
+                break;
+            }
+        }
+        if (value !== undefined)
+            return value;
+    }
+    // Fall back to raw output string
+    return result.output ?? result.data;
+}
+/** Generate a unique execution ID */
+function generateExecutionId(workflowId, conversationId) {
+    return `${workflowId}:${conversationId}:${Date.now()}`;
+}
+export class WorkflowExecutor {
+    /**
+     * Execute a workflow step by step, returning a summary of all results.
+     * Supports variable interpolation, conditional steps, and cancellation.
+     */
+    async execute(workflow, context, options = {}) {
+        const executionId = generateExecutionId(workflow.id, context.conversationId);
+        const abortController = new AbortController();
+        activeExecutions.set(executionId, abortController);
+        // Forward external abort signal into our controller
+        if (context.signal) {
+            context.signal.addEventListener('abort', () => abortController.abort());
+        }
+        const startedAt = Date.now();
+        const variables = {
+            ...(workflow.variables ?? {}),
+            ...(context.variables ?? {}),
+        };
+        const execution = {
+            workflowId: workflow.id,
+            conversationId: context.conversationId,
+            status: 'running',
+            currentStep: 0,
+            stepResults: workflow.steps.map((step) => ({
+                stepId: step.id,
+                toolName: step.tool,
+                status: 'pending',
+            })),
+            variables,
+            startedAt,
+        };
+        const outputs = {};
+        let fatalError;
+        for (let i = 0; i < workflow.steps.length; i++) {
+            const step = workflow.steps[i];
+            // Check for cancellation
+            if (abortController.signal.aborted) {
+                execution.status = 'cancelled';
+                execution.stepResults[i].status = 'skipped';
+                break;
+            }
+            // Check explicit skip list
+            if (options.skipSteps?.includes(step.id)) {
+                execution.stepResults[i].status = 'skipped';
+                continue;
+            }
+            // Evaluate step condition
+            if (step.condition) {
+                const shouldRun = evaluateCondition(step.condition, variables);
+                if (!shouldRun) {
+                    execution.stepResults[i].status = 'skipped';
+                    continue;
+                }
+            }
+            execution.currentStep = i;
+            execution.stepResults[i].status = 'running';
+            context.onStepStart?.(step, i);
+            const stepStartMs = Date.now();
+            const stepResult = await this.executeStep(step, variables, context, options);
+            const durationMs = Date.now() - stepStartMs;
+            execution.stepResults[i] = {
+                stepId: step.id,
+                toolName: step.tool,
+                status: stepResult.success ? 'completed' : 'failed',
+                output: stepResult.output ?? stepResult.data,
+                error: stepResult.error?.message,
+                durationMs,
+            };
+            // Capture output into variables
+            if (step.captureOutput && stepResult.success) {
+                const captured = extractOutput(stepResult, step.captureOutput);
+                variables[step.captureOutput] = captured;
+                outputs[step.captureOutput] = captured;
+            }
+            context.onStepComplete?.(step, execution.stepResults[i]);
+            // Handle failure
+            if (!stepResult.success && !step.continueOnError) {
+                fatalError = stepResult.error?.message ?? `Step "${step.name}" failed`;
+                execution.status = 'failed';
+                execution.error = fatalError;
+                break;
+            }
+        }
+        activeExecutions.delete(executionId);
+        execution.completedAt = Date.now();
+        if (execution.status === 'running') {
+            execution.status = 'completed';
+        }
+        const completedSteps = execution.stepResults.filter((r) => r.status === 'completed').length;
+        const failedSteps = execution.stepResults.filter((r) => r.status === 'failed').length;
+        const skippedSteps = execution.stepResults.filter((r) => r.status === 'skipped').length;
+        return {
+            workflowId: workflow.id,
+            name: workflow.name,
+            totalSteps: workflow.steps.length,
+            completedSteps,
+            failedSteps,
+            skippedSteps,
+            totalDurationMs: execution.completedAt - startedAt,
+            outputs,
+        };
+    }
+    /** Cancel a running workflow by its execution ID */
+    cancel(executionId) {
+        const controller = activeExecutions.get(executionId);
+        if (controller) {
+            controller.abort();
+            activeExecutions.delete(executionId);
+        }
+    }
+    /** Execute a single workflow step, applying param interpolation and overrides */
+    async executeStep(step, variables, context, options) {
+        // Build params with interpolation
+        const baseParams = interpolateValue(step.params, variables);
+        const overrides = options.overrides?.[step.id] ?? {};
+        const params = { ...baseParams, ...overrides };
+        // Apply step-level timeout if specified
+        if (step.timeoutMs !== undefined) {
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Step "${step.name}" timed out after ${step.timeoutMs}ms`)), step.timeoutMs));
+            try {
+                return await Promise.race([
+                    context.toolExecutor(step.tool, params),
+                    timeoutPromise,
+                ]);
+            }
+            catch (error) {
+                console.error(`[workflow] Step "${step.id}" timed out:`, error);
+                return {
+                    success: false,
+                    error: {
+                        code: 'STEP_TIMEOUT',
+                        message: error instanceof Error ? error.message : 'Step timed out',
+                    },
+                };
+            }
+        }
+        try {
+            return await context.toolExecutor(step.tool, params);
+        }
+        catch (error) {
+            console.error(`[workflow] Step "${step.id}" threw:`, error);
+            return {
+                success: false,
+                error: {
+                    code: 'STEP_ERROR',
+                    message: error instanceof Error ? error.message : 'Unknown error in step',
+                },
+            };
+        }
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/chat/execution/workflows/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './built-in.js';
+export { WorkflowExecutor } from './executor.js';
+export { detectWorkflow, matchWorkflow } from './trigger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/chat/execution/workflows/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './built-in.js';
+export { WorkflowExecutor } from './executor.js';
+export { detectWorkflow, matchWorkflow } from './trigger.js';
+//# sourceMappingURL=index.js.map

package/dist/chat/execution/workflows/trigger.d.ts

@@ -0,0 +1,15 @@
+import type { WorkflowDefinition, WorkflowMatch } from './types.js';
+/**
+ * Detect which workflow (if any) best matches the user's intent.
+ * Returns null if no workflow reaches the minimum confidence threshold.
+ */
+export declare function detectWorkflow(userMessage: string, availableWorkflows: WorkflowDefinition[]): WorkflowMatch | null;
+/**
+ * Detect workflow from user message against all available workflows,
+ * returning the best match above the confidence threshold.
+ *
+ * Convenience wrapper that also injects extracted variables as
+ * workflow-level variable overrides.
+ */
+export declare function matchWorkflow(userMessage: string, availableWorkflows: WorkflowDefinition[]): WorkflowMatch | null;
+//# sourceMappingURL=trigger.d.ts.map

package/dist/chat/execution/workflows/trigger.js

@@ -0,0 +1,111 @@
+/** Minimum confidence threshold to return a workflow match */
+const MIN_CONFIDENCE = 0.5;
+/** Patterns for extracting common variables from user messages */
+const VARIABLE_PATTERNS = [
+    // File paths
+    { name: 'filePath', pattern: /(?:in|at|file|path)\s+([\w./\\-]+\.\w+)/i },
+    // Error messages in quotes
+    { name: 'errorPattern', pattern: /(?:error|pattern|search for)\s+["']([^"']+)["']/i },
+    // Search query
+    { name: 'query', pattern: /(?:search|look up|find|research)\s+(?:for\s+)?["']?([^"'\n]{3,80})["']?/i },
+    // Branch name
+    { name: 'branch', pattern: /(?:branch|from)\s+([\w/-]+)/i },
+    // Directory
+    { name: 'searchDir', pattern: /(?:in|directory|dir|folder)\s+([\w./\\-]+)/i },
+    // Target pattern for refactoring
+    { name: 'targetPattern', pattern: /(?:rename|replace|refactor)\s+["']?(\w+)["']?/i },
+    // Test command override
+    { name: 'testCommand', pattern: /(?:using|with|run)\s+(pnpm|npm|yarn|bun)\s+test/i },
+];
+/**
+ * Score how well a user message matches a workflow's triggers.
+ * Returns a value 0-1 where 1 is a perfect match.
+ */
+function scoreTriggers(message, triggers) {
+    const normalised = message.toLowerCase().trim();
+    let best = 0;
+    for (const trigger of triggers) {
+        const triggerLower = trigger.toLowerCase();
+        // Exact phrase match
+        if (normalised.includes(triggerLower)) {
+            const lengthRatio = triggerLower.length / normalised.length;
+            // Longer trigger relative to message = higher confidence
+            const score = 0.6 + Math.min(0.4, lengthRatio * 2);
+            if (score > best)
+                best = score;
+            continue;
+        }
+        // Word-level overlap
+        const triggerWords = triggerLower.split(/\s+/);
+        const messageWords = new Set(normalised.split(/\W+/).filter((w) => w.length > 2));
+        const matchedWords = triggerWords.filter((w) => messageWords.has(w));
+        if (matchedWords.length > 0) {
+            const ratio = matchedWords.length / triggerWords.length;
+            const score = ratio * 0.55;
+            if (score > best)
+                best = score;
+        }
+    }
+    return best;
+}
+/**
+ * Extract variable values from the user message using known patterns.
+ */
+function extractVariables(message) {
+    const extracted = {};
+    for (const { name, pattern } of VARIABLE_PATTERNS) {
+        const match = message.match(pattern);
+        if (match?.[1]) {
+            extracted[name] = match[1].trim();
+        }
+    }
+    return extracted;
+}
+/**
+ * Detect which workflow (if any) best matches the user's intent.
+ * Returns null if no workflow reaches the minimum confidence threshold.
+ */
+export function detectWorkflow(userMessage, availableWorkflows) {
+    if (!userMessage || availableWorkflows.length === 0) {
+        return null;
+    }
+    let bestMatch = null;
+    for (const workflow of availableWorkflows) {
+        const confidence = scoreTriggers(userMessage, workflow.triggers);
+        if (confidence >= MIN_CONFIDENCE && (bestMatch === null || confidence > bestMatch.confidence)) {
+            bestMatch = {
+                workflow,
+                confidence,
+                extractedVariables: extractVariables(userMessage),
+            };
+        }
+    }
+    return bestMatch;
+}
+/**
+ * Detect workflow from user message against all available workflows,
+ * returning the best match above the confidence threshold.
+ *
+ * Convenience wrapper that also injects extracted variables as
+ * workflow-level variable overrides.
+ */
+export function matchWorkflow(userMessage, availableWorkflows) {
+    const match = detectWorkflow(userMessage, availableWorkflows);
+    if (!match)
+        return null;
+    // Merge extracted variables into a copy of the workflow's defaults
+    if (Object.keys(match.extractedVariables).length > 0) {
+        return {
+            ...match,
+            workflow: {
+                ...match.workflow,
+                variables: {
+                    ...(match.workflow.variables ?? {}),
+                    ...match.extractedVariables,
+                },
+            },
+        };
+    }
+    return match;
+}
+//# sourceMappingURL=trigger.js.map

package/dist/chat/execution/workflows/types.d.ts

@@ -0,0 +1,80 @@
+/** Workflow definition - YAML/JSON compatible structure */
+export interface WorkflowDefinition {
+    id: string;
+    name: string;
+    description: string;
+    /** Keywords that trigger this workflow */
+    triggers: string[];
+    /** Sequential steps */
+    steps: WorkflowStep[];
+    /** Variables available to all steps */
+    variables?: Record<string, unknown>;
+}
+export interface WorkflowStep {
+    id: string;
+    name: string;
+    /** Tool to execute */
+    tool: string;
+    /** Parameters - supports {{variable}} interpolation from previous step outputs */
+    params: Record<string, unknown>;
+    /** Condition to skip this step (simple expression) */
+    condition?: string;
+    /** Which output field to capture for later steps */
+    captureOutput?: string;
+    /** Whether failure of this step is fatal */
+    continueOnError?: boolean;
+    /** Timeout override in ms */
+    timeoutMs?: number;
+}
+export interface WorkflowExecution {
+    workflowId: string;
+    conversationId: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    currentStep: number;
+    stepResults: WorkflowStepResult[];
+    variables: Record<string, unknown>;
+    startedAt: number;
+    completedAt?: number;
+    error?: string;
+}
+export interface WorkflowStepResult {
+    stepId: string;
+    toolName: string;
+    status: 'pending' | 'running' | 'completed' | 'skipped' | 'failed';
+    output?: unknown;
+    error?: string;
+    durationMs?: number;
+}
+export interface WorkflowSummary {
+    workflowId: string;
+    name: string;
+    totalSteps: number;
+    completedSteps: number;
+    failedSteps: number;
+    skippedSteps: number;
+    totalDurationMs: number;
+    outputs: Record<string, unknown>;
+}
+export interface WorkflowExecutionContext {
+    conversationId: string;
+    /** Function to execute a tool by name */
+    toolExecutor: (toolName: string, params: Record<string, unknown>) => Promise<import('../types.js').ToolResult>;
+    /** Initial variables */
+    variables?: Record<string, unknown>;
+    signal?: AbortSignal;
+    onStepStart?: (step: WorkflowStep, index: number) => void;
+    onStepComplete?: (step: WorkflowStep, result: WorkflowStepResult) => void;
+}
+export interface WorkflowExecuteOptions {
+    /** Steps to skip by ID */
+    skipSteps?: string[];
+    /** Override params for specific steps */
+    overrides?: Record<string, Record<string, unknown>>;
+}
+export interface WorkflowMatch {
+    workflow: WorkflowDefinition;
+    /** Confidence score 0-1 */
+    confidence: number;
+    extractedVariables: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/chat/execution/workflows/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/chat/failover/error.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Failover Error System
+ *
+ * Error classification and FailoverError class for provider failover.
+ * Based on OpenClaw's sophisticated error handling patterns.
+ */
+import type { FailoverReason } from './types.js';
+/**
+ * Error class that includes failover metadata.
+ * Used to track and propagate error context through the fallback chain.
+ */
+export declare class FailoverError extends Error {
+    readonly reason: FailoverReason;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, params: {
+        reason: FailoverReason;
+        provider?: string;
+        model?: string;
+        status?: number;
+        code?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Check if an error is a FailoverError
+ */
+export declare function isFailoverError(err: unknown): err is FailoverError;
+/**
+ * Resolve HTTP status code from failover reason
+ */
+export declare function resolveFailoverStatus(reason: FailoverReason): number | undefined;
+/**
+ * Check if an error is a timeout error
+ */
+export declare function isTimeoutError(err: unknown): boolean;
+/**
+ * Classify an error message into a failover reason
+ */
+export declare function classifyFailoverReason(raw: string): FailoverReason | null;
+/**
+ * Resolve failover reason from an error object
+ */
+export declare function resolveFailoverReasonFromError(err: unknown): FailoverReason | null;
+/**
+ * Describe a failover error for logging/display
+ */
+export declare function describeFailoverError(err: unknown): {
+    message: string;
+    reason?: FailoverReason;
+    status?: number;
+    code?: string;
+};
+/**
+ * Convert any error into a FailoverError if it matches failover criteria.
+ * Returns null if the error doesn't warrant a failover attempt.
+ */
+export declare function coerceToFailoverError(err: unknown, context?: {
+    provider?: string;
+    model?: string;
+}): FailoverError | null;
+/**
+ * Check if an error should be rethrown without attempting fallback.
+ * User-initiated aborts should not trigger fallback.
+ */
+export declare function shouldRethrowWithoutFallback(err: unknown): boolean;
+/**
+ * Get a user-friendly error message based on the error and provider
+ */
+export declare function getUserFriendlyErrorMessage(err: unknown, provider: string): string;
+//# sourceMappingURL=error.d.ts.map