@theoremjs/studio 0.0.0-stage → 0.3.1

package/browser-connection.js

@@ -0,0 +1,215 @@
+import { TheoremError, z } from '@theoremjs/agents';
+import { GEMINI_MODELS_URL } from '@theoremjs/agents/presets/google';
+/** Which service a pasted key belongs to, from its published prefix; `undefined` when unknown. */
+export function keyKind(secret) {
+    const key = secret?.trim() ?? '';
+    if (key.startsWith('AIza'))
+        return 'gemini';
+    if (key.startsWith('sk-or-'))
+        return 'openrouter';
+    return undefined;
+}
+export function localStudioConfig(local) {
+    let url;
+    try {
+        url = new URL(local.baseUrl);
+    }
+    catch {
+        throw new TheoremError('config', 'Enter a valid localhost URL.');
+    } // labels-exempt: builder diagnostic
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new TheoremError('config', 'Use a localhost URL without credentials, query parameters or a fragment.'); // labels-exempt: builder diagnostic
+    }
+    return {
+        baseUrl: url.href.replace(/\/$/, ''),
+        // A token, when the model names a slot, comes from the vault through the adapter.
+        fetch: (input, init) => {
+            const target = new URL(input instanceof Request ? input.url : String(input));
+            if (target.origin !== url.origin) {
+                return Promise.reject(new TheoremError('blocked', 'Local requests must stay on the configured origin.')); // labels-exempt: builder diagnostic
+            }
+            return fetch(input, {
+                ...init,
+                redirect: 'error',
+                credentials: 'omit',
+            });
+        },
+    };
+}
+export const STUDIO_KEY_SLOT_CAP = 32;
+const localModelList = z.object({ data: z.array(z.object({ id: z.string().min(1) })) });
+/** The same localhost origin and transport used for inference; never a site proxy. */
+export async function listLocalStudioModels(local, signal) {
+    const config = localStudioConfig(local);
+    if (!config?.fetch)
+        throw new TheoremError('config', 'Enter a local endpoint.'); // labels-exempt: builder diagnostic
+    const response = await config.fetch(`${config.baseUrl}/v1/models`, {
+        signal,
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok)
+        throw new TheoremError('network', `Local model list returned HTTP ${response.status}.`); // labels-exempt: builder diagnostic
+    const parsed = localModelList.safeParse(await response.json());
+    if (!parsed.success)
+        throw new TheoremError('request', 'The endpoint returned an invalid model list.'); // labels-exempt: builder diagnostic
+    return [...new Set(parsed.data.data.map((model) => model.id))];
+}
+const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
+const OPENROUTER_EMBEDDING_MODELS_URL = 'https://openrouter.ai/api/v1/embeddings/models';
+export const KNOWN_GEMINI_EMBEDDING_MODELS = [
+    { id: 'gemini-embedding-2-preview', label: 'Gemini Embeddings 2 (preview)' },
+    { id: 'gemini-embedding-001', label: 'Gemini Embedding 001' },
+];
+export const KNOWN_OPENROUTER_EMBEDDING_MODELS = [
+    { id: 'liquid/lfm-2.5-embedding-350m:free', label: 'Liquid LFM 2.5 Embedding 350M (free)' },
+    { id: 'nvidia/nemotron-3-embed-1b:free', label: 'NVIDIA Nemotron 3 Embed 1B (free)' },
+    {
+        id: 'nvidia/llama-nemotron-embed-vl-1b-v2:free',
+        label: 'NVIDIA Llama Nemotron Embed VL 1B v2 (free)',
+    },
+];
+/**
+ * OpenRouter's `output_modalities` for each profile type: chat models for text, `/images` models
+ * for image, `/audio/speech` models for speech. OpenRouter has no live models.
+ */
+const OPENROUTER_OUTPUT = {
+    text: 'text',
+    image: 'image',
+    speech: 'speech',
+    live: undefined,
+    embedding: undefined,
+};
+const openRouterModelList = z.object({
+    data: z.array(z.object({
+        id: z.string().min(1),
+        name: z.string().optional(),
+        architecture: z.object({ output_modalities: z.array(z.string()).optional() }).optional(),
+    })),
+});
+const openRouterEmbeddingModelList = z.object({
+    data: z.array(z.object({ id: z.string().min(1), name: z.string().optional() })),
+});
+const geminiModelList = z.object({
+    models: z
+        .array(z.object({
+        name: z.string().min(1),
+        displayName: z.string().optional(),
+        supportedGenerationMethods: z.array(z.string()).optional(),
+    }))
+        .optional(),
+    nextPageToken: z.string().optional(),
+});
+/** Enough pages for every model a Gemini project lists; a runaway token stops here. */
+const GEMINI_MODEL_PAGES = 5;
+async function listedJson(provider, url, init) {
+    const response = await fetch(url, { ...init, redirect: 'error', credentials: 'omit' });
+    // Gemini answers a key it doesn't know with 400; the list's own query never earns one.
+    if (response.status === 400 || response.status === 401 || response.status === 403) {
+        throw new TheoremError('auth', `${provider} refused the key.`); // labels-exempt: builder diagnostic
+    }
+    if (!response.ok) {
+        throw new TheoremError('network', `${provider} model list returned HTTP ${response.status}.`); // labels-exempt: builder diagnostic
+    }
+    return await response.json();
+}
+/**
+ * The models a provider offers for a profile type, fetched from the browser with the key in this
+ * tab, never through the site. OpenRouter lists without a key and says what each model returns, so
+ * its list keeps only models of the profile's kind. Gemini needs the key and says only which calls
+ * a model takes, so its list keeps the models that answer a turn (live models for live).
+ */
+export async function listProviderModels(provider, profileType, key, signal) {
+    const secret = key?.trim();
+    if (profileType === 'embedding' && !secret) {
+        return [
+            ...(provider === 'openrouter'
+                ? KNOWN_OPENROUTER_EMBEDDING_MODELS
+                : KNOWN_GEMINI_EMBEDDING_MODELS),
+        ];
+    }
+    if (provider === 'openrouter')
+        return await listOpenRouterModels(profileType, secret, signal);
+    if (!secret)
+        throw new TheoremError('auth', 'Choose a key to list Gemini models.'); // labels-exempt: builder diagnostic
+    return await listGeminiModels(profileType, secret, signal);
+}
+/** OpenRouter's models of the profile's kind; the key is optional. */
+async function listOpenRouterModels(profileType, secret, signal) {
+    const init = {
+        signal,
+        headers: {
+            Accept: 'application/json',
+            ...(secret ? { Authorization: ['Bearer', secret].join(' ') } : {}),
+        },
+    };
+    if (profileType === 'embedding') {
+        const parsed = openRouterEmbeddingModelList.safeParse(await listedJson('OpenRouter', OPENROUTER_EMBEDDING_MODELS_URL, init));
+        if (!parsed.success)
+            throw new TheoremError('bad_response', 'OpenRouter returned an invalid embedding model list.'); // labels-exempt: builder diagnostic
+        return parsed.data.data.map((model) => ({ id: model.id, label: model.name ?? model.id }));
+    }
+    const output = OPENROUTER_OUTPUT[profileType];
+    if (!output)
+        return [];
+    const parsed = openRouterModelList.safeParse(await listedJson('OpenRouter', `${OPENROUTER_MODELS_URL}?output_modalities=${output}`, init));
+    if (!parsed.success)
+        throw new TheoremError('bad_response', 'OpenRouter returned an invalid model list.'); // labels-exempt: builder diagnostic
+    return parsed.data.data
+        .filter((model) => model.architecture?.output_modalities?.includes(output) ?? true)
+        .map((model) => ({ id: model.id, label: model.name ?? model.id }));
+}
+/** The Gemini method a profile type's models must take. */
+const GEMINI_METHOD = {
+    live: 'bidiGenerateContent',
+    embedding: 'embedContent',
+};
+/** The key's Gemini models that take the profile type's method, page by page. */
+async function listGeminiModels(profileType, secret, signal) {
+    const method = GEMINI_METHOD[profileType] ?? 'generateContent';
+    const models = [];
+    let pageToken;
+    for (let page = 0; page < GEMINI_MODEL_PAGES; page++) {
+        const url = new URL(GEMINI_MODELS_URL);
+        url.searchParams.set('pageSize', '1000');
+        if (pageToken)
+            url.searchParams.set('pageToken', pageToken);
+        const parsed = geminiModelList.safeParse(await listedJson('Google', url.href, {
+            signal,
+            headers: { Accept: 'application/json', 'x-goog-api-key': secret },
+        }));
+        if (!parsed.success)
+            throw new TheoremError('bad_response', 'Google returned an invalid model list.'); // labels-exempt: builder diagnostic
+        for (const model of parsed.data.models ?? []) {
+            if (!model.supportedGenerationMethods?.includes(method))
+                continue;
+            const id = model.name.replace(/^models\//, '');
+            models.push({ id, label: model.displayName ?? id });
+        }
+        pageToken = parsed.data.nextPageToken;
+        if (!pageToken)
+            break;
+    }
+    return models;
+}
+/** Slot references come from the compiled contract, including each model's overrides. */
+export function studioKeySlots(profile) {
+    return [
+        ...new Set([
+            profile.key,
+            profile.fallbackKey,
+            ...Object.values(profile.models ?? {}).flatMap((model) => [
+                model.keySlot,
+                model.fallbackKeySlot,
+            ]),
+        ].filter((slot) => Boolean(slot))),
+    ];
+}
+/** Defines even empty referenced slots, so names such as `constructor` never read inherited values. */
+export function studioVault(slots, vault) {
+    return Object.fromEntries(slots.map((slot) => [slot, Object.hasOwn(vault, slot) ? vault[slot] : undefined]));
+}

package/browser-engine.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What a run in the page runs on: the kernel's engine and the session machinery around it. The
+ * page's transports load it on their first call, so a studio that never runs in the page never
+ * downloads it.
+ *
+ * @module
+ */
+export { createMemorySteerInbox, createSealedConversationStore, liveSessionOpen, parseLiveOpenMessage, steerUnitOf, } from '@theoremjs/react/server';
+export { browserExecution } from './browser-execution.ts';
+export { attachStudioLiveSession } from './live-session-bridge.ts';
+export { rewindStudio, runStudioDecision, runStudioEmbedding, streamStudioCall, streamStudioHostInvoke, streamStudioInvoke, streamStudioTurn, studioConversation, studioScope, studioTraces, } from './runtime.ts';

package/browser-engine.js

@@ -0,0 +1,11 @@
+/**
+ * What a run in the page runs on: the kernel's engine and the session machinery around it. The
+ * page's transports load it on their first call, so a studio that never runs in the page never
+ * downloads it.
+ *
+ * @module
+ */
+export { createMemorySteerInbox, createSealedConversationStore, liveSessionOpen, parseLiveOpenMessage, steerUnitOf, } from '@theoremjs/react/server';
+export { browserExecution } from "./browser-execution.js";
+export { attachStudioLiveSession } from "./live-session-bridge.js";
+export { rewindStudio, runStudioDecision, runStudioEmbedding, streamStudioCall, streamStudioHostInvoke, streamStudioInvoke, streamStudioTurn, studioConversation, studioScope, studioTraces, } from "./runtime.js";

package/browser-execution.d.ts

@@ -0,0 +1,6 @@
+export declare function browserExecution(): {
+    boundary: Promise<import("@theoremjs/react/server").TheoremSessionBoundary>;
+    execution: import("../mod").ToolExecutionCoordinator;
+    pageExecution: import("../mod").PageToolExecution;
+    pageResult: (result: import("@theoremjs/react/server").PageToolResult) => Promise<boolean>;
+};

package/browser-execution.js

@@ -0,0 +1,18 @@
+import { createMemoryPageToolBroker, createMemorySessionStore, createTheoremSessionBoundary, DEFAULT_OPERATION_RETENTION_MS, resolveSessionLimits, sessionPageDispatch, sessionStateStore, sessionToolCoordinator, } from '@theoremjs/react/server';
+export function browserExecution() {
+    const id = crypto.randomUUID();
+    const memory = createMemorySessionStore();
+    const boundary = createTheoremSessionBoundary({
+        request: new Request('https://studio.local'),
+        session: () => id,
+        sessionStore: memory,
+    });
+    const store = sessionStateStore(memory, 30 * 60_000, DEFAULT_OPERATION_RETENTION_MS, resolveSessionLimits());
+    const page = sessionPageDispatch(store, id, createMemoryPageToolBroker());
+    return {
+        boundary,
+        execution: sessionToolCoordinator(store, id),
+        pageExecution: page.execution,
+        pageResult: page.answer,
+    };
+}

package/browser-live.d.ts

@@ -0,0 +1,4 @@
+import type { LiveConnection } from '@theoremjs/react/client';
+import { type StudioBrowserRuntime } from './browser-transport.ts';
+import type { StudioRunPayload } from './run-payload.ts';
+export declare function browserStudioLiveConnection(payload: StudioRunPayload, runtime: StudioBrowserRuntime): LiveConnection;

package/browser-live.js

@@ -0,0 +1,132 @@
+import { TheoremError } from '@theoremjs/agents';
+import { clientError } from '@theoremjs/agents/host';
+import { browserEngine } from "./browser-transport.js";
+import { STUDIO_READER } from "./reader.js";
+/** The Live UI's existing relay protocol, carried in memory instead of over a site socket. */
+class BrowserLiveSocket {
+    readyState = 0;
+    binaryType = 'arraybuffer';
+    onopen = null;
+    onmessage = null;
+    onclose = null;
+    onerror = null;
+    outbound = new EventTarget();
+    closeSession;
+    queued = [];
+    listening = false;
+    constructor(payload, runtime, local) {
+        // Install the UI's handlers before the first ready/error message.
+        queueMicrotask(() => {
+            void this.open(payload, runtime, local);
+        });
+    }
+    send(data) {
+        if (this.readyState !== 1) {
+            throw new TheoremError('network', 'Live connection is closed'); // labels-exempt: internal diagnostic
+        }
+        if (!this.listening)
+            this.queued.push(data);
+        else
+            this.outbound.dispatchEvent(new MessageEvent('message', { data }));
+    }
+    close() {
+        if (this.readyState === 3)
+            return;
+        this.readyState = 3;
+        this.queued = [];
+        this.outbound.dispatchEvent(new Event('close'));
+        void this.closeSession?.();
+        this.emit('onclose', new CloseEvent('close'));
+    }
+    emit(kind, event) {
+        // Native socket callbacks carry a WebSocket `this`; these callbacks only read the event.
+        const callback = this[kind];
+        callback?.(event);
+    }
+    async open(payload, runtime, local) {
+        if (this.readyState === 3)
+            return;
+        this.readyState = 1;
+        this.emit('onopen', new Event('open'));
+        let traces;
+        try {
+            const run = await browserEngine();
+            const page = local?.(run);
+            traces = run.studioTraces.route((record) => this.receive({ type: 'trace', record }));
+            const { scope, profile } = await run.studioScope(payload.profile, payload.customTools, payload.structured, runtime);
+            if (!runtime.providers?.vault) {
+                throw new TheoremError('auth', 'Fill the vault slot this model names.'); // labels-exempt: builder diagnostic
+            }
+            // The client sends its open message as the socket opens: the call's slots, context, and resume.
+            const [first] = this.queued.splice(0, 1);
+            if (typeof first !== 'string') {
+                throw new TheoremError('request', 'A live call must open with its open message'); // labels-exempt: internal diagnostic
+            }
+            const session = await scope.runSession({
+                ...(await (page
+                    ? (await page.boundary).prepareLiveOpen(run.parseLiveOpenMessage(first))
+                    : Promise.resolve(run.liveSessionOpen(run.parseLiveOpenMessage(first))))),
+                profile: profile.id,
+                metadata: traces.metadata,
+                signal: runtime.signal,
+            }, {
+                execution: runtime.execution ?? page?.execution,
+                pageExecution: runtime.pageExecution ?? page?.pageExecution,
+                vault: runtime.providers.vault,
+                fetch: runtime.providers.fetch,
+                wait: runtime.providers.wait,
+                openWebSocket: runtime.providers.openWebSocket,
+            });
+            this.closeSession = () => session.close('client disconnected');
+            if (this.readyState !== 1) {
+                await this.closeSession();
+                traces.close();
+                return;
+            }
+            await this.attach(run.attachStudioLiveSession, session, profile.id, traces, profile.labels, page
+                ? {
+                    pageResult: page.pageResult,
+                    beforeEvent: async (event) => {
+                        if ((event.type === 'done' || event.type === 'provider_checkpoint') &&
+                            event.providerState)
+                            await (await page.boundary).recordCheckpoint(event.providerState);
+                    },
+                }
+                : {});
+        }
+        catch (err) {
+            traces?.close();
+            this.receive({ type: 'error', ...clientError(err, payload.profile.labels, STUDIO_READER) });
+            this.close();
+        }
+    }
+    async attach(attachStudioLiveSession, session, profileId, traces, labels, options = {}) {
+        const socket = {
+            send: (data) => {
+                if (typeof data === 'string')
+                    this.receive(JSON.parse(data));
+            },
+            close: () => this.close(),
+            addEventListener: this.outbound.addEventListener.bind(this.outbound),
+        };
+        const ended = attachStudioLiveSession(socket, session, profileId, crypto.randomUUID(), traces, labels, { ...options, clientEvents: STUDIO_READER });
+        this.closeSession = undefined;
+        this.listening = true;
+        for (const data of this.queued.splice(0)) {
+            this.outbound.dispatchEvent(new MessageEvent('message', { data }));
+        }
+        await ended;
+    }
+    receive(message) {
+        if (this.readyState === 1) {
+            this.emit('onmessage', new MessageEvent('message', { data: JSON.stringify(message) }));
+        }
+    }
+}
+export function browserStudioLiveConnection(payload, runtime) {
+    // The in-process connection knows its draft, so its open message carries none.
+    // The page's sessions are made once, by the first call, from the engine that call loaded.
+    let page;
+    const local = runtime.execution ? undefined : (run) => (page ??= run.browserExecution());
+    return { createSocket: () => new BrowserLiveSocket(payload, runtime, local) };
+}

package/browser-transport.d.ts

@@ -0,0 +1,33 @@
+import type { RunDecisionOptions } from '@theoremjs/agents/kernel';
+import { type DecisionTransport, type EmbeddingTransport, type HostTransport, type TheoremTransport, type TraceFeed } from '@theoremjs/react/client';
+import type { StudioRunPayload } from './run-payload.ts';
+import type { StudioRuntimeBase } from './runtime-scope.ts';
+/**
+ * The engine a run in the page runs on, loaded once. A connection asks for it as it is made, so
+ * the first run waits on nothing; a studio that never runs in the page never downloads it.
+ */
+export declare const browserEngine: () => Promise<typeof import("./browser-engine.ts")>;
+/** A run in the page: on the builder's own keys or machine, never on lent keys. */
+export interface StudioBrowserRuntime extends StudioRuntimeBase {
+    mode: 'byok' | 'local';
+    decision?: Pick<RunDecisionOptions, 'vault' | 'fetch'>;
+    /** Disconnecting aborts active requests, without retaining the vault in a saved payload. */
+    signal?: AbortSignal;
+}
+/**
+ * A chat run in the page. Its conversation is sealed with `conversationKey`,
+ * a key the tab keeps, so every transport of the tab opens the same refs.
+ */
+export declare function createBrowserStudioTransport(payload: StudioRunPayload, runtime: StudioBrowserRuntime, options: {
+    conversationKey: string;
+    traces?: TraceFeed;
+}): TheoremTransport;
+export declare function createBrowserStudioHostTransport(payload: StudioRunPayload, runtime: StudioBrowserRuntime, options?: {
+    traces?: TraceFeed;
+}): HostTransport;
+export declare function createBrowserStudioDecisionTransport(payload: StudioRunPayload, runtime: StudioBrowserRuntime, options?: {
+    traces?: TraceFeed;
+}): DecisionTransport;
+export declare function createBrowserStudioEmbeddingTransport(payload: StudioRunPayload, runtime: StudioBrowserRuntime, options?: {
+    traces?: TraceFeed;
+}): EmbeddingTransport;

package/browser-transport.js

@@ -0,0 +1,229 @@
+import { defineProfile, TheoremError } from '@theoremjs/agents';
+import { clientError, forClient } from '@theoremjs/agents/host';
+import { createTraceFeed, decisionInterface, embeddingInterface, failedTraces, hostError, hostInterface, isTheoremStreamError, withFailedTraces, } from '@theoremjs/react/client';
+import { STUDIO_READER } from "./reader.js";
+import { hostCallLines, routeStudioLines, studioInterface, } from "./transport.js";
+let engine;
+/**
+ * The engine a run in the page runs on, loaded once. A connection asks for it as it is made, so
+ * the first run waits on nothing; a studio that never runs in the page never downloads it.
+ */
+export const browserEngine = () => (engine ??= import("./browser-engine.js"));
+/** The lines `open` streams once `ready` settles: a run's lines wait for the engine it runs on. */
+async function* after(ready, open) {
+    yield* open(await ready);
+}
+/** The run's signal: the disconnect's and the request's, either of which aborts it. */
+function runSignal(runtime, signal) {
+    return AbortSignal.any([runtime.signal, signal].filter((each) => each !== undefined));
+}
+/** A failure of a run made in the page, as the studio's reader has it. */
+function failed(error, payload) {
+    return hostError(clientError(error, payload.profile.labels, STUDIO_READER), 'internal');
+}
+/** Direct streams use the same event and trace routing as the HTTP transport. */
+async function deliver(source, payload, sink) {
+    try {
+        for await (const line of source) {
+            const read = line.type === 'trace' || line.type === 'steer_inbox' || line.type === 'conversation'
+                ? line
+                : forClient(line, STUDIO_READER);
+            if (read.type === 'error')
+                throw hostError(read, 'internal');
+            sink(read);
+        }
+    }
+    catch (error) {
+        throw isTheoremStreamError(error) ? error : failed(error, payload);
+    }
+}
+/** A page tool's answer goes to the page's own sessions, once the engine they live in has loaded. */
+function localPageResult(runtime, local) {
+    return runtime.execution
+        ? undefined
+        : async (result) => {
+            await (await local())?.pageResult(result);
+        };
+}
+function withBrowserExecution(runtime, run) {
+    const local = runtime.execution ? undefined : run.browserExecution();
+    if (local) {
+        const original = runtime;
+        runtime = {
+            mode: original.mode,
+            providers: original.providers,
+            providerDefinitions: original.providerDefinitions,
+            decision: original.decision,
+            signal: original.signal,
+            resolveHost: original.resolveHost?.bind(original),
+            remoteTools: original.remoteTools,
+            hostOptions: original.hostOptions?.bind(original),
+            provider: original.provider?.bind(original),
+            onAgentCall: original.onAgentCall?.bind(original),
+            execution: local.execution,
+            pageExecution: local.pageExecution,
+        };
+    }
+    return { runtime, local };
+}
+/** The one session a page's conversations open in: the tab holds the key, so only its refs open. */
+const PAGE_SESSION = 'studio-page';
+/**
+ * A chat run in the page. Its conversation is sealed with `conversationKey`,
+ * a key the tab keeps, so every transport of the tab opens the same refs.
+ */
+export function createBrowserStudioTransport(payload, runtime, options) {
+    const traces = options.traces ?? createTraceFeed();
+    // The engine starts loading as the transport is made, when the builder connects.
+    const session = browserEngine().then((run) => ({
+        run,
+        ...withBrowserExecution(runtime, run),
+        steer: run.createMemorySteerInbox(),
+        conversations: {
+            sessionId: PAGE_SESSION,
+            store: run.createSealedConversationStore({
+                keys: { 1: options.conversationKey },
+                keyVersion: 1,
+            }),
+        },
+    }));
+    // why: a failed load surfaces on the run that awaits it, not as an unhandled rejection.
+    session.catch(() => { });
+    const inboxes = new Map();
+    const compiled = {
+        profile: payload.profile,
+        customTools: payload.customTools,
+        structured: payload.structured,
+        dependencies: payload.dependencies,
+    };
+    const route = (onLine, onInbox = (_inbox) => { }) => routeStudioLines(onLine, traces, onInbox);
+    /** A request the page answers at once: its failure as the studio's reader has it. */
+    const answered = async (answer) => {
+        try {
+            return await answer();
+        }
+        catch (error) {
+            throw failed(error, payload);
+        }
+    };
+    return {
+        pageResult: localPageResult(runtime, async () => (await session).local),
+        describe: () => Promise.resolve(studioInterface(payload)),
+        async turn(request, onEvent, signal) {
+            try {
+                await deliver(after(session, ({ run, runtime: inPage, conversations, steer }) => run.streamStudioTurn({
+                    ...compiled,
+                    runtime: inPage,
+                    request,
+                    conversations,
+                    signal: runSignal(runtime, signal),
+                    steer,
+                })), payload, route(onEvent, (inbox) => {
+                    if (request.turnId)
+                        inboxes.set(request.turnId, inbox);
+                }));
+            }
+            finally {
+                if (request.turnId)
+                    inboxes.delete(request.turnId);
+            }
+        },
+        invoke: (answer, onEvent, signal) => deliver(after(session, ({ run, runtime: inPage, conversations }) => run.streamStudioInvoke({
+            ...compiled,
+            runtime: inPage,
+            answer,
+            conversations,
+            signal: runSignal(runtime, signal),
+        })), payload, route(onEvent)),
+        conversation: (request) => answered(async () => {
+            const { run, runtime: inPage, conversations } = await session;
+            return run.studioConversation({ ...compiled, runtime: inPage }, conversations, request);
+        }),
+        rewind: (request, signal) => answered(async () => {
+            const { run, runtime: inPage, conversations } = await session;
+            return run.rewindStudio({ ...compiled, runtime: inPage }, conversations, request, runSignal(runtime, signal));
+        }),
+        async steer(request) {
+            const inbox = inboxes.get(request.turnId);
+            const { run, steer } = await session;
+            if (!inbox || !(await steer.enqueue(inbox, run.steerUnitOf(request)))) {
+                throw new TheoremError('request', 'The turn has ended', {
+                    copy: { key: 'session.turn_ended' },
+                }); // labels-exempt: internal diagnostic
+            }
+        },
+        traces,
+    };
+}
+export function createBrowserStudioHostTransport(payload, runtime, options = {}) {
+    const traces = options.traces ?? createTraceFeed();
+    let sessionPermissions = [];
+    let prepared;
+    /** The engine and the page's sessions, made on the first call and kept for the rest. */
+    const prepare = () => (prepared ??= browserEngine().then((run) => ({ run, ...withBrowserExecution(runtime, run) })));
+    const compiled = {
+        profile: payload.profile,
+        customTools: payload.customTools,
+        dependencies: payload.dependencies,
+    };
+    const route = (onEvent) => routeStudioLines(hostCallLines(onEvent), traces, () => { });
+    return {
+        pageResult: localPageResult(runtime, async () => (await prepare()).local),
+        describe: () => Promise.resolve(hostInterface(defineProfile(payload.profile), (name) => payload.customTools.find((tool) => tool.name === name))),
+        call: (call, onEvent, signal) => deliver(after(prepare(), ({ run, runtime: inPage }) => run.streamStudioCall({
+            ...compiled,
+            runtime: inPage,
+            call,
+            sessionPermissions,
+            signal: runSignal(runtime, signal),
+        })), payload, route(onEvent)),
+        invoke(answer, onEvent, signal) {
+            sessionPermissions = answer.replay?.sessionPermissions ?? sessionPermissions;
+            return deliver(after(prepare(), ({ run, runtime: inPage }) => run.streamStudioHostInvoke({
+                ...compiled,
+                runtime: inPage,
+                answer,
+                signal: runSignal(runtime, signal),
+            })), payload, route(onEvent));
+        },
+        traces,
+    };
+}
+export function createBrowserStudioDecisionTransport(payload, runtime, options = {}) {
+    const traces = options.traces ?? createTraceFeed();
+    return {
+        describe: () => Promise.resolve(decisionInterface(defineProfile(payload.profile), payload.questions ?? {}, payload.images)),
+        decide: async (state, signal, assets) => {
+            try {
+                const run = await browserEngine();
+                return await run.runStudioDecision(payload, state, runtime.decision ?? {}, runSignal(runtime, signal), assets);
+            }
+            catch (err) {
+                // The failure keeps the trace the kernel left.
+                throw withFailedTraces(failed(err, payload), failedTraces(err));
+            }
+        },
+        traces,
+    };
+}
+export function createBrowserStudioEmbeddingTransport(payload, runtime, options = {}) {
+    const traces = options.traces ?? createTraceFeed();
+    return {
+        describe: () => Promise.resolve(embeddingInterface(defineProfile(payload.profile))),
+        embed: async (input, embed, signal) => {
+            try {
+                const run = await browserEngine();
+                const response = await run.runStudioEmbedding(payload, {
+                    input,
+                    ...embed,
+                    signal: runSignal(runtime, signal),
+                }, withBrowserExecution(runtime, run).runtime);
+                return { result: response.result, traces: response.traces };
+            }
+            catch (error) {
+                throw withFailedTraces(failed(error, payload), failedTraces(error));
+            }
+        },
+        traces,
+    };
+}

package/browser.d.ts

@@ -0,0 +1,4 @@
+export { KNOWN_GEMINI_EMBEDDING_MODELS, KNOWN_OPENROUTER_EMBEDDING_MODELS, keyKind, type ListedProfileType, type ListedProvider, listLocalStudioModels, listProviderModels, localStudioConfig, type ProviderModel, STUDIO_KEY_SLOT_CAP, type StudioBrowserConnection, studioKeySlots, studioVault, } from './browser-connection.ts';
+export { browserStudioLiveConnection } from './browser-live.ts';
+export { createBrowserStudioDecisionTransport, createBrowserStudioEmbeddingTransport, createBrowserStudioHostTransport, createBrowserStudioTransport, type StudioBrowserRuntime, } from './browser-transport.ts';
+export { attachStudioLiveSession } from './live-session-bridge.ts';