@theoremjs/studio 0.0.0-stage → 0.3.2

package/held-credentials.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A tool's credentials stay with the project. The page gets the tool's URLs and headers with
+ * their credentials masked, and a mask it sends back is filled in from what the project holds:
+ * the tool it registered for a run, the file's own text for a Save.
+ *
+ * @module
+ */
+/** A tool as the page gets it: the credentials in its URLs and headers masked. */
+export declare function withoutCredentials<T extends object>(tool: T): T;
+/**
+ * What a provider connects with, as the page gets it: its addresses with any credential masked.
+ * Only what is text is told; a provider defined with nothing has nothing to tell.
+ */
+export declare function shownConnection(connection: unknown): Record<string, string> | undefined;
+/**
+ * Why a provider cannot run or be saved, when what it connects with shows a mask. A provider's
+ * credential is its key slot's, so a mask here stands for nothing the project holds.
+ */
+export declare function unheldConnection(id: string, connection: Record<string, string> | undefined): string | undefined;
+/** One setting of a tool the page sent, each mask in it filled in from `held`, the project's own. */
+export declare function heldSetting(key: string, shown: unknown, held: unknown): unknown;
+/**
+ * The credentials `tool` shows masked that nothing holds a value for: every mask, or with
+ * `opened`, the tool as the page got it, the masks that were not there.
+ */
+export declare function unheld(tool: object, opened?: object): string[];
+/** Why a tool cannot run or be saved, when it shows a credential nothing holds a value for. */
+export declare function unheldProblem(name: string, tool: object, opened?: object): string | undefined;

package/held-credentials.js

