speakeasy-api / speakeasy-api/kit

Include structured retry exhaustion accounting and correlation IDs in terminal failures

Open
#47 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
40
Forks
4
Avg merge
4h 18m
Merged PRs (30d)
148

Description

Summary

Terminal provider failures do not expose a complete structured retry summary. Attempt count can appear in rendered text and fatal records already have session/event identity, but cumulative backoff and correlation data are not propagated together as typed exhaustion metadata to the failing tool boundary.

Split from #35 after the transient overload retry policy was fixed by #32.

Desired behavior

On retry exhaustion, provide a structured, sanitized summary containing:

  • total attempts;
  • cumulative backoff or sleep time;
  • total elapsed retry time;
  • final retry/exhaustion category; and
  • session ID and event ID, or an equivalent stable correlation reference to the fatal record.

The parent should not need to parse a rendered error string or search ~/.kit/errors to correlate the tool failure with its fatal record. This issue is about terminal accounting; live progress belongs in a separate issue.

Suggested coverage

  • Use deterministic time to verify attempts, cumulative delays, and elapsed time.
  • Verify the parent-visible structured failure correlates with the schema-v2 fatal record.
  • Cover subagent(...) through compose(background=true).
  • Assert no provider body, credentials, private prompts, or customer identifiers are exposed.

Environment

  • Originally observed with Kit 0.1.96 on Darwin 25.6.0 arm64.
  • Confirmed as a remaining gap on Kit 0.1.105 on Darwin 25.5.0 arm64.
  • Surface: ACP; provider route: openai-subscription.

Related work

  • #35
  • #32

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the ACP provider failure boundary and the schema-v2 fatal record, then trace how subagent(...) flows through compose(background=true). Add deterministic coverage for attempts, delays, elapsed time, correlation, and sanitization; done means the parent receives typed terminal metadata without sensitive provider data.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.