@xybrid/react-native 0.10.0-rc1

package/lib/commonjs/wire.js

@@ -0,0 +1,285 @@
+"use strict";
+// Translation between the public types and the plain objects that cross the
+// TurboModule boundary. Every convenience field (voiceId, speed, sampleRate,
+// channels, role) is folded into / lifted out of envelope metadata HERE, once,
+// so the native codecs stay generic and lossless: an envelope is a payload
+// kind plus string metadata, exactly like bolt's `XybridEnvelope`.
+//
+// Pure functions only — no native calls — so tests/wire.test.mjs covers them
+// on Node.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWireEnvelope = toWireEnvelope;
+exports.fromWireEnvelope = fromWireEnvelope;
+exports.normalizeImageFormat = normalizeImageFormat;
+exports.toWireToolDefinition = toWireToolDefinition;
+exports.toWireGenerationConfig = toWireGenerationConfig;
+exports.fromWireGenerationConfig = fromWireGenerationConfig;
+exports.toWireRunOptions = toWireRunOptions;
+exports.toWireToolResult = toWireToolResult;
+exports.fromWireResult = fromWireResult;
+exports.fromWireStreamToken = fromWireStreamToken;
+exports.fromWirePipelineResult = fromWirePipelineResult;
+exports.fromWireDownloadStatus = fromWireDownloadStatus;
+// Metadata keys the Rust core reads; see the Swift/Kotlin envelope factories.
+const KEY_VOICE_ID = 'voice_id';
+const KEY_SPEED = 'speed';
+const KEY_SAMPLE_RATE = 'sample_rate';
+const KEY_CHANNELS = 'channels';
+const KEY_ROLE = 'xybrid.role';
+const ROLES = ['system', 'user', 'assistant'];
+// -- Envelopes ----------------------------------------------------------------
+function setIfDefined(target, key, value) {
+    if (value !== undefined && value !== null)
+        target[key] = String(value);
+}
+/**
+ * Fold an envelope's convenience fields into metadata. Typed fields win over
+ * raw `metadata` entries for the same key; audio input defaults to 16 kHz
+ * mono, like the Swift and Kotlin `Envelope.audio` factories.
+ */
+function toWireEnvelope(envelope) {
+    if (envelope == null || typeof envelope !== 'object') {
+        throw new TypeError('An envelope must be an object with a `kind` field');
+    }
+    const metadata = { ...(envelope.metadata ?? {}) };
+    setIfDefined(metadata, KEY_ROLE, envelope.role);
+    switch (envelope.kind) {
+        case 'text':
+            requireType(envelope.text, 'string', 'text envelope: `text`');
+            setIfDefined(metadata, KEY_VOICE_ID, envelope.voiceId);
+            setIfDefined(metadata, KEY_SPEED, envelope.speed);
+            return { kind: 'text', text: envelope.text, metadata };
+        case 'audio':
+            requireType(envelope.bytesBase64, 'string', 'audio envelope: `bytesBase64`');
+            setIfDefined(metadata, KEY_SAMPLE_RATE, envelope.sampleRate ?? metadata[KEY_SAMPLE_RATE] ?? 16000);
+            setIfDefined(metadata, KEY_CHANNELS, envelope.channels ?? metadata[KEY_CHANNELS] ?? 1);
+            return { kind: 'audio', bytesBase64: envelope.bytesBase64, metadata };
+        case 'embedding':
+            if (!Array.isArray(envelope.data)) {
+                throw new TypeError('embedding envelope: `data` must be a number array');
+            }
+            return { kind: 'embedding', data: envelope.data, metadata };
+        case 'image':
+            requireType(envelope.bytesBase64, 'string', 'image envelope: `bytesBase64`');
+            return {
+                kind: 'image',
+                bytesBase64: envelope.bytesBase64,
+                format: normalizeImageFormat(envelope.format),
+                metadata,
+            };
+        case 'multipart':
+            if (!Array.isArray(envelope.parts)) {
+                throw new TypeError('multipart envelope: `parts` must be an array');
+            }
+            return { kind: 'multipart', parts: envelope.parts.map(toWireEnvelope), metadata };
+        default:
+            throw new TypeError(`Unknown envelope kind: ${String(envelope.kind)}`);
+    }
+}
+/** Lift well-known metadata keys back into typed fields. Lossless. */
+function fromWireEnvelope(wire) {
+    const metadata = { ...(wire.metadata ?? {}) };
+    const role = metadata[KEY_ROLE];
+    const base = {
+        ...(role && ROLES.includes(role) ? { role } : {}),
+        metadata,
+    };
+    switch (wire.kind) {
+        case 'text': {
+            const speed = parseNumber(metadata[KEY_SPEED]);
+            return {
+                kind: 'text',
+                text: wire.text,
+                ...(metadata[KEY_VOICE_ID] !== undefined ? { voiceId: metadata[KEY_VOICE_ID] } : {}),
+                ...(speed !== undefined ? { speed } : {}),
+                ...base,
+            };
+        }
+        case 'audio': {
+            const sampleRate = parseNumber(metadata[KEY_SAMPLE_RATE]);
+            const channels = parseNumber(metadata[KEY_CHANNELS]);
+            return {
+                kind: 'audio',
+                bytesBase64: wire.bytesBase64,
+                ...(sampleRate !== undefined ? { sampleRate } : {}),
+                ...(channels !== undefined ? { channels } : {}),
+                ...base,
+            };
+        }
+        case 'embedding':
+            return { kind: 'embedding', data: wire.data, ...base };
+        case 'image':
+            return {
+                kind: 'image',
+                bytesBase64: wire.bytesBase64,
+                format: normalizeImageFormat(wire.format),
+                ...base,
+            };
+        case 'multipart':
+            return { kind: 'multipart', parts: wire.parts.map(fromWireEnvelope), ...base };
+        default:
+            throw new Error(`Unexpected envelope kind from native: ${String(wire.kind)}`);
+    }
+}
+/** Accept `jpg` as an alias and reject anything the core cannot decode. */
+function normalizeImageFormat(format) {
+    const normalized = String(format ?? '').trim().toLowerCase();
+    if (normalized === 'jpg' || normalized === 'jpeg')
+        return 'jpeg';
+    if (normalized === 'png' || normalized === 'webp')
+        return normalized;
+    throw new TypeError(`Unsupported image format '${format}'. Supported: png, jpeg, jpg, webp`);
+}
+// -- Options ------------------------------------------------------------------
+const GENERATION_KEYS = [
+    'maxTokens',
+    'temperature',
+    'topP',
+    'minP',
+    'topK',
+    'repetitionPenalty',
+    'stopSequences',
+    'grammar',
+    'tools',
+];
+function toWireToolDefinition(tool) {
+    const parameters = tool.parameters;
+    return {
+        name: tool.name,
+        description: tool.description,
+        parametersJson: typeof parameters === 'string' ? parameters : JSON.stringify(parameters),
+    };
+}
+function toWireGenerationConfig(config) {
+    const { tools, ...rest } = config;
+    return {
+        ...rest,
+        ...(tools ? { tools: tools.map(toWireToolDefinition) } : {}),
+    };
+}
+function fromWireGenerationConfig(wire) {
+    const { tools, ...rest } = wire;
+    return {
+        ...rest,
+        tools: (tools ?? []).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parametersJson,
+        })),
+    };
+}
+/**
+ * Build the wire options. Sampling parameters must sit under
+ * `generationConfig`; passing them at the top level is a mistake that would
+ * otherwise be silently ignored, so it throws.
+ */
+function toWireRunOptions(options, handles = {}) {
+    if (options != null && typeof options !== 'object') {
+        throw new TypeError('Run options must be an object');
+    }
+    const misplaced = GENERATION_KEYS.filter((key) => options != null && key in options);
+    if (misplaced.length > 0) {
+        throw new TypeError(`Sampling parameters belong under \`generationConfig\` (got ${misplaced.join(', ')} ` +
+            'at the top level of the run options)');
+    }
+    const wire = {};
+    if (options?.generationConfig) {
+        wire.generationConfig = toWireGenerationConfig(options.generationConfig);
+    }
+    if (options?.abortOn)
+        wire.abortOn = [...options.abortOn];
+    if (options?.fallbackToCloud !== undefined)
+        wire.fallbackToCloud = options.fallbackToCloud;
+    if (options?.maxGraceTokens !== undefined)
+        wire.maxGraceTokens = options.maxGraceTokens;
+    if (options?.correlationId !== undefined)
+        wire.correlationId = options.correlationId;
+    if (handles.context)
+        wire.context = handles.context;
+    if (handles.cancel)
+        wire.cancel = handles.cancel;
+    return Object.keys(wire).length > 0 ? wire : null;
+}
+function toWireToolResult(result) {
+    const { content } = result;
+    return {
+        callId: result.callId,
+        name: result.name,
+        contentJson: typeof content === 'string' ? content : JSON.stringify(content ?? null),
+    };
+}
+// -- Results ------------------------------------------------------------------
+/** Convenience payload fields derived from an envelope (no copies). */
+function payloadFields(envelope) {
+    switch (envelope.kind) {
+        case 'text':
+            return { text: envelope.text };
+        case 'audio':
+            return { audioBytesBase64: envelope.bytesBase64 };
+        case 'embedding':
+            return { embedding: envelope.data };
+        default:
+            return {};
+    }
+}
+function fromWireResult(wire) {
+    return {
+        envelope: fromWireEnvelope(wire.envelope),
+        outputType: wire.outputType,
+        modelId: wire.modelId,
+        ...payloadFields(wire.envelope),
+        ...(wire.reasoningContent !== undefined ? { reasoningContent: wire.reasoningContent } : {}),
+        toolCalls: wire.toolCalls ?? [],
+        latencyMs: wire.latencyMs,
+        metrics: wire.metrics,
+        executionTarget: wire.executionTarget,
+    };
+}
+function fromWireStreamToken(wire) {
+    return { ...wire, toolCalls: wire.toolCalls ?? [] };
+}
+function fromWireStage(wire) {
+    const payload = payloadFields(wire.envelope);
+    return {
+        stageId: wire.stageId,
+        envelope: fromWireEnvelope(wire.envelope),
+        outputType: wire.outputType,
+        ...(payload.text !== undefined ? { text: payload.text } : {}),
+        ...(payload.audioBytesBase64 !== undefined
+            ? { audioBytesBase64: payload.audioBytesBase64 }
+            : {}),
+        latencyMs: wire.latencyMs,
+        executionTarget: wire.executionTarget,
+        metrics: wire.metrics,
+    };
+}
+function fromWirePipelineResult(wire) {
+    const payload = payloadFields(wire.envelope);
+    return {
+        envelope: fromWireEnvelope(wire.envelope),
+        outputType: wire.outputType,
+        ...(payload.text !== undefined ? { text: payload.text } : {}),
+        ...(payload.audioBytesBase64 !== undefined
+            ? { audioBytesBase64: payload.audioBytesBase64 }
+            : {}),
+        latencyMs: wire.latencyMs,
+        stages: wire.stages.map(fromWireStage),
+    };
+}
+function fromWireDownloadStatus(wire) {
+    // Both shims omit `totalBytes` when unknown; drop an explicit null too so
+    // callers can rely on `status.totalBytes === undefined`.
+    const { totalBytes, ...rest } = wire;
+    return totalBytes == null ? rest : { ...rest, totalBytes };
+}
+// -- Helpers ------------------------------------------------------------------
+function requireType(value, type, what) {
+    if (typeof value !== type)
+        throw new TypeError(`${what} must be a ${type}`);
+}
+function parseNumber(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}

