@scotthuang/agent-knock-knock 0.12.15 → 0.12.16

package/dist/src/command-json-callback-transport.js

@@ -0,0 +1,298 @@
+import { spawnSync } from "node:child_process";
+import { parseHostProfileV1 } from "./host-profile.js";
+import { callbackEnvelopeMatchesRoute, parseCallbackRoute } from "./callback-transport.js";
+/*
+ * Keep the callback driver behind the canonical transport port. Profile
+ * parsing owns untrusted-document validation and is deliberately re-applied
+ * here so programmatic callers cannot bypass the same fail-closed contract.
+ */
+export const COMMAND_JSON_CALLBACK_TRANSPORT_KIND = "command_json_v1";
+class CommandJsonAcknowledgementError extends Error {
+    errorCode;
+    constructor(errorCode, message) {
+        super(message);
+        this.name = "CommandJsonAcknowledgementError";
+        this.errorCode = errorCode;
+    }
+}
+/**
+ * Deliver canonical AKK callback envelopes through one administrator-selected
+ * command Profile. The Profile and trusted controller identity are captured at
+ * construction time and cannot be supplied by a model-facing delivery call.
+ */
+export function createCommandJsonCallbackTransport(options) {
+    const profile = parseHostProfileV1(options.profile, { source: "built_in" });
+    const profileId = profile.id;
+    const profileRevision = profile.revision;
+    const controllerSessionId = requiredNonBlank(options.controllerSessionId, "controller session id");
+    const callback = Object.freeze({
+        executable: profile.callback.executable,
+        arguments: profile.callback.arguments,
+        stdin: profile.callback.stdin,
+        environmentVariables: profile.callback.environment.allow,
+        timeoutMs: profile.callback.timeoutMs,
+        maxOutputBytes: profile.callback.maxOutputBytes,
+        acknowledgement: profile.callback.acknowledgement
+    });
+    const now = options.now ?? (() => new Date());
+    const environment = options.environment ?? (() => process.env);
+    const runSync = options.spawnSync ??
+        ((executable, arguments_, spawnOptions) => spawnSync(executable, arguments_, spawnOptions));
+    return Object.freeze({
+        kind: COMMAND_JSON_CALLBACK_TRANSPORT_KIND,
+        deliver(input) {
+            let route;
+            try {
+                route = parseCallbackRoute(input.route);
+            }
+            catch {
+                return permanentFailure("command_json_callback_route_invalid");
+            }
+            if (route.transport !== COMMAND_JSON_CALLBACK_TRANSPORT_KIND) {
+                return permanentFailure("unsupported_callback_transport");
+            }
+            if (route.profile_id !== profileId) {
+                return permanentFailure("command_json_callback_profile_mismatch");
+            }
+            if (route.profile_revision !== profileRevision) {
+                return permanentFailure("command_json_callback_profile_revision_mismatch");
+            }
+            if (route.controller_session_id !== controllerSessionId) {
+                return permanentFailure("command_json_controller_session_mismatch");
+            }
+            if (!callbackEnvelopeMatchesRoute(input.envelope, route)) {
+                return permanentFailure("callback_envelope_route_mismatch");
+            }
+            if (!Number.isSafeInteger(input.attempt.number) ||
+                input.attempt.number < 1 ||
+                !nonBlank(input.attempt.id)) {
+                return permanentFailure("command_json_callback_attempt_invalid");
+            }
+            let arguments_;
+            let stdin;
+            let env;
+            try {
+                const values = interpolationValues(input.envelope, controllerSessionId);
+                arguments_ = callback.arguments.map((argument) => interpolate(argument, values, "argument"));
+                stdin = interpolate(callback.stdin, values, "stdin");
+                env = filteredEnvironment(environment(), callback.environmentVariables);
+            }
+            catch {
+                return permanentFailure("command_json_callback_configuration_error");
+            }
+            let result;
+            try {
+                result = runSync(callback.executable, arguments_, {
+                    encoding: "utf8",
+                    env,
+                    input: stdin,
+                    killSignal: "SIGKILL",
+                    maxBuffer: callback.maxOutputBytes,
+                    shell: false,
+                    timeout: callback.timeoutMs,
+                    windowsHide: true
+                });
+            }
+            catch (error) {
+                return processExecutionFailure(error, now());
+            }
+            // A spawn error means the process did not complete inside the bounded
+            // execution contract. In particular, stdout emitted before a timeout or
+            // output-limit kill cannot prove that the Host finished processing the
+            // callback, even when it happens to contain an exact accepted payload.
+            if (result.error) {
+                return processExecutionFailure(result.error, now());
+            }
+            const acknowledgement = acknowledgementOutcome({
+                callback,
+                envelope: input.envelope,
+                result,
+                now: now()
+            });
+            if (acknowledgement) {
+                if (acknowledgement.disposition === "accepted") {
+                    try {
+                        input.reportCheckpoint?.(acknowledgement);
+                    }
+                    catch {
+                        // The exact command acknowledgement remains authoritative even when
+                        // the caller cannot persist the optional early checkpoint here.
+                    }
+                }
+                return acknowledgement;
+            }
+            return uncertainFailure(result.status === 0
+                ? "command_json_callback_acknowledgement_invalid"
+                : "command_json_callback_exit_unacknowledged", now());
+        }
+    });
+}
+function acknowledgementOutcome(input) {
+    const stdout = typeof input.result.stdout === "string"
+        ? input.result.stdout.trim()
+        : "";
+    if (!stdout)
+        return undefined;
+    let acknowledgement;
+    try {
+        acknowledgement = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const definition = input.callback.acknowledgement;
+        const hostDisposition = requiredPointerString(acknowledgement, definition.disposition, "disposition");
+        const disposition = Object.hasOwn(definition.disposition.mapping, hostDisposition)
+            ? definition.disposition.mapping[hostDisposition]
+            : undefined;
+        if (!disposition) {
+            throw new CommandJsonAcknowledgementError("command_json_callback_acknowledgement_disposition_unknown", "callback acknowledgement disposition is not mapped");
+        }
+        const deliveryId = requiredPointerString(acknowledgement, definition.acknowledgedDeliveryId, "acknowledged delivery id");
+        const messageId = requiredPointerString(acknowledgement, definition.acknowledgedMessageId, "acknowledged message id");
+        if (deliveryId !== input.envelope.delivery_id ||
+            messageId !== input.envelope.event.id) {
+            throw new CommandJsonAcknowledgementError("command_json_callback_acknowledgement_identity_mismatch", "callback acknowledgement does not bind the exact delivery and message");
+        }
+        if (disposition === "accepted") {
+            const acceptanceId = requiredPointerString(acknowledgement, definition.acceptanceId, "acceptance id");
+            return {
+                disposition,
+                accepted_at: input.now.toISOString(),
+                acceptance_id: acceptanceId,
+                evidence: processEvidence(input.result)
+            };
+        }
+        const errorCode = defaultOutcomeErrorCode(disposition);
+        if (disposition === "uncertain") {
+            return {
+                disposition,
+                error_code: errorCode,
+                observed_at: input.now.toISOString(),
+                evidence: processEvidence(input.result)
+            };
+        }
+        return {
+            disposition,
+            error_code: errorCode,
+            evidence: processEvidence(input.result)
+        };
+    }
+    catch (error) {
+        const errorCode = error instanceof CommandJsonAcknowledgementError
+            ? error.errorCode
+            : "command_json_callback_acknowledgement_invalid";
+        return uncertainFailure(errorCode, input.now);
+    }
+}
+function processEvidence(result) {
+    return {
+        transport: COMMAND_JSON_CALLBACK_TRANSPORT_KIND,
+        process_status: result.status,
+        ...(result.signal ? { process_signal: result.signal } : {})
+    };
+}
+function processExecutionFailure(error, observedAt) {
+    const code = errorCode(error);
+    if (["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(code ?? "")) {
+        return permanentFailure("command_json_callback_executable_unavailable");
+    }
+    return uncertainFailure(code === "ETIMEDOUT" || code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ||
+        code === "ENOBUFS"
+        ? "command_json_callback_execution_limit_uncertain"
+        : "command_json_callback_execution_uncertain", observedAt);
+}
+function interpolationValues(envelope, controllerSessionId) {
+    const values = new Map();
+    const add = (name, value, sensitiveBody = false) => {
+        if (value !== undefined) {
+            values.set(name, { value: String(value), sensitiveBody });
+        }
+    };
+    add("controller.session_id", controllerSessionId);
+    add("envelope.delivery_id", envelope.delivery_id);
+    add("envelope.idempotency_key", envelope.idempotency_key);
+    add("envelope.message_id", envelope.event.id);
+    add("envelope.body", envelope.event.body, true);
+    return values;
+}
+function interpolate(template, values, destination) {
+    let malformed = false;
+    const rendered = template.replace(/\$\{([^{}]+)\}/gu, (_match, name) => {
+        const resolved = values.get(String(name));
+        if (!resolved || (destination === "argument" && resolved.sensitiveBody)) {
+            malformed = true;
+            return "";
+        }
+        return resolved.value;
+    });
+    if (malformed || rendered.includes("${")) {
+        throw new Error("command_json_v1 interpolation is unsupported or malformed");
+    }
+    assertNoNullByte(rendered, `command_json_v1 ${destination}`);
+    return rendered;
+}
+function filteredEnvironment(source, allowed) {
+    const filtered = Object.create(null);
+    for (const name of allowed) {
+        if (Object.hasOwn(source, name) && source[name] !== undefined) {
+            filtered[name] = source[name];
+        }
+    }
+    return filtered;
+}
+function requiredPointerString(document, definition, label) {
+    const value = resolveJsonPointer(document, definition.jsonPointer);
+    if (!nonBlank(value)) {
+        throw new CommandJsonAcknowledgementError("command_json_callback_acknowledgement_invalid", `callback acknowledgement ${label} must be a non-empty string`);
+    }
+    return value;
+}
+function resolveJsonPointer(document, pointer) {
+    if (pointer === "")
+        return document;
+    let current = document;
+    for (const encoded of pointer.slice(1).split("/")) {
+        const token = encoded.replace(/~1/gu, "/").replace(/~0/gu, "~");
+        if (current === null ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, token)) {
+            return undefined;
+        }
+        current = current[token];
+    }
+    return current;
+}
+function defaultOutcomeErrorCode(disposition) {
+    return `command_json_callback_${disposition}`;
+}
+function permanentFailure(errorCode) {
+    return { disposition: "permanent_failure", error_code: errorCode };
+}
+function uncertainFailure(errorCode, observedAt) {
+    return {
+        disposition: "uncertain",
+        error_code: errorCode,
+        observed_at: observedAt.toISOString()
+    };
+}
+function requiredNonBlank(value, label) {
+    if (!nonBlank(value))
+        throw new Error(`${label} must be a non-empty string`);
+    return value;
+}
+function nonBlank(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function assertNoNullByte(value, label) {
+    if (value.includes("\0"))
+        throw new Error(`${label} contains a null byte`);
+}
+function errorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const value = error.code;
+    return typeof value === "string" ? value : undefined;
+}
+//# sourceMappingURL=command-json-callback-transport.js.map

