managed-deepagents 0.9.6-dev.19 → 0.9.6-dev.20

package/dist/runtime/browser.js

@@ -0,0 +1,795 @@
+/**
+ * Browser use: Stagehand's TypeScript facade tools on a LangSmith browser.
+ *
+ * A browser per key (`thread:<id>`, or `user:<id>` under user scope). A
+ * thread's own browser has one window, `mda`; a user's has a window per
+ * thread, so their threads share logins but not tabs. Each browser has one
+ * Stagehand client in this process (the extension serves one at a time),
+ * released between runs and after a minute idle so the browser can idle out.
+ *
+ * `browser_handoff` hands the window to the user and returns at once. A run of
+ * the watcher graph, which `mda` builds beside the agent, waits on its own
+ * thread for the user to hand it back, then enqueues a run on the agent's
+ * thread with a notification, as an async subagent tells the agent that
+ * started it that it finished.
+ *
+ * The middleware half of Python's `browser.py`; `browser-langsmith.ts` holds
+ * the LangSmith half. Only projects that declare `browser.ts` import this
+ * module or install Stagehand.
+ */
+import { createHash } from "node:crypto";
+import { readdir, readFile, unlink } from "node:fs/promises";
+import { join, posix, relative, sep } from "node:path";
+import { SystemMessage, ToolMessage, } from "@langchain/core/messages";
+import { tool } from "@langchain/core/tools";
+import { Annotation, Command, END, START, StateGraph, } from "@langchain/langgraph";
+import { Client } from "@langchain/langgraph-sdk";
+import { isSandboxBackend, } from "deepagents";
+import { createMiddleware } from "langchain";
+import { z } from "zod";
+import { CodeModeRunInputSchema, FACADE_AGENT_INSTRUCTIONS, FACADE_TOOLS, sanitizeErrorMessage, StagehandFacadeExecutionError, StagehandFacadeInputError, } from "./browser-facade.js";
+import { browserBox, closeSession, handOver, HANDOFF_LINK_TTL_S, handoffStatus, newestTab, openSession, RecorderError, shareLocalhost, PendingBrowserHandoffSchema, shellQuote, startTake, stopTake, } from "./browser-langsmith.js";
+import { LazyManagedSandboxBackend } from "./backend.js";
+import { logger } from "./log.js";
+import { verifiedLeadThread } from "./parent-run.js";
+import { MDA_NOTIFICATION_KEY } from "../channels/assistant-text.js";
+const WORKSPACE = "/workspace"; // where run code's screenshots land in the sandbox
+const INSTRUCTIONS = 
+// The facade's text and errors name its tools `run` and so on; ours gain `browser_`.
+"These tools are named browser_run, browser_snapshot and browser_screenshot: " +
+    "call those wherever this text or an error names run, snapshot or screenshot.\n" +
+    "Screenshots that run code saves go to /workspace in your sandbox: " +
+    "`await page.screenshot({ path: 'shots/a.png' })` saves /workspace/shots/a.png.";
+const SCREENSHOT_PATH = "Only if you have a sandbox: also save the image to this absolute path in it, " +
+    "creating its folder, e.g. to publish it.";
+const LOCALHOST_NOTE = // a thread's browser shares its sandbox's localhost
+ "Servers running in your sandbox are reachable at http://localhost:<port> " +
+    "(any port but 80 and 443).";
+const RECORDINGS = `${WORKSPACE}/recordings`;
+// The recorder's own limits, which Python's `_browser_recording.py` sets: it runs in
+// the browser's sandbox, so this process never imports it.
+const RECORD_VIEWPORT = [1280, 800];
+const RECORD_MAX_HOLD_S = 1.5;
+const RECORD_MAX_S = 300;
+const RECORD_DESCRIPTION = `Record the browser tab as a video, to show a person what you did.
+
+\`start\`, act as usual, then \`stop\`: it saves an H.264 mp4 to the \`path\` you gave
+either, in your sandbox (default ${RECORDINGS}/<time>.mp4), with what happened when
+beside it as JSON (the same path, ending .json), and shows you its first and last
+frames. The video shows a cursor
+gliding to each click, the clicks, and what is typed (masked in password fields). While
+recording, the viewport is ${RECORD_VIEWPORT[0]}x${RECORD_VIEWPORT[1]}, and each
+pause between your calls plays for at most ${RECORD_MAX_HOLD_S}s.
+A recording also ends, and is saved, when the run ends or you hand the browser to
+the user: it never shows what they do. It stops at
+${RECORD_MAX_S / 60} minutes.`;
+const RECORD_SCHEMA = {
+    type: "object",
+    properties: {
+        action: { type: "string", enum: ["start", "stop"] },
+        path: { type: "string" },
+    },
+    required: ["action"],
+};
+const HANDOFF_DESCRIPTION = "Hand the browser to the user; you'll be notified when they hand it back.\n\n" +
+    "Use it for what only they should do: log in, solve a CAPTCHA, approve a " +
+    "2FA prompt. Never ask for passwords. `reason` is shown to them as is: a " +
+    'few words on what to do, such as "Log in to LinkedIn".';
+const HAND_BACK_POLL_MS = 2_000;
+const WITH_USER = "The browser is with the user until they hand it back; wait for the notification " +
+    "that they did before using it.";
+const HANDED_OVER = // what the model reads from browser_handoff
+ "The browser is with the user. You'll get a notification when they hand it back; " +
+    "until then, don't use the browser. Tell the user what to do in it.";
+/** Clients such as Studio show a notification's first sentence, so it reads for both. */
+const WAKE_TEXT = {
+    handed_back: "The browser was handed back. Take a snapshot of the page; if the user hasn't " +
+        "finished, call browser_handoff again.",
+    ended: "The browser handoff ended. Take a snapshot to see whether the user finished.",
+};
+/**
+ * The thread's handoff that waits on the user, as Python's `mda_browser_handoff`.
+ * A leading `_` keeps it out of run input, as Python's `OmitFromInput` does.
+ */
+const HANDOFF_KEY = "_mda_browser_handoff";
+/** The graph `mda` builds beside the agent, whose run waits out a handoff. */
+export const HANDOFF_WATCHER_GRAPH = "mda-browser-handoff";
+/** Where deepagents puts the reference to the agent that started a run, which isn't forwarded. */
+const PARENT_REFERENCE_KEY = "deepagents_parent";
+const RELEASE_AFTER_MS = 60_000; // a run that throws or interrupts never reaches afterAgent
+const BrowserStateSchema = z.object({
+    [HANDOFF_KEY]: PendingBrowserHandoffSchema.nullable().optional(),
+});
+// Process-wide: a user's concurrent threads share their browser's one client.
+const sessions = new Map();
+// By browser key, for its client; by `takeKey`, for the window's take, taken
+// first. A take starts and ends in turn, and saving one holds up no other window.
+const locks = new Map();
+const releases = new Map();
+// By browser key and window: a user's threads record their own windows.
+const takes = new Map();
+async function release(key) {
+    const session = sessions.get(key);
+    sessions.delete(key);
+    if (session)
+        await closeSession(session);
+}
+/**
+ * Run code's `browser.close()`: release the client once the tool call is done.
+ *
+ * The facade asks before the run tool has moved the screenshots that code saved.
+ */
+async function closeAfterCall(key) {
+    const session = sessions.get(key);
+    if (session)
+        session.closing = true;
+}
+/** Release `key`'s client a minute after its last call; each call restarts the wait. */
+function releaseWhenIdle(key) {
+    clearTimeout(releases.get(key));
+    const timer = setTimeout(() => {
+        withLock(key, async () => {
+            if (releases.get(key) !== timer)
+                return; // a later call restarted the wait
+            releases.delete(key);
+            await release(key);
+        });
+    }, RELEASE_AFTER_MS).unref(); // never keeps the process alive
+    releases.set(key, timer);
+}
+/**
+ * Give the agent Stagehand's tools, named `browser_run`, `browser_snapshot` and
+ * so on, plus `browser_record` for a video.
+ */
+export function createBrowserMiddleware(options) {
+    const { scope } = options;
+    const tools = browserTools(options);
+    const accepted = new Map(tools.map((t) => [t.name, Object.keys(t.schema.properties)]));
+    let instructions = `${FACADE_AGENT_INSTRUCTIONS}\n\n${INSTRUCTIONS}`;
+    if (scope === "thread")
+        instructions += ` ${LOCALHOST_NOTE}`;
+    return createMiddleware({
+        name: "mda-browser",
+        stateSchema: BrowserStateSchema,
+        tools,
+        // JSON-schema tools turn away input their schema rejects, with a stack trace,
+        // before their function runs. Answer it as Python's tools and facade do: names
+        // a tool lacks, such as snake_case ones, and bad run input. Like them, take a
+        // null argument as left out; some models send every argument.
+        async wrapToolCall(request, handler) {
+            const { name, args, id } = request.toolCall;
+            const names = accepted.get(name);
+            if (names === undefined)
+                return handler(request); // not a browser tool
+            const extra = Object.keys(args).filter((arg) => !names.includes(arg));
+            const given = Object.fromEntries(Object.entries(args).filter(([, value]) => value !== null));
+            let error = extra.length > 0 ? unexpected(extra) : undefined;
+            if (name === "browser_run")
+                error ??= invalidRun(given);
+            if (error === undefined) {
+                return handler({
+                    ...request,
+                    toolCall: { ...request.toolCall, args: given },
+                });
+            }
+            return new ToolMessage({ content: error, tool_call_id: id ?? "", name });
+        },
+        // A run the handoff's notification starts ends the handoff.
+        async beforeAgent(state) {
+            const messages = state.messages ?? [];
+            const last = messages.at(-1);
+            if (pending(state) && last && isHandoffNotification(last)) {
+                return { [HANDOFF_KEY]: null };
+            }
+            return undefined;
+        },
+        // Save the run's recording and release the client; the browser and windows stay.
+        async afterAgent(_state, runtime) {
+            const found = locate(runtime, scope);
+            if (typeof found === "string")
+                return; // no thread or user, so no session
+            const { key, window } = found;
+            await withLock(takeKey(key, window), () => endTake(key, window));
+            await withLock(key, () => release(key));
+        },
+        // Append the facade's instructions to the system message, as their own block.
+        async wrapModelCall(request, handler) {
+            const content = request.systemMessage?.content ?? request.systemPrompt;
+            const blocks = typeof content === "string"
+                ? content
+                    ? [{ type: "text", text: content }]
+                    : []
+                : (content ?? []);
+            return handler({
+                ...request,
+                systemMessage: new SystemMessage({
+                    content: [...blocks, { type: "text", text: instructions }],
+                }),
+            });
+        },
+    });
+}
+/**
+ * Run `fn` on the run's session. Errors go to the model; nothing is retried.
+ *
+ * While the user has the window, the agent waits.
+ */
+async function call(options, runtime, fn) {
+    // The handoff is asked about here too: after a restart no watcher says it ended.
+    const handoff = pending(runtime.state);
+    if (handoff && (await handoffStatus(handoff)) === undefined) {
+        return `error: ${WITH_USER}`;
+    }
+    const found = locate(runtime, options.scope);
+    if (typeof found === "string")
+        return found;
+    const { key, window } = found;
+    return withLock(key, async () => {
+        try {
+            if (sessions.get(key)?.window !== window) {
+                await release(key); // another of the user's threads: move windows
+                const ttl = options.idleTtlSeconds;
+                const opened = openSession(key, window, ttl, () => closeAfterCall(key));
+                sessions.set(key, await opened);
+            }
+            const session = sessions.get(key);
+            await share(session, key, runtime);
+            return await fn(session);
+        }
+        catch (err) {
+            return await failed(key, err);
+        }
+        finally {
+            if (sessions.get(key)?.closing)
+                await release(key);
+            releaseWhenIdle(key);
+        }
+    });
+}
+/**
+ * Give the user the window and return at once, keeping the handoff in state.
+ *
+ * It needs no client, only the browsers API: a window a person controls turns
+ * a client away, so a second handoff could not connect. The agent's client
+ * lets go, and the next browser call connects afresh and takes the window back.
+ */
+async function handToUser(options, runtime, reason) {
+    const found = locate(runtime, options.scope);
+    if (typeof found === "string")
+        return found;
+    const { thread, key, window } = found;
+    let ended;
+    let handed;
+    try {
+        // No take starts meanwhile.
+        handed = await withLock(takeKey(key, window), async () => {
+            ended = await endTake(key, window); // saved before the user has the window
+            return withLock(key, async () => {
+                await release(key);
+                return handOver(key, window, options.idleTtlSeconds);
+            });
+        });
+    }
+    catch (err) {
+        const failed = `error: ${sanitizeErrorMessage(errorText(err))}`;
+        return withRecording(failed, ended);
+    }
+    const handoff = {
+        browser: handed.browser,
+        window_id: handed.windowId,
+        until: Date.now() / 1000 + HANDOFF_LINK_TTL_S,
+    };
+    try {
+        await startWatcher(loopback(), runtime, handoff);
+    }
+    catch (err) {
+        // The browser tools still work once it ended.
+        const label = logger.safeErrorLabel(err);
+        logger.warn(`could not watch the handoff on thread ${thread}: ${label}`);
+    }
+    // What clients such as Studio show the user: the ask, and a link that lets
+    // whoever holds it drive the window, for 15 minutes. The model never sees it.
+    const reply = new ToolMessage({
+        content: withRecording(HANDED_OVER, ended),
+        artifact: { type: "browser_handoff", message: reason, url: handed.url },
+        name: "browser_handoff",
+        tool_call_id: runtime.toolCallId ?? "",
+    });
+    return new Command({ update: { [HANDOFF_KEY]: handoff, messages: [reply] } });
+}
+/**
+ * Start a run of the watcher graph on a thread of its own, as deepagents starts
+ * an async subagent's task: the thread's metadata names this agent, which the
+ * Agent Server copies into the run, and the run gets this run's context.
+ *
+ * The wait is a run rather than a promise in this process, so the wake-up comes
+ * from a live run, the only caller a deployed graph's Agent Server takes.
+ */
+export async function startWatcher(client, runtime, handoff) {
+    const thread = await client.threads.create({
+        metadata: {
+            parent_thread_id: runtime.configurable?.thread_id,
+            parent_assistant_id: runtime.serverInfo?.assistantId || runtime.serverInfo?.graphId,
+        },
+    });
+    const context = forwardedContext(runtime.context);
+    await client.runs.create(thread.thread_id, HANDOFF_WATCHER_GRAPH, {
+        input: { handoff },
+        ...(context && { context }),
+    });
+}
+const WatcherState = Annotation.Root({
+    handoff: Annotation(),
+});
+/**
+ * Once the handoff ends, notify the agent that started it, unless it has moved
+ * on: a newer handoff replaced this one, or the agent waits on a person, where
+ * a new run would drop what it waits for. Its browser tools work again either way.
+ */
+export async function watch(state, config) {
+    const { handoff } = state;
+    let status;
+    while (status === undefined) {
+        await new Promise((resolve) => {
+            setTimeout(resolve, HAND_BACK_POLL_MS);
+        });
+        status = await handoffStatus(handoff);
+    }
+    const { threadId, assistantId } = await launchingAgent(config);
+    if (!threadId || !assistantId)
+        return {};
+    const client = loopback();
+    const thread = await client.threads.get(threadId);
+    if (thread.status === "interrupted" ||
+        !sameHandoff(pending(thread.values), handoff)) {
+        return {};
+    }
+    const context = forwardedContext(config.context);
+    await client.runs.create(threadId, assistantId, {
+        input: { messages: [wakeMessage(status)] },
+        multitaskStrategy: "enqueue", // after a run that is going on
+        ...(context && { context }),
+    });
+    return {};
+}
+/** The watcher graph: one run per handoff, from `browser_handoff` until it ends. */
+export const handoffWatcher = new StateGraph(WatcherState)
+    .addNode("watch", watch)
+    .addEdge(START, "watch")
+    .addEdge("watch", END)
+    .compile();
+/**
+ * The agent that started this run, as an async subagent's run finds its lead:
+ * its thread, once this run's caller is verified to own it, and its assistant,
+ * from the thread's metadata the Agent Server copies into every run on it.
+ */
+async function launchingAgent(config) {
+    const lead = await verifiedLeadThread(config);
+    const assistantId = config.metadata?.parent_assistant_id;
+    return {
+        threadId: lead?.id,
+        assistantId: typeof assistantId === "string" ? assistantId : undefined,
+    };
+}
+/** A run's context for another run, without deepagents' parent reference, as deepagents forwards it. */
+function forwardedContext(context) {
+    if (!context || typeof context !== "object")
+        return undefined;
+    const forwarded = Object.fromEntries(Object.entries(context).filter(([key]) => key !== PARENT_REFERENCE_KEY));
+    return Object.keys(forwarded).length > 0 ? forwarded : undefined;
+}
+/**
+ * This Agent Server, called as the user who started the run, as Python's
+ * in-process `get_client()` is. With no `apiUrl`, the client takes the Agent
+ * Server's loopback, which marks each call with the live run so the server
+ * restores that run's user; managed auth never sees the call. It answers only
+ * while the run is live.
+ */
+function loopback() {
+    return new Client();
+}
+function pending(state) {
+    const value = state && typeof state === "object"
+        ? state[HANDOFF_KEY]
+        : undefined;
+    return (value ?? undefined);
+}
+function sameHandoff(a, b) {
+    return (a?.browser === b.browser &&
+        a.window_id === b.window_id &&
+        a.until === b.until);
+}
+/**
+ * A notification in deepagents' task notification's shape: a user-role message
+ * framed as a system notification. Its `mda_notification` tells clients how the
+ * handoff ended, so they can tell it from the user's message.
+ */
+export function wakeMessage(status) {
+    return {
+        role: "user",
+        content: `[SYSTEM NOTIFICATION - NOT USER INPUT]\n${WAKE_TEXT[status]}`,
+        additional_kwargs: {
+            [MDA_NOTIFICATION_KEY]: { type: "browser_handoff", status },
+        },
+    };
+}
+function isHandoffNotification(message) {
+    const notification = message.additional_kwargs?.[MDA_NOTIFICATION_KEY];
+    return notification?.type === "browser_handoff";
+}
+/** What the model gets for `err`, releasing the session if its connection may be dead. */
+async function failed(key, err) {
+    if (err instanceof StagehandFacadeInputError)
+        return `error: ${err.message}`;
+    if (err instanceof StagehandFacadeExecutionError) {
+        return `error: ${err.name}: ${err.message}`; // thrown by run code
+    }
+    // The connection may be dead, unless the browser answered or the facade turned
+    // away run code that does not parse, with a plain SyntaxError. Stagehand rejects
+    // a JSON-RPC error reply (Python's RPCError) with the reply, and its code, as cause.
+    const reply = err instanceof Error ? err.cause : null;
+    if (typeof reply?.code !== "number" && !(err instanceof SyntaxError)) {
+        await release(key);
+    }
+    return `error: ${sanitizeErrorMessage(errorText(err))}`;
+}
+/**
+ * Share the thread's sandbox's localhost with its browser, once that sandbox exists.
+ *
+ * Runs before every browser call. Only a thread's browser shares: a user's
+ * serves several threads, whose sandboxes cannot all be `localhost`.
+ */
+async function share(session, key, runtime) {
+    const sandbox = key.startsWith("thread:")
+        ? threadSandbox(runtime.backend)
+        : undefined;
+    if (sandbox === undefined || session.shared === sandbox)
+        return;
+    try {
+        await shareLocalhost(session.browser, sandbox.id);
+    }
+    catch (err) {
+        // Browsing goes on; tried again next call.
+        const label = logger.safeErrorLabel(err);
+        logger.warn(`could not share sandbox ${sandbox.id}'s localhost with ${session.browser} (${label})`);
+        return;
+    }
+    session.shared = sandbox;
+}
+/** The facade's tools as its hosts advertise them, names prefixed `browser_`. */
+function browserTools(options) {
+    const facade = (name) => {
+        const entry = FACADE_TOOLS.find((candidate) => candidate.name === name);
+        const { description, inputSchema: schema } = entry;
+        return { name: `browser_${name}`, description, schema };
+    };
+    const screenshot = facade("screenshot");
+    const path = { type: "string", description: SCREENSHOT_PATH };
+    const properties = { ...screenshot.schema.properties, path };
+    const run = tool(async (input, config) => {
+        const { code, actions } = input;
+        const runtime = config;
+        return call(options, runtime, async (session) => {
+            let value;
+            let saved;
+            try {
+                value =
+                    code === undefined
+                        ? await session.tools.runActions(actions)
+                        : await session.tools.run(code);
+            }
+            finally {
+                // Code that threw may have saved some first.
+                saved = await saveArtifacts(runtime.backend, session.artifacts);
+            }
+            return [JSON.stringify(value ?? null), ...saved].join("\n");
+        });
+    }, facade("run"));
+    const snapshot = tool(async (input, config) => {
+        const includeIframes = input.includeIframes ?? true;
+        return call(options, config, (session) => session.tools.snapshot({ includeIframes }));
+    }, facade("snapshot"));
+    const shoot = tool(async (input, config) => {
+        const { fullPage, type = "png", quality, path } = input;
+        const runtime = config;
+        const shot = await call(options, runtime, (session) => session.tools.screenshot({ fullPage, type, quality }));
+        if (typeof shot === "string")
+            return shot;
+        let text = "Screenshot of the current page.";
+        if (path) {
+            const data = Buffer.from(shot.data, "base64");
+            text += ` ${await save(runtime.backend, path, data)}`;
+        }
+        const url = `data:${shot.mimeType};base64,${shot.data}`;
+        return [
+            { type: "text", text },
+            { type: "image", url },
+        ];
+    }, { ...screenshot, schema: { ...screenshot.schema, properties } });
+    const handoff = tool(async (input, config) => handToUser(options, config, input.reason), {
+        name: "browser_handoff",
+        description: HANDOFF_DESCRIPTION,
+        schema: {
+            type: "object",
+            properties: {
+                reason: { type: "string" },
+            },
+            required: ["reason"],
+        },
+    });
+    return [run, snapshot, shoot, handoff, recordTool(options)];
+}
+/** `browser_record`: start recording the window's tab, or stop and save it. */
+function recordTool(options) {
+    return tool(async (input, config) => {
+        const runtime = config;
+        const found = locate(runtime, options.scope);
+        if (typeof found === "string")
+            return found;
+        const where = takeKey(found.key, found.window);
+        const { path } = input;
+        if (path !== undefined && !posix.isAbsolute(path)) {
+            // Before a take starts or ends, so none is lost.
+            if (input.action === "start") {
+                return `error: ${path} is not an absolute path. Recording not started.`;
+            }
+            return `error: ${path} not saved: give an absolute path. Still recording.`;
+        }
+        return withLock(where, async () => {
+            if (input.action === "start") {
+                if (runtime.backend == null) {
+                    return "error: this agent has no sandbox to save a recording in. Recording not started.";
+                }
+                return call(options, runtime, (session) => startRecording(session, where, runtime.backend, path));
+            }
+            const take = takes.get(where);
+            if (take === undefined) {
+                return ("error: not recording. A recording ends when the run ends or you " +
+                    "hand the browser to the user, and is saved where `start` said, " +
+                    `or under ${RECORDINGS}/.`);
+            }
+            takes.delete(where);
+            return finishTake(take, path || take.path);
+        });
+    }, {
+        name: "browser_record",
+        description: RECORD_DESCRIPTION,
+        schema: RECORD_SCHEMA,
+    });
+}
+/** Start recording the session's window, beside Chrome, unless it is already. */
+async function startRecording(session, where, backend, path) {
+    if (takes.has(where)) {
+        return "error: already recording. Stop this recording first.";
+    }
+    const tab = await newestTab(session.stagehand.browser.context);
+    try {
+        const box = await browserBox(session.browser);
+        const folder = await startTake(box, session.localUrl, tab.pageId);
+        takes.set(where, { browser: session.browser, folder, backend, path });
+    }
+    catch (err) {
+        if (!(err instanceof RecorderError))
+            throw err; // `call` answers the rest
+        return `error: ${sanitizeErrorMessage(err.message)}`; // the client is fine
+    }
+    const [width, height] = RECORD_VIEWPORT;
+    return (`Recording. The viewport is ${width}x${height} until you stop, ` +
+        "so take a browser_snapshot before acting on the page.");
+}
+/**
+ * Save the window's recording, if any, where `start` said or under recordings/.
+ * Call it under the window's lock.
+ *
+ * The run's end calls it, and so does `browser_handoff` before it hands the
+ * window over: the take is then saved, and the recorder has let go of the
+ * window, before the user has it, so a recording never shows what they do.
+ * Returns what `finishTake` does, or undefined if nothing was recording.
+ */
+async function endTake(key, window) {
+    const where = takeKey(key, window);
+    const take = takes.get(where);
+    if (take === undefined)
+        return undefined;
+    takes.delete(where);
+    let saved;
+    let why = "";
+    try {
+        saved = await finishTake(take, take.path);
+    }
+    catch (err) {
+        // The run ends, or the user gets the window, regardless.
+        why = ` (${logger.safeErrorLabel(err)})`;
+        saved = `error: ${sanitizeErrorMessage(errorText(err))}`;
+    }
+    if (typeof saved === "string") {
+        logger.warn(`could not save ${key}'s recording${why}`);
+    }
+    return saved;
+}
+/** `text`, then what became of the recording a handoff ended, if one was running. */
+function withRecording(text, ended) {
+    if (ended === undefined)
+        return text;
+    if (typeof ended === "string") {
+        return `${text}\nYour recording ended here: ${ended}`;
+    }
+    const [note, ...frames] = ended;
+    const said = `${text}\nYour recording ended here. ${note.text}`;
+    return [{ type: "text", text: said }, ...frames];
+}
+/**
+ * Stop `take` and save it to `path`, or under recordings/ if it can't be saved there.
+ *
+ * Returns what was saved and the first and last frames, for the model to check.
+ */
+async function finishTake(take, path) {
+    let finished;
+    try {
+        finished = await stopTake(await browserBox(take.browser), take.folder);
+    }
+    catch (err) {
+        return `error: ${sanitizeErrorMessage(errorText(err))}`;
+    }
+    const fallback = `${RECORDINGS}/${timestamp()}.mp4`;
+    let video = path || fallback;
+    let saved = await save(take.backend, video, finished.video);
+    if (saved.startsWith("error:")) {
+        // The browser's sandbox no longer has the take, so try once more, under recordings/.
+        const missed = sanitizeErrorMessage(saved.slice("error: ".length));
+        const moved = await save(take.backend, fallback, finished.video);
+        if (moved.startsWith("error:")) {
+            return `error: ${missed}. The recording is lost.`;
+        }
+        saved =
+            video === fallback ? moved : `${missed}. ${moved.slice(0, -1)} instead.`;
+        video = fallback;
+    }
+    const named = normpath(video);
+    const timeline = `${named.slice(0, named.length - posix.extname(named).length)}.json`;
+    const noted = await save(take.backend, timeline, finished.timeline);
+    const frame = (jpeg) => {
+        const data = Buffer.from(jpeg).toString("base64");
+        return { type: "image", url: `data:image/jpeg;base64,${data}` };
+    };
+    const megabytes = (finished.video.length / 1e6).toFixed(1);
+    const seconds = finished.seconds.toFixed(0);
+    let text = `${saved.slice(0, -1)}: ${seconds}s, ${megabytes} MB. ${noted}`;
+    if (finished.early)
+        text += ` ${finished.early}`;
+    text += `\nWhat happened, at video time:\n${finished.summary}`;
+    text += "\nIts first and last frames follow; check them before sharing it.";
+    return [{ type: "text", text }, frame(finished.first), frame(finished.last)];
+}
+/** The local time as Python's `time.strftime("%Y%m%d-%H%M%S")` writes it. */
+function timestamp(now = new Date()) {
+    const offset = now.getTimezoneOffset() * 60_000;
+    const local = new Date(now.getTime() - offset).toISOString();
+    return local.slice(0, 19).replace(/[-:]/g, "").replace("T", "-");
+}
+/** Where a window's take is kept in `takes`. */
+function takeKey(key, window) {
+    return JSON.stringify([key, window]);
+}
+function errorText(err) {
+    return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+}
+/** The facade's answer to run input it turns away; the page never sees it. */
+function invalidRun(args) {
+    if ((args.code === undefined) === (args.actions === undefined)) {
+        return "error: run requires exactly one of code or actions";
+    }
+    const { error } = CodeModeRunInputSchema.safeParse(args);
+    return error && `error: Invalid run input: ${error.issues[0]?.message}`;
+}
+function unexpected(names) {
+    const quoted = names.map((name) => `'${name}'`).join(", ");
+    return `error: unexpected argument${names.length > 1 ? "s" : ""} ${quoted}.`;
+}
+/** Move what the facade saved under `root` to the same relative path in /workspace. */
+async function saveArtifacts(backend, root) {
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    const files = entries.filter((entry) => entry.isFile());
+    const saved = [];
+    for (const path of files.map((f) => join(f.parentPath, f.name)).sort()) {
+        const data = await readFile(path);
+        await unlink(path);
+        const rel = relative(root, path).split(sep).join("/");
+        saved.push(await save(backend, `${WORKSPACE}/${rel}`, data));
+    }
+    return saved;
+}
+/** Write `data` to absolute `path` in the agent's sandbox, creating its folder. */
+export async function save(backend, path, data) {
+    if (backend == null) {
+        return `error: ${path} not saved: this agent has no sandbox.`;
+    }
+    if (!posix.isAbsolute(path)) {
+        return `error: ${path} not saved: give an absolute path.`;
+    }
+    const target = normpath(path);
+    let result;
+    try {
+        if (isSandboxBackend(backend)) {
+            await backend.execute(`mkdir -p -- ${shellQuote(posix.dirname(target))}`);
+        }
+        [result] = await backend.uploadFiles([[target, data]]);
+    }
+    catch (err) {
+        return `error: ${target} not saved: ${errorText(err)}`;
+    }
+    return result?.error
+        ? `error: ${target} not saved: ${result.error}`
+        : `Saved ${target}.`;
+}
+/** `path` as Python's `posixpath.normpath` writes it. */
+function normpath(path) {
+    return posix.normalize(path).replace(/(.)\/$/, "$1");
+}
+/** Under user scope, a person's browser; service principals stand for many people. */
+export function browserKey(serverInfo, thread, scope) {
+    if (scope === "user") {
+        const principal = serverInfo?.principal;
+        if (principal === undefined) {
+            throw new Error('browser scope "user" needs a signed-in user');
+        }
+        if (principal.kind === "person")
+            return `user:${principal.id}`;
+    }
+    return `thread:${thread}`;
+}
+/** The run's browser key and window, or the error that leaves it without them. */
+function locate(runtime, scope) {
+    const id = runtime.configurable?.thread_id;
+    if (!id)
+        return "error: browser use needs a thread_id";
+    const thread = String(id);
+    try {
+        const key = browserKey(runtime.serverInfo, thread, scope);
+        return { thread, key, window: windowName(key, thread) };
+    }
+    catch (err) {
+        return `error: ${err.message}`;
+    }
+}
+/**
+ * The run's sandbox once MDA has opened it; the browser never opens one.
+ *
+ * Tools see it through a lazy handle made fresh for each run, so the handle
+ * asks the process whether the box is open.
+ */
+export function threadSandbox(backend) {
+    const box = backend instanceof LazyManagedSandboxBackend ? backend.opened() : backend;
+    if (!isSandboxBackend(box) || box.id.startsWith("pending:"))
+        return undefined;
+    return box;
+}
+/** A thread's own browser has the one window `mda`; a user's, one per thread. */
+function windowName(key, thread) {
+    if (key.startsWith("thread:"))
+        return "mda";
+    return `mda-${createHash("sha256").update(thread).digest("hex").slice(0, 16)}`;
+}
+/** Run `fn` after `key`'s earlier calls, so calls on one browser take turns. */
+function withLock(key, fn) {
+    const result = (locks.get(key) ?? Promise.resolve()).then(fn);
+    const tail = result.then(() => { }).catch(() => { }); // settles once `fn` has
+    locks.set(key, tail);
+    tail.then(() => {
+        if (locks.get(key) === tail)
+            locks.delete(key); // no one is waiting
+    });
+    return result;
+}
+/** Close every session and stop its timer, and forget recordings, for tests. */
+export async function clearBrowserSessionsForTests() {
+    for (const timer of releases.values())
+        clearTimeout(timer);
+    releases.clear();
+    locks.clear();
+    takes.clear();
+    const open = [...sessions.values()];
+    sessions.clear();
+    await Promise.all(open.map(closeSession));
+}
+//# sourceMappingURL=browser.js.map