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

[bossriceshark]

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 <topic> 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 <topic> through the existing feat(acp): pass slash commands through to ACP connectors #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 feat(desktop): slash-command autocomplete in composer from ACP available_commands_update (follow-up to #919) #2528 or feat(desktop): autocomplete ACP slash commands (rebase of #2653) #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

• feat(acp): pass slash commands through to ACP connectors #919 — merged ACP slash-command pass-through
• feat(desktop): slash-command autocomplete in composer from ACP available_commands_update (follow-up to #919) #2528 — slash-command discovery/autocomplete issue
• feat(desktop): autocomplete ACP slash commands (rebase of #2653) #3537 — active autocomplete PR
• Add countdown bot reference example #516 — merged standalone bot reference example

No existing issue or PR was found for a Last30Days reference agent.