llmz 0.9.0 → 1.0.2

package/dist/chat/chat.d.ts

@@ -0,0 +1,63 @@
+import type { Context } from '../context.js';
+import type { ValueOrGetter } from '../getter.js';
+import type { ExecutionResult } from '../result.js';
+import type { Component, RenderedComponent } from './component.js';
+import type { Response } from './response.js';
+/** Ordinary assistant output, independent of the configured response style. */
+export type AssistantTextMessage = {
+    type: 'text';
+    text: string;
+};
+/** Text uses native assistant output; registered components provide rich UI. */
+export type ChatMessage = AssistantTextMessage | RenderedComponent;
+export type MessageMetadata = {
+    /** The iteration that owns this response or component send. */
+    iterationId: string;
+    /** Logical send ID, shared with its streamed text deltas. */
+    id: string;
+};
+/** Receives the complete committed assistant response. */
+export type ResponseHandler = (text: string, metadata: MessageMetadata) => Promise<void> | void;
+export type MessageDelta = {
+    restart: false;
+    type: 'text';
+    iterationId: string;
+    id: string;
+    /** New text since the preceding delta. */
+    delta: string;
+    /** Complete provisional text received so far. */
+    content: string;
+} | {
+    /** Retract provisional text for this iteration before any replacement. */
+    restart: true;
+    iterationId: string;
+    attempt: number;
+    fromModel: string;
+    toModel: string;
+    reason: string;
+};
+/** Preview failures are ignored; failed retractions stop generation. */
+export type MessageDeltaHandler = (delta: MessageDelta) => Promise<void> | void;
+/**
+ * Connects native assistant replies and rich components to the host application.
+ *
+ * `response` controls how all assistant text is written. It does not create a
+ * JavaScript method or synthesize audio. `components` registers only rich UI
+ * methods such as chat.buttons or chat.image.
+ *
+ * Streamed deltas are provisional. After successful generation, the response
+ * handler receives the complete text with the same message ID. Each component
+ * owns its delivery handler. Without response callbacks, text remains available
+ * in the native session history.
+ */
+export declare class Chat {
+    readonly components: ValueOrGetter<Component[], Context>;
+    readonly response: ValueOrGetter<Response, Context>;
+    constructor(props?: {
+        components?: ValueOrGetter<Component[], Context>;
+        /** Resolved once per iteration; defaults to Markdown. */
+        response?: ValueOrGetter<Response, Context>;
+    });
+    /** Called after an execution completes or fails. */
+    onExecutionDone(_result: ExecutionResult): void;
+}

package/dist/chat/component.d.ts

@@ -0,0 +1,31 @@
+import { z } from '@bpinternal/zui';
+import type { MessageMetadata } from './chat.js';
+export type ComponentSchema = z.ZodObject<any> | z.ZodArray<any> | z.ZodEffects<any> | z.ZodPipeline<any, any>;
+export type ComponentHandler<P extends ComponentSchema = any> = (props: z.output<P>, metadata: MessageMetadata) => Promise<void> | void;
+export type ComponentDefinition<P extends ComponentSchema = any> = {
+    /** The exact JavaScript method name exposed on chat. */
+    name: string;
+    description: string;
+    props: P;
+    handler?: ComponentHandler<P>;
+};
+export type RenderedComponent<TProps = unknown> = {
+    readonly type: 'component';
+    readonly name: string;
+    readonly props: TProps;
+};
+export type ComponentRegistry = ReadonlyMap<string, Component>;
+export declare function assertValidComponent(component: unknown): asserts component is ComponentDefinition;
+export declare class Component<P extends ComponentSchema = any> {
+    readonly definition: Readonly<ComponentDefinition<P>>;
+    readonly propsType: z.output<P>;
+    readonly handler: ComponentHandler<P> | undefined;
+    constructor(definition: ComponentDefinition<P>);
+    withHandler(handler: ComponentHandler<P>): Component<P>;
+    /** Parse once and retain an immutable delivery value. */
+    render(props: z.input<P>): RenderedComponent<z.output<P>>;
+}
+/** Resolve the exact methods once and share them between the prompt and runtime. */
+export declare function createComponentRegistry(components: readonly Component[]): ComponentRegistry;
+export declare function isComponent<P extends ComponentSchema>(rendered: unknown, component: Component<P>): rendered is RenderedComponent<z.output<P>>;
+export declare function isAnyComponent(value: unknown): value is RenderedComponent;

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

@@ -0,0 +1,58 @@
+import { z } from '@bpinternal/zui';
+import { Component } from './component.js';
+export declare const DefaultComponents: {
+    Buttons: Component<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>;
+    }, "strict">, "many">>;
+    Image: Component<z.ZodObject<{
+        url: z.ZodString;
+        alt: z.ZodOptional<z.ZodString>;
+    }, "strict">>;
+    File: Component<z.ZodObject<{
+        url: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, "strict">>;
+    Video: Component<z.ZodObject<{
+        url: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, "strict">>;
+    Audio: Component<z.ZodObject<{
+        url: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, "strict">>;
+    Card: Component<z.ZodObject<{
+        title: z.ZodString;
+        subtitle: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+        }, "strict">>;
+        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>;
+        }, "strict">, "many">>;
+    }, "strict">>;
+    Carousel: Component<z.ZodObject<{
+        cards: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            subtitle: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            image: z.ZodOptional<z.ZodObject<{
+                url: z.ZodString;
+                alt: z.ZodOptional<z.ZodString>;
+            }, "strict">>;
+            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>;
+            }, "strict">, "many">>;
+        }, "strict">, "many">;
+    }, "strict">>;
+};

package/dist/chat/response.d.ts

