# Oberik

> Oberik lets a product give its own customers AI over their own data: retrieval with citations, tools, sandboxed compute and scheduling, isolated per customer and scoped by capability-bounded tokens.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Oberik


Oberik is the AI layer you put **inside your product**. Your customers ask questions about
*their own* data and get grounded answers with citations; the agent can also do the work —
run code, transform files, hand results back.

You call it from your backend and from your frontend. Oberik handles retrieval, tool calling,
sandboxed compute, scheduling, isolation and cost attribution.

```ts
import { createClient } from "@oberik/sdk";

// Your backend mints short-lived tokens; the SDK asks for a new one when the
// current one expires, so expiry never surfaces at a call site.
const ai = createClient({ getToken });

const res = await ai.chat.send({
  message: "How did Q3 revenue trend, and why?",
  tags: ["finance"],
});

res.content;     // grounded answer
res.citations;   // document · page · quote
```

## The model in one minute

| Concept | What it is |
|---|---|
| **Project** | One isolated workspace. Its documents, embeddings, files, sandboxes, credentials and spend are separate from every other project's. Most integrations use one project per customer, or one per environment. |
| **Token** | A short-lived JWT your backend mints for one end-user, carrying exactly the capabilities you grant. Your frontend never holds anything privileged. |
| **Capability** | A permission (`chat`, `documents:read`, `computer`…). A token can only hold what the project allows, and the API refuses anything outside it — including a tool the model decides to call. |
| **Scope** | A hierarchical path (`acme:finance:user_9f3c`) bounding *which data* a token can see, so one customer's users don't read each other's documents. |

## Where things live

Two hosts, two credentials. Nothing else to configure.

| | URL | Credential | What it's for |
|---|---|---|---|
| **Control plane** | `https://oberik.com` | `X-API-Key: pk_…` | administering a project: minting end-user tokens, setting the capability ceiling, curating the corpus. Server-side only. |
| **Data plane** | `https://api.oberik.com` | `Authorization: Bearer <jwt>` | the AI itself: chat, documents, tools, sandboxes. This is what the SDK talks to. |
| **Dashboard** | `https://oberik.com/app` | your login | the same control plane with a UI on it. |
| **SSH** | `ssh ssh.oberik.com` | your account, or an SSH key | [the same control plane as text](./ssh.md) — for terminals and coding agents. |

```bash
npm install @oberik/sdk
```

The SDK defaults to the hosted data plane, so `baseUrl` is only needed for a self-hosted
deployment. Self-hosting? Every URL above becomes yours; nothing else in these docs
changes.

## What you can turn on

Each of these is a capability you grant a project and then, per end-user, a token — and
can still decline on any single request.

