/** * Auto-Resume Extension for Pi * * Handles multiple types of response interruptions: * * 1. TOKEN LIMIT (max_tokens): Response truncated with stopReason "length" * 2. INCOMPLETE TOOL CALLS: Output cut off mid-tool-call (empty JSON arguments) * 3. PROVIDER RATE LIMITS: HTTP 429 with retry-after headers * 4. PLAN LIMITS: Quota/billing exhaustion errors (Claude Pro, OpenCode, etc.) * 5. CONTEXT OVERFLOW: ( defers to Pi's built-in auto-compaction) * * For rate limits and plan exhaustion, the extension waits and retries automatically. * For token limits and incomplete tool calls, it sends a continuation prompt. * * Configuration via settings.json: * { * "autoResume": { * "enabled": true, * "maxResumes": 5, * "delayMs": 1000, * "continuePrompt": "Continue from where you left off...", * "rateLimit": { * "enabled": true, * "maxRetries": 3, * "baseDelayMs": 60000, * "maxDelayMs": 3600000 * } * } * } * * Usage: * pi -e auto-resume-on-token-limit.ts * * Or install to ~/.pi/agent/extensions/ for auto-discovery. */ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; interface RateLimitConfig { /** Whether to handle rate limits (default: true) */ enabled: boolean; /** Max retry attempts for rate limits (default: 3) */ maxRetries: number; /** Base delay in ms for exponential backoff (default: 60000 = 1 min) */ baseDelayMs: number; /** Maximum delay in ms (default: 3600000 = 1 hour) */ maxDelayMs: number; } interface AutoResumeConfig { /** Whether auto-resume is enabled (default: true) */ enabled: boolean; /** Maximum number of consecutive auto-resumes for token limits (default: 5) */ maxResumes: number; /** Delay in ms before sending continuation prompt (default: 1000) */ delayMs: number; /** The prompt sent to continue truncated responses */ continuePrompt: string; /** Rate limit handling configuration */ rateLimit: RateLimitConfig; } const DEFAULT_CONFIG: AutoResumeConfig = { enabled: true, maxResumes: 5, delayMs: 1000, continuePrompt: "Continue from where you left off. Do not repeat what you've already written. Pick up exactly where the previous response was cut off.", rateLimit: { enabled: true, maxRetries: 3, baseDelayMs: 60000, // 1 minute maxDelayMs: 3600000, // 1 hour }, }; // Patterns that indicate provider plan/rate limits const RATE_LIMIT_PATTERNS = [ // Anthropic /rate.?limit/i, /too.?many.?requests/i, /overloaded/i, /capacity/i, /throttl/i, // OpenAI /you.?have.?exceeded.?the.?rate/i, /you.?have.?exceeded.?your.?quota/i, /billing.?hard.?limit/i, /insufficient.?quota/i, /quota.?exceeded/i, // OpenCode / common /plan.?limit/i, /usage.?limit/i, /quota.?limit/i, /request.?limit/i, /api.?limit/i, /rate.?limit.?exceeded/i, /please.?slow.?down/i, /retry.?after/i, // GitHub Copilot /copilot.?quota/i, /copilot.?limit/i, // Generic /unavailable.*due.?to.?load/i, /temporarily.?unavailable/i, /service.?overloaded/i, /peak.?capacity/i, ]; // Patterns for billing/quota exhaustion (non-retryable without user action) const BILLING_LIMIT_PATTERNS = [ /billing/i, /payment/i, /subscription/i, /plan.?exhausted/i, /quota.?exhausted/i, /limit.?reached.*upgrade/i, /upgrade.?plan/i, /out.?of.?credits/i, /no.?remaining/i, ]; export default function (pi: ExtensionAPI) { let resumeCount = 0; let rateLimitRetryCount = 0; let config: AutoResumeConfig = { ...DEFAULT_CONFIG }; let lastResumedMessageId: string | null = null; let lastRateLimitTime: number = 0; // Load config from settings const loadConfig = () => { try { const settingsPath = require("node:path").join( process.env.PI_CODING_AGENT_DIR || require("node:os").homedir() + "/.pi/agent", "settings.json" ); const fs = require("node:fs"); if (fs.existsSync(settingsPath)) { const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8")); if (settings.autoResume) { config = { ...DEFAULT_CONFIG, ...settings.autoResume, rateLimit: { ...DEFAULT_CONFIG.rateLimit, ...(settings.autoResume.rateLimit || {}), }, }; } } } catch { // Use defaults } }; // Check if error message matches rate limit patterns const isRateLimitError = (errorMessage: string): boolean => { return RATE_LIMIT_PATTERNS.some((pattern) => pattern.test(errorMessage)); }; // Check if error message matches billing/quota exhaustion patterns const isBillingLimitError = (errorMessage: string): boolean => { return BILLING_LIMIT_PATTERNS.some((pattern) => pattern.test(errorMessage)); }; // Calculate delay with exponential backoff const calculateDelay = (attempt: number): number => { const delay = config.rateLimit.baseDelayMs * Math.pow(2, attempt - 1); return Math.min(delay, config.rateLimit.maxDelayMs); }; // Format delay for display const formatDelay = (ms: number): string => { if (ms < 60000) return `${Math.round(ms / 1000)}s`; if (ms < 3600000) return `${Math.round(ms / 60000)}m`; return `${Math.round(ms / 3600000 * 10) / 10}h`; }; // Reset counters on new session pi.on("session_start", async (_event, _ctx) => { resumeCount = 0; rateLimitRetryCount = 0; lastResumedMessageId = null; lastRateLimitTime = 0; loadConfig(); }); // Handle HTTP 429 responses (rate limiting) pi.on("after_provider_response", async (event, ctx) => { if (!config.enabled || !config.rateLimit.enabled) return; if (event.status === 429) { const retryAfterHeader = event.headers["retry-after"]; const retryAfterSeconds = retryAfterHeader ? parseInt(retryAfterHeader, 10) : null; const delayMs = retryAfterSeconds ? retryAfterSeconds * 1000 : calculateDelay(rateLimitRetryCount + 1); rateLimitRetryCount++; lastRateLimitTime = Date.now(); if (rateLimitRetryCount > config.rateLimit.maxRetries) { if (ctx.hasUI) { ctx.ui.notify( `Rate limit: max retries (${config.rateLimit.maxRetries}) exhausted. Please wait or switch provider.`, "error" ); } return; } if (ctx.hasUI) { const delayStr = formatDelay(delayMs); ctx.ui.notify( `Rate limited (429). Waiting ${delayStr} before retry... (${rateLimitRetryCount}/${config.rateLimit.maxRetries})`, "warning" ); } // Wait for the delay await new Promise((resolve) => setTimeout(resolve, delayMs)); // Pi's built-in retry should handle the actual retry // But if it doesn't, we can send a continue message if (ctx.isIdle()) { try { await ctx.sendUserMessage( "The previous request was rate limited. Please continue with your task.", { deliverAs: "followUp" } ); } catch (error) { // Ignore - Pi's retry should handle this } } } }); // Detect truncated responses and provider errors pi.on("message_end", async (event, ctx) => { if (!config.enabled) return; const message = event.message; // Only process assistant messages if (message.role !== "assistant") return; // === CASE 1: Token limit (max_tokens) === const isTruncated = message.stopReason === "length"; // === CASE 2: Incomplete tool call === const lastContent = message.content?.[message.content.length - 1]; const isIncompleteToolCall = lastContent?.type === "toolCall" && (!lastContent.arguments || Object.keys(lastContent.arguments).length === 0); // === CASE 3: Provider error (rate limit, billing, etc.) === const isProviderError = message.stopReason === "error" && message.errorMessage; const isRateLimit = isProviderError && isRateLimitError(message.errorMessage!); const isBillingLimit = isProviderError && isBillingLimitError(message.errorMessage!); // === CASE 4: Context overflow (defer to Pi's built-in compaction) === const isContextOverflow = isProviderError && (message.errorMessage?.toLowerCase().includes("context") || message.errorMessage?.toLowerCase().includes("too long") || message.errorMessage?.toLowerCase().includes("prompt is too long") || message.errorMessage?.toLowerCase().includes("maximum context") || message.errorMessage?.toLowerCase().includes("request too large") || message.errorMessage?.toLowerCase().includes("exceeds")); // Handle context overflow - let Pi's built-in compaction handle it if (isContextOverflow) { if (ctx.hasUI) { ctx.ui.notify("Context overflow detected. Pi will attempt auto-compaction.", "info"); } return; } // Handle billing limits - these require user action if (isBillingLimit) { if (ctx.hasUI) { ctx.ui.notify( `Provider billing/quota limit reached: "${message.errorMessage}"\nPlease upgrade your plan or switch provider with /model`, "error" ); } return; } // Handle rate limits from message_end (some providers report here instead of HTTP 429) if (isRateLimit) { if (!config.rateLimit.enabled) { if (ctx.hasUI) { ctx.ui.notify( `Rate limit detected but rate limit handling is disabled: "${message.errorMessage}"`, "warning" ); } return; } rateLimitRetryCount++; if (rateLimitRetryCount > config.rateLimit.maxRetries) { if (ctx.hasUI) { ctx.ui.notify( `Rate limit: max retries (${config.rateLimit.maxRetries}) exhausted.`, "error" ); } return; } const delayMs = calculateDelay(rateLimitRetryCount); if (ctx.hasUI) { ctx.ui.notify( `Rate limit detected. Waiting ${formatDelay(delayMs)} before retry... (${rateLimitRetryCount}/${config.rateLimit.maxRetries})`, "warning" ); } await new Promise((resolve) => setTimeout(resolve, delayMs)); if (ctx.isIdle()) { try { await ctx.sendUserMessage( "The previous request was rate limited. Please continue with your task.", { deliverAs: "followUp" } ); } catch (error) { if (ctx.hasUI) { ctx.ui.notify(`Retry failed: ${error instanceof Error ? error.message : String(error)}`, "error"); } } } return; } // If not a truncation or incomplete tool call, nothing to do if (!isTruncated && !isIncompleteToolCall) { return; } // === Handle token limit / incomplete tool call === // Don't resume if we've hit the limit if (resumeCount >= config.maxResumes) { if (ctx.hasUI) { ctx.ui.notify( `Auto-resume limit reached (${config.maxResumes} resumes). Stopping.`, "warning" ); } return; } // Don't resume the same message twice if (lastResumedMessageId === message.timestamp?.toString()) { return; } // Check if agent is idle if (!ctx.isIdle()) { return; } // Increment counter resumeCount++; lastResumedMessageId = message.timestamp?.toString(); const reason = isTruncated ? "token limit (max_tokens)" : "incomplete tool call (output truncated)"; if (ctx.hasUI) { ctx.ui.notify( `Response truncated (${reason}). Auto-resuming... (${resumeCount}/${config.maxResumes})`, "info" ); } // Delay to let turn settle await new Promise((resolve) => setTimeout(resolve, config.delayMs)); if (!ctx.isIdle()) { return; } // Choose continuation prompt const continuePrompt = isIncompleteToolCall ? "Your previous response was cut off mid-tool-call. Please complete the tool call you were making, or if you were finished with tool calls, provide your final response." : config.continuePrompt; try { await ctx.sendUserMessage(continuePrompt, { deliverAs: "followUp" }); } catch (error) { if (ctx.hasUI) { ctx.ui.notify( `Auto-resume failed: ${error instanceof Error ? error.message : String(error)}`, "error" ); } resumeCount--; lastResumedMessageId = null; } }); // Reset rate limit counter when things are going well pi.on("agent_settled", async (_event, ctx) => { // Reset rate limit counter after successful completion if (rateLimitRetryCount > 0) { rateLimitRetryCount = 0; } // Log token limit resume completion if (resumeCount > 0 && config.enabled) { if (ctx.hasUI) { ctx.ui.notify(`Auto-resume completed (${resumeCount} continuations)`, "info"); } resumeCount = 0; lastResumedMessageId = null; } }); // Add system prompt guidance pi.on("before_agent_start", async (event, _ctx) => { // Reset resume counter on new user message resumeCount = 0; lastResumedMessageId = null; if (!config.enabled) return; const autoResumeGuidance = ` ## Auto-Resume Behavior When your response is cut off due to token limits, you will receive a continuation message. When this happens: - Do NOT repeat any content you already wrote - Continue exactly from where you left off - If you were in the middle of a tool call, complete it - If you were writing code, continue from the last line - Keep the same style and format as before - Be mindful of output length to minimize truncations `; return { systemPrompt: event.systemPrompt + autoResumeGuidance, }; }); // Register commands pi.registerCommand("auto-resume", { description: "Check auto-resume status or configure", handler: async (args, ctx) => { const subcommand = args.trim().toLowerCase(); if (subcommand === "status" || subcommand === "") { ctx.ui.notify( `Auto-Resume Status:\n` + ` Enabled: ${config.enabled ? "yes" : "no"}\n` + ` Token limit resumes: ${resumeCount}/${config.maxResumes}\n` + ` Rate limit retries: ${rateLimitRetryCount}/${config.rateLimit.maxRetries}\n` + ` Rate limit handling: ${config.rateLimit.enabled ? "enabled" : "disabled"}\n` + ` Delay: ${config.delayMs}ms\n` + ` Rate limit base delay: ${formatDelay(config.rateLimit.baseDelayMs)}`, "info" ); return; } if (subcommand === "on" || subcommand === "enable") { config.enabled = true; ctx.ui.notify("Auto-resume enabled", "info"); return; } if (subcommand === "off" || subcommand === "disable") { config.enabled = false; ctx.ui.notify("Auto-resume disabled", "info"); return; } if (subcommand === "reset") { resumeCount = 0; rateLimitRetryCount = 0; lastResumedMessageId = null; ctx.ui.notify("Auto-resume counters reset", "info"); return; } ctx.ui.notify( "Usage: /auto-resume [status|on|off|reset]", "info" ); }, }); }