@@ -0,0 +1,87 @@
+/**
+ * A tool's credentials stay with the project. The page gets the tool's URLs and headers with
+ * their credentials masked, and a mask it sends back is filled in from what the project holds:
+ * the tool it registered for a run, the file's own text for a Save.
+ *
+ * @module
+ */
+import { MASK, maskHeaders, maskUrl, unmaskHeaders, unmaskUrl } from '@theoremjs/agents/surface';
+const URLS = ['endpoint', 'serverUrl'];
+/** What a held URL is told as in a refusal: a mask in a URL has no name of its own to give. */
+const URL_LABELS = {
+    endpoint: 'its endpoint URL',
+    serverUrl: 'its server URL',
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A tool as the page gets it: the credentials in its URLs and headers masked. */
+export function withoutCredentials(tool) {
+    const shown = { ...tool };
+    for (const key of URLS) {
+        const url = shown[key];
+        if (typeof url === 'string')
+            shown[key] = maskUrl(url);
+    }
+    if (isRecord(shown.headers))
+        shown.headers = maskHeaders(shown.headers);
+    return shown;
+}
+/**
+ * What a provider connects with, as the page gets it: its addresses with any credential masked.
+ * Only what is text is told; a provider defined with nothing has nothing to tell.
+ */
+export function shownConnection(connection) {
+    if (!isRecord(connection))
+        return undefined;
+    const shown = Object.entries(connection).flatMap(([key, value]) => typeof value === 'string' ? [[key, maskUrl(value)]] : []);
+    return shown.length > 0 ? Object.fromEntries(shown) : undefined;
+}
+/**
+ * Why a provider cannot run or be saved, when what it connects with shows a mask. A provider's
+ * credential is its key slot's, so a mask here stands for nothing the project holds.
+ */
+export function unheldConnection(id, connection) {
+    const names = Object.entries(connection ?? {}).flatMap(([name, value]) => value.includes(MASK) ? [name] : []);
+    return names.length
+        ? `${id}: the studio has no value for ${names.join(', ')}. A provider's key comes from its key slot. Write the address without one.` // labels-exempt: builder diagnostic
+        : undefined;
+}
+/** One setting of a tool the page sent, each mask in it filled in from `held`, the project's own. */
+export function heldSetting(key, shown, held) {
+    if (URLS.includes(key) && typeof shown === 'string') {
+        return typeof held === 'string' ? unmaskUrl(shown, held) : shown;
+    }
+    if (key === 'headers' && isRecord(shown)) {
+        return unmaskHeaders(shown, isRecord(held) ? held : undefined);
+    }
+    return shown;
+}
+/**
+ * The credentials `tool` shows masked that nothing holds a value for: every mask, or with
+ * `opened`, the tool as the page got it, the masks that were not there.
+ */
+export function unheld(tool, opened) {
+    const [shown, before] = [tool, (opened ?? {})];
+    const names = [];
+    for (const key of URLS) {
+        const [url, was] = [shown[key], before[key]];
+        if (typeof url !== 'string')
+            continue;
+        // A mask the opened URL had is one the project holds; any text stands in for its value here.
+        const filled = unmaskUrl(url, typeof was === 'string' ? was.replaceAll(MASK, 'held') : '');
+        if (filled.includes(MASK))
+            names.push(URL_LABELS[key] ?? key);
+    }
+    const was = isRecord(before.headers) ? before.headers : {};
+    for (const [name, value] of Object.entries(isRecord(shown.headers) ? shown.headers : {})) {
+        if (value === MASK && was[name] !== MASK)
+            names.push(name);
+    }
+    return names;
+}
+/** Why a tool cannot run or be saved, when it shows a credential nothing holds a value for. */
+export function unheldProblem(name, tool, opened) {
+    const names = unheld(tool, opened);
+    return names.length
+        ? `${name}: the studio has no value for ${names.join(', ')}. It fills in only what the project's file holds. Write the value there, or put it under Auth.` // labels-exempt: builder diagnostic
+        : undefined;
+}

package/installed.mjs

@@ -0,0 +1,40 @@
+/**
+ * Stops with the install line when a package the studio runs on is missing. The studio is opt-in:
+ * nothing installs it with the kernel, so its commands check for it and never install it themselves.
+ * The packages resolve from here as the studio's own code finds them: beside it in the repo, or
+ * in the project's install when the studio is installed from the registry.
+ */
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BUILT_PAGE } from './page.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+/** Whether this is the installed package, with its page built. The repo's page is built as it is served. */
+export const builtPage = existsSync(path.join(here, BUILT_PAGE, 'index.html'));
+/** What the project's server runs on, and in the repo what Vite builds the page from. */
+const NEEDED = [
+  'zod',
+  '@theoremjs/agents',
+  '@theoremjs/react',
+  ...(builtPage ? [] : ['react', 'react-dom', '@astryxdesign/core', 'vite']),
+];
+
+/** Whether `name` is installed where Node would look for it from here; its exports need not list its manifest. */
+const installed = (name) =>
+  (require.resolve.paths(name) ?? []).some((dir) =>
+    existsSync(path.join(dir, name, 'package.json')),
+  );
+const missing = NEEDED.filter((name) => !installed(name));
+if (missing.length) {
+  const line = here.split(path.sep).includes('node_modules')
+    ? `npm install ${missing.join(' ')}`
+    : `npm install --prefix ${here}`;
+  console.error(
+    `The studio is missing ${missing.join(', ')}. Install it once, then run this again:\n\n  ${line}\n`,
+  );
+  process.exit(1);
+}

