feat(examples): add a provider-agnostic Last30Days agent
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Motivation
Buzz already passes a leading slash command through to ACP connectors (#919), but the repository has no small end-to-end reference agent that advertises a useful slash command and demonstrates a safe long-running implementation.
That leaves contributors to rediscover several integration details at once:
- advertising a command through ACP `available_commands_update`;
- accepting the bare command block while retaining Buzz channel and thread context;
- publishing an acknowledgement and a final threaded result;
- running parallel model work with an explicit success threshold;
- keeping provider credentials out of prompts, artifacts, logs, and public errors; and
- bounding concurrency, retries, cost, cooldowns, and per-request output.
`/last30days ` is a useful flagship example because it exercises the full path without adding command semantics to Buzz itself: collect recent evidence, ask multiple workers for independent analysis, synthesize one sourced brief, and publish it back to the originating thread.
## Proposed solution
Add an examples-only package at `examples/last30days-agent/` that runs as an ACP-compatible Last30Days agent.
The first version would:
- advertise `/last30days` with a one-line description;
- accept `/last30days ` through the existing #919 pass-through path;
- run 10 independent analysis workers by default, followed by one synthesis call;
- require all configured workers to return usable message content before publishing a brief;
- support any OpenAI-compatible endpoint through environment configuration;
- document OpenRouter plus `deepseek/deepseek-v4-pro` as the working default, while allowing adopters to choose another provider/model;
- read the API key only from the process environment, with no env-file discovery or bundled credentials;
- keep artifacts private and receipts metadata-only;
- sanitize public failures and never publish raw provider responses, stderr, host paths, or secrets;
- enable bounded concurrency, retries, cooldown, requester quota, and a spend ceiling by default; and
- include offline mocked tests plus a manual Buzz smoke-test recipe.
The example would follow the focused reference style of `examples/countdown-bot` (#516) and the portable configuration/documentation style of `examples/meadow-core`.
## Alternatives considered
### Add command execution semantics to Buzz core
Rejected. #919 deliberately keeps command meaning in ACP connectors, and that boundary should remain intact.
### Add slash-command discovery or composer UI
Rejected as duplicate scope. #2528 tracks discovery and #3537 is the active implementation.
### Ship the current machine-specific runner unchanged
Rejected. A public example must not contain owner keys, pubkeys, channel IDs, absolute host paths, private env-file locations, or a hard dependency on one provider account.
### Publish only a prompt or skill file
Too weak for the reference goal. It would not prove the ACP command lifecycle, failure handling, provider boundary, or 10-worker success contract end to end.
## Non-goals
- No relay, event-kind, or Desktop UI changes.
- No replacement for #2528 or #3537.
- No provider credentials, secret storage system, or hosted service.
- No guarantee that every OpenAI-compatible provider supports web search; evidence acquisition remains an explicit, documented backend capability.
- No general plugin marketplace or command framework.
- No changes to the existing `examples/countdown-bot` behavior.
## Acceptance shape
- A clean checkout can run the offline example tests without a provider key.
- With adopter-supplied configuration, the agent advertises `/last30days`, accepts one command through `buzz-acp`, and posts a threaded result only after the configured worker threshold and synthesis succeed.
- The default configuration uses 10 workers and the documented DeepSeek V4 Pro model slug.
- Model/base URL/worker count/gates are configurable without code changes.
- Secret scanning of logs, receipts, and output finds no API key or Buzz credential material.
- Example artifacts use private directory/file modes on Unix.
- The package is documented from installation through manual Buzz verification.
- Repository formatting, lint, unit tests, and the applicable `just ci` gate pass.
## Related work
- #919 — merged ACP slash-command pass-through
- #2528 — slash-command discovery/autocomplete issue
- #3537 — active autocomplete PR
- #516 — merged standalone bot reference example
No existing issue or PR was found for a Last30Days reference agent.
Contributor guide
Research direction
Start by reading examples/countdown-bot and examples/meadow-core, then trace the existing #919 ACP slash-command pass-through used by buzz-acp. Add the package under examples/last30days-agent/ with offline mocked tests and the documented manual Buzz smoke test. Done means the configured worker threshold and synthesis produce a private, sanitized threaded result, with the stated configuration and just ci checks passing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design, documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100