@beeos-ai/device-agent 0.4.0

package/dist/model/client.js

@@ -0,0 +1,300 @@
+import OpenAI from "openai";
+import { detectAdapter, getAdapter } from "./adapters/base.js";
+import "./adapters/index.js"; // register all adapters
+const ACTION_MARKERS = ["finish(message=", "do(action=", "<tool_call>", "<answer>"];
+export class OpenAIClient {
+    openai;
+    config;
+    adapter;
+    constructor(opts = {}) {
+        this.config = {
+            baseUrl: normalizeBaseUrl(opts.baseUrl ?? process.env.GUI_AGENT_BASE_URL ?? "https://api.openai.com/v1"),
+            apiKey: opts.apiKey ?? process.env.GUI_AGENT_API_KEY ?? "EMPTY",
+            modelName: opts.modelName ?? process.env.GUI_AGENT_MODEL ?? "gpt-4o",
+            maxTokens: opts.maxTokens ?? 3000,
+            temperature: opts.temperature ?? 0,
+            topP: opts.topP ?? 0.85,
+        };
+        this.openai = new OpenAI({
+            baseURL: this.config.baseUrl,
+            apiKey: this.config.apiKey,
+            timeout: 120_000,
+            maxRetries: 4,
+        });
+        this.adapter =
+            typeof opts.adapter === "string" ? getAdapter(opts.adapter)
+                : opts.adapter instanceof Object && "name" in opts.adapter ? opts.adapter
+                    : detectAdapter(this.config.modelName);
+    }
+    get modelName() { return this.config.modelName; }
+    get adapterName() { return this.adapter.name; }
+    buildMessages(task, screenInfo, context, isFirst, lang) {
+        return this.adapter.buildMessages(task, screenInfo, context, isFirst, lang);
+    }
+    async request(messages, verboseOrOptions = false, signalArg) {
+        const opts = typeof verboseOrOptions === "boolean"
+            ? { verbose: verboseOrOptions, signal: signalArg }
+            : { ...verboseOrOptions, signal: verboseOrOptions.signal ?? signalArg };
+        const verbose = opts.verbose ?? false;
+        const signal = opts.signal;
+        const onTextDelta = opts.onTextDelta;
+        const emitDelta = (s) => {
+            if (!s || !onTextDelta)
+                return;
+            try {
+                const ret = onTextDelta(s);
+                if (ret && typeof ret.then === "function") {
+                    ret.catch(() => { });
+                }
+            }
+            catch {
+                // hook failures must not abort the model stream
+            }
+        };
+        // Some providers (e.g. Zhipu) occasionally RESET long streaming responses.
+        // Allow disabling streaming via env for robustness.
+        const useStream = process.env.GUI_AGENT_STREAM !== "0";
+        if (!useStream) {
+            const resp = await this.openai.chat.completions.create({
+                model: this.config.modelName,
+                messages: messages,
+                max_tokens: this.config.maxTokens,
+                temperature: this.config.temperature,
+                top_p: this.config.topP,
+            }, { signal });
+            const rawContent = resp.choices?.[0]?.message?.content ?? "";
+            if (verbose)
+                process.stdout.write(rawContent);
+            emitDelta(rawContent);
+            const [thinking, action] = splitRaw(rawContent);
+            return { rawContent, thinking, action };
+        }
+        // ── streaming path with chunk-level watchdog ───────────────────────────
+        //
+        // ARouter / OpenRouter occasionally hold a request in `: OPENROUTER PROCESSING`
+        // SSE-comment heartbeats while the upstream model is stuck. The OpenAI SDK's
+        // socket timeout never fires (bytes ARE flowing — they're just comments the
+        // SSE parser discards), and the `for await` yields zero chunks indefinitely.
+        // To bound the worst case we layer two watchdog timers on top of the SDK:
+        //
+        //   • first-chunk: aborts if no SSE chunk (delta-bearing or empty) lands within
+        //     `GUI_AGENT_FIRST_CHUNK_TIMEOUT_MS` (default 30s).
+        //   • inter-chunk: once the first chunk lands, aborts if subsequent chunks
+        //     stall for `GUI_AGENT_INTER_CHUNK_TIMEOUT_MS` (default 60s).
+        //
+        // Both are converted to `Error("model stream stalled …")` so upstream
+        // `agent-runtime/adapters/openai.ts` logs `vlm.predict.failed` and the
+        // SessionManager `onError` fallback surfaces a `task:notice` to the UI
+        // instead of leaving the worker silently parked.
+        const FIRST_CHUNK_TIMEOUT_MS = readPositiveInt(process.env.GUI_AGENT_FIRST_CHUNK_TIMEOUT_MS, 30_000);
+        const INTER_CHUNK_TIMEOUT_MS = readPositiveInt(process.env.GUI_AGENT_INTER_CHUNK_TIMEOUT_MS, 60_000);
+        // The watchdog runs side-by-side with the iterator: every `iter.next()`
+        // (and the initial `create()`) is wrapped in `withStallTimeout` which
+        // fires a `setTimeout` and races it against the underlying promise. If
+        // the timer wins, the wrapper rejects with a stall error AND aborts the
+        // SDK's signal — both paths are needed because some iterators (mocks,
+        // and providers that send `: OPENROUTER PROCESSING` SSE comments to
+        // keep sockets warm) don't surface AbortSignal cancellation cleanly,
+        // so the bare SDK idle timer never fires.
+        const controller = new AbortController();
+        const externalAbortHandler = () => {
+            controller.abort(signal.reason);
+        };
+        if (signal) {
+            if (signal.aborted) {
+                controller.abort(signal.reason);
+            }
+            else {
+                signal.addEventListener("abort", externalAbortHandler, { once: true });
+            }
+        }
+        let phase = "first";
+        const cleanup = () => {
+            signal?.removeEventListener("abort", externalAbortHandler);
+        };
+        const withStallTimeout = (work) => {
+            const ms = phase === "first" ? FIRST_CHUNK_TIMEOUT_MS : INTER_CHUNK_TIMEOUT_MS;
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                const timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    const reason = phase === "first"
+                        ? `model stream stalled: no chunk within ${ms}ms (first-chunk timeout)`
+                        : `model stream stalled: no chunk within ${ms}ms after partial output (inter-chunk timeout)`;
+                    const err = new Error(reason);
+                    controller.abort(err);
+                    reject(err);
+                }, ms);
+                work.then((v) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(v);
+                }, (e) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    reject(e);
+                });
+            });
+        };
+        let stream;
+        try {
+            stream = (await withStallTimeout(this.openai.chat.completions.create({
+                model: this.config.modelName,
+                messages: messages,
+                max_tokens: this.config.maxTokens,
+                temperature: this.config.temperature,
+                top_p: this.config.topP,
+                stream: true,
+            }, { signal: controller.signal })));
+        }
+        catch (e) {
+            cleanup();
+            throw e;
+        }
+        let rawContent = "";
+        let buffer = "";
+        let inAction = false;
+        const iter = stream[Symbol.asyncIterator]();
+        try {
+            while (true) {
+                const result = await withStallTimeout(iter.next());
+                if (result.done)
+                    break;
+                const chunk = result.value;
+                // Any SSE chunk (even an empty role-only frame) means the upstream is
+                // still alive — swap to the inter-chunk budget for the next wait.
+                phase = "inter";
+                if (signal?.aborted) {
+                    const e = new Error("aborted");
+                    e.name = "AbortError";
+                    throw e;
+                }
+                if (!chunk.choices.length)
+                    continue;
+                const delta = chunk.choices[0].delta;
+                // Reasoning models (MAI-UI etc.) emit reasoning_content before content
+                const reasoning = delta.reasoning_content;
+                if (typeof reasoning === "string" && reasoning) {
+                    rawContent += reasoning;
+                    if (!inAction) {
+                        if (verbose)
+                            process.stdout.write(reasoning);
+                        emitDelta(reasoning);
+                    }
+                }
+                const content = delta.content ?? "";
+                if (!content)
+                    continue;
+                rawContent += content;
+                if (inAction)
+                    continue;
+                buffer += content;
+                let markerFound = false;
+                for (const marker of ACTION_MARKERS) {
+                    if (buffer.includes(marker)) {
+                        const pre = buffer.slice(0, buffer.indexOf(marker));
+                        if (verbose) {
+                            process.stdout.write(pre);
+                            process.stdout.write("\n");
+                        }
+                        emitDelta(pre);
+                        inAction = true;
+                        markerFound = true;
+                        break;
+                    }
+                }
+                if (!markerFound) {
+                    // Only flush buffer if no partial marker at end
+                    const partialMatch = ACTION_MARKERS.some((m) => Array.from({ length: m.length - 1 }, (_, k) => k + 1)
+                        .some((k) => buffer.endsWith(m.slice(0, k))));
+                    if (!partialMatch) {
+                        if (verbose)
+                            process.stdout.write(buffer);
+                        emitDelta(buffer);
+                        buffer = "";
+                    }
+                }
+            }
+        }
+        catch (e) {
+            cleanup();
+            // Best-effort cancel the underlying stream so the SDK / fetch socket
+            // is freed even when our watchdog fires while the iterator is still
+            // parked.
+            try {
+                await iter.return?.(undefined);
+            }
+            catch { /* ignore */ }
+            throw e;
+        }
+        cleanup();
+        const [thinking, action] = splitRaw(rawContent);
+        return { rawContent, thinking, action };
+    }
+    parseResponse(raw) {
+        return this.adapter.parseResponse(raw);
+    }
+    updateContext(context, response, parsed) {
+        return this.adapter.updateContext(context, response, parsed);
+    }
+}
+/**
+ * Ensure the OpenAI baseURL ends with a versioned API path. A bare host
+ * like `https://api.arouter.ai` causes the SDK to POST `/chat/completions`,
+ * which ARouter's edge maps to the wrong upstream and surfaces as
+ * `HTTP 502 status code (no body)`. The canonical OpenAI-compatible path
+ * is `/v1/chat/completions`, so when the supplied baseURL has no path
+ * (just origin), append `/v1`. Anything that already has a path
+ * (e.g. custom `/api/v2`, Azure deployments) is left untouched.
+ */
+function normalizeBaseUrl(input) {
+    if (!input)
+        return input;
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        return input;
+    }
+    const path = url.pathname.replace(/\/+$/, "");
+    if (path === "" || path === "/") {
+        url.pathname = "/v1";
+        return url.toString().replace(/\/+$/, "");
+    }
+    return input.replace(/\/+$/, "");
+}
+function readPositiveInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.floor(n);
+}
+function splitRaw(content) {
+    const tcM = content.match(/<tool_call>([\s\S]*?)<\/tool_call>/);
+    if (tcM)
+        return [content.slice(0, tcM.index).trim(), tcM[0]];
+    if (content.includes("<answer>")) {
+        const [pre, post] = content.split("<answer>", 2);
+        return [pre.replace(/<\/?think>/g, "").trim(), post.replace("</answer>", "").trim()];
+    }
+    const lastDo = content.lastIndexOf("do(action=");
+    const lastFin = content.lastIndexOf("finish(message=");
+    const idx = lastDo >= 0 && lastFin >= 0 ? Math.max(lastDo, lastFin)
+        : lastDo >= 0 ? lastDo
+            : lastFin >= 0 ? lastFin
+                : -1;
+    if (idx >= 0) {
+        return [content.slice(0, idx).trim(), content.slice(idx)];
+    }
+    return ["", content];
+}
+//# sourceMappingURL=client.js.map

