@qilin-agent/tools 3.1.5 → 3.1.6

package/lib/index.js

@@ -1,4 +1,4 @@
-import { Service } from "@qilin-agent/kylin";
+import { Service, symbols } from "@qilin-agent/kylin";
 import z from "@qilin-agent/schemastery";
 import { AnonymousEntries, NamedEntries, ScopedLayers, scopeOf, scopeTarget } from "@qilin-agent/scope";
 import { HarnessError, createUserMessage } from "@qilin-agent/llm";
@@ -884,6 +884,63 @@ function defineTool(options) {
 	return tool;
 }
 //#endregion
+//#region lib/types/ptc-calls.js
+/** Keeps calls under a changed policy from overlapping their canceled predecessors. */
+var PtcCalls = class {
+	calls = /* @__PURE__ */ new Map();
+	disposed = false;
+	/**
+	* Observe policy changes for the owning tool registry.
+	* @param ctx - Registry lifecycle and Session events.
+	*/
+	constructor(ctx) {
+		ctx.on("session/event", (session, event) => {
+			if (event.type !== "sandbox/mode") return;
+			for (const call of this.calls.get(session.id) ?? []) if (call.mode !== event.data.mode) call.controller.abort(/* @__PURE__ */ new Error("sandbox mode changed"));
+		}, { global: true });
+		ctx.effect(() => async () => {
+			this.disposed = true;
+			const calls = [...this.calls.values()].flatMap((calls) => [...calls]);
+			for (const call of calls) call.controller.abort(/* @__PURE__ */ new Error("PTC tool registry disposed"));
+			await Promise.all(calls.map((call) => call.done));
+		}, "PTC calls");
+	}
+	/**
+	* Await canceled predecessors before resolving authority and admitting a call.
+	* @param sessionId - Calling Session.
+	* @param signal - Caller cancellation.
+	* @param mode - Current standing mode, read after preceding cleanup.
+	* @param run - Complete call, including nested-tool cleanup.
+	* @returns The call result.
+	*/
+	async run(sessionId, signal, mode, run) {
+		for (;;) {
+			const pending = [...this.calls.get(sessionId) ?? []].filter((call) => call.controller.signal.aborted);
+			if (pending.length === 0) break;
+			await Promise.all(pending.map((call) => call.done));
+		}
+		signal.throwIfAborted();
+		if (this.disposed) throw new Error("PTC tool registry disposed");
+		const controller = new AbortController();
+		const done = Promise.withResolvers();
+		const call = {
+			mode: mode(),
+			controller,
+			done: done.promise
+		};
+		let calls = this.calls.get(sessionId);
+		if (calls === void 0) this.calls.set(sessionId, calls = /* @__PURE__ */ new Set());
+		calls.add(call);
+		try {
+			return await run(AbortSignal.any([signal, controller.signal]));
+		} finally {
+			calls.delete(call);
+			if (calls.size === 0) this.calls.delete(sessionId);
+			done.resolve(void 0);
+		}
+	}
+};
+//#endregion
 //#region lib/types/ptc.js
 /**
 * PTC mode `run_code` transport. Programs call the registry's agent-visible
@@ -894,23 +951,27 @@ function defineTool(options) {
 */
 /** The model-facing name of the PTC mode tool. */
 const RUN_CODE_NAME = "run_code";
