pi-pattern-retry

Keep your Pi Agent session alive across provider rate-limits, quota exhaustion, and transient auth failures. pi-pattern-retry watches provider responses and agent errors, matches them against configurable patterns (regex / substring), and re-injects a continuation message at escalating intervals — 30s → 1m → 5m → 15m → 30m → 1h → 4h → 5h → 12h → 24h by default — so the agent picks up where it left off.

Designed alongside todo-enforcer: same retry-scheduler idea, separate package, ships independently.

Install

pi install npm:pi-pattern-retry

Then restart your Pi session. The plugin ships with sensible defaults — no config file is required to get started.

What it does

Two trigger sources feed one matcher:

| Event | What it inspects | |---------------------------|------------------------------------------------------------------| | after_provider_response | HTTP status — catches 401 / 403 / 429 / 5xx | | agent_end | last assistant message's errorMessage — catches transport text |

A match schedules one timer per (sessionId, patternName). When the timer fires:

1. If the conversation has progressed (branch grew, excluding our own injections), reset attempt counter and stop.
2. Otherwise inject pi.sendUserMessage(<your template>) so the agent retries.
3. Advance to the next delay in the schedule. When the schedule is exhausted, the pattern stays inert until /pattern-retry-reset.

Duplicate triggers (e.g. both events firing for the same failure) are debounced — the already-live timer wins.

Default patterns

Shipped with three patterns pre-seeded. Override or replace via config file.

| Name | Trigger | Schedule (seconds) | |------------------------|----------------------|------------------------------------------------------------------------| | llm-429-quota | HTTP 429 | 30, 60, 300, 900, 1800, 3600, 14400, 18000, 43200, 86400 (10 steps) | | llm-401-403-auth | HTTP 401 / 403 | 60, 300, 1800 (3 steps) | | litellm-weekly-limit | errorMessage contains "Weekly/Monthly Limit Exhausted" | 3600, 14400, 43200, 86400 |

Configuration

Global file: ~/.pattern-retry.json. Project override: <cwd>/.pattern-retry.json. Project keys override global; arrays replace, they do not merge.

{
  "enabled": true,
  "patterns": [
    {
      "name": "llm-429-quota",
      "match": { "source": "providerStatus", "kind": "regex", "value": "^429$" },
      "scheduleSec": [30, 60, 300, 900, 1800, 3600, 14400, 18000, 43200, 86400],
      "message": "Provider returned {{status}} (attempt {{attempt}}/{{maxAttempts}}). Retrying after {{lastDelaySec}}s.",
      "stopOnProgress": true,
      "notify": ["webhook", "dashboard"]
    },
    {
      "name": "litellm-weekly-limit",
      "match": {
        "source": "errorMessage",
        "kind": "contains",
        "value": "Weekly/Monthly Limit Exhausted"
      },
      "scheduleSec": [3600, 14400, 43200, 86400],
      "message": "Hit weekly LLM quota. Resuming attempt {{attempt}}."
    }
  ],
  "notifyTargets": {
    "webhook":   { "enabled": false, "url": "", "headers": {}, "timeoutMs": 10000 },
    "dashboard": { "enabled": false, "endpoint": "" }
  }
}

Match semantics

• kind: "contains" — case-sensitive substring match.
• kind: "regex" — compiled with new RegExp(value); no implicit flags. For case-insensitive, encode flags in the pattern itself.
• source: "providerStatus" — matched against the decimal status string (e.g. "429").
• source: "errorMessage" — matched against the assistant message's errorMessage string. If absent/empty, the pattern does not match.

A malformed regex degrades to a logged warning — other patterns continue to work.

Template variables

| Variable | Value | |--------------------|----------------------------------------------------------------| | {{status}} | HTTP status from providerStatus, or 0 | | {{statusText}} | Human label (e.g. "Too Many Requests") | | {{reason}} | Match-source snippet | | {{patternName}} | The matched pattern's name | | {{attempt}} | 1-indexed current attempt | | {{maxAttempts}} | scheduleSec.length | | {{lastDelaySec}} | Delay that elapsed before this fire | | {{nextDelaySec}} | Next delay if any, else 0 |

Missing variables interpolate to empty string.

Commands

• /pattern-retry-status — show each pattern's attempt/max, exhausted, and scheduled flags.
• /pattern-retry-reset [patternName|all] — cancel timer(s) and reset attempt counter.
• /pattern-retry-toggle — flip the global enabled flag.
• /pattern-retry-log [N] — tail the last N lines (default 50, max 500) of the central log file straight into the session.

Troubleshooting / Logs

Every meaningful decision is appended to a single central log file:

~/.pi/logs/extensions/pattern-retry.log

This is the shared convention across all pi extensions — written via the rotated, size-capped (25 MB, 80% trim) createPluginLogger. Each line is:

<iso-timestamp> [pattern-retry] <LEVEL> <event> <json-details>

Events you can grep for:

| Event | Means | |--------------------------------|------------------------------------------------------------------------| | session-start | Session bound to pattern-retry; sessionId + cwd recorded | | config-loaded / config-load failed | Result of merging ~/.pattern-retry.json + project override | | trigger:matched | A provider/error trigger arrived; lists matched pattern names | | trigger:skipped-disabled / trigger:skipped-no-session | Trigger dropped — explains why | | schedule:armed | Timer set; attempt, delaySec, trigger metadata | | schedule:skip-idempotent | Duplicate trigger dropped because a live timer already exists | | schedule:skip-exhausted / schedule:exhausted | All attempts used up | | timer:elapsed | Scheduled delay elapsed; about to fire | | fire:injected | Continuation message sent via pi.sendUserMessage | | fire:reset-on-progress | Agent advanced before timer fired → attempt counter reset, no send | | cancel:pattern / cancel:session | /pattern-retry-reset or session shutdown | | command:toggle / command:reset / command:reset-all | Audit trail for user commands | | notify:<event>:<target> | A configured notify target fired (V1: log-only) |

When something looks wrong:

tail -f ~/.pi/logs/extensions/pattern-retry.log
# or from inside a session:
/pattern-retry-log 200

The file is the source of truth — every fire, skip, reset, and exhaustion is there with the sessionId and pattern name attached, so you can reconstruct exactly what happened and why.

Notify hooks (V1: no-op)

Each pattern may carry notify?: ("webhook" | "dashboard")[]. V1 logs one line per enabled target — real HTTP/WebSocket senders ship in V2 (see flow/plans/pattern-retry-future.md upstream).

The notifyHooks() signature is the public contract — V2 swaps the implementation without changing callers.

How it differs from todo-enforcer

| Plugin | Trigger | Use case | |---------------------|----------------------------------|-------------------------------------------------| | todo-enforcer | Idle agent with pending todos | Nudge the agent to keep working on its list | | pi-pattern-retry | Provider error / quota signal | Resume after an external rate-limit or outage |

They share the retry-scheduler pattern (copy-adapted), not code — install one without the other.

License

MIT