package/lent-keys.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Keys a page lends to whoever opens its studio. The studio runs agents on them for anyone, so it
+ * holds those runs to what the page says its keys allow. A studio given none has no such runs:
+ * it runs on the builder's own keys, their own machine, or their project.
+ *
+ * @module
+ */
+import type { TaintGate } from '@theoremjs/agents/guardrails';
+import type { DecisionQuestion } from '@theoremjs/agents/kernel';
+import type { ModelBindingDraft, StudioProfileType } from './draft.ts';
+import type { ModelRoute } from './providers.ts';
+/** An agent type that runs on a model. */
+export type ModelProfileType = Exclude<StudioProfileType, 'host'>;
+/** Where a new model of `type` starts: its provider and API model. */
+export type ModelStart = (type: ModelProfileType) => Pick<ModelBindingDraft, 'protocol' | 'provider' | 'apiId'>;
+/** What switching an agent's type reads from lent keys: each type's models, and where a new one starts. */
+export type ModelPicks = Pick<LentKeys, 'models' | 'start'>;
+/** A model the lent keys offer, as a picker lists it. */
+export interface LentModel {
+    id: string;
+    label: string;
+}
+/** A binding as these checks read it: its route and its built-ins. */
+export type LentBinding = ModelRoute & Pick<ModelBindingDraft, 'builtInTools'>;
+/** What is wrong with a binding, on the field that holds it. */
+export interface ModelBindingViolation {
+    field: 'provider' | 'apiId' | 'builtInTools';
+    message: string;
+}
+/** The most a decision sent on the lent keys may hold. */
+export interface LentDecisionLimits {
+    questions: number;
+    /** Options or levels in one question. */
+    criteria: number;
+    instructionsChars: number;
+    criterionChars: number;
+    /** Question ids, option labels, model ids, and the handle. */
+    nameChars: number;
+    /** The profile id, the contract, and the API model. */
+    idChars: number;
+    stateBytes: number;
+    /** Images one decision may carry; 0 takes none, and a box question then has nothing to read. */
+    images: number;
+    /** The most one image may weigh, in bytes, before it is encoded. */
+    imageBytes: number;
+    timeoutMs: number;
+}
+/** What runs on lent keys keep to, whatever a profile says. The editor notes each where it is set. */
+export interface LentHolds {
+    /** Runs reach public hosts only: a profile's network rules give way to the kernel's default. */
+    publicHostsOnly: boolean;
+    /** The calls a turn refuses once it has read a remote result. A profile that refuses more keeps its own. */
+    afterRemoteRead: TaintGate;
+}
+/** A page's lent keys, and what runs on them. */
+export interface LentKeys {
+    /** The models a binding of `type` may pick on a provider from `definition`, in order. */
+    models(type: ModelProfileType, definition: string | undefined): readonly LentModel[];
+    /** Whether the keys run agents of `type` on a provider from `definition`. */
+    runs(type: ModelProfileType, definition: string | undefined): boolean;
+    /** The binding a new model of `type` starts on. */
+    start: ModelStart;
+    /** Why `binding` can't run on the keys; `null` when it can. */
+    violation(binding: LentBinding): ModelBindingViolation | null;
+    /** The built-ins `apiId` may use on the keys. */
+    builtins(apiId: string): readonly string[];
+    /** The most a decision may hold. */
+    decision: LentDecisionLimits;
+    /** Why `question` can't be asked of `binding`'s model; `null` when it can. */
+    questionViolation(binding: ModelRoute, question: DecisionQuestion): string | null;
+    /** Why `state` can't be decided on by `binding`'s model; `null` when it can. */
+    stateViolation(binding: ModelRoute, state: unknown): string | null;
+    /** The most input tokens a Live session holds on the keys. Compression starts below it. */
+    liveInputTokens: number;
+    /** What runs on the keys keep to, whatever a profile says. */
+    holds: LentHolds;
+}
+/**
+ * What a studio runs on: a page's lent keys, the builder's own keys, or their own machine. Runs
+ * on lent keys always carry the keys they are held to.
+ */
+export type StudioRunsOn = {
+    mode: 'demo';
+    keys: LentKeys;
+} | {
+    mode: 'byok';
+} | {
+    mode: 'local';
+};
+/**
+ * The compression sizes a Live session runs with on lent keys: those the profile sets, and for a
+ * blank one Gemini's rule (start at 80% of the window, keep half the start), applied to what a
+ * session holds on the keys. Gemini would apply it to the model's whole window, past what the keys
+ * hold, so the session would be cut before compression started.
+ */
+export declare function lentCompression(keys: Pick<LentKeys, 'liveInputTokens'>, set: {
+    triggerTokens?: number;
+    targetTokens?: number;
+}): {
+    triggerTokens: number;
+    targetTokens: number;
+};
+/** The builder's own keys. */
+export declare const ON_OWN_KEYS: StudioRunsOn;
+/** Where a run's tools may reach, from what the studio runs it on. */
+export type RuntimeNetwork = 'public' | 'asWritten' | 'none';
+/** The parts of a runtime that decide its network. */
+export type NetworkRuntime = StudioRunsOn & {
+    remoteTools?: boolean;
+    providers?: {
+        local?: unknown;
+    };
+};
+/**
+ * Lent keys that hold runs to public hosts drop the draft's network rules. A local model with
+ * remote tools off reaches no host. Otherwise the rules run as written.
+ */
+export declare function runtimeNetwork(runtime: NetworkRuntime): RuntimeNetwork;
+/** What the studio does with the Network section on `runtime`; nothing when it runs as written. */
+export declare function studioNetworkNote(runtime: NetworkRuntime): string | undefined;
+/** What lent keys refuse after a remote read; nothing when the profile's own setting runs. */
+export declare function studioTaintNote(on: StudioRunsOn): string | undefined;