-/**
-* The TypeScript flavor: the fallback for a schema read with no runtime
-* mounted ({@link resolveFlavor} owns which readers reach that). A real
-* assembly always resolves a runtime first, so the model never sees this
-* fallback outside its own language.
-*/
-const TYPESCRIPT_FLAVOR = {
-	description: "Execute a TypeScript program against the available tools. Takes two required arguments: `description`, a short summary of what the program does, and `code`, the BODY of an async function (erasable syntax only; top-level `await` and `return` work). Call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return is program output — curate it. Image-bearing subtool results are attached after the run.",
+/** Keep tool-call rules here; the runtime owns evaluation syntax and state retention. */
+function runCodeFlavor(language, execution = {
+	programDescription: "the program to execute",
+	outputInstruction: "Curate the program output.",
+	codeDescription: `The ${language} program to execute, following this tool's execution instructions.`
+}) {
+	return {
+		description: `Execute a ${language} program against the available tools. Takes two required arguments: \`description\`, a short summary of what the program does, and \`code\`, ${execution.programDescription}. Call tools as \`await tools.name(args)\` per the declarations in the system prompt. ${execution.outputInstruction} Image-bearing subtool results are attached after the run.`,
+		codeDescription: execution.codeDescription
+	};
+}
+const TYPESCRIPT_FLAVOR = runCodeFlavor("TypeScript");
+const TYPESCRIPT_FUNCTION_FLAVOR = runCodeFlavor("TypeScript", {
+	programDescription: "the BODY of an async function (erasable syntax only; top-level `await` and `return` work)",
+	outputInstruction: "Only what you print or return is program output — curate it.",
 	codeDescription: "The program: the body of an async TypeScript function."
-};
+});
 /** Per-language `run_code` schema flavors (see {@link RunCodeFlavor}); one entry per {@link PtcSdkLanguage}. */
 const RUN_CODE_FLAVORS = {
 	typescript: TYPESCRIPT_FLAVOR,
-	python: {
-		description: "Execute a Python program against the available tools. Takes two required arguments: `description`, a short summary of what the program does, and `code`, the BODY of an async function (top-level `await` and `return` work). Call tools as `await tools.name(args)` per the declarations in the system prompt. Use `print(...)` and/or `return <value>` for program output — curate it. Image-bearing subtool results are attached after the run.",
-		codeDescription: "The program: the body of an async Python function."
-	}
+	python: runCodeFlavor("Python")
 };
 /**
 * The `description` parameter's model-facing description: language-independent
@@ -972,7 +1033,7 @@ function resolveFlavor(peekRuntime) {
 		const known = Object.keys(RUN_CODE_FLAVORS).map((name) => JSON.stringify(name)).join(", ");
 		throw new Error(`qilin-tools: no run_code schema flavor registered for runtime language ${JSON.stringify(runtime.language)} (known: ${known})`);
 	}
-	return flavor;
+	return runtime.language === "typescript" && runtime.programFormat === "function-body" ? TYPESCRIPT_FUNCTION_FLAVOR : flavor;
 }
 /**
 * Thrown by `run_code` when the program run itself failed — a program
@@ -1104,18 +1165,21 @@ function renderValue(value) {
 	return typeof value === "string" ? value : renderJsonValue(value);
 }
 /**
-* Build the `run_code` {@link ToolDefinition}: required `description` and
-* `code` parameters, executed through the dispatch bridge described
+* Build the `run_code` {@link ToolDefinition}: required `code` and
+* `description` parameters, executed through the dispatch bridge described
 * above. The
 * registry reserves it as presentation infrastructure under non-native modes,
 * outside the filterable global/scoped capability layers.
 * @param registry - the owning registry (sub-calls go through its `execute`,
 *   bindings cover its registered tools).
 * @param options - the registry-private capabilities described above.
+* @param ctx - Owning registry context, independent of the calling Agent.
 * @returns the registry-ready definition.
 */
