@nodetool-ai/websocket 0.7.0-rc.23 → 0.8.1

package/dist/websocket-client-session.js

@@ -0,0 +1,1253 @@
+import { getSetting } from "./settings-registry.js";
+import { ConfiguredProviderCache } from "./configured-providers.js";
+import { packWebSocketMessage, unpackWebSocketMessage } from "./messagepack.js";
+import { createLogger, getByteLimitEnv } from "@nodetool-ai/config";
+import { getAssetAdapter } from "./lib/storage.js";
+import { isNonEmptyString, isObjectLike, isString } from "./lib/wire-values.js";
+import { onDrain } from "./drain.js";
+import { resourceEvents } from "./resource-events.js";
+import { createSystemStatsSampler, systemStatsBroadcastEnabled } from "./system-stats.js";
+import { resolveContentUrls } from "./resolve-media-urls.js";
+import { Asset, ModelObserver } from "@nodetool-ai/models";
+import { fetchExternalMedia } from "@nodetool-ai/runtime";
+import { webSocketCommandEnvelopeSchema, commandDataSchemas, controlMessageInSchemas, outboundControlMessageSchemas, processingMessageSchemas } from "@nodetool-ai/protocol";
+import { retrieveAssetBytes } from "./lib/asset-paths.js";
+import { encodeNativeAudioChunks, primaryTextOutputName } from "./session/asset-autosave.js";
+import { buildChatAgentSystemPrompt, CHAT_AGENT_SYSTEM_PROMPT, focusedUiToolNames, normalizeToolCallName, RESIDENT_TOOL_NAMES, unroutableToolMessage } from "./session/chat-prompt.js";
+import { serverModelInterfaces } from "./session/model-interfaces.js";
+import { formatSanitizedError } from "./session/sanitize.js";
+import { DirectInferenceHandler, entityRefResolver, estimateDirectTextSpend, resolveEntityReferenceImages } from "./session/inference.js";
+// The pure helpers moved to ./session/*; re-exported here so every existing
+// import path keeps working.
+export { CHAT_AGENT_SYSTEM_PROMPT, RESIDENT_TOOL_NAMES, buildChatAgentSystemPrompt, estimateDirectTextSpend, focusedUiToolNames, normalizeToolCallName, primaryTextOutputName, serverModelInterfaces, unroutableToolMessage };
+import { DEFAULT_RUN_JOB_EXECUTION_OPTIONS, JobExecutionManager, resolveRunJobExecutionOptions, resolveRunJobUserId } from "./session/job-execution.js";
+// The job region moved to ./session/job-execution.ts; its wire types are
+// re-exported here so every existing import path keeps working.
+export { DEFAULT_RUN_JOB_EXECUTION_OPTIONS, resolveRunJobExecutionOptions, resolveRunJobUserId };
+import { ChatTurnHandler } from "./session/chat-turn.js";
+import { CommandRouter } from "./session/commands.js";
+const log = createLogger("nodetool.websocket.runner");
+/** RFC 6455 "service restart" — what a drained connection is closed with. */
+const DRAIN_CLOSE_CODE = 1012;
+/** How often a draining connection re-checks whether its work has settled. */
+const DRAIN_POLL_MS = 250;
+/**
+ * Largest binary (MsgPack) frame accepted from a client before deserialization.
+ * MsgPack can amplify a small payload into a huge in-memory structure, so the
+ * raw byte length is bounded up front. Override with the
+ * `NODETOOL_WS_MAX_MESSAGE_BYTES` environment variable (value in bytes);
+ * default 256 MiB.
+ */
+const DEFAULT_MAX_WS_MESSAGE_BYTES = 256 * 1024 * 1024;
+function getMaxWsMessageBytes() {
+    return getByteLimitEnv("NODETOOL_WS_MAX_MESSAGE_BYTES", DEFAULT_MAX_WS_MESSAGE_BYTES);
+}
+/**
+ * Outbound (server→client) frame validation gate. Every message `sendMessage`
+ * emits whose `type` matches a known `ProcessingMessage` variant or one of
+ * the small set of non-`ProcessingMessage` server frames (`pong`,
+ * `rpc_response`, `system_stats`, `resource_change`) is safe-parsed against
+ * its Zod schema before it goes on the wire; frames with an unrecognized (or
+ * absent) `type` — the ad hoc `{ error, details }` command replies — are left
+ * alone, as they always have been.
+ *
+ * Set `NODETOOL_VALIDATE_OUTBOUND_WS=1` to force validation on, `=0` to force
+ * it off. Unset, it defaults to on under `NODE_ENV=test` or Vitest (`VITEST`)
+ * and off everywhere else — a server bug that produces a malformed frame
+ * should fail the test that exercised it, not corrupt a production
+ * connection with a thrown error mid-stream. On failure it throws (the
+ * caller — `sendMessage` — is already inside the code path the bug is in, so
+ * failing loudly there is what surfaces it to the test).
+ */
+function shouldValidateOutboundWs() {
+    const override = process.env["NODETOOL_VALIDATE_OUTBOUND_WS"]?.trim();
+    if (override === "1" || override === "true")
+        return true;
+    if (override === "0" || override === "false")
+        return false;
+    return process.env["NODE_ENV"] === "test" || Boolean(process.env["VITEST"]);
+}
+/**
+ * Throws when outbound validation is enabled and `message` carries a `type`
+ * this package can validate but fails to conform to its schema. No-op for
+ * unrecognized/absent `type` values — see {@link shouldValidateOutboundWs}.
+ */
+function assertValidOutboundMessage(message) {
+    if (!shouldValidateOutboundWs())
+        return;
+    const type = isString(message["type"]) ? message["type"] : null;
+    if (!type)
+        return;
+    const schema = processingMessageSchemas[type] ??
+        outboundControlMessageSchemas[type];
+    if (!schema)
+        return;
+    const parsed = schema.safeParse(message);
+    if (!parsed.success) {
+        throw new Error(`Outbound WebSocket message failed protocol validation (type: "${type}"): ` +
+            parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+                .join("; "));
+    }
+}
+export class ToolBridge {
+    waiters = new Map();
+    createWaiter(toolCallId, timeoutMs = 300_000, scope) {
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            const cleanup = () => {
+                if (timer)
+                    clearTimeout(timer);
+                this.waiters.delete(toolCallId);
+            };
+            const wrappedResolve = (value) => {
+                cleanup();
+                resolve(value);
+            };
+            const wrappedReject = (reason) => {
+                cleanup();
+                reject(reason);
+            };
+            this.waiters.set(toolCallId, {
+                resolve: wrappedResolve,
+                reject: wrappedReject,
+                scope
+            });
+            if (timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    if (this.waiters.has(toolCallId)) {
+                        wrappedReject(new Error(`Tool call ${toolCallId} timed out after ${timeoutMs}ms`));
+                    }
+                }, timeoutMs);
+            }
+        });
+    }
+    resolveResult(toolCallId, payload) {
+        const waiter = this.waiters.get(toolCallId);
+        if (!waiter)
+            return;
+        waiter.resolve(payload);
+    }
+    /** Resolve every waiter in `scope` with the same payload. */
+    resolveScope(scope, payload) {
+        for (const waiter of [...this.waiters.values()]) {
+            if (waiter.scope === scope) {
+                waiter.resolve(payload);
+            }
+        }
+    }
+    rejectResult(toolCallId, error) {
+        const waiter = this.waiters.get(toolCallId);
+        if (!waiter)
+            return;
+        waiter.reject(error);
+    }
+    cancelAll() {
+        const error = new Error("All pending tool calls cancelled");
+        for (const waiter of this.waiters.values()) {
+            waiter.reject(error);
+        }
+        this.waiters.clear();
+    }
+    cancelScope(scope) {
+        const error = new Error(`Pending tool calls cancelled for ${scope}`);
+        for (const [id, waiter] of this.waiters) {
+            if (waiter.scope === scope) {
+                waiter.reject(error);
+                this.waiters.delete(id);
+            }
+        }
+    }
+    /**
+     * Cancel every pending call except those scoped to `scope`. Used on
+     * disconnect when a detached chat turn stays alive: its client tool calls
+     * survive (the replay re-delivers the `tool_call` frames, so a reconnecting
+     * client can still answer them) while everything else is rejected.
+     */
+    cancelAllExcept(scope) {
+        const error = new Error("All pending tool calls cancelled");
+        for (const [id, waiter] of this.waiters) {
+            if (waiter.scope === scope)
+                continue;
+            waiter.reject(error);
+            this.waiters.delete(id);
+        }
+    }
+}
+export class WebSocketClientSession {
+    websocket = null;
+    mode = "binary";
+    userId;
+    authToken;
+    /**
+     * Set when this connection was opened by a visitor to a deployed app's
+     * hidden URL. `userId` is then the app's owner, so nothing downstream can
+     * tell the two apart on its own — this is what does.
+     */
+    appSession;
+    /**
+     * Assigned once, in the constructor. `readonly` because JobExecutionManager
+     * snapshots both by value into its `defaults`, and a later reassignment here
+     * would silently leave the manager on the old pair.
+     */
+    defaultModel;
+    defaultProvider;
+    resolveExecutor;
+    resolveNodeType;
+    resolveProvider;
+    getSystemStats;
+    systemStatsEnabled;
+    workspaceResolver;
+    getNodeMetadata;
+    validateNode;
+    nodeRegistry;
+    pythonBridge;
+    frontendRendererRegistry;
+    frontendRendererId = null;
+    configuredProvidersCache = new ConfiguredProviderCache({});
+    sendLock = Promise.resolve();
+    /**
+     * The job region — run_job through terminal status. It owns `activeJobs`,
+     * the concurrency queue and the slot counters; nothing outside it holds a
+     * reference to them.
+     */
+    jobs;
+    heartbeatTimer = null;
+    statsTimer = null;
+    statsPrimeTimer = null;
+    /**
+     * Abort controllers for RPC calls that are still waiting on a provider.
+     * An RPC has no chat turn to hang off, so a `stop` command and a dropped
+     * socket reach an in-flight model call through this set.
+     */
+    rpcAborts = new Set();
+    /** One-shot model calls: the `inference` stream and the direct-generation RPCs. */
+    inference;
+    clientToolsManifest = {};
+    clientToolsManifestReady = false;
+    toolBridge = new ToolBridge();
+    /** Separate bridge for connection-level renderer calls; never resolves chat tool_result waiters. */
+    rendererToolBridge = new ToolBridge();
+    /** Round-trips permission approvals for gated tool calls. */
+    approvalBridge = new ToolBridge();
+    /** This connection's chat turns: state, permissions, and the turn loop. */
+    chat;
+    /** The client's command surface: one dispatch table over the wire commands. */
+    commands;
+    observerRegistered = false;
+    /** Unsubscribe from the process drain, held for the life of the socket. */
+    drainUnsubscribe = null;
+    /** Set while waiting for this connection's own work to settle mid-drain. */
+    drainTimer = null;
+    /**
+     * The detachable session for the chat turn THIS connection is executing.
+     * While set (and running), every outbound frame carrying its thread_id is
+     * routed through the session: stamped with `chat_seq`, buffered for replay,
+     * and delivered to whichever connection is currently attached — which stops
+     * being this one if the socket drops mid-turn.
+     */
+    chatTurnSession = null;
+    /**
+     * Turns still executing on a previous connection's runner that THIS
+     * connection reattached to via `resume_chat`, keyed by thread id. Client
+     * frames for them (`tool_result`, approvals, `stop`) are forwarded to the
+     * executing runner through the session's hooks.
+     */
+    adoptedSessions = new Map();
+    /**
+     * This connection's identity as a chat-turn delivery target. A stable
+     * object so `detach(target)` only clears the session's attachment when it
+     * still points at THIS connection — never a newer one that reattached.
+     */
+    chatDeliveryTarget = {
+        deliver: (message) => this.sendToSocket(message)
+    };
+    logError(context, error) {
+        log.error(context, formatSanitizedError(error));
+    }
+    /**
+     * Hooks a resilient chat-turn session carries so a LATER connection that
+     * reattaches can route the client's `tool_result` / approvals / `stop`
+     * back to this runner — the one whose bridges own the pending waiters.
+     */
+    buildChatTurnHooks() {
+        return {
+            resolveToolResult: (toolCallId, payload) => this.toolBridge.resolveResult(toolCallId, payload),
+            resolveApproval: (approvalId, payload) => this.approvalBridge.resolveResult(approvalId, payload),
+            cancelPendingCalls: (threadId) => {
+                this.toolBridge.cancelScope(threadId);
+                this.approvalBridge.cancelScope(threadId);
+            }
+        };
+    }
+    /** Abort every RPC still waiting on a provider. Idempotent. */
+    cancelRpcCalls() {
+        for (const abort of this.rpcAborts)
+            abort.abort();
+        this.rpcAborts.clear();
+    }
+    /**
+     * Put a controller in {@link rpcAborts} so {@link cancelRpcCalls} — a `stop`
+     * command or a dropped socket — reaches the call it belongs to, and hand
+     * back the deregistration the caller runs when the call settles.
+     */
+    registerAbort(controller) {
+        this.rpcAborts.add(controller);
+        return () => {
+            this.rpcAborts.delete(controller);
+        };
+    }
+    sendDetached(message) {
+        void this.sendMessage(message).catch((err) => {
+            this.logError("detached websocket send failed", err);
+        });
+    }
+    requireUserId() {
+        if (this.userId === null) {
+            throw new Error("WebSocketClientSession has no user id: connect() has not run");
+        }
+        return this.userId;
+    }
+    constructor(options) {
+        this.userId = options.userId ?? null;
+        this.authToken = options.authToken ?? null;
+        this.appSession = options.appSession ?? null;
+        this.defaultModel = options.defaultModel ?? "gpt-oss:20b";
+        this.defaultProvider = options.defaultProvider ?? "ollama";
+        this.resolveExecutor = options.resolveExecutor;
+        this.resolveNodeType = options.resolveNodeType;
+        this.resolveProvider = options.resolveProvider;
+        this.workspaceResolver = options.workspaceResolver;
+        this.getNodeMetadata = options.getNodeMetadata;
+        this.validateNode = options.validateNode;
+        this.nodeRegistry = options.nodeRegistry;
+        this.pythonBridge = options.pythonBridge;
+        this.frontendRendererRegistry = options.frontendRendererRegistry;
+        this.getSystemStats = options.getSystemStats ?? createSystemStatsSampler();
+        this.systemStatsEnabled =
+            options.systemStatsEnabled ?? systemStatsBroadcastEnabled();
+        this.inference = new DirectInferenceHandler(this, {
+            defaults: { provider: this.defaultProvider, model: this.defaultModel },
+            currentRequestSeq: () => this.chat.currentRequestSeq,
+            registerAbort: (controller) => this.registerAbort(controller)
+        });
+        this.jobs = new JobExecutionManager(this, {
+            beforeRunJob: options.beforeRunJob,
+            getMaxConcurrentJobs: () => this.getMaxConcurrentJobs(),
+            getMaxConcurrentRunsPerWorkflow: () => this.getMaxConcurrentRunsPerWorkflow(),
+            defaultMaxConcurrentJobs: WebSocketClientSession.DEFAULT_MAX_CONCURRENT_JOBS,
+            defaultMaxConcurrentRunsPerWorkflow: WebSocketClientSession.DEFAULT_MAX_CONCURRENT_RUNS_PER_WORKFLOW,
+            sendToSocket: (message) => this.sendToSocket(message),
+            isSocketConnected: () => this.isRendererConnected(),
+            defaults: {
+                provider: this.defaultProvider,
+                model: this.defaultModel
+            }
+        });
+        this.chat = new ChatTurnHandler(this, {
+            // A chat-driven workflow run shares the connection's concurrency
+            // accounting, so it is registered and released here rather than in a
+            // map of chat's own.
+            jobs: {
+                registerJob: (jobId, active) => this.jobs.registerJob(jobId, active),
+                dropJob: (jobId) => this.jobs.dropJob(jobId),
+                releaseJob: (jobId) => this.jobs.releaseJob(jobId),
+                handleNodeProviderCost: (active, outbound) => this.jobs._handleNodeProviderCost(active, outbound),
+                runMeasuredCost: (active) => this.jobs.runMeasuredCost(active)
+            },
+            toolBridge: this.toolBridge,
+            approvalBridge: this.approvalBridge,
+            clientTools: () => this.clientToolsManifest,
+            authToken: () => this.authToken,
+            beforeRunJob: options.beforeRunJob,
+            defaults: {
+                provider: this.defaultProvider,
+                model: this.defaultModel
+            },
+            hydrateGraph: (graph) => this.jobs.hydrateGraph(graph),
+            configuredProviders: (userId) => this.configuredProvidersCache.get(userId),
+            entityRefResolver,
+            resolveEntityReferenceImages,
+            resolveSourceImageBytes: (data, mediaGeneration, userId) => this.resolveSourceImageBytes(data, mediaGeneration, userId),
+            resolveReferenceMediaBytes: (data, mediaGeneration, userId) => this.resolveReferenceMediaBytes(data, mediaGeneration, userId)
+        });
+        this.commands = new CommandRouter({
+            session: this,
+            jobs: this.jobs,
+            chat: this.chat,
+            inference: this.inference,
+            // What a command does to the connection itself: the socket, the wire
+            // mode, the RPC abort set, the tool bridges, and the chat-turn session
+            // bookkeeping the frame router reads. All host state, reached through
+            // this adapter rather than owned by the router.
+            host: {
+                sendToSocket: (message) => this.sendToSocket(message),
+                setMode: (mode) => {
+                    this.mode = mode;
+                },
+                clearModels: () => this.clearModels(),
+                cancelRpcCalls: () => this.cancelRpcCalls(),
+                cancelToolScope: (scope) => {
+                    this.toolBridge.cancelScope(scope);
+                    this.approvalBridge.cancelScope(scope);
+                },
+                chatTurnHooks: () => this.buildChatTurnHooks(),
+                chatDeliveryTarget: this.chatDeliveryTarget,
+                getChatTurnSession: () => this.chatTurnSession,
+                setChatTurnSession: (session) => {
+                    this.chatTurnSession = session;
+                },
+                adoptSession: (threadId, session) => {
+                    this.adoptedSessions.set(threadId, session);
+                },
+                forgetAdoptedSession: (threadId) => {
+                    this.adoptedSessions.delete(threadId);
+                },
+                closeForDrain: () => this.onDraining()
+            },
+            defaults: {
+                provider: this.defaultProvider,
+                model: this.defaultModel
+            },
+            apiOptions: options.apiOptions,
+            getPythonBridgeReady: options.getPythonBridgeReady
+        });
+    }
+    isRendererConnected() {
+        return (this.websocket !== null &&
+            this.websocket.clientState !== "disconnected" &&
+            this.websocket.applicationState !== "disconnected");
+    }
+    isRendererReady() {
+        return this.clientToolsManifestReady;
+    }
+    getRendererToolManifest() {
+        return Object.fromEntries(Object.entries(this.clientToolsManifest).map(([name, manifest]) => [
+            name,
+            { ...manifest }
+        ]));
+    }
+    /** Send a connection-level frontend tool call and await its renderer result. */
+    async executeRendererTool(rendererId, call, timeoutMs = 300_000) {
+        if (this.frontendRendererId !== rendererId || !this.isRendererConnected()) {
+            throw new Error(`Renderer "${rendererId}" is not connected`);
+        }
+        if (!this.isRendererReady()) {
+            throw new Error(`Renderer "${rendererId}" is not ready`);
+        }
+        if (!this.clientToolsManifest[call.name]) {
+            throw new Error(`Tool "${call.name}" is not available in renderer`);
+        }
+        const resultPromise = this.rendererToolBridge.createWaiter(call.tool_call_id, timeoutMs);
+        try {
+            await this.sendToSocket({
+                type: "renderer_tool_call",
+                renderer_id: rendererId,
+                tool_call_id: call.tool_call_id,
+                name: call.name,
+                args: call.args
+            });
+            if (!this.isRendererConnected()) {
+                throw new Error(`Renderer "${rendererId}" disconnected during tool call`);
+            }
+        }
+        catch (error) {
+            this.rendererToolBridge.rejectResult(call.tool_call_id, error instanceof Error ? error : new Error(String(error)));
+        }
+        const result = await resultPromise;
+        if (result.ok !== true) {
+            throw new Error(isString(result.error) ? result.error : "Renderer tool failed");
+        }
+        return {
+            renderer_id: rendererId,
+            tool_call_id: call.tool_call_id,
+            ok: true,
+            result: result.result ?? result.content
+        };
+    }
+    async connect(websocket, userId, authToken) {
+        if (userId)
+            this.userId = userId;
+        if (authToken)
+            this.authToken = authToken;
+        this.userId = this.userId ?? "1";
+        await websocket.accept();
+        this.websocket = websocket;
+        if (this.frontendRendererRegistry) {
+            this.frontendRendererId = this.frontendRendererRegistry.register(this.userId, this);
+            await this.sendToSocket({
+                type: "renderer_registered",
+                renderer_id: this.frontendRendererId
+            });
+        }
+        log.info("Client connected", { userId: this.userId });
+        this.startHeartbeat();
+        this.startStatsBroadcast();
+        this.registerObserver();
+        // A connection accepted just before the drain took effect gets the
+        // callback immediately, so it closes like any older one.
+        this.drainUnsubscribe = onDrain(() => this.onDraining());
+    }
+    async disconnect() {
+        log.info("Client disconnected");
+        this.drainUnsubscribe?.();
+        this.drainUnsubscribe = null;
+        this.stopDrainTimer();
+        this.stopHeartbeat();
+        this.stopStatsBroadcast();
+        this.unregisterObserver();
+        if (this.frontendRendererId) {
+            this.frontendRendererRegistry?.unregister(this.frontendRendererId);
+            this.frontendRendererId = null;
+        }
+        this.rendererToolBridge.cancelAll();
+        // An RPC has no session to detach into and no client left to answer, so
+        // it is always cancelled — unlike a resilient chat turn below.
+        this.cancelRpcCalls();
+        // A resilient chat turn survives the socket: detach it (frames keep
+        // buffering in the session for replay) instead of aborting. The session's
+        // execution budget bounds its work while detached. Its pending
+        // client tool calls stay alive too — replay re-delivers the `tool_call`
+        // frames, so a reconnecting client can still answer them. Everything
+        // else (a sessionless `inference` turn, other pending calls) is cancelled
+        // as before: nobody is left to receive its output.
+        const detachedThreadId = this.chatTurnSession?.status === "running"
+            ? this.chatTurnSession.threadId
+            : null;
+        if (detachedThreadId) {
+            this.chatTurnSession?.detach(this.chatDeliveryTarget);
+            this.toolBridge.cancelAllExcept(detachedThreadId);
+            this.approvalBridge.cancelAllExcept(detachedThreadId);
+        }
+        else {
+            this.toolBridge.cancelAll();
+            this.approvalBridge.cancelAll();
+            this.chat.cancel();
+        }
+        for (const session of this.adoptedSessions.values()) {
+            session.detach(this.chatDeliveryTarget);
+        }
+        this.adoptedSessions.clear();
+        await this.jobs.cancelAll();
+        if (this.websocket) {
+            try {
+                await this.websocket.close();
+            }
+            catch (error) {
+                this.logError("disconnect websocket.close failed", error);
+            }
+        }
+        this.websocket = null;
+    }
+    /** A chat turn or a workflow run this connection is still driving. */
+    hasRunningWork() {
+        if (this.chatTurnSession?.status === "running")
+            return true;
+        for (const session of this.adoptedSessions.values()) {
+            if (session.status === "running")
+                return true;
+        }
+        return this.jobs.activeJobIds().length > 0;
+    }
+    /**
+     * The process is draining. A connection with nothing in flight is closed at
+     * once so the client's own reconnect lands on a machine that is staying; one
+     * driving a turn or a run keeps it and closes when that settles, because
+     * closing here would only move the work's output nowhere.
+     */
+    onDraining() {
+        if (!this.hasRunningWork()) {
+            void this.closeForDrain();
+            return;
+        }
+        if (this.drainTimer)
+            return;
+        this.drainTimer = setInterval(() => {
+            if (this.hasRunningWork())
+                return;
+            void this.closeForDrain();
+        }, DRAIN_POLL_MS);
+        this.drainTimer.unref?.();
+    }
+    /**
+     * Close this socket with 1012. The client reconnects on its own and the
+     * proxy sends it to a machine whose health check still passes.
+     */
+    async closeForDrain() {
+        this.stopDrainTimer();
+        const websocket = this.websocket;
+        if (!websocket)
+            return;
+        try {
+            await websocket.close(DRAIN_CLOSE_CODE, "Server draining");
+        }
+        catch (error) {
+            this.logError("drain close failed", error);
+        }
+    }
+    stopDrainTimer() {
+        if (this.drainTimer) {
+            clearInterval(this.drainTimer);
+            this.drainTimer = null;
+        }
+    }
+    serializeForJson(value) {
+        if (value instanceof Uint8Array)
+            return Array.from(value);
+        if (value instanceof Date)
+            return value.toISOString();
+        if (Array.isArray(value))
+            return value.map((v) => this.serializeForJson(v));
+        if (isObjectLike(value)) {
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                out[k] = this.serializeForJson(v);
+            }
+            return out;
+        }
+        // SAFETY: bytes, dates, arrays and objects are handled above; what is left
+        // is a JSON scalar.
+        return value;
+    }
+    send(message) {
+        return this.sendMessage(message);
+    }
+    async sendMessage(message) {
+        // Frames belonging to this connection's resilient chat turn go through the
+        // session: seq-stamped, buffered for replay, delivered to the attached
+        // connection (possibly a later one than this).
+        const session = this.chatTurnSession;
+        if (session &&
+            session.status === "running" &&
+            isString(message.thread_id) &&
+            message.thread_id === session.threadId) {
+            session.emit(message);
+            return;
+        }
+        // Same for a resilient run's frames — including its terminal job_update,
+        // which is the one frame a reconnecting client most needs replayed.
+        // Adopted sessions are checked too so a `cancel_job` this connection
+        // issued against a run owned by another connection still buffers its
+        // acknowledgement into that run's session rather than only this socket.
+        const jobSession = this.jobs.resolveJobSession(message.job_id);
+        if (jobSession && jobSession.status === "running") {
+            jobSession.emit(message);
+            return;
+        }
+        await this.sendToSocket(message);
+    }
+    async sendToSocket(message) {
+        if (!this.websocket)
+            return;
+        if (this.websocket.clientState === "disconnected" ||
+            this.websocket.applicationState === "disconnected") {
+            return;
+        }
+        assertValidOutboundMessage(message);
+        // Resolve storage keys in content to browser-accessible URLs before
+        // sending over the wire.  This keeps DB storage URL-agnostic while
+        // delivering ready-to-use URLs to the client.
+        if (Array.isArray(message.content)) {
+            message = {
+                ...message,
+                content: await resolveContentUrls(message.content, message.user_id ?? this.userId ?? undefined)
+            };
+        }
+        // In-process audio/CV chunks carry samples as a native Float32Array,
+        // which neither msgpack nor JSON represents. Encode them to base64
+        // f32le here — the one and only conversion on the path to the client.
+        message = encodeNativeAudioChunks(message);
+        // Snapshot the mode ONCE for this frame. Reading this.mode again after the
+        // send-lock await would let a set_mode that lands mid-queue transmit a
+        // payload prepared for the other mode (e.g. a binary payload with raw
+        // Uint8Arrays JSON.stringify'd into index-keyed garbage).
+        const mode = this.mode;
+        const payload = mode === "text"
+            ? this.serializeForJson(message)
+            : message;
+        const prev = this.sendLock;
+        let release;
+        this.sendLock = new Promise((resolve) => {
+            release = resolve;
+        });
+        await prev;
+        try {
+            const websocket = this.websocket;
+            if (!websocket ||
+                websocket.clientState === "disconnected" ||
+                websocket.applicationState === "disconnected") {
+                return;
+            }
+            if (mode === "binary") {
+                await websocket.sendBytes(packWebSocketMessage(payload));
+            }
+            else {
+                await websocket.sendText(JSON.stringify(payload));
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    async receiveMessage() {
+        if (!this.websocket) {
+            throw new Error("WebSocket is not connected");
+        }
+        const message = await this.websocket.receive();
+        if (message.type === "websocket.disconnect")
+            return null;
+        if (message.bytes) {
+            const maxBytes = getMaxWsMessageBytes();
+            if (message.bytes.length > maxBytes) {
+                throw new Error(`Incoming WebSocket message exceeds maximum size: ` +
+                    `${message.bytes.length} > ${maxBytes} bytes ` +
+                    `(set NODETOOL_WS_MAX_MESSAGE_BYTES to raise the limit)`);
+            }
+            return unpackWebSocketMessage(message.bytes);
+        }
+        if (message.text) {
+            const maxBytes = getMaxWsMessageBytes();
+            const textBytes = Buffer.byteLength(message.text, "utf8");
+            if (textBytes > maxBytes) {
+                throw new Error(`Incoming WebSocket message exceeds maximum size: ` +
+                    `${textBytes} > ${maxBytes} bytes ` +
+                    `(set NODETOOL_WS_MAX_MESSAGE_BYTES to raise the limit)`);
+            }
+            return JSON.parse(message.text);
+        }
+        return null;
+    }
+    /** Default cap when `MAX_CONCURRENT_JOBS` is unset/invalid. */
+    static DEFAULT_MAX_CONCURRENT_JOBS = 4;
+    /** Default per-workflow cap when `MAX_CONCURRENT_RUNS_PER_WORKFLOW` is unset/invalid. */
+    static DEFAULT_MAX_CONCURRENT_RUNS_PER_WORKFLOW = 4;
+    /** How long a resolved concurrency-setting value is reused before re-reading. */
+    static MAX_CONCURRENT_JOBS_TTL_MS = 5000;
+    maxConcurrentJobsCache = null;
+    maxRunsPerWorkflowCache = null;
+    /**
+     * Resolve the per-client concurrency cap from settings (>= 1), cached for a
+     * few seconds so back-to-back run_job/drainQueue calls don't hit the settings
+     * store every time. The setting changes rarely, so a short TTL is fine.
+     */
+    async getMaxConcurrentJobs() {
+        const cached = this.maxConcurrentJobsCache;
+        const value = await this.resolvePositiveIntSetting("MAX_CONCURRENT_JOBS", WebSocketClientSession.DEFAULT_MAX_CONCURRENT_JOBS, cached);
+        this.maxConcurrentJobsCache = value;
+        return value.value;
+    }
+    /**
+     * Resolve the per-workflow concurrency cap (>= 1) for runs that opt into
+     * concurrency. When this many runs of the same workflow are already in
+     * flight, further opted-in runs queue. Cached like {@link getMaxConcurrentJobs}.
+     */
+    async getMaxConcurrentRunsPerWorkflow() {
+        const cached = this.maxRunsPerWorkflowCache;
+        const value = await this.resolvePositiveIntSetting("MAX_CONCURRENT_RUNS_PER_WORKFLOW", WebSocketClientSession.DEFAULT_MAX_CONCURRENT_RUNS_PER_WORKFLOW, cached);
+        this.maxRunsPerWorkflowCache = value;
+        return value.value;
+    }
+    /**
+     * Read a positive-integer setting, reusing the cached value while it's still
+     * within the TTL. Falls back to `fallback` when the setting is unset/invalid
+     * or the settings store is unavailable (e.g. DB not initialized) rather than
+     * blocking the run, matching the runner's other best-effort DB access.
+     */
+    async resolvePositiveIntSetting(key, fallback, cached) {
+        const now = Date.now();
+        if (cached &&
+            now - cached.at < WebSocketClientSession.MAX_CONCURRENT_JOBS_TTL_MS) {
+            return cached;
+        }
+        let raw = null;
+        try {
+            raw = await getSetting(key);
+        }
+        catch {
+            // Settings store unavailable — fall back to the default.
+        }
+        const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+        const value = Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+        return { value, at: now };
+    }
+    async clearModels() {
+        return {
+            message: "Model clearing is managed by provider implementations in TS runtime"
+        };
+    }
+    /**
+     * Bytes behind one media content block, whatever form the client used to
+     * name them: a stored `asset_id`, an `asset://<id>.<ext>` uri written by the
+     * `@`-mention picker, an inline `data:` uri, an http(s) url, or a bare
+     * base64 `data` field. Returns null when none of them resolves.
+     */
+    async resolveMediaRefBytes(ref, userId) {
+        const assetId = isString(ref.asset_id) ? ref.asset_id : null;
+        if (assetId) {
+            const bytes = await this.loadAssetBytes(userId, assetId);
+            if (bytes && bytes.length > 0)
+                return bytes;
+        }
+        const uri = isString(ref.uri) ? ref.uri : null;
+        if (uri) {
+            if (uri.startsWith("asset://")) {
+                // `@`-mentioned or library-dragged asset: `asset://<id>.<ext>`.
+                const withoutScheme = uri.slice("asset://".length);
+                const dotIdx = withoutScheme.lastIndexOf(".");
+                const mentionedId = dotIdx > -1 ? withoutScheme.slice(0, dotIdx) : withoutScheme;
+                const bytes = await this.loadAssetBytes(userId, mentionedId);
+                if (bytes && bytes.length > 0)
+                    return bytes;
+            }
+            else if (uri.startsWith("data:")) {
+                const commaIdx = uri.indexOf(",");
+                if (commaIdx > -1) {
+                    const b64 = uri.slice(commaIdx + 1);
+                    try {
+                        return new Uint8Array(Buffer.from(b64, "base64"));
+                    }
+                    catch {
+                        /* fall through to the `data` field below */
+                    }
+                }
+            }
+            else if (uri.startsWith("http://") || uri.startsWith("https://")) {
+                // A chat client picked this uri, so the media-ref egress policy
+                // decides — including on every redirect hop, which the predicate
+                // this replaced never saw.
+                try {
+                    const resp = await fetchExternalMedia(uri);
+                    if (resp.ok) {
+                        return new Uint8Array(await resp.arrayBuffer());
+                    }
+                }
+                catch (err) {
+                    log.warn("resolveMediaRefBytes: fetch failed", {
+                        uri,
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                }
+            }
+        }
+        const data64 = isString(ref.data) ? ref.data : null;
+        if (data64) {
+            try {
+                return new Uint8Array(Buffer.from(data64, "base64"));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        return null;
+    }
+    /** One asset's bytes, or null when it is gone or unreadable. */
+    async loadAssetBytes(userId, assetId) {
+        if (!assetId)
+            return null;
+        try {
+            const asset = await Asset.find(userId, assetId);
+            if (!asset)
+                return null;
+            return await retrieveAssetBytes(getAssetAdapter(), userId, assetId, asset.content_type);
+        }
+        catch (err) {
+            log.warn("loadAssetBytes: asset load failed", {
+                assetId,
+                error: err instanceof Error ? err.message : String(err)
+            });
+            return null;
+        }
+    }
+    /** The inner ref record of every `image_url` / `video` block on a message. */
+    mediaRefsOnMessage(data, blockType) {
+        const content = data.content;
+        if (!Array.isArray(content))
+            return [];
+        const field = blockType === "image_url" ? "image" : "video";
+        const refs = [];
+        for (const c of content) {
+            if (!isObjectLike(c))
+                continue;
+            const block = c;
+            if (block.type !== blockType)
+                continue;
+            const ref = block[field];
+            refs.push(isObjectLike(ref) ? ref : {});
+        }
+        return refs;
+    }
+    /**
+     * Resolve the source image bytes for image-edit / image-to-video calls.
+     * Searches in priority order:
+     *   1. `media_generation.source_asset_id`  → load from Asset storage
+     *   2. The first `image_url` content block on the user message
+     *      (supports asset_id, http(s) uri, and inline data:base64 payloads)
+     * Returns `null` when no usable source image can be found.
+     */
+    async resolveSourceImageBytes(data, mediaGeneration, userId) {
+        const explicitId = isString(mediaGeneration.source_asset_id)
+            ? mediaGeneration.source_asset_id
+            : null;
+        if (explicitId) {
+            const fromAsset = await this.loadAssetBytes(userId, explicitId);
+            if (fromAsset && fromAsset.length > 0)
+                return fromAsset;
+        }
+        for (const ref of this.mediaRefsOnMessage(data, "image_url")) {
+            const bytes = await this.resolveMediaRefBytes(ref, userId);
+            if (bytes && bytes.length > 0)
+                return bytes;
+        }
+        return null;
+    }
+    /**
+     * Every reference the user attached, for reference-to-video: *all* the
+     * image and video blocks on the message rather than the first one, because
+     * the whole point of the mode is that several references describe one shot
+     * (a character, a garment, a location). `source_asset_id` joins the images
+     * so a surface that names one explicitly still reaches the model. A block
+     * whose bytes do not resolve drops rather than failing the turn — the
+     * caller refuses only when nothing at all resolved.
+     */
+    async resolveReferenceMediaBytes(data, mediaGeneration, userId) {
+        const collect = async (blockType) => {
+            const out = [];
+            for (const ref of this.mediaRefsOnMessage(data, blockType)) {
+                const bytes = await this.resolveMediaRefBytes(ref, userId);
+                if (bytes && bytes.length > 0)
+                    out.push(bytes);
+            }
+            return out;
+        };
+        const images = await collect("image_url");
+        const videos = await collect("video");
+        const explicitId = isString(mediaGeneration.source_asset_id)
+            ? mediaGeneration.source_asset_id
+            : null;
+        if (explicitId) {
+            const bytes = await this.loadAssetBytes(userId, explicitId);
+            if (bytes && bytes.length > 0)
+                images.unshift(bytes);
+        }
+        return { images, videos };
+    }
+    async handleCommand(command) {
+        return this.commands.handle(command.command, command.data ?? {}, command.request_id);
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            this.sendMessage({ type: "ping", ts: Date.now() / 1000 }).catch((err) => {
+                log.warn("Failed to send heartbeat ping", { error: String(err) });
+            });
+        }, 25_000);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    startStatsBroadcast() {
+        this.stopStatsBroadcast();
+        if (!this.systemStatsEnabled) {
+            return;
+        }
+        const send = () => {
+            this.sendMessage({
+                type: "system_stats",
+                stats: this.getSystemStats()
+            }).catch((err) => {
+                log.warn("Failed to send system stats", { error: String(err) });
+            });
+        };
+        // Fire an initial sample ~1s after connect so the sampler has a delta to
+        // report — then keep emitting on a regular cadence.
+        this.statsPrimeTimer = setTimeout(send, 1000);
+        this.statsTimer = setInterval(send, 5_000);
+    }
+    stopStatsBroadcast() {
+        if (this.statsPrimeTimer) {
+            clearTimeout(this.statsPrimeTimer);
+            this.statsPrimeTimer = null;
+        }
+        if (this.statsTimer) {
+            clearInterval(this.statsTimer);
+            this.statsTimer = null;
+        }
+    }
+    registerObserver() {
+        if (this.observerRegistered)
+            return;
+        // Both feeds are scoped by `this.userId`, which for a deployed app's
+        // visitor is the *owner* — so subscribing would stream them the ids,
+        // etags and timestamps of every row that user touches, from any tab or
+        // agent, for as long as the page is open. The public page has no cache to
+        // invalidate anyway: it renders one release and runs it.
+        if (this.appSession)
+            return;
+        ModelObserver.subscribe(this.onModelChange);
+        resourceEvents.on("change", this.onResourceEvent);
+        this.observerRegistered = true;
+    }
+    unregisterObserver() {
+        if (!this.observerRegistered)
+            return;
+        ModelObserver.unsubscribe(this.onModelChange);
+        resourceEvents.off("change", this.onResourceEvent);
+        this.observerRegistered = false;
+    }
+    onModelChange = (instance, event, meta) => {
+        if (!this.websocket)
+            return;
+        // Only forward changes for models the connected user owns. Models without
+        // a `user_id` (runtime-internal types) are forwarded to every connection.
+        const ownerId = instance.user_id;
+        if (ownerId && this.userId && ownerId !== this.userId)
+            return;
+        const resource = {
+            id: instance.partitionValue(),
+            etag: instance.getEtag()
+        };
+        // Include scope fields for resource types whose cache is keyed on a
+        // parent id (Message → thread_id, WorkflowVersion → workflow_id, etc.).
+        // Frontend handlers use these to narrow invalidation. `updated_at` rides
+        // along as the row's concurrency token: an open editor compares it against
+        // the token it last saved with to tell its own write apart from one made
+        // outside the browser (agent, CLI, another tab).
+        const data = instance;
+        for (const field of [
+            "workflow_id",
+            "thread_id",
+            "parent_id",
+            "updated_at"
+        ]) {
+            const value = data[field];
+            if (isNonEmptyString(value)) {
+                resource[field] = value;
+            }
+        }
+        const message = {
+            type: "resource_change",
+            event,
+            resource_type: instance.constructor.name.toLowerCase(),
+            resource
+        };
+        if (meta?.ops && meta.ops.length > 0) {
+            message.ops = meta.ops;
+        }
+        this.sendDetached(message);
+    };
+    onResourceEvent = (payload) => {
+        if (!this.websocket)
+            return;
+        if (payload.userId && this.userId && payload.userId !== this.userId)
+            return;
+        this.sendDetached({
+            type: "resource_change",
+            event: payload.event,
+            resource_type: payload.resource_type,
+            resource: payload.resource
+        });
+    };
+    async run(websocket) {
+        try {
+            await this.connect(websocket, this.userId ?? undefined, this.authToken ?? undefined);
+            await this.receiveMessages();
+        }
+        finally {
+            await this.disconnect();
+        }
+    }
+    async receiveMessages() {
+        while (true) {
+            let data;
+            try {
+                data = await this.receiveMessage();
+            }
+            catch (err) {
+                // A frame that fails to even decode (truncated msgpack, an
+                // oversized payload past NODETOOL_WS_MAX_MESSAGE_BYTES, …) must not
+                // kill the connection or this loop — it's just one bad frame from a
+                // client that may otherwise be mid-job. Reject it and keep reading.
+                this.logError("Failed to receive/decode WebSocket frame", err);
+                if (this.websocket &&
+                    this.websocket.clientState !== "disconnected" &&
+                    this.websocket.applicationState !== "disconnected") {
+                    await this.sendMessage({
+                        error: "invalid_frame",
+                        message: err instanceof Error ? err.message : String(err)
+                    }).catch((sendErr) => {
+                        this.logError("Failed to notify client of invalid frame", sendErr);
+                    });
+                    continue;
+                }
+                break;
+            }
+            if (data === null)
+                break;
+            const msgType = isString(data.type) ? data.type : null;
+            if (msgType !== null && msgType in controlMessageInSchemas) {
+                const schema = controlMessageInSchemas[msgType];
+                const parsed = schema.safeParse(data);
+                if (!parsed.success) {
+                    await this.sendMessage({
+                        error: "invalid_message",
+                        message: `Malformed '${msgType}' frame: ` +
+                            parsed.error.issues
+                                .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+                                .join("; ")
+                    });
+                    continue;
+                }
+            }
+            // Heartbeats show that the connection is alive, not that the user is
+            // working in this editor.
+            if (this.frontendRendererId && msgType !== "ping" && msgType !== "pong") {
+                this.frontendRendererRegistry?.touch(this.frontendRendererId);
+            }
+            if (msgType === "client_tools_manifest") {
+                const tools = Array.isArray(data.tools) ? data.tools : [];
+                this.clientToolsManifest = {};
+                for (const tool of tools) {
+                    if (isObjectLike(tool) &&
+                        isString(tool.name)) {
+                        const name = tool.name;
+                        this.clientToolsManifest[name] = tool;
+                    }
+                }
+                this.clientToolsManifestReady = true;
+                if (this.frontendRendererId) {
+                    this.frontendRendererRegistry?.markReady(this.frontendRendererId);
+                }
+                continue;
+            }
+            if (msgType === "renderer_tool_result") {
+                const rendererId = isString(data.renderer_id) ? data.renderer_id : null;
+                const toolCallId = isString(data.tool_call_id)
+                    ? data.tool_call_id
+                    : null;
+                if (rendererId &&
+                    toolCallId &&
+                    rendererId === this.frontendRendererId) {
+                    this.frontendRendererRegistry?.touch(rendererId);
+                    this.rendererToolBridge.resolveResult(toolCallId, data);
+                }
+                continue;
+            }
+            if (msgType === "tool_result") {
+                const toolCallId = isString(data.tool_call_id)
+                    ? data.tool_call_id
+                    : null;
+                if (toolCallId) {
+                    this.chat.resolveToolResult(toolCallId, data);
+                    // The waiter may live on the runner executing an adopted turn.
+                    // resolveResult no-ops on unknown ids, so forwarding is safe.
+                    for (const session of this.adoptedSessions.values()) {
+                        session.hooks.resolveToolResult(toolCallId, data);
+                    }
+                }
+                continue;
+            }
+            if (msgType === "tool_approval_response") {
+                const approvalId = isString(data.approval_id) ? data.approval_id : null;
+                if (approvalId) {
+                    this.approvalBridge.resolveResult(approvalId, data);
+                    for (const session of this.adoptedSessions.values()) {
+                        session.hooks.resolveApproval(approvalId, data);
+                    }
+                }
+                continue;
+            }
+            if (msgType === "plan_approval_response") {
+                const approvalId = isString(data.approval_id) ? data.approval_id : null;
+                if (approvalId) {
+                    this.approvalBridge.resolveResult(approvalId, data);
+                    for (const session of this.adoptedSessions.values()) {
+                        session.hooks.resolveApproval(approvalId, data);
+                    }
+                }
+                continue;
+            }
+            if (msgType === "secret_request_response") {
+                const approvalId = isString(data.approval_id) ? data.approval_id : null;
+                if (approvalId) {
+                    this.approvalBridge.resolveResult(approvalId, data);
+                    for (const session of this.adoptedSessions.values()) {
+                        session.hooks.resolveApproval(approvalId, data);
+                    }
+                }
+                continue;
+            }
+            if (msgType === "ping") {
+                await this.sendMessage({ type: "pong", ts: Date.now() / 1000 });
+                continue;
+            }
+            if (msgType === "pong") {
+                continue;
+            }
+            if (isString(data.command)) {
+                const envelopeParsed = webSocketCommandEnvelopeSchema.safeParse(data);
+                if (!envelopeParsed.success) {
+                    await this.sendMessage({
+                        error: "invalid_command",
+                        details: "Malformed command envelope: " +
+                            envelopeParsed.error.issues
+                                .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+                                .join("; ")
+                    });
+                    continue;
+                }
+                // Commands this build doesn't recognize fall through to
+                // handleCommand's own `{ error: "Unknown command" }` reply below —
+                // only known commands get their `data` payload schema-checked here.
+                const dataSchema = commandDataSchemas[envelopeParsed.data.command];
+                if (dataSchema) {
+                    const dataParsed = dataSchema.safeParse(envelopeParsed.data.data ?? {});
+                    if (!dataParsed.success) {
+                        await this.sendMessage({
+                            error: "invalid_command",
+                            details: `Malformed '${envelopeParsed.data.command}' data: ` +
+                                dataParsed.error.issues
+                                    .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+                                    .join("; ")
+                        });
+                        continue;
+                    }
+                }
+                try {
+                    // The envelope Zod-parsed above is the same frame — its schema
+                    // passes every key through, so nothing was dropped.
+                    // SAFETY: the schema types `command` as a bare string on purpose;
+                    // `handleCommand`'s switch answers `{ error: "Unknown command" }`
+                    // for anything this build does not implement.
+                    const response = await this.handleCommand({
+                        ...envelopeParsed.data,
+                        command: envelopeParsed.data.command,
+                        data: envelopeParsed.data.data ?? {},
+                        // MessagePack clients encode an absent request_id as nil; the
+                        // envelope declares it optional, not nullable.
+                        request_id: envelopeParsed.data.request_id ?? undefined
+                    });
+                    // RPC commands send their `rpc_response` frame inline (in runRpc)
+                    // and return null so we don't send a stray legacy reply.
+                    if (response)
+                        await this.sendMessage(response);
+                }
+                catch (err) {
+                    this.logError("invalid_command handling failed", err);
+                    await this.sendMessage({
+                        error: "invalid_command",
+                        details: err instanceof Error ? err.message : String(err)
+                    });
+                }
+                continue;
+            }
+            await this.sendMessage({
+                error: "invalid_message",
+                message: "All messages must include a 'command' field. Use 'chat_message' command for chat."
+            });
+        }
+    }
+}
+//# sourceMappingURL=websocket-client-session.js.map