llmz 0.7.1 → 0.9.0

package/dist/example-format.d.ts

@@ -0,0 +1,8 @@
+/** Documentation boundaries only; never part of the response protocol. */
+export declare const quoteExample: (output: string) => string;
+/** A single block excerpt; the omitted response is not part of this example. */
+export declare const quotePartialExample: (output: string) => string;
+export declare const exampleBoundaryInstructions = "Triple quotes (\"\"\") mark the beginning and end of examples only. Do NOT emit these delimiters in your response.";
+/** A complete response example, unlike individual block/syntax examples. */
+export declare const quoteResponseExample: (output: string) => string;
+export declare const responseEnvelopeInstructions = "Every response starts with \u25A0start on its own line and ends with \u25A0end on its own line. Between them write only the documented protocol blocks. Nothing goes before \u25A0start or after \u25A0end. The envelope is protocol, not a code fence.";

package/dist/example.d.ts

@@ -0,0 +1,45 @@
+import type { Component } from './component.js';
+import type { Exit } from './exit.js';
+export type ExampleMessage = {
+    component: Component | string;
+    props?: Record<string, unknown>;
+    body?: string;
+};
+/** Exactly one model response: messages followed by code or an exit. */
+type ExampleResponse = {
+    messages?: ExampleMessage[];
+} & ({
+    code: string;
+    exit?: never;
+    props?: never;
+} | {
+    exit: Exit | string;
+    props?: Record<string, unknown>;
+    code?: never;
+});
+/** One hypothetical situation and the single response to produce in it. */
+export type ExampleDefinition = {
+    /** Include the request, known facts, or previous tool results needed to understand this response. */
+    situation: string;
+    /** Optional explanation of why this response is appropriate. Context for the model, not generated output. */
+    reason?: string;
+} & ExampleResponse;
+/**
+ * Builds one protocol-correct response to one hypothetical situation.
+ *
+ * @example
+ * new Example({
+ *   situation: 'The user asks a question that needs a knowledge-base search.',
+ *   reason: 'Search first so the answer can use actual evidence.',
+ *   code: 'return await searchKnowledge({ query: "reset password" })',
+ * })
+ */
+export declare class Example {
+    readonly situation: string;
+    readonly reason?: string;
+    readonly output: string;
+    constructor(definition: ExampleDefinition);
+}
+/** Internal prompt renderer. Checks examples against this iteration's component/exit catalog. */
+export declare const renderExamples: (examples: readonly Example[], components: Component[], exits: Exit[]) => Promise<string>;
+export {};

package/dist/example.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/{execute-DP_17lYZ.js → execute-BWcdv9so.js}

@@ -1,11 +1,13 @@
-import { a as StreamingMessageParser, d as isEqual, h as toNumber, i as toParsedAssistantResponse } from "./dual-modes-mNyMThtf.js";
-import { d as Snapshot, f as parseExit, l as PartialExecutionResult, n as Context, s as ErrorExecutionResult, t as _CustomModelClient, u as SuccessExecutionResult } from "./custom-client-CMuy7fXU.js";
+import { a as isEqual, l as toNumber } from "./dual-modes-DDkoCp3R.js";
+import { a as ResponseParser, i as toParsedAssistantResponse } from "./common-BlRFtdf2.js";
+import { d as Snapshot, f as parseExit, l as PartialExecutionResult, n as Context, s as ErrorExecutionResult, t as _CustomModelClient, u as SuccessExecutionResult } from "./custom-client-ChuZ63zp.js";
 import { d as stripInvalidIdentifiers, i as getErrorMessage, s as init } from "./utils-UBeAFeEI.js";
 import { t as createJsxComponent } from "./jsx-CIgdGGVs.js";
 import { t as cleanStackTrace } from "./stack-traces-BIE_5Xwf.js";
 import { a as InvalidCodeError, c as SnapshotSignal, i as CognitiveError, l as ThinkSignal, n as CodeExecutionError, o as LoopExceededError, s as Signals, t as AssignmentError } from "./errors-Cg1G0Awu.js";
 import { n as truncateWrappedContent } from "./truncator-DZqEqnpD.js";
-import { runAsyncFunction, t as hasTopLevelReturn, warmupVM } from "./vm-C5vf1LH3.js";
+import { r as hasTopLevelReturn } from "./compiler-CW1VjQsn.js";
+import { runAsyncFunction, warmupVM } from "./vm-BLsHw1da.js";
 import { z } from "@bpinternal/zui";
 import { ulid } from "ulid";
 import { Client } from "@botpress/client";
