# Pi Auto-Resume Extension

A [Pi coding agent](https://pi.dev) extension that automatically resumes when responses are interrupted by token limits, rate limits, or provider plan exhaustion.

## The Problem

When working with AI coding assistants, your workflow gets interrupted by:

1. **Token limits** - Response truncated mid-generation because it hit `max_tokens`
2. **Rate limits** - HTTP 429 errors when you exceed API rate limits (Claude Pro, OpenAI, etc.)
3. **Plan limits** - Quota/billing exhaustion on subscription plans (Claude Max, OpenCode, etc.)
4. **Incomplete tool calls** - Output cut off mid-tool-call, leaving broken JSON

These interruptions break your flow and require manual intervention to continue.

## The Solution

This extension handles all these cases automatically:

- **Token truncation** → Sends continuation prompt to finish the response
- **Rate limits (429)** → Waits for retry-after period, then retries
- **Plan/quota errors** → Notifies user to upgrade or switch provider
- **Incomplete tool calls** → Prompts model to complete the tool call

## Features

| Feature | Description |
|---------|-------------|
| **Token limit detection** | Detects `stopReason: "length"` (max_tokens hit) |
| **Rate limit handling** | Detects HTTP 429 and rate limit error messages |
| **Plan limit detection** | Detects billing/quota exhaustion errors |
| **Incomplete tool call detection** | Detects cut-off tool calls with empty arguments |
| **Exponential backoff** | Rate limit retries use exponential backoff (1m, 2m, 4m...) |
| **Retry-after support** | Respects `Retry-After` headers from providers |
| **Configurable limits** | Max resumes, delays, and retry counts are configurable |
| **System prompt guidance** | Tells the model how to handle continuation gracefully |
| **Manual control** | `/auto-resume` command for status, enable/disable, reset |

## Installation

### One-liner install (easiest)

**Linux/macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/kasaiarashi/pi-auto-resume/master/install.sh | bash
```

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/kasaiarashi/pi-auto-resume/master/install.ps1 | iex
```

**Windows (batch):** Download and run `install.bat` from [Releases](https://github.com/kasaiarashi/pi-auto-resume/releases)

### Pi package install

```bash
pi install git:github.com/kasaiarashi/pi-auto-resume
```

### Manual install

```bash
cp auto-resume-on-token-limit.ts ~/.pi/agent/extensions/
```

Pi will automatically load it on next startup.

## Configuration

Add to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project):

```json
{
  "autoResume": {
    "enabled": true,
    "maxResumes": 5,
    "delayMs": 1000,
    "continuePrompt": "Continue from where you left off. Do not repeat what you've already written.",
    "rateLimit": {
      "enabled": true,
      "maxRetries": 3,
      "baseDelayMs": 60000,
      "maxDelayMs": 3600000
    }
  }
}
```

### Settings Reference

| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `true` | Enable/disable auto-resume |
| `maxResumes` | `5` | Max consecutive token limit continuations |
| `delayMs` | `1000` | Delay (ms) before sending continuation message |
| `continuePrompt` | (see above) | Prompt for truncated responses |
| `rateLimit.enabled` | `true` | Enable rate limit handling |
| `rateLimit.maxRetries` | `3` | Max rate limit retry attempts |
| `rateLimit.baseDelayMs` | `60000` | Base delay (1 min) for exponential backoff |
| `rateLimit.maxDelayMs` | `3600000` | Maximum delay (1 hour) |

## Commands

| Command | Description |
|---------|-------------|
| `/auto-resume` or `/auto-resume status` | Show current status |
| `/auto-resume on` or `/auto-resume enable` | Enable auto-resume |
| `/auto-resume off` or `/auto-resume disable` | Disable auto-resume |
| `/auto-resume reset` | Reset all counters |

## How It Works

### Token Limit Handling

1. **Detection**: Listens for `message_end` with `stopReason === "length"`
2. **Safety checks**: Won't exceed `maxResumes`, checks agent is idle
3. **Delay**: Waits `delayMs` for turn to settle
4. **Continuation**: Sends follow-up message via `sendUserMessage()`
5. **System prompt**: Adds guidance telling model not to repeat content

### Rate Limit Handling

1. **Detection**: HTTP 429 responses or rate limit error messages
2. **Wait**: Respects `Retry-After` header or calculates exponential backoff
3. **Retry**: Sends continue message after delay
4. **Limits**: Stops after `maxRetries` attempts

### Plan Limit Handling

1. **Detection**: Error messages matching billing/quota patterns
2. **Notification**: Alerts user to upgrade plan or switch provider
3. **No auto-retry**: These require user action

## Detected Error Patterns

### Rate Limits (auto-retry)
- Anthropic: "rate limit", "too many requests", "overloaded", "capacity"
- OpenAI: "exceeded the rate", "exceeded your quota"
- OpenCode: "plan limit", "usage limit"
- Generic: "retry after", "slow down", "temporarily unavailable"

### Plan Limits (user action required)
- "billing", "payment", "subscription"
- "quota exhausted", "plan exhausted"
- "upgrade plan", "out of credits"

### Context Overflow (Pi's built-in compaction)
- "context", "too long", "prompt is too long"
- "maximum context", "request too large"

## What About Context Overflow?

Pi already has built-in auto-compaction for context window overflow. This extension defers to Pi's built-in handling for those cases and focuses on:

1. **Output truncation** (max_tokens)
2. **Provider rate limits** (HTTP 429)
3. **Plan/quota exhaustion** (billing errors)
4. **Incomplete tool calls** (truncated JSON)

## License

MIT