package/lib/commonjs/xybrid.js

@@ -0,0 +1,133 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Xybrid = void 0;
+const react_native_1 = require("react-native");
+const NativeXybrid_1 = __importDefault(require("./NativeXybrid"));
+const model_1 = require("./model");
+let initialized = false;
+/**
+ * Process-wide SDK entry points. Local inference needs no setup at all —
+ * `initialize` only matters for the optional platform features.
+ */
+exports.Xybrid = {
+    /**
+     * Apply process-wide configuration. The SDK otherwise configures itself
+     * anonymously on first use, so call this before anything else when you
+     * have options. Configuration is applied once per app process: repeating
+     * it with the same options resolves, with different options rejects
+     * (`xybrid_config_error`) — restart the app to change them.
+     */
+    async initialize(options = {}) {
+        await NativeXybrid_1.default.initialize(options);
+        initialized = true;
+    },
+    /** Whether {@link initialize} has resolved in this JS context. */
+    get isInitialized() {
+        return initialized;
+    },
+    /** Describe a registry model without loading it (same as `ModelLoader.fromRegistry`). */
+    model(id) {
+        return model_1.ModelLoader.fromRegistry(id);
+    },
+    /** The native SDK version, e.g. `0.9.0`. */
+    version() {
+        return NativeXybrid_1.default.sdkVersion();
+    },
+    /** Whether an API key resolves, from {@link initialize} or the environment. */
+    hasApiKey() {
+        return NativeXybrid_1.default.hasApiKey();
+    },
+    /** Set the key for a cloud provider the gateway forwards to (not the Xybrid key). */
+    setProviderApiKey(provider, apiKey) {
+        return NativeXybrid_1.default.setProviderApiKey(provider, apiKey);
+    },
+    /** Point the cloud gateway at a platform base URL; the `/v1` suffix is added for you. */
+    setPlatformUrl(url) {
+        return NativeXybrid_1.default.setPlatformUrl(url);
+    },
+    /**
+     * Default speculative cloud serving on or off for loads that don't opt in
+     * per load (`ModelLoader.fromRegistrySpeculative` always speculates). Needs
+     * an API key. LLM/chat only — prefer the per-load form when the app also
+     * loads ASR/TTS models.
+     */
+    setSpeculativeCloud(enabled) {
+        return NativeXybrid_1.default.setSpeculativeCloud(enabled);
+    },
+    isSpeculativeCloudEnabled() {
+        return NativeXybrid_1.default.isSpeculativeCloudEnabled();
+    },
+    /**
+     * Release every idle model's memory; resolves how many were released. Runs
+     * in flight are skipped, and a released model reloads itself on next use.
+     */
+    releaseMemory() {
+        return NativeXybrid_1.default.releaseMemory();
+    },
+    /**
+     * Call {@link releaseMemory} on every OS memory warning (React Native
+     * `AppState` `memoryWarning`, iOS and Android). Returns the unsubscribe
+     * function.
+     */
+    releaseMemoryOnWarning() {
+        const subscription = react_native_1.AppState.addEventListener('memoryWarning', () => {
+            NativeXybrid_1.default.releaseMemory().catch(() => { });
+        });
+        return () => subscription.remove();
+    },
+    /** Release least-recently-used idle models before loads under memory pressure. */
+    setAutoRelease(enabled) {
+        return NativeXybrid_1.default.setAutoRelease(enabled);
+    },
+    isAutoReleaseEnabled() {
+        return NativeXybrid_1.default.isAutoReleaseEnabled();
+    },
+    // -- Device state. Both platforms already observe battery (and Android
+    //    thermal) natively; these exist for tests and custom readings. --
+    /** Push a battery percentage (0–100) to the routing engine. */
+    setBatteryLevel(percent) {
+        return NativeXybrid_1.default.setBatteryLevel(percent);
+    },
+    clearBatteryLevel() {
+        return NativeXybrid_1.default.clearBatteryLevel();
+    },
+    setThermalState(state) {
+        return NativeXybrid_1.default.setThermalState(state);
+    },
+    clearThermalState() {
+        return NativeXybrid_1.default.clearThermalState();
+    },
+    // -- Model cache. Every call walks or deletes the cache on disk, off the
+    //    JS thread. --
+    /** Aggregate storage usage across every managed cache location. */
+    async modelCacheStatus() {
+        return (await NativeXybrid_1.default.cacheStatus());
+    },
+    /** Physical entries; a model can appear more than once. */
+    async modelCacheEntries() {
+        return (await NativeXybrid_1.default.cacheEntries());
+    },
+    /** Whether `modelId` occupies any cache entry. */
+    hasCachedModelData(modelId) {
+        return NativeXybrid_1.default.cacheIsModelCached(modelId);
+    },
+    /** A local path for `modelId`, or `null`. Presence does not mean extracted. */
+    cachedModelPath(modelId) {
+        return NativeXybrid_1.default.cacheModelPath(modelId);
+    },
+    /** Models extracted, validated and ready to run offline. */
+    extractedModelIds() {
+        return NativeXybrid_1.default.cacheExtractedModelIds();
+    },
+    /** Remove every cache entry for `modelId`. Don't race a load of the same model. */
+    removeCachedModel(modelId) {
+        return NativeXybrid_1.default.cacheRemoveModel(modelId);
+    },
+    /** Clear all managed cache storage. Don't race any model load. */
+    clearModelCache() {
+        return NativeXybrid_1.default.cacheClear();
+    },
+};