@@ -126,35 +128,7 @@ const assertSuccessfulGeneration = (metadata) => {
 	if (metadata.stopReason === "max_tokens" || metadata.stopReason === "content_filter") throw new CognitiveError(`LLM generation did not complete: stopReason=${metadata.stopReason}`);
 };
 const getModelOutputLimit = (inputLength) => clamp(RESPONSE_LENGTH_BUFFER.PERCENTAGE * inputLength, RESPONSE_LENGTH_BUFFER.MIN_TOKENS, RESPONSE_LENGTH_BUFFER.MAX_TOKENS);
-/**
-* Models sometimes wrap their whole response in a code fence. The fence has to
-* be removed before it reaches the incremental parser to avoid a spurious
-* unexpected-text diagnostic. Works on arbitrary chunk boundaries
-* by holding content back until the first newline.
-*/
-var LeadingFenceFilter = class {
-	_buffer = "";
-	_done = false;
-	push(text) {
-		if (this._done) return text;
-		this._buffer += text;
-		const newline = this._buffer.indexOf("\n");
-		if (newline === -1) return "";
-		this._done = true;
-		const firstLine = this._buffer.slice(0, newline);
-		const rest = this._buffer.slice(newline + 1);
-		this._buffer = "";
-		return firstLine.trim().startsWith("```") ? rest : `${firstLine}\n${rest}`;
-	}
-	flush() {
-		if (this._done) return "";
-		this._done = true;
-		const buffered = this._buffer;
-		this._buffer = "";
-		return buffered.trim().startsWith("```") ? "" : buffered;
-	}
-};
-const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, onSend, onSendDelta, onRunStart, onRunComplete }) => {
+const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, onSend, onSendDelta, onRunStart }) => {
 	const startedAt = Date.now();
 	const traces = iteration.traces;
 	const modelRef = Array.isArray(iteration.model) ? iteration.model[0] : iteration.model;
@@ -217,6 +191,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 	const liveContent = /* @__PURE__ */ new Map();
 	let codeGenerationTraced = false;
 	let runCompleted = false;
+	let completions = [];
 	const dispatchSends = async (events) => {
 		for (const event of events) if (event.type === "item-start") {
 			liveItems.set(event.item.id, event.item);
@@ -230,7 +205,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			}
 		} else if (event.type === "body-delta" && onSendDelta) {
 			const item = liveItems.get(event.itemId);
-			if ((item === null || item === void 0 ? void 0 : item.kind) !== "send") continue;
+			if ((item === null || item === void 0 ? void 0 : item.kind) !== "send" || runCompleted) continue;
 			const content = (liveContent.get(item.id) ?? "") + event.delta;
 			liveContent.set(item.id, content);
 			const delta = {
@@ -243,21 +218,19 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			};
 			await preview(delta);
 		} else if (event.type === "item-complete") {
-			if (event.item.kind === "send" && onSend) await onSend({
-				name: event.item.name,
-				props: event.item.props,
-				body: event.item.body
-			}, messageMetadata(event.item.id));
-			else if (event.item.kind === "run" && event.item.status === "complete" && !runCompleted) {
-				runCompleted = true;
-				const code = (event.item.body ?? "").trim();
-				onRunComplete === null || onRunComplete === void 0 || onRunComplete(code);
-			}
+			if (event.item.kind === "send" && onSend && !runCompleted) {
+				const send = {
+					name: event.item.name,
+					props: event.item.props,
+					body: event.item.body
+				};
+				const metadata = messageMetadata(event.item.id);
+				completions.push(() => onSend(send, metadata));
+			} else if (event.item.kind === "run" && event.item.status === "complete" && !runCompleted) runCompleted = true;
 		}
 	};
 	if (typeof cognitive.generateTextStream === "function") {
-		let parser = new StreamingMessageParser();
-		let fence = new LeadingFenceFilter();
+		let parser = new ResponseParser();
 		const streamController = createJoinedAbortController([controller.signal]);
 		const requestedAt = Date.now();
 		const stream = cognitive.generateTextStream({
@@ -285,6 +258,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 		};
 		raw = "";
 		let streamCompleted = false;
+		let accepted = false;
 		try {
 			while (true) {
 				var _chunk$value, _chunk$value2, _chunk$value3, _chunk$value4;
@@ -309,8 +283,9 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 						...chunk.value.restart
 					});
 					raw = "";
-					parser = new StreamingMessageParser();
-					fence = new LeadingFenceFilter();
+					completions = [];
+					accepted = false;
+					parser = new ResponseParser();
 					liveItems.clear();
 					liveContent.clear();
 					codeGenerationTraced = false;
@@ -332,19 +307,52 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 				timeToLastToken = Date.now() - requestedAt;
 				timeToFirstToken ??= timeToLastToken;
 				raw += delta;
-				await dispatchSends(parser.push(fence.push(delta)));
+				await dispatchSends(parser.push(delta));
 			}
 			if (!responseMetadata) throw new CognitiveError("LLM streaming completed without metadata");
 			assertSuccessfulGeneration(responseMetadata);
-			const remaining = fence.flush();
-			if (remaining) await dispatchSends(parser.push(remaining));
-			await dispatchSends(parser.finish());
+			await dispatchSends(parser.finish(responseMetadata.stopReason));
+			if (parser.valid) {
+				for (const complete of completions) await complete();
+				accepted = true;
+			}
 			assistantResponse = toParsedAssistantResponse(parser.items, raw, parser.diagnostics);
+		} catch (error) {
+			parser.finish();
+			const usage = (responseMetadata === null || responseMetadata === void 0 ? void 0 : responseMetadata.usage) ?? {
+				inputTokens: 0,
+				outputTokens: 0,
+				inputCost: 0,
+				outputCost: 0
+			};
+			iteration.llm = {
+				started_at: startedAt,
+				ended_at: Date.now(),
+				status: "error",
+				cached: (responseMetadata === null || responseMetadata === void 0 ? void 0 : responseMetadata.cached) ?? false,
+				tokens: usage.inputTokens + usage.outputTokens,
+				spend: (responseMetadata === null || responseMetadata === void 0 ? void 0 : responseMetadata.cost) ?? usage.inputCost + usage.outputCost,
+				output: raw,
+				diagnostics: parser.diagnostics,
+				model: (responseMetadata === null || responseMetadata === void 0 ? void 0 : responseMetadata.model) ?? model.id,
+				time_to_first_token: timeToFirstToken,
+				time_to_last_token: timeToLastToken,
+				usage
+			};
+			throw error;
 		} finally {
 			streamController.abort("LLM stream closed");
 			if (!streamCompleted) stream.return(void 0).catch((err) => {});
+			if (!accepted && liveContent.size) await preview({
+				restart: true,
+				iterationId: iteration.id,
+				attempt: attempt + 1,
+				fromModel: model.id,
+				toModel: model.id,
+				reason: "invalid or incomplete response envelope"
+			});
 		}
