llmz 0.7.1 → 0.8.0

package/dist/component.default.d.ts

@@ -1,5 +1,25 @@
 import { z } from '@bpinternal/zui';
-import { Component } from './component.js';
+import { Component, type ContainerComponentDefinition, type RenderedComponent } from './component.js';
+declare const carouselProps: z.ZodObject<{
+    cards: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        subtitle: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+        }, "strip">>;
+        buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            action: z.ZodDefault<z.ZodEnum<["say", "url", "postback"]>>;
+            label: z.ZodString;
+            value: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+        }, "strip">, "many">>;
+    }, "strip">, "many">;
+}, "strip">;
+declare class CarouselComponent extends Component<ContainerComponentDefinition<typeof carouselProps>> {
+    render(props: Component['propsType'], children?: any[]): RenderedComponent;
+}
 export declare const DefaultComponents: {
     Button: Component<{
         type: "leaf";
@@ -8,13 +28,28 @@ export declare const DefaultComponents: {
         aliases: string[];
         generation: {
             usage: string;
-            examples: {
+            examples: ({
+                props: {
+                    action: string;
+                    label: string;
+                    url?: undefined;
+                    value?: undefined;
+                };
+            } | {
                 props: {
+                    action: string;
+                    label: string;
+                    url: string;
+                    value?: undefined;
+                };
+            } | {
+                props: {
+                    url?: undefined;
                     action: string;
                     label: string;
                     value: string;
                 };
-            }[];
+            })[];
         };
         leaf: {
             props: z.ZodObject<{
@@ -31,6 +66,7 @@ export declare const DefaultComponents: {
         description: string;
         aliases: never[];
         generation: {
+            usage: string;
             examples: {
                 props: {
                     url: string;
@@ -111,6 +147,7 @@ export declare const DefaultComponents: {
         description: string;
         aliases: never[];
         generation: {
+            usage: string;
             examples: {
                 props: {
                     title: string;
@@ -132,6 +169,7 @@ export declare const DefaultComponents: {
                     description: string;
                     aliases: never[];
                     generation: {
+                        usage: string;
                         examples: {
                             props: {
                                 url: string;
@@ -155,13 +193,28 @@ export declare const DefaultComponents: {
                     aliases: string[];
                     generation: {
                         usage: string;
-                        examples: {
+                        examples: ({
+                            props: {
+                                action: string;
+                                label: string;
+                                url?: undefined;
+                                value?: undefined;
+                            };
+                        } | {
                             props: {
+                                action: string;
+                                label: string;
+                                url: string;
+                                value?: undefined;
+                            };
+                        } | {
+                            props: {
+                                url?: undefined;
                                 action: string;
                                 label: string;
                                 value: string;
                             };
-                        }[];
+                        })[];
                     };
                     leaf: {
                         props: z.ZodObject<{
@@ -175,88 +228,7 @@ export declare const DefaultComponents: {
             })[];
         };
     }>;
-    Carousel: Component<{
-        type: "container";
-        name: string;
-        description: string;
-        aliases: never[];
-        container: {
-            props: z.ZodObject<{}, "strip">;
-            children: {
-                description: string;
-                component: {
-                    type: "container";
-                    name: string;
-                    description: string;
-                    aliases: never[];
-                    generation: {
-                        examples: {
-                            props: {
-                                title: string;
-                                subtitle: string;
-                            };
-                            body: string;
-                        }[];
-                    };
-                    container: {
-                        props: z.ZodObject<{
-                            title: z.ZodString;
-                            subtitle: z.ZodOptional<z.ZodString>;
-                        }, "strip">;
-                        children: ({
-                            description: string;
-                            component: {
-                                type: "leaf";
-                                name: string;
-                                description: string;
-                                aliases: never[];
-                                generation: {
-                                    examples: {
-                                        props: {
-                                            url: string;
-                                            alt: string;
-                                        };
-                                    }[];
-                                };
-                                leaf: {
-                                    props: z.ZodObject<{
-                                        url: z.ZodString;
-                                        alt: z.ZodOptional<z.ZodString>;
-                                    }, "strip">;
-                                };
-                            };
-                        } | {
-                            description: string;
-                            component: {
-                                type: "leaf";
-                                description: string;
-                                name: string;
-                                aliases: string[];
-                                generation: {
-                                    usage: string;
-                                    examples: {
-                                        props: {
-                                            action: string;
-                                            label: string;
-                                            value: string;
-                                        };
-                                    }[];
-                                };
-                                leaf: {
-                                    props: z.ZodObject<{
-                                        action: z.ZodDefault<z.ZodEnum<["say", "url", "postback"]>>;
-                                        label: z.ZodString;
-                                        value: z.ZodOptional<z.ZodString>;
-                                        url: z.ZodOptional<z.ZodString>;
-                                    }, "strip">;
-                                };
-                            };
-                        })[];
-                    };
-                };
-            }[];
-        };
-    }>;
+    Carousel: CarouselComponent;
     Text: Component<{
         type: "default";
         name: string;
@@ -293,3 +265,4 @@ export declare const DefaultComponents: {
         };
     }>;
 };
+export {};

package/dist/component.default.test.d.ts

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

package/dist/context.d.ts

@@ -3,6 +3,7 @@ import { z } from '@bpinternal/zui';
 import { Chat } from './chat.js';
 import { Component } from './component.js';
 import { SnapshotSignal } from './errors.js';
+import type { Example } from './example.js';
 import { Exit } from './exit.js';
 import { ValueOrGetter } from './getter.js';
 import { HookedArray } from './handlers.js';
@@ -30,6 +31,8 @@ export type ContextTokens = {
     transcript: number;
     /** The ■ protocol reference documenting components and exits. */
     protocol: number;
+    /** Consumer few-shot demonstrations, separate from the live transcript. */
+    examples: number;
     /** Messages carried over from previous iterations (assistant responses, execution results, errors). */
     iterations: number;
 };
@@ -57,6 +60,7 @@ export type IterationParameters = {
     objects: ObjectInstance[];
     exits: Exit[];
     instructions?: string;
+    examples?: Example[];
     components: Component[];
     model: Models | Models[];
     temperature: number;
@@ -93,6 +97,8 @@ export declare namespace IterationStatuses {
             /** The value returned by the executed code (or the context provided by a ThinkSignal). */
             variables: unknown;
             metadata?: Record<string, unknown>;
+            /** A tool paused execution; it did not finish or return normally. */
+            interrupted?: boolean;
         };
     };
     type Callback = {
@@ -405,6 +411,7 @@ export declare class Iteration implements Serializable<Iteration.JSON> {
     get mutations(): ObjectMutation[];
     trackMutation(mutation: ObjectMutation): void;
     private _parameters;
+    get components(): Component[];
     get transcript(): TranscriptArray;
     get tools(): Tool<z.ZodType<any, z.ZodTypeDef, any>, z.ZodType<any, z.ZodTypeDef, any>>[];
     get objects(): ObjectInstance[];
@@ -551,6 +558,7 @@ export declare class Context implements Serializable<Context.JSON> {
     id: string;
     chat?: Chat;
     instructions?: ValueOrGetter<string, Context>;
+    examples?: ValueOrGetter<Example[], Context>;
     objects?: ValueOrGetter<ObjectInstance[], Context>;
     tools?: ValueOrGetter<Tool[], Context>;
     exits?: ValueOrGetter<Exit[], Context>;
@@ -588,6 +596,7 @@ export declare class Context implements Serializable<Context.JSON> {
     transcriptionModel?: SttModels;
     metadata: Record<string, any>;
     snapshot?: Snapshot;
+    private _lastMessageWithoutExecutionState?;
     iteration: number;
     iterations: Iteration[];
     nextIteration(): Promise<Iteration>;
@@ -605,6 +614,7 @@ export declare class Context implements Serializable<Context.JSON> {
     constructor(props: {
         chat?: Chat;
         instructions?: ValueOrGetter<string, Context>;
+        examples?: ValueOrGetter<Example[], Context>;
         objects?: ValueOrGetter<ObjectInstance[], Context>;
         tools?: ValueOrGetter<Tool[], Context>;
         exits?: ValueOrGetter<Exit[], Context>;

package/dist/{custom-client-CMuy7fXU.js → custom-client-2V9lmzUf.js}

@@ -1,13 +1,13 @@
+import { d as baseCreate, i as inspect, l as flatRest, r as extractType, t as DualModePrompt, u as copyArray } from "./dual-modes-Cy0_W4O2.js";
 import { a as Symbol, n as isArray, o as root, r as isObjectLike } from "./_overArg-CRYbj1NH.js";
 import { D as isBuffer, E as baseUnary, M as baseAssignValue, R as isObject, T as nodeUtil, _ as baseGet, c as _getTag_default, f as getSymbols, h as Stack, k as isPrototype, s as Uint8Array, u as getAllKeys, v as toKey, x as keys, y as castPath, z as arrayMap } from "./_baseIteratee-P_firB7b.js";
-import { f as flatRest, l as extractType, m as baseCreate, p as copyArray, t as DualModePrompt, u as inspect } from "./dual-modes-mNyMThtf.js";
-import { _ as getSymbolsIn, b as keysIn, g as getAllKeysIn, o as getTokenizer, x as assignValue, y as baseSlice } from "./utils-UBeAFeEI.js";
+import { _ as getSymbolsIn, b as keysIn, g as getAllKeysIn, i as getErrorMessage, o as getTokenizer, x as assignValue, y as baseSlice } from "./utils-UBeAFeEI.js";
 import { t as getPrototype } from "./_getPrototype-CG7Dxrrz.js";
-import { t as isPlainObject } from "./isPlainObject-D39AzPO2.js";
+import { a as isPlainObject } from "./jsx-B0iYyvfr.js";
+import { n as assertValidComponent } from "./component-Dq7ZLdvy.js";
 import { t as Tool } from "./tool-Bv8N4IPj.js";
-import { o as LoopExceededError } from "./errors-Cg1G0Awu.js";
+import { l as ThinkSignal, o as LoopExceededError } from "./errors-Cg1G0Awu.js";
 import { t as Exit } from "./exit-CDdxDBRT.js";
-import { n as assertValidComponent } from "./component-DGG7d_Mz.js";
 import { i as wrapContent, t as stripTruncationTags } from "./truncator-DZqEqnpD.js";
 import { z } from "@bpinternal/zui";
 import { ulid } from "ulid";
@@ -819,7 +819,8 @@ function parseExit(returnValue, exits) {
 	}
 	const schema = returnExit.zSchema;
 	const schemaType = schema._def.typeName;
-	let parsed = schema.safeParse(valueToValidate);
+	const initialParse = schema.safeParse(valueToValidate);
+	let parsed = initialParse;
 	if (!parsed.success && alternativeValue !== void 0 && alternativeValue !== valueToValidate) {
 		const altParsed = schema.safeParse(alternativeValue);
 		if (altParsed.success) {
@@ -833,6 +834,7 @@ function parseExit(returnValue, exits) {
 		parsed = result.parsed;
 	}
 	if (!parsed.success) {
+		var _initialParse$error;
 		const getValueTypeDescription = (val) => {
 			if (val === null) return "null";
 			if (val === void 0) return "undefined";
@@ -894,6 +896,7 @@ function parseExit(returnValue, exits) {
 				"But expected one of:",
 				...expectedStatements.map((s) => `  ${s}`)
 			].join("\n"),
+			validationErrors: (((_initialParse$error = initialParse.error) === null || _initialParse$error === void 0 ? void 0 : _initialParse$error.issues) ?? []).map((issue) => `${issue.path.join(".") || "value"}: ${issue.message}`),
 			returnValue
 		};
 	}
@@ -1788,6 +1791,49 @@ var HookedArray = class extends Array {
 	}
 };
 //#endregion
+//#region src/prompts/execution-history.ts
+function describeOutcome(status) {
+	switch (status.type) {
+		case "thinking_requested": return status.thinking_requested.interrupted ? "a tool paused execution" : "code completed and returned control";
+		case "execution_error": return "code execution failed";
+		case "invalid_code_error": return "invalid code or protocol";
+		case "exit_error": return "exit validation failed";
+		default: return status.type;
+	}
+}
+/** Summarize observed effects, including failed calls and retracted deliveries. */
+function summarizeIterations(iterations, canTalk) {
+	const history = [];
+	const attempts = /* @__PURE__ */ new Map();
+	const deliveredMessages = [];
+	for (const [index, iteration] of iterations.entries()) {
+		const calls = [];
+		const lastRestart = iteration.traces.reduce((last, trace, traceIndex) => trace.type === "llm_call_restarted" ? traceIndex : last, -1);
+		for (const [traceIndex, trace] of iteration.traces.entries()) {
+			if (trace.type === "tool_call") {
+				const name = trace.object ? `${trace.object}.${trace.tool_name}` : trace.tool_name;
+				let outcome = "failed or paused";
+				if (trace.success) outcome = trace.output instanceof ThinkSignal ? "paused for attention" : "succeeded";
+				attempts.set(name, (attempts.get(name) ?? 0) + 1);
+				calls.push(`${name}: ${outcome}`);
+			}
+			if (canTalk && trace.type === "yield") deliveredMessages.push({
+				iteration: index + 1,
+				content: trace.value,
+				...traceIndex < lastRestart ? { retracted: true } : {}
+			});
+		}
+		const outcome = describeOutcome(iteration.status);
+		const toolSummary = calls.length ? ` Tool attempts: ${calls.join("; ")}.` : "";
+		history.push(`Iteration ${index + 1}: ${outcome}.${toolSummary}`);
+	}
+	return {
+		history,
+		toolAttempts: Object.fromEntries(attempts),
+		deliveredMessages: canTalk ? deliveredMessages : void 0
+	};
+}
+//#endregion
 //#region src/transcript.ts
 const MAX_MESSAGE_LENGTH = 5e3;
 function getMessagePreview(message) {
@@ -1991,7 +2037,7 @@ const ThinkExit = new Exit({
 */
 const ListenExit = new Exit({
 	name: "listen",
-	description: "Listen to the user and provide a response"
+	description: "Stop talking and wait for the user to talk next."
 });
 /**
 * Default exit used when no custom exits are provided.
@@ -2117,6 +2163,9 @@ var Iteration = class {
 		this._mutations.set(`${mutation.object ?? "global"}:${mutation.property}`, mutation);
 	}
 	_parameters;
+	get components() {
+		return this._parameters.components;
+	}
 	get transcript() {
 		return this._parameters.transcript;
 	}
@@ -2234,6 +2283,7 @@ var Context = class {
 	id;
 	chat;
 	instructions;
+	examples;
 	objects;
 	tools;
 	exits;
@@ -2271,6 +2321,7 @@ var Context = class {
 	transcriptionModel;
 	metadata;
 	snapshot;
+	_lastMessageWithoutExecutionState;
 	iteration = 0;
 	iterations;
 	async nextIteration() {
@@ -2329,18 +2380,20 @@ var Context = class {
 		const tools = countText(parts.tools);
 		const transcript = countText(parts.transcript);
 		const protocol = countText(parts.protocol);
+		const examples = countText(parts.examples);
 		const systemTokens = messages.filter((x) => x.role === "system").reduce((acc, x) => acc + countMessage(x), 0);
 		const otherTokens = messages.filter((x) => x.role !== "system").reduce((acc, x) => acc + countMessage(x), 0);
 		const isFirstIteration = this.iterations.length === 0 && !this.snapshot;
-		const framework = Math.max(0, systemTokens - (instructions + tools + transcript + protocol));
+		const framework = Math.max(0, systemTokens - (instructions + tools + transcript + protocol + examples));
 		const iterations = isFirstIteration ? 0 : otherTokens;
 		return {
-			total: framework + instructions + tools + transcript + protocol + iterations + (isFirstIteration ? otherTokens : 0),
+			total: framework + instructions + tools + transcript + protocol + examples + iterations + (isFirstIteration ? otherTokens : 0),
 			framework: framework + (isFirstIteration ? otherTokens : 0),
 			instructions,
 			tools,
 			transcript,
 			protocol,
+			examples,
 			iterations
 		};
 	}
@@ -2348,24 +2401,50 @@ var Context = class {
 		var _this$snapshot2, _this$snapshot3;
 		const lastIteration = this.iterations.at(-1);
 		const promptProps = {
+			iteration: {
+				current: this.iterations.length + 1,
+				limit: this.loop,
+				resumed: !!this.snapshot,
+				...summarizeIterations(this.iterations, parameters.components.length > 0)
+			},
 			globalTools: parameters.tools,
 			objects: parameters.objects,
 			instructions: parameters.instructions,
+			examples: parameters.examples,
 			transcript: parameters.transcript,
 			exits: parameters.components.length ? [...parameters.exits, ListenExit] : parameters.exits,
 			components: parameters.components
 		};
 		const { message: systemMessage, parts } = await this.version.getSystemMessage(promptProps);
-		const withParts = (messages) => ({
-			messages,
-			parts
-		});
+		const previousLastMessage = this._lastMessageWithoutExecutionState;
+		const withParts = (messages) => {
+			var _this$version$getExec, _this$version;
+			const last = messages.at(-1);
+			this._lastMessageWithoutExecutionState = last;
+			const state = ((_this$version$getExec = (_this$version = this.version).getExecutionState) === null || _this$version$getExec === void 0 ? void 0 : _this$version$getExec.call(_this$version, promptProps)) ?? "";
+			if (state) messages[messages.length - 1] = Array.isArray(last.content) ? {
+				...last,
+				content: [...last.content, {
+					type: "text",
+					text: state.trim()
+				}]
+			} : {
+				...last,
+				content: (last.content ?? "") + state
+			};
+			return {
+				messages,
+				parts
+			};
+		};
 		if (((_this$snapshot2 = this.snapshot) === null || _this$snapshot2 === void 0 ? void 0 : _this$snapshot2.status.type) === "resolved") return withParts([systemMessage, this.version.getSnapshotResolvedMessage({ snapshot: this.snapshot })]);
 		if (((_this$snapshot3 = this.snapshot) === null || _this$snapshot3 === void 0 ? void 0 : _this$snapshot3.status.type) === "rejected") return withParts([systemMessage, this.version.getSnapshotRejectedMessage({ snapshot: this.snapshot })]);
 		if (!lastIteration) return withParts([systemMessage, await this.version.getInitialUserMessage(promptProps)]);
-		const lastIterationMessages = [systemMessage, ...lastIteration.messages.filter((x) => x.role !== "system")];
+		const history = lastIteration.messages.slice();
+		if (previousLastMessage) history[history.length - 1] = previousLastMessage;
+		const lastIterationMessages = [systemMessage, ...history.filter((x) => x.role !== "system")];
 		if ((lastIteration === null || lastIteration === void 0 ? void 0 : lastIteration.status.type) === "thinking_requested") {
-			var _lastIteration$llm;
+			var _lastIteration$llm, _lastIteration$llm2;
 			return withParts([
 				...lastIterationMessages,
 				{
@@ -2377,60 +2456,73 @@ var Context = class {
 					})
 				},
 				await this.version.getThinkingMessage({
+					isChatEnabled: parameters.components.length > 0,
 					reason: lastIteration.status.thinking_requested.reason,
-					variables: lastIteration.status.thinking_requested.variables
+					variables: lastIteration.status.thinking_requested.variables,
+					interrupted: lastIteration.status.thinking_requested.interrupted,
+					discardedMessages: (_lastIteration$llm2 = lastIteration.llm) === null || _lastIteration$llm2 === void 0 || (_lastIteration$llm2 = _lastIteration$llm2.diagnostics) === null || _lastIteration$llm2 === void 0 ? void 0 : _lastIteration$llm2.some((diagnostic) => diagnostic.code === "send-after-run")
 				})
 			]);
 		}
 		if ((lastIteration === null || lastIteration === void 0 ? void 0 : lastIteration.status.type) === "exit_error") {
-			var _lastIteration$llm2;
+			var _lastIteration$llm3;
 			return withParts([
 				...lastIterationMessages,
 				{
 					role: "assistant",
-					content: wrapContent(((_lastIteration$llm2 = lastIteration.llm) === null || _lastIteration$llm2 === void 0 ? void 0 : _lastIteration$llm2.output) ?? "", {
+					content: wrapContent(((_lastIteration$llm3 = lastIteration.llm) === null || _lastIteration$llm3 === void 0 ? void 0 : _lastIteration$llm3.output) ?? "", {
 						preserve: "top",
 						flex: 4,
 						minTokens: 25
 					})
 				},
 				await this.version.getInvalidCodeMessage({
-					code: lastIteration.code ?? "// No code generated",
-					message: `Invalid return statement (action: ${lastIteration.status.exit_error.exit}): ${lastIteration.status.exit_error.message}`
+					isChatEnabled: parameters.components.length > 0,
+					code: lastIteration.next ? `■next=${lastIteration.next.name} ${JSON.stringify(lastIteration.next.props)}` : lastIteration.code ?? "// No code generated",
+					message: `Invalid ■next block (${lastIteration.status.exit_error.exit}): ${lastIteration.status.exit_error.message}`
 				})
 			]);
 		}
 		if ((lastIteration === null || lastIteration === void 0 ? void 0 : lastIteration.status.type) === "invalid_code_error") {
-			var _lastIteration$llm3;
+			var _lastIteration$llm4;
 			return withParts([
 				...lastIterationMessages,
 				{
 					role: "assistant",
-					content: wrapContent(((_lastIteration$llm3 = lastIteration.llm) === null || _lastIteration$llm3 === void 0 ? void 0 : _lastIteration$llm3.output) ?? "", {
+					content: wrapContent(((_lastIteration$llm4 = lastIteration.llm) === null || _lastIteration$llm4 === void 0 ? void 0 : _lastIteration$llm4.output) ?? "", {
 						preserve: "top",
 						flex: 4,
 						minTokens: 25
 					})
 				},
 				await this.version.getInvalidCodeMessage({
+					isChatEnabled: parameters.components.length > 0,
 					code: lastIteration.code ?? "// No code generated",
 					message: lastIteration.status.invalid_code_error.message
 				})
 			]);
 		}
 		if ((lastIteration === null || lastIteration === void 0 ? void 0 : lastIteration.status.type) === "execution_error") {
-			var _lastIteration$llm4;
+			var _lastIteration$llm5;
 			return withParts([
 				...lastIterationMessages,
 				{
 					role: "assistant",
-					content: wrapContent(((_lastIteration$llm4 = lastIteration.llm) === null || _lastIteration$llm4 === void 0 ? void 0 : _lastIteration$llm4.output) ?? "", {
+					content: wrapContent(((_lastIteration$llm5 = lastIteration.llm) === null || _lastIteration$llm5 === void 0 ? void 0 : _lastIteration$llm5.output) ?? "", {
 						preserve: "top",
 						flex: 4,
 						minTokens: 25
 					})
 				},
 				await this.version.getCodeExecutionErrorMessage({
+					isChatEnabled: parameters.components.length > 0,
+					variables: lastIteration.variables,
+					toolCalls: lastIteration.traces.filter((trace) => trace.type === "tool_call").map((trace) => ({
+						tool: trace.tool_name,
+						input: trace.input,
+						success: trace.success,
+						...trace.success ? { output: trace.output } : { error: getErrorMessage(trace.error) }
+					})),
 					message: lastIteration.status.execution_error.message,
 					stacktrace: lastIteration.status.execution_error.stack
 				})
@@ -2441,6 +2533,7 @@ var Context = class {
 	async _refreshIterationParameters() {
 		var _this$chat, _this$chat2;
 		const instructions = await getValue(this.instructions, this);
+		const examples = await getValue(this.examples, this);
 		const transcript = new TranscriptArray(await getValue(((_this$chat = this.chat) === null || _this$chat === void 0 ? void 0 : _this$chat.transcript) ?? [], this));
 		const tools = Tool.withUniqueNames(await getValue(this.tools, this) ?? []);
 		const objects = await getValue(this.objects, this) ?? [];
@@ -2497,6 +2590,7 @@ var Context = class {
 			objects,
 			exits,
 			instructions,
+			examples,
 			components,
 			model,
 			temperature,
@@ -2506,6 +2600,7 @@ var Context = class {
 	constructor(props) {
 		this.id = `llmz_${ulid()}`;
 		this.instructions = props.instructions;
+		this.examples = props.examples;
 		this.objects = props.objects;
 		this.tools = props.tools;
 		this.exits = props.exits;