llmz 0.8.0 → 1.0.1

package/dist/runtime/types.d.ts

@@ -1,12 +1,12 @@
-import { Cognitive, type BotpressClientLike, Models, type SttModels } from '@botpress/cognitive';
-import { Chat } from '../chat.js';
+import { Cognitive, type CognitiveMessage, type BotpressClientLike, Models, type SttModels } from '@botpress/cognitive';
+import { Chat } from '../chat/chat.js';
 import { Context, Iteration } from '../context.js';
 import { _CustomModelClient } from '../custom-client.js';
-import type { Example } from '../example.js';
 import { Exit, ExitResult } from '../exit.js';
 import { ValueOrGetter } from '../getter.js';
+import type { OnInspect } from '../inspection.js';
 import { type ObjectInstance } from '../objects.js';
-import { Snapshot } from '../snapshots.js';
+import type { Session } from '../session/session.js';
 import { type Tool } from '../tool.js';
 import { Trace } from '../types.js';
 export type ExecutionHooks = {
@@ -31,9 +31,21 @@ export type ExecutionHooks = {
      *   This hook will block the execution of the iteration until it resolves.
      *
      * This hook will be called before each iteration starts, regardless of the status.
-     * This is useful for logging or dynamically change model arguments
+     * Use this for observation. Configure dynamic model arguments with their getters.
      */
-    onIterationStart?: (iteration: Iteration, controller: AbortController, context: Context) => Promise<void | Partial<Iteration>> | void | Partial<Iteration>;
+    onIterationStart?: (iteration: Iteration, controller: AbortController, context: Context) => Promise<void> | void;
+    /** Customize the assembled request after compaction. Custom messages must fit the context budget. */
+    onBeforeRequest?: (event: {
+        messages: CognitiveMessage[];
+        iteration: Iteration;
+        controller: AbortController;
+    }) => Promise<{
+        messages: CognitiveMessage[];
+    } | void> | {
+        messages: CognitiveMessage[];
+    } | void;
+    /** Format runtime values; LLMz enforces the supplied budget on custom output. */
+    onInspect?: OnInspect;
     /**
      * BLOCKING HOOK
      *   This hook will block the execution of the iteration until it resolves.
@@ -84,6 +96,8 @@ export type ExecutionHooks = {
         input: any;
         controller: AbortController;
         toolCallId: string;
+        /** Native run_javascript call owning this business call. */
+        nativeCallId?: string;
         object?: string;
     }) => Promise<{
         input?: any;
@@ -104,6 +118,8 @@ export type ExecutionHooks = {
         output: any;
         controller: AbortController;
         toolCallId: string;
+        /** Native run_javascript call owning this business call. */
+        nativeCallId?: string;
         object?: string;
     }) => Promise<{
         output?: any;
@@ -112,10 +128,15 @@ export type ExecutionHooks = {
 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)`.
+     * The effective limit is `min(maxTokens, smallest configured model input limit)`.
      * Useful to reduce cost and latency on models with very large context windows.
      */
     maxTokens?: number;
+    /**
+     * Default inspection budget for tool results, from 0 to 2,000 tokens.
+     * Defaults to 2,000. A tool's truncate() wrapper can override this limit.
+     */
+    toolResultMaxTokens?: 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
@@ -124,13 +145,11 @@ type Options = Partial<Pick<Context, 'loop' | 'timeout'>> & {
      */
     maxTimeToFirstToken?: number;
     /**
-     * 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.
+     * Allow Cognitive to restart a failed stream on another model. Previews remain
+     * live and are retracted with a restart delta before replacement output.
+     * Complete calls may execute while transport is open. Once execution starts,
+     * a stream failure or restart ends the iteration without replaying its effects.
+     * Streaming-only; defaults to false.
      */
     midStreamFallback?: boolean;
     /**
@@ -141,13 +160,15 @@ type Options = Partial<Pick<Context, 'loop' | 'timeout'>> & {
     transcriptionModel?: SttModels;
 };
 export type ExecutionProps = {
+    /** Append input to this session before execution. Retains history, queued input, and JavaScript memory. */
+    session?: Session;
     /**
      * If provided, the execution will be run in "Chat Mode".
-     * In this mode, the execution will be able to send messages to the chat and will also have access to a chat transcript.
+     * Chat configures assistant text and rich component delivery. Conversation input belongs to the session.
      * The execution can still end with a custom Exit, but a special ListenExit will be added to give back the chat control to the user.
      *
-     * If `chat` is not provided, the execution will run in "Worker Mode", where it will not have access to a chat transcript.
-     * In Worker Mode, the execution will iterate until it reaches an Exit or runs out of iterations.
+     * If `chat` is not provided, the execution will run in "Worker Mode" without chat delivery.
+     * In Worker Mode, the execution uses the same session history and memory, and iterates until an Exit or its limit.
      */
     chat?: Chat;
     /**
@@ -157,14 +178,6 @@ export type ExecutionProps = {
      * Dynamic instructions are evaluated at the start of each iteration, allowing for context-aware instructions.
      */
     instructions?: ValueOrGetter<string, Context>;
-    /**
-     * Labeled examples of one situation and one response, kept outside the live transcript.
-     * Use `new Example({ situation, code })` or `new Example({ situation, messages, exit })`.
-     * Evaluated each iteration, like instructions. Examples must use the current
-     * component/exit catalog. They are kept intact when the prompt is truncated;
-     * select a small relevant set to leave room for tools and conversation.
-     */
-    examples?: ValueOrGetter<Example[], Context>;
     /**
      * Objects available in the context.
      * Objects are useful to scope related tools together and to provide data to the VM.
@@ -197,7 +210,7 @@ export type ExecutionProps = {
      * Exits define the possible endpoints for the execution. Every execution will either end with an exit, or run out of iterations.
      *
      * When `chat` is provided, the built-in "ListenExit" is automatically added.
-     * When `exits` is not provided, the built-in "DefaultExit" is automatically added.
+     * In worker mode, omitting `exits` adds the built-in "DefaultExit". An explicit empty array provides no exits.
      *
      * Each exit has a name and can have aliases, which are alternative names for the exit that can be used to call it.
      * Exits can also have a Zui schema to validate the return value when the exit is reached.
@@ -219,14 +232,6 @@ export type ExecutionProps = {
      * Aborted iterations will end with IterationStatuses.Aborted and the execution will be marked as failed.
      */
     signal?: AbortSignal;
-    /**
-     * A snapshot is a saved state of the execution context.
-     * It can be used to resume the execution of a context at a later time.
-     * This is useful for long-running executions that may need to be paused and resumed later.
-     * The snapshot MUST be settled, which means it has to be resolved or rejected.
-     * Providing an unsettled snapshot will throw an error.
-     */
-    snapshot?: Snapshot;
     /**
      * The model to use for the LLM.
      * This can be a static model name or a function that returns a model name based on the current context.
@@ -255,8 +260,8 @@ export type ExecutionProps = {
 } & ExecutionHooks;
 export type RuntimeCognitive = Pick<Cognitive, 'getModelDetails' | 'generateText'> & {
     /**
-     * Streaming generation. When present, the runtime streams the response and
-     * parses ■ blocks incrementally.
+     * Streaming generation. Assistant text streams as provisional previews; native
+     * tool calls can execute while text streams; both settle before the next iteration.
      */
     generateTextStream?: Cognitive['generateTextStream'];
 };

package/dist/runtime/variable-recovery.test.d.ts

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

package/dist/runtime/vm-context.d.ts

@@ -1,5 +1,7 @@
 import { Context, Iteration } from '../context.js';
+import type { TruncationPolicy } from '../truncate.js';
 import { type VMContext } from '../vm/types.js';
+import type { JavaScriptApi } from './javascript-api.js';
 import { ExecutionHooks } from './types.js';
 type BuildVMContextProps = {
     ctx: Context;
@@ -7,6 +9,9 @@ type BuildVMContextProps = {
     controller: AbortController;
     onBeforeTool?: ExecutionHooks['onBeforeTool'];
     onAfterTool?: ExecutionHooks['onAfterTool'];
+    onTruncation?: (value: unknown, policy: TruncationPolicy) => void;
+    onToolResult?: (value: unknown) => void;
+    javascriptApi?: JavaScriptApi;
 };
-export declare const buildVMContext: ({ ctx, iteration, controller, onBeforeTool, onAfterTool, }: BuildVMContextProps) => VMContext;
+export declare const buildVMContext: ({ ctx, iteration, controller, onBeforeTool, onAfterTool, onTruncation, onToolResult, javascriptApi, }: BuildVMContextProps) => VMContext;
 export {};

package/dist/runtime/worker-completion.test.d.ts

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

package/dist/runtime-names.d.ts

@@ -0,0 +1,4 @@
+/** Runtime bindings are never tool names or retained user variables. */
+export declare const RUNTIME_BINDING_NAMES: readonly ['$return', '$iterations', 'exit', 'inspect', 'chat'];
+export declare const TERMINATION_BINDING_NAMES: readonly ['__llmz_guard', '__llmz_checkpoint', '__llmz_missing_tool'];
+export declare const RESERVED_RUNTIME_NAMES: ReadonlySet<string>;

package/dist/schema-Aer_W7Al.js

@@ -0,0 +1,45 @@
+import { H as isLLMzError, b as InvalidConfigurationError } from "./errors-H4JJFH3S.js";
+import { transforms, z } from "@bpinternal/zui";
+//#region src/schema.ts
+const INPUT_SCHEMA_OPTIONS = {
+	target: "openApi3",
+	effectStrategy: "input",
+	pipeStrategy: "input"
+};
+/** Describe values supplied to a schema; JavaScript effects remain in the original validator. */
+function toModelSchema(schema) {
+	try {
+		return transforms.toJSONSchema(schema);
+	} catch {
+		try {
+			return transforms.toJSONSchemaLegacy(schema, INPUT_SCHEMA_OPTIONS);
+		} catch (cause) {
+			throw new InvalidConfigurationError(`Cannot describe schema input: ${String(cause)}`, { cause });
+		}
+	}
+}
+/** Async tool inputs still run their validator exactly once, including before retries. */
+async function parseSchemaAsync(schema, value, subject) {
+	try {
+		return await schema.safeParseAsync(value);
+	} catch (cause) {
+		if (isLLMzError(cause)) throw cause;
+		throw new InvalidConfigurationError(`${subject} schema evaluation failed: ${String(cause)}`, { cause });
+	}
+}
+/** Exit, component and property APIs are synchronous. Tool inputs use safeParseAsync instead. */
+function parseSchemaSync(schema, value, subject) {
+	try {
+		return schema.safeParse(value);
+	} catch (cause) {
+		if (isLLMzError(cause)) throw cause;
+		throw new InvalidConfigurationError(`${subject} schema could not be evaluated synchronously. Use synchronous transforms and refinements here; put asynchronous validation in a tool input schema. ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+}
+/** Unwrap root effects without executing them or losing the original schema. */
+function schemaInput(schema) {
+	if (z.is.zuiEffects(schema)) return schemaInput(schema.innerType());
+	return z.is.zuiPipeline(schema) ? schemaInput(schema._def.in) : schema;
+}
+//#endregion
+export { toModelSchema as i, parseSchemaSync as n, schemaInput as r, parseSchemaAsync as t };

