llmz 0.1.5 → 0.2.1

package/dist/result.d.ts

@@ -291,6 +291,28 @@ export declare abstract class ExecutionResult implements Serializable<ExecutionR
      * ```
      */
     get iterations(): Iteration[];
+    /**
+     * Gets the total token usage of the execution, aggregated across all iterations.
+     *
+     * `input`/`output` are the provider-reported token counts of every LLM call made
+     * during the execution. Per-iteration detail (including the measured context size
+     * breakdown by prompt part) is available on each iteration's `tokens` property.
+     *
+     * @example
+     * ```typescript
+     * const result = await execute({ ... })
+     * console.log(`Execution used ${result.tokens.total} tokens`)
+     *
+     * for (const iteration of result.iterations) {
+     *   console.log(iteration.id, iteration.tokens?.context)
+     * }
+     * ```
+     */
+    get tokens(): {
+        input: number;
+        output: number;
+        total: number;
+    };
     abstract toJSON(): ExecutionResult.JSON;
 }
 export declare namespace SuccessExecutionResult {
@@ -406,6 +428,8 @@ export declare class SuccessExecutionResult<TOutput = unknown> extends Execution
                     spend: number;
                     output: string;
                     model: string;
+                    time_to_first_token?: number;
+                    time_to_last_token?: number;
                     usage: {
                         inputCost: number;
                         outputCost: number;
@@ -413,6 +437,7 @@ export declare class SuccessExecutionResult<TOutput = unknown> extends Execution
                         outputTokens: number;
                     };
                 } | undefined;
+                tokens: import("./context.js").TokenUsage | undefined;
                 transcript: import("./transcript.js").Transcript.Message[];
                 tools: {
                     name: string;
@@ -568,6 +593,8 @@ export declare class ErrorExecutionResult extends ExecutionResult implements Ser
                     spend: number;
                     output: string;
                     model: string;
+                    time_to_first_token?: number;
+                    time_to_last_token?: number;
                     usage: {
                         inputCost: number;
                         outputCost: number;
@@ -575,6 +602,7 @@ export declare class ErrorExecutionResult extends ExecutionResult implements Ser
                         outputTokens: number;
                     };
                 } | undefined;
+                tokens: import("./context.js").TokenUsage | undefined;
                 transcript: import("./transcript.js").Transcript.Message[];
                 tools: {
                     name: string;
@@ -750,6 +778,8 @@ export declare class PartialExecutionResult extends ExecutionResult implements S
                     spend: number;
                     output: string;
                     model: string;
+                    time_to_first_token?: number;
+                    time_to_last_token?: number;
                     usage: {
                         inputCost: number;
                         outputCost: number;
@@ -757,6 +787,7 @@ export declare class PartialExecutionResult extends ExecutionResult implements S
                         outputTokens: number;
                     };
                 } | undefined;
+                tokens: import("./context.js").TokenUsage | undefined;
                 transcript: import("./transcript.js").Transcript.Message[];
                 tools: {
                     name: string;

package/dist/runtime/execute.test.d.ts

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

package/dist/runtime/generate.d.ts

@@ -1,4 +1,6 @@
+import type { MessageDelta } from '../chat.js';
 import { Context, Iteration } from '../context.js';
+import type { ParsedSend } from '../prompts/prompt.js';
 import { RuntimeCognitive } from './types.js';
 type GenerateCodeProps = {
     iteration: Iteration;
@@ -6,6 +8,27 @@ type GenerateCodeProps = {
     cognitive: RuntimeCognitive;
     controller: AbortController;
     metadata?: Record<string, string>;
+    /**
+     * 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>;
+    /**
+     * Called for each `■send` body chunk as it is parsed from the stream
+     * (streaming clients only). Best-effort: errors are ignored.
+     */
+    onSendDelta?: (delta: MessageDelta) => Promise<void> | void;
+    /**
+     * Called as soon as the model opens a `■run` block, while the code is still
+     * being generated (streaming clients only). Used to pre-warm the VM.
+     */
+    onRunStart?: () => void;
+    /**
+     * Called with the code of the first `■run` block the moment it is fully
+     * parsed — the rest of the response (e.g. `■next`) may still be streaming
+     * (streaming clients only). Used to start executing the code early.
+     */
+    onRunComplete?: (code: string) => void;
 };
-export declare const generateCode: ({ iteration, ctx, cognitive, controller, metadata }: GenerateCodeProps) => Promise<void>;
+export declare const generateCode: ({ iteration, ctx, cognitive, controller, metadata, onSend, onSendDelta, onRunStart, onRunComplete, }: GenerateCodeProps) => Promise<void>;
 export {};

package/dist/runtime/interpret-result.d.ts

@@ -9,4 +9,14 @@ type InterpretVMResultProps = {
     onExit?: ExecutionHooks['onExit'];
 };
 export declare const interpretVMResult: ({ iteration, result, controller, startedAt, onExit, }: InterpretVMResultProps) => Promise<void>;
+/**
+ * Applies the `■next=<exit>` block of the current iteration: validates the exit
+ * name and props against the available exits, runs the onExit hook, and ends
+ * the iteration with exit_success or exit_error.
+ */
+export declare const applyNextExit: ({ iteration, controller, onExit, }: {
+    iteration: Iteration;
+    controller: AbortController;
+    onExit?: ExecutionHooks["onExit"];
+}) => Promise<void>;
 export {};

package/dist/runtime/types.d.ts

@@ -1,4 +1,4 @@
-import { Cognitive, CognitiveBeta, type BotpressClientLike, Models } from '@botpress/cognitive';
+import { Cognitive, CognitiveBeta, type BotpressClientLike, type CognitiveLike, Models } from '@botpress/cognitive';
 import { Chat } from '../chat.js';
 import { Context, Iteration } from '../context.js';
 import { _CustomModelClient } from '../custom-client.js';
@@ -17,10 +17,13 @@ export type ExecutionHooks = {
      *
      * This hook is called for each trace that is generated during the iteration.
      * It is useful for logging, debugging, or monitoring the execution of the iteration.
+     * The abort controller can be used to stop the execution when a trace reveals
+     * something that should halt it (e.g. a forbidden tool call).
      */
     onTrace?: (event: {
         trace: Trace;
         iteration: number;
+        controller: AbortController;
     }) => void;
     /**
      * BLOCKING HOOK
@@ -50,8 +53,9 @@ export type ExecutionHooks = {
      * It is useful for logging, sending notifications, or performing actions based on the exit.
      * It can also be used to throw an error and preventing the exit from being successful.
      * If this hook throws an error, the execution will keep iterating with the error as context.
+     * The abort controller can be used to stop the execution entirely instead of iterating.
      */
-    onExit?: <T = unknown>(result: ExitResult<T>) => Promise<void> | void;
+    onExit?: <T = unknown>(result: ExitResult<T>, controller: AbortController) => Promise<void> | void;
     /**
      * BLOCKING HOOK
      *   This hook will block the execution of the iteration until it resolves.
@@ -104,7 +108,21 @@ export type ExecutionHooks = {
         output?: any;
     } | void>;
 };
-type Options = Partial<Pick<Context, 'loop' | 'timeout'>>;
+type Options = Partial<Pick<Context, 'loop' | 'timeout'>> & {
+    /**
+     * Optional cap on the model's context window, in tokens.
+     * The effective limit is `min(maxTokens, model's max input tokens)`.
+     * Useful to reduce cost and latency on models with very large context windows.
+     */
+    maxTokens?: number;
+    /**
+     * Maximum time to wait for the first streamed token, in milliseconds, before
+     * the cognitive service falls back to the next model/provider. Only applies
+     * to streaming clients (CognitiveBeta / Cognitive v2), and works best when
+     * `model` is an array of fallback models.
+     */
+    maxTimeToFirstToken?: number;
+};
 export type ExecutionProps = {
     /**
      * If provided, the execution will be run in "Chat Mode".
@@ -211,5 +229,12 @@ export type ExecutionProps = {
      */
     metadata?: Record<string, string>;
 } & ExecutionHooks;