package/dist/model/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/model/client.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAI5B,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,qBAAqB,CAAC,CAAC,wBAAwB;AAEtD,MAAM,cAAc,GAAG,CAAC,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;AAWpF,MAAM,OAAO,YAAY;IACN,MAAM,CAAS;IACf,MAAM,CAAwB;IAC9B,OAAO,CAAe;IAEvC,YAAY,OAA0D,EAAE;QACtE,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,gBAAgB,CACvB,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,2BAA2B,CAC9E;YACD,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,OAAO;YAC/D,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,QAAQ;YACpE,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;YACjC,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC;YAClC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;SACxB,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC;YACvB,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,OAAO,EAAE,OAAO;YAChB,UAAU,EAAE,CAAC;SACd,CAAC,CAAC;QACH,IAAI,CAAC,OAAO;YACV,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;gBAC3D,CAAC,CAAC,IAAI,CAAC,OAAO,YAAY,MAAM,IAAI,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAuB;oBACzF,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,SAAS,KAAa,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IACzD,IAAI,WAAW,KAAa,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAEvD,aAAa,CAAC,IAAY,EAAE,UAAsB,EAAE,OAAkB,EAAE,OAAgB,EAAE,IAAY;QACpG,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,OAAO,CACX,QAAmB,EACnB,mBAAkD,KAAK,EACvD,SAAuB;QAEvB,MAAM,IAAI,GACR,OAAO,gBAAgB,KAAK,SAAS;YACnC,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE;YAClD,CAAC,CAAC,EAAE,GAAG,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;QACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACrC,MAAM,SAAS,GAAG,CAAC,CAAS,EAAQ,EAAE;YACpC,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW;gBAAE,OAAO;YAC/B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;gBAC3B,IAAI,GAAG,IAAI,OAAQ,GAAwB,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBAC/D,GAAwB,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;gBAC5C,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,gDAAgD;YAClD,CAAC;QACH,CAAC,CAAC;QAEF,2EAA2E;QAC3E,oDAAoD;QACpD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,GAAG,CAAC;QAEvD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CACpD;gBACE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAC5B,QAAQ,EAAE,QAAgE;gBAC1E,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBACjC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;gBACpC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;aACxB,EACD,EAAE,MAAM,EAAE,CACX,CAAC;YACF,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC;YAC7D,IAAI,OAAO;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC9C,SAAS,CAAC,UAAU,CAAC,CAAC;YACtB,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;YAChD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC1C,CAAC;QAED,0EAA0E;QAC1E,EAAE;QACF,gFAAgF;QAChF,6EAA6E;QAC7E,4EAA4E;QAC5E,6EAA6E;QAC7E,0EAA0E;QAC1E,EAAE;QACF,gFAAgF;QAChF,wDAAwD;QACxD,2EAA2E;QAC3E,kEAAkE;QAClE,EAAE;QACF,sEAAsE;QACtE,uEAAuE;QACvE,uEAAuE;QACvE,iDAAiD;QACjD,MAAM,sBAAsB,GAAG,eAAe,CAC5C,OAAO,CAAC,GAAG,CAAC,gCAAgC,EAC5C,MAAM,CACP,CAAC;QACF,MAAM,sBAAsB,GAAG,eAAe,CAC5C,OAAO,CAAC,GAAG,CAAC,gCAAgC,EAC5C,MAAM,CACP,CAAC;QAEF,wEAAwE;QACxE,sEAAsE;QACtE,uEAAuE;QACvE,wEAAwE;QACxE,sEAAsE;QACtE,oEAAoE;QACpE,qEAAqE;QACrE,0CAA0C;QAC1C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,oBAAoB,GAAG,GAAS,EAAE;YACtC,UAAU,CAAC,KAAK,CAAE,MAA6C,CAAC,MAAM,CAAC,CAAC;QAC1E,CAAC,CAAC;QACF,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,UAAU,CAAC,KAAK,CAAE,MAA6C,CAAC,MAAM,CAAC,CAAC;YAC1E,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAED,IAAI,KAAK,GAAsB,OAAO,CAAC;QACvC,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QAC7D,CAAC,CAAC;QAEF,MAAM,gBAAgB,GAAG,CAAI,IAAgB,EAAc,EAAE;YAC3D,MAAM,EAAE,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,sBAAsB,CAAC;YAC/E,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACxC,IAAI,OAAO,GAAG,KAAK,CAAC;gBACpB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC5B,IAAI,OAAO;wBAAE,OAAO;oBACpB,OAAO,GAAG,IAAI,CAAC;oBACf,MAAM,MAAM,GACV,KAAK,KAAK,OAAO;wBACf,CAAC,CAAC,yCAAyC,EAAE,0BAA0B;wBACvE,CAAC,CAAC,yCAAyC,EAAE,+CAA+C,CAAC;oBACjG,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;oBAC9B,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;oBACtB,MAAM,CAAC,GAAG,CAAC,CAAC;gBACd,CAAC,EAAE,EAAE,CAAC,CAAC;gBACP,IAAI,CAAC,IAAI,CACP,CAAC,CAAC,EAAE,EAAE;oBACJ,IAAI,OAAO;wBAAE,OAAO;oBACpB,OAAO,GAAG,IAAI,CAAC;oBACf,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,OAAO,CAAC,CAAC,CAAC,CAAC;gBACb,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;oBACJ,IAAI,OAAO;wBAAE,OAAO;oBACpB,OAAO,GAAG,IAAI,CAAC;oBACf,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,MAAM,CAAC,CAAC,CAAC,CAAC;gBACZ,CAAC,CACF,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,IAAI,MAAkE,CAAC;QACvE,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,MAAM,gBAAgB,CAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CACjC;gBACE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAC5B,QAAQ,EAAE,QAAgE;gBAC1E,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBACjC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;gBACpC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;gBACvB,MAAM,EAAE,IAAI;aACb,EACD,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAC9B,CACF,CAA+D,CAAC;QACnE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,CAAC;QACV,CAAC;QAED,IAAI,UAAU,GAAG,EAAE,CAAC;QACpB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;gBACnD,IAAI,MAAM,CAAC,IAAI;oBAAE,MAAM;gBACvB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;gBAE3B,sEAAsE;gBACtE,kEAAkE;gBAClE,KAAK,GAAG,OAAO,CAAC;gBAEhB,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;oBACpB,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;oBAC9B,CAA8B,CAAC,IAAI,GAAG,YAAY,CAAC;oBACpD,MAAM,CAAC,CAAC;gBACV,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM;oBAAE,SAAS;gBACpC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;gBAErC,uEAAuE;gBACvE,MAAM,SAAS,GAAI,KAAiC,CAAC,iBAAiB,CAAC;gBACvE,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,EAAE,CAAC;oBAC/C,UAAU,IAAI,SAAS,CAAC;oBACxB,IAAI,CAAC,QAAQ,EAAE,CAAC;wBACd,IAAI,OAAO;4BAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;wBAC7C,SAAS,CAAC,SAAS,CAAC,CAAC;oBACvB,CAAC;gBACH,CAAC;gBAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;gBACpC,IAAI,CAAC,OAAO;oBAAE,SAAS;gBAEvB,UAAU,IAAI,OAAO,CAAC;gBACtB,IAAI,QAAQ;oBAAE,SAAS;gBAEvB,MAAM,IAAI,OAAO,CAAC;gBAElB,IAAI,WAAW,GAAG,KAAK,CAAC;gBACxB,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;oBACpC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;wBAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;wBACpD,IAAI,OAAO,EAAE,CAAC;4BAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;4BAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;wBAAC,CAAC;wBACvE,SAAS,CAAC,GAAG,CAAC,CAAC;wBACf,QAAQ,GAAG,IAAI,CAAC;wBAChB,WAAW,GAAG,IAAI,CAAC;wBACnB,MAAM;oBACR,CAAC;gBACH,CAAC;gBAED,IAAI,CAAC,WAAW,EAAE,CAAC;oBACjB,gDAAgD;oBAChD,MAAM,YAAY,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAC7C,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;yBAClD,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAC/C,CAAC;oBACF,IAAI,CAAC,YAAY,EAAE,CAAC;wBAClB,IAAI,OAAO;4BAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;wBAC1C,SAAS,CAAC,MAAM,CAAC,CAAC;wBAClB,MAAM,GAAG,EAAE,CAAC;oBACd,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,EAAE,CAAC;YACV,qEAAqE;YACrE,oEAAoE;YACpE,UAAU;YACV,IAAI,CAAC;gBAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;YAC9D,MAAM,CAAC,CAAC;QACV,CAAC;QAED,OAAO,EAAE,CAAC;QACV,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;QAChD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC1C,CAAC;IAED,aAAa,CAAC,GAAW;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACzC,CAAC;IAED,aAAa,CAAC,OAAkB,EAAE,QAAuB,EAAE,MAAoB;QAC7E,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QAChC,GAAG,CAAC,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,eAAe,CAAC,GAAuB,EAAE,QAAgB;IAChE,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,QAAQ,CAAC,OAAe;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAChE,IAAI,GAAG;QAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,KAAM,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACjD,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC;IACvD,MAAM,GAAG,GACP,MAAM,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;QACvD,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM;YACtB,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO;gBACxB,CAAC,CAAC,CAAC,CAAC,CAAC;IACP,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;AACvB,CAAC"}

