block / block/buzz

feat(examples): add a provider-agnostic Last30Days agent

Open
#4,158 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.