-export type RuntimeCognitive = Pick<Cognitive, 'getModelDetails' | 'generateContent'>;
+export type RuntimeCognitive = Pick<Cognitive, 'getModelDetails' | 'generateContent'> & {
+    /**
+     * Streaming generation. Only available on clients backed by the Cognitive v2
+     * (beta) API — when present, the runtime streams the response and parses
+     * ■ blocks incrementally.
+     */
+    generateContentStream?: CognitiveLike['generateContentStream'];
+};
 export {};

package/dist/{tool-DNHVW3KC.js → tool-HTAYKIA2.js}

@@ -1,7 +1,7 @@
 import {
   Tool
-} from "./chunk-IRCB4FRM.js";
-import "./chunk-TOGYDN6U.js";
+} from "./chunk-GC5IQDGV.js";
+import "./chunk-665O7CAN.js";
 import "./chunk-WSVDMGMR.js";
 import "./chunk-YEAWWJSJ.js";
 import "./chunk-YX27XM67.js";

package/dist/{tool-GJ6ZXWS2.cjs → tool-V55GD2FS.cjs}

@@ -1,11 +1,11 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkWODK7Y4Jcjs = require('./chunk-WODK7Y4J.cjs');
-require('./chunk-7LMIOS6H.cjs');
+var _chunkETYFOCWCcjs = require('./chunk-ETYFOCWC.cjs');
+require('./chunk-DD4AZSP5.cjs');
 require('./chunk-PK72FAKD.cjs');
 require('./chunk-KIN7Y247.cjs');
 require('./chunk-FPLSJF4S.cjs');
 require('./chunk-HC2QZTVT.cjs');
 
 
