llmz 1.0.1 → 1.0.2

package/dist/index.workerd.js

@@ -49,7 +49,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 //#region package.json
-var version = "1.0.1";
+var version = "1.0.2";
 //#endregion
 //#region src/errors/catalog.ts
 function validationMessage(subject, issues, expectedInput) {
@@ -68,7 +68,7 @@ function isLLMzError(error, code) {
 function isCriticalError(error) {
 	return isLLMzError(error) && error.critical;
 }
-var ERROR_BRAND, LLMzError, CodeExecutionError, InvalidCodeError, CodeFormattingError, ToolInputError, ExitInputError, ObjectPropertyError, ComponentInputError, UnknownToolError, UnknownComponentError, UnknownExitError, ReservedIdentifierError, ToolExecutionError, LoopExceededError, TokenOverflowError, MemoryCapacityError, AssignmentError, CognitiveError, CompactionError, InvalidToolError, InvalidObjectError, InvalidExitError, InvalidComponentError, InvalidConfigurationError, InvalidMessageError, InvalidEventError, InvalidSessionError, SessionStateError, MemoryValueError, NativeProtocolError, HostOperationError, DeliveryError, HookError, ExecutionAbortedError, InternalError, errorClasses$1, ERROR_CODES;
+var ERROR_BRAND, LLMzError, CodeExecutionError, InvalidCodeError, CodeFormattingError, ToolInputError, ExitInputError, ObjectPropertyError, ComponentInputError, UnknownToolError, UnknownComponentError, UnknownExitError, ReservedIdentifierError, ToolExecutionError, LoopExceededError, TokenOverflowError, MemoryCapacityError, AssignmentError, CognitiveError, CompactionError, InvalidToolError, InvalidObjectError, InvalidExitError, InvalidComponentError, InvalidConfigurationError, InvalidMessageError, InvalidEventError, InvalidSessionError, SessionStateError, MemoryValueError, NativeProtocolError, HostOperationError, MissingChatResponseError, DeliveryError, HookError, ExecutionAbortedError, InternalError, errorClasses$1, ERROR_CODES;
 var init_catalog = __esmMin((() => {
 	ERROR_BRAND = Symbol.for("llmz.error.v1");
 	LLMzError = class extends Error {
@@ -358,6 +358,13 @@ var init_catalog = __esmMin((() => {
 			super(message, false, options);
 		}
 	};
+	MissingChatResponseError = class extends LLMzError {
+		static is = (value) => isLLMzError(value, "MISSING_CHAT_RESPONSE");
+		code = "MISSING_CHAT_RESPONSE";
+		constructor(message, options) {
+			super(message, false, options);
+		}
+	};
 	DeliveryError = class extends LLMzError {
 		static is = (value) => isLLMzError(value, "DELIVERY_FAILED");
 		code = "DELIVERY_FAILED";
@@ -418,6 +425,7 @@ var init_catalog = __esmMin((() => {
 		NativeProtocolError,
 		HostOperationError,
 		DeliveryError,
+		MissingChatResponseError,
 		HookError,
 		ExecutionAbortedError,
 		InternalError
@@ -454,6 +462,7 @@ var init_catalog = __esmMin((() => {
 		"INVALID_NATIVE_CALL",
 		"HOST_OPERATION_FAILED",
 		"DELIVERY_FAILED",
+		"MISSING_CHAT_RESPONSE",
 		"HOOK_FAILED",
 		"EXECUTION_ABORTED",
 		"INTERNAL_ERROR"
@@ -6175,7 +6184,7 @@ function createInspector(onInspect) {
 		if (onInspect) try {
 			const budget = resolveInspectionBudget(value, formatting);
 			const output = onInspect(Object.freeze({
-				value: snapshot(value),
+				value: snapshotInspectionValue(value),
 				purpose: options.purpose,
 				maxTokens: budget.tokens,
 				preserve: budget.preserve,
@@ -6187,12 +6196,13 @@ function createInspector(onInspect) {
 		return inspect(value, void 0, formatting);
 	};
 }
-function snapshot(value, copies = /* @__PURE__ */ new WeakMap()) {
+/** Isolate evidence from subsequent guest mutations without invoking getters. */
+function snapshotInspectionValue(value, copies = /* @__PURE__ */ new WeakMap()) {
 	if (!value || typeof value !== "object") return typeof value === "function" ? "[Function]" : value;
 	if (copies.has(value)) return copies.get(value);
 	if (isTruncated(value)) {
 		copies.set(value, "[Circular]");
-		const copy = snapshot(value.value, copies);
+		const copy = snapshotInspectionValue(value.value, copies);
 		copies.set(value, copy);
 		return copy;
 	}
@@ -6203,7 +6213,7 @@ function snapshot(value, copies = /* @__PURE__ */ new WeakMap()) {
 		if (Array.isArray(value) && key === "length") continue;
 		const descriptor = Object.getOwnPropertyDescriptor(value, key);
 		if (descriptor) Object.defineProperty(copy, key, {
-			value: "value" in descriptor ? snapshot(descriptor.value, copies) : "[Getter]",
+			value: "value" in descriptor ? snapshotInspectionValue(descriptor.value, copies) : "[Getter]",
 			enumerable: descriptor.enumerable
 		});
 	}
@@ -8464,6 +8474,10 @@ function normalizeMessage(message) {
 	validateInputMessage(normalized);
 	return normalized;
 }
+/** Only actual participant content counts as speech, including image/audio-only messages. */
+function inputSpeaker(message) {
+	return (Array.isArray(message.content) ? message.content.some((part) => part.type !== "text" || Boolean(part.text?.trim())) : Boolean(message.content?.trim())) && (message.role === "user" || message.role === "assistant") ? message.role : null;
+}
 function createAssistantMessage(response) {
 	if (response.assistantMessage) return asSessionMessage(response.assistantMessage);
 	const message = {
@@ -8635,6 +8649,7 @@ function validateRestoredHistory(state) {
 	if (!Array.isArray(state.groups) || !Array.isArray(state.pendingInputs)) throw new InvalidSessionError("Session history and queued inputs must be arrays.");
 	if (!Number.isSafeInteger(state.turn) || state.turn < 0 || !Number.isSafeInteger(state.iteration) || state.iteration < 0) throw new InvalidSessionError("Session turn and iteration counters must be non-negative safe integers");
 	if (typeof state.activeTurn !== "boolean" || state.activeTurn && (!state.turn || !state.turnId)) throw new InvalidSessionError("Session processing state must identify an active turn.");
+	if (state.lastSpeaker !== void 0 && state.lastSpeaker !== null && !["user", "assistant"].includes(state.lastSpeaker)) throw new InvalidSessionError("Session last speaker must be user, assistant, or null.");
 	const groupIds = /* @__PURE__ */ new Set();
 	const callIds = /* @__PURE__ */ new Set();
 	let previousIteration = 0;
@@ -8749,6 +8764,7 @@ var init_session = __esmMin((() => {
 		#pendingInputs = [];
 		#activeTurn = false;
 		#locked = false;
+		#lastSpeaker = null;
 		constructor(options = {}) {
 			this.id = `session_${ulid()}`;
 			this.memory = new Memory({
@@ -8773,6 +8789,15 @@ var init_session = __esmMin((() => {
 		get transcript() {
 			return structuredClone([...this.#allGroups().flatMap((group) => group.source ? [group.source] : group.messages), ...this.#pendingInputs.map((input) => input.source ?? input.message)]);
 		}
+		/** Last participant who spoke in the active history. Events and queued inputs do not count. */
+		get lastSpeaker() {
+			return this.#lastSpeaker;
+		}
+		/** Record acknowledged text or component delivery, never generation alone. */
+		recordAssistantDelivery(iterationId) {
+			this.#getActiveIteration(iterationId);
+			this.#lastSpeaker = "assistant";
+		}
 		get pendingMessages() {
 			return structuredClone(this.#pendingInputs.map((input) => input.message));
 		}
@@ -8861,12 +8886,15 @@ var init_session = __esmMin((() => {
 			this.#turn++;
 			this.#turnId = `turn_${ulid()}`;
 			this.#activeTurn = true;
-			for (const input of this.#pendingInputs) this.#groups.push({
-				id: input.id,
-				turn: this.#turn,
-				messages: [input.message],
-				...input.source ? { source: input.source } : {}
-			});
+			for (const input of this.#pendingInputs) {
+				if (!input.source) this.#lastSpeaker = inputSpeaker(input.message) ?? this.#lastSpeaker;
+				this.#groups.push({
+					id: input.id,
+					turn: this.#turn,
+					messages: [input.message],
+					...input.source ? { source: input.source } : {}
+				});
+			}
 			this.#pendingInputs = [];
 		}
 		/** Mark the active input batch complete without consuming newly queued input. */
@@ -9167,6 +9195,7 @@ var init_session = __esmMin((() => {
 				groups: this.#groups.map(serializeGroup),
 				memory: this.memory.serialize(),
 				pendingInputs: structuredClone(this.#pendingInputs),
+				lastSpeaker: this.#lastSpeaker,
 				activeTurn: this.#activeTurn,
 				latestResultId: this.#latestResultId,
 				compaction
@@ -9185,6 +9214,7 @@ var init_session = __esmMin((() => {
 			session.#groups = state.groups.map(restoreGroup);
 			session.#pendingInputs = structuredClone(state.pendingInputs);
 			session.#activeTurn = state.activeTurn;
+			session.#lastSpeaker = state.lastSpeaker ?? null;
 			session.#latestResultId = state.latestResultId;
 			Object.defineProperty(session, "memory", {
 				value: Memory.restore(state.memory, () => session.#resultBytes()),
@@ -9703,7 +9733,7 @@ function runtimeRules(props, chat) {
 	}
 	rules.push("Execution may overlap the remaining response stream. The runtime waits for the stream, code, and queued message deliveries before the next response.", "# Memory", "Declare retained variables at top level with const or let. Bare assignment only updates a variable already declared in this program or listed in Memory. Named variables survive transcript compaction; assignment age records when they were set, not when the underlying data was fetched.", "Object properties are immutable snapshots. Replace a writable property completely, such as account.profile = { ...account.profile, age: 42 }; nested edits are forbidden and replacements are schema-validated.", "$return is the latest successful inspection result. $iterations is read-only retained history, newest first: [0] is the last settled iteration and [1] the preceding one. The current execution is not included. Entries without results still occupy indexes; check hasResult. Compaction prunes automatic results. Assign useful data to named variables to retain it independently.", "# Recovery", "Execution reports identify completed actions, inspected values, memory changes, and errors. Reuse preserved variables and completed actions; retry only failed work. Build completion payloads from those values, not by calling successful tools again. An inspection has already run the recorded calls; it is not a dry run.", "An operational error does not by itself finish the task. Inspect the actual error, repair its cause when safe and authorized, then retry. Unchanged retries do not establish that recovery is exhausted. If another response must diagnose the error, return inspect({ errors, completed }) or let the error reach the runtime. Honor task instructions defining terminal failure outcomes.");
 	if (hasExits) rules.push("Use a failure exit only when recovery is unavailable, unsafe, forbidden, its budget is exhausted, or task instructions make the failure terminal. Do not select failure in advance for an unseen error. Do not turn an unexpected exception or rejected Promise.allSettled entry directly into failure completion: first expose it with inspect or let it reach the runtime, then diagnose the actual cause and available recovery tools. Explicit task instructions may define an error as terminal.");
-	rules.push("A thinking interruption stops the current program and requests another model response. Statements after the interruption have not run; continue with a new program without repeating completed actions.", "Respect tool-attempt limits separately from the model-response budget. An empty successful inspection result is not a failure.");
+	rules.push("A tool may request forced inspection through ThinkSignal. The tool succeeded and its context is returned to JavaScript. Other calls and assignments continue normally. At the end of the program, forced inspection takes precedence over completion: review the reported results as an inspect() call, then continue from retained values without repeating successful calls.", "Respect tool-attempt limits separately from the model-response budget. An empty successful inspection result is not a failure.");
 	return rules.join("\n\n");
 }
 async function describeRuntimeAPI(props, chat) {
@@ -13901,10 +13931,11 @@ var init_errors = __esmMin((() => {
 }));
 //#endregion
 //#region src/vm/types.ts
-var VM_PROGRAM_COMPLETE, VM_TERMINATION, VM_ON_ERROR;
+var VM_PROGRAM_COMPLETE, VM_TERMINATION, VM_CALL_SITE, VM_ON_ERROR;
 var init_types = __esmMin((() => {
 	VM_PROGRAM_COMPLETE = Symbol("llmz.programComplete");
 	VM_TERMINATION = Symbol("llmz.termination");
+	VM_CALL_SITE = Symbol("llmz.callSite");
 	VM_ON_ERROR = Symbol("llmz.onError");
 }));
 //#endregion
@@ -14043,6 +14074,15 @@ var init_node = __esmMin((() => {
 		async execute(ctx) {
 			const { transformed, consumer, context, traces, recordTrace, code, lines_executed, variables } = ctx;
 			const state = instrumentContext(context, transformed, recordTrace, variables, lines_executed, consumer, findUserCodeStartLine(transformed), ctx.memoryNames);
+			context[VM_CALL_SITE] = () => {
+				const frame = (/* @__PURE__ */ new Error()).stack?.match(/<anonymous>:(\d+):(\d+)/);
+				if (!frame) return;
+				const position = consumer.originalPositionFor({
+					line: Number(frame[1]) - 1,
+					column: Number(frame[2])
+				});
+				return position.line ? Math.max(1, position.line - 3) : void 0;
+			};
 			const AsyncFunction = async function() {}.constructor;
 			return finalizeMemoryCapture(await (async () => {
 				const descriptors = Object.getOwnPropertyDescriptors(context);
@@ -14497,6 +14537,19 @@ var init_quickjs = __esmMin((() => {
 			const disposeIfNeeded = (handle) => {
 				if (handle !== vm.true && handle !== vm.false && handle !== vm.null && handle !== vm.undefined) handle.dispose();
 			};
+			context[VM_CALL_SITE] = () => {
+				const stack = vm.evalCode("new Error().stack");
+				if ("error" in stack) {
+					stack.error?.dispose();
+					return;
+				}
+				try {
+					const frame = vm.getString(stack.value).match(/<quickjs>:(\d+)/);
+					return frame ? Math.max(1, Number(frame[1]) - 9 - userCodeStartLine + 1) : void 0;
+				} finally {
+					stack.value.dispose();
+				}
+			};
 			const bridgeFunction = (fn, _fnName = "anonymous") => {
 				return (...argHandles) => {
 					const args = argHandles.map((h) => vm.dump(h));
@@ -14991,10 +15044,7 @@ var init_execution_activity = __esmMin((() => {
 //#region src/runtime/execution-diagnostics.ts
 /** XML-style boundaries keep diagnostic text separate from recovery instructions. */
 function reportSection(name, content, maxTokens = 2e3, options = {}) {
-	const escape = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;");
-	const heading = options.heading ? `${escape(options.heading)}\n` : "";
-	const body = limitInspectionOutput(content, maxTokens, false, options.preserve ?? "top");
-	return `<${name}>\n${heading}${/[<&]|\]\]>/.test(body) ? `<![CDATA[\n${body.replaceAll("]]>", "]]]]><![CDATA[>")}\n]]>` : body}\n</${name}>`;
+	return `<${name}>\n${options.heading ? `${options.heading}\n` : ""}${limitInspectionOutput(content, maxTokens, false, options.preserve ?? "top")}\n</${name}>`;
 }
 /** Show the specific failure and guest source, never the host's implementation stack. */
 function renderExecutionDiagnostics(error, message, inspector, identity) {
@@ -15039,6 +15089,56 @@ var init_execution_diagnostics = __esmMin((() => {
 	init_inspect();
 }));
 //#endregion
+//#region src/runtime/forced-inspection.ts
+/** Keep attribution and content together, using the same display budgets as inspect(). */
+function renderForcedInspection(inspections, inspector, identity, maxTokens, policies) {
+	return [
+		"<forced_inspection>",
+		"Forced inspection: the tools listed below completed successfully and requested review of their results.",
+		"This is the equivalent of an inspect() call. Do not repeat these tool calls; use the results below and retained variables.",
+		"No exit was applied. Review the evidence before continuing or completing the task.",
+		"",
+		"Tools requesting inspection (lines refer to the executed JavaScript):",
+		...inspections.map((entry) => {
+			const entryIdentity = {
+				...identity,
+				tool: entry.tool
+			};
+			const name = inspector(entry.tool, {
+				purpose: "name",
+				maxTokens: 80,
+				identity: entryIdentity
+			});
+			const reason = inspector(entry.reason, {
+				purpose: "error",
+				maxTokens: 1e3,
+				identity: entryIdentity
+			});
+			const budget = resolveInspectionBudget(entry.value, {
+				tokens: maxTokens,
+				policies
+			});
+			const result = inspector(entry.value, {
+				purpose: "result",
+				maxTokens,
+				policies,
+				identity: entryIdentity
+			});
+			return [
+				`<tool name="${name}" line="${entry.line ?? "unknown"}">`,
+				`<reason>${reason}</reason>`,
+				reportSection("result", result, budget.tokens, { preserve: budget.preserve }),
+				"</tool>"
+			].join("\n");
+		}),
+		"</forced_inspection>"
+	].join("\n");
+}
+var init_forced_inspection = __esmMin((() => {
+	init_inspect();
+	init_execution_diagnostics();
+}));
+//#endregion
 //#region src/runtime/execution-report.ts
 /** Format one settled outcome; execution is responsible for deciding what happened. */
 function renderExecutionReport({ outcome, activity, memory, source, requiresExit = false, iteration, identity = { iteration }, inspector = createInspector(), maxTokens = DEFAULT_TOOL_RESULT_MAX_TOKENS, policies }) {
@@ -15068,6 +15168,13 @@ function renderExecutionReport({ outcome, activity, memory, source, requiresExit
 		});
 	};
 	const sections = [renderStatus(outcome, memory)];
+	if (outcome.type === "inspect" && outcome.forcedInspections?.length) {
+		sections.push(renderForcedInspection(outcome.forcedInspections, inspector, identity, maxTokens, policies));
+		if (outcome.downstreamError) {
+			sections.push(...renderExecutionDiagnostics(outcome.downstreamError, getErrorMessage(outcome.downstreamError), inspector, identity));
+			sections.push(reportSection("recovery", "A later operation failed. The tool results above were successfully retrieved; inspect them and repair only the failed work. Do not repeat successful calls."));
+		}
+	}
 	if (outcome.type === "error") {
 		sections.push(...renderExecutionDiagnostics(outcome.error, outcome.message, inspector, identity));
 		sections.push(reportSection("recovery", [
@@ -15100,7 +15207,7 @@ function renderExecutionReport({ outcome, activity, memory, source, requiresExit
 		if (memory.unavailable.length > failures.length) entries.push(`- ${memory.unavailable.length - failures.length} additional values could not be retained.`);
 		sections.push(reportSection("memory_errors", `Memory errors\n${entries.join("\n")}`));
 	}
-	if (outcome.type === "inspect") {
+	if (outcome.type === "inspect" && outcome.forcedInspections?.length && (!outcome.explicit || outcome.forcedInspections.some((entry) => isEqual(entry.value, outcome.value)))) {} else if (outcome.type === "inspect") {
 		const heading = outcome.explicit ? "inspect() result" : "Result";
 		sections.push(outcome.available ? resultSection("result", heading, outcome.value) : reportSection("result", "Unavailable; see memory errors above.", maxTokens, { heading }));
 	} else if (outcome.type === "exit") sections.push(resultSection("completion", `Completion\nExit "${outcome.name}" completed.`, outcome.value === void 0 ? "" : outcome.value));
@@ -15149,12 +15256,15 @@ function renderChanges(label, changes, name) {
 }
 var MAX_REPORTED_CHANGES, MAX_OVERRIDE_SOURCE_LENGTH;
 var init_execution_report = __esmMin((() => {
+	init_lodash();
 	init_errors$1();
 	init_inspect();
 	init_inspection();
 	init_truncate();
+	init_utils$1();
 	init_execution_activity();
 	init_execution_diagnostics();
+	init_forced_inspection();
 	MAX_REPORTED_CHANGES = 40;
 	MAX_OVERRIDE_SOURCE_LENGTH = 3e3;
 }));
@@ -15650,6 +15760,7 @@ var init_inspection_values = __esmMin((() => {
 function createJavaScriptApi({ iteration, components, exits, deliver, signal, onError }) {
 	const decisions = /* @__PURE__ */ new Map();
 	const pending = /* @__PURE__ */ new Set();
+	const inspections = [];
 	let open = true;
 	let outstanding = [];
 	let delivery;
@@ -15785,6 +15896,10 @@ function createJavaScriptApi({ iteration, components, exits, deliver, signal, on
 		isReceipt: (value) => resolve(value) !== void 0,
 		getTerminalOutcome: () => terminalOutcome,
 		getInterruption: () => interruption,
+		requestInspection: (inspection) => {
+			inspections.push(inspection);
+		},
+		getForcedInspections: () => inspections,
 		throwIfTerminated,
 		track,
 		assertOpen,
@@ -15824,8 +15939,8 @@ var init_utils = __esmMin((() => {
 }));
 //#endregion
 //#region src/runtime/tool-wrapper.ts
-function wrapTool({ tool, object, iteration, beforeHook, afterHook, onTruncation, onResult, controller }) {
-	return async function(input) {
+function wrapTool({ tool, object, iteration, beforeHook, afterHook, onTruncation, onResult, controller, onThink }) {
+	return async function(input, line) {
 		controller.signal.throwIfAborted();
 		const toolCallId = `tcall_${ulid()}`;
 		const originalInput = input;
@@ -15844,7 +15959,7 @@ function wrapTool({ tool, object, iteration, beforeHook, afterHook, onTruncation
 		let output;
 		let error;
 		let success = true;
-		let signalToThrow;
+		const inspections = [];
 		const pushToolCallTrace = () => {
 			iteration.recordTrace({
 				type: "tool_call",
@@ -15860,32 +15975,21 @@ function wrapTool({ tool, object, iteration, beforeHook, afterHook, onTruncation
 				success
 			});
 		};
-		const handleSignals = async (err) => {
-			if (output === err) return true;
-			if (ThinkSignal.is(err)) {
-				signalToThrow = err;
-				iteration.recordTrace({
-					type: "think_signal",
-					started_at: Date.now(),
-					line: 0,
-					ended_at: Date.now()
-				});
-				success = true;
-				output = err;
-				const afterRes = await callHook(() => afterHook?.({
-					iteration,
-					tool,
-					input: originalInput,
-					output,
-					controller,
-					object,
-					toolCallId,
-					nativeCallId: iteration.nativeCallId
-				}));
-				if (typeof afterRes?.output !== "undefined") output = afterRes.output;
-				return true;
-			}
-			return false;
+		const unwrapSignal = (value) => {
+			if (!ThinkSignal.is(value)) return value;
+			const context = value.context;
+			const output = unwrapTruncated(context);
+			if (isTruncated(context)) onTruncation?.(output, context.$$truncate);
+			const inspection = {
+				tool: object ? `${object}.${tool.name}` : tool.name,
+				toolCallId,
+				line,
+				reason: value.reason,
+				value: output,
+				metadata: value.metadata
+			};
+			inspections.push(inspection);
+			return output;
 		};
 		try {
 			const beforeRes = await callHook(() => beforeHook?.({
@@ -15897,18 +16001,25 @@ function wrapTool({ tool, object, iteration, beforeHook, afterHook, onTruncation
 				toolCallId,
 				nativeCallId: iteration.nativeCallId
 			}));
+			if (ThinkSignal.is(beforeRes)) throw new HookError("Tool hooks cannot request inspection with ThinkSignal. Return it from the tool handler instead.");
 			if (typeof beforeRes?.input !== "undefined") effectiveInput = beforeRes.input;
 			controller.signal.throwIfAborted();
-			output = await tool.execute(effectiveInput, {
-				callId: toolCallId,
-				iterationId: iteration.id,
-				nativeCallId: iteration.nativeCallId,
-				onTruncation,
-				onInput: (parsed) => {
-					controller.signal.throwIfAborted();
-					if (effectiveInput === originalInput) reportedInput = parsed;
-				}
-			});
+			try {
+				output = await tool.execute(effectiveInput, {
+					callId: toolCallId,
+					iterationId: iteration.id,
+					nativeCallId: iteration.nativeCallId,
+					onTruncation,
+					onInput: (parsed) => {
+						controller.signal.throwIfAborted();
+						if (effectiveInput === originalInput) reportedInput = parsed;
+					}
+				});
+			} catch (error) {
+				if (!ThinkSignal.is(error)) throw error;
+				output = error;
+			}
+			output = unwrapSignal(output);
 			const afterRes = await callHook(() => afterHook?.({
 				iteration,
 				tool,
@@ -15919,19 +16030,39 @@ function wrapTool({ tool, object, iteration, beforeHook, afterHook, onTruncation
 				toolCallId,
 				nativeCallId: iteration.nativeCallId
 			}));
+			if (ThinkSignal.is(afterRes) || ThinkSignal.is(afterRes?.output)) throw new HookError("Tool hooks cannot request inspection with ThinkSignal. Return it from the tool handler instead.");
 			if (typeof afterRes?.output !== "undefined") output = afterRes.output;
+			controller.signal.throwIfAborted();
 		} catch (err) {
-			if (!await handleSignals(err)) {
-				success = false;
-				error = isLLMzError(err) ? err : new ToolExecutionError(tool.name, err);
-				iteration.recordError(error);
-			}
+			success = false;
+			output = void 0;
+			if (ThinkSignal.is(err)) error = new HookError("Tool hooks cannot request inspection with ThinkSignal. Return it from the tool handler instead.");
+			else error = isLLMzError(err) ? err : new ToolExecutionError(tool.name, err);
+			iteration.recordError(error);
 		} finally {
 			clearTimeout(alertSlowTool);
+			for (const inspection of success ? inspections : []) {
+				const value = snapshotInspectionValue(output);
+				onThink?.({
+					...inspection,
+					value
+				});
+				iteration.recordTrace({
+					type: "think_signal",
+					started_at: Date.now(),
+					ended_at: Date.now(),
+					line: line ?? 0,
+					tool_name: tool.name,
+					tool_call_id: toolCallId,
+					object,
+					reason: inspection.reason,
+					context: value,
+					metadata: inspection.metadata
+				});
+			}
 			pushToolCallTrace();
 		}
 		if (!success) throw error;
-		if (signalToThrow) throw signalToThrow;
 		onResult?.(output);
 		return output;
 	};
@@ -15940,6 +16071,8 @@ var SLOW_TOOL_WARNING;
 var init_tool_wrapper = __esmMin((() => {
 	init_hooks();
 	init_errors$1();
+	init_inspection();
+	init_truncate();
 	SLOW_TOOL_WARNING = ms("15s");
 }));
 //#endregion
@@ -16046,9 +16179,13 @@ var init_vm_context = __esmMin((() => {
 					afterHook: onAfterTool,
 					onTruncation,
 					onResult: onToolResult,
-					controller
+					controller,
+					onThink: javascriptApi?.requestInspection
 				});
-				instance[tool.name] = javascriptApi ? (input) => javascriptApi.track(() => wrapped(input)) : wrapped;
+				instance[tool.name] = javascriptApi ? (input) => {
+					const line = vmContext[VM_CALL_SITE]?.();
+					return javascriptApi.track(() => wrapped(input, line));
+				} : wrapped;
 			}
 			vmContext[obj.name] = withMissingMember(instance, (name) => {
 				const error = new UnknownToolError(`${obj.name}.${name}`, (obj.tools ?? []).map((tool) => `${obj.name}.${tool.name}`));
@@ -16064,9 +16201,13 @@ var init_vm_context = __esmMin((() => {
 				afterHook: onAfterTool,
 				onTruncation,
 				onResult: onToolResult,
-				controller
+				controller,
+				onThink: javascriptApi?.requestInspection
 			});
-			const callable = javascriptApi ? (input) => javascriptApi.track(() => wrapped(input)) : wrapped;
+			const callable = javascriptApi ? (input) => {
+				const line = vmContext[VM_CALL_SITE]?.();
+				return javascriptApi.track(() => wrapped(input, line));
+			} : wrapped;
 			for (const key of [tool.name, ...tool.aliases ?? []]) vmContext[key] = callable;
 		}
 		return vmContext;
@@ -16100,6 +16241,7 @@ async function executeContextInternal(props) {
 	try {
 		if ("snapshot" in props) throw new InvalidConfigurationError("Snapshots and external pause/resume are no longer supported. Use a session for conversation history and memory.");
 		if ("messages" in props) throw new InvalidConfigurationError("Append input with session.append(message) before calling execute(). execute.messages is no longer supported.");
+		if (props.options?.requireChatResponse !== void 0 && typeof props.options.requireChatResponse !== "boolean") throw new InvalidConfigurationError("Invalid requireChatResponse. Expected a boolean.");
 		release = ctx.session.acquire();
 		prepareSession(ctx);
 		const client = props.client ?? new Client();
@@ -16270,18 +16412,19 @@ async function rejectNativeBatch({ ctx, iteration }, generated, errors) {
 }
 async function deliverAssistantText(state, generated) {
 	const { ctx, iteration } = state;
-	if (!generated.output.trim() || !ctx.chat) return;
+	if (!generated.output.trim() || !ctx.chat || !iteration.response?.handler) return;
 	const startedAt = Date.now();
 	const message = {
 		type: "text",
 		text: generated.output
 	};
 	try {
-		await iteration.response?.handler?.(generated.output.trim(), generated.messageMetadata);
+		await iteration.response.handler(generated.output.trim(), generated.messageMetadata);
 	} catch (cause) {
 		if (isCriticalError(cause)) throw cause;
 		throw new DeliveryError(`Assistant response delivery failed: ${getErrorMessage(cause)}`, { cause });
 	}
+	ctx.session.recordAssistantDelivery(iteration.id);
 	iteration.recordTrace({
 		type: "message_delivery",
 		value: message,
@@ -16319,6 +16462,31 @@ async function settleJavaScriptCall(state, execution) {
 		inspected: outcome?.type === "inspect"
 	};
 	if (outcome?.type === "inspect" && result.success) result.return_value = outcome.value;
+	const forcedInspections = api.getForcedInspections();
+	if (forcedInspections.length && !controller.signal.aborted && !isCriticalError(result.error)) {
+		if (!result.success && result.error) {
+			iteration.recordError(result.error);
+			state.capture.downstreamError = result.error;
+		}
+		state.capture.forcedInspections = forcedInspections;
+		let value = forcedInspections.length === 1 ? forcedInspections[0].value : forcedInspections.map((entry) => entry.value);
+		if (outcome?.type === "inspect") value = outcome.value;
+		state.capture.result = {
+			...result,
+			success: true,
+			signal: void 0,
+			return_value: value
+		};
+		iteration.end({
+			type: "thinking_requested",
+			thinking_requested: {
+				reason: "Tools completed successfully and requested forced inspection.",
+				variables: value,
+				metadata: forcedInspections.length === 1 ? forcedInspections[0].metadata : void 0
+			}
+		});
+		return;
+	}
 	if (outcome?.type === "exit") {
 		await completeJavaScriptExit(state, result, outcome);
 		return;
@@ -16378,11 +16546,11 @@ function containsDecision(value, api, seen = /* @__PURE__ */ new Set()) {
 	return Object.values(value).some((nested) => containsDecision(nested, api, seen));
 }
 async function completeJavaScriptExit(state, result, outcome) {
-	const { iteration, controller, props } = state;
+	const { iteration, controller } = state;
 	state.memory = commitMemory(state, result, false);
 	try {
 		controller.signal.throwIfAborted();
-		await applyNativeExit(iteration, outcome.exit, outcome.value, controller, props.onExit);
+		await applyNativeExit(state, outcome.exit, outcome.value);
 	} catch (error) {
 		endFailedIteration(iteration, controller, error);
 	}
@@ -16414,6 +16582,7 @@ async function deliverJavaScriptMessages({ ctx, iteration, controller }, message
 			});
 			throw isCriticalError(error) ? error : new DeliveryError(`Delivery ${message.id} failed: ${getErrorMessage(error)}. Its external outcome is uncertain. Later messages were skipped; earlier acknowledged messages remain delivered.`, { cause: error });
 		}
+		ctx.session.recordAssistantDelivery(iteration.id);
 		iteration.recordTrace({
 			type: "message_delivery",
 			value: message.component,
@@ -16426,9 +16595,9 @@ async function deliverJavaScriptMessages({ ctx, iteration, controller }, message
 	}
 }
 async function finishNativeResponse(state, generated) {
-	const { ctx, iteration, controller, props } = state;
-	if (!generated.toolCalls.length && generated.output.trim() && ctx.chat) {
-		await applyNativeExit(iteration, ListenExit, {}, controller, props.onExit);
+	const { ctx, iteration } = state;
+	if (!generated.toolCalls.length && ctx.chat && (generated.output.trim() || generated.metadata.stopReason === "stop")) {
+		await applyNativeExit(state, ListenExit, {});
 		if (!iteration.hasExited()) ctx.session.appendContext(ctx.inspector(iteration.error ?? "Completion rejected.", {
 			purpose: "error",
 			maxTokens: 200
@@ -16524,7 +16693,9 @@ function getExecutionOutcome(state, memory) {
 			type: "inspect",
 			value: capture?.result.success ? capture.result.return_value : void 0,
 			available: memory.resultAvailable,
-			explicit: capture?.inspected ?? false
+			explicit: capture?.inspected ?? false,
+			forcedInspections: capture?.forcedInspections,
+			downstreamError: capture?.downstreamError
 		};
 	}
 	return {
@@ -16615,9 +16786,11 @@ function getIterationResult(state) {
 	}
 	if (iteration.status.type === "aborted") return new ErrorExecutionResult(ctx, iteration.error);
 }
-async function applyNativeExit(iteration, exit, value, controller, onExit) {
+async function applyNativeExit(state, exit, value) {
+	const { ctx, iteration, controller, props } = state;
 	try {
-		await callHook(() => onExit?.({
+		if (ctx.chat && exit === ListenExit && props.options?.requireChatResponse !== false && ctx.session.lastSpeaker !== "assistant") throw new MissingChatResponseError("The assistant has not delivered a message since the last user message. Send a response using the inspected results before waiting for the user. Do not repeat completed tool calls.");
+		await callHook(() => props.onExit?.({
 			exit,
 			result: value
 		}, controller));
@@ -16875,4 +17048,4 @@ const init = async () => {
 	await Promise.resolve().then(() => (init_native(), native_exports));
 };
 //#endregion
-export { AssignmentError, Chat, CitationsManager, CodeExecutionError, CodeFormattingError, CognitiveError, CompactionError, Component, ComponentInputError, DefaultComponents, DefaultExit, DeliveryError, ErrorExecutionResult, ExecutionAbortedError, ExecutionResult, Exit, ExitInputError, HookError, HostOperationError, InternalError, InvalidCodeError, InvalidComponentError, InvalidConfigurationError, InvalidEventError, InvalidExitError, InvalidMessageError, InvalidObjectError, InvalidSessionError, InvalidToolError, LLMzError, ListenExit, LoopExceededError, Memory, MemoryCapacityError, MemoryValueError, NativeProtocolError, ObjectInstance, ObjectPropertyError, ReservedIdentifierError, Session, SessionStateError, SuccessExecutionResult, ThinkSignal, TokenOverflowError, Tool, ToolExecutionError, ToolInputError, UnknownComponentError, UnknownExitError, UnknownToolError, _CustomModelClient, assertValidComponent, configureQuickJS, configureTokenizer, createInspector, execute, getValue, init, inspect, isAnyComponent, isComponent, isCriticalError, isLLMzError, truncate, utils, version };
+export { AssignmentError, Chat, CitationsManager, CodeExecutionError, CodeFormattingError, CognitiveError, CompactionError, Component, ComponentInputError, DefaultComponents, DefaultExit, DeliveryError, ErrorExecutionResult, ExecutionAbortedError, ExecutionResult, Exit, ExitInputError, HookError, HostOperationError, InternalError, InvalidCodeError, InvalidComponentError, InvalidConfigurationError, InvalidEventError, InvalidExitError, InvalidMessageError, InvalidObjectError, InvalidSessionError, InvalidToolError, LLMzError, ListenExit, LoopExceededError, Memory, MemoryCapacityError, MemoryValueError, MissingChatResponseError, NativeProtocolError, ObjectInstance, ObjectPropertyError, ReservedIdentifierError, Session, SessionStateError, SuccessExecutionResult, ThinkSignal, TokenOverflowError, Tool, ToolExecutionError, ToolInputError, UnknownComponentError, UnknownExitError, UnknownToolError, _CustomModelClient, assertValidComponent, configureQuickJS, configureTokenizer, createInspector, execute, getValue, init, inspect, isAnyComponent, isComponent, isCriticalError, isLLMzError, truncate, utils, version };