759 lines
54 KiB
Markdown
759 lines
54 KiB
Markdown
# REST API Contract
|
||
|
||
Base URL: `/api` behind web proxy, or server root directly in local/dev.
|
||
|
||
Authentication:
|
||
- If `ADMIN_TOKEN` is set on server, send `Authorization: Bearer <token>`.
|
||
- If `ADMIN_TOKEN` is unset, API is open for local/dev use.
|
||
|
||
Content type:
|
||
- Requests with bodies use `application/json`.
|
||
- Responses are JSON unless noted otherwise.
|
||
|
||
Chat upload limits:
|
||
- Chat completion and direct message payloads support inline attachments up to a 32 MB request body.
|
||
- Up to 8 attachments per message.
|
||
- Image attachments: PNG or JPEG only, max 6 MB each.
|
||
- Text attachments: up to 8 MB source size each; server accepts at most 200,000 characters of inlined text content per attachment.
|
||
|
||
## Health + Auth
|
||
|
||
### `GET /health`
|
||
- Response: `{ "ok": true }`
|
||
|
||
### `GET /v1/auth/session`
|
||
- Response: `{ "authenticated": true, "mode": "open" | "token" }`
|
||
- In token mode, a missing bearer token returns `401` (`missing bearer token`); an incorrect token returns `403` (`invalid bearer token`).
|
||
- Web clients show a neutral sign-in form when the initial check has no token, and an error when a supplied token is rejected. Open development servers authenticate automatically; the sign-in form has no tokenless bypass.
|
||
|
||
## Models
|
||
|
||
### `GET /v1/models`
|
||
- Response:
|
||
```json
|
||
{
|
||
"providers": {
|
||
"openai": { "models": ["chat-latest", "gpt-4.1-mini"], "loadedAt": "2026-02-14T00:00:00.000Z", "error": null },
|
||
"anthropic": { "models": ["claude-3-5-sonnet-latest"], "loadedAt": null, "error": null },
|
||
"xai": { "models": ["grok-3-mini"], "loadedAt": null, "error": null },
|
||
"gemini": { "models": ["gemini-3.5-flash"], "loadedAt": null, "error": null },
|
||
"hermes-agent": { "models": ["hermes-agent"], "loadedAt": null, "error": null }
|
||
}
|
||
}
|
||
```
|
||
- OpenAI model lists are filtered to models that are expected to work with the backend's Responses API implementation, including the exact `chat-latest` alias when returned by OpenAI. Audio, image-generation, embedding, moderation, and other specialized model ids remain excluded. See [OpenAI's Chat Latest documentation](https://developers.openai.com/api/docs/models/chat-latest) for supported capabilities.
|
||
- Gemini model lists are loaded from Google's native Models API and filtered to Gemini `generateContent` model ids.
|
||
- `hermes-agent` is included only when `HERMES_AGENT_API_KEY` is configured. Set it to Hermes `API_SERVER_KEY`, or any non-empty value if that local server does not require auth. `HERMES_AGENT_API_BASE_URL` defaults to `http://127.0.0.1:8642/v1`; set `HERMES_AGENT_MODEL` only when you need an additional fallback/override model id.
|
||
- The backend loads provider model lists at startup and refreshes them about once every 24 hours. If a later provider refresh fails, the response keeps the last loaded model list for that provider and sets `error` to the latest failure message.
|
||
|
||
## Chat Tools
|
||
|
||
### `GET /v1/chat-tools`
|
||
- Response:
|
||
```json
|
||
{
|
||
"tools": [
|
||
{ "name": "web_search", "description": "..." },
|
||
{ "name": "fetch_url", "description": "..." }
|
||
]
|
||
}
|
||
```
|
||
|
||
Behavior notes:
|
||
- Lists Sybil-managed chat tools that can be enabled for `openai`, `anthropic`, `xai`, and `gemini` chat completions.
|
||
- Optional tools such as `codex_exec` and `shell_exec` appear only when enabled by server environment configuration.
|
||
|
||
## Active Runs
|
||
|
||
### `GET /v1/active-runs`
|
||
- Response:
|
||
```json
|
||
{
|
||
"chats": ["chat-id-with-active-stream"],
|
||
"searches": ["search-id-with-active-stream"]
|
||
}
|
||
```
|
||
|
||
Behavior notes:
|
||
- Lists in-memory chat/search streams that are still running on this server process.
|
||
- Clients should use this after app start or page refresh to restore per-row generating indicators.
|
||
- The lists are not durable across server restarts.
|
||
|
||
## Workspace Items
|
||
|
||
### `GET /v1/workspace-items`
|
||
- Response: `{ "items": WorkspaceItem[] }`
|
||
- Optional query: `q` (trimmed string, up to 200 characters). Omit or leave blank for the recent-items list.
|
||
- With nonblank `q`, response: `{ "items": WorkspaceItem[], "hasMore": boolean }`; each item also has `searchSnippet: string | null` (plain text, no HTML).
|
||
- `WorkspaceItem` is a discriminated union sorted by `updatedAt` descending:
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"type": "chat",
|
||
"id": "chat-id",
|
||
"title": "optional title",
|
||
"parentChatId": null,
|
||
"titleGenerationPending": false,
|
||
"createdAt": "2026-02-14T00:00:00.000Z",
|
||
"updatedAt": "2026-02-14T00:00:00.000Z",
|
||
"starred": true,
|
||
"starredAt": "2026-02-14T01:00:00.000Z",
|
||
"initiatedProvider": "openai",
|
||
"initiatedModel": "gpt-4.1-mini",
|
||
"lastUsedProvider": "openai",
|
||
"lastUsedModel": "gpt-4.1-mini",
|
||
"additionalSystemPrompt": null,
|
||
"enabledTools": ["web_search", "fetch_url"]
|
||
},
|
||
{
|
||
"type": "search",
|
||
"id": "search-id",
|
||
"title": "optional title",
|
||
"query": "search query",
|
||
"createdAt": "2026-02-14T00:00:00.000Z",
|
||
"updatedAt": "2026-02-14T00:00:00.000Z",
|
||
"starred": false,
|
||
"starredAt": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Behavior notes:
|
||
- This endpoint is intended for combined conversation/search lists such as sidebars.
|
||
- The legacy `GET /v1/chats` and `GET /v1/searches` endpoints remain available for clients that need separate collections.
|
||
- The response currently combines the 100 most recently updated chats, any additional root chats needed to group those forks, and up to 100 searches.
|
||
- Root chats have `parentChatId: null`. Every fork points directly to its single root chat, including a fork created from another fork, so clients can group rows without traversing a fork chain.
|
||
- `starred`/`starredAt` are backed by membership in a reserved `Project` with id `starred`; future project folders can reuse the same project item model.
|
||
|
||
History search (`q`) notes:
|
||
- Searches all saved history, including items outside the recent-items window. Chats match their title or the text of a user/assistant message; saved web searches match their title, query, or generated answer. System prompts, tool logs, attachments, and raw web-result payloads are excluded.
|
||
- Case- and diacritic-insensitive Unicode word-prefix matching: `plan` matches `planning`. All query words must match within the title, a single message, or one saved web search (across its indexed fields). Punctuation separates words; quotes, `*`, and operators have no special query syntax. Punctuation-only queries return no matches. This is word-prefix search, not arbitrary substring matching.
|
||
- Returns at most 100 distinct matching items, newest `updatedAt` first, with ties ordered by `type` then `id`. `hasMore` indicates additional matches; refine `q` to narrow them. Unmatched fork roots are not added in search mode. Selecting a fork result opens that fork directly. Search-mode fork results carry their root's `starred`/`starredAt`; clients should star/unstar the `parentChatId`, as in the grouped sidebar.
|
||
- `searchSnippet` is a bounded excerpt from a matching message or saved web search; title-only chat matches have `null`. Clients should render it as plain text.
|
||
- The web and iOS sidebar search fields use this endpoint across saved history. Both display matching excerpts; web title-only chat results display “Title match”.
|
||
- Invalid/non-string queries or queries exceeding 200 characters return `400`. Authentication is unchanged.
|
||
- SQLite FTS5 external-content indexes and prefix indexes serve these queries without scanning or transferring every transcript. The migration backfills existing content; transactional triggers maintain the indexes on inserts, updates, deletes, and cascades. Recent chat listing also has an `updatedAt` index.
|
||
|
||
## Chats
|
||
|
||
### `GET /v1/chats`
|
||
- Response: `{ "chats": ChatSummary[] }`
|
||
|
||
### `POST /v1/chats`
|
||
- Body:
|
||
```json
|
||
{
|
||
"title": "optional title",
|
||
"provider": "optional openai|anthropic|xai|gemini|hermes-agent",
|
||
"model": "optional model id",
|
||
"additionalSystemPrompt": "optional stored system prompt",
|
||
"enabledTools": ["web_search", "fetch_url"],
|
||
"messages": [
|
||
{
|
||
"role": "system|user|assistant|tool",
|
||
"content": "string",
|
||
"name": "optional",
|
||
"attachments": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
- Response: `{ "chat": ChatSummary }`
|
||
|
||
Behavior notes:
|
||
- `provider` and `model` must be supplied together when present.
|
||
- Newly created non-fork chats have `parentChatId: null` and `titleGenerationPending: false`.
|
||
- When `provider`/`model` are supplied, the new chat initializes `initiatedProvider`/`initiatedModel` and `lastUsedProvider`/`lastUsedModel`.
|
||
- `additionalSystemPrompt` is trimmed and stored on the chat; blank values are stored as `null`.
|
||
- `enabledTools` stores the enabled Sybil-managed tool names for future chat completions. Unknown tool names are ignored; omitted values default to all currently available tools.
|
||
- Optional `messages` are inserted as the initial transcript. Attachment metadata uses the same schema and limits as chat completion messages.
|
||
|
||
### `POST /v1/chats/:chatId/fork`
|
||
- Body: `{ "messageId"?: string }`
|
||
- Response: `{ "chat": ChatSummary }`
|
||
- Source chat not found: `404 { "message": "chat not found" }`
|
||
- Supplied message missing from the source chat: `404 { "message": "message not found in chat" }`
|
||
- Supplied message is not an assistant response: `400 { "message": "fork message must be an assistant response" }`
|
||
|
||
Behavior notes:
|
||
- With no `messageId`, the server copies the complete source transcript. With an assistant response `messageId`, it copies the transcript through that response, inclusive.
|
||
- The source chat is unchanged. Copied messages receive new ids while retaining their role, content, name, creation time, order, and metadata except for the source request's transport-only `clientRequestId`. Attachments and tool-call metadata are retained. LLM call logs, star/project memberships, and other child threads are not copied.
|
||
- The fork inherits the source chat's user, initiated/last-used provider and model, additional system prompt, and enabled tool settings.
|
||
- A fork of a root or another fork always sets `parentChatId` to the single root chat id. Root chats keep `parentChatId: null`.
|
||
- A whole-chat fork starts with `Fork of <source title>` (or `Fork of Untitled chat`). A message fork starts with `Fork of '<message snippet>'`.
|
||
- The placeholder title is returned with `titleGenerationPending: true`. After the first new prompt, call `POST /v1/chats/title/suggest`; the placeholder is eligible for replacement exactly once.
|
||
|
||
### `PATCH /v1/chats/:chatId`
|
||
- Body: any subset of `{ "title": string, "additionalSystemPrompt": string|null, "enabledTools": string[] }`
|
||
- Response: `{ "chat": ChatSummary }`
|
||
- Blank titles are rejected. The server trims surrounding whitespace before storing the title.
|
||
- Setting a title clears `titleGenerationPending`, preventing an in-flight or later automatic suggestion from replacing the manual title.
|
||
- `additionalSystemPrompt: null` clears the stored prompt. Blank string values are also stored as `null`.
|
||
- `enabledTools: []` disables Sybil-managed tools for this chat. Omitted settings are left unchanged.
|
||
- Updating chat fields changes the returned chat's `updatedAt`.
|
||
- Not found: `404 { "message": "chat not found" }`
|
||
|
||
### `PATCH /v1/chats/:chatId/star`
|
||
- Body: `{ "starred": boolean }`
|
||
- Response: `{ "chat": ChatSummary }`
|
||
- Not found: `404 { "message": "chat not found" }`
|
||
|
||
Behavior notes:
|
||
- Starring adds the chat to the reserved `starred` project and sets `starredAt` to the membership creation time.
|
||
- Unstarring removes that membership and returns `starred: false`, `starredAt: null`.
|
||
- This does not modify the chat transcript or chat `updatedAt`.
|
||
|
||
### `POST /v1/chats/title/suggest`
|
||
- Body:
|
||
```json
|
||
{
|
||
"chatId": "chat-id",
|
||
"content": "user request text"
|
||
}
|
||
```
|
||
- Response: `{ "chat": ChatSummary }`
|
||
|
||
Behavior notes:
|
||
- If the chat already has a non-empty title and `titleGenerationPending` is false, server returns the existing chat unchanged.
|
||
- A fork placeholder with `titleGenerationPending: true` is eligible for the same title-generation flow as an untitled original chat. A successful or fallback suggestion clears the flag.
|
||
- If a title is set while suggestion generation is in flight, server returns the current chat instead of overwriting that title.
|
||
- For an eligible untitled chat or pending fork placeholder, server uses OpenAI `gpt-4.1-mini` to generate a one-line title (up to ~4 words), updates the chat title, and returns the updated chat.
|
||
- If the title provider is unavailable or rejects the request, server still persists a deterministic title derived from the first line of `content` instead of leaving the chat untitled.
|
||
|
||
### `DELETE /v1/chats/:chatId`
|
||
- Response: `{ "deleted": true }`
|
||
- Not found: `404 { "message": "chat not found" }`
|
||
- Active chat or fork: `409 { "message": "chat or fork has an active stream" }`
|
||
- Concurrent family deletion: `409 { "message": "chat family deletion already in progress" }`
|
||
- Deleting a root chat also deletes its grouped forks. Deleting a fork leaves the root and sibling forks unchanged.
|
||
- A root cannot be deleted while it or any grouped fork has an active completion stream. A fork cannot be deleted while its own completion stream is active.
|
||
|
||
### `GET /v1/chats/:chatId`
|
||
- Response: `{ "chat": ChatDetail }`
|
||
|
||
### `POST /v1/chats/:chatId/messages`
|
||
- Body:
|
||
```json
|
||
{
|
||
"role": "system|user|assistant|tool",
|
||
"content": "string",
|
||
"name": "optional",
|
||
"metadata": {},
|
||
"attachments": [
|
||
{
|
||
"kind": "image",
|
||
"id": "attachment-id",
|
||
"filename": "photo.jpg",
|
||
"mimeType": "image/jpeg",
|
||
"sizeBytes": 12345,
|
||
"dataUrl": "data:image/jpeg;base64,..."
|
||
},
|
||
{
|
||
"kind": "text",
|
||
"id": "attachment-id",
|
||
"filename": "notes.md",
|
||
"mimeType": "text/markdown",
|
||
"sizeBytes": 4567,
|
||
"text": "# Notes\\n...",
|
||
"truncated": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
- Response: `{ "message": Message }`
|
||
|
||
Notes:
|
||
- `attachments` is optional and is merged into stored `message.metadata.attachments`.
|
||
- Tool messages should not include attachments.
|
||
|
||
## Chat Completions (non-streaming)
|
||
|
||
### `POST /v1/chat-completions`
|
||
- Body:
|
||
```json
|
||
{
|
||
"chatId": "optional-chat-id",
|
||
"provider": "openai|anthropic|xai|gemini|hermes-agent",
|
||
"model": "string",
|
||
"messages": [
|
||
{
|
||
"role": "system|user|assistant|tool",
|
||
"content": "string",
|
||
"name": "optional",
|
||
"attachments": [
|
||
{
|
||
"kind": "image",
|
||
"id": "attachment-id",
|
||
"filename": "photo.jpg",
|
||
"mimeType": "image/jpeg",
|
||
"sizeBytes": 12345,
|
||
"dataUrl": "data:image/jpeg;base64,..."
|
||
},
|
||
{
|
||
"kind": "text",
|
||
"id": "attachment-id",
|
||
"filename": "notes.md",
|
||
"mimeType": "text/markdown",
|
||
"sizeBytes": 4567,
|
||
"text": "# Notes\\n...",
|
||
"truncated": false
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"additionalSystemPrompt": "optional one-off system prompt",
|
||
"enabledTools": ["web_search", "fetch_url"],
|
||
"temperature": 0.2,
|
||
"maxTokens": 256
|
||
}
|
||
```
|
||
- Response:
|
||
```json
|
||
{
|
||
"chatId": "chat-id-or-null",
|
||
"provider": "openai",
|
||
"model": "gpt-4.1-mini",
|
||
"message": { "role": "assistant", "content": "..." },
|
||
"usage": { "inputTokens": 10, "outputTokens": 20, "totalTokens": 30 },
|
||
"raw": {}
|
||
}
|
||
```
|
||
|
||
Behavior notes:
|
||
- If `chatId` is present, server validates chat existence.
|
||
- For `chatId` calls, server stores only *new* non-assistant messages from provided history to avoid duplicates.
|
||
- `additionalSystemPrompt`, when present directly or loaded from stored chat settings, is prepended to the provider request as a `system` message and is not inserted into the persisted chat transcript by this endpoint.
|
||
- `enabledTools` limits Sybil-managed tools for this request. When omitted for a saved chat, the stored chat setting is used; otherwise all available tools are enabled by default. An empty array disables Sybil-managed tools.
|
||
- `maxTokens` is optional. For `anthropic`, when omitted the backend requests the selected model's maximum output token limit from Anthropic's Models API and uses that as `max_tokens`; if the model limit cannot be loaded, the fallback is 128000. For other providers, omitted `maxTokens` is not sent as an explicit cap.
|
||
- Server persists final assistant output and call metadata (`LlmCall`) in DB.
|
||
- Server updates chat-level model metadata on each call: `lastUsedProvider`/`lastUsedModel`; first successful/failed call also initializes `initiatedProvider`/`initiatedModel` if unset.
|
||
- Attachments are optional and currently apply to `user` messages. Persisted chat history stores them under `message.metadata.attachments`.
|
||
- Images are forwarded inline to providers as multimodal image parts. Use PNG or JPEG for cross-provider compatibility.
|
||
- Text files are forwarded as explicit text blocks rather than provider-managed file references. Large text attachments should already be truncated client-side before submission.
|
||
- For `openai`, backend calls OpenAI's Responses API and enables internal tool use with an internal system instruction.
|
||
- For `anthropic`, backend calls Anthropic's Messages API and enables internal tool use with Anthropic `tool_use`/`tool_result` content blocks.
|
||
- For `xai`, backend calls xAI's OpenAI-compatible Chat Completions API and enables internal tool use with the same internal system instruction.
|
||
- For `gemini`, backend calls Google's native Gemini `generateContent` API and enables internal tool use with Gemini function calling.
|
||
- For `hermes-agent`, backend calls the configured Hermes Agent OpenAI-compatible Chat Completions API without adding Sybil-managed tool definitions; Hermes Agent handles its own tools server-side.
|
||
- For `openai`, image attachments are sent as Responses `input_image` items and text attachments are sent as `input_text` items.
|
||
- For `gemini`, image attachments are sent as native Gemini `inlineData` parts and text attachments are sent as text parts.
|
||
- For `xai` and `hermes-agent`, image attachments are sent as Chat Completions content parts alongside text.
|
||
- For `openai`, Responses calls that can enter the server-managed tool loop use `store: true` so reasoning and function-call items can be passed between tool rounds.
|
||
- For `anthropic`, image attachments are sent as Messages API `image` blocks using base64 source data; text attachments are added as `text` blocks.
|
||
- Available Sybil-managed tool calls for `openai`, `anthropic`, `xai`, and `gemini`: `web_search` and `fetch_url`. When `CHAT_CODEX_TOOL_ENABLED=true`, `codex_exec` is also available. When `CHAT_SHELL_TOOL_ENABLED=true`, `shell_exec` is also available.
|
||
- `web_search` returns ranked results with per-result summaries/snippets. Its backend engine is selected by `CHAT_WEB_SEARCH_ENGINE`: `exa` (default), `brave` (requires `BRAVE_SEARCH_API_KEY`), or `searxng` (requires `SEARXNG_BASE_URL`; the instance must allow `format=json`).
|
||
- Brave searches are queued and evenly paced according to the shortest window in Brave's `X-RateLimit-Policy` response header. The backend also honors `X-RateLimit-Remaining`/`X-RateLimit-Reset` and retries `429` responses up to three times with reset-aware exponential backoff; quota resets beyond the bounded retry window fail immediately.
|
||
- `fetch_url` fetches a URL with browser-like navigation headers and returns plaintext page content (HTML converted to text server-side).
|
||
- `codex_exec` delegates coding, shell, repository inspection, and other complex software tasks to a persistent remote Codex CLI workspace over SSH. The server runs `codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check <non-interactive wrapped prompt>` on the configured devbox inside `CHAT_CODEX_REMOTE_WORKDIR`, with SSH stdin closed.
|
||
- `shell_exec` runs arbitrary non-interactive shell commands on the same configured devbox, starting in `CHAT_CODEX_REMOTE_WORKDIR`. It uses `bash -lc` when bash exists, otherwise `sh -lc`, closes SSH stdin, and does not run inside the Sybil server container.
|
||
- Devbox tool configuration:
|
||
- `CHAT_MAX_TOOL_ROUNDS=100` (optional; maximum model/tool result cycles before the backend returns a limit message)
|
||
- `CHAT_CODEX_TOOL_ENABLED=true`
|
||
- `CHAT_SHELL_TOOL_ENABLED=true`
|
||
- `CHAT_CODEX_REMOTE_HOST=<host-or-ip>` (required when enabled)
|
||
- `CHAT_CODEX_REMOTE_USER=<ssh-user>` (optional; omitted if `CHAT_CODEX_REMOTE_HOST` already contains `user@host`)
|
||
- `CHAT_CODEX_REMOTE_PORT=22` (optional)
|
||
- `CHAT_CODEX_REMOTE_WORKDIR=/workspace/sybil-codex` (optional; created on the remote host if missing)
|
||
- `CHAT_CODEX_SSH_KEY_PATH=/run/secrets/codex_ssh_key` (recommended private-key delivery via read-only volume mount)
|
||
- `CHAT_CODEX_SSH_PRIVATE_KEY_B64=<base64-private-key>` (optional fallback when a volume mount is not practical)
|
||
- `CHAT_CODEX_EXEC_TIMEOUT_MS=600000` (optional)
|
||
- `CHAT_SHELL_EXEC_TIMEOUT_MS=120000` (optional)
|
||
- When a tool call is executed, backend stores a chat `Message` with `role: "tool"` and tool metadata (`metadata.kind = "tool_call"`). Streaming requests emit an initiated SSE `tool_call` event before execution, then persist each completed or failed tool call as its terminal SSE `tool_call` event is emitted, then store the assistant output when the completion finishes.
|
||
|
||
## Streaming Chat
|
||
|
||
### `POST /v1/chat-completions/stream`
|
||
|
||
- The request accepts the chat-completion fields above plus optional `persist` and `clientRequestId` fields.
|
||
- `clientRequestId` is only valid for a persisted request with a `chatId`, may be up to 128 characters, and should be a stable unique value generated once per user submission.
|
||
- Retrying with the same `chatId` and `clientRequestId` replays the matching active or completed stream rather than starting a duplicate provider call.
|
||
- The server persists the ID in `metadata.clientRequestId` on the submitted user message and completed assistant message.
|
||
- The complete request, SSE event, persistence, retry, and attach contracts are defined in `docs/api/streaming-chat.md`.
|
||
|
||
## Searches
|
||
|
||
### `GET /v1/searches`
|
||
- Response: `{ "searches": SearchSummary[] }`
|
||
|
||
### `POST /v1/searches`
|
||
- Body: `{ "title"?: string, "query"?: string, "reuseByQuery"?: boolean }`
|
||
- Response: `{ "search": SearchSummary, "reused": boolean, "cacheHit": boolean }`
|
||
|
||
Behavior notes:
|
||
- `reuseByQuery` defaults to `false`, preserving the normal create-a-new-search behavior.
|
||
- When `reuseByQuery` is `true` and `query` is present, the backend normalizes the query with `trim().toLowerCase()` and returns the most recently updated existing search with that normalized query instead of creating a duplicate.
|
||
- `cacheHit` is `true` only when the reused search has persisted results or answer text, is not currently streaming, and was updated within the 24-hour search cache window. Clients can then fetch `GET /v1/searches/:searchId` and display it without running another search.
|
||
- If a matching search exists but `cacheHit` is `false`, clients may run the search again on the returned `search.id`; the run endpoints replace that search's persisted results and answer with the latest run.
|
||
|
||
### `PATCH /v1/searches/:searchId/star`
|
||
- Body: `{ "starred": boolean }`
|
||
- Response: `{ "search": SearchSummary }`
|
||
- Not found: `404 { "message": "search not found" }`
|
||
|
||
Behavior notes:
|
||
- Starring adds the search to the reserved `starred` project and sets `starredAt` to the membership creation time.
|
||
- Unstarring removes that membership and returns `starred: false`, `starredAt: null`.
|
||
- This does not modify the search results or search `updatedAt`.
|
||
|
||
### `DELETE /v1/searches/:searchId`
|
||
- Response: `{ "deleted": true }`
|
||
- Not found: `404 { "message": "search not found" }`
|
||
|
||
### `GET /v1/searches/:searchId`
|
||
- Response: `{ "search": SearchDetail }`
|
||
|
||
### `POST /v1/searches/:searchId/chat`
|
||
- Body: `{ "title"?: string }`
|
||
- Response: `{ "chat": ChatSummary }`
|
||
- Not found: `404 { "message": "search not found" }`
|
||
|
||
Behavior notes:
|
||
- Creates a new chat seeded with a hidden `system` message containing the search query, answer text, answer citations, and top search results.
|
||
- Clients should include existing `system` messages when sending the chat history to `/v1/chat-completions` or `/v1/chat-completions/stream`; they may hide those messages in the transcript UI.
|
||
- The default chat title is `Search: <query-or-title>`, unless `title` is supplied.
|
||
|
||
### `POST /v1/searches/:searchId/run`
|
||
- Body:
|
||
```json
|
||
{
|
||
"query": "optional override",
|
||
"title": "optional override",
|
||
"type": "auto|fast|deep|instant",
|
||
"numResults": 10,
|
||
"includeDomains": ["example.com"],
|
||
"excludeDomains": ["example.org"]
|
||
}
|
||
```
|
||
- Response: `{ "search": SearchDetail }`
|
||
|
||
Search run notes:
|
||
- Backend executes Exa search and Exa answer.
|
||
- Search mode is independent from chat `web_search` tool configuration and remains Exa-only.
|
||
- Persists answer text/citations + ranked results.
|
||
- If both search and answer fail, endpoint returns an error.
|
||
|
||
### `POST /v1/searches/:searchId/run/stream`
|
||
- Body: same as `POST /v1/searches/:searchId/run`
|
||
- Response: `text/event-stream`
|
||
|
||
Events:
|
||
- `search_results`: `{ "requestId": string|null, "results": SearchResultItem[] }`
|
||
- `search_error`: `{ "error": string }`
|
||
- `answer`: `{ "answerText": string|null, "answerRequestId": string|null, "answerCitations": SearchDetail["answerCitations"] }`
|
||
- `answer_error`: `{ "error": string }`
|
||
- terminal `done`: `{ "search": SearchDetail }`
|
||
- terminal `error`: `{ "message": string }`
|
||
|
||
Behavior notes:
|
||
- The stream is owned by the backend after it starts. If the original HTTP client disconnects, the backend keeps running and persists the final search state.
|
||
- While a search stream is active, `GET /v1/active-runs` includes the `searchId`.
|
||
- If a stream is already active for the same `searchId`, this endpoint attaches to the existing stream instead of starting a second run.
|
||
|
||
### `POST /v1/searches/:searchId/run/stream/attach`
|
||
- Body: none
|
||
- Response: `text/event-stream` with the same event names as `POST /v1/searches/:searchId/run/stream`
|
||
- Not found: `404 { "message": "active search stream not found" }`
|
||
|
||
Behavior notes:
|
||
- Replays buffered events for the active in-memory stream, then emits new events until `done` or `error`.
|
||
- Intended for clients that discovered a pending search via `GET /v1/active-runs`, such as after browser refresh.
|
||
|
||
## Type Shapes
|
||
|
||
`ChatSummary`
|
||
```json
|
||
{
|
||
"id": "...",
|
||
"title": null,
|
||
"parentChatId": null,
|
||
"titleGenerationPending": false,
|
||
"createdAt": "...",
|
||
"updatedAt": "...",
|
||
"starred": false,
|
||
"starredAt": null,
|
||
"initiatedProvider": "openai|anthropic|xai|gemini|hermes-agent|null",
|
||
"initiatedModel": "string|null",
|
||
"lastUsedProvider": "openai|anthropic|xai|gemini|hermes-agent|null",
|
||
"lastUsedModel": "string|null",
|
||
"additionalSystemPrompt": null,
|
||
"enabledTools": ["web_search", "fetch_url"]
|
||
}
|
||
```
|
||
|
||
`Message`
|
||
```json
|
||
{
|
||
"id": "...",
|
||
"createdAt": "...",
|
||
"role": "system|user|assistant|tool",
|
||
"content": "...",
|
||
"name": null,
|
||
"metadata": {
|
||
"attachments": [
|
||
{
|
||
"kind": "image",
|
||
"id": "attachment-id",
|
||
"filename": "photo.jpg",
|
||
"mimeType": "image/jpeg",
|
||
"sizeBytes": 12345,
|
||
"dataUrl": "data:image/jpeg;base64,..."
|
||
},
|
||
{
|
||
"kind": "text",
|
||
"id": "attachment-id",
|
||
"filename": "notes.md",
|
||
"mimeType": "text/markdown",
|
||
"sizeBytes": 4567,
|
||
"text": "# Notes\\n...",
|
||
"truncated": false
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
`metadata` remains nullable. Tool-call log messages still use `metadata.kind = "tool_call"`; regular user messages with attachments use `metadata.attachments`.
|
||
|
||
`ChatDetail`
|
||
```json
|
||
{
|
||
"id": "...",
|
||
"title": null,
|
||
"parentChatId": null,
|
||
"titleGenerationPending": false,
|
||
"createdAt": "...",
|
||
"updatedAt": "...",
|
||
"starred": false,
|
||
"starredAt": null,
|
||
"initiatedProvider": "openai|anthropic|xai|gemini|hermes-agent|null",
|
||
"initiatedModel": "string|null",
|
||
"lastUsedProvider": "openai|anthropic|xai|gemini|hermes-agent|null",
|
||
"lastUsedModel": "string|null",
|
||
"additionalSystemPrompt": null,
|
||
"enabledTools": ["web_search", "fetch_url"],
|
||
"messages": [Message]
|
||
}
|
||
```
|
||
|
||
`SearchSummary`
|
||
```json
|
||
{ "id": "...", "title": null, "query": null, "createdAt": "...", "updatedAt": "...", "starred": false, "starredAt": null }
|
||
```
|
||
|
||
`SearchDetail`
|
||
```json
|
||
{
|
||
"id": "...",
|
||
"title": "...",
|
||
"query": "...",
|
||
"createdAt": "...",
|
||
"updatedAt": "...",
|
||
"starred": false,
|
||
"starredAt": null,
|
||
"requestId": "...",
|
||
"latencyMs": 123,
|
||
"error": null,
|
||
"answerText": "...",
|
||
"answerRequestId": "...",
|
||
"answerCitations": [],
|
||
"answerError": null,
|
||
"results": []
|
||
}
|
||
```
|
||
|
||
For streaming contracts, see `docs/api/streaming-chat.md`.
|
||
|
||
## Sybil Agent Room
|
||
|
||
The Sybil Agent tab connects to one persistent root conversation. The agent owns its messages,
|
||
background work, and history; these endpoints do not create ordinary Sybil chats or
|
||
copy the transcript into the Sybil message database. All endpoints use normal Sybil
|
||
REST authentication. The server connects privately to `SYBIL_AGENT_BASE_URL` (default
|
||
`http://sybil-agent:8788`) using `SYBIL_AGENT_API_KEY`. The agent key never reaches browsers.
|
||
|
||
### `GET /v1/agent`
|
||
|
||
Returns the Sybil Agent room descriptor: `id`, `title`, `type: "persistent-agent"`, `model`,
|
||
`protocol: "pi-room.v1"`, `activity`, and `websocket: "/v1/agent/ws"`. The socket path
|
||
is relative to the API base, so web deployments use `/api/v1/agent/ws`. Missing agent
|
||
configuration returns 503; an unreachable agent server or malformed upstream JSON
|
||
returns 502.
|
||
|
||
### `GET /v1/agent/messages`
|
||
|
||
Query parameters: optional `after` or `before` (mutually exclusive nonnegative
|
||
numeric cursor strings), and `limit` (1–200). Without a cursor, returns recent
|
||
history. `after` catches up forward; `before` loads earlier history.
|
||
|
||
```json
|
||
{
|
||
"conversationId": "1",
|
||
"messages": [{ "id": "outbound:43", "createdAt": "2026-10-14T18:00:00.000Z", "role": "assistant", "content": "The task finished.", "name": "Sybil Agent", "metadata": { "kind": "message", "entryId": 43, "status": "complete" } }],
|
||
"cursor": "43",
|
||
"beforeCursor": "43",
|
||
"hasMore": false
|
||
}
|
||
```
|
||
|
||
Messages use `user`, `assistant`, and `tool` roles. Tools use
|
||
`metadata.kind: "tool_call"` and stable IDs; merge by message `id`, since later
|
||
pages can update initiated tools to completed or failed. Internal worker reports,
|
||
event prompts, and model reasoning are excluded. Cursors refer to underlying
|
||
durable entries and can advance without visible messages. Use returned cursors;
|
||
do not derive them from message IDs. `limit` bounds source entries, not displayed
|
||
messages.
|
||
|
||
### `POST /v1/agent/messages`
|
||
|
||
Body: `{ "content": "Check the oven", "requestId": "client-generated-uuid" }`.
|
||
Content is limited to 40,000 characters; it must contain non-whitespace text unless attachment IDs are included;
|
||
`requestId` is required (1–256 characters). Preserve the ID when retrying uncertain
|
||
network results. The proxy fixes `channel: "sybil"`, `whenBusy: "followUp"`, and
|
||
`wait: false`.
|
||
|
||
Returns the agent's `202 Accepted` receipt, including `id` (submission ID), `status`, and
|
||
`messageId` such as `inbound:sybil:client-generated-uuid`. This is admission, not
|
||
completion: watch the room for answers, including unsolicited later replies.
|
||
Multiple requests can be accepted while the agent works. Optional `attachments: [{"id":"att_…"}]` accepts uploaded files as specified below; no client paths or inline file bytes are accepted.
|
||
The proxy verifies successful receipts contain a positive submission ID, a known
|
||
status (`queued`, `placed`, `done`, or `unanswered`), and the expected `messageId`. Attached sends also require matching ordered `attachmentIds` in the receipt.
|
||
Invalid receipts return 502; delivery remains uncertain, so retry using the original
|
||
`requestId` to avoid creating a duplicate message.
|
||
|
||
### `GET /v1/agent/read-state`
|
||
### `PUT /v1/agent/read-state`
|
||
|
||
GET returns `{ "cursor": "43", "updatedAt": "2026-10-14T18:00:00.000Z", "sourceId": "00000000-0000-4000-8000-000000000001" }`.
|
||
Initially: `{ "cursor": "0", "updatedAt": null, "sourceId": null }` (after source discovery the zero row also has its source UUID).
|
||
PUT takes `{ "cursor": "43", "sourceId": "00000000-0000-4000-8000-000000000001" }`; `sourceId` is optional for old clients.
|
||
A supplied source must match the bound runtime or the server returns 409. Both operations return the same additive response shape. The cursor is shared across this
|
||
personal installation and persisted in SQLite. Atomic, monotonic updates prevent
|
||
a stale browser from lowering a cursor saved by another browser. Advance it only
|
||
after showing the corresponding history; poll it to reconcile unread indicators
|
||
across clients. Agent REST responses use `Cache-Control: no-store`.
|
||
|
||
Source-aware clients bind both history and queued acknowledgments to the first accepted read source. A missing/null source is a legacy binding once read state or history has been accepted, not permission to adopt a later UUID. A source mismatch, HTTP 409 or invalid/non-advancing PUT acknowledgment stops old read writers and requires an explicit fresh history load; old cursors must never be relabeled. Known-source writes include `sourceId`; legacy writes omit it. Client reload does not reset server read state. See the source-binding rules in the streaming contract.
|
||
|
||
See the persistent Agent WebSocket section in `streaming-chat.md` for live updates.
|
||
|
||
### Agent attachments (v1)
|
||
|
||
`POST /v1/agent/attachments`: multipart/form-data with exactly one `file` part (original UTF-8 filename in Content-Disposition) and one `uploadId` field (client-generated UUID, stable across retries). Either part order is accepted. Request limit 8 MiB + 64 KiB. 201 new / 200 identical retry:
|
||
|
||
```json
|
||
{"attachment":{"id":"att_12345678-1234-4234-8234-123456789abc","kind":"text","filename":"notes.txt","mimeType":"text/plain","sizeBytes":12,"sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","workspacePath":"/data/workspace/uploads/att_12345678-1234-4234-8234-123456789abc/notes.txt"}}
|
||
```
|
||
|
||
`workspacePath` is OPTIONAL for clients, canonical absolute runtime path when supplied. Never a host path, URL, or request parameter. Descriptors must retain filename/mimeType/sizeBytes/sha256. `kind` is `image`, `text`, or `file`. IDs are opaque. UUID retries must match normalized filename, effective MIME type and bytes, otherwise 409 `idempotency_conflict`. Filename is NFC normalized, 1–255 UTF-8 bytes, no slash/backslash/control characters, not `.`/`..`. A leading dot becomes `_` in the on-disk basename only; display filename remains unchanged.
|
||
|
||
`POST /v1/agent/messages`:
|
||
|
||
```json
|
||
{"content":"Read these notes","requestId":"client-stable-id","attachments":[{"id":"att_12345678-1234-4234-8234-123456789abc"}]}
|
||
```
|
||
|
||
`content` is required, <=40,000 characters; empty/whitespace is allowed with attachments. `requestId` is 1–256 characters and must survive retries. Omit attachments for text-only requests. At most 8 distinct references, 32 MiB total original bytes. References contain ONLY `id`; filenames, paths, URLs, base64 and forged workspacePath are rejected. Root delivery uses channel sybil, followUp and wait=false. 202 receipt:
|
||
|
||
```json
|
||
{"id":123,"status":"queued","messageId":"inbound:sybil:client-stable-id","attachmentIds":["att_12345678-1234-4234-8234-123456789abc"]}
|
||
```
|
||
|
||
Receipt status also permits placed/done/unanswered. `attachmentIds` is present for attached input, in request order, and MUST be checked before treating delivery as acknowledged. Caption + ordered IDs are durably bound to requestId; conflicting replay 409. Native admission atomically stores the input payload, binding, quota charge and worker eligibility; a competing text-only input cannot falsely acknowledge attachment IDs. Network errors may be retried with the same request/upload IDs. Never auto-create a fresh ID on ambiguous failure.
|
||
|
||
History, replay and queued activity use the existing public message schema with `metadata.agentAttachments` containing these descriptors. `content` is the original caption, or `Attached: notes.txt.` for a file-only message. No model-only manifest, text preview or base64 is inserted into public message content. Ordinary chat's `metadata.attachments` schema is unchanged. Raw tool rows stay in the protocol; client transcript filters stay unchanged.
|
||
|
||
`GET /v1/agent/attachments/:id/content`: authenticated original bytes, Content-Length, Content-Disposition attachment (safe ASCII filename and UTF-8 filename*), Cache-Control private/no-store and nosniff. No URLs containing tokens, public static mount, redirects or inline serving. Browser previews use authenticated fetch + revocable blob URL. Native downloads hold one of four slots through response finish/close/error, with a 30-second outbound timeout and disconnect cleanup. Raster types retain their validated MIME type; text downloads use text/plain; other files application/octet-stream. Clients can display/copy workspacePath as text.
|
||
|
||
### Attachment capability and errors
|
||
|
||
Optional `GET /v1/agent` field:
|
||
|
||
```json
|
||
{"capabilities":{"attachments":{"version":1,"maxCount":8,"maxTotalBytes":33554432,"maxImageBytes":6291456,"maxFileBytes":8388608,"imageMimeTypes":["image/png","image/jpeg","image/gif","image/webp"],"maxImagePixels":50000000,"maxImageDimension":16384,"quotaBytes":1073741824,"usedBytes":0,"remainingBytes":1073741824,"maxConcurrentUploads":2,"maxConcurrentDecodes":1}}}
|
||
```
|
||
|
||
Quota values are a snapshot, not a reservation. Absence disables attachment selection and sending. Backend rejects attachments against an old/unsafe upstream rather than allowing dropped references. Sybil also requires ADMIN_TOKEN for attachments; text-only open development behavior remains compatible.
|
||
|
||
Errors: `{ "error": true, "message": "...", "statusCode": 507, "code": "attachment_quota_exceeded", "quotaBytes": 1073741824, "remainingBytes": 1200, "requiredBytes": 20000 }`. Quota numbers are included for 507; no host filesystem information. 400 invalid_upload/invalid_attachment; 401 authentication; 404 attachment_not_found; 409 idempotency_conflict; 413 attachment_limit_exceeded; 415 unsupported_media_type; 422 invalid_image/image_model_unsupported; 429 attachments_busy with Retry-After: 2; 503 attachments_unavailable; 507 attachment_quota_exceeded; 502 unavailable/invalid upstream at proxy. Clients show message and retain retry identity. Remove from composer does not delete completed durable uploads.
|
||
|
||
### Runtime access and release requirements
|
||
|
||
The runtime resolves IDs to persistent `WORKSPACE_DIR/uploads/<id>/<safe-original-basename>` files (default `/data/workspace/uploads/...`), backed by the existing `/data` mount. Images are native model image blocks, never remote links: supported PNG/JPEG/GIF/WebP originals are at most 6 MiB and are prepared as a bounded static first frame (orientation corrected, at most 2000×2000 and 4.5 MiB base64, further limited by the actual model). Reject unsupported image models; no arbitrary document/file provider blocks. Other files are at most 8 MiB and are available through actual workspace read/bash tools. Valid recognized UTF-8 text receives a bounded preview of 16,000 Unicode characters per file / 64,000 per input. PDF/archive/binary files are paths plus metadata. Original hash, size and confinement are validated during resolution. Root and workers share the same workspace; explicit `subagent` spawn/send `attachmentIds` persist in durable Reporter tasks and use the same resolver. Preparation saturation retries through a durable checkpoint after two seconds using the same Reporter request ID. Permanent admission failures, including quota exhaustion, reach the parent through the durable worker-report path. Uploads never auto-execute.
|
||
|
||
Global `SYBIL_AGENT_ATTACHMENT_QUOTA_BYTES` defaults to 1 GiB. Concurrent reservations cover originals, static renditions, staging, metadata and conservative attachment input copies. Quota is conservative accounting, not free disk space. No complete upload expiry or delete endpoint is enabled. Removed composer files stay stored; crashed/uncertain reservations stay charged across restart until deliberate operator reconciliation. Ordinary authorized workspace tool writes and unrelated conversation history are outside attachment-ingestion accounting. Runtime uploads default to two concurrently (`SYBIL_AGENT_ATTACHMENT_UPLOADS`, max8), image decodes one (`SYBIL_AGENT_ATTACHMENT_DECODES`, max4); bounded input preparation and proxy transfers return429 when saturated. Disconnected proxy transfers cancel upstream work and release slots.
|
||
|
||
Release requires native `SYBIL_AGENT_AUTH_MODE=token` with nonempty `SYBIL_AGENT_API_KEY`, plus backend `ADMIN_TOKEN` and matching server-side `SYBIL_AGENT_API_KEY` / `SYBIL_AGENT_BASE_URL`. Native open mode cannot advertise/store/download attachments. A runtime containing attachment records/files refuses open startup; raw/model APIs and sockets are protected in token mode. An open Sybil proxy also refuses access to an attachment-capable native runtime, rather than exposing its history through a private server credential. Explicit text-only open development remains supported with an open/legacy runtime lacking attachment capability. Native keys never enter browser/iOS payloads. No insecure development opt-in is enabled.
|
||
|
||
The runtime source is built into its container: rebuild it with pinned busboy/sharp dependencies for the target Node/Linux platform before release. The deployed open auth mode must be changed separately; no deployed config or mount is modified by this implementation. Backend and web must be upgraded with runtime capability/auth configured before clients advertise uploads.
|
||
|
||
Browser drafts retain upload IDs and completed descriptors across pane changes and reload. Incomplete uploads require reselection of the original filename/type/size and, once network delivery has begun, matching SHA-256 bytes; retries reuse uploadId. Sending persists the attachment-bearing outbox before clearing the draft. Message confirmation requires the same ordered attachment IDs in receipts and canonical echoes. Mismatched echoes must retain local attachments and delivery errors; they are not acknowledgement of a file submission.
|
||
|
||
|
||
## Agent push notifications (v1)
|
||
|
||
All push/config/presence routes require a configured `ADMIN_TOKEN` and bearer authentication; open development mode returns 503. Missing/wrong bearer returns 401/403. Bodies are limited to 16 KiB, responses use `Cache-Control: no-store`, invalid bodies return 400, and unavailable configuration returns 503. Do not put credentials, device tokens or subscription endpoints into URLs. Ownership is one **shared authenticated personal principal**, derived on the server from the configured credential generation. Anyone possessing that shared token has authority over all its installations; UUIDs identify installations and do not create per-human isolation. No `ownerId` is accepted. Changing `ADMIN_TOKEN` invalidates all prior push opt-ins. Protect the SQLite database/backups because endpoint credentials are stored there.
|
||
|
||
### `GET /v1/agent/push/config`
|
||
|
||
```json
|
||
{"version":1,"enabled":false,"apnsAvailable":false,"webPushAvailable":false,"sourceId":null,"quarantined":false,"policy":{"promptGraceMs":5000,"debounceMs":2000,"interactionGraceMs":30000,"presenceHeartbeatMs":15000,"presenceLeaseMs":60000}}
|
||
```
|
||
|
||
`vapidPublicKey` is present only when Web Push is enabled and its credentials are valid. No private keys, tokens, paths or configured account identifiers are returned. Source discovery and browser presence run independently of transport enablement/installation consent. Clients bind local consent to a known source UUID as well as the authenticated backend; null/unknown source cannot opt in. A source change retires prior local consent/installation and requires a new UUID plus explicit user opt-in, rechecking the source after asynchronous permission/subscription/registration work. `sourceId` is the persisted bound runtime UUID or null before discovery. A changed runtime source or regressed durable cursor quarantines delivery and cancels pending alerts without resetting the canonical read cursor. There is deliberately no HTTP read-reset/rebaseline endpoint; an operator must reconcile replacement runtime data with source-aware clients before enabling a new baseline.
|
||
|
||
### `PUT /v1/agent/push/installations/:installationId`
|
||
|
||
Use a stable random UUID per local installation, authenticated with the current shared token. Registration is explicit user opt-in and requires enabled/configured transport. Native body:
|
||
|
||
```json
|
||
{"transport":"apns","enabled":true,"token":"hex-device-token","environment":"production","topic":"net.buzzert.sybil2"}
|
||
```
|
||
|
||
Device tokens must be even-length hexadecimal, 32–512 characters; use the exact token returned by the OS. The server pins permitted topic and environment. TestFlight/App Store normally use production; local development must match the signed `aps-environment` entitlement. Tokens rotate: upsert the current token after registration callbacks and each opted-in launch. App Store upload passwords cannot authenticate APNs.
|
||
|
||
Web body (the keys and endpoint come from the browser's actual `PushSubscription`):
|
||
|
||
```json
|
||
{"transport":"web","enabled":true,"subscription":{"endpoint":"https://web.push.apple.com/provider-path","expirationTime":null,"keys":{"p256dh":"base64url-P256-public-key","auth":"base64url-16-byte-auth-secret"}}}
|
||
```
|
||
|
||
Subscription keys are curve/size validated. Endpoints must use HTTPS, port 443, no userinfo/fragment, and the standard allowlisted Apple (`web.push.apple.com` or one-label `*.push.apple.com`), Google (`fcm.googleapis.com`) or Mozilla (`updates.push.services.mozilla.com`) provider hosts. HTTP redirects are never followed; DNS addresses are checked at connection time to reject private/reserved addresses. Other providers require a reviewed server allowlist change. There is no arbitrary push URL fetch.
|
||
|
||
Response: `{ "installationId":"uuid", "transport":"apns|web", "enabled":true, "version":1 }`. No endpoint/token/key is reflected. Identical registrations retain the same version. Rotation increments the version and cancels old pending deliveries; a provider rejection of an old version cannot disable a newer one. A single endpoint is active under at most one installation ID; rebinding it irreversibly retires every prior non-retired UUID for that endpoint, including provider-disabled and prior credential-generation registrations. A provider-invalid UUID may refresh only until a newer installation claims its endpoint. A PUT to an explicitly retired UUID returns 409. At most 64 opted-in installations are allowed (429 when full).
|
||
|
||
### `DELETE /v1/agent/push/installations/:installationId`
|
||
|
||
Idempotent authenticated 204. Irreversibly retires the UUID, including an unknown UUID (durable tombstone), removes stored transport payload, increments its generation once and cancels pending deliveries. Late/delayed PUTs cannot re-enable a retired UUID, including after restart. A new explicit user opt-in must mint a **new UUID**; rotations may continue using the still-active UUID. Provider-invalid disabled endpoints are separate from explicit retirement and may re-register their active UUID. Clients unregister before discarding their bearer on logout and unsubscribe locally. Offline logout must persist a local revocation tombstone for a later authenticated retry and must never silently re-enable consent. Retry that tombstone only against its original backend and credential authority; a 204 from a different backend does not acknowledge the old revocation. Persist authority digests and installation IDs, never raw credentials. Changing source under the same authority can still revoke the old UUID. A transport request already crossing the provider boundary cannot be recalled reliably.
|
||
|
||
### `PUT /v1/agent/presence/:sessionId`
|
||
|
||
A UUID per browser document/tab, independent of notification permission and selected workspace tab:
|
||
|
||
```json
|
||
{"sequence":12,"visibility":"visible","focused":true,"interacted":false}
|
||
```
|
||
|
||
Response `{ "expiresAt":"2026-10-15T03:00:00.000Z" }`. Sequence is a nonnegative signed 32-bit integer; stale/out-of-order heartbeats neither overwrite state nor extend the lease. Heartbeat every 15 seconds and on focus/visibility changes and recent pointer/key/touch input. Times are assigned by the server. Visible+focused is active even without recent interaction; any recent interaction blocks alerts for another 30 seconds. Leases expire after 60 seconds. All authenticated workspace sessions must report, even without notification opt-in; at most 512 unexpired sessions are accepted. Associate the UUID with WS auth as described in the streaming contract. Unknown authenticated web sockets block dispatch until classified or their heartbeat lease expires.
|
||
|
||
`DELETE /v1/agent/presence/:sessionId` returns 204 and retires focus/visibility best effort; recent-interaction grace is retained until expiry. It does not revoke push consent. Backend restarts impose a full 60-second attention warm-up, with leases preserved across restart.
|
||
|
||
### Scheduling, read reconciliation and delivery identities
|
||
|
||
Only complete user-visible root assistant messages enter the durable outbox. Tool output, model reasoning, worker envelopes and raw events do not. A runtime external event or timer may result in a later qualifying assistant message. First source discovery bootstraps at the current high-water cursor without historical alerts. Checkpoint advancement and enqueue are atomic. Latest accepted human input, including queued input and runtime-native channels, delays alerts for at least five seconds; backend prompt admission also records a durable five-second guard before proxying, covering a concurrent source snapshot (a failed submission only delays briefly). Bursts debounce for two seconds, with a 15-second burst cap subject to the prompt grace. Timer/external-event results and replies arriving at least 30 seconds after a prompt receive higher queue priority; coalescing keeps the latest message identity and preserves the burst's higher priority.
|
||
|
||
All web sessions must be inactive at dispatch, including the runtime-native browser. Before each provider request, the backend refreshes runtime read/prompt/presence, merges native read into the canonical shared read row, and transactionally rechecks opt-in/version, owner generation, source freshness, read cursor and all attention leases. Unknown/malformed/unavailable source data suppresses sends. Messages expire after five minutes; provider TTL is at most 60 seconds. The active outbox coalesces per installation; completed receipts are capped at 10,000 and expire after seven days, while revocation tombstones remain durable. There are at most four attempts, only after definite retryable provider rejections, with bounded backoff. A persisted send intent protects crash recovery: interrupted/ambiguous network sends are never automatically replayed. Exactly-once provider/device delivery is not promised; a final focus/read race after dispatch remains possible.
|
||
|
||
Alert payload identity is top-level `{version:1,sourceId,kind:"message",messageId,cursor}`. APNs adds `aps.alert` with title **Sybil Agent**, body **You have a new message.**, default sound and `thread-id:sybil-agent-root`. Web Push adds those same generic title/body strings, fixed `url:"/?agent=root"` and `tag:"sybil-agent:"+sourceId`. No transcript preview, filename, event source, token or key appears in a notification. Normal APNs alerts do not request critical/time-sensitive entitlements.
|
||
|
||
Monotonic canonical read advances cancel pending alerts and broadcast `read_state` on authenticated WS. New read-aware clients pass the response's exact source/cursor to their notification manager; receiving/tapping a push does not itself mark history read. Native APNs clear payload is `{version:1,sourceId,kind:"read_state",readCursor,aps:{"content-available":1}}`, push type background/priority 5, coalesced to at most one request per minute per installation that has an earlier delivered/ambiguous alert. App foreground/background handlers reconcile delivered OS notifications by source/cursor. Silent pushes are best effort and cannot guarantee removal when an app is terminated or force-quit; foreground read sync remains required.
|
||
|
||
**No silent Web Push read-clear is sent.** Safari requires visible notifications for Web Push. Authenticated foreground pages forward source-bound read state to their service worker; it closes only owned notifications at/below that read cursor. Closing while every browser client is stopped is best effort only. The service worker must never receive/store the general bearer token. Notification click uses the fixed same-origin Agent link and waits for actual rendered history before acknowledging read.
|
||
|
||
### Server configuration and runtime source contract
|
||
|
||
Shipping is disabled by default: `AGENT_PUSH_ENABLED=false`. Native transport requires `AGENT_PUSH_APNS_KEY_FILE` (APNs-enabled ES256 `.p8`, regular secret file 0400/0600), `AGENT_PUSH_APNS_KEY_ID`, `AGENT_PUSH_APNS_TEAM_ID`, optional `AGENT_PUSH_APNS_TOPIC` (default `net.buzzert.sybil2`) and `AGENT_PUSH_APNS_ENVIRONMENT` (`production` by default, or `sandbox`; exactly one credential environment per deployment). Web Push requires `AGENT_PUSH_VAPID_FILE`, a private regular JSON file 0400/0600 containing `publicKey`, `privateKey` (base64url P-256) and `subject` (mailto/HTTPS contact). Invalid/missing/unsafe files leave only that adapter unavailable; files and parse errors are never exposed. This implementation neither creates production keys nor changes Apple portal capabilities. Correct native team/topic is `DQQH5H6GBD` / `net.buzzert.sybil2`; parent portal work, push entitlements/provisioning and real device registration are separate prerequisites. An environment-scoped production key cannot send sandbox notifications: sandbox registrations are rejected when production is configured. Concurrent sandbox/production credentials require a future explicit per-environment credential map; do not reuse one scoped key across environments.
|
||
|
||
Backend independently polls token-authenticated runtime `GET /api/notification-context?after=<cursor>&limit=200` and sends `X-Sybil-Client: backend-proxy-v1` on private proxy REST/WS traffic. The marker classifies the proxy for the native attention census and never replaces runtime authentication. The runtime source is version 1 with `{sourceId,conversationId,cursor,hasMore,latestUserMessageAt,nativeReadCursor,uncertain,webPresence:{active,unknown,observedAt},candidates:[{messageId,cursor,createdAt,trigger}]}`; trigger is `user|external_event|timer|worker|unknown`. No transcript text is included. `uncertain` and `webPresence.unknown` fail closed. Candidate pages preserve all candidates belonging to each consumed cursor (max 200 candidates/page), advancing across non-candidates; omitted `after` is high-water bootstrap with no old candidates. The source identity survives normal runtime restarts. If an incremental context request returns 409 because its cursor exceeds a replaced/restored runtime high-water mark, the backend makes exactly one authenticated no-after probe under the same 10-second deadline. Only a candidate-free, nonpaginated snapshot proving a different source or lower cursor is accepted, solely to quarantine and cancel old pending alerts. It never resets reads/checkpoints, rebaselines, or enumerates historical candidates. Failed/invalid probes and same-source nonregressions remain unavailable and suppress delivery. Runtime native presence/read is an acknowledgment input to the existing canonical backend read state, not a second independently authoritative read store.
|