package/dist/schema-DBkjo0b7.cjs

@@ -0,0 +1,68 @@
+const require_errors = require("./errors-IhnTKUp7.cjs");
+let _bpinternal_zui = require("@bpinternal/zui");
+//#region src/schema.ts
+const INPUT_SCHEMA_OPTIONS = {
+	target: "openApi3",
+	effectStrategy: "input",
+	pipeStrategy: "input"
+};
+/** Describe values supplied to a schema; JavaScript effects remain in the original validator. */
+function toModelSchema(schema) {
+	try {
+		return _bpinternal_zui.transforms.toJSONSchema(schema);
+	} catch {
+		try {
+			return _bpinternal_zui.transforms.toJSONSchemaLegacy(schema, INPUT_SCHEMA_OPTIONS);
+		} catch (cause) {
+			throw new require_errors.InvalidConfigurationError(`Cannot describe schema input: ${String(cause)}`, { cause });
+		}
+	}
+}
+/** Async tool inputs still run their validator exactly once, including before retries. */
+async function parseSchemaAsync(schema, value, subject) {
+	try {
+		return await schema.safeParseAsync(value);
+	} catch (cause) {
+		if (require_errors.isLLMzError(cause)) throw cause;
+		throw new require_errors.InvalidConfigurationError(`${subject} schema evaluation failed: ${String(cause)}`, { cause });
+	}
+}
+/** Exit, component and property APIs are synchronous. Tool inputs use safeParseAsync instead. */
+function parseSchemaSync(schema, value, subject) {
+	try {
+		return schema.safeParse(value);
+	} catch (cause) {
+		if (require_errors.isLLMzError(cause)) throw cause;
+		throw new require_errors.InvalidConfigurationError(`${subject} schema could not be evaluated synchronously. Use synchronous transforms and refinements here; put asynchronous validation in a tool input schema. ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+}
+/** Unwrap root effects without executing them or losing the original schema. */
+function schemaInput(schema) {
+	if (_bpinternal_zui.z.is.zuiEffects(schema)) return schemaInput(schema.innerType());
+	return _bpinternal_zui.z.is.zuiPipeline(schema) ? schemaInput(schema._def.in) : schema;
+}
+//#endregion
+Object.defineProperty(exports, "parseSchemaAsync", {
+	enumerable: true,
+	get: function() {
+		return parseSchemaAsync;
+	}
+});
+Object.defineProperty(exports, "parseSchemaSync", {
+	enumerable: true,
+	get: function() {
+		return parseSchemaSync;
+	}
+});
+Object.defineProperty(exports, "schemaInput", {
+	enumerable: true,
+	get: function() {
+		return schemaInput;
+	}
+});
+Object.defineProperty(exports, "toModelSchema", {
+	enumerable: true,
+	get: function() {
+		return toModelSchema;
+	}
+});

package/dist/schema.d.ts

@@ -0,0 +1,10 @@
+import { z } from '@bpinternal/zui';
+import type { JSONSchema7 } from 'json-schema';
+/** Describe values supplied to a schema; JavaScript effects remain in the original validator. */
+export declare function toModelSchema(schema: z.ZodType): JSONSchema7;
+/** Async tool inputs still run their validator exactly once, including before retries. */
+export declare function parseSchemaAsync<T extends z.ZodType>(schema: T, value: unknown, subject: string): Promise<z.SafeParseReturnType<T["_input"], T["_output"]>>;
+/** Exit, component and property APIs are synchronous. Tool inputs use safeParseAsync instead. */
+export declare function parseSchemaSync<T extends z.ZodType>(schema: T, value: unknown, subject: string): z.SafeParseReturnType<T["_input"], T["_output"]>;
+/** Unwrap root effects without executing them or losing the original schema. */
+export declare function schemaInput(schema: z.ZodType): z.ZodType;

package/dist/schema.test.d.ts

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

package/dist/session/compactor.d.ts

@@ -0,0 +1,51 @@
+import { type BotpressClientLike, type Models } from '@botpress/cognitive';
+import type { RuntimeCognitive } from '../runtime/types.js';
+import type { SessionMessage } from './messages.js';
+import type { Session, SessionCompaction } from './session.js';
+import type { Transcript } from './transcript.js';
+export type SummaryRequest = {
+    /** A detached copy of the history being replaced; queued input is excluded. */
+    messages: readonly SessionMessage[];
+    maxTokens: number;
+    signal?: AbortSignal;
+};
+export type CompactionOptions = {
+    /** Start automatic compaction at this fraction of the input budget. Default: 0.85. */
+    triggerRatio?: number;
+    /** Aim for this fraction after compaction. Default: 0.65. */
+    targetRatio?: number;
+    /** Prefer to keep this many recent iterations; a hard overflow may require fewer. Default: 2. */
+    keepRecentIterations?: number;
+    /** Maximum summary length, reduced further when the request has less space. Default: 1024. */
+    maxSummaryTokens?: number;
+    /** Defaults to the execution model, or 'fast' for standalone summarization. */
+    model?: Models | Models[];
+    /** Replace the built-in LLM summarizer. Invalid or oversized output never replaces history. */
+    summarize?: (request: SummaryRequest) => Promise<string>;
+};
+export type SummarizeOptions = {
+    client: RuntimeCognitive | BotpressClientLike;
+    model?: Models | Models[];
+    maxTokens?: number;
+    /** Optional cap on the summarizer's context window, including its output reserve. */
+    contextWindow?: number;
+    signal?: AbortSignal;
+    /** Metadata attached to the summarizer's Cognitive usage records. */
+    metadata?: Record<string, string>;
+};
+export declare function resolveCompaction(options?: CompactionOptions): Readonly<{
+    triggerRatio: number;
+    targetRatio: number;
+    keepRecentIterations: number;
+    maxSummaryTokens: number;
+    model: Models[] | Models | undefined;
+    summarize: ((request: SummaryRequest) => Promise<string>) | undefined;
+}>;
+/** Select whole settled iterations, then summarize only after proving the mandatory input can fit. */
+export declare function prepareAutoCompaction(session: Session, options: SummarizeOptions & {
+    iterationId: string;
+    inputLimit: number;
+    measure(retainedIds: readonly string[], summary?: Transcript.SummaryMessage): number;
+}): Promise<SessionCompaction | undefined>;
+/** Summarize in bounded segments, including when the source history exceeds the model window. */
+export declare function summarizeMessages(messages: readonly SessionMessage[], options: SummarizeOptions, custom?: CompactionOptions['summarize']): Promise<Transcript.SummaryMessage>;

package/dist/session/compactor.test.d.ts

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

package/dist/session/history.d.ts

@@ -0,0 +1,36 @@
+import type { CognitiveMessage } from '@botpress/cognitive';
+import type { MemoryValue } from './memory-codec.js';
+import { type SessionMessage } from './messages.js';
+import type { Transcript } from './transcript.js';
+export type SessionIteration = {
+    id: string;
+    number: number;
+    turn: number;
+    turnId: string;
+    timestamp: number;
+};
+export type SessionIterationRecord = SessionIteration & {
+    outcome: string;
+    error?: string;
+} & ({
+    hasResult: true;
+    result: MemoryValue;
+    unavailable?: never;
+} | {
+    hasResult: false;
+    result?: never;
+    unavailable?: string;
+});
+export type HistoryGroup = {
+    id: string;
+    turn: number;
+    iteration?: SessionIterationRecord;
+    messages: SessionMessage[];
+    /** Preserve typed external events and compaction summaries alongside native model input. */
+    source?: Transcript.EventMessage | Transcript.SummaryMessage;
+};
+export declare function pendingCallIds(group: HistoryGroup): string[];
+export declare function validateBatch(message: CognitiveMessage): void;
+export declare function validateGroup(group: HistoryGroup): void;
+/** Select whole iterations and the inputs belonging to their turns. */
+export declare function compactHistory(groups: readonly HistoryGroup[], retained: ReadonlySet<string>, currentTurn: number, pendingId?: string): HistoryGroup[];

package/dist/session/history.test.d.ts

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

package/dist/session/json.d.ts

@@ -0,0 +1,3 @@
+export declare function stableJSON(value: unknown): string;
+/** Native provider payloads must survive the advertised JSON persistence API. */
+export declare function assertPersistableData(data: unknown): void;

package/dist/session/json.test.d.ts

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

package/dist/session/memory-codec.d.ts

@@ -0,0 +1,9 @@
+/** Exact, bounded session data. Model-facing previews are never used as stored values. */
+export type MemoryValue = null | undefined | boolean | number | string | MemoryValue[] | {
+    [key: string]: MemoryValue;
+};
+export type EncodedMemoryValue = ['negative-zero'] | ['undefined'] | ['value', null | boolean | number | string] | ['array', EncodedMemoryValue[]] | ['object', [string, EncodedMemoryValue][]];
+export declare function encodeMemoryValue(value: unknown, seen?: Set<object>): EncodedMemoryValue;
+export declare function decodeMemoryValue(value: EncodedMemoryValue): MemoryValue;
+export declare const cloneMemoryValue: (value: unknown) => MemoryValue;
+export declare function freezeMemoryValue<T>(value: T): T;

package/dist/session/memory-codec.test.d.ts

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

package/dist/session/memory-render.d.ts

@@ -0,0 +1,15 @@
+import { type Inspector } from '../inspection.js';
+import type { MemoryValue, NamedMemoryBinding, ObjectPropertyMemory } from './memory.js';
+import type { SessionIterationRecord } from './session.js';
+export declare function memoryValueType(value: MemoryValue): string;
+export declare function previewMemoryValue(value: MemoryValue): string;
+export declare function renderMemory(options: {
+    bindings: readonly NamedMemoryBinding[];
+    properties: readonly ObjectPropertyMemory[];
+    iterations?: readonly SessionIterationRecord[];
+    latestResultId?: string;
+    turn: number;
+    now?: number;
+    maxChars?: number;
+    inspector?: Inspector;
+}): string;

package/dist/session/memory-render.test.d.ts

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

package/dist/session/memory.d.ts

@@ -0,0 +1,112 @@
+import type { JSONSchema7Definition } from 'json-schema';
+import type { Inspector } from '../inspection.js';
+import type { ObjectInstance } from '../objects.js';
+import type { ObjectMutation } from '../types.js';
+import { type EncodedMemoryValue, type MemoryValue } from './memory-codec.js';
+export { MemoryCapacityError } from '../errors.js';
+export { cloneMemoryValue, decodeMemoryValue, type MemoryValue } from './memory-codec.js';
+export { previewMemoryValue } from './memory-render.js';
+export type VariableWrite = {
+    name: string;
+    timestamp: number;
+    kind?: 'assignment' | 'mutation';
+};
+export type MemoryProvenance = {
+    timestamp?: number;
+    turn?: number;
+    turnId?: string;
+    id?: string;
+    number?: number;
+};
+export type MemoryChange = {
+    name: string;
+    type: string;
+    preview: string;
+    provenance: MemoryProvenance;
+};
+export type ObjectPropertyMemory = {
+    hostValue?: MemoryValue;
+    object: string;
+    property: string;
+    value: MemoryValue;
+    type: string;
+    schema?: JSONSchema7Definition;
+    writable: boolean;
+    description?: string;
+    provenance: MemoryProvenance;
+};
+export type MemoryBinding = {
+    value: MemoryValue;
+    created: MemoryProvenance;
+    assigned: MemoryProvenance;
+    updated?: MemoryProvenance;
+};
+export type NamedMemoryBinding = MemoryBinding & {
+    name: string;
+};
+export type SerializedMemory = {
+    version: 2;
+    maxBytes: number;
+    variables: {
+        name: string;
+        value: EncodedMemoryValue;
+        created: MemoryProvenance;
+        assigned: MemoryProvenance;
+        updated?: MemoryProvenance;
+    }[];
+    objects?: (Omit<ObjectPropertyMemory, 'value' | 'hostValue'> & {
+        value: EncodedMemoryValue;
+        hostValue?: EncodedMemoryValue;
+    })[];
+};
+export type MemoryAssignment = MemoryProvenance & {
+    variableWrites?: VariableWrite[];
+    captureErrors?: {
+        name: string;
+        reason: string;
+    }[];
+};
+export type MemoryReport = {
+    created: MemoryChange[];
+    updated: MemoryChange[];
+    unavailable: {
+        name: string;
+        reason: string;
+    }[];
+    resultAvailable: boolean;
+};
+export declare class Memory {
+    private _bindings;
+    private _objectProperties;
+    private _activeObjects;
+    private readonly _additionalBytes;
+    readonly maxBytes: number;
+    constructor(options?: {
+        variables?: Record<string, unknown>;
+        maxBytes?: number;
+        /** Bytes retained by the owning Session, outside named/object memory. */
+        additionalBytes?: () => number;
+    });
+    private _assertName;
+    /** Object values remain authoritative in the host; this inventory never injects mutable duplicates. */
+    syncObjects(objects: readonly Pick<ObjectInstance, 'name' | 'properties'>[], observation?: MemoryProvenance): Promise<void>;
+    getObjectPropertyValue(object: string, property: string): MemoryValue;
+    /** Reject collisions before executing code, even if the conflicting declaration would run later. */
+    assertNamesAvailable(names: Iterable<string>): void;
+    recordObjectMutations(mutations: readonly ObjectMutation[], provenance: MemoryProvenance): MemoryChange[];
+    get variables(): Record<string, MemoryValue>;
+    get bindings(): readonly NamedMemoryBinding[];
+    get objectProperties(): readonly ObjectPropertyMemory[];
+    assign(variables: Record<string, unknown>, metadata: MemoryAssignment): MemoryReport;
+    render(options: {
+        turn: number;
+        now?: number;
+        maxChars?: number;
+        inspector?: Inspector;
+    }): string;
+    serialize(): SerializedMemory;
+    toJSON(): SerializedMemory;
+    static fromJSON(state: SerializedMemory): Memory;
+    static restore(state: SerializedMemory, additionalBytes?: () => number): Memory;
+    assertCapacity(additionalBytes?: number): void;
+}

package/dist/session/memory.test.d.ts

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

package/dist/session/messages.d.ts

@@ -0,0 +1,17 @@
+import type { CognitiveMessage, CognitiveToolCall } from '@botpress/cognitive';
+import { type Transcript } from './transcript.js';
+/** A native message plus opaque adapter fields, preserved without interpreting them. */
+export type SessionMessage = CognitiveMessage & Record<string, unknown>;
+export type SessionInput = CognitiveMessage | Transcript.Message;
+export type AssistantResponse = {
+    output: string;
+    toolCalls?: CognitiveToolCall[];
+    assistantMessage?: CognitiveMessage;
+    continuation?: unknown;
+};
+export declare function normalizeInput(message: SessionInput): SessionMessage;
+export declare function createAssistantMessage(response: AssistantResponse): SessionMessage;
+export declare function validateInputMessage(message: CognitiveMessage): void;
+export declare function validateMessageContent(message: CognitiveMessage): void;
+/** Add runtime context to an isolated request, leaving canonical history untouched. */
+export declare function withMemoryOverview(history: readonly SessionMessage[], overview?: string): SessionMessage[];

package/dist/session/messages.test.d.ts

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

package/dist/session/serialization.d.ts

@@ -0,0 +1,34 @@
+import type { CompactionOptions } from './compactor.js';
+import { type HistoryGroup, type SessionIterationRecord } from './history.js';
+import { type EncodedMemoryValue } from './memory-codec.js';
+import type { SerializedMemory } from './memory.js';
+import { type SessionMessage } from './messages.js';
+type SerializedHistoryGroup = Omit<HistoryGroup, 'iteration'> & {
+    iteration?: Omit<SessionIterationRecord, 'result'> & {
+        result?: EncodedMemoryValue;
+    };
+};
+export type PendingInput = {
+    id: string;
+    message: SessionMessage;
+    source?: HistoryGroup['source'];
+};
+export type SessionState = {
+    version: 3;
+    id: string;
+    turn: number;
+    turnId: string;
+    iteration: number;
+    groups: SerializedHistoryGroup[];
+    memory: SerializedMemory;
+    pendingInputs: PendingInput[];
+    activeTurn: boolean;
+    latestResultId?: string;
+    compaction?: false | Omit<CompactionOptions, 'summarize'>;
+};
+/** Persisted counters, native identities, and exact values must describe one history. */
+export declare function validateRestoredHistory(state: SessionState): void;
+export declare function serializeGroup(group: HistoryGroup): SerializedHistoryGroup;
+export declare function restoreGroup(group: SerializedHistoryGroup): HistoryGroup;
+export declare function resultBytes(records: readonly SessionIterationRecord[]): number;
+export {};

package/dist/session/serialization.test.d.ts

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

package/dist/session/session-memory.test.d.ts

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