-		if (midStreamFallback) controller.signal.throwIfAborted();
+		controller.signal.throwIfAborted();
 	} else {
 		const response = await cognitive.generateText(input, { signal: controller.signal }).catch((thrown) => {
 			throw new CognitiveError(`LLM generation failed: ${getErrorMessage(thrown)}`);
@@ -354,7 +362,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 		responseMetadata = response.metadata;
 		assertSuccessfulGeneration(responseMetadata);
 		raw = response.output;
-		assistantResponse = ctx.version.parseAssistantResponse(raw);
+		assistantResponse = ctx.version.parseAssistantResponse(raw, responseMetadata.stopReason);
 		for (const [index, send] of assistantResponse.sends.entries()) await (onSend === null || onSend === void 0 ? void 0 : onSend(send, messageMetadata(`send-${index}`)));
 	}
 	iteration.code = assistantResponse.code;
@@ -396,6 +404,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 //#endregion
 //#region src/runtime/interpret-result.ts
 const interpretVMResult = async ({ iteration, result, controller, startedAt, onExit }) => {
+	Object.assign(iteration.variables, Object.fromEntries(Object.entries(result.variables ?? {}).filter(([, value]) => value !== "[[non-primitive]]")));
 	if (result.error && result.error instanceof InvalidCodeError) {
 		iteration.end({
 			type: "invalid_code_error",
@@ -443,7 +452,8 @@ const interpretVMResult = async ({ iteration, result, controller, startedAt, onE
 			thinking_requested: {
 				variables: result.signal.context,
 				reason: result.signal.reason,
-				metadata: result.signal.metadata
+				metadata: result.signal.metadata,
+				interrupted: true
 			}
 		});
 		return;
@@ -504,11 +514,14 @@ const applyNextExit = async ({ iteration, controller, onExit }) => {
 		value: parsedExit.success ? parsedExit.value : next.props
 	};
 	if (!parsedExit.success) {
+		var _parsedExit$validatio;
+		const details = (_parsedExit$validatio = parsedExit.validationErrors) === null || _parsedExit$validatio === void 0 ? void 0 : _parsedExit$validatio.join("; ");
+		const error = [parsedExit.error.split("\n")[0], details].filter(Boolean).join(". ");
 		iteration.end({
 			type: "exit_error",
 			exit_error: {
 				exit: next.name,
-				message: parsedExit.error,
+				message: `${error}. Received props: ${JSON.stringify(next.props)}. Choose an exit from <exits> and supply its required props as ONE JSON object on the SAME LINE as ■next=${next.name}. Do not use a JavaScript return statement or wrap the fields in "value" or "props".`,
 				return_value: returnValue
 			}
 		});
@@ -748,6 +761,7 @@ const executeContextInternal = async (props) => {
 	const ctx = new Context({
 		chat: props.chat,
 		instructions: props.instructions,
+		examples: props.examples,
 		objects: props.objects,
 		tools: props.tools,
 		loop: (_props$options = props.options) === null || _props$options === void 0 ? void 0 : _props$options.loop,
@@ -948,8 +962,6 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 			};
 		});
 	};
-	const canExecuteEarly = typeof onBeforeExecution !== "function" && !ctx.midStreamFallback;
-	let earlyExecution;
 	await generateCode({
 		iteration,
 		ctx,
@@ -957,22 +969,15 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 		controller,
 		metadata,
 		onRunStart: () => warmupVM(),
-		onRunComplete: canExecuteEarly ? (code) => {
-			if (!code.length || controller.signal.aborted || earlyExecution) return;
-			iteration.code = code;
-			earlyExecution = {
-				code,
-				started_at: Date.now(),
-				promise: runCode(code)
-			};
-		} : void 0,
 		onSend: async (send, messageMetadata) => {
 			if (!ctx.chat) return;
 			const sendStartedAt = Date.now();
-			const component = createJsxComponent({
+			const registered = iteration.components.find((component) => component.definition.name.toLowerCase() === send.name);
+			const children = send.body ? [send.body] : [];
+			const component = registered ? registered.render(send.props, children) : createJsxComponent({
 				type: send.name,
 				props: send.props,
-				children: send.body ? [send.body] : []
+				children
 			});
 			try {
 				await ctx.chat.handler(component, messageMetadata);
@@ -988,7 +993,6 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 		},
 		onSendDelta: ((_ctx$chat = ctx.chat) === null || _ctx$chat === void 0 ? void 0 : _ctx$chat.onMessageDelta) ? (delta) => ctx.chat.onMessageDelta(delta) : void 0
 	});
-	if (earlyExecution) iteration.code = earlyExecution.code;
 	if (typeof onBeforeExecution === "function") try {
 		const hookRes = await onBeforeExecution(iteration, controller);
 		if (typeof (hookRes === null || hookRes === void 0 ? void 0 : hookRes.code) === "string" && hookRes.code.trim().length > 0) iteration.code = hookRes.code.trim();
@@ -1026,7 +1030,7 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 		return;
 	}
 	if (!iteration.code) {
-		var _iteration$sends;
+		var _iteration$llm;
 		if (iteration.next) {
 			await applyNextExit({
 				iteration,
@@ -1035,26 +1039,14 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 			});
 			return;
 		}
-		if (ctx.chat && ((_iteration$sends = iteration.sends) === null || _iteration$sends === void 0 ? void 0 : _iteration$sends.length)) {
-			iteration.next = {
-				name: "listen",
-				props: {}
-			};
-			await applyNextExit({
-				iteration,
-				controller,
-				onExit
-			});
-			return;
-		}
 		iteration.end({
 			type: "invalid_code_error",
-			invalid_code_error: { message: "The response did not include a ■run block or a ■next exit. Reply using ■ blocks and end your response with ■run or ■next=<exit>." }
+			invalid_code_error: { message: ((_iteration$llm = iteration.llm) === null || _iteration$llm === void 0 || (_iteration$llm = _iteration$llm.diagnostics) === null || _iteration$llm === void 0 || (_iteration$llm = _iteration$llm.find((diagnostic) => diagnostic.code === "invalid-envelope")) === null || _iteration$llm === void 0 ? void 0 : _iteration$llm.message) ?? "The response did not include a ■run block or a ■next exit. Reply with ■start, the required ■ blocks, and ■end." }
 		});
 		return;
 	}
-	const startedAt = (earlyExecution === null || earlyExecution === void 0 ? void 0 : earlyExecution.started_at) ?? Date.now();
-	const result = earlyExecution ? await earlyExecution.promise : await runCode(iteration.code ?? "");
+	const startedAt = Date.now();
+	const result = await runCode(iteration.code);
 	await interpretVMResult({
 		iteration,
 		result,