@questpie/sandbox 3.16.0 → 3.17.0

package/dist/custom-tools-DxI7JvUn.mjs

@@ -0,0 +1,407 @@
+import { createWorkloadMcpToolPort, mcpPublicErrorCode } from "@questpie/mcp";
+
+//#region src/broker-wire.ts
+/**
+* One place for the sandbox broker's decoded payload and derived wire budgets.
+*
+* `http.fetch` bodies are binary-to-base64, then nested in JSON RPC envelopes.
+* The transport limits therefore cannot equal the decoded body limit. Keep all
+* supervisor, route, frame, and custom-tool caps derived here.
+*/
+/** Decoded request/response body limit promised by `http.fetch`. */
+const BROKER_HTTP_BODY_CAP_BYTES = 5 * 1024 * 1024;
+/** Exact maximum base64 length for a decoded HTTP body at the public cap. */
+const BROKER_HTTP_BASE64_CAP_BYTES = 4 * Math.ceil(BROKER_HTTP_BODY_CAP_BYTES / 3);
+/**
+* Room for URL, method, bounded HTTP headers, status metadata, and JSON RPC
+* envelope syntax around a maximum-size base64 body.
+*/
+const BROKER_HTTP_JSON_HEADROOM_BYTES = 128 * 1024;
+/** Whole JSON request/response budget for the `http.fetch` method. */
+const BROKER_HTTP_WIRE_CAP_BYTES = BROKER_HTTP_BASE64_CAP_BYTES + BROKER_HTTP_JSON_HEADROOM_BYTES;
+/** Existing small native binding request budget, including its JSON envelope. */
+const BROKER_NATIVE_REQUEST_WIRE_CAP_BYTES = 64 * 1024;
+/** Maximum JSON value returned by native bindings before envelope overhead. */
+const BROKER_NATIVE_RESULT_CAP_BYTES = 768 * 1024;
+/** Custom-tool logical limits; shared with the host session implementation. */
+const BROKER_CUSTOM_ARGUMENT_CAP_BYTES = 63 * 1024;
+const BROKER_CUSTOM_RESULT_CAP_BYTES = 768 * 1024;
+const BROKER_CUSTOM_LIST_CAP_BYTES = 768 * 1024;
+const BROKER_JSON_ENVELOPE_HEADROOM_BYTES = 4 * 1024;
+const BROKER_NATIVE_RESPONSE_WIRE_CAP_BYTES = BROKER_NATIVE_RESULT_CAP_BYTES + BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+const BROKER_CUSTOM_REQUEST_WIRE_CAP_BYTES = BROKER_CUSTOM_ARGUMENT_CAP_BYTES + BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+const BROKER_CUSTOM_RESPONSE_WIRE_CAP_BYTES = Math.max(BROKER_CUSTOM_RESULT_CAP_BYTES, BROKER_CUSTOM_LIST_CAP_BYTES) + BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+/** Maximum body the app broker route will read before method-aware validation. */
+const BROKER_MAX_REQUEST_WIRE_BYTES = Math.max(BROKER_HTTP_WIRE_CAP_BYTES, BROKER_NATIVE_REQUEST_WIRE_CAP_BYTES, BROKER_CUSTOM_REQUEST_WIRE_CAP_BYTES);
+/** Maximum response the supervisor will read before method-aware validation. */
+const BROKER_MAX_RESPONSE_WIRE_BYTES = Math.max(BROKER_HTTP_WIRE_CAP_BYTES, BROKER_NATIVE_RESPONSE_WIRE_CAP_BYTES, BROKER_CUSTOM_RESPONSE_WIRE_CAP_BYTES);
+/** Prefix/newline room around the largest JSON RPC frame. */
+const BROKER_FRAME_CAP_BYTES = Math.max(BROKER_MAX_REQUEST_WIRE_BYTES, BROKER_MAX_RESPONSE_WIRE_BYTES) + 1024;
+/**
+* A run may emit one maximum RPC request and still return a maximum-sized final
+* frame. Repeated large calls remain bounded by this cumulative budget.
+*/
+const BROKER_TOTAL_OUTPUT_CAP_BYTES = BROKER_FRAME_CAP_BYTES * 2;
+function brokerRequestWireCap(method) {
+	if (method === "http.fetch") return BROKER_HTTP_WIRE_CAP_BYTES;
+	if (method === "tools.call") return BROKER_CUSTOM_REQUEST_WIRE_CAP_BYTES;
+	if (method === "tools.list") return BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+	return BROKER_NATIVE_REQUEST_WIRE_CAP_BYTES;
+}
+function brokerResponseWireCap(method) {
+	if (method === "http.fetch") return BROKER_HTTP_WIRE_CAP_BYTES;
+	if (method === "tools.call" || method === "tools.list") return BROKER_CUSTOM_RESPONSE_WIRE_CAP_BYTES;
+	return BROKER_NATIVE_RESPONSE_WIRE_CAP_BYTES;
+}
+function brokerResultValueCap(method) {
+	if (method === "http.fetch") return BROKER_HTTP_WIRE_CAP_BYTES - BROKER_JSON_ENVELOPE_HEADROOM_BYTES;
+	if (method === "tools.call") return BROKER_CUSTOM_RESULT_CAP_BYTES;
+	if (method === "tools.list") return BROKER_CUSTOM_LIST_CAP_BYTES;
+	return BROKER_NATIVE_RESULT_CAP_BYTES;
+}
+
+//#endregion
+//#region src/server-internals.ts
+const MAX_RESULT_DEPTH = 32;
+const MAX_RESULT_NODES = 1e4;
+const MAX_RESULT_JSON_BYTES = 1048576;
+const MAX_RESULT_LOGS = 1e3;
+const MAX_RESULT_LOG_BYTES = 4e3;
+const MAX_TOTAL_LOG_BYTES = 1048576;
+function exactKeys(value, required, optional) {
+	const keys = Object.keys(value);
+	return required.every((key) => keys.includes(key)) && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+function isBoundedJson(value, budget = {
+	nodes: 0,
+	bytes: 0
+}, depth = 0, maximumBytes = MAX_RESULT_JSON_BYTES) {
+	if (depth > MAX_RESULT_DEPTH) return false;
+	budget.nodes += 1;
+	if (budget.nodes > MAX_RESULT_NODES) return false;
+	if (value === null || typeof value === "boolean") budget.bytes += 5;
+	else if (typeof value === "number") {
+		if (!Number.isFinite(value)) return false;
+		budget.bytes += 24;
+	} else if (typeof value === "string") budget.bytes += new TextEncoder().encode(value).byteLength;
+	else if (Array.isArray(value)) {
+		budget.bytes += 2;
+		for (const item of value) if (!isBoundedJson(item, budget, depth + 1, maximumBytes)) return false;
+	} else if (typeof value === "object" && value !== null) {
+		budget.bytes += 2;
+		for (const [key, item] of Object.entries(value)) {
+			budget.bytes += new TextEncoder().encode(key).byteLength;
+			if (!isBoundedJson(item, budget, depth + 1, maximumBytes)) return false;
+		}
+	} else return false;
+	return budget.bytes <= maximumBytes;
+}
+function parseSandboxRunResult(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const result = value;
+	if (!exactKeys(result, ["ok", "logs"], [
+		"output",
+		"error",
+		"timedOut",
+		"ms"
+	]) || typeof result.ok !== "boolean" || !Array.isArray(result.logs) || result.logs.length > MAX_RESULT_LOGS || result.error !== void 0 && typeof result.error !== "string" || result.timedOut !== void 0 && typeof result.timedOut !== "boolean" || result.ms !== void 0 && (typeof result.ms !== "number" || !Number.isFinite(result.ms) || result.ms < 0)) return null;
+	if (result.ok === true && (Object.hasOwn(result, "error") || Object.hasOwn(result, "timedOut")) || result.ok === false && (typeof result.error !== "string" || Object.hasOwn(result, "output") || Object.hasOwn(result, "timedOut") && result.timedOut !== true)) return null;
+	let logBytes = 0;
+	for (const log of result.logs) {
+		if (typeof log !== "string") return null;
+		const bytes = new TextEncoder().encode(log).byteLength;
+		logBytes += bytes;
+		if (bytes > MAX_RESULT_LOG_BYTES || logBytes > MAX_TOTAL_LOG_BYTES) return null;
+	}
+	if (result.output !== void 0 && !isBoundedJson(result.output)) return null;
+	return {
+		ok: result.ok,
+		...result.output !== void 0 ? { output: result.output } : {},
+		...typeof result.error === "string" ? { error: result.error } : {},
+		logs: result.logs,
+		...typeof result.timedOut === "boolean" ? { timedOut: result.timedOut } : {},
+		...typeof result.ms === "number" ? { ms: result.ms } : {}
+	};
+}
+const BROKER_ERROR_MESSAGES = Object.freeze({
+	bad_method: "invalid sandbox binding method",
+	bad_args: "invalid sandbox binding arguments",
+	unauthorized: "sandbox binding authorization failed",
+	forbidden: "sandbox binding operation forbidden",
+	not_implemented: "sandbox binding operation unavailable",
+	execution_error: "sandbox binding operation failed"
+});
+/** Normalize a broker URL for comparison (drop a trailing slash; ignore case of origin). */
+function normalizeBrokerUrl(raw) {
+	try {
+		const u = new URL(raw);
+		if (u.protocol !== "http:" && u.protocol !== "https:" || u.username.length > 0 || u.password.length > 0 || u.hash.length > 0) return null;
+		const path = u.pathname.replace(/\/$/, "");
+		return `${u.origin}${path}${u.search}`;
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+//#region src/custom-tools.ts
+const DEFAULT_MAX_TOOLS = 64;
+const HARD_MAX_TOOLS = 256;
+const DEFAULT_MAX_LIST_BYTES = 256 * 1024;
+const HARD_MAX_LIST_BYTES = BROKER_CUSTOM_LIST_CAP_BYTES;
+const DEFAULT_MAX_ARGUMENT_BYTES = 32 * 1024;
+const HARD_MAX_ARGUMENT_BYTES = BROKER_CUSTOM_ARGUMENT_CAP_BYTES;
+const DEFAULT_MAX_RESULT_BYTES = 256 * 1024;
+const HARD_MAX_RESULT_BYTES = BROKER_CUSTOM_RESULT_CAP_BYTES;
+const DEFAULT_MAX_CALLS = 64;
+const HARD_MAX_CALLS = 256;
+const DEFAULT_TIMEOUT_MS = 5e3;
+const HARD_MAX_TIMEOUT_MS = 3e4;
+const DEFAULT_CONCURRENCY = 4;
+const HARD_MAX_CONCURRENCY = 16;
+const DEFAULT_EVIDENCE_TIMEOUT_MS = 250;
+const HARD_MAX_EVIDENCE_TIMEOUT_MS = 1e3;
+const MAX_ACTIVE_TOOL_SESSIONS = 1024;
+const MAX_EXPIRED_SESSION_CLEANUP_SCAN = 64;
+function sandboxCustomTools(config) {
+	if (!resolveLimits(config)) throw new Error("sandbox custom-tool limits are invalid");
+	return config;
+}
+const sessions = /* @__PURE__ */ new Map();
+const encoder = new TextEncoder();
+function closeSession(token, session) {
+	session.revoked = true;
+	if (sessions.get(token) === session) sessions.delete(token);
+	session.port = void 0;
+	session.envelope = void 0;
+}
+function cleanupExpiredSessions(now) {
+	const candidates = [];
+	for (const [token, session] of sessions) {
+		candidates.push([token, session]);
+		if (candidates.length >= MAX_EXPIRED_SESSION_CLEANUP_SCAN) break;
+	}
+	for (const [token, session] of candidates) if (session.revoked || now >= session.expiresAt) closeSession(token, session);
+	else if (sessions.get(token) === session) {
+		sessions.delete(token);
+		sessions.set(token, session);
+	}
+}
+function boundedPositiveInteger(value, fallback, maximum) {
+	if (value === void 0) return fallback;
+	return Number.isSafeInteger(value) && value >= 1 && value <= maximum ? value : null;
+}
+function resolveLimits(config) {
+	const limits = config.limits;
+	const maxTools = boundedPositiveInteger(limits?.maxTools, DEFAULT_MAX_TOOLS, HARD_MAX_TOOLS);
+	const maxListBytes = boundedPositiveInteger(limits?.maxListBytes, DEFAULT_MAX_LIST_BYTES, HARD_MAX_LIST_BYTES);
+	const maxArgumentBytes = boundedPositiveInteger(limits?.maxArgumentBytes, DEFAULT_MAX_ARGUMENT_BYTES, HARD_MAX_ARGUMENT_BYTES);
+	const maxResultBytes = boundedPositiveInteger(limits?.maxResultBytes, DEFAULT_MAX_RESULT_BYTES, HARD_MAX_RESULT_BYTES);
+	const maxCalls = boundedPositiveInteger(limits?.maxCalls, DEFAULT_MAX_CALLS, HARD_MAX_CALLS);
+	const timeoutMs = boundedPositiveInteger(limits?.timeoutMs, DEFAULT_TIMEOUT_MS, HARD_MAX_TIMEOUT_MS);
+	const concurrency = boundedPositiveInteger(limits?.concurrency, DEFAULT_CONCURRENCY, HARD_MAX_CONCURRENCY);
+	const evidenceTimeoutMs = boundedPositiveInteger(config.evidenceTimeoutMs, DEFAULT_EVIDENCE_TIMEOUT_MS, HARD_MAX_EVIDENCE_TIMEOUT_MS);
+	if (maxTools === null || maxListBytes === null || maxArgumentBytes === null || maxResultBytes === null || maxCalls === null || timeoutMs === null || concurrency === null || evidenceTimeoutMs === null) return null;
+	return {
+		maxTools,
+		maxListBytes,
+		maxArgumentBytes,
+		maxResultBytes,
+		maxCalls,
+		timeoutMs,
+		concurrency,
+		evidenceTimeoutMs
+	};
+}
+function error(code, message) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, required, optional = []) {
+	const keys = Object.keys(value);
+	return required.every((key) => keys.includes(key)) && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+function jsonBytes(value) {
+	try {
+		const serialized = JSON.stringify(value);
+		if (serialized === void 0) return null;
+		return encoder.encode(serialized).byteLength;
+	} catch {
+		return null;
+	}
+}
+var DeadlineError = class extends Error {};
+var CancelledError = class extends Error {};
+async function within(work, timeoutMs, parent, onWorkSettled) {
+	const controller = new AbortController();
+	const cancel = () => controller.abort(new CancelledError());
+	if (parent?.aborted) cancel();
+	else parent?.addEventListener("abort", cancel, { once: true });
+	let timer;
+	const operation = Promise.resolve().then(() => work(controller.signal));
+	if (onWorkSettled) operation.then(onWorkSettled, onWorkSettled);
+	try {
+		return await Promise.race([operation, new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				const deadline = new DeadlineError();
+				controller.abort(deadline);
+				reject(deadline);
+			}, timeoutMs);
+			controller.signal.addEventListener("abort", () => reject(controller.signal.reason ?? new CancelledError()), { once: true });
+			if (controller.signal.aborted) reject(controller.signal.reason ?? new CancelledError());
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+		parent?.removeEventListener("abort", cancel);
+	}
+}
+async function emitEvidence(config, limits, event) {
+	if (!config.evidence) return;
+	const controller = new AbortController();
+	let timer;
+	try {
+		await Promise.race([Promise.resolve(config.evidence(Object.freeze(event), { signal: controller.signal })), new Promise((resolve) => {
+			timer = setTimeout(() => {
+				controller.abort();
+				resolve();
+			}, limits.evidenceTimeoutMs);
+		})]);
+	} catch {} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+function registerSandboxCustomToolsSession(token, brokerUrl, envelope, ttlMs) {
+	const now = Date.now();
+	cleanupExpiredSessions(now);
+	const endpoint = normalizeBrokerUrl(brokerUrl);
+	if (typeof token !== "string" || token.length === 0 || encoder.encode(token).byteLength > 8192 || endpoint === null || !Number.isSafeInteger(ttlMs) || ttlMs <= 0 || sessions.has(token) || sessions.size >= MAX_ACTIVE_TOOL_SESSIONS) throw new Error("sandbox custom-tool session could not be registered");
+	const session = {
+		envelope,
+		endpoint,
+		expiresAt: now + Math.min(Math.round(ttlMs), 5 * 6e4),
+		calls: 0,
+		inFlight: 0,
+		revoked: false
+	};
+	sessions.set(token, session);
+	return { revoke() {
+		if (session.revoked) return;
+		closeSession(token, session);
+	} };
+}
+function resolveSession(token, requestUrl) {
+	if (!token) return null;
+	const session = sessions.get(token);
+	if (!session || session.revoked) return null;
+	if (normalizeBrokerUrl(requestUrl) !== session.endpoint) return null;
+	if (Date.now() >= session.expiresAt) {
+		closeSession(token, session);
+		return null;
+	}
+	return session;
+}
+function createToolPort(app, config, envelope) {
+	return createWorkloadMcpToolPort(app, {
+		envelope,
+		authorizer: config.authorizer,
+		contextBinder: config.contextBinder,
+		audit: config.authorizationAudit,
+		handoff: config.handoff
+	});
+}
+function mcpResultCode(result) {
+	const meta = result["_meta"];
+	const detail = isRecord(meta) && isRecord(meta["questpie/error"]) ? meta["questpie/error"] : void 0;
+	const descriptor = detail ? Object.getOwnPropertyDescriptor(detail, "code") : void 0;
+	const code = descriptor && "value" in descriptor ? descriptor.value : void 0;
+	return [
+		"access_denied",
+		"invalid_input",
+		"input_too_large",
+		"output_too_large",
+		"timeout",
+		"cancelled",
+		"busy",
+		"internal"
+	].includes(code) ? code : void 0;
+}
+async function handleSandboxCustomToolsRpc({ app, config, token, requestUrl, method, args, signal }) {
+	const session = resolveSession(token, requestUrl);
+	if (!session || !config) return error("unauthorized", "sandbox custom tool session is unavailable");
+	if (method !== "tools.list" && method !== "tools.call") return error("bad_method", "invalid sandbox custom tool method");
+	const limits = resolveLimits(config);
+	if (!limits) return error("execution_error", "sandbox custom tool configuration is invalid");
+	const phase = method === "tools.list" ? "discovery" : "call";
+	const started = performance.now();
+	let toolName;
+	const finish = async (result, evidenceResult, reason) => {
+		await emitEvidence(config, limits, {
+			boundary: "sandbox.tool",
+			phase,
+			...toolName ? { toolName } : {},
+			result: evidenceResult,
+			reason,
+			durationMs: Math.max(0, Math.round(performance.now() - started))
+		});
+		return result;
+	};
+	if (session.calls >= limits.maxCalls) return finish(error("forbidden", "sandbox custom tool limit exceeded"), "denied", "limit_exceeded");
+	session.calls += 1;
+	const requestId = session.calls;
+	if (session.inFlight >= limits.concurrency) return finish(error("forbidden", "sandbox custom tool limit exceeded"), "denied", "limit_exceeded");
+	if (method === "tools.list") {
+		if (!isRecord(args) || !hasExactKeys(args, [])) return finish(error("bad_args", "invalid sandbox custom tool arguments"), "denied", "invalid_request");
+	} else {
+		if (!isRecord(args) || !hasExactKeys(args, ["name"], ["arguments"]) || typeof args.name !== "string" || args.name.length === 0 || encoder.encode(args.name).byteLength > 256 || args.arguments !== void 0 && !isRecord(args.arguments)) return finish(error("bad_args", "invalid sandbox custom tool arguments"), "denied", "invalid_request");
+		toolName = args.name;
+		const argumentBytes = jsonBytes(args.arguments ?? {});
+		if (argumentBytes === null || argumentBytes > limits.maxArgumentBytes) return finish(error("bad_args", "sandbox custom tool arguments are too large"), "denied", "limit_exceeded");
+	}
+	session.inFlight += 1;
+	try {
+		const value = await within(async (operationSignal) => {
+			const port = session.port ?? (session.port = createToolPort(app, config, session.envelope));
+			if (method === "tools.list") {
+				const listed = await port.listCustomTools({
+					signal: operationSignal,
+					requestId
+				});
+				if (listed.tools.length > limits.maxTools || (jsonBytes(listed) ?? Number.POSITIVE_INFINITY) > limits.maxListBytes) throw new RangeError("tool list limit exceeded");
+				return listed;
+			}
+			return port.callCustomTool({
+				name: toolName,
+				input: args.arguments ?? {},
+				signal: operationSignal,
+				requestId
+			});
+		}, limits.timeoutMs, signal, () => {
+			session.inFlight = Math.max(0, session.inFlight - 1);
+		});
+		const callResult = value;
+		if (method === "tools.call" && callResult.isError === true) {
+			const code = mcpResultCode(callResult);
+			return finish(error(code === "invalid_input" || code === "input_too_large" ? "bad_args" : code === "access_denied" ? "forbidden" : "execution_error", code === "invalid_input" || code === "input_too_large" ? "invalid sandbox custom tool arguments" : code === "access_denied" ? "sandbox custom tool denied" : "sandbox custom tool failed"), code === "access_denied" || code === "invalid_input" || code === "input_too_large" || code === "busy" ? "denied" : "failed", code === "access_denied" ? "authorization_or_tool_denied" : code === "invalid_input" || code === "input_too_large" ? "invalid_request" : code === "timeout" || code === "cancelled" ? "timed_out" : code === "busy" || code === "output_too_large" ? "limit_exceeded" : "execution_failed");
+		}
+		const resultBytes = jsonBytes(value);
+		if (resultBytes === null || resultBytes > limits.maxResultBytes) return finish(error("execution_error", "sandbox custom tool result is too large"), "failed", "limit_exceeded");
+		return finish({
+			ok: true,
+			value
+		}, "succeeded", "completed");
+	} catch (caught) {
+		const publicCode = mcpPublicErrorCode(caught);
+		return finish(error(publicCode === "invalid_input" || publicCode === "input_too_large" ? "bad_args" : publicCode === "access_denied" || publicCode === "busy" ? "forbidden" : "execution_error", caught instanceof DeadlineError || publicCode === "timeout" ? "sandbox custom tool timed out" : caught instanceof CancelledError || publicCode === "cancelled" ? "sandbox custom tool cancelled" : publicCode === "invalid_input" || publicCode === "input_too_large" ? "invalid sandbox custom tool arguments" : publicCode === "access_denied" ? "sandbox custom tool denied" : publicCode === "busy" ? "sandbox custom tool limit exceeded" : "sandbox custom tool failed"), publicCode === "access_denied" || publicCode === "invalid_input" || publicCode === "input_too_large" || publicCode === "busy" ? "denied" : "failed", caught instanceof DeadlineError || caught instanceof CancelledError || publicCode === "timeout" || publicCode === "cancelled" ? "timed_out" : caught instanceof RangeError || publicCode === "busy" || publicCode === "output_too_large" ? "limit_exceeded" : publicCode === "invalid_input" || publicCode === "input_too_large" ? "invalid_request" : publicCode === "access_denied" ? "authorization_or_tool_denied" : "execution_failed");
+	}
+}
+
+//#endregion
+export { BROKER_MAX_REQUEST_WIRE_BYTES as a, brokerResultValueCap as c, parseSandboxRunResult as i, registerSandboxCustomToolsSession as n, brokerRequestWireCap as o, sandboxCustomTools as r, brokerResponseWireCap as s, handleSandboxCustomToolsRpc as t };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { n as HttpSandboxAdapterOptions, r as httpSandboxAdapter, t as HttpSandboxAdapter } from "./adapter-http-7ypWHBck.mjs";
+import { A as SandboxWorkloadAdmissionVerification, C as SandboxCapabilities, D as SandboxWorkloadAdmissionClaims, E as WORKLOAD_ADMISSION_HEADER, O as SandboxWorkloadAdmissionDenialReason, S as SandboxBindings, T as SandboxRunResult, _ as GuestResultMessage, a as SANDBOX_WORKLOAD_DENIAL_MESSAGE, b as HostRpcResultMessage, c as SandboxWorkloadAuthorizationContext, d as SandboxWorkloadDeniedError, f as SandboxWorkloadPolicy, g as GuestMessage, h as FRAME_MARKER, i as httpSandboxAdapter, k as SandboxWorkloadAdmissionKey, l as SandboxWorkloadAuthorizationPhase, m as BINDINGS_TOKEN_HEADER, n as HttpSandboxAdapterOptions, o as SandboxWorkloadAuditContext, p as SandboxWorkloadRunOptions, r as WorkloadHttpSandboxOptions, s as SandboxWorkloadAuditEvent, t as HttpSandboxAdapter, u as SandboxWorkloadAuthorizer, v as GuestRpcMessage, w as SandboxRunRequest, x as SandboxBindingError, y as HOST_ADMISSION_HEADER } from "./adapter-http-DDeL-Ym3.mjs";
+import { a as SandboxCustomToolsRunOptions, i as SandboxCustomToolsLimits, n as SandboxCustomToolEvidenceEvent, o as sandboxCustomTools, r as SandboxCustomToolsConfig, t as SandboxCustomToolEvidenceContext } from "./custom-tools-CgfgyVNv.mjs";
 
 //#region src/net-validation.d.ts
 
@@ -57,6 +58,8 @@ declare function classifyIpLiteral(ip: string): IpValidationResult;
  */
 declare function validateHostEgress(entry: string, opts?: {
   resolve?: DnsResolver;
+  signal?: AbortSignal;
+  timeoutMs?: number;
 }): Promise<IpValidationResult>;
 /**
  * Validate ALL `net` + `import` hosts in a capability set.
@@ -64,121 +67,11 @@ declare function validateHostEgress(entry: string, opts?: {
  */
 declare function validateEgressHosts(hosts: readonly string[], opts?: {
   resolve?: DnsResolver;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  concurrency?: number;
 }): Promise<IpValidationResult>;
 //#endregion
-//#region src/types.d.ts
-/**
- * Wire contract between the `executor` adapter (Bun/Node, main app) and the
- * standalone Deno sandbox server. Kept intentionally minimal: the main app
- * never imports Deno; it only speaks this JSON over HTTP.
- */
-/**
- * Per-request guest capabilities. `net` and `import` are INDEPENDENT axes
- * (Deno enforces them separately — `--allow-net` gates `fetch`, `--allow-import`
- * gates module imports). The richer app-binding capabilities (`data`, `services`,
- * etc.) live on the core `ExecutorCapabilities` type and are NOT enforced by the
- * sandbox server — they are the later bindings-broker's job.
- */
-interface SandboxCapabilities {
-  /** Runtime `fetch()` allowlist as `host[:port]`. Empty = no network. */
-  net: string[];
-  /** Module import allowlist as `host[:port]` (e.g. `esm.sh:443`). Empty = no remote imports. */
-  import: string[];
-  /** Hard wall-clock timeout; the subprocess is force-killed on exceed. */
-  timeoutMs: number;
-  /** Hard per-guest memory bound (`--v8-flags=--max-old-space-size`). */
-  memoryMb: number;
-}
-/**
- * App-bindings wiring for the UNTRUSTED path. When present, the supervisor
- * exposes a capability-scoped `globalThis.questpie` proxy to the guest whose
- * methods RPC (over STDIO, never the network) to the host broker at {@link url},
- * authenticated by the per-run scoped {@link token}.
- *
- * The token is OPAQUE and is held by the SUPERVISOR only — it is never written
- * into the guest subprocess, so guest code cannot read or forge it to widen
- * scope. The guest only ever sees the typed proxy.
- *
- * Critically, the broker is reached SERVER-TO-SERVER (supervisor → app), NOT by
- * the guest's `fetch`: the guest's egress allowlist rejects loopback/private IPs
- * (the SSRF defense), so a localhost broker is unreachable from guest code by
- * design — we do not poke a hole in that.
- */
-interface SandboxBindings {
-  /** Absolute URL of the host broker endpoint (e.g. `https://app/sandbox/rpc`). */
-  url: string;
-  /** Per-run opaque scoped token. Supervisor-only; never exposed to the guest. */
-  token: string;
-}
-/** POST /run request body. */
-interface SandboxRunRequest {
-  /** Guest TypeScript source. Must `export default` a `function(input)`. */
-  source: string;
-  /** Payload passed to the guest entry function. */
-  input: unknown;
-  capabilities: SandboxCapabilities;
-  /**
-   * Secrets injected into the guest (NOT in source). Surfaced to the guest as
-   * `globalThis.__secrets`. The sandbox never persists these.
-   */
-  secrets?: Record<string, string>;
-  /**
-   * App-bindings broker wiring. When omitted, the guest gets no `questpie`
-   * proxy (the legacy compute-only path). When present, the supervisor brokers
-   * the guest's binding RPCs to the host. See {@link SandboxBindings}.
-   */
-  bindings?: SandboxBindings;
-}
-/** POST /run response body — also the `ExecutorAdapter.run` result shape. */
-interface SandboxRunResult {
-  ok: boolean;
-  output?: unknown;
-  logs: string[];
-  error?: string;
-  /** True when the run was killed by the wall-clock timeout. */
-  timedOut?: boolean;
-  /** Wall-clock duration in ms (server-measured). */
-  ms?: number;
-}
-/** Line prefix marking a framed protocol message on guest stdout. */
-declare const FRAME_MARKER = "__QP_SANDBOX_MSG__";
-/**
- * Header carrying the per-run scoped token on the supervisor → broker request.
- * Mirrors `questpie`'s `BINDINGS_TOKEN_HEADER`. Supervisor-only; never set by or
- * exposed to guest code.
- */
-declare const BINDINGS_TOKEN_HEADER = "x-questpie-sandbox-token";
-/** Structured error returned by the broker (mirrors `questpie` `BindingError`). */
-interface SandboxBindingError {
-  code: string;
-  message: string;
-}
-/** Guest → supervisor: a binding RPC awaiting a brokered result. */
-interface GuestRpcMessage {
-  type: "rpc";
-  id: number;
-  method: string;
-  args: unknown;
-}
-/** Guest → supervisor: the run's final result. */
-interface GuestResultMessage {
-  type: "result";
-  ok: boolean;
-  output?: unknown;
-  error?: string;
-  logs: string[];
-}
-/** Any message the guest emits on stdout (framed). */
-type GuestMessage = GuestRpcMessage | GuestResultMessage;
-/** Supervisor → guest: the brokered outcome of a prior {@link GuestRpcMessage}. */
-interface HostRpcResultMessage {
-  type: "rpc-result";
-  id: number;
-  ok: boolean;
-  value?: unknown;
-  error?: SandboxBindingError;
-}
-//#endregion
 //#region src/guest-bindings.d.ts
 /**
  * Guest bindings proxy — the UNTRUSTED-side typed surface a sandboxed mini-app
@@ -237,6 +130,33 @@ interface GuestStore {
     where?: unknown;
   }): Promise<unknown>;
 }
+/** Schema-preserving custom-tool descriptor returned by discovery. */
+interface GuestToolDescriptor {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  annotations?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+}
+/** Protocol-safe custom-tool result returned to the guest. */
+interface GuestToolResult {
+  content: Array<{
+    type: string;
+    [key: string]: unknown;
+  }>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+  _meta?: Record<string, unknown>;
+}
+/** Explicit custom-tool discovery/call surface. Authorization stays host-side. */
+interface GuestTools {
+  list(): Promise<{
+    tools: GuestToolDescriptor[];
+  }>;
+  call(name: string, args?: Record<string, unknown>): Promise<GuestToolResult>;
+}
 /** The `globalThis.questpie` surface handed to untrusted guest code. */
 interface GuestBindings {
   /** Files (file-as-DB), scoped by the run's `capabilities.files`. */
@@ -265,6 +185,11 @@ interface GuestBindings {
    * `collections.document_store.<op>` call.
    */
   store: Record<string, GuestStore>;
+  /**
+   * Explicitly released custom MCP tools. Built-in CRUD/file/store operations
+   * never flow through this namespace.
+   */
+  tools: GuestTools;
 }
 /**
  * Build the guest bindings proxy over an injected {@link HostCall}.
@@ -277,4 +202,4 @@ interface GuestBindings {
  */
 declare function buildGuestBindings(hostCall: HostCall): GuestBindings;
 //#endregion
-export { BINDINGS_TOKEN_HEADER, type DnsResolver, FRAME_MARKER, type GuestBindings, type GuestCollection, type GuestMessage, type GuestResultMessage, type GuestRpcMessage, type HostCall, type HostRpcResultMessage, HttpSandboxAdapter, type HttpSandboxAdapterOptions, type IpValidationResult, type ParsedHost, type SandboxBindingError, type SandboxBindings, type SandboxCapabilities, type SandboxRunRequest, type SandboxRunResult, buildGuestBindings, classifyIpLiteral, httpSandboxAdapter, parseHostEntry, validateEgressHosts, validateHostEgress };
+export { BINDINGS_TOKEN_HEADER, type DnsResolver, FRAME_MARKER, type GuestBindings, type GuestCollection, type GuestMessage, type GuestResultMessage, type GuestRpcMessage, type GuestToolDescriptor, type GuestToolResult, type GuestTools, HOST_ADMISSION_HEADER, type HostCall, type HostRpcResultMessage, HttpSandboxAdapter, type HttpSandboxAdapterOptions, type IpValidationResult, type ParsedHost, SANDBOX_WORKLOAD_DENIAL_MESSAGE, type SandboxBindingError, type SandboxBindings, type SandboxCapabilities, type SandboxCustomToolEvidenceContext, type SandboxCustomToolEvidenceEvent, type SandboxCustomToolsConfig, type SandboxCustomToolsLimits, type SandboxCustomToolsRunOptions, type SandboxRunRequest, type SandboxRunResult, type SandboxWorkloadAdmissionClaims, type SandboxWorkloadAdmissionDenialReason, type SandboxWorkloadAdmissionKey, type SandboxWorkloadAdmissionVerification, type SandboxWorkloadAuditContext, type SandboxWorkloadAuditEvent, type SandboxWorkloadAuthorizationContext, type SandboxWorkloadAuthorizationPhase, type SandboxWorkloadAuthorizer, SandboxWorkloadDeniedError, type SandboxWorkloadPolicy, type SandboxWorkloadRunOptions, WORKLOAD_ADMISSION_HEADER, type WorkloadHttpSandboxOptions, buildGuestBindings, classifyIpLiteral, httpSandboxAdapter, parseHostEntry, sandboxCustomTools, validateEgressHosts, validateHostEgress };

package/dist/index.mjs

@@ -1,16 +1,6 @@
-import { a as validateEgressHosts, i as parseHostEntry, n as httpSandboxAdapter, o as validateHostEgress, r as classifyIpLiteral, t as HttpSandboxAdapter } from "./adapter-http-w7SjAfcC.mjs";
+import { r as sandboxCustomTools } from "./custom-tools-DxI7JvUn.mjs";
+import { a as BINDINGS_TOKEN_HEADER, c as WORKLOAD_ADMISSION_HEADER, d as validateEgressHosts, f as validateHostEgress, i as SandboxWorkloadDeniedError, l as classifyIpLiteral, n as httpSandboxAdapter, o as FRAME_MARKER, r as SANDBOX_WORKLOAD_DENIAL_MESSAGE, s as HOST_ADMISSION_HEADER, t as HttpSandboxAdapter, u as parseHostEntry } from "./adapter-http-Coy4jqsj.mjs";
 
-//#region src/types.ts
-/** Line prefix marking a framed protocol message on guest stdout. */
-const FRAME_MARKER = "__QP_SANDBOX_MSG__";
-/**
-* Header carrying the per-run scoped token on the supervisor → broker request.
-* Mirrors `questpie`'s `BINDINGS_TOKEN_HEADER`. Supervisor-only; never set by or
-* exposed to guest code.
-*/
-const BINDINGS_TOKEN_HEADER = "x-questpie-sandbox-token";
-
-//#endregion
 //#region src/guest-bindings.ts
 /**
 * Build the guest bindings proxy over an injected {@link HostCall}.
@@ -61,9 +51,16 @@ function buildGuestBindings(hostCall) {
 				update: (args) => ds("update", withStoreWhere(args ?? {})),
 				delete: (args = {}) => ds("delete", withStoreWhere(args))
 			};
-		} })
+		} }),
+		tools: {
+			list: async () => await hostCall("tools.list", {}),
+			call: async (name, args) => await hostCall("tools.call", {
+				name,
+				arguments: args ?? {}
+			})
+		}
 	};
 }
 
 //#endregion
-export { BINDINGS_TOKEN_HEADER, FRAME_MARKER, HttpSandboxAdapter, buildGuestBindings, classifyIpLiteral, httpSandboxAdapter, parseHostEntry, validateEgressHosts, validateHostEgress };
+export { BINDINGS_TOKEN_HEADER, FRAME_MARKER, HOST_ADMISSION_HEADER, HttpSandboxAdapter, SANDBOX_WORKLOAD_DENIAL_MESSAGE, SandboxWorkloadDeniedError, WORKLOAD_ADMISSION_HEADER, buildGuestBindings, classifyIpLiteral, httpSandboxAdapter, parseHostEntry, sandboxCustomTools, validateEgressHosts, validateHostEgress };