@oberik/sdk 0.2.0 → 0.4.0

package/dist/esm/index.d.ts

@@ -124,12 +124,36 @@ export interface TokenResponse {
     token_type: string;
     expires_in: number;
     tenant_id: string;
+    /** Who the token is for. Omitting `user_ref` inherits the caller's subject — it does
+     *  not mint a token without one, which used to fail much later at an unrelated call
+     *  site with `Token missing subject claim 'sub'`. */
+    subject: string;
+    /** What was actually granted, after intersecting with the caller's own. Absent when
+     *  the request named none (the token is then as broad as the caller). */
+    capabilities?: string[] | null;
+    scope?: string | null;
 }
 export interface ToolInfo {
     name: string;
-    source: "builtin" | "mcp" | string;
+    source: "builtin" | "mcp" | "webhook" | string;
     description: string;
 }
+/** What happened when this project's MCP server was asked for its tools.
+ *
+ *  Without this, a server that registered cleanly and contributed nothing is
+ *  indistinguishable from one still connecting, one whose handshake failed, and one
+ *  that genuinely has no tools — all four are an absence of rows in the listing. */
+export interface McpServerStatus {
+    name: string;
+    /** Did it answer? */
+    ok: boolean;
+    /** How many tools it contributed. `ok` with `0` means it answered and offered none. */
+    tools: number;
+    /** Answered from the short-lived cache rather than dialled again this call. */
+    cached?: boolean;
+    /** Why not, when `ok` is false — including a URL refused as private or unroutable. */
+    error?: string;
+}
 export type DocumentStatus = "awaiting_upload" | "pending" | "processing" | "ready" | "failed" | string;
 export interface DocumentOut {
     id: string;
@@ -524,9 +548,17 @@ export interface QuestionAnswerItem {
     /** The question's `id` (or `header`). Omit for a single question, or when the
      *  answers are in the order they were asked. */
     question_id?: string;
-    /** Option labels the user picked. Anything not offered is reported to the agent
-     *  as text the user typed, not as a selection. */
-    selected?: string[];
+    /** What the user picked: an option's `label`, or the `QuestionOption` itself.
+     *
+     *  Both, because the options you are handed are objects and `selected: [q.options[0]]`
+     *  is the natural thing to write — and it was a 422 (`Input should be a valid string`)
+     *  telling you nothing about `.label`. The server unwraps an object to its label, so
+     *  an `onQuestion` handler that returns the option it was given now works, which is
+     *  what "pass an `onQuestion` handler and the pause is answered for you" claimed.
+     *
+     *  Anything not among the offered options is reported to the agent as text the user
+     *  typed, not as a selection. */
+    selected?: (string | QuestionOption)[];
     /** The "type something else" answer. May accompany selections. */
     text?: string | null;
 }
@@ -676,8 +708,14 @@ export interface ComputerHost {
     workdir: string;
     /** Applied when a command names no timeout of its own. */
     exec_default_timeout_s: number;
-    /** Hard ceiling: past this a command is killed. */
+    /** Hard ceiling for the AGENT's `computer_bash`, which streams and so can use all of
+     *  it. Not what `computers.exec` can get — see below. */
     exec_max_timeout_s: number;
+    /** Ceiling for a direct `computers.exec`, which blocks an HTTP response and so is
+     *  bounded by the edge long before `exec_max_timeout_s`. Asking for more than this is
+     *  clamped to it, rather than left to become a proxy's HTML error page. For work that
+     *  needs longer, let the agent run it, or start it with `&` and poll. */
+    sync_exec_max_timeout_s: number;
     max_sessions_per_tenant: number;
 }
 export type ComputerSessionStatus = "creating" | "running" | "paused" | "stopped" | "failed" | string;
@@ -778,7 +816,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. */
     /** 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. */
@@ -808,7 +845,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;
@@ -850,6 +907,17 @@ 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. */
@@ -863,8 +931,17 @@ export interface ChatResponse {
     /** 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 {
@@ -920,6 +997,65 @@ export interface TaskOut {
     last_error: string | null;
     created_at: string;
 }
+/** 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";
@@ -964,6 +1100,23 @@ export interface TokenCapabilities {
         max_context_tokens: number | null;
     };
 }
+/** A URL that starts a turn when something happens in another system. */
+export interface Trigger {
+    id: string;
+    name: 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;
@@ -1156,6 +1309,8 @@ export type StreamEvent = {
         guard_flags: string[];
         context?: ContextReport | null;
         citations: Citation[];
+        claims: Claim[];
+        attribution: "per-claim" | "retrieval-only" | "none";
         sources: Source[];
         attachments: Attachment[];
         reasoning?: string;
@@ -1300,6 +1455,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`). */
@@ -1367,6 +1529,9 @@ export interface DownloadOptions {
 }
 export declare class AgentApiError extends Error {
     status: number;
+    /** The server's `detail`, in whatever shape it sent — except an HTML error page from
+     *  an intermediary, which is replaced by the same summary as `message`. Keeping four
+     *  kilobytes of someone else's markup here helped nobody and buried the status. */
     detail: unknown;
     constructor(status: number, detail: unknown);
 }
@@ -1491,13 +1656,29 @@ export declare class AgentFramework {
         } & Record<string, string>>;
     };
     tools: {
+        /** Every tool this token would actually be handed on its next request.
+         *
+         *  `mcp_servers` is present when the project has any, and answers the question the
+         *  listing alone cannot: "still connecting", "handshake failed" and "this server has
+         *  no tools" all look identical as an absence of rows. Each entry says whether the
+         *  server answered, how many tools it contributed, and why not. */
         list: () => Promise<{
             tools: ToolInfo[];
+            mcp_servers?: McpServerStatus[];
         }>;
     };
     chat: {
         /** One round-trip. Returns `requires_action` + `tool_calls` for you to handle
-         *  manually — use `chat.run` to auto-dispatch client tools instead. */
+         *  manually — use `chat.run` to auto-dispatch client tools instead.
+         *
+         *  Client *tools* stay manual here; that is the whole difference from `run`. UI
+         *  components do not, because there is no manual handling of one: the registry
+         *  passed to `createClient({ ui: [...] })` IS the handling, and `chat.stream`
+         *  already both declares it and draws from it. A blocking client that registered a
+         *  chart renderer got an empty `ui` and no error — the declarations were never sent,
+         *  so the agent was not offered the component at all; and when they were repeated by
+         *  hand as `ui_tools`, the renderer still never ran. The one wiring `tools.md`
+         *  documents produced nothing on the one call it documents it with. */
         send: (body: ChatRequest) => Promise<ChatResponse>;
         /** Blocking chat that AUTO-EXECUTES registered client tools: it sends the
          *  message, and whenever the agent asks for client tools it runs their
@@ -1533,7 +1714,16 @@ export declare class AgentFramework {
         handoffDone: (sessionId: string) => Promise<ChatResponse>;
         answer: (sessionId: string, ...answers: QuestionAnswer[]) => Promise<ChatResponse>;
         sessions: {
-            list: (userRef?: string) => Promise<SessionOut[]>;
+            /** Conversations this token may see, newest first.
+             *
+             *  Paged: `limit` defaults to 100 and is capped at 500. This used to return every
+             *  session in one unbounded response — fine for one end-user, and an admin token
+             *  on a busy project gets the whole tenant's history to render a sidebar showing
+             *  twenty. Page with `offset`. */
+            list: (userRef?: string, opts?: {
+                limit?: number;
+                offset?: number;
+            }) => Promise<SessionOut[]>;
             /** The agent's plan for this conversation — what a UI renders on a page load,
              *  or between turns. A turn that touched the list also returns it directly. */
             todos: (sessionId: string) => Promise<TodoItem[]>;
@@ -1728,6 +1918,36 @@ export declare class AgentFramework {
         get: (id: string) => Promise<TaskOut>;
         cancel: (id: string) => Promise<TaskOut>;
     };
+    /**
+     * 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;
+            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.
      *
@@ -1921,6 +2141,18 @@ export declare class OberikProject {
     };
     /** 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?: {
@@ -1929,6 +2161,126 @@ export declare class OberikProject {
         }) => 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>;
@@ -1953,6 +2305,33 @@ export declare class OberikProject {
         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.
      *