avelino / avelino/dotagent

Declarative `[retry]` policy in `agent.toml`

Open
#24 0 comments 0 reactions 0 assignees View on GitHub
area: manifest area: runner breaking-change type: feature
Dominant language
Rust
Stars
3
Forks
1
Avg merge
4h 50m
Merged PRs (30d)
1

Description

When an agent fails, the daemon already retries (see `attempts` in the audit log's `AgentRecovered` / `AgentGivenUp` events). But retry behavior — max attempts, delay between attempts, backoff strategy — is currently baked into the daemon code, not declared in the manifest. Every agent gets the same policy.

This is wrong for a polyglot orchestrator. A 10-second linkedin scraper should retry quickly; a 30-minute Databricks query should not retry at all.

## Proposal

A new `[retry]` block in `agent.toml` declaring the per-agent retry policy:

```toml
[retry]
max_attempts = 3
backoff = "exponential" # none | linear | exponential
initial_delay_seconds = 30
max_delay_seconds = 900
jitter = true
retry_on = ["timeout", "non-zero-exit"] # | "any" | specific exit codes
```

Defaults preserve today's behavior so existing manifests don't break.

This is a **breaking change** to the manifest schema only if today's defaults disagree with the new defaults — otherwise it is additive.

## Acceptance criteria

- [ ] `[retry]` parses in `dotagent-core`'s `AgentManifest`.
- [ ] Scheduler honors `max_attempts`, `backoff`, `initial_delay_seconds`, `max_delay_seconds`, `jitter`.
- [ ] `retry_on` filter works: `["timeout"]` retries timeouts but not non-zero exits, etc.
- [ ] When `[retry]` is absent, behavior matches today exactly (regression-tested).
- [ ] [`docs/reference/agent-spec.md`](docs/reference/agent-spec.md) gains a `[retry]` section.
- [ ] Example added under `examples/`.

## Where to start

- `crates/dotagent-core/src/manifest.rs` — schema addition.
- `crates/dotagent-scheduler/src/lib.rs` — where retry timing is computed today.
- `crates/dotagent-runner/src/lib.rs` — outcome interpretation.

## Non-goals

- Mid-run retries (the agent itself retries internally). This is *between* runs.
- Replacing the OS scheduler. Retries still fire from the daemon tick loop.

Contributor guide

Open the contributing guide

Research direction

Start with crates/dotagent-core/src/manifest.rs, then trace retry timing in crates/dotagent-scheduler/src/lib.rs and outcome interpretation in crates/dotagent-runner/src/lib.rs. Review existing retry behavior and the AgentRecovered/AgentGivenUp audit events before assessing the manifest proposal. Done means the listed acceptance criteria pass, including regression coverage, documentation in docs/reference/agent-spec.md, and an example under examples/.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.