-function createRunCodeTool(registry, options) {
+function createRunCodeTool(registry, options, ctx) {
 	const { requireRuntime, peekRuntime, maxParallel, shapeDispatchLog } = options;
+	const stateOwners = /* @__PURE__ */ new WeakMap();
+	const calls = new PtcCalls(ctx);
 	const definition = defineTool({
 		name: RUN_CODE_NAME,
 		description: TYPESCRIPT_FLAVOR.description,
@@ -1182,265 +1246,287 @@ function createRunCodeTool(registry, options) {
 		async execute(args, exec) {
 			if (args.description.trim().length === 0) throw new Error("invalid description: expected a non-empty string");
 			const runtime = requireRuntime();
-			validateEscalationArgs(args.sandbox_permissions, args.justification);
-			if (args.timeoutMs !== void 0 && runtime.timeout === void 0) throw new Error("timeoutMs is not available for this PTC runtime");
-			if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error("invalid timeoutMs: expected a positive finite number");
-			const standingPolicy = runtime.sandboxMode === void 0 ? void 0 : options.resolveSandboxPolicy(exec);
-			let policy = standingPolicy;
-			if (args.sandbox_permissions !== void 0 && args.justification !== void 0) {
-				if (standingPolicy === void 0) throw new Error("sandbox_permissions is not available for this PTC runtime");
-				const approvedMode = await approveEscalation({
-					requestedMode: args.sandbox_permissions,
-					justification: args.justification,
-					effectiveMode: standingPolicy.mode,
-					subject: "program"
-				}, {
-					approver: options.peekApprover(),
-					agent: exec.agent,
-					callId: exec.callId,
-					toolName: RUN_CODE_NAME,
-					signal: exec.signal
+			const run = async (callSignal) => {
+				validateEscalationArgs(args.sandbox_permissions, args.justification);
+				if (args.timeoutMs !== void 0 && runtime.timeout === void 0) throw new Error("timeoutMs is not available for this PTC runtime");
+				if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error("invalid timeoutMs: expected a positive finite number");
+				const standingPolicy = runtime.sandboxMode === void 0 ? void 0 : options.resolveSandboxPolicy(exec);
+				let policy = standingPolicy;
+				if (args.sandbox_permissions !== void 0 && args.justification !== void 0) {
+					if (standingPolicy === void 0) throw new Error("sandbox_permissions is not available for this PTC runtime");
+					const approvedMode = await approveEscalation({
+						requestedMode: args.sandbox_permissions,
+						justification: args.justification,
+						effectiveMode: standingPolicy.mode,
+						subject: "program"
+					}, {
+						approver: options.peekApprover(),
+						agent: exec.agent,
+						callId: exec.callId,
+						toolName: RUN_CODE_NAME,
+						signal: callSignal
+					});
+					policy = {
+						...standingPolicy,
+						mode: approvedMode
+					};
+				}
+				const cwd = await options.resolveWorkingDirectory({
+					...exec,
+					signal: callSignal
 				});
-				policy = {
-					...standingPolicy,
-					mode: approvedMode
+				callSignal.throwIfAborted();
+				const runController = new AbortController();
+				const onOuterAbort = () => {
+					runController.abort(callSignal.reason);
 				};
-			}
-			const cwd = await options.resolveWorkingDirectory(exec);
-			exec.signal.throwIfAborted();
-			const runController = new AbortController();
-			const onOuterAbort = () => {
-				runController.abort(exec.signal.reason);
-			};
-			exec.signal.addEventListener("abort", onOuterAbort, { once: true });
-			let dispatches = 0;
-			const pendingQueue = [];
-			const inFlight = /* @__PURE__ */ new Set();
-			/** Tracked settle-event side work (log-content listener + append), drained at run settlement. */
-			const logWork = /* @__PURE__ */ new Set();
-			const commitQueue = [];
-			let exclusiveActive = false;
-			let driving = false;
-			let driverRun = Promise.resolve();
-			let wake;
-			const wakeup = () => {
-				const release = wake;
-				wake = void 0;
-				release?.();
-			};
-			/**
-			* The single ordered lane. Each pass commits the head-of-line settled
-			* dispatch (ordered post-execute), then starts the next queued entry if
-			* its slot is free (ordered pre-execute), and otherwise sleeps until a
-			* body settles or a new submission arrives. One run reaching the
-			* empty-queues/empty-pool state is quiescence.
-			*/
-			const drive = () => {
-				if (driving) return driverRun;
-				driving = true;
-				driverRun = (async () => {
-					try {
-						for (;;) {
-							const signal = new Promise((resolve) => {
-								wake = resolve;
-							});
-							const commitHead = commitQueue[0];
-							if (commitHead !== void 0 && commitHead.settled) {
-								commitQueue.shift();
-								await commitHead.commit();
-								if (commitHead.mode === "exclusive") exclusiveActive = false;
-								continue;
-							}
-							const head = pendingQueue[0];
-							if (head !== void 0) {
-								if (runController.signal.aborted) {
-									pendingQueue.shift();
-									head.abandon();
+				callSignal.addEventListener("abort", onOuterAbort, { once: true });
+				let dispatches = 0;
+				const pendingQueue = [];
+				const inFlight = /* @__PURE__ */ new Set();
+				/** Tracked settle-event side work (log-content listener + append), drained at run settlement. */
+				const logWork = /* @__PURE__ */ new Set();
+				const commitQueue = [];
+				let exclusiveActive = false;
+				let driving = false;
+				let driverRun = Promise.resolve();
+				let wake;
+				const wakeup = () => {
+					const release = wake;
+					wake = void 0;
+					release?.();
+				};
+				/**
+				* The single ordered lane. Each pass commits the head-of-line settled
+				* dispatch (ordered post-execute), then starts the next queued entry if
+				* its slot is free (ordered pre-execute), and otherwise sleeps until a
+				* body settles or a new submission arrives. One run reaching the
+				* empty-queues/empty-pool state is quiescence.
+				*/
+				const drive = () => {
+					if (driving) return driverRun;
+					driving = true;
+					driverRun = (async () => {
+						try {
+							for (;;) {
+								const signal = new Promise((resolve) => {
+									wake = resolve;
+								});
+								const commitHead = commitQueue[0];
+								if (commitHead !== void 0 && commitHead.settled) {
+									commitQueue.shift();
+									await commitHead.commit();
+									if (commitHead.mode === "exclusive") exclusiveActive = false;
 									continue;
 								}
-								const mode = head.classify();
-								if (!exclusiveActive && (mode === "exclusive" ? inFlight.size === 0 : inFlight.size < maxParallel)) {
-									if (mode === "exclusive") exclusiveActive = true;
-									head.mode = mode;
-									pendingQueue.shift();
-									commitQueue.push(head);
-									await head.start();
-									const flight = head.flight.finally(() => {
-										inFlight.delete(flight);
-										wakeup();
-									});
-									inFlight.add(flight);
-									continue;
+								const head = pendingQueue[0];
+								if (head !== void 0) {
+									if (runController.signal.aborted) {
+										pendingQueue.shift();
+										head.abandon();
+										continue;
+									}
+									const mode = head.classify();
+									if (!exclusiveActive && (mode === "exclusive" ? inFlight.size === 0 : inFlight.size < maxParallel)) {
+										if (mode === "exclusive") exclusiveActive = true;
+										head.mode = mode;
+										pendingQueue.shift();
+										commitQueue.push(head);
+										await head.start();
+										const flight = head.flight.finally(() => {
+											inFlight.delete(flight);
+											wakeup();
+										});
+										inFlight.add(flight);
+										continue;
+									}
 								}
+								if (pendingQueue.length === 0 && commitQueue.length === 0 && inFlight.size === 0) return;
+								await signal;
 							}
-							if (pendingQueue.length === 0 && commitQueue.length === 0 && inFlight.size === 0) return;
-							await signal;
+						} finally {
+							driving = false;
+							wake = void 0;
 						}
-					} finally {
-						driving = false;
-						wake = void 0;
-					}
-				})();
-				return driverRun;
-			};
-			/** Every dispatch settled AND committed; nothing can start (the run is aborted at call time). */
-			const drainDispatches = async () => {
-				await drive();
-				while (logWork.size > 0) await Promise.allSettled([...logWork]);
-			};
-			const runOver = () => runController.signal.aborted;
-			const binding = (schema) => async (rawArgs) => {
-				const { name } = schema;
-				if (runOver()) throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`);
-				const normalized = jsonNormalizeArgs(rawArgs);
-				const n = ++dispatches;
-				const subCallId = brandString(`${String(exec.callId)}:ptc:${n}`);
-				const input = {
-					callId: subCallId,
-					rootCallId: exec.rootCallId,
-					name,
-					schema,
-					arguments: normalized.dispatched,
-					...exec.agent ? { agent: exec.agent } : {},
-					parent: exec.token,
-					signal: runController.signal
+					})();
+					return driverRun;
 				};
-				const scheduler = registry[TOOL_RUNTIME_SCHEDULER];
-				const outcome = await new Promise((resolve, reject) => {
-					let parked;
-					const settle = (result) => {
-						resolve(result.isError ? {
-							isError: true,
-							message: result.error.message
-						} : {
-							isError: false,
-							value: result.value
-						});
-						const agent = exec.agent;
-						if (agent === void 0) return;
-						const task = (async () => {
-							const logged = await shapeDispatchLog({
-								exec,
-								agent,
-								subCallId,
-								name,
-								isError: result.isError,
-								content: result.content
-							});
-							agent.session.append("tool/ptc-dispatch", {
-								rootCallId: exec.rootCallId,
-								parentCallId: exec.callId,
-								subCallId,
-								name,
-								arguments: normalized.logged,
-								isError: result.isError,
-								...result.error?.info === void 0 ? {} : { error: result.error.info },
-								content: logged,
-								...result.meta === void 0 ? {} : { meta: result.meta }
-							});
-						})().finally(() => {
-							logWork.delete(task);
-						});
-						logWork.add(task);
+				/** Every dispatch settled AND committed; nothing can start (the run is aborted at call time). */
+				const drainDispatches = async () => {
+					await drive();
+					while (logWork.size > 0) await Promise.allSettled([...logWork]);
+				};
+				const runOver = () => runController.signal.aborted;
+				const binding = (schema) => async (rawArgs) => {
+					const { name } = schema;
+					if (runOver()) throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`);
+					const normalized = jsonNormalizeArgs(rawArgs);
+					const n = ++dispatches;
+					const subCallId = brandString(`${String(exec.callId)}:ptc:${n}`);
+					const input = {
+						callId: subCallId,
+						rootCallId: exec.rootCallId,
+						name,
+						schema,
+						arguments: normalized.dispatched,
+						...exec.agent ? { agent: exec.agent } : {},
+						parent: exec.token,
+						signal: runController.signal
 					};
-					pendingQueue.push({
-						flight: Promise.resolve(),
-						settled: false,
-						classify: () => registry.executionMode(input).kind,
-						abandon: () => {
-							reject(/* @__PURE__ */ new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} tool call abandoned`));
-						},
-						async start() {
-							exec.agent?.session.append("tool/ptc-dispatch-start", {
-								rootCallId: exec.rootCallId,
-								parentCallId: exec.callId,
-								subCallId,
-								name,
-								arguments: normalized.logged
+					const scheduler = registry[TOOL_RUNTIME_SCHEDULER];
+					const outcome = await new Promise((resolve, reject) => {
+						let parked;
+						const settle = (result) => {
+							resolve(result.isError ? {
+								isError: true,
+								message: result.error.message
+							} : {
+								isError: false,
+								value: result.value
+							});
+							const agent = exec.agent;
+							if (agent === void 0) return;
+							const task = (async () => {
+								const logged = await shapeDispatchLog({
+									exec,
+									agent,
+									subCallId,
+									name,
+									isError: result.isError,
+									content: result.content
+								});
+								agent.session.append("tool/ptc-dispatch", {
+									rootCallId: exec.rootCallId,
+									parentCallId: exec.callId,
+									subCallId,
+									name,
+									arguments: normalized.logged,
+									isError: result.isError,
+									...result.error?.info === void 0 ? {} : { error: result.error.info },
+									content: logged,
+									...result.meta === void 0 ? {} : { meta: result.meta }
+								});
+							})().finally(() => {
+								logWork.delete(task);
 							});
-							const prepared = await scheduler.prepare(input);
-							if (prepared.kind === "dispatch") {
-								this.flight = scheduler.dispatch(prepared.exec).then((dispatchOutcome) => {
-									parked = {
-										kind: dispatchOutcome.kind,
-										exec: prepared.exec,
-										result: dispatchOutcome.result
-									};
-									this.settled = true;
+							logWork.add(task);
+						};
+						pendingQueue.push({
+							flight: Promise.resolve(),
+							settled: false,
+							classify: () => registry.executionMode(input).kind,
+							abandon: () => {
+								reject(/* @__PURE__ */ new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} tool call abandoned`));
+							},
+							async start() {
+								exec.agent?.session.append("tool/ptc-dispatch-start", {
+									rootCallId: exec.rootCallId,
+									parentCallId: exec.callId,
+									subCallId,
+									name,
+									arguments: normalized.logged
 								});
-								return;
+								const prepared = await scheduler.prepare(input);
+								if (prepared.kind === "dispatch") {
+									this.flight = scheduler.dispatch(prepared.exec).then((dispatchOutcome) => {
+										parked = {
+											kind: dispatchOutcome.kind,
+											exec: prepared.exec,
+											result: dispatchOutcome.result
+										};
+										this.settled = true;
+									});
+									return;
+								}
+								parked = {
+									kind: prepared.kind,
+									exec: prepared.exec,
+									result: prepared.result
+								};
+								this.settled = true;
+							},
+							async commit() {
+								/* v8 ignore next -- commit() runs only after `settled` flipped, which set parked. */
+								if (parked === void 0) return;
+								const result = parked.kind === "post-result" ? await scheduler.finalize(parked.exec, parked.result) : scheduler.finish(parked.exec, parked.result);
+								if (!result.isError && result.content.some((block) => block.type === "image")) exec.deferContext(createUserMessage({
+									content: result.content,
+									source: { kind: "ptc-mode" }
+								}));
+								for (const context of result.additionalContexts ?? []) exec.deferContext(context);
+								if (result.concludesTurn) exec.concludeTurn();
+								settle(result);
+								while (logWork.size > maxParallel) await Promise.race(logWork);
 							}
-							parked = {
-								kind: prepared.kind,
-								exec: prepared.exec,
-								result: prepared.result
-							};
-							this.settled = true;
-						},
-						async commit() {
-							/* v8 ignore next -- commit() runs only after `settled` flipped, which set parked. */
-							if (parked === void 0) return;
-							const result = parked.kind === "post-result" ? await scheduler.finalize(parked.exec, parked.result) : scheduler.finish(parked.exec, parked.result);
-							if (!result.isError && result.content.some((block) => block.type === "image")) exec.deferContext(createUserMessage({
-								content: result.content,
-								source: { kind: "ptc-mode" }
-							}));
-							for (const context of result.additionalContexts ?? []) exec.deferContext(context);
-							if (result.concludesTurn) exec.concludeTurn();
-							settle(result);
-							while (logWork.size > maxParallel) await Promise.race(logWork);
-						}
+						});
+						wakeup();
+						drive();
 					});
-					wakeup();
-					drive();
-				});
-				if (runOver()) throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`);
-				if (outcome.isError) throw new Error(outcome.message);
-				return outcome.value;
-			};
-			const functions = Object.create(null);
-			for (const schema of registry.schemas(exec.agent)) {
-				if (schema.name === "run_code") continue;
-				Object.defineProperty(functions, schema.name, {
-					enumerable: true,
-					value: binding(deepFreeze(schema))
-				});
-			}
-			try {
-				let result;
+					if (runOver()) throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`);
+					if (outcome.isError) throw new Error(outcome.message);
+					return outcome.value;
+				};
+				const functions = Object.create(null);
+				for (const schema of registry.schemas(exec.agent)) {
+					if (schema.name === "run_code") continue;
+					Object.defineProperty(functions, schema.name, {
+						enumerable: true,
+						value: binding(deepFreeze(schema))
+					});
+				}
 				try {
-					result = await runtime.run(runtime.resolve({
-						program: args.code,
-						bindings: [{
-							global: "tools",
-							functions,
-							errorClass: {
-								name: "ToolCallError",
-								memberNameProperty: "toolName"
+					let result;
+					try {
+						if (exec.agent !== void 0) {
+							const agent = exec.agent;
+							let runtimes = stateOwners.get(agent);
+							if (runtimes === void 0) stateOwners.set(agent, runtimes = /* @__PURE__ */ new WeakSet());
+							let provider = runtime;
+							for (;;) {
+								const original = provider[symbols.original];
+								if (original === void 0) break;
+								provider = original;
 							}
-						}],
-						signal: runController.signal,
-						...cwd !== void 0 ? { cwd } : {},
-						...policy !== void 0 ? { sandboxPolicy: policy } : {},
-						...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {}
-					}));
+							if (!runtimes.has(provider)) {
+								agent.ctx.effect(() => () => runtime.release(agent), "PTC retained environment");
+								runtimes.add(provider);
+							}
+						}
+						result = await runtime.run(runtime.resolve({
+							program: args.code,
+							...exec.agent === void 0 || policy?.mode !== standingPolicy?.mode ? {} : { stateOwner: exec.agent },
+							bindings: [{
+								global: "tools",
+								functions,
+								errorClass: {
+									name: "ToolCallError",
+									memberNameProperty: "toolName"
+								}
+							}],
+							signal: runController.signal,
+							...cwd !== void 0 ? { cwd } : {},
+							...policy !== void 0 ? { sandboxPolicy: policy } : {},
+							...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {}
+						}));
+					} finally {
+						runController.abort("run_code settled");
+						await drainDispatches();
+					}
+					if (result.error) {
+						const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join("\n")}` : "";
+						const sandboxText = result.sandbox === void 0 ? "" : `\nFile sandbox: ${result.sandbox.mode}${result.sandbox.enforcement === void 0 ? "" : `; enforcement: ${result.sandbox.enforcement}`}${result.sandbox.denied ? "; operation denied" : ""}.`;
+						throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}${sandboxText}${result.sandbox?.denied ? escalationGuidance(runtime) : ""}`);
+					}
+					return {
+						logs: result.logs,
+						...result.sandbox === void 0 ? {} : { sandbox: result.sandbox },
+						...result.value !== void 0 ? { result: result.value } : {}
+					};
 				} finally {
-					runController.abort("run_code settled");
-					await drainDispatches();
-				}
-				if (result.error) {
-					const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join("\n")}` : "";
-					const sandboxText = result.sandbox === void 0 ? "" : `\nFile sandbox: ${result.sandbox.mode}${result.sandbox.enforcement === void 0 ? "" : `; enforcement: ${result.sandbox.enforcement}`}${result.sandbox.denied ? "; operation denied" : ""}.`;
-					throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}${sandboxText}${result.sandbox?.denied ? escalationGuidance(runtime) : ""}`);
+					callSignal.removeEventListener("abort", onOuterAbort);
 				}
-				return {
-					logs: result.logs,
-					...result.sandbox === void 0 ? {} : { sandbox: result.sandbox },
-					...result.value !== void 0 ? { result: result.value } : {}
-				};
-			} finally {
-				exec.signal.removeEventListener("abort", onOuterAbort);
-			}
+			};
+			return runtime.sandboxMode === void 0 || exec.agent === void 0 ? run(exec.signal) : calls.run(exec.agent.session.id, exec.signal, () => options.resolveSandboxPolicy(exec).mode, run);
 		},
 		presentCall: (args) => ({
 			card: "generic",
@@ -1685,24 +1771,29 @@ function jsonSchemaToTs(schema, indent = 0) {
 		return "unknown";
 	}
 }
-/** The fixed model-facing usage contract rendered above the declarations (see the PTC mode Agent Note's "What the model sees"). */
-const SDK_INSTRUCTIONS$1 = `## Writing code for run_code
+/** Render the argument and call instructions for the selected execution syntax. */
+function renderSdkInstructions(programFormat) {
+	return `## Writing code for run_code
 
-\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\` — the body of an async TypeScript function (erasable syntax only — no \`enum\` or namespaces; type annotations are advisory, the code runs type-stripped). The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly.`;
-const SDK_PROGRAM_INSTRUCTIONS = `Inside the program:
+\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\`, ${programFormat === "function-body" ? "the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped)" : "the program to execute"}. The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly.`;
+}
+/** Render tool execution and output instructions for the selected execution syntax. */
+function renderSdkProgramInstructions(programFormat) {
+	return `Inside the program:
 
 - Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
 - A FAILED tool call rejects with \`ToolCallError\`, whose \`toolName\` identifies the failed tool and whose \`message\` is human-readable — \`try/catch\` it to handle and continue.
 - Independent read-only calls MAY overlap under \`Promise.all\` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with \`await\`.
-- Emit results with \`return\` and/or \`console.log(...)\`. Only what you print or return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
+- ${programFormat === "function-body" ? "Emit results with `return` and/or `console.log(...)`. Only what you print or return is program output." : "Only values emitted as program output enter the conversation."} A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
 
 Program-only SDK bindings:`;
+}
 /** Whether one string schema accepts the literal used by the bash example. */
 function acceptsExampleString(schema, value) {
 	return schema?.type === "string" && (schema.const === void 0 || schema.const === value) && (schema.enum === void 0 || schema.enum.includes(value));
 }
 /** Render the bash example only when its literal arguments satisfy the current parameter schema. */
-function renderBashExample(schemas) {
+function renderBashExample(schemas, programFormat) {
 	const bash = schemas.find((schema) => schema.name === "bash");
 	if (bash === void 0) return "";
 	const parameters = bash.parameters;
@@ -1712,7 +1803,8 @@ function renderBashExample(schemas) {
 	if (!acceptsExampleString(parameters.properties?.command, "pwd")) return "";
 	const needsDescription = required.includes("description");
 	if (needsDescription && !acceptsExampleString(parameters.properties?.description, "Show current directory")) return "";
-	return ` When no separate \`bash\` schema is supplied, invoke a declared \`bash\` binding inside \`run_code\`:\n\n\`run_code({ description: "Show current directory", code: "return await tools.bash({ ${needsDescription ? "description: 'Show current directory', " : ""}command: 'pwd' })" })\``;
+	const description = needsDescription ? "description: 'Show current directory', " : "";
+	return ` When no separate \`bash\` schema is supplied, invoke a declared \`bash\` binding inside \`run_code\`:\n\n\`run_code({ description: "Show current directory", code: "${programFormat === "function-body" ? `return await tools.bash({ ${description}command: 'pwd' })` : `console.log(await tools.bash({ ${description}command: 'pwd' }))`}" })\``;
 }
 /**
 * Render the full `tools:sdk` prompt section: the fixed usage instructions
@@ -1724,9 +1816,10 @@ function renderBashExample(schemas) {
 * by name, so the input never carries a duplicate.
 * @param schemas - the tool schemas to declare (the caller excludes
 *   `run_code` itself).
+* @param programFormat - Runtime syntax; function bodies support returning a result, REPLs print it.
 * @returns the complete section text.
 */
-function renderToolsSdk(schemas) {
+function renderToolsSdk(schemas, programFormat = "function-body") {
 	const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 	const argsMembers = [];
 	const outputMembers = [];
@@ -1751,7 +1844,10 @@ function renderToolsSdk(schemas) {
 			"}"
 		].join("\n")
 	].join("\n\n");
-	return `${SDK_INSTRUCTIONS$1}${renderBashExample(sorted)}\n\n${SDK_PROGRAM_INSTRUCTIONS}\n\n\`\`\`ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\n${declaration}\n\`\`\``;
+	const jsonValue = "type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }";
+	const instructions = renderSdkInstructions(programFormat);
+	const programInstructions = renderSdkProgramInstructions(programFormat);
+	return `${instructions}${renderBashExample(sorted, programFormat)}\n\n${programInstructions}\n\n\`\`\`ts\n${jsonValue}\n\n${declaration}\n\`\`\``;
 }
 //#endregion
 //#region lib/types/py-types.js
@@ -1764,7 +1860,7 @@ function renderToolsSdk(schemas) {
 *
 * Under `mode: 'ptc'` the native tool schemas are omitted from the request, so this generated
 * SDK is the model's ONLY source for each tool's argument names, required fields, types,
-* descriptions, and canonical output shapes. Object-shaped arguments and outputs therefore render as one
+* descriptions, and canonical output types. Object-shaped arguments and outputs render as one
 * named `TypedDict` per tool (and per nested object), not an opaque `dict[str, Any]`, so the
 * shape survives into the program under the mode that has nothing else to carry it.
 * @module @qilin-agent/tools/src/py-types
@@ -2402,12 +2498,12 @@ function jsonSchemaToPy(schema) {
 /** The fixed model-facing usage contract rendered above the declarations. */
 const SDK_INSTRUCTIONS = `## Writing code for run_code
 
-\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\` — the body of an async Python function (top-level \`await\` and \`return\` both work). At run time exactly two of the names declared below are bound: \`tools\` and \`ToolCallError\`. Everything else is a STATIC STUB describing argument and return types — in particular the \`TypedDict\` classes do NOT exist at run time, so build arguments as plain \`dict\`/\`list\` JSON values: \`await tools.name({"field": 1})\`, never \`FooArgs(field=1)\`, which raises \`NameError\`. Inside the program:
+\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\`, the program to execute. At run time exactly two of the names declared below are bound: \`tools\` and \`ToolCallError\`. Everything else is a STATIC STUB describing argument and return types — in particular the \`TypedDict\` classes do NOT exist at run time, so build arguments as plain \`dict\`/\`list\` JSON values: \`await tools.name({"field": 1})\`, never \`FooArgs(field=1)\`, which raises \`NameError\`. Inside the program:
 
 - Call tools as \`await tools.name(args)\` — subscript access for exotic, reserved, or underscore-leading names: \`await tools["my-tool"](args)\`. Every call resolves to the tool's typed canonical JSON value (each method's return type below). Tool arguments must be lossless JSON.
 - A FAILED tool call raises \`ToolCallError\`, whose \`toolName\` identifies the failed tool and whose message is human-readable — wrap in \`try/except\` to handle and continue.
 - Independent read-only calls MAY overlap under \`asyncio.gather\` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with \`await\`.
-- Emit the run's answer with \`print(...)\` and/or a top-level \`return <value>\`; the returned value must be lossless JSON. Only what you print and return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
+- Only values emitted as program output enter the conversation. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
 
 The available tools:`;
 /**
@@ -2694,11 +2790,13 @@ var ToolRuntime = class extends Service {
 	* Reserved presentation transport, kept outside the filterable registration
 	* layers. Built on first need rather than at construction: which agents run
 	* a PTC mode is no longer known when the service is constructed, and the
-	* transport is stateless beyond its closures over `this`.
+	* transport owns its PTC call tracking and state-owner registrations.
 	*/
 	ptcTransport;
+	ptcContext;
 	constructor(ctx, config = {}) {
 		super(ctx, "tools");
+		this.ptcContext = ctx;
 		this.defaultMode = config.mode ?? "native";
 		this.maxParallelSubCalls = resolveMaxParallelSubCalls(config.maxParallelSubCalls);
 		ctx.systemPrompt.tools((context) => this.wireSchemas(context.scope));
@@ -2751,7 +2849,7 @@ var ToolRuntime = class extends Service {
 				const render = SDK_RENDERERS[runtime.language];
 				/* v8 ignore next -- requirePtcRuntime rejects an unknown language before this runs. */
 				if (render === void 0) throw new Error(`qilin-tools: no SDK renderer for ${runtime.language}`);
-				return render(this.sdkSchemas(context.scope));
+				return render(this.sdkSchemas(context.scope), runtime.programFormat);
 			}
 		};
 	}
@@ -2796,7 +2894,7 @@ var ToolRuntime = class extends Service {
 			peekRuntime: () => this.ctx.get("ptcRuntime"),
 			maxParallel: this.maxParallelSubCalls,
 			shapeDispatchLog: (dispatch) => this.shapeDispatchLog(dispatch)
-		});
+		}, this.ptcContext);
 		return this.ptcTransport;
 	}
 	/**