package/dist/model/image/compress.d.ts

@@ -0,0 +1,53 @@
+/**
+ * VLM image compression — single-purpose utility that produces an
+ * ARouter / llama.cpp friendly JPEG from raw screenshot bytes.
+ *
+ * Why this lives here and not in `device-mcp-server`:
+ *   - mcp-server is a protocol-layer service. Other consumers (debug
+ *     viewers, e2e recordings, research tools) want 1:1 high-fidelity
+ *     captures. Compression is a VLM-specific application-layer concern.
+ *   - The boundary `mcp-server v0.2.3` deliberately defaults
+ *     `SS_MAX_EDGE=Infinity` to push compression up the stack — this
+ *     module fulfils that contract on the device-agent side.
+ *
+ * Why 1280-edge JPEG q80:
+ *   - AutoGLM-Phone-9B (= GLM-4.1V-9B-Thinking) vision encoder uses 14-px
+ *     patches with `image_size=336` and dynamic resize. A 1280-edge input
+ *     is already past the model's effective perception ceiling — bigger
+ *     bytes are pure waste.
+ *   - mozjpeg q80 yields ~20× compression vs raw PNG with no measurable
+ *     visual loss for UI screenshots (high-frequency text rendering is
+ *     the worst case and stays sharp at q80).
+ *   - The combination keeps post-base64 body under ~330KB, well below
+ *     ARouter's 5MB body limit and llama.cpp's 10MB image cap.
+ */
+export interface CompressedImage {
+    bytes: Buffer;
+    mime: "image/jpeg";
+    width: number;
+    height: number;
+}
+export interface CompressOptions {
+    /** Override `BEEOS_VLM_MAX_EDGE` env (default 1280). */
+    maxEdge?: number;
+    /** Override `BEEOS_VLM_JPEG_QUALITY` env (default 80, range 1-100). */
+    jpegQuality?: number;
+}
+/**
+ * Resize (long edge ≤ `maxEdge`) and re-encode an image as mozjpeg
+ * `image/jpeg`. Idempotent on already-compressed JPEGs that fit under
+ * `maxEdge`: sharp will still re-encode but bytes converge fast.
+ *
+ * Inputs are accepted in any sharp-readable format (PNG, JPEG, WebP, ...).
+ * Output MIME is always `image/jpeg` — this is intentional, see module
+ * docstring.
+ *
+ * Resilience: if `sharp` cannot decode the input (e.g. truncated bytes,
+ * corrupt frames, or test-fixture sentinels like `"AAAA"`), the
+ * function returns the input bytes unchanged tagged as `image/jpeg`
+ * with `width=height=0`. The caller's transport then ships them as-is
+ * — letting the upstream model surface the decoding error rather than
+ * silently dropping the screenshot. This matches the legacy
+ * "wrap-and-forward" semantics of pre-A1 device-agent.
+ */
+export declare function compressForVlm(buf: Buffer, opts?: CompressOptions): Promise<CompressedImage>;

