@oberik/sdk 0.1.0

package/dist/esm/index.js

@@ -0,0 +1,1743 @@
+/**
+ * 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;
+ */
+// ============================================================================
+// Types
+// ============================================================================
+/**
+ * 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 const DEFAULT_BASE_URL = "https://api.oberik.com";
+/** Wrap the stream's `done` promise into a thenable handle: `await handle` yields
+ *  the ChatDone, and `.done`/`.cancel`/`.disconnect`/`.runId` remain available. */
+function makeStreamHandle(done, extra) {
+    // A plain thenable: `await handle` delegates to `done`, and the control methods
+    // (.done/.cancel/.disconnect/.runId) remain directly accessible.
+    return {
+        done,
+        then: (onF, onR) => done.then(onF, onR),
+        catch: (onR) => done.catch(onR),
+        finally: (onF) => done.finally(onF),
+        ...extra,
+    };
+}
+export class AgentCancelledError extends Error {
+    constructor() {
+        super("run cancelled");
+        this.name = "AgentCancelledError";
+    }
+}
+// ============================================================================
+// Errors
+// ============================================================================
+export class AgentApiError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(typeof detail === "string" ? detail : `HTTP ${status}`);
+        this.name = "AgentApiError";
+        this.status = status;
+        this.detail = detail;
+    }
+}
+export class AgentStreamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentStreamError";
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const backoff = (attempt) => Math.min(1000 * 2 ** attempt, 15000) + Math.floor(Math.random() * 250);
+/** Convert client tool defs to the OpenAI-format schemas the API expects. */
+function toolSchemas(tools) {
+    return [...tools.values()].map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.parameters ?? { type: "object", properties: {} } },
+    }));
+}
+/** Run each pending client tool via its handler; failures become error results
+ *  (not thrown) so one bad tool doesn't abort the whole turn. */
+async function executeToolCalls(calls, tools) {
+    return Promise.all(calls.map(async (call) => {
+        const tool = tools.get(call.name);
+        let content;
+        if (!tool) {
+            content = JSON.stringify({ error: `no client tool registered named "${call.name}"` });
+        }
+        else {
+            try {
+                const out = await tool.handler(call.args ?? {}, call);
+                content = typeof out === "string" ? out : JSON.stringify(out ?? null);
+            }
+            catch (e) {
+                content = JSON.stringify({ error: String(e?.message ?? e) });
+            }
+        }
+        return { tool_call_id: call.id, content };
+    }));
+}
+/** Put each paused question batch to the handler and shape the result for the API.
+ *
+ *  A handler that throws is treated as the user declining rather than as a failure:
+ *  the alternative is leaving the turn paused forever on a question nobody can now
+ *  answer, and "they'd rather talk about it" is both true and recoverable. */
+async function collectAnswers(pending, handler) {
+    const out = [];
+    for (const batch of pending) {
+        let answer;
+        try {
+            const result = await handler(batch);
+            answer = Array.isArray(result) ? { answers: result } : result;
+        }
+        catch (e) {
+            answer = { chat_instead: true, message: String(e?.message ?? e) };
+        }
+        out.push({ ...answer, tool_call_id: answer.tool_call_id ?? batch.tool_call_id });
+    }
+    return out;
+}
+function toUint8(input) {
+    if (typeof Blob !== "undefined" && input instanceof Blob) {
+        return { size: input.size, slice: (a, b) => input.slice(a, b) };
+    }
+    const u8 = input instanceof Uint8Array ? input : new Uint8Array(input);
+    return { size: u8.byteLength, slice: (a, b) => u8.subarray(a, b) };
+}
+async function* parseSSE(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    // Handle both LF (\n\n) and CRLF (\r\n\r\n) frame separators and line endings.
+    const FRAME_SEP = /\r?\n\r?\n/;
+    let buffer = "";
+    try {
+        for (;;) {
+            if (signal?.aborted)
+                throw new DOMException("aborted", "AbortError");
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let m;
+            while ((m = FRAME_SEP.exec(buffer)) !== null) {
+                const raw = buffer.slice(0, m.index);
+                buffer = buffer.slice(m.index + m[0].length);
+                let id;
+                let event = "message";
+                const dataLines = [];
+                for (const line of raw.split(/\r?\n/)) {
+                    if (line.startsWith("id:")) {
+                        const n = parseInt(line.slice(3).trim(), 10);
+                        if (!Number.isNaN(n))
+                            id = n;
+                    }
+                    else if (line.startsWith("event:")) {
+                        event = line.slice(6).trim();
+                    }
+                    else if (line.startsWith("data:")) {
+                        dataLines.push(line.slice(5).replace(/^ /, ""));
+                    }
+                }
+                yield { id, event, data: dataLines.join("\n") };
+            }
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* noop */
+        }
+    }
+}
+// ============================================================================
+// Client
+// ============================================================================
+export class AgentFramework {
+    baseUrl;
+    opts;
+    _fetch;
+    toolRegistry = new Map();
+    /** Active session watchers, so a streamed turn can mark its own messages seen. */
+    watchers = new Set();
+    /** The bearer in use: `opts.token` initially, replaced on refresh. */
+    currentToken;
+    /** The last token the server rejected, so we don't keep re-sending it. */
+    rejectedToken;
+    /** In-flight refresh, shared so N concurrent 401s mint one token, not N. */
+    refreshing;
+    constructor(opts) {
+        this.opts = opts;
+        this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+        // Bind to globalThis: native fetch throws "Illegal invocation" in the browser
+        // when called as a method (this !== window). (Node's fetch tolerates it, so this
+        // only bit browser usage.)
+        const rawFetch = opts.fetch ?? globalThis.fetch;
+        if (!rawFetch)
+            throw new Error("No fetch available; pass options.fetch");
+        this._fetch = rawFetch.bind(globalThis);
+        this.currentToken = opts.token;
+        for (const t of opts.tools ?? [])
+            this.toolRegistry.set(t.name, t);
+    }
+    /** 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. */
+    buildHandoff(sessionId, initial, options) {
+        const api = this.chat.sessions;
+        const settleMs = options.settleMs ?? 700;
+        const relayMs = options.relayMs ?? 16;
+        const fallbackMs = options.fallbackMs ?? 1500;
+        const fail = (e) => options.onError?.(String(e?.message ?? e));
+        let handoff = initial;
+        let live = null;
+        let clip = null;
+        let polled = null;
+        let active = true;
+        let checking = false;
+        let stream = null;
+        /** The selector the stream was opened for — what actually identifies the view. */
+        let watching = null;
+        let frames = 0;
+        let fallbackTimer = null;
+        let checkTimer = null;
+        let element = null;
+        let dragging = false;
+        let lastMove = 0;
+        const compute = () => {
+            const streaming = !!live;
+            const from = streaming ? clip : polled;
+            const origin = from?.origin ?? { x: 0, y: 0 };
+            const width = from?.width ?? 0;
+            const height = from?.height ?? 0;
+            const clipped = !!from?.clipped;
+            // The screencast is scaled to Chrome's own maxWidth, so image pixels and page
+            // pixels are NOT the same unit. Cropping without the page width puts the region
+            // in the wrong place and every click with it.
+            const pageWidth = live?.device_width ?? 0;
+            const cropping = streaming && clipped && width > 0 && height > 0 && pageWidth > 0;
+            // Every key the SDK owns is always present, "" where it does not apply — so a view
+            // that stops cropping clears the offsets instead of leaving the last ones behind.
+            const style = cropping
+                ? {
+                    image: {
+                        // Blow the full-viewport frame up until the region fills the window, then
+                        // shift it so the region is what shows through. Percentages are of the
+                        // WINDOW's width — including the vertical one, which is how CSS margins
+                        // work and what makes this survive a resize.
+                        width: `${(pageWidth / width) * 100}%`,
+                        marginLeft: `${(-origin.x / width) * 100}%`,
+                        marginTop: `${(-origin.y / width) * 100}%`,
+                        maxWidth: "none",
+                    },
+                    window: {
+                        width: "100%",
+                        maxWidth: `${width}px`,
+                        aspectRatio: `${width} / ${height}`,
+                    },
+                }
+                : {
+                    image: { width: "auto", marginLeft: "", marginTop: "", maxWidth: "100%" },
+                    window: { width: "", maxWidth: "100%", aspectRatio: "" },
+                };
+            return {
+                active,
+                url: (streaming ? clip?.url : polled?.url) || polled?.url || handoff.url || "",
+                image: (streaming ? live?.image : polled?.image) || "",
+                live: streaming,
+                origin,
+                width,
+                height,
+                clipped,
+                cropping,
+                style,
+                interactive: handoff.interactive,
+                checking,
+                handoff,
+            };
+        };
+        let view = compute();
+        const paint = () => {
+            const el = element;
+            if (!el)
+                return;
+            if (view.image && el.src !== view.image)
+                el.src = view.image;
+            if (el.style)
+                Object.assign(el.style, view.style.image);
+            const parent = el.parentElement;
+            if (parent?.style)
+                Object.assign(parent.style, view.style.window);
+        };
+        const publish = () => {
+            view = compute();
+            paint();
+            options.onView?.(view);
+        };
+        const stopWatching = () => {
+            stream?.close();
+            stream = null;
+            watching = null;
+            if (fallbackTimer)
+                clearTimeout(fallbackTimer);
+            fallbackTimer = null;
+        };
+        /** Open the live view, or leave it alone if it is already showing this region.
+         *
+         *  Keyed on the selector, NOT on the hand-off object: the agent re-announces a
+         *  hand-off as it works and each announcement is a new object, so re-opening on
+         *  every one tore the picture down and put "waiting for the page" back up
+         *  mid-gesture. */
+        const watch = () => {
+            const selector = handoff.selector ?? "";
+            if (!active || (stream && watching === selector))
+                return;
+            stopWatching();
+            watching = selector;
+            frames = 0;
+            stream = api.browserStream(sessionId, {
+                onFrame: (f) => {
+                    if (!active)
+                        return;
+                    frames++;
+                    live = f;
+                    publish();
+                },
+                onClip: (c) => {
+                    if (!active)
+                        return;
+                    clip = c;
+                    publish();
+                },
+                // Reported, not swallowed: a hand-off whose frames never arrive shows an
+                // empty box and tells nobody why.
+                onError: (m) => options.onError?.(m),
+            }, selector);
+            // Nothing painted? Fetch one frame the slow way, so the user is not left looking
+            // at a spinner over a stream that may simply be quiet.
+            fallbackTimer = setTimeout(() => {
+                if (!active || frames)
+                    return;
+                api
+                    .browserFrame(sessionId, selector)
+                    .then((f) => {
+                    if (!active || frames)
+                        return;
+                    polled = f;
+                    publish();
+                })
+                    .catch(fail);
+            }, fallbackMs);
+        };
+        const finish = async () => {
+            if (!active)
+                return;
+            const resume = !!handoff.blocking;
+            active = false;
+            stopWatching();
+            if (checkTimer)
+                clearTimeout(checkTimer);
+            checkTimer = null;
+            publish();
+            options.onEnded?.({ resume });
+        };
+        const send = async (input) => {
+            if (!active)
+                return;
+            const body = {
+                ...input,
+                selector: handoff.selector,
+                // Echoed, never added to here: the server adds it, so a crop that moved between
+                // paint and click cannot displace the click.
+                origin: input.origin ?? view.origin,
+                // A drag is dozens of events a second; rendering a JPEG for each would cost more
+                // than the gesture and arrive after the stream had already shown it. With no
+                // stream the reply IS the feedback.
+                want_frame: input.want_frame ?? !live,
+            };
+            try {
+                const frame = await api.browserInput(sessionId, body);
+                if (body.want_frame && frame?.image) {
+                    polled = frame;
+                    publish();
+                }
+            }
+            catch (e) {
+                fail(e);
+            }
+        };
+        const settled = () => {
+            // Only a blocking hand-off has something to finish, and only when the agent gave
+            // a goal to judge against.
+            if (!active || !handoff.blocking || !handoff.auto_done || checkTimer)
+                return;
+            checkTimer = setTimeout(async () => {
+                checkTimer = null;
+                checking = true;
+                publish();
+                try {
+                    const result = await api.handoffCheck(sessionId);
+                    if (result.checked && result.done) {
+                        checking = false;
+                        await finish();
+                        return;
+                    }
+                }
+                catch (e) {
+                    // Never fatal: the Done button is the whole fallback.
+                    fail(e);
+                }
+                checking = false;
+                if (active)
+                    publish();
+            }, settleMs);
+        };
+        /** Where a pointer landed, in the image space the server expects.
+         *
+         *  The element is CSS-scaled to fit its box, so displayed pixels are converted back
+         *  to page pixels here. When cropping, the visible window is the parent box rather
+         *  than the (deliberately oversized) image. */
+        const point = (el, event) => {
+            const box = el.getBoundingClientRect();
+            if (!box.width || !box.height)
+                return null;
+            const shown = view.cropping
+                ? { w: view.width, h: view.height }
+                : {
+                    w: view.width || el.naturalWidth || box.width,
+                    h: view.height || el.naturalHeight || box.height,
+                };
+            const win = view.cropping ? (el.parentElement?.getBoundingClientRect() ?? box) : box;
+            if (!win.width || !win.height)
+                return null;
+            return {
+                x: Math.round((event.clientX - win.left) * (shown.w / win.width)),
+                y: Math.round((event.clientY - win.top) * (shown.h / win.height)),
+            };
+        };
+        const held = (event) => {
+            const out = [];
+            if (event.shiftKey)
+                out.push("Shift");
+            if (event.ctrlKey)
+                out.push("Control");
+            if (event.altKey)
+                out.push("Alt");
+            if (event.metaKey)
+                out.push("Meta");
+            return out;
+        };
+        const button = (event) => event.button === 2 ? "right" : event.button === 1 ? "middle" : "left";
+        const attach = (el) => {
+            element = el;
+            const onDown = (event) => {
+                // Read-only is enforced server-side too; this just avoids a pointless refusal.
+                if (!active || !view.interactive)
+                    return;
+                const p = point(el, event);
+                if (!p)
+                    return;
+                // Capture, so a drag that wanders off the image still ends properly. Without it
+                // the pointer stays down on the page and every later click compounds the mess.
+                el.setPointerCapture?.(event.pointerId);
+                dragging = true;
+                lastMove = 0;
+                void send({ type: "pointer_down", ...p, button: button(event), modifiers: held(event) });
+            };
+            const onMove = (event) => {
+                if (!active || !view.interactive || !dragging)
+                    return;
+                const now = Date.now();
+                if (now - lastMove < relayMs)
+                    return;
+                lastMove = now;
+                const p = point(el, event);
+                if (p)
+                    void send({ type: "pointer_move", ...p });
+            };
+            const onUp = (event) => {
+                if (!active || !view.interactive || !dragging)
+                    return;
+                dragging = false;
+                el.releasePointerCapture?.(event.pointerId);
+                const p = point(el, event);
+                if (p) {
+                    void send({ type: "pointer_up", ...p, button: button(event), modifiers: held(event) });
+                }
+                settled();
+            };
+            const onWheel = (event) => {
+                if (!active || !view.interactive)
+                    return;
+                // Over the element, not the window: a challenge in its own scrollable pane does
+                // not move when the document scrolls.
+                void send({
+                    type: "wheel",
+                    x: Math.round(view.width / 2),
+                    y: Math.round(view.height / 2),
+                    delta_x: Math.round(event.deltaX ?? 0),
+                    delta_y: Math.round(event.deltaY ?? 0),
+                });
+            };
+            const onContextMenu = (event) => event.preventDefault?.();
+            el.addEventListener("pointerdown", onDown);
+            el.addEventListener("pointermove", onMove);
+            el.addEventListener("pointerup", onUp);
+            el.addEventListener("pointercancel", onUp);
+            el.addEventListener("wheel", onWheel);
+            el.addEventListener("contextmenu", onContextMenu);
+            paint();
+            return () => {
+                el.removeEventListener("pointerdown", onDown);
+                el.removeEventListener("pointermove", onMove);
+                el.removeEventListener("pointerup", onUp);
+                el.removeEventListener("pointercancel", onUp);
+                el.removeEventListener("wheel", onWheel);
+                el.removeEventListener("contextmenu", onContextMenu);
+                dragging = false;
+                if (element === el)
+                    element = null;
+            };
+        };
+        watch();
+        return {
+            get view() {
+                return view;
+            },
+            attach,
+            update: (next) => {
+                handoff = next;
+                if (!next.active) {
+                    void finish();
+                    return;
+                }
+                watch();
+                publish();
+            },
+            send,
+            type: async (text, opts = {}) => {
+                if (text)
+                    await send({ type: "type", text });
+                if (opts.submit !== false)
+                    await send({ type: "key", key: "Enter" });
+            },
+            key: (key, modifiers) => send({ type: "key", key, modifiers }),
+            scroll: (pixels) => send({ type: "scroll", pixels }),
+            settled,
+            done: finish,
+            close: () => {
+                active = false;
+                stopWatching();
+                if (checkTimer)
+                    clearTimeout(checkTimer);
+                checkTimer = null;
+            },
+        };
+    }
+    static EXPIRY_MARGIN_S = 60;
+    /** 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. */
+    tokenLifeLeft(token) {
+        if (!token)
+            return null;
+        try {
+            const [, payload] = token.split(".");
+            if (!payload)
+                return null;
+            const json = payload.replace(/-/g, "+").replace(/_/g, "/");
+            // Whichever base64 the runtime has. Neither is guaranteed — this SDK runs in a
+            // browser, in Node and in a worker — and having neither just means no proactive
+            // refresh, which leaves the 401 path doing what it always did.
+            const g = globalThis;
+            const decoded = typeof g.atob === "function"
+                ? g.atob(json)
+                : g.Buffer
+                    ? g.Buffer.from(json, "base64").toString("utf8")
+                    : null;
+            if (!decoded)
+                return null;
+            const claims = JSON.parse(decoded);
+            const exp = Number(claims?.exp);
+            if (!Number.isFinite(exp))
+                return null;
+            return exp - Math.floor(Date.now() / 1000);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The bearer for the next request. */
+    async resolveToken() {
+        if (!this.opts.getToken)
+            return this.currentToken;
+        const token = await this.opts.getToken({ expired: false });
+        // About to lapse: ask for a replacement now rather than after the server refuses it.
+        const left = this.tokenLifeLeft(token || this.currentToken);
+        if (this.proactive && left !== null && left < AgentFramework.EXPIRY_MARGIN_S) {
+            const fresh = await this.refreshToken();
+            // If refreshing didn't buy any life — a project whose whole TTL is shorter than
+            // the margin, or a token endpoint that is down — stop doing this. Minting once per
+            // request is a far worse failure than the expiry it was avoiding, and every
+            // request is already replayed on a real 401, so this path is only ever an
+            // optimisation to give up on.
+            if (fresh === undefined || (this.tokenLifeLeft(fresh) ?? 0) < AgentFramework.EXPIRY_MARGIN_S) {
+                this.proactive = false;
+            }
+            if (fresh)
+                return fresh;
+        }
+        if (!token)
+            return this.currentToken;
+        // If the app handed back the exact token the server just rejected — the common
+        // shape, `getToken: () => myCache.token`, where the cache didn't learn about our
+        // refresh — use the fresher one we already hold instead of 401-ing every request.
+        if (token === this.rejectedToken && this.currentToken && this.currentToken !== token) {
+            return this.currentToken;
+        }
+        this.currentToken = token;
+        return token;
+    }
+    /** Whether pre-expiry refreshing is still worth attempting; see `resolveToken`. */
+    proactive = true;
+    /** 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. */
+    async refreshToken() {
+        const get = this.opts.getToken;
+        if (!get)
+            return undefined;
+        this.rejectedToken = this.currentToken;
+        if (!this.refreshing) {
+            this.refreshing = (async () => {
+                try {
+                    const fresh = await get({ expired: true });
+                    if (!fresh)
+                        return undefined;
+                    this.currentToken = fresh;
+                    return fresh;
+                }
+                catch {
+                    // A failing token endpoint must not mask the auth error: surface the 401.
+                    return undefined;
+                }
+                finally {
+                    this.refreshing = undefined;
+                }
+            })();
+        }
+        return this.refreshing;
+    }
+    /** Register a client-side tool (handler run when the agent calls it). */
+    registerTool(tool) {
+        this.toolRegistry.set(tool.name, tool);
+        return this;
+    }
+    registerTools(tools) {
+        for (const t of tools)
+            this.toolRegistry.set(t.name, t);
+        return this;
+    }
+    /** Merge the client-level registry with any per-call tools (per-call wins). */
+    resolveTools(extra) {
+        const m = new Map(this.toolRegistry);
+        for (const t of extra ?? [])
+            m.set(t.name, t);
+        return m;
+    }
+    // -- auth headers --------------------------------------------------------
+    /** `bearer` overrides token resolution — used to replay a request with the token a
+     *  refresh just produced, instead of asking for one again. */
+    async authHeaders(bearer) {
+        const h = { ...(this.opts.headers ?? {}) };
+        const token = bearer ?? (await this.resolveToken());
+        if (token)
+            h["Authorization"] = `Bearer ${token}`;
+        else if (this.opts.apiKey)
+            h["X-API-Key"] = this.opts.apiKey;
+        return h;
+    }
+    // -- low-level request ---------------------------------------------------
+    /** Like `request`, but hands back the raw Response (for binary payloads). */
+    async raw(method, path, init = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(init.query ?? {})) {
+            if (v !== undefined && v !== null)
+                url.searchParams.set(k, String(v));
+        }
+        const send = async (bearer) => {
+            const headers = { ...(await this.authHeaders(bearer)), ...(init.headers ?? {}) };
+            let body;
+            if (init.form !== undefined) {
+                // Let fetch set Content-Type so the multipart boundary is correct.
+                body = init.form;
+            }
+            else if (init.body !== undefined) {
+                headers["Content-Type"] = "application/json";
+                body = JSON.stringify(init.body);
+            }
+            return this._fetch(url.toString(), { method, headers, body, signal: init.signal });
+        };
+        let res = await send();
+        // Token expired mid-session: get a fresh one and replay the request once, so the
+        // expiry is invisible to the caller.
+        //
+        // Uploads are replayed too. They used to be excluded on the theory that a body
+        // might already be consumed, but a `FormData` is not a consumed stream — fetch
+        // serialises it into a fresh multipart body per call, in the browser and in Node
+        // alike. Excluding it meant an upload was the one request an expiry could kill
+        // outright, and an upload is the request a user is least willing to repeat.
+        if (res.status === 401) {
+            const fresh = await this.refreshToken();
+            if (fresh)
+                res = await send(fresh);
+        }
+        if (!res.ok) {
+            let detail = await res.text();
+            try {
+                detail = JSON.parse(detail);
+                if (detail && typeof detail === "object" && "detail" in detail)
+                    detail = detail.detail;
+            }
+            catch {
+                /* leave as text */
+            }
+            throw new AgentApiError(res.status, detail);
+        }
+        return res;
+    }
+    async request(method, path, init = {}) {
+        const res = await this.raw(method, path, init);
+        if (res.status === 204)
+            return undefined;
+        const ct = res.headers.get("content-type") ?? "";
+        return (ct.includes("application/json") ? await res.json() : await res.text());
+    }
+    // -- auth ----------------------------------------------------------------
+    /**
+     * 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 = {}) => this.request("POST", "/auth/token", { body }),
+    };
+    // -- tenants (operator admin; require adminKey / X-Admin-Key) -------------
+    adminHeaders() {
+        if (!this.opts.adminKey)
+            throw new Error("adminKey is required for tenant-management calls");
+        return { "X-Admin-Key": this.opts.adminKey };
+    }
+    tenants = {
+        // api_key is returned ONLY here, once.
+        create: (body) => this.request("POST", "/tenants", { body, headers: this.adminHeaders() }),
+        list: () => this.request("GET", "/tenants", { headers: this.adminHeaders() }),
+        /** 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, settings) => this.request("PATCH", `/tenants/${id}`, { body: { settings }, headers: this.adminHeaders() }),
+    };
+    /** 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: () => this.request("GET", "/health"),
+        ready: () => this.request("GET", "/ready"),
+    };
+    // -- tools ---------------------------------------------------------------
+    tools = {
+        list: () => this.request("GET", "/tools"),
+    };
+    // -- chat ----------------------------------------------------------------
+    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) => this.request("POST", "/chat", { body }),
+        /** 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 = {}) => this.runWithTools(opts),
+        /** 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, handlers = {}) => {
+            const handle = this.startStreamWithTools(body, handlers);
+            // A watcher on this session must not re-deliver what we just streamed
+            // ourselves, so mark this turn's messages seen before the next poll.
+            handle.done
+                .then((d) => this.resyncWatchers(d.session_id))
+                .catch(() => { }); // stream errors surface through the handle, not here
+            return handle;
+        },
+        /** 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: async (runId, message) => {
+            try {
+                await this.request("POST", `/chat/stream/${runId}/steer`, { body: { message } });
+                return true;
+            }
+            catch (e) {
+                if (e instanceof AgentApiError && (e.status === 409 || e.status === 404))
+                    return false;
+                throw e;
+            }
+        },
+        /** 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) => this.request("POST", "/chat", { body: { session_id: sessionId, handoff_done: true } }),
+        answer: (sessionId, ...answers) => this.request("POST", "/chat", {
+            body: { session_id: sessionId, question_answers: answers },
+        }),
+        sessions: {
+            list: (userRef) => this.request("GET", "/chat/sessions", { query: { user_ref: userRef } }),
+            /** 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) => this.request("GET", `/chat/sessions/${sessionId}/todos`),
+            /** 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, selector = "") => this.request("POST", `/chat/sessions/${sessionId}/browser/frame`, { body: { selector } }),
+            /** 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, handlers, selector = "") => {
+                const controller = new AbortController();
+                void (async () => {
+                    try {
+                        const url = new URL(`${this.baseUrl}/chat/sessions/${sessionId}/browser/stream`);
+                        if (selector)
+                            url.searchParams.set("selector", selector);
+                        const open = async (bearer) => {
+                            const headers = await this.authHeaders(bearer);
+                            headers["Accept"] = "text/event-stream";
+                            return this._fetch(url.toString(), {
+                                method: "GET",
+                                headers,
+                                signal: controller.signal,
+                            });
+                        };
+                        let res = await open();
+                        if (res.status === 401) {
+                            // A hand-off can sit open longer than a token lives — the whole point is
+                            // that it waits for a person. Expiring mid-gesture must not end the view.
+                            const fresh = await this.refreshToken();
+                            if (fresh)
+                                res = await open(fresh);
+                        }
+                        if (!res.ok)
+                            throw new AgentApiError(res.status, await res.text());
+                        if (!res.body)
+                            throw new AgentStreamError("browser stream returned no body");
+                        for await (const ev of parseSSE(res.body, controller.signal)) {
+                            if (ev.event === "frame")
+                                handlers.onFrame(JSON.parse(ev.data));
+                            else if (ev.event === "clip")
+                                handlers.onClip?.(JSON.parse(ev.data));
+                            else if (ev.event === "error") {
+                                handlers.onError?.(JSON.parse(ev.data)?.detail ?? "browser stream failed");
+                            }
+                        }
+                    }
+                    catch (e) {
+                        // An abort is the caller closing the viewer, not a failure to report.
+                        if (e?.name === "AbortError")
+                            return;
+                        handlers.onError?.(String(e?.message ?? e));
+                    }
+                })();
+                return { close: () => controller.abort() };
+            },
+            /** 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) => this.request("POST", `/chat/sessions/${sessionId}/browser/check`),
+            /** 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, input) => this.request("POST", `/chat/sessions/${sessionId}/browser/input`, { body: input }),
+            /** 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, handoff, options = {}) => this.buildHandoff(sessionId, handoff, options),
+            /** 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, count = 3) => this.request("POST", `/chat/sessions/${sessionId}/followups`, { body: { count } }),
+            /** 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) => this.request("POST", `/chat/sessions/${sessionId}/recap`),
+            messages: (sessionId) => this.request("GET", `/chat/sessions/${sessionId}/messages`),
+            delete: (sessionId) => this.request("DELETE", `/chat/sessions/${sessionId}`),
+            /**
+             * 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, handlers) => this.watchSession(sessionId, handlers),
+            /** Branch a conversation: create a new chat by copying `sessionId` up to and
+             *  including `upToMessageId` (or the whole chat if omitted). */
+            fork: (sessionId, opts = {}) => this.request("POST", `/chat/sessions/${sessionId}/fork`, {
+                body: { up_to_message_id: opts.upToMessageId ?? null, title: opts.title },
+            }),
+        },
+    };
+    // -- documents -----------------------------------------------------------
+    documents = {
+        list: (query = {}) => this.request("GET", "/documents", { query }),
+        get: (id) => this.request("GET", `/documents/${id}`),
+        delete: (id) => this.request("DELETE", `/documents/${id}`),
+        retrieve: (body) => this.request("POST", "/documents/retrieve", { body }),
+        /** Small-file convenience upload via multipart form (server proxies to S3). */
+        uploadSimple: async (file, opts) => {
+            const form = new FormData();
+            const blob = typeof Blob !== "undefined" && file instanceof Blob
+                ? file
+                : new Blob([file], { type: opts.contentType ?? "application/octet-stream" });
+            form.append("file", blob, opts.filename);
+            form.append("tags", (opts.tags ?? []).join(","));
+            // Set visibility AT UPLOAD, not after: a document is retrievable as soon as
+            // ingestion finishes, so patching later leaves a window where it's readable by
+            // more people than intended.
+            if (opts.visibility)
+                form.append("visibility", opts.visibility);
+            if (opts.visibility_scope)
+                form.append("visibility_scope", opts.visibility_scope);
+            if (opts.acl_roles?.length)
+                form.append("acl_roles", opts.acl_roles.join(","));
+            if (opts.acl_groups?.length)
+                form.append("acl_groups", opts.acl_groups.join(","));
+            const send = async (bearer) => this._fetch(this.baseUrl + "/documents", {
+                method: "POST",
+                headers: await this.authHeaders(bearer),
+                body: form,
+                signal: opts.signal,
+            });
+            let res = await send();
+            // Same replay as `request`: an upload is often the longest-lived request a page
+            // makes, and losing a whole file to a token that lapsed while it was in flight is
+            // the worst possible time to surface an expiry.
+            if (res.status === 401) {
+                const fresh = await this.refreshToken();
+                if (fresh)
+                    res = await send(fresh);
+            }
+            if (!res.ok)
+                throw new AgentApiError(res.status, await res.text());
+            return (await res.json());
+        },
+        /** Resumable presigned multipart upload (direct to S3). */
+        upload: (file, opts) => this.multipartUpload(file, opts),
+        /** 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: async (id, opts = {}) => {
+            const timeout = opts.timeoutMs ?? 120_000;
+            const interval = opts.intervalMs ?? 1500;
+            const deadline = Date.now() + timeout;
+            for (;;) {
+                const doc = await this.request("GET", `/documents/${id}`, { signal: opts.signal });
+                if (doc.status === "ready")
+                    return doc;
+                if (doc.status === "failed")
+                    throw new AgentApiError(422, `ingestion failed: ${doc.error ?? "unknown"}`);
+                if (Date.now() > deadline)
+                    throw new AgentApiError(408, `ingestion timed out after ${timeout}ms (status=${doc.status})`);
+                await sleep(interval);
+            }
+        },
+        /** Upload a small file AND wait for it to finish ingesting — the common case. */
+        uploadAndWait: async (file, 
+        // Takes the ACL fields too: this is the upload most callers use, so omitting them
+        // here forced a second `patch` and left a window where the document was already
+        // retrievable at its default visibility.
+        opts) => {
+            const doc = await this.documents.uploadSimple(file, opts);
+            return this.documents.waitReady(doc.id, { timeoutMs: opts.timeoutMs, signal: opts.signal });
+        },
+        /** Get a presigned GET URL for the raw file. */
+        downloadUrl: (id) => this.request("GET", `/documents/${id}/download-url`),
+        /** Resumable ranged download; returns a Blob. */
+        download: (id, opts = {}) => this.rangedDownload(id, opts),
+        /** Update a document's tags / visibility / ACL. */
+        patch: (id, body) => this.request("PATCH", `/documents/${id}`, { body }),
+        /** Reprocess a document (retry a failed ingest, or re-embed with a new model). */
+        reingest: (id) => this.request("POST", `/documents/${id}/reingest`),
+        /** Inspect the stored chunks of a document (text + page + index). */
+        chunks: (id) => this.request("GET", `/documents/${id}/chunks`),
+    };
+    // -- tasks ---------------------------------------------------------------
+    tasks = {
+        create: (body) => this.request("POST", "/tasks", { body }),
+        list: (status) => this.request("GET", "/tasks", { query: { status } }),
+        get: (id) => this.request("GET", `/tasks/${id}`),
+        cancel: (id) => this.request("POST", `/tasks/${id}/cancel`),
+    };
+    // -- knowledge sources (ai.sync data connectors) -------------------------
+    sources = {
+        list: () => this.request("GET", "/sources"),
+        get: (id) => this.request("GET", `/sources/${id}`),
+        types: () => this.request("GET", "/sources/types"),
+        /** 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, body) => this.request("PATCH", `/sources/${id}`, { body }),
+        /** Trigger a sync now; pass `fullRefresh` to re-pull everything. */
+        sync: (id, fullRefresh = false) => this.request("POST", `/sources/${id}/sync`, { query: { full_refresh: fullRefresh } }),
+        remove: (id) => this.request("DELETE", `/sources/${id}`),
+    };
+    // -- governance: audit trail + right-to-be-forgotten (admin) -------------
+    audit = {
+        /** Read the tenant's audit trail (admin). Filter by action/subject. */
+        list: (opts = {}) => this.request("GET", "/audit", { query: opts }),
+        /** Purge a subject's documents, sessions, and vectors (GDPR erasure; admin). */
+        forget: (subject) => this.request("POST", "/audit/forget", { body: { subject } }),
+    };
+    /**
+     * 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: () => this.request("GET", "/computers/host"),
+        /** Start a sandbox. Bind it to a chat session to give that conversation a
+         *  persistent workspace. */
+        create: (body = {}) => this.request("POST", "/computers/sessions", { body }),
+        list: (opts = {}) => this.request("GET", "/computers/sessions", { query: opts }),
+        get: (id) => this.request("GET", `/computers/sessions/${id}`),
+        /** Put it to sleep now rather than waiting for it to go idle; the workspace is
+         *  preserved either way. */
+        pause: (id) => this.request("POST", `/computers/sessions/${id}/pause`),
+        /** Wake a sleeping sandbox and reattach to its workspace. */
+        resume: (id) => this.request("POST", `/computers/sessions/${id}/resume`),
+        destroy: (id) => this.request("DELETE", `/computers/sessions/${id}`),
+        /** 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, body) => this.request("POST", `/computers/sessions/${id}/exec`, { body }),
+        /** Push a file (any type) into the sandbox. */
+        upload: async (id, file, dest) => {
+            const form = new FormData();
+            form.append("file", file, file.name ?? "upload.bin");
+            if (dest)
+                form.append("dest", dest);
+            return this.request("POST", `/computers/sessions/${id}/files`, { form });
+        },
+        /** Pull a file out of the sandbox as bytes. */
+        download: async (id, path) => {
+            const res = await this.raw("GET", `/computers/sessions/${id}/files`, { query: { path } });
+            return res.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) => this.request("POST", "/sources", { body: config });
+    // ==========================================================================
+    // Automatic client-tool dispatch
+    // ==========================================================================
+    async runWithTools(opts) {
+        const { tools: extra, maxToolRounds, onToolCalls, onQuestion, ...body } = opts;
+        const tools = this.resolveTools(extra);
+        const schemas = tools.size ? toolSchemas(tools) : undefined;
+        const maxRounds = maxToolRounds ?? 10;
+        let resp = await this.request("POST", "/chat", {
+            body: { ...body, client_tools: schemas },
+            signal: opts.signal,
+        });
+        let rounds = 0;
+        // Two ways a turn pauses: work for the client to run, or a question for the user
+        // to answer. Both resume the same way, and the round budget covers both together
+        // so a pathological alternation can't loop forever.
+        for (;;) {
+            const hasTools = resp.requires_action && resp.tool_calls.length > 0;
+            const hasQuestions = onQuestion != null && (resp.questions?.length ?? 0) > 0;
+            if (!hasTools && !hasQuestions)
+                return resp;
+            if (rounds++ >= maxRounds)
+                throw new AgentStreamError(`agent pause loop exceeded maxToolRounds (${maxRounds})`);
+            const next = { session_id: resp.session_id, client_tools: schemas };
+            if (hasTools) {
+                onToolCalls?.(resp.tool_calls);
+                next.tool_results = await executeToolCalls(resp.tool_calls, tools);
+            }
+            if (hasQuestions)
+                next.question_answers = await collectAnswers(resp.questions, onQuestion);
+            resp = await this.request("POST", "/chat", { body: next, signal: opts.signal });
+        }
+    }
+    /** Wrap startStream so a `done` carrying `requires_action` auto-executes the
+     *  client tools and continues the stream (same session) until the agent ends. */
+    startStreamWithTools(body, handlers) {
+        const tools = this.resolveTools(handlers.tools);
+        const onQuestion = handlers.onQuestion;
+        if (tools.size === 0 && onQuestion == null)
+            return this.startStream(body, handlers);
+        const schemas = tools.size ? toolSchemas(tools) : undefined;
+        const maxRounds = handlers.maxToolRounds ?? 10;
+        let current;
+        let stopped = false;
+        const done = (async () => {
+            let reqBody = { ...body, client_tools: schemas };
+            let rounds = 0;
+            for (;;) {
+                current = this.startStream(reqBody, handlers);
+                const d = await current.done;
+                const hasTools = d.requires_action && d.tool_calls.length > 0;
+                const hasQuestions = onQuestion != null && (d.questions?.length ?? 0) > 0;
+                if (!hasTools && !hasQuestions)
+                    return d;
+                if (stopped)
+                    return d;
+                if (rounds++ >= maxRounds)
+                    throw new AgentStreamError(`agent pause loop exceeded maxToolRounds (${maxRounds})`);
+                reqBody = { session_id: d.session_id, client_tools: schemas };
+                if (hasTools) {
+                    handlers.onToolCalls?.(d.tool_calls);
+                    reqBody.tool_results = await executeToolCalls(d.tool_calls, tools);
+                }
+                if (hasQuestions)
+                    reqBody.question_answers = await collectAnswers(d.questions, onQuestion);
+            }
+        })();
+        return makeStreamHandle(done, {
+            disconnect: () => { stopped = true; current?.disconnect(); },
+            cancel: async () => { stopped = true; await current?.cancel(); },
+            runId: () => current?.runId(),
+            steer: (m) => current?.steer(m) ?? Promise.resolve(false),
+        });
+    }
+    async resyncWatchers(sessionId) {
+        await Promise.all([...this.watchers].filter((w) => w.sessionId === sessionId).map((w) => w.resync()));
+    }
+    watchSession(sessionId, handlers) {
+        const seen = new Set();
+        let primed = false;
+        let stopped = false;
+        /** Read the session and emit whatever has not been delivered yet. */
+        const collect = async (emit) => {
+            const messages = await this.chat.sessions.messages(sessionId);
+            const fresh = messages.filter((m) => !seen.has(m.id));
+            for (const m of fresh)
+                seen.add(m.id);
+            if (emit)
+                for (const m of fresh)
+                    handlers.onMessage(m);
+        };
+        const entry = { sessionId, resync: () => collect(false) };
+        this.watchers.add(entry);
+        const controller = new AbortController();
+        let poller;
+        const stop = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            if (poller)
+                clearInterval(poller);
+            controller.abort();
+            this.watchers.delete(entry);
+        };
+        handlers.signal?.addEventListener("abort", stop, { once: true });
+        /** Fallback: ask periodically. Works against any deployment. */
+        const startPolling = () => {
+            if (stopped || poller)
+                return;
+            handlers.onTransport?.("poll");
+            const tick = async () => {
+                if (stopped)
+                    return;
+                try {
+                    await collect(primed);
+                    primed = true;
+                }
+                catch (e) {
+                    handlers.onError?.(e);
+                }
+            };
+            poller = setInterval(tick, handlers.intervalMs ?? 4000);
+            void tick();
+        };
+        /**
+         * Preferred: subscribe to the session's event stream, so a message appears the
+         * moment it is committed. Deployments without the endpoint fall back to polling,
+         * which is why this stays an implementation detail of `watch`.
+         */
+        const startStreaming = async () => {
+            let lastId;
+            try {
+                // Snapshot first, so history is never replayed as new.
+                await collect(false);
+                primed = true;
+            }
+            catch {
+                /* the stream itself will surface a real failure */
+            }
+            for (let attempt = 0; !stopped; attempt++) {
+                try {
+                    const url = new URL(`${this.baseUrl}/chat/sessions/${sessionId}/events`);
+                    if (lastId)
+                        url.searchParams.set("after", lastId);
+                    const headers = await this.authHeaders();
+                    headers["Accept"] = "text/event-stream";
+                    const res = await this._fetch(url.toString(), {
+                        method: "GET",
+                        headers,
+                        signal: controller.signal,
+                    });
+                    if (res.status === 404 || res.status === 405)
+                        return startPolling(); // older deployment
+                    if (!res.ok || !res.body)
+                        throw new AgentStreamError(`session events: HTTP ${res.status}`);
+                    handlers.onTransport?.("stream");
+                    attempt = 0;
+                    for await (const frame of parseSSE(res.body, controller.signal)) {
+                        if (stopped)
+                            return;
+                        if (frame.event !== "message" || !frame.data)
+                            continue;
+                        let message;
+                        try {
+                            message = JSON.parse(frame.data);
+                        }
+                        catch {
+                            continue; // a keepalive or a frame we don't understand
+                        }
+                        if (seen.has(message.id))
+                            continue;
+                        seen.add(message.id);
+                        lastId = message.id;
+                        handlers.onMessage(message);
+                    }
+                    if (stopped)
+                        return;
+                }
+                catch (e) {
+                    if (stopped || controller.signal.aborted)
+                        return;
+                    handlers.onError?.(e);
+                    // A dropped connection is normal; back off, then resume after `lastId`.
+                    await sleep(Math.min(1000 * 2 ** Math.min(attempt, 4), 15_000));
+                }
+            }
+        };
+        if (handlers.poll)
+            startPolling();
+        else
+            void startStreaming();
+        return { stop, resync: entry.resync };
+    }
+    // ==========================================================================
+    // Streaming with reconnect
+    // ==========================================================================
+    startStream(body, handlers) {
+        const ac = new AbortController();
+        const onOuterAbort = () => ac.abort();
+        handlers.signal?.addEventListener("abort", onOuterAbort);
+        const maxRetries = handlers.maxRetries ?? 10;
+        let runId;
+        let lastId = -1;
+        let full = "";
+        let reasoning = "";
+        // Merged by ref, because the wire carries one subagent per move and a UI wants the
+        // whole set. Doing it here rather than in every client is the difference between a
+        // panel that survives a dropped frame and one that quietly goes stale.
+        const subagents = new Map();
+        const openConnection = async (bearer) => {
+            const headers = await this.authHeaders(bearer);
+            headers["Accept"] = "text/event-stream";
+            if (runId === undefined) {
+                headers["Content-Type"] = "application/json";
+                return this._fetch(this.baseUrl + "/chat/stream", {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(body),
+                    signal: ac.signal,
+                });
+            }
+            const url = new URL(`${this.baseUrl}/chat/stream/${runId}`);
+            url.searchParams.set("last_event_id", String(lastId));
+            return this._fetch(url.toString(), { method: "GET", headers, signal: ac.signal });
+        };
+        const done = (async () => {
+            let attempt = 0; // reset to 0 whenever a frame is received (see below)
+            let refreshed = false; // one token refresh per connection, reset on progress
+            for (;;) {
+                if (ac.signal.aborted)
+                    throw new DOMException("aborted", "AbortError");
+                let shouldRetry = false;
+                try {
+                    let res = await openConnection();
+                    if (res.status === 401 && !refreshed) {
+                        // The token expired — on a resume this re-attaches to the SAME run, so
+                        // generation already in flight is picked up rather than restarted.
+                        const fresh = await this.refreshToken();
+                        if (fresh) {
+                            refreshed = true;
+                            res = await openConnection(fresh);
+                        }
+                    }
+                    if (!res.ok) {
+                        // POST failed, or 404 on resume (run expired) — terminal, no retry.
+                        throw new AgentApiError(res.status, await res.text());
+                    }
+                    runId = res.headers.get("X-Run-Id") ?? runId;
+                    if (!res.body)
+                        throw new Error("response has no body"); // retryable
+                    for await (const frame of parseSSE(res.body, ac.signal)) {
+                        attempt = 0; // progress: a successful (re)connection resets the budget
+                        refreshed = false; // ...and re-arms the refresh, for streams outliving a TTL
+                        if (frame.id !== undefined)
+                            lastId = frame.id;
+                        const ev = { event: frame.event, data: safeJson(frame.data) };
+                        handlers.onEvent?.(ev);
+                        switch (ev.event) {
+                            case "run":
+                                runId = ev.data.run_id;
+                                break;
+                            case "token":
+                                full += ev.data.delta;
+                                handlers.onToken?.(ev.data.delta, full);
+                                break;
+                            case "tool_start":
+                                handlers.onToolStart?.(ev.data.name, ev.data.input);
+                                break;
+                            case "tool_end":
+                                handlers.onToolEnd?.(ev.data.name, ev.data.output);
+                                break;
+                            case "citations":
+                                handlers.onCitations?.(ev.data.citations);
+                                break;
+                            case "sources":
+                                handlers.onSources?.(ev.data.sources);
+                                break;
+                            case "guardrail":
+                                handlers.onGuardrail?.(ev.data.stage, ev.data.flags, ev.data.content);
+                                break;
+                            case "attachments":
+                                handlers.onAttachments?.(ev.data.attachments);
+                                break;
+                            case "todos":
+                                handlers.onTodos?.(ev.data.todos);
+                                break;
+                            case "subagent":
+                                subagents.set(ev.data.subagent.ref, ev.data.subagent);
+                                handlers.onSubagents?.([...subagents.values()]);
+                                break;
+                            case "subagents":
+                                // The authoritative list. It replaces rather than merges: a subagent
+                                // the server no longer reports is one this conversation does not have.
+                                subagents.clear();
+                                for (const a of ev.data.subagents)
+                                    subagents.set(a.ref, a);
+                                handlers.onSubagents?.([...subagents.values()]);
+                                break;
+                            case "command_output":
+                                handlers.onCommandOutput?.(ev.data);
+                                break;
+                            case "command_finished":
+                                handlers.onCommandFinished?.(ev.data);
+                                break;
+                            case "questions":
+                                handlers.onQuestions?.(ev.data.questions);
+                                break;
+                            case "browser_handoff":
+                                handlers.onBrowserHandoff?.(ev.data);
+                                break;
+                            case "context":
+                                handlers.onContext?.(ev.data);
+                                break;
+                            case "reasoning":
+                                reasoning += ev.data.delta;
+                                handlers.onReasoning?.(ev.data.delta, reasoning);
+                                break;
+                            case "done":
+                                return ev.data;
+                            case "cancelled":
+                                throw new AgentCancelledError(); // terminal
+                            case "error":
+                                throw new AgentStreamError("server: " + ev.data.detail); // terminal
+                        }
+                    }
+                    // Stream ended with no terminal event => dropped connection.
+                    shouldRetry = true;
+                }
+                catch (err) {
+                    if (ac.signal.aborted)
+                        throw new DOMException("aborted", "AbortError");
+                    // Terminal errors: server 'error'/'cancelled' event, or an HTTP failure.
+                    if (err instanceof AgentApiError ||
+                        err instanceof AgentCancelledError ||
+                        (err instanceof AgentStreamError && err.message.startsWith("server:"))) {
+                        throw err;
+                    }
+                    shouldRetry = true; // network/read error
+                }
+                // Single retry site — increments once per failed attempt, resumes if possible.
+                if (shouldRetry) {
+                    attempt += 1;
+                    if (attempt > maxRetries || runId === undefined)
+                        throw new AgentStreamError("stream ended before completion (retries exhausted)");
+                    handlers.onReconnect?.(attempt);
+                    await sleep(backoff(attempt));
+                }
+            }
+        })().finally(() => handlers.signal?.removeEventListener("abort", onOuterAbort));
+        const cancel = async () => {
+            const id = runId;
+            if (id) {
+                try {
+                    await this.request("POST", `/chat/stream/${id}/cancel`);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            ac.abort();
+        };
+        const steer = async (message) => {
+            if (!runId)
+                return false; // nothing to steer yet — the run has no id
+            try {
+                await this.request("POST", `/chat/stream/${runId}/steer`, { body: { message } });
+                return true;
+            }
+            catch (e) {
+                // 409 means the turn finished between the user typing and this landing. That
+                // is the caller's cue to send it as a normal message, so report it rather
+                // than throwing — a lost message is worse than a false.
+                if (e instanceof AgentApiError && (e.status === 409 || e.status === 404))
+                    return false;
+                throw e;
+            }
+        };
+        return makeStreamHandle(done, {
+            disconnect: () => ac.abort(), cancel, runId: () => runId, steer,
+        });
+    }
+    // ==========================================================================
+    // Resumable multipart upload
+    // ==========================================================================
+    async multipartUpload(file, opts) {
+        const { size, slice } = toUint8(file);
+        const concurrency = opts.concurrency ?? 4;
+        const maxRetries = opts.maxRetries ?? 5;
+        const presign = await this.request("POST", "/documents/presign-upload", {
+            body: {
+                filename: opts.filename,
+                content_type: opts.contentType,
+                tags: opts.tags ?? [],
+                ...(opts.visibility ? { visibility: opts.visibility } : {}),
+                ...(opts.visibility_scope ? { visibility_scope: opts.visibility_scope } : {}),
+                ...(opts.acl_roles ? { acl_roles: opts.acl_roles } : {}),
+                ...(opts.acl_groups ? { acl_groups: opts.acl_groups } : {}),
+            },
+            signal: opts.signal,
+        });
+        const partSize = presign.part_size;
+        const partCount = Math.max(1, Math.ceil(size / partSize));
+        const partNumbers = Array.from({ length: partCount }, (_, i) => i + 1);
+        try {
+            const { urls } = await this.request("POST", `/documents/${presign.document_id}/presign-parts`, { body: { upload_id: presign.upload_id, part_numbers: partNumbers }, signal: opts.signal });
+            const urlByPart = new Map(urls.map((u) => [u.part_number, u.url]));
+            const etags = new Array(partCount);
+            let sent = 0;
+            let cursor = 0;
+            const worker = async () => {
+                for (;;) {
+                    if (opts.signal?.aborted)
+                        throw new DOMException("aborted", "AbortError");
+                    const idx = cursor++;
+                    if (idx >= partCount)
+                        return;
+                    const partNumber = partNumbers[idx];
+                    const start = idx * partSize;
+                    const end = Math.min(start + partSize, size);
+                    const bodyPart = slice(start, end);
+                    const url = urlByPart.get(partNumber);
+                    let lastErr;
+                    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                        try {
+                            const res = await this._fetch(url, {
+                                method: "PUT",
+                                body: bodyPart,
+                                signal: opts.signal,
+                            });
+                            if (!res.ok)
+                                throw new AgentStreamError(`part ${partNumber} failed: HTTP ${res.status}`);
+                            const etag = res.headers.get("ETag") ?? res.headers.get("etag");
+                            if (!etag)
+                                throw new AgentStreamError(`part ${partNumber}: missing ETag (expose it via S3 CORS ExposeHeaders)`);
+                            etags[idx] = { part_number: partNumber, etag };
+                            sent += end - start;
+                            opts.onProgress?.(sent, size);
+                            lastErr = undefined;
+                            break;
+                        }
+                        catch (e) {
+                            if (opts.signal?.aborted)
+                                throw e;
+                            lastErr = e;
+                            if (attempt < maxRetries)
+                                await sleep(backoff(attempt));
+                        }
+                    }
+                    if (lastErr)
+                        throw lastErr;
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(concurrency, partCount) }, () => worker()));
+            return await this.request("POST", `/documents/${presign.document_id}/complete-upload`, {
+                body: {
+                    upload_id: presign.upload_id,
+                    parts: etags.map((e) => ({ part_number: e.part_number, etag: e.etag })),
+                },
+                signal: opts.signal,
+            });
+        }
+        catch (err) {
+            // Best-effort abort so we don't leak an incomplete multipart upload.
+            try {
+                await this.request("POST", `/documents/${presign.document_id}/abort-upload`, {
+                    body: { upload_id: presign.upload_id },
+                });
+            }
+            catch {
+                /* ignore */
+            }
+            throw err;
+        }
+    }
+    // ==========================================================================
+    // Resumable ranged download
+    // ==========================================================================
+    async rangedDownload(id, opts) {
+        const info = await this.documents.downloadUrl(id);
+        const chunkSize = opts.chunkSize ?? 8 * 1024 * 1024;
+        const maxRetries = opts.maxRetries ?? 5;
+        const type = info.content_type ?? "application/octet-stream";
+        let url = info.url; // refreshed if the presigned URL expires mid-download
+        const refreshUrl = async () => {
+            url = (await this.documents.downloadUrl(id)).url;
+        };
+        // Unknown size: single GET, retry whole on failure (no resume possible).
+        if (info.size == null) {
+            for (let attempt = 0;; attempt++) {
+                try {
+                    const res = await this._fetch(url, { signal: opts.signal });
+                    if (res.status === 401 || res.status === 403) {
+                        await refreshUrl();
+                        throw new AgentStreamError("presigned url expired; refreshed");
+                    }
+                    if (!res.ok)
+                        throw new AgentStreamError(`download failed: HTTP ${res.status}`);
+                    const buf = await res.arrayBuffer();
+                    opts.onProgress?.(buf.byteLength, null);
+                    return new Blob([buf], { type });
+                }
+                catch (e) {
+                    if (opts.signal?.aborted || attempt >= maxRetries)
+                        throw e;
+                    await sleep(backoff(attempt));
+                }
+            }
+        }
+        const total = info.size;
+        const parts = [];
+        let received = 0;
+        outer: while (received < total) {
+            const wantEnd = Math.min(received + chunkSize, total) - 1;
+            let lastErr;
+            let ok = false;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    const res = await this._fetch(url, {
+                        headers: { Range: `bytes=${received}-${wantEnd}` },
+                        signal: opts.signal,
+                    });
+                    if (res.status === 401 || res.status === 403) {
+                        await refreshUrl(); // presigned URL expired mid-download
+                        continue;
+                    }
+                    if (res.status === 200) {
+                        // Server ignored Range and sent the whole object. Only valid at the
+                        // very start; otherwise appending it would corrupt the output.
+                        if (received !== 0)
+                            throw new AgentStreamError("server ignored Range on a resumed download");
+                        const buf = new Uint8Array(await res.arrayBuffer());
+                        parts.push(buf);
+                        received = buf.byteLength;
+                        opts.onProgress?.(received, total);
+                        break outer;
+                    }
+                    if (res.status !== 206)
+                        throw new AgentStreamError(`range download failed: HTTP ${res.status}`);
+                    const buf = new Uint8Array(await res.arrayBuffer());
+                    if (buf.byteLength === 0)
+                        throw new AgentStreamError("empty range response");
+                    const take = Math.min(buf.byteLength, total - received); // never overshoot
+                    parts.push(take === buf.byteLength ? buf : buf.subarray(0, take));
+                    received += take;
+                    opts.onProgress?.(received, total);
+                    ok = true;
+                    break;
+                }
+                catch (e) {
+                    if (opts.signal?.aborted)
+                        throw e;
+                    lastErr = e;
+                    if (attempt < maxRetries)
+                        await sleep(backoff(attempt));
+                }
+            }
+            if (!ok)
+                throw lastErr;
+        }
+        return new Blob(parts, { type });
+    }
+}
+function safeJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+/** Factory helper. */
+export function createClient(opts) {
+    return new AgentFramework(opts);
+}
+export default AgentFramework;
+//# sourceMappingURL=index.js.map