package/dist/src/command-json-callback-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-json-callback-transport.js","sourceRoot":"","sources":["../../src/command-json-callback-transport.ts"],"names":[],"mappings":"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"}

package/dist/src/host-adapter.d.ts

@@ -0,0 +1,52 @@
+import { type HostBridgeCommandResult, type HostBridgeToolContext, type HostBridgeToolLogger, type HostBridgeToolResult } from "./host-bridge-tools.js";
+export type { HostBridgeCommandResult, HostBridgeToolContext, HostBridgeToolLogger, HostBridgeToolResult } from "./host-bridge-tools.js";
+export { createTrustedHostProfileRuntime, hostProfileRelayEnvironment } from "./host-profile-runtime.js";
+export type { CreateTrustedHostProfileRuntimeOptions, TrustedHostProfileRuntimeV1 } from "./host-profile-runtime.js";
+/** Stable relay entrypoint for native Host connector packages. */
+export declare const defaultHostAdapterRelayPath: string;
+export interface HostAdapterControllerContext extends HostBridgeToolContext {
+    /** Exact Host-owned controller incarnation; never derive this from text. */
+    readonly authority: object;
+}
+export type HostAdapterEnvironmentContext = HostBridgeToolContext;
+export interface HostAdapterToolMetadata {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+export interface HostAdapterCommandMetadata {
+    readonly name: string;
+    readonly description: string;
+    readonly acceptsArgs: boolean;
+}
+export interface HostAdapterLifecycle {
+    readonly id: string;
+    start(): void;
+    stop(): Promise<void>;
+}
+export interface CreateHostAdapterOptions {
+    readonly relayPath?: string;
+    readonly environmentForContext: (context: HostAdapterEnvironmentContext) => NodeJS.ProcessEnv;
+    /** Fixed child environment used by the one Host-owned lifecycle service. */
+    readonly lifecycleEnvironment?: NodeJS.ProcessEnv;
+    readonly lifecycleIntervalMs?: number;
+    readonly pluginConfig?: Readonly<Record<string, unknown>>;
+    readonly logger: HostBridgeToolLogger;
+}
+export interface HostAdapter {
+    readonly command: HostAdapterCommandMetadata;
+    readonly tools: readonly HostAdapterToolMetadata[];
+    readonly lifecycle: HostAdapterLifecycle;
+    executeCommand(context: HostAdapterControllerContext, args: string, signal?: AbortSignal): Promise<HostBridgeCommandResult>;
+    executeTool(context: HostAdapterControllerContext, name: string, toolCallId: string, args: Readonly<Record<string, unknown>>, signal?: AbortSignal): Promise<HostBridgeToolResult>;
+    /** Drop private action/snapshot authority when the Host disposes an owner. */
+    disposeContext(authority: object): void;
+}
+/**
+ * Adapt AKK's established slash command and 16 semantic tools to a native Host.
+ *
+ * Public metadata is captured exactly once. Executable registries are created
+ * lazily per exact Host authority object so private approvals, action offers,
+ * resume snapshots, and idempotency identities cannot leak across controllers.
+ */
+export declare function createHostAdapter(options: CreateHostAdapterOptions): HostAdapter;

package/dist/src/host-adapter.js

@@ -0,0 +1,123 @@
+import { createHostBridgeToolRegistry } from "./host-bridge-tools.js";
+import { bindOpenClawRelayEnvironment, bindOpenClawRelayPath, defaultOpenClawRelayPath, withHostBridgeInvocationSignal } from "./openclaw-plugin-command-adapter.js";
+import { createMonitorReconciliationService, MONITOR_SUPERVISOR_INTERVAL_MS } from "./openclaw-plugin-supervisor.js";
+export { createTrustedHostProfileRuntime, hostProfileRelayEnvironment } from "./host-profile-runtime.js";
+/** Stable relay entrypoint for native Host connector packages. */
+export const defaultHostAdapterRelayPath = defaultOpenClawRelayPath;
+const METADATA_CONTEXT = Object.freeze({
+    sessionKey: "host-adapter:metadata",
+    sessionId: "host-adapter:metadata"
+});
+/**
+ * Adapt AKK's established slash command and 16 semantic tools to a native Host.
+ *
+ * Public metadata is captured exactly once. Executable registries are created
+ * lazily per exact Host authority object so private approvals, action offers,
+ * resume snapshots, and idempotency identities cannot leak across controllers.
+ */
+export function createHostAdapter(options) {
+    const relayPath = requiredString(options.relayPath ?? defaultHostAdapterRelayPath, "relayPath");
+    const pluginConfig = options.pluginConfig ?? {};
+    const metadataRegistry = createHostBridgeToolRegistry({
+        relayPath,
+        relayEnvironment: {},
+        pluginConfig,
+        logger: options.logger,
+        context: METADATA_CONTEXT
+    });
+    const commandMetadata = immutableMetadataClone({
+        name: metadataRegistry.command().name,
+        description: metadataRegistry.command().description,
+        acceptsArgs: metadataRegistry.command().acceptsArgs
+    });
+    const toolMetadata = immutableMetadataClone(metadataRegistry.list().map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+    })));
+    const registries = new WeakMap();
+    const lifecycleApi = {
+        pluginConfig,
+        logger: options.logger
+    };
+    bindOpenClawRelayPath(lifecycleApi, relayPath);
+    bindOpenClawRelayEnvironment(lifecycleApi, options.lifecycleEnvironment ?? process.env);
+    const lifecycle = createMonitorReconciliationService(lifecycleApi, options.lifecycleIntervalMs ?? MONITOR_SUPERVISOR_INTERVAL_MS);
+    const registryFor = (context) => {
+        const trusted = trustedControllerContext(context);
+        const cached = registries.get(context.authority);
+        if (cached) {
+            if (cached.context.sessionKey !== trusted.sessionKey ||
+                cached.context.sessionId !== trusted.sessionId) {
+                throw new Error("Host adapter authority cannot be reused with another controller context");
+            }
+            return cached.registry;
+        }
+        const environment = options.environmentForContext(trusted);
+        if (!environment || typeof environment !== "object") {
+            throw new Error("environmentForContext must return a process environment");
+        }
+        const registry = createHostBridgeToolRegistry({
+            relayPath,
+            relayEnvironment: environment,
+            pluginConfig,
+            logger: options.logger,
+            context: trusted
+        });
+        registries.set(context.authority, { context: trusted, registry });
+        return registry;
+    };
+    return Object.freeze({
+        command: commandMetadata,
+        tools: toolMetadata,
+        lifecycle,
+        executeCommand(context, args, signal) {
+            return withHostBridgeInvocationSignal(signal, () => registryFor(context).command().execute(args));
+        },
+        executeTool(context, name, toolCallId, args, signal) {
+            return withHostBridgeInvocationSignal(signal, () => registryFor(context).execute(name, toolCallId, args));
+        },
+        disposeContext(authority) {
+            requiredAuthority(authority);
+            registries.delete(authority);
+        }
+    });
+}
+function trustedControllerContext(context) {
+    requiredAuthority(context?.authority);
+    return Object.freeze({
+        sessionKey: requiredString(context?.sessionKey, "context.sessionKey"),
+        sessionId: requiredString(context?.sessionId, "context.sessionId")
+    });
+}
+function requiredAuthority(value) {
+    if (value === null ||
+        (typeof value !== "object" && typeof value !== "function")) {
+        throw new Error("context.authority must be an exact Host-owned object");
+    }
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} is required`);
+    }
+    return value;
+}
+function immutableMetadataClone(value) {
+    return deepFreezeMetadata(structuredClone(value));
+}
+function deepFreezeMetadata(value, seen = new WeakSet()) {
+    if (value === null ||
+        (typeof value !== "object" && typeof value !== "function")) {
+        return value;
+    }
+    const objectValue = value;
+    if (seen.has(objectValue)) {
+        return value;
+    }
+    seen.add(objectValue);
+    for (const key of Reflect.ownKeys(objectValue)) {
+        deepFreezeMetadata(objectValue[key], seen);
+    }
+    return Object.freeze(value);
+}
+//# sourceMappingURL=host-adapter.js.map

package/dist/src/host-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-adapter.js","sourceRoot":"","sources":["../../src/host-adapter.ts"],"names":[],"mappings":"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"}

package/dist/src/host-bridge-mcp.d.ts

@@ -0,0 +1,22 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { HostBridgeToolRegistry } from "./host-bridge-tools.js";
+export declare const HOST_BRIDGE_MCP_SERVER_NAME = "agent-knock-knock-host-bridge";
+export interface CreateHostBridgeMcpServerOptions {
+    readonly registry: HostBridgeToolRegistry;
+    readonly version: string;
+    /** Test seam; production callers receive a fresh identity per Bridge. */
+    readonly instanceId?: string;
+}
+/**
+ * Expose the established AKK semantic tool registry over MCP.
+ *
+ * The low-level SDK server intentionally does not infer validation from the
+ * schemas returned by tools/list, so every schema is compiled once here and
+ * enforced again before any semantic tool can execute.
+ */
+export declare function createHostBridgeMcpServer(options: CreateHostBridgeMcpServerOptions): Server;
+export declare function getHostBridgeMcpActiveCallCount(server: Server): number;
+/** Preserve both JSON-RPC request-id type and value inside one Bridge. */
+export declare function hostBridgeToolCallId(instanceId: string, requestId: string | number): string;
+/** Wait until every already accepted MCP tool call has produced a result. */
+export declare function drainHostBridgeMcpCalls(server: Server): Promise<void>;

package/dist/src/host-bridge-mcp.js

@@ -0,0 +1,145 @@
+import { randomUUID } from "node:crypto";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
+export const HOST_BRIDGE_MCP_SERVER_NAME = "agent-knock-knock-host-bridge";
+const MAX_MODEL_ERROR_LENGTH = 1_024;
+const activeCallsByServer = new WeakMap();
+/**
+ * Expose the established AKK semantic tool registry over MCP.
+ *
+ * The low-level SDK server intentionally does not infer validation from the
+ * schemas returned by tools/list, so every schema is compiled once here and
+ * enforced again before any semantic tool can execute.
+ */
+export function createHostBridgeMcpServer(options) {
+    const version = requiredString(options.version, "version");
+    const instanceId = requiredString(options.instanceId ?? randomUUID(), "instanceId");
+    const descriptors = [...options.registry.list()];
+    const validatorProvider = new AjvJsonSchemaValidator();
+    const compiledByName = new Map();
+    for (const descriptor of descriptors) {
+        if (compiledByName.has(descriptor.name)) {
+            throw new Error(`duplicate host bridge MCP tool ${descriptor.name}`);
+        }
+        const validate = validatorProvider.getValidator(descriptor.inputSchema);
+        compiledByName.set(descriptor.name, { validate });
+    }
+    const advertisedTools = descriptors.map((descriptor) => ({
+        name: descriptor.name,
+        description: descriptor.description,
+        inputSchema: descriptor.inputSchema
+    }));
+    const server = new Server({ name: HOST_BRIDGE_MCP_SERVER_NAME, version }, { capabilities: { tools: {} } });
+    const activeCalls = new Set();
+    activeCallsByServer.set(server, activeCalls);
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: advertisedTools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const name = request.params.name;
+        const compiled = compiledByName.get(name);
+        if (!compiled) {
+            throw invalidParams(`Unknown host bridge tool: ${name}`);
+        }
+        if (request.params.task !== undefined ||
+            hasLegacyTaskRequest(request.params._meta)) {
+            throw invalidParams(`Task execution is not supported for tool: ${name}`);
+        }
+        const validation = compiled.validate(request.params.arguments ?? {});
+        if (!validation.valid) {
+            throw invalidParams(`Invalid arguments for ${name}: ${validation.errorMessage}`);
+        }
+        const execution = executeToolCall(options.registry, name, hostBridgeToolCallId(instanceId, extra.requestId), validation.data);
+        activeCalls.add(execution);
+        try {
+            return await execution;
+        }
+        finally {
+            activeCalls.delete(execution);
+        }
+    });
+    return server;
+}
+export function getHostBridgeMcpActiveCallCount(server) {
+    return activeCallsByServer.get(server)?.size ?? 0;
+}
+/** Preserve both JSON-RPC request-id type and value inside one Bridge. */
+export function hostBridgeToolCallId(instanceId, requestId) {
+    if ((typeof requestId !== "string" && typeof requestId !== "number") ||
+        (typeof requestId === "number" && !Number.isFinite(requestId))) {
+        throw new Error("MCP request id must be a finite number or string");
+    }
+    return `host-bridge:${JSON.stringify([instanceId, requestId])}`;
+}
+/** Wait until every already accepted MCP tool call has produced a result. */
+export async function drainHostBridgeMcpCalls(server) {
+    const activeCalls = activeCallsByServer.get(server);
+    while (activeCalls && activeCalls.size > 0) {
+        await Promise.allSettled([...activeCalls]);
+    }
+}
+async function executeToolCall(registry, name, toolCallId, args) {
+    try {
+        const result = await registry.execute(name, toolCallId, args);
+        return mapToolResult(result);
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: modelFacingErrorMessage(error) }],
+            isError: true
+        };
+    }
+}
+function mapToolResult(result) {
+    const mapped = {
+        content: [...(result.content ?? [])]
+    };
+    if (isRecord(result.details)) {
+        mapped.structuredContent = result.details;
+    }
+    if (typeof result.isError === "boolean") {
+        mapped.isError = result.isError;
+    }
+    return mapped;
+}
+function invalidParams(message) {
+    return new McpError(ErrorCode.InvalidParams, boundedSingleLine(message));
+}
+function modelFacingErrorMessage(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : "Tool execution failed.";
+    return boundedSingleLine(message) || "Tool execution failed.";
+}
+function boundedSingleLine(value) {
+    const sanitized = value
+        .replace(/\u001B\[[0-?]*[ -/]*[@-~]/gu, "")
+        .replace(/[\u0000-\u001F\u007F-\u009F]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+    if (sanitized.length <= MAX_MODEL_ERROR_LENGTH) {
+        return sanitized;
+    }
+    let prefix = "";
+    for (const character of sanitized) {
+        if (prefix.length + character.length > MAX_MODEL_ERROR_LENGTH - 3) {
+            break;
+        }
+        prefix += character;
+    }
+    return `${prefix}...`;
+}
+function hasLegacyTaskRequest(meta) {
+    return isRecord(meta) && meta.task !== undefined;
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} is required`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=host-bridge-mcp.js.map