package/lent-keys.js

@@ -0,0 +1,47 @@
+/**
+ * Keys a page lends to whoever opens its studio. The studio runs agents on them for anyone, so it
+ * holds those runs to what the page says its keys allow. A studio given none has no such runs:
+ * it runs on the builder's own keys, their own machine, or their project.
+ *
+ * @module
+ */
+/**
+ * The compression sizes a Live session runs with on lent keys: those the profile sets, and for a
+ * blank one Gemini's rule (start at 80% of the window, keep half the start), applied to what a
+ * session holds on the keys. Gemini would apply it to the model's whole window, past what the keys
+ * hold, so the session would be cut before compression started.
+ */
+export function lentCompression(keys, set) {
+    const triggerTokens = set.triggerTokens ?? Math.round(keys.liveInputTokens * 0.8);
+    return { triggerTokens, targetTokens: set.targetTokens ?? Math.round(triggerTokens / 2) };
+}
+/** The builder's own keys. */
+export const ON_OWN_KEYS = { mode: 'byok' };
+/**
+ * Lent keys that hold runs to public hosts drop the draft's network rules. A local model with
+ * remote tools off reaches no host. Otherwise the rules run as written.
+ */
+export function runtimeNetwork(runtime) {
+    if (runtime.mode === 'demo')
+        return runtime.keys.holds.publicHostsOnly ? 'public' : 'asWritten';
+    return (runtime.mode === 'local' || runtime.providers?.local) && !runtime.remoteTools
+        ? 'none'
+        : 'asWritten';
+}
+const NETWORK_NOTES = {
+    public: "This page's keys reach public hosts only.",
+    asWritten: undefined,
+    none: 'Remote tools off: no host reached.',
+};
+/** What the studio does with the Network section on `runtime`; nothing when it runs as written. */
+export function studioNetworkNote(runtime) {
+    return NETWORK_NOTES[runtimeNetwork(runtime)];
+}
+/** What lent keys refuse after a remote read; nothing when the profile's own setting runs. */
+export function studioTaintNote(on) {
+    const gate = on.mode === 'demo' ? on.keys.holds.afterRemoteRead : 'off';
+    if (gate === 'off')
+        return undefined;
+    const refused = gate === 'write' ? 'writes' : 'destructive calls';
+    return `This page's keys refuse ${refused} after a remote read. Stricter settings hold.`;
+}

package/line-diff.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Two texts as the lines one takes out and the other puts in, with the lines they share between.
+ *
+ * @module
+ */
+/** One line of a diff: shared, taken out, or put in. */
+export interface DiffLine {
+    sign: ' ' | '-' | '+';
+    text: string;
+}
+/**
+ * `was` and `now` line by line. A line both hold in the same order is shared; the rest are taken
+ * out of `was` or put in by `now`, the taken-out lines first where they meet.
+ */
+export declare function lineDiff(was: string, now: string): DiffLine[];

package/line-diff.js

