llmz 0.8.0 → 1.0.1

package/dist/runtime/execute.d.ts

@@ -1,3 +1,4 @@
 import { ExecutionResult } from '../result.js';
-import { ExecutionProps } from './types.js';
-export declare const executeContext: (props: ExecutionProps) => Promise<ExecutionResult>;
+import type { ExecutionProps } from './types.js';
+/** Each iteration joins generation and execution before settling its transcript. */
+export declare function executeContext(props: ExecutionProps): Promise<ExecutionResult>;

package/dist/runtime/execution-activity.d.ts

@@ -0,0 +1,11 @@
+import type { Iteration } from '../context.js';
+import { type InspectionIdentity, type Inspector } from '../inspection.js';
+import type { Traces } from '../types.js';
+export type ExecutionActivity = {
+    calls: Traces.ToolCall[];
+    deliveries: Traces.MessageDelivery[];
+};
+/** Collect recorded operations, excluding ordinary assistant text delivery. */
+export declare function getExecutionActivity(iteration: Iteration): ExecutionActivity;
+export declare function renderToolCalls(activity: ExecutionActivity, includeRecoveryValues?: boolean, inspector?: Inspector, identity?: InspectionIdentity): string | undefined;
+export declare function renderMessageDeliveries({ deliveries }: ExecutionActivity, cancelled?: boolean, inspector?: Inspector, identity?: InspectionIdentity): string | undefined;

package/dist/runtime/execution-activity.test.d.ts

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

package/dist/runtime/execution-diagnostics.d.ts

@@ -0,0 +1,11 @@
+import type { InspectionIdentity, Inspector } from '../inspection.js';
+import type { TruncatePreserve } from '../truncate.js';
+/** XML-style boundaries keep diagnostic text separate from recovery instructions. */
+export declare function reportSection(name: string, content: string, maxTokens?: number, options?: {
+    heading?: string;
+    preserve?: TruncatePreserve;
+}): string;
+/** Show the specific failure and guest source, never the host's implementation stack. */
+export declare function renderExecutionDiagnostics(error: unknown, message: string, inspector: Inspector, identity: InspectionIdentity): string[];
+/** Keep failure sites visible even when they are near the end of a long program. */
+export declare function renderSourceTrace(stack: string, inspector: Inspector, identity: InspectionIdentity): string;

package/dist/runtime/execution-diagnostics.test.d.ts

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

package/dist/runtime/execution-report.d.ts

@@ -0,0 +1,48 @@
+import { type InspectionPolicyLookup } from '../inspect.js';
+import { type InspectionIdentity, type Inspector } from '../inspection.js';
+import type { MemoryReport } from '../session/memory.js';
+import { type ExecutionActivity } from './execution-activity.js';
+export { renderMessageDeliveries } from './execution-activity.js';
+export type ExecutionOutcome = {
+    type: 'inspect';
+    value: unknown;
+    available: boolean;
+    explicit: boolean;
+} | {
+    type: 'exit';
+    name: string;
+    value: unknown;
+} | {
+    type: 'error';
+    message: string;
+    error?: unknown;
+    exitName?: string;
+} | {
+    type: 'cancelled';
+    message: string;
+} | {
+    type: 'interrupted';
+    reason: 'stream' | 'thinking';
+    message?: string;
+    context?: unknown;
+    stacktrace?: string;
+};
+export type ExecutionReport = {
+    outcome: ExecutionOutcome;
+    activity: ExecutionActivity;
+    memory: MemoryReport;
+    source?: {
+        requested?: string;
+        executed?: string;
+    };
+    requiresExit?: boolean;
+    iteration?: number;
+    identity?: InspectionIdentity;
+    inspector?: Inspector;
+    maxTokens?: number;
+    policies?: InspectionPolicyLookup;
+};
+/** Format one settled outcome; execution is responsible for deciding what happened. */
+export declare function renderExecutionReport({ outcome, activity, memory, source, requiresExit, iteration, identity, inspector, maxTokens, policies, }: ExecutionReport): string;
+/** Keep the requested assistant call intact while disclosing the source the host actually ran. */
+export declare function renderExecutionOverride(executedCode?: string, requestedCode?: string, inspector?: Inspector, identity?: InspectionIdentity): string | undefined;