package/lib/module/NativeXybrid.js

@@ -0,0 +1,22 @@
+// TurboModule spec consumed by React Native Codegen — the one contract both
+// native shims are compiled against: Android extends the generated
+// `NativeXybridSpec` class and iOS conforms to the generated
+// `NativeXybridSpec` protocol (tests/spec-conformance.test.mjs checks the
+// selectors without a Mac).
+//
+// Codegen accepts only `string`, `number`, `boolean`, `Object`, arrays and
+// `Promise`s of those, and `| null`. Structured values therefore cross as
+// plain `Object`s: the TS facade (src/index.ts) builds and narrows them, and
+// the native codecs (ios/XybridCodec.swift, android/.../XybridCodec.kt)
+// translate them to and from the bolt types.
+//
+// Native objects (models, conversation contexts, cancellation tokens, token
+// streams, downloads, pipelines, live-ASR sessions) are opaque string handles
+// held in one registry per platform. `dispose` frees any of them, and freeing
+// a model also disposes the token streams started from it.
+//
+// Nothing here is public API. Keep method names distinct from NSObject /
+// Java `Object` members (hence `dispose`, not `release`; `sdkVersion`, not
+// `version`).
+import { TurboModuleRegistry } from 'react-native';
+export default TurboModuleRegistry.getEnforcing('RNXybrid');