@@ -0,0 +1,41 @@
+/**
+ * Two texts as the lines one takes out and the other puts in, with the lines they share between.
+ *
+ * @module
+ */
+/**
+ * `was` and `now` line by line. A line both hold in the same order is shared; the rest are taken
+ * out of `was` or put in by `now`, the taken-out lines first where they meet.
+ */
+export function lineDiff(was, now) {
+    const [a, b] = [was.split('\n'), now.split('\n')];
+    // The longest run of lines both hold, from each place to the end, row after row.
+    const width = b.length + 1;
+    const held = new Array((a.length + 1) * width).fill(0);
+    const run = (i, j) => held[i * width + j] ?? 0;
+    for (let i = a.length - 1; i >= 0; i -= 1) {
+        for (let j = b.length - 1; j >= 0; j -= 1) {
+            held[i * width + j] =
+                a[i] === b[j] ? run(i + 1, j + 1) + 1 : Math.max(run(i + 1, j), run(i, j + 1));
+        }
+    }
+    const lines = [];
+    let [i, j] = [0, 0];
+    while (i < a.length || j < b.length) {
+        const [out, put] = [a[i], b[j]];
+        if (out !== undefined && out === put) {
+            lines.push({ sign: ' ', text: out });
+            i += 1;
+            j += 1;
+        }
+        else if (out !== undefined && (put === undefined || run(i + 1, j) >= run(i, j + 1))) {
+            lines.push({ sign: '-', text: out });
+            i += 1;
+        }
+        else {
+            lines.push({ sign: '+', text: put ?? '' });
+            j += 1;
+        }
+    }
+    return lines;
+}

package/live-connection.d.ts

@@ -0,0 +1,22 @@
+import type { ProfileDefinition } from '@theoremjs/agents';
+import type { PageTools } from '@theoremjs/react/client';
+import type { ToolRegistration } from './registrations.ts';
+import type { StudioRunPayload } from './run-payload.ts';
+/** The first message on a studio live call: the draft the relay runs, on a scope of its own. */
+export type StudioLiveDraftMessage = {
+    type: 'draft';
+    profile: ProfileDefinition;
+    customTools: ToolRegistration[];
+};
+/**
+ * A live call that carries its draft, so no other call can reach or replace it.
+ * The react client's `LiveConnection` accepts it as is.
+ */
+export declare function studioLiveConnection(payload: StudioRunPayload): {
+    openMessage: StudioLiveDraftMessage;
+};
+/**
+ * The studio's page: for each tool the page answers (`answeredBy: 'page'`), a function that
+ * answers with the tool's stub. A host's page does the real thing here.
+ */
+export declare function studioPageTools(payload: Pick<StudioRunPayload, 'customTools'>): PageTools;

package/live-connection.js

@@ -0,0 +1,27 @@
+import { stubOutputFromSchema } from "./stub.js";
+/**
+ * A live call that carries its draft, so no other call can reach or replace it.
+ * The react client's `LiveConnection` accepts it as is.
+ */
+export function studioLiveConnection(payload) {
+    const openMessage = {
+        type: 'draft',
+        profile: payload.profile,
+        customTools: payload.customTools,
+    };
+    return { openMessage };
+}
+/**
+ * The studio's page: for each tool the page answers (`answeredBy: 'page'`), a function that
+ * answers with the tool's stub. A host's page does the real thing here.
+ */
+export function studioPageTools(payload) {
+    const pageTools = {};
+    for (const tool of payload.customTools) {
+        if (tool.type !== 'function' || tool.answeredBy !== 'page')
+            continue;
+        const output = tool.stubResponse ?? stubOutputFromSchema(tool.outputSchema);
+        pageTools[tool.name] = () => ({ output });
+    }
+    return pageTools;
+}

package/live-session-bridge.d.ts