package/dist/runtime/execution-report.test.d.ts

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

package/dist/runtime/execution-safety.test.d.ts

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

package/dist/runtime/exit-control-flow.test.d.ts

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

package/dist/runtime/fixtures/chat.d.ts

@@ -0,0 +1,8 @@
+import { Chat, type ChatMessage, type MessageDeltaHandler, type MessageMetadata } from '../../chat/chat.js';
+import type { Component } from '../../chat/component.js';
+/** Collect both delivery paths when testing execution order and receipts. */
+export declare function createRecordingChat({ handler, onMessageDelta, components, }: {
+    handler: (message: ChatMessage, metadata: MessageMetadata) => Promise<void> | void;
+    onMessageDelta?: MessageDeltaHandler;
+    components?: Component[];
+}): Chat;

package/dist/runtime/fixtures/long-search.d.ts

@@ -0,0 +1,19 @@
+import { CitationsManager } from '../../chat/citations.js';
+export type SearchChallenge = {
+    id: string;
+    size: number;
+    profile: 'scope' | 'revision' | 'join' | 'arithmetic';
+    language: string;
+    position: number;
+};
+export declare const longSearchChallenges: SearchChallenge[];
+/** Synthetic VDK-shaped search results. No customer data or external search is involved. */
+export declare function buildSearchChallenge(challenge: SearchChallenge, compact: boolean, citations: CitationsManager): {
+    question: string;
+    facts: string[];
+    expectedSources: string[];
+    relevantSources: string[];
+    evidenceTags: string[];
+    content: string;
+    reason: string;
+};

package/dist/runtime/fixtures/long-search.test.d.ts

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

package/dist/runtime/fixtures/native-client.d.ts

@@ -0,0 +1,33 @@
+import type { CognitiveMetadata, CognitiveResponse, CognitiveStreamChunk, CognitiveToolCall } from '@botpress/cognitive';
+import { _CustomModelClient, type RuntimeGenerateContentInput } from '../../custom-client.js';
+export declare const nativeMetadata: CognitiveMetadata;
+export declare const nativeCall: (name: string, input?: Record<string, unknown>, id?: string) => CognitiveToolCall;
+export declare const javascript: (code: string) => CognitiveResponse;
+export declare const response: (output?: string, toolCalls?: CognitiveToolCall[]) => CognitiveResponse;
+export declare class NativeClient extends _CustomModelClient {
+    responses: CognitiveResponse[];
+    requests: RuntimeGenerateContentInput[];
+    constructor(responses: CognitiveResponse[]);
+    getModelDetails(id: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        input: {
+            maxTokens: number;
+            costPer1MTokens: number;
+        };
+        output: {
+            maxTokens: number;
+            costPer1MTokens: number;
+        };
+        tags: never[];
+        lifecycle: 'production';
+    }>;
+    generateText(input: RuntimeGenerateContentInput): Promise<CognitiveResponse>;
+}
+export declare class NativeStreamClient extends NativeClient {
+    size: number;
+    probe: () => void;
+    constructor(responses: CognitiveResponse[], size?: number, probe?: () => void);
+    generateTextStream(input: RuntimeGenerateContentInput): AsyncGenerator<CognitiveStreamChunk>;
+}

package/dist/runtime/fixtures/protocol-languages.d.ts

