50 lines
3.5 KiB
HTML
50 lines
3.5 KiB
HTML
|
<div class="docs-content" data-render>
|
||
|
|
# Tools and scopes
|
||
|
|
|
||
|
|
Devii's capabilities are a declarative **catalog** of actions. Each action declares a `handler` that
|
||
|
|
routes it, and an auth scope. See also [Devii internals](/docs/devii-internals.html) and [Data and persistence](/docs/devii-data.html).
|
||
|
|
|
||
|
|
## How tools are declared
|
||
|
|
|
||
|
|
`actions/spec.py` defines `Action` (name, method, path, params, `requires_auth`, `handler`) and
|
||
|
|
`Catalog`. `registry.py` unions the per-category tuples into `CATALOG`. `tool_schema()` projects
|
||
|
|
each action into the JSON tool schema sent to the model; `tool_schemas_for(authenticated)` is the
|
||
|
|
**auth scope filter** - guests only receive actions where `requires_auth` is false, so
|
||
|
|
account-operating tools are not even offered to a guest.
|
||
|
|
|
||
|
|
## Handler categories (scopes)
|
||
|
|
|
||
|
|
| Handler | Scope | What it does |
|
||
|
|
|---|---|---|
|
||
|
|
| `http` | platform API | The bulk of the catalog (`actions/catalog.py`): posts, comments, votes, follows, messages, projects, gists, bookmarks, polls, notifications, admin endpoints, and the admin-only `site_analytics` (GET `/admin/analytics`). Sent over the `PlatformClient` with the user's auth. |
|
||
|
|
| `login` / `logout` / `status` | session | Authenticate or report auth state. |
|
||
|
|
| `agentic` | reasoning | `plan`, `reflect`, `recall`, `forget_lessons`, `verify`, `delegate`. |
|
||
|
|
| `task` | scheduling | Create/list/update/delete autonomous tasks (once / interval / cron). |
|
||
|
|
| `docs` | knowledge | `search_docs` over this documentation. |
|
||
|
|
| `fetch` | web | `fetch_url` with an SSRF guard and size caps. |
|
||
|
|
| `rsearch` | external web | `rsearch` (web/image search), `rsearch_answer` (web-grounded AI answer), `rsearch_chat` (direct AI chat), `rsearch_describe_image` (vision). They call an external public service, not this platform, and are gated by the `devii_rsearch_enabled` config (URL configurable via `devii_rsearch_url`). |
|
||
|
|
| `cost` | accounting | `cost_stats` for the live session. |
|
||
|
|
| `chunks` | large results | `read_more` paginates any oversized tool result. |
|
||
|
|
| `avatar` | on-screen | The `avatar_*` tools (md-clippy character) - web only. |
|
||
|
|
| `client` | the browser | `get_page_context`, `run_js`, `highlight_element`, `clear_highlights`, `show_toast`, `scroll_to_element`, `navigate_to`, `reload_page` - run in the user's own browser; `run_js` is gated by the `devii_allow_eval` config. |
|
||
|
|
|
||
|
|
## Auth scope
|
||
|
|
|
||
|
|
`requires_auth` defaults to true. The dispatcher refuses an auth-required action when the platform
|
||
|
|
client is not authenticated. Beyond authentication, **role** enforcement is done by the platform
|
||
|
|
endpoints themselves (for example the admin endpoints return 403 to non-admins) - Devii does not
|
||
|
|
re-implement role checks for platform data. The local handlers (`avatar`, `client`, `agentic`,
|
||
|
|
`task`, `docs`, `cost`, `chunks`) act only on the owner's own session, browser, or memory.
|
||
|
|
|
||
|
|
## The ReAct protocol
|
||
|
|
|
||
|
|
The system prompt enforces an operating protocol: `plan()` must be the first tool call;
|
||
|
|
authentication and permissions gate account actions; `recall()` consults lessons; mutating actions
|
||
|
|
require a `verify()`; tool errors trigger a `reflect()`. For counts and "how many" questions the
|
||
|
|
model is told to use `site_analytics` (the admin-only [analytics endpoint](/docs/admin.html)) rather
|
||
|
|
than paging lists, and to `search_docs` before guessing a route. The external `rsearch_*` web tools
|
||
|
|
are not platform-specific: the prompt makes Devii prefer platform tools always and call them only when
|
||
|
|
the user explicitly asks to search the web or an outside source. See
|
||
|
|
[Security and limits](/docs/devii-security.html) for the confidentiality and memory rules.
|
||
|
|
</div>
|