llmz 0.9.0 → 1.0.2

package/dist/custom-client.d.ts

@@ -1,8 +1,13 @@
-import { Model } from '@botpress/cognitive';
+import { Model, type CognitiveMessage } from '@botpress/cognitive';
 import { RuntimeCognitive } from './runtime/types.js';
 export type RuntimeGenerateContentInput = Parameters<RuntimeCognitive['generateText']>[0];
 export type RuntimeGenerateContentOptions = Parameters<RuntimeCognitive['generateText']>[1];
-export type RuntimeGenerateContentOutput = Awaited<ReturnType<RuntimeCognitive['generateText']>>;
+export type RuntimeGenerateContentOutput = Awaited<ReturnType<RuntimeCognitive['generateText']>> & {
+    /** Full native assistant message, including opaque provider reasoning/signature fields. */
+    assistantMessage?: CognitiveMessage & Record<string, unknown>;
+    /** Opaque provider continuation state. The adapter must consume it on subsequent requests. */
+    continuation?: unknown;
+};
 /**
  * Internal escape hatch for supplying a custom model client that bypasses Cognitive.
  *
@@ -10,6 +15,11 @@ export type RuntimeGenerateContentOutput = Awaited<ReturnType<RuntimeCognitive['
  * against arbitrary models). It is intentionally undocumented and offers no stability
  * guarantees — the API may change or be removed without notice. Avoid it unless you
  * fully understand the implications.
+ *
+ * Native clients must forward request tools/toolControl, return real toolCalls
+ * with unique IDs, and report successful completion metadata. Preserve provider
+ * reasoning/signature state using assistantMessage or continuation; flattened
+ * reasoning text is not a replacement for provider-required continuation data.
  */
 export declare abstract class _CustomModelClient implements RuntimeCognitive {
     private readonly ['$$COGNITIVE'];

package/dist/errors/catalog.d.ts

@@ -0,0 +1,294 @@
+declare const ERROR_BRAND: unique symbol;
+/** Stable library failures. Control-flow signals (such as ThinkSignal) are not errors. */
+export declare abstract class LLMzError<C extends string = string> extends Error {
+    readonly critical: boolean;
+    abstract readonly code: C;
+    protected constructor(message: string, critical: boolean, options?: ErrorOptions);
+    /** Shared across independently loaded copies of the library. */
+    get [ERROR_BRAND](): true;
+    static readonly is: (value: unknown) => value is LLMzError;
+}
+/** A schema validation issue, relative to the supplied argument or property. */
+export type ValidationIssue = {
+    path: (string | number)[];
+    message: string;
+};
+export type ToolInputIssue = ValidationIssue;
+export declare class CodeExecutionError extends LLMzError<'EXECUTION_FAILED'> {
+    readonly source: string;
+    readonly stacktrace: string;
+    readonly originalErrorName?: string | undefined;
+    static readonly is: (value: unknown) => value is CodeExecutionError;
+    readonly code = "EXECUTION_FAILED";
+    constructor(message: string, source: string, stacktrace: string, originalErrorName?: string | undefined, cause?: Error);
+}
+export declare class InvalidCodeError extends LLMzError<'INVALID_CODE'> {
+    readonly source: string;
+    static readonly is: (value: unknown) => value is InvalidCodeError;
+    readonly code = "INVALID_CODE";
+    constructor(message: string, source: string, options?: ErrorOptions);
+}
+export declare class CodeFormattingError extends LLMzError<'CODE_FORMATTING_FAILED'> {
+    readonly source: string;
+    static readonly is: (value: unknown) => value is CodeFormattingError;
+    readonly code = "CODE_FORMATTING_FAILED";
+    constructor(message: string, source: string);
+}
+export declare class ToolInputError extends LLMzError<'INVALID_TOOL_INPUT'> {
+    readonly toolName: string;
+    readonly issues: ValidationIssue[];
+    readonly expectedInput: string;
+    static readonly is: (value: unknown) => value is ToolInputError;
+    readonly code = "INVALID_TOOL_INPUT";
+    constructor(toolName: string, issues: ValidationIssue[], expectedInput: string);
+}
+export declare class ExitInputError extends LLMzError<'INVALID_EXIT_INPUT'> {
+    readonly exitName: string;
+    readonly issues: ValidationIssue[];
+    readonly expectedInput: string;
+    static readonly is: (value: unknown) => value is ExitInputError;
+    readonly code = "INVALID_EXIT_INPUT";
+    constructor(exitName: string, issues: ValidationIssue[], expectedInput: string);
+}
+export declare class ObjectPropertyError extends LLMzError<'INVALID_OBJECT_PROPERTY'> {
+    readonly objectName: string;
+    readonly propertyName: string;
+    readonly issues: ValidationIssue[];
+    readonly expectedInput: string;
+    static readonly is: (value: unknown) => value is ObjectPropertyError;
+    readonly code = "INVALID_OBJECT_PROPERTY";
+    constructor(objectName: string, propertyName: string, issues: ValidationIssue[], expectedInput: string);
+}
+export declare class ComponentInputError extends LLMzError<'INVALID_COMPONENT_INPUT'> {
+    readonly componentName: string;
+    readonly issues: ValidationIssue[];
+    readonly expectedInput: string;
+    static readonly is: (value: unknown) => value is ComponentInputError;
+    readonly code = "INVALID_COMPONENT_INPUT";
+    constructor(componentName: string, issues: ValidationIssue[], expectedInput: string);
+}
+export declare class UnknownToolError extends LLMzError<'UNKNOWN_TOOL'> {
+    readonly toolName: string;
+    readonly availableTools: readonly string[];
+    static readonly is: (value: unknown) => value is UnknownToolError;
+    readonly code = "UNKNOWN_TOOL";
+    constructor(toolName: string, availableTools?: readonly string[], message?: string);
+}
+export declare class UnknownComponentError extends LLMzError<'UNKNOWN_COMPONENT'> {
+    readonly componentName: string;
+    readonly availableComponents: readonly string[];
+    static readonly is: (value: unknown) => value is UnknownComponentError;
+    readonly code = "UNKNOWN_COMPONENT";
+    constructor(componentName: string, availableComponents: readonly string[]);
+}
+export declare class UnknownExitError extends LLMzError<'UNKNOWN_EXIT'> {
+    readonly exitName: string;
+    readonly availableExits: readonly string[];
+    static readonly is: (value: unknown) => value is UnknownExitError;
+    readonly code = "UNKNOWN_EXIT";
+    constructor(exitName: string, availableExits: readonly string[]);
+}
+export declare class ReservedIdentifierError extends LLMzError<'RESERVED_IDENTIFIER'> {
+    readonly identifier: string;
+    readonly kind: 'variable' | 'tool' | 'object' | 'exit' | 'component' | 'binding';
+    static readonly is: (value: unknown) => value is ReservedIdentifierError;
+    readonly code = "RESERVED_IDENTIFIER";
+    constructor(identifier: string, kind: 'variable' | 'tool' | 'object' | 'exit' | 'component' | 'binding', critical?: boolean, message?: string);
+}
+export declare class ToolExecutionError extends LLMzError<'TOOL_EXECUTION_FAILED'> {
+    readonly toolName: string;
+    static readonly is: (value: unknown) => value is ToolExecutionError;
+    readonly code = "TOOL_EXECUTION_FAILED";
+    constructor(toolName: string, cause: unknown);
+}
+export declare class LoopExceededError extends LLMzError<'ITERATION_LIMIT'> {
+    readonly limit?: number | undefined;
+    static readonly is: (value: unknown) => value is LoopExceededError;
+    readonly code = "ITERATION_LIMIT";
+    constructor(limit?: number | undefined);
+}
+export declare class TokenOverflowError extends LLMzError<'TOKEN_OVERFLOW'> {
+    readonly tokens?: number | undefined;
+    readonly limit?: number | undefined;
+    readonly phase: 'input' | 'output';
+    static readonly is: (value: unknown) => value is TokenOverflowError;
+    readonly code = "TOKEN_OVERFLOW";
+    constructor(message: string, tokens?: number | undefined, limit?: number | undefined, phase?: 'input' | 'output');
+}
+export declare class MemoryCapacityError extends LLMzError<'MEMORY_CAPACITY'> {
+    readonly maxBytes: number;
+    static readonly is: (value: unknown) => value is MemoryCapacityError;
+    readonly code = "MEMORY_CAPACITY";
+    constructor(maxBytes: number);
+}
+/** A generated program tried to change read-only runtime state. */
+export declare class AssignmentError extends LLMzError<'INVALID_ASSIGNMENT'> {
+    static readonly is: (value: unknown) => value is AssignmentError;
+    readonly code = "INVALID_ASSIGNMENT";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The provider failed, or returned an incomplete or malformed generation. */
+export declare class CognitiveError extends LLMzError<'GENERATION_FAILED'> {
+    static readonly is: (value: unknown) => value is CognitiveError;
+    readonly code = "GENERATION_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Summarization failed; canonical history is preserved. */
+export declare class CompactionError extends LLMzError<'COMPACTION_FAILED'> {
+    static readonly is: (value: unknown) => value is CompactionError;
+    readonly code = "COMPACTION_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid tool definition. */
+export declare class InvalidToolError extends LLMzError<'INVALID_TOOL'> {
+    static readonly is: (value: unknown) => value is InvalidToolError;
+    readonly code = "INVALID_TOOL";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid object definition. */
+export declare class InvalidObjectError extends LLMzError<'INVALID_OBJECT'> {
+    static readonly is: (value: unknown) => value is InvalidObjectError;
+    readonly code = "INVALID_OBJECT";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid exit definition. */
+export declare class InvalidExitError extends LLMzError<'INVALID_EXIT'> {
+    static readonly is: (value: unknown) => value is InvalidExitError;
+    readonly code = "INVALID_EXIT";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid chat component definition. */
+export declare class InvalidComponentError extends LLMzError<'INVALID_COMPONENT'> {
+    static readonly is: (value: unknown) => value is InvalidComponentError;
+    readonly code = "INVALID_COMPONENT";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid execution, chat, or library configuration. */
+export declare class InvalidConfigurationError extends LLMzError<'INVALID_CONFIG'> {
+    static readonly is: (value: unknown) => value is InvalidConfigurationError;
+    readonly code = "INVALID_CONFIG";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid session input message. */
+export declare class InvalidMessageError extends LLMzError<'INVALID_MESSAGE'> {
+    static readonly is: (value: unknown) => value is InvalidMessageError;
+    readonly code = "INVALID_MESSAGE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid external event name or payload. */
+export declare class InvalidEventError extends LLMzError<'INVALID_EVENT'> {
+    static readonly is: (value: unknown) => value is InvalidEventError;
+    readonly code = "INVALID_EVENT";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Invalid persisted session or native history. */
+export declare class InvalidSessionError extends LLMzError<'INVALID_SESSION'> {
+    static readonly is: (value: unknown) => value is InvalidSessionError;
+    readonly code = "INVALID_SESSION";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The operation is not allowed in the current session state. */
+export declare class SessionStateError extends LLMzError<'SESSION_STATE'> {
+    static readonly is: (value: unknown) => value is SessionStateError;
+    readonly code = "SESSION_STATE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A value cannot be retained in session memory. */
+export declare class MemoryValueError extends LLMzError<'INVALID_MEMORY_VALUE'> {
+    static readonly is: (value: unknown) => value is MemoryValueError;
+    readonly code = "INVALID_MEMORY_VALUE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The model returned an invalid native tool call. */
+export declare class NativeProtocolError extends LLMzError<'INVALID_NATIVE_CALL'> {
+    static readonly is: (value: unknown) => value is NativeProtocolError;
+    readonly code = "INVALID_NATIVE_CALL";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Generated code used a closed or unawaited host operation. */
+export declare class HostOperationError extends LLMzError<'HOST_OPERATION_FAILED'> {
+    static readonly is: (value: unknown) => value is HostOperationError;
+    readonly code = "HOST_OPERATION_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Chat tried to wait for the user without delivering any message. */
+export declare class MissingChatResponseError extends LLMzError<'MISSING_CHAT_RESPONSE'> {
+    static readonly is: (value: unknown) => value is MissingChatResponseError;
+    readonly code = "MISSING_CHAT_RESPONSE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Message delivery failed; external delivery may have partially completed. */
+export declare class DeliveryError extends LLMzError<'DELIVERY_FAILED'> {
+    static readonly is: (value: unknown) => value is DeliveryError;
+    readonly code = "DELIVERY_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** An execution hook failed; its external effects may be incomplete. */
+export declare class HookError extends LLMzError<'HOOK_FAILED'> {
+    static readonly is: (value: unknown) => value is HookError;
+    readonly code = "HOOK_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Execution was cancelled or timed out. */
+export declare class ExecutionAbortedError extends LLMzError<'EXECUTION_ABORTED'> {
+    static readonly is: (value: unknown) => value is ExecutionAbortedError;
+    readonly code = "EXECUTION_ABORTED";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** An unexpected library failure; inspect cause for the original exception. */
+export declare class InternalError extends LLMzError<'INTERNAL_ERROR'> {
+    static readonly is: (value: unknown) => value is InternalError;
+    readonly code = "INTERNAL_ERROR";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** @internal Constructor registry for VM diagnostics. */
+export declare const errorClasses: {
+    CodeExecutionError: typeof CodeExecutionError;
+    InvalidCodeError: typeof InvalidCodeError;
+    CodeFormattingError: typeof CodeFormattingError;
+    ToolInputError: typeof ToolInputError;
+    ExitInputError: typeof ExitInputError;
+    ObjectPropertyError: typeof ObjectPropertyError;
+    ComponentInputError: typeof ComponentInputError;
+    UnknownToolError: typeof UnknownToolError;
+    UnknownExitError: typeof UnknownExitError;
+    UnknownComponentError: typeof UnknownComponentError;
+    ReservedIdentifierError: typeof ReservedIdentifierError;
+    ToolExecutionError: typeof ToolExecutionError;
+    LoopExceededError: typeof LoopExceededError;
+    TokenOverflowError: typeof TokenOverflowError;
+    MemoryCapacityError: typeof MemoryCapacityError;
+    AssignmentError: typeof AssignmentError;
+    CognitiveError: typeof CognitiveError;
+    CompactionError: typeof CompactionError;
+    InvalidToolError: typeof InvalidToolError;
+    InvalidObjectError: typeof InvalidObjectError;
+    InvalidExitError: typeof InvalidExitError;
+    InvalidComponentError: typeof InvalidComponentError;
+    InvalidConfigurationError: typeof InvalidConfigurationError;
+    InvalidMessageError: typeof InvalidMessageError;
+    InvalidEventError: typeof InvalidEventError;
+    InvalidSessionError: typeof InvalidSessionError;
+    SessionStateError: typeof SessionStateError;
+    MemoryValueError: typeof MemoryValueError;
+    NativeProtocolError: typeof NativeProtocolError;
+    HostOperationError: typeof HostOperationError;
+    DeliveryError: typeof DeliveryError;
+    MissingChatResponseError: typeof MissingChatResponseError;
+    HookError: typeof HookError;
+    ExecutionAbortedError: typeof ExecutionAbortedError;
+    InternalError: typeof InternalError;
+};
+/** Discriminated union of every library error. */
+export type LLMzFailure = InstanceType<(typeof errorClasses)[keyof typeof errorClasses]>;
+export type ErrorCode = LLMzFailure['code'];
+/** Test an unknown exception, optionally narrowing to a stable error code. */
+export declare function isLLMzError<C extends ErrorCode>(error: unknown, code: C): error is Extract<LLMzFailure, {
+    code: C;
+}>;
+export declare function isLLMzError(error: unknown): error is LLMzFailure;
+/** Critical errors end execution; they are never sent back to the model for retry. */
+export declare function isCriticalError(error: unknown): error is LLMzFailure & {
+    critical: true;
+};
+export {};

package/dist/errors/hooks.d.ts

@@ -0,0 +1,2 @@
+/** Hooks may reject an iteration to request a correction; explicit critical errors still stop execution. */
+export declare function callHook<T>(callback: () => T | Promise<T>): Promise<T>;