@@ -0,0 +1,74 @@
+/** Synthetic multilingual inputs for native protocol boundary tests. */
+export declare const protocolLanguages: readonly [{
+    readonly language: 'English';
+    readonly hello: 'Hello!';
+    readonly question: 'Help me choose a plan.';
+    readonly reply: 'How many conversations do you expect per month?';
+    readonly checking: 'Checking.';
+}, {
+    readonly language: 'French';
+    readonly hello: 'Bonjour !';
+    readonly question: 'Aidez-moi à choisir un forfait.';
+    readonly reply: 'Combien de conversations prévoyez-vous par mois ?';
+    readonly checking: 'Je vérifie.';
+}, {
+    readonly language: 'Spanish';
+    readonly hello: '¡Hola!';
+    readonly question: 'Ayúdame a elegir un plan.';
+    readonly reply: '¿Cuántas conversaciones esperas al mes?';
+    readonly checking: 'Estoy comprobando.';
+}, {
+    readonly language: 'German';
+    readonly hello: 'Hallo!';
+    readonly question: 'Hilf mir, einen Tarif auszuwählen.';
+    readonly reply: 'Wie viele Gespräche erwartest du pro Monat?';
+    readonly checking: 'Ich prüfe das.';
+}, {
+    readonly language: 'Portuguese';
+    readonly hello: 'Olá!';
+    readonly question: 'Ajude-me a escolher um plano.';
+    readonly reply: 'Quantas conversas você espera por mês?';
+    readonly checking: 'Estou verificando.';
+}, {
+    readonly language: 'Italian';
+    readonly hello: 'Ciao!';
+    readonly question: 'Aiutami a scegliere un piano.';
+    readonly reply: 'Quante conversazioni prevedi al mese?';
+    readonly checking: 'Sto controllando.';
+}, {
+    readonly language: 'Arabic';
+    readonly hello: 'مرحباً!';
+    readonly question: 'ساعدني في اختيار خطة.';
+    readonly reply: 'كم محادثة تتوقع في الشهر؟';
+    readonly checking: 'أتحقق الآن.';
+}, {
+    readonly language: 'Chinese';
+    readonly hello: '你好！';
+    readonly question: '帮我选择一个套餐。';
+    readonly reply: '你预计每月有多少次对话？';
+    readonly checking: '正在查询。';
+}, {
+    readonly language: 'Japanese';
+    readonly hello: 'こんにちは！';
+    readonly question: 'プラン選びを手伝ってください。';
+    readonly reply: '月に何件の会話を想定していますか？';
+    readonly checking: '確認しています。';
+}, {
+    readonly language: 'Korean';
+    readonly hello: '안녕하세요!';
+    readonly question: '요금제 선택을 도와주세요.';
+    readonly reply: '월별 대화 수는 얼마나 예상하시나요?';
+    readonly checking: '확인 중입니다.';
+}, {
+    readonly language: 'Hindi';
+    readonly hello: 'नमस्ते!';
+    readonly question: 'एक योजना चुनने में मेरी मदद करें।';
+    readonly reply: 'आपको हर महीने कितनी बातचीत की उम्मीद है?';
+    readonly checking: 'मैं जाँच कर रहा हूँ।';
+}, {
+    readonly language: 'Russian';
+    readonly hello: 'Здравствуйте!';
+    readonly question: 'Помогите мне выбрать тариф.';
+    readonly reply: 'Сколько разговоров вы ожидаете в месяц?';
+    readonly checking: 'Проверяю.';
+}];

package/dist/runtime/generate.d.ts

@@ -1,35 +1,31 @@
-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';
+import type { CognitiveMessage, CognitiveMetadata, CognitiveResponse, CognitiveToolCall } from '@botpress/cognitive';
+import type { MessageDelta, MessageMetadata } from '../chat/chat.js';
+import type { Context, Iteration } from '../context.js';
+import type { ExecutionHooks, RuntimeCognitive } from './types.js';
+export { countNativeRequestTokens } from './token-budget.js';
+/** A custom provider adapter can return the full assistant message, including opaque continuation data. */
+export type NativeResponse = CognitiveResponse & {
+    assistantMessage?: CognitiveMessage;
+    continuation?: unknown;
+};
+export type NativeGeneration = {
+    attempt: number;
+    output: string;
+    toolCalls: CognitiveToolCall[];
+    assistantMessage?: CognitiveMessage;
+    continuation?: unknown;
+    metadata: CognitiveMetadata;
+    messageMetadata: MessageMetadata;
+};
 type GenerateCodeProps = {
     iteration: Iteration;
     ctx: Context;
     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, metadata: MessageMetadata) => Promise<void>;