package/dist/model/image/compress.js

@@ -0,0 +1,89 @@
+/**
+ * VLM image compression — single-purpose utility that produces an
+ * ARouter / llama.cpp friendly JPEG from raw screenshot bytes.
+ *
+ * Why this lives here and not in `device-mcp-server`:
+ *   - mcp-server is a protocol-layer service. Other consumers (debug
+ *     viewers, e2e recordings, research tools) want 1:1 high-fidelity
+ *     captures. Compression is a VLM-specific application-layer concern.
+ *   - The boundary `mcp-server v0.2.3` deliberately defaults
+ *     `SS_MAX_EDGE=Infinity` to push compression up the stack — this
+ *     module fulfils that contract on the device-agent side.
+ *
+ * Why 1280-edge JPEG q80:
+ *   - AutoGLM-Phone-9B (= GLM-4.1V-9B-Thinking) vision encoder uses 14-px
+ *     patches with `image_size=336` and dynamic resize. A 1280-edge input
+ *     is already past the model's effective perception ceiling — bigger
+ *     bytes are pure waste.
+ *   - mozjpeg q80 yields ~20× compression vs raw PNG with no measurable
+ *     visual loss for UI screenshots (high-frequency text rendering is
+ *     the worst case and stays sharp at q80).
+ *   - The combination keeps post-base64 body under ~330KB, well below
+ *     ARouter's 5MB body limit and llama.cpp's 10MB image cap.
+ */
+import sharp from "sharp";
+const DEFAULT_MAX_EDGE = 1280;
+const DEFAULT_JPEG_QUALITY = 80;
+/**
+ * Resize (long edge ≤ `maxEdge`) and re-encode an image as mozjpeg
+ * `image/jpeg`. Idempotent on already-compressed JPEGs that fit under
+ * `maxEdge`: sharp will still re-encode but bytes converge fast.
+ *
+ * Inputs are accepted in any sharp-readable format (PNG, JPEG, WebP, ...).
+ * Output MIME is always `image/jpeg` — this is intentional, see module
+ * docstring.
+ *
+ * Resilience: if `sharp` cannot decode the input (e.g. truncated bytes,
+ * corrupt frames, or test-fixture sentinels like `"AAAA"`), the
+ * function returns the input bytes unchanged tagged as `image/jpeg`
+ * with `width=height=0`. The caller's transport then ships them as-is
+ * — letting the upstream model surface the decoding error rather than
+ * silently dropping the screenshot. This matches the legacy
+ * "wrap-and-forward" semantics of pre-A1 device-agent.
+ */
+export async function compressForVlm(buf, opts = {}) {
+    const maxEdge = resolveInt(opts.maxEdge, "BEEOS_VLM_MAX_EDGE", DEFAULT_MAX_EDGE);
+    const jpegQuality = clampQuality(resolveInt(opts.jpegQuality, "BEEOS_VLM_JPEG_QUALITY", DEFAULT_JPEG_QUALITY));
+    try {
+        const meta = await sharp(buf, { failOn: "none" }).metadata();
+        const srcW = meta.width ?? 0;
+        const srcH = meta.height ?? 0;
+        const longEdge = Math.max(srcW, srcH);
+        let pipeline = sharp(buf, { failOn: "none" });
+        if (longEdge > maxEdge) {
+            pipeline = srcW >= srcH
+                ? pipeline.resize({ width: maxEdge, withoutEnlargement: true })
+                : pipeline.resize({ height: maxEdge, withoutEnlargement: true });
+        }
+        const bytes = await pipeline.jpeg({ quality: jpegQuality, mozjpeg: true }).toBuffer();
+        const out = await sharp(bytes).metadata();
+        return {
+            bytes,
+            mime: "image/jpeg",
+            width: out.width ?? srcW,
+            height: out.height ?? srcH,
+        };
+    }
+    catch {
+        return { bytes: buf, mime: "image/jpeg", width: 0, height: 0 };
+    }
+}
+function resolveInt(explicit, envKey, fallback) {
+    if (typeof explicit === "number" && Number.isFinite(explicit) && explicit > 0)
+        return explicit;
+    const raw = process.env[envKey];
+    if (!raw)
+        return fallback;
+    const parsed = parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+function clampQuality(q) {
+    if (q < 1)
+        return 1;
+    if (q > 100)
+        return 100;
+    return Math.round(q);
+}
+//# sourceMappingURL=compress.js.map

package/dist/model/image/compress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../../src/model/image/compress.ts"],"names":[],"mappings":"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"}

package/dist/model/image/transport.d.ts

@@ -0,0 +1,134 @@
+/**
+ * ImageTransport — strategy abstraction for delivering a compressed VLM
+ * image to the model.
+ *
+ *   bytes ──▶ Transport ──▶ ImageRef
+ *
+ * Two concrete strategies live in the codebase:
+ *   - `DataUrlTransport`  (Phase A) → inline `data:<mime>;base64,...`
+ *   - `HttpUrlTransport`  (Phase B) → presign + PUT to S3, return signed
+ *                                     GET URL
+ *
+ * `FallbackTransport` composes any two strategies so production traffic
+ * can be configured to "prefer http-url, gracefully degrade to data-url
+ * on transient upload failure" — keeping a hard correctness floor while
+ * still gaining the body-size win when everything is healthy.
+ */
+import { type AgentGatewayIdentity, type PresignFilePair } from "../../adapters/agent-gateway-client.js";
+import type { ImageRef } from "../../types.js";
+export type ImageMime = "image/jpeg" | "image/png";
+export interface ImageTransport {
+    /** Stable, log-friendly identifier — useful for metrics/labels. */
+    readonly name: string;
+    send(bytes: Buffer, mime: ImageMime): Promise<ImageRef>;
+}
+/**
+ * Inline-base64 transport. Always succeeds (modulo OOM); the body bloat
+ * is bounded only by the input bytes — pair this with `compressForVlm`
+ * upstream to stay below ARouter's 5MB body cap.
+ */
+export declare class DataUrlTransport implements ImageTransport {
+    readonly name = "data-url";
+    send(bytes: Buffer, mime: ImageMime): Promise<ImageRef>;
+}
+export interface HttpUrlFileClient {
+    presignFileUpload(args: {
+        fileName: string;
+        mimeType: string;
+    }): Promise<PresignFilePair>;
+    putPresignedBytes(args: {
+        uploadUrl: string;
+        bytes: Uint8Array;
+        mimeType: string;
+    }): Promise<void>;
+}
+export interface HttpUrlTransportOptions {
+    /**
+     * Object-name prefix passed as `fileName` to `presignFileUpload`.
+     * Defaults to `vlm-screenshots/`. Lifecycle rules in Phase B8 attach
+     * to this prefix for automatic 24h cleanup.
+     */
+    keyPrefix?: string;
+    /** Test seam — defaults to `crypto.randomUUID()`. */
+    randomUUID?: () => string;
+    /** Test seam — defaults to `Date.now()`. */
+    now?: () => number;
+}
+/**
+ * Adapter implementation of `HttpUrlFileClient` that hits the live
+ * Agent Gateway over HTTP/1.1 with Ed25519 auth. Suitable for
+ * production wiring; tests should pass a mock `HttpUrlFileClient`.
+ */
+export declare class AgentGatewayFileClient implements HttpUrlFileClient {
+    private readonly opts;
+    constructor(opts: {
+        agentGatewayUrl: string;
+        identity: AgentGatewayIdentity;
+        timeoutMs?: number;
+    });
+    presignFileUpload(args: {
+        fileName: string;
+        mimeType: string;
+    }): Promise<PresignFilePair>;
+    putPresignedBytes(args: {
+        uploadUrl: string;
+        bytes: Uint8Array;
+        mimeType: string;
+    }): Promise<void>;
+}
+/**
+ * Resource-link transport — pre-signs an S3/MinIO PUT URL via Agent
+ * Gateway, uploads the (already-compressed) image bytes, and returns
+ * the paired pre-signed GET URL as an `kind: "http-url"` `ImageRef`.
+ *
+ * Why this exists:
+ *
+ *   - ARouter / Cloudfront / nginx in front of `llama.cpp` cap request
+ *     bodies at ≈5 MB. A raw 1080×1920 PNG screenshot base64-encoded
+ *     in a chat-completion message routinely overflows that cap, so
+ *     the only robust path for production traffic is to ship a URL,
+ *     not bytes.
+ *   - `llama.cpp`'s vision server fetches `image_url`s natively
+ *     (subject to its own ≈10 MB / 10 s download caps), making this a
+ *     transport-only change — no model-side adapter rewrite required.
+ *
+ * Errors:
+ *   - Both steps surface `AgentGatewayError`. Compose with
+ *     `FallbackTransport(http, data)` if the caller wants a graceful
+ *     degradation to inline base64 on transient upload failure.
+ *
+ * Body sigv4 caveat: the `Content-Type` MUST equal what was passed at
+ * presign time, otherwise S3 returns 403 (signature mismatch). We
+ * forward `mime` to both calls so this is automatic.
+ */
+export declare class HttpUrlTransport implements ImageTransport {
+    private readonly client;
+    readonly name = "http-url";
+    private readonly keyPrefix;
+    private readonly randomUUID;
+    private readonly now;
+    constructor(client: HttpUrlFileClient, opts?: HttpUrlTransportOptions);
+    send(bytes: Buffer, mime: ImageMime): Promise<ImageRef>;
+}
+export interface FallbackTransportLogger {
+    warn(msg: string, fields?: Record<string, unknown>): void;
+}
+export interface FallbackTransportOptions {
+    logger?: FallbackTransportLogger;
+    /** Hook for monitoring — invoked once per fallback path taken. */
+    onFallback?: (reason: unknown) => void;
+}
+/**
+ * Try `primary`; if it throws, log and fall back to `fallback`. The
+ * second transport's failure propagates to the caller — we never silently
+ * swallow a degraded-mode error.
+ */
+export declare class FallbackTransport implements ImageTransport {
+    private readonly primary;
+    private readonly fallback;
+    readonly name: string;
+    private readonly logger;
+    private readonly onFallback?;
+    constructor(primary: ImageTransport, fallback: ImageTransport, opts?: FallbackTransportOptions);
+    send(bytes: Buffer, mime: ImageMime): Promise<ImageRef>;
+}