v1.9.0

This release centers three visible changes: a single command for opening the Agent Swarm TUI, OpenClaw support inside Agency Swarm, and more control over FastAPI requests for OpenAI and LiteLLM models.

If you're new to Agency Swarm, here's the short version:

- **Agent Swarm TUI**: run `npx @vrsen/agentswarm` from your project root. On first launch, the TUI can select or create a project, prepare `.venv`, install dependencies, and open local `Agent Builder` mode. See the [Agent Swarm CLI docs](https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli).
- **OpenClaw support**: expose OpenClaw through Agency Swarm's FastAPI integration and use `OpenClawAgent` for worker-oriented flows. See the [OpenClaw marketplace docs](https://agency-swarm.ai/platform/marketplace/openclaw) and [OpenClawAgent docs](https://agency-swarm.ai/core-framework/third-party-agents/openclaw-agent#openclawagent).
- **Request-scoped FastAPI control**: for OpenAI and LiteLLM models, change `base_url`, `api_key`, headers, and LiteLLM provider keys for one request at a time.
- **Run-scoped multi-agent control**: runs can keep their own agency context, use the public `streaming_context` field, and refresh recipient reminders after manual handoff switches.

## Compatibility Notes

These notes call out the small number of limits and behavior changes you may notice after upgrading.

- `npx @vrsen/agentswarm` is now the main terminal launch path. `agency.tui()` is still supported as the Python-first path, and `terminal_demo()` remains a backward-compatible alias.
- `tui(show_reasoning=False)` is not supported in the new TUI yet.
- FastAPI is stricter in a few useful ways: wildcard CORS origins no longer keep credentials turned on automatically, and the metadata response now shows absolute `allowed_local_file_dirs` entries.

## Features

The main additions in this release are a simpler way to open the TUI, built-in OpenClaw support, and more control over FastAPI requests and agent runs.

- **Open the Agent Swarm TUI with one command** by @bonk1t in #566, #572, #574, #577, #581, #584, #589, #590, #601, #602, #603, and #608
  - **What changed**: `npx @vrsen/agentswarm` is now the main way to open the TUI. On first run, it can help you choose or create a project, set up `.venv`, install dependencies, and open local `Agent Builder` mode. `agency.tui()` still works for Python-first projects. See the [Agent Swarm CLI docs](https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli).
  - **Why it matters**: New users now have one clear way to start, while existing Python-first projects can keep `agency.tui()`.

- **OpenClaw runtime, proxy, and agent support inside Agency Swarm** by @bonk1t in #540, #554, #582, and #583
  - **What changed**: Agency Swarm now includes OpenClaw runtime and proxy support, the `openclaw:main` alias, a worker-focused `OpenClawAgent`, replay coverage, and dedicated docs and marketplace coverage: [OpenClaw marketplace docs](https://agency-swarm.ai/platform/marketplace/openclaw) and [OpenClawAgent docs](https://agency-swarm.ai/core-framework/third-party-agents/openclaw-agent#openclawagent).
  - **Why it matters**: OpenClaw can now be exposed and operated through Agency Swarm using the built-in runtime, proxy, and agent paths.

- **Request-scoped FastAPI client overrides** by @ArtemShatokhin in #518
  - **What changed**: For OpenAI and LiteLLM models, each request can bring its own `base_url`, `api_key`, `default_headers`, and LiteLLM provider keys. Custom `Model` subclasses keep their current behavior.
  - **Why it matters**: This makes it easy to send one request through a different provider, environment, or header set without changing the rest of your app.

- **Run-scoped agency context and public streaming state** by @bonk1t in #555, #558, and #561
  - **What changed**: Runs can use isolated agency context, and `streaming_context` is now the supported public path instead of private state access.
  - **Why it matters**: Multi-agent streaming and per-run isolation are easier to extend without relying on private framework internals.

- **Simpler custom `SendMessage` extensions and better handoff control** by @bonk1t in #564 and #597
  - **What changed**: Custom `SendMessage` tools can define inline fields more easily, and recipient reminders refresh when users manually switch agents after a handoff.
  - **Why it matters**: Tool customization is simpler, and handoff-heavy flows stay aligned with the active recipient.

## Improvements & Fixes

This release also fixes several FastAPI and file-handling issues and refreshes the framework default model.

- **Safer FastAPI and file handling** by @bonk1t, @ArtemShatokhin, and @RinZ27 in #537, #547, #548, #553, #557, #559, and #560
  - **What changed**: Remote PDF fallback is more reliable, header overrides now work correctly even when there is no baseline OpenAI client, downloads no longer collide or leak temp files, wildcard CORS origins now disable credentials automatically, and metadata now shows absolute `allowed_local_file_dirs` entries.
  - **Why it matters**: FastAPI deployments are more predictable under real traffic, file-heavy flows, and wildcard-origin setups.

- **Framework default model now uses `gpt-5.4-mini` instead of the SDK's `gpt-4.1`** by @bonk1t in #578, #580, and #591
  - **What changed**: Agency Swarm's framework default model is now `gpt-5.4-mini` rather than the SDK's `gpt-4.1`.
  - **Why it matters**: Agents that rely on framework defaults now start from the model family Agency Swarm is actually tuned and tested against.

## Docs

The public docs now cover the new `user_context`, FastAPI, and tool streaming paths.

- **Docs and examples for `user_context`, FastAPI, and tool streaming** by @MykhailoShchuka, @ArtemShatokhin, and @bonk1t in #508, #546, and #556
  - Adds public docs for `user_context` and widget control, expands the FastAPI example, and adds tool streaming guidance.

## Other Work

- **Internal maintenance** by @bonk1t in #570, #571, and #607

## Tests

These changes also come with broader test coverage across the TUI, OpenClaw, FastAPI, and runtime paths.

- **Quality, typing, and release hardening across TUI, OpenClaw, FastAPI, and runtime paths** by @bonk1t in #542, #545, #549, #563, #575, and #576
  - Tightens coverage, typing, hosted-tool tests, OpenClaw-adjacent checks, and oversized test structure so the new runtime paths ship with broader automated coverage.

## New Contributors

- @RinZ27 made their first contribution in #548

**Full Changelog**: https://github.com/VRSEN/agency-swarm/compare/v1.8.0...v1.9.0