profclaw 2.0.0 → 2.3.0

package/dist/agents/error-recovery.js

@@ -0,0 +1,197 @@
+/**
+ * Error Recovery Advisor
+ *
+ * Analyzes API errors and returns an ordered list of recovery actions.
+ * The caller drives the actual recovery; this module is purely advisory.
+ */
+// === Constants ===
+const WAIT_RATE_LIMIT_MS = 10_000; // 10 s initial back-off for 429
+const WAIT_OVERLOADED_MS = 5_000; // 5 s for 503
+const WAIT_TIMEOUT_MS = 2_000; // 2 s before retrying after timeout
+// Provider preference for alternatives (local-first)
+const PROVIDER_PREFERENCE = ['ollama', 'anthropic', 'openai', 'azure', 'google', 'cerebras'];
+// === Helpers ===
+function pickAlternativeProvider(current, available) {
+    return available
+        .filter(p => p !== current)
+        .sort((a, b) => PROVIDER_PREFERENCE.indexOf(a) - PROVIDER_PREFERENCE.indexOf(b))[0];
+}
+function containsAny(haystack, needles) {
+    const lower = haystack.toLowerCase();
+    return needles.some(n => lower.includes(n));
+}
+// === ErrorRecoveryAdvisor ===
+export class ErrorRecoveryAdvisor {
+    /**
+     * Analyze an error and return an ordered list of recommended recovery actions.
+     *
+     * Rules applied (in priority order):
+     *   401 / 403 → abort (auth errors cannot be retried)
+     *   429 (rate limit) → wait + switch_provider (if available) + retry
+     *   503 (server overloaded) → wait + retry
+     *   400 (bad request) → reduce_context or switch_model
+     *   ECONNREFUSED / ENOTFOUND → switch_provider
+     *   timeout → wait briefly + retry with reduce_context hint
+     *   context_length_exceeded → reduce_context + switch_model
+     *   content filter → switch_model
+     *   generic retry-eligible → retry (up to maxRetries)
+     */
+    advise(error, context) {
+        const { statusCode, code, message, provider, model } = error;
+        const { availableProviders, retryCount, maxRetries } = context;
+        const actions = [];
+        const msgLower = message.toLowerCase();
+        const codeLower = (code ?? '').toLowerCase();
+        // --- Auth errors: no recovery possible ---
+        if (statusCode === 401 || statusCode === 403) {
+            actions.push({
+                type: 'abort',
+                description: `Authentication failed for ${provider}. Check your API key or credentials.`,
+            });
+            return actions;
+        }
+        // --- Rate limit (429) ---
+        if (statusCode === 429 || containsAny(msgLower, ['rate limit', 'too many requests', 'ratelimit'])) {
+            const backOffMs = WAIT_RATE_LIMIT_MS * Math.pow(2, Math.min(retryCount, 3));
+            actions.push({
+                type: 'wait',
+                description: `Rate limit hit on ${provider}. Waiting ${backOffMs / 1000}s before retry.`,
+                waitMs: backOffMs,
+            });
+            const alternative = pickAlternativeProvider(provider, availableProviders);
+            if (alternative) {
+                actions.push({
+                    type: 'switch_provider',
+                    description: `Switch to ${alternative} to avoid rate limit on ${provider}.`,
+                    provider: alternative,
+                });
+            }
+            if (retryCount < maxRetries) {
+                actions.push({
+                    type: 'retry',
+                    description: `Retry request on ${provider} after waiting (attempt ${retryCount + 1}/${maxRetries}).`,
+                });
+            }
+            return actions;
+        }
+        // --- Server overloaded (503) ---
+        if (statusCode === 503 || containsAny(msgLower, ['overloaded', 'service unavailable', 'server error'])) {
+            actions.push({
+                type: 'wait',
+                description: `${provider} is overloaded. Waiting ${WAIT_OVERLOADED_MS / 1000}s.`,
+                waitMs: WAIT_OVERLOADED_MS,
+            });
+            if (retryCount < maxRetries) {
+                actions.push({
+                    type: 'retry',
+                    description: `Retry on ${provider} after server overload (attempt ${retryCount + 1}/${maxRetries}).`,
+                });
+            }
+            return actions;
+        }
+        // --- Context length exceeded ---
+        if (containsAny(msgLower, ['context length', 'context_length_exceeded', 'maximum context', 'too long', 'token limit'])
+            || codeLower === 'context_length_exceeded') {
+            actions.push({
+                type: 'reduce_context',
+                description: 'Message is too long for the current model. Reduce context or summarize earlier turns.',
+            });
+            actions.push({
+                type: 'switch_model',
+                description: `Switch to a model with a larger context window than ${model}.`,
+                model,
+            });
+            return actions;
+        }
+        // --- Content filter ---
+        if (containsAny(msgLower, ['content filter', 'content_filter', 'safety', 'policy violation', 'blocked'])) {
+            actions.push({
+                type: 'switch_model',
+                description: `Content was filtered by ${provider}. Try a different model with different safety settings.`,
+                model,
+            });
+            actions.push({
+                type: 'abort',
+                description: 'If the issue persists, rephrase your request to avoid the content filter.',
+            });
+            return actions;
+        }
+        // --- Bad request (400) ---
+        if (statusCode === 400) {
+            actions.push({
+                type: 'reduce_context',
+                description: 'Request was malformed or too large. Try reducing context size.',
+            });
+            actions.push({
+                type: 'switch_model',
+                description: `The model ${model} may not support this request format. Try a different model.`,
+                model,
+            });
+            return actions;
+        }
+        // --- Connection refused / DNS failure ---
+        if (codeLower === 'econnrefused'
+            || codeLower === 'enotfound'
+            || containsAny(msgLower, ['econnrefused', 'enotfound', 'connection refused', 'network error'])) {
+            const alternative = pickAlternativeProvider(provider, availableProviders);
+            if (alternative) {
+                actions.push({
+                    type: 'switch_provider',
+                    description: `Cannot reach ${provider}. Switch to ${alternative}.`,
+                    provider: alternative,
+                });
+            }
+            else {
+                actions.push({
+                    type: 'abort',
+                    description: `Cannot reach ${provider} and no alternative providers are available.`,
+                });
+            }
+            return actions;
+        }
+        // --- Timeout ---
+        if (codeLower === 'etimedout'
+            || codeLower === 'econnaborted'
+            || containsAny(msgLower, ['timeout', 'timed out', 'request timeout'])) {
+            actions.push({
+                type: 'wait',
+                description: `Request timed out. Waiting ${WAIT_TIMEOUT_MS / 1000}s before retry.`,
+                waitMs: WAIT_TIMEOUT_MS,
+            });
+            if (retryCount < maxRetries) {
+                actions.push({
+                    type: 'retry',
+                    description: `Retry with a shorter prompt or context (attempt ${retryCount + 1}/${maxRetries}).`,
+                });
+                actions.push({
+                    type: 'reduce_context',
+                    description: 'Reducing context may help the request complete within the timeout.',
+                });
+            }
+            return actions;
+        }
+        // --- Generic: retry if budget allows ---
+        if (retryCount < maxRetries) {
+            actions.push({
+                type: 'retry',
+                description: `Retry request (attempt ${retryCount + 1}/${maxRetries}).`,
+            });
+        }
+        else {
+            actions.push({
+                type: 'abort',
+                description: `Max retries (${maxRetries}) reached. Cannot recover automatically.`,
+            });
+        }
+        return actions;
+    }
+}
+// === Singleton ===
+let _advisor;
+export function getErrorRecoveryAdvisor() {
+    if (!_advisor) {
+        _advisor = new ErrorRecoveryAdvisor();
+    }
+    return _advisor;
+}
+//# sourceMappingURL=error-recovery.js.map