- **Conversation** — [chat with citations](./chat.md) over your customer's data, blocking
  or streaming, with [steering](./working-together.md#steering--a-message-into-a-running-turn)
  into a running turn.
- **Knowledge** — [documents](./documents.md) you curate or your users upload, and
  [memory and a wiki](./scheduling.md#memory) the agent keeps between chats.
- **Internet** — [web search, page reads, and a real browser](./tools.md#driving-a-browser)
  the agent can click and type in.
- **Agentic work** — [plans it keeps](./working-together.md#todos--the-agents-plan),
  [subagents](./subagents.md) beside it, a [Linux sandbox](./sandbox.md) per conversation,
  [scheduled runs](./scheduling.md) and [webhook triggers](./scheduling.md#webhook-triggers).
- **Human in the loop** — [questions it asks](./working-together.md#questions-the-agent-asks),
  [permission before irreversible actions](./working-together.md#asking-permission),
  [components it draws in your UI](./tools.md#ui-components--tools-that-draw),
  follow-ups and recaps.
- **Extensions** — [your own tools](./tools.md#your-own-tools-client-side), [tools you
  host](./tools.md#tools-you-host-webhook-tools) that work when nobody is connected,
  [MCP servers](./tools.md#mcp-servers), and [skills](./skills.md) that teach it your
  procedures.
- **In and out** — [images, audio, files](./multimodal.md) in; documents, media and
  [downloads](./files.md) back.
- **Guardrails** — [injection defence, groundedness, moderation](./guardrails.md), optional
  PII handling.

## How do I…

| | |
|---|---|
| get one cited answer | [Quickstart](./quickstart.md) |
| do all of this from a terminal, or from a coding agent | [Oberik over SSH](./ssh.md) |
| mint a token for a signed-in user | [Authentication](./authentication.md#minting-a-token) |
| set up a project from a script instead of the dashboard | [Project API](./project-api.md) |
| upload a corpus my users can only read | [Documents](./documents.md#a-corpus-you-curate-that-users-only-read) |
| let the model call my application's functions | [Tools](./tools.md#your-own-tools-client-side) |
| …including in a scheduled run, with no client attached | [Webhook tools](./tools.md#tools-you-host-webhook-tools) |
| stream tokens into a UI | [Chat](./chat.md#streaming) |
| call the API from a browser | [Browser origins](./browser-origins.md) |
| let the agent run code | [Sandboxed compute](./sandbox.md) |
| stop it before it does something irreversible | [Asking permission](./working-together.md#asking-permission) |
| run something every Monday | [Scheduling](./scheduling.md) |
| know what went wrong | [Limits & errors](./limits-and-errors.md) |
| find the exact endpoint | [API reference](./api-reference.md) · [Recipes](./recipes.md) |

## Start here

1. **[Quickstart](./quickstart.md)** — a cited answer in about five minutes.
2. **[Authentication](./authentication.md)** — how to mint tokens, and why it belongs on your server.
3. **[Calling from the browser](./browser-origins.md)** — required before your frontend calls us directly.

:::tip Working from a terminal, or building with an agent?
Everything here is also a shell: `ssh ssh.oberik.com` signs up, creates projects, mints
tokens and talks to the agent, with no browser and no client to install. A coding agent
can sign in without ever handling your password, and read these docs in place with
`docs`, `docs page <name>` and `docs search <term>`. See [Oberik over SSH](./ssh.md).

This site is also published as [`llms.txt`](pathname:///docs/llms.txt) (an index) and
[`llms-full.txt`](pathname:///docs/llms-full.txt) (every page, one file), and the data
plane serves its own OpenAPI schema at
[`api.oberik.com/openapi.json`](https://api.oberik.com/openapi.json).
:::

---

## Quickstart


You'll create a project, mint a token for one of your users, upload a document, and get a
cited answer. Everything below is copy-pasteable; nothing is pseudocode.

:::info Before anything works: register a model
A new project has no models, so it cannot answer a question and cannot index a document.
Add a provider key **once**, and name two kinds of model with it:

- **a chat model** — otherwise every request fails with the provider's own error
- **an embedding model** — otherwise every document upload fails

```bash
curl -sX POST "https://oberik.com/api/projects/$OBERIK_PROJECT_ID/providers" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"provider":"openai",
       "models":["gpt-4o-mini","text-embedding-3-small"],
       "values":{"api_key":"sk-…"}}'
# -> { …, "derived": { "defaultModel": "gpt-4o-mini",
#                      "embeddingModel": "text-embedding-3-small", "embeddingDim": 1536 } }
```

`derived` is the rest of the setup done for you: the chat default, and the embedding model
with its dimension **measured** rather than assumed. Nothing else to configure.

At any point, ask what is left:

```bash
curl -s "https://oberik.com/api/projects/$OBERIK_PROJECT_ID/readiness" -H "X-API-Key: $OBERIK_PROJECT_KEY"
# -> { "canAnswer": true, "ready": true, "next": null, "steps": [ … ] }
```

Each unfinished step names what it blocks and the one call that fixes it. In the dashboard
the same list is at the top of the project's overview.

Two booleans, because there are two questions. **Gate a deploy on `canAnswer`** — it is
true once the project can run a turn at all. `ready` is the full checklist and includes
steps that only hold back one capability: turning on subagents without choosing subagent
models makes `ready` false on a project that answers questions perfectly well. Each step
carries `essential` if you want to make the distinction yourself.
:::

## 1. Create a project and a key

In the dashboard, **New project** — a project is one isolated workspace,
in most integrations one per customer. Then **Project → API keys → Create key**.

:::tip No browser? Do the whole of this over SSH
`ssh ssh.oberik.com` is the same control plane as text — sign up, create the project,
create the key, mint tokens. A coding agent can sign in without ever being handed a
password. See [Oberik over SSH](./ssh.md).
:::

The key (`pk_…`) is shown once and is for *your server only*. Never ship it to a browser:
it can mint tokens with any capability the project allows, and it can administer the
project itself.

```bash
export OBERIK_PROJECT_KEY="pk_…"     # server-side only
export OBERIK_PROJECT_ID="7f3c…"      # a UUID, from the URL of the project page
```

:::note You can do this without a browser
Everything after this — the capability ceiling, the corpus, skills, MCP servers, the
system prompt — is driven over HTTP with that key ([Project API](./project-api.md)). And
the two steps above are not browser-only either: `ssh ssh.oberik.com` will `signup`,
`org new`, `project new` and `key new`, so a coding agent or a CI job can stand a project
up end to end. See [Oberik over SSH](./ssh.md).
:::

## 2. Mint a token for one end-user

Your backend decides who the user is and what they may do. Nothing downstream can widen it.

```bash
npm install @oberik/sdk
```

```ts title="server/oberik.ts"
import { createProjectClient } from "@oberik/sdk";

// The server-side client. It holds the project key, so it is a different object from
// the one your app uses — and it refuses to construct in a browser, because a project
// key there can mint anything the project allows and delete the project outright.
export const oberik = createProjectClient({
  projectId: process.env.OBERIK_PROJECT_ID!,
  projectKey: process.env.OBERIK_PROJECT_KEY!,
});

export async function mintToken(user: { id: string; orgId: string }) {
  const { access_token } = await oberik.tokens.mint({
    subject: `${user.orgId}:${user.id}`,   // who they are
    scope: `${user.orgId}:${user.id}`,     // what they may see
    capabilities: ["chat", "documents:read", "documents:write"],
    expiresIn: 3600,
  });
  return access_token;
}
```

`mint` returns what was **actually** granted, which is worth checking the first time:

```ts
const t = await oberik.tokens.mint({ subject: "acme:user_1", capabilities: ["chat", "computer"] });
t.capabilities;   // ["chat"] — the project's ceiling trimmed `computer`
```

A capability you asked for and did not get is a toggle in the dashboard (Project →
Capabilities), not a bug in your code.

### Without the SDK

It is one HTTP call, so you can check your key before writing any code:

```bash
curl -sX POST "https://oberik.com/api/projects/$OBERIK_PROJECT_ID/token" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" \
  -H "content-type: application/json" \
  -d '{"subject":"acme:user_1","scope":"acme:user_1","capabilities":["chat","documents:read"],"expiresIn":3600}'
```

```json
{
  "access_token": "eyJ…",
  "token_type": "bearer",
  "expires_in": 3600,
  "tenant_id": "…",
  "capabilities": ["chat", "documents:read"],
  "scope": "acme:user_1"
}
```

Note the host: minting is a **control-plane** call (`oberik.com`), while everything your
app does afterwards goes to the **data plane** (`api.oberik.com`).

## 3. Upload a document, ask a question

```ts title="ask.ts — a complete script"
import { readFile } from "node:fs/promises";
import { createClient } from "@oberik/sdk";
import { oberik } from "./server/oberik.js";

// `getToken` is the recommended way in: the SDK calls it back when a token expires and
// replays the request, so expiry never reaches your call sites. `forUser` is that
// callback, so the two halves fit together without glue.
const ai = createClient({
  getToken: oberik.tokens.forUser({
    subject: "acme:user_1",
    capabilities: ["chat", "documents:read", "documents:write"],
  }),
});

const doc = await ai.documents.uploadAndWait(await readFile("q3-report.pdf"), {
  filename: "q3-report.pdf",
  tags: ["finance"],
});
console.log(doc.status);          // "ready"

const res = await ai.chat.send({
  message: "How did Q3 revenue trend, and why?",
  tags: ["finance"],
});

console.log(res.content);
for (const c of res.citations) {
  // `page` is null for anything without pages — Markdown, CSV, a web page — so guard
  // it rather than rendering "p.null" for every non-paginated source.
  const where = c.page != null ? ` p.${c.page}` : "";
  console.log(`${c.filename}${where} — "${c.quote}"`);
}
```

Run it with whatever you already use for TypeScript — `tsx ask.ts`, or Node 22.6+ with
`node --experimental-strip-types ask.ts`. The SDK ships ESM and CJS builds and needs
Node 18 or newer.

Ingestion is asynchronous. `uploadAndWait` returns once the document is parsed, chunked
and searchable; use `ai.documents.upload(...)` for large files, or if you'd rather poll
`ai.documents.get(id)` yourself.

:::tip Try it before you write any code
Every project has a **Try agent** button. It opens a chat client that talks to your real
project through this same API, on a disposable identity erased when you close it — so you
can check your corpus, capabilities and models answer the way you expect before wiring
anything up.

To see what a *particular* user sees, mint a token for them under **Connect → Mint a test
token** and press **Try agent with this token**. The same chat opens as that subject and
scope: their documents, their memories, their scope boundary. Nothing is erased when you
close it, because none of it is yours.
:::

## 4. Stream it into a UI

```ts
const handle = ai.chat.stream(
  { message: input, tags: ["finance"] },
  {
    onToken: (_delta, full) => render(full),
    onCitations: (cs) => showSources(cs),
  },
);
const done = await handle.done;
```

`handle` is awaitable and also gives you `cancel()`, `disconnect()` and `runId()`. A
dropped connection re-attaches to the same run and replays what you missed —
[details](./chat.md#dropped-connections-resume).

## 5. Keep the conversation

Pass back the `session_id` and Oberik keeps the history — including images from earlier
turns.

```ts
const follow = await ai.chat.send({
  session_id: res.session_id,
  message: "Which region drove it?",
});
```

## Without the SDK

Every SDK call is one HTTP request. The same turn, over curl:

```bash
curl -sX POST https://api.oberik.com/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"message":"How did Q3 revenue trend?","tags":["finance"]}'
```

Streaming is Server-Sent Events on `POST /chat/stream` — no WebSocket, no proxy. The
full surface is in the [API reference](./api-reference.md), and the data plane serves its
own OpenAPI schema at `https://api.oberik.com/openapi.json` if you'd rather generate a
client.

## Next

- Calling from a browser? Declare your **[origins](./browser-origins.md)** first, or the
  request is refused.
- Want the agent to *do* things, not just answer? **[Tools](./tools.md)** and
  **[sandboxed compute](./sandbox.md)**.
- Setting up projects from code? **[Project API](./project-api.md)**.
- Going live? **[Limits & errors](./limits-and-errors.md)**.

---

## Recipes


One working call per task, and a link to the page that explains why it looks like that.
Everything assumes a client:

```ts
import { createClient } from "@oberik/sdk";
const ai = createClient({ getToken });     // see Authentication
```

## Answer a question over the customer's own documents

```ts
const res = await ai.chat.send({ message: "What's our refund window?", tags: ["policies"] });
res.content;
res.citations;   // document · page · quote — the passages retrieved
res.claims;      // which sentence came from which passage
```

Naming `tags` (or `document_ids`) also switches web search off for that turn, so the
answer cannot quietly come from the internet. → [Chat](./chat.md#grounding)

## Stream the answer into a UI

```ts
const h = ai.chat.stream({ message, session_id }, {
  onToken: (_d, full) => setText(full),
  onCitations: setSources,
  onTodos: setPlan,
});
const done = await h.done;
```

`h.cancel()` stops generation (and the spend); `h.disconnect()` just stops listening.
→ [Chat](./chat.md#streaming)

## Let the model call your own functions

```ts
const ai = createClient({
  getToken,
  tools: [{
    name: "cancel_order",
    description: "Cancel an order belonging to the signed-in customer.",
    parameters: { type: "object", properties: { order_id: { type: "string" } }, required: ["order_id"] },
    handler: async ({ order_id }) => {
      await assertOwnedBySignedInUser(order_id as string);   // arguments are model-generated
      return await orders.cancel(order_id as string);
    },
  }],
});

await ai.chat.run({ message: "Cancel my most recent order" });
```

`run` (and `stream`) dispatch the call, submit the result and continue until the agent is
done. → [Tools](./tools.md#your-own-tools-client-side)

## Curate a corpus your users can only read

```bash
# Once, from your server — the project owns these, not any one user.
curl -sX POST "https://oberik.com/api/projects/$ID/documents" \
  -H "X-API-Key: $KEY" -F file=@handbook.pdf -F tags=policies

curl -sX PATCH "https://oberik.com/api/projects/$ID" \
  -H "X-API-Key: $KEY" -H "content-type: application/json" \
  -d '{"capabilities":{"documentsMode":"read"}}'
```

With `documentsMode: "read"`, no token minted for this project can ever carry
`documents:write`. → [Project API](./project-api.md) · [Documents](./documents.md#a-corpus-you-curate-that-users-only-read)

## Keep one customer's users out of each other's data

```ts
// Two users of the same customer, in one project.
mint({ subject: "acme:fin:ana",  scope: "acme:fin:ana" });   // only Ana's own
mint({ subject: "acme:fin:lead", scope: "acme:fin" });       // the whole finance team
```

A token sees its own subtree and nothing above it. Use a project per customer for hard
isolation, scopes for the hierarchy inside one. → [Scopes](./authentication.md#scopes-isolating-users-inside-one-project)

## Let the agent run code

```ts
await ai.chat.send({ message: "Convert these CSVs to one parquet file and send it back" });
// -> res.attachments: [{ id, kind, url, name, mime_type, size }]
```

The sandbox is provisioned only if the agent actually uses it, and it's bound to the
chat session, so the next turn is in the same workspace. → [Sandboxed compute](./sandbox.md)

## Stop it before something irreversible

```ts
await ai.chat.stream({ message: "email the Q3 numbers to finance" }, {
  onApproval: async (req) => showDialog(req),   // true | false | { approved, note }
});
```

Without `onApproval` the turn returns with `approvals` set and you resume it with
`approval_decisions` — nothing is approved by default, and tool auto-dispatch never sees
these. → [Asking permission](./working-together.md#asking-permission)

## Run something on a schedule

```ts
await ai.tasks.create({
  name: "Monday digest",
  kind: "recurring",
  cron: "0 8 * * 1",
  timezone: "Europe/Istanbul",
  action: {
    type: "agent",
    prompt: "Summarize last week's support tickets.",
    callback_url: "https://app.acme.com/hooks/oberik",   // or poll ai.tasks.get(id)
  },
});
```

Scheduled runs never bind `ask_user` or `approvals`: nobody is watching, so a turn that
paused would wait forever. → [Scheduling](./scheduling.md)

## Start a turn when something happens in another system

```bash
curl -sX POST https://api.oberik.com/triggers \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"prompt":"Triage this ticket: {{ body.subject }}","signed":true}'
# -> { "url": "https://api.oberik.com/triggers/<slug>", "secret": "…" }
```

`prompt` is a template filled in from the event, so the sending system needs to know
nothing about talking to an agent. The URL **is** the credential and the run happens as
whoever created the trigger, so treat it like a password; `signed: true` additionally
requires a matching `X-Signature`. Firing answers `{"accepted": true}` immediately rather
than waiting for the turn — a webhook sender retries a slow response, and that would run
the agent twice on one event. → [Webhook triggers](./scheduling.md#webhook-triggers)

## Let the agent do something in a scheduled run

A client-side tool needs a client. A scheduled run has none — so publish the tool as a
URL and Oberik calls it server-side:

```bash
curl -sX POST "https://oberik.com/api/projects/$ID/webhook-tools" \
  -H "X-API-Key: $KEY" -H "content-type: application/json" -d '{
    "name":"open_ticket","description":"Open a support ticket for the signed-in customer.",
    "url":"https://acme.com/agent/tickets",
    "parameters":{"type":"object","properties":{"subject":{"type":"string"}},"required":["subject"]}}'
```

Your endpoint gets the arguments **and** the end-user's `subject`, `scope`, `roles` and
`groups`, with an `X-Oberik-Signature` over the body so you can trust them. →
[Tools you host](./tools.md#tools-you-host-webhook-tools)

## Call it from a browser

```bash
curl -sX PUT "https://oberik.com/api/projects/$ID/origins" \
  -H "X-API-Key: $KEY" -H "content-type: application/json" \
  -d '{"origins":["https://app.acme.com"]}'
```

Exact origins, no wildcards, and the token is still minted on your server. →
[Calling from the browser](./browser-origins.md)

## Show the user what a long turn is doing

```ts
ai.chat.stream({ message }, {
  onTodos: setChecklist,              // the plan, as it's written and ticked off
  onToolStart: (n) => setStatus(n),
  onCommandOutput: (c) => appendLog(c.delta),   // a build or test run, live
  onSubagents: setWorkers,
});
```

→ [Working with the user](./working-together.md) · [Subagents](./subagents.md)

## Correct it without waiting for it to finish

```ts
const h = ai.chat.stream({ message: "migrate every fetcher" }, { onToken: write });
const landed = await h.steer("only the forfaits-* ones");
if (!landed) { /* the turn ended first — send it as a normal message */ }
```

→ [Steering](./working-together.md#steering--a-message-into-a-running-turn)

## Cap what a single turn may cost

Per request, a client may only ever ask for *less*:

```ts
await ai.chat.send({
  message,
  model: "openai/gpt-4o-mini",
  reasoning_effort: "low",
  enable_computer: false,
  enable_subagents: false,
});
```

The ceilings that a client cannot raise go on the token, at mint time —
`maxToolIterations`, `maxEffort`, `maxContextTokens`, `models`. There is no
platform-imposed tool-loop limit, so this is the place to set one. →
[Bounding a run](./limits-and-errors.md#bounding-a-run)

## Teach it one of your procedures

```ts
// From your server, with the project key. Applies to everyone in the project.
await oberik.skills.upload(zip, { filename: "acme-support.zip" });

// From your app, with an end-user's token. Private to them; needs `plugins:write`.
await ai.plugins.upload(zip);          // a packaged plugin, a zipped folder, or one SKILL.md
```

One feature, two clients, and they are spelled differently: the project client calls it
**`skills`**, the end-user client calls it **`plugins`**. → [Skills](./skills.md)

## Erase a user

```ts
await ai.audit.forget("acme:fin:ana");
// -> { subject, documents_deleted, sessions_deleted, sandboxes_destroyed,
//      tasks_cancelled, vectors_purged, objects_deleted, rows_deleted }
```

Every row that names them goes — documents, conversations, sandboxes, scheduled tasks,
triggers, background jobs, uploaded plugins — and anything with a life outside the
database is torn down rather than merely deleted: a sandbox is destroyed on its host, a
schedule is cancelled with the scheduler, and their **stored files are removed** along
with the rows that named them, unless something that survives still points at one.
`rows_deleted` reports what each table gave up; `objects_deleted`, how many files went.

→ [Guardrails & auditing](./guardrails.md#auditing)

## Find the conversation that went wrong

```ts
const failed = await ai.chat.sessions.list(undefined, { status: "error", limit: 20 });
for (const s of failed.items) console.log(s.id, s.last_model, s.last_error);

// narrow further — a search over id, title, user or model
await ai.chat.sessions.list(undefined, { q: "invoice", model: "gpt-5" });
// what the model filter should offer, read from the traces themselves
await ai.chat.sessions.models();
```

Every session carries what its **last** turn ran on and whether it worked, so finding a
broken conversation does not mean opening them one at a time. Filtering happens
server-side — the rows you want are a handful out of thousands.

## Find out what the agent could actually do right now

```ts
const { tools } = await ai.tools.list();
```

Filtered exactly the way a turn is — ceiling ∩ token ∩ flags — so it answers "what would
my next request get?" rather than "what exists". → [Tools](./tools.md#discover-whats-available)

---

## The SSH interface

# Oberik over SSH

```bash
ssh ssh.oberik.com
```

Everything the dashboard does, as text: sign up, create a project, set the capability
ceiling, upload documents, mint tokens, publish tools, read the docs, talk to the agent.
No client to install and nothing to configure — if you have `ssh`, you have Oberik.

The command set is not hand-written. The control plane describes its own routes, and the
gateway generates commands, help and forms from that description at connect time — so a
new dashboard feature appears here without anyone updating a CLI.

## For coding agents

This interface exists mostly for you. A browser-based dashboard is unusable to something
that only has a shell, and the alternative — asking your user to paste an API key into
your terminal — is the habit that makes credential theft work.

**Sign in without ever handling a credential:**

```bash
ssh ssh.oberik.com 'login link'
# {"ok":true,"data":{"url":"https://oberik.com/auth/device?code=7E2R2NZY","code":"7E2R2NZY"}}
```

Show that URL to your user and ask them to open it. Then:

```bash
ssh ssh.oberik.com 'login wait'      # blocks until they approve, then returns
```

The two are separate commands on purpose. `login link` **returns immediately**, because
a command that blocked while waiting would hand you its link only after the request had
expired — you would never get to show anyone anything. `login wait` is the part that
blocks, which is fine, because by then you know what you are waiting for.

What your user sees is a page naming the SSH key being added, with approve and decline.
You never see their password, and they can check the code on the page against the one
you printed. Once approved, the key is registered: **every later connection is signed in
automatically**, with no link at all.

If you already have a key registered, none of this is needed — just run commands.

**Read the documentation without leaving the shell:**

```bash
ssh ssh.oberik.com 'docs'                      # every page, with what it covers
ssh ssh.oberik.com 'docs page quickstart'      # one page, in full
ssh ssh.oberik.com 'docs search capability'    # the lines mentioning something
```

This is the same text as [the docs site](/), so nothing is a summary of something else.

**Everything is scriptable:**

```bash
ssh ssh.oberik.com 'discover'                  # the whole command catalog as JSON
ssh ssh.oberik.com 'projects --json'           # any command, as JSON
ssh ssh.oberik.com 'format json; project use acme; capabilities'   # several per line
```

**The flag goes inside the quotes.** `ssh ssh.oberik.com --json 'projects'` cannot run:
`ssh` parses its own options after the destination too, so the client eats `--json` and
answers with its own usage dump — which mentions neither Oberik nor the flag, and reads
like a broken host or a bad key. Everything after the destination is one command line for
the gateway, so every flag belongs inside it.

`format json` is the better answer for a line with several commands: it sets the output
format for the rest of the line rather than being repeated per command.

If a VALUE starts with `--`, put `--` in front of it — everything after that is an
argument rather than a flag:

```bash
ssh ssh.oberik.com 'docs search -- --json'     # search for the text "--json"
```

`discover` is worth reading first: it gives every command, its parameters and their
types, so you can drive this without guessing at syntax.

**The JSON envelope.** Every response is one line:

```jsonc
{"ok": true,  "command": "projects", "message": null, "data": [ … ]}
{"ok": false, "command": "playground end", "message": "…", "error": "…", "data": null,
 "status": 400}
```

Branch on `ok`. The human-readable text is in `message` either way — a failure repeats it
in `error`, which is the field to prefer when you want *only* the failure text. It used to
appear in `error` alone, so a client logging `message` printed a blank for a perfectly
clear three-line error. `status` is the HTTP status behind it, so a retry can tell a `429`
from a `400`.

**Every line gets one, including the ones that failed, and including a line that was never
a command at all.** That holds in a session you hold open as well as in a one-shot
invocation — the two used to differ, so a program running several commands down one
connection parsed the successes and got human prose for the failures. If you asked for
JSON, prompts are off too: a command missing a required field answers with what is missing
rather than opening a form into the middle of your stream, and a destructive one answers
`re-run with --yes` rather than stopping to ask.

## A first session, end to end

```bash
# 1. sign in (or `signup <email> <password>` if you have no account)
ssh ssh.oberik.com 'login link'          # show the URL to your user
ssh ssh.oberik.com 'login wait'          # blocks until approved

# 2. an organization and a project — the project provisions an isolated tenant
ssh ssh.oberik.com 'org new "Acme"'
ssh ssh.oberik.com 'project new "Support Bot"'

# 3. what tokens minted for it may do
ssh ssh.oberik.com 'project use "Support Bot"; capabilities set --allowTodo on --allowComputer on'

# 4. a server-side key, then an end-user token
ssh ssh.oberik.com 'key new ci'                       # pk_… shown once
ssh ssh.oberik.com 'token --subject acme:user_1'      # a JWT for one end-user

# 5. try the agent
ssh ssh.oberik.com 'chat "what can you do?"'
```

Every one of those maps to a dashboard screen; `open` browses the same thing as pages
with numbered menus if you would rather look around than know the command.

## Two identities on one connection

Almost every command acts as **you, the operator** — `documents`, `document upload`,
`capabilities`, `providers`, `sources`, `audit`. One does not:

```bash
ssh ssh.oberik.com 'dp GET /capabilities'   # {"subject":"user", …}
```

`dp` is the raw data-plane escape hatch, and the data plane only speaks end-user tokens, so
it mints one — **it sees the project the way one of your customers does.** That makes
`documents` and `dp GET /documents` return different corpora on the same connection:

```bash
ssh ssh.oberik.com 'document upload notes.txt --visibility self'
ssh ssh.oberik.com 'documents'          # you see it — you own it
ssh ssh.oberik.com 'dp GET /documents'  # a customer does not, so neither does dp
```

Nothing is broken there: a `self`-visibility document belongs to whoever uploaded it, and
the ACL is doing its job in both answers. But the difference is **silent** — a shorter list
and a `200`, never a refusal — so use `documents` and `document` to audit what a project
holds, and `dp` to check what a customer actually gets.

The corollary is that `dp` cannot do the operator-only things either. `/audit` requires an
admin role and an end-user token is not an admin, so `dp GET /audit` answers
`403 admin role required` — read the trail with `audit`, which goes through the control
plane with the project key like every other operator command:

```bash
ssh ssh.oberik.com 'audit --limit 20'
ssh ssh.oberik.com 'audit --subject acme:user_1'
```

## Reporting a bug

```bash
ssh ssh.oberik.com 'bug report "Uploads fail" "A 14MB PDF returns a 500."'
```

Two arguments, because everything else is already known: who you are comes from the
session, and which client filed it from the connection. Add `--project` when it is about
one — by name, the way you would say it:

```bash
ssh ssh.oberik.com 'bug report "Retrieval is empty" "No chunks come back." --project "Support Bot"'
```

A project you cannot reach is refused rather than dropped, so a report never ends up
filed against nothing when you thought you had said where it happened.

`bugs` lists what you have filed and `bug status <id> closed` closes one when it stops
happening. The same reports arrive from the dashboard's **Report a bug**, in the sidebar.

For anything that is not a bug — a feature you need, a question about your integration,
or a look at what you are building — [hello@oberik.com](mailto:hello@oberik.com) reaches
a person.

## Registering a key by hand

If you already have a session — or you would rather not use the link flow — the key you
connected with can be registered directly:

```bash
ssh ssh.oberik.com 'ssh-key add'                # registers the key this connection presented
ssh ssh.oberik.com 'ssh-keys'                   # what is registered
ssh ssh.oberik.com 'ssh-key rm <id> --yes'      # remove one — confirmed, like the others
```

`ssh-key add` with no argument uses the key you are already connected with, so there is
nothing to paste.

**A key is identified by its fingerprint, not by its name.** `ssh-key add` derives the name
from the enrolment command, so every key enrolled the same way carries the same one — the
picker and the confirmation both name the fingerprint instead.

**`status` says which key this connection is using** — it is the `keyFingerprint` field,
and it is `null` on a password or guest session because there is no key to name. So you do
not have to work it out from `lastUsedAt`; and if you point `ssh-key rm` at that one, the
confirmation says so:

```
! Remove a registered SSH public key (SHA256:kBliaV…) — this is the key this connection
  is using, and you cannot re-add it over SSH — irreversible. Re-run with --yes to confirm.
```

## Sending a file

There is no SFTP and no file picker: the gateway runs on our side and cannot read your
disk. So a command that takes a file takes its **name** as the argument and its **bytes**
from the connection — you pipe the file into the `ssh` command itself.

```bash
ssh ssh.oberik.com 'use "Support Bot"; document upload handbook.pdf --tags policies' < handbook.pdf
ssh ssh.oberik.com 'use "Support Bot"; skill upload refunds.zip'                     < refunds.zip
```

The filename you pass is the name the document is stored under, so it is worth it matching
the file you are piping — nothing checks that they agree.

For something short, or from a session with nothing to pipe, `--content` takes the body
inline instead:

```bash
ssh ssh.oberik.com 'use "Support Bot"; document upload notes.md --content "Refunds are 30 days."'
```

`help document upload` lists both, along with every other field the route takes. This works
for any described route with a file field, present or future — `discover --json` reports
them as `"type": "file"`, which is how a client can tell a field that needs bytes from one
that needs a string. It is the only way a command can read your bytes, so the catalog
cannot be wrong about which ones do.

An upload is stored `tenant`-visible by default — readable by every end-user of the
project, which is what a curated corpus is for. The same fields the dashboard offers are
here to narrow it:

```bash
ssh ssh.oberik.com 'use "Support Bot"; document upload rates.csv \
  --visibility groups --acl_roles finance' < rates.csv
```

Ingestion is asynchronous. The row appears immediately and turns `ready` once it is
indexed, so poll it if the next thing you do depends on the corpus:

```bash
ssh ssh.oberik.com 'use "Support Bot"; documents'      # status per document
```

## Destructive commands, and how confirming works without a person

Some commands ask before they run — `project rm`, `org rm`, `document rm`, `wiki rm`,
`ssh-key rm`. `discover` reports which, as `confirm: true` on the command.

`ssh-key rm` is the one worth knowing about: every other delete here is re-doable from the
same connection — mint another key, re-add the provider, re-add the MCP server — while this
one removes the credential the connection is authenticated by. Remove the key you are using
and you cannot re-add it over SSH, because you can no longer open a session.

What confirming means depends on who is driving, and the safeguard is deliberately *not*
the prompt:

- **At a terminal**, you are asked to type `yes`, with the target named in the question.
- **Non-interactively** — `ssh host 'project rm …'`, a script, an agent — there is nobody
  to ask, so the command refuses outright unless you pass `--yes`.
- **In both cases the target has to be named as an argument.** `--yes` skips the prompt; it
  never skips the name. `project rm` takes the project's name and the server checks it
  against the selected project, so the delete either lands on the project you identified or
  on nothing at all:

```bash
ssh ssh.oberik.com 'project use "Support Bot"; project rm "Support Bot" --yes'
# and a mistake is a 400, not a deleted workspace:
ssh ssh.oberik.com 'project use "Support Bot"; project rm "Staging" --yes'
# ! "Staging" is not this project's name — it is "Support Bot". Nothing was deleted.
```

That is the part that matters for an agent. A prompt is a speed bump for someone who is
already looking at the right screen; the failure mode for a client that is not looking at a
screen is acting on whatever the connection happens to have selected. Naming the target
removes that, and the acknowledgement is recorded in the command log either way.

`project rm` erases the project's tenant — documents, agent knowledge, conversations,
uploaded files, sandboxes, scheduled tasks — along with its keys and provider credentials.
It answers with what the erasure reached. There is no undo.

## What it is not

The gateway holds no state and no privileges of its own. Every command runs through a
control-plane session over HTTP, exactly as the React app does — so it can do what your
account can do, and nothing more. Signing out, revoking a key, or deleting the account
takes effect here immediately, because there is nothing else to revoke.

## What is recorded

Every command you run over SSH is logged, with the address it came from and — once you are
signed in — your account. The gateway is a public front door that anyone may connect to
anonymously, so this is how abuse is told apart from use.

**Credentials are not stored.** A password typed at `login`, and a provider key passed as
`--values {"api_key":"…"}`, are replaced with `<redacted>` before the row is written. The
rest of the command is kept as-is, so `login you@example.com <redacted>` still records who
tried. Alongside it is a hash of the original line, which lets repeated commands be
correlated without the credential being recoverable.

Records are kept for 30 days, or 100,000 commands, whichever comes first — except for rows
an operator has flagged while investigating something.

If you would rather not have a credential in a log at all, don't pass one: register your
key (`ssh-key add`) or use the browser flow (`login link`), and no password is typed on a
command line in the first place.

**Repeated failed logins get slower.** After a handful of wrong passwords for the same
account (or from the same address) inside ten minutes, each further attempt is held back a
little longer, up to a few seconds. Nothing is ever locked: a person who has forgotten
which password they used never reaches the delay, and a client whose credentials have gone
stale is slowed rather than shut out. If you are automating `login`, the fix is the
credential — a retry loop against a wrong password gets progressively less useful, which is
the point.

---

## Authentication


There are two credentials and they are not interchangeable.

| Credential | Lives | Used for |
|---|---|---|
| **Project API key** (`pk_…`) | your server, only | minting end-user tokens; project administration |
| **End-user token** (JWT) | your frontend, or your server | every data-plane call: chat, documents, actions |

The rule: **your server mints, your client calls.** A token carries the permissions, so
your frontend never holds anything that could widen them.

:::tip Issue a mint-only key
A project key carries a **scope**, chosen when you create it:

| Scope | What it can do |
|---|---|
| `mint` *(default)* | Mint end-user tokens for this project, and read its capability ceiling. Nothing else. |
| `admin` | Every [Project API](./project-api.md) call: the ceiling, the corpus, skills, further keys, deleting the project. |

Almost every backend wants `mint`. It is the difference between a leaked key costing
you some tokens and costing you the workspace — an `admin` key can raise the project's
own ceiling and delete everything in it.

An `admin` key satisfies a mint requirement, never the reverse. A mint key used on an
admin route is refused with a 403 that says so. Either way: keep it in a secret store,
one per environment, and revoke it in the dashboard the moment it might have leaked.
:::

## Minting a token

```bash
curl -X POST "https://oberik.com/api/projects/$PROJECT_ID/token" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" \
  -H "content-type: application/json" \
  -d '{
    "subject": "acme:finance:user_9f3c",
    "scope": "acme:finance:user_9f3c",
    "capabilities": ["chat", "documents:read"],
    "expiresIn": 3600
  }'
```

```json
{ "access_token": "eyJ…", "expires_in": 3600, "capabilities": ["chat", "documents:read"] }
```

Send it as `Authorization: Bearer <access_token>`.

### Fields

| Field | Meaning |
|---|---|
| `subject` | Who this token is. Owns whatever it creates, and is the default visibility boundary. |
| `scope` | What it may **see** — a path prefix. Omit to mean "only this subject's own data". |
| `capabilities` | What it may **do**. Intersected with the project's ceiling; you can narrow, never widen. Modalities are the exception — see below. |
| `roles` / `groups` | Labels used by document ACLs — **except three role names that are privilege grants.** See below. |
| `models` | Restrict this token to a subset of models. |
| `maxEffort` | Cap reasoning effort. |
| `maxToolIterations` | Cap agent↔tool loops for this token. Unset means unlimited. |
| `expiresIn` | Seconds. Keep it short and mint per session. |

### `admin`, `owner` and `service` are not labels

:::danger Do not forward your application's own role names

Three role names mean something to the data plane. A token carrying `admin`, `owner` or
`service`:

- reads **every** end-user's chat sessions in the project, not just its subject's —
  `chat.sessions.list()` returns the whole tenant;
- reads every document and memory regardless of owner (`self`-visibility is the one
  exception, which even an admin cannot see);
- is what `ai.audit.list` and `ai.audit.forget` require.

That is the entire per-end-user isolation boundary, switched off by a string. If your
backend maps its own users' roles onto this field — and `admin` is the most likely name
to pass straight through — one customer's admin gets every customer's conversations.

Use `groups`, or any other name, for ACL labels; those carry no privilege. Mint an
admin token deliberately, for a back-office caller, and never from a role name that
arrived in a request. The mint response returns a `warnings` array whenever a
privileged role was granted, so you can assert on it in a test.

:::

### Read `warnings` on every mint

The same array says when a capability you asked for is **not** on the token, which is
otherwise invisible until something else refuses:

```jsonc
{ "capabilities": ["chat", "input:file", "output:file"],
  "warnings": [
    "'tasks' is not a capability — did you mean 'tasks:read' or 'tasks:write'? Nothing was
     granted for it, and a request needing it will be refused later by whichever call needs it.",
    "'computer' was not granted: this project's ceiling does not allow it. Turn it on under
     Capabilities in the dashboard, or mint without it — the agent will otherwise simply say
     it cannot do the thing, which is not something you can assert on."
  ] }
```

Two different mistakes with two different fixes: the first is a spelling, the second is a
dashboard toggle. Without them a mistyped name mints happily and the `403` arrives from
`tasks.create` forty seconds later, and a ceiling-trimmed capability shows up only as the
agent explaining in prose that it cannot help — which no test can assert on.

## Capabilities

A capability is a permission the data plane checks on every call. The project's
**Capabilities** page is the ceiling; a token can hold any subset of it.

List the ones *this end-user* needs. The [modality](./multimodal.md) capabilities —
`input:<kind>` and `output:<kind>` — are the one thing you don’t have to restate: leave
them out and the token carries whatever the project is configured for. They describe
what the agent you built can perceive and hand back, which is a property of the project
rather than a decision about one user, and reading their absence as a refusal meant an
app that listed its tool permissions ended up with an agent that could write a document
and not give it to anyone. Name any `output:<kind>` and you're being explicit: that side
narrows to exactly what you listed. The two sides are independent, and neither can
exceed the ceiling.

The full set, grouped the way the dashboard groups them. Every one is also declinable
per request with the `enable_*` flag beside it.

| Capability | Grants | Per-request flag |
|---|---|---|
| **Conversation** | | |
| `chat` | conversations | — |
| `system_prompt` | send a per-request system message (the project's still applies, and wins) | — |
| `steer` | [a message into a running turn](./working-together.md#steering--a-message-into-a-running-turn) | — |
| `voice` | [talk to the agent](./voice.md) — a live full-duplex call, not a transcript round trip. The per-request flag governs the agent's own conversation controls (hold, resume), not whether a call can be opened | `enable_voice_control` |
| **Knowledge** | | |
| `documents:read` / `documents:write` | search / upload and manage [documents](./documents.md). Setting the project to **read-only documents** stops `documents:write` ever being minted | `enable_rag` |
| `memory` | [durable memory and the wiki](./scheduling.md#memory) | `enable_memory` |
| **Internet** | | |
| `web_search` | public web search and page reads | `enable_web_search` |
| `browser` | [drive a real browser](./tools.md#driving-a-browser) — click, type, scroll, screenshot | `enable_browser` |
| `browser_handoff` | [hand a page to the user](./tools.md#handing-the-page-to-the-user) when only a person can act | — |
| **Agentic** | | |
| `todo` | [the plan it keeps](./working-together.md#todos--the-agents-plan) across a conversation | `enable_todo` |
| `computer` | [sandboxed compute](./sandbox.md) | `enable_computer` |
| `subagents` | [work handed to another agent](./subagents.md) beside it | `enable_subagents` |
| `tasks:read` / `tasks:write` | [scheduling](./scheduling.md) | `enable_scheduling` |
| `triggers` | [webhook triggers](./scheduling.md#webhook-triggers) an end-user may create | — |
| **Human in the loop** | | |
| `ask_user` | [pause on a question](./working-together.md#questions-the-agent-asks) and wait for an answer | `enable_ask_user` |
| `approvals` | [stop before something irreversible](./working-together.md#asking-permission) | `enable_approvals` |
| `ui_tools` | [components it draws into your UI](./tools.md#ui-components--tools-that-draw) | — |
| `voice:transfer` | on a call, [hand the caller to a person](./voice.md#transfer) — they wait on hold while whoever picks up is briefed, and come back to the agent if nobody does | — |
| `followups` | suggested next messages, generated beside the conversation | — |
| `recap` | a one-line "where we got to" for someone returning | — |
| `auto_title` | name each conversation from its first message; titles stay empty otherwise, and a title you set yourself needs no capability | `enable_auto_title` |
| **Extensions** | | |
| `webhook_tools` | the agent may call the [tools you publish as URLs](./tools.md#tools-you-host-webhook-tools) — they work in unattended runs, where a client-side tool has no client | `enable_webhook_tools` |
| `mcp:manage` | end-users may attach their own [MCP servers](./tools.md#mcp-servers) | — |
| `plugins:write` | end-users may **upload** their own [skills](./skills.md#who-can-upload). Using the ones you published needs no capability — decline them for a turn with `enable_plugins: false` | `enable_plugins` |
| `action_space` | relevance-based tool pre-selection for large catalogs | `enable_action_space` |
| **In and out** | | |
| `input:file` | a user may attach **any** file; what the model can't perceive is read as text (OCR, transcript, extraction) | — |
| `input:image` / `audio` / `video` | the model may perceive that kind **directly**, rather than through extraction | — |
| `output:file` | the agent may hand back **any file it produced** — a document, a sandbox export, a screenshot | — |
| `output:image` / `audio` / `video` | the model may **generate** that kind | `output_modalities` |

Anything not granted is refused — **including a tool the model tries to call anyway**.
That's the point: prompt injection can't reach a capability you didn't grant.

```ts
// A read-only research token.
capabilities: ["chat", "documents:read"]

// Narrow further per request: this turn may only read documents, nothing else.
await ai.chat.send({ message, allowed_tools: ["rag_search"] });
```

:::note "Read-only" here means read-only, network included
A token like the one above carries the project's **modality** capabilities too —
`output:file` and `output:image` are inherited rather than listed ([Files &
media](./multimodal.md)) — so it can hand back a file the agent produced.

It cannot reach the network. Every tool that fetches something is behind a capability this
token does not list: `web_search` and `browse_url` behind `web_search`, the browser family
behind `browser`, and `screenshot_url` behind `web_search` as well (it fetches a URL to
make the image it returns). That last one used to be gated on the output modality alone,
which meant this exact token could read an external page — [details](./tools.md#driving-a-browser).

`allowed_tools` still narrows further per request when you want a capability granted and
one tool withheld.
:::

## Scopes: isolating users inside one project

`scope` is a path prefix, with `:` as the separator. A token sees its own subtree.

| `subject` | `scope` | Sees |
|---|---|---|
| `acme:fin:ana` | `acme:fin:ana` | only Ana's own documents and sessions |
| `acme:fin:lead` | `acme:fin` | everything in the finance team |
| `acme:admin` | `acme` | the whole customer |

Use one **project per customer** for hard isolation, and scopes for the hierarchy
*inside* that customer.

## Rotation and expiry

Mint a token per user session with a short `expiresIn`. Rather than handing the SDK a
static token and dealing with expiry at every call site, give it `getToken` — the SDK
calls it back with `{ expired: true }` when the current token is finished with, replays
the request with the new one, and your code never sees the 401:

```ts
const ai = createClient({
  getToken: async ({ expired }) => {
    if (!expired && cached) return cached;          // your own cache
    cached = await mintFromYourBackend();           // the endpoint above
    return cached;
  },
});
```

This is the recommended way to authenticate. Details worth knowing:

- **Two things call you back with `{ expired: true }`**, and the second is the one that
  surprises people. The first is a `401` — the server rejected the token. The second is a
  local check: if the token you returned **expires within the next 60 seconds**, the SDK
  asks for another one *before sending anything*. So you will see `{ expired: true }` with
  no request having failed. That is a `401` avoided rather than recovered from.
- The check is on the token's **remaining** life, not on the `expiresIn` you minted it
  with. A short-lived token trips it straight after minting; a long-lived cached one trips
  it in its final minute — which is the recommended shape working as intended, not a
  problem. There is no TTL for which it never fires.
- Either way it costs **one extra mint per client**, not per request. If the replacement is
  also inside the margin (a project whose whole TTL is under a minute), the SDK stops
  checking ahead for that client rather than minting on every call, and expiry goes back to
  being handled by the `401`.
- Concurrent requests share **one** refresh, so a page that fires five calls at once
  doesn't mint five tokens.
- A request is replayed at most once, so a token that's still rejected surfaces as a
  normal `401` instead of looping.
- An interrupted stream re-attaches to the **same run** with the new token — an answer
  in flight is neither lost nor paid for twice.
- If your callback throws, the original `401` is what you get, not the callback's error.

A static `token` still works and is fine for a script or a server job shorter than the
TTL — but nothing can rescue it once it expires.

### Narrowing a token you already hold

A backend that already has a project credential can mint a narrower one without going back
to the control plane:

```ts
const { access_token } = await ai.auth.token({
  user_ref: user.id,
  capabilities: ["chat", "documents:read"],
  scope: `${user.orgId}:${user.id}`,
  allowed_models: ["openai/gpt-4o-mini"],
  max_effort: "low",
  expires_in: 900,
});
```

Every field here is intersected or clamped against what the calling credential holds, so
a restricted token cannot mint a broader one. That covers what the child may *do*:
capabilities, scope, `data_scope`, `allowed_models`, `max_effort`, the tool-iteration and
context ceilings, and the subject it may be minted for — a bound the caller holds is
applied whether or not you mention the field, because an absent claim reads as
*unrestricted*.

**`expires_in` is the exception, and it is deliberate.** It is clamped against the
project's maximum rather than the caller's remaining lifetime, so a 10-minute token can
mint a 24-hour one. The child holds no more *privilege* than its parent — it is the same
grant, for longer — and a short-lived credential refreshing itself into a session is a
pattern worth keeping. Size a token's lifetime by what it may do, not by the lifetime of
whatever minted it.

`allowed_models` narrows *within* the project's own registrations; it is not what keeps a
token inside them. A request may only name a model this project registered, whatever the
token says:

```
model: "gpt-4o"      // on a project that registered only "hukuk-db"
400 model 'gpt-4o' is not available to this project. Registered: hukuk-db
```

That boundary is checked before the request goes anywhere, so a name the project never
configured cannot reach a shared deployment, cannot spend on anything but the project's own
key, and cannot escape its cap. Use `allowed_models` to narrow further — pinning a browser
token to your cheapest model — rather than as the thing standing between projects.

Project API keys are shown once at creation and can be revoked from the dashboard.
Revoking one immediately stops new tokens being minted with it; already-minted tokens
expire on their own schedule.

:::warning Never put a project key in a browser
It can mint tokens with any capability the project allows. If one leaks, revoke it in the
dashboard and create a new one.
:::

---

## Project API


Everything on a project's dashboard is an HTTP call your server can make with the
project key. Nothing here needs a browser, a session or a human, so a project's
configuration can live in your repository and be applied by a deploy rather than
reconstructed by clicking.

```bash
export OBERIK_PROJECT_KEY="pk_…"
export OBERIK_PROJECT_ID="7f3c…"    # a UUID
CP=https://oberik.com
```

## Which client

There are two, and knowing the feature does not tell you which one has it:

- **`createProjectClient`** — the **project key**, server-side. What an *operator*
  configures: providers, models, limits, the capability ceiling, skills, MCP servers,
  webhooks, retrieval, the system prompt.
- **`createClient`** — an **end-user token**, usable in a browser. What a *user* does:
  chat, their documents, memory, tools, sandboxes, voice — and `audit`, which needs a
  token minted with `roles: ["admin"]`.

Two real confusions, in opposite directions, from people who knew the product well:

| Reached for | Actually on | Why it is not obvious |
|---|---|---|
| `project.audit.list(…)` | the **end-user** client, admin role | reading a trail feels like an operator's job |
| `ai.retrieval.set(…)` | the **project** client | choosing the embedding model feels like a user setting because retrieval is what a user experiences |

And three names exist on **both**, meaning different things — the case where guessing
wrong still compiles:

- **`documents`** — the project client sees every document in the project; the end-user
  client sees what that user's token may see.
- **`capabilities`** — the project client sets the project's *ceiling*; the end-user
  client reads what this token actually carries.
- **`tasks`** — the project client manages the project's schedules; the end-user client
  manages that user's own.

`createProjectClient` also takes `projectId` **and** `projectKey`, not an `apiKey`.

The SDK has a server-side client for all of it:

```bash
npm install @oberik/sdk
```

```ts
import { createProjectClient } from "@oberik/sdk";

const oberik = createProjectClient({
  projectId: process.env.OBERIK_PROJECT_ID!,
  projectKey: process.env.OBERIK_PROJECT_KEY!,
});

await oberik.readiness();                        // can this project answer yet?
await oberik.tokens.mint({ subject: "acme:ana", capabilities: ["chat"] });
await oberik.capabilities.set({ allowTodo: true, allowComputer: true });
await oberik.documents.upload(file, { tags: ["policies"] });
await oberik.systemPrompt.set("You are Acme's support agent.");
await oberik.origins.set(["https://app.acme.com"]);
await oberik.webhookTools.create({ name: "cancel_order", description: "…", url: "…" });
await oberik.keys.create("ci", { scope: "admin" });
await oberik.usage.observability();
```

It is a **different client** from the one your app uses, deliberately. That one takes an
end-user token and belongs wherever your app runs; this one holds the project key and
belongs only on your server — so it throws if it is ever constructed in a browser,
rather than shipping and leaking the key to every visitor.

The curl equivalents are below, since everything here is one HTTP call. Each carries the
same header:

```
X-API-Key: pk_…
```

:::danger Everything on this page needs an `admin` key
A project key carries a scope, and a new key defaults to **`mint`** — enough to mint
end-user tokens and read the capability ceiling, and nothing else. That is what a
backend usually wants, and it is what you should be holding unless a script genuinely
administers the project.

The calls on this page are the rest of the Project API, so they need an **`admin`** key:
it can change the capability ceiling, upload and delete documents, publish skills,
**create more keys**, and **delete the project**. Treat one exactly like a root
credential — server-side only, in a secret store, one per environment, revoked in the
dashboard the moment it might have leaked. A mint key used here is refused with a 403
that names the scope it has.

Already-minted end-user tokens are unaffected by a revocation and expire on their own
schedule.
:::

## Read the whole project

```bash
curl -s "$CP/api/projects/$OBERIK_PROJECT_ID" -H "X-API-Key: $OBERIK_PROJECT_KEY"
```

Returns the project, its `capabilities` ceiling, default model and context settings —
the same object the dashboard renders. `GET …/capabilities` returns just the ceiling,
with **every** flag present (an untouched one comes back `false`, not missing), plus
`supportedModalities`: what the project's registered models can actually read and
produce.

In the SDK, `oberik.project.get()` and `oberik.project.set({ … })` cover this and the
top-level fields (`name`, `description`, `doneWebhookUrl`), and `oberik.project.citations()`
sets the marker style.

It also carries **`health`** and **`healthDetail`** — the same badge the dashboard renders
on the project card, so you can show your own operators what Oberik shows you rather than
reconstructing it:

```ts
const p = await oberik.project.get();
// p.health        "ok" | "degraded" | "down"
// p.healthDetail  "Every request fails until this is done — your own provider key, and the
//                  models it may use. POST /api/projects/:id/providers · dashboard: LLM &
//                  limits → Add provider"
```

`healthDetail` is a written sentence that leads with what still works and then names what
does not; it is not reconstructable from the booleans. Both fields come from `readiness`
below — one function computes them, so no surface can report a different badge than
another.

:::tip Anything without a method: `oberik.raw()`
The project client wraps the routes people use most, and this page describes more than
that. For any route with no method of its own, `raw` is the escape hatch — same key, same
base URL, same error handling, so you never have to hand-roll a control-plane fetch:

```ts
await oberik.raw("GET", "/sandbox-host");   // what this deployment's sandboxes provide
```

The example here used to be `raw("PUT", "/subagents", …)`, and then
`oberik.subagents.set()` existed; the same has since happened to `/computer`. When a route
grows a method, `raw` keeps working — it just stops being the shortest way.

Paths are relative to `/api/projects/:projectId`.
:::

## Set the capability ceiling

The ceiling is the maximum any token minted for this project may hold. Minting
intersects with it, so a token can always be narrower and can never be wider.

```bash
curl -sX PATCH "$CP/api/projects/$OBERIK_PROJECT_ID" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"capabilities":{"allowTodo":true,"allowComputer":true,"allowApprovals":true}}'
```

**Only the flags you send change**; the rest are preserved, so you never have to read
the ceiling back and resend it whole.

| Field | Type | Grants the capability |
|---|---|---|
| `allowChat` | boolean | `chat` |
| `allowDocuments` | boolean | `documents:read` (+`documents:write` unless read-only) |
| `documentsMode` | `"read-write"` \| `"read"` | read-only stops `documents:write` ever being minted |
| `allowMemory` | boolean | `memory` |
| `sharedWiki` | boolean | one wiki for the project instead of one per end-user |
| `allowWebSearch` | boolean | `web_search` |
| `allowBrowser` | boolean | `browser` |
| `allowBrowserHandoff` | boolean | `browser_handoff` |
| `allowTodo` | boolean | `todo` |
| `allowComputer` | boolean | `computer` |
| `allowSubagents` | boolean | `subagents` |
| `allowScheduling` | boolean | `tasks:read`, `tasks:write` |
| `allowTriggers` | boolean | `triggers` |
| `allowAskUser` | boolean | `ask_user` |
| `allowApprovals` | boolean | `approvals` |
| `allowUiTools` | boolean | `ui_tools` |
| `allowFollowups` | boolean | `followups` |
| `allowRecap` | boolean | `recap` |
| `allowSteer` | boolean | `steer` |
| `allowSystemPrompt` | boolean | `system_prompt` |
| `allowWebhookTools` | boolean | `webhook_tools` |
| `allowMcp` | boolean | `mcp:manage` |
| `allowPluginUploads` | boolean | `plugins:write` |
| `allowActionSpace` | boolean | `action_space` |
| `inputModalities` | string[] | `input:image` … — bounded by what your models can read |
| `outputModalities` | string[] | `output:image` … — `file` is always grantable |
| `sessionVisibility` | `"private"` \| `"self"` | who may read a session — see below |
| `defaultRoles` / `defaultGroups` | string[] | used when a mint does not name its own. An explicit `roles` / `groups` **replaces** these — including `[]`, which mints with none. `admin`, `owner` and `service` bypass per-user isolation, so do not put your own application's role names here |
| `allowedTools` | string[] \| null | a project-wide tool allow-list |

The two modality lists take members of a closed set — `image`, `audio`, `video`, `file` —
and anything else is **refused**, naming the set, the way `sessionVisibility` and
`documentsMode` are. `["image"]` used to be indistinguishable from `["banana"]`: both were
filtered out and both answered 200, so `outputModalities: ["image"]` could quietly leave a
project able to produce nothing at all.

A real modality that **no registered model supports** is a different thing and still
**dropped on save** rather than granted — otherwise every token would carry a promise the
agent then refuses — but the response says so in `warnings`, naming the modality and what
would make it stick. Read the response back either way: what it returns is what was stored.

### `private` vs `self`

They are not synonyms, and the difference is about **your** staff rather than your
end-users. Both keep one end-user out of another's conversations.

| | who can read a conversation |
|---|---|
| `private` (default) | its owner, a tenant admin, and any token whose `scope` covers the owner — the last one is what makes a support view or a team-lead view possible |
| `self` | the exact owner, and nobody else. An admin token is refused, and so is a scoped one |

Pick `self` when even your own staff must not read the conversation — a therapy intake, an
HR channel, a whistleblowing form. Everything else wants `private`, because with `self` a
support engineer cannot see the thread a customer is complaining about, and no role or
scope can be granted to change that.

A value outside the two is refused (`sessionVisibility 'tenant' is not one of: private,
self. Nothing was changed.`) — deliberately not coerced to the safe default, because a
caller who typed `"tenant"` meant something, and a 200 that quietly stored `private`
would be the same defect one field over.

**An empty string is refused too**, and that is the case worth knowing, because nobody
types it: it is what an untouched `<select>`, a cleared input, or `--sessionVisibility
"$UNSET_VAR"` in a deploy script produces. It used to be stored — so a field deciding who
may read your customers' conversations could be set to `""` by a shell variable nobody had
exported. To clear a setting back to its default, omit it or send `null`; `""` is not a
second spelling for that. (An empty *query* value is still absence — `?status_filter=`
means "no filter", as it does everywhere.)

**A setting whose empty or null state removes a restriction costs an explicit
`confirm: true`.** That is the rule, and it exists because those writes are the ones with no
symptom: clearing a restriction breaks nothing, raises no error, and leaves every existing
caller working exactly as before — so it is found later, by somebody reading an invoice or
an access log. The refusal counts what would go and says what it would mean:

```
origins.set([])                     -> 400  this clears all 1 allowed origin(s), which lets ANY
                                            origin call the API with this project's tokens.
limits.set({maxBudget: null, …})    -> 400  this removes every usage limit on the project,
                                            including its spend cap…
capabilities.set({allowedTools: null})    -> 400  …every token this project has ever issued may
                                            reach every tool its capabilities allow.
capabilities.set({maxToolIterations: null}) -> 400  …there is no platform bound behind it.
```

A widening you ask for **by name** is not guarded — `allowComputer: true` says what it does,
and confirming it would be nagging. The guard is for the ones expressed as *absence*, where
the call looks like tidying up a list.

### Destructive deletes ask too, and the route is what asks

The rule above is about writes that remove a restriction. The mirror of it is deletes that
remove a **thing**, and those carry `?confirm=true` on the URL:

```
DELETE /providers/{credId}          -> 400  Remove a provider credential and its model
                                            deployments — this cannot be undone: the
                                            credential cannot be read back — only a hint is
                                            ever shown — and the model deployment(s)
                                            registered from it go too. Nothing was changed.
                                            Re-send with `?confirm=true` …
DELETE /providers/{credId}?confirm=true  -> 204
```

Which deletes are gated is decided by **what the caller can reconstruct**, not by how
irreversible they are. Removing a document, a wiki page, an organization, a project, an SSH
key or a provider credential destroys the only copy of something; removing an MCP server, a
webhook tool or a plugin destroys a URL and a name you still have. Revoking an API key is
irreversible and deliberately *not* gated — revocation is the emergency path for a
compromised key, and a prompt there is the wrong trade.

The guard lives on the route, so every client inherits it: `--yes` in the SSH gateway, the
dashboard's confirmation modal and the SDK's `{ confirm: true }` are three spellings of the
same server-side rule. A client can decline to confirm; none of them can skip being asked.

```ts
await project.providers.delete(credId, { confirm: true });
await project.documents.delete(documentId, { confirm: true });
await project.wiki.delete(itemId, { confirm: true });
```

:::warning `[]` and `null` are not two spellings of the same thing

On `allowedTools` they are **opposites**, and `GET /tools` is where you see it:

| `allowedTools` | tools a token can reach |
|---|---|
| `["read_file", "write_file"]` | those two |
| `[]` | **none at all** — a list that permits nothing |
| `null` | **every one** the capabilities allow — no list |

Both cost a `confirm`, because both change what every token the project has ever issued may
do, and each refusal says which of the two you are about to get. Note that `origins` is the
other way round — there `[]` **removes** the restriction and lets any origin call. That is
why each setting's refusal describes its own outcome rather than the gesture: "empty clears
it" is not a rule that holds across the surface.

Over SSH, `--allowed-tools ""` sends the **empty list**, not the removal. Removing the
restriction is `allowedTools: null` through the API or the SDK.
:::

`confirm` is a top-level field on these calls, beside `capabilities` rather than inside it.
The SDK takes it as a **second argument** on `capabilities.set`, `origins.set`,
`systemPrompt.set` and `defaultModel.set`:

```ts
await project.capabilities.set({ allowedTools: null }, { confirm: true });
```

`limits.set` is the exception and takes it **inside** the object — `limits.set({ maxBudget:
null, budgetDuration: null, confirm: true })` — because that call is already a bag of
optional fields rather than one value plus options. Over SSH every one of them is
`--confirm`.

**Numbers are refused the same way.** A value outside a field's declared range is a `400`
naming the bounds — `execTimeoutS '0' must be at least 1. Nothing was changed. To remove
the limit instead, send null.` — rather than a `200` that stores something else. It used to
be the latter, and the four fields involved did four different things: clamped at both
ends, clamped at one, turned into `null`, or stored verbatim, all with `warnings: null`.

Two consequences worth knowing:

* **`null` (or a blank) is how you remove a limit, not `0`.** On `execTimeoutS`,
  `maxSessions` and `subagents.maxConcurrent`, `null` means "no project limit, use the
  deployment's" — so `0` used to be accepted and stored as the *loosest* setting, which is
  the opposite of what anyone typing it meant.
* **`capabilities.maxToolIterations` is the exception**, because its own documentation has
  always said so: `0` there means "no project limit" and reads back as `null`.

A key that is not in this table is rejected with a `400` naming it, rather than merged
and ignored. That matters most for fields that look like they belong here and don't:

| Field | Type | Where it actually goes |
|---|---|---|
| `doneWebhookUrl` | string | **top level**, beside `name` — not inside `capabilities` |

```bash
# right
curl -sX PATCH "$CP/api/projects/$ID" -H "X-API-Key: $KEY" \
  -d '{"doneWebhookUrl":"https://example.com/hooks/oberik"}'
```

`doneWebhookUrl` is not a capability: an end-user token cannot ask for less of it, so it
is a property of the project's behaviour rather than a permission a token carries. Read
it back from `GET /api/projects/:id`, which returns it alongside the other project
fields; `GET /api/projects/:id/capabilities` deliberately does not, because it answers
"what may a token do".

## Curate the corpus

Documents uploaded with the project key belong to the project rather than to any one
end-user, which is the shape most integrations want: you curate, your users ask.

```bash
curl -sX POST "$CP/api/projects/$OBERIK_PROJECT_ID/documents" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" \
  -F file=@handbook.pdf -F tags=policies

curl -s "$CP/api/projects/$OBERIK_PROJECT_ID/documents" -H "X-API-Key: $OBERIK_PROJECT_KEY"
curl -sX DELETE "$CP/api/projects/$OBERIK_PROJECT_ID/documents/$DOC_ID" -H "X-API-Key: $OBERIK_PROJECT_KEY"
```

The listing is a **page** — `{ items, has_more, next_offset }` — with the same `limit`
(default 100, max 500), `offset`, `tag` and `status_filter` the data plane takes, and
`with_total` for the census:

```ts
const page = await oberik.documents.list({ with_total: true });
page.total;      // how many documents this project holds
page.items;      // the first 100, newest first
```

`with_total` costs a second query, so it is for a summary rather than for paging — *"is
there another page"* is `has_more`, and that is free.

Pair this with `documentsMode: "read"` and your end-users can search the corpus and
never add to it. The full document surface — visibility, ACLs, chunk inspection,
re-ingestion — is on the data plane and covered in [Documents](./documents.md).

## The system prompt

```bash
curl -sX PUT "$CP/api/projects/$OBERIK_PROJECT_ID/system-prompt" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"systemPrompt":"You are Acme’s support agent. Never speculate about pricing."}'
```

Goes into every request for the project, first, marked authoritative. A caller's own
`system_prompt` is appended after it and told the project's wins — see
[System prompts](./chat.md#system-prompts). Send `""` to clear.

## Skills, webhook tools and MCP servers

```bash
# Publish a skill to everyone using this project: a packaged plugin, a zipped folder
# of skills, or a single SKILL.md — a manifest is written when there isn't one.
curl -sX POST "$CP/api/projects/$OBERIK_PROJECT_ID/skills" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -F file=@refunds.zip

# Publish a tool the agent calls by URL. The signing secret comes back once.
curl -sX POST "$CP/api/projects/$OBERIK_PROJECT_ID/webhook-tools" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"name":"cancel_order","description":"Cancel an order belonging to the signed-in customer.",
       "url":"https://acme.com/agent/orders",
       "parameters":{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}}'

# Attach an MCP server to the project's agent.
curl -sX POST "$CP/api/projects/$OBERIK_PROJECT_ID/mcp" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"name":"orders","url":"https://mcp.acme.com/sse","transport":"sse","headers":{"authorization":"Bearer …"}}'
```

All three are the project's own and apply to every end-user — though a webhook tool is
only bound to turns whose token carries `webhook_tools`, so publishing one and granting
it are separate decisions. See [Tools you host](./tools.md#tools-you-host-webhook-tools). An end-user uploading *their*
own skill is a different thing, needs `plugins:write`, and goes straight to the data
plane with their token — [Skills](./skills.md).

## Browser origins

Required before any browser calls the API with your tokens.

```bash
curl -sX PUT "$CP/api/projects/$OBERIK_PROJECT_ID/origins" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"origins":["https://app.acme.com","http://localhost:3000"]}'
```

Exact origins and single-level wildcards — [Calling from the browser](./browser-origins.md).
This REPLACES the list; clearing it removes the restriction entirely and takes
`"confirm": true` (`origins.set([], { confirm: true })` in the SDK).

## Models, retrieval and context

| Method | Path | Sets |
|---|---|---|
| `GET` | `/api/providers/catalog` | which providers exist and what credentials each needs |
| `GET` `POST` `DELETE` | `/api/projects/:id/providers[/:credId]` | your own LLM keys and the models they register |
| `POST` | `/api/projects/:id/providers/:credId/refresh` | re-read a provider's catalog and prices |
| `GET` `POST` | `/api/projects/:id/default-model` | which model is used when a request names none |
| `GET` `POST` | `/api/projects/:id/model-tiers` | route a request to one of three models by how much work it looks like |
| `PUT` | `/api/projects/:id/retrieval` | embedding and rerank model overrides |
| `PUT` | `/api/projects/:id/document-processor` | who does OCR: `auto`, a specific model, or `local` |
| `GET` | `/api/projects/:id/context` | how long conversations are kept in the window |
| `GET` | `/api/projects/:id/limits` | usage caps on the project's LLM key |

A model registered without a known price logs spend as zero, which means a usage cap
cannot trip on it — `refresh` is what fixes that.

**`providers catalog` says which credential fields each provider requires, and registering
one without them is refused.** Everything the catalog lists for a provider is required
unless it is marked `optional` — a self-hosted vLLM needs `api_base` and may have no key at
all, a hosted API is the other way round. The refusal names the field, its label and the
JSON shape that supplies it, and nothing is registered.

A credential stored *before* that check existed is a different thing and is not refusable
after the fact, so `readiness` raises it instead: its `provider` step reports the missing
field and the call that fixes it.

`readiness` also carries `health` and `healthDetail` — it is the route that computes their
inputs, so it is the route that answers the question directly.

**A base URL that cannot be reached is caught when you register it.** For a provider whose
endpoint you supply — a self-hosted vLLM, anything `custom` — the URL is asked for
`/models` once, at registration, and the answer is kept. A host that does not resolve makes
`provider` the blocking step, so `canAnswer` is `false` and `next` names the URL and the
call that corrects it, instead of sending you off to configure retrieval. Registration
still succeeds: an endpoint can be down now and up in an hour, and refusing would turn a
temporary outage into a permanent inability to configure. Correcting the URL asks again.

Only a **transport** failure counts — DNS, connect, TLS, a timeout. Any HTTP response at
all, including a `404` from a server with no `/models` and a `401` wanting a different key,
proves the host is there, which is the only question being asked.

:::caution What `readiness` does and does not ask

Every step except `rerank-model` and `provider` answers **"is this configured"**, not "can
it be reached", and those two ask at different moments. `rerank-model` is measured by
reranking with it, and re-measured whenever the credential behind it changes. `provider`
reads the verdict recorded when the credential was written — so an endpoint that worked at
registration and stopped afterwards is not noticed here; the first thing that fails is a
turn or an upload.

`chat-model` and `default-model` never ask. A model name that resolves to nothing passes
both, and `canAnswer` stays `true`.
:::

### One model per request, instead of one per project

A project registers several models and one of them is the default, so every request that
names no model gets the same one whatever it asks for: *"what time do you close?"* answered
by the model you bought for the hard questions. Pointing the default at something cheaper
fixes the bill and quietly degrades the work.

`model-tiers` lets the request pick:

```ts
await project.modelTiers.set({
  mode: "auto",
  simple: "gpt-5-mini",        // a short question with nothing asked for
  normal: "hukuk-db",          // everything else
  complex: "claude-opus-5",    // a file, the sandbox, delegates, several steps, a long brief
});
```

| | |
|---|---|
| **A request that names a model** | is never re-routed. The tiers answer "and if they didn't say?" |
| **A tier left empty** | falls back to the project's default model, so a half-configured project behaves exactly as before |
| **`mode: "off"`** (the default) | one default model, as it has always been |
| **A resumed turn** | stays on the model it started on. A tool result is a short message with nothing asked for, so re-sorting it would finish a hard turn on the cheap model |
| **The token's own limits** | apply unchanged: a routed model is checked against `allowed_models` and against what the project registered, exactly as a named one is |

**The sorting reads the request — it does not ask a model.** A classifier call in front of
every turn would cost latency on the fast path this exists to make fast, and spend money to
decide how much money to spend. So it reads what came with the request (a file, named
documents), what you switched on **on that request** (the sandbox, delegates, generated
media) and the shape of the message (its length, a numbered list, "then … then").
`enable_computer` and `enable_subagents` default to `true` — that is a permission, not a
request, and a turn that simply *may* use the sandbox is not sorted `complex` for it. It is wrong sometimes, and being
wrong means a neighbouring model answers rather than the turn failing. It errs upward on
purpose: a hard question on the cheap model is a bad answer somebody has to notice, and an
easy one on the strong model costs a fraction of a cent.

Every answer carries `model` and `model_tier`, which is how you tune it — without them a
routing mistake and a model being bad at something are indistinguishable, and there is no
way to notice that everything is being sorted `complex`.

:::caution Reading a setting and replacing one are different requests

`POST …/default-model` and `PUT …/limits` **replace** what is there. Sending a body with
no fields is refused rather than read as "clear it", and clearing something that is set
takes `"confirm": true` — because from a shell the natural way to look at a setting is to
type its command with no arguments, and for a while that deleted the thing you were looking
at. `GET …/default-model` and `GET …/limits` are the reads.

That is not hypothetical: a bug filed as "adding a provider does not store the default
model" turned out to be the reporter's own next command — a bare `default-model`, run to
check — wiping it and answering `{"defaultModel": null}`, which reads exactly like a getter
confirming the problem.

Four settings are guarded this way, and every one of them can be cleared from the SDK:

```ts
await project.origins.set([], { confirm: true });        // removes the origin restriction
await project.systemPrompt.set("", { confirm: true });   // deletes the project prompt
await project.defaultModel.set("", { confirm: true });   // every unnamed-model request then fails
await project.limits.set({ maxBudget: null, budgetDuration: null, confirm: true });  // uncaps spend
await project.capabilities.set({ allowedTools: null }, { confirm: true });  // every token reaches every tool
```

The API says what each would remove before it refuses, so a script that resets a project to
a known state reads the refusal rather than guessing.

:::

### Telling Oberik what a model can do

Most models are described by their provider's own catalog, or by the published model index.
A **self-hosted** one is described by nothing: `vllm serve --served-model-name hukuk-db`
reports an id no index carries, over a `/v1/models` that publishes no capabilities. So it is
recorded conservatively — text in, text out — and the project's `input:image` ceiling
follows from that. `GET /providers` marks such a model `"derivedFrom": "name"`, which is the
word for "nobody knew".

`modelFacts` is how you correct it, keyed by model name, and it can be sent on its own:

```bash
curl -sX PATCH "$CP/api/projects/$OBERIK_PROJECT_ID/providers/$CRED_ID" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"modelFacts":{"hukuk-db":{"input":["text","image"],"output":["text"],"mode":"chat"}}}'
```

```ts
await oberik.providers.update(credId, {
  modelFacts: { "hukuk-db": { input: ["text", "image"], output: ["text"], mode: "chat" } },
});
```

Nothing is re-registered — a deployment is created from a name and a price, and what a model
can read is metadata. `input` decides whether the agent may put a picture or a PDF in front
of it; `output` and `mode` decide which pickers offer it and which modalities the project may
grant. The dashboard asks the same question under **LLM & limits → the model's row**.

### Rotating a key

The same call replaces a credential, and it takes effect on the next turn:

```ts
await oberik.providers.update(credId, { values: { api_key: NEW_KEY } });
```

Every model on that credential is re-registered against the new value, because a model
deployment is built *from* the key and keeps its own copy of it — storing a new one without
rebuilding them would leave the platform using the key you just revoked. Your declared
`modelFacts` are carried across untouched: rotating a key is not a catalog re-read.

Re-reading the catalog is `providers.refresh(credId)`, and it is a different job — it asks
the provider what its models can do and what they now cost, which is worth doing when a
provider adds a modality or publishes a price. A model registered before its price was
published logs a spend of zero, so a refresh is also how a usage cap starts working.

**Name a model exactly as `GET /providers` lists it.** That is the form `/chat` accepts and
the form `default-model` stores, and for most providers it is what you would guess:
`openai/gpt-4o`, `anthropic/claude-sonnet-4.6`. For a **self-hosted** provider (vLLM,
LM Studio, an OpenAI-compatible gateway) it is the *served model name* on its own — the id
its `/v1/models` returns, e.g. `hukuk-db` — with **no provider prefix**. `vllm/hukuk-db`
looks right and is not a model: `default-model` refuses it with the list of what is
registered, and `/chat` refuses it the same way.

## Watch what it costs

```bash
curl -s "$CP/api/projects/$OBERIK_PROJECT_ID/usage"          -H "X-API-Key: $OBERIK_PROJECT_KEY"
curl -s "$CP/api/projects/$OBERIK_PROJECT_ID/observability?window=86400" -H "X-API-Key: $OBERIK_PROJECT_KEY"
```

`observability` returns spend, requests, tokens and p95 latency as time series, plus
per-model and **per-user** breakdowns — spend is attributed to the token's `subject`, so
this is where "which customer is this costing us" is answered.

Every billable call names an actor, including the ones you never asked for directly: the
retrieval embedding and the rerank behind an answer, the guardrail check, the history
summarisation, and the OCR and embeddings of a document are all billed to whoever caused
them. A call your backend makes with a project API key is attributed to the service
principal rather than to an end-user, because that is who made it. A `byUser` row with
`unattributed: true` is therefore a **bug on our side** — not a category of usage — and worth
reporting.

There are two spend figures and they answer different questions:

| Field | What it is | Use it for |
|---|---|---|
| `spendBilled` | cumulative charge from the LLM gateway's own billing record | invoicing, "what has this project cost" |
| `totals.spend` | metered spend over the requested `window` | trends, per-model and per-user attribution |

`spendBilled` is the figure spend caps are enforced against, and it is `null` — never `0` —
when the billing record could not be read. `spendBilledPeriod` says what it covers: `all
time`, or `per 30d` when the project has a reset window, because the gateway zeroes the
figure at each rollover.

Everything windowed reconciles: `totals` is the sum of its own series and the sum of either
breakdown, because all of them are derived from the same readings. The **last point of every
series is the bucket still filling** — `partialFrom` is its timestamp, and `stepSeconds` is
how wide a bucket is. It covers a period that has not finished, so it is lower than the ones
before it; draw it as in-progress rather than as a drop in usage.

Both endpoints carry `metricsAvailable`. When it is `false` the numbers are **unknown, not
zero** — the metrics backend could not be read — and `metricsError` says why. Two more
fields say when a window is incomplete rather than quiet: `metricsRestarts` counts
metrics-collector restarts (a deploy resets its in-process counters, losing up to one bucket
around each), and `metricsGaps` counts buckets where nothing could be read at all.
`spendBilled` and spend caps are unaffected by any of these, so a project can be over its
cap while the metered view reports nothing.

`GET /api/orgs/:orgId/costs` does the same across every project in an organization, but it
needs a **signed-in session** rather than a project key: a project key belongs to one
project, and an org-wide breakdown is by definition everyone else's numbers too.

## Sessions, tasks and sandboxes

| Method | Path | Returns |
|---|---|---|
| `GET` | `/api/projects/:id/sessions` | every chat session in the project |
| `GET` | `/api/projects/:id/sessions/:sessionId/messages` | one session's messages and tool calls |
| `GET` | `/api/projects/:id/tasks` | scheduled tasks and reminders |
| `GET` | `/api/projects/:id/wiki` | pages the agent has written |
| `DELETE` | `/api/projects/:id/wiki/:itemId` | remove a page or a memory |
| `GET` | `/api/projects/:id/sandboxes` | live sandboxes |
| `POST` | `/api/projects/:id/sandboxes/:sessionId/:action` | `pause`, `resume` or `delete` one |

These read across the whole project, unlike the data-plane equivalents, which are bounded
by the calling token's scope. That is the difference between an operator view and an
end-user's.

## Keys

```bash
curl -sX POST "$CP/api/projects/$OBERIK_PROJECT_ID/keys" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"name":"ci","scope":"mint"}'
# -> { "id": "…", "name": "ci", "scope": "mint", "prefix": "pk_ab12", "key": "pk_…" }
#    `key` is shown once and never again — only its hash is stored.
#    scope: "mint" (default) mints end-user tokens and reads the ceiling; "admin" is
#    everything on this page, including issuing keys and deleting the project.

curl -s        "$CP/api/projects/$OBERIK_PROJECT_ID/keys"        -H "X-API-Key: $OBERIK_PROJECT_KEY"
curl -sX DELETE "$CP/api/projects/$OBERIK_PROJECT_ID/keys/$KEY_ID" -H "X-API-Key: $OBERIK_PROJECT_KEY"
```

In the SDK those three are `keys.create(name, { scope })`, `keys.list()` and
**`keys.revoke(keyId)`** — the delete is named `revoke` rather than `delete`, so searching
the client for the endpoint's own word finds nothing.

## Creating the project itself

The routes above all authenticate with a project key, which leaves one question: where
the project and its first key come from. Both need a signed-in *account* rather than a
key — but that does not mean a browser. The [SSH interface](./ssh.md) is the same control
plane as text:

```bash
ssh ssh.oberik.com 'login link'          # prints a URL; a person approves it once
ssh ssh.oberik.com 'login wait'          # blocks until they do
ssh ssh.oberik.com 'org new "Acme"'
ssh ssh.oberik.com 'project new "Support Bot"'
ssh ssh.oberik.com 'project use "Support Bot"; key new ci'    # pk_… shown once
```

One human approval, once — which is the right amount of consent for handing something an
account — and after that the SSH key is registered, so the same commands run unattended
from CI.

## Deleting a project

A project is an isolated tenant, so deleting one is a data-deletion: its documents, agent
knowledge, conversations, uploaded files, sandboxes and scheduled tasks are erased on the
data plane, and its API keys, provider credentials and LLM access go with it. Every token
minted for it stops working. There is no undo and no export.

**The project's name is the confirmation, and it is required.** The risk here is deleting
the *wrong* project, and `confirm=true` cannot tell you which one you are on — a flag is
something a client sends by default, while a name is something it has to have been told. So
the name answers *which*, and it is the part that makes this safe; `confirm=true` answers
*whether*, and it is there because every gated delete takes it and an exception is how a
rule stops holding.

```bash
curl -sX DELETE "$CP/api/projects/$ID?name=Support%20Bot&confirm=true" -H "X-API-Key: $KEY"
# -> { "id":"…", "name":"Support Bot",
#      "rowsDeleted": { "project_keys":2, "provider_credentials":1, "projects":1 },
#      "dataPlane": { "rows_deleted": { "documents":41, "chat_sessions":12 },
#                     "sandboxes_destroyed":1, "schedules_cancelled":2,
#                     "vectors_purged":1204, "objects_deleted":57 } }
```

A name that does not match answers `400` and deletes nothing. The response says what the
erasure actually reached — a `null` under `dataPlane` means that store could not be
reached, and if the tenant erase fails the request fails with `502` and the project is
left intact, because a project row deleted while its tenant survives would leave the
customer's data unreachable forever.

Needs an **admin** key (a mint key is refused), or a signed-in owner/admin of the
organization. From the dashboard it is *Overview → Danger zone*; over SSH it is
`project rm "<name>"`.

## A project as code

Applying a known configuration on deploy, rather than remembering which toggles were set:

```ts title="scripts/configure-oberik.ts"
import { readFile } from "node:fs/promises";

const CP = "https://oberik.com";
const id = process.env.OBERIK_PROJECT_ID!;
const headers = {
  "X-API-Key": process.env.OBERIK_PROJECT_KEY!,
  "content-type": "application/json",
};

const put = (path: string, body: unknown, method = "PUT") =>
  fetch(`${CP}/api/projects/${id}${path}`, { method, headers, body: JSON.stringify(body) })
    .then(async (r) => (r.ok ? r.json() : Promise.reject(new Error(`${path}: ${r.status} ${await r.text()}`))));

await put("", {
  capabilities: {
    allowChat: true,
    allowDocuments: true,
    documentsMode: "read",        // we curate the corpus; users only read it
    allowTodo: true,
    allowApprovals: true,         // stop before anything irreversible
    allowAskUser: false,          // no human on the other end of our batch jobs
    outputModalities: ["file"],   // it may hand back documents it writes
  },
}, "PATCH");

await put("/system-prompt", { systemPrompt: await readFile("prompts/support.md", "utf8") });
await put("/origins", { origins: ["https://app.acme.com"] });

console.log("configured");
```

Re-running this is safe: the capability patch merges, and the other two set a value
rather than appending to one.

---

## Chat & citations


One call runs the whole turn: the agent retrieves, calls tools, and answers. You choose
blocking or streaming.

## Blocking

```ts
const res = await ai.chat.send({
  message: "How did Q3 revenue trend?",
  tags: ["finance"],
});
```

| Field | What it holds |
|---|---|
| `session_id` | pass it back to continue the conversation |
| `content` | the answer |
| `citations` | everything the turn was shown that a sentence can point at, numbered — `{ marker, kind, title, quote, url, used }` and the extras for its kind |
| `attachments` | non-text outputs: generated media, files exported from a sandbox |
| `guard_flags` | guardrails that acted this turn (`[]` normally) |
| `requires_action` / `tool_calls` | the agent is waiting on **your** tools — see [Tools](./tools.md) |
| `finish_reason` | `null` normally; see [Limits & errors](./limits-and-errors.md) |

## Streaming

Streaming is Server-Sent Events over plain `fetch` — no WebSocket, no proxy.

```ts
const handle = ai.chat.stream(
  { message: input, tags: ["finance"] },
  {
    onToken: (delta, full) => render(full),
    onCitations: (cs) => showSources(cs),
    onToolStart: (name) => setStatus(`Running ${name}…`),
    onAttachments: (files) => offerDownloads(files),
  },
);

const done = await handle.done;   // the terminal payload
```

The handle is itself awaitable, and gives you `disconnect()` (stop listening, generation
continues), `cancel()` (stop server-side generation too, which stops model spend), and
`runId()`.

`runId()` returns `null` until the server's first frame arrives, so reading it on the line
after `stream()` logs `null`. Read it inside a handler, or after awaiting:

```ts
const handle = ai.chat.stream({ message }, { onEvent: () => log(handle.runId()) });
await handle.done;
handle.runId();                    // always set by here
```

### Events

Every frame the server can send, and the handler it reaches. `onEvent` receives all of
them, typed, if you'd rather switch on it yourself — which is also what you'd implement
against if you're writing a client in another language.

| Event | Payload | Handler |
|---|---|---|
| `run` | `{ run_id }` | — (also on the `X-Run-Id` header) |
| `start` | `{ session_id }` | `onEvent` |
| `token` | `{ delta }` | `onToken(delta, full)` |
| `reasoning` | `{ delta }` | `onReasoning(delta, full)` — arrives before and between `token` frames |
| `tool_start` / `tool_end` | `{ name, input }` / `{ name, output }` | `onToolStart` / `onToolEnd` |
| `command_output` | `{ command_id, command, stream, delta }` | `onCommandOutput` — a [sandbox](./sandbox.md#long-commands) command's output *while* it runs |
| `command_finished` | `{ job_id, command, exit_code, status }` | `onCommandFinished` — a background command reported back at a step boundary |
| `citations` | `{ citations }` | `onCitations` |
| `attachments` | `{ attachments }` | `onAttachments` — every file so far, not just the new one |
| `todos` | `{ todos }` | `onTodos` — the [plan](./working-together.md#todos--the-agents-plan), as it's written and ticked off |
| `title` | `{ title }` | `onTitle` — the conversation was just [named](./working-together.md#naming-a-conversation), mid-turn by default |
| `subagent` / `subagents` | one [subagent](./subagents.md) / all of them | `onSubagents` (both frames) |
| `questions` | `{ questions }` | `onQuestions` to render, `onQuestion` to answer and resume — the turn is [paused](./working-together.md#questions-the-agent-asks) until you do |
| `approvals` | `{ approvals }` | `onApproval` — [nothing proceeds](./working-together.md#asking-permission) until you decide |
| `ui` | a [component render](./tools.md#ui-components--tools-that-draw) | `onUi` |
| `browser_handoff` | a [hand-off](./tools.md#handing-the-page-to-the-user) | `onBrowserHandoff` |
| `context` | progress, then a report | `onContext` — [compaction](./context.md), which happens before the turn produces anything |
| `guardrail` | `{ stage, flags, reason?, content? }` | `onGuardrail(stage, flags, content)` — **three positional arguments**, not the frame object |
| `done` | the terminal payload | resolves `handle.done` |
| `cancelled` / `error` | `{ run_id }` / `{ detail, code?, run_id?, session_id? }` | rejects `handle.done` |

Frames that are only a comment (`: keepalive`) are not events. The server sends one every
15 seconds while a turn is thinking rather than talking — a reasoning model can go minutes
between frames, and to anything with an idle read timeout that is indistinguishable from a
dead connection. The SDK drops them; a client you write yourself should too.

Three of these mean **the turn has stopped and is waiting on you**: `questions`,
`approvals` and `browser_handoff`. All three also come back on the blocking `/chat`
response with `requires_action`, and all three arrive with an **empty `tool_calls`** —
a question is not work for your client to run, so tool auto-dispatch can never answer
one by accident.

The `done` payload carries the final state of everything above (`content`, `citations`,
`attachments`, `todos`, `subagents`, `questions`, `approvals`, `ui`,
`handoff`, `guard_flags`, `context`, `reasoning`, `finish_reason`), so a client that
ignored the incremental frames still ends up with the whole turn.

### Dropped connections resume

Generation runs independently of your connection. Every frame carries an id and the
response carries `X-Run-Id`, so the SDK reconnects to the same run and replays what you
missed — a closed laptop lid mid-answer doesn't lose the answer, and doesn't pay for it
twice. `onReconnect(attempt)` fires each time it re-attaches; `maxRetries` defaults to 10.

Because generation is decoupled, `disconnect()` then reconnecting later is a legitimate
pattern, and `cancel()` is what you call when the user really means stop.

### What cancel guarantees

`cancel()` stops generation, and the request it stopped is **not carried out later**. That
second half is worth stating because the alternative is a real hazard: the cancelled turn's
message stays in the conversation (the user typed it; the transcript should show it), and a
message nothing has answered reads to a model as work still outstanding. So a cancelled
"close every berth for July", followed a minute later by "what time is it?", used to get
both. It is now marked unanswered at the start of the next turn and never replayed — it
stays visible in `sessions/{id}/messages` with `extra.turn_abandoned: true`, and the model
does not see it.

The same applies to a turn that ended without an answer for any other reason — the
provider hung up, the server was replaced mid-turn. Nothing was answered, so nothing is
resumed; send it again if you still want it.

One thing cancel cannot do: stop a **blocking** `chat.send()`. It holds no resumable run to
cancel, and closing the HTTP request does not stop generation either, so
`/chat/stream/{run_id}/cancel` answers 409 rather than reporting a turn stopped that is
still spending. Use `chat.stream()` for anything a user may want to stop.

### How long a run lasts

Worth knowing exactly, because a turn that thinks for minutes is a turn where this
matters:

| | |
|---|---|
| **while generating** | as long as the turn takes. No ceiling — an eighteen-minute turn is resumable for eighteen minutes. |
| **after it finishes** | its frames stay replayable for **10 minutes**, so a reconnect a moment late still replays the whole turn. Eviction is lazy, so a quiet deployment sometimes keeps them longer — treat 10 minutes as the guarantee, not the limit. |
| **a restart of the API process** | ends every run it held. That is a deploy, a crash, or an OOM. |

The frames are what expires; the run is not. A reconnect to a run whose frames are gone
answers **200 with one terminal `error` frame** — not a 404 — and that frame names the
conversation.

**A run id is not a capability.** Attaching, steering and cancelling all check the same
per-subject ACL that `sessions.messages` checks, on the same conversation — so a token that
could not read the transcript cannot read the stream, cannot steer a message into the turn,
and cannot stop it, whatever run id it holds. Steer and cancel are checked as *writes*, so a
conversation another user may read is still not one they may interrupt. This matters because
run ids travel: a 409 for a racing turn names the run in flight, resume errors quote one, and
anything that logs them puts them somewhere else.

A `404` on a reconnect means one of two things and says so without distinguishing them:
nobody has a record of that run id, or it belongs to a conversation this token may not read
(the same 404-not-403 rule as everywhere else — probing ids must reveal nothing). It will
never tell you the *session* is gone, because on a resume that would be the one wrong thing
to say: the answer is usually sitting in the transcript. `handle.done` rejects with an `AgentStreamError` carrying the details:

```ts
try {
  await ai.chat.attach(runId, { onToken: render });
} catch (e) {
  if (e instanceof AgentStreamError) {
    e.code;       // "stream_expired" | "stream_lost" | "stream_elsewhere" | ...
    e.sessionId;  // which conversation — set from the turn's FIRST frame
    e.content;    // the text that had streamed. Render it; the user watched it arrive
  }
}
```

| `code` | What happened | What to do |
|---|---|---|
| `stream_expired` | the turn finished; its frames aged out | `sessions.messages(e.sessionId)` — the answer is there |
| `stream_lost` | the process generating it restarted, so it never finished | send the turn again |
| `stream_cancelled` / `stream_failed` | cancelled, or failed | `e.message` carries the server's own words |
| `stream_elsewhere` | recorded as running, but not on the worker that answered | retry; do not resend |

`sessionId` is the point of all this. It used to be the thing a broken stream took with
it: on a **first** turn the conversation is created inside the turn, so the stream is the
only place its id has ever appeared — and a 404 on the reconnect left a finished answer
sitting in a conversation the client could not name. It is now on the handle from the
`start` frame onward, before the first token:

```ts
const handle = ai.chat.stream({ message: "..." }, { onToken: render });
handle.sessionId();   // known from the first frame, not just from `done`
```

A `runId` nothing has any record of is still a 404. That one really is a bad id.

### Re-attaching after a page reload

The paragraph above covers a dropped socket, which the handle recovers by itself. It does
**not** cover a reload: a new page has no handle, and the assistant's reply is not stored
until the turn ends — so `sessions.messages` returns the question and an empty answer while
generation is still going.

Ask the session what is running on it, and attach:

```ts
const { run_id, last_event_id } = await ai.chat.sessions.activeRun(sessionId);
if (run_id) {
  const handle = ai.chat.attach(run_id, { onToken: (_d, full) => render(full) });
  const done = await handle.done;
}
```

`run_id` is null when nothing is running, and `status` says what that null means: `idle`
(the last turn ended normally), `lost` (a turn *was* generating and the process running it
went away — nothing was persisted, so send it again), `elsewhere` (running, but not on the
worker that answered — retry), or `running` alongside a `run_id`. `lost` was previously
indistinguishable from `idle`, which is how a ten-minute answer became a blank bubble
nobody thought to retry.

`authoritative` says whether that null is the whole truth. A run lives in the memory of
the API process that started it, so a deployment running several workers can only answer
for the one that took your request; `authoritative: false` means "no run **here**, possibly
one elsewhere". It is true on a single-worker deployment, which is the common one. `attach` gives you
the same `StreamHandle` — `cancel`, `steer`, `disconnect` and `done` all work as if this
client had started the turn — and replays from the beginning by default, which is what a
fresh page wants; pass `{ lastEventId }` to receive only what you have not rendered.

You do not have to persist the run id for this. That matters: a client that keeps it in
memory loses it on the reload, and one that keeps it in storage still cannot help a user
who opens the same conversation on another device.

:::note Two limits worth knowing
Client tools are not auto-executed on a re-attached stream — this client did not start the
turn, so a pause arrives as a `done` with `requires_action` and you answer it with
`chat.send({ session_id, tool_results })`.

And a run lives in the memory of the API process that started it, so `activeRun` answers
for that process — check `authoritative` before treating a null as "the turn finished".
This is the same constraint the underlying resume endpoint has always had, and it is why a
run id is not a durable handle. If you scale the API out, route by run id (or pin a
session to a worker) so re-attachment keeps working.
:::

## Reasoning models

A reasoning model thinks before it answers, and that phase can take a while. Its thinking
streams on its own channel, so the wait is visible instead of looking like a hang:

```ts
ai.chat.stream({ message, model: "openai/o4-mini", reasoning_effort: "medium" }, {
  onReasoning: (_delta, full) => showThinking(full),   // or just setStatus("Thinking…")
  onToken: (_delta, full) => render(full),
});
```

`reasoning` frames arrive before — and between — `token` frames. Two ways to use them:
render the trace as it streams, or ignore the content and treat the first frame as your
"thinking" indicator. Either way you have something to show during a phase that would
otherwise be silent.

Blocking callers get the whole trace at once:

```ts
const res = await ai.chat.send({ message, reasoning_effort: "high" });
res.reasoning;   // the thinking, or "" for a non-reasoning model
res.content;     // the answer — thinking never leaks into this
```

`reasoning_effort` is `minimal | low | medium | high`, clamped to the token's ceiling and
dropped for models that don't support it — including a model that takes the parameter but
not the *value*, since the vocabulary is the provider's (a model offering
`xhigh | medium | low` refuses `minimal`). The turn is answered without it rather than
failing, so a token minted with `maxEffort: "minimal"` is a cheaper tier and never a broken
one. Thinking is **not stored**: it won't appear in
session history, and it is never sent back to the model on a later turn (providers don't
accept their own thinking back, and it would cost context for nothing). Persist it
yourself if you need an audit trail.

## Grounding

**Everything the turn was shown is numbered, whatever it came from.** A document passage, a
web result, a page the agent opened, something it remembered, a wiki page, a result from one
of your own systems, a port it exposed — one list, one sequence of numbers, and the agent
closes a grounded sentence with the number it used:

```ts
res.content;      // "There are 5 free days at destination [2]."
res.claims;       // [{ text: "There are 5 free days…", start, end, citations: [2] }]
res.citations[1]; // { marker: 2, kind: "document", title, quote, used: true, page, score }
res.attribution;  // "per-claim" | "retrieval-only" | "none"
```

`kind` is `document · web · memory · wiki · tool · preview · file`. Render `title`, `quote`
and `url`; branch on `kind` only for the extras you want — a page number for a document, the
tool's name for a result, "you told me this" for a memory, the path for a `file`.

`kind` describes the **evidence, not the tool**: a page the agent fetched with `browse_url`
and one it drove to with the browser are both `web`, because what the reader checks is the
same URL either way.

### What is citable, and what is not

The rule is the one this page opened with — a citation is something anyone can go and check —
applied literally:

| | |
|---|---|
| a file the agent read in its sandbox | `kind: "file"`, `title` is the path. Citable: you can ask for that file, and the agent can send it |
| a page it browsed or fetched | `kind: "web"`, with the URL |
| **command output** | **not citable.** It is gone once it scrolls past, so there is nothing for a reader to look at — and a twenty-step loop would bury the register in noise |

If a computation matters, the agent is told to write it to a file and read the file back —
which makes it citable under the first rule rather than needing a special case. This matters
for the answers that are most worth checking: an audit whose number comes out of arithmetic
done in a sandbox can now point at the file it computed from, where before it could only
say "according to /workspace/fact.txt" in prose. A parenthetical and a pill look the same to
a reader and only one of them is checkable.

This used to be two arrays and only one of them could be footnoted: `citations` held
document passages, and everything else went to a `sources` list no claim could point at. So
an answer built on a web page, on your MCP server, or on what the user told you last week
came back with `attribution: "none"` and nothing a reader could follow — on a product whose
pitch is an agent that does all four. There is one array now.

`claims` is what answers *"where did that sentence come from"*, and `used` says which of
the register did any work. **Check `attribution`**: `retrieval-only` means the model
attributed nothing this turn, so you have what was looked at and no per-sentence mapping,
which is a different thing to draw.

### Rendering the pills

`renderCited` gives you the answer already split into the segments a pill sits at the end
of, so you are not doing offset arithmetic:

```tsx
import { renderCited } from "@oberik/sdk";

{renderCited(res).map((seg, i) => (
  <span key={i}>
    {seg.text}
    {seg.citations.map((c) => <Pill key={c.marker} citation={c} />)}
  </span>
))}
```

Every segment comes back in order, attributed or not, and concatenating `text` reproduces
`content` exactly — so an unattributed answer is one segment with no pills and needs no
special case. A marker the model invented resolves to nothing and is dropped rather than
rendered as a pill the reader would click.

To keep `[2]` out of the visible prose and place footnotes yourself from
`claims[].start`/`end`:

```bash
curl -sX PUT "$CP/api/projects/$OBERIK_PROJECT_ID/citations" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
  -d '{"markers":"stripped"}'
```

Every entry carries a `title` and a `quote`, so your UI can show the reader what to check.
Scope a turn to a subset of the project's data:

```ts
await ai.chat.send({
  message: "What's our refund policy?",
  tags: ["policies"],            // only documents with these tags
  // document_ids: ["…"],        // or exactly these documents
});
```

Scoping this way also keeps the turn on your data: web search is switched off automatically
when a request names `tags` or `document_ids`.

## Choosing what the agent may do this turn

Every capability the token grants can be declined per request — useful for a cheap
"just answer" path, or a user-facing toggle.

```ts
await ai.chat.send({
  message,
  enable_web_search: false,        // don't leave our data
  enable_computer: false,          // no sandbox this turn
  allowed_tools: ["rag_search"],   // exactly one tool
});
```

The effective set is always **project ceiling ∩ token capabilities ∩ this request**. Naming
a tool the token doesn't carry never grants it.

Every switch, all defaulting to `true`:

`enable_rag` · `enable_memory` · `enable_web_search` ·
`enable_browser` · `enable_todo` · `enable_computer` · `enable_subagents` ·
`enable_scheduling` · `enable_ask_user` · `enable_approvals` · `enable_plugins` ·
`enable_action_space`

Two of them are worth turning **off** deliberately rather than leaving on:
`enable_ask_user` and `enable_approvals` stop a turn dead until a person answers, which
is right in a chat window and wrong in a batch job, a webhook or a scheduled run — where
nobody is watching and the turn simply waits forever. Scheduled tasks never bind them
for exactly this reason.

The capability each switch corresponds to is in the
[capability table](./authentication.md#capabilities).

## Models

Omit `model` and the project default applies. Pass one to override, bounded by the token's
allow-list:

```ts
await ai.chat.send({ message, model: "openai/gpt-4o", reasoning_effort: "low" });
```

`reasoning_effort` is `minimal | low | medium | high`, clamped to the token's ceiling and
dropped for models that don't support it — including a model that takes the parameter but
not the *value*, since the vocabulary is the provider's (a model offering
`xhigh | medium | low` refuses `minimal`). The turn is answered without it rather than
failing, so a token minted with `maxEffort: "minimal"` is a cheaper tier and never a broken
one. `temperature` defaults to `0.2`.

## System prompts

Two can apply, and they don't have equal standing.

**The project's** (dashboard → Capabilities → *System prompt*) goes into every request for
that project, first, under a heading marking it authoritative. It's where the persona, tone
and refusal rules belong.

**Yours, per request**, is additive and needs the `system_prompt` capability:

```ts
await ai.chat.send({ message, system_prompt: "Answer in British English." });
```

Without that capability the request is refused with **403** rather than having the prompt
quietly dropped — a token that can't set one may send user messages only. It's appended
after the project's, labelled as additional, with an explicit instruction that the project's
wins on a conflict.

Worth being straight about the limit: ordering and labelling is instruction, not
enforcement — a model can still be talked around. Anything that must *hold* belongs in a
capability, an `allowed_tools` list or a [guardrail](./guardrails.md), which is why the
capability gate exists rather than trusting the wording.

## Sessions

Pass `session_id` to continue. History includes images from earlier turns, so
"make that chart green instead" works without re-sending anything.

```ts
const first = await ai.chat.send({ message: "Draft a summary" });
await ai.chat.send({ session_id: first.session_id, message: "Shorter, and mention EMEA." });
```

```ts
const page = await ai.chat.sessions.list(userRef);   // userRef is your own label, optional
page.items;        // the conversations
page.has_more;     // is there another page?
page.next_offset;  // pass as `offset` to get it — null when this is the last

await ai.chat.sessions.messages(sessionId);     // full transcript
await ai.chat.sessions.fork(sessionId, { upToMessageId });   // branch a conversation
await ai.chat.sessions.delete(sessionId);
```

`list` is a **page**, not the set: the default limit is 100 and the cap is 500. It used to
return a bare array, so a project with 137 conversations answered with 100 rows and nothing
saying so — indistinguishable from a project that has exactly 100. Read `has_more`, and
page with `next_offset` rather than your own arithmetic (`limit` is clamped server-side, so
`offset + yourLimit` can be wrong).

Forking is how you build "edit this message and try again" without destroying the original
thread. Sessions are owned by the token's subject: one end-user can never list another's.

## While a turn is running

A long turn is not a closed door. With the `steer` capability a user can send a message
**into** it and the agent picks it up at its next step, and several messages typed while
it works can be sent together as separate messages with one reply. Once it ends, you can
offer suggested follow-ups and — for someone coming back later — a one-line recap.

All of that is [Working with the user](./working-together.md), along with the plans the
agent keeps and the questions it can ask.

**One conversation runs one turn at a time.** Starting a second while the first is still
generating answers `409`, naming the run in flight:

```
409 a turn is already running on this conversation (run 9f3c…). Starting a second one
    would interleave the two in the transcript, and nothing stored says which answer
    belongs to which question. Attach to it with GET /chat/stream/9f3c… …
```

That is almost always what the second caller wanted anyway — a retry, a second tab, a phone
resuming while the desktop submits. Attach to the run and you get the answer that is already
being written; start a second turn and the stored conversation stops alternating (`user`,
`user`, `assistant`, `assistant`), nothing pairs an answer with its question, and every later
turn replays a transcript some providers refuse. To add something *to* a turn in flight, use
`steer`.

**A turn that ended does not wedge its conversation, however it ended.** One that failed at
the provider — a rotated key, a rate limit, a model outage — is finished, and the next turn
proceeds normally; one whose process died is reported as `lost` rather than running. And
`GET /chat/sessions/{id}/run` answers from the same place this `409` does, so if it says
`idle`, posting will not be refused. (It did not always: a turn that failed at the provider
reported the failure and then left its conversation refusing every later turn, while `/run`
reported that same conversation idle. Two doors, opposite answers — OBE-115.)

Very long conversations eventually outgrow the model's window; what happens then is
[Context management](./context.md), and it is a project setting rather than something
each request decides.

---

## Documents


Upload a file and it becomes searchable for the users you allow. Parsing is layout-aware, so
tables and headings survive, and each PDF page is checked for a text layer — so only the
pages that actually need OCR are sent anywhere.

## Upload

```ts
const doc = await ai.documents.uploadAndWait(file, {
  filename: "q3-report.pdf",
  contentType: "application/pdf",
  tags: ["finance", "q3"],
  visibility: "shared",              // set the ACL here, not afterwards
  visibility_scope: "acme:finance",
});

doc.status;       // "ready" — searchable now ("failed" carries `error`)
doc.chunk_count;
doc.visibility;   // reads back what you set
```

Set visibility **at upload**. A document becomes retrievable the moment ingestion
finishes, so patching it afterwards leaves a window where more people could read it than
you intended.

Ingestion is asynchronous, so a just-uploaded document isn't retrievable yet.
`uploadAndWait` polls until it is. The pieces are also available separately:

```ts
const doc = await ai.documents.uploadSimple(file, { filename, tags });   // small files
await ai.documents.waitReady(doc.id, { timeoutMs: 120_000 });
```

For large files use the resumable presigned upload, which goes **straight to storage** —
the bytes never transit your backend, and an interrupted upload resumes per part:

```ts
await ai.documents.upload(file, {
  filename: "10gb-export.csv",
  visibility: "private",
  onProgress: (sent, total) => setPct(sent / total),
});
```

## A corpus you curate, that users only read

The most common shape: you upload the documents, your end-users ask questions of them and
never upload anything themselves. Three settings:

1. **Capabilities → Document access → Read only.** Minted tokens then never carry
   `documents:write`, so a user cannot upload however your backend mints them — it's a
   project-level guarantee, not something every mint call has to remember.
2. **Upload with your project key**, which stores them `tenant`-visible by default —
   readable by every end-user of the project. Pass `visibility` to narrow that.
3. **Restrict the tools** (`allowed_tools: ["rag_search"]`, and don't grant `web_search`)
   if answers must come from your corpus and nowhere else.

```ts
// your backend, with the project key — a different client from the one your app uses
import { createProjectClient } from "@oberik/sdk";

const oberik = createProjectClient({ projectId, projectKey: process.env.OBERIK_PROJECT_KEY! });
await oberik.documents.upload(file, { filename, tags: ["handbook"] });          // tenant-wide

await oberik.documents.upload(salaries, {                                       // narrower
  filename: "salary-bands.xlsx",
  visibility: "groups",
  acl_roles: ["finance"],
});
```

`visibility` takes the same values here as it does on an end-user upload, and the table
below is the whole vocabulary. A project key authenticates as the subject `service`, so
`private` means that principal plus admins and `self` means that principal alone — both
are coherent, and both are narrower than `tenant`.

What a project key cannot do is upload *as one of your users*: the owner recorded is
`service`, not them. A document that belongs to a particular end-user goes through the
**data-plane** client with that user's token (`ai.documents.uploadAndWait`), where the
subject is the owner.

Note this interacts with [memory](./scheduling.md#memory): a project-wide corpus is the
one case where a *shared* agent wiki is safe.

## Visibility

Who may retrieve a document is set per document and enforced on every search.

| `visibility` | Retrievable by |
|---|---|
| `self` | only the exact uploader — not even admins |
| `private` | the owner, admins, and tokens scoped above the owner |
| `shared` | anyone under `visibility_scope` (e.g. a team path) |
| `groups` | anyone whose token carries a matching `acl_group` |
| `tenant` | everyone in the project |

`acl_roles` / `acl_groups` are matched against the token's `roles` / `groups`.

:::info `self` is also unlistable, so an operator's totals exclude it

The row above is about *retrieval*, and the same rule applies to listing: a `self` document
does not appear in `documents.list` for anybody but its uploader, and `documents.get`
answers `404`. So a project key's own count of the corpus is short by however many there
are.

That number is available without weakening the guarantee. `with_total` answers `hidden`
alongside `total` for an admin or a project key — how many documents exist that the caller
may not list:

```ts
const page = await project.documents.list({ with_total: true });
page.total;   // what you can see
page.hidden;  // how many you cannot, and nothing else about them
```

A count is not a read: it names no filename, no owner and no text. It is `null` for an
end-user token, because to a reader the same number would say how many private documents
other people have.
:::

```ts
await ai.documents.update(doc.id, {
  visibility: "shared",
  visibility_scope: "acme:finance",
  tags: ["finance", "q3", "reviewed"],
});
```

Retrieval applies the same rules, so a user cannot get an answer grounded in a document they
aren't allowed to read — the model never sees it in the first place.

## How a file is read

You don't choose this per file, and you shouldn't have to. Each file is read the way that
file can be read — and for a PDF, that decision is made **per page**:

| File | How it is read |
|---|---|
| `.pdf` page with a text layer | Extracted locally, about 150ms, no cost. Reports `text-layer`. |
| `.pdf` page without one | Sent to your OCR engine, one page at a time. |
| A mixed `.pdf` | Both. A 200-page report with two scanned exhibits costs two pages of OCR, not 200. |
| `.png`, `.jpg`, `.tiff`, … | Straight to OCR. There is no text layer in a bitmap to look for. |
| `.docx`, `.pptx`, `.xlsx`, `.odt`, … | Converted to PDF to ask the same question. If no page needs OCR the **original** is parsed natively, which keeps structure a round trip through PDF would flatten. If a page does, the converted PDF goes through the ladder above — which is what makes a `.docx` of photographed pages readable. |
| `.txt`, `.md`, `.csv`, `.html`, … | Parsed directly. There is no OCR question for a text file. |

### Who does the OCR

One setting, under **LLM & limits → Document processing**:

```ts
// The PROJECT client — this is your setting, not your end-user's.
await oberik.documentProcessor.set({ ocr: "auto" });                        // the default
await oberik.documentProcessor.set({ ocr: "model", ocrModel: "gpt-4o" });   // a specific one
await oberik.documentProcessor.set({ ocr: "local" });                       // never leaves us
```

- **`auto`** uses your project's default model when it can be handed a page, and local OCR
  when it cannot. Register a vision model and good OCR is the default.
- **`model`** pins a specific vision/OCR model, called with your own key. Saving a model
  whose registered inputs don't include an image or a file is refused here rather than
  failing on every later upload.
- **`local`** never sends a page to a model. Lower quality on hard scans, and a guarantee.

Local OCR reports itself as `local-ocr` in `read_with` — so a project on
`auto` can tell at a glance whether a document went to a model or was read on our machines.

`ocrComplexPages` additionally sends pages that *do* have a text layer but a flattening
layout — tables, multi-column — to the model, at one call per such page. Off by default, and
ignored unless the resolved engine is a model: local OCR reads a table worse than local
extraction does.

### What it tells you afterwards

Every document reports which engine actually read it, which is the answer to both "why did
this come back empty" and "why did ingesting these cost what it did":

```ts
const doc = await ai.documents.get(id);
doc.read_with;       // ["text-layer", "gpt-4o"] — local for most pages, the model for scans
doc.pdf_type;        // "text_based" | "scanned" | "image_based" | "mixed" | null
doc.ocr_page_count;  // 2 — what OCR was billed for
```

`read_with` names **what happened**, not what we run:

| | |
|---|---|
| `text-layer` | the PDF's own text, extracted here. Free. |
| `document-parser` | a non-PDF format parsed natively. Free. |
| `local-ocr` | OCR on our machines. No model call, no cost. |
| anything else | **a model name** — the one you registered, and the line on your bill. |

On `auto` this is the only place you can see whether your scans went to a model or to local
OCR. A file nothing could read comes back `failed` with a reason, never `ready` with
`chunk_count: 0`.

A `failed` document reports these three as well, and they mean the same thing there: a page
sent to OCR that came back empty is still a page you were billed for. They are read off the
same record the error sentence is written from, so the two always agree.

## Every field on a document

`documents.get` and each row of `documents.list` carry all of these. They are listed
together because a field that is on the wire and named nowhere can only be found by
printing an object and then guessed at — which is not a way to learn an API.

| field | what it is |
|---|---|
| `id` | the document. Stable across `update` and `reingest`; a re-upload is a **different** document. |
| `filename` | the name it is stored under. A label, not a key — see the duplicate note below. |
| `content_type` | what the upload declared, or what was sniffed from the bytes. Null when neither could say. |
| `tags` | how a curated corpus is scoped: `retrieve({tags})` and `chat({tags})` read this. |
| `owner_subject` | the end-user who uploaded it. A project-key upload is owned by the project. |
| `visibility` · `visibility_scope` · `acl_roles` · `acl_groups` | who may retrieve it — see [Visibility](#visibility). |
| `status` | `pending` → `processing` → `ready` \| `failed`. Only `ready` is searchable. |
| `chunk_count` | how many pieces are in the index. Never `0` on a `ready` document. |
| `error` | the sentence to show a person, when it failed. |
| `failure` | the same failure as one word for your code to branch on — `usage_cap`, `rate_limit`, `unsupported_type`, `unreadable`, `embedding`, `vector_store`, `storage`, `unknown`. |
| `embedding_model` | **which model's vectors this document is in.** A document embedded by an older model lives in its own collection; this is how you tell which ones a `reingest` still owes. |
| `pipeline_version` | the reader and embedder that produced the current vectors, as one string. Same use: it tells you what is stale after you change the project's settings. |
| `content_hash` | SHA-256 of the bytes as uploaded. **This is what you check to find a duplicate before uploading one**, rather than reading `duplicate_of` afterwards. Null until ingestion has read the file. |
| `duplicate_of` | the oldest document with the same `content_hash`, or null — see the note below. |
| `read_with` · `pdf_type` · `ocr_page_count` | how it was read and what OCR cost — the table above. |
| `created_at` | when the row was made, which is when the upload was accepted rather than when it finished indexing. |

## Retrieval

Usually you don't call retrieval: `chat` does it and returns citations. Call it directly when
you want the chunks themselves — to build your own UI, or feed another system:

```ts
const chunks = await ai.documents.retrieve({
  query: "refund window",
  tags: ["policies"],
  top_n: 5,
});
// [{ text, score, document_id, chunk_index, metadata: { filename, page, … } }]
```

`top_k` is how many candidates are fetched; `top_n` is how many survive reranking — and
when no rerank model is configured, how many of the vector hits come back.

Reranking is a second, more expensive pass that reorders what recall found, and it only
happens when the project has a rerank model set (**LLM & limits → Rerank model**, or
`retrieval set --rerank-model`). Setting one now checks it can actually rerank and refuses
it if it cannot, because a rerank that fails degrades to vector order on purpose — losing
the whole query because a cross-encoder is down would be worse — which means a model that
can never work would otherwise look exactly like one that works.

Note that the model has to be **registered on one of the project's providers**, not just
named here, and it has to be reachable through a provider that can rerank: a model on an
OpenRouter key cannot, whatever the model is.

**And it is re-checked afterwards.** A credential that worked when the model was set can
stop working later, and the same silence applies — so `GET /readiness` carries a
`rerank-model` step that asks the model to rerank two documents and reports what it said.
It is **not** `essential`: a dead reranker costs a project the precision half of retrieval
and nothing else, so `canAnswer` stays true and a deploy gated on it still passes. `ready`
goes false, and the step names both the reason and how to stop the setting claiming
something that is not happening.

## Managing documents

```ts
await ai.documents.list({ tag: "finance", status_filter: "ready" });
await ai.documents.get(id);
await ai.documents.chunks(id);        // exactly what was indexed
await ai.documents.reingest(id);      // re-parse / re-embed
await ai.documents.downloadUrl(id);   // signed URL for the original file
await ai.documents.download(id);      // resumable ranged download -> Blob
await ai.documents.delete(id);        // removes the file and its vectors
```

`chunks` is the tool to reach for when an answer looks wrong: it shows what the model
actually had to work with. `reingest` is what you call after changing the project's document
processor or embedding model.

### Deleting from the two clients is deliberately not the same

The end-user client above deletes without being asked. The **project** client does not:

```ts
await ai.documents.delete(id);                          // end-user token — goes
await project.documents.delete(id, { confirm: true });  // project key — required
```

That is not an inconsistency to be tidied up. An end-user removing their own upload is an
ordinary action, and the place to confirm it is your product's UI, where the person is; a
project key is an operator credential reaching across every end-user in the workspace,
usually from a script that nobody is watching, and the confirmation is the only thing
standing between a stray loop and a corpus (OBE-270).

So the gate is on the operator route, not on the document. `confirm` is a required argument
rather than an optional one, which means a script that has not thought about it fails to
compile instead of failing at run time against a corpus it was halfway through.

:::info Uploading the same file twice

Nothing is refused. A filename is a label — documents have ids — and re-uploading a revised
file under its stable name is a normal, useful thing to do, so a duplicate name is a `201`
like any other upload.

What you get instead is `duplicate_of` on the new document: the id of the **oldest** document
in the project carrying the same content hash, or `null`. It fires on identical bytes whatever
they are called, including a re-upload under the identical name, and both copies stay
retrievable — which is worth knowing, because retrieval will then return the same passage
twice and that quietly doubles its weight in an answer.

```ts
const doc = await ai.documents.get(id);
if (doc.duplicate_of) {
  // already in the corpus under `doc.duplicate_of` — delete one of them
}
```

**Read it off `get` or `list`, not off the upload response.** It is resolved when you ask,
against the corpus as it stands, so an upload that has not finished indexing yet has no hash
to match on and reports `null`. That is also why a whole folder uploaded at once resolves
correctly: every copy links as soon as the rows have hashes, with nothing to sweep and
nothing to backfill. Delete the original later and the copies stop pointing at it.

The link is always to something strictly older, so two uploads racing cannot come back naming
each other.
:::

**`list` returns a page**, the same envelope `chat.sessions.list` does — a corpus is the one
collection that only grows, and a bare array asserts completeness by omission:

```ts
let offset: number | null = 0;
const all = [];
while (offset !== null) {
  const page = await ai.documents.list({ limit: 200, offset });
  all.push(...page.items);
  offset = page.next_offset;   // null on the last page
}
```

`limit` defaults to 100 and is capped at 500; a value outside that is a `422` naming the
bound rather than a `200` that quietly means something else. Page with **`next_offset`**
rather than adding your own limit to your own offset — the cap can make that arithmetic skip
rows. `has_more` is free (the server reads one spare row); `with_total: true` adds a `total`
and costs a second query, so it is for a summary rather than for paging.

### Retagging a document you uploaded

Tags scope a curated corpus — `retrieve({tags})` and `chat({tags})` both key on them — so
getting one wrong is ordinary, and fixing it should not cost the document's identity:

```ts
await oberik.documents.update(id, { tags: ["policies", "2026"] });   // project client
await oberik.documents.reingest(id);
```

`tags` **replaces** the list; fields you do not pass are left alone. The id does not change,
which is the point: deleting and re-uploading gives you a new id and silently breaks every
citation, stored `document_ids` scope and audit record that pointed at the old one.

This is on the **project** client, not the end-user one. An end-user token is refused a
document it does not own, deliberately — your users must not be able to rewrite the corpus
you curate. Uploads made with a project key are recorded against the subject `service`,
which is why the project client is the surface that can edit them.

**An upload needs an embedding model.** Without one there is nothing to index with, so the
upload is refused with a `409` naming the setting rather than accepted and failed minutes
later — `GET /readiness` lists it as `embedding-model`, and registering an embedding model
with your provider sets it (and measures its dimension) for you. A project on a deployment
whose shared embedder works is not affected, and one on a deployment that supplies no models
at all is told exactly that — "this deployment provides no default embedding model" — rather
than being handed a credential error about somebody else's key.

**And so does searching.** `rag_search` is not bound at all without one, so the agent is
told it cannot search this project's documents and says so — rather than being handed the
embedder's own error mid-turn, which reads as retryable and had it trying the same call
three times. It is the same fact as the paragraph above and the same fact as
[memory](./scheduling.md#memory): one setting, and everything that turns text into vectors
waits on it. Nothing is silently degraded — a project in that state answers from what it is
given in the conversation, and tells the user why it cannot look further.

---

## Files


A file is a file. Where it came from — the user attached it, the model generated it,
the agent screenshotted a page or exported it from a sandbox — is provenance, not type,
and it does not decide what can be done with it. What a file **is** decides how it is
read; where it came from decides nothing.

This is separate from [Documents](./documents.md), which is about a curated corpus the
agent *searches*. This page is about the files in one conversation.

## Read anything in the conversation

```ts
// The agent calls these; nothing to implement on your side.
list_files()            // everything here: attached, generated, screenshotted, exported
read_file(name?)        // read one — blank takes the most recent
```

`read_file` picks the best available route for that file and that model:

| File | How it is read |
|---|---|
| Text, CSV, JSON, code, logs | Decoded directly — no processor, no model support needed |
| PDF, Word, spreadsheets | Converted to text with the project's [document processor](./documents.md) |
| Images, audio, video | Put in front of the model to perceive, if it can and `input:<kind>` allows |
| Anything else | Reported as what it is, with the sandbox suggested |

**No sandbox is required for any of it.** Reading a file in your own conversation is not
a privilege, so these are bound for every chat.

That last row matters: a tool that implied a read it never performed is how an agent
ends up handing over a screenshot it never checked. It says so instead.

## Producing a file, and sending one

These are **two separate acts**, and deliberately so. Every producer puts a file into
the conversation and hands back an **id**; nothing reaches the user until the agent
says so:

```ts
write_file(name, content)     // something the agent writes    → id
screenshot_url(url)           // a captured page               → id
computer_export_file(path)    // out of a sandbox              → id
send_file(id)                 // give ANY of them to the user
```

A producer that also delivered would force the decision at the wrong moment: the agent
would have to know at capture time whether a screenshot is worth showing — before it
has looked at it — and could not change its mind after cropping. `send_file` works on
any file in the conversation whatever produced it and however long ago, so
"screenshot → check → crop → send the crop" is just four calls with the user seeing
only the last.

**`write_file` needs no sandbox** — a text-only model can write a CSV and hand it over.

Every file classifies as one of four kinds — `image`, `audio`, `video`, or `file` for
everything else — and delivery is allowed when **either** of these is true:

- the token holds **`output:file`**, which permits sending *any* kind; or
- the token holds **`output:<that kind>`** — so `output:image` alone is enough to send a
  picture.

So a screenshot goes out under `output:file` **or** `output:image`, and needs neither the
other one nor both.

:::tip Why `output:file` is the broad one
`output:file` means "the agent may hand the user a file", full stop — a screenshot it
took, a chart it rendered in a sandbox, a CSV it wrote. Those are files it **produced**,
and a project that granted "you may send files" did not mean "except pictures".

`output:image|audio|video` answer a different question — whether the *model* may
**generate** that medium — and they additionally permit delivering their own kind, since
generated media the user can never be shown is generated for nobody.
:::

Delivery is deliberately *not* gated on the turn's requested `output_modalities`: a
screenshot the agent took is a file it produced, not a modality the model emitted.

### Files the user never sees

Anything produced but not sent stays in the conversation for the agent's own use — an
intermediate screenshot, a scratch CSV — and `list_files` still shows it. That is what
keeps working notes out of the chat without throwing them away.

## Moving between layers

```ts
computer_fetch_attachment(name?)        // conversation  → sandbox
computer_fetch_document("prices.csv")   // knowledge base → sandbox (name or id)
computer_export_file(path)              // sandbox        → the conversation (then send_file)
```

All of these refer to the same descriptors, so a file crosses a boundary without
changing identity: screenshot a page, pull it into a sandbox, annotate it with
ImageMagick, send the result — and read any of them back at any point.

Note the third one: exporting brings a file **into the conversation**, it does not hand it
over. That is `send_file`, for the reason the [producers](#producing-a-file-and-sending-one)
section gives — and it is the step easiest to forget, because the failure looks like
success from every angle: the tool succeeded, the file exists, nothing errored, and
`attachments` is empty.

---

## Tools


The agent decides what to call; you decide what exists. Three kinds, all through the same
gate: **project ceiling ∩ token capabilities ∩ request flags ∩ `allowed_tools`**.

`allowed_tools` narrows the tools the SERVER offers. It does not touch what you declare in
the request itself — your client tools and your UI components are bound whichever way it is
set, because declaring one is already the strongest statement there is about whether you want
it. So `allowed_tools: []` means "no built-in tools this turn", not "none of my own either".

## Discover what's available

```ts
const { tools } = await ai.tools.list();
// [{ name: "rag_search", source: "builtin", description: "…" }, …]
```

The listing is filtered exactly the way a turn is, so it answers "what could the agent
actually be handed on my next request?" — use it to build an `allowed_tools` list or to
render a capability UI.

That includes infrastructure, not only permissions. A family your token holds and the
project cannot run — today, anything that needs an embedding model — is **absent from
`tools`** and reported in `withheld` with the reason:

```ts
const { tools, withheld } = await ai.tools.list();
// withheld: [{ name: "remember", source: "builtin",
//              unavailable: "this project has no embedding model, and the platform's
//                            default is not usable on this deployment (…). Nothing can be
//                            remembered, recalled or written to the wiki: configure one
//                            under Retrieval (LLM & limits) …" }]
```

Both halves matter if you render controls from this. Leaving them in `tools` put a
"Remember this" button in front of users on a project whose next turn refuses it; leaving
them out entirely would fix the lie and leave you unable to explain a control that has
quietly disappeared.

## Server-side tools

These run inside Oberik. Nothing to implement.

| Family | Tools | Capability |
|---|---|---|
| Retrieval | `rag_search` | `documents:read` |
| Web | `web_search`, `browse_url` | `web_search` |
| Browser | `browser_goto`, `browser_read`, `browser_html`, `browser_viewport`, `browser_click`, `browser_type`, `browser_scroll`, `browser_wait`, `browser_screenshot`, `browser_close` | `browser` |
| Browser hand-off | `browser_handoff`, `browser_handoff_end` | `browser_handoff` |
| Memory | `remember`, `recall`, `wiki_write`, `wiki_read`, `search_history` | `memory` |
| Scheduling | `schedule_reminder`, `cancel_reminder`, `list_reminders`, `current_time`, `wait` | `tasks:write` |
| Files | `list_files`, `read_file`, `write_file` | — (see [Files](./files.md)) |
| Sending files | `send_file`, `write_file` | `output:<kind>` |
| Capture a page | `screenshot_url` | `web_search` **and** `output:<kind>` — it fetches a URL: see below |
| Plans | `todo_write`, `todo_update`, `todo_remove`, `todo_clear` | `todo` |
| Asking | `ask_user` | `ask_user` |
| Approvals | `request_approval` | `approvals` |
| Skills | `load_skill`, `read_skill_file` | — (see [Skills](./skills.md)) |
| Subagents | `subagent_start`, `subagent_check`, `subagent_stop`, `subagent_answer` | `subagents` |
| Tool search | `tool_search` | `action_space` |
| Sandbox | `computer_*` (12 tools) | `computer` |

This table is a map, not the contract. **`tools.list()` is the reference** — it is
generated from what your token would actually be handed, so it accounts for the
project's ceiling, this token's capabilities, `allowed_tools`, and any MCP or webhook
tools you added. Where the two disagree, the listing is right and this table is stale.

## Your own tools (client-side)

When a tool has to run in *your* application — read the signed-in user's cart, call an
internal service, drive your UI — declare it per call. The agent pauses, hands the call back,
you run it, and the turn continues.

The SDK can do the whole loop for you. Register a handler and use `chat.run` or
`chat.stream`:

```ts
const ai = createClient({
  getToken,
  tools: [{
    name: "cancel_order",
    description: "Cancel an order belonging to the signed-in customer.",
    parameters: {
      type: "object",
      properties: { order_id: { type: "string" } },
      required: ["order_id"],
    },
    handler: async ({ order_id }) => {
      // Authorize HERE: the arguments are model-generated.
      await assertOwnedBySignedInUser(order_id as string);
      return await orders.cancel(order_id as string);
    },
  }],
});

const res = await ai.chat.run({ message: "Cancel my most recent order" });
```

`chat.run` dispatches tool calls, submits results, and repeats until the agent is done
(`maxToolRounds` defaults to 10). Streaming works the same way — pass `tools` in the handlers
and `handle.done` only resolves once the agent has finished, never with `requires_action`.

### Doing it manually

If you'd rather control the loop — or your tools run somewhere else entirely — use
`chat.send`:

```ts
let res = await ai.chat.send({ message, client_tools: schemas });

while (res.requires_action && res.tool_calls.length) {
  const tool_results = await Promise.all(
    res.tool_calls.map(async (call) => ({
      tool_call_id: call.id,
      content: JSON.stringify(await runLocally(call.name, call.args)),
    })),
  );
  res = await ai.chat.send({ session_id: res.session_id, tool_results, client_tools: schemas });
}
```

`client_tools` are OpenAI-format tool schemas (`{ type: "function", function: {…} }`). Two
rules worth internalising:

- **Authorize inside your handler.** Arguments come from the model. Check the `order_id`
  really belongs to the signed-in user before acting.
- **Keep handlers idempotent** where you can. Retries and reconnects are normal.

### Tools that need a person to say yes

Add `requiresApproval: true` (or `"requires_approval": true` beside `function` on the raw
schema) and the call is never handed to your handler until somebody approves it:

```ts
{
  name: "cancel_order",
  description: "Cancel an order. Irreversible: the customer is refunded and the slot is released.",
  parameters: { /* … */ },
  requiresApproval: true,
  handler: async ({ order_id }) => orders.cancel(order_id as string),
}
```

The call comes back in `approvals` — carrying `tool` and `arguments`, and **not** in
`tool_calls` — so auto-dispatch cannot reach it. Say yes and the identical call arrives in
`tool_calls` on the next round; say no and the agent is told the refusal is the point.

This is not the same as the agent's own
[`request_approval`](./working-together.md#asking-permission), where the *model* decides to
ask. Here the gate fires because the tool was called, so there is nothing for the model to
skip — which for money moving, a message sent as the user, or anything deleted is the
difference between a rule and a habit. It needs no capability: you are declaring a property
of your own tool.

:::note A webhook tool can be gated too
`requiresApproval` works on a [webhook tool](#gating-one-behind-a-decision) as well, and
means the same thing from your side: the turn pauses, the call comes back in `approvals`,
and nothing happens until somebody decides. The difference is who runs it afterwards —
there, we do.
:::

## Tools you host (webhook tools)

`webhook_tools` · per-turn flag `enable_webhook_tools`

A client-side tool runs in your app's process, which is the right place for it — until
there is no app process. A [scheduled run](./scheduling.md), a
[webhook trigger](./scheduling.md#webhook-triggers) and a [subagent](./subagents.md) all
execute server-side with nobody connected, so a client tool is never offered to them: an
agent that can cancel an order in a chat window cannot do it at 3am.

A webhook tool closes that. You publish an HTTPS endpoint; Oberik calls it during the
turn and hands your handler the end-user's identity.

```bash
curl -sX POST "https://oberik.com/api/projects/$ID/webhook-tools" \
  -H "X-API-Key: $KEY" -H "content-type: application/json" -d '{
    "name": "cancel_order",
    "description": "Cancel an order belonging to the signed-in customer.",
    "url": "https://acme.com/agent/orders",
    "parameters": {
      "type": "object",
      "properties": { "order_id": { "type": "string" } },
      "required": ["order_id"]
    }
  }'
# -> { "id": "…", "name": "cancel_order", "secret": "…" }   the secret is shown once
```

:::caution One secret **per tool**, not per project

Every webhook tool gets its own signing secret, returned once at creation and never
listed again. Three tools means three secrets, captured when you create them — if you
lose one, [rotate it](#rotating-the-secret) rather than re-creating the tool.

The single `OBERIK_TOOL_SECRET` in the verifier below is a one-endpoint example. If
several tools point at one handler, key the lookup by the `tool` field in the body; if
each has its own route, give each its own secret in the environment.

:::

### Gating one behind a decision

Set `requiresApproval: true` and the tool is not bound at all: the agent can call for it,
the turn stops, and your endpoint is called only after somebody approves.

```bash
curl -sX PATCH "https://oberik.com/api/projects/$ID/webhook-tools/$TOOL_ID" \
  -H "X-API-Key: $KEY" -H "content-type: application/json" \
  -d '{"requiresApproval": true}'
# -> { …, "requiresApproval": true }
```

:::warning Omit the field to leave the gate alone — do not send `null`

`requiresApproval` takes `true` or `false` and nothing else. `null`, `0` and the string
`"false"` are all refused with a `400` that changes nothing, and the first of those is the
one worth knowing about: most typed HTTP clients serialise an absent optional as `null`, so
`{"requiresApproval": null}` is the body a client sends to mean *"I am not touching this"*.
It used to be read as `false` and answered `200` — turning the gate off on an irreversible
tool and reporting success.

A **partial** PATCH is honoured: send only the fields you are changing and the gate is left
exactly as it was.

Note also that the write surface spells it `requiresApproval` while `GET /tools` reports
`requires_approval`. Sending the underscored name to the PATCH is a `400` rather than a
silent no-op, which is what keeps the two spellings from being a trap.
:::

From a client's side this is the same pause a gated
[client tool](#tools-that-need-a-person-to-say-yes) produces — `approvals` carries `tool`
and `arguments`, `tool_calls` stays empty — with one difference: **approving produces no
`tool_calls`**, because we make the call rather than handing it to you. The next round
simply continues with its result. There is nothing for your app to execute.

**It pauses on an unattended run too** — a scheduled task, a webhook trigger, a subagent —
and that is deliberate rather than an oversight. An unanswered *question* is safe to
proceed without: the agent uses its judgement and the answer would only have made it
better, which is why `ask_user` is not offered to an unattended run at all. An unanswered
*permission* is not safe to proceed without, so the turn waits, and the decision can be
given out of band from your [`turn.stopped`](./working-together.md#knowing-when-the-agent-stopped)
handler with `approval_decisions`. The two alternatives are worse: withholding the tool
takes away the capability you configured on purpose, and skipping the gate where nobody is
watching removes a safety control exactly where it matters most.

`GET /tools` reports `requires_approval` per webhook tool, so a caller deciding what the
agent may do this turn can see which of them stop and wait.

### What your endpoint receives

```jsonc
POST /agent/orders
X-Oberik-Signature: sha256=…            // HMAC-SHA256 of the raw body, with your secret
{
  "tool": "cancel_order",
  "arguments": { "order_id": "o_1029" },  // model-generated — validate it
  "subject": "acme:fin:ana",              // who is asking. From the token, never the model
  "scope": "acme:fin",                    // what they may see
  "roles": ["member"],
  "groups": ["finance"],
  "tenant_id": "…",
  "session_id": "…"
}
```

Answer with anything — JSON or text. The body becomes the tool result the agent reads,
capped at 20,000 characters. A non-2xx status comes back to the agent as a result too
(`'cancel_order' returned 409: order already shipped`), so a handler that explains its
refusal is telling the model something useful rather than just failing.

### Verify the signature

Until you do, anyone who learns your URL can claim to be any of your users.

**Mind the header name.** A webhook *tool* delivery is signed with that tool's own secret
in **`X-Oberik-Signature`**. Everything Oberik POSTs at you for its own reasons —
`turn.stopped` and `scheduled_task.fired` — is signed with the **project's**
webhook secret in **`X-Signature`**. Two schemes, two header names, two secrets; wiring
one verifier to the other's header fails every call and looks like a broken signature.
See [Verifying a delivery](./working-together.md#verifying-a-delivery) for the other one.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

app.post("/agent/orders", async (req, res) => {
  const raw = req.rawBody;                       // the exact bytes, not the parsed body
  const expected = "sha256=" + createHmac("sha256", process.env.OBERIK_TOOL_SECRET!)
    .update(raw).digest("hex");
  const got = req.header("X-Oberik-Signature") ?? "";
  if (got.length !== expected.length ||
      !timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.status(401).end();
  }

  const { arguments: args, subject } = JSON.parse(raw.toString());
  const order = await orders.find(args.order_id);
  if (order.customer !== subject) return res.status(403).json({ error: "not your order" });
  await orders.cancel(order.id);
  res.json({ ok: true });
});
```

### Rotating the secret

```bash
curl -sX POST "https://oberik.com/api/projects/$ID/webhook-tools/$TOOL_ID/rotate" \
  -H "X-API-Key: $KEY"
# -> { "secret": "…", "previousSecretUntil": 1786… }
```

For 24 hours `X-Oberik-Signature` carries **two** comma-separated signatures, one per
live secret. **Accept the call if either matches** and rotating costs you nothing — you
deploy the new secret whenever it suits, instead of during the switch:

```ts
const sigs = (req.header("X-Oberik-Signature") ?? "").split(",");
const ok = [process.env.SECRET_NEW, process.env.SECRET_OLD].filter(Boolean).some((s) =>
  sigs.includes("sha256=" + createHmac("sha256", s!).update(raw).digest("hex")),
);
```

Without the window, rotating would fail every call between issuing the new secret and
redeploying — which is why, in most products, nobody ever rotates.

### Watching them work

The dashboard's **Webhook tools** tab lists recent deliveries: which tool, what came
back, how long it took, and the error if there was one. Worth checking after a deploy on
your side — a handler that starts returning 500 is otherwise only visible inside one
turn's tool result, so the first sign is somebody asking why the agent stopped being able
to do something.

The same list, without the dashboard — **with your project key**, against the control
plane:

```bash
curl -s "$CP/api/projects/$OBERIK_PROJECT_ID/webhook-tools/deliveries" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY"
```

The data plane publishes `GET /tools/deliveries` too, but that one wants an **admin
credential**: a project key is a control-plane credential and the data plane does not
accept one, so reach it with a token minted with `roles: ["admin"]` (see
[the warning about that field](./authentication.md#admin-owner-and-service-are-not-labels))
or use the control-plane route above. Prefer the control-plane route — it needs nothing
you do not already have.

### How it compares

| | needs a connected client | knows which end-user | you host |
|---|---|---|---|
| [Client-side tool](#your-own-tools-client-side) | **yes** | yes | nothing — it runs in your app |
| [MCP server](#mcp-servers) | no | **no** — headers are static per project | a server |
| **Webhook tool** | no | yes, signed | an endpoint |

Reach for a client tool when the work belongs in the browser or needs something only the
signed-in session has. Reach for a webhook tool when the agent should be able to do it
whether or not anyone is watching.

### Publishing and granting are separate

Defining a tool doesn't bind it. The `webhook_tools` capability decides whether a given
token may reach any of them, so you can ship a tool that cancels an order and still mint
a read-only token that cannot. `enable_webhook_tools: false` declines them for one turn,
and `allowed_tools` names them individually like any other tool.

:::caution The arguments are model-generated
`subject` is ours and is signed; everything in `arguments` is text the model wrote.
Authorize inside your handler against `subject`, exactly as you would against a
session — the example above refuses an order that isn't the caller's.
:::

## MCP servers

Connect an MCP server in the dashboard and its tools join the project's catalog
(`source: "mcp"`), gated like any other tool. That's how you reach a system Oberik has
no built-in tool for.

:::note An MCP answer is cited like any other
Each result the turn used gets a numbered entry in
[`citations`](./chat.md#grounding) with `kind: "tool"` and the tool's name, so a sentence
built on your MCP server carries a marker and renders as a pill — and `renderCited` puts it
under the sentence that used it.

It reads `kind: "tool"` rather than pretending to be a document, which is the distinction
that used to make this impossible: a citation meant "a passage with a `document_id` and a
`chunk_index` you can open", an MCP result has neither, so MCP answers came back with
`citations: []`, `claims: []`, `attribution: "none"` and the `[n]` in the reply really was
the model's invention. What was uncheckable was never the result — it is the tool call in
the transcript, which is at least as followable as a 280-character quote — it was that
nothing had numbered it.

**Groundedness** covers it too: the [output guardrail](./guardrails.md) judges the answer
against what the turn's tools returned as well as against retrieved passages, so an answer
built from MCP data is checked like any other.

What the document index still gives you that MCP does not is a page and a chunk to open, and
staleness detection when the source changes. Upload it as [documents](./documents.md) when
you want those.
:::

Separately, `mcp:manage` controls whether your **end-users** may attach their own servers at
request time:

```ts
await ai.chat.send({
  message,
  mcp_servers: [{ name: "acme", url: "https://mcp.acme.com/sse", transport: "sse" }],
});
```

Off by default — a user-supplied server is code you didn't review. Your project's own servers
always load either way.

## Driving a browser

`browse_url` fetches a page and closes it, so the agent only ever sees a site's first
paint. With the `browser` capability it gets a page that **stays open** across tool
calls and works it like a person would:

```
browser_goto("https://shop.example/login", width=390, height=844)   # mobile layout
browser_type(3, "user@example.com")            # by number, from the observation
browser_type(selector="#password", "hunter2", submit=true)   # or by CSS selector
browser_wait(text="Your orders")
browser_html("#order-42")                      # raw markup: attributes, hidden fields
browser_scroll("bottom")
browser_screenshot()                           # look at it; sending is a separate step
```

Every observation returns the page text plus a **numbered list of what is actually
clickable or typeable**, and actions refer to those numbers by default. Asking a model
to invent a CSS selector for a page it has only read as text is asking it to guess, and
a bad guess matches nothing and fails silently. The numbering is recomputed after every
action, so a page that changed underneath can't leave the agent clicking something that
moved.

A **selector** works anywhere a number does, and is the right choice once the agent has
read the markup with `browser_html` — which is also how it gets at attributes, `data-`
values and hidden fields the rendered text doesn't show. `browser_viewport` sets the
window size, so checking a mobile layout is a normal thing to ask for.

`browser_wait(text: "…")` returns the moment the text appears rather than sleeping for
a guessed duration — pages that load late are most of why this exists.

One page per conversation, reaped when idle (10 min), on age (1 hour) and when too
many are open — a page being *used* is still a page holding memory and a login, so an
idle timer alone cannot bound it. A reaped page is reopened transparently on the next
call (blank, and the agent is told so).

Granting `browser` withholds `screenshot_url`: `browser_goto` plus `browser_screenshot`
does everything it did, and two ways to capture a page is one more decision than the
model needs to make.

:::warning `screenshot_url` reaches the internet — it needs `web_search` **and** a delivery kind
It is filed under **Sending files** because what it *produces* is a file. But to make that
file it **fetches a URL of the model's choosing**, and the page's text comes back into the
turn — so it is `browse_url` answering in pixels, and it is gated the same way.

**A token without `web_search` does not have it.** That was not always true: it used to
ride on `output:file` / `output:image` alone, so the capability set
[Authentication](./authentication.md) prints as *"a read-only research token"*
(`["chat", "documents:read"]`) came out able to reach the public internet, and the only way
to withhold it at mint time was to decline the output modalities — which also takes away
`send_file`. "May hand back a file" and "may fetch a URL" are not the same decision and
were being made together.

Still worth knowing:

- **Granting `browser` withholds it**, per the paragraph above — `browser_goto` plus
  `browser_screenshot` covers it. So `web_search` alone gets you this one; `browser` gets
  you the better ones instead.
- Whatever the agent fetches is untrusted input in the same way [sandbox
  output](./sandbox.md) is — and a message can ask for it, so a prompt injection can drive
  it. That is true of `web_search` and `browse_url` too: it is what granting the web means.
- `allowed_tools` on a request still narrows further, per-turn, if you want the capability
  granted and this one tool withheld.
:::

### Handing the page to the user

Some things only a person can do: a bot check, a login the agent has no credentials
for, a consent dialog, a 2FA prompt. With `browser_handoff` the agent gives the user
**live control of that part of the page** instead of guessing or giving up.

The SDK ships the viewer, so this is an `<img>` and about ten lines:

```ts
let view: HandoffController | null = null;

ai.chat.stream({ message: "check my order status" }, {
  onBrowserHandoff: (handoff) => {
    // Also fires when the agent CLOSES an open hand-off, and when it re-announces one
    // it is still waiting on — `update` handles both without blanking the picture.
    if (view) return view.update(handoff);
    view = ai.chat.sessions.handoff(sessionId, handoff, {
      onView: () => render(),                       // a frame, a crop, a check
      onEnded: ({ resume }) => {
        view = null;
        if (resume) ai.chat.handoffDone(sessionId); // a blocking hand-off stopped the turn
      },
    });
  },
});

// Once you have the element — in a React ref callback, an effect, or plain DOM:
const detach = view.attach(img);   // paints into it and relays what the user does
```

That is the whole integration. `attach` owns the parts that are easy to get subtly
wrong and impossible to notice:

- **the live stream**, opened per region and left alone while the agent re-announces the
  same one, with a single polled frame as a fallback if it never paints;
- **the crop** — frames are the whole viewport, so the image is blown up and offset
  inside a window the size of the region, which is what lets the challenge overlay that
  appears after the first click re-aim the view with no re-encoding and no round trip;
- **the coordinates** — the picture is CSS-scaled to fit, so displayed pixels are
  converted back to page pixels before they are sent. A click a centimetre from where
  the user aimed is, on a CAPTCHA grid, simply a wrong answer;
- **the gestures** — press, move, release relayed as a real drag, throttled to ~60/s
  because a pointermove handler fires far faster than any network will carry;
- **the keyboard** — typing, Tab, Enter, Backspace and the arrows go to the page, and so
  does a paste. Pointing at the image focuses it, so there is no separate click-to-type
  step. A printable character is sent as *text* rather than as a key press, which is the
  only way anything a layout produces with a modifier — an accent, a `ı`, anything behind
  AltGr — arrives as what the person typed. Paste is read from the real clipboard event:
  `Ctrl-V` inside the remote page would paste the *server's* clipboard, which is empty,
  and a password out of a manager reaches a login form no other way;
- **the finished-check** — after each release, once the page has settled.

What it deliberately leaves alone is the viewer's own browser: `Cmd-R`, `Cmd-T` and the
address bar keep working, because a picture of a page should not swallow the shortcuts of
the window it is in. `Ctrl/Cmd-A` and `Ctrl/Cmd-Z` do go to the page — select-all before
retyping a field, and undo. Copy and cut do not, and cannot usefully: inside the remote
page they act on a clipboard the person has no way to read.

`onView` gives you everything needed to render the rest — the URL, whether it is live,
whether the crop is the agent's selector or the whole page, whether a check is in flight,
and **whether the page currently holds the keyboard** (`focused`) — so the card around the
image is yours and the geometry is not. Render `focused`: a picture of a login form gives
a person no way to tell whether their keystrokes are reaching it, and the failure is
silent in the worst way, which is someone typing a password into nothing.

**Nothing here needs a browser until `attach`,** and `attach` takes anything shaped like
an image rather than an `HTMLImageElement`. Importing the SDK server-side is unaffected,
and its published types need no DOM lib.

### Building your own viewer

The primitives are all public if you want to render it differently — a canvas, a native
app, a different framework's binding:

```ts
const stream = ai.chat.sessions.browserStream(sessionId, {
  onFrame: (f) => paint(f.image),          // the whole viewport, already encoded
  onClip: (c) => setCrop(c),               // where to crop it, when that MOVES
  onError: (m) => show(m),
}, selector);

await ai.chat.sessions.browserInput(sessionId, {
  type: "pointer_down", x, y, origin: clip.origin, selector, want_frame: false,
});

stream.close();
await ai.chat.handoffDone(sessionId);
```

**Stream, don't poll.** `browserFrame` renders a fresh screenshot per call and gives a
viewer roughly one frame a second — enough to watch a page settle, nowhere near enough
to *work* one. Keep it for a still or as a fallback; use `browserStream` for anything
interactive.

### What the user can do to the page

Everything a mouse can, not just tapping — which matters because the common bot check
is now a slider you drag, and a viewer that only relays clicks hands someone a puzzle
they physically cannot finish.

| `type` | For |
|---|---|
| `click` | A tap. `button` for right/middle, `clicks: 2` for a double. |
| `pointer_down` / `pointer_move` / `pointer_up` | **A drag.** Stream `pointer_move` from a real pointermove handler and the page sees the gesture the person actually made, path and all. |
| `drag` | The same gesture described in one call, for the *agent*: `to`, `steps`, `hold_ms`. Interpolated, because a straight teleport from A to B is a motion no hand makes. |
| `wheel` | Scrolling a pane that isn't the document — a map, a listbox, a scrollable challenge. |
| `type` / `key` | Text and keys. `modifiers: ["Control"]` to hold one. |
| `scroll` | The window itself. |

Coordinates are always **image space plus the `origin`** of the frame they came from.
Echo the origin back; never add it yourself. The server does that arithmetic, so a crop
that moved between paint and release cannot displace the gesture.

### Only the part that matters

The agent passes a selector for the widget and **only that region is shown** — along
with any challenge overlay currently visible. That second part matters: every widget
CAPTCHA renders its puzzle in a separate absolutely-positioned overlay that appears
*after* the checkbox is clicked, so clipping to the named element alone would show a
tick box and hide the thing to solve. The region is recomputed continuously for exactly
that reason.

**A selector that matches nothing no longer means the whole page.** The agent has to
guess a selector from markup it may never have read, and one wrong guess used to throw
away all the aiming silently. Oberik already recognises these widgets well enough to
tell the agent a page is a bot check, so it points the camera at one itself. Each frame
says which happened:

| `region` | Meaning |
|---|---|
| `selector` | The agent's own selector produced this crop (`matched: true`). |
| `detected` | It matched nothing, and the widget was found anyway. |
| `viewport` | Neither — this is the whole page, and your UI should say so. |

The agent is told when its selector missed, so it can pick a better one rather than
believing it handed over what it named.

### Ending it without asking them to say so

Someone who has just passed a bot check should not then have to report that they passed
it, to a system looking straight at the result. So after each release the region is
shown to a **separate, small model** — separate because the turn's own context is large
and this runs repeatedly — which answers one question: is this finished?

`chat.sessions.handoff()` does this for you — after each release, once the page has
settled. Driving it yourself is two calls:

```ts
// Call this after each gesture ends, once the page has settled.
async function finishIfDone() {
  const r = await ai.chat.sessions.handoffCheck(sessionId);
  if (r.done) return ai.chat.handoffDone(sessionId);        // press Done for them
  if (!r.will_check_again) autoDone = false;                // and stop asking
}
```

**The page is asked before the model is.** Passing a bot check is normally a
*navigation*: the widget goes away and you land on the content, on a redirect, or for a
moment on nothing at all. So two of the answers cost nothing and are facts rather than
opinions.

| `state` | Meaning | Costs a model call |
|---|---|---|
| `gone` | A bot check **that was on screen earlier in this hand-off** is not any more, and something has rendered. **Done.** | no |
| `loading` | Mid-navigation — blank, or not finished loading. Decides nothing; ask again shortly. | no |
| `solved` | Visibly complete. **Done.** | yes |
| `unsolved` | Still waiting on them. | yes |
| `unclear` | Genuinely cannot tell. | yes |

Landing somewhere *unexpected* counts as finished: the person is done with what they
were handed, and the agent reads the page the moment it resumes, so it finds out where
it ended up. Leaving someone staring at a page they have finished with, because it
isn't the one we predicted, is the worse failure. A blank page is the one case that
decides nothing — mid-navigation looks identical to failure, so it waits.

:::caution `gone` needs something to have gone
"Nothing recognisable is on screen" is only evidence of an ending if something
recognisable was there to begin with — so `gone` requires having *seen* a bot check
during this hand-off, and everything else goes to the model.

Without that condition it fired on the **first** check of every hand-off whose subject
nothing can recognise. A login form is not a bot check and a hand-off need not carry a
selector, so both signals were absent before the person had done anything — and since the
check runs on their first release, clicking into the email field ended the hand-off and
resumed the turn while they were still reading the page. A hand-off for a consent dialog,
a 2FA prompt or a payment form ended the same way.

A selector that stops matching does **not** count either. A two-step login takes the named
form off the page halfway through, and a selector is the agent's guess at a region worth
showing rather than a definition of done.
:::

Of the three the model does answer, **only those words can ever come back**. That is a
security property rather than brevity: the checker is looking at a CAPTCHA, and a
closed vocabulary is what stops it being a way to read one out. It reports a state; it
never describes the picture, and it never touches the page.

`checked: false` means no call was made, and **`will_check_again` is the field to branch
on**: it is the difference between waiting and giving up. Calling on every mouse-up is
fine; the extras come back unchecked.

| `reason` | `will_check_again` | What to do |
|---|---|---|
| `too_soon` | `true` | Nothing. The last check was moments ago; the next gesture's will land. |
| `checked_enough` | `false` | Stop polling. One hand-off gets a finite number of checks, and someone still going after that is not being helped by another one. |
| `autodetect_disabled` | `false` | Stop polling. This deployment has the checker switched off. |
| `nothing_to_check` | `false` | Stop polling. Not a hand-off that can end itself. |

Stop polling means **show the Done button and leave it to them** — which is the fallback
either way, since every failure means "not finished".

The agent arms this with `auto_done` (default on) and it needs a `reason` to judge
against — "pass the captcha" works, "help me" does not. It stays off for open hand-offs,
which have no button to press, and off when `enable_handoff_autodetect=false`, because
with no checker running there is nothing for a client to poll and `auto_done: true` would
be an invitation to wait for ever.

:::caution `auto_done` is where a hand-off starts, not a guarantee for its lifetime
A hand-off that begins with `auto_done: true` can still run out of checks while the person
is working — so a client that reads it once and polls on the strength of it will, on a long
hand-off, keep asking a question that has stopped being answered. That is what
`will_check_again: false` is for, and `chat.sessions.handoff()` already does it: the view's
`autoDone` goes false and the Done button becomes the way out.
:::

**Three modes**, because "here, deal with this" and "here, have a look" are different
asks:

| `mode` / flag | What happens |
|---|---|
| `blocking` *(default)* | The turn **stops**, exactly like a pending client tool call. The response carries `handoff.blocking`; render a Done button and send `handoff_done: true` to resume. The agent is told not to ask a question — the button is the answer. |
| `open` | The agent carries on. It closes the view itself with `browser_handoff_end` when it no longer needs you looking. |
| `interactive: false` | Show it, don't let them touch it. The input endpoint **refuses** for these, so a read-only hand-off is read-only on the server rather than merely looking it in the UI. |

**On CAPTCHAs specifically:** the agent is told when a page is a bot check — otherwise
it reads a near-empty page, decides the site is broken and reports something untrue —
and is told not to work through it. That check exists to establish a person is
present, and the agent isn't one. Relaying a real person's clicks is a different
thing, and it's what this is. With nobody to ask — a scheduled run, a webhook — it
says the page is gated and stops.

:::caution It browses as your end-user
Anything reachable behind a login the agent can complete is reachable by the agent.
Grant it where you would be comfortable with that.
:::

## Large tool catalogs

With `action_space`, only the tools relevant to the message are bound for that turn, instead
of every tool in the catalog. It keeps accuracy up and cost down once you have dozens of
tools. Decline it per request with `enable_action_space: false`.

Two things worth knowing before you turn it on, because neither is guessable:

- **It needs an embedding model.** Relevance is measured by embedding your message and each
  tool's description, which is the same machinery retrieval and memory use — so a project
  with no embedding model configured gets nothing from this capability. `GET /capabilities`
  says so: the flag comes back `effective: false` with `blocked: "needs an embedding
  model"`, and the turn behaves as though the capability were off (every tool bound, no
  `tool_search`) rather than failing. **The turn says so too**, on `warnings`, because this
  is the one capability that degrades to *everything* rather than to *nothing* — there is no
  missing tool to notice, so a caller who set the flag once and never re-read
  `capabilities()` would otherwise see a feature that appears to work:

  ```jsonc
  { "warnings": ["this project has no embedding model, and the platform's default is not
     usable on this deployment (…). enable_action_space was set and could not narrow
     anything, so every tool is bound on every turn instead of the relevant few — the cost
     this capability exists to avoid: configure one under Retrieval (LLM & limits) …"] }
  ```
- **Nothing is narrowed below about 8 tools.** Under that, the whole catalog is smaller
  than the subset would be, so narrowing is skipped and `tool_search` is not bound either —
  a tool whose description is "there are more tools than you can see" must not appear on a
  turn where that is false. Past it, roughly the 6 most relevant are bound, plus anything
  pinned or already in use.

  Both numbers are deployment defaults rather than a contract, which is why they are
  written as "about" and "roughly" — but they are written as digits so that grepping for
  one finds it. Somebody looking for the threshold searched for a number, found nothing,
  and reported that it was documented nowhere; it was, four lines from where they looked.

Crucially, **the narrowing is reversible by the agent**. It always holds `tool_search`, so
when it needs something it can't see it searches for it and whatever matches becomes
callable immediately — for the rest of the turn, not just the next step. Tool families
that only work whole (the todo tools, scheduling, the browser) are
never split, and anything the agent is already mid-way through using is kept regardless of
how the current message happens to rank.

That matters because the alternative is worse than a large catalog: an agent that silently
lost a tool it used a moment ago, with no way to ask for it back, reasons about its own
capabilities from a false picture.

## Restricting a single turn

```ts
await ai.chat.send({ message, allowed_tools: ["rag_search"] });   // retrieval only
await ai.chat.send({ message, allowed_tools: [] });                // no server-side tools
await ai.chat.send({ message, enable_web_search: false });         // keep it internal
```

`allowed_tools` covers server-side and MCP tools; your own `client_tools` are always
available, since you chose to pass them.

A project-wide restriction is also available (**Capabilities → allowed tools**), applied
before any request-level list — and unlike the per-request one, an end-user token cannot
widen it. That makes it the answer to "withhold this tool from every token this project
mints": set it once on the project rather than remembering to send `allowed_tools` on
every request.

`GET /capabilities` reports it as `allowed_tools` (null = no restriction), so a client can
tell a tool it may not call from a tool that does not exist. `GET /tools` already applies
it, as it applies every other gate.

## UI components — tools that draw

`ui_tools` · per-turn field `ui_tools`

A client tool is work handed back: the turn stops, you run it, the result returns as a
tool message. That shape is wrong for showing a chart, dropping a booking card into the
thread, or highlighting a row — there is no result. Waiting for one turns a one-way
instruction into a round trip, and a client with nothing useful to say ends up inventing
`{"ok": true}` for the model to reason about.

So a UI component is declared like a tool and behaves like a display:

```ts
const ai = createClient({
  getToken,
  ui: [{
    name: "show_chart",
    description: "Draw a line chart of a numeric series over time.",
    parameters: {
      type: "object",
      properties: {
        title: { type: "string" },
        points: { type: "array", items: { type: "number" } },
      },
      required: ["title", "points"],
    },
    render: ({ title, points }) => setChart({ title, points }),
  }],
});
```

The agent calls it, your `render` runs, and **the turn does not pause** — it carries on
in the same step. Streaming clients render the instant it is called; waiting for `done`
would mean a chart appearing after the paragraph that refers to it. The whole list also
comes back on the turn as `ui`, in call order, so a client that re-mounts can redraw
from it rather than replaying events.

The agent is told what it drew and asked to refer to it rather than repeat it in prose,
so you get "here's how that trended" beside the chart instead of the chart described
twice.

A few things it deliberately is not:

- **Not trusted to be listening.** A component that reaches nobody still returns
  cleanly. A closed tab is not a failed turn.
- **Not a transport.** Payloads are capped — pass an id and let your client fetch the
  rest — and a turn can draw at most 40 things.
- **Not available to subagents.** A delegate's output is a report the main agent has to
  weigh; letting one paint the conversation would put something in front of the user
  that the agent answerable for the turn never saw.

---

## Working with the user


Five capabilities for the back-and-forth around a turn. Two are things the **agent**
does (keeping a plan, asking a question), one is something the **user** does mid-turn
(steering), and two are affordances for your **UI** that the agent never sees at all.

## Todos — the agent's plan

`todo` · per-turn flag `enable_todo`

For work with several distinct steps, the agent writes a checklist and updates it as it
goes. The list is stored per chat session and injected into the agent's context each
turn, so it survives a tool loop, a resumed stream, or a restart — and the agent never
spends a call reading it back.

```ts
const done = await ai.chat.stream({ message: "migrate every fetcher" }, {
  onTodos: (items) => render(items),   // fires as each step is written or ticked off
});
done.todos;                             // final state
await ai.chat.sessions.todos(sessionId); // or read it any time
```

Each item has a `number` that is stable for the life of the session and never reused,
so ticking off item 3 still means item 3 after item 1 is deleted.

The agent is told to open a list only for genuinely multi-step work — a question it can
answer or a one-step edit gets none, because a one-item checklist is noise.

## Asking permission

`approvals` · per-turn flag `enable_approvals`

Every other gate here is decided before the turn starts — a project ceiling, a
capability on the token, a per-request flag. That is the right shape for "may this
agent use a sandbox at all" and the wrong one for "may it run *this* command", because
the thing being judged does not exist until the model proposes it.

So the agent can stop and describe exactly what it is about to do, and nothing happens
until a person answers:

```ts
await ai.chat.stream({ message: "email the Q3 numbers to finance" }, {
  onApproval: async (request) => {
    // request.action      — one line, with the specifics in it
    // request.detail      — the message it would actually send
    // request.consequence — what cannot be undone
    return await showApprovalDialog(request);   // true / false / {approved, note}
  },
});
```

Without `onApproval` the turn simply returns with `approvals` set and you resume it
with `approval_decisions` — which is the right default. Nothing should be able to
approve an irreversible action by accident, so tool auto-dispatch never sees the call
being decided about: an approval arrives with `requires_action`, and whatever it is
holding back is **not** in `tool_calls`.

One entry per decision, and only `approved` is required:

```jsonc
{
  "session_id": "…",
  "approval_decisions": [
    {
      "approved": false,
      // Omit when only one approval is outstanding, which is the common case.
      // Otherwise it is the `tool_call_id` from the matching `approvals[]` entry.
      "tool_call_id": "call_abc123",
      // Optional. The difference between "no" and "no, use the other address".
      "note": "use finance@acme.com instead"
    }
  ]
}
```

An outstanding approval you send no decision for stays outstanding: the turn pauses
again rather than treating silence as either answer.

**Saying no stops the work.** The agent is told not to try another way, not to reach for
a different tool that achieves the same thing, and not to continue with any part of the
plan that depended on it — a refusal is a decision about the outcome, not about how it
asked. It comes back and asks what you want instead. A `note` on the decision is the
difference between "no" and "no, use the other address".

**The model decides when to ask** — which is weaker than a rule that fires whether it
cooperates or not. It buys the large middle ground where the agent knows perfectly well
that sending the mail is the irreversible step. For the cases where "usually asks" is not
good enough, mark the tool instead.

### A tool that cannot be called without asking

`requiresApproval` on one of your own [client tools](./tools.md#your-own-tools-client-side)
makes the pause a property of the tool rather than a decision the model gets to make:

```ts
const ai = createClient({
  getToken,
  tools: [{
    name: "cancel_booking",
    description: "Cancel a booking. Irreversible: the slot is released to the market immediately.",
    parameters: {
      type: "object",
      properties: { booking_id: { type: "string" } },
      required: ["booking_id"],
    },
    requiresApproval: true,
    handler: async ({ booking_id }) => cancel(booking_id as string),
  }],
});
```

Now a call to it comes back as an approval carrying the call itself, and the handler is
unreachable until somebody says yes:

```jsonc
{
  "requires_action": true,
  "tool_calls": [],                       // ← the call is NOT here yet
  "approvals": [{
    "tool_call_id": "call_abc123",
    "action": "Cancel a booking. Irreversible: the slot is released to the market immediately.",
    "detail": "booking_id: NW-3009",      // the arguments — this is what is being decided
    "tool": "cancel_booking",             // null when the MODEL asked, via request_approval
    "arguments": { "booking_id": "NW-3009" }
  }]
}
```

Approve it and the identical call arrives in `tool_calls` on the next round and runs
normally — the SDK's auto-dispatch does the second round for you. Refuse it and the agent
is told, in the same words as any other refusal, that stopping was the point.

Why it is a different thing from the paragraph above: this gate fires because the tool was
**called**. A model that has never heard of `request_approval`, or that simply does not
think to ask, cannot get past it — the only way to skip it is not to declare the tool. That
matters because "usually asks" is measurable, and what was measured was a tool described in
as many words as *"Cancel a booking. Irreversible"* being called straight through, twice,
on a project that granted `approvals`, past an `onApproval` handler that refused everything
and was never once consulted. Nothing was broken; the model just did not ask.

`requiresApproval` needs no capability and no flag: you are declaring a property of your
own tool, not asking for permission to have one. `action` is the tool's `description`, so
write that sentence for the person who will read it — it is already the sentence you wrote
to tell the model when the tool applies.

Subagents never get it: there is no user on a delegate's turn, so it asks the main
agent, and the main agent asks you if it comes to that.

## Questions the agent asks

`ask_user` · per-turn flag `enable_ask_user`

When a decision is genuinely the user's and guessing wrong would waste real work, the
agent can stop and ask. The turn **pauses** and comes back with `requires_action` and a
`questions` array — and an **empty `tool_calls`**, because a question is not work for
your client to execute.

```ts
const r = await ai.chat.send({ message: "migrate the fetchers" });
if (r.questions.length) {
  const batch = r.questions[0];
  // batch.questions[0] → { header, question, options[], multi_select, allow_other }
  await ai.chat.answer(r.session_id, {
    tool_call_id: batch.tool_call_id,
    answers: [{ question_id: "Scope", selected: ["box-* too"] }],
  });
}
```

Two escapes are always available and are **not the agent's to remove**: free text
(`text`), and declining the picker entirely (`chat_instead: true`), which tells the
agent to drop the question and keep talking rather than re-ask it.

:::caution Only where someone can answer
A paused turn waits forever if nobody is there. Set `enable_ask_user: false` for batch
jobs, webhooks and scheduled runs — scheduled tasks never bind it for this reason.
:::

With `chat.run` or `chat.stream`, pass an `onQuestion` handler and the pause is
answered and resumed for you.

## Steering — a message into a running turn

`steer`

Correct the agent mid-flight instead of watching it finish work you can already see is
wrong.

```ts
const h = ai.chat.stream({ message: "migrate every fetcher" }, { onToken: write });
const landed = await h.steer("only the forfaits-* ones");
if (!landed) { /* the turn ended first — send it as a normal message */ }
```

The message is picked up at the agent's **next step boundary**, after any tool in
flight finishes. That is deliberate: cancelling a half-done tool call would leave a
call nothing answered, and that state fails every later turn on the session
permanently. It arrives as a normal user message, so it cannot outrank your project's
own system prompt, and it is stored with `extra.steered` so the transcript shows why
the agent changed course.

**A `true` means it will be acted on.** If your message lands while the model is already
writing its answer — which is most of the window on a fast tool — the turn takes one more
step for it rather than finishing and dropping it. So the two answers mean exactly what
they say: `true`, the agent will see it before this turn ends; `false`, the turn was
already over and it is yours to send as a normal message.

**And `done.steered` says what actually landed.** `true` is about the message being
accepted; this is about the agent having read it:

```ts
const done = await h.done;
done.steered;        // ["only the forfaits-* ones"] — empty on an ordinary turn
```

Read it before you tell the user their correction took effect. It also explains something
about `content` that surprises people: **a steered turn speaks twice.** The agent answers
the instruction it had, you correct it, and it answers again — so `content` holds both,
because it is the same text `onToken` gave you. If you want them separated, render
`chat.sessions.messages`: the correction is a user row between the two answers, marked
`extra.steered`. And if your tests assert "the reply is exactly X", remember that a
corrected turn is not one reply.

Only streaming turns can be steered — a blocking `/chat` call has no run to send to.

**Queueing needs no capability.** Holding a message until the turn ends is just your
next `send`. If you send several at once, pass them as `messages` and they arrive as
separate user messages with one reply:

```ts
await ai.chat.send({ session_id, message: "start it", messages: ["skip archived"] });
```

## Knowing when the agent stopped

A turn ends one of two ways, and the difference is everything: it finished, or it is
**waiting on a person**. A connected client sees both on its stream. One that isn't —
a closed tab, a backgrounded phone, a scheduled run nobody was watching — sees
neither, and an agent blocked on a question nobody knows was asked just sits there.

Set a **turn-stopped webhook** on the project and the server POSTs when either
happens:

```jsonc
{
  "event": "turn.stopped",
  "reason": "needs_client_tool",   // completed | needs_answer | needs_approval |
                                   // needs_client_tool | needs_browser |
                                   // hit_tool_limit | subagents_incomplete |
                                   // no_answer
  "needs_input": true,             // somebody is expected to act
  "complete": false,               // did this finish the work?
  "scheduled": false,              // a scheduled run: nobody was watching by definition
  "tenant_id": "…",
  "session_id": "…",
  "user_ref": "your-own-id",
  "preview": "Here you go. The Q3…",  // the answer's OPENING, on a `completed` turn —
                                      // at most 280 characters, never the whole thing.
                                      // null when there was no prose to preview
  "preview_truncated": true,          // there is more; `preview` is a prefix
  "content_chars": 1840,              // how much there is, so you can decide whether
                                      // fetching the session is worth it
  "tools": ["lookup_order"],       // when a client tool is why — you may be able to
                                   // answer it without a human at all
  "questions": [                   // when `needs_answer` is why
    { "tool_call_id": "…", "headers": ["Scope"] }
  ],
  "approvals": [                   // when `needs_approval` is why — route it to
    { "tool_call_id": "…",         // whoever is allowed to make the decision
      "action": "Email the Q3 numbers to finance" }
  ]
}
```

Two booleans, so a receiver doesn't have to know every reason string — including ones
added later. They are **not** opposites:

| | `needs_input` | `complete` |
|---|---|---|
| `completed` | false | **true** |
| `needs_answer` / `needs_approval` / `needs_client_tool` / `needs_browser` | **true** | false |
| `hit_tool_limit` / `subagents_incomplete` / `no_answer` | false | false |

**Branch on the booleans, not the strings.** They are computed from the turn's own state
as well as from the reason, so a pause added after you wrote your handler still arrives as
`needs_input: true` — with a reason string your code will not recognise, which is the
harmless half of the problem.

:::note A pause your own client answers is not delivered
The webhook is for the client that *isn't* there, but a turn stops before a connected
client has had a chance to answer it. So a `needs_input` delivery on an **interactive**
turn waits a few seconds and looks again: if the conversation has moved on — your
`onApproval` or `onQuestion` handler dealt with it, which usually takes milliseconds —
nothing is sent.

Without that, every approval handled in a browser also paged whoever your backend routes
`needs_input` to, and there was no field on the payload saying it had already been
decided.

Two consequences worth knowing: a genuine pause notification arrives a few seconds after
the turn stops rather than instantly, and **scheduled runs skip the wait entirely** —
nobody is watching those by definition, so they deliver immediately.
:::

`needs_input` means somebody is expected to act — route it to a person or answer it
from your backend. `complete` means the turn finished the work it was given. The last
row is the one worth handling: the turn is over and nobody is waiting, but the answer is
short of what was asked. `subagents_incomplete` means the turn ended while work it had
delegated was still running, so part of the reply may be missing — see
[Subagents](./subagents.md). `no_answer` means the turn produced nothing at all: no prose,
no file, nothing to pause on. It is rare and it is not the user's fault — a provider
dropping a message on a filter of its own is the usual cause — so the useful handling is a
retry, or telling them it failed, rather than rendering an empty reply.

Private and metadata targets are refused, and delivery is best-effort — the reply is
already saved, so a failed webhook costs a notification, not an answer.

### Verifying a delivery

Every delivery carries `X-Signature: sha256=<hmac>` over the exact body with keys sorted,
plus an `X-Delivery-Id` you can deduplicate on. Get the key with:

```bash
curl -s "$CP/api/projects/$OBERIK_PROJECT_ID/webhook-secret" -H "X-API-Key: $OBERIK_PROJECT_KEY"
# -> { "secret": "…" }
```

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.header("x-signature")!));
```

Verify against the **raw** bytes, before any JSON parsing — re-serialising changes them.
`POST …/webhook-secret/rotate` issues a new key; update your verifier and the next delivery
uses it.

#### What this key covers

Three deliveries, one key, one scheme — so a single verifier handles all of them:

| Delivery | `event` | Sent when |
|---|---|---|
| the project's turn-stopped webhook | `turn.stopped` | a turn finishes or needs a person |
| a scheduled task's `action.callback_url` | `scheduled_task.fired` | an agent task ran |
| a scheduled task's webhook action | `scheduled_task.fired` | a webhook task fired |

All three carry `X-Signature` and `X-Delivery-Id`. A `scheduled_task.fired` body is:

```jsonc
{ "event": "scheduled_task.fired", "task_id": "…", "tenant_id": "…",
  "session_id": "…", "message": "the agent's reply" }
```

`X-Delivery-Id` identifies **one delivery**: unique per notification, and stable across
retries of that same notification. Deduplicate on it rather than on `task_id` or
`session_id` — a retried delivery is the same reminder, not a second one, while two turns
of the same conversation are two real notifications and both matter.

:::note Not the same as a webhook **tool**

Webhook tools — the ones the agent calls as tools — sign with a **per-tool** secret,
returned once when you create the tool, in a header named `X-Oberik-Signature`. Two
schemes, two header names, two secrets. See
[Tools you host](./tools.md#tools-you-host-webhook-tools).

:::

The dashboard playground pairs this with two notifications, because they reach
different people. The Notification API covers a tab that is merely in the background.
**Web Push** covers a tab that is closed — a service worker, a VAPID keypair and a
subscription stored server-side — which is the case that matters, since a turn stopping
because it needs you is exactly when you are not looking at it.

The playground runs the real thing rather than faking it. Three pieces, and each one is a
command you can call, so the worked example is something you can watch rather than a
description of one:

```bash
push key         # the VAPID public key to hand a browser; blank when push is off
push subscribe   # store one browser's subscription against an end-user subject
push hook        # where the data plane POSTs `turn.stopped`, which sends the notification
```

**Use them to see the shape, not as your own notification path.** The notification they send
links back into *this* dashboard's playground, which is the wrong destination for your
product — your customer wants to land in your app. Everything else about the path is
yours to copy: `turn.stopped` on a webhook, a lookup of who was waiting, a push. Nothing
in it is privileged, and the three pieces are the three you will write.

It is off unless the deployment sets `VAPID_PUBLIC_KEY` and `VAPID_PRIVATE_KEY`
(`npx web-push generate-vapid-keys`) — you need your own pair either way, because the
keypair identifies *you* to the browser's push service. Those keys must stay put:
rotating them silently invalidates every subscription already in a browser.

## Naming a conversation

`auto_title` · per-turn flag `enable_auto_title`

**Titles are empty by default, and that is deliberate.** A conversation gets a name only
if you set one or you switch this on — naming costs a model call on every new
conversation, and a client that shows no sidebar, or knows its own subject already,
should not pay for it.

Three ways to end up with a name, in the order they cost you anything:

```ts
// 1. You know what it is. Set it on the request that CREATES the session — nothing is
//    generated, so this is free.
const r = await ai.chat.send({ message, title: "Q3 close — meal penalties" });

// 2. Let the agent name it. Needs the capability; happens once, from the first message.
const r2 = await ai.chat.send({ message, enable_auto_title: true });
r2.title;            // "Meal penalty reconciliation" — on the turn that produced it

// 3. Rename whenever you like. No capability: it is your label for your own chat.
await ai.chat.sessions.rename(r2.session_id, "Week 12 payroll");
await ai.chat.sessions.rename(r2.session_id, null);   // back to no name
```

`title` comes back on the response and on the stream's `done` frame, so a sidebar can
label the row it just created without a second request. It is generated **once** — a
conversation that already has a name is never renamed behind your back, which is why
setting one up front skips generation entirely.

The name follows the conversation's language, and leaves filenames, ids and quoted
values alone: a title exists to be recognised.

### When the name is written

By default it is written from **the user's first message, as they send it** — alongside
the turn, not after it. Streaming, that arrives as its own `title` event while the answer
is still coming in:

```ts
await ai.chat.stream(
  { message, enable_auto_title: true },
  { onTitle: (name) => renameRowInSidebar(name) },   // fires mid-turn
).done;
```

`title_from: "response"` waits for the first exchange instead. It names slightly better,
having seen what the agent made of the question — but it arrives only with `done`, and
**not at all for a turn that never gets there**: a provider 429 or 500, a tool that
raised, a run the user cancelled. Those conversations keep their placeholder until someone
sends another message into them, and a chat whose first turn failed is exactly the one
that never gets a second.

```ts
await ai.chat.send({ message, enable_auto_title: true, title_from: "response" });
```

Either way it is one call, once, and a name arriving late never overwrites one you set in
the meantime.

:::note What it is not
Not a summary — one line, for finding a conversation again in a list. If you want "where
did we get to", that is the [recap](#follow-ups-and-the-recap) below, which is written
for someone coming back and is regenerated each time you ask.
:::

## Follow-ups and the recap

`followups` · `recap`

Two UI affordances generated **beside** the conversation. Neither is stored, and **the
agent sees neither** — that is the design, not an implementation detail.

```ts
// After the turn — never as part of it.
const { suggestions } = await ai.chat.sessions.followups(sessionId, 3);
// ["do the box-* ones too", "show me a diff first", "what breaks if I skip archived?"]

// When your UI decides the user has been away.
const { recap } = await ai.chat.sessions.recap(sessionId);
// "You were migrating the forfaits-* fetchers and hadn't decided about archived ones."
```

Follow-ups are written in the **user's** voice, for rendering as buttons. A clicked one
is sent as an ordinary message and the agent is not told it was suggested — an agent
that knew it had written the question would answer the one it meant rather than the one
that was asked.

The recap is for someone returning after a while. **When to ask is your call**, because
only your client knows the tab has been idle; the dashboard playground waits 90 seconds
and renders it above the composer. It is not [context compaction](./context.md), which
summarizes *for the model* and is replayed to it.

Both return empty on failure rather than erroring — a missing affordance is not worth
breaking a chat over — and **empty includes "took too long"**. Each is one model call with a
deadline (30s by default), so `suggestions: []` can mean the conversation has nowhere obvious
to go *or* that the model did not answer in time; from a client's point of view those are the
same thing, which is why they are not distinguished. Neither endpoint streams, so a bounded
call is what lets you render buttons or nothing instead of a spinner: `followups` on a
six-row conversation once ran past ten minutes, which is longer than any client waits.

Ask for them after the turn, not inside it. A turn that waited on a suggestion would make
the user wait for something they never asked for.

---

## Skills & plugins


`plugins:write` · per-turn fields `enable_plugins`, `plugins`

Your domain knowledge had exactly one home: the project's system prompt, loaded on every
turn whether relevant or not. So it grew until it was a liability, every behaviour change
was a global change, and nobody could edit what the agent does without touching the
prompt everything else depends on.

A **skill** is one procedure — how you handle a refund, how you triage a ticket — with
its own instructions and files. Skills are shipped as [Agent
Plugins](https://agent-plugins.org/), the portable format, so what you write here works
in any client that supports it.

## What a plugin looks like

```
acme-support/
├── plugin.json           # required: the manifest
├── mcp.json              # optional: MCP servers this plugin brings
└── skills/
    └── refunds/
        ├── SKILL.md      # required: frontmatter + instructions
        ├── references/   # loaded only if SKILL.md says to
        └── scripts/
```

```json title="plugin.json"
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "acme-support",
  "version": "1.2.0",
  "description": "How Acme handles support."
}
```

```markdown title="skills/refunds/SKILL.md"
---
name: refunds
description: How we issue a refund. Use whenever a customer asks for money back.
---

1. Check the order is under 90 days old.
2. Refund to the original payment method.
```

## Publishing one

Upload it in the dashboard under **Skills**, or over the API. Three shapes are accepted
and only the first is a packaged plugin.

The examples below use the **data plane** (`api.oberik.com`) with an end-user token
carrying `plugins:write`. Publishing to the whole project from your server is a
*control-plane* call with your project key — `oberik.skills.upload(...)`, or
`POST https://oberik.com/api/projects/:id/skills` with `X-API-Key`. A `pk_…` project key
is **not** accepted on `POST /plugins`; it is a control-plane credential and the data
plane answers 401.

```bash
# A packaged plugin — read as written.
curl -X POST "$BASE/plugins" -H "Authorization: Bearer $KEY" -F file=@acme-support.zip

# A single SKILL.md. This is what a first procedure actually looks like.
curl -X POST "$BASE/plugins" -H "Authorization: Bearer $KEY" -F file=@SKILL.md

# A folder of skills, each part named by its path inside the folder.
curl -X POST "$BASE/plugins" -H "Authorization: Bearer $KEY" \
  -F "files=@refunds/SKILL.md;filename=refunds/SKILL.md" \
  -F "files=@triage/SKILL.md;filename=triage/SKILL.md"
```

**A manifest is written for you when there isn't one.** Requiring a `plugin.json` — with
a `$schema` URL and a name obeying rules nobody has read — in order to publish one file
of instructions is a packaging exercise standing in front of the feature. The manifest is
what makes a plugin portable, so it still gets written; it just gets written for you, and
what is stored is a proper archive you can pull back out. Ship your own `plugin.json` and
it is never overridden.

The name comes from the skill when there is exactly one, and from the folder or archive
otherwise, cleaned into something the spec accepts.

**A skill is named by its frontmatter, not by its folder.** The spec wants the directory
and the `name:` to match and we say so when they do not — but the skill is published under
the name it declares, because that is the name the agent sees it by and the one a re-upload
replaces. This was once a refusal, which meant a skill in *any* folder failed to publish:
nobody names a folder after the skill inside it.

**What was skipped comes back in `warnings`.** A skill that would not parse, an MCP server
that was refused, a file named nearly `SKILL.md` — the upload succeeds with the rest and
names what it left out, rather than a 201 that quietly published less than you sent. Note
that a second skill is a second *directory*: a file called anything other than exactly
`SKILL.md` is an ordinary bundled file.

Re-uploading a name replaces it, so fixing a typo in a procedure is one upload rather
than a delete and an upload.

**There is no capability for USING the skills you publish.** A project that publishes a
procedure wants its agent to read it, so a toggle for that would be a switch that exists
to be found rather than decided — and a customer whose plugin was silently ignored would
have no way to discover why. Callers that want to skip or narrow them for one request
have the per-turn fields below.

## Why this is not just a longer prompt

**Progressive disclosure.** Each skill's `name` and `description` — about a hundred
tokens — are in the system prompt from the first step, so the agent knows what exists.
The instructions are loaded only when it decides a skill applies, and the bundled files
only when the instructions say they are worth reading. A hundred procedures cost about
what three do at rest.

That is why the `description` is the most important line you will write. It is all the
agent has when deciding, so name the trigger, not the topic: *"How we issue a refund.
Use whenever a customer asks for money back"* beats *"Refund policy"*.

## Who can upload

| | |
|---|---|
| **You**, with a project key (`pk_…`) | Published to the whole project. Always allowed — dashboard → Skills, `oberik.skills.upload(...)`, or `POST https://oberik.com/api/projects/:id/skills` with `X-API-Key`. |
| **Your end-users**, with their own token | Only with `plugins:write`. Private to them, unioned on top of yours. |

```ts
// From your app, with an end-user's token:
await ai.plugins.upload(file);              // a .zip or a SKILL.md
await ai.plugins.uploadFolder(             // a directory picker's files
  [...input.files].map((f) => ({ path: f.webkitRelativePath, content: f })),
);
await ai.plugins.list();                    // the project's, plus theirs
```

An end-user's plugins are visible exactly the way their documents are — the same rules,
the same scoping — because a plugin is a thing a person uploaded and there is no reason
it should behave differently. Only a project key can publish to everyone: one end-user
changing how the agent behaves for the whole workspace is not a thing to leave to a
capability toggle.

## Choosing per turn

```ts
await ai.chat.send({ message: "...", plugins: ["acme-support"] });
```

Omit it and the agent gets everything the token can see. It narrows only, and a name
that is not visible is simply absent rather than an error — a pinned list should not
start failing turns the day somebody deletes a plugin.

## MCP servers in a plugin

`mcp.json` is loaded and its servers join the project's own, through the same allow-list
gate every other tool goes through.

**`stdio` servers are refused.** A stdio server is a command line, and a plugin may have
come from a file an end-user uploaded — running one would be arbitrary execution on the
host with none of the sandbox's isolation. The refusal is reported on the plugin rather
than silent, because a plugin whose tools never appear and never says why is the failure
people spend an afternoon on.

A skill's `scripts/` are fine: they are files the agent may run *in the sandbox*, under
the same capability and path rules as anything else it writes there.

---

## Subagents


`subagents` · per-turn flag `enable_subagents`

The agent can hand a self-contained piece of work to another agent that runs beside it,
and carry on. A sweep across nine files, an independent verification of a conclusion,
six unrelated lookups at once — work that is genuinely separable and long enough to be
worth the hand-off.

It is the same promise a [background command](./sandbox.md) makes, one level up: the
agent starts something, keeps working, and is told when it comes back. If the turn ends
first, the report lands in the next one — or starts one, so "I'll tell you when it's
done" doesn't depend on the user still being there.

## Turning it on

Two things, and it needs both:

1. **The capability**, in Project → Capabilities. Each subagent is another model loop
   billed to you, so this is a spending decision as much as a permission — and it is a
   capability precisely so a token that should not be able to multiply its own cost
   doesn't carry it.
2. **The models**, in Project → LLM & limits → *Subagent models*. A subset of your
   generation models, and — beside them — how many may run at once. With the capability
   on and no models chosen, the agent gets no subagent tools at all: a tool whose only
   possible answer is "the project configured nothing" is worse than its absence,
   because the agent plans around it.

Picking a *subset* is the point. Delegated work is usually the cheap half of a
conversation, and pinning it to a smaller model is how a fan-out stays affordable. Pick
more than one and the agent chooses per task from exactly that list; pick one and it
never sees the choice at all.

## Watching them

```ts
const done = await ai.chat.stream({ message: "audit every fetcher for retry handling" }, {
  onSubagents: (agents) => render(agents),
});
done.subagents;
```

`onSubagents` fires whenever one starts, moves, asks the main agent something, or
finishes — and always with **every** subagent of the conversation, not just the one that
moved, so render from the list and a dropped frame cannot leave your panel wrong.

Each carries a `ref` (`a1`, `a2`, … — stable for the conversation), the `task` in the
main agent's words, and a `progress` line of four or five words:

```
a1  audit services/api           running   searching the code: retry
a2  audit services/worker        running   reading a file: fetch.py
a3  check the shared http client finished  reported back
```

`progress` is written from what the subagent is actually doing rather than asked of the
model, so it stays live under load — which is exactly when someone is watching it. Use
`steps` for movement when the phrase itself doesn't change.

A subagent that is still `running` when the turn ends **is still running**. Keep showing
it; it reports into the next turn.

:::caution The turn can finish before its delegates do

When that happens the turn carries `finish_reason: "subagents_incomplete"`, and the
`turn.stopped` webhook reports the same with `complete: false`. Nobody is waiting — the
turn is over — but the answer was written without part of what it asked for.

Check it before rendering a reply as final:

```ts
if (done.finish_reason === "subagents_incomplete") {
  const waiting = done.subagents.filter((a) => a.status === "running");
  banner(`Still working: ${waiting.map((a) => a.task).join(", ")}`);
}
```

The main agent is told the same thing and is instructed to say which part is missing
rather than fill it in, but the flag is what your UI should key on.

`status` on each entry is authoritative, and there are five:

| `status` | Meaning |
|---|---|
| `running` | still working |
| `finished` | done; `result` holds what it reported |
| `failed` | could not do the work; `error` says why |
| `stopped` | cancelled, by `subagent_stop` or by the turn ending |
| `delivered` | **terminal.** Finished *and* already reported to the main agent |

`delivered` is the one worth knowing about. A completed delegate is claimed once, so that
its result is handed to the orchestrator exactly once — reported twice and the agent
reasons about work that only happened once. After that claim the row reads `delivered`,
so **treat it as terminal alongside `finished`, `failed` and `stopped`**: a UI that keys
only on `finished` shows a delegate as unfinished forever. The outcome it had is
preserved, so `error` still tells you whether it succeeded.

:::

### Their conversations are not in your session list

A delegate gets a real conversation — that is what gives it a transcript, a plan and a
context budget of its own — but it is a conversation nobody had, and the only part of it
anyone else needs is the `result` at the end. So `chat.sessions.list()` leaves them out:

```ts
await ai.chat.sessions.list();                                  // your users' chats
await ai.chat.sessions.list(undefined, { includeSubagents: true });  // and the delegates
// both answer { items, has_more, next_offset } — a page, not the whole set
```

Every row carries `parent_session_id` — null for an ordinary conversation, the delegating
turn for a delegate — so a client that does ask can tell them apart, and you can get from
a delegate back to what started it.

Going the other way is one field, not a search: **a `subagents[]` entry carries
`session_id`**, so a client holding a subagent event can read that delegate's transcript
directly with `chat.sessions.messages(session_id)`. Do not use `id` for this — it
identifies the delegate record and 404s on the session routes, which is exactly the wrong
turn a developer takes first. Their titles are a short label (`Delegate: …`), not
the task: a delegated prompt routinely carries file paths and the wording used to steer
it, which is not something to put in an end user's sidebar.

## What a subagent can and cannot do

It runs with your project's capabilities, on your corpus, with the same tools — that is
what makes it a delegate rather than a second, weaker product. Four things are withheld,
and the main agent cannot grant them back:

| Withheld | Why |
|---|---|
| `remember`, `wiki_write` | Nothing durable. A delegate writing to your project's memory puts something there that the agent answerable for the conversation never saw and cannot correct. It says so in its report instead, and the main agent decides. |
| `send_file` | It would hand your user a file nobody reviewed. |
| `ask_user` | There is no user on the end of a delegate's turn. It asks the main agent instead (below). |
| `subagent_*` | One level deep, so a fan-out's cost is bounded rather than exponential. |

Reading is not writing: a subagent still has `recall`, `wiki_read` and retrieval over
the same documents.

## Narrowing one

The main agent may hand a subagent less than it has itself — never more:

- **`workdir`** — confine it to a sub-directory of the sandbox workspace. Subagents
  share the conversation's sandbox, so this is a part of the same tree the main agent
  works in — which is also what lets it read what they produced. Enforced by the same
  path resolution every sandbox tool already goes through, so `../` gets a refusal
  rather than a surprise.
- **`network: "none"`** — takes away web search and the browser. This is an honest claim
  about the *agent's* reach, not about the sandbox's: commands still run in the same VM
  under your deployment's egress policy, so a subagent with `network: "none"` and shell
  access can still `curl`. Use the sandbox's own [network mode](./sandbox.md) for a
  guarantee.
- **`tools`** — an explicit allow-list, intersected with what the main agent holds.

## Waiting

The agent gets a `wait` tool wherever it can start work that outlives a tool call. It
blocks for up to two minutes and returns the moment a subagent or background command
finishes, so the agent stops when the work does rather than at the end of a timer.

Without it the agent polls, and each poll is a full model round-trip that learns
nothing — in one transcript, eight consecutive `subagent_check` calls, which is what a
user sees as the chat looping.

## When it asks

A subagent that is genuinely blocked on a decision only the main agent can make uses
`ask_parent`, which stops its work until answered. The main agent is told at its next
step and answers with `subagent_answer`; if it has no answer either, it says so and the
subagent proceeds on its own judgement and reports what it assumed.

There is nothing for your UI to do here — this is one agent talking to another — but
`question` is on the subagent's state so you can show it rather than a status line that
has silently stopped moving.

## Limits

| | | |
|---|---|---|
| Running at once, per conversation | **yours** | Project → LLM & limits → Subagent models. Clamped against the deployment's maximum (4 by default) — you can ask for fewer, never more. Blank uses the deployment's. |
| Agent↔tool steps per subagent | 40 | Operator setting. A delegate that has taken fifty steps has misunderstood its brief and should report what it has. |
| How long one waits for an answer | 15 minutes | Operator setting. Past it the subagent proceeds on its own judgement and says what it assumed. |

The first is the one worth thinking about: every subagent running is a turn's worth of
tokens in flight, so it is the knob that decides what a fan-out costs.

Subagents run as durable workflows, so a deploy or a worker dying moves the work rather
than losing it — the report arrives late rather than never. Where a deployment has no
scheduling they run in the API process instead and a restart does end them; those are
reported as failed with the reason rather than left saying `running` forever.

---

## Sandboxed compute


With the `computer` capability the agent gets an isolated Linux sandbox: it can run commands,
read and edit files, transform a spreadsheet, build and test code, then hand the result back
as a download. State persists across turns in a conversation, and the sandbox pauses when
idle so you don't pay for a machine nobody is using.

## Enable it

1. **Capabilities**: turn on *Computer / sandbox* for the project.
2. **Token**: include `computer` in the capabilities you mint. Leave it out and the tools
   don't exist for that user.
3. **Request**: `enable_computer` defaults to `true`; pass `false` to decline it for a turn.

That's it — there is no backend to choose, no credentials to paste and no machine spec to
fill in. Every project on the platform gets the same isolated Linux machine, and
**Dashboard → Computer** shows you what it is and what's running.

A sandbox is only provisioned if the agent actually reaches for it — enabling the capability
costs nothing on turns that don't use it.

## What the machine is

A microVM of its own per conversation: its own kernel, its own disk, nothing shared with
another customer or another end-user. The agent is root on it, with a working `sudo`.

| | |
|---|---|
| Linux | Ubuntu 24.04, `/workspace` as the working directory |
| Python | numpy, pandas, scipy, matplotlib, pillow, openpyxl, requests, beautifulsoup4, lxml, uv |
| Node | node + npm |
| Documents | pandoc, LibreOffice, poppler, qpdf, ghostscript, tesseract + ocrmypdf, typst |
| Media | ffmpeg, sox, ImageMagick, libvips, the image optimisers, yt-dlp, exiftool |
| Development | clang/gcc, cmake, ninja, gdb, git, sqlite3, psql/mysql/redis clients |
| Shell tools | ripgrep, fd, fzf, jq, yq, dasel, bat, eza, tree, the archivers |
| Resources | 2 vCPU, 2 GiB RAM, 8 GiB disk |

Anything missing, the agent installs itself: `sudo apt-get install -y <it>` works, and the
change stays in that conversation's workspace.

## What the agent can do

| Tool | |
|---|---|
| `computer_bash` | run a shell command (state persists between calls) — output streams to you as it appears, and it can run in the background |
| `computer_jobs` | check on or stop a command running in the background |
| `computer_read_file` / `computer_write_file` | read (with line offset/limit) and write text files |
| `computer_edit_file` | replace an exact string, with an ambiguity check |
| `computer_list` / `computer_glob` / `computer_grep` | explore the workspace |
| `computer_fetch_document` | copy one of your uploaded documents in, **whole** — by filename or id |
| `computer_fetch_attachment` | copy a file already in the conversation in — one it generated, one you uploaded, one it exported earlier |
| `computer_export_file` | bring a sandbox file into the conversation — `send_file` is what hands it to the user |
| `computer_view_file` | *look at* an image in the sandbox to check its own work |
| `computer_expose_port` | publish a port at a URL (only where the deployment supports it) |

## Long commands

Two things make a slow command bearable, and both are automatic.

**You see the output as it happens.** While a command runs, its output arrives on the
stream as `command_output` chunks, grouped by `command_id`. Append them to a pane and a
five-minute test run looks like a test run instead of a hang:

```ts
await ai.chat.stream({ message: "run the test suite" }, {
  onCommandOutput: ({ command_id, delta }) => appendToPane(command_id, delta),
  onToken: (_d, full) => setAnswer(full),
});
```

**Really long work runs in the background.** The agent can start a build and keep working;
when it finishes, the agent is told and carries on. You get a `command_finished` event if
the turn is still going — and if it had already ended, the result arrives as a **new turn
in the same session**, exactly like a scheduled run, so it reaches the user through
whatever you already do with those (including the `turn.stopped` webhook if the tab is
closed). Nothing to poll.

`computer_view_file` is the one worth knowing about: after rendering a chart the agent can
open the PNG, see it, and fix it before showing the user — instead of describing a file it
never looked at.

## It reads before it writes

Both writers refuse a file the agent hasn't read: `computer_edit_file` for a file it has
never seen, `computer_write_file` for an existing file it hasn't seen *in full* — that one
replaces everything, including whatever it didn't look at. And both refuse again if the
file changed since it was read, because a command it ran, a background job or your own
user may have written to it in between; the agent reads it again and works from what is
actually there.

**"Hasn't read" means in the current turn.** The record of what the agent has looked at is
scoped to one turn, deliberately: the guarantee is not that somebody looked at the file
once, it is that its current contents are in front of the model as it decides — and across
turns they may have scrolled out of the window or been compacted away. So the agent re-reads
before editing on a later turn. That costs one tool call and is the whole reason the guard
catches a file that changed while nobody was looking.

You don't configure this and there is nothing to handle: it costs the agent a `read_file`
call, and it is what stops a confident edit from quietly deleting a paragraph nobody knew
was in the file.

A worked example — the agent pulls a document in, computes what it needs, plots it, checks
the result, and hands it over:

```
computer_fetch_document  bookings.csv     # a document from the corpus, into the sandbox
computer_write_file  data/revenue.csv
computer_bash        python plot.py        # matplotlib → out/chart.png
computer_view_file   out/chart.png         # look at it before claiming it's done
computer_export_file out/chart.png         # into the conversation, as kind: "image"
send_file            <id from the export>  # ...and now the user has it
```

That last line is not optional. Exporting stages the file; `send_file` delivers it. The
separation is deliberate — see [Files](./files.md#producing-a-file-and-sending-one) — and
leaving it out is a silent failure: the export succeeds, the file is really there, nothing
errors, and `attachments` comes back empty.

:::tip Totals need the whole file, not search results

`rag_search` returns the passages that *matched* — a ranked fragment, never the whole
document. So for anything that depends on all of a file (a total, a count, a sum, a
maximum, any per-row arithmetic) the agent must `computer_fetch_document` it and compute
in the sandbox.

It is told this, and the retrieval results say it too. Worth knowing anyway, because the
failure is silent when it goes wrong: arithmetic over a fragment produces an exact-looking
number that is simply short, with a row count and a filename that make it read as
verified. If you have a domain where this matters, a [skill](./skills.md) naming the
procedure is the strongest guarantee available.

:::

One thing to get right for this to work: aggregate in SQL rather than pulling raw rows — only the result
preview passes through the agent, so `group by` beats fetching 10,000 rows to sum them
in Python.

## Files, both directions

**In.** Attach a file with `to_sandbox` and the **original bytes** land in the workspace
instead of being extracted to text for the model. That's what you want for data files:

```ts
await ai.chat.send({
  message: "Clean this export and give me a per-region summary as CSV",
  attachments: [{
    kind: "file",
    name: "sales.csv",
    url: `data:text/csv;base64,${b64}`,
    to_sandbox: true,
  }],
});
```

The agent is told the path it landed at. Already-uploaded documents don't need re-sending —
the agent copies them in itself with `computer_fetch_document`.

**Out.** Anything the agent hands over arrives on the normal channel: `res.attachments`, or
the `attachments` stream event — which now fires the moment the file is produced, so a
download or a screenshot appears next to the step that made it rather than after the agent
has finished talking.

```ts
res.attachments;
// [{ kind: "file",  url, name: "summary.csv", mime_type: "text/csv",  size: 8213 },
//  { kind: "image", url, name: "chart.png",   mime_type: "image/png", size: 41022 }]
```

`kind` follows the file's type, so a chart the agent rendered arrives as an `image` your
UI can show inline rather than a download card — while a CSV or a zip stays a `file`.
URLs are signed and short-lived; download the bytes if you need them permanently.

A rendered chart also comes back into the *next* turn, so "same chart, but log scale"
works without re-deriving it.

## Sessions

Each sandbox is a session with a stable id. By default one is bound to the chat session, so a
conversation keeps its workspace; pass `computer_session_id` to attach a specific one
instead — that's how you reconnect a user to work from yesterday.

```ts
const s = await ai.computers.create();                      // start one explicitly
await ai.computers.upload(s.id, file, "inbox/data.csv");     // push a file in
await ai.chat.send({ message: "Summarise inbox/data.csv", computer_session_id: s.id });
await ai.computers.pause(s.id);                              // stop paying while idle
await ai.computers.resume(s.id);                             // same workspace, later
await ai.computers.destroy(s.id);
```

```ts
await ai.computers.list({ include_stopped: false });
await ai.computers.exec(s.id, { command: "ls -la", timeout_s: 30 });
await ai.computers.download(s.id, "out/summary.csv");        // -> Blob
```

Paused sandboxes resume with the workspace intact, and you rarely need to pause one by hand:
an idle sandbox does it itself, in stages.

| idle for | what happens | what coming back costs |
|---|---|---|
| 1 minute | it sleeps — memory written to disk | nothing you can feel: it wakes exactly where it was, processes and all |
| 5 minutes | memory is dropped, files kept | a boot (about a second); running processes are gone, the workspace isn't |
| 10 minutes | the disk moves to object storage | a few seconds while it comes back |
| 7 days | it's deleted | a fresh workspace |

A sandbox running a command is never put to sleep, however long the command takes. And if a
sandbox has genuinely gone, the next tool call recreates it rather than failing the turn.

## Isolation and limits

A sandbox reaches the public internet — it can fetch a page, install from any registry,
call an API you point it at. What it cannot reach is anything private: the platform's own
services, its own network, another sandbox. That boundary is enforced on addresses rather
than hostnames, so there is no allowlist to keep up to date.

It also cannot **resolve** them. The sandbox's resolver asks public DNS and never the
deployment's own — otherwise a sandbox could look up the platform's internal service names
and read its topology off the answers, which the address filter would block it from
*reaching* but had already told it about. IPv6 is dropped outright, since a VM here is
IPv4-only by construction and an unfiltered v6 packet is traffic no policy was written for.

The defaults:

| Limit | Default |
|---|---|
| working directory | `/workspace` — every path is confined here |
| CPU / RAM / disk | 2 vCPU, 2 GiB, 8 GiB per sandbox |
| per-command timeout | 5 minutes by default; up to your project's limit (30 min ceiling), then it's killed |
| command output | 30,000 characters, then explicitly truncated — whatever the command printed |
| file read/write/export | 20 MB |
| concurrent sandboxes | your project's setting; 10 by default |

### How long a command may run

Two of those numbers are yours, not the deployment's:

```ts
await oberik.computer.set({ execTimeoutS: 120, maxSessions: 2 });
await oberik.computer.get();   // { execTimeoutS: 120, maxSessions: 2 }
```

`execTimeoutS` is the project's own **default** for one command — the figure
`GET /computers/host` reports as `exec_default_timeout_s`, which is why that page tells
you to read it rather than hard-code five minutes. `maxSessions` is how many sandboxes
this project may hold at once. `null` on either means the deployment's own.

Both are **clamped at the point of use, not on the way in**, and that distinction is worth
knowing: `computer.set({ execTimeoutS: 18000 })` stores 18000 and `computer.get()` reads it
back, while a command on a host whose maximum is 1800 is killed at 1800 and says so
(`[command timed out after 1800s]`). So the number you stored is what you asked for, and
`exec_max_timeout_s` on `GET /computers/host` is what you will get — read both if you are
sizing your own client's timeout.

Paths are validated server-side, so `../../etc/passwd` is rejected before it reaches the
sandbox — the model's arguments are never trusted. Isolation is a virtual machine with its
own kernel, not a shared container: there's no host mount, no Docker socket, and neither your
provider keys nor the JWT secret are ever placed inside it. Every command, write and export
is recorded in the audit log.

One thing to keep in mind: **sandbox output is untrusted input**. A file the agent downloads
could contain text aimed at the model. It comes back as a tool result, never as instructions,
and guardrails still screen the final answer — but treat sandbox-derived content the way you'd
treat user-supplied content in your own app.

## Read-only sandboxes

Because the sandbox tools go through the same per-tool gate as everything else, you can hand
out a look-but-don't-touch workspace with no extra machinery:

```ts
await ai.chat.send({
  message: "What's in the workspace?",
  allowed_tools: ["computer_list", "computer_read_file", "computer_grep", "computer_glob"],
});
```

---

## Files, images & generated media


Modalities are capabilities, granted per token: `input:image`, `input:audio`,
`input:video`, `input:file` and `output:image`, `output:audio`, `output:video`,
`output:file`. Anything not granted is ignored rather than trusted.

You don't list them when you [mint](./authentication.md#capabilities): a token gets
whatever the project's toggles allow. Pass an `output:<kind>` only to narrow that side
— to stop the agent sending images to a client that can't render them, say — and the
other side is untouched either way.

## `file` is about access. The rest are about the model's senses.

This is the whole model, and getting it backwards is the one mistake worth avoiding.

| | `file` | `image` · `audio` · `video` |
|---|---|---|
| **Input** | a user may attach **anything**, of any type. What the model can't perceive is read as text — extracted where there is a text layer, OCR'd where there is not, a transcript for a recording. | the model may look at that kind **with its own senses**, raw. |
| **Output** | the agent may hand back **any file it produced** — a document it wrote, a sandbox export, a screenshot. | the model may **generate** that kind. |

So:

- `input:file` alone is enough for a photo upload. The picture is accepted and read with
  your project's OCR engine (see [Documents](./documents.md#how-a-file-is-read)),
  and the agent works from the text. Add `input:image` when you want the model to
  actually *see* it — the difference between reading the words on a receipt and being
  able to say the logo is crooked.
- `output:file` alone is enough for the agent to send you a screenshot it took or a
  chart it rendered in a sandbox. Those are files it **produced**, not modalities it
  **emitted**. `output:image` is for the model drawing a picture itself.

`file` therefore needs no multimodal model on either side — extraction and delivery are
plain machinery — which is why it's the one modality every project can grant, and why a
new project **starts** with `input:file` and `output:file`. See [Files](./files.md) for
what the agent does with them once they exist.

The media kinds are filled in the moment you register a model that can handle them:
`provider add` seeds the project's input modalities from what the models can perceive, so
a vision model arrives with `input:image` rather than leaving a project that will not
accept a photo.

:::caution A self-hosted model's senses are guessed from its name
"What this model can perceive" comes from the provider's catalog where there is one, and
otherwise from the model's **name** — which is chosen by you and tells us nothing. So a
self-hosted vision deployment called `hukuk-db` is recorded as text-only, the project's
ceiling follows, and granting `input:image` is narrowed straight back out. The refusal an
end-user sees then names a capability whose switch appears not to work.

Correct the record on the provider credential and the grant holds:

```bash
curl -sX PATCH "$CP/api/projects/$PID/providers/$CRED_ID" \
  -H "X-API-Key: $KEY" -H 'content-type: application/json' \
  -d '{"modelFacts":{"hukuk-db":{"input":["text","image"],"output":["text"],"mode":"chat"}}}'
```

It is a merge, so sending only `input` is enough, and it is recorded as **your** answer —
`provider refresh` re-derives everything else from the catalog and leaves this alone.
`capabilities set` says so too when it narrows a grant away: it names the model whose facts
were guessed and the request that fixes it.
::: Output media is never granted for you — generating a picture is a spend
decision, and adding a provider is not making it. Clearing a list is respected: an
explicit empty list is a project saying "no attachments", and nothing fills it back in.

**The media modalities are bounded by your models.** The dashboard reads what each
registered model can take and produce, from the provider's own catalog, and one none of
them supports cannot be switched on. A project whose only model answers in text will
find `output:image` struck through: granting it would mint a capability on every token
the agent then refuses to honour, with nothing on screen explaining why. `input:image`
struck through does not stop your users attaching pictures — that's `input:file`, and it
stays available.

### Self-hosted models

Most catalogs answer "what models are there" and nothing else — OpenAI's `/v1/models`
publishes four fields, and every server speaking its shape (vLLM, LM Studio, LocalAI,
your own gateway) publishes the same four. So a model is identified in as many ways as
there are:

1. **what the provider says** — modalities, where it publishes them;
2. **the real model behind the name** — vLLM reports `root` alongside a
   `--served-model-name`, so a model registered as `house-model` is still recognised as
   the `Qwen/Qwen2.5-VL-…` it actually is;
3. **the published model index**, matched on the model's own name rather than on who is
   selling it — the same open-weights model has an entry under every provider that hosts
   it, and none under a server you run yourself.

**When none of them knows, the dashboard says so and asks you.** A private fine-tune is
not described anywhere, and no amount of inference will change that. The model keeps a
text-in/text-out floor so it works, the provider form flags it, and you tick what it
actually takes and returns — one row per unidentified model, with what it is *for*
(chat, embedding, rerank) beside it and a line saying what that choice will do. Your
answer is kept as an answer: re-listing the catalog will not derive over it.

**Every model stays editable, not only the unidentified ones.** A served model name is a
label, and the model behind it can be swapped out from under it — so a catalog that was
right in March is not evidence about today. Models the catalog described are one click
away under *Adjust*, in the same provider form.

That is what bounds the modalities your project can grant, so an unticked box is a
capability your users won't get.

## Sending things in

Attach a file when it's context for *this* question, rather than something to index
permanently.

```ts
await ai.chat.send({
  message: "What changed between these two invoices?",
  attachments: [
    { kind: "file", name: "march.pdf", url: `data:application/pdf;base64,${b64(march)}` },
    { kind: "file", name: "april.pdf", url: `data:application/pdf;base64,${b64(april)}` },
  ],
});
```

An attachment is `{ kind, url, name?, mime_type? }` where `url` is a `data:` URI or an
`https://` URL. Images go to the model as images; documents a model can't read natively are
extracted with the same layout-aware pipeline used for uploads. Nothing is added to the
knowledge base — use [Documents](./documents.md) for that.

Prefer an `https://` URL for anything large, and `to_sandbox: true` when the file is data for
the agent to *process* rather than *read* (see [Sandboxed compute](./sandbox.md)).

```ts
attachments: [{ kind: "image", url: signedUrl, name: "chart.png" }]
```

To attach something already uploaded, hand over a signed URL for it rather than re-sending
the bytes:

```ts
const { url } = await ai.documents.downloadUrl(doc.id);
await ai.chat.send({ message: "Read the chart on page 3", attachments: [{ kind: "file", url }] });
```

Though for indexed documents the usual answer is simply to let retrieval find them —
`tags` / `document_ids` on the request, no attachment at all.

## Getting media back

Ask for a modality and the answer comes back as an attachment:

```ts
const res = await ai.chat.send({
  message: "Draw a clean diagram of this pipeline",
  output_modalities: ["image"],
});

res.attachments;   // [{ id, kind: "image", url, name, mime_type, size }]
```

Pass `model` to choose a generation model; the token's model allow-list still applies. Media
generation is exclusive for the turn — the agent produces the asset rather than calling tools,
so do retrieval on one turn and generation on the next if you need both.

:::danger A generated image is not grounded in anything
That exclusivity is not only a sequencing inconvenience. Because no tools run, the turn does
**no retrieval** — so the picture is drawn from the model's own knowledge, and the output
groundedness check has no context to judge it against even when it is switched on.

Asked for a diagram of four SLA tiers, a project whose corpus says 24 hours / 3 days / 14
days / 90 days got a clean, confident PNG labelled "1 hour / 4 hour / 12 hour / 24 hour".
`content` came back `""` and `guard_flags` was `[]`: nothing on the response hints that the
numbers were invented.

**Never generate an image of your own data in one step.** Retrieve the figures on one turn,
check them, then ask for a diagram *of those figures* on the next — the values you pass in
are the only thing keeping the picture honest. Treat a generated image the way you would
treat an uncited sentence.
:::

While streaming, files arrive on the `attachments` event as soon as they are produced —
right after the tool call that made one — and again before `done` with the full list. Every
frame carries the whole list so far, so render from it rather than appending and a missed
frame cannot leave a gap.

**Match on `id`, not on `url`.** A URL is signed with an expiry, so it is a handle with a
lifetime rather than an identity: do not persist one, and do not compare two. The `id` is
stable for the life of the file and is what the tools take.

Why that is not just tidiness, since the reason used to be given wrongly here: every
response re-signs the URL, but an S3 signature is deterministic given the same key, expiry
and timestamp — and the timestamp is granular to the second. So the stream event and the
response that follows it usually carry a byte-identical URL, and carry different ones when
they happen to land either side of a second tick. Keying on the URL works nearly every
time, then shows one file twice — the version of this bug that is hardest to reproduce and
so hardest to ever get reported.

## Reusing what was generated

Generated media is stored, not discarded, and a URL is signed with an expiry rather than
kept. That's what makes two expected things work.

**Follow-up edits.** The previous image is put back in front of the model on the next turn, so
revision prompts have the original to work from:

```ts
const first = await ai.chat.send({
  message: "A wide banner, dark background, violet accent",
  output_modalities: ["image"],
});

await ai.chat.send({
  session_id: first.session_id,
  message: "Same, but make the accent teal",
  output_modalities: ["image"],
});
```

**Piping into the sandbox.** With the `computer` capability the agent copies an image it
generated into the workspace (`computer_fetch_attachment`) and processes it there — crop it,
convert it, drop it into a report — then exports the result as a download.

## Files the agent produced

Anything exported from a sandbox rides the same channel — `res.attachments`, or the
`attachments` stream event — with a `kind` matching its type. So a chart the agent
plotted is an `image` you can render inline, while a report or a zip stays a `file`:

```ts
// [{ id: "9a50d2717488", kind: "image", url, name: "chart.png", mime_type: "image/png", size: 41022 },
//  { id: "c17f0e42aa10", kind: "file",  url, name: "summary.csv", mime_type: "text/csv", size: 8213 }]
```

Rendered images also come back into the next turn's context, so "same chart, log scale"
doesn't start from scratch. See [Sandboxed compute](./sandbox.md).

Signed URLs expire. Show them or download them; don't persist them in your own database —
store the `id` if you need to refer to a file later, and it is also what the file-taking
tools accept.

## A note on PII

By default the model receives attachment content verbatim — on a "talk to your own data"
product, the user is deliberately sharing their own information. If your compliance posture
requires otherwise, PII redaction is available per project under
[Guardrails](./guardrails.md).

---

## Scheduling & memory


## Scheduled work

With `tasks:write`, work can be scheduled to run later — once, on a cron, or on an interval.
Schedules are durable: they survive restarts and deploys and run whether or not anyone has a
session open.

```ts
await ai.tasks.create({
  name: "weekly-finance-digest",
  kind: "recurring",
  cron: "0 9 * * MON",
  timezone: "Europe/Istanbul",
  action: {
    type: "agent",
    prompt: "Summarise this week's new documents tagged finance",
    callback_url: "https://app.example.com/hooks/oberik",
  },
});
```

Two `kind`s and two `action` types:

| | |
|---|---|
| `kind: "once"` | needs `run_at` (ISO-8601) |
| `kind: "recurring"` | needs `cron` **or** `interval_seconds` |
| `action.type: "agent"` | runs a turn: `prompt`, optional `session_id`, `system_prompt`, `model`, `callback_url` |
| `action.type: "webhook"` | calls you directly: `url`, `method`, `headers`, `payload` |

### When a schedule is refused

A `cron`, `timezone` or `interval_seconds` the scheduler will not accept is answered **400**
with its own diagnosis — these are worth reading, they are specific:

```
Invalid schedule spec: Minute is not in range [0-59]
Invalid schedule spec: CronString does not have 5-7 fields
Invalid schedule spec: unknown time zone Mars/Olympus
Invalid schedule spec: interval is too small
```

Do not retry any of these: no number of attempts makes `99 3 * * *` a valid cron. A 5xx from
this endpoint means the scheduler itself was unreachable, which *is* worth retrying — that
split is the point of the status.

`cron` accepts 5 to 7 fields, so second- and year-precision expressions work as well as the
usual five. `timezone` is an IANA name; leaving it blank means `UTC`.

Once a recurring task is accepted, `next_run_at` tells you when it actually fires next, in
UTC. It is never null on a task reporting `scheduled`.

An `agent` action with a `session_id` continues an existing conversation, which is how "remind
me about this thread on Friday" works. With `callback_url`, the completed run is POSTed to you;
without one, poll for it — and `last_session_id` on the task is where the answer went:

```ts
const task = await ai.tasks.get(id);
if (task.status === "completed" && task.last_session_id) {
  const messages = await ai.chat.sessions.messages(task.last_session_id);
}
```

Not `action.session_id`, which is the session you *asked* for — a task that named none has
null there forever. `last_session_id` is null before the first run, for a `webhook` action,
and after a run that failed (`last_error` says why).

### "completed" means the work got done

A one-shot has three outcomes, not two:

| `status` | what happened | `last_error` | `last_finish_reason` |
|---|---|---|---|
| `completed` | the turn ran and finished | null | null |
| `incomplete` | the turn ran, nothing broke, and the work did not get done | null | why — see below |
| `failed` | it broke | the reason | possibly null |

`incomplete` exists because of a case worth knowing about before you build on this. A
scheduled run whose prompt needs an approval calls the approval tool, nobody is there to
answer, and the turn stops — so a task told to archive a record asks permission into an
empty room and stops. That used to report `status: "completed"`, `run_count: 1`,
`last_error: null`: identical to a run that did the work, when the work is the whole point.

`last_finish_reason` says which way, in the same words `turn.stopped` uses:
`needs_input` (waiting on a person — an approval, a client tool, a question),
`max_tool_iterations`, `no_answer` (the turn produced nothing at all), `guardrail`,
`subagents_incomplete`. It is set on recurring tasks too, where the status stays
`scheduled` and this is the only record of how the last fire went.

**Anything that pauses cannot be answered by a scheduled run**, so a task that needs a
person is a task that will not finish. `ask_user` is withheld from unattended runs for
that reason; approvals are not, because continuing without a *permission* is the one thing
worse than stopping. Design the prompt so it does not need one, or handle the pause
out-of-band from the `turn.stopped` delivery.

You do not have to go looking for it. `GET /readiness` carries a `tasks-waiting` step
whenever any task's last run ended `needs_input`, naming the task, when it stopped, and the
session holding the question it asked. It is read off that one finish reason rather than
off a list of the things that can pause, so an approval, a client tool, a question and a
browser hand-off all raise it. `GET /api/projects/:id/tasks?status=incomplete` is the
direct read.

It is deliberately **not** `essential`: the project answers questions perfectly well, it is
the scheduled work that stopped. And note that a **recurring** task in this state stays
`scheduled` and stalls again on every fire — which is why the check does not filter on
status.

The delivery is signed with the project's webhook secret, exactly like `turn.stopped`:

```jsonc
POST <callback_url>
X-Signature: sha256=…        // same key and scheme as turn.stopped — one verifier does both
X-Delivery-Id: …             // stable across retries of the same fire; deduplicate on it
                             // (outbound only — inbound events use X-Event-Id, see below)
{
  "event": "scheduled_task.fired",
  "task_id": "…", "tenant_id": "…", "session_id": "…",
  "message": "the agent's reply"
}
```

See [Verifying a delivery](./working-together.md#verifying-a-delivery) for the verifier
and where to get the key. `model` here is a model name your project has registered — the
same names `providers` lists.

```ts
await ai.tasks.list("scheduled");   // or omit for all; "cancelled" once cancelled
await ai.tasks.get(id);       // run_count, last_run_at, next_run_at, last_error
await ai.tasks.cancel(id);
```

The agent can also schedule its own reminders mid-conversation via `schedule_reminder` /
`cancel_reminder` / `list_reminders`, gated by the same capability.

### Relative times

"Remind me in ten minutes" doesn't require the agent to know the clock: `schedule_reminder`
takes a duration (`in_seconds`, or a phrase like `in 2 hours` / `1h 30m`), which is exact
regardless of what the model thinks the time is. Absolute ISO timestamps still work for a
specific clock time.

A `current_time` tool ships alongside these, so the agent can read the exact time when it
needs it — the timestamp in its prompt goes stale during a long turn. An unreadable time is
reported back to the agent rather than silently dropped, so it retries instead of telling
your user a reminder exists when it doesn't.

Every task runs as the subject that created it, with that subject's visibility — a scheduled
run can never see more than the user could see themselves. `last_error` is where a failed run
explains itself; `next_run_at` tells you the schedule is alive.

## Memory

With `memory`, the agent keeps facts across sessions — "I'm in the EU", "we call them
workspaces, not projects" — and recalls them when relevant, via `remember` / `recall`.

**Memory is scoped to the token's `subject`, and only to that.** One user's memories never
reach another user's answers — not a colleague's, not a team lead's, not an admin's. The
`scope` claim, which widens what *documents* a token can see, has no effect here: a token
with `subject: "acme:fin:lead"` and `scope: "acme:fin"` reads every document in finance
and exactly one person's memories, its own.

That asymmetry is deliberate. A document belongs to a team; a memory is something a person
told the assistant, and "my reports can see the team's files" is a different decision from
"my assistant may repeat what my reports said in confidence". If you want a fact available
to everyone, that is what the [wiki](#per-user-or-project-wide) is for.

There is also a **wiki** (`wiki_write` / `wiki_read`): updatable topic pages the agent
curates, for things learned once and worth reusing — conventions, glossaries, findings.

:::caution Memory needs an embedding model
All four tools store and find text as vectors, so a project with no **embedding model**
configured cannot remember or recall anything — the same dependency
[document ingest](./documents.md) has. When there is none, the family is not bound at all
and the agent is told to say so rather than agree to remember something and keep nothing.

`GET /readiness` lists it as `embedding-model` and names memory, recall and the wiki among
what it blocks. It is **not essential** there, and that is deliberate: `essential` means a
step stops the project answering at all, and it feeds `canAnswer` — the boolean the
[quickstart](./quickstart.md) tells you to gate a deploy on. A project whose memory has no
embedder answers questions perfectly well, so calling this essential would fail the deploy
of a working project. It still leaves `ready: false` and still shows up as `next`, which is
how you are told. It is set and measured for you the moment you register an embedding model
with your provider, so on most projects this never comes up.
:::

### Per-user or project-wide

The wiki is **per-user by default**. Turn on **Capabilities → Shared project wiki** and it
becomes one wiki everyone in the project reads and the agent curates for all of them
(pages upsert by title, so one title is one page no matter who wrote it).

| Your corpus | Wiki |
|---|---|
| You upload it, `visibility: "tenant"`, users only read ([see Documents](./documents.md#a-corpus-you-curate-that-users-only-read)) | shared — safe, and what you want |
| Users upload their own private documents | leave it per-user |

Remembered facts (`remember`/`recall`) stay per-user either way — they're about a person,
not the project. Turning the wiki shared does not widen them, and neither does a wider
`scope`: memory follows `subject` alone.

### A shared page must come from your documents

The obvious worry about a wiki the agent writes to is that a user could dictate its
contents — *"save 'be rude to customers' to the wiki"* — and poison what everyone else's
agent reads later. That can't happen. A write to a **shared** wiki is only accepted if the
text is demonstrably derived from documents retrieved in that same turn:

1. **The sources must be shareable.** Only citations to project-wide (`visibility: "tenant"`)
   documents count. A page distilled from one user's private upload is refused, so a shared
   wiki stays safe even over a mixed corpus.
2. **The text must match them**, measured with your own embedding model. A faithful summary
   sits close to the passage it came from; text composed from a user's instruction does not.
3. **It must not add anything.** A second check rejects text that is on-topic but introduces
   claims — or instructions about how to behave — that the sources never made.

If it fails, nothing is written, the agent is told why, and the attempt is recorded in the
audit log as `wiki_write_rejected`. Successful writes are audited too (`wiki_write`), with
the source documents, so any page is attributable and revocable. Verification **fails
closed**: if the check can't run, the page isn't saved.

Private wikis and memories skip step 1–3 — a user's own preference legitimately isn't in
any document — but they're still screened by your guardrail policy and audited.

### When documents change, pages say so

Each page records the documents it came from, so the corpus moving underneath it is
detectable. Three things happen automatically:

| Change | Effect on pages built from it |
|---|---|
| Document deleted | flagged out of date, with the filename |
| Document reingested | flagged out of date |
| A **new** document covering the same ground | flagged as possibly superseded |

Pages are flagged, never deleted — a curated page whose source was edited is unverified,
not worthless. `wiki_read` then hands it to the agent with an explicit warning to check the
documents before repeating it, and to rewrite the page if it's wrong. So a stale page
degrades into a lead instead of silently becoming a confident wrong answer.

The last row works by similarity, so it needs no pre-existing link between the new document
and the page. Both thresholds are tunable (`wiki_grounding_similarity`,
`wiki_supersede_similarity`) because the right cut moves with your embedding model.

Both are visible and editable in the dashboard, which matters for support: when an answer
looks strange, a remembered fact is often the reason. Leave `memory` off if you'd rather every
session start clean.

## Webhook triggers

`triggers`

Scheduling answers "every Monday". A trigger answers "when a ticket arrives, when a
build breaks, when a file lands" — which is what turns the agent from something people
visit into something that works while they don't.

```bash
# Create one. The prompt is a template; the event fills it in.
curl -X POST "$BASE/triggers" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{
    "name": "new ticket",
    "prompt": "A ticket arrived from {{ body.customer.name }}: {{ body.subject }}. Triage it.",
    "signed": true
  }'
# -> { "url": "https://api.../triggers/<slug>", "secret": "..." }
```

Give that URL to the other system. Every POST to it starts a turn.

**The path is the credential.** The fire endpoint takes no token, because it is called
by systems that cannot hold a short-lived JWT and will not be taught a bespoke auth
scheme. That is genuinely weaker than a token, and it is why a trigger runs as a *fixed*
subject — whoever created it. Knowing the URL gets you that subject's access and nothing
more; there is no field in the request that can widen it. Where the caller can sign, set
`signed` and the body must carry a matching `X-Signature`, which turns the URL from a
bearer token into a proof of origin.

**It answers immediately.** A webhook sender retries a slow response and gives up on a
long one, and an agent turn is tens of seconds. So the run is started durably and you
get `{"accepted": true}` — never the agent's reply. The reply lands in the session and
fires your [turn-stopped webhook](./chat.md) like any other unattended run.

**A retry is not a second run.** Runs are keyed per *event*, so the same delivery arriving
twice starts the agent once:

```json
{ "accepted": true, "trigger": "…", "duplicate": true }
```

Still a `200` — a sender retrying an event we already took wants to hear that it landed,
and a 4xx or 5xx would only make it retry harder. `duplicate` tells you which it was.

The event is identified by your `X-Event-Id` or `Idempotency-Key` header if you send one,
and otherwise by a hash of the body. (Not `X-Delivery-Id` — that is a header *we* send
*you*, on the outbound webhook above. Sending it here does nothing and the body hash takes
over.) Deduplication lasts **24 hours** on this deployment.

**Send the header if your payload is not byte-identical across retries** — many senders
re-serialise JSON, and a re-ordered object is a different body even though it is the same
event. That is one event arriving as two.

**Send it, too, if two genuinely different events can carry the same body** — which is the
same mistake in the other direction, and the more expensive one. A bare `{"event":"ping"}`,
an empty payload, a "something changed, come and look" webhook with no detail, two people
submitting the same form: to us those are one event for the next 24 hours. The later fires
answer `accepted: true, duplicate: true` and start nothing, so a heartbeat with a constant
body runs **once a day** and its sender is told every time that it landed.

None of those payloads carry a natural id, so nobody sending them thinks to add a header.
If your events do not identify themselves, identify them — a counter, a timestamp, a uuid
in `X-Event-Id` is enough.

Every refusal answers 404 — no such trigger, disabled, bad signature. A webhook endpoint
is enumerable by anyone who can reach it, and telling them apart tells a prober which
slugs exist.

Rotating a URL that has leaked:

```bash
curl -sX POST https://api.oberik.com/triggers/$TRIGGER_ID/rotate \
  -H "Authorization: Bearer $TOKEN"
# -> a new url; the old one keeps working for 24 hours
```

The old path stays live for a day, so you change the address in the sending system on
your own schedule rather than during the switch. Without that window the only way to
deal with a leaked URL is to break the integration.

**Only the path changes.** The signing secret is unchanged — the response carries a new
`url` and **no** `secret` — so a sender that already signs keeps working the moment you
give it the new address. This call is for a leaked *path*, which is the credential when a
trigger is unsigned.

If the *secret* is what leaked, there is no rotate for it: the secret is shown once, when
the trigger is created, so delete the trigger and create a new one. And do not confuse
this with [rotating a webhook tool's secret](./tools.md#rotating-the-secret) — that one
does carry two signatures for 24 hours, which is where the "both move" assumption tends
to come from.

---

## Context management


Replaying a whole transcript works until it doesn't. Once a conversation outgrows the
model's window, every later turn fails with "context length exceeded" — **permanently**,
because the message that tipped it over is still in the history.

This is configured **per project** (Dashboard → Context management), not per request.

| Strategy | What it does |
|---|---|
| `trim` *(default)* | Drop the oldest material until it fits. Cheap, no added latency. |
| `summarize` | Compact the old prefix into one summary, keep recent turns verbatim. One model call on the turn that crosses the budget; the summary is stored, so later turns are free. |
| `none` | Replay everything. Fine for short conversations; long ones will start failing. |

Under `trim`, **what goes first** is configurable. `tool_output_first` (the default)
guts old tool outputs before dropping whole messages — a command's output can be
produced again, the reasoning around it cannot.

## What always holds

- **Below the budget, nothing changes.** Every strategy replays the transcript
  unaltered. This only ever activates on a conversation that would otherwise break.
- **The task survives.** The first user message and the most recent turns are never
  evicted.
- **The transcript stays valid.** Eviction is followed by a repair pass, so trimming can
  never leave the agent with tool calls nothing answered.
- **Nothing is deleted.** Summarized messages keep their content; `GET
  /chat/sessions/{id}/messages` still returns the real conversation.

## Budget

Leave the token budget blank and it is derived from the model's own window, minus a
reserve for the reply. A **token** can narrow it further via a `max_context_tokens`
claim (`maxContextTokens` when minting) — like every numeric ceiling here it only ever
narrows, so a cheap tier can be given a shorter memory without its own project.

**Checking that a ceiling applied.** The report says whose number bounded the turn:

```jsonc
{ "budget": 4096, "budget_from": "token", "tokens_before": 8017, "tokens_after": 4087,
  "truncated": 1, … }
```

`budget_from` is `"token"`, `"project"` or `"model"`, and a report arrives for a **token**
ceiling even on a turn small enough that nothing had to be cut — so you can confirm the
tier you are selling without waiting for it to bite.

:::caution Reading a marker back does not prove the history was kept
The first user message is protected on purpose: losing the task is how an agent
confidently continues work it can no longer describe. So a marker planted in turn 1 is
exactly what survives while the bulk around it is truncated. Use `tokens_after` and
`budget` as the evidence, not a recalled string.
:::

## Images and other media

A single image is worth roughly 1600 tokens, so a multimodal conversation reaches the
budget far sooner than its text suggests — media is priced accordingly rather than as
the few characters a placeholder occupies.

Under `summarize`, the media in the evicted span is **attached to the summarization call
itself**: it is the last thing that will ever look at those images, so the model is
asked to write down what each one actually shows before it goes. Under `trim` media is
dropped, and a marker is left behind either way so the agent knows a picture was there.

## Keeping evicted messages searchable

Turn on **archive to memory** and whatever leaves the window is embedded into the
project's vector store, with the agent given a `search_history` tool scoped to that one
conversation — so it can go back for a detail instead of asking the user to repeat it.

## Knowing it happened

A response includes `context` when history had to be cut — **or whenever a token's own
ceiling is in force**, even on a turn small enough not to hit it. That second case exists
because a ceiling you cannot confirm is worth very little: the documented use for
`maxContextTokens` is a cheaper tier, and somebody wiring that up needs to see the budget
they bought before it bites.

```jsonc
"context": { "strategy": "trim", "resolved_by": "trim", "fallback": null,
             "tokens_before": 210431, "tokens_after": 95880, "budget": 96000,
             "compacted": 0, "dropped": 0, "truncated": 23, "summarized": false }
```

`budget_from` says whose number that budget is — `"token"`, `"project"` or `"model"` — so
"did my clamp take effect" is a field to read rather than damage to infer from. Under a
token ceiling it reads `"token"`, and `tokens_before` / `tokens_after` / `truncated` say
what it cost.

**On a stream the `context` frame arrives before `start`.** Fitting happens before the model
is called, so it is the first thing a turn emits — earlier than the frame that carries the
session id. Register `onContext` when you open the stream, not after the turn has started,
or you will count zero of them on a turn that fitted perfectly well. Summarizing also emits
`phase: "compacting"` ahead of its model call, so render a "compacting conversation…" state
rather than leaving the UI blank.

Its presence is the signal that the model did *not* see the whole transcript, unless
`truncated`, `dropped` and `summarized` are all zero — which is the "your ceiling is in
force and cost nothing this turn" case.

### Two fields, because there are two questions

`strategy` is **what the project asked for**. `resolved_by` is **what actually fitted the
window**. They are usually the same and the interesting case is when they are not:

```jsonc
{ "phase": "done", "strategy": "summarize", "resolved_by": "trim",
  "fallback": "summarizer_returned_nothing", "compacted": 0, "dropped": 3, … }
```

That is a summarize policy that could not run — here because the summarizer's own model
call came back empty or timed out — so the window was fitted by trimming instead. The turn
still worked; it worked on a cut view of a conversation you had asked to have summarized,
which is worth knowing and used to be invisible. `fallback` is `null` when nothing went
wrong, and otherwise names which way it gave up:

| | |
|---|---|
| `summarizer_timed_out` | it did not answer within the deadline — the model behind it is too slow for a transcript this size |
| `summarizer_returned_nothing` | it answered, with nothing usable in it |
| `nothing_to_summarize`, `nothing_evictable` | there was no prefix to compact, so trimming was all there was to do |

The first two are worth telling apart: one points at your infrastructure and one at the
model's output. Summarizing is bounded as a whole — including its retry — because it runs
*before* the turn's first token, so every second of it is a second of blank screen.

**Which of the three causes it was.** `summarizer_timed_out` names the failure and not the
reason, and from outside a ceiling too tight, a model too slow, and a summarizer that never
finishes look identical. So the report carries the numbers:

```jsonc
{ "strategy": "summarize", "resolved_by": "trim", "fallback": "summarizer_timed_out",
  "summarizer_timeout_s": 45, "summarizer_ms": 45002, "summary_model": "hukuk-db",
  "compacted": 0, "dropped": 2, "truncated": 1 }
```

| | |
|---|---|
| `summarizer_timeout_s` | how long it was allowed (`CONTEXT_SUMMARY_TIMEOUT_S`, 45s by default) |
| `summarizer_ms` | how long it actually took |
| `summary_model` | which model was asked — your `summaryModel` if set, otherwise **the turn's own model** |

All three are `null` unless a `summarize` policy actually ran, and they are reported on a
*successful* compaction too: `summarizer_ms` close to `summarizer_timeout_s` is the warning
that the next slightly longer conversation will fall back to a trim.

`summary_model` matters more than it looks. Unless you set one, summarizing a 96k-token
transcript is done by your chat model — and a reasoning model that spends its output budget
thinking before it emits anything is close to a worst case for this. "Raise the ceiling" and
"point `summaryModel` at something fast" are different fixes, and these fields are what tell
you which you need.

Two counts, for the same reason:

| | |
|---|---|
| `compacted` | messages that left the window **and whose content is in the summary** |
| `dropped` | messages that left the window and whose content is gone |
| `truncated` | messages kept but shortened (usually tool output) |

They were one number, and "we summarised the earlier part of this conversation" is not the
same sentence as "we dropped three messages".

### Something the turn produced itself

Fitting the transcript happens before the turn runs, and a turn can produce something too
big for the window *while* it runs: a sandbox command that printed a whole build log, an
MCP tool that returned a repository. Those are fitted too, at the step boundary before the
model reads them, and reported as `context` with `phase: "step"`:

```jsonc
{ "phase": "step", "strategy": "summarize", "resolved_by": "trim", "fallback": null,
  "tokens_before": 212159, "tokens_after": 52827, "budget": 96000,
  "compacted": 0, "dropped": 0, "truncated": 1, "summarized": false }
```

A `"step"` report says `resolved_by: "trim"` however the project's strategy is set, with
`fallback: null` — nothing went wrong, this path simply never summarizes (see below).

`trim_order` decides what gets cut here exactly as it does before the turn, and the tool
output carries a marker saying it was shortened — so the agent answers knowing its view
was cut, rather than confidently from half a file. A `"step"` report never summarizes,
whatever the project's strategy: a model round trip per step of a tool loop is not a trade
worth making, so it is the deterministic trim.

Until this existed the two halves disagreed in a way nobody could have predicted from the
settings. A **client** tool's oversized result comes back on a new request, so it was
fitted and the turn survived; an **MCP or sandbox** tool's ran inside the turn, so it went
to the provider whole and the turn died with the provider's own
`ContextWindowExceededError` — same size, same project, same policy.

---

## Calling from the browser


Calling Oberik directly from your frontend is a first-class path: the end-user token already
bounds what the caller can do, and it keeps streaming traffic off your servers.

## Mint on your server, never in the browser

Your project key signs tokens, so it stays server-side. Your frontend receives only a
short-lived JWT.

```ts title="your backend"
app.post("/api/ai-token", requireLogin, async (req, res) => {
  const r = await fetch(
    `https://oberik.com/api/projects/${PROJECT_ID}/token`,
    {
      method: "POST",
      headers: { "content-type": "application/json", "X-API-Key": PROJECT_KEY },
      body: JSON.stringify({
        subject: `${req.user.orgId}:${req.user.id}`,
        scope: `${req.user.orgId}:${req.user.id}`,
        capabilities: ["chat", "documents:read"],
        expiresIn: 900,
      }),
    },
  );
  res.json(await r.json());   // { access_token, expires_in, capabilities, … }
});
```

Short TTLs are the point: a leaked 15-minute token scoped to one user is a small problem.
Let the SDK handle the refresh — it calls `getToken({ expired: true })` when the server
rejects a token and replays the request, so a long-lived tab never breaks:

```ts
let cached: string | undefined;
const ai = createClient({
  getToken: async ({ expired }) => {
    if (!expired && cached) return cached;
    cached = (await (await fetch("/api/ai-token", { method: "POST" })).json()).access_token;
    return cached;
  },
});
```

See [Authentication](./authentication.md#rotation-and-expiry) for the exact guarantees
(single in-flight refresh, one replay per request, streams resumed rather than restarted).

## Allowed origins

Add each origin your frontend runs on under **Project → Browser origins** (comma-separated),
or via the API:

```
https://app.example.com, https://*.example.dev, http://localhost:3000
```

Then tokens from this project are accepted only from those origins.

Details that bite people:

- An entry must be an **origin**, not a URL with a path. `https://app.example.com/chat` is
  rejected at save time, because a stray path would silently never match.
- A wildcard covers exactly one label. `https://*.example.com` matches
  `https://app.example.com`, but **not** `https://a.b.example.com` and **not** the apex
  `https://example.com` — list those separately.
- Scheme and port are part of the origin: `http://localhost:3000` and
  `https://localhost:3000` are different entries.
- Server-to-server calls send no `Origin` header and are never affected.
- A project with **no** origins configured is unrestricted. Add yours before going live.
- Setting the list **replaces** it — read it first, and pass the whole list. Setting it to
  EMPTY removes the restriction entirely, which is a widening nothing downstream can notice
  (every existing caller keeps working), so it takes `confirm`:

  ```ts
  await oberik.origins.set(["https://app.example.com"]);
  await oberik.origins.set([]);                    // 400: this would allow any origin
  await oberik.origins.set([], { confirm: true }); // 200
  await oberik.origins.set(["*"]);                 // 400 too — same outcome, same question
  ```

  `[]` and `["*"]` are two spellings of the same thing and both take `confirm`: the refusal
  names the OUTCOME as the risk, and the stored list cannot tell a slip from intent
  afterwards. `https://*.example.com` is **not** allow-all — it is a single-label wildcard
  host and a genuine restriction.

  ```bash
  curl -sX PUT "$CP/api/projects/$OBERIK_PROJECT_ID/origins" \
    -H "X-API-Key: $OBERIK_PROJECT_KEY" -H "content-type: application/json" \
    -d '{"origins":[],"confirm":true}'
  ```

  The 400 says how many origins it would have removed, so a deploy script that clears the
  list on purpose asks for it once and a script that clears it by accident stops.

A mismatch fails with a clear **403** (`origin '…' is not allowed for this project`) rather
than an opaque CORS error, because the token tells us whose policy applies. CORS itself is
handled for you.

:::info The preflight succeeds and then the request is refused. That is the design.

If you watch a disallowed origin in the network tab you will see `OPTIONS` answer **204 with
`Access-Control-Allow-Origin: <your origin>`**, and the real request that follows answer
**403**. That looks like the two layers disagreeing, and they are answering different
questions:

| | decides from | answers |
|---|---|---|
| the preflight | the deployment-wide union of every project's origins, plus the operator's | may a **browser** read a response from this API at all |
| the request | **your project's** list, read off the token | may this token be used from this origin |

**A preflight carries no `Authorization` header**, so at that moment there is no project and
therefore no list to enforce. The union is the only allow-list that exists there. It is a
browser permission, not the boundary — being told a browser may *read* a response is not
being handed the data, and every project whose list does not match still gets a 403.

Two consequences worth knowing:

- The 403 is the better diagnostic. A preflight refusal would give your app an opaque
  "blocked by CORS" with no reason; the 403 names the origin and the project.
- The **403 itself carries no `Access-Control-Allow-Origin`**. A refusal that advertised the
  origin it was refusing is the one thing here that really was wrong, and it is fixed —
  `Vary: Origin` stays, so a cache never serves that refusal to an allowed origin.

`Access-Control-Allow-Credentials` is not set on any response. Tokens travel in the
`Authorization` header, not in cookies, so nothing here depends on credentialed CORS.
:::

## Streaming and uploads from the browser

```ts
const ai = createClient({ getToken });
const handle = ai.chat.stream({ message }, { onToken: (_, full) => render(full) });
```

Streaming is SSE over `fetch` — nothing to keep alive, no proxy to run. `X-Run-Id` is exposed
to JavaScript, which is what lets the SDK resume a dropped stream instead of restarting the
answer.

Uploads go straight to storage over a signed URL, so large files never transit your backend:

```ts
await ai.documents.upload(file, { filename: file.name, onProgress: (s, t) => setPct(s / t) });
```

:::note S3 CORS
Multipart upload reads the `ETag` of each part. If you're pointing at your own bucket, expose
it (`ExposeHeaders: ["ETag"]`) or the upload fails with a clear message about it.
:::

---

## Guardrails


Capabilities decide what the agent *can* do. Guardrails decide what's *acceptable* — on the
way in and on the way out. They're configured per project and, unlike the per-request
switches, a client cannot turn them off.

**Off by default.** A new project runs none of this, and the agent still refuses obvious
injection on its own judgement — guardrails are the checks you want *enforced* rather than
left to it.

```ts
await oberik.guardrails.set({
  enabled: true,
  injection: true,                       // deterministic, costs nothing
  blockedTopics: ["politics", "legal advice"],
  groundedness: true,                    // one model call on the turns it runs
  onViolation: "flag",                   // start here — see below
});

await oberik.guardrails.get();
```

Or in the dashboard: **Project → Capabilities → Guardrails**. Over SSH:
`guardrails set --enabled true --groundedness true`.

:::caution Start on `flag`, especially with `groundedness`
`onViolation` decides what a verdict *costs*. On `flag` a violation is annotated in
`guard_flags` and the answer still goes out; on `block` the answer is **replaced** with a
refusal the user cannot get past.

The semantic checks — `groundedness`, `blockedTopics`, `moderation` — are model
judgements, so they are wrong sometimes, and `block` turns each wrong judgement into a
refused answer on a question the corpus could answer. Run on `flag` against your real
corpus first, watch `guard_flags` on turns you know are good, and move to `block` once the
false-positive rate is one you can live with. `injection` and `pii` are deterministic and
carry no such risk.
:::

**Blocked topics are tidied on the way in.** Each entry is trimmed, blank ones are dropped,
and duplicates are removed case-insensitively — so `["staffing", " staffing ", "Staffing"]`
stores as `["staffing"]`. These topics are handed to the judge as prompt material, so a
repeated or blank-looking entry is repetition and a blank line in the prompt it is built
from, paid for on every guarded turn. The entry that survives is the first spelling you
sent. `get()` shows exactly what was stored, so you can always see what the policy holds.

:::warning `get()` and `set()` are different shapes

`get()` returns the policy **nested** — `{enabled, input: {injection, blockedTopics,
pii}, output: {...}}`. `set()` takes a **flat** patch, which is what the example above
shows. Note that `input.pii` reads back and `inputPii` writes.

Feeding `set()` the object `get()` returned is now a **400** naming the flat fields to
send instead. It used to return 200, echo the unchanged policy, and apply nothing — a
project ran a whole round of testing believing a blocked topic was in force when nothing
was enforcing it. Anything you omit is left as it was; anything the endpoint does not
recognise is refused rather than dropped.

:::

## Two stages

**Input**, before the agent runs:

- **Injection heuristics** — catch prompt-injection and jailbreak attempts in the message.
- **Blocked topics** — refuse subjects your product shouldn't discuss.
- **PII** — `off` (default), `detect`, or `redact`.

**Output**, before the answer is returned:

- **Groundedness** ("cite-or-refuse") — if the answer isn't supported by the retrieved
  sources, say so instead of asserting it.
- **Moderation** — screen the generated answer.
- **PII** — same three modes.

Deterministic checks (PII patterns, injection heuristics) always run and need no model. The
semantic checks (groundedness, moderation, topics) use your project's model, and only run when
you enable them.

## What your app sees

```ts
res.guard_flags;   // e.g. ["injection"], ["blocked_topic:legal advice"], ["pii:EMAIL"]
```

A blocked-topic flag names **which** of your topics matched, so you can tell which string
is catching real questions and tune it. `guard_flags` is present on every turn, streamed
or not, including the blocked ones — that is what lets you measure your own false-positive
rate rather than guessing at it.

When something fires, `on_violation` decides what happens:

- `block` — the answer is replaced with a refusal (or a "not enough information in the
  available data" message for ungrounded answers).
- `flag` — the answer is returned as-is and annotated, so you can log, review or badge it
  without breaking the experience.

While streaming, tokens may already have reached the user before the output check completes.
That's why the `guardrail` event carries the corrected `content`:

```ts
ai.chat.stream({ message }, {
  onToken: append,
  onGuardrail: (stage, flags, content) => {
    if (content) replaceAnswer(content);   // reconcile what was streamed
    log(stage, flags);
  },
});
```

Handle it, or a blocked answer will still be visible in your UI.

**`stage` says which of the two checks fired**, and it is the only thing that does —
`guard_flags` on the turn is a flat union of both. One `guardrail` event per stage that
did something:

| | when it fires | carries |
|---|---|---|
| `stage: "input"` | before the first token — the message was redacted or refused | `flags`, and `reason` on a refusal. No `content`: what was redacted is the user's own message, not ours to hand back |
| `stage: "output"` | after the answer, before `done` | `flags` and the corrected `content` |

So an input-only PII policy produces exactly one event, labelled `input`, before anything
is generated — which is the point at which telling the user "we removed a phone number
from your message" is still useful to them. Injection and blocked topics are input checks
and have no output side; groundedness and moderation are output checks and have no input
side. PII is the only one with both.

### Tune your blocked topics

A blocked topic is matched by a model, so it generalises — and it will take on-domain
questions with it if the string is broad. `"personal tax advice"` on a bookkeeping
assistant caught *"What is the mileage rate for 2026?"*, which is a company
reimbursement rate and the most on-domain question in that corpus.

Two things to do about it:

- **Start on `flag`.** You get the flags without refusing anybody, so you can read a
  week of real traffic before deciding.
- **Name the topic narrowly.** `"personal income tax filing"` refuses less of your own
  product than `"personal tax advice"`.

By default a refused user sees only *"I can't help with that request."*, which is a dead
end — they cannot tell anything was blocked, let alone rephrase. Turn `explainRefusals`
on to append the reason:

```ts
await oberik.guardrails.set({ explainRefusals: true });
// "I can't help with that request. (asks for personal tax filing advice)"
```

Off by default on purpose: the sentence that helps a confused user also helps somebody
probing the filter iterate against it. It applies to every refusal a guardrail produces,
including a groundedness block — that one starts from its own sentence ("I don't have enough
information in the available data to answer that reliably", because *"I can't help with that
request"* would be untrue: the agent can help, it just cannot support this answer) and gains
the same parenthetical.

**Which check fired is on the record, not only on the response.** `guard_flags` comes back on
the turn, and the same list is stored on the assistant row (`extra.guard_flags`, with
`extra.guardrail: "blocked"` when the answer was replaced) and written to the audit trail. So
a caller who did not keep `guard_flags` at the time can still find out afterwards — which
used to be impossible for an output guard: `finish_reason: "guardrail"` said *that* one
fired and nothing said which.

## PII is off by default

This is deliberate. On a "talk to your own data" product the end-user is sharing *their own*
information on purpose — redacting it would break the feature. The three modes:

| Mode | Behaviour |
|---|---|
| `off` | the model receives the text unchanged (default) |
| `detect` | flagged in `guard_flags` for audit, but the model still gets the raw text |
| `redact` | replaced before the model or provider sees it |

Choose `redact` only if you must keep PII away from your model provider, and accept that the
model can no longer use it to answer.

### Exactly what is detected

Pattern matching, not a model — so it is fast, deterministic and free, and it finds
**identifiers, not people**. The full list, which is the whole of it:

| Flag | Matches |
|---|---|
| `pii:EMAIL` | email addresses |
| `pii:CARD` | 13–16 digit payment card numbers, spaced or hyphenated |
| `pii:PHONE` | international (`+44 7700 900123`), national trunk (`07700 900123`, `0117 496 0123`) and US (`555-123-4567`) forms |
| `pii:SSN` | US Social Security numbers (`123-45-6789`) |
| `pii:NINO` | UK National Insurance numbers (`QQ 12 34 56 C`) |
| `pii:IP` | IPv4 addresses |

:::caution Names and addresses are **not** detected
There is no pattern for a person's name that does not also match ordinary prose, so
`redact` will not remove one — `Priya Raghunathan` reaches the provider unchanged, and
`guard_flags` will be empty because nothing matched. The same goes for street addresses,
dates of birth and free-text notes about a person.

So `redact` **reduces** what reaches your provider; it does not guarantee that nothing
identifying does. If your obligation is "no personal data leaves our infrastructure", the
control that meets it is a self-hosted or region-pinned model — configured per project
under **Models** — with this as a second layer, not the first one.

Anything above that we do not match is a bug worth reporting. Anything not above, we do
not claim to find.
:::

## Auditing

Every turn is recorded, with the guardrail flags that fired:

```ts
await ai.audit.list({ action: "chat", subject: "acme:fin:ana", limit: 100 });
```

So is every change to the corpus, and every search of it. A row names the document it
concerns in `resource_id`, so the two questions an audit exists to answer are answerable
from the rows themselves:

| Question | The rows that answer it |
|---|---|
| When did this document arrive, and who put it there? | `document_upload` |
| Who removed it, and what was it? | `document_delete` — recorded before the row goes, so it still describes what went |
| Who changed who may see it? | `document_update`, with the previous and new value of each field that changed |
| Who has seen this document? | `retrieve` and `chat`, both of which carry `metadata.document_ids` |

A `document_update` row is written only when a field actually changed; a request that sets
a document to what it already was is not an event.

`document` finds both — the rows that name it and the rows that merely saw it:

```ts
// everything that has ever happened to one document
const rows = await ai.audit.list({ document: doc.id, limit: 100 });
```

And for erasure requests, one call removes a subject's documents, sessions and vectors:

```ts
await ai.audit.forget("acme:fin:ana");
// { documents_deleted, sessions_deleted, vectors_purged, objects_deleted }
```

Both need an admin role on the token.

---

## Limits & errors


## Error shape

Failures are JSON with a `detail` string:

```json
{ "detail": "token lacks capability: computer" }
```

The SDK throws `AgentApiError` with `.status` and `.detail`:

```ts
try {
  await ai.chat.send({ message });
} catch (e) {
  if (e instanceof AgentApiError && e.status === 403) requestUpgrade();
  else throw e;
}
```

| Status | Meaning | What to do |
|---|---|---|
| `400` | malformed request, a **bad attachment** (unresolvable URL, truncated `data:` URI, not-an-image), or the model provider rejecting it (unsupported parameter, context too long) | fix the call; `detail` names the problem |
| `401` | missing, invalid or expired token | mint a fresh one |
| `403` | capability or origin denied, or an action you may not take on something you *can* see | not allowed — don't retry |
| `404` | not found, **or** not visible to this subject | treat as not found |
| `409` | conflict — a project or organization name already taken, an upload acted on out of order, a turn already running on the conversation you addressed, or **this project has no usable provider** | reconcile, then retry; for a running turn, attach to it (see [Chat](./chat.md#while-a-turn-is-running)); for a provider, register one |
| `422` | invalid request body, or an ingest that failed on the document itself | `detail` is an **array** of `{loc, msg}` — see below |
| `429` | rate limit or usage cap reached — including on an **upload** | back off; see below |
| `500` | a bug on our side, or a backend we depend on being unreachable | retry once; if it repeats, the `detail` is worth sending us |
| `502` | the model provider failed with an error of its own | retry with backoff |
| `504` | the model provider did not answer in time | retry with backoff; if it repeats, your endpoint is too slow rather than your request wrong |

**`504`, not `502`, when nothing answered.** A provider that never replies and a provider
that replies badly are different problems with different fixes, and they used to share a
number. If your model endpoint sits behind a CDN, a `504` here is the same event your CDN
logs as `524` — your origin exceeded its limit — and the `detail` says so in as many words:
`the request to the upstream endpoint timed out after 125.4s`. Nothing in that sentence is a
status code any more, because none was ever sent: an upstream that has not answered has not
answered with a number either.

An attachment you got wrong is a `400`, not a `502`. Three shapes used to answer `502` — a
host that does not resolve, a `data:` URI cut short, and a URL that resolves to something
that is not an image — which told every client following the table above to retry a request
that cannot succeed. On a stream the same failure arrives as `code: "bad_attachment"` with
`status: 400`.

A 404 that's really "you can't see it" is deliberate: probing ids shouldn't reveal which
exist. So reading another subject's document or session is `404`, in the same words a
made-up id gets — not `403`, which would confirm the id was real. `403` is kept for the
case where it tells you nothing you didn't know: you can see the thing and may not do
*this* to it (deleting a tenant-visible document you don't own), or the capability,
origin or model allow-list refused the call outright.

### The project's own per-minute limits

`tpmLimit` and `rpmLimit` (dashboard: **LLM & limits**, or `limits.set`) bound how fast a
project may call its models. Exhausting one answers **429** — the same status and the same
`rate_limit` reason as any other rate limit — with the provider's own reset time in the
message where it gives one:

```
429 rate limit reached on rpm — this is transient, so retry shortly (resets at 12:01 UTC).
    Raise the per-minute limits under LLM & limits if it keeps happening.
```

**Back off and retry; do not treat it as a failure.** Unlike a spend cap, this one clears by
itself.

It used to be enforced by *waiting* rather than refusing — the proxy answered `Retry-After:
60` and the data plane's own HTTP client slept through it, twice — so a project with
`rpmLimit: 2` sending five requests saw 5.6s, 5.9s, 64.1s, 66.0s and 125.6s and no 429 at
all. That outlived most client timeouts, including this SDK's own, so the platform was
holding requests its caller had already abandoned, and nothing named the delay. If you have
retry logic written against a queueing platform, it is now the ordinary 429 path.

### A streamed turn that is refused

A stream cannot answer with a status — the response has already begun — so the refusal
arrives as an `error` frame, and the SDK throws `AgentStreamError`. Two of its codes are
about the turn rather than the stream, and both carry the status the same refusal would
have had on `POST /chat`:

```ts
try {
  await ai.chat.stream({ message }, handlers);
} catch (e) {
  if (e instanceof AgentStreamError) {
    if (e.code === "usage_cap") stopAndTellSomeone(e.message);  // raise it, or wait
    if (e.code === "rate_limited") await backOffAndRetry();     // transient
    if (e.status === 429) { /* either of the two, if you don't care which */ }
  }
}
```

Before this the streaming path handed you the provider's own sentence — `Budget has been
exceeded! Key=… Max budget: 0.0` — with no code and no status, so "am I out of budget" was
answerable only by matching English against the message. `POST /chat` had always answered
`429` with a sentence naming the setting; the two paths now say the same thing.

### An upload that fails

Ingestion is asynchronous, so its failure is not the status of any one request: the
document ends `status: "failed"` and carries both a sentence and a word.

```ts
const doc = await ai.documents.uploadAndWait(file, { filename: "handbook.pdf" }); // throws
// or, polling yourself:
if (doc.status === "failed") {
  doc.error;     // "spend cap reached for this project — raise it under LLM & limits…"
  doc.failure;   // "usage_cap"
}
```

`error` is for a person; `failure` is for the code around them. Two of its values are not
about the file at all — `usage_cap` and `rate_limit` mean the project hit its own spend cap
or per-minute limit, nothing is wrong with the document, and re-uploading it will fail the
same way until the cap is raised or the window resets. (`rate_limited` is a 429 whose body
did not say which of the two it was.) The rest name where it broke:
`unsupported_type`, `unreadable`, `embedding`, `vector_store`, `storage`, `unknown`.

`uploadAndWait` and `waitReady` throw with the status that matches: **429** for the two
limit cases, 422 for the rest. So the retry rule is the same one you already have for
`/chat` — back off on 429, don't retry a 422.

### Reading `detail`

`detail` is a string for most errors and an **array** for a `422`, so
`` `${e.detail}` `` prints `[object Object]` on the one status where the useful content
is per-field. `e.message` is always a readable summary — use that for logs, and reach
into `e.detail` when you want to attach errors to form fields:

```ts
catch (e) {
  if (e instanceof AgentApiError && Array.isArray(e.detail)) {
    for (const { loc, msg } of e.detail) console.log(`${loc.join(".")}: ${msg}`);
  } else if (e instanceof AgentApiError) {
    console.log(e.status, e.message);
  }
}
```

## When the provider goes away mid-conversation

Rotating a credential out from under a live conversation is routine, and it used to answer
with the proxy's own words: `User not found.` A customer reads that as *their* end-user and
goes looking at the subject, the token, the mint call and per-user isolation — all correct,
none of them the thing that changed. It is now a `409` naming the cause and the fix, with
`code: "no_provider"` on the streaming path.

Do not retry it: nothing can answer until a provider is registered. **The conversation is
not damaged** — the failed turn persisted nothing, and a turn on the same session works the
moment a provider exists again, with its history intact.

A `502`/`524` may be generated by the proxy in front of the API rather than by the API,
in which case the body is an HTML page. The SDK collapses that to a one-line summary
before it reaches `message` and `detail` — logging one used to print ninety lines of
markup — and says it came from an intermediary, which is your cue that the request may
never have reached us at all.

### Which turn failed

A failure carries the ids of the turn it belongs to, on both paths, so a report of one is
answerable afterwards rather than only at the moment it happened:

```ts
try {
  await ai.chat.send({ message: "…" });
} catch (e) {
  if (e instanceof AgentApiError) {
    console.error(e.status, e.message, { runId: e.runId, sessionId: e.sessionId });
    // Whatever the turn managed to write is still readable:
    if (e.sessionId) await ai.chat.sessions.messages(e.sessionId);
  }
}
```

`AgentStreamError` has carried both for longer, alongside the content that had already
streamed. Either one is absent when the failure happened before there was anything to name —
a refused token has no run — so check before using them.

Streaming has its own two: `AgentStreamError` (the server sent an `error` frame, or retries
were exhausted) and `AgentCancelledError` (someone called `cancel()`). `handle.disconnect()`
and aborting your own `signal` reject with a plain `AbortError` instead — the run carries
on server-side in those cases, so calling it cancelled would be wrong.

An `AgentCancelledError` means the request is finished with, not parked: the message stays in
the conversation but is marked unanswered and never replayed, so your next turn does not
inherit what the user just stopped. See [What cancel guarantees](/chat#what-cancel-guarantees).

## Retries

The SDK retries transport failures and resumes dropped streams; it does not blindly re-POST a
chat turn, because a dropped stream **resumes by run id** instead — you never pay twice for
the same answer. Uploads retry per part with backoff, and ranged downloads resume from where
they stopped.

For your own retries: `429`, `502` and `504` are worth retrying with jittered backoff, `4xx`
otherwise is not.

**A streamed turn carries the same number.** A failure inside a stream cannot be an HTTP
status — the response was already `200` when the first frame left — so the `error` frame
carries `status` alongside its `code`, and it is the status the same failure would have got
from a blocking `POST /chat`. Branch on that and one retry policy covers both, which is the
point: a rotated provider key is `409` either way, a spend cap is `429` either way, and a
provider timeout is `502` either way. Read `status` where you have it and treat a frame
without one as a failure you cannot classify rather than as a retryable one.

### Knowing your turns are failing at all

A failed **streamed** turn is a `200 OK` — the failure is a frame inside a body that had
already started — so it appears in no access log, no `5xx` count, and no HTTP-level alert
you have built. That is the correct shape and it has a cost: a client that retries into a
provider which cannot answer produces a failure every few minutes and looks, from outside,
like silence.

Two reads answer it:

```bash
# What the last 24 hours of turns did
curl -s "https://oberik.com/api/projects/$OBERIK_PROJECT_ID/turns" \
  -H "X-API-Key: $OBERIK_PROJECT_KEY"
# {"window_hours":24,"total":234,"errored":234,"consecutive_errors":234,
#  "last_error":"the upstream endpoint answered 502 Bad Gateway","last_success_at":null}
```

`consecutive_errors` is the number to alert on: it counts back from the most recent turn
and a success resets it, so it separates a client retrying carefully from a client stuck in
a loop. `window_hours` defaults to 24 and takes 1–168.

The control plane says the same thing without you asking. `GET /readiness` carries a
`turns` step once the streak passes a handful, naming the count and the last reason. It is
deliberately **not** `essential`, so `canAnswer` stays true and a deploy gated on it is not
held hostage to your provider having a bad night — but `ready` goes false and `next` points
at it.

Neither of these refuses anything or asks you to back off. What is failing is your own
provider or configuration, the first failure already said which, and retrying into it
returns the same answer.

### Telling a refusal from a dropped connection

`AgentStreamError.terminal` says which one you have. `true` means the server sent an
`error` frame and closed — `status`, `code` and the sentence are all populated, the SDK
does not reconnect, and retrying the same request gets the same answer. `false` means the
stream stopped without saying anything, which is the case reconnection is for; the SDK has
already retried by the time you see it, and the message says why it gave up.

```ts
try {
  await ai.chat.stream({ message }).done;
} catch (e) {
  if (e instanceof AgentStreamError && e.terminal) {
    // e.status is the same number `POST /chat` would have given: branch on it.
    if (e.status === 429) await backOff();
    else show(e.message, e.content);   // render what already arrived
  }
}
```

It is a property rather than something you read out of the message, and that is not
cosmetic: the SDK itself used to decide terminality by testing whether the message started
with `"server: "`, that prefix was removed for being noise in front of the first word a
customer reads, and every server refusal silently became a "dropped connection" — ten
reconnects over 136 seconds against a 405, ending in `status: null`.

### A stream that cannot be resumed

Resuming needs the run's frames, and those live in the memory of the API process that
produced them — for the length of the turn, plus 10 minutes, and no longer than that
process itself. See [how long a run lasts](./chat.md#how-long-a-run-lasts).

When they are gone the reconnect does **not** 404. It answers with one terminal `error`
frame, so `handle.done` rejects with an `AgentStreamError` that carries `code`,
`sessionId` and the `content` that had already streamed — enough to render what the user
watched arrive and then either read the finished answer out of the conversation
(`stream_expired`) or send the turn again (`stream_lost`). Retrying the POST blindly is
the one wrong move: on `stream_expired` it pays for an answer that already exists.

## Timeouts

Long runs are normal — retrieval, tools, a sandbox build. Prefer streaming for anything
interactive: the first token arrives quickly and you're not holding a request open with
nothing to show. If you must block, set a generous client timeout (120s+) and expect
tool-heavy turns to sit near it.

In the SDK that timeout is `timeoutMs` on the client, and it defaults to **600000** (10
minutes):

```ts
const ai = createClient({ getToken, timeoutMs: 180_000 });
```

:::caution On Node, past 300 seconds, you also need a dispatcher
`timeoutMs` aborts the request. Node's HTTP client has its own **300-second**
`headersTimeout` that fires first and is not reachable from an `AbortSignal`, so a
600000 budget really ends at ~302s as `UND_ERR_HEADERS_TIMEOUT`.

**Streaming is the better answer** and needs none of what follows: it holds the connection
open by design, has no header ceiling, and can be resumed after a dropped connection. Reach
for a dispatcher only when you must block.

Raising it takes an undici `Agent`, which is yours to pass — this SDK has no
dependencies and has to load in a browser and under React Native, so it cannot import
one for you:

```bash
npm i undici@^7      # the major matters — see below
```

```ts
import { Agent } from "undici";

const ai = createClient({
  getToken,
  timeoutMs: 900_000,
  dispatcher: new Agent({ headersTimeout: 900_000, bodyTimeout: 900_000 }),
});
```

**Pin the major.** Node's built-in `fetch` is an embedded copy of undici, and the
dispatcher handler protocol changed between majors — so an `Agent` from `undici@8` makes
**every** request fail, `tools.list()` included:

```
TypeError: fetch failed
  cause: invalid onRequestStart method
```

`undici@7` matches what Node embeds and works. Ask before you rely on it:

```ts
import { blockingBudgetIsHonoured, dispatcherProblem } from "@oberik/sdk";

const problem = dispatcherProblem(agent);   // null, or the sentence
if (problem) throw new Error(problem);
blockingBudgetIsHonoured(900_000, agent);   // false for a dispatcher that would fail
```

Both ask the dispatcher itself which handler interface it speaks and compare it with the one
serving `fetch`, so a mismatch is caught before you make a request rather than by every
request failing as `TypeError: fetch failed`. (They used to answer "is one configured",
which meant `true` for exactly the setup that breaks everything.)

In a browser there is no such ceiling and none of this applies.
:::

:::caution A blocking call that times out loses the turn
A stream can be re-attached: it has a run id, and a dropped connection resumes the same
run and replays what was missed. **A blocking call has neither.** There is no run id to
reconnect to, so a timed-out `chat.send` or `chat.answer` leaves the work done and paid
for with no way to collect the answer — and what surfaces in your code is your HTTP
client's error (`TypeError: fetch failed … read ETIMEDOUT` from undici, with nothing
naming Oberik in the stack), not ours.

So: streams are resumable, blocking calls are not. For anything that may run long, stream
it — even if you only use the final `done`.
:::

Sandbox commands default to **5 minutes** and may ask for up to **30 minutes**, for the
agent's `computer_bash` and for `ai.computers.exec` alike. `GET /computers/host` reports
both figures as `exec_default_timeout_s` and `exec_max_timeout_s` — read them rather than
hard-coding these. A `timeout_s` above the ceiling is clamped to it, and a command that
overruns is killed and reported as `timed_out`, not left to hang.

## Bounding a run

There's **no platform-imposed tool-loop limit** — an agent that needs forty steps to finish a
job gets forty. Bound it deliberately, at mint time:

```ts
{
  subject: user.id,
  maxToolIterations: 12,                    // ceiling for this token
  models: ["openai/gpt-4o-mini"],           // model allow-list
  maxEffort: "low",                         // reasoning-effort ceiling
  expiresIn: 900,
}
```

`maxToolIterations` on a mint is bounded by the project's own ceiling (Capabilities tab):
a token can be given fewer loops than the project allows and never more, and a mint that
omits it inherits the project's. With no project ceiling set there is **no limit** — an
agent that has misread a task keeps calling tools until the project's spend cap stops it,
so a project serving end-users should set one.

If a run hits the ceiling you get whatever prose the agent had already written, plus:

```ts
res.finish_reason;   // "max_tool_iterations"
```

**`content` can be empty.** If the ceiling lands mid-tool-loop — which is the common
case, since that is what the ceiling counts — the agent had not started writing its reply
yet, and there is no partial answer to hand back. Your UI needs its own copy for that,
not just "render `content`":

```ts
if (res.finish_reason === "max_tool_iterations" && !res.content.trim()) {
  show("That took more steps than allowed. Try a narrower question.");
}
```

It's a machine-readable string, deliberately not a sentence — you decide how (and in which
language) to tell the user. `null` means the agent finished on its own terms. Check it before
treating a response as complete.

| `finish_reason` | What happened | Who can fix it |
|---|---|---|
| `max_tool_iterations` | the tool-loop ceiling was hit; `content` is the prose written so far, and is often **empty** | you, by raising `maxToolIterations` on the mint — or the project's own ceiling, which the mint can only narrow |
| `guardrail` | an input guardrail refused the message | the end-user, by asking something else |
| `no_model` | **the project has no model configured**, so nothing could run | whoever set the project up |

`no_model` is worth handling separately: it is not the end-user's doing and not something
they can act on, so showing it as a normal agent reply sends them looking for a different
question to ask. Route it to whoever configures the project —
`GET /api/projects/{id}/readiness` lists everything that is still missing. The turn costs
nothing: no model runs.

A project does **not** silently fall back to a shared platform model. It would bill the
operator rather than the project, land outside the spend cap that project set, and be
attributed to nobody — and where no shared model is configured it simply fails with the
provider's own error, which reads as the product being broken rather than as one setup step.

## Rate limits and spend caps

Per-project caps are set in the dashboard: requests per minute, tokens per minute, and a spend
budget over a window. Exceeding any of them returns **429** rather than silently degrading —
including `budget_exceeded`, which is a cap you set, not a transient condition, so retrying
won't help until the window resets or you raise it.

Other standing limits: 10 concurrent sandboxes per project, 20 MB per sandbox file
read/write/export, 30,000 characters of command output per call.

## When an answer looks wrong

In order of usefulness:

1. `res.citations` — did it retrieve the right thing?
2. `ai.documents.chunks(id)` — was the document indexed the way you expect?
3. `ai.chat.sessions.messages(id)` — the full transcript, including tool calls.
4. `res.guard_flags` — did a [guardrail](./guardrails.md) rewrite the answer?
5. Memory, if enabled — a remembered fact may be steering it.
6. The dashboard's usage and run views — latency, tokens, cost, per model.

Every streamed run has an id (`X-Run-Id`, and the `run` event). Log it next to your own
request id and a support question becomes one lookup instead of an investigation.

---

## API reference


Two surfaces, two credentials, two hosts.

| Surface | Host | Auth | For |
|---|---|---|---|
| **Control plane** | `https://oberik.com` | `X-API-Key: pk_…` | administering a project — [Project API](./project-api.md) |
| **Data plane** | `https://api.oberik.com` | `Authorization: Bearer <jwt>` | everything an end-user does |

The SDK has a client for each, and they are separate types because their credentials
are: `createClient` takes an end-user token and runs wherever your app runs;
`createProjectClient` holds the project key and runs only on your server.

```ts
import { createClient, createProjectClient } from "@oberik/sdk";

// Server-side: administers the project and mints tokens.
const oberik = createProjectClient({ projectId, projectKey });

// Anywhere: one end-user's view of the data plane.
const ai = createClient({ getToken: oberik.tokens.forUser({ subject: user.id }) });
```

`createClient` already knows where the data plane is, so `baseUrl` is only needed
for a self-hosted deployment or local development:

```ts
import { createClient } from "@oberik/sdk";

const ai = createClient({
  // Recommended: called for a token, and again with { expired: true } on a 401.
  getToken: async ({ expired }) => fetchTokenFromYourBackend({ force: expired }),
  // baseUrl: "http://localhost:8000",   // only if you're not on the hosted API
});
```

The data plane also serves its own generated OpenAPI schema —
[`/openapi.json`](https://api.oberik.com/openapi.json), with an interactive explorer at
`/docs` **on the API host** (not on this site). That schema is generated from the running
code, so it is the authority on request and response shapes; this page is the map.

## Control plane

Authenticated with `X-API-Key`. The key is project **admin**, not just a minting
credential — see the [warning](./project-api.md).

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/api/projects/:id/token` | mint an end-user JWT |
| `GET` | `/api/projects/:id` | the project, with its capability ceiling |
| `PATCH` | `/api/projects/:id` | rename, or change the ceiling (`{ capabilities: {…} }`) |
| `GET` | `/api/projects/:id/capabilities` | the ceiling alone, every flag present, plus supported modalities |
| `PUT` | `/api/projects/:id/system-prompt` | the project's system prompt |
| `PUT` | `/api/projects/:id/origins` | browser origins allowed to call the API |
| `GET` `POST` `DELETE` | `/api/projects/:id/keys[/:keyId]` | project API keys (created ones are shown once) |
| `GET` `POST` `DELETE` | `/api/projects/:id/documents[/:documentId]` | the project-owned corpus |
| `GET` `POST` | `/api/projects/:id/skills` | this project's skills — including end-users' own private uploads, which `visibility` and `owner_subject` tell apart |
| `DELETE` | `/api/projects/:id/skills/:pluginId` | remove one |
| `GET` `POST` `DELETE` | `/api/projects/:id/mcp[/:mcpId]` | the project's MCP servers |
| `GET` `POST` `DELETE` | `/api/projects/:id/webhook-tools[/:toolId]` | [tools the agent calls by URL](./tools.md#tools-you-host-webhook-tools) (the signing secret is returned once) |
| `POST` | `/api/projects/:id/webhook-tools/:toolId/rotate` | a new signing secret; the old one keeps verifying for 24 hours |
| `GET` | `/api/projects/:id/webhook-tools/deliveries` | [recent calls to your handlers](./tools.md#watching-them-work) — when, which tool, what came back |
| `GET` `POST` `DELETE` | `/api/projects/:id/providers[/:credId]` | your own LLM keys |
| `POST` | `/api/projects/:id/providers/:credId/refresh` | re-read a provider's catalog and prices |
| `GET` `POST` | `/api/projects/:id/default-model` | model used when a request names none |
| `PUT` | `/api/projects/:id/retrieval` | embedding and rerank overrides |
| `PUT` | `/api/projects/:id/document-processor` | how documents are read |
| `PUT` | `/api/projects/:id/guardrails` | `oberik.guardrails.set` — [input and output checks](./guardrails.md) |
| `PUT` | `/api/projects/:id/subagents` | `oberik.subagents.set` — which models [delegates](./subagents.md) may run on |
| `PUT` | `/api/projects/:id/citations` | `oberik.citations` — inline markers or a source list |
| `POST` | `/api/projects/:id/retrieval/probe` | `oberik.retrieval.probe` — measure an embedding model's dimension |
| `GET` | `/api/projects/:id/context` | context-window strategy |
| `GET` | `/api/projects/:id/usage` · `/observability` | spend, requests, tokens, latency, per-model and per-user |
| `GET` | `/api/projects/:id/limits` | usage caps on the project's LLM key |
| `GET` | `/api/projects/:id/sessions[/:sessionId/messages]` | every session in the project — [subagents' own](./subagents.md#their-conversations-are-not-in-your-session-list) excluded unless `include_subagents` |
| `GET` | `/api/projects/:id/readiness` | `oberik.readiness` — what still has to happen before this project can answer |
| `GET` | `/api/projects/:id/connect` | `oberik.connect` — the starting snippet and this project's endpoints |
| `GET` `POST` | `/api/projects/:id/webhook-secret[/rotate]` | the key that signs deliveries to you |
| `GET` | `/api/projects/:id/tasks` | scheduled tasks |
| `GET` `DELETE` | `/api/projects/:id/wiki[/:itemId]` | what the agent has written |
| `GET` | `/api/projects/:id/sandboxes` · `/sandbox-host` | live sandboxes, and what they provide |
| `POST` | `/api/projects/:id/sandboxes/:sessionId/:action` | `pause` · `resume` · `delete` |
| `GET` `PUT` | `/api/projects/:id/computer` | `oberik.computer` — [this project's own](./sandbox.md#how-long-a-command-may-run) command timeout and how many sandboxes it may hold |
| `GET` | `/api/orgs/:orgId/projects` · `/costs` | across the organization — **session only**, not a project key |

Creating a project (`POST /api/orgs/:orgId/projects`) and its first key need a signed-in
account rather than a key, so those two steps happen in the dashboard.

### `POST /api/projects/:id/token`

| Field | Type | Meaning |
|---|---|---|
| `subject` | string | who the token is (hierarchical identity path) |
| `scope` | string | visibility boundary — a prefix of `subject` |
| `capabilities` | string[] | intersected with the project's ceiling |
| `roles`, `groups` | string[] | added to the project's defaults; used by document ACLs |
| `models` | string[] | model allow-list |
| `maxEffort` | enum | `minimal \| low \| medium \| high` |
| `maxToolIterations` | number | agent↔tool loop ceiling (default: unlimited) |
| `maxContextTokens` | number | history ceiling for this token, clamped against the project's |
| `expiresIn` | number | TTL in seconds (default 3600) |

Returns `{ access_token, token_type, expires_in, tenant_id, capabilities, scope, allowed_models, max_effort, max_context_tokens }`.
`capabilities` is what was actually granted — compare it with what you asked for to see
what the ceiling trimmed.

## Data plane

### Chat

| Method | Path | SDK |
|---|---|---|
| `POST` | `/chat` | `ai.chat.send` · `ai.chat.run` |
| `POST` | `/chat/stream` | `ai.chat.stream` |
| `GET` | `/chat/stream/{run_id}` | resume (automatic) |
| `POST` | `/chat/stream/{run_id}/cancel` | `handle.cancel()` |
| `POST` | `/chat/stream/{run_id}/steer` | `handle.steer` · `ai.chat.steer` |
| `GET` | `/chat/sessions` | `ai.chat.sessions.list` — [subagents' own conversations](./subagents.md#their-conversations-are-not-in-your-session-list) excluded unless `include_subagents` |
| `GET` | `/chat/sessions/{id}/messages` | `ai.chat.sessions.messages` |
| `GET` | `/chat/sessions/{id}/todos` | `ai.chat.sessions.todos` |
| `GET` | `/chat/sessions/{id}/events` | `ai.chat.sessions.watch` |
| `POST` | `/chat/sessions/{id}/followups` | `ai.chat.sessions.followups` |
| `POST` | `/chat/sessions/{id}/recap` | `ai.chat.sessions.recap` |
| `POST` | `/chat/sessions/{id}/fork` | `ai.chat.sessions.fork` |
| `DELETE` | `/chat/sessions/{id}` | `ai.chat.sessions.delete` |

Answering a paused question is `ai.chat.answer` — a `POST /chat` carrying
`question_answers`, not its own endpoint. Approving a paused action is the same shape
with `approval_decisions`, and returning client-tool results is `tool_results`.

### Browser hand-off

| Method | Path | SDK |
|---|---|---|
| `POST` | `/chat/sessions/{id}/browser/frame` | `ai.chat.sessions.browserFrame` |
| `GET` | `/chat/sessions/{id}/browser/stream` | `ai.chat.sessions.browserStream` (SSE screencast) |
| `POST` | `/chat/sessions/{id}/browser/input` | `ai.chat.sessions.browserInput` |
| `POST` | `/chat/sessions/{id}/browser/check` | `ai.chat.sessions.handoffCheck` |

`ai.chat.sessions.handoff()` wraps all four into one controller — [Handing the page to
the user](./tools.md#handing-the-page-to-the-user).

### Documents

| Method | Path | SDK |
|---|---|---|
| `POST` | `/documents` | `ai.documents.uploadSimple` |
| `GET` | `/documents` | `ai.documents.list` |
| `GET` | `/documents/{id}` | `ai.documents.get` |
| `PATCH` | `/documents/{id}` | `ai.documents.update` |
| `POST` | `/documents/{id}/reingest` | `ai.documents.reingest` |
| `GET` | `/documents/{id}/chunks` | `ai.documents.chunks` |
| `GET` | `/documents/{id}/download-url` | `ai.documents.downloadUrl` |
| `DELETE` | `/documents/{id}` | `ai.documents.delete` |
| `POST` | `/documents/retrieve` | `ai.documents.retrieve` |
| `POST` | `/documents/presign-upload` | `ai.documents.upload` |
| `POST` | `/documents/{id}/presign-parts` | ″ |
| `POST` | `/documents/{id}/complete-upload` | ″ |
| `POST` | `/documents/{id}/abort-upload` | ″ |

### Tools, tasks, triggers

| Method | Path | SDK |
|---|---|---|
| `GET` | `/tools` | `ai.tools.list` |
| `GET` | `/capabilities` | `ai.capabilities` — what this token holds, and which `enable_*` switches are worth setting on it |
| `POST` | `/tasks` | `ai.tasks.create` |
| `GET` | `/tasks` · `/tasks/{id}` | `ai.tasks.list` · `ai.tasks.get` |
| `POST` | `/tasks/{id}/cancel` | `ai.tasks.cancel` |
| `POST` `GET` | `/triggers` | `ai.triggers.create` · `ai.triggers.list` |
| `POST` | `/triggers/{trigger_id}/rotate` | `ai.triggers.rotate` — new URL, old one alive 24h |
| `DELETE` | `/triggers/{trigger_id}` | `ai.triggers.delete` |
| `POST` | `/triggers/{slug}` | **fire one** — no bearer token; the URL is the credential |

### Skills and memory

| Method | Path | SDK |
|---|---|---|
| `POST` | `/plugins` | `ai.plugins.upload` · `ai.plugins.uploadFolder` |
| `GET` | `/plugins` | `ai.plugins.list` |
| `DELETE` | `/plugins/{id}` | `ai.plugins.delete` |
| `GET` | `/memory` | `ai.memory.list` — what the agent remembers, and its wiki pages |
| `DELETE` | `/memory/{item_id}` | `ai.memory.delete` |

### Sandboxes

| Method | Path | SDK |
|---|---|---|
| `GET` | `/computers/host` | `ai.computers.host` |
| `POST` `GET` | `/computers/sessions` | `ai.computers.create` · `list` |
| `GET` `DELETE` | `/computers/sessions/{id}` | `ai.computers.get` · `destroy` |
| `POST` | `/computers/sessions/{id}/pause` · `/resume` | `ai.computers.pause` · `resume` |
| `POST` | `/computers/sessions/{id}/exec` | `ai.computers.exec` |
| `POST` `GET` | `/computers/sessions/{id}/files` | `ai.computers.upload` · `download` |

### Governance

| Method | Path | SDK |
|---|---|---|
| `GET` | `/audit` | `ai.audit.list` |
| `POST` | `/audit/forget` | `ai.audit.forget` |
| `POST` | `/auth/token` | `ai.auth.token` — narrow an existing credential |
| `GET` | `/health` · `/ready` | `ai.health.live` · `ai.health.ready` |

`/tenants` exists too, for a service key provisioning tenants directly — including
`DELETE /tenants/{id}`, which erases a tenant whole: every row carrying its id, its vectors,
its raw bytes in object storage, its sandboxes and its schedules. An integration using
projects never touches it; [deleting a project](./project-api.md#deleting-a-project) calls
it for you.

## Capabilities

The complete set, grouped as the dashboard groups them, with the per-request flag that
can decline each one. Fuller descriptions, and what a token can and can't do with them,
are in [Authentication](./authentication.md#capabilities).

| Group | Capabilities | Per-request flags |
|---|---|---|
| Conversation | `chat`, `system_prompt`, `steer`, `voice` | `enable_voice_control` |
| Knowledge | `documents:read`, `documents:write`, `memory` | `enable_rag`, `enable_memory` |
| Internet | `web_search`, `browser`, `browser_handoff` | `enable_web_search`, `enable_browser` |
| Agentic | `todo`, `computer`, `subagents`, `tasks:read`, `tasks:write`, `triggers` | `enable_todo`, `enable_computer`, `enable_subagents`, `enable_scheduling` |
| Human in the loop | `ask_user`, `approvals`, `ui_tools`, `followups`, `recap`, `auto_title`, `voice:transfer` | `enable_ask_user`, `enable_approvals`, `enable_auto_title` |
| Extensions | `webhook_tools`, `mcp:manage`, `plugins:write`, `action_space` | `enable_webhook_tools`, `enable_plugins`, `enable_action_space` |
| In and out | `input:file` (accept any upload) · `input:image\|audio\|video` (model perceives it directly) · `output:file` (send any produced file) · `output:image\|audio\|video` (model generates it) | `output_modalities` |

The effective answer for any tool family is always **project ceiling ∩ token capability ∩
per-request flag**, plus `allowed_tools` if you set one. A client can always decline; it
can never exceed.

## For agents

This documentation is published in machine-readable form:

- [`llms.txt`](pathname:///docs/llms.txt) — the index
- [`llms-full.txt`](pathname:///docs/llms-full.txt) — every page, one file
- [`api.oberik.com/openapi.json`](https://api.oberik.com/openapi.json) — the data plane's
  own schema, generated from the running code

---

## Voice


:::info Preview — enabled per account

Voice is not generally available. The **Voice** switch does not appear under Capabilities
until your account is added to the rollout, and until then a token cannot carry the `voice`
capability at any ceiling — so there is nothing to turn on and nothing to misconfigure.
[Ask us to enable it](mailto:hello@wite.com.tr) and the switch appears where this page says
it is.

The reason it is gated rather than simply off by default: a call holds a live speech session
for its whole duration, so it is the one capability whose cost is a machine rather than a
request.

:::

With the `voice` capability your users can **talk** to the agent. Not speech-to-text, a
model, and text-to-speech glued together — a full-duplex speech model that hears them while
it is speaking, so they can interrupt it mid-sentence and it stops.

The part that makes it usable for real work is the split:

| | Owns |
|---|---|
| The speech frontend | The **talking**. Timing, interruptions, backchannels, prosody, the "yeah, let me check" while it waits. |
| The model you chose | The **answer**. Whatever model your project is configured for, with your documents, tools, memory and sandbox behind it. |
| Oberik | The **waiting**. Bridging a 300ms gap, holding for a 30-second lookup, transferring to a person. |

So the voice does not change when the substance arrives. The caller hears one agent saying
"yeah, let me check — it left the warehouse yesterday and it's expected Friday", and the
second half of that sentence came from your model. Change the model and the voice is
identical.

## Enable it

1. **Capabilities**: turn on *Voice* for the project. Turn on *Transfer to a person* too if
   the agent should be able to escalate.
2. **Token**: include `voice` (and `voice:transfer`) in the capabilities you mint.
3. **Open a call**: `POST /voice/sessions`, then stream audio.

```ts
const call = await af.voice.open({
  voice: "warm",
  role: "support",
  waiting: { strategy: "auto", barge_in: true },
});

call.on("state", (s) => setStatus(s.status));       // "Listening" · "Thinking" · "On hold"
call.on("caller.transcript", (t) => addLine("them", t.text));
await call.send(micPcm);                            // 16-bit PCM, any rate
```

The token is the same end-user JWT everything else uses, and the turn behind the voice is an
ordinary turn — same capability gate, same tool allow-list, same per-customer cost
attribution. There is no separate voice agent to configure.

Two options worth knowing about at setup:

```ts
const call = await af.voice.open({
  // Narrow what this call may use. Intersected with what the token already allows, so a call
  // can decline a tool and never buy one. Omit for everything the token allows.
  allowed_tools: ["search_documents", "get_order_status"],
  // Which checkpoint on the speech host, where it serves more than one. `af.voice.frontend()`
  // lists them. Asking for one it does not serve is a 400 rather than a silent fallback.
  voice_model: "support-tuned",
});
```

Narrowing is worth doing. A support line has no business running sandboxed compute, and every
tool the model can see is a tool it can spend a caller's silence on.

### Which speech model

The **Speech frontend** setting on a project picks which one runs its calls. Blank uses the
deployment's default, and every project should be on that unless it is deliberately comparing.

| Frontend | What it is | How a lookup starts |
|---|---|---|
| `personaplex` | A self-hosted full-duplex model. The answer is spoken into it word by word as it streams. | The runtime decides, from the caller's words and the model's own. |
| `openai` | OpenAI's hosted realtime API. | **The model asks**, by calling a tool; the runtime stands down. |
| `nemotron` | NVIDIA's NemotronLabs VoiceChat container. | The model asks, as above. |

The difference in that last column is the one that matters. On a frontend that asks for itself,
the model owns the decision: a social turn delegates nothing, and a turn it does not ask about is
not looked up. On `personaplex` the runtime routes, because that model has no tool channel.

**`openai` needs a key, and if you have already registered one it is used.** A project with an
OpenAI provider under **LLM & limits** needs nothing here: calls use that credential. The box on
this tab is for the case where you want a *different* key for calls than for the rest of the
project — it is billed to your own account and is never sent back to the dashboard, so an empty box
means "keep the stored one". So the order is:

1. a key set on the Voice tab, when you deliberately set one;
2. otherwise the project's registered `openai` provider key;
3. otherwise the deployment's own, if it has one.

A project with none of the three is refused at `POST /voice/sessions` with a 400 rather than
failing mid-call. `GET /voice` reports which of the three answers, as `openaiApiKeyFrom`.

Whichever you pick, Oberik is reached the same way: the model calls one tool with the caller's
intent in plain words, or a second tool that takes no arguments at all and lets Oberik read the
conversation. The answer comes back as a fact to relay or as a question to put to the caller, and
the model does the relaying in its own voice.

## Saying something the agent could not know

Two channels, deliberately different. `inject()` is "know this"; `say()` is "say this".
Conflating them is what makes an agent recite a reference number.

```ts
await call.inject({ tier: "enterprise", customer_id: "c_8812" });  // shapes tone, never spoken

const r = await call.say("Sorry to interrupt — that card was just declined.");
if (!r.spoken) console.warn("not said:", r.reason);
```

`say()` is for what only your application knows in the moment: a card that was just declined,
an appointment that has moved, a line compliance requires on every call. **Not for answers** —
an answer is a turn, and it gets a model, a bridge while it is being composed, and a latency you
can measure. Text pushed through `say()` gets none of those.

It goes through the same machinery the agent's own speech does, so the caller can talk over it.
That is the point: a line the caller cannot interrupt is a line they keep hearing while they are
trying to object to it.

By default it **takes the floor** — an answer being spoken is abandoned, and `displaced_chars`
says how much of it was. That is right for what this is for; a declined card outranks the
sentence it lands in the middle of. Pass `{ interrupt: false }` for a disclosure that should
wait, and it is refused rather than chopping an answer in half.

Always check `spoken`. On hold, mid-transfer, or against a speech host that cannot be forced,
the honest answer is no and `reason` says which — and an application told its compliance line was
read when it was not has no way to find out.

## What a caller actually hears

A call where the answer takes a second and a half:

```
0ms      the caller stops talking
~200ms   "Yeah, absolutely—"                 ← the frontend, covering the gap
~250ms   the model starts, calls a tool
~1500ms  "...it left the warehouse yesterday and it's expected Friday."
                                             ← the model's words, the same voice
```

They never experienced a 1.5-second delay. And if they interrupt halfway through —
*"actually, never mind, I found the email"* — the agent stops inside 200ms, the answer is
abandoned, and nothing from it is ever spoken. Not "queued and skipped": a superseded answer
cannot reach the caller, by construction.

## Waiting

A gap of 300ms and a gap of 30 seconds are different problems, and covering both with a
longer "let me see" gets the second one wrong. Oberik picks from four behaviours, using what
it has actually measured for your models and tools rather than a guess:

| | |
|---|---|
| **Bridge** | Under two seconds. The agent says something noncommittal — “yeah, let me check” — and the answer arrives inside it, so the caller never hears a gap |
| **Wait** | Two to ten seconds. The agent says once that it is looking something up, then goes quiet |
| **Hold** | Longer than ten seconds. The agent tells the caller it is putting them on hold, hold media takes over the line, and the work carries on independently |
| **Transfer** | A hold whose resolution is a person rather than a result |

The filler is deliberately noncommittal. "Yeah—" and "okay, so—" leave the sentence open for
whatever the model says next; the agent never guesses at the answer, because whatever it
guessed the model might contradict and the caller would have heard both.

### Hold

A hold is a state, not a sentence. The caller hears hold media, the work carries on, and —
this is the part most systems get wrong — **they can still speak**. A caller who says "never
mind" into thirty seconds of hold music and is not heard has been hung up on by a system
that thinks it is being helpful.

Four listening policies, because the cost is real: keeping the full speech session live for a
ninety-second hold is a machine doing nothing.

| `listen` | |
|---|---|
| `full` | The speech model stays live. Barge-in, corrections, everything |
| `interrupt_only` | Cheap detection for a wake or a cancel, rather than the full model. The default |
| `dtmf_only` | Keypad only — "press 1 to come back" |
| `off` | Nothing. Only where being interrupted would break something |

Coming back is one moment, not two: the media fades and the agent speaks into it. "Thanks for
waiting — I found it, the replacement is with the courier."

When the slow thing is **yours** — a CRM lookup, a booking system, your own backend — let the
SDK own the race:

```ts
const account = await call.holdUntil(
  () => crm.expensiveLookup(customerId),
  { reason: "looking up the account", maxSeconds: 90 },
);
if (account.outcome === "done") {
  // The caller is already back and has heard "thanks for waiting". Say the answer.
}
```

Four things can happen and all four come back rather than throwing: the work finishes, it
fails, the ceiling is reached, or **the caller talks their way out of it**. That last one is why
this exists — getting it right by hand means racing four conditions and cancelling in the right
order.

Your agent can ask for a hold itself when it knows something is slow:

| Tool | |
|---|---|
| `voice_hold` | put the caller on hold because this will take a while |
| `voice_resume` | come back, then say the answer |
| `voice_transfer` | hand the call to a person (needs `voice:transfer`) |

It does not need these for an ordinary tool call — short waits are covered automatically.
They are for when the agent already knows the alternative is silence.

### Deep hold

A ninety-second wait for a human agent is ninety seconds of an expensive speech session
generating nothing, and the hold media does not come from the model — so there is nothing for it
to do. A **deep** hold releases the session and restores it on the way back.

Two conditions, and Oberik refuses rather than pretending when either fails:

- The frontend must genuinely be able to restore. Parking one that cannot come back means a
  resumed call arrives as a subtly different agent mid-conversation, which is worse than an
  expensive one.
- The hold cannot be listening. A parked session has nothing to hear with, and a hold that
  claimed to keep listening would be deaf and say otherwise.

Where either fails the session stays resident and the call reports why. So a deep hold is worth
asking for on a `listen: "off"` or `dtmf_only` wait for a person, and is not available on the
short lookups where you would want barge-in anyway.

### Transfer

A warm transfer: the caller waits on hold while the agent briefs whoever is picking up with
the context you asked for, then they are connected. If nobody takes it, **the caller comes
back to the agent** rather than to a dead line — which is the whole reason to do this here
rather than in your phone system.

## What the agent says itself, and in which language

Almost everything on the call comes from your model. A handful of things do not — the filler
that covers a gap, the sentence announcing a hold, the line it comes back on, the apology when
the model falls over. Those are Oberik's own words, and there are two reasons you would want to
change them:

- **Language.** An English "Yeah—" spoken into a Turkish call is not a small blemish, it is the
  feature working *incorrectly*.
- **Register.** "Yeah—" is wrong for a private bank, and every other utterance on the call
  already follows your system prompt.

So they are a project setting, editable in the dashboard under **Voice** — one box per line,
with what each one is for beside it, and a badge saying whether it is yours, the built-in, or a
line the agent currently stays silent on. Or over the API:

```bash
curl -s localhost:8000/api/projects/$ID/voice -X PUT \
  -H "X-API-Key: $KEY" -H 'content-type: application/json' \
  -d '{
        "language": "tr",
        "phrases": {
          "bridge.open": ["Tabii—", "Şey—"],
          "hold": "Bu biraz uzun sürecek. Kontrol ederken sizi beklemeye alıyorum.",
          "resume.done": ["Beklediğiniz için teşekkürler—"]
        }
      }'
```

`voice show` lists every line with what it is for. `language` blank takes the speech host's
answer, which is the right default — a voice is trained in a language and the host is the one
that knows.

**Two rules, and they are enforced.** A `bridge.*` or `resume.done` line must end **open** —
with a dash, an ellipsis or a comma — because the model's answer continues the same sentence.
And a `bridge.*` line must commit to nothing: it is spoken before the answer exists, so if it
says "yes" and the model then says no, the caller has heard both. `"I think it's probably—"` is
refused for the same reason, and so are `"Unfortunately—"`, `"Good news—"` and
`"That order has shipped—"`.

Both are checked when you save, not on the call — so you find out at the box you typed it in.

:::info Which of the two ran, in your language

The **shape** rule is typographic and holds for any language. The **commit-to-nothing** rule is
English morphology, and it only runs for English wording: it can see that `"Yes, it's ready—"`
answers the question and it cannot see that `"Evet, hazır—"` does.

So a project configuring non-English phrases gets a `warning` on the save saying exactly that,
rather than a silent pass that reads like approval. The rule still applies — a filler that
answers the question before the model has is still wrong, and still worth writing carefully —
it is just not something we can catch for you. `voice show` prints what each line is for, which
is the thing to write against.
:::

**What happens in a language we have no words for.** Nothing is said. Not English — a sentence
the caller cannot understand is worse than silence, so the agent stays quiet where it would have
spoken and the call reports which lines those were, in `phrases_missing` on the session and as
an `error` event. A missing filler means the speech model covers its own gap, which it is good
at; a missing hold announcement means the media takes over unannounced, which is worse and still
better than a sentence nobody follows.

The built-in set is English only. Configuring your own is how any other language works, and the
dashboard's Voice tab — or `voice show` — tells you exactly which lines are still silent.

Give a line **several** entries and it rotates, so a caller who waits twice does not hear the
same sentence twice. In the dashboard that is one per line in the box; over the API it is a list.

## Numbers said correctly

A speech layer must not round a balance. Mark anything that has to survive exactly and it is
spoken verbatim, never paraphrased, and never split across a pause:

```
Your balance is <verbatim>£1,847.23</verbatim> and the invoice is due
<verbatim>31 August</verbatim>.
```

If a caller interrupts partway through one of those, the call reports that the figure was
**not** conveyed — rather than assuming that no error means it was heard. That is checked
against what the frontend actually said, frame by frame, not against what was queued: the two
differ by exactly the interesting amount whenever somebody interrupts.

Three fidelity modes: `strict` (every character, for figures and disclosures), `natural` (the
default — punctuation may adapt, meaning may not), and `free` (the agent may paraphrase). In
`strict`, a figure that did not reach the caller produces an `error` event on the call, because
that is precisely the thing you asked to be told about.

## On the telephone

| | |
|---|---|
| Browser / app | WebRTC or a WebSocket, full quality |
| Phone number | Twilio Media Streams, or RTP behind your own SIP termination |

Oberik carries the **audio** of a SIP call — RTP, µ-law, keypad input as RFC 4733 events. It
does not do the signalling: no INVITE, no SDP, no registration. Point whatever already
terminates SIP for you at it — an SBC, a media gateway, FreeSWITCH, Twilio's SIP interface —
which is the same division Twilio itself makes between Media Streams and TwiML.

One consequence worth knowing before you build against it: on RTP the agent cannot be told when
audio has *played*, only that it was sent. So `verbatim` figures are still checked against what
the frontend said, and never against a playout report that does not exist.

A PSTN call is 8 kHz µ-law — a quarter of the bandwidth the speech model generates. That is
the telephone network, not a setting, so a phone call will not sound like the browser demo.
What Oberik does guarantee is that it sounds like a *phone call* rather than like aliasing,
and every call reports whether it is on a narrowband channel.

Barge-in on a phone needs one thing most integrations miss: when the caller starts talking,
audio already sent to the carrier has to be **dropped**, not just stopped at the source.
Oberik sends Twilio's `clear` for exactly this. Without it a caller interrupts and then
listens to a second of the agent still talking, which reads as rudeness rather than as a
limitation.

## Watching a call

Every call emits a stream of events — the same ones the dashboard's **Try agent** page
renders. The ones worth wiring into your own UI:

| Event | |
|---|---|
| `state` | the call moved: `listening` · `delegating` · `bridging` · `external_speech` · `holding` · `resuming` · `transferred` |
| `caller.transcript` | what the caller said |
| `voice.bridge` | the filler it chose, and how long it expects to need it |
| `voice.takeover` | the model's words are now being spoken |
| `voice.interrupted` | the caller barged in; what was spoken and what was dropped |
| `hold.entered` / `resume.done` | hold media on and off |
| `delegate.failed` | the model could not answer, and the agent is recovering conversationally |

And a set of latencies, because a voice agent lives or dies on them and an average that
excludes the turns it dropped gets *better* as the system gets worse:

| | |
|---|---|
| `response_start` | caller stops → the agent says anything at all |
| `answer_start` | caller stops → the agent says something with substance in it |
| `barge_in_stop` | caller starts → the agent has stopped |
| `tool_to_spoken` | a tool finished → the answer is being spoken. Separates a slow tool from a model that is slow to compose from a result it already has |
| `dropped_turns` | requests that never produced an answer. Reported beside the timings, never folded into them |
| `unwanted_barge_ins` | the agent stopped for something that turned out not to be a request — an acknowledgement, a "mm-hmm". Counted apart from `barge_ins`, because that raw count going up can mean the feature is working and this one going up cannot |
| `false_interruptions` | the agent stopped and the caller then said nothing at all. The number that says whether the detection threshold is set for the room the call is actually in |

And one number that is not a latency. `word_error` compares what the model produced against
what the caller actually heard, per turn:

Because the frontend is handed the model's own characters, this is designed to be **zero**.
Anything above it is a lossy path — a dropped chunk, a cut span — and not a paraphrase, which
is exactly why it is worth reporting. Turns the caller interrupted are reported separately and
excluded from the call's figure: an answer abandoned on purpose is not a transcription failure.

## Sent, said, heard

Three different facts, reported separately, because a system that cannot tell them apart will
act on the first when only the third matters.

- **sent** — the runtime released the text.
- **said** — the agent realised it as audio. `verbatim` figures report `delivered`.
- **heard** — the caller's own player got that far. `verbatim` figures report `heard`.

The third needs evidence from your side of the wire. The server places a mark at the point each
protected figure finishes being spoken and tells you about it (`media.mark_placed`); confirm it
with `markPlayed(mark)` once your player has played past it. The SDK's browser player does this
for you.

`heard` is three-valued and `null` means **unknown** — either your transport cannot report
playout, or the confirmation has not arrived yet. Not `false`: a network round trip is not a
defect, and rendering it as one shows every figure as lost for a moment after it was spoken.
Once the call has ended, an outstanding mark is a `false` — the confirmation is not coming.

If you cannot honestly tell when audio played, do not confirm. A mark confirmed early tells the
server a sentence was heard while it was still queued, which is the one fact a compliance
readback must not get wrong.

## Limits

- One live speech session per call, for the call's whole duration. This is the one capability
  whose cost is a machine rather than a request, so a deployment caps how many it accepts —
  `voice_max_concurrent`.
- A call has a duration ceiling. A token can narrow it (`max_voice_seconds`) and never widen
  it.
- The agent does not work through bot checks, on a call or anywhere else.