package/lib/module/base64.js

@@ -0,0 +1,41 @@
+// Minimal base64 for the one binary payload JS produces itself: live-ASR PCM.
+// Hermes has no Buffer, and `btoa` only takes binary strings, so encode the
+// bytes directly. Every platform React Native runs on is little-endian, which
+// is the byte order the native shims decode Float32 samples in.
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** Standard (RFC 4648, padded) base64 of `bytes`. */
+export function bytesToBase64(bytes) {
+    const chunks = [];
+    let chunk = '';
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        chunk +=
+            ALPHABET[(n >> 18) & 63] +
+                ALPHABET[(n >> 12) & 63] +
+                ALPHABET[(n >> 6) & 63] +
+                ALPHABET[n & 63];
+        // Flush periodically so long inputs don't build one enormous rope.
+        if (chunk.length >= 8192) {
+            chunks.push(chunk);
+            chunk = '';
+        }
+    }
+    const rest = bytes.length - i;
+    if (rest === 1) {
+        const n = bytes[i] << 16;
+        chunk += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + '==';
+    }
+    else if (rest === 2) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+        chunk +=
+            ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + '=';
+    }
+    chunks.push(chunk);
+    return chunks.join('');
+}
+/** Base64 of Float32 PCM samples as little-endian bytes. */
+export function float32ToBase64(samples) {
+    const floats = samples instanceof Float32Array ? samples : Float32Array.from(samples);
+    return bytesToBase64(new Uint8Array(floats.buffer, floats.byteOffset, floats.byteLength));
+}