@@ -0,0 +1,15 @@
+import type { MessageDeltaHandler, ResponseHandler } from './chat.js';
+export type ResponsePreset = 'markdown' | 'text' | 'speech';
+export type Response = ResponsePreset | {
+    preset?: ResponsePreset;
+    instructions?: string;
+    handler?: ResponseHandler;
+    onDelta?: MessageDeltaHandler;
+};
+export type ResolvedResponse = {
+    instructions: string;
+    handler?: ResponseHandler;
+    onDelta?: MessageDeltaHandler;
+};
+/** Resolve one response style for the entire generation, including its stream. */
+export declare function resolveResponse(response?: Response): ResolvedResponse;

package/dist/compiler/compiler.d.ts

@@ -1,10 +1,7 @@
-import { ToolCallEntry } from './plugins/track-tool-calls.js';
 export declare const Identifiers: {
     ConsoleObjIdentifier: string;
     LineTrackingFnIdentifier: string;
     VariableTrackingFnIdentifier: string;
-    ToolCallTrackerFnIdentifier: string;
-    ToolTrackerRetIdentifier: string;
     CommentFnIdentifier: string;
 };
 export type CompiledCode = ReturnType<typeof compile>;
@@ -20,8 +17,7 @@ export declare function hasTopLevelReturn(code: string): boolean;
  *
  * 1. wraps it in an async `__fn__` so top-level `await`/`return` parse
  * 2. instruments it in a single parse + text-edit pass:
- *    line tracking, last-line return, tool-call tracking, comment tracing
- *    and variable tracking
+ *    line tracking, last-line awaiting, comment tracing and variable tracking
  * 3. unwraps it — the VM drivers re-wrap the bare statements themselves
  *
  * All edits preserve line numbers 1:1 with the wrapped source, so positions
@@ -30,7 +26,6 @@ export declare function hasTopLevelReturn(code: string): boolean;
 export declare function compile(code: string): {
     code: string;
     codeWithMarkers: string;
-    map: import("magic-string").SourceMap;
+    map: import("source-map-js").RawSourceMap;
     variables: Set<string>;
-    toolCalls: Map<number, ToolCallEntry>;
 };

package/dist/compiler/plugins/dynamic-code.d.ts

@@ -0,0 +1,7 @@
+import { type AnyNode } from '../ast.js';
+/**
+ * Dynamically generated source bypasses the VM's control-flow instrumentation.
+ * Reject identifiable entry points and constructor aliases. This is a language
+ * restriction, not a security boundary against reflective JavaScript escapes.
+ */
+export declare function rejectDynamicCode(ast: AnyNode): void;

package/dist/compiler/plugins/replace-comment.d.ts

@@ -3,7 +3,6 @@ export declare const CommentFnIdentifier = "__comment__";
 /**
  * Replaces comments at statement position with `__comment__("<text>", <line>)`
  * calls so the agent's inline "thinking" comments show up as traces at runtime.
- * Comments inside expressions and the user-code markers are blanked; comments
- * inside instrumented tool-call ranges are left verbatim.
+ * Comments inside expressions and the user-code markers are blanked.
  */
-export declare function applyCommentReplacement(ctx: Ctx, skipRanges: Array<[number, number]>): void;
+export declare function applyCommentReplacement(ctx: Ctx): void;

package/dist/compiler/plugins/return-async.d.ts

@@ -6,11 +6,12 @@ export type LastLineEdit = {
     suffix: string;
 };
 /**
- * Plans the instrumentation of the last statement of the `__fn__` wrapper so
- * the generated code always returns an awaited value (the isolated VM cannot
- * return a pending Promise):
+ * Awaits the last expression without changing whether the program returns it.
+ * The isolated VM cannot return a pending Promise:
  * - `return expr` → `return await (expr)`
- * - a trailing `call()` / `await call()` statement → `return await (…)`
+ * - a trailing `call()` / `await call()` statement → `await (…)`
+ *
+ * Discarded values must stay discarded, especially terminal decision receipts.
  *
  * The prefix must be applied before, and the suffix after, all other edits so
  * they wrap around the tool-call instrumentation.

package/dist/compiler/plugins/termination.d.ts

@@ -0,0 +1,8 @@
+import { type Ctx } from '../ast.js';
+export declare const TerminationGuardIdentifier = "__llmz_guard";
+export declare const TerminationCheckpointIdentifier = "__llmz_checkpoint";
+/**
+ * A terminal host call unwinds ordinary JavaScript. User error handlers must not
+ * consume that control flow, and async continuations must check before resuming.
+ */
+export declare function applyTerminationGuards(ctx: Ctx): () => void;

package/dist/compiler/plugins/tool-resolution.d.ts

@@ -0,0 +1,4 @@
+import { type Ctx } from '../ast.js';
+export declare const MissingToolIdentifier = "__llmz_missing_tool";
+/** Diagnose missing free callables at the lookup, before evaluating their arguments. */
+export declare function applyToolResolution({ ast, ms }: Ctx): void;

package/dist/compiler/plugins/variable-extraction.d.ts

@@ -1,10 +1,4 @@
 import { type Ctx } from '../ast.js';
 export declare const VariableTrackingFnIdentifier = "__var__";
-/**
- * Tracks user variables so the VM can read their values between iterations:
- * - after each variable declaration: `__var__("a", () => eval("a"));`
- * - at the top of function bodies, for their parameters
- *
- * The `eval` indirection captures the variable lazily in its own scope.
- */
-export declare function applyVariableTracking(ctx: Ctx, variables: Set<string>): void;
+/** Capture only session-level bindings, and record completed writes without changing expression values. */
+export declare function applyVariableTracking(ctx: Ctx, variables: Set<string>, deferSuffixes?: boolean): () => void;