-exports.Tool = _chunkWODK7Y4Jcjs.Tool;
+exports.Tool = _chunkETYFOCWCcjs.Tool;

package/dist/truncator-7PGEGCHV.cjs

@@ -0,0 +1,12 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunkYQT5G77Wcjs = require('./chunk-YQT5G77W.cjs');
+require('./chunk-FPLSJF4S.cjs');
+require('./chunk-HC2QZTVT.cjs');
+
+
+
+
+exports.stripTruncationTags = _chunkYQT5G77Wcjs.stripTruncationTags; exports.truncateWrappedContent = _chunkYQT5G77Wcjs.truncateWrappedContent; exports.wrapContent = _chunkYQT5G77Wcjs.wrapContent;

package/dist/{truncator-3U2QUUJJ.js → truncator-OZOBNYON.js}

@@ -1,10 +1,12 @@
 import {
+  stripTruncationTags,
   truncateWrappedContent,
   wrapContent
-} from "./chunk-L74UZONX.js";
+} from "./chunk-HM5H556L.js";
 import "./chunk-YX27XM67.js";
 import "./chunk-34GJUS6U.js";
 export {
+  stripTruncationTags,
   truncateWrappedContent,
   wrapContent
 };

package/dist/truncator.d.ts

@@ -113,4 +113,6 @@ export declare function wrapContent(content: string, options?: Partial<TruncateO
  * ```
  */
 export declare function truncateWrappedContent<T extends MessageLike>({ messages, tokenLimit, throwOnFailure, }: Options<T>): T[];
+/** Removes truncation wrapper tags from content, leaving the wrapped content intact. */
+export declare const stripTruncationTags: (content: string) => string;
 export {};

package/dist/types.d.ts

@@ -55,6 +55,13 @@ export declare namespace Traces {
         model: string;
         code: string;
     }>;
+    /**
+     * Emitted on streaming clients the moment the model starts writing a `■run`
+     * block — before the code is fully generated. Useful to show a
+     * "writing code..." indicator while waiting for `llm_call_success` (which
+     * carries the final code) and the subsequent execution.
+     */
+    type CodeGenerationStart = TraceTemplate<'code_generation_started', {}>;
     type AbortTrace = TraceTemplate<'abort_signal', {
         reason: string;
     }>;
@@ -70,7 +77,7 @@ export declare namespace Traces {
         started_at: number;
         ended_at?: number;
     } & Content;
-    type Trace = Comment | Log | ToolCall | ToolSlow | PropertyMutation | YieldTrace | LLMCallStart | LLMCallSuccess | ThinkSignal | CodeExecution | CodeExecutionException | InvalidCodeExceptionTrace | AbortTrace;
+    type Trace = Comment | Log | ToolCall | ToolSlow | PropertyMutation | YieldTrace | LLMCallStart | LLMCallSuccess | CodeGenerationStart | ThinkSignal | CodeExecution | CodeExecutionException | InvalidCodeExceptionTrace | AbortTrace;
 }
 export type Trace = Traces.Trace;
 export type VMExecutionResult = {

package/dist/{typings-ZTFPPA5W.cjs → typings-S6I6IPTG.cjs}

@@ -1,10 +1,10 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunk7LMIOS6Hcjs = require('./chunk-7LMIOS6H.cjs');
+var _chunkDD4AZSP5cjs = require('./chunk-DD4AZSP5.cjs');
 require('./chunk-PK72FAKD.cjs');
 require('./chunk-KIN7Y247.cjs');
 require('./chunk-FPLSJF4S.cjs');
 require('./chunk-HC2QZTVT.cjs');
 
 
-exports.getTypings = _chunk7LMIOS6Hcjs.getTypings;
+exports.getTypings = _chunkDD4AZSP5cjs.getTypings;

package/dist/{typings-3YV3RDMP.js → typings-SCKZCAPN.js}

@@ -1,6 +1,6 @@
 import {
   getTypings
-} from "./chunk-TOGYDN6U.js";
+} from "./chunk-665O7CAN.js";
 import "./chunk-WSVDMGMR.js";
 import "./chunk-YEAWWJSJ.js";
 import "./chunk-YX27XM67.js";

package/dist/typings-formatter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A minimal, dependency-free formatter for the TypeScript typings generated by
+ * llmz (typings.ts, objects.ts, hoist.ts). It supports only the small grammar
+ * those generators emit — type expressions, `declare const` / `declare function`
+ * declarations, `type` aliases and `export namespace` blocks — and produces
+ * prettier-like output: 80 columns, 2-space indent, no semicolons in broken
+ * objects, hugged single-object function params, unions wrapped with leading `|`.
+ *
+ * If the input cannot be tokenized or has unbalanced brackets, it is returned
+ * unchanged.
+ */
+/** Formats typings, throwing on input it cannot parse (unbalanced brackets, etc.) */
+export declare function formatTypingsUnsafe(typings: string): string;
+/** Formats typings, returning the input unchanged when it cannot be parsed */
+export declare function formatTypings(typings: string): string;

package/dist/typings-formatter.test.d.ts

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

package/dist/vm/drivers/quickjs.d.ts

@@ -1,5 +1,7 @@
+import { type QuickJSWASMModule } from 'quickjs-emscripten-core';
 import type { VMExecutionResult } from '../../types.js';
 import type { DriverExecutionContext, VMDriver } from '../types.js';
+export declare const loadQuickJSModule: () => Promise<QuickJSWASMModule>;
 export declare class QuickJSDriver implements VMDriver {
     execute(ctx: DriverExecutionContext): Promise<VMExecutionResult>;
     private _pumpEventLoop;

package/dist/vm/index.d.ts

@@ -1,3 +1,10 @@
 import type { Trace, VMExecutionResult } from '../types.js';
 import type { VMContext } from './types.js';
+/**
+ * Pre-warms the VM so the first execution doesn't pay the QuickJS WASM
+ * instantiation cost. Fire-and-forget: called as soon as the model starts
+ * writing a `■run` block, so the module loads while the code is still being
+ * generated. No-op when the QuickJS driver is disabled or already loaded.
+ */
+export declare const warmupVM: () => void;
 export declare function runAsyncFunction(context: VMContext, code: string, traces?: Trace[], signal?: AbortSignal | null, timeout?: number): Promise<VMExecutionResult>;

package/dist/vm/instrument.d.ts

@@ -3,7 +3,7 @@ import { type CompiledCode } from '../compiler/index.js';
 import { SnapshotSignal } from '../errors.js';
 import type { Trace } from '../types.js';
 import { VMContext } from './types.js';
-export declare const NO_TRACKING: readonly [string, string, string, string, string, string];
+export declare const NO_TRACKING: readonly [string, string, string, string, string];
 export type InstrumentationState = {
     currentToolCall: SnapshotSignal['toolCall'] | undefined;
 };

package/dist/{vm-PYCKS77H.js → vm-44H4UKI2.js}

@@ -1,10 +1,11 @@
 import {
-  runAsyncFunction
-} from "./chunk-EFEF2AL7.js";
+  runAsyncFunction,
+  warmupVM
+} from "./chunk-DH35WO5G.js";
 import "./chunk-WSVDMGMR.js";
 import "./chunk-YEAWWJSJ.js";
-import "./chunk-XTEHT2TK.js";
 import "./chunk-34GJUS6U.js";
 export {
-  runAsyncFunction
+  runAsyncFunction,
+  warmupVM
 };

package/dist/{vm-VHB67FVH.cjs → vm-A3OTQVIR.cjs}

@@ -1,10 +1,11 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkJXD2KJVBcjs = require('./chunk-JXD2KJVB.cjs');
+
+var _chunkWWZ2W4WRcjs = require('./chunk-WWZ2W4WR.cjs');
 require('./chunk-PK72FAKD.cjs');
 require('./chunk-KIN7Y247.cjs');
-require('./chunk-5ZF6NTYI.cjs');
 require('./chunk-HC2QZTVT.cjs');
 
 
-exports.runAsyncFunction = _chunkJXD2KJVBcjs.runAsyncFunction;
+
+exports.runAsyncFunction = _chunkWWZ2W4WRcjs.runAsyncFunction; exports.warmupVM = _chunkWWZ2W4WRcjs.warmupVM;

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.1.5",
+  "version": "0.2.1",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -30,11 +30,8 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@babel/core": "^7.26.0",
     "@babel/generator": "^7.26.3",
     "@babel/parser": "^7.26.3",
-    "@babel/plugin-transform-react-jsx": "^7.25.9",
-    "@babel/preset-typescript": "^7.26.0",
     "@babel/standalone": "^7.26.4",
     "@babel/traverse": "^7.26.4",
     "@babel/types": "^7.26.3",
@@ -42,14 +39,15 @@
     "bytes": "^3.1.2",
     "exponential-backoff": "^3.1.1",
     "handlebars": "^4.7.8",
+    "json5": "^2.2.3",
+    "jsonrepair": "^3.10.0",
     "lodash-es": "^4.17.21",
-    "lru-cache": "~11.0.2",
     "ms": "^2.1.3",
-    "prettier": "^3.4.2",
     "quickjs-emscripten-core": "^0.31.0",
     "ulid": "^2.3.0"
   },
   "devDependencies": {
+    "@babel/core": "^7.26.0",
     "@botpress/cli": "workspace:*",
     "@microsoft/api-extractor": "^7.49.0",
     "@types/babel__core": "^7.20.5",
@@ -66,6 +64,7 @@
     "dotenv": "^16.4.4",
     "esbuild": "^0.25.10",
     "glob": "^9.3.4",
+    "prettier": "^3.4.2",
     "source-map-js": "1.2.1",
     "tsup": "^8.0.2",
     "tsx": "^4.19.2"
@@ -73,7 +72,7 @@
   "peerDependencies": {
     "@botpress/client": "1.49.0",
     "@botpress/cognitive": "0.6.2",
-    "@bpinternal/thicktoken": "^2.0.0",
+    "@bpinternal/thicktoken": "^3.0.0",
     "@bpinternal/zui": "^2.3.1"
   },
   "dependenciesMeta": {