profclaw 2.0.0 → 2.4.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-runner.d.ts

@@ -0,0 +1,135 @@
+/**
+ * ExecutorRunner: the built-in model-backed AgentRunner for verified runs.
+ *
+ * Adapts AgentExecutor to the AgentRunner seam used by runVerifiedGoal:
+ * - runs the executor with the run's worktree as the only place it can touch
+ *   (worktree-confined tools plus the PermissionManager, never push or PR);
+ * - feeds it the goal plus the previous attempt's trimmed verifier output;
+ * - reports tokens, dollars and cache hit rate so the loop's budget guard works,
+ *   and cancels an attempt mid-flight when the remaining budget is spent;
+ * - cascades models: starts on the smart router's cheap pick and moves one
+ *   tier up after N consecutive verifier failures (N is configurable).
+ *
+ * AgentExecutor is used as-is. Cache usage is read from its public
+ * `step:complete` event, so the executor internals are not touched.
+ */
+import type { LanguageModel, ModelMessage, ToolSet } from 'ai';
+import type { ToolExecuteHandler } from './executor.js';
+import type { AgentConfig, AgentState } from './types.js';
+import type { AgentAttemptInput, AgentAttemptResult, AgentRunner } from './verified-run.js';
+import type { PermissionManager } from './permissions.js';
+import type { ComplexityTier } from '../providers/smart-router.js';
+import type { ProviderType } from '../providers/core/types.js';
+import type { PromptCacheConfig } from '../providers/prompt-cache.js';
+export interface ModelChoice {
+    provider: ProviderType;
+    model: string;
+    costPer1MInput: number;
+    costPer1MOutput: number;
+    /** Router tier the pick came from, or 'pinned' for an explicit --model */
+    tier: ComplexityTier | 'pinned';
+}
+/**
+ * Build the ordered list of models an attempt series may use.
+ *
+ * `modelSpec` (comma separated) pins an explicit ladder, cheapest first.
+ * Without it the smart router classifies the goal, picks the cheap model for
+ * that tier, and appends the picks for each higher tier (deduplicated).
+ */
+export declare function buildModelLadder(goal: string, availableProviders: Set<ProviderType>, modelSpec?: string): ModelChoice[];
+export interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/** Dollar cost with cache reads and writes priced by their multipliers. */
+export declare function computeCostUsd(choice: ModelChoice, usage: UsageTotals, cache: PromptCacheConfig): number;
+export interface ExecutorRunnerConfig {
+    /** Consecutive verifier failures on a model before moving up a tier. 0 disables cascading. */
+    escalateAfter: number;
+    maxStepsPerAttempt: number;
+    /** Token cap per attempt (also bounded by the run's remaining budget) */
+    attemptTokenBudget: number;
+    commandTimeoutMs: number;
+    maxToolOutputChars: number;
+}
+export declare const DEFAULT_RUNNER_CONFIG: ExecutorRunnerConfig;
+/** Precedence: explicit flag > PROFCLAW_RUN_* env var > default. */
+export declare function resolveRunnerConfig(flags: Partial<ExecutorRunnerConfig>, env?: NodeJS.ProcessEnv): ExecutorRunnerConfig;
+/** The slice of AgentExecutor the runner uses; lets tests inject a fake. */
+export interface AgentLoop {
+    run(model: LanguageModel, messages: ModelMessage[], tools: ToolSet, onToolExecute?: ToolExecuteHandler, providerHint?: string): Promise<AgentState>;
+    cancel(): void;
+    getState(): AgentState;
+    on(event: 'step:complete', listener: (state: AgentState, result: unknown) => void): unknown;
+}
+export interface CreateLoopArgs {
+    sessionId: string;
+    goal: string;
+    config: Partial<AgentConfig>;
+}
+export type RunnerEvent = {
+    type: 'model_selected';
+    attempt: number;
+    choice: ModelChoice;
+    escalated: boolean;
+};
+/** One tool invocation by the agent, reported after it finishes. */
+export interface ToolCallEvent {
+    attempt: number;
+    name: string;
+    args: Record<string, unknown>;
+    durationMs: number;
+    ok: boolean;
+}
+export interface ExecutorRunnerOptions {
+    ladder: ModelChoice[];
+    createModel: (choice: ModelChoice) => Promise<LanguageModel>;
+    config?: Partial<ExecutorRunnerConfig>;
+    env?: NodeJS.ProcessEnv;
+    /** Run-level budgets (0 disables); attempts are capped to what is left */
+    maxTokens?: number;
+    maxCostUsd?: number;
+    permissions?: PermissionManager;
+    createLoop?: (args: CreateLoopArgs) => AgentLoop;
+    onEvent?: (event: RunnerEvent) => void;
+    /** Called after every tool call (used for run receipts) */
+    onToolCall?: (event: ToolCallEvent) => void;
+}
+export declare function buildAgentMessages(input: AgentAttemptInput): ModelMessage[];
+export declare class ExecutorRunner implements AgentRunner {
+    private readonly options;
+    private readonly config;
+    private readonly env;
+    private readonly permissions;
+    private tierIndex;
+    private failuresOnTier;
+    private spentTokens;
+    private spentUsd;
+    constructor(options: ExecutorRunnerOptions);
+    /** Model the next attempt would use (for tests and diagnostics). */
+    get currentChoice(): ModelChoice;
+    /**
+     * A call that arrives with feedback means the previous attempt failed
+     * verification (or crashed). After `escalateAfter` such failures in a row on
+     * the same model, move to the next tier up, if there is one.
+     */
+    private selectChoice;
+    runAttempt(input: AgentAttemptInput): Promise<AgentAttemptResult>;
+    private summarize;
+}
+export interface DefaultRunnerArgs {
+    goal: string;
+    /** Comma separated ladder, cheapest first; a single value pins the model */
+    model?: string;
+    config?: Partial<ExecutorRunnerConfig>;
+    maxTokens?: number;
+    maxCostUsd?: number;
+    env?: NodeJS.ProcessEnv;
+    onEvent?: (event: RunnerEvent) => void;
+    onToolCall?: (event: ToolCallEvent) => void;
+}
+/** Build a runner on the configured providers via the smart router. */
+export declare function createDefaultExecutorRunner(args: DefaultRunnerArgs): Promise<ExecutorRunner>;
+//# sourceMappingURL=executor-runner.d.ts.map