@oberik/sdk 0.53.1 → 0.55.0

package/dist/cjs/index.js

@@ -426,13 +426,28 @@ class AgentApiError extends Error {
      *  an intermediary, which is replaced by the same summary as `message`. Keeping four
      *  kilobytes of someone else's markup here helped nobody and buried the status. */
     detail;
-    constructor(status, detail) {
+    /** The run that failed, when the server said which.
+     *
+     *  A failed `chat.send` used to carry neither this nor {@link sessionId}, so the reason
+     *  the server stores for the turn — the only durable answer to "why did this fail" —
+     *  could not be looked up by the person who hit it. `chat.stream` had both all along;
+     *  this is the same handle on the blocking path (OBE-142). */
+    runId;
+    /** The conversation the failed turn belongs to, when the server said which.
+     *
+     *  Present even when the turn failed before producing anything: the session exists from
+     *  the moment the turn is prepared, and whatever it wrote is readable with
+     *  `ai.chat.sessions.messages(err.sessionId)`. */
+    sessionId;
+    constructor(status, detail, ids) {
         const described = describeDetail(status, detail);
         super(described);
         this.name = "AgentApiError";
         this.status = status;
         this.detail =
             typeof detail === "string" && looksLikeHtml(detail) ? described : detail;
+        this.runId = ids?.runId;
+        this.sessionId = ids?.sessionId;
     }
 }
 exports.AgentApiError = AgentApiError;
@@ -874,6 +889,7 @@ class AgentFramework {
         let element = null;
         let dragging = false;
         let lastMove = 0;
+        let focused = false;
         const compute = () => {
             const streaming = !!live;
             const from = streaming ? clip : polled;
@@ -923,6 +939,7 @@ class AgentFramework {
                 style,
                 interactive: handoff.interactive,
                 checking,
+                focused,
                 autoDone,
                 handoff,
             };
@@ -1105,6 +1122,14 @@ class AgentFramework {
             return out;
         };
         const button = (event) => event.button === 2 ? "right" : event.button === 1 ? "middle" : "left";
+        /** Keys that only ever modify another one. Relaying them alone presses nothing and
+         *  would burn a request per Shift. */
+        const MODIFIER_KEYS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock"]);
+        /** Ctrl/Cmd chords that mean something INSIDE a page and are worth taking over.
+         *  Select-all before retyping a field, and undo. Everything else a chord can do here
+         *  either belongs to the viewer's own browser or acts on a clipboard the person
+         *  cannot reach — see `onKeyDown`. */
+        const PAGE_CHORDS = new Set(["a", "z"]);
         const attach = (el) => {
             element = el;
             const onDown = (event) => {
@@ -1117,6 +1142,10 @@ class AgentFramework {
                 // 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);
+                // Pointing at the page is also how you start typing on it. Requiring a separate
+                // click-to-focus would be a step nobody is told about, and the symptom of missing
+                // it — keystrokes going nowhere — looks exactly like the bug this fixes.
+                el.focus?.();
                 dragging = true;
                 lastMove = 0;
                 void send({ type: "pointer_down", ...p, button: button(event), modifiers: held(event) });
@@ -1157,12 +1186,96 @@ class AgentFramework {
                 });
             };
             const onContextMenu = (event) => event.preventDefault?.();
+            /**
+             * A keystroke, relayed into the page.
+             *
+             * Pointer events were relayed from the first version of this and keys never were,
+             * so a hand-off could work a slider puzzle and could not fill in a login form —
+             * which is the other case the tool that opens a hand-off names in its own
+             * description. The only way to enter text was a separate box in the host UI that
+             * typed wherever focus happened to be, so nothing could Tab between fields, correct
+             * a typo, or submit a form.
+             *
+             * A printable character goes as `type` rather than `key`: a key press is a physical
+             * key and gets the wrong result for anything the person's own layout produces with a
+             * modifier — a Turkish `ı`, an accented character, anything behind AltGr. Text is
+             * what they meant, and text is what the page receives.
+             */
+            const onKeyDown = (event) => {
+                if (!active || !view.interactive)
+                    return;
+                const key = String(event.key ?? "");
+                // A modifier on its own carries nothing; it rides along with the next key.
+                if (!key || key === "Unidentified" || MODIFIER_KEYS.has(key))
+                    return;
+                const chord = !!(event.ctrlKey || event.metaKey);
+                const printable = key.length === 1 && !chord && !event.altKey;
+                // A chord that is not one of the two worth relaying stays with the VIEWER's
+                // browser — reload, new tab, devtools, the address bar. An allow-list rather
+                // than a block-list, so a combination nobody thought about keeps working where
+                // the person expects it instead of being swallowed by a picture.
+                //
+                // Only two are worth having, and the reason the rest are not is the clipboard:
+                // Ctrl-C and Ctrl-X inside the page copy to the REMOTE Chrome's clipboard, which
+                // the person cannot reach. Pasting INTO the page is the case that matters and it
+                // is handled properly below, from the real paste event.
+                if (chord && !PAGE_CHORDS.has(key.toLowerCase()))
+                    return;
+                // Taken over from here: relayed and not also acted on locally, or Tab moves the
+                // viewer's own focus away mid-form and Backspace navigates the host app back.
+                event.preventDefault?.();
+                event.stopPropagation?.();
+                if (printable)
+                    void send({ type: "type", text: key });
+                else
+                    void send({ type: "key", key, modifiers: held(event) });
+            };
+            /**
+             * Paste, relayed as text.
+             *
+             * Not reachable as a keystroke: Ctrl-V inside the remote page pastes the remote
+             * Chrome's clipboard, which is empty and is not the person's. Reading the real
+             * clipboard from the real paste event and sending the text is the only version of
+             * this that works — and it is the one that matters here, because a password out of
+             * a password manager arrives no other way.
+             */
+            const onPaste = (event) => {
+                if (!active || !view.interactive)
+                    return;
+                const text = event.clipboardData?.getData?.("text") ?? "";
+                if (!text)
+                    return;
+                event.preventDefault?.();
+                void send({ type: "type", text });
+            };
+            const onFocus = () => {
+                if (focused)
+                    return;
+                focused = true;
+                publish();
+            };
+            const onBlur = () => {
+                if (!focused)
+                    return;
+                focused = false;
+                publish();
+            };
+            // Focusable, so keystrokes have somewhere to land. An <img> cannot hold focus on
+            // its own, and a keydown listener on an element that can never be focused is a
+            // listener that never fires — which is indistinguishable from the relay not
+            // existing, and is how this looked.
+            if (el.tabIndex === undefined || el.tabIndex < 0)
+                el.tabIndex = 0;
             el.addEventListener("pointerdown", onDown);
             el.addEventListener("pointermove", onMove);
             el.addEventListener("pointerup", onUp);
             el.addEventListener("pointercancel", onUp);
             el.addEventListener("wheel", onWheel);
             el.addEventListener("contextmenu", onContextMenu);
+            el.addEventListener("keydown", onKeyDown);
+            el.addEventListener("paste", onPaste);
+            el.addEventListener("focus", onFocus);
+            el.addEventListener("blur", onBlur);
             paint();
             return () => {
                 el.removeEventListener("pointerdown", onDown);
@@ -1171,7 +1284,12 @@ class AgentFramework {
                 el.removeEventListener("pointercancel", onUp);
                 el.removeEventListener("wheel", onWheel);
                 el.removeEventListener("contextmenu", onContextMenu);
+                el.removeEventListener("keydown", onKeyDown);
+                el.removeEventListener("paste", onPaste);
+                el.removeEventListener("focus", onFocus);
+                el.removeEventListener("blur", onBlur);
                 dragging = false;
+                focused = false;
                 if (element === el)
                     element = null;
             };
@@ -1504,15 +1622,32 @@ class AgentFramework {
         }
         if (!res.ok) {
             let detail = await res.text();
+            // Alongside `detail`, when the server said which turn this was about. Read here
+            // because this is the one place an API error is built from a response — every route's
+            // refusal passes through it, so a route that starts saying which run failed needs no
+            // change on this side.
+            let ids;
             try {
-                detail = JSON.parse(detail);
-                if (detail && typeof detail === "object" && "detail" in detail)
-                    detail = detail.detail;
+                const body = JSON.parse(detail);
+                if (body && typeof body === "object") {
+                    const b = body;
+                    if ("detail" in b)
+                        detail = b.detail;
+                    else
+                        detail = body;
+                    const runId = typeof b.run_id === "string" ? b.run_id : undefined;
+                    const sessionId = typeof b.session_id === "string" ? b.session_id : undefined;
+                    if (runId || sessionId)
+                        ids = { runId, sessionId };
+                }
+                else {
+                    detail = body;
+                }
             }
             catch {
                 /* leave as text */
             }
-            throw new AgentApiError(res.status, detail);
+            throw new AgentApiError(res.status, detail, ids);
         }
         return res;
     }
@@ -2555,7 +2690,13 @@ class AgentFramework {
                                 // This used to be a bare message, so a stream that died at minute
                                 // eighteen threw away the answer AND the only handle on where the rest
                                 // of it had been written.
-                                throw new AgentStreamError("server: " + ev.data.detail, {
+                                // The server's sentence, unprefixed. This read `"server: " + detail`, so
+                                // every streamed failure reached the customer as
+                                // `server: the upstream endpoint answered 408 …` — a lowercase field name in
+                                // front of the first word they read, and the one difference between the two
+                                // paths' otherwise identical message (OBE-140). `AgentStreamError` already
+                                // says where it came from; the label said it again, worse.
+                                throw new AgentStreamError(ev.data.detail, {
                                     code: ev.data.code,
                                     // The status the same refusal carries on `POST /chat` — 429 for a spend
                                     // cap or a rate limit. Without it a streaming caller had no number to