@lamplitisles/dsh-nanocodex 0.1.0-beta.0

package/vendor/nanocodex-tools/dist/hosted/broker-core.js

@@ -0,0 +1,1278 @@
+import { HOSTED_TOOL_CALL_TIMEOUT_MS, HOSTED_TOOLS_LEASE_MS, MAX_HOSTED_TOOL_OUTPUT_BYTES, HostedToolsProtocolError, parseHostedToolsHostFrame, parseHostedToolsManagedFrame, } from "./protocol.js";
+import { hostedToolCatalogDigest } from "../../tools/hostedCatalog.mjs";
+import { EXEC_COMMAND_PARAMETERS, EXECUTION_OUTPUT_SCHEMA, MACHINE_PREVIEW_PARAMETERS, PREVIEW_OUTPUT_SCHEMA, WRITE_STDIN_PARAMETERS, } from "../../tools/execution-contract.mjs";
+const SOCKET_TAG = "hosted-tools";
+const INVALID_CONNECT_GRANT_ID = "invalid-connect-grant";
+const DEFAULT_MAX_IN_FLIGHT = 64;
+const OPEN = 1;
+const MAX_RETAINED_RECEIPTS = 512;
+const MAX_CALLS_PER_GENERATION = 512;
+const REVOKED_ROUTE_LEASE_EXPIRES_AT = -1;
+const TOOL_RESULT = Symbol.for("nanocodex.toolResult");
+const LEGACY_ROUTE_ID = "$legacy";
+export const HOSTED_MACHINE_TOOL_NAMES = Object.freeze([
+    "exec_command",
+    "write_stdin",
+    "preview",
+]);
+const MACHINE_TOOL_NAMES = new Set(HOSTED_MACHINE_TOOL_NAMES);
+const encoder = new TextEncoder();
+/**
+ * Marks the one case where an attached source is known to be absent before a
+ * durable admission. The unified ToolRouter may then select the exact
+ * same-name cloud contract. It must never infer this from an outcome message:
+ * every other unavailable, cancellation, timeout, and ambiguous outcome is
+ * pinned to the attached source and is final.
+ */
+export const HOSTED_TOOLS_PRE_ADMISSION_UNAVAILABLE = Symbol.for("nanocodex.tool.preDispatchUnavailable");
+/** Owns one reverse-tool attachment over an injected socket and durable ledger. */
+export class HostedToolsBrokerCore {
+    context;
+    #provider;
+    #pending = new Map();
+    #now;
+    #randomUUID;
+    #maxInFlight;
+    #maxCallsPerGeneration;
+    #persistence;
+    #onCatalogChanged;
+    #entryAllowed;
+    #renewLeasedAttachment;
+    #catalogValidator;
+    #nextCandidateGeneration;
+    constructor(context, options) {
+        this.context = context;
+        this.#now = options.now ?? Date.now;
+        this.#randomUUID = options.randomUUID ?? (() => crypto.randomUUID());
+        this.#maxInFlight = options.maxInFlight ?? DEFAULT_MAX_IN_FLIGHT;
+        if (!Number.isSafeInteger(this.#maxInFlight) || this.#maxInFlight < 1
+            || this.#maxInFlight > DEFAULT_MAX_IN_FLIGHT) {
+            throw new TypeError(`maxInFlight must be an integer from 1 through ${DEFAULT_MAX_IN_FLIGHT}`);
+        }
+        this.#maxCallsPerGeneration = options.maxCallsPerGeneration ?? MAX_CALLS_PER_GENERATION;
+        if (!Number.isSafeInteger(this.#maxCallsPerGeneration) || this.#maxCallsPerGeneration < 1
+            || this.#maxCallsPerGeneration > MAX_CALLS_PER_GENERATION) {
+            throw new TypeError(`maxCallsPerGeneration must be an integer from 1 through ${MAX_CALLS_PER_GENERATION}`);
+        }
+        this.#persistence = options.persistence;
+        this.#onCatalogChanged = options.onCatalogChanged;
+        this.#entryAllowed = options.entryAllowed ?? (() => true);
+        this.#renewLeasedAttachment = options.renewLeasedAttachment;
+        const now = this.#now();
+        const sockets = this.context.sockets();
+        const retainHosts = options.resumeRetainedSockets === true && sockets.length > 0;
+        const retained = this.#persistence.initialize(now);
+        this.#nextCandidateGeneration = Math.max(0, ...this.#persistence.states().map((state) => state.generation));
+        for (const socket of sockets) {
+            const generation = this.#attachment(socket)?.generation;
+            if (generation !== undefined)
+                this.#nextCandidateGeneration = Math.max(this.#nextCandidateGeneration, generation);
+        }
+        for (const state of retained) {
+            if (!state.lease_id)
+                continue;
+            const resumed = retainHosts
+                && state.lease_expires_at > now
+                && this.#routingSocketForState(state) !== undefined;
+            if (resumed)
+                continue;
+            this.#persistence.clearHost(state.lease_id, state.generation);
+            for (const socket of sockets) {
+                const attachment = this.#attachment(socket);
+                if (attachment?.routeId !== state.route_id
+                    || attachment.leaseId !== state.lease_id
+                    || attachment.generation !== state.generation)
+                    continue;
+                closeSocket(socket, 1012, "Hosted Tools owner restarted");
+            }
+        }
+        this.#provider = Object.freeze({
+            // ToolRouter owns the one aggregate tool_search. This provider exposes
+            // only the current attached definitions, which stay deferred and can be
+            // overlaid onto exact cloud contracts by that router.
+            definitions: () => {
+                return this.#publicCatalogBindings()
+                    .filter((binding) => this.#entryAllowed(binding.entry, binding.connectGrantId, binding.appToolCatalogDigest))
+                    .map((binding) => Object.freeze({
+                    ...binding.entry.definition,
+                    defer_loading: true,
+                }));
+            },
+            resolve: (name) => {
+                const prepared = this.#resolve(name);
+                if (!prepared || !this.#entryAllowed(prepared.entry, prepared.connectGrantId, prepared.appToolCatalogDigest))
+                    return undefined;
+                return this.#codeTool(name, prepared);
+            },
+            setCatalogValidator: (validator) => {
+                this.#catalogValidator = validator;
+            },
+        });
+    }
+    owns(socket) { return this.handles(socket); }
+    async message(socket, message) {
+        await this.webSocketMessage(socket, message);
+    }
+    close(socket, reason) {
+        if (this.handles(socket))
+            this.#retire(socket, reason);
+    }
+    shutdown(reason) {
+        const sockets = this.context.sockets();
+        for (const socket of sockets)
+            this.#fence(socket, reason);
+        for (const state of this.#persistence.states())
+            this.#retireState(state, reason);
+    }
+    /** Fences one attachment only when its exact durable route is still current. */
+    revokeRoute(routeId, reason) {
+        const state = this.#persistence.state(routeId) ?? emptyState(routeId);
+        const active = state.lease_id !== null;
+        if (active) {
+            const socket = this.#socketForState(state);
+            if (socket)
+                this.#fence(socket, reason);
+            else
+                this.#retireState(state, reason);
+        }
+        // Revocation can race ahead of catalog publication in another Durable
+        // Object. Retain an exact route tombstone so a previously validated socket
+        // cannot publish after its control-plane fence has completed.
+        const retired = this.#persistence.state(routeId) ?? state;
+        this.#persistence.replaceHost({
+            ...retired,
+            host_id: null,
+            lease_id: null,
+            lease_expires_at: REVOKED_ROUTE_LEASE_EXPIRES_AT,
+            catalog_json: null,
+        });
+        return active;
+    }
+    isReady() { return this.#definitions().length > 0; }
+    hasPendingCalls() { return this.#pending.size > 0; }
+    provider() { return this.#provider; }
+    /** Resolves one canonical machine primitive against its exact admitted attachment generation. */
+    machineTool(machineId, name, context) {
+        if (!MACHINE_TOOL_NAMES.has(name))
+            return undefined;
+        const binding = this.#catalogBindings().find((candidate) => (candidate.machine?.id === machineId && candidate.wireName === name));
+        if (!binding)
+            return undefined;
+        const prepared = this.#preparedTool(binding);
+        if (!this.#entryAllowed(prepared.entry, prepared.connectGrantId, prepared.appToolCatalogDigest, context))
+            return undefined;
+        return this.#codeTool(name, prepared);
+    }
+    /** Resolves one canonical machine primitive only on the named durable route. */
+    machineToolOnRoute(routeId, machineId, name, context) {
+        if (!MACHINE_TOOL_NAMES.has(name))
+            return undefined;
+        const binding = this.#catalogBindings(undefined, true).find((candidate) => (candidate.routeId === routeId
+            && candidate.machine?.id === machineId
+            && candidate.wireName === name));
+        if (!binding)
+            return undefined;
+        const prepared = this.#preparedTool(binding);
+        if (!this.#entryAllowed(prepared.entry, prepared.connectGrantId, prepared.appToolCatalogDigest, context))
+            return undefined;
+        return this.#codeTool(name, prepared);
+    }
+    /** Returns one live machine only when its exact durable route still owns it. */
+    machineOnRoute(routeId, machineId) {
+        const state = this.#persistence.state(routeId);
+        if (state === undefined)
+            return undefined;
+        const socket = this.#liveRoutingSocketForState(state);
+        if (socket === undefined)
+            return undefined;
+        const attachment = this.#attachment(socket);
+        if (attachment?.connectGrantId !== undefined)
+            return undefined;
+        return attachment?.machines?.find(({ id }) => id === machineId);
+    }
+    /** Returns the live, non-secret user-machine snapshot for the account-owned host. */
+    machines() {
+        const machines = [];
+        const ids = new Set();
+        for (const state of this.#sortedStates()) {
+            const socket = this.#liveRoutingSocketForState(state);
+            if (socket === undefined)
+                continue;
+            const attachment = this.#attachment(socket);
+            if (attachment?.connectGrantId !== undefined)
+                continue;
+            for (const machine of attachment?.machines ?? []) {
+                if (ids.has(machine.id))
+                    return [];
+                ids.add(machine.id);
+                machines.push({ routeId: state.route_id, machine });
+            }
+        }
+        return machines
+            .sort((left, right) => left.machine.id.localeCompare(right.machine.id)
+            || left.routeId.localeCompare(right.routeId))
+            .map(({ machine }) => machine);
+    }
+    accept(socket, sessionId, allowedMcpIds, appToolCatalogDigest, connectGrantId, leasedAttachment) {
+        if (allowedMcpIds !== undefined && !isConnectGrantId(connectGrantId)) {
+            throw new TypeError("Connect Hosted Tools requires an exact grant ID");
+        }
+        if (leasedAttachment !== undefined && (connectGrantId !== undefined
+            || leasedAttachment.expectedAttachmentId.length === 0
+            || leasedAttachment.fixedRouteId.length === 0
+            || leasedAttachment.renewalToken.length === 0
+            || leasedAttachment.renewalToken.length > 2_048
+            || !Number.isSafeInteger(leasedAttachment.maximumLeaseExpiresAt))) {
+            throw new TypeError("leased Hosted Tools requires one complete ordinary-route policy");
+        }
+        this.context.writeAttachment(socket, {
+            kind: SOCKET_TAG,
+            sessionId,
+            ...(allowedMcpIds === undefined ? {} : { allowedMcpIds: [...allowedMcpIds] }),
+            ...(appToolCatalogDigest === undefined ? {} : { appToolCatalogDigest }),
+            ...(connectGrantId === undefined ? {} : { connectGrantId }),
+            ...(leasedAttachment === undefined ? {} : {
+                expectedAttachmentId: leasedAttachment.expectedAttachmentId,
+                maximumLeaseExpiresAt: leasedAttachment.maximumLeaseExpiresAt,
+                fixedRouteId: leasedAttachment.fixedRouteId,
+                renewalToken: leasedAttachment.renewalToken,
+            }),
+        });
+        this.context.accept(socket);
+    }
+    handles(socket) {
+        return this.#attachment(socket)?.kind === SOCKET_TAG;
+    }
+    async webSocketMessage(socket, message) {
+        if (!this.handles(socket))
+            return;
+        if (typeof message !== "string") {
+            this.#fence(socket, "Hosted Tools requires bounded text frames", 1003);
+            return;
+        }
+        let frame;
+        try {
+            frame = parseHostedToolsHostFrame(message);
+            await this.#dispatchHostFrame(socket, frame);
+        }
+        catch (error) {
+            const protocol = error instanceof HostedToolsProtocolError
+                ? error
+                : new HostedToolsProtocolError("broker_failure", errorMessage(error));
+            this.#fence(socket, `${protocol.code}: ${protocol.message}`);
+        }
+    }
+    webSocketClose(socket, code, reason) {
+        if (!this.handles(socket))
+            return;
+        this.#retire(socket, reason || `peer closed with code ${code}`);
+        closeSocket(socket, code, reason || "Hosted Tools peer closed");
+    }
+    webSocketError(socket) {
+        if (!this.handles(socket))
+            return;
+        this.#retire(socket, "WebSocket failed");
+        closeSocket(socket, 1011, "Hosted Tools WebSocket failed");
+    }
+    /** May be called by an owning alarm; normal reads and call timers also expire leases lazily. */
+    expire() {
+        for (const state of this.#persistence.states()) {
+            if (!state.lease_id || state.lease_expires_at > this.#now())
+                continue;
+            const socket = this.#socketForState(state);
+            if (socket)
+                this.#fence(socket, "Hosted Tools lease expired");
+            else
+                this.#retireState(state, "Hosted Tools lease expired");
+        }
+    }
+    cancel(callId) {
+        const pending = this.#pending.get(callId);
+        if (!pending)
+            return false;
+        const row = this.#persistence.call(callId);
+        if (!row || row.state !== "dispatched")
+            return false;
+        const state = this.#stateForLease(row.lease_id, row.generation);
+        const socket = this.#socketForState(state);
+        if (!socket
+            || !state
+            || state.lease_expires_at <= this.#now()) {
+            this.#finishAmbiguous(row, "Hosted Tools cancellation lost its pinned attachment");
+            return false;
+        }
+        const cancelRequested = this.#persistence.markCancelRequested(callId, this.#now());
+        if (!cancelRequested || cancelRequested.state !== "dispatched"
+            || cancelRequested.cancel_requested !== 1)
+            return false;
+        try {
+            this.#send(socket, {
+                type: "cancel",
+                call_id: row.call_id,
+            });
+            return true;
+        }
+        catch {
+            this.#retire(socket, "cancellation delivery failed");
+            closeSocket(socket, 1011, "Hosted Tools cancellation delivery failed");
+            return false;
+        }
+    }
+    async #dispatchHostFrame(socket, frame) {
+        if (frame.type === "catalog")
+            await this.#publishCatalog(socket, frame);
+        else if (frame.type === "ping")
+            await this.#heartbeat(socket, frame);
+        else if (frame.type === "drain")
+            this.#drain(socket);
+        else
+            this.#completeResult(socket, frame);
+    }
+    #activeAttachment(socket) {
+        const attachment = this.#attachment(socket);
+        const state = attachment?.routeId === undefined
+            ? undefined
+            : this.#persistence.state(attachment.routeId);
+        if (!attachment?.active || !attachment.leaseId || attachment.generation === undefined || !state
+            || state.lease_id !== attachment.leaseId
+            || state.generation !== attachment.generation
+            || state.lease_expires_at <= this.#now()) {
+            throw new HostedToolsProtocolError("stale_socket", "socket no longer owns the tool attachment");
+        }
+        return attachment;
+    }
+    async #heartbeat(socket, frame) {
+        let attachment = this.#activeAttachment(socket);
+        if (attachment.renewalToken !== undefined) {
+            const renewal = {
+                expectedAttachmentId: attachment.expectedAttachmentId,
+                fixedRouteId: attachment.fixedRouteId,
+                renewalToken: attachment.renewalToken,
+            };
+            let maximumLeaseExpiresAt;
+            try {
+                maximumLeaseExpiresAt = await this.#renewLeasedAttachment?.(renewal);
+            }
+            catch {
+                this.#retire(socket, "leased Hosted Tools validation unavailable");
+                closeSocket(socket, 1011, "leased Hosted Tools validation unavailable");
+                return;
+            }
+            if (!Number.isSafeInteger(maximumLeaseExpiresAt)
+                || Number(maximumLeaseExpiresAt) <= this.#now()) {
+                this.revokeRoute(renewal.fixedRouteId, "leased Hosted Tools validation failed");
+                return;
+            }
+            const renewedExpiry = Number(maximumLeaseExpiresAt);
+            const renewed = this.#activeAttachment(socket);
+            if (renewed.routeId !== attachment.routeId
+                || renewed.leaseId !== attachment.leaseId
+                || renewed.generation !== attachment.generation
+                || renewed.fixedRouteId !== renewal.fixedRouteId
+                || renewed.expectedAttachmentId !== renewal.expectedAttachmentId
+                || renewed.renewalToken !== renewal.renewalToken) {
+                throw new HostedToolsProtocolError("stale_socket", "socket changed while its leased attachment was being validated");
+            }
+            attachment = { ...renewed, maximumLeaseExpiresAt: renewedExpiry };
+            this.context.writeAttachment(socket, attachment);
+        }
+        const expiresAt = Math.min(this.#now() + HOSTED_TOOLS_LEASE_MS, attachment.maximumLeaseExpiresAt ?? Number.MAX_SAFE_INTEGER);
+        const state = this.#persistence.state(attachment.routeId);
+        this.#persistence.replaceHost({ ...state, lease_expires_at: expiresAt });
+        this.#send(socket, {
+            type: "pong",
+            nonce: frame.nonce,
+        });
+    }
+    async #publishCatalog(socket, frame) {
+        const initial = this.#attachment(socket);
+        if (!initial || initial.leaseId || initial.generation !== undefined || initial.active) {
+            throw new HostedToolsProtocolError("catalog_immutable", "one immutable catalog is allowed per socket");
+        }
+        if (this.#nextCandidateGeneration >= Number.MAX_SAFE_INTEGER) {
+            throw new HostedToolsProtocolError("generation_exhausted", "Hosted Tools generation is exhausted");
+        }
+        const routeId = initial.fixedRouteId ?? scopedRouteId(initial.connectGrantId, frame.attachment_id);
+        let maximumLeaseExpiresAt = initial.maximumLeaseExpiresAt;
+        if (initial.renewalToken !== undefined) {
+            const renewal = {
+                expectedAttachmentId: initial.expectedAttachmentId,
+                fixedRouteId: routeId,
+                renewalToken: initial.renewalToken,
+            };
+            try {
+                const renewed = await this.#renewLeasedAttachment?.(renewal);
+                if (!Number.isSafeInteger(renewed) || Number(renewed) <= this.#now()) {
+                    this.revokeRoute(routeId, "leased Hosted Tools validation failed before admission");
+                    throw new HostedToolsProtocolError("route_revoked", "leased Hosted Tools validation failed before admission");
+                }
+                maximumLeaseExpiresAt = Number(renewed);
+            }
+            catch (error) {
+                if (error instanceof HostedToolsProtocolError)
+                    throw error;
+                throw new HostedToolsProtocolError("lease_validation_unavailable", "leased Hosted Tools validation was unavailable before admission");
+            }
+        }
+        let state = this.#persistence.state(routeId) ?? emptyState(routeId);
+        if (state.lease_id === null && state.lease_expires_at === REVOKED_ROUTE_LEASE_EXPIRES_AT) {
+            throw new HostedToolsProtocolError("route_revoked", "tool attachment route was revoked before admission");
+        }
+        if (state.lease_id && state.lease_expires_at <= this.#now()) {
+            const expiredSocket = this.#socketForState(state);
+            if (expiredSocket)
+                this.#fence(expiredSocket, "Hosted Tools lease expired");
+            else
+                this.#retireState(state, "Hosted Tools lease expired");
+            state = this.#persistence.state(routeId) ?? emptyState(routeId);
+        }
+        const activeSocket = this.#socketForState(state);
+        const activeGrantId = activeSocket === undefined
+            ? undefined
+            : this.#activeConnectGrantId(state);
+        if (activeSocket !== undefined && activeGrantId !== initial.connectGrantId) {
+            throw new HostedToolsProtocolError("grant_conflict", "another Connect grant already owns this agent's tool host");
+        }
+        const generation = ++this.#nextCandidateGeneration;
+        const leaseId = this.#randomUUID();
+        const expiresAt = Math.min(this.#now() + HOSTED_TOOLS_LEASE_MS, maximumLeaseExpiresAt ?? Number.MAX_SAFE_INTEGER);
+        const candidate = {
+            ...initial,
+            ...(maximumLeaseExpiresAt === undefined ? {} : { maximumLeaseExpiresAt }),
+            routeId,
+            leaseId,
+            generation,
+        };
+        this.context.writeAttachment(socket, candidate);
+        const catalogJson = JSON.stringify(frame.tools);
+        const machine = frame.machines?.[0];
+        const candidateEntries = frame.tools
+            .filter((entry) => !reservedMachineEntry(entry, machine))
+            .map((entry) => exposedEntry(entry, machine));
+        const candidateDefinitions = candidateEntries.map((entry) => Object.freeze({
+            ...entry,
+            definition: Object.freeze({
+                ...entry.definition,
+                defer_loading: true,
+            }),
+        }));
+        try {
+            if (initial.connectGrantId !== undefined && (frame.machines?.length ?? 0) > 0) {
+                throw new Error("Connect tool hosts cannot publish account machine metadata");
+            }
+            if ((frame.machines?.length ?? 0) > 0
+                && (frame.machines?.length !== 1 || frame.attachment_id !== frame.machines[0]?.id)) {
+                throw new Error("an account machine route requires one machine whose id equals attachment_id");
+            }
+            if (initial.expectedAttachmentId !== undefined
+                && (frame.attachment_id !== initial.expectedAttachmentId
+                    || frame.machines?.length !== 1
+                    || frame.machines[0]?.id !== initial.expectedAttachmentId)) {
+                throw new Error("leased tool attachment must publish its exact assigned machine ID");
+            }
+            if (initial.expectedAttachmentId !== undefined) {
+                const extra = frame.tools.find((entry) => !MACHINE_TOOL_NAMES.has(entry.definition.name));
+                if (extra !== undefined) {
+                    throw new Error("leased tool attachments may publish only canonical machine primitives");
+                }
+            }
+            if (machine !== undefined)
+                validateMachineToolContracts(frame.tools);
+            if (initial.allowedMcpIds !== undefined) {
+                if (!isConnectGrantId(initial.connectGrantId)) {
+                    throw new Error("Connect tool host is missing its exact grant binding");
+                }
+                const allowed = new Set(initial.allowedMcpIds);
+                const forbiddenMcp = frame.tools.find((entry) => {
+                    const match = /^mcp:([A-Za-z0-9_-]{43})$/.exec(entry.provider);
+                    return entry.provider.startsWith("mcp:")
+                        && (match === null || !allowed.has(match[1]));
+                });
+                if (forbiddenMcp) {
+                    throw new Error(`tool ${forbiddenMcp.provider}:${forbiddenMcp.remote_name} is not authorized by the Connect grant`);
+                }
+                const appTools = frame.tools.filter((entry) => !entry.provider.startsWith("mcp:"));
+                const candidateDigest = appTools.length === 0
+                    ? undefined
+                    : await hostedToolCatalogDigest(appTools);
+                if (candidateDigest !== initial.appToolCatalogDigest) {
+                    throw new Error("the app-local tool catalog does not match the signed Connect grant");
+                }
+            }
+            const otherBindings = this.#publicCatalogBindings(routeId, true);
+            const exposedNames = new Set(otherBindings.map((binding) => binding.entry.definition.name));
+            const duplicateTool = candidateEntries.find((entry) => exposedNames.has(entry.definition.name));
+            if (duplicateTool) {
+                throw new Error(`tool name ${duplicateTool.definition.name} is already exposed by another attachment`);
+            }
+            if (initial.connectGrantId === undefined) {
+                const machineIds = new Set(this.#machineIds(routeId));
+                const duplicateMachine = frame.machines?.find((machine) => machineIds.has(machine.id));
+                if (duplicateMachine) {
+                    throw new Error(`machine ID ${duplicateMachine.id} is already published by another attachment`);
+                }
+            }
+            const validator = this.#catalogValidator;
+            const aggregateDefinitions = [
+                ...otherBindings.map((binding) => Object.freeze({
+                    ...binding.entry,
+                    definition: Object.freeze({
+                        ...binding.entry.definition,
+                        defer_loading: true,
+                    }),
+                })),
+                ...candidateDefinitions,
+            ].sort((left, right) => left.definition.name.localeCompare(right.definition.name));
+            if (validator !== undefined && validator(aggregateDefinitions) !== true) {
+                throw new Error("ToolRouter rejected the candidate catalog");
+            }
+        }
+        catch (error) {
+            throw new HostedToolsProtocolError("catalog_contract_mismatch", `candidate catalog is incompatible with the managed tool route: ${errorMessage(error)}`);
+        }
+        const now = this.#now();
+        const replaced = state.lease_id ? state : undefined;
+        // A failed ready send must leave the previous attachment routable.
+        this.#send(socket, { type: "ready" });
+        this.#persistence.transaction(() => {
+            if (state.lease_id) {
+                this.#persistence.markGenerationAmbiguous(state.lease_id, state.generation, JSON.stringify(hostedToolsAmbiguous("Hosted Tools call became ambiguous when its host was replaced")), now);
+            }
+            this.#persistence.replaceHost({
+                route_id: routeId,
+                generation,
+                host_id: candidate.sessionId,
+                lease_id: leaseId,
+                lease_expires_at: expiresAt,
+                catalog_json: catalogJson,
+            });
+        });
+        if (replaced?.lease_id) {
+            const outcome = hostedToolsAmbiguous("Hosted Tools call became ambiguous when its host was replaced");
+            this.#resolveGeneration(replaced.lease_id, replaced.generation, outcome);
+            for (const existing of this.context.sockets()) {
+                if (existing === socket)
+                    continue;
+                const old = this.#attachment(existing);
+                if (!old?.active || old.leaseId !== replaced.lease_id || old.generation !== replaced.generation)
+                    continue;
+                closeSocket(existing, 1008, "Hosted Tools attachment replaced");
+            }
+        }
+        this.context.writeAttachment(socket, {
+            ...candidate,
+            active: true,
+            ...(frame.machines === undefined ? {} : { machines: frame.machines }),
+        });
+        this.#notifyCatalogChanged();
+    }
+    #drain(socket) {
+        const attachment = this.#activeAttachment(socket);
+        if (attachment.draining) {
+            throw new HostedToolsProtocolError("already_draining", "socket is already draining");
+        }
+        const state = this.#persistence.state(attachment.routeId);
+        // Visibility is removed before the peer is told that draining began.
+        this.#persistence.clearCatalog(state.lease_id, state.generation);
+        this.context.writeAttachment(socket, { ...attachment, draining: true });
+        this.#notifyCatalogChanged();
+        this.#send(socket, { type: "draining" });
+    }
+    #completeResult(socket, frame) {
+        const attachment = this.#activeAttachment(socket);
+        const row = this.#persistence.call(frame.call_id);
+        const stored = JSON.stringify(frame.outcome);
+        if (!row
+            || row.lease_id !== attachment.leaseId
+            || row.generation !== attachment.generation) {
+            throw new HostedToolsProtocolError("unknown_call", "result does not match an admitted pinned call");
+        }
+        if (row.state === "ambiguous") {
+            const receiptJson = JSON.stringify({ type: "result", outcome: frame.outcome });
+            const recorded = this.#persistence.recordLateReceipt(row.call_id, receiptJson, this.#now());
+            if (!recorded || recorded.receipt_json !== receiptJson) {
+                throw new HostedToolsProtocolError("result_conflict", "late terminal receipt conflicts with retained proof");
+            }
+            this.#ackResult(socket, frame);
+            return;
+        }
+        if (row.state !== "dispatched") {
+            if (row.result_json === stored && row.state === outcomeState(frame.outcome)) {
+                this.#ackResult(socket, frame);
+                return;
+            }
+            throw new HostedToolsProtocolError("result_conflict", "terminal call result cannot be changed");
+        }
+        if (this.#now() >= row.deadline_at) {
+            this.#finishAmbiguous(row, "Hosted Tools call result arrived after its durable deadline");
+            const receiptJson = JSON.stringify({ type: "result", outcome: frame.outcome });
+            const recorded = this.#persistence.recordLateReceipt(row.call_id, receiptJson, this.#now());
+            if (!recorded || recorded.receipt_json !== receiptJson) {
+                throw new HostedToolsProtocolError("result_conflict", "late terminal receipt conflicts with retained proof");
+            }
+            this.#ackResult(socket, frame);
+            return;
+        }
+        if (frame.outcome.status === "completed"
+            && encoder.encode(JSON.stringify(frame.outcome.output)).byteLength > row.output_byte_budget) {
+            throw new HostedToolsProtocolError("output_budget_exceeded", "completed output exceeds the byte budget pinned to the call");
+        }
+        const completed = this.#persistence.transitionCall(row.call_id, ["dispatched"], outcomeState(frame.outcome), stored, this.#now());
+        if (!completed || completed.result_json !== stored) {
+            throw new HostedToolsProtocolError("result_conflict", "call result lost durable ownership");
+        }
+        const pending = this.#takePending(row.call_id);
+        this.#pruneReceipts();
+        this.#ackResult(socket, frame);
+        pending?.resolve(frame.outcome);
+    }
+    #ackResult(socket, frame) {
+        try {
+            this.#send(socket, {
+                type: "ack",
+                call_id: frame.call_id,
+            });
+        }
+        catch {
+            this.#retire(socket, "result acknowledgement delivery failed");
+            closeSocket(socket, 1011, "Hosted Tools result acknowledgement failed");
+        }
+    }
+    #definitions() {
+        return this.#publicCatalogBindings().map((binding) => binding.entry);
+    }
+    #resolve(name) {
+        const binding = this.#publicCatalogBindings()
+            .find((candidate) => candidate.entry.definition.name === name);
+        if (!binding)
+            return undefined;
+        return this.#preparedTool(binding);
+    }
+    #preparedTool(binding) {
+        return Object.freeze({
+            routeToken: JSON.stringify([
+                binding.routeId,
+                binding.generation,
+                binding.leaseId,
+                binding.wireName,
+            ]),
+            ...(binding.connectGrantId === undefined ? {} : { connectGrantId: binding.connectGrantId }),
+            ...(binding.appToolCatalogDigest === undefined
+                ? {}
+                : { appToolCatalogDigest: binding.appToolCatalogDigest }),
+            canonicalName: binding.wireName,
+            ...(binding.machine === undefined ? {} : { machine: binding.machine }),
+            entry: binding.entry,
+            invoke: (request) => this.#invoke(binding, request),
+        });
+    }
+    #codeTool(name, prepared) {
+        return Object.freeze({
+            name,
+            parallelSafe: prepared.entry.parallel_safe,
+            routeToken: prepared.routeToken,
+            provider: prepared.entry.provider,
+            remoteName: prepared.entry.remote_name,
+            summary: prepared.entry.summary,
+            timeoutMs: prepared.entry.timeout_ms,
+            handler: async (input, context) => {
+                if (!this.#entryAllowed(prepared.entry, prepared.connectGrantId, prepared.appToolCatalogDigest, context)) {
+                    return toolResult("Hosted tool is outside the active grant", {
+                        status: "unavailable",
+                        message: "Hosted tool is outside the active grant",
+                    }, false, null);
+                }
+                const outcome = await prepared.invoke({
+                    sessionId: context.sessionId,
+                    callId: context.callId,
+                    model: context.model ?? "unknown",
+                    input: input,
+                    outputTokenBudget: 10_000,
+                    ...(context.signal === undefined ? {} : { signal: context.signal }),
+                });
+                if (outcome.status === "completed") {
+                    return wireToolResult(outcome.output, prepared.canonicalName, prepared.machine);
+                }
+                const result = toolResult(outcome.message, outcome, false, null);
+                return outcome[HOSTED_TOOLS_PRE_ADMISSION_UNAVAILABLE] === true
+                    ? Object.freeze({
+                        ...result,
+                        [HOSTED_TOOLS_PRE_ADMISSION_UNAVAILABLE]: true,
+                    })
+                    : result;
+            },
+        });
+    }
+    #invoke(binding, request) {
+        const retained = this.#persistence.callBySource(request.sessionId, request.callId);
+        const leaseId = binding.leaseId;
+        const now = this.#now();
+        const deadlineAt = request.deadlineAt === undefined && retained
+            ? retained.deadline_at
+            : Math.min(request.deadlineAt ?? Number.MAX_SAFE_INTEGER, now + Math.min(binding.entry.timeout_ms, HOSTED_TOOL_CALL_TIMEOUT_MS));
+        const outputByteBudget = request.outputByteBudget ?? MAX_HOSTED_TOOL_OUTPUT_BYTES;
+        const transportCallId = retained?.call_id ?? this.#randomUUID();
+        const hostId = retained?.host_id ?? binding.hostId;
+        const pinnedLeaseId = retained?.lease_id ?? binding.leaseId;
+        const generation = retained?.generation ?? binding.generation;
+        let call;
+        try {
+            call = parseHostedToolsManagedFrame(JSON.stringify({
+                type: "call",
+                session_id: request.sessionId,
+                call_id: transportCallId,
+                model: request.model,
+                name: binding.wireName,
+                input: request.input,
+                output_token_budget: request.outputTokenBudget,
+                output_byte_budget: outputByteBudget,
+                deadline_at: deadlineAt,
+            }));
+        }
+        catch (error) {
+            return Promise.resolve(hostedToolsUnavailable(`Hosted Tools call was invalid before dispatch: ${errorMessage(error)}`));
+        }
+        const inputJson = JSON.stringify(call.input);
+        const proposed = {
+            call_id: call.call_id,
+            session_id: call.session_id,
+            source_call_id: request.callId,
+            host_id: hostId,
+            lease_id: pinnedLeaseId,
+            generation,
+            model: call.model,
+            name: call.name,
+            input_json: inputJson,
+            output_token_budget: call.output_token_budget,
+            output_byte_budget: call.output_byte_budget,
+            deadline_at: call.deadline_at,
+            cancel_requested: 0,
+            state: "admitted",
+            result_json: null,
+            receipt_json: null,
+        };
+        if (retained)
+            return this.#repeatedCall(retained, proposed);
+        const existing = this.#persistence.call(call.call_id);
+        if (existing)
+            return this.#repeatedCall(existing, proposed);
+        if (!this.#attachmentIsPresent(binding, now)) {
+            return Promise.resolve(preAdmissionUnavailable("Hosted Tools attachment was absent before durable admission"));
+        }
+        if (this.#persistence.generationCallCount(leaseId, binding.generation)
+            >= this.#maxCallsPerGeneration) {
+            const state = this.#persistence.state(binding.routeId);
+            const socket = state?.lease_id === leaseId && state.generation === binding.generation
+                ? this.#socketForState(state)
+                : undefined;
+            if (socket)
+                this.#fence(socket, "Hosted Tools generation exhausted its durable call ledger");
+            else if (state?.lease_id === leaseId && state.generation === binding.generation) {
+                this.#retireState(state, "Hosted Tools generation exhausted its durable call ledger");
+            }
+            return Promise.resolve(hostedToolsUnavailable("Hosted Tools generation reached its durable call limit"));
+        }
+        try {
+            this.#persistence.insertCall(proposed, now);
+        }
+        catch {
+            const recovered = this.#persistence.callBySource(request.sessionId, request.callId)
+                ?? this.#persistence.call(call.call_id);
+            if (recovered)
+                return this.#repeatedCall(recovered, proposed);
+            return Promise.resolve(hostedToolsAmbiguous("Hosted Tools admission may have persisted; replay is unsafe"));
+        }
+        if (request.signal?.aborted) {
+            return Promise.resolve(this.#finishBeforeDispatch(proposed, "cancelled", {
+                status: "cancelled",
+                message: "Hosted Tools call was cancelled before dispatch",
+            }));
+        }
+        const current = this.#persistence.state(binding.routeId);
+        const dispatchNow = this.#now();
+        const socket = this.#routingSocketForState(current);
+        if (!socket
+            || !current
+            || current.host_id !== binding.hostId
+            || current.lease_id !== leaseId
+            || current.generation !== binding.generation
+            || current.lease_expires_at <= dispatchNow
+            || deadlineAt <= dispatchNow) {
+            return Promise.resolve(this.#finishBeforeDispatch(proposed, "unavailable", hostedToolsUnavailable("Hosted Tools binding became unavailable before dispatch")));
+        }
+        if (this.#persistence.activeCallCount(leaseId, binding.generation) > this.#maxInFlight) {
+            return Promise.resolve(this.#finishBeforeDispatch(proposed, "unavailable", hostedToolsUnavailable("Hosted Tools host is at its bounded in-flight limit")));
+        }
+        const dispatched = this.#persistence.transitionCall(call.call_id, ["admitted"], "dispatched", "", dispatchNow);
+        if (!dispatched || dispatched.state !== "dispatched") {
+            return Promise.resolve(hostedToolsAmbiguous("Hosted Tools call lost durable dispatch ownership"));
+        }
+        let resolve;
+        const promise = new Promise((completed) => { resolve = completed; });
+        const pending = {
+            leaseId,
+            generation: binding.generation,
+            deadlineAt,
+            promise,
+            resolve,
+        };
+        this.#pending.set(call.call_id, pending);
+        if (request.signal) {
+            const cancel = () => { this.cancel(call.call_id); };
+            request.signal.addEventListener("abort", cancel, { once: true });
+            pending.removeAbort = () => request.signal?.removeEventListener("abort", cancel);
+        }
+        this.#armExpiry(call.call_id, pending, Math.min(current.lease_expires_at, deadlineAt));
+        try {
+            this.#send(socket, call);
+        }
+        catch {
+            this.#retire(socket, "call delivery failed");
+            closeSocket(socket, 1011, "Hosted Tools call delivery failed");
+        }
+        return promise;
+    }
+    #attachmentIsPresent(binding, now) {
+        const current = this.#persistence.state(binding.routeId);
+        return current !== undefined
+            && current.host_id === binding.hostId
+            && current.lease_id === binding.leaseId
+            && current.generation === binding.generation
+            && current.lease_expires_at > now
+            && this.#routingSocketForState(current) !== undefined;
+    }
+    #repeatedCall(existing, proposed) {
+        if (!sameImmutableCall(existing, proposed)) {
+            const state = this.#stateForLease(existing.lease_id, existing.generation);
+            const socket = this.#socketForState(state);
+            if (socket)
+                this.#fence(socket, "call ID was reused with different immutable fields");
+            return Promise.resolve(hostedToolsAmbiguous("Hosted Tools call ID conflicts with retained durable state"));
+        }
+        if (existing.result_json)
+            return Promise.resolve(JSON.parse(existing.result_json));
+        const pending = this.#pending.get(existing.call_id);
+        if (existing.state === "dispatched" && pending)
+            return pending.promise;
+        return Promise.resolve(existing.state === "admitted"
+            ? hostedToolsUnavailable("Hosted Tools call was admitted but never dispatched")
+            : hostedToolsAmbiguous("Hosted Tools call has no retained terminal receipt"));
+    }
+    #finishBeforeDispatch(row, state, outcome) {
+        this.#persistence.transitionCall(row.call_id, ["admitted"], state, JSON.stringify(outcome), this.#now());
+        this.#pruneReceipts();
+        return outcome;
+    }
+    #armExpiry(callId, pending, at) {
+        if (pending.timeout !== undefined)
+            clearTimeout(pending.timeout);
+        pending.timeout = setTimeout(() => {
+            const current = this.#pending.get(callId);
+            if (current !== pending)
+                return;
+            const state = this.#stateForLease(pending.leaseId, pending.generation);
+            const now = this.#now();
+            if (state?.lease_id === pending.leaseId
+                && state.generation === pending.generation
+                && state.lease_expires_at > now
+                && pending.deadlineAt > now) {
+                this.#armExpiry(callId, pending, Math.min(state.lease_expires_at, pending.deadlineAt));
+                return;
+            }
+            if (state?.lease_id === pending.leaseId
+                && state.generation === pending.generation
+                && state.lease_expires_at <= now) {
+                const socket = this.#socketForState(state);
+                if (socket)
+                    this.#fence(socket, "Hosted Tools lease expired during a call");
+                else
+                    this.#retireState(state, "Hosted Tools lease expired during a call");
+                return;
+            }
+            const row = this.#persistence.call(callId);
+            if (row) {
+                this.cancel(callId);
+                this.#finishAmbiguous(row, "Hosted Tools call deadline expired after dispatch");
+            }
+        }, Math.max(1, at - this.#now()));
+    }
+    #finishAmbiguous(row, message) {
+        const outcome = hostedToolsAmbiguous(message);
+        this.#persistence.transitionCall(row.call_id, ["dispatched"], "ambiguous", JSON.stringify(outcome), this.#now());
+        this.#pruneReceipts();
+        this.#takePending(row.call_id)?.resolve(outcome);
+    }
+    #retire(socket, reason) {
+        const attachment = this.#attachment(socket);
+        if (!attachment?.leaseId || attachment.generation === undefined)
+            return;
+        const state = attachment.routeId === undefined
+            ? undefined
+            : this.#persistence.state(attachment.routeId);
+        if (state)
+            this.#retireState(state, reason, attachment.leaseId, attachment.generation);
+    }
+    #retireState(state, reason, leaseId = state.lease_id ?? undefined, generation = state.generation) {
+        if (!leaseId)
+            return;
+        const outcome = hostedToolsAmbiguous(`Hosted Tools outcome is ambiguous after transport loss: ${reason}`);
+        this.#persistence.transaction(() => {
+            this.#persistence.markGenerationAmbiguous(leaseId, generation, JSON.stringify(outcome), this.#now());
+            this.#persistence.clearHost(leaseId, generation);
+        });
+        this.#pruneReceipts();
+        this.#resolveGeneration(leaseId, generation, outcome);
+        this.#notifyCatalogChanged();
+    }
+    #resolveGeneration(leaseId, generation, outcome) {
+        for (const [callId, pending] of this.#pending) {
+            if (pending.leaseId !== leaseId || pending.generation !== generation)
+                continue;
+            this.#takePending(callId)?.resolve(outcome);
+        }
+    }
+    #pruneReceipts() {
+        this.#persistence.pruneReceipts(MAX_RETAINED_RECEIPTS);
+    }
+    #takePending(callId) {
+        const pending = this.#pending.get(callId);
+        if (!pending)
+            return undefined;
+        if (pending.timeout !== undefined)
+            clearTimeout(pending.timeout);
+        pending.removeAbort?.();
+        this.#pending.delete(callId);
+        return pending;
+    }
+    #fence(socket, reason, code = 1008) {
+        const attachment = this.#attachment(socket);
+        if (attachment?.leaseId && attachment.generation !== undefined) {
+            this.#retire(socket, reason);
+        }
+        closeSocket(socket, code, boundedReason(reason));
+    }
+    #socketForState(state) {
+        if (!state)
+            return undefined;
+        if (!state.host_id || !state.lease_id)
+            return undefined;
+        return this.context.sockets().find((socket) => {
+            const attachment = this.#attachment(socket);
+            return socket.readyState === OPEN
+                && attachment?.leaseId === state.lease_id
+                && attachment.generation === state.generation
+                && attachment.routeId === state.route_id
+                && attachment.active === true;
+        });
+    }
+    #routingSocketForState(state) {
+        if (!state)
+            return undefined;
+        if (!state.catalog_json)
+            return undefined;
+        const socket = this.#socketForState(state);
+        return socket && this.#attachment(socket)?.draining !== true ? socket : undefined;
+    }
+    #liveRoutingSocketForState(state) {
+        if (state.lease_id && state.lease_expires_at <= this.#now()) {
+            const socket = this.#socketForState(state);
+            if (socket)
+                this.#fence(socket, "Hosted Tools lease expired");
+            else
+                this.#retireState(state, "Hosted Tools lease expired");
+            return undefined;
+        }
+        return this.#routingSocketForState(state);
+    }
+    #activeConnectGrantId(state) {
+        const socket = this.#socketForState(state);
+        if (socket === undefined)
+            return undefined;
+        const attachment = this.#attachment(socket);
+        if (attachment?.connectGrantId === undefined)
+            return undefined;
+        return isConnectGrantId(attachment.connectGrantId)
+            ? attachment.connectGrantId
+            : INVALID_CONNECT_GRANT_ID;
+    }
+    #activeAppToolCatalogDigest(state) {
+        const socket = this.#socketForState(state);
+        return socket === undefined ? undefined : this.#attachment(socket)?.appToolCatalogDigest;
+    }
+    #sortedStates() {
+        return [...this.#persistence.states()].sort((left, right) => left.route_id.localeCompare(right.route_id));
+    }
+    #stateForLease(leaseId, generation) {
+        return this.#persistence.states().find((state) => state.lease_id === leaseId
+            && state.generation === generation);
+    }
+    #catalogBindings(excludeRouteId, includeAmbiguous = false) {
+        const bindings = [];
+        for (const state of this.#sortedStates()) {
+            if (state.route_id === excludeRouteId || !state.host_id || !state.lease_id || !state.catalog_json)
+                continue;
+            const socket = this.#liveRoutingSocketForState(state);
+            if (!socket)
+                continue;
+            const attachment = this.#attachment(socket);
+            const connectGrantId = this.#activeConnectGrantId(state);
+            const appToolCatalogDigest = this.#activeAppToolCatalogDigest(state);
+            let entries;
+            try {
+                entries = JSON.parse(state.catalog_json);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const machine = attachment?.machines?.[0];
+                bindings.push(Object.freeze({
+                    routeId: state.route_id,
+                    hostId: state.host_id,
+                    leaseId: state.lease_id,
+                    generation: state.generation,
+                    wireName: entry.definition.name,
+                    ...(machine === undefined ? {} : { machine }),
+                    entry: exposedEntry(entry, machine),
+                    ...(connectGrantId === undefined ? {} : { connectGrantId }),
+                    ...(appToolCatalogDigest === undefined ? {} : { appToolCatalogDigest }),
+                }));
+            }
+        }
+        bindings.sort((left, right) => left.routeId.localeCompare(right.routeId)
+            || left.entry.definition.name.localeCompare(right.entry.definition.name));
+        if (includeAmbiguous)
+            return bindings;
+        const counts = new Map();
+        for (const binding of bindings) {
+            const name = binding.entry.definition.name;
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+        return bindings.filter((binding) => counts.get(binding.entry.definition.name) === 1);
+    }
+    #publicCatalogBindings(excludeRouteId, includeAmbiguous = false) {
+        return this.#catalogBindings(excludeRouteId, includeAmbiguous)
+            .filter((binding) => !reservedMachineBinding(binding));
+    }
+    #machineIds(excludeRouteId) {
+        const ids = [];
+        for (const state of this.#sortedStates()) {
+            if (state.route_id === excludeRouteId)
+                continue;
+            const socket = this.#liveRoutingSocketForState(state);
+            if (!socket)
+                continue;
+            const attachment = this.#attachment(socket);
+            if (attachment?.connectGrantId !== undefined)
+                continue;
+            for (const machine of attachment?.machines ?? [])
+                ids.push(machine.id);
+        }
+        return ids;
+    }
+    #attachment(socket) {
+        const value = this.context.readAttachment(socket);
+        return value?.kind === SOCKET_TAG ? value : undefined;
+    }
+    #send(socket, frame) {
+        socket.send(JSON.stringify(frame));
+    }
+    #notifyCatalogChanged() {
+        this.#onCatalogChanged?.(this.#definitions());
+    }
+}
+function emptyState(routeId) {
+    return {
+        route_id: routeId,
+        generation: 0,
+        host_id: null,
+        lease_id: null,
+        lease_expires_at: 0,
+        catalog_json: null,
+    };
+}
+function scopedRouteId(connectGrantId, attachmentId) {
+    return `${connectGrantId === undefined ? "user" : "connect"}:${attachmentId ?? LEGACY_ROUTE_ID}`;
+}
+function reservedMachineEntry(entry, machine) {
+    return machine !== undefined && MACHINE_TOOL_NAMES.has(entry.definition.name);
+}
+function reservedMachineBinding(binding) {
+    return binding.machine !== undefined && MACHINE_TOOL_NAMES.has(binding.wireName);
+}
+function validateMachineToolContracts(entries) {
+    for (const entry of entries) {
+        const name = entry.definition.name;
+        if (!MACHINE_TOOL_NAMES.has(name))
+            continue;
+        if (entry.definition.type !== "function") {
+            throw new Error(`machine tool ${name} must use its canonical function schema`);
+        }
+        switch (name) {
+            case "exec_command":
+                validateCanonicalObjectSchema(name, entry.definition.parameters, EXEC_COMMAND_PARAMETERS);
+                validateCanonicalObjectSchema(`${name} output`, entry.definition.output_schema, EXECUTION_OUTPUT_SCHEMA);
+                break;
+            case "write_stdin":
+                validateCanonicalObjectSchema(name, entry.definition.parameters, WRITE_STDIN_PARAMETERS);
+                validateCanonicalObjectSchema(`${name} output`, entry.definition.output_schema, EXECUTION_OUTPUT_SCHEMA);
+                break;
+            case "preview":
+                validateCanonicalObjectSchema(name, entry.definition.parameters, MACHINE_PREVIEW_PARAMETERS);
+                validateCanonicalObjectSchema(`${name} output`, entry.definition.output_schema, PREVIEW_OUTPUT_SCHEMA);
+                break;
+        }
+    }
+}
+function validateCanonicalObjectSchema(label, schema, canonical) {
+    const properties = objectRecord(canonical.properties);
+    const required = canonical.required;
+    if (properties === undefined || !Array.isArray(required)) {
+        throw new Error(`invalid canonical machine tool schema for ${label}`);
+    }
+    const propertyTypes = Object.fromEntries(Object.entries(properties).map(([name, property]) => {
+        const type = objectRecord(property)?.type;
+        if (typeof type !== "string")
+            throw new Error(`invalid canonical type for ${label}.${name}`);
+        return [name, type];
+    }));
+    validateObjectSchema(label, schema, required, propertyTypes);
+}
+function validateObjectSchema(label, schema, required, propertyTypes) {
+    const properties = objectRecord(schema?.properties);
+    const actualRequired = schema?.required;
+    if (schema?.type !== "object"
+        || schema?.additionalProperties !== false
+        || properties === undefined
+        || !Array.isArray(actualRequired)
+        || actualRequired.some((value) => typeof value !== "string")
+        || !sameStrings(actualRequired, required)
+        || !sameStrings(Object.keys(properties), Object.keys(propertyTypes))) {
+        throw new Error(`machine tool ${label} must use its canonical object schema`);
+    }
+    for (const [property, type] of Object.entries(propertyTypes)) {
+        if (objectRecord(properties[property])?.type !== type) {
+            throw new Error(`machine tool ${label}.${property} must use canonical type ${type}`);
+        }
+    }
+}
+function objectRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value) => right.includes(value));
+}
+function exposedEntry(entry, machine) {
+    if (machine === undefined)
+        return entry;
+    const routeName = `user:${machine.id}:${entry.definition.name}`;
+    const candidate = `user_${machine.id}_${entry.definition.name}`;
+    const safeCandidate = candidate.replace(/[^A-Za-z0-9_-]/g, "_");
+    const exposedName = candidate === safeCandidate && candidate.length <= 128
+        ? candidate
+        : `${safeCandidate.slice(0, 111)}_${stableHash(routeName)}`;
+    const definition = {
+        ...entry.definition,
+        name: exposedName,
+        description: `Routes to ${routeName}. ${entry.definition.description}`,
+    };
+    return Object.freeze({
+        ...entry,
+        definition: Object.freeze(definition),
+    });
+}
+function stableHash(value) {
+    let hash = 0xcbf29ce484222325n;
+    for (const byte of encoder.encode(value)) {
+        hash ^= BigInt(byte);
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, "0");
+}
+function isConnectGrantId(value) {
+    return typeof value === "string" && /^0x[0-9a-f]{64}$/.test(value);
+}
+function wireToolResult(output, canonicalName, machine) {
+    return toolResult(output.output, output.structured_result, output.success, toolExecutionMetadata(output.metadata, canonicalName, machine));
+}
+function toolExecutionMetadata(metadata, canonicalName, machine) {
+    if (machine === undefined)
+        return metadata;
+    const execution = {
+        machine_id: machine.id,
+        machine_name: machine.name,
+        tool_name: canonicalName,
+    };
+    if (metadata === null || metadata === undefined)
+        return Object.freeze(execution);
+    if (typeof metadata === "object" && !Array.isArray(metadata)) {
+        return Object.freeze({ ...metadata, ...execution });
+    }
+    return Object.freeze({ ...execution, provider_metadata: metadata });
+}
+function toolResult(output, structuredResult, success, metadata) {
+    return Object.freeze({
+        [TOOL_RESULT]: true,
+        metadata,
+        output,
+        structuredResult,
+        success,
+        value: structuredResult ?? output,
+    });
+}
+function sameImmutableCall(left, right) {
+    return left.call_id === right.call_id
+        && left.session_id === right.session_id
+        && left.source_call_id === right.source_call_id
+        && left.host_id === right.host_id
+        && left.lease_id === right.lease_id
+        && left.generation === right.generation
+        && left.model === right.model
+        && left.name === right.name
+        && left.input_json === right.input_json
+        && left.output_token_budget === right.output_token_budget
+        && left.output_byte_budget === right.output_byte_budget
+        && left.deadline_at === right.deadline_at;
+}
+function outcomeState(outcome) {
+    return outcome.status;
+}
+export function hostedToolsUnavailable(message) {
+    return { status: "unavailable", message: boundedReason(message) };
+}
+function preAdmissionUnavailable(message) {
+    return Object.freeze({
+        ...hostedToolsUnavailable(message),
+        [HOSTED_TOOLS_PRE_ADMISSION_UNAVAILABLE]: true,
+    });
+}
+export function hostedToolsAmbiguous(message) {
+    return { status: "ambiguous", message: boundedReason(message) };
+}
+function boundedReason(message) {
+    if (encoder.encode(message).byteLength <= 2 * 1024)
+        return message;
+    return "Hosted Tools protocol failure exceeded the bounded reason limit";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function closeSocket(socket, code, reason) {
+    try {
+        socket.close(code, websocketCloseReason(reason));
+    }
+    catch { /* The socket is already closed or never reached an open state. */ }
+}
+function websocketCloseReason(reason) {
+    if (encoder.encode(reason).byteLength <= 123)
+        return reason;
+    let bounded = "";
+    for (const scalar of reason) {
+        if (encoder.encode(bounded + scalar).byteLength > 123)
+            break;
+        bounded += scalar;
+    }
+    return bounded;
+}