llmz 0.6.5 → 0.6.7

package/DOCS.md

@@ -1582,30 +1582,94 @@ await execute({
 
 ---
 
-### Buffered Delivery (midStreamFallback)
+### Mid-Stream Model Fallback (midStreamFallback)
 
-By default, LLMz streams responses: send blocks are dispatched as soon as they are parsed, and the ■run block starts executing while the model is still generating the rest of the response. This gives the lowest time-to-first-token but runs code before the response is complete.
+By default, LLMz streams responses: message bodies (`■send` blocks) and completed `Chat.handler` sends are dispatched as soon as they are produced, and the ■run block starts executing while the model is still generating the rest of the response. This gives the lowest time-to-first-token but runs code before the response is complete.
 
-Set `options.midStreamFallback: true` to allow Cognitive to restart a failed stream on another model safely. LLMz buffers delivery and discards all content from abandoned attempts:
+Set `options.midStreamFallback: true` to allow Cognitive to restart a failed stream on another model. There is **no buffered delivery and no final delivery queue**: with fallback enabled, delta text and completed `Chat.handler` sends both stream immediately during generation. Only **TOOL/CODE execution** waits for a stream to complete successfully. When Cognitive abandons an attempt, a reset-only delta (`restart: true`) is delivered through the existing `Chat.onMessageDelta`; it invalidates **all** messages of the current iteration — **including messages already committed through `handler`** — so consumers must retract and replace them:
 
 ```typescript
 await execute({
   // ...
+  chat: new MyChat({
+    onMessageDelta: (delta) => {
+      if (delta.restart) {
+        // invalidates ALL current-iteration messages, including completed handler
+        // sends: retract/replace them before the replacement streams
+        return retractIteration(delta.iterationId)
+      } else {
+        // stream this message's text as it arrives (same iterationId as below)
+        updateMessage(delta)
+      }
+    },
+  }),
   options: { midStreamFallback: true },
 })
 ```
 
-When enabled, the runtime buffers the full generated response and only dispatches it (sends and code execution) once the stream has finished. Trade-offs:
+`retractIteration`/`updateMessage` are placeholder names for your consumer's message store. **This option is not safe to enable blindly**: a reset invalidates messages that were already delivered through `handler`. If your transport cannot retract or replace an already-sent message — an external irreversible send such as SMS, email, or a third-party webhook — those sends cannot be undone, so keep `midStreamFallback` disabled unless your consumer can retract and replace invalidated messages.
+
+#### MessageDelta contract
+
+`Chat.onMessageDelta` receives a single typed `MessageDelta` discriminated union:
+
+- **Ordinary text chunk** (`restart: false`) — the next piece of one message's body; all fields are required:
+  ```typescript
+  {
+    restart: false,
+    iterationId: string, // stable across ALL attempts of this LLM generation iteration
+    id: string, // message id — DIFFERENT per attempt (unique when fallback is on)
+    component: string,
+    props: Record<string, unknown>, // final by the time the body starts streaming
+    delta: string, // new chunk of body text
+    content: string, // full body text accumulated so far, including this chunk
+  }
+  ```
+- **Reset-only delta** (`restart: true`) — carries no text; signals the current generation attempt was abandoned and a replacement is being attempted:
+  ```typescript
+  {
+    restart: true,
+    iterationId: string, // the iteration whose messages (incl. handler sends) must be retracted/replaced
+    attempt: number,
+    fromModel: string,
+    toModel: string,
+    reason: string,
+  }
+  ```
+
+IDs: `iterationId` is **stable across attempts** — every restart of the same iteration keeps the same `iterationId` — while `id` is **different per attempt**. After a reset, replacement chunks arrive under new `id`s within the same `iterationId`.
+
+Consumer rules:
+
+- On `restart: true`, retract/replace **all** current-iteration messages bearing that `iterationId` — streamed text **and** messages already delivered through `handler`.
+- On an ordinary chunk, update the message for `delta.id` (create it if new, otherwise append).
+- A reset is emitted and awaited **before** replacement output begins, **even if the replacement yields no message at all**. Return/await the retraction promise in your handler. If it throws or rejects, generation fails without delivering replacement output or executing code; ordinary text-preview errors remain best-effort.
+- A reset only invalidates the messages of its own `iterationId`; it **never** invalidates messages from earlier, completed iterations.
+- Only TOOL/CODE execution is gated on a successful stream: generated code and tool calls never run from an abandoned attempt.
+
+Outside of fallback (the default), `onMessageDelta` behavior is unchanged: ordinary chunks carry `iterationId`/`id`/`component`/`props`/`delta`/`content` with a single stable message id, and no restart/reset deltas are produced.
+
+#### Completed-send correlation
+
+`Chat.handler(component, metadata)` receives `{ iterationId: string, id: string }` for **every send**, including empty-body and non-text components, without requiring `onMessageDelta`. For streamed messages, `metadata.id` matches the text delta's `id`; it changes across attempts while `iterationId` stays stable. Existing one-argument handlers continue to work.
+
+Record **all** persisted message IDs created while awaiting that handler under its metadata (one component may produce multiple persisted messages). A restart can then retract everything for the matching iteration, even after a message's stream tracking has completed. Non-streaming sends also receive metadata. Tool-yielded messages get unique per-yield IDs and the runtime iteration ID; standalone `Tool.execute` calls without an iteration use their `callId` as the scope.
+
+#### Migrating consumers
+
+- **No final delivery queue**: messages are not withheld until the stream ends. Deltas and completed `handler` sends arrive during generation; drop any "promote on success" design — treat every delivered message as provisional until the iteration completes without a reset.
+- **Retract, don't just clear previews**: on `restart: true`, retraction must cascade to every current-iteration message, including ones already committed through `handler`. If your UI or transport cannot do that, keep `midStreamFallback` disabled.
+- **Clear on errors and cancellation**: a failed or cancelled generation can leave current-iteration messages on screen, incomplete, or unresettable. Explicitly clear/roll back current-iteration state when execution errors or ends — there is no exactly-once guarantee, and caller retries can duplicate effects.
+- **Irreversible transports**: external sends that cannot be undone (SMS, email, webhooks) must not blindly enable fallback without a reset-capable gateway.
+
+#### Caveats
 
-- **Latency**: higher time-to-first-send/token, since nothing is delivered until the response completes.
-- **No early code**: the VM is not run mid-stream; code executes only after the full response is parsed.
-- **Cancellation**: cancellation still aborts the original generation request as usual.
 - **No extra retry loop**: Cognitive owns fallback, bounded by the model chain. LLMz does not retry abandoned attempts itself.
-- **Not exactly-once**: abandoned attempts deliver nothing, but successful-attempt callbacks cannot be rolled back if delivery fails or cancellation arrives during delivery. Caller retries can duplicate effects.
+- **Cancellation**: cancellation still aborts the original generation request as usual; consumers must clear current-iteration state on abort (see above). Cancellation deadlines are not reset, and the existing stream inactivity guard remains active during handoffs.
 
-This option defaults to false and applies only to streaming clients. Non-streaming Cognitive requests already fall back transparently. It can be combined with `maxTimeToFirstToken` and `transcriptionModel`; do not enable it globally underneath LLMz without also enabling LLMz's buffering option.
+This option defaults to false and applies only to streaming clients. Non-streaming Cognitive requests already fall back transparently. It can be combined with `maxTimeToFirstToken` and `transcriptionModel`; do not enable it globally underneath LLMz without also enabling LLMz's fallback option and a reset-capable consumer.
 
-Restarts emit `llm_call_restarted` traces with the attempt, source/destination models, and reason. Token timings remain relative to the original request and describe the surviving attempt (including time spent on prior attempts). Usage and cost retain Cognitive's final reported metadata; LLMz does not infer or sum abandoned-attempt billing. Cancellation deadlines are not reset, and the existing stream inactivity guard remains active during handoffs.
+Restarts emit `llm_call_restarted` traces with the attempt, source/destination models, and reason. Token timings remain relative to the original request and describe the surviving attempt (including time spent on prior attempts). Usage and cost retain Cognitive's final reported metadata; LLMz does not infer or sum abandoned-attempt billing.
 
 ## API Reference
 

package/dist/chat.d.ts

@@ -24,7 +24,14 @@ import { TranscriptArray, Transcript } from './transcript.js';
  * }
  * ```
  */
-export type MessageHandler = (input: RenderedComponent) => Promise<void> | void;
+/** Correlates every generated send with its deltas and restart scope. */
+export type MessageMetadata = {
+    /** Stable across generation attempts; standalone tool calls use their callId. */
+    iterationId: string;
+    /** Logical send ID; matches MessageDelta.id when text deltas exist. Unique across attempts. */
+    id: string;
+};
+export type MessageHandler = (input: RenderedComponent, metadata: MessageMetadata) => Promise<void> | void;
 /**
  * A chunk of a message body streamed live from the LLM, before the message is complete.
  *
@@ -32,10 +39,14 @@ export type MessageHandler = (input: RenderedComponent) => Promise<void> | void;
  * Each chunk is forwarded to {@link Chat} `onMessageDelta` as soon as it is parsed, so the
  * client can render the message progressively (e.g. typewriter effect in a chat UI).
  *
- * The complete message is always delivered to the regular `handler` afterwards — deltas
- * are a progressive preview, the `handler` call remains the authoritative delivery.
+ * In mid-stream fallback mode, both deltas and completed `handler` messages
+ * are live and retractable: restart deltas invalidate every message from that
+ * iteration. Consumers must retract them; only code execution waits for success.
  */
 export type MessageDelta = {
+    restart: false;
+    /** Generation whose provisional messages must be cleared on a restart. */
+    iterationId: string;
     /** Identifies the message being streamed. Unique within an `execute()` call. */
     id: string;
     /** Component name of the message being streamed (e.g. 'message', 'button'). */
@@ -46,10 +57,24 @@ export type MessageDelta = {
     delta: string;
     /** The full body text accumulated so far, including this chunk. */
     content: string;
+} | {
+    /**
+     * Reset-only delta, emitted before replacement text (even if none follows).
+     * Clear ALL messages for iterationId, including completed `handler` sends.
+     * Other iterations are unaffected. Irreversible sends cannot be undone.
+     */
+    restart: true;
+    iterationId: string;
+    /** 1-based index of the new attempt. */
+    attempt: number;
+    fromModel: string;
+    toModel: string;
+    reason: string;
 };
 /**
  * Function type for handling message chunks as they are streamed from the LLM.
- * Errors thrown by this handler are ignored — streaming previews are best-effort.
+ * Text-preview errors are ignored. Restart-handler errors stop generation:
+ * replacement output must not be delivered if retraction fails.
  */
 export type MessageDeltaHandler = (delta: MessageDelta) => Promise<void> | void;
 /**

package/dist/context.d.ts

@@ -565,8 +565,14 @@ export declare class Context implements Serializable<Context.JSON> {
      */
     maxTimeToFirstToken?: number;
     /**
-     * Allow Cognitive mid-stream fallback, buffering delivery until generation
-     * succeeds and discarding abandoned attempts. Streaming-only; defaults to false.
+     * Allow Cognitive to restart a failed stream on another model. With fallback
+     * enabled, there is no buffered delivery and no final delivery queue: delta
+     * text and completed Chat.handler sends stream immediately during generation.
+     * A reset-only delta (restart: true) on Chat.onMessageDelta invalidates ALL
+     * current-iteration messages, including completed sends — consumers must
+     * retract/replace them, which is unsafe for irreversible external transports.
+     * Only TOOL/CODE execution waits for a successful stream. Streaming-only;
+     * defaults to false, which leaves progressive sending unchanged.
      */
     midStreamFallback?: boolean;
     /**

package/dist/{custom-client-BnlDpjdI.js → custom-client-CJIThG2H.js}

@@ -4,7 +4,7 @@ import { f as flatRest, l as extractType, m as baseCreate, p as copyArray, t as
 import { _ as getSymbolsIn, b as keysIn, g as getAllKeysIn, 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 { t as Tool } from "./tool-CAo-BQHs.js";
+import { t as Tool } from "./tool-Bv8N4IPj.js";
 import { o as LoopExceededError } from "./errors-Cg1G0Awu.js";
 import { t as Exit } from "./exit-CDdxDBRT.js";
 import { n as assertValidComponent } from "./component-DGG7d_Mz.js";
@@ -2254,8 +2254,14 @@ var Context = class {
 	*/
 	maxTimeToFirstToken;
 	/**
-	* Allow Cognitive mid-stream fallback, buffering delivery until generation
-	* succeeds and discarding abandoned attempts. Streaming-only; defaults to false.
+	* Allow Cognitive to restart a failed stream on another model. With fallback
+	* enabled, there is no buffered delivery and no final delivery queue: delta
+	* text and completed Chat.handler sends stream immediately during generation.
+	* A reset-only delta (restart: true) on Chat.onMessageDelta invalidates ALL
+	* current-iteration messages, including completed sends — consumers must
+	* retract/replace them, which is unsafe for irreversible external transports.
+	* Only TOOL/CODE execution waits for a successful stream. Streaming-only;
+	* defaults to false, which leaves progressive sending unchanged.
 	*/
 	midStreamFallback;
 	/**

package/dist/{custom-client-BX8gx0tI.cjs → custom-client-Cr33K60k.cjs}

@@ -4,7 +4,7 @@ const require_dual_modes = require("./dual-modes-wAOAlaBS.cjs");
 const require_utils = require("./utils-ZpJm00ed.cjs");
 const require__getPrototype = require("./_getPrototype-DQDlNVVM.cjs");
 const require_isPlainObject = require("./isPlainObject-CSxXVKCk.cjs");
-const require_tool = require("./tool-DdPZb0JW.cjs");
+const require_tool = require("./tool-ReA9gxMp.cjs");
 const require_errors = require("./errors-C962uJdS.cjs");
 const require_exit = require("./exit-BGi0Kk0y.cjs");
 const require_component = require("./component-BwixNVH8.cjs");
@@ -2254,8 +2254,14 @@ var Context = class {
 	*/
 	maxTimeToFirstToken;
 	/**
-	* Allow Cognitive mid-stream fallback, buffering delivery until generation
-	* succeeds and discarding abandoned attempts. Streaming-only; defaults to false.
+	* Allow Cognitive to restart a failed stream on another model. With fallback
+	* enabled, there is no buffered delivery and no final delivery queue: delta
+	* text and completed Chat.handler sends stream immediately during generation.
+	* A reset-only delta (restart: true) on Chat.onMessageDelta invalidates ALL
+	* current-iteration messages, including completed sends — consumers must
+	* retract/replace them, which is unsafe for irreversible external transports.
+	* Only TOOL/CODE execution waits for a successful stream. Streaming-only;
+	* defaults to false, which leaves progressive sending unchanged.
 	*/
 	midStreamFallback;
 	/**

package/dist/{execute-BJF4Txh2.cjs → execute-BmEjJjka.cjs}

@@ -1,6 +1,6 @@
 const require__baseForOwn = require("./_baseForOwn-buOZDFbK.cjs");
 const require_dual_modes = require("./dual-modes-wAOAlaBS.cjs");
-const require_custom_client = require("./custom-client-BX8gx0tI.cjs");
+const require_custom_client = require("./custom-client-Cr33K60k.cjs");
 const require_utils = require("./utils-ZpJm00ed.cjs");
 const require_jsx = require("./jsx-BWvT6ukg.cjs");
 const require_stack_traces = require("./stack-traces-ntw_qhoy.cjs");
@@ -197,11 +197,18 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 	/** Milliseconds between the stream request and the first/last streamed tokens. */
 	let timeToFirstToken;
 	let timeToLastToken;
-	const bufferedDelivery = ctx.midStreamFallback === true;
-	let pendingDeliveries = [];
-	const deliver = async (callback) => {
-		if (bufferedDelivery) pendingDeliveries.push(callback);
-		else await callback();
+	const midStreamFallback = ctx.midStreamFallback === true;
+	let attempt = 1;
+	const messageMetadata = (itemId) => ({
+		iterationId: iteration.id,
+		id: midStreamFallback ? `${iteration.id}:${attempt}:${itemId}` : `${iteration.id}:${itemId}`
+	});
+	const preview = async (delta) => {
+		try {
+			await (onSendDelta === null || onSendDelta === void 0 ? void 0 : onSendDelta(delta));
+		} catch (err) {
+			if (delta.restart) throw new require_errors.CognitiveError(`LLM stream restart handler failed: ${require_utils.getErrorMessage(err)}`);
+		}
 	};
 	const liveItems = /* @__PURE__ */ new Map();
 	const liveContent = /* @__PURE__ */ new Map();
@@ -212,14 +219,11 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			liveItems.set(event.item.id, event.item);
 			if (event.item.kind === "run" && !codeGenerationTraced) {
 				codeGenerationTraced = true;
-				const started_at = Date.now();
-				await deliver(() => {
-					traces.push({
-						type: "code_generation_started",
-						started_at
-					});
-					onRunStart === null || onRunStart === void 0 || onRunStart();
+				traces.push({
+					type: "code_generation_started",
+					started_at: Date.now()
 				});
+				onRunStart === null || onRunStart === void 0 || onRunStart();
 			}
 		} else if (event.type === "body-delta" && onSendDelta) {
 			const item = liveItems.get(event.itemId);
@@ -227,29 +231,24 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			const content = (liveContent.get(item.id) ?? "") + event.delta;
 			liveContent.set(item.id, content);
 			const delta = {
-				id: `${iteration.id}:${item.id}`,
+				restart: false,
+				...messageMetadata(item.id),
 				component: item.name,
-				props: bufferedDelivery ? structuredClone(item.props) : item.props,
+				props: item.props,
 				delta: event.delta,
 				content
 			};
-			await deliver(async () => {
-				try {
-					await onSendDelta(delta);
-				} catch (err) {}
-			});
+			await preview(delta);
 		} else if (event.type === "item-complete") {
-			if (event.item.kind === "send" && onSend) {
-				const send = {
-					name: event.item.name,
-					props: bufferedDelivery ? structuredClone(event.item.props) : event.item.props,
-					body: event.item.body
-				};
-				await deliver(() => onSend(send));
-			} else if (event.item.kind === "run" && event.item.status === "complete" && !runCompleted) {
+			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();
-				await deliver(() => onRunComplete === null || onRunComplete === void 0 ? void 0 : onRunComplete(code));
+				onRunComplete === null || onRunComplete === void 0 || onRunComplete(code);
 			}
 		}
 	};
@@ -260,10 +259,10 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 		const requestedAt = Date.now();
 		const stream = cognitive.generateTextStream({
 			...input,
-			...ctx.maxTimeToFirstToken || bufferedDelivery ? { options: {
+			...ctx.maxTimeToFirstToken || midStreamFallback ? { options: {
 				...input.options,
 				...ctx.maxTimeToFirstToken ? { maxTimeToFirstToken: ctx.maxTimeToFirstToken } : {},
-				...bufferedDelivery ? { midStreamFallback: true } : {}
+				...midStreamFallback ? { midStreamFallback: true } : {}
 			} } : {}
 		}, { signal: streamController.signal });
 		const inactivityTimeout = Math.max(STREAM_INACTIVITY_TIMEOUT, ctx.maxTimeToFirstToken ?? 0);
@@ -296,7 +295,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 					streamCompleted = true;
 					break;
 				}
-				if (((_chunk$value = chunk.value) === null || _chunk$value === void 0 ? void 0 : _chunk$value.restart) && !bufferedDelivery) {
+				if (((_chunk$value = chunk.value) === null || _chunk$value === void 0 ? void 0 : _chunk$value.restart) && !midStreamFallback) {
 					streamController.abort("Unexpected LLM stream restart");
 					throw new require_errors.CognitiveError("LLM stream restarted without options.midStreamFallback enabled");
 				}
@@ -311,10 +310,15 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 					fence = new LeadingFenceFilter();
 					liveItems.clear();
 					liveContent.clear();
-					pendingDeliveries = [];
 					codeGenerationTraced = false;
 					runCompleted = false;
 					responseMetadata = void 0;
+					attempt = chunk.value.restart.attempt;
+					await preview({
+						...chunk.value.restart,
+						restart: true,
+						iterationId: iteration.id
+					});
 					timeToFirstToken = void 0;
 					timeToLastToken = void 0;
 					continue;
@@ -334,16 +338,9 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			assistantResponse = require_dual_modes.toParsedAssistantResponse(parser.items, raw);
 		} finally {
 			streamController.abort("LLM stream closed");
-			if (!streamCompleted) stream.return(void 0).catch(() => {});
-		}
-		if (bufferedDelivery) {
-			controller.signal.throwIfAborted();
-			for (const callback of pendingDeliveries) {
-				controller.signal.throwIfAborted();
-				await callback();
-			}
-			pendingDeliveries = [];
+			if (!streamCompleted) stream.return(void 0).catch((err) => {});
 		}
+		if (midStreamFallback) controller.signal.throwIfAborted();
 	} else {
 		const response = await cognitive.generateText(input, { signal: controller.signal }).catch((thrown) => {
 			throw new require_errors.CognitiveError(`LLM generation failed: ${require_utils.getErrorMessage(thrown)}`);
@@ -352,7 +349,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 		responseMetadata = response.metadata;
 		raw = response.output;
 		assistantResponse = ctx.version.parseAssistantResponse(raw);
-		for (const send of assistantResponse.sends) await (onSend === null || onSend === void 0 ? void 0 : onSend(send));
+		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;
 	iteration.sends = assistantResponse.sends;
@@ -628,7 +625,10 @@ function wrapTool({ chat, tool, traces, object, iteration, beforeHook, afterHook
 				toolCallId
 			}));
 			if (typeof (beforeRes === null || beforeRes === void 0 ? void 0 : beforeRes.input) !== "undefined") effectiveInput = beforeRes.input;
-			output = await tool.execute(effectiveInput, { callId: toolCallId }, chat);
+			output = await tool.execute(effectiveInput, {
+				callId: toolCallId,
+				iterationId: iteration.id
+			}, chat);
 			const afterRes = await (afterHook === null || afterHook === void 0 ? void 0 : afterHook({
 				iteration,
 				tool,
@@ -959,7 +959,7 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 				promise: runCode(code)
 			};
 		} : void 0,
-		onSend: async (send) => {
+		onSend: async (send, messageMetadata) => {
 			if (!ctx.chat) return;
 			const sendStartedAt = Date.now();
 			const component = require_jsx.createJsxComponent({
@@ -968,7 +968,7 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 				children: send.body ? [send.body] : []
 			});
 			try {
-				await ctx.chat.handler(component);
+				await ctx.chat.handler(component, messageMetadata);
 			} catch (err) {
 				throw new Error(`Error while sending message (■send=${send.name}): ${require_utils.getErrorMessage(err)}`);
 			}

package/dist/{execute-BjBBTshA.js → execute-sn9RT_IN.js}

@@ -1,5 +1,5 @@
 import { a as StreamingMessageParser, d as isEqual, h as toNumber, i as toParsedAssistantResponse } from "./dual-modes-D_p-jedw.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-BnlDpjdI.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-CJIThG2H.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";
@@ -195,11 +195,18 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 	/** Milliseconds between the stream request and the first/last streamed tokens. */
 	let timeToFirstToken;
 	let timeToLastToken;
-	const bufferedDelivery = ctx.midStreamFallback === true;
-	let pendingDeliveries = [];
-	const deliver = async (callback) => {
-		if (bufferedDelivery) pendingDeliveries.push(callback);
-		else await callback();
+	const midStreamFallback = ctx.midStreamFallback === true;
+	let attempt = 1;
+	const messageMetadata = (itemId) => ({
+		iterationId: iteration.id,
+		id: midStreamFallback ? `${iteration.id}:${attempt}:${itemId}` : `${iteration.id}:${itemId}`
+	});
+	const preview = async (delta) => {
+		try {
+			await (onSendDelta === null || onSendDelta === void 0 ? void 0 : onSendDelta(delta));
+		} catch (err) {
+			if (delta.restart) throw new CognitiveError(`LLM stream restart handler failed: ${getErrorMessage(err)}`);
+		}
 	};
 	const liveItems = /* @__PURE__ */ new Map();
 	const liveContent = /* @__PURE__ */ new Map();
@@ -210,14 +217,11 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			liveItems.set(event.item.id, event.item);
 			if (event.item.kind === "run" && !codeGenerationTraced) {
 				codeGenerationTraced = true;
-				const started_at = Date.now();
-				await deliver(() => {
-					traces.push({
-						type: "code_generation_started",
-						started_at
-					});
-					onRunStart === null || onRunStart === void 0 || onRunStart();
+				traces.push({
+					type: "code_generation_started",
+					started_at: Date.now()
 				});
+				onRunStart === null || onRunStart === void 0 || onRunStart();
 			}
 		} else if (event.type === "body-delta" && onSendDelta) {
 			const item = liveItems.get(event.itemId);
@@ -225,29 +229,24 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			const content = (liveContent.get(item.id) ?? "") + event.delta;
 			liveContent.set(item.id, content);
 			const delta = {
-				id: `${iteration.id}:${item.id}`,
+				restart: false,
+				...messageMetadata(item.id),
 				component: item.name,
-				props: bufferedDelivery ? structuredClone(item.props) : item.props,
+				props: item.props,
 				delta: event.delta,
 				content
 			};
-			await deliver(async () => {
-				try {
-					await onSendDelta(delta);
-				} catch (err) {}
-			});
+			await preview(delta);
 		} else if (event.type === "item-complete") {
-			if (event.item.kind === "send" && onSend) {
-				const send = {
-					name: event.item.name,
-					props: bufferedDelivery ? structuredClone(event.item.props) : event.item.props,
-					body: event.item.body
-				};
-				await deliver(() => onSend(send));
-			} else if (event.item.kind === "run" && event.item.status === "complete" && !runCompleted) {
+			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();
-				await deliver(() => onRunComplete === null || onRunComplete === void 0 ? void 0 : onRunComplete(code));
+				onRunComplete === null || onRunComplete === void 0 || onRunComplete(code);
 			}
 		}
 	};
@@ -258,10 +257,10 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 		const requestedAt = Date.now();
 		const stream = cognitive.generateTextStream({
 			...input,
-			...ctx.maxTimeToFirstToken || bufferedDelivery ? { options: {
+			...ctx.maxTimeToFirstToken || midStreamFallback ? { options: {
 				...input.options,
 				...ctx.maxTimeToFirstToken ? { maxTimeToFirstToken: ctx.maxTimeToFirstToken } : {},
-				...bufferedDelivery ? { midStreamFallback: true } : {}
+				...midStreamFallback ? { midStreamFallback: true } : {}
 			} } : {}
 		}, { signal: streamController.signal });
 		const inactivityTimeout = Math.max(STREAM_INACTIVITY_TIMEOUT, ctx.maxTimeToFirstToken ?? 0);
@@ -294,7 +293,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 					streamCompleted = true;
 					break;
 				}
-				if (((_chunk$value = chunk.value) === null || _chunk$value === void 0 ? void 0 : _chunk$value.restart) && !bufferedDelivery) {
+				if (((_chunk$value = chunk.value) === null || _chunk$value === void 0 ? void 0 : _chunk$value.restart) && !midStreamFallback) {
 					streamController.abort("Unexpected LLM stream restart");
 					throw new CognitiveError("LLM stream restarted without options.midStreamFallback enabled");
 				}
@@ -309,10 +308,15 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 					fence = new LeadingFenceFilter();
 					liveItems.clear();
 					liveContent.clear();
-					pendingDeliveries = [];
 					codeGenerationTraced = false;
 					runCompleted = false;
 					responseMetadata = void 0;
+					attempt = chunk.value.restart.attempt;
+					await preview({
+						...chunk.value.restart,
+						restart: true,
+						iterationId: iteration.id
+					});
 					timeToFirstToken = void 0;
 					timeToLastToken = void 0;
 					continue;
@@ -332,16 +336,9 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 			assistantResponse = toParsedAssistantResponse(parser.items, raw);
 		} finally {
 			streamController.abort("LLM stream closed");
-			if (!streamCompleted) stream.return(void 0).catch(() => {});
-		}
-		if (bufferedDelivery) {
-			controller.signal.throwIfAborted();
-			for (const callback of pendingDeliveries) {
-				controller.signal.throwIfAborted();
-				await callback();
-			}
-			pendingDeliveries = [];
+			if (!streamCompleted) stream.return(void 0).catch((err) => {});
 		}
+		if (midStreamFallback) controller.signal.throwIfAborted();
 	} else {
 		const response = await cognitive.generateText(input, { signal: controller.signal }).catch((thrown) => {
 			throw new CognitiveError(`LLM generation failed: ${getErrorMessage(thrown)}`);
@@ -350,7 +347,7 @@ const generateCode = async ({ iteration, ctx, cognitive, controller, metadata, o
 		responseMetadata = response.metadata;
 		raw = response.output;
 		assistantResponse = ctx.version.parseAssistantResponse(raw);
-		for (const send of assistantResponse.sends) await (onSend === null || onSend === void 0 ? void 0 : onSend(send));
+		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;
 	iteration.sends = assistantResponse.sends;
@@ -626,7 +623,10 @@ function wrapTool({ chat, tool, traces, object, iteration, beforeHook, afterHook
 				toolCallId
 			}));
 			if (typeof (beforeRes === null || beforeRes === void 0 ? void 0 : beforeRes.input) !== "undefined") effectiveInput = beforeRes.input;
-			output = await tool.execute(effectiveInput, { callId: toolCallId }, chat);
+			output = await tool.execute(effectiveInput, {
+				callId: toolCallId,
+				iterationId: iteration.id
+			}, chat);
 			const afterRes = await (afterHook === null || afterHook === void 0 ? void 0 : afterHook({
 				iteration,
 				tool,
@@ -957,7 +957,7 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 				promise: runCode(code)
 			};
 		} : void 0,
-		onSend: async (send) => {
+		onSend: async (send, messageMetadata) => {
 			if (!ctx.chat) return;
 			const sendStartedAt = Date.now();
 			const component = createJsxComponent({
@@ -966,7 +966,7 @@ const executeIteration = async ({ iteration, ctx, cognitive, controller, onExit,
 				children: send.body ? [send.body] : []
 			});
 			try {
-				await ctx.chat.handler(component);
+				await ctx.chat.handler(component, messageMetadata);
 			} catch (err) {
 				throw new Error(`Error while sending message (■send=${send.name}): ${getErrorMessage(err)}`);
 			}

package/dist/index.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_dual_modes = require("./dual-modes-wAOAlaBS.cjs");
-const require_custom_client = require("./custom-client-BX8gx0tI.cjs");
+const require_custom_client = require("./custom-client-Cr33K60k.cjs");
 const require_utils = require("./utils-ZpJm00ed.cjs");
-const require_tool = require("./tool-DdPZb0JW.cjs");
+const require_tool = require("./tool-ReA9gxMp.cjs");
 const require_errors = require("./errors-C962uJdS.cjs");
 const require_typings = require("./typings-BwAz_TM9.cjs");
 const require_exit = require("./exit-BGi0Kk0y.cjs");
@@ -11,7 +11,7 @@ const require_truncator = require("./truncator-B6aaJaN1.cjs");
 const require_quickjs_variant = require("./quickjs-variant-CsIwTVFC.cjs");
 let _bpinternal_zui = require("@bpinternal/zui");
 //#region package.json
-var version = "0.6.5";
+var version = "0.6.7";
 //#endregion
 //#region src/hoist.ts
 /**
@@ -1774,7 +1774,7 @@ const utils = {
 * })
 */
 const execute = async (props) => {
-	const { executeContext } = await Promise.resolve().then(() => require("./execute-BJF4Txh2.cjs"));
+	const { executeContext } = await Promise.resolve().then(() => require("./execute-BmEjJjka.cjs"));
 	return executeContext(props);
 };
 /**
@@ -1783,9 +1783,9 @@ const execute = async (props) => {
 * It's recommended to call this function at the beginning of your application without awaiting it (void init())
 */
 const init = async () => {
-	await Promise.resolve().then(() => require("./execute-BJF4Txh2.cjs"));
+	await Promise.resolve().then(() => require("./execute-BmEjJjka.cjs"));
 	await Promise.resolve().then(() => require("./component-BwixNVH8.cjs")).then((n) => n.component_exports);
-	await Promise.resolve().then(() => require("./tool-DdPZb0JW.cjs")).then((n) => n.tool_exports);
+	await Promise.resolve().then(() => require("./tool-ReA9gxMp.cjs")).then((n) => n.tool_exports);
 	await Promise.resolve().then(() => require("./exit-BGi0Kk0y.cjs")).then((n) => n.exit_exports);
 	await Promise.resolve().then(() => require("./jsx-BWvT6ukg.cjs")).then((n) => n.jsx_exports);
 	await Promise.resolve().then(() => require("./vm-BjkJqSQH.cjs"));

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { Component, type RenderedComponent, type LeafComponentDefinition, type C
 export { type Citation, CitationsManager } from './citations.js';
 export { DefaultComponents } from './component.default.js';
 export { Snapshot } from './snapshots.js';
-export { Chat, type MessageHandler, type MessageDelta, type MessageDeltaHandler } from './chat.js';
+export { Chat, type MessageHandler, type MessageMetadata, type MessageDelta, type MessageDeltaHandler } from './chat.js';
 import { ExecutionResult } from './result.js';
 import { type ExecutionProps } from './runtime/types.js';
 import { stripTruncationTags, truncateWrappedContent, wrapContent } from './truncator.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 import { a as StreamingMessageParser, c as NAME_REGEX, o as tryParseJson, r as generateInstructions, s as MARKER } from "./dual-modes-D_p-jedw.js";
-import { a as ThinkExit, c as ExecutionResult, d as Snapshot, f as parseExit, i as ListenExit, l as PartialExecutionResult, o as getValue, r as DefaultExit, s as ErrorExecutionResult, t as _CustomModelClient, u as SuccessExecutionResult } from "./custom-client-BnlDpjdI.js";
+import { a as ThinkExit, c as ExecutionResult, d as Snapshot, f as parseExit, i as ListenExit, l as PartialExecutionResult, o as getValue, r as DefaultExit, s as ErrorExecutionResult, t as _CustomModelClient, u as SuccessExecutionResult } from "./custom-client-CJIThG2H.js";
 import { a as getMultilineComment, c as isJsonSchema, l as isValidIdentifier, m as toValidObjectName, n as escapeString, p as toValidFunctionName, t as configureTokenizer, u as isZuiSchema, v as upperFirst } from "./utils-UBeAFeEI.js";
-import { t as Tool } from "./tool-CAo-BQHs.js";
+import { t as Tool } from "./tool-Bv8N4IPj.js";
 import { c as SnapshotSignal, l as ThinkSignal, o as LoopExceededError, r as CodeFormattingError } from "./errors-Cg1G0Awu.js";
 import { a as isPunct, i as isGroup, o as parse, r as formatTypings, s as tokenize, t as getTypings } from "./typings-CrBa7Tyy.js";
 import { t as Exit } from "./exit-CDdxDBRT.js";
@@ -10,7 +10,7 @@ import { i as wrapContent, n as truncateWrappedContent, t as stripTruncationTags
 import { t as configureQuickJS } from "./quickjs-variant-BYhMBpwU.js";
 import { transforms, z } from "@bpinternal/zui";
 //#region package.json
-var version = "0.6.5";
+var version = "0.6.7";
 //#endregion
 //#region src/hoist.ts
 /**
@@ -1773,7 +1773,7 @@ const utils = {
 * })
 */
 const execute = async (props) => {
-	const { executeContext } = await import("./execute-BjBBTshA.js");
+	const { executeContext } = await import("./execute-sn9RT_IN.js");
 	return executeContext(props);
 };
 /**
@@ -1782,9 +1782,9 @@ const execute = async (props) => {
 * It's recommended to call this function at the beginning of your application without awaiting it (void init())
 */
 const init = async () => {
-	await import("./execute-BjBBTshA.js");
+	await import("./execute-sn9RT_IN.js");
 	await import("./component-DGG7d_Mz.js").then((n) => n.r);
-	await import("./tool-CAo-BQHs.js").then((n) => n.n);
+	await import("./tool-Bv8N4IPj.js").then((n) => n.n);
 	await import("./exit-CDdxDBRT.js").then((n) => n.n);
 	await import("./jsx-CIgdGGVs.js").then((n) => n.i);
 	await import("./vm-C5vf1LH3.js");

package/dist/index.workerd.js

@@ -52,7 +52,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 //#region package.json
-var version = "0.6.5";
+var version = "0.6.7";
 //#endregion
 //#region ../../node_modules/.pnpm/lodash-es@4.17.21/node_modules/lodash-es/_freeGlobal.js
 var freeGlobal;
@@ -7682,7 +7682,10 @@ var init_tool = __esmMin((() => {
 				if (done) return value;
 				if (yieldIndex >= yieldedCount) {
 					setYieldedCount(yieldIndex + 1);
-					await chat?.handler?.(value);
+					await chat?.handler?.(value, {
+						iterationId: ctx.iterationId ?? ctx.callId,
+						id: `${ctx.callId}:yield-${yieldIndex}`
+					});
 				}
 				yieldIndex++;
 			}
@@ -12215,8 +12218,14 @@ var init_context = __esmMin((() => {
 		*/
 		maxTimeToFirstToken;
 		/**
-		* Allow Cognitive mid-stream fallback, buffering delivery until generation
-		* succeeds and discarding abandoned attempts. Streaming-only; defaults to false.
+		* Allow Cognitive to restart a failed stream on another model. With fallback
+		* enabled, there is no buffered delivery and no final delivery queue: delta
+		* text and completed Chat.handler sends stream immediately during generation.
+		* A reset-only delta (restart: true) on Chat.onMessageDelta invalidates ALL
+		* current-iteration messages, including completed sends — consumers must
+		* retract/replace them, which is unsafe for irreversible external transports.
+		* Only TOOL/CODE execution waits for a successful stream. Streaming-only;
+		* defaults to false, which leaves progressive sending unchanged.
 		*/
 		midStreamFallback;
 		/**
@@ -17100,11 +17109,18 @@ var init_generate = __esmMin((() => {
 		/** Milliseconds between the stream request and the first/last streamed tokens. */
 		let timeToFirstToken;
 		let timeToLastToken;
-		const bufferedDelivery = ctx.midStreamFallback === true;
-		let pendingDeliveries = [];
-		const deliver = async (callback) => {
-			if (bufferedDelivery) pendingDeliveries.push(callback);
-			else await callback();
+		const midStreamFallback = ctx.midStreamFallback === true;
+		let attempt = 1;
+		const messageMetadata = (itemId) => ({
+			iterationId: iteration.id,
+			id: midStreamFallback ? `${iteration.id}:${attempt}:${itemId}` : `${iteration.id}:${itemId}`
+		});
+		const preview = async (delta) => {
+			try {
+				await onSendDelta?.(delta);
+			} catch (err) {
+				if (delta.restart) throw new CognitiveError(`LLM stream restart handler failed: ${getErrorMessage(err)}`);
+			}
 		};
 		const liveItems = /* @__PURE__ */ new Map();
 		const liveContent = /* @__PURE__ */ new Map();
@@ -17115,14 +17131,11 @@ var init_generate = __esmMin((() => {
 				liveItems.set(event.item.id, event.item);
 				if (event.item.kind === "run" && !codeGenerationTraced) {
 					codeGenerationTraced = true;
-					const started_at = Date.now();
-					await deliver(() => {
-						traces.push({
-							type: "code_generation_started",
-							started_at
-						});
-						onRunStart?.();
+					traces.push({
+						type: "code_generation_started",
+						started_at: Date.now()
 					});
+					onRunStart?.();
 				}
 			} else if (event.type === "body-delta" && onSendDelta) {
 				const item = liveItems.get(event.itemId);
@@ -17130,29 +17143,24 @@ var init_generate = __esmMin((() => {
 				const content = (liveContent.get(item.id) ?? "") + event.delta;
 				liveContent.set(item.id, content);
 				const delta = {
-					id: `${iteration.id}:${item.id}`,
+					restart: false,
+					...messageMetadata(item.id),
 					component: item.name,
-					props: bufferedDelivery ? structuredClone(item.props) : item.props,
+					props: item.props,
 					delta: event.delta,
 					content
 				};
-				await deliver(async () => {
-					try {
-						await onSendDelta(delta);
-					} catch (err) {}
-				});
+				await preview(delta);
 			} else if (event.type === "item-complete") {
-				if (event.item.kind === "send" && onSend) {
-					const send = {
-						name: event.item.name,
-						props: bufferedDelivery ? structuredClone(event.item.props) : event.item.props,
-						body: event.item.body
-					};
-					await deliver(() => onSend(send));
-				} else if (event.item.kind === "run" && event.item.status === "complete" && !runCompleted) {
+				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();
-					await deliver(() => onRunComplete?.(code));
+					onRunComplete?.(code);
 				}
 			}
 		};
@@ -17163,10 +17171,10 @@ var init_generate = __esmMin((() => {
 			const requestedAt = Date.now();
 			const stream = cognitive.generateTextStream({
 				...input,
-				...ctx.maxTimeToFirstToken || bufferedDelivery ? { options: {
+				...ctx.maxTimeToFirstToken || midStreamFallback ? { options: {
 					...input.options,
 					...ctx.maxTimeToFirstToken ? { maxTimeToFirstToken: ctx.maxTimeToFirstToken } : {},
-					...bufferedDelivery ? { midStreamFallback: true } : {}
+					...midStreamFallback ? { midStreamFallback: true } : {}
 				} } : {}
 			}, { signal: streamController.signal });
 			const inactivityTimeout = Math.max(STREAM_INACTIVITY_TIMEOUT, ctx.maxTimeToFirstToken ?? 0);
@@ -17198,7 +17206,7 @@ var init_generate = __esmMin((() => {
 						streamCompleted = true;
 						break;
 					}
-					if (chunk.value?.restart && !bufferedDelivery) {
+					if (chunk.value?.restart && !midStreamFallback) {
 						streamController.abort("Unexpected LLM stream restart");
 						throw new CognitiveError("LLM stream restarted without options.midStreamFallback enabled");
 					}
@@ -17213,10 +17221,15 @@ var init_generate = __esmMin((() => {
 						fence = new LeadingFenceFilter();
 						liveItems.clear();
 						liveContent.clear();
-						pendingDeliveries = [];
 						codeGenerationTraced = false;
 						runCompleted = false;
 						responseMetadata = void 0;
+						attempt = chunk.value.restart.attempt;
+						await preview({
+							...chunk.value.restart,
+							restart: true,
+							iterationId: iteration.id
+						});
 						timeToFirstToken = void 0;
 						timeToLastToken = void 0;
 						continue;
@@ -17236,16 +17249,9 @@ var init_generate = __esmMin((() => {
 				assistantResponse = toParsedAssistantResponse(parser.items, raw);
 			} finally {
 				streamController.abort("LLM stream closed");
-				if (!streamCompleted) stream.return(void 0).catch(() => {});
-			}
-			if (bufferedDelivery) {
-				controller.signal.throwIfAborted();
-				for (const callback of pendingDeliveries) {
-					controller.signal.throwIfAborted();
-					await callback();
-				}
-				pendingDeliveries = [];
+				if (!streamCompleted) stream.return(void 0).catch((err) => {});
 			}
+			if (midStreamFallback) controller.signal.throwIfAborted();
 		} else {
 			const response = await cognitive.generateText(input, { signal: controller.signal }).catch((thrown) => {
 				throw new CognitiveError(`LLM generation failed: ${getErrorMessage(thrown)}`);
@@ -17254,7 +17260,7 @@ var init_generate = __esmMin((() => {
 			responseMetadata = response.metadata;
 			raw = response.output;
 			assistantResponse = ctx.version.parseAssistantResponse(raw);
-			for (const send of assistantResponse.sends) await onSend?.(send);
+			for (const [index, send] of assistantResponse.sends.entries()) await onSend?.(send, messageMetadata(`send-${index}`));
 		}
 		iteration.code = assistantResponse.code;
 		iteration.sends = assistantResponse.sends;
@@ -17534,7 +17540,10 @@ function wrapTool({ chat, tool, traces, object, iteration, beforeHook, afterHook
 				toolCallId
 			});
 			if (typeof beforeRes?.input !== "undefined") effectiveInput = beforeRes.input;
-			output = await tool.execute(effectiveInput, { callId: toolCallId }, chat);
+			output = await tool.execute(effectiveInput, {
+				callId: toolCallId,
+				iterationId: iteration.id
+			}, chat);
 			const afterRes = await afterHook?.({
 				iteration,
 				tool,
@@ -17887,7 +17896,7 @@ var init_execute = __esmMin((() => {
 					promise: runCode(code)
 				};
 			} : void 0,
-			onSend: async (send) => {
+			onSend: async (send, messageMetadata) => {
 				if (!ctx.chat) return;
 				const sendStartedAt = Date.now();
 				const component = createJsxComponent({
@@ -17896,7 +17905,7 @@ var init_execute = __esmMin((() => {
 					children: send.body ? [send.body] : []
 				});
 				try {
-					await ctx.chat.handler(component);
+					await ctx.chat.handler(component, messageMetadata);
 				} catch (err) {
 					throw new Error(`Error while sending message (■send=${send.name}): ${getErrorMessage(err)}`);
 				}

package/dist/runtime/generate.d.ts

@@ -1,4 +1,4 @@
-import type { MessageDelta } from '../chat.js';
+import type { MessageDelta, MessageMetadata } from '../chat.js';
 import { Context, Iteration } from '../context.js';
 import type { ParsedSend } from '../prompts/prompt.js';
 import { RuntimeCognitive } from './types.js';
@@ -12,10 +12,11 @@ type GenerateCodeProps = {
      * Called for each completed `■send` block. On streaming clients this fires
      * while the model is still generating — messages are delivered progressively.
      */
-    onSend?: (send: ParsedSend) => Promise<void>;
+    onSend?: (send: ParsedSend, metadata: MessageMetadata) => Promise<void>;
     /**
      * Called for each `■send` body chunk as it is parsed from the stream
-     * (streaming clients only). Best-effort: errors are ignored.
+     * (streaming clients only), or with a restart delta before replacement output.
+     * Text errors are best-effort; restart errors terminate generation.
      */
     onSendDelta?: (delta: MessageDelta) => Promise<void> | void;
     /**

package/dist/runtime/types.d.ts

@@ -123,10 +123,13 @@ type Options = Partial<Pick<Context, 'loop' | 'timeout'>> & {
      */
     maxTimeToFirstToken?: number;
     /**
-     * Allow Cognitive to restart failed streams on another model. Buffers message
-     * previews, sends, and code execution until generation succeeds; abandoned
-     * attempts deliver nothing. Streaming-only; defaults to false, preserving
-     * progressive sends and early code execution.
+     * Allow Cognitive to restart failed streams on another model. No buffered
+     * delivery and no final delivery queue: delta text and completed Chat.handler
+     * sends stream immediately during generation. A reset-only delta (restart:
+     * true) on Chat.onMessageDelta invalidates ALL current-iteration messages,
+     * including completed sends — consumers must retract/replace them (not safe for
+     * irreversible transports). Only TOOL/CODE execution waits for a successful
+     * stream. Streaming-only; defaults to false, preserving progressive sending.
      */
     midStreamFallback?: boolean;
     /**

package/dist/{tool-CAo-BQHs.js → tool-Bv8N4IPj.js}

@@ -500,7 +500,10 @@ var Tool = class Tool {
 			if (yieldIndex >= yieldedCount) {
 				var _chat$handler;
 				setYieldedCount(yieldIndex + 1);
-				await (chat === null || chat === void 0 || (_chat$handler = chat.handler) === null || _chat$handler === void 0 ? void 0 : _chat$handler.call(chat, value));
+				await (chat === null || chat === void 0 || (_chat$handler = chat.handler) === null || _chat$handler === void 0 ? void 0 : _chat$handler.call(chat, value, {
+					iterationId: ctx.iterationId ?? ctx.callId,
+					id: `${ctx.callId}:yield-${yieldIndex}`
+				}));
 			}
 			yieldIndex++;
 		}

package/dist/{tool-DdPZb0JW.cjs → tool-ReA9gxMp.cjs}

@@ -500,7 +500,10 @@ var Tool = class Tool {
 			if (yieldIndex >= yieldedCount) {
 				var _chat$handler;
 				setYieldedCount(yieldIndex + 1);
-				await (chat === null || chat === void 0 || (_chat$handler = chat.handler) === null || _chat$handler === void 0 ? void 0 : _chat$handler.call(chat, value));
+				await (chat === null || chat === void 0 || (_chat$handler = chat.handler) === null || _chat$handler === void 0 ? void 0 : _chat$handler.call(chat, value, {
+					iterationId: ctx.iterationId ?? ctx.callId,
+					id: `${ctx.callId}:yield-${yieldIndex}`
+				}));
 			}
 			yieldIndex++;
 		}

package/dist/tool.d.ts

@@ -49,6 +49,8 @@ type SmartPartial<T> = IsObject<T> extends true ? Partial<T> : T;
 type ToolCallContext = {
     /** Unique identifier for this specific tool call */
     callId: string;
+    /** Set by the runtime; standalone calls use callId as their message scope. */
+    iterationId?: string;
 };
 export declare namespace Tool {
     type JSON = {

package/package.json

@@ -2,7 +2,7 @@
   "name": "llmz",
   "type": "module",
   "description": "LLMz - An LLM-native Typescript VM built on top of Zui",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "files": [
     "dist",
     "DOCS.md"
@@ -68,7 +68,7 @@
     "tsx": "^4.19.2"
   },
   "peerDependencies": {
-    "@botpress/client": "2.4.0",
+    "@botpress/client": "2.5.0",
     "@botpress/cognitive": "1.2.0",
     "@bpinternal/thicktoken": "^3.1.0",
     "@bpinternal/zui": "^2.4.1"