v3.1.0

## New Features

- **User Management / Authorization (RBAC):** a new `agno.os.authz` package adds role-based access control to AgentOS — a role store, scope policy, audit log, user directory and an admin router, with pluggable authorization engines (a native engine plus a fine-grained `fga` engine). Scopes and auth middleware were extended to enforce it.
- **AgentOS Filesystem:** a new `agno.fs` filesystem (`DbFileSystem`) with dedicated `/filesystem` routes (list/read/manage files) backed by an `agno_fs` table.
- **MCP config / auth updates:** refreshed MCP server config and built-in MCP auth handling.
- **AIMLAPITools:** new toolkit for image, video, speech and transcription via the AI/ML API.

## ⚠️ Breaking Changes

- Filesystem table re-key (`agno_fs`): v3.1 keys the filesystem table by `(namespace, user_id, path)`, where `user_id` is the user partition (`""` for the shared/no-user partition). A table created by an earlier release is refused with `SchemaOutdatedError` until upgraded — the re-key never runs automatically. Upgrade once, with the application stopped, using the script for your database (#10530):

This affects you only if you use `DbFileSystem`. The table is managed by `DbFileSystem` (its own schema, buildable from a bare `db_url`), so it is deliberately not part of `MigrationManager`.
    
```python
python libs/agno/migrations/migrate_filesystem_postgres.py   # PostgreSQL
python libs/agno/migrations/migrate_filesystem_sqlite.py     # SQLite
 ```
 - **MCP default & lifecycle tools are now opt-in:** `MCPConfig(tools=[...])` now publishes exactly the tools you list — both `default_tools` and `lifecycle_tools` default to `False`. Previously a `tools=[...]` config also served the built-in default tools (and the lifecycle `continue_run / cancel_run`).

## Bug Fixes

- **HITL:** continuing a paused run with `background` + `stream` no longer duplicates the paused run in its own history.
- **OpenAIResponses:** recover requests when the chained (previous) response is gone.
- **DB:** an async delete that *failed* is no longer reported as a run that *wasn't there* — the two cases are distinguished.
- **Structured output:** don't crash when a JSON fragment provides a scalar before a list.
- **Python tool results:** distinguish `None`valued results from missing variables.
- **Chunking:** reject an overlap that is not smaller than the chunk size.
- **CSV readers:** handle CR (`\r`) record endings.
- **CsvTools:** honor explicit zero row limits.
- **Shell / workspace command tools:** honor an explicit zero `tail`.
- **GeminiTools:** store raw video bytes in the `generate_video` artifact.
- **GithubTools:** build branch links from the repository web URL (#10509); `get_file_content` preserves valid non-ASCII UTF-8 text
- **LocalFileSystemTools:** read and write local files as UTF-8.
- **PubMed:** preserve metadata for short abstracts.
- **Claude citations:** preserve nullable document titles.

## What's Changed
* [fix] Honor explicit zero row limits in CsvTools by @hfg369 in https://github.com/agno-agi/agno/pull/10492
* [fix] GithubTools.get_file_content: preserve valid non-ASCII UTF-8 text by @indexGin in https://github.com/agno-agi/agno/pull/10480
* fix: recover OpenAIResponses requests when the chained response is gone by @ysolanky in https://github.com/agno-agi/agno/pull/10395
* [feat] Add AIMLAPITools: image, video, speech and transcription via AI/ML API by @hugoaimlapi in https://github.com/agno-agi/agno/pull/10276
* test: abort the create name prompt with Ctrl-D instead of SIGINT by @ysolanky in https://github.com/agno-agi/agno/pull/10541
* fix: Add GPT 6 series to reasoning list and Add GPT-6 Astra reasoning cookbook example by @RayST3 in https://github.com/agno-agi/agno/pull/10542
* fix: make `test_encoded_sse_cannot_bypass_public_error_inspection` test more robust by @sannya-singal in https://github.com/agno-agi/agno/pull/10533
* [fix] Read and write local files as UTF-8 in LocalFileSystemTools by @yetuge in https://github.com/agno-agi/agno/pull/10538
* [fix] Build GithubTools branch links from repository web URL by @jiangjiang248 in https://github.com/agno-agi/agno/pull/10509
* fix: reject an overlap that is not smaller than the chunk size by @sclfcz in https://github.com/agno-agi/agno/pull/10321
* fix: store raw video bytes in GeminiTools.generate_video artifact by @BlueX888 in https://github.com/agno-agi/agno/pull/10554
* [fix] Honor explicit zero tail in shell and workspace command tools by @yetuge in https://github.com/agno-agi/agno/pull/10593
* chore: move Docling knowledge tests into their own CI job by @sannya-singal in https://github.com/agno-agi/agno/pull/10499
* [fix] Preserve nullable document titles in Claude citations by @basnijholt in https://github.com/agno-agi/agno/pull/10147
* [fix] Preserve PubMed metadata for short abstracts by @zyouekiri in https://github.com/agno-agi/agno/pull/10640
* [fix] Distinguish None-valued Python tool results from missing variables by @icearia0219 in https://github.com/agno-agi/agno/pull/10637
* [fix] Handle CR record endings in CSV readers by @lakers-abing in https://github.com/agno-agi/agno/pull/10657
* fix: HITL continue with background and stream duplicates the paused run in its own history by @kausmeows in https://github.com/agno-agi/agno/pull/10597
* [fix] db: an async delete that failed is not a run that was not there by @ericdelorefice in https://github.com/agno-agi/agno/pull/10682
* [fix] Don't crash when a JSON fragment provides a scalar before a list by @inchang-ing in https://github.com/agno-agi/agno/pull/10654
* feat: v3.1 by @kausmeows in https://github.com/agno-agi/agno/pull/10530
* feat: make MCPConfig default and lifecycle tools opt-in by @ashpreetbedi in https://github.com/agno-agi/agno/pull/10285
* feat: Release v3.1.0 by @kausmeows in https://github.com/agno-agi/agno/pull/10702

## New Contributors
* @hfg369 made their first contribution in https://github.com/agno-agi/agno/pull/10492
* @indexGin made their first contribution in https://github.com/agno-agi/agno/pull/10480
* @jiangjiang248 made their first contribution in https://github.com/agno-agi/agno/pull/10509
* @sclfcz made their first contribution in https://github.com/agno-agi/agno/pull/10321
* @zyouekiri made their first contribution in https://github.com/agno-agi/agno/pull/10640
* @icearia0219 made their first contribution in https://github.com/agno-agi/agno/pull/10637
* @lakers-abing made their first contribution in https://github.com/agno-agi/agno/pull/10657
* @ericdelorefice made their first contribution in https://github.com/agno-agi/agno/pull/10682
* @inchang-ing made their first contribution in https://github.com/agno-agi/agno/pull/10654

**Full Changelog**: https://github.com/agno-agi/agno/compare/v3.0.11...v3.1.0