llmz 0.9.0 → 1.0.2

package/dist/inspect.d.ts

@@ -1,8 +1,22 @@
-type PreviewOptions = {
+import { type TruncatePreserve, type TruncationPolicy } from './truncate.js';
+export type InspectionPolicyLookup = (value: unknown) => TruncationPolicy | undefined;
+export type InspectOptions = {
     tokens: number;
-    /** Latest tool results defer string clipping to the request context budget. */
+    /** Maximum characters shown from a string, within the overall token budget. */
     maxStringLength?: number;
+    /** Render a single-line value without headings or analysis. */
+    compact?: boolean;
+    /** Disable per-value overrides for compact inventories and other fixed budgets. */
+    honorTruncation?: boolean;
+    /** Policies retained for unchanged tool values during the current execution. */
+    policies?: InspectionPolicyLookup;
+    preserve?: TruncatePreserve;
 };
+export declare function limitInspectionOutput(output: string, tokens: number, truncated: boolean, preserve?: TruncatePreserve): string;
 export declare function extractType(value: unknown, generic?: boolean): string;
-export declare const inspect: (value: unknown, name?: string, options?: PreviewOptions) => string;
-export {};
+export declare function resolveInspectionBudget(value: unknown, options: InspectOptions): {
+    tokens: number;
+    preserve: TruncatePreserve;
+    explicit: boolean;
+};
+export declare const inspect: (value: unknown, name?: string, options?: InspectOptions) => string;

package/dist/inspection.d.ts

@@ -0,0 +1,40 @@
+import { type InspectionPolicyLookup } from './inspect.js';
+import { type TruncatePreserve } from './truncate.js';
+export type InspectionPurpose = 'result' | 'variable' | 'property' | 'tool-input' | 'tool-output' | 'message' | 'error' | 'code' | 'event' | 'name';
+export type InspectionIdentity = {
+    sessionId?: string;
+    turn?: number;
+    turnId?: string;
+    iteration?: number;
+    iterationId?: string;
+    variable?: string;
+    object?: string;
+    property?: string;
+    tool?: string;
+    component?: string;
+    name?: string;
+};
+export type InspectEvent = {
+    /** An isolated, read-only copy. Changing a preview never changes runtime memory. */
+    readonly value: unknown;
+    readonly purpose: InspectionPurpose;
+    readonly maxTokens: number;
+    readonly preserve: TruncatePreserve;
+    readonly compact: boolean;
+    readonly identity?: Readonly<InspectionIdentity>;
+};
+/** Return undefined to use LLMz's default formatter. Returned text remains token-bounded. */
+export type OnInspect = (event: InspectEvent) => string | undefined;
+export type InspectionOptions = {
+    purpose: InspectionPurpose;
+    maxTokens: number;
+    preserve?: TruncatePreserve;
+    compact?: boolean;
+    identity?: InspectionIdentity;
+    policies?: InspectionPolicyLookup;
+};
+export type Inspector = (value: unknown, options: InspectionOptions) => string;
+/** The shared boundary for values displayed in prompts, reports, and memory inventories. */
+export declare function createInspector(onInspect?: OnInspect): Inspector;
+/** Isolate evidence from subsequent guest mutations without invoking getters. */
+export declare function snapshotInspectionValue(value: unknown, copies?: WeakMap<object, unknown>): unknown;

package/dist/native-0bq5ATZM.cjs

@@ -0,0 +1,212 @@
+const require_utils = require("./utils-CTlsXvdj.cjs");
+const require_errors = require("./errors-C6ppQUZX.cjs");
+const require_typings = require("./typings-BA_XxAcY.cjs");
+//#region src/chat/response.ts
+const presets = {
+	markdown: { instructions: "Write natural Markdown directly in the assistant response. Use paragraphs, lists, links, and code blocks where useful. Do not wrap the entire response in JSON or a Markdown fence." },
+	text: { instructions: "Write plain text directly in the assistant response. Use natural sentences and paragraph breaks. Do not use Markdown formatting, headings, tables, or code fences." },
+	speech: { instructions: "Write plain conversational prose for text-to-speech. Use short sentences that sound natural when spoken. Do not use Markdown, links, URLs, emojis, code, bullet points, tables, or headings. Spell out numbers, dates, units, and abbreviations as they should be pronounced." }
+};
+/** Resolve one response style for the entire generation, including its stream. */
+function resolveResponse(response = "markdown") {
+	var _config$instructions;
+	const config = typeof response === "string" ? { preset: response } : response;
+	if (!config || typeof config !== "object" || Array.isArray(config)) throw new require_errors.InvalidConfigurationError("Chat response must be a preset or a response configuration.");
+	if (Object.keys(config).some((key) => ![
+		"preset",
+		"instructions",
+		"handler",
+		"onDelta"
+	].includes(key))) throw new require_errors.InvalidConfigurationError("Chat response only accepts preset, instructions, handler, and onDelta.");
+	if (config.preset !== void 0 && (typeof config.preset !== "string" || !Object.hasOwn(presets, config.preset))) throw new require_errors.InvalidConfigurationError("Chat response preset must be \"markdown\", \"text\", or \"speech\".");
+	if (config.instructions !== void 0 && (typeof config.instructions !== "string" || !config.instructions.trim())) throw new require_errors.InvalidConfigurationError("Chat response instructions must be a non-empty string.");
+	for (const key of ["handler", "onDelta"]) if (config[key] !== void 0 && typeof config[key] !== "function") throw new require_errors.InvalidConfigurationError(`Chat response ${key} must be a function.`);
+	const presetName = config.preset ?? (config.instructions === void 0 ? "markdown" : void 0);
+	const preset = presetName === void 0 ? void 0 : presets[presetName];
+	return {
+		instructions: [preset === null || preset === void 0 ? void 0 : preset.instructions, (_config$instructions = config.instructions) === null || _config$instructions === void 0 ? void 0 : _config$instructions.trim()].filter(Boolean).join("\n\n"),
+		...config.handler === void 0 ? {} : { handler: config.handler },
+		...config.onDelta === void 0 ? {} : { onDelta: config.onDelta }
+	};
+}
+//#endregion
+//#region src/runtime/native-tools.ts
+const WORKER_RESPONSE_INSTRUCTION = "You are running in worker mode. Respond only with a run_javascript tool call. Keep assistant text empty: do not send messages, preambles, progress updates, explanations, acknowledgements such as \"Done\", Markdown, or JSON outside the tool call. This applies before and after tools, during recovery, and when completing the task.";
+const RUN_JAVASCRIPT_TOOL = {
+	name: "run_javascript",
+	description: "Run business tools, send requested chat components, or finish a worker task by executing JavaScript. For text plus actions, write the requested text as a preamble to this tool call; do not end with a text-only answer before the actions. Exact requested text needs no separator before this call: do not append a space or newline to the preamble. An ordinary chat reply with no remaining action needs no tool call just to finish the turn. Code displayed in an answer is text, not a program to execute. See \"run_javascript syntax\" and the documented functions and memory.",
+	parameters: {
+		type: "object",
+		properties: { code: {
+			type: "string",
+			minLength: 1,
+			description: "JavaScript source with an explicit return statement. Top-level await is supported."
+		} },
+		required: ["code"],
+		additionalProperties: false
+	}
+};
+/** Select delivery guidance without changing the native tool name or input schema. */
+function getRunJavaScriptTool(chat) {
+	if (chat) return RUN_JAVASCRIPT_TOOL;
+	return {
+		...RUN_JAVASCRIPT_TOOL,
+		description: `${WORKER_RESPONSE_INSTRUCTION} See "run_javascript syntax" and the documented functions and memory.`
+	};
+}
+/** Validate the entire response before any delivery or business action begins. */
+function validateNativeToolCalls(calls) {
+	if (!calls.length) return { valid: true };
+	if (calls.length > 1) return {
+		valid: false,
+		errors: ["Use at most one run_javascript call per response. Put all operations inside its JavaScript program."]
+	};
+	const [call] = calls;
+	if (!call || typeof call.id !== "string" || !call.id.trim()) return {
+		valid: false,
+		errors: ["Every native tool call requires a non-empty ID."]
+	};
+	if (call.name !== RUN_JAVASCRIPT_TOOL.name) return {
+		valid: false,
+		errors: [`Unknown native tool ${JSON.stringify(call.name)}. Use run_javascript.`]
+	};
+	const input = call.input;
+	if (!input || typeof input !== "object" || Array.isArray(input)) return {
+		valid: false,
+		errors: ["Tool arguments must be a JSON object."]
+	};
+	if (Object.keys(input).some((key) => key !== "code") || typeof input.code !== "string" || !input.code.trim()) return {
+		valid: false,
+		errors: ["run_javascript requires exactly one non-empty code string."]
+	};
+	return {
+		valid: true,
+		call: {
+			id: call.id,
+			code: input.code
+		}
+	};
+}
+//#endregion
+//#region src/prompts/native.ts
+var native_exports = /* @__PURE__ */ require_utils.__exportAll({ getNativeSystemMessage: () => getNativeSystemMessage });
+const runJavaScriptSyntax = [
+	"# run_javascript syntax",
+	"run_javascript is the only native tool. Call it with a JSON object containing exactly one property: \"code\", a non-empty string of JavaScript source.",
+	"The code string is the body of an async JavaScript program. Top-level await and return are supported. Send plain JavaScript without Markdown fences, an enclosing function, type annotations, imports, or JSX. eval, Function constructors, and dynamically generated code are not supported.",
+	"Make at most one run_javascript call per response. Put multiple operations in that program: await dependent business calls in order, or await Promise.all for independent operations when safe. Await all business operations before the final return, including unfinished siblings after a Promise.all failure.",
+	"Use only the functions documented in the JavaScript API and variables listed in Memory. Do not assume browser, network, filesystem, or package APIs are available.",
+	"Match each function signature exactly. A string parameter takes a string, not an object containing that string."
+].join("\n\n");
+function runtimeRules(props, chat) {
+	const hasExits = props.exits.length > 0;
+	const listen = props.exits.find((exit) => exit.name.toLowerCase() === "listen");
+	const rules = [
+		"# Responses and execution",
+		hasExits ? "Every run_javascript program must explicitly return inspect(value) for inspection or return exit(\"NAME\", payload) with a registered name and its required payload for completion." : "Every run_javascript program must explicitly return inspect(value).",
+		"The only way for the model to see a business tool return value is return inspect(value). JavaScript can use tool results immediately to compute, branch, or call other functions. Inspection exposes the result in the next response.",
+		"If completing the task requires interpreting natural-language tool output, inspect it before constructing the completion payload. Do not substitute the whole returned text for an extracted field, guess facts, or fill required fields with placeholders. Structured results may be used directly when the program can compute the complete payload from them.",
+		"inspect(...) constructs an opaque decision that takes effect only when returned as the result of the JavaScript program. Never fabricate, serialize, or store a decision as persistent memory."
+	];
+	if (chat) rules.push("Reply to the user with normal assistant text. Assistant text streams normally and is visible to the user. A completed response without tool calls finishes the turn. Choose text-only only when no requested action remains; a requested component or business operation requires a tool call in this response, even when you already wrote the requested text. Keep private reasoning out of assistant text.", "Follow the task's response constraints exactly. When exact text is requested, reproduce it byte-for-byte, without a greeting, explanation, translation, or extra whitespace. Do not add a leading or trailing space or newline, including before a tool call. This constrains assistant text, not the tool calls needed to carry out the task. Response style applies to free-form prose; it must not rewrite supplied text or code that the task asks you to preserve, including whitespace, quotes, and escapes. When transcribing source, check each line against the supplied source rather than completing familiar patterns from memory.", "Keep routine business lookups and recovery silent unless progress updates are requested; answer from inspected results. This does not suppress text explicitly requested alongside components. When more work remains, send a requested progress update alongside the run_javascript call that continues that work; a text-only update ends the turn.");
+	else {
+		rules.push(WORKER_RESPONSE_INSTRUCTION);
+		if (hasExits) rules.push("Complete the assigned task with return exit(\"NAME\", payload) inside JavaScript. Assistant prose alone does not complete a worker task. Every worker response, including completion after an inspection, must call run_javascript. Return the completion payload through exit, never as assistant text or a Markdown/JSON response.");
+	}
+	if (hasExits) rules.push("Complete all required work before returning the registered exit. JavaScript can compute its payload from tool results without another model response. Completion validates the payload and requires its hook to succeed. Omit the payload when an exit signature has no payload parameter.");
+	if (chat && props.exits.some((exit) => exit !== listen)) rules.push("When a known outcome matches a registered task exit description, return exit(\"NAME\", payload) for that outcome, even if you also explain it in assistant text. Prose does not select a typed exit.");
+	if (chat && listen) rules.push(`Use return exit(${JSON.stringify(listen.name)}) only when waiting for the user or when no task outcome matches another registered exit, within a program that already needs to run. A plain assistant reply automatically waits for the user when its text ends. Do not call run_javascript solely to listen after a text-only reply, even if the task says "then listen".`);
+	if (chat && props.components.size) {
+		rules.push("Send rich messages with the registered chat methods. Each method accepts its documented props, sends synchronously, and returns void; do not await it. Messages are delivered in invocation order. A component call does not finish the program; follow it with the required return.", `When the task requests text AND components, put the requested text in the assistant preamble to a native tool call, then call run_javascript to send the components. Use a tool-call response with a text preamble, not a final text-only answer. Both belong in this response.${hasExits ? " exit ends the turn and cannot send the missing text afterward." : ""} Text alone omits the components; components alone omit the text. When only components are requested, keep assistant output empty and do not add an acknowledgement afterward.`, "Never print a rich-message description instead of sending its component. Reuse acknowledged deliveries; a failed delivery may have an uncertain external outcome.");
+		if (listen) rules.push(`After sending all requested components, finish in the same program with return exit(${JSON.stringify(listen.name)}) when waiting for the user. Returning inspect(undefined) requests another response and does not finish the turn.`);
+	}
+	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 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) {
+	const declarations = ["declare function inspect<T>(value: T): InspectionDecision;"];
+	for (const exit of props.exits) {
+		const name = JSON.stringify(exit.name);
+		const description = `${exit.description}${!exit.zSchema && chat ? " This does not send a message." : ""}`;
+		const parameters = exit.zSchema ? `name: ${name}, payload${exit.zSchema.isOptional() ? "?" : ""}: ${await require_typings.getTypings(exit.zSchema)}` : `name: ${name}`;
+		declarations.push(require_utils.getMultilineComment(description), `declare function exit(${parameters}): never;`);
+	}
+	if (chat && props.components.size) {
+		declarations.push("declare const chat: {");
+		for (const [name, component] of props.components) declarations.push(require_utils.getMultilineComment(component.definition.description), `${name}(props: ${await require_typings.getTypings(component.definition.props)}): void;`);
+		declarations.push("};");
+	}
+	return "```typescript\n" + await require_typings.formatTypings(declarations.join("\n")) + "\n```";
+}
+async function getNativeSystemMessage(props) {
+	var _props$instructions;
+	const chat = props.isChatEnabled;
+	const declarations = await Promise.all([...props.objects.filter((object) => {
+		var _object$tools;
+		return (_object$tools = object.tools) === null || _object$tools === void 0 ? void 0 : _object$tools.length;
+	}).map((object) => object.getToolTypings()), ...props.globalTools.map((tool) => tool.getTypings())]);
+	const instructions = ((_props$instructions = props.instructions) === null || _props$instructions === void 0 ? void 0 : _props$instructions.trim()) || "Carry out the assigned task.";
+	const tools = [await describeRuntimeAPI(props, chat), ...declarations.length ? ["```typescript\n" + declarations.join("\n\n") + "\n```"] : []].join("\n\n");
+	const protocol = [
+		runJavaScriptSyntax,
+		runtimeRules(props, chat),
+		...chat ? ["# Assistant response", (props.response ?? resolveResponse()).instructions] : []
+	].join("\n\n");
+	return {
+		message: {
+			role: "system",
+			content: [
+				protocol,
+				"# JavaScript API",
+				"These TypeScript declarations describe functions inside run_javascript. Object properties, their types, values, and read/write rules are listed in Memory.",
+				tools,
+				"# Task instructions",
+				instructions
+			].join("\n\n")
+		},
+		parts: {
+			instructions,
+			tools,
+			protocol
+		}
+	};
+}
+//#endregion
+Object.defineProperty(exports, "WORKER_RESPONSE_INSTRUCTION", {
+	enumerable: true,
+	get: function() {
+		return WORKER_RESPONSE_INSTRUCTION;
+	}
+});
+Object.defineProperty(exports, "getNativeSystemMessage", {
+	enumerable: true,
+	get: function() {
+		return getNativeSystemMessage;
+	}
+});
+Object.defineProperty(exports, "getRunJavaScriptTool", {
+	enumerable: true,
+	get: function() {
+		return getRunJavaScriptTool;
+	}
+});
+Object.defineProperty(exports, "native_exports", {
+	enumerable: true,
+	get: function() {
+		return native_exports;
+	}
+});
+Object.defineProperty(exports, "resolveResponse", {
+	enumerable: true,
+	get: function() {
+		return resolveResponse;
+	}
+});
+Object.defineProperty(exports, "validateNativeToolCalls", {
+	enumerable: true,
+	get: function() {
+		return validateNativeToolCalls;
+	}
+});

package/dist/native-n_718Z-T.js

@@ -0,0 +1,177 @@
+import { Y as __exportAll, i as getMultilineComment } from "./utils-BOFzb8Ok.js";
+import { b as InvalidConfigurationError } from "./errors-Crk5P8jo.js";
+import { i as formatTypings, t as getTypings } from "./typings-BEVDvtuk.js";
+//#region src/chat/response.ts
+const presets = {
+	markdown: { instructions: "Write natural Markdown directly in the assistant response. Use paragraphs, lists, links, and code blocks where useful. Do not wrap the entire response in JSON or a Markdown fence." },
+	text: { instructions: "Write plain text directly in the assistant response. Use natural sentences and paragraph breaks. Do not use Markdown formatting, headings, tables, or code fences." },
+	speech: { instructions: "Write plain conversational prose for text-to-speech. Use short sentences that sound natural when spoken. Do not use Markdown, links, URLs, emojis, code, bullet points, tables, or headings. Spell out numbers, dates, units, and abbreviations as they should be pronounced." }
+};
+/** Resolve one response style for the entire generation, including its stream. */
+function resolveResponse(response = "markdown") {
+	var _config$instructions;
+	const config = typeof response === "string" ? { preset: response } : response;
+	if (!config || typeof config !== "object" || Array.isArray(config)) throw new InvalidConfigurationError("Chat response must be a preset or a response configuration.");
+	if (Object.keys(config).some((key) => ![
+		"preset",
+		"instructions",
+		"handler",
+		"onDelta"
+	].includes(key))) throw new InvalidConfigurationError("Chat response only accepts preset, instructions, handler, and onDelta.");
+	if (config.preset !== void 0 && (typeof config.preset !== "string" || !Object.hasOwn(presets, config.preset))) throw new InvalidConfigurationError("Chat response preset must be \"markdown\", \"text\", or \"speech\".");
+	if (config.instructions !== void 0 && (typeof config.instructions !== "string" || !config.instructions.trim())) throw new InvalidConfigurationError("Chat response instructions must be a non-empty string.");
+	for (const key of ["handler", "onDelta"]) if (config[key] !== void 0 && typeof config[key] !== "function") throw new InvalidConfigurationError(`Chat response ${key} must be a function.`);
+	const presetName = config.preset ?? (config.instructions === void 0 ? "markdown" : void 0);
+	const preset = presetName === void 0 ? void 0 : presets[presetName];
+	return {
+		instructions: [preset === null || preset === void 0 ? void 0 : preset.instructions, (_config$instructions = config.instructions) === null || _config$instructions === void 0 ? void 0 : _config$instructions.trim()].filter(Boolean).join("\n\n"),
+		...config.handler === void 0 ? {} : { handler: config.handler },
+		...config.onDelta === void 0 ? {} : { onDelta: config.onDelta }
+	};
+}
+//#endregion
+//#region src/runtime/native-tools.ts
+const WORKER_RESPONSE_INSTRUCTION = "You are running in worker mode. Respond only with a run_javascript tool call. Keep assistant text empty: do not send messages, preambles, progress updates, explanations, acknowledgements such as \"Done\", Markdown, or JSON outside the tool call. This applies before and after tools, during recovery, and when completing the task.";
+const RUN_JAVASCRIPT_TOOL = {
+	name: "run_javascript",
+	description: "Run business tools, send requested chat components, or finish a worker task by executing JavaScript. For text plus actions, write the requested text as a preamble to this tool call; do not end with a text-only answer before the actions. Exact requested text needs no separator before this call: do not append a space or newline to the preamble. An ordinary chat reply with no remaining action needs no tool call just to finish the turn. Code displayed in an answer is text, not a program to execute. See \"run_javascript syntax\" and the documented functions and memory.",
+	parameters: {
+		type: "object",
+		properties: { code: {
+			type: "string",
+			minLength: 1,
+			description: "JavaScript source with an explicit return statement. Top-level await is supported."
+		} },
+		required: ["code"],
+		additionalProperties: false
+	}
+};
+/** Select delivery guidance without changing the native tool name or input schema. */
+function getRunJavaScriptTool(chat) {
+	if (chat) return RUN_JAVASCRIPT_TOOL;
+	return {
+		...RUN_JAVASCRIPT_TOOL,
+		description: `${WORKER_RESPONSE_INSTRUCTION} See "run_javascript syntax" and the documented functions and memory.`
+	};
+}
+/** Validate the entire response before any delivery or business action begins. */
+function validateNativeToolCalls(calls) {
+	if (!calls.length) return { valid: true };
+	if (calls.length > 1) return {
+		valid: false,
+		errors: ["Use at most one run_javascript call per response. Put all operations inside its JavaScript program."]
+	};
+	const [call] = calls;
+	if (!call || typeof call.id !== "string" || !call.id.trim()) return {
+		valid: false,
+		errors: ["Every native tool call requires a non-empty ID."]
+	};
+	if (call.name !== RUN_JAVASCRIPT_TOOL.name) return {
+		valid: false,
+		errors: [`Unknown native tool ${JSON.stringify(call.name)}. Use run_javascript.`]
+	};
+	const input = call.input;
+	if (!input || typeof input !== "object" || Array.isArray(input)) return {
+		valid: false,
+		errors: ["Tool arguments must be a JSON object."]
+	};
+	if (Object.keys(input).some((key) => key !== "code") || typeof input.code !== "string" || !input.code.trim()) return {
+		valid: false,
+		errors: ["run_javascript requires exactly one non-empty code string."]
+	};
+	return {
+		valid: true,
+		call: {
+			id: call.id,
+			code: input.code
+		}
+	};
+}
+//#endregion
+//#region src/prompts/native.ts
+var native_exports = /* @__PURE__ */ __exportAll({ getNativeSystemMessage: () => getNativeSystemMessage });
+const runJavaScriptSyntax = [
+	"# run_javascript syntax",
+	"run_javascript is the only native tool. Call it with a JSON object containing exactly one property: \"code\", a non-empty string of JavaScript source.",
+	"The code string is the body of an async JavaScript program. Top-level await and return are supported. Send plain JavaScript without Markdown fences, an enclosing function, type annotations, imports, or JSX. eval, Function constructors, and dynamically generated code are not supported.",
+	"Make at most one run_javascript call per response. Put multiple operations in that program: await dependent business calls in order, or await Promise.all for independent operations when safe. Await all business operations before the final return, including unfinished siblings after a Promise.all failure.",
+	"Use only the functions documented in the JavaScript API and variables listed in Memory. Do not assume browser, network, filesystem, or package APIs are available.",
+	"Match each function signature exactly. A string parameter takes a string, not an object containing that string."
+].join("\n\n");
+function runtimeRules(props, chat) {
+	const hasExits = props.exits.length > 0;
+	const listen = props.exits.find((exit) => exit.name.toLowerCase() === "listen");
+	const rules = [
+		"# Responses and execution",
+		hasExits ? "Every run_javascript program must explicitly return inspect(value) for inspection or return exit(\"NAME\", payload) with a registered name and its required payload for completion." : "Every run_javascript program must explicitly return inspect(value).",
+		"The only way for the model to see a business tool return value is return inspect(value). JavaScript can use tool results immediately to compute, branch, or call other functions. Inspection exposes the result in the next response.",
+		"If completing the task requires interpreting natural-language tool output, inspect it before constructing the completion payload. Do not substitute the whole returned text for an extracted field, guess facts, or fill required fields with placeholders. Structured results may be used directly when the program can compute the complete payload from them.",
+		"inspect(...) constructs an opaque decision that takes effect only when returned as the result of the JavaScript program. Never fabricate, serialize, or store a decision as persistent memory."
+	];
+	if (chat) rules.push("Reply to the user with normal assistant text. Assistant text streams normally and is visible to the user. A completed response without tool calls finishes the turn. Choose text-only only when no requested action remains; a requested component or business operation requires a tool call in this response, even when you already wrote the requested text. Keep private reasoning out of assistant text.", "Follow the task's response constraints exactly. When exact text is requested, reproduce it byte-for-byte, without a greeting, explanation, translation, or extra whitespace. Do not add a leading or trailing space or newline, including before a tool call. This constrains assistant text, not the tool calls needed to carry out the task. Response style applies to free-form prose; it must not rewrite supplied text or code that the task asks you to preserve, including whitespace, quotes, and escapes. When transcribing source, check each line against the supplied source rather than completing familiar patterns from memory.", "Keep routine business lookups and recovery silent unless progress updates are requested; answer from inspected results. This does not suppress text explicitly requested alongside components. When more work remains, send a requested progress update alongside the run_javascript call that continues that work; a text-only update ends the turn.");
+	else {
+		rules.push(WORKER_RESPONSE_INSTRUCTION);
+		if (hasExits) rules.push("Complete the assigned task with return exit(\"NAME\", payload) inside JavaScript. Assistant prose alone does not complete a worker task. Every worker response, including completion after an inspection, must call run_javascript. Return the completion payload through exit, never as assistant text or a Markdown/JSON response.");
+	}
+	if (hasExits) rules.push("Complete all required work before returning the registered exit. JavaScript can compute its payload from tool results without another model response. Completion validates the payload and requires its hook to succeed. Omit the payload when an exit signature has no payload parameter.");
+	if (chat && props.exits.some((exit) => exit !== listen)) rules.push("When a known outcome matches a registered task exit description, return exit(\"NAME\", payload) for that outcome, even if you also explain it in assistant text. Prose does not select a typed exit.");
+	if (chat && listen) rules.push(`Use return exit(${JSON.stringify(listen.name)}) only when waiting for the user or when no task outcome matches another registered exit, within a program that already needs to run. A plain assistant reply automatically waits for the user when its text ends. Do not call run_javascript solely to listen after a text-only reply, even if the task says "then listen".`);
+	if (chat && props.components.size) {
+		rules.push("Send rich messages with the registered chat methods. Each method accepts its documented props, sends synchronously, and returns void; do not await it. Messages are delivered in invocation order. A component call does not finish the program; follow it with the required return.", `When the task requests text AND components, put the requested text in the assistant preamble to a native tool call, then call run_javascript to send the components. Use a tool-call response with a text preamble, not a final text-only answer. Both belong in this response.${hasExits ? " exit ends the turn and cannot send the missing text afterward." : ""} Text alone omits the components; components alone omit the text. When only components are requested, keep assistant output empty and do not add an acknowledgement afterward.`, "Never print a rich-message description instead of sending its component. Reuse acknowledged deliveries; a failed delivery may have an uncertain external outcome.");
+		if (listen) rules.push(`After sending all requested components, finish in the same program with return exit(${JSON.stringify(listen.name)}) when waiting for the user. Returning inspect(undefined) requests another response and does not finish the turn.`);
+	}
+	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 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) {
+	const declarations = ["declare function inspect<T>(value: T): InspectionDecision;"];
+	for (const exit of props.exits) {
+		const name = JSON.stringify(exit.name);
+		const description = `${exit.description}${!exit.zSchema && chat ? " This does not send a message." : ""}`;
+		const parameters = exit.zSchema ? `name: ${name}, payload${exit.zSchema.isOptional() ? "?" : ""}: ${await getTypings(exit.zSchema)}` : `name: ${name}`;
+		declarations.push(getMultilineComment(description), `declare function exit(${parameters}): never;`);
+	}
+	if (chat && props.components.size) {
+		declarations.push("declare const chat: {");
+		for (const [name, component] of props.components) declarations.push(getMultilineComment(component.definition.description), `${name}(props: ${await getTypings(component.definition.props)}): void;`);
+		declarations.push("};");
+	}
+	return "```typescript\n" + await formatTypings(declarations.join("\n")) + "\n```";
+}
+async function getNativeSystemMessage(props) {
+	var _props$instructions;
+	const chat = props.isChatEnabled;
+	const declarations = await Promise.all([...props.objects.filter((object) => {
+		var _object$tools;
+		return (_object$tools = object.tools) === null || _object$tools === void 0 ? void 0 : _object$tools.length;
+	}).map((object) => object.getToolTypings()), ...props.globalTools.map((tool) => tool.getTypings())]);
+	const instructions = ((_props$instructions = props.instructions) === null || _props$instructions === void 0 ? void 0 : _props$instructions.trim()) || "Carry out the assigned task.";
+	const tools = [await describeRuntimeAPI(props, chat), ...declarations.length ? ["```typescript\n" + declarations.join("\n\n") + "\n```"] : []].join("\n\n");
+	const protocol = [
+		runJavaScriptSyntax,
+		runtimeRules(props, chat),
+		...chat ? ["# Assistant response", (props.response ?? resolveResponse()).instructions] : []
+	].join("\n\n");
+	return {
+		message: {
+			role: "system",
+			content: [
+				protocol,
+				"# JavaScript API",
+				"These TypeScript declarations describe functions inside run_javascript. Object properties, their types, values, and read/write rules are listed in Memory.",
+				tools,
+				"# Task instructions",
+				instructions
+			].join("\n\n")
+		},
+		parts: {
+			instructions,
+			tools,
+			protocol
+		}
+	};
+}
+//#endregion
+export { validateNativeToolCalls as a, getRunJavaScriptTool as i, native_exports as n, resolveResponse as o, WORKER_RESPONSE_INSTRUCTION as r, getNativeSystemMessage as t };

package/dist/objects.d.ts

@@ -217,25 +217,6 @@ export declare namespace ObjectInstance {
  * })
  * ```
  *
- * ## TypeScript Integration
- *
- * Objects generate TypeScript namespace declarations:
- *
- * ```typescript
- * // Generated types for the LLM context:
- * export namespace user {
- *   const name: Writable<string | null> = null
- *   const age: Writable<number | null> = null
- *   const id: Readonly<string> = "user_123"
- * }
- *
- * export namespace fs {
- *   function readFile(args: { path: string }): Promise<string>
- *   function writeFile(args: { path: string, content: string }): Promise<void>
- * }
- * ```
- *
- * @see {@link https://github.com/botpress/botpress/blob/master/packages/llmz/examples/09_chat_variables/index.ts} Example usage
  */
 export declare class ObjectInstance implements Serializable<ObjectInstance.JSON> {
     name: string;
@@ -306,44 +287,8 @@ export declare class ObjectInstance implements Serializable<ObjectInstance.JSON>
         properties?: ObjectProperty[];
         metadata?: Record<string, unknown>;
     });
-    /**
-     * Generates TypeScript namespace declarations for this object.
-     *
-     * This method creates TypeScript definitions that are included in the LLM context
-     * to help it understand the available properties and tools. Properties become
-     * const declarations with appropriate Readonly/Writable types, and tools become
-     * function signatures.
-     *
-     * @returns Promise resolving to TypeScript namespace declaration
-     *
-     * @example
-     * ```typescript
-     * const obj = new ObjectInstance({
-     *   name: 'user',
-     *   properties: [
-     *     { name: 'name', value: 'John', writable: true },
-     *     { name: 'id', value: 123, writable: false },
-     *   ],
-     *   tools: [
-     *     new Tool({
-     *       name: 'save',
-     *       input: z.object({ data: z.string() }),
-     *       handler: async ({ data }) => { /* ... *\/ },
-     *     }),
-     *   ],
-     * })
-     *
-     * const typings = await obj.getTypings()
-     * console.log(typings)
-     * // Output:
-     * // export namespace user {
-     * //   const name: Writable<string> = "John"
-     * //   const id: Readonly<number> = 123
-     * //   function save(args: { data: string }): Promise<void>
-     * // }
-     * ```
-     */
-    getTypings(): Promise<string>;
+    /** Callable API only. Property values, schemas, and access rules belong in Memory. */
+    getToolTypings(): Promise<string>;
     /**
      * Converts this ObjectInstance to its JSON representation.
      *

package/dist/prompts/native.d.ts

@@ -0,0 +1,2 @@
+import type { LLMzPrompts } from './prompt.js';
+export declare function getNativeSystemMessage(props: LLMzPrompts.InitialStateProps): Promise<LLMzPrompts.SystemMessage>;