package/lib/module/cancel.js

@@ -0,0 +1,29 @@
+import NativeXybrid from './NativeXybrid';
+const NO_SIGNAL = { token: null, release: () => Promise.resolve() };
+/**
+ * Create a native stop button wired to `signal`. Aborting the signal cancels
+ * the token, which stops generation at the next token boundary. A signal
+ * that is already aborted cancels the token before the call starts, so the
+ * call rejects with `xybrid_cancelled` instead of running.
+ */
+export async function bindCancel(signal) {
+    if (!signal)
+        return NO_SIGNAL;
+    const token = await NativeXybrid.createCancelToken();
+    const onAbort = () => {
+        NativeXybrid.cancel(token).catch(() => { });
+    };
+    if (signal.aborted) {
+        await NativeXybrid.cancel(token);
+    }
+    else {
+        signal.addEventListener('abort', onAbort);
+    }
+    return {
+        token,
+        release: async () => {
+            signal.removeEventListener('abort', onAbort);
+            await NativeXybrid.dispose(token).catch(() => { });
+        },
+    };
+}

package/lib/module/context.js

@@ -0,0 +1,60 @@
+import NativeXybrid from './NativeXybrid';
+import { fromWireEnvelope, toWireEnvelope } from './wire';
+/**
+ * Multi-turn conversation history, held natively. Pass it to
+ * `model.run(envelope, { context })` or `runStreaming`; inference reads the
+ * history but never changes it. The prompt you run is appended to the
+ * history for that run only, so push both turns *after* the run — pushing the
+ * prompt first would send it twice:
+ *
+ * ```ts
+ * const chat = await ConversationContext.create();
+ * await chat.setSystem('You are terse.');
+ *
+ * const question = Envelope.user('What is the capital of France?');
+ * const reply = await model.run(question, { context: chat });
+ * await chat.push(question);
+ * await chat.push(reply.envelope); // already tagged `assistant`
+ * ```
+ */
+export class ConversationContext {
+    constructor(
+    /** Opaque native handle. */
+    handle) {
+        this.handle = handle;
+    }
+    /** A new, empty conversation; `id` defaults to a fresh one (telemetry correlation). */
+    static async create(id) {
+        return new ConversationContext(await NativeXybrid.createContext(id ?? null));
+    }
+    /** Append a turn. Give it a `role` (see `Envelope.user` / `Envelope.assistant`). */
+    push(envelope) {
+        return NativeXybrid.contextPush(this.handle, toWireEnvelope(envelope));
+    }
+    /** Set the persistent system prompt; it survives {@link clear}. */
+    setSystem(system) {
+        const envelope = typeof system === 'string' ? { kind: 'text', text: system, role: 'system' } : system;
+        return NativeXybrid.contextSetSystem(this.handle, toWireEnvelope(envelope));
+    }
+    /** Drop the history; the system prompt is kept. */
+    clear() {
+        return NativeXybrid.contextClear(this.handle);
+    }
+    /** Id, history length and whether a system prompt is set. */
+    async info() {
+        return (await NativeXybrid.contextInfo(this.handle));
+    }
+    /** History turns in order, excluding the system prompt. */
+    async history() {
+        const wire = (await NativeXybrid.contextHistory(this.handle));
+        return wire.map(fromWireEnvelope);
+    }
+    /** Cap the history; older turns are pruned first, immediately. */
+    setMaxHistoryLength(length) {
+        return NativeXybrid.contextSetMaxHistoryLength(this.handle, length);
+    }
+    /** Free the native context. Runs already started keep their snapshot. */
+    release() {
+        return NativeXybrid.dispose(this.handle);
+    }
+}