-    /**
-     * Called for each `■send` body chunk as it is parsed from the stream
-     * (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;
-    /**
-     * 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;
+    onBeforeRequest?: ExecutionHooks['onBeforeRequest'];
+    /** Start a complete normalized call without waiting for execution or the stream tail. */
+    onToolCalls?: (calls: CognitiveToolCall[]) => boolean;
 };
-export declare const generateCode: ({ iteration, ctx, cognitive, controller, metadata, onSend, onSendDelta, onRunStart, onRunComplete, }: GenerateCodeProps) => Promise<void>;
-export {};
+export declare function generateCode({ iteration, ctx, cognitive, controller, metadata, onSendDelta, onToolCalls, onBeforeRequest, }: GenerateCodeProps): Promise<NativeGeneration>;

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

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

package/dist/runtime/hook-provenance.test.d.ts

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

package/dist/runtime/inspection-hook.test.d.ts

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

package/dist/runtime/inspection-values.d.ts

@@ -0,0 +1,14 @@
+import type { InspectionPolicyLookup } from '../inspect.js';
+import type { TruncationPolicy } from '../truncate.js';
+/** Explicit display policies apply only to unchanged values in this JavaScript execution. */
+export declare class InspectionValues {
+    private readonly _primitives;
+    private readonly _objects;
+    capture(value: unknown, policy: TruncationPolicy): void;
+    captureDefault(value: unknown, maxTokens: number): void;
+    private _register;
+    /** Match unchanged VM copies without rebuilding a wrapped display graph. */
+    readonly getPolicy: InspectionPolicyLookup;
+    private _objectKey;
+    private _mergePolicy;
+}

package/dist/runtime/inspection-values.test.d.ts

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

package/dist/runtime/interruption-control-flow.test.d.ts

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

package/dist/runtime/interruption-settings.test.d.ts

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

package/dist/runtime/javascript-api.d.ts

@@ -0,0 +1,59 @@
+import type { ComponentRegistry, RenderedComponent } from '../chat/component.js';
+import type { Iteration } from '../context.js';
+import { ThinkSignal } from '../errors.js';
+import type { Exit } from '../exit.js';
+/** A child message keeps its identity from preparation through acknowledged delivery. */
+export type PreparedMessage = {
+    id: string;
+    component: RenderedComponent;
+};
+export type JavaScriptOutcome = {
+    type: 'inspect';
+    value: unknown;
+} | {
+    type: 'exit';
+    exit: Exit;
+    value: unknown;
+};
+type DecisionReceipt = Readonly<{
+    __llmz_decision: string;
+}>;
+type TerminalOutcome = Extract<JavaScriptOutcome, {
+    type: 'exit';
+}>;
+export type JavaScriptBindings = {
+    exit(name?: string, value?: unknown): never;
+    inspect(value: unknown): DecisionReceipt;
+    chat: Readonly<Record<string, (input: unknown) => void>>;
+};
+export type JavaScriptApi = {
+    bindings: JavaScriptBindings;
+    resolve(value: unknown): JavaScriptOutcome | undefined;
+    isReceipt(value: unknown): boolean;
+    getTerminalOutcome(): TerminalOutcome | undefined;
+    /** The first host interruption closes execution before guest handlers can consume it. */
+    getInterruption(): ThinkSignal | undefined;
+    throwIfTerminated(): void;
+    track<T>(operation: () => Promise<T>): Promise<T>;
+    assertOpen(): void;
+    /** Record validation failures and close host operations on critical configuration errors. */
+    reportError(error: unknown): void;
+    /** Called at program settlement, before background work can invoke another host operation. */
+    complete(): void;
+    /** Joins automatic message delivery and business work before the iteration can settle. */
+    close(): Promise<void>;
+};
+type JavaScriptApiOptions = {
+    iteration: Pick<Iteration, 'id' | 'nativeCallId'>;
+    components: ComponentRegistry;
+    exits: readonly Exit[];
+    deliver(messages: readonly PreparedMessage[]): Promise<void>;
+    signal?: AbortSignal;
+    onError?(error: unknown): void;
+};
+/**
+ * Component methods send synchronously; the runtime joins delivery in close().
+ * Inspection returns a decision, while exit latches an outcome and stops the program.
+ */
+export declare function createJavaScriptApi({ iteration, components, exits, deliver, signal, onError, }: JavaScriptApiOptions): JavaScriptApi;
+export {};

