@oberik/sdk 0.1.0 → 0.2.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. */
@@ -662,7 +779,6 @@ export interface ChatRequest {
      *  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. */
@@ -701,10 +817,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 +838,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
@@ -735,6 +854,10 @@ export interface ChatResponse {
     /** 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
@@ -797,42 +920,63 @@ export interface TaskOut {
     last_error: string | null;
     created_at: string;
 }
-export type ConnectorType = "postgres" | "http" | string;
-export interface SyncConfig {
+/** 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 {
+/** One memory or wiki page. */
+export interface KnowledgeItem {
     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[];
+    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 +1104,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,6 +1148,8 @@ export type StreamEvent = {
         requires_action: boolean;
         tool_calls: PendingToolCall[];
         questions: PendingQuestions[];
+        approvals: PendingApproval[];
+        ui: UiRender[];
         todos: TodoItem[];
         subagents: SubagentState[];
         handoff?: Handoff | null;
@@ -1046,6 +1205,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 +1238,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 +1284,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
@@ -1208,6 +1378,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 +1424,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 +1631,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 +1728,35 @@ 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 & {
-            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>;
+    /**
+     * 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 +1816,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 +1826,162 @@ 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. */
+    documents: {
+        list: () => Promise<unknown[]>;
+        upload: (file: Blob | File, opts?: {
+            filename?: string;
+            tags?: string[];
+        }) => Promise<unknown>;
+        delete: (documentId: string) => Promise<void>;
+    };
+    /** 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. */
+    /**
+     * 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;