@@ -0,0 +1,15 @@
+import type { LabelOverrides, LiveSession, TurnEvent } from '@theoremjs/agents';
+import { type ClientTurnOptions } from '@theoremjs/agents/host';
+import { type PageToolResult } from '@theoremjs/react/server';
+import type { StudioTraceRoute } from './traces.ts';
+export type StudioLiveSocket = Pick<WebSocket, 'send' | 'close' | 'addEventListener'>;
+export type StudioLiveBridgeOptions = {
+    pageResult?: (result: PageToolResult) => Promise<boolean | undefined>;
+    /** Save trusted checkpoint ownership before the bridge exposes the event. */
+    beforeEvent?: (event: TurnEvent) => void | Promise<void>;
+    /** How long the browser has to run a call the model made before the bridge settles it as unanswered. */
+    clientCallTimeoutMs?: number;
+    /** Who reads the bridge's events and failures (`forClient`). Default: a visitor. */
+    clientEvents?: ClientTurnOptions;
+};
+export declare function attachStudioLiveSession(socket: StudioLiveSocket, session: LiveSession, profileId: string, sessionId: string, traces: StudioTraceRoute, labels?: LabelOverrides, options?: StudioLiveBridgeOptions): Promise<void>;

package/live-session-bridge.js

@@ -0,0 +1,202 @@
+import { clientError, forClient, forClientEvents, } from '@theoremjs/agents/host';
+import { bytesToBase64 } from '@theoremjs/agents/kernel';
+import { issuedOperationId as requiredOperationId } from '@theoremjs/react/client';
+import { parseLiveClientMessage } from '@theoremjs/react/server';
+function errorBody(err, reads) {
+    return clientError(err, reads.labels, reads.clientEvents);
+}
+function errorEnvelope(err, reads) {
+    return JSON.stringify({ type: 'error', ...errorBody(err, reads) });
+}
+function callWatch(session, timeoutMs) {
+    const timers = new Map();
+    const stop = (callId, operationId) => {
+        const watched = timers.get(callId);
+        if (watched?.operationId !== operationId)
+            return;
+        clearTimeout(watched.timer);
+        timers.delete(callId);
+    };
+    return {
+        start(callId, operationId) {
+            const previous = timers.get(callId);
+            if (previous)
+                clearTimeout(previous.timer);
+            timers.set(callId, {
+                operationId,
+                timer: setTimeout(() => {
+                    timers.delete(callId);
+                    // The kernel never times out an ungated held call; a refusal here means it already settled.
+                    session.executeTool({ callId, operationId, page: { timedOut: true } }).catch(() => { });
+                }, timeoutMs),
+            });
+        },
+        stop,
+        stopAll() {
+            for (const watched of timers.values())
+                clearTimeout(watched.timer);
+            timers.clear();
+        },
+    };
+}
+function pipeBrowserToSession(serverWs, session, watch, reads, pageResult) {
+    // A send the session refuses (a channel the profile turned off, a closed call) reaches the browser.
+    const forward = (sent) => {
+        sent.catch((err) => {
+            serverWs.send(errorEnvelope(err, reads));
+        });
+    };
+    serverWs.addEventListener('message', (event) => {
+        try {
+            if (typeof event.data === 'string') {
+                // A message that fails its check ends the call with a `request` error (the catch below).
+                const msg = parseLiveClientMessage(event.data);
+                switch (msg.type) {
+                    case 'audio':
+                        forward(session.sendAudio({
+                            data: msg.data,
+                            mimeType: 'audio/pcm;rate=16000',
+                        }));
+                        return;
+                    case 'video':
+                        forward(session.sendVideo({ data: msg.data, mimeType: msg.mimeType }));
+                        return;
+                    case 'text':
+                        forward(session.sendText(msg.text));
+                        return;
+                    case 'context':
+                        forward(session.sendContext({ client: msg.context }));
+                        return;
+                    case 'executeTool': {
+                        const { type: _type, output, grantId, unanswered, ...call } = msg;
+                        if (grantId) {
+                            if (!pageResult)
+                                throw new Error('Page dispatch result is unavailable');
+                            forward(pageResult({
+                                callId: call.callId,
+                                operationId: call.operationId,
+                                grantId,
+                                page: unanswered ? { unanswered: true } : { output },
+                            }).then((settled) => {
+                                if (settled)
+                                    serverWs.send(JSON.stringify({
+                                        type: 'executeToolResult',
+                                        callId: call.callId,
+                                        operationId: call.operationId,
+                                        status: 'settled',
+                                    }));
+                            }));
+                            return;
+                        }
+                        if (pageResult && output !== undefined)
+                            throw new Error('Page result requires a dispatch grant');
+                        watch.stop(call.callId, call.operationId);
+                        void answerExecuteTool(serverWs, session, output === undefined ? call : { ...call, page: { output } }, reads);
+                        return;
+                    }
+                }
+            }
+            if (event.data instanceof ArrayBuffer || event.data instanceof Uint8Array) {
+                forward(session.sendAudio({
+                    data: bytesToBase64(event.data instanceof Uint8Array ? event.data : new Uint8Array(event.data)),
+                    mimeType: 'audio/pcm;rate=16000',
+                }));
+            }
+        }
+        catch (err) {
+            serverWs.send(errorEnvelope(err, reads));
+        }
+    });
+}
+async function pipeSessionToBrowser(serverWs, session, profileId, sessionId, traces, watch, reads, beforeEvent) {
+    serverWs.send(JSON.stringify({ type: 'ready', profile: profileId, sessionId }));
+    try {
+        for await (const event of session.events()) {
+            await beforeEvent?.(event);
+            if (event.type === 'error') {
+                serverWs.send(JSON.stringify(forClient(event, reads.clientEvents)));
+                try {
+                    serverWs.close(1011, 'session error');
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            if (event.type === 'tool') {
+                const { tool } = event;
+                if (tool.phase === 'dispatch') {
+                    watch.stop(tool.callId, requiredOperationId(tool));
+                    serverWs.send(JSON.stringify({
+                        type: 'executeToolResult',
+                        callId: tool.callId,
+                        operationId: requiredOperationId(tool),
+                        status: 'dispatched',
+                        grantId: tool.grantId,
+                        arguments: tool.arguments,
+                    }));
+                }
+                if (tool.phase === undefined)
+                    watch.start(tool.callId, requiredOperationId(tool));
+                else if (tool.phase === 'complete' || tool.phase === 'error' || tool.phase === 'cancel') {
+                    watch.stop(tool.callId, requiredOperationId(tool));
+                }
+            }
+            serverWs.send(JSON.stringify({ type: 'events', events: forClientEvents([event], reads.clientEvents) }));
+        }
+    }
+    catch (err) {
+        serverWs.send(errorEnvelope(err, reads));
+    }
+    finally {
+        watch.stopAll();
+        // The events loop ends after the session's root record is written.
+        traces.close();
+        try {
+            serverWs.close(1000, 'session ended');
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Run the browser's `executeTool` on the session and tell the browser what became of the call. */
+async function answerExecuteTool(serverWs, session, call, reads) {
+    try {
+        const result = await session.executeTool(call);
+        serverWs.send(JSON.stringify(result.gated
+            ? {
+                type: 'executeToolResult',
+                callId: call.callId,
+                operationId: call.operationId,
+                status: 'gated',
+                gate: result.gated,
+            }
+            : {
+                type: 'executeToolResult',
+                callId: call.callId,
+                operationId: call.operationId,
+                status: 'settled',
+            }));
+    }
+    catch (err) {
+        // The session refused it (an unknown call, a decision it takes no more): the browser reads why.
+        serverWs.send(JSON.stringify({
+            type: 'executeToolResult',
+            callId: call.callId,
+            operationId: call.operationId,
+            status: 'refused',
+            body: errorBody(err, reads),
+        }));
+    }
+}
+const CLIENT_CALL_TIMEOUT_MS = 20_000;
+export function attachStudioLiveSession(socket, session, profileId, sessionId, traces, labels, options = {}) {
+    const watch = callWatch(session, options.clientCallTimeoutMs ?? CLIENT_CALL_TIMEOUT_MS);
+    const reads = { labels, clientEvents: options.clientEvents };
+    pipeBrowserToSession(socket, session, watch, reads, options.pageResult);
+    socket.addEventListener('close', () => {
+        void session.close('client disconnected');
+    });
+    return pipeSessionToBrowser(socket, session, profileId, sessionId, traces, watch, reads, options.beforeEvent);
+}