@oberik/sdk 0.1.0 → 0.3.0

package/dist/esm/index.d.ts

@@ -82,6 +82,8 @@ export interface ClientOptions {
     headers?: Record<string, string>;
     /** Client-side tools registered up-front; auto-dispatched by chat.run/stream. */
     tools?: ClientToolDef[];
+    /** UI components the agent can draw into your app. Needs the `ui_tools` capability. */
+    ui?: UiComponent<any>[];
 }
 /** Public tenant view — never includes the API key. */
 export interface TenantOut {
@@ -540,10 +542,86 @@ export interface QuestionAnswer {
 }
 /** Answer a batch of questions. Return one entry per question (or a single
  *  `{ chat_instead: true }` to decline the whole batch and keep chatting). */
+/** An Agent Plugin visible to this token: what the project published, plus anything
+ *  this end-user uploaded. */
+export interface PublishedPlugin {
+    id: string;
+    name: string;
+    version?: string | null;
+    description: string;
+    /** `tenant` = published by the project to everyone; `private` = this user's own. */
+    visibility: string;
+    owner_subject?: string | null;
+    enabled: boolean;
+    size_bytes: number;
+    /** Each skill's name and description are all the agent sees until it loads one, so
+     *  the description is the line that decides whether a procedure ever gets used. */
+    skills: {
+        name: string;
+        description: string;
+        files: string[];
+    }[];
+    mcp_servers: string[];
+    /** Wrong but not fatal — a skill that would not parse, a server that was refused.
+     *  Worth surfacing: a plugin whose skill silently did not load is the failure people
+     *  spend an afternoon on. */
+    warnings: string[];
+}
+/** A component your app can render, declared for the agent to call.
+ *
+ *  The difference from a client tool is that there is no result. A client tool is work
+ *  handed back — the turn stops, you run it, the answer returns. This is a one-way
+ *  instruction: the agent calls it, your `render` runs, and the turn carries straight
+ *  on. Use it wherever showing beats describing. */
+export interface UiComponent<A = Record<string, unknown>> {
+    name: string;
+    /** What it shows, and when the agent should reach for it. The agent picks from this,
+     *  so "Draw a line chart of a numeric series over time" beats "chart". */
+    description: string;
+    /** JSON Schema for the arguments, exactly as a client tool declares them. */
+    parameters?: Record<string, unknown>;
+    /** Called when the agent draws it. Return nothing — anything you return is dropped,
+     *  because the agent is not waiting. */
+    render: (args: A) => void;
+}
+/** One thing the agent drew, as it comes back on the turn. */
+export interface UiRender {
+    name: string;
+    args: Record<string, unknown>;
+}
+/** Something the agent stopped to ask permission for.
+ *
+ *  Arrives with `requires_action` and an EMPTY `tool_calls`: an approval is not the
+ *  client's work to execute, so tool auto-dispatch can never grant one on the user's
+ *  behalf. It has to reach a person. */
+export interface PendingApproval {
+    tool_call_id: string;
+    /** One line saying exactly what the agent will do, with the specifics in it. */
+    action: string;
+    /** What the person needs in order to decide — the message, the command, the rows. */
+    detail?: string | null;
+    /** What cannot easily be undone. Usually the only part that decides the answer. */
+    consequence?: string | null;
+}
+/** A person's answer to one approval pause. */
+export interface ApprovalDecision {
+    tool_call_id?: string;
+    approved: boolean;
+    /** The difference between "no" and "no, use the other address". */
+    note?: string | null;
+}
+/** Put the request to a person and return their decision.
+ *
+ *  Throwing, or returning `false`, is a refusal — and a refusal stops the work: the
+ *  agent is told not to try another way and to ask what you want instead. */
+export type ApprovalHandler = (request: PendingApproval) => ApprovalDecision | boolean | Promise<ApprovalDecision | boolean>;
 export type QuestionHandler = (pending: PendingQuestions) => QuestionAnswer | QuestionAnswerItem[] | Promise<QuestionAnswer | QuestionAnswerItem[]>;
 export interface RunOptions extends Omit<ChatRequest, "tool_results" | "client_tools"> {
     /** Extra client tools for this call (merged over any registered on the client). */
     tools?: ClientToolDef[];
+    /** UI components for this call (merged over any registered on the client). Needs the
+     *  `ui_tools` capability. */
+    ui?: UiComponent<any>[];
     /** Max auto tool-dispatch rounds before giving up (default 10). */
     maxToolRounds?: number;
     /** Fires before each batch of client tools is executed. */
@@ -551,10 +629,24 @@ export interface RunOptions extends Omit<ChatRequest, "tool_results" | "client_t
     /** Answer the agent's questions and continue the turn automatically. Without it,
      *  `run` returns as soon as the agent asks, with `questions` set. */
     onQuestion?: QuestionHandler;
+    /** Decide the agent's approval requests and continue the turn. Without it, `run`
+     *  returns as soon as the agent asks, with `approvals` set — which is the right
+     *  default: nothing should be able to approve an irreversible action by accident. */
+    onApproval?: ApprovalHandler;
     signal?: AbortSignal;
 }
-/** A non-text input part (any modality the model supports). `url` is a data: URI or
- *  an https URL. Gated by the token's `input:<kind>` capability. */
+/** A non-text input part. `url` is a data: URI or an https URL.
+ *
+ *  Two capabilities decide what happens to it, and they are separate on purpose:
+ *
+ *    - `input:file` accepts ANY attachment — a PNG and a WAV included. What the model
+ *      cannot perceive is read as text instead (OCR for a scan, a transcript, an
+ *      extraction), so granting it costs fidelity, never access.
+ *    - `input:image` / `input:audio` / `input:video` additionally let the model look at
+ *      that kind with its own senses, raw.
+ *
+ *  So a project that just wants users to attach whatever they have grants `input:file`;
+ *  one that wants the model to actually SEE the picture grants `input:image` too. */
 export interface Attachment {
     /** Stable identity, set on anything the agent produced. Match on this, not on `url`:
      *  a URL is signed per response, so the same file arrives with a different one from
@@ -623,14 +715,39 @@ export interface ChatRequest {
     messages?: string[] | null;
     /** Multimodal inputs (images/audio/video/files) for this turn. */
     attachments?: Attachment[] | null;
-    /** Modalities the model may return, e.g. ["text","image"]. Bounded by the token's
-     *  output:<modality> capabilities; ignored by text-only models. */
+    /** Modalities the MODEL may generate this turn, e.g. ["text","image"]. Bounded by the
+     *  token's `output:<modality>` capabilities; ignored by text-only models.
+     *
+     *  Nothing to do with what the agent may hand over as a file: a screenshot it took or
+     *  a chart it rendered in a sandbox is a file it produced, not a modality it emitted,
+     *  and `output:file` is what permits sending those — any of them, pictures included. */
     output_modalities?: string[] | null;
     tool_results?: ClientToolResult[] | null;
     /** Resume a turn paused on `ask_user`. The wording the agent reads is composed
      *  server-side from the question it actually asked, so the transcript can't drift
      *  from what was on screen. */
     question_answers?: QuestionAnswer[] | null;
+    /** UI components the agent may draw this turn. `chat.run`/`chat.stream` fill this in
+     *  from the components you registered — set it directly only on a raw `/chat` call. */
+    ui_tools?: Record<string, unknown>[] | null;
+    /** Answers to approval pauses, resuming the turn. */
+    approval_decisions?: ApprovalDecision[] | null;
+    /** Let the agent stop and ask permission before an action with consequences. Needs
+     *  the `approvals` capability. Set false for any caller that cannot answer — a batch
+     *  job, a webhook — so the agent never stalls waiting on a decision. */
+    enable_approvals?: boolean;
+    /** Let the agent reach for the skills published to this project. Needs the `plugins`
+     *  capability. */
+    /** Let the agent call the tools this project publishes as URLs — Oberik POSTs to
+     *  the customer's endpoint with the end-user's identity signed into the body. Needs
+     *  the `webhook_tools` capability. Turn it off for a turn that should not touch your
+     *  systems. */
+    enable_webhook_tools?: boolean;
+    enable_plugins?: boolean;
+    /** Which plugins this turn may use, by name. Omit for everything the token can see.
+     *  Narrowing only — a name that is not visible is absent rather than an error, so a
+     *  pinned list does not start failing turns the day someone deletes one. */
+    plugins?: string[] | null;
     /** The user pressed Done on a page the agent handed them. Resumes a turn that
      *  stopped on a blocking hand-off — the button IS the answer, so nothing else is
      *  needed with it. */
@@ -661,8 +778,6 @@ export interface ChatRequest {
     /** Attach a specific existing sandbox to this turn (reconnect to a prior session).
      *  Omitted = the sandbox bound to this chat session, else a fresh one. */
     computer_session_id?: string | null;
-    /** Let the agent run read-only SQL against connected query-mode data sources. */
-    enable_data_query?: boolean;
     /** Let the agent drive a real browser — click, type, scroll, wait, capture — rather
      *  than fetching one page at a time. Needs the `browser` capability and the browser
      *  service; `web_search`/`browse_url` work without it. */
@@ -692,7 +807,27 @@ export interface PendingToolCall {
     name: string;
     args: Record<string, unknown>;
 }
+/** One sentence, and the passages it came from.
+ *
+ *  `citations` is still the whole retrieval set — a client may want to show what was
+ *  searched — but this is what answers "where did THAT come from". Before it existed the
+ *  docs promised a citation "for every claim" and delivered the retrieval set in score
+ *  order, so a question whose answer lived in one chunk came back with three "sources" and
+ *  a UI built as instructed showed the reader citations that did not support the sentence. */
+export interface Claim {
+    text: string;
+    /** Offsets into `content`. Null when the claim could not be located after markers were
+     *  stripped — better absent than pointing at the wrong span. */
+    start: number | null;
+    end: number | null;
+    /** `Citation.marker` values, in the order the model wrote them. */
+    citations: number[];
+}
 export interface Citation {
+    /** The number the model was shown for this passage, and what a `Claim` refers to. */
+    marker?: number | null;
+    /** Whether a sentence was actually attributed to it. */
+    used?: boolean;
     document_id: string;
     chunk_index: number;
     filename: string | null;
@@ -701,10 +836,9 @@ export interface Citation {
     quote: string | null;
 }
 /** A unified source for UI rendering (clickable pill) — a document citation, a
- * web result/page, or a database query. `type` = "document" | "web" | "query"
- * (query sources carry the executed SQL in `snippet` for verifiability). */
+ * web result/page. `type` = "document" | "web". */
 export interface Source {
-    type: "document" | "web" | "query" | string;
+    type: "document" | "web" | string;
     title?: string | null;
     url?: string | null;
     snippet?: string | null;
@@ -723,6 +857,10 @@ export interface ChatResponse {
      *  auto-dispatch can never answer it on the user's behalf. Resume by sending
      *  `question_answers` (or let `chat.run`/`chat.stream` do it via `onQuestion`). */
     questions: PendingQuestions[];
+    /** The agent stopped before doing something and is waiting to be allowed. Same shape
+     *  of pause as `questions`, and likewise never in `tool_calls`. Resume by sending
+     *  `approval_decisions` (or let `chat.run`/`chat.stream` do it via `onApproval`). */
+    approvals: PendingApproval[];
     /** The agent's plan for this session, when the todo family ran this turn. */
     todos: TodoItem[];
     /** Every subagent of this conversation, including ones still working — a turn ending
@@ -731,17 +869,41 @@ export interface ChatResponse {
     /** Set only when history had to be trimmed or summarized to fit the window. */
     context?: ContextReport | null;
     citations: Citation[];
+    /** Sentences attributed to a passage, in order. Empty when the model emitted no markers,
+     *  which `attribution` reports rather than hiding. */
+    claims: Claim[];
+    /** `per-claim` · `retrieval-only` · `none`. Draw footnotes from `claims` on the first;
+     *  on the second you have the retrieval set and no attribution, which is a different
+     *  thing to show. */
+    attribution: "per-claim" | "retrieval-only" | "none";
+    /** Set when the agent put a page in front of the user. Declared here as well as on
+     *  `ChatDone`: a `chat.send()` caller could not learn a hand-off had happened at all,
+     *  while the docs say the blocking path carries `handoff.blocking`. */
+    handoff?: Handoff | null;
     sources: Source[];
     /** Non-text outputs of the turn: generated media, and files the agent exported
      *  from its sandbox. `url` is signed fresh per response — don't persist it. */
     attachments: Attachment[];
+    /** Components the agent drew this turn, in call order. `chat.run`/`chat.stream` have
+     *  already called each component's `render` by the time you see this; it is here so a
+     *  client that re-mounts can redraw from the list. */
+    ui: UiRender[];
     /** Guardrail actions taken this turn, e.g. "pii:EMAIL", "ungrounded", "injection". */
     guard_flags: string[];
     /** A reasoning model's thinking for this turn, else "". Live only — it is not stored
      *  and is never sent back to the model, so it won't appear in session history. */
     reasoning?: string;
-    /** Non-normal stop reason, else null. "max_tool_iterations" when a token's
-     *  tool-loop ceiling was hit. Language-neutral — localize it yourself. */
+    /**
+     * Non-normal stop reason, else null. Language-neutral — localize it yourself.
+     *
+     *   `max_tool_iterations`  a token's tool-loop ceiling was hit; `content` is the answer
+     *                          produced so far
+     *   `guardrail`            an input guardrail refused the message
+     *   `no_model`             the PROJECT has no model configured, so nothing could run.
+     *                          Not the end-user's problem and not something they can fix —
+     *                          route it to whoever set the project up. `GET /readiness` on
+     *                          the control plane lists what is missing.
+     */
     finish_reason?: string | null;
 }
 export interface SessionOut {
@@ -797,42 +959,139 @@ export interface TaskOut {
     last_error: string | null;
     created_at: string;
 }
-export type ConnectorType = "postgres" | "http" | string;
-export interface SyncConfig {
+/** A project's guardrail policy, complete — an untouched field reads as its default
+ *  rather than as missing. */
+export interface GuardrailPolicy {
+    enabled: boolean;
+    input: {
+        injection: boolean;
+        blockedTopics: string[];
+        pii: PiiMode;
+    };
+    output: {
+        groundedness: boolean;
+        moderation: boolean;
+        pii: PiiMode;
+    };
+    /** Which model judges. Null = the turn's own model. */
+    guardModel: string | null;
+    /** `block` refuses the turn; `flag` allows it and annotates `guard_flags`. */
+    onViolation: "block" | "flag";
+}
+/** Off is the default and deliberately so: on a product where an end-user shares their own
+ *  information on purpose, the model has to see it. `detect` records that it was there;
+ *  `redact` keeps it from the provider and costs the agent the ability to use it. */
+export type PiiMode = "off" | "detect" | "redact";
+/** Flat, because that is what a form sends. Anything omitted is left unchanged. */
+export interface GuardrailUpdate {
+    enabled?: boolean;
+    injection?: boolean;
+    blockedTopics?: string[];
+    inputPii?: PiiMode;
+    groundedness?: boolean;
+    moderation?: boolean;
+    outputPii?: PiiMode;
+    guardModel?: string;
+    onViolation?: "block" | "flag";
+}
+/** What still has to happen before a project can answer a question. */
+export interface ProjectReadiness {
+    ready: boolean;
+    /** The first blocking step, so one line of UI has something to render. */
+    next: ReadinessStep | null;
+    steps: ReadinessStep[];
+}
+export interface ReadinessStep {
+    id: string;
+    done: boolean;
+    /** What stops working while this is undone — "every request", "every document upload". */
+    blocks: string;
+    what: string;
+    /** The one call, or the one screen, that fixes it. */
+    how: string;
+}
+export interface ConnectInfo {
+    projectId: string;
+    tenantId: string | null;
+    controlPlaneUrl: string;
+    dataPlaneUrl: string;
+    /** Copy-pasteable: the server half and the app half, using both clients correctly. */
+    snippet: string;
+}
+/** What a project key may do. An admin key satisfies a mint requirement, never the
+ *  reverse. */
+export type ProjectKeyScope = "admin" | "mint";
+export interface ProjectKeyInfo {
+    id: string;
     name: string;
-    connector_type: ConnectorType;
-    /**
-     * "sync" (default) copies records into the vector store (RAG over the data).
-     * "query" is live query-in-place: the agent runs read-only SQL against the source
-     * at question time — the right mode for structured/analytical data (postgres only).
-     */
-    mode?: "sync" | "query";
-    /** Connector-specific config (dsn/query, token/repo, ...). Holds secrets. */
-    config: Record<string, unknown>;
-    /** Auto-refresh cadence in seconds; 0 = manual only. Default 3600. Ignored for query mode. */
-    sync_interval_seconds?: number;
-    tags?: string[];
-    visibility?: "self" | "private" | "shared" | "groups" | "tenant";
-    visibility_scope?: string | null;
-    acl_roles?: string[];
-    acl_groups?: string[];
+    scope: ProjectKeyScope;
+    /** The visible stub, e.g. "pk_ab12…". The key itself is shown once, at creation. */
+    prefix: string;
+    lastUsedAt: string | null;
+    createdAt: string;
+}
+/** What a token holds, and which per-turn switches are worth setting on it. */
+export interface TokenCapabilities {
+    subject: string;
+    scope: string;
+    /** `null` = unrestricted (a service key), which is NOT the same as an empty list. */
+    capabilities: string[] | null;
+    flags: {
+        flag: string;
+        /** Any one of these is enough to grant it. Empty = ungated. */
+        capability: string[];
+        granted: boolean;
+        platform_enabled: boolean;
+        /** Whether setting this flag on a request would change anything. */
+        effective: boolean;
+        label: string;
+        description: string;
+        group: string | null;
+    }[];
+    modalities: {
+        /** What may be attached. */
+        input: string[];
+        /** What the model perceives directly; the rest arrives as extracted text. */
+        native: string[];
+        /** What the agent may hand back. */
+        output: string[];
+    };
+    limits: {
+        max_effort: string | null;
+        max_tool_iterations: number | null;
+        max_context_tokens: number | null;
+    };
 }
-export interface SourceOut {
+/** A URL that starts a turn when something happens in another system. */
+export interface Trigger {
     id: string;
     name: string;
-    connector_type: ConnectorType;
-    mode: "sync" | "query";
-    /** Config key names only — secret values are never returned. */
-    config_keys: string[];
-    sync_interval_seconds: number;
-    tags: string[];
+    prompt: string;
+    enabled: boolean;
+    /** Events that started a run. A sender's retry of the same event is not counted twice. */
+    fired_count: number;
+    last_fired_at: string | null;
+    last_error: string | null;
+    /** Absolute, and give it to the other system. Not shown-once: their configuration holds
+     *  it, so we cannot forget it on their behalf. */
+    url: string;
+    /** Only on create and rotate. Sign the body with it and the URL stops being a bearer
+     *  token: `X-Signature: sha256=<hmac>`. */
+    secret?: string | null;
+}
+/** One memory or wiki page. */
+export interface KnowledgeItem {
+    id: string;
+    kind: "memory" | "wiki" | string;
+    title?: string | null;
+    text: string;
+    owner_subject?: string | null;
     visibility: string;
-    visibility_scope: string | null;
-    status: string;
-    error: string | null;
-    record_count: number;
-    last_synced_at: string | null;
-    created_at: string;
+    /** Documents a wiki page was written from. */
+    source_document_ids: string[];
+    written_at?: string | null;
+    /** True once a source document changed or went away — the page is unverified. */
+    stale?: boolean;
 }
 export interface AuditEntry {
     id: string;
@@ -960,6 +1219,19 @@ export type StreamEvent = {
         questions: PendingQuestions[];
     };
 }
+/** The agent is waiting to be allowed to do something. Render it and answer — nothing
+ *  proceeds until you do. */
+ | {
+    event: "approvals";
+    data: {
+        approvals: PendingApproval[];
+    };
+}
+/** The agent drew something. Arrives the instant it is called, mid-turn. */
+ | {
+    event: "ui";
+    data: UiRender;
+}
 /** The agent has handed a page to the user — open a viewer, poll `browserFrame`
  *  and relay clicks with `browserInput`. It then asks a question and waits. */
  | {
@@ -991,12 +1263,16 @@ export type StreamEvent = {
         requires_action: boolean;
         tool_calls: PendingToolCall[];
         questions: PendingQuestions[];
+        approvals: PendingApproval[];
+        ui: UiRender[];
         todos: TodoItem[];
         subagents: SubagentState[];
         handoff?: Handoff | null;
         guard_flags: string[];
         context?: ContextReport | null;
         citations: Citation[];
+        claims: Claim[];
+        attribution: "per-claim" | "retrieval-only" | "none";
         sources: Source[];
         attachments: Attachment[];
         reasoning?: string;
@@ -1046,6 +1322,10 @@ export interface StreamHandlers {
      *  cannot leave the panel wrong. One that is `running` after the turn ends is still
      *  running — keep showing it, and it will report into the next turn. */
     onSubagents?: (subagents: SubagentState[]) => void;
+    /** UI components the agent may draw, for this stream. Their `render` is called for
+     *  you as each arrives; this fires alongside if you also want to observe them. */
+    ui?: UiComponent<any>[];
+    onUi?: (render: UiRender) => void;
     /** A sandbox command's output as it is produced. Append it to a live pane keyed by
      *  `command_id` — a long build should look like it is working, and a person watching
      *  needs to be able to tell a slow command from a stuck one. */
@@ -1075,6 +1355,9 @@ export interface StreamHandlers {
      *  picker, resolve with what the user chose (or `{ chat_instead: true }` if they
      *  would rather keep talking), and `done` resolves only once the agent finishes. */
     onQuestion?: QuestionHandler;
+    /** Decide the agent's approval requests and continue the stream. Without it the
+     *  stream ends with `approvals` on `done` and you resume it yourself. */
+    onApproval?: ApprovalHandler;
     /** Called each time the client (re)connects, with the resume attempt count. */
     onReconnect?: (attempt: number) => void;
     signal?: AbortSignal;
@@ -1118,6 +1401,10 @@ export interface ChatDone {
     tool_calls: PendingToolCall[];
     /** Questions the agent paused on. Empty once `onQuestion` has answered them. */
     questions: PendingQuestions[];
+    /** Approvals the agent is waiting on. Empty once `onApproval` has decided them. */
+    approvals: PendingApproval[];
+    /** Components the agent drew this turn, in call order. Already rendered by then. */
+    ui: UiRender[];
     /** The agent's plan for this session, when the todo family ran this turn. */
     todos: TodoItem[];
     /** Every subagent of the conversation. Some may still be `running` — the turn
@@ -1130,6 +1417,13 @@ export interface ChatDone {
     /** Set only when history had to be trimmed or summarized to fit the window. */
     context?: ContextReport | null;
     citations: Citation[];
+    /** Sentences attributed to a passage, in order. Empty when the model emitted no markers,
+     *  which `attribution` reports rather than hiding. */
+    claims: Claim[];
+    /** `per-claim` · `retrieval-only` · `none`. Draw footnotes from `claims` on the first;
+     *  on the second you have the retrieval set and no attribution, which is a different
+     *  thing to show. */
+    attribution: "per-claim" | "retrieval-only" | "none";
     sources: Source[];
     attachments: Attachment[];
     /** The full thinking trace of a reasoning model, else "" (streamed as `reasoning`). */
@@ -1208,6 +1502,7 @@ export declare class AgentFramework {
     private readonly opts;
     private readonly _fetch;
     private readonly toolRegistry;
+    private readonly uiRegistry;
     /** Active session watchers, so a streamed turn can mark its own messages seen. */
     private readonly watchers;
     /** The bearer in use: `opts.token` initially, replaced on refresh. */
@@ -1253,8 +1548,20 @@ export declare class AgentFramework {
     /** Register a client-side tool (handler run when the agent calls it). */
     registerTool(tool: ClientToolDef): this;
     registerTools(tools: ClientToolDef[]): this;
+    /** Register a UI component the agent can draw into your app.
+     *
+     *  Unlike a tool, nothing is handed back: the agent calls it, your `render` runs, and
+     *  the turn carries on without waiting. */
+    registerUi(component: UiComponent<any>): this;
+    registerUiComponents(components: UiComponent<any>[]): this;
     /** Merge the client-level registry with any per-call tools (per-call wins). */
     private resolveTools;
+    private resolveUi;
+    /** Draw whatever the agent asked for, in order.
+     *
+     *  A component that throws is logged and skipped: one broken chart must not take down
+     *  the turn that drew it, and there is nothing to report back to the agent anyway. */
+    private renderUi;
     /** `bearer` overrides token resolution — used to replay a request with the token a
      *  refresh just produced, instead of asking for one again. */
     private authHeaders;
@@ -1448,6 +1755,42 @@ export declare class AgentFramework {
             }) => Promise<SessionOut>;
         };
     };
+    /** Agent Plugins — the skills this token can reach for, and the ones it may add.
+     *
+     *  Two sources, one list: what the project published plus anything this end-user
+     *  uploaded. Uploading needs the `plugins:write` capability; reading does not, because
+     *  a project that publishes a procedure wants its agent to use it. */
+    plugins: {
+        list: () => Promise<PublishedPlugin[]>;
+        delete: (id: string) => Promise<void>;
+        /** Publish a skill. Re-uploading a name replaces it.
+         *
+         *  Takes whatever the customer actually has:
+         *
+         *    - a packaged Agent Plugin (`plugin.json` + `skills/`), read as-is;
+         *    - a zipped folder of skills, or a single `SKILL.md` — a manifest is written
+         *      for them, because requiring one to publish a file of instructions is a
+         *      packaging exercise standing in front of the feature;
+         *    - a folder's files, from a directory picker, each keyed by its relative path.
+         *
+         *  An end-user's plugin is private to them and unioned on top of the project's —
+         *  only a project key can publish to everyone. */
+        upload: (file: UploadInput, opts?: {
+            filename?: string;
+            signal?: AbortSignal;
+        }) => Promise<PublishedPlugin>;
+        /** Publish a folder of skills without zipping it.
+         *
+         *  `files` is what a browser directory picker gives you. Each part is sent under
+         *  its path relative to the folder, which is all the server needs to lay the
+         *  skills out — so no zip library is needed on your side. */
+        uploadFolder: (files: {
+            path: string;
+            content: UploadInput;
+        }[], opts?: {
+            signal?: AbortSignal;
+        }) => Promise<PublishedPlugin>;
+    };
     documents: {
         list: (query?: {
             tag?: string;
@@ -1509,26 +1852,65 @@ export declare class AgentFramework {
         get: (id: string) => Promise<TaskOut>;
         cancel: (id: string) => Promise<TaskOut>;
     };
-    sources: {
-        list: () => Promise<SourceOut[]>;
-        get: (id: string) => Promise<SourceOut>;
-        types: () => Promise<{
-            types: string[];
-        }>;
-        /** Rotate credentials, retag, change the refresh cadence or the ACL. A new
-         *  `config` is tested before it replaces the old one, so a bad DSN fails here
-         *  (400) instead of at the next scheduled sync. Changing the interval
-         *  reschedules; 0 turns auto-refresh off. */
-        patch: (id: string, body: AclFields & {
+    /**
+     * Turns that start because something happened somewhere else.
+     *
+     * A trigger is a URL you give another system — a ticket tracker, a CI job, a Zapier step
+     * — and the path is the credential, so it runs as a fixed subject chosen at creation.
+     * These were the only routes in the API reference with no SDK method: every integration
+     * hand-wrote `fetch` for them.
+     *
+     * The URL comes back absolute and is not a secret we can show once: the whole point is
+     * that someone else's configuration holds it. `secret` IS shown once — with it, the
+     * sender signs the body and the URL stops being a bearer token.
+     */
+    triggers: {
+        list: () => Promise<Trigger[]>;
+        /** `prompt` may interpolate the event: `"A ticket arrived: {{ body.title }}"`. */
+        create: (opts: {
+            prompt: string;
             name?: string;
-            config?: Record<string, unknown>;
-            sync_interval_seconds?: number;
-            tags?: string[];
-        }) => Promise<SourceOut>;
-        /** Trigger a sync now; pass `fullRefresh` to re-pull everything. */
-        sync: (id: string, fullRefresh?: boolean) => Promise<SourceOut>;
-        remove: (id: string) => Promise<void>;
+            systemPrompt?: string;
+            /** Run every event in one conversation. Off by default: two unrelated events sharing
+             *  a transcript confuse both. */
+            sessionId?: string;
+            /** Require a signed body, and return the key to sign it with. */
+            signed?: boolean;
+        }) => Promise<Trigger>;
+        delete: (triggerId: string) => Promise<void>;
+        /** A new URL, with the old one alive for 24 hours — so telling the other system its new
+         *  address is not an outage. */
+        rotate: (triggerId: string) => Promise<Trigger>;
     };
+    /**
+     * What the agent wrote down — remembered facts and wiki pages.
+     *
+     * Retrieval reads these back on every turn, so when an answer looks wrong a
+     * remembered fact is often the reason. The ACL that governs retrieval governs this
+     * too: a caller sees exactly what its token could have retrieved.
+     */
+    memory: {
+        /** `kind` is "memory" (facts, per end-user) or "wiki" (pages, per user or shared). */
+        list: (opts?: {
+            kind?: "memory" | "wiki";
+            limit?: number;
+        }) => Promise<KnowledgeItem[]>;
+        /** Forget one. The agent can write it again; this removes what is there now. */
+        delete: (itemId: string) => Promise<void>;
+    };
+    /**
+     * What this token can actually do.
+     *
+     * The three gates on a turn are the platform's kill switch, the token's capability
+     * and the per-request `enable_*` flag, and until this existed a client could read
+     * none of them. `flags[].effective` is the useful one: false means setting that flag
+     * changes nothing on this token — which is otherwise indistinguishable from the agent
+     * simply choosing not to use the tool.
+     *
+     * Cheap and safe to call on load: a token asking what it holds is reading its own
+     * claims back, so it needs no capability of its own.
+     */
+    capabilities: () => Promise<TokenCapabilities>;
     audit: {
         /** Read the tenant's audit trail (admin). Filter by action/subject. */
         list: (opts?: {
@@ -1588,16 +1970,6 @@ export declare class AgentFramework {
         /** Pull a file out of the sandbox as bytes. */
         download: (id: string, path: string) => Promise<Blob>;
     };
-    /**
-     * Connect an external data source and keep it live in the agent's knowledge.
-     * Validates the connector, runs an initial sync, and (when an interval is set)
-     * schedules recurring auto-refresh so the data never goes stale.
-     *
-     *   await ai.sync({ name: "orders", connector_type: "postgres",
-     *     config: { dsn, query: "select id, status, total from orders",
-     *               cursor_column: "updated_at" }, sync_interval_seconds: 900 });
-     */
-    sync: (config: SyncConfig) => Promise<SourceOut>;
     private runWithTools;
     /** Wrap startStream so a `done` carrying `requires_action` auto-executes the
      *  client tools and continues the stream (same session) until the agent ends. */
@@ -1608,6 +1980,321 @@ export declare class AgentFramework {
     private multipartUpload;
     private rangedDownload;
 }
+/** Where projects are administered and end-user tokens are minted. A different host
+ *  from {@link DEFAULT_BASE_URL}, and a different credential — the two are not
+ *  interchangeable, which is the whole reason there are two clients. */
+export declare const DEFAULT_CONTROL_PLANE_URL = "https://oberik.com";
+export interface ProjectClientOptions {
+    /** From the project's URL in the dashboard. */
+    projectId: string;
+    /** `pk_…`. Server-side only — see the constructor. */
+    projectKey: string;
+    /** Only for a self-hosted control plane. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface MintTokenInput {
+    /** Who this token is. Owns whatever it creates, and is the default visibility
+     *  boundary. A hierarchical path: `acme:finance:ana`. */
+    subject: string;
+    /** What it may SEE — a prefix of `subject`. Omit for "only its own data". */
+    scope?: string;
+    /** What it may DO. Intersected with the project's ceiling: you can narrow, never
+     *  widen. Omit and the token carries everything the project allows. */
+    capabilities?: string[];
+    roles?: string[];
+    groups?: string[];
+    /** Restrict this token to a subset of the project's models. */
+    models?: string[];
+    maxEffort?: "minimal" | "low" | "medium" | "high";
+    /** Ceiling on agent↔tool loops. Unset means unlimited. */
+    maxToolIterations?: number;
+    maxContextTokens?: number;
+    /** Seconds. Keep it short and mint per session. */
+    expiresIn?: number;
+}
+export interface MintedToken {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    tenant_id: string;
+    /** What was ACTUALLY granted. Compare with what you asked for to see what the
+     *  project's ceiling trimmed — a capability you expected and did not get is a
+     *  toggle in the dashboard, not a bug in your code. */
+    capabilities: string[];
+    scope: string | null;
+    allowed_models: string[] | null;
+    max_effort: string | null;
+    max_context_tokens: number | null;
+}
+/**
+ * The control plane, from your backend.
+ *
+ * The other client in this package talks to the data plane as one end-user. This one
+ * holds the project key and administers the project itself: minting those tokens,
+ * setting the capability ceiling, curating the corpus.
+ *
+ * They are separate classes on purpose. A project key can mint a token with any
+ * capability the project allows — and create further keys, and delete the project — so
+ * it must never travel to the same place an end-user token does. Two types make that a
+ * decision someone has to make rather than a field they can accidentally set.
+ */
+export declare class OberikProject {
+    readonly baseUrl: string;
+    private readonly projectId;
+    private readonly key;
+    private readonly _fetch;
+    constructor(opts: ProjectClientOptions);
+    private request;
+    tokens: {
+        /**
+         * Mint a short-lived token for ONE end-user.
+         *
+         *   const { access_token } = await oberik.tokens.mint({
+         *     subject: `${user.orgId}:${user.id}`,
+         *     scope: `${user.orgId}:${user.id}`,
+         *     capabilities: ["chat", "documents:read"],
+         *   });
+         */
+        mint: (input: MintTokenInput) => Promise<MintedToken>;
+        /**
+         * The same thing shaped as the callback {@link createClient} wants, so the two
+         * halves of this package fit together without a wrapper:
+         *
+         *   const ai = createClient({ getToken: oberik.tokens.forUser({ subject: id }) });
+         *
+         * Called again whenever a token expires, so the client refreshes on its own.
+         */
+        forUser: (input: MintTokenInput) => () => Promise<string>;
+    };
+    /** The capability ceiling: the maximum any token minted here may hold. */
+    capabilities: {
+        get: () => Promise<Record<string, unknown>>;
+        /** Merges — send only what you want to change. */
+        set: (caps: Record<string, unknown>) => Promise<unknown>;
+    };
+    /** Documents owned by the project rather than by any one end-user: the corpus you
+     *  curate and your users only read. */
+    /**
+     * The corpus you curate.
+     *
+     * Uploads here are stored `tenant`-visible — readable by every end-user of the project —
+     * which is what "a corpus you curate, that users only read" means. That is the default
+     * and the only option, deliberately: a project key is not a person, so there is no
+     * per-user subtree for it to write into. Per-user documents go through the data-plane
+     * client with an end-user token, where the subject IS the owner.
+     *
+     * The docs used to show `visibility: "tenant"` being passed here, which was neither
+     * accepted nor needed — a recipe that worked by luck rather than by expression.
+     */
+    documents: {
+        list: () => Promise<unknown[]>;
+        upload: (file: Blob | File, opts?: {
+            filename?: string;
+            tags?: string[];
+        }) => Promise<unknown>;
+        delete: (documentId: string) => Promise<void>;
+    };
+    /**
+     * The models this project runs on, and the retrieval it uses.
+     *
+     * These had no methods at all: `project-api.md` documents them in a table and every
+     * integration hand-rolled `fetch` for half its setup. `providers.add` is the one that
+     * matters most — it is the step a new project cannot answer a question without, and it
+     * finishes the rest of the setup itself (see `derived` in the response).
+     *
+     * `providers.catalog` is deliberately absent: it is not project-scoped, so it does not
+     * belong on a client whose every path hangs off one project.
+     */
+    providers: {
+        list: () => Promise<unknown[]>;
+        /** Name a chat model AND an embedding model: the first lets the agent answer, the
+         *  second lets it index. The response's `derived` says what was set for you. */
+        add: (opts: {
+            provider: string;
+            models: string[];
+            values: Record<string, string>;
+            label?: string;
+        }) => Promise<{
+            id: string;
+            derived?: Record<string, unknown>;
+        }>;
+        edit: (credId: string, opts: {
+            models?: string[];
+            label?: string;
+            values?: Record<string, string>;
+        }) => Promise<unknown>;
+        /** Re-read the provider's catalog: a model registered before its price was published
+         *  bills nothing, so the usage cap never trips. */
+        refresh: (credId: string) => Promise<unknown>;
+        remove: (credId: string) => Promise<void>;
+    };
+    /** The model used when a request does not name one. */
+    defaultModel: {
+        set: (model: string) => Promise<unknown>;
+    };
+    /** Embedding and rerank overrides. Set for you when you register an embedding model, so
+     *  this is for changing it rather than for getting started. */
+    retrieval: {
+        set: (opts: {
+            embeddingModel?: string;
+            embeddingDim?: number;
+            rerankModel?: string;
+        }) => Promise<unknown>;
+        /** How many floats a model returns, measured by embedding one word. No provider
+         *  publishes it, and a wrong one fails at the first ingest rather than here. */
+        probe: (model: string) => Promise<{
+            dim: number | null;
+            error?: string;
+        }>;
+    };
+    /** How documents are read: the built-in parser, or a vision model you choose. */
+    documentProcessor: {
+        set: (opts: {
+            type: string;
+            model?: string;
+        }) => Promise<unknown>;
+    };
+    /** What happens when a conversation outgrows the model's window. */
+    context: {
+        get: () => Promise<unknown>;
+        set: (opts: Record<string, unknown>) => Promise<unknown>;
+    };
+    /** Spend and rate caps on this project's LLM key. Enforced by the biller, so they hold
+     *  even when the usage views cannot be read. */
+    limits: {
+        get: () => Promise<unknown>;
+        set: (opts: {
+            maxBudget?: number | null;
+            budgetDuration?: string;
+            tpmLimit?: number | null;
+            rpmLimit?: number | null;
+        }) => Promise<unknown>;
+    };
+    /** Which models a delegate may run on, and how many may run at once. Without this the
+     *  subagents capability stays unavailable however it is granted. */
+    subagents: {
+        set: (opts: {
+            models: string[];
+            maxConcurrent?: number;
+        }) => Promise<unknown>;
+    };
+    /** Procedures you publish as Agent Plugins, and what your end-users have added. */
+    skills: {
+        list: () => Promise<unknown[]>;
+        upload: (zip: Blob | File, filename?: string) => Promise<unknown>;
+        delete: (pluginId: string) => Promise<void>;
+    };
+    /** MCP servers whose tools join this project's catalog. */
+    mcp: {
+        list: () => Promise<unknown[]>;
+        add: (opts: {
+            name: string;
+            url: string;
+            transport?: "streamable_http" | "sse";
+            headers?: Record<string, string>;
+        }) => Promise<unknown>;
+        remove: (mcpId: string) => Promise<void>;
+    };
+    /** Conversations, and what was said in them. */
+    sessions: {
+        list: () => Promise<unknown[]>;
+        messages: (sessionId: string) => Promise<unknown[]>;
+    };
+    /** Scheduled work this project's end-users have created. */
+    tasks: {
+        list: () => Promise<unknown[]>;
+    };
+    /** What the agent has written down: remembered facts and wiki pages. */
+    wiki: {
+        list: () => Promise<unknown[]>;
+        delete: (itemId: string) => Promise<void>;
+    };
+    /** Live sandboxes, and what to do about one. */
+    sandboxes: {
+        list: () => Promise<unknown[]>;
+        action: (sessionId: string, action: "pause" | "resume" | "delete") => Promise<unknown>;
+    };
+    /** Prepended to every request for this project, above anything a caller sends. */
+    systemPrompt: {
+        set: (systemPrompt: string) => Promise<unknown>;
+    };
+    /** Browser origins allowed to call the data plane with this project's tokens. */
+    origins: {
+        set: (origins: string[]) => Promise<unknown>;
+    };
+    /** Tools the agent calls by URL. The signing secret comes back once, on create. */
+    webhookTools: {
+        list: () => Promise<unknown[]>;
+        create: (tool: {
+            name: string;
+            description: string;
+            url: string;
+            parameters?: Record<string, unknown>;
+            headers?: Record<string, string>;
+        }) => Promise<{
+            id: string;
+            secret: string;
+        }>;
+        delete: (toolId: string) => Promise<void>;
+    };
+    /** Server-side keys. A created one is returned once and never again. */
+    /**
+     * Checks on what goes into the model and what comes back.
+     *
+     * The enforcement has existed for a long time and there was no way to configure it — no
+     * route, no dashboard section, no column — so a documentation page described switches
+     * that could not be reached. `set` takes a partial: what you do not mention is left as it
+     * is.
+     */
+    guardrails: {
+        get: () => Promise<GuardrailPolicy>;
+        set: (policy: GuardrailUpdate) => Promise<GuardrailPolicy>;
+    };
+    /**
+     * Whether this project can actually answer a question yet.
+     *
+     * A new project has no models, so it can neither answer nor index anything — and the
+     * flag that used to be the closest thing to this (`hasLlm`) meant "a LiteLLM key was
+     * provisioned", which is true from the moment a project exists. Every unfinished step
+     * names what it blocks and the one call that fixes it.
+     *
+     * Worth calling in a deploy check: a project that is not ready fails every request with
+     * the provider's own error, which reads as your bug rather than as missing setup.
+     */
+    readiness: () => Promise<ProjectReadiness>;
+    /** The starting snippet and this project's endpoints — the same one the dashboard and the
+     *  SSH gateway show, so there is one of it rather than three. */
+    connect: () => Promise<ConnectInfo>;
+    /**
+     * Further project keys.
+     *
+     * `scope` is the important argument and it defaults to the narrow one. A `mint` key
+     * can turn your signed-in user into an end-user token and nothing else — it cannot
+     * read the corpus, raise the capability ceiling, issue more keys, or delete the
+     * project. That is what almost every backend actually needs, and it is the difference
+     * between a leaked key costing you some tokens and costing you the workspace.
+     */
+    keys: {
+        list: () => Promise<ProjectKeyInfo[]>;
+        create: (name: string, opts?: {
+            scope?: ProjectKeyScope;
+        }) => Promise<{
+            id: string;
+            key: string;
+            scope: ProjectKeyScope;
+        }>;
+        revoke: (keyId: string) => Promise<void>;
+    };
+    /** Spend, requests, tokens and latency — including per end-user, since spend is
+     *  attributed to the token's subject. */
+    usage: {
+        summary: () => Promise<unknown>;
+        observability: (windowSeconds?: number) => Promise<unknown>;
+    };
+}
+/** Factory helper for the server-side client. */
+export declare function createProjectClient(opts: ProjectClientOptions): OberikProject;
 /** Factory helper. */
 export declare function createClient(opts: ClientOptions): AgentFramework;
 export default AgentFramework;