package/lib/module/envelope.js

@@ -0,0 +1,73 @@
+import NativeXybrid from './NativeXybrid';
+import { fromWireEnvelope, normalizeImageFormat, toWireToolResult, } from './wire';
+/**
+ * Envelope factories, named like the Swift and Kotlin `Envelope` helpers.
+ * Object literals (`{ kind: 'text', text }`) work just as well; these only
+ * save typing and apply the same defaults.
+ */
+export const Envelope = {
+    /** A text prompt, or text to speak with an optional TTS voice and speed. */
+    text(text, options = {}) {
+        return { kind: 'text', text, ...options };
+    },
+    /** A user turn for a conversation. */
+    user(text) {
+        return { kind: 'text', text, role: 'user' };
+    },
+    /** An assistant turn for a conversation (e.g. a model reply you keep). */
+    assistant(text) {
+        return { kind: 'text', text, role: 'assistant' };
+    },
+    /** A system prompt. */
+    system(text) {
+        return { kind: 'text', text, role: 'system' };
+    },
+    /** PCM/WAV audio, base64-encoded. Defaults to 16 kHz mono. */
+    audio(bytesBase64, options = {}) {
+        return {
+            kind: 'audio',
+            bytesBase64,
+            sampleRate: options.sampleRate ?? 16000,
+            channels: options.channels ?? 1,
+        };
+    },
+    /** An embedding vector. */
+    embedding(data) {
+        return { kind: 'embedding', data };
+    },
+    /**
+     * An encoded image for vision-language models. The bytes are validated
+     * natively at run time (`xybrid_invalid_image` on bad input).
+     */
+    image(bytesBase64, format) {
+        return { kind: 'image', bytesBase64, format: normalizeImageFormat(format) };
+    },
+    /** A user message with image attachments, for vision-language models. */
+    userMessage(text, images = []) {
+        if (!images.every((image) => image?.kind === 'image')) {
+            throw new TypeError('Envelope.userMessage accepts only image envelopes');
+        }
+        return {
+            kind: 'multipart',
+            parts: [{ kind: 'text', text }, ...images],
+            role: 'user',
+        };
+    },
+    /**
+     * The continuation envelope for the turn after the model asked for tools.
+     *
+     * One `run` is one model turn, so the tool loop lives in your code: run a
+     * request carrying `generationConfig.tools`, execute every
+     * `result.toolCalls` entry, then run this envelope (with the same tools) to
+     * feed the outcomes back.
+     *
+     * @param userText the original user message of the turn being continued.
+     * @param priorAssistantText that turn's raw output — `result.text` from a
+     *   batch run, or the terminal token's `rawText` when streaming.
+     * @param results tool outcomes, in call order.
+     */
+    async toolResults(userText, priorAssistantText, results) {
+        const wire = (await NativeXybrid.toolResultsEnvelope(userText, priorAssistantText, results.map(toWireToolResult)));
+        return fromWireEnvelope(wire);
+    },
+};