@oberik/sdk 0.1.0

package/dist/esm/index.d.ts

@@ -0,0 +1,1614 @@
+/**
+ * Agent Framework — single-file TypeScript client.
+ *
+ * Isomorphic: works server-side (Node 18+) and in the browser. The only runtime
+ * requirements are the standard `fetch`, `Blob`, `TextDecoder`, and web
+ * `ReadableStream` (all present in Node 18+ and modern browsers). No deps.
+ *
+ * Handles the tedious parts for you:
+ *   - Auth via JWT (Bearer) or legacy API key, with optional async token refresh.
+ *   - Chat streaming over SSE with automatic reconnection — if the connection
+ *     drops mid-generation it resumes from the last event id (server keeps going).
+ *   - Client-side tools: register a handler and the client auto-executes tool
+ *     calls the agent makes and submits the results, looping until the agent ends.
+ *   - Resumable uploads: presigned S3 multipart with per-part retry + concurrency.
+ *   - Resumable downloads: presigned URL fetched with ranged GETs that retry.
+ *
+ * Quick start:
+ *   const af = createClient({ token: jwt });                  // hosted API
+ *   const af = createClient({ token: jwt, baseUrl: "http://localhost:8000" });  // local
+ *   const res = await af.chat.send({ message: "hello" });
+ *
+ *   // Client-side tools — the client runs your handler and resumes automatically:
+ *   af.registerTool({
+ *     name: "get_weather",
+ *     description: "Current weather for a city",
+ *     parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
+ *     handler: async ({ city }) => ({ tempC: 21, city }),
+ *   });
+ *   const done = await af.chat.run({ message: "what's the weather in Paris?" });
+ *   // ...or streaming, tokens + auto tool dispatch in one call:
+ *   const handle = af.chat.stream({ message: "weather in Paris?" }, { onToken: t => process.stdout.write(t) });
+ *   await handle.done;
+ */
+/**
+ * Where the agent API lives. Override for a self-hosted deployment or local
+ * development (`http://localhost:8000`); the hosted API needs no `baseUrl` at all.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.oberik.com";
+export interface ClientOptions {
+    /** Base URL of the API. Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /**
+     * Static JWT (sent as `Authorization: Bearer`). Fine for a script; for anything
+     * long-lived prefer `getToken`, because end-user tokens are deliberately
+     * short-lived and a static one eventually 401s with nothing the SDK can do.
+     */
+    token?: string;
+    /** Legacy API key (sent as `X-API-Key`). Prefer `token`/`getToken`. */
+    apiKey?: string;
+    /**
+     * How the client obtains a token — **the recommended way to authenticate.** Called
+     * to get one, and called again with `{ expired: true }` whenever the server rejects
+     * the current token (401), so an expiry is handled where it happens instead of
+     * everywhere you make a call:
+     *
+     *   const ai = createClient({
+     *     baseUrl,
+     *     getToken: async ({ expired }) => {
+     *       // YOUR endpoint, which mints with your project key server-side.
+     *       const r = await fetch("/api/ai-token", { cache: expired ? "reload" : "default" });
+     *       return (await r.json()).access_token;
+     *     },
+     *   });
+     *
+     * On a 401 the failed request is replayed once with the new token, so callers never
+     * see the expiry. Concurrent requests share one refresh (no stampede), the replay
+     * happens at most once per request (a still-rejected token surfaces as a normal
+     * 401 rather than looping), and an interrupted stream re-attaches to the *same* run
+     * with the new token — the answer in flight is neither lost nor paid for twice.
+     *
+     * `{ expired: false }` calls happen per request, so keep your own token cached and
+     * only go to the network when `expired` is true.
+     */
+    getToken?: (ctx: {
+        expired: boolean;
+    }) => string | Promise<string>;
+    /** Operator admin key for tenant-management endpoints (sent as X-Admin-Key). */
+    adminKey?: string;
+    /** Custom fetch (e.g. for tests or non-global fetch). Defaults to global. */
+    fetch?: typeof fetch;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Client-side tools registered up-front; auto-dispatched by chat.run/stream. */
+    tools?: ClientToolDef[];
+}
+/** Public tenant view — never includes the API key. */
+export interface TenantOut {
+    id: string;
+    slug: string;
+    name: string;
+    created_at: string;
+}
+/** Returned ONCE at creation — the only time the API key is exposed. */
+export interface TenantCreated extends TenantOut {
+    api_key: string;
+}
+/** Everything a minted token can be narrowed by. Each field is intersected (or
+ *  clamped) against the minting credential's own grant — never widened. */
+export interface TokenRequest {
+    /** Your own label for the end-user (appears on sessions). */
+    user_ref?: string;
+    expires_in?: number;
+    /** e.g. ["chat", "documents:read"]. Absent = inherit the caller's set. */
+    capabilities?: string[];
+    roles?: string[];
+    groups?: string[];
+    /** Visibility boundary for this token (must sit within the caller's). */
+    scope?: string;
+    /** Hierarchical data-visibility prefix, if you separate it from `scope`. */
+    data_scope?: string;
+    /** Restrict this token to a subset of models. */
+    allowed_models?: string[];
+    /** Reasoning-effort ceiling. */
+    max_effort?: "minimal" | "low" | "medium" | "high";
+    /** Ceiling on how much conversation history is replayed for this token, in tokens.
+     *  Narrows the project's own context budget (Dashboard → Context management) — it
+     *  can never widen it. Use it to give a cheap tier a shorter memory. */
+    max_context_tokens?: number;
+}
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    tenant_id: string;
+}
+export interface ToolInfo {
+    name: string;
+    source: "builtin" | "mcp" | string;
+    description: string;
+}
+export type DocumentStatus = "awaiting_upload" | "pending" | "processing" | "ready" | "failed" | string;
+export interface DocumentOut {
+    id: string;
+    filename: string;
+    content_type: string | null;
+    tags: string[];
+    /** The subject that uploaded it — owns it for ACL purposes. */
+    owner_subject?: string | null;
+    visibility: Visibility | string;
+    visibility_scope?: string | null;
+    acl_roles: string[];
+    acl_groups: string[];
+    status: DocumentStatus;
+    chunk_count: number;
+    error: string | null;
+    /** Which model embedded it, and with which pipeline — a document embedded by an
+     *  older model lives in its own vector collection and needs `reingest` to move. */
+    embedding_model?: string | null;
+    pipeline_version?: string | null;
+    content_hash?: string | null;
+    created_at: string;
+}
+export interface RetrievedChunk {
+    text: string;
+    score: number;
+    document_id: string;
+    chunk_index: number;
+    metadata: Record<string, unknown>;
+}
+export interface RetrieveRequest {
+    query: string;
+    document_ids?: string[] | null;
+    tags?: string[] | null;
+    top_k?: number | null;
+    top_n?: number | null;
+}
+/** OpenAI-format tool schema for client-executed (non-MCP) tools. */
+export interface ClientTool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface ClientToolResult {
+    tool_call_id: string;
+    content: string;
+}
+/** A client-side tool: its JSON-schema + a handler the client runs when the agent
+ *  calls it. Register via `createClient({ tools })` / `client.registerTool(...)`,
+ *  or pass per-call. `chat.run` / `chat.stream` then dispatch and resume for you. */
+export interface ClientToolDef {
+    name: string;
+    description?: string;
+    /** JSON Schema for the arguments (the `parameters` of the OpenAI tool schema). */
+    parameters?: Record<string, unknown>;
+    /** Executed with the model-provided args. Return a string, or any JSON value
+     *  (it's JSON-stringified). Throwing is caught and returned as an error result. */
+    handler: (args: Record<string, unknown>, call: PendingToolCall) => unknown | Promise<unknown>;
+}
+/** One step on the agent's plan for a conversation. `number` is stable within the
+ *  session and never reused, so it keeps meaning the same step as items come and go. */
+export interface TodoItem {
+    id: string;
+    number: number;
+    content: string;
+    status: "pending" | "in_progress" | "completed" | string;
+}
+/** One piece of work the agent handed to another agent running beside it.
+ *
+ *  Small on purpose: a UI shows a line per subagent — what it is doing and how far
+ *  along — not a transcript. The subagent's working conversation is its own, and the
+ *  only part of it anyone else needs is `result` at the end. */
+export interface SubagentState {
+    id: string;
+    /** The short handle the agent addresses it by, e.g. "a1". Stable per conversation. */
+    ref: string;
+    /** What it was asked to do, in the main agent's words. */
+    task: string;
+    model?: string | null;
+    /** `delivered` means the main agent has been told; the work is over either way. */
+    status: "running" | "finished" | "failed" | "stopped" | "delivered" | string;
+    /** Four or five words on what it is doing right now, written from its own actions
+     *  rather than asked of the model — so it stays live under load. */
+    progress: string;
+    /** Agent↔tool steps taken. Use it for movement when `progress` does not change. */
+    steps: number;
+    /** Set while it is blocked waiting for the main agent to decide something. The main
+     *  agent answers it; there is nothing for a client to do but show it. */
+    question?: string | null;
+    /** Its report to the main agent. Empty until it has finished. */
+    result: string;
+    error?: string | null;
+}
+/** What context management did to fit this turn's history into the model's window.
+ *
+ *  Present only when the conversation did NOT fit as-is — which is exactly when it
+ *  matters, because it means the model was not shown the whole transcript. The
+ *  strategy is a project setting (Dashboard → Context management), not a per-call one. */
+export interface ContextReport {
+    strategy: "trim" | "summarize" | string;
+    /** Present on stream events, absent on `ChatResponse.context`. */
+    phase?: "done";
+    tokens_before: number;
+    tokens_after: number;
+    budget: number;
+    /** Messages removed from the window entirely. */
+    dropped: number;
+    /** Messages (usually tool outputs) kept but shortened. */
+    truncated: number;
+    /** True when the evicted prefix was compacted into a summary. */
+    summarized: boolean;
+}
+/** Emitted when compaction starts, before the summarizer has produced anything.
+ *  `tokens_after` is not known yet — that arrives on the `done` frame. */
+export interface ContextProgress {
+    phase: "compacting";
+    strategy: "summarize" | string;
+    tokens_before: number;
+    budget: number;
+    /** Images/audio/video being sent to the summarizer to be described before they go. */
+    media: number;
+}
+/** A picture of a page the agent has handed to the user, and what a click means. */
+export interface BrowserFrame {
+    url: string;
+    title: string;
+    /** data: URI, ready for an <img src>. */
+    image: string;
+    width: number;
+    height: number;
+    /** Where the crop was taken from. Echo this back with a click. */
+    origin: {
+        x: number;
+        y: number;
+    };
+    /** False when the whole viewport is shown. */
+    clipped: boolean;
+    /** Whether the agent's OWN selector produced this crop. */
+    matched: boolean;
+    /** `selector` — the agent's; `detected` — it matched nothing and the widget was found
+     *  anyway; `viewport` — neither, so this is the whole page. */
+    region: "selector" | "detected" | "viewport";
+}
+/** One frame of the live view, as Chrome painted it. */
+export interface BrowserStreamFrame {
+    image: string;
+    device_width?: number;
+    device_height?: number;
+    scroll_x?: number;
+    scroll_y?: number;
+}
+/** Where to crop the live view, and why. Sent when it MOVES, not per frame — an
+ *  overlay appearing mid-gesture changes it, a repaint does not. */
+export interface BrowserStreamClip {
+    origin: {
+        x: number;
+        y: number;
+    };
+    width: number;
+    height: number;
+    clipped: boolean;
+    matched: boolean;
+    region: "selector" | "detected" | "viewport";
+    url: string;
+}
+/** Whether the person seems to have finished with the page.
+ *
+ *  `state` is one of four fixed words. That is a security property, not brevity: the
+ *  checker is looking at a CAPTCHA, and a closed vocabulary is what stops it being a
+ *  way to read one out. `checked: false` means no call was made (rate-limited, off, or
+ *  nothing handed over) — ask again later; it does not mean "not finished". */
+export interface HandoffCheck {
+    /** `gone` (the widget is no longer on the page) and `loading` (mid-navigation) are
+     *  decided from the page itself, without paying for a model call. */
+    state: "solved" | "gone" | "unsolved" | "loading" | "unclear";
+    done: boolean;
+    checked: boolean;
+}
+export interface BrowserStreamHandlers {
+    onFrame: (frame: BrowserStreamFrame) => void;
+    onClip?: (clip: BrowserStreamClip) => void;
+    onError?: (message: string) => void;
+}
+/** A live view being watched. Call `close()` when the viewer goes away — the page
+ *  keeps painting for as long as anyone is listening. */
+export interface BrowserStream {
+    close: () => void;
+}
+/** The bit of `getBoundingClientRect()` the geometry needs. */
+export interface HandoffRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** What `attach()` needs of an element — satisfied by a real `<img>`, and by anything
+ *  else shaped like one. Deliberately not `HTMLImageElement`: the published types would
+ *  then require a DOM lib in every consumer's tsconfig, including the server-side ones
+ *  that never open a viewer. */
+export interface HandoffElement {
+    getBoundingClientRect(): HandoffRect;
+    parentElement?: {
+        getBoundingClientRect(): HandoffRect;
+        style?: any;
+    } | null;
+    naturalWidth?: number;
+    naturalHeight?: number;
+    src?: string;
+    style?: any;
+    addEventListener(type: string, handler: (event: any) => void, options?: any): void;
+    removeEventListener(type: string, handler: (event: any) => void, options?: any): void;
+    setPointerCapture?(pointerId: number): void;
+    releasePointerCapture?(pointerId: number): void;
+}
+/** Everything needed to render the handed-over page, recomputed as frames arrive.
+ *
+ *  Read it in `onView` and paint however you like — or hand an element to `attach()`
+ *  and never look at this at all. */
+export interface HandoffView {
+    /** False once the hand-off is over; the viewer should come off the screen. */
+    active: boolean;
+    /** The page's address, for the caption. */
+    url: string;
+    /** The picture to show, as a data URI. Empty until the first frame lands. */
+    image: string;
+    /** True when frames are being pushed; false while showing the polled fallback. */
+    live: boolean;
+    /** The region being shown, in page pixels, and where it was taken from. `origin` is
+     *  echoed back with every pointer event — never added to a coordinate here. */
+    origin: {
+        x: number;
+        y: number;
+    };
+    width: number;
+    height: number;
+    /** False when the whole viewport is being shown rather than a region. */
+    clipped: boolean;
+    /** True when the frame must be blown up and offset to show only the region — which
+     *  is what `style` does. */
+    cropping: boolean;
+    /** CSS for the image and the window it shows through. Applied for you by `attach()`;
+     *  spread onto your own elements if you render the picture yourself. */
+    style: {
+        image: Record<string, string>;
+        window: Record<string, string>;
+    };
+    /** False = they may look and not touch. Enforced server-side as well. */
+    interactive: boolean;
+    /** A "did that finish it?" check is in flight — say so, rather than letting the
+     *  viewer vanish under them a moment later with no explanation. */
+    checking: boolean;
+    /** The hand-off as the agent announced it (reason, blocking, auto_done…). */
+    handoff: Handoff;
+}
+export interface HandoffOptions {
+    /** Called whenever anything about the view changes — a frame, a clip, a check. */
+    onView?: (view: HandoffView) => void;
+    /** The hand-off is over. `resume` is true when the turn stopped for it and is waiting
+     *  to be continued: send `handoff_done: true` (via `chat.handoffDone`, or your own
+     *  streamed turn if you render one). Deliberately yours to do — the SDK owns the
+     *  viewer, not the conversation. */
+    onEnded?: (info: {
+        resume: boolean;
+    }) => void;
+    /** Frame/relay/check failures. Never thrown: a viewer that dies on a dropped frame is
+     *  worse than one that misses it. */
+    onError?: (message: string) => void;
+    /** How long after a gesture ends before asking whether it finished the job. A check
+     *  fired the instant a drag ends asks about a widget still animating. Default 700ms. */
+    settleMs?: number;
+    /** Minimum gap between relayed pointer moves. A pointermove handler fires far faster
+     *  than any network will carry. Default 16ms (~60/s). */
+    relayMs?: number;
+    /** How long to wait for the stream to paint before fetching one frame the slow way,
+     *  so a viewer shows something even if the stream cannot be opened. Default 1500ms. */
+    fallbackMs?: number;
+}
+/** A live hand-off: the stream, the geometry, the gestures and the finished-check. */
+export interface HandoffController {
+    /** The current view. Also delivered to `onView` as it changes. */
+    readonly view: HandoffView;
+    /** Paint into this element and relay what the user does to it. Returns a detach
+     *  function; call it when the element goes away (a re-render, an unmount). */
+    attach: (element: HandoffElement) => () => void;
+    /** The agent re-announced the hand-off. Keeps the stream when it is still the same
+     *  view — each announcement is a new object, and re-opening on every one blanks the
+     *  picture mid-gesture. */
+    update: (handoff: Handoff) => void;
+    /** Relay one thing the user did. `selector`, `origin` and `want_frame` are filled in;
+     *  for a custom viewer, send `x`/`y` in the image space `view` describes. */
+    send: (input: BrowserInputEvent) => Promise<void>;
+    /** Type into the page, then (optionally) press Enter — what a text box in your UI
+     *  should call. */
+    type: (text: string, opts?: {
+        submit?: boolean;
+    }) => Promise<void>;
+    key: (key: string, modifiers?: string[]) => Promise<void>;
+    scroll: (pixels: number) => Promise<void>;
+    /** A gesture ended: schedule the "did that finish it?" check. `attach()` calls this
+     *  on release; call it yourself if you relay gestures your own way. */
+    settled: () => void;
+    /** Finish the hand-off — the "I'm done" button. Fires `onEnded`. */
+    done: () => Promise<void>;
+    /** Stop watching without ending anything: the viewer went away, the turn did not. */
+    close: () => void;
+}
+/** A page the agent has put in front of the user. */
+export interface Handoff {
+    active: boolean;
+    /** The turn STOPPED and resumes when they say they're done — same shape as a pending
+     *  client tool call, because it is the same situation. Render a "Done" button and
+     *  send `handoff_done: true` when it's pressed. */
+    blocking: boolean;
+    /** False = show it, don't let them touch it. Enforced server-side too. */
+    interactive: boolean;
+    /** Poll `handoffCheck` after each release and press Done when it reports finished —
+     *  someone who has just passed a bot check should not then have to report that they
+     *  passed it. False when the agent gave nothing to judge against, or wants telling. */
+    auto_done: boolean;
+    reason: string;
+    url: string;
+    selector: string;
+    clipped: boolean;
+}
+/** One thing the user did, relayed into the page.
+ *
+ *  The pointer kinds are what make a hand-off able to do more than tap: press, move,
+ *  release IS a drag, which is what a slider puzzle asks for. Stream `pointer_move`
+ *  from a real pointermove handler and the page sees the gesture the person actually
+ *  made, path and all. */
+export interface BrowserInputEvent {
+    type: "click" | "pointer_down" | "pointer_move" | "pointer_up" | "drag" | "wheel" | "type" | "key" | "scroll";
+    /** Keep the same crop the agent handed over, so the view doesn't jump. */
+    selector?: string;
+    x?: number;
+    y?: number;
+    origin?: {
+        x: number;
+        y: number;
+    };
+    text?: string;
+    key?: string;
+    pixels?: number;
+    /** Held for this input: "Shift" | "Control" | "Alt" | "Meta". */
+    modifiers?: string[];
+    button?: "left" | "right" | "middle" | "back" | "forward";
+    /** 2 is a double-click, 3 a triple — a selection gesture, not three clicks. */
+    clicks?: number;
+    /** `drag`: where it ends, same image space as x/y. */
+    to?: {
+        x: number;
+        y: number;
+    };
+    /** `drag`: how long the path takes. A drag with no duration is a teleport. */
+    hold_ms?: number;
+    steps?: number;
+    /** `wheel`: for panes that scroll under the pointer rather than the window. */
+    delta_x?: number;
+    delta_y?: number;
+    /** Set FALSE when watching `browserStream` — otherwise every pointer move renders a
+     *  full JPEG server-side that arrives after the stream has already shown it. */
+    want_frame?: boolean;
+}
+export interface QuestionOption {
+    label: string;
+    description?: string | null;
+}
+/** One decision the agent put to the user. Render `options` as a picker —
+ *  checkboxes when `multi_select`, radio otherwise — and always offer two escapes
+ *  the agent cannot take away: a free-text answer, and declining to answer at all
+ *  (`chat_instead`), which tells the agent to drop the question and keep talking.
+ *
+ *  `options` is empty when the answer is genuinely open-ended: render a text input. */
+export interface AgentQuestion {
+    id: string;
+    /** Very short label — the tab/chip for this question in a multi-question batch. */
+    header: string;
+    question: string;
+    options: QuestionOption[];
+    multi_select: boolean;
+    /** Always true today: "type something else" is never withheld. */
+    allow_other: boolean;
+}
+/** A paused `ask_user` call: what was asked, and the id that answers it. */
+export interface PendingQuestions {
+    tool_call_id: string;
+    questions: AgentQuestion[];
+}
+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[];
+    /** The "type something else" answer. May accompany selections. */
+    text?: string | null;
+}
+/** Resumes a turn paused on a question. Set `chat_instead` when the user declined
+ *  the picker — the agent is told to drop the question rather than re-ask it. */
+export interface QuestionAnswer {
+    /** The paused call. Optional when exactly one question is outstanding. */
+    tool_call_id?: string;
+    answers?: QuestionAnswerItem[];
+    chat_instead?: boolean;
+    /** What the user said instead, if anything. */
+    message?: string | null;
+}
+/** Answer a batch of questions. Return one entry per question (or a single
+ *  `{ chat_instead: true }` to decline the whole batch and keep chatting). */
+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[];
+    /** Max auto tool-dispatch rounds before giving up (default 10). */
+    maxToolRounds?: number;
+    /** Fires before each batch of client tools is executed. */
+    onToolCalls?: (calls: PendingToolCall[]) => void;
+    /** 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;
+    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. */
+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
+     *  the mid-turn `attachments` event and from the response that follows. It is also
+     *  the handle to pass to a tool that takes a file. */
+    id?: string;
+    kind: "image" | "audio" | "video" | "file" | string;
+    url: string;
+    mime_type?: string | null;
+    name?: string | null;
+    format?: string | null;
+    /** Set on outputs (e.g. a file the agent exported from its sandbox). */
+    size?: number | null;
+    /** Generated/exported media is stored server-side and `url` is signed fresh on each
+     *  response — download it or show it, but don't persist the URL, it expires. */
+    /** Input only: hand the ORIGINAL bytes to the sandbox instead of showing the file
+     *  to the model. Needs the `computer` capability; the model is told the path it
+     *  landed at. Use for data files the agent should process with commands. */
+    to_sandbox?: boolean;
+}
+/** What this deployment's sandboxes are and what they can do. The sandbox host is the
+ *  deployment's, not the project's: there is no backend to configure. */
+export interface ComputerHost {
+    provider: "firecracker" | "cloudflare" | "e2b" | string;
+    /** pause / snapshot / expose_port / network_policy. */
+    capabilities: Record<string, boolean>;
+    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. */
+    exec_max_timeout_s: number;
+    max_sessions_per_tenant: number;
+}
+export type ComputerSessionStatus = "creating" | "running" | "paused" | "stopped" | "failed" | string;
+/** A sandbox. `id` is stable across pause/resume — pass it as `computer_session_id`
+ *  on a later turn to reattach the agent to this workspace. */
+export interface ComputerSession {
+    id: string;
+    name?: string | null;
+    provider: string;
+    /** The backend's own sandbox id. */
+    external_id: string;
+    status: ComputerSessionStatus;
+    workdir: string;
+    chat_session_id?: string | null;
+    error?: string | null;
+    last_used_at?: string | null;
+    expires_at?: string | null;
+    created_at: string;
+}
+export interface ComputerExecResult {
+    stdout: string;
+    stderr: string;
+    exit_code: number;
+    truncated: boolean;
+    timed_out: boolean;
+    duration_ms?: number | null;
+}
+export interface ChatRequest {
+    session_id?: string | null;
+    message?: string | null;
+    /** Additional user messages for this turn, in order — someone who kept typing while
+     *  the agent was busy. Each is stored as its own message and the agent replies once
+     *  to all of them, so the transcript shows what was actually said rather than one
+     *  merged prompt. */
+    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. */
+    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;
+    /** 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. */
+    handoff_done?: boolean;
+    client_tools?: ClientTool[] | null;
+    /** End-user-supplied MCP servers for this turn, merged with the tenant's own
+     *  project-level servers. Only honored when the token has the `mcp:manage`
+     *  capability (the project's `allowMcp` ceiling); otherwise ignored. */
+    mcp_servers?: Array<{
+        name: string;
+        url: string;
+        transport?: "sse" | "streamable_http";
+        headers?: Record<string, string>;
+    }> | null;
+    allowed_tools?: string[] | null;
+    document_ids?: string[] | null;
+    tags?: string[] | null;
+    enable_rag?: boolean;
+    enable_scheduling?: boolean;
+    enable_memory?: boolean;
+    enable_web_search?: boolean;
+    /** Opt-in: bind only the most relevant tools when the action space is large. */
+    enable_action_space?: boolean;
+    /** Let the agent run commands / edit files in an isolated sandbox. Needs the
+     *  `computer` capability and a configured backend; the sandbox is only provisioned
+     *  if the agent actually uses it. */
+    enable_computer?: boolean;
+    /** 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. */
+    enable_browser?: boolean;
+    /** Let the agent keep a todo list for this conversation. Needs the `todo` capability. */
+    enable_todo?: boolean;
+    /** Let the agent hand a self-contained piece of work to another agent that runs
+     *  alongside it. Needs the `subagents` capability AND models chosen for it in the
+     *  dashboard (Project → LLM & limits → Subagent models).
+     *
+     *  Turning it off stops new delegation; it does not abandon work already running —
+     *  a subagent started earlier still reports back into this conversation. */
+    enable_subagents?: boolean;
+    /** Let the agent pause and ask the user a structured multiple-choice question.
+     *  Needs the `ask_user` capability. Set false for any caller that cannot answer —
+     *  a batch job, a webhook, a scheduled task — so the agent never stalls waiting. */
+    enable_ask_user?: boolean;
+    model?: string | null;
+    /** Reasoning effort (minimal|low|medium|high), bounded by the token's max_effort. */
+    reasoning_effort?: "minimal" | "low" | "medium" | "high" | null;
+    system_prompt?: string | null;
+    temperature?: number;
+    user_ref?: string | null;
+}
+export interface PendingToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface Citation {
+    document_id: string;
+    chunk_index: number;
+    filename: string | null;
+    page: number | null;
+    score: number | null;
+    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). */
+export interface Source {
+    type: "document" | "web" | "query" | string;
+    title?: string | null;
+    url?: string | null;
+    snippet?: string | null;
+    document_id?: string | null;
+    page?: number | null;
+    score?: number | null;
+    screenshot?: string | null;
+}
+export interface ChatResponse {
+    session_id: string;
+    content: string;
+    requires_action: boolean;
+    tool_calls: PendingToolCall[];
+    /** The agent paused to ask the user something. Arrives with `requires_action` and
+     *  an EMPTY `tool_calls`: a question is not the client's work to execute, so tool
+     *  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'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
+     *  is not a reason to stop showing work that has not. Empty unless it has delegated. */
+    subagents: SubagentState[];
+    /** Set only when history had to be trimmed or summarized to fit the window. */
+    context?: ContextReport | null;
+    citations: Citation[];
+    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[];
+    /** 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. */
+    finish_reason?: string | null;
+}
+export interface SessionOut {
+    id: string;
+    title: string | null;
+    user_ref: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface MessageOut {
+    id: string;
+    role: "user" | "assistant" | "tool" | "system" | string;
+    content: string;
+    extra: Record<string, unknown>;
+    created_at: string;
+}
+export type TaskKind = "once" | "recurring";
+export interface TaskAction {
+    type?: "agent" | "webhook";
+    session_id?: string | null;
+    prompt?: string | null;
+    system_prompt?: string | null;
+    model?: string | null;
+    callback_url?: string | null;
+    url?: string | null;
+    method?: string;
+    headers?: Record<string, string>;
+    payload?: Record<string, unknown>;
+}
+export interface TaskCreate {
+    name: string;
+    kind: TaskKind;
+    run_at?: string | null;
+    cron?: string | null;
+    interval_seconds?: number | null;
+    timezone?: string;
+    action: TaskAction;
+}
+export interface TaskOut {
+    id: string;
+    name: string;
+    kind: TaskKind;
+    status: string;
+    created_by: string;
+    run_at: string | null;
+    cron: string | null;
+    interval_seconds: number | null;
+    timezone: string;
+    action: Record<string, unknown>;
+    run_count: number;
+    last_run_at: string | null;
+    next_run_at: string | null;
+    last_error: string | null;
+    created_at: string;
+}
+export type ConnectorType = "postgres" | "http" | string;
+export interface SyncConfig {
+    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[];
+}
+export interface SourceOut {
+    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[];
+    visibility: string;
+    visibility_scope: string | null;
+    status: string;
+    error: string | null;
+    record_count: number;
+    last_synced_at: string | null;
+    created_at: string;
+}
+export interface AuditEntry {
+    id: string;
+    subject: string | null;
+    action: string;
+    resource_type: string | null;
+    resource_id: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+export interface ForgetResult {
+    subject: string;
+    documents_deleted: number;
+    sessions_deleted: number;
+    /** Sandboxes destroyed — they hold the subject's files too. */
+    sandboxes_destroyed: number;
+    vectors_purged: boolean;
+}
+export type StreamEvent = {
+    event: "run";
+    data: {
+        run_id: string;
+    };
+} | {
+    event: "start";
+    data: {
+        session_id: string;
+    };
+} | {
+    event: "token";
+    data: {
+        delta: string;
+    };
+} | {
+    event: "tool_start";
+    data: {
+        name: string;
+        input: unknown;
+    };
+} | {
+    event: "tool_end";
+    data: {
+        name: string;
+        output: string;
+    };
+}
+/** A sandbox command's output WHILE it runs, a chunk at a time. Arrives between a
+ *  `tool_start` for `computer_bash` and its `tool_end`, so a long build or test run
+ *  can be watched instead of appearing to hang. `command_id` groups the chunks of one
+ *  command; the same text also arrives whole in `tool_end`, so ignoring these events
+ *  costs nothing but the liveness. */
+ | {
+    event: "command_output";
+    data: {
+        command_id: string;
+        command: string;
+        stream: "stdout" | "stderr";
+        delta: string;
+    };
+}
+/** A command the agent started in the background has finished and been reported to it.
+ *  Arrives at a step boundary — the agent is told between its own moves, never
+ *  mid-tool. If the turn had already ended when the command finished, the report
+ *  arrives as a NEW turn in the same session instead (like a scheduled run), which your
+ *  `onTurn`/webhook path already handles. */
+ | {
+    event: "command_finished";
+    data: {
+        job_id: string;
+        command: string;
+        exit_code: number | null;
+        status: string;
+    };
+} | {
+    event: "citations";
+    data: {
+        citations: Citation[];
+    };
+} | {
+    event: "sources";
+    data: {
+        sources: Source[];
+    };
+} | {
+    event: "guardrail";
+    data: {
+        stage: "input" | "output";
+        flags: string[];
+        content?: string;
+    };
+}
+/** Files for the user. Arrives DURING the turn, as each is produced, and once more
+ *  before `done`; every frame carries the whole list so far. */
+ | {
+    event: "attachments";
+    data: {
+        attachments: Attachment[];
+    };
+} | {
+    event: "todos";
+    data: {
+        todos: TodoItem[];
+    };
+}
+/** One subagent moved: started, changed what it is doing, asked the main agent
+ *  something, or finished. Carries that ONE subagent — merge it into what you are
+ *  showing by `ref`. */
+ | {
+    event: "subagent";
+    data: {
+        subagent: SubagentState;
+    };
+}
+/** Every subagent of the conversation, sent once before `done`. Render from this
+ *  rather than from accumulated `subagent` frames where you can: a reconnect or a
+ *  missed frame cannot leave it wrong. */
+ | {
+    event: "subagents";
+    data: {
+        subagents: SubagentState[];
+    };
+} | {
+    event: "questions";
+    data: {
+        questions: PendingQuestions[];
+    };
+}
+/** 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. */
+ | {
+    event: "browser_handoff";
+    data: Handoff;
+}
+/** History management. `compacting` arrives BEFORE the turn produces anything —
+ *  summarizing a long transcript is a full model round-trip, so show a
+ *  "compacting conversation…" state rather than a blank screen — and is followed by
+ *  a `done` frame with the outcome. `compacting` never fires for a plain trim,
+ *  which is instant. */
+ | {
+    event: "context";
+    data: ContextProgress | ContextReport;
+}
+/** A reasoning model's thinking, streamed as it happens — arrives BEFORE (and
+ *  between) `token` frames. Render it, or just use the first one to show that the
+ *  model is working. */
+ | {
+    event: "reasoning";
+    data: {
+        delta: string;
+    };
+} | {
+    event: "done";
+    data: {
+        session_id: string;
+        content: string;
+        requires_action: boolean;
+        tool_calls: PendingToolCall[];
+        questions: PendingQuestions[];
+        todos: TodoItem[];
+        subagents: SubagentState[];
+        handoff?: Handoff | null;
+        guard_flags: string[];
+        context?: ContextReport | null;
+        citations: Citation[];
+        sources: Source[];
+        attachments: Attachment[];
+        reasoning?: string;
+        finish_reason?: string | null;
+    };
+} | {
+    event: "cancelled";
+    data: {
+        run_id: string;
+    };
+} | {
+    event: "error";
+    data: {
+        detail: string;
+    };
+};
+export interface StreamHandlers {
+    onToken?: (delta: string, full: string) => void;
+    onEvent?: (event: StreamEvent) => void;
+    onToolStart?: (name: string, input: unknown) => void;
+    onToolEnd?: (name: string, output: string) => void;
+    onCitations?: (citations: Citation[]) => void;
+    onSources?: (sources: Source[]) => void;
+    /** A guardrail acted on the turn (input block/redaction or output redaction/refusal). */
+    onGuardrail?: (stage: "input" | "output", flags: string[], content?: string) => void;
+    /** Non-text outputs: a file the agent handed over, a screenshot it took, media it
+     *  generated. Fires as soon as one is produced — mid-turn, right after the tool call
+     *  that made it — and again before `done` with the complete list.
+     *
+     *  Each call carries EVERY file of the turn so far, not just the new one, so render
+     *  from the list rather than appending: that way a reconnect or a missed frame cannot
+     *  leave a gap, and re-rendering is idempotent. Files the agent kept for itself
+     *  (a screenshot taken only to be cropped) are never in it. */
+    onAttachments?: (attachments: Attachment[]) => void;
+    /** A reasoning model is thinking. `delta` is the newest thinking text and `full` the
+     *  accumulated trace. With a reasoning model this fires well before the first token,
+     *  which is what a "Thinking…" indicator should key off — otherwise the UI looks
+     *  frozen for as long as the model reasons. */
+    onReasoning?: (delta: string, full: string) => void;
+    /** The agent's plan changed. Fires whenever the turn touched its todo list —
+     *  render it as a live checklist so the user can see where the agent is. */
+    onTodos?: (todos: TodoItem[]) => void;
+    /** A subagent started, moved, asked the main agent something, or finished.
+     *
+     *  Called with EVERY subagent of the conversation, not just the one that moved, for
+     *  the same reason `onAttachments` is: render from the list and a dropped frame
+     *  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;
+    /** 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. */
+    onCommandOutput?: (chunk: {
+        command_id: string;
+        command: string;
+        stream: "stdout" | "stderr";
+        delta: string;
+    }) => void;
+    /** A background command finished and the agent has just been told. Show it: the user
+     *  watched the command start and has been waiting longer than the agent has. */
+    onCommandFinished?: (job: {
+        job_id: string;
+        command: string;
+        exit_code: number | null;
+        status: string;
+    }) => void;
+    /** The agent paused on a question. Without `onQuestion` the stream simply ends
+     *  with these on `done`, and you resume it yourself with `question_answers`. */
+    onQuestions?: (pending: PendingQuestions[]) => void;
+    /** The agent needs the user to act on a page themselves. */
+    onBrowserHandoff?: (h: Handoff) => void;
+    /** History had to be trimmed or summarized to fit the model's window. Fires only
+     *  when it actually happened — useful for spotting a budget set too low. */
+    onContext?: (event: ContextProgress | ContextReport) => void;
+    /** Answer the agent's questions and continue the stream automatically. Show the
+     *  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;
+    /** Called each time the client (re)connects, with the resume attempt count. */
+    onReconnect?: (attempt: number) => void;
+    signal?: AbortSignal;
+    /** Max reconnection attempts after a drop (default 10). */
+    maxRetries?: number;
+    /** Extra client tools for this stream (merged over any registered on the client).
+     *  When any tools are available, the stream auto-executes tool calls and resumes,
+     *  so `done` only resolves once the agent finishes (no `requires_action`). */
+    tools?: ClientToolDef[];
+    /** Fires before each batch of client tools runs. */
+    onToolCalls?: (calls: PendingToolCall[]) => void;
+    /** Max auto tool-dispatch rounds before giving up (default 10). */
+    maxToolRounds?: number;
+}
+/** Handlers for `chat.sessions.watch`. */
+export interface WatchHandlers {
+    /** A message that appeared in the session which this client did not stream.
+     *  A fired reminder arrives as its prompt (`role: "user"`) followed by the
+     *  agent's answer (`role: "assistant"`) — filter to what your UI should show. */
+    onMessage: (message: MessageOut) => void;
+    onError?: (error: Error) => void;
+    /** Poll interval in ms for the fallback path (default 4000). */
+    intervalMs?: number;
+    /** Force polling instead of the live stream (mostly for testing). */
+    poll?: boolean;
+    /** Fires when the transport is decided, so a UI can say "live" vs "polling". */
+    onTransport?: (transport: "stream" | "poll") => void;
+    signal?: AbortSignal;
+}
+export interface SessionWatch {
+    /** Stop watching. Safe to call more than once. */
+    stop: () => void;
+    /** Treat everything currently in the session as already delivered. Called for
+     *  you whenever this client streams a turn on the watched session. */
+    resync: () => Promise<void>;
+}
+export interface ChatDone {
+    session_id: string;
+    content: string;
+    requires_action: boolean;
+    tool_calls: PendingToolCall[];
+    /** Questions the agent paused on. Empty once `onQuestion` has answered them. */
+    questions: PendingQuestions[];
+    /** 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
+     *  finishing does not finish them, and they report into the next one. */
+    subagents: SubagentState[];
+    /** Set when the agent put a page in front of the user. */
+    handoff?: Handoff | null;
+    /** Guardrails that acted on this turn (also announced live as a `guardrail` event). */
+    guard_flags: string[];
+    /** Set only when history had to be trimmed or summarized to fit the window. */
+    context?: ContextReport | null;
+    citations: Citation[];
+    sources: Source[];
+    attachments: Attachment[];
+    /** The full thinking trace of a reasoning model, else "" (streamed as `reasoning`). */
+    reasoning?: string;
+    /** Non-normal stop reason, else null (e.g. "max_tool_iterations"). */
+    finish_reason?: string | null;
+}
+export interface StreamHandle extends Promise<ChatDone> {
+    /** Resolves with the terminal `done` payload; rejects on server error/cancel/abort.
+     *  The handle is itself awaitable — `await af.chat.stream(...)` returns this. */
+    done: Promise<ChatDone>;
+    /** Stop listening locally. Server-side generation KEEPS running (resume later). */
+    disconnect: () => void;
+    /** Terminate server-side generation (stops model spend), then stop listening.
+     *  Best-effort: fires POST /chat/stream/{run_id}/cancel once the run id is known. */
+    cancel: () => Promise<void>;
+    /** The run id (available once the first frame arrives). */
+    runId: () => string | undefined;
+    /** Send a message INTO this running turn. Needs the `steer` capability.
+     *
+     *  The agent picks it up at its next step — after any tool in flight finishes — and
+     *  reads it as the user speaking. Use it to correct work you can already see going
+     *  wrong; to simply say the next thing, wait for `done` and send a normal message.
+     *
+     *  Resolves `false` if the turn finished first, in which case send it as a normal
+     *  message instead — the caller has to know, so it is not swallowed. */
+    steer: (message: string) => Promise<boolean>;
+}
+export declare class AgentCancelledError extends Error {
+    constructor();
+}
+export type UploadInput = Blob | ArrayBuffer | Uint8Array;
+/** Who may retrieve a document/source once it's indexed. `self` is the strictest —
+ *  not even an admin token sees it. Matched on every search, so a user can't get an
+ *  answer grounded in something they may not read. */
+export type Visibility = "self" | "private" | "shared" | "groups" | "tenant";
+/** Access control shared by uploads, presigned uploads and patches. */
+export interface AclFields {
+    visibility?: Visibility;
+    /** Path prefix `shared` visibility applies under, e.g. "acme:finance". */
+    visibility_scope?: string | null;
+    /** Roles/groups (matched against the reader's token) for `groups` visibility. */
+    acl_roles?: string[];
+    acl_groups?: string[];
+}
+export interface UploadOptions extends AclFields {
+    filename: string;
+    contentType?: string;
+    tags?: string[];
+    /** Parallel part uploads (default 4). */
+    concurrency?: number;
+    /** Per-part retry attempts (default 5). */
+    maxRetries?: number;
+    /** Part-completion progress: fires after each part finishes (not byte-level;
+     *  fetch has no upload-progress event without XHR). */
+    onProgress?: (sent: number, total: number) => void;
+    signal?: AbortSignal;
+}
+export interface DownloadOptions {
+    /** Range chunk size in bytes (default 8 MiB). */
+    chunkSize?: number;
+    maxRetries?: number;
+    onProgress?: (received: number, total: number | null) => void;
+    signal?: AbortSignal;
+}
+export declare class AgentApiError extends Error {
+    status: number;
+    detail: unknown;
+    constructor(status: number, detail: unknown);
+}
+export declare class AgentStreamError extends Error {
+    constructor(message: string);
+}
+export declare class AgentFramework {
+    readonly baseUrl: string;
+    private readonly opts;
+    private readonly _fetch;
+    private readonly toolRegistry;
+    /** 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. */
+    private currentToken?;
+    /** The last token the server rejected, so we don't keep re-sending it. */
+    private rejectedToken?;
+    /** In-flight refresh, shared so N concurrent 401s mint one token, not N. */
+    private refreshing?;
+    constructor(opts: ClientOptions);
+    /** Seconds before a token's own expiry at which we stop using it.
+     *
+     *  Reacting to a 401 covers most requests, because the failed one is replayed. It
+     *  cannot cover an upload: a FormData body is a stream that may already have been
+     *  consumed, so a multipart request that 401s cannot be replayed and the expiry
+     *  surfaces as a failed upload with nothing the caller can do. Nor does it help a
+     *  long-running turn that starts with a token about to lapse.
+     *
+     *  So a token is retired slightly before it expires, from the `exp` it carries. The
+     *  margin covers clock skew between the browser and the server and the round trip
+     *  itself. The 401 path stays exactly as it was — this only avoids reaching it. */
+    /** Everything behind `chat.sessions.handoff()`.
+     *
+     *  A closure rather than a class because all of it is state that dies with the
+     *  hand-off, and because the whole point is that the caller holds one object and
+     *  nothing else. See the notes on `HandoffController` for what it takes off them. */
+    private buildHandoff;
+    private static readonly EXPIRY_MARGIN_S;
+    /** Seconds until this JWT expires, or null if it does not say.
+     *
+     *  Reads `exp` without verifying anything: the signature is the server's business and
+     *  a token we cannot parse is simply used as-is, which is the behaviour that existed
+     *  before. Never throws — a malformed token must not break a request that might have
+     *  worked. */
+    private tokenLifeLeft;
+    /** The bearer for the next request. */
+    private resolveToken;
+    /** Whether pre-expiry refreshing is still worth attempting; see `resolveToken`. */
+    private proactive;
+    /** Ask `getToken` for a replacement after a 401, at most one call in flight so N
+     *  concurrent rejections mint one token rather than N. Returns undefined when there
+     *  is no callback (or it failed) — the signal to let the 401 through untouched. */
+    private refreshToken;
+    /** Register a client-side tool (handler run when the agent calls it). */
+    registerTool(tool: ClientToolDef): this;
+    registerTools(tools: ClientToolDef[]): this;
+    /** Merge the client-level registry with any per-call tools (per-call wins). */
+    private resolveTools;
+    /** `bearer` overrides token resolution — used to replay a request with the token a
+     *  refresh just produced, instead of asking for one again. */
+    private authHeaders;
+    /** Like `request`, but hands back the raw Response (for binary payloads). */
+    raw(method: string, path: string, init?: {
+        query?: Record<string, unknown>;
+        body?: unknown;
+        form?: FormData;
+        signal?: AbortSignal;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    request<T = unknown>(method: string, path: string, init?: {
+        query?: Record<string, unknown>;
+        body?: unknown;
+        form?: FormData;
+        signal?: AbortSignal;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /**
+     * Mint a narrower token from the current credential — for a backend holding a
+     * project key that hands short-lived, per-end-user tokens to its frontend. Every
+     * field is intersected/clamped with what the caller already holds, so this can only
+     * ever narrow: a restricted token cannot mint a broader one.
+     */
+    auth: {
+        token: (body?: TokenRequest) => Promise<TokenResponse>;
+    };
+    private adminHeaders;
+    tenants: {
+        create: (body: {
+            slug: string;
+            name: string;
+            settings?: Record<string, unknown>;
+        }) => Promise<TenantCreated>;
+        list: () => Promise<TenantOut[]>;
+        /** Merge keys into a tenant's settings (model routing, retrieval models, allowed
+         *  browser origins, guardrail policy...). Merged, not replaced — omitted keys are
+         *  left alone. */
+        patchSettings: (id: string, settings: Record<string, unknown>) => Promise<TenantOut>;
+    };
+    /** Liveness (`health`) and dependency readiness (`ready`). No auth required — use
+     *  them from a probe or a status page. `ready` reports "degraded" with a per-check
+     *  reason rather than failing, so you can tell "up but Postgres is unreachable"
+     *  apart from "down". */
+    health: {
+        live: () => Promise<{
+            status: string;
+        }>;
+        ready: () => Promise<{
+            status: string;
+        } & Record<string, string>>;
+    };
+    tools: {
+        list: () => Promise<{
+            tools: ToolInfo[];
+        }>;
+    };
+    chat: {
+        /** One round-trip. Returns `requires_action` + `tool_calls` for you to handle
+         *  manually — use `chat.run` to auto-dispatch client tools instead. */
+        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
+         *  handlers, submits the results, and repeats until the agent is done. */
+        run: (opts?: RunOptions) => Promise<ChatResponse>;
+        /** Streaming chat. When client tools are registered/passed, tool calls are
+         *  auto-executed and the stream resumes, so `done` only resolves when the
+         *  agent finishes (never with `requires_action`). */
+        stream: (body: ChatRequest, handlers?: StreamHandlers) => StreamHandle;
+        /** Send a message into a turn that is still running (needs `steer`).
+         *
+         *  Prefer `handle.steer(...)` when you have the stream handle. This is for a
+         *  caller that only kept the run id. Resolves false if the turn already ended. */
+        steer: (runId: string, message: string) => Promise<boolean>;
+        /** Resume a turn the agent paused on a question.
+         *
+         *  Use it when you drive the picker yourself (`chat.send` returned `questions`);
+         *  with `onQuestion` on `chat.run`/`chat.stream` this happens for you.
+         *
+         *    const r = await ai.chat.send({ message: "migrate the fetchers" });
+         *    if (r.questions.length) {
+         *      const picked = await showPicker(r.questions[0]);       // your UI
+         *      await ai.chat.answer(r.session_id, {
+         *        tool_call_id: r.questions[0].tool_call_id,
+         *        answers: [{ question_id: "Scope", selected: [picked] }],
+         *      });
+         *    }
+         *
+         *  Pass `{ chat_instead: true, message }` when the user would rather keep
+         *  talking — the agent drops the question instead of re-asking it. */
+        /** Tell the agent the user is finished with a page it handed over, resuming the
+         *  turn that stopped on it. */
+        handoffDone: (sessionId: string) => Promise<ChatResponse>;
+        answer: (sessionId: string, ...answers: QuestionAnswer[]) => Promise<ChatResponse>;
+        sessions: {
+            list: (userRef?: string) => 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[]>;
+            /** What the handed-over page looks like right now. Needs `browser_handoff`.
+             *
+             *  Poll this while the user has control, and pass the same `selector` the agent
+             *  handed over so the view doesn't jump. Re-read rather than sent once because
+             *  the thing a person has to act on — a CAPTCHA challenge grid — often only
+             *  appears after their first click. */
+            browserFrame: (sessionId: string, selector?: string) => Promise<BrowserFrame>;
+            /** Watch the handed-over page live, instead of asking for pictures of it.
+             *
+             *  Frames are pushed as Chrome repaints. Polling `browserFrame` gives roughly one
+             *  frame a second, which is fine for watching a page settle and not enough to act
+             *  on one — a slider puzzle at that rate can't be completed.
+             *
+             *  `onClip` fires only when the region worth showing MOVES (an overlay appears,
+             *  the page scrolls). Crop client-side against the last clip: the frames are the
+             *  whole viewport, so `origin` is both where to crop and what to echo back with a
+             *  pointer event. */
+            browserStream: (sessionId: string, handlers: BrowserStreamHandlers, selector?: string) => BrowserStream;
+            /** Has the person finished with the page they were handed?
+             *
+             *  Call it after they let go of the mouse. A separate small model looks at the
+             *  region and reports one of four words; when `done`, press Done for them with
+             *  `chat.handoffDone`. Rate-limited server-side, so calling it on every mouse-up
+             *  is fine — the extra calls come back `checked: false`. */
+            handoffCheck: (sessionId: string) => Promise<HandoffCheck>;
+            /** Relay one thing the user did into the page, and get the resulting frame.
+             *
+             *  Send `x`/`y` in IMAGE space along with the `origin` of the frame they clicked
+             *  — echo it back rather than adding it yourself, so a frame that moved between
+             *  render and click can't displace the click.
+             *
+             *  Watching `browserStream`? Set `want_frame: false` — otherwise every pointer
+             *  move renders a JPEG that arrives after the stream already showed it. */
+            browserInput: (sessionId: string, input: BrowserInputEvent) => Promise<BrowserFrame>;
+            /** The whole hand-off, driven for you.
+             *
+             *  Call it when a `browser_handoff` event arrives with `active: true`, give it an
+             *  `<img>`, and you are done: it opens the live stream, crops each frame to the
+             *  region the agent pointed at, maps clicks and drags back into page space, relays
+             *  them, and asks the server whether the gesture finished the job — pressing Done
+             *  for the user when it did.
+             *
+             *      const view = ai.chat.sessions.handoff(sessionId, handoff, {
+             *        onView: () => render(),
+             *        onEnded: ({ resume }) => resume && ai.chat.handoffDone(sessionId),
+             *      });
+             *      const detach = view.attach(imgElement);   // in your effect
+             *      // …later: detach(); view.close();
+             *
+             *  Nothing here needs a browser until `attach()`, and `attach()` needs only an
+             *  object shaped like an image — so importing the SDK on a server is unaffected. */
+            handoff: (sessionId: string, handoff: Handoff, options?: HandoffOptions) => HandoffController;
+            /** A few things the user might say next, in their voice — render as buttons and
+             *  send the clicked one as an ordinary message. Needs the `followups` capability.
+             *
+             *  Call it AFTER the turn's `done`, not before: it is a separate request on
+             *  purpose, so the answer is never held up by a suggestion nobody asked for.
+             *  The agent is not told a message was suggested rather than typed, and nothing
+             *  is stored. Returns [] when nothing sensible follows or generation failed —
+             *  a missing affordance is not worth an error. */
+            followups: (sessionId: string, count?: number) => Promise<{
+                suggestions: string[];
+            }>;
+            /** One or two sentences on where this conversation got to, for a user coming
+             *  back after a while. Needs the `recap` capability.
+             *
+             *  Your client decides when to ask — only it knows the tab has been idle. This
+             *  is not context compaction: that summarizes FOR the model and is replayed to
+             *  it, whereas the agent never sees this. Returns "" on failure. */
+            recap: (sessionId: string) => Promise<{
+                recap: string;
+            }>;
+            messages: (sessionId: string) => Promise<MessageOut[]>;
+            delete: (sessionId: string) => Promise<void>;
+            /**
+             * Deliver messages that appear in a session which this client did not stream.
+             *
+             * A scheduled reminder (`schedule_reminder`, or any task with an `agent`
+             * action) runs server-side and appends its answer to the session — there is no
+             * stream to listen to, so without this a reminder fires and the UI never hears
+             * about it. History is snapshotted on start and this client's own turns are
+             * marked seen automatically, so `onMessage` only fires for genuinely new
+             * messages. For server-to-server delivery, give the task a `callback_url`
+             * instead of polling.
+             */
+            watch: (sessionId: string, handlers: WatchHandlers) => SessionWatch;
+            /** Branch a conversation: create a new chat by copying `sessionId` up to and
+             *  including `upToMessageId` (or the whole chat if omitted). */
+            fork: (sessionId: string, opts?: {
+                upToMessageId?: string;
+                title?: string;
+            }) => Promise<SessionOut>;
+        };
+    };
+    documents: {
+        list: (query?: {
+            tag?: string;
+            status_filter?: string;
+        }) => Promise<DocumentOut[]>;
+        get: (id: string) => Promise<DocumentOut>;
+        delete: (id: string) => Promise<void>;
+        retrieve: (body: RetrieveRequest) => Promise<RetrievedChunk[]>;
+        /** Small-file convenience upload via multipart form (server proxies to S3). */
+        uploadSimple: (file: UploadInput, opts: AclFields & {
+            filename: string;
+            contentType?: string;
+            tags?: string[];
+            signal?: AbortSignal;
+        }) => Promise<DocumentOut>;
+        /** Resumable presigned multipart upload (direct to S3). */
+        upload: (file: UploadInput, opts: UploadOptions) => Promise<DocumentOut>;
+        /** Poll a document until ingestion finishes (status "ready" or "failed").
+         *  Ingestion is async, so querying a just-uploaded doc may return nothing until
+         *  this resolves. Throws on "failed" or timeout. */
+        waitReady: (id: string, opts?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+            signal?: AbortSignal;
+        }) => Promise<DocumentOut>;
+        /** Upload a small file AND wait for it to finish ingesting — the common case. */
+        uploadAndWait: (file: UploadInput, opts: AclFields & {
+            filename: string;
+            contentType?: string;
+            tags?: string[];
+            timeoutMs?: number;
+            signal?: AbortSignal;
+        }) => Promise<DocumentOut>;
+        /** Get a presigned GET URL for the raw file. */
+        downloadUrl: (id: string) => Promise<{
+            url: string;
+            expires_in: number;
+            size: number | null;
+            content_type: string | null;
+        }>;
+        /** Resumable ranged download; returns a Blob. */
+        download: (id: string, opts?: DownloadOptions) => Promise<Blob>;
+        /** Update a document's tags / visibility / ACL. */
+        patch: (id: string, body: AclFields & {
+            tags?: string[];
+        }) => Promise<DocumentOut>;
+        /** Reprocess a document (retry a failed ingest, or re-embed with a new model). */
+        reingest: (id: string) => Promise<DocumentOut>;
+        /** Inspect the stored chunks of a document (text + page + index). */
+        chunks: (id: string) => Promise<{
+            chunk_index: number | null;
+            page: number | null;
+            text: string;
+        }[]>;
+    };
+    tasks: {
+        create: (body: TaskCreate) => Promise<TaskOut>;
+        list: (status?: string) => Promise<TaskOut[]>;
+        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>;
+    };
+    audit: {
+        /** Read the tenant's audit trail (admin). Filter by action/subject. */
+        list: (opts?: {
+            action?: string;
+            subject?: string;
+            limit?: number;
+        }) => Promise<AuditEntry[]>;
+        /** Purge a subject's documents, sessions, and vectors (GDPR erasure; admin). */
+        forget: (subject: string) => Promise<ForgetResult>;
+    };
+    /**
+     * Sandboxed compute — the isolated machines the agent works in. Each session has a
+     * stable id, survives sleep/wake, and can be reattached to a later turn via
+     * `chat({ computer_session_id })`.
+     *
+     * Nothing to configure: the deployment runs one sandbox host, and a project with the
+     * `computer` capability gets a machine. `host()` says what that machine is.
+     *
+     *   const s = await ai.computers.create();
+     *   await ai.computers.upload(s.id, file);            // any file type, straight in
+     *   await ai.chat({ message: "summarise inbox/data.csv", computer_session_id: s.id });
+     *   await ai.computers.pause(s.id);                   // sleep now instead of on idle
+     */
+    computers: {
+        /** What this deployment's sandboxes are and can do — use it to hide a feature
+         *  (port exposure, say) rather than offering a button that fails. */
+        host: () => Promise<ComputerHost>;
+        /** Start a sandbox. Bind it to a chat session to give that conversation a
+         *  persistent workspace. */
+        create: (body?: {
+            name?: string;
+            chat_session_id?: string;
+        }) => Promise<ComputerSession>;
+        list: (opts?: {
+            include_stopped?: boolean;
+        }) => Promise<ComputerSession[]>;
+        get: (id: string) => Promise<ComputerSession>;
+        /** Put it to sleep now rather than waiting for it to go idle; the workspace is
+         *  preserved either way. */
+        pause: (id: string) => Promise<ComputerSession>;
+        /** Wake a sleeping sandbox and reattach to its workspace. */
+        resume: (id: string) => Promise<ComputerSession>;
+        destroy: (id: string) => Promise<void>;
+        /** Run a command yourself (same guardrails as the agent's tool). `timeout_s` is
+         *  clamped to the host's ceiling — 30 minutes — and then the command is killed. */
+        exec: (id: string, body: {
+            command: string;
+            cwd?: string;
+            timeout_s?: number;
+            stdin?: string;
+        }) => Promise<ComputerExecResult>;
+        /** Push a file (any type) into the sandbox. */
+        upload: (id: string, file: Blob | File, dest?: string) => Promise<{
+            path: string;
+            size: number;
+        }>;
+        /** 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. */
+    private startStreamWithTools;
+    private resyncWatchers;
+    private watchSession;
+    private startStream;
+    private multipartUpload;
+    private rangedDownload;
+}
+/** Factory helper. */
+export declare function createClient(opts: ClientOptions): AgentFramework;
+export default AgentFramework;
+//# sourceMappingURL=index.d.ts.map