package/dist/agents/events.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Agent Streaming Events
+ *
+ * Discriminated union of all events that the AgentExecutor can yield
+ * from its async generator stream() method.
+ */
+export type AgentEvent = {
+    type: 'session:start';
+    sessionId: string;
+    config: Record<string, unknown>;
+} | {
+    type: 'step:start';
+    stepIndex: number;
+} | {
+    type: 'tool:call';
+    toolName: string;
+    args: unknown;
+    toolCallId: string;
+} | {
+    type: 'tool:result';
+    toolCallId: string;
+    result: unknown;
+    duration: number;
+    success: boolean;
+} | {
+    type: 'tool:error';
+    toolCallId: string;
+    error: string;
+} | {
+    type: 'content';
+    text: string;
+    delta: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'cost:update';
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCost: number;
+} | {
+    type: 'circuit:open';
+    toolName: string;
+    cooldownMs: number;
+} | {
+    type: 'step:complete';
+    stepIndex: number;
+    toolCalls: number;
+    hasContent: boolean;
+} | {
+    type: 'session:complete';
+    result: Record<string, unknown>;
+    totalSteps: number;
+    totalTokens: number;
+} | {
+    type: 'session:error';
+    error: string;
+    stack?: string;
+} | {
+    type: 'session:abort';
+    reason: string;
+} | {
+    type: 'checkpoint:saved';
+    sessionId: string;
+    step: number;
+} | {
+    type: 'checkpoint:resumed';
+    sessionId: string;
+    step: number;
+} | {
+    type: 'budget:warning';
+    usedPercent: number;
+    tokensUsed: number;
+    tokensMax: number;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/agents/events.js

@@ -0,0 +1,8 @@
+/**
+ * Agent Streaming Events
+ *
+ * Discriminated union of all events that the AgentExecutor can yield
+ * from its async generator stream() method.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/agents/executor.d.ts

@@ -9,19 +9,47 @@
 import type { LanguageModel, ModelMessage, ToolSet } from "ai";
 import { EventEmitter } from "node:events";
 import type { AgentState, AgentConfig, AgentEvents } from "./types.js";
+import type { AgentEvent } from "./events.js";
+import type { ExecutorCheckpoint } from "./checkpoint-manager.js";
+/** Handler called by the executor to execute a tool by name */
+export type ToolExecuteHandler = (name: string, args: Record<string, unknown>) => Promise<unknown>;
 type ExecutorTools = ToolSet;
 export declare class AgentExecutor extends EventEmitter<AgentEvents> {
     private state;
     private config;
     private abortController;
     private isRunning;
+    private resultStore;
+    private circuitBreaker;
+    private hooks;
+    private compactor;
+    private checkpointManager;
     constructor(sessionId: string, conversationId: string, goal: string, config?: Partial<AgentConfig>);
+    /**
+     * Async generator that streams agent events as they happen.
+     *
+     * Yields AgentEvent values in real time: session:start, step:start,
+     * tool:call, tool:result/tool:error, content, cost:update, step:complete,
+     * and finally session:complete, session:error, or session:abort.
+     *
+     * This is the canonical implementation; run() delegates here.
+     */
+    stream(model: LanguageModel, messages: ModelMessage[], tools: ExecutorTools, onToolExecute?: ToolExecuteHandler, providerHint?: string): AsyncGenerator<AgentEvent>;
     /**
      * Run the agent until completion or stop condition.
      * Uses AI SDK's native multi-step execution — a single generateText call
      * with stopWhen + onStepFinish replaces the old manual loop.
+     *
+     * Backward-compatible: delegates to stream() and returns the final AgentState.
+     */
+    run(model: LanguageModel, messages: ModelMessage[], tools: ExecutorTools, onToolExecute?: ToolExecuteHandler, providerHint?: string): Promise<AgentState>;
+    /**
+     * Resume execution from a saved checkpoint.
+     *
+     * Restores the message history and step counter from the checkpoint, emits a
+     * checkpoint:resumed event, then continues with generateText from that point.
      */
-    run(model: LanguageModel, messages: ModelMessage[], tools: ExecutorTools, onToolExecute?: (name: string, args: Record<string, unknown>) => Promise<unknown>, providerHint?: string): Promise<AgentState>;
+    resume(checkpoint: ExecutorCheckpoint, model: LanguageModel, tools: ExecutorTools, onToolExecute?: ToolExecuteHandler, providerHint?: string): AsyncGenerator<AgentEvent>;
     /**
      * Cancel the running agent.
      */
@@ -45,6 +73,12 @@ export declare class AgentExecutor extends EventEmitter<AgentEvents> {
      * after each step, the SDK calls execute() and feeds results back.
      */
     private wrapToolsWithExecute;
+    /**
+     * Like wrapToolsWithExecute, but additionally pushes tool:call, tool:result,
+     * and tool:error AgentEvents via the provided push callback so that the
+     * stream() generator can yield them in real time.
+     */
+    private wrapToolsWithExecuteAndEvents;
     /**
      * Check custom stop conditions that can't be expressed via AI SDK's stopWhen.
      * These include consecutive failures, same tool repeated, budget, timeout, etc.