@agimon-ai/po-codemode 0.0.1-alpha.2 → 0.0.1-alpha.21

package/dist/codemodeTools-De6GNjzR.mjs

@@ -0,0 +1,761 @@
+import { assertCodemodeNamespaceName } from "@agimon-ai/po-core/codemode";
+import { gateApproval, isUnattended } from "@agimon-ai/po-core/approval";
+import { invalidImageReason } from "@agimon-ai/po-core/headless";
+import { Type } from "typebox";
+//#region src/services/codemodeRegistry/index.ts
+const MEMBER_PATH = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/u;
+/** A gated member that cannot be gated must fail at registration, not run ungated. */
+function assertApproval(source, namespace) {
+	for (const [path, policy] of Object.entries(namespace.approval ?? {})) if (!(MEMBER_PATH.test(path) && (policy?.requirement === "ask" || policy?.requirement === "human") && typeof policy.describe === "function")) throw new Error(`Code-mode namespace "${namespace.name}" from ${source} declares an invalid approval for "${path}": use a dotted member path with requirement "ask" or "human" and a describe function.`);
+}
+/** The session's namespaces and script folders, in registration order. One name per session. */
+function createCodemodeRegistry(options) {
+	const entries = /* @__PURE__ */ new Map();
+	const scripts = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => {
+		for (const listener of listeners) listener();
+	};
+	return {
+		register(source, namespace) {
+			assertCodemodeNamespaceName(namespace.name);
+			assertApproval(source, namespace);
+			const taken = entries.get(namespace.name);
+			if (taken) throw new Error(`Code-mode namespace "${namespace.name}" from ${source} is already registered by ${taken.source}.`);
+			const entry = {
+				source,
+				namespace
+			};
+			entries.set(namespace.name, entry);
+			notify();
+			return { dispose: () => {
+				if (entries.get(namespace.name) !== entry) return;
+				entries.delete(namespace.name);
+				notify();
+			} };
+		},
+		list: () => [...entries.values()].filter((entry) => options?.isActive?.(entry.source) ?? true).map((entry) => entry.namespace),
+		registerScripts(_source, entry) {
+			const owned = {
+				domain: entry.domain,
+				directory: entry.directory
+			};
+			scripts.add(owned);
+			notify();
+			return { dispose: () => void (scripts.delete(owned) && notify()) };
+		},
+		listScripts: () => [...scripts],
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+//#endregion
+//#region src/schemas/codemodeTools.ts
+const DiscoverToolSchema = Type.Object({
+	namespace: Type.Optional(Type.String({ description: "Show the full TypeScript declarations of one namespace." })),
+	query: Type.Optional(Type.String({ description: "Find matching members across every namespace." }))
+});
+const ExecToolSchema = Type.Object({
+	code: Type.String({ description: "TypeScript body of an async function. Top-level await and return work. The returned value, console output and image() calls come back." }),
+	timeoutMs: Type.Optional(Type.Integer({
+		minimum: 1e3,
+		maximum: 12e4,
+		description: "Deadline in milliseconds. Default 30000."
+	}))
+});
+const ExecBackgroundToolSchema = Type.Object({
+	code: ExecToolSchema.properties.code,
+	timeoutMs: Type.Optional(Type.Integer({
+		minimum: 1e3,
+		maximum: 72e5,
+		description: "Deadline in milliseconds. Default 1800000 (30 minutes), maximum 2 hours."
+	}))
+});
+const ExecCancelToolSchema = Type.Object({
+	id: Type.String({
+		minLength: 1,
+		description: "The background exec ID returned by exec_background."
+	}),
+	reason: Type.Optional(Type.String({ maxLength: 256 }))
+});
+//#endregion
+//#region src/services/codemodeTools/index.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const MAX_TIMEOUT_MS = 12e4;
+const MIN_TIMEOUT_MS = 1e3;
+const BACKGROUND_DEFAULT_TIMEOUT_MS = 18e5;
+const BACKGROUND_MAX_TIMEOUT_MS = 72e5;
+const MAX_LOG_CHARS = 1e4;
+const MAX_VALUE_CHARS = 65536;
+const MAX_DECLARATION_CHARS = 24e3;
+const MAX_QUERY_LINES = 40;
+const MAX_CONCURRENT_RUNS = 8;
+const MAX_RECORDED_CALLS = 50;
+const MAX_RECORDED_TEXT = 8e3;
+const MAX_RECORDED_JSON = 16e3;
+const MAX_LISTED_SCRIPTS = 20;
+const MAX_IMAGES = 4;
+const MAX_IMAGE_BYTES = 5242880;
+const DEFAULT_IMAGE_MIME = "image/png";
+const MEMBER_LINE = /^\s{2}(?:readonly\s+)?(\w+)\s*[(?:<]/u;
+const GLOBALS_HELP = "Globals: console.log/info/warn/error, image(data, mimeType?) to return a screenshot, sleep(ms). Return a value with `return`.";
+const SCRIPTS_HELP = "Every exec run is saved. Call a saved script with `await (await import(specifier))(args)`; inside it, `args` is the argument and its `return` is the result.";
+function text(value, isError = false) {
+	return {
+		content: [{
+			type: "text",
+			text: value
+		}],
+		...isError ? { isError: true } : {}
+	};
+}
+function truncate(value, limit) {
+	return value.length <= limit ? value : `${value.slice(0, limit)}\n[truncated ${value.length - limit} chars]`;
+}
+function format(value) {
+	if (typeof value === "string") return value;
+	try {
+		const json = JSON.stringify(value, null, 2);
+		if (json !== void 0) return json;
+	} catch {}
+	return String(value);
+}
+function memberNames(namespace) {
+	const names = /* @__PURE__ */ new Set();
+	const declaration = new RegExp(`^declare const ${namespace.name}: \\{([\\s\\S]*?)^\\};`, "mu").exec(namespace.declarations)?.[1] ?? "";
+	for (const line of declaration.split("\n")) {
+		const name = MEMBER_LINE.exec(line)?.[1];
+		if (name) names.add(name);
+	}
+	return [...names];
+}
+function bytesToBase64(bytes) {
+	let binary = "";
+	for (let index = 0; index < bytes.length; index += 32768) binary += String.fromCharCode(...bytes.subarray(index, index + 32768));
+	return btoa(binary);
+}
+/** Collects what a script prints and the images it returns, within the output caps. */
+function createOutput() {
+	const lines = [];
+	const images = [];
+	let imageBytes = 0;
+	const log = (level) => (...args) => {
+		const line = args.map(format).join(" ");
+		lines.push(level === "log" || level === "info" ? line : `[${level}] ${line}`);
+	};
+	const note = (message) => void lines.push(`[note] ${message}`);
+	/** Why an image cannot join this run's output, checked before anything is counted, so a refusal costs nothing. */
+	const refusal = (data, mime) => {
+		if (images.length >= MAX_IMAGES) return /* @__PURE__ */ new RangeError(`An exec run returns at most ${MAX_IMAGES} images.`);
+		if (imageBytes + Math.ceil(data.length * 3 / 4) > MAX_IMAGE_BYTES) return /* @__PURE__ */ new RangeError("Images from one exec run exceed 5 MB.");
+		const invalid = invalidImageReason(data, mime);
+		return invalid === void 0 ? void 0 : /* @__PURE__ */ new TypeError(`image() rejected an undecodable image: ${invalid}.`);
+	};
+	const push = (data, mimeType) => {
+		imageBytes += Math.ceil(data.length * 3 / 4);
+		images.push({
+			data,
+			mimeType
+		});
+	};
+	const addImage = (input, mimeType) => {
+		if (typeof input === "object" && input !== null && "images" in input && Array.isArray(input.images)) {
+			for (const image of input.images) addImage(image);
+			return;
+		}
+		let data;
+		let mime = typeof mimeType === "string" ? mimeType : DEFAULT_IMAGE_MIME;
+		if (typeof input === "string") data = input.replace(/^data:([^;]+);base64,/u, (_match, type) => (mime = type, ""));
+		else if (ArrayBuffer.isView(input)) data = bytesToBase64(new Uint8Array(input.buffer, input.byteOffset, input.byteLength));
+		else if (typeof input === "object" && input !== null && "data" in input && typeof input.data === "string") {
+			data = input.data;
+			if ("mimeType" in input && typeof input.mimeType === "string") mime = input.mimeType;
+		} else throw new TypeError("image() takes base64 text, bytes, or { data, mimeType }.");
+		const error = refusal(data, mime);
+		if (error !== void 0) throw error;
+		push(data, mime);
+	};
+	/** A namespace's image for the model: the same limits as image(), but a refusal is a note and a warning, not a throw. */
+	const emitImage = ({ data, mimeType }) => {
+		const error = refusal(data, mimeType);
+		if (error === void 0) {
+			push(data, mimeType);
+			return { emitted: true };
+		}
+		const warning = `Image not shown to the model: ${error.message}`;
+		note(warning);
+		return {
+			emitted: false,
+			warning
+		};
+	};
+	return {
+		console: {
+			log: log("log"),
+			info: log("info"),
+			warn: log("warn"),
+			error: log("error"),
+			debug: log("debug")
+		},
+		note,
+		addImage,
+		emitImage,
+		lines,
+		images
+	};
+}
+/** The session's active domains; every registered domain when the host reports none. */
+function activeDomains(execution) {
+	return execution?.selection?.domains;
+}
+/** A JSON copy of `value`, or undefined when it does not serialise or is larger than `limit` characters. */
+function bounded(value, limit) {
+	try {
+		const json = JSON.stringify(value);
+		return json !== void 0 && json.length <= limit ? JSON.parse(json) : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* The call as it is kept in the transcript: text clipped, pictures kept while the run's
+* budget lasts (a note says when one was not), args and details dropped when large.
+*/
+function recordedCall(call, budget) {
+	const content = (call.result?.content ?? []).flatMap((block) => {
+		const { type, text, data, mimeType } = block ?? {};
+		if (type === "text" && typeof text === "string") return [{
+			type: "text",
+			text: truncate(text, MAX_RECORDED_TEXT)
+		}];
+		if (type !== "image" || typeof data !== "string" || typeof mimeType !== "string") return [];
+		const bytes = Math.ceil(data.length * 3 / 4);
+		if (budget.count >= MAX_IMAGES || budget.bytes + bytes > MAX_IMAGE_BYTES) return [{
+			type: "text",
+			text: `[picture not kept: one exec run keeps at most ${MAX_IMAGES} pictures, 5 MB]`
+		}];
+		budget.count += 1;
+		budget.bytes += bytes;
+		return [{
+			type: "image",
+			data,
+			mimeType
+		}];
+	});
+	const details = bounded(call.result?.details, MAX_RECORDED_JSON);
+	if (call.result?.details !== void 0 && details === void 0) content.push({
+		type: "text",
+		text: `[details not kept: larger than ${MAX_RECORDED_JSON} characters]`
+	});
+	return {
+		name: call.name,
+		tool: call.tool,
+		args: bounded(call.args, MAX_RECORDED_JSON) ?? {},
+		ok: call.ok,
+		ms: Math.max(0, Math.round(call.ms)),
+		...call.error === void 0 ? {} : { error: truncate(call.error, MAX_RECORDED_TEXT) },
+		...call.result === void 0 ? {} : { result: {
+			content,
+			...details === void 0 ? {} : { details }
+		} }
+	};
+}
+function toResult(result, output, saved, calls) {
+	const content = [];
+	if (output.lines.length > 0) content.push({
+		type: "text",
+		text: truncate(output.lines.join("\n"), MAX_LOG_CHARS)
+	});
+	if (result.ok) {
+		if (ArrayBuffer.isView(result.value)) content.push({
+			type: "text",
+			text: "The script returned bytes. Pass them to image(data, mimeType) instead."
+		});
+		else if (result.value !== void 0) content.push({
+			type: "text",
+			text: truncate(format(result.value), MAX_VALUE_CHARS)
+		});
+	} else {
+		const { kind, name, message } = result.error;
+		const hint = kind === "timeout" ? " Raise timeoutMs or split the work into smaller exec calls." : "";
+		content.push({
+			type: "text",
+			text: `${name}: ${message}${hint}`
+		});
+	}
+	if (content.length === 0) content.push({
+		type: "text",
+		text: "(no return value)"
+	});
+	if (saved !== void 0) content.push({
+		type: "text",
+		text: saved
+	});
+	for (const image of output.images) content.push({
+		type: "image",
+		data: image.data,
+		mimeType: image.mimeType
+	});
+	return {
+		content,
+		...calls.length > 0 ? { details: { calls } } : {},
+		...result.ok ? {} : { isError: true }
+	};
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) return reject(/* @__PURE__ */ new Error("Run ended."));
+		const stop = () => {
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error("Run ended."));
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", stop);
+			resolve();
+		}, Math.max(0, ms));
+		signal.addEventListener("abort", stop, { once: true });
+	});
+}
+/**
+* A view of `target` whose gated member paths ask before calling the original on its own receiver.
+* The view inherits from a shadow, so frozen targets keep their proxy invariants.
+*/
+function gateMembers(target, policies, prefix, gate) {
+	if (typeof target !== "object" || target === null) throw new Error(`Code-mode member ${prefix} declares approval but is not an object.`);
+	const overrides = /* @__PURE__ */ new Map();
+	const nested = /* @__PURE__ */ new Map();
+	for (const [path, policy] of Object.entries(policies)) {
+		const dot = path.indexOf(".");
+		if (dot === -1) {
+			const original = Reflect.get(target, path, target);
+			if (typeof original !== "function") throw new Error(`Code-mode member ${prefix}.${path} declares approval but is not a function.`);
+			overrides.set(path, gate(`${prefix}.${path}`, policy, (args) => Reflect.apply(original, target, args)));
+		} else {
+			const head = path.slice(0, dot);
+			nested.set(head, {
+				...nested.get(head),
+				[path.slice(dot + 1)]: policy
+			});
+		}
+	}
+	for (const [key, children] of nested) overrides.set(key, gateMembers(Reflect.get(target, key, target), children, `${prefix}.${key}`, gate));
+	return new Proxy(Object.create(target), {
+		get: (_shadow, key) => overrides.has(key) ? overrides.get(key) : Reflect.get(target, key, target),
+		has: (_shadow, key) => overrides.has(key) || Reflect.has(target, key),
+		ownKeys: () => Reflect.ownKeys(target),
+		getOwnPropertyDescriptor: (_shadow, key) => {
+			const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
+			if (!descriptor) return void 0;
+			return {
+				configurable: true,
+				enumerable: descriptor.enumerable ?? false,
+				writable: false,
+				value: overrides.has(key) ? overrides.get(key) : Reflect.get(target, key, target)
+			};
+		},
+		set: () => false,
+		defineProperty: () => false,
+		deleteProperty: () => false
+	});
+}
+/** `name (asks first)` for each gated top-level member, so discover shows which calls wait for the person. */
+function gatedLabel(namespace, member) {
+	const policies = Object.entries(namespace.approval ?? {}).filter(([path]) => path === member || path.startsWith(`${member}.`));
+	if (policies.length === 0) return member;
+	return policies.some(([, policy]) => policy.requirement === "human") ? `${member} (needs the person)` : `${member} (asks first)`;
+}
+/** `discover` and `exec` for one session, over the namespaces its packages contributed. */
+function createCodemodeTools({ registry, isolate, scripts, npm, signal: lifecycleSignal, onBackgroundChange, approval }) {
+	let running = 0;
+	let closing = false;
+	const lifecycle = new AbortController();
+	const ownerSignal = lifecycleSignal ? AbortSignal.any([lifecycle.signal, lifecycleSignal]) : lifecycle.signal;
+	const jobs = /* @__PURE__ */ new Map();
+	const backgroundWork = {
+		provider: "po-codemode-background",
+		listActiveWork: () => [...jobs.values()].map(({ id, sessionId, status }) => ({
+			id,
+			sessionId,
+			status,
+			label: "Background exec"
+		}))
+	};
+	const visible = (service) => registry.list().filter((namespace) => service.liveObjects || namespace.portable === true);
+	let domainScripts = [];
+	let refreshes = 0;
+	const refreshScripts = () => {
+		if (!scripts) return;
+		const turn = ++refreshes;
+		scripts.list().then((entries) => {
+			if (turn !== refreshes) return;
+			domainScripts = entries.flatMap((entry) => entry.specifier.startsWith("session:") ? [] : [entry.specifier]);
+		}, () => void 0);
+	};
+	refreshScripts();
+	const unsubscribe = registry.subscribe(refreshScripts);
+	const domainScriptsHelp = () => {
+		if (domainScripts.length === 0) return [];
+		return [`Domain scripts: ${domainScripts.slice(0, MAX_LISTED_SCRIPTS).join(", ")}${domainScripts.length > MAX_LISTED_SCRIPTS ? ` and ${domainScripts.length - MAX_LISTED_SCRIPTS} more` : ""}. Use discover({ query }) to see what one does before importing it.`];
+	};
+	const executeCode = async (parameters, signal, execution, deadlineMs, toolCallId, background = false) => {
+		const service = isolate();
+		if (!service) return text("Code mode is not available on this host.", true);
+		if (closing || ownerSignal.aborted) return text("Code mode session is disposing.", true);
+		if (running >= MAX_CONCURRENT_RUNS) return text(`This session already has ${MAX_CONCURRENT_RUNS} exec runs active. Wait for one to finish.`, true);
+		running += 1;
+		const expiresAt = Date.now() + deadlineMs;
+		const controller = new AbortController();
+		const runSignal = AbortSignal.any([
+			ownerSignal,
+			controller.signal,
+			...signal ? [signal] : []
+		]);
+		const cleanups = [];
+		const calls = [];
+		const imageBudget = {
+			count: 0,
+			bytes: 0
+		};
+		const output = createOutput();
+		const presence = execution.interaction === "unattended" ? "unattended" : execution.sessionContext?.interaction;
+		const interaction = isUnattended({
+			...execution.caller === void 0 ? {} : { caller: execution.caller },
+			background,
+			...presence === void 0 ? {} : { interaction: presence }
+		}) ? "unattended" : "interactive";
+		const run = {
+			sessionId: execution.sessionId,
+			...execution.caller === void 0 ? {} : { caller: execution.caller },
+			toolCallId,
+			...background ? { background } : {},
+			interaction,
+			signal: runSignal,
+			onDispose: (cleanup) => void cleanups.push(cleanup),
+			record: (call) => {
+				if (calls.length < MAX_RECORDED_CALLS) calls.push(recordedCall(call, imageBudget));
+			},
+			emitImage: (image) => runSignal.aborted ? {
+				emitted: false,
+				warning: "The exec run has ended."
+			} : output.emitImage(image)
+		};
+		const gateFor = (namespace) => (name, policy, call) => async (...args) => {
+			const gate = await gateApproval({
+				policy,
+				operation: {
+					kind: "codemode",
+					name
+				},
+				input: args[0],
+				sessionId: run.sessionId,
+				toolCallId,
+				...run.caller === void 0 ? {} : { caller: run.caller },
+				background,
+				interaction,
+				service: approval?.(),
+				signal: runSignal,
+				expiresAt
+			});
+			if (!gate.ok) throw new Error(gate.reason);
+			if (!registry.list().includes(namespace)) throw new Error(`'${name}' is no longer active. Nothing ran.`);
+			if (runSignal.aborted) throw new Error(`'${name}' was cancelled. Nothing ran.`);
+			return call(args);
+		};
+		let saved;
+		let result = {
+			ok: true,
+			value: void 0
+		};
+		try {
+			runSignal.throwIfAborted();
+			try {
+				const file = await scripts?.save(parameters.code);
+				if (file) saved = `Saved as ${file.specifier} (${file.path})`;
+			} catch (error) {
+				output.note(`Could not save the script: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			runSignal.throwIfAborted();
+			const globals = {
+				console: output.console,
+				image: output.addImage,
+				sleep: (ms) => sleep(ms, runSignal)
+			};
+			const deny = /* @__PURE__ */ new Set();
+			for (const namespace of visible(service)) {
+				const bound = namespace.bind(run);
+				if (namespace.approval === void 0 || Object.keys(namespace.approval).length === 0) globals[namespace.name] = bound;
+				else try {
+					globals[namespace.name] = gateMembers(bound, namespace.approval, namespace.name, gateFor(namespace));
+				} catch (error) {
+					output.note(`${namespace.name} is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+					continue;
+				}
+				for (const member of namespace.deny ?? []) deny.add(member);
+			}
+			result = await service.run({
+				source: parameters.code,
+				globals,
+				deadlineMs,
+				signal: runSignal,
+				deny: [...deny],
+				onDiagnostic: output.note,
+				resolveImport: async (specifier) => {
+					if (specifier.startsWith("node:")) throw new Error(`Code mode is sandboxed, so "${specifier}" cannot be imported. Use the shell namespace or an npm: import.`);
+					if (!specifier.startsWith("npm:")) {
+						if (!scripts) throw new Error("Script imports are not available on this host.");
+						return scripts.resolve(specifier, activeDomains(execution));
+					}
+					const loader = npm?.();
+					if (!loader) throw new Error("npm imports are not available on this host.");
+					run.signal.throwIfAborted();
+					const started = Date.now();
+					try {
+						const exports = await loader.import(specifier, {
+							sessionId: run.sessionId,
+							signal: run.signal
+						});
+						run.signal.throwIfAborted();
+						run.record?.({
+							name: "npm.import",
+							tool: "npm",
+							args: { specifier },
+							ms: Date.now() - started,
+							ok: true
+						});
+						return {
+							kind: "module",
+							id: specifier,
+							exports
+						};
+					} catch (error) {
+						run.record?.({
+							name: "npm.import",
+							tool: "npm",
+							args: { specifier },
+							ms: Date.now() - started,
+							ok: false,
+							error: error instanceof Error ? error.message : String(error)
+						});
+						throw error;
+					}
+				}
+			});
+		} catch (error) {
+			result = {
+				ok: false,
+				error: {
+					kind: "error",
+					name: "Error",
+					message: `Code mode could not run the script: ${error instanceof Error ? error.message : String(error)}`
+				}
+			};
+		} finally {
+			controller.abort();
+			for (const cleanup of cleanups.reverse()) await Promise.resolve().then(cleanup).catch((error) => {
+				const message = `Code mode cleanup failed: ${String(error)}`;
+				output.note(message);
+				result = {
+					ok: false,
+					error: {
+						kind: "error",
+						name: "CleanupError",
+						message
+					}
+				};
+			});
+			running -= 1;
+		}
+		return toResult(result, output, saved, calls);
+	};
+	return {
+		discover: {
+			name: "discover",
+			label: "Discover",
+			description: "List the code-mode namespaces and reusable scripts you can use from `exec`, show one namespace in full, or search members and scripts. Not required before exec: its description already names the namespaces.",
+			parameters: DiscoverToolSchema,
+			promptSnippet: "List code-mode namespaces and their TypeScript declarations",
+			executionMode: "parallel",
+			async execute(_toolCallId, parameters, _signal, _onUpdate, execution) {
+				const service = isolate();
+				if (!service) return text("Code mode is not available on this host.", true);
+				const namespaces = visible(service);
+				const listed = scripts && service.liveObjects ? await scripts.list(activeDomains(execution)) : [];
+				if (parameters.namespace !== void 0) {
+					const found = namespaces.find((namespace) => namespace.name === parameters.namespace);
+					if (!found) {
+						const names = namespaces.map((namespace) => namespace.name).join(", ") || "none";
+						return text(`Unknown namespace "${parameters.namespace}". Registered: ${names}.`, true);
+					}
+					return text(truncate(found.declarations, MAX_DECLARATION_CHARS));
+				}
+				if (parameters.query !== void 0) {
+					const needle = parameters.query.toLowerCase();
+					const hits = [];
+					for (const namespace of namespaces) {
+						const lines = namespace.declarations.split("\n");
+						lines.forEach((line, index) => {
+							if (!line.toLowerCase().includes(needle) || hits.length >= MAX_QUERY_LINES) return;
+							const doc = lines[index - 1]?.trim().startsWith("/**") ? `${lines[index - 1]?.trim()} ` : "";
+							hits.push(`${namespace.name}: ${doc}${line.trim()}`);
+						});
+					}
+					for (const script of listed) {
+						if (hits.length >= MAX_QUERY_LINES) break;
+						if (`${script.specifier} ${script.description}`.toLowerCase().includes(needle)) hits.push(`script ${script.specifier}: ${script.description}`);
+					}
+					return text(hits.length > 0 ? hits.join("\n") : `No members or scripts match "${parameters.query}".`);
+				}
+				const sections = [];
+				if (namespaces.length === 0) sections.push("No namespaces are registered in this session.");
+				for (const namespace of namespaces) {
+					const members = memberNames(namespace).map((member) => gatedLabel(namespace, member));
+					sections.push(`- ${namespace.name}: ${namespace.summary}\n  members: ${members.join(", ")}`);
+				}
+				sections.push(GLOBALS_HELP);
+				if (!service.liveObjects) sections.push("This host runs plain JavaScript with JSON-only functions.");
+				if (listed.length > 0) {
+					sections.push(`Scripts. ${SCRIPTS_HELP}`);
+					for (const script of listed.slice(0, MAX_LISTED_SCRIPTS)) sections.push(`- ${script.specifier}${script.description ? `: ${script.description}` : ""}`);
+					if (listed.length > MAX_LISTED_SCRIPTS) sections.push(`...and ${listed.length - MAX_LISTED_SCRIPTS} more; use discover({ query }) to search.`);
+				}
+				if (namespaces.length > 0) sections.push("Call discover({ namespace }) for full types.");
+				return text(sections.join("\n"));
+			}
+		},
+		exec: {
+			name: "exec",
+			label: "Exec",
+			get description() {
+				const service = isolate();
+				return [
+					"Run a TypeScript script inside the Po server with live objects from the namespaces below in scope.",
+					"It runs with full server trust, like bash. Keep each call to one logical step.",
+					(service ? visible(service) : []).map((namespace) => `- ${namespace.name}: ${namespace.summary}`).join("\n") || "(no namespaces registered yet; call discover to check)",
+					GLOBALS_HELP,
+					...scripts && service?.liveObjects ? [`${SCRIPTS_HELP} discover lists saved and domain scripts.`, ...domainScriptsHelp()] : [],
+					"Use discover({ namespace }) for full signatures when needed."
+				].join("\n");
+			},
+			parameters: ExecToolSchema,
+			promptSnippet: "Run a TypeScript script against live Po objects (browser and other namespaces)",
+			executionMode: "serial",
+			async execute(toolCallId, parameters, signal, _onUpdate, execution) {
+				return executeCode(parameters, signal, execution, Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, parameters.timeoutMs ?? DEFAULT_TIMEOUT_MS)), toolCallId);
+			}
+		},
+		execBackground: {
+			name: "exec_background",
+			label: "Background Exec",
+			description: "Run a long-lived Node code-mode script. Returns its ID immediately; one completion message arrives after execution and cleanup. End the turn rather than polling. Full server trust, like exec.",
+			parameters: ExecBackgroundToolSchema,
+			mainAgentOnly: true,
+			executionMode: "serial",
+			async execute(toolCallId, parameters, signal, _onUpdate, execution) {
+				if (signal?.aborted) return text("Background exec launch was aborted.", true);
+				if (closing || ownerSignal.aborted) return text("Code mode session is disposing.", true);
+				if (!isolate()?.liveObjects) return text("Background exec requires a Node host with live objects.", true);
+				if (!execution.session?.admitMessage) return text("This session cannot admit background exec completion messages.", true);
+				if (running >= MAX_CONCURRENT_RUNS) return text(`This session already has ${MAX_CONCURRENT_RUNS} exec runs active. Wait for one to finish.`, true);
+				const deadlineMs = Math.min(BACKGROUND_MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, parameters.timeoutMs ?? BACKGROUND_DEFAULT_TIMEOUT_MS));
+				const id = crypto.randomUUID();
+				const controller = new AbortController();
+				const job = {
+					id,
+					sessionId: execution.sessionId,
+					controller,
+					status: "running",
+					done: Promise.resolve()
+				};
+				jobs.set(id, job);
+				onBackgroundChange?.();
+				job.done = (async () => {
+					let timedOut = false;
+					const timer = setTimeout(() => {
+						timedOut = true;
+						controller.abort();
+					}, deadlineMs);
+					try {
+						const result = await executeCode(parameters, controller.signal, execution, deadlineMs, toolCallId, true);
+						clearTimeout(timer);
+						job.status = "reporting";
+						onBackgroundChange?.();
+						const status = timedOut ? "timed-out" : controller.signal.aborted ? "stopped" : result.isError ? "failed" : "completed";
+						const message = {
+							type: "po-codemode-finished",
+							text: `Background exec ${id} ${status}.\n${result.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n")}`,
+							display: true,
+							details: {
+								id,
+								status,
+								result
+							}
+						};
+						let warned = false;
+						while (!ownerSignal.aborted) {
+							let stopAdmission;
+							try {
+								const stopped = new Promise((resolve) => {
+									stopAdmission = resolve;
+									ownerSignal.addEventListener("abort", stopAdmission, { once: true });
+									if (ownerSignal.aborted) resolve();
+								});
+								await Promise.race([execution.session.admitMessage(message, "steer", `po-codemode-finished:${execution.sessionId}:${id}`), stopped]);
+								break;
+							} catch (error) {
+								if (ownerSignal.aborted) break;
+								if (!warned) {
+									warned = true;
+									await Promise.resolve().then(() => execution.client.notify({
+										body: `Background exec completion admission failed; retrying: ${String(error)}`,
+										level: "warning"
+									})).catch(() => void 0);
+								}
+								await sleep(250, ownerSignal).catch(() => void 0);
+							} finally {
+								if (stopAdmission) ownerSignal.removeEventListener("abort", stopAdmission);
+							}
+						}
+					} finally {
+						clearTimeout(timer);
+						jobs.delete(id);
+						onBackgroundChange?.();
+					}
+				})();
+				return {
+					...text(JSON.stringify({ id })),
+					details: { id }
+				};
+			}
+		},
+		execCancel: {
+			name: "exec_cancel",
+			label: "Cancel Exec",
+			description: "Cancel a background exec in this session. Its terminal message follows child cleanup.",
+			parameters: ExecCancelToolSchema,
+			mainAgentOnly: true,
+			executionMode: "serial",
+			async execute(_toolCallId, parameters, _signal, _onUpdate, execution) {
+				const job = jobs.get(parameters.id);
+				if (job && job.sessionId !== execution.sessionId) return text("Background exec belongs to another session.", true);
+				if (job?.status === "running") job.controller.abort(parameters.reason ? new Error(parameters.reason) : void 0);
+				return text(JSON.stringify({
+					id: parameters.id,
+					status: job?.status === "running" ? "stopping" : "finished"
+				}));
+			}
+		},
+		backgroundWork,
+		async dispose() {
+			closing = true;
+			unsubscribe();
+			lifecycle.abort();
+			await Promise.all([...jobs.values()].map((job) => job.done));
+		}
+	};
+}
+//#endregion
+export { createCodemodeRegistry as n, createCodemodeTools as t };
+
+//# sourceMappingURL=codemodeTools-De6GNjzR.mjs.map