llmz 0.9.0 → 1.0.2

package/dist/schema-CXlnbb3n.cjs

@@ -0,0 +1,68 @@
+const require_errors = require("./errors-C6ppQUZX.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-GE4ISPCR.js

@@ -0,0 +1,45 @@
+import { U as isLLMzError, b as InvalidConfigurationError } from "./errors-Crk5P8jo.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.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,19 @@
+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;
+/** Only actual participant content counts as speech, including image/audio-only messages. */
+export declare function inputSpeaker(message: SessionMessage): 'user' | 'assistant' | null;
+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,36 @@
+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;
+    /** Acknowledged conversation speaker, independent of retained/compacted history. Absent in older snapshots. */
+    lastSpeaker?: 'user' | 'assistant' | null;
+    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 {};

package/dist/session/session.d.ts

@@ -0,0 +1,121 @@
+import type { Inspector } from '../inspection.js';
+import { resolveCompaction, type CompactionOptions, type SummarizeOptions } from './compactor.js';
+import { type SessionIteration, type SessionIterationRecord } from './history.js';
+import { type MemoryValue } from './memory-codec.js';
+import { Memory, type MemoryAssignment, type MemoryReport } from './memory.js';
+import { type AssistantResponse, type SessionInput, type SessionMessage } from './messages.js';
+import { type SessionState } from './serialization.js';
+import type { Transcript } from './transcript.js';
+export type { SessionIteration, SessionIterationRecord } from './history.js';
+export type { SessionInput, SessionMessage } from './messages.js';
+export type IterationCapture = MemoryAssignment & {
+    id: string;
+    variables?: Record<string, unknown>;
+    hasResult?: boolean;
+    result?: unknown;
+};
+export declare namespace Session {
+    type JSON = SessionState;
+}
+export type SessionOptions = {
+    variables?: Record<string, unknown>;
+    maxBytes?: number;
+    /** Automatic LLM summarization is enabled by default. Set false to preserve history and fail on overflow. */
+    compaction?: false | CompactionOptions;
+};
+export type SessionCompaction = {
+    summary: Transcript.SummaryMessage;
+    retainedIterationIds: readonly string[];
+    /** Commit only after the final request and all request hooks pass their budget checks. */
+    commit(): void;
+};
+/**
+ * Owns canonical native conversation history and its exact JavaScript memory.
+ * Reuse a Session across execute() calls; persist toJSON(), not prompt previews.
+ */
+export declare class Session {
+    #private;
+    readonly id: string;
+    readonly memory: Memory;
+    readonly compaction: false | ReturnType<typeof resolveCompaction>;
+    constructor(options?: SessionOptions);
+    get turn(): number;
+    get turnId(): string;
+    get iteration(): number;
+    get messages(): SessionMessage[];
+    /** Retained conversation plus queued input, preserving event and summary roles. Returns a detached copy. */
+    get transcript(): SessionInput[];
+    /** Last participant who spoke in the active history. Events and queued inputs do not count. */
+    get lastSpeaker(): 'user' | 'assistant' | null;
+    /** Record acknowledged text or component delivery, never generation alone. */
+    recordAssistantDelivery(iterationId: string): void;
+    get pendingMessages(): SessionMessage[];
+    get hasActiveTurn(): boolean;
+    get status(): 'idle' | 'pending' | 'active';
+    get retainedIterationIds(): string[];
+    get pendingCalls(): Array<{
+        iterationId: string;
+        callId: string;
+    }>;
+    /** Exact retained execution results, newest first. Each access returns a frozen copy. */
+    get iterations(): readonly SessionIterationRecord[];
+    getBindings(): Record<string, MemoryValue>;
+    renderMemory(options?: {
+        now?: number;
+        maxChars?: number;
+        inspector?: Inspector;
+    }): string;
+    /** Prevent concurrent execute() calls from changing a shared session. */
+    acquire(): () => void;
+    /**
+     * Queue new input for the next turn. Appending during an execution never
+     * changes the batch currently being processed. Identical messages stay distinct.
+     */
+    append(input: SessionInput | readonly SessionInput[]): void;
+    /** Claim queued input, or continue the current turn after a failed execution. */
+    beginTurn(): void;
+    /** Mark the active input batch complete without consuming newly queued input. */
+    completeTurn(): void;
+    nextIteration(id?: string): SessionIteration;
+    appendAssistant(iterationId: string, response: AssistantResponse): void;
+    appendToolResult(iterationId: string, callId: string, content: string): void;
+    /** Capture successful writes and the inspection result even when later delivery fails. */
+    commitIteration(input: IterationCapture): MemoryReport;
+    /** Set the outcome once, after generation, code and delivery have all finished. */
+    settleIteration(iterationId: string, outcome?: {
+        outcome: string;
+        error?: string;
+    }): void;
+    /** Reserve failure metadata before model generation or side effects begin. */
+    assertCapacityForIteration(info: SessionIteration): void;
+    /** Discard a preflight failure that generated no response and ran no code. */
+    cancelIteration(iterationId: string): void;
+    /** Runtime feedback without inventing a tool-call identity or user turn. */
+    appendContext(content: string): void;
+    /**
+     * Build ephemeral model input. Canonical user text/tool results remain intact;
+     * the dynamic inventory is generated once, on the final eligible input only.
+     */
+    requestMessages(options?: {
+        memory?: boolean | string;
+        now?: number;
+        maxMemoryChars?: number;
+        inspector?: Inspector;
+        /** Preview compaction without discarding retained history or results. */
+        retainedIterationIds?: Iterable<string>;
+        /** Preview a prepared summary without changing the transcript. */
+        summary?: Transcript.SummaryMessage;
+    }): SessionMessage[];
+    /** Keep complete iterations, pruning their automatic results in the same operation. */
+    prune(retainedIds: Iterable<string>): void;
+    /** Summarize processed conversation without changing it. Queued inputs remain for the next turn. */
+    summarize(options: SummarizeOptions): Promise<Transcript.SummaryMessage | undefined>;
+    /** Replace older complete history with a summary, preserving named memory and queued input. */
+    compact(options: SummarizeOptions & {
+        keepRecentIterations?: number;
+    }): Promise<Transcript.SummaryMessage | undefined>;
+    /** @internal Prepare a transactional summary; callers must validate its final request before committing. */
+    prepareCompaction(retainedIds: Iterable<string>, options: SummarizeOptions): Promise<SessionCompaction | undefined>;
+    toJSON(): Session.JSON;
+    static fromJSON(state: Session.JSON, options?: Pick<SessionOptions, 'compaction'>): Session;
+}

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

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

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

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

package/dist/{transcript.d.ts → session/transcript.d.ts}

@@ -4,8 +4,7 @@ export declare namespace Transcript {
      *
      * - `image`: a picture the model can see.
      * - `audio`: a voice message — spoken audio of what the user said. Messages
-     *   carrying an audio attachment are presented to the model as spoken turns
-     *   (tagged `modality="voice"` in the prompt) and the audio is sent as model
+     *   carrying an audio attachment are presented as spoken turns, with audio sent as model
      *   input: audio-capable models hear it directly, others receive a
      *   transcription (see `@botpress/cognitive`'s `transcriptionModel` option).
      *
@@ -13,8 +12,7 @@ export declare namespace Transcript {
      *
      * `id` is an optional stable identifier for referencing the attachment from
      * the message content (e.g. `screenshot-A` in a screen-share event log). It
-     * is used as the attachment's reference in the prompt; without it, a
-     * positional letter (A, B, C...) is auto-assigned.
+     * is preserved next to the attachment in the native message.
      *
      * `alt` is an optional human-readable description shown to the model next to
      * the attachment (e.g. "Screenshot of the checkout error page").
@@ -66,7 +64,5 @@ export declare namespace Transcript {
 }
 /** Whether the message is a spoken turn: explicit voice modality or an audio attachment. */
 export declare function isVoiceMessage(message: Transcript.Message): boolean;
-export declare class TranscriptArray extends Array<Transcript.Message> {
-    constructor(items?: Transcript.Message[]);
-    toString(): string;
-}
+/** Validate the convenience input shape before converting it to a native message. */
+export declare function validateTranscriptMessage(message: Transcript.Message): void;

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

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