package/dist/runtime/javascript-api.test.d.ts

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

package/dist/runtime/native-review.test.d.ts

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

package/dist/runtime/native-tools.d.ts

@@ -0,0 +1,18 @@
+import type { CognitiveTool, CognitiveToolCall } from '@botpress/cognitive';
+export declare const WORKER_RESPONSE_INSTRUCTION = "You are running in worker mode. Respond only with a run_javascript tool call. Keep assistant text empty: do not send messages, preambles, progress updates, explanations, acknowledgements such as \"Done\", Markdown, or JSON outside the tool call. This applies before and after tools, during recovery, and when completing the task.";
+export declare const RUN_JAVASCRIPT_TOOL: CognitiveTool;
+/** Select delivery guidance without changing the native tool name or input schema. */
+export declare function getRunJavaScriptTool(chat: boolean): CognitiveTool;
+export type ValidatedNativeCall = {
+    id: string;
+    code: string;
+};
+export type NativeCallValidation = {
+    valid: true;
+    call?: ValidatedNativeCall;
+} | {
+    valid: false;
+    errors: string[];
+};
+/** Validate the entire response before any delivery or business action begins. */
+export declare function validateNativeToolCalls(calls: readonly CognitiveToolCall[]): NativeCallValidation;

package/dist/runtime/native-tools.test.d.ts

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

package/dist/runtime/object-memory.test.d.ts

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

package/dist/runtime/protocol-adherence.test.d.ts

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

package/dist/runtime/single-tool.test.d.ts

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

package/dist/runtime/token-budget.d.ts

@@ -0,0 +1,22 @@
+import type { CognitiveMessage } from '@botpress/cognitive';
+/**
+ * Estimate text, structured arguments, schemas, and message scaffolding. Media
+ * URLs carry bytes or locations, not model text. Cognitive does not expose a
+ * media-token estimator; actual media usage is reported by the provider.
+ */
+export declare function countNativeRequestTokens(messages: CognitiveMessage[], tools: unknown): number;
+type ModelLimits = {
+    input: {
+        maxTokens: number;
+    };
+    output: {
+        maxTokens: number;
+    };
+};
+/** Reserve output space within every model that can receive this request. */
+export declare function resolveTokenBudget(model: ModelLimits | readonly ModelLimits[], maxTokens?: number): {
+    limit: number;
+    output: number;
+    input: number;
+};
+export {};

package/dist/runtime/token-budget.test.d.ts

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

package/dist/runtime/tool-wrapper.d.ts

@@ -1,17 +1,16 @@
-import { Chat } from '../chat.js';
 import { Iteration } from '../context.js';
 import { type Tool } from '../tool.js';
-import { Trace } from '../types.js';
+import type { TruncationPolicy } from '../truncate.js';
 import { ExecutionHooks } from './types.js';
 type ToolWrapperProps = {
-    chat?: Chat;
     tool: Tool;
     object?: string;
-    traces: Trace[];
     iteration: Iteration;
     beforeHook?: ExecutionHooks['onBeforeTool'];
     afterHook?: ExecutionHooks['onAfterTool'];
+    onTruncation?: (value: unknown, policy: TruncationPolicy) => void;
+    onResult?: (value: unknown) => void;
     controller: AbortController;
 };
-export declare function wrapTool({ chat, tool, traces, object, iteration, beforeHook, afterHook, controller, }: ToolWrapperProps): (input: any) => Promise<any>;
+export declare function wrapTool({ tool, object, iteration, beforeHook, afterHook, onTruncation, onResult, controller, }: ToolWrapperProps): (input: any) => Promise<any>;
 export {};

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

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

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

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