@xybrid/react-native 0.10.0-rc1

package/lib/module/wire.js

@@ -0,0 +1,271 @@
+// 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.
+// 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.
+ */
+export 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. */
+export 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. */
+export 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',
+];
+export function toWireToolDefinition(tool) {
+    const parameters = tool.parameters;
+    return {
+        name: tool.name,
+        description: tool.description,
+        parametersJson: typeof parameters === 'string' ? parameters : JSON.stringify(parameters),
+    };
+}
+export function toWireGenerationConfig(config) {
+    const { tools, ...rest } = config;
+    return {
+        ...rest,
+        ...(tools ? { tools: tools.map(toWireToolDefinition) } : {}),
+    };
+}
+export 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.
+ */
+export 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;
+}
+export 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 {};
+    }
+}
+export 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,
+    };
+}
+export 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,
+    };
+}
+export 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),
+    };
+}
+export 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/module/xybrid.js

@@ -0,0 +1,127 @@
+import { AppState } from 'react-native';
+import NativeXybrid from './NativeXybrid';
+import { ModelLoader } from './model';
+let initialized = false;
+/**
+ * Process-wide SDK entry points. Local inference needs no setup at all —
+ * `initialize` only matters for the optional platform features.
+ */
+export const 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.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 ModelLoader.fromRegistry(id);
+    },
+    /** The native SDK version, e.g. `0.9.0`. */
+    version() {
+        return NativeXybrid.sdkVersion();
+    },
+    /** Whether an API key resolves, from {@link initialize} or the environment. */
+    hasApiKey() {
+        return NativeXybrid.hasApiKey();
+    },
+    /** Set the key for a cloud provider the gateway forwards to (not the Xybrid key). */
+    setProviderApiKey(provider, apiKey) {
+        return NativeXybrid.setProviderApiKey(provider, apiKey);
+    },
+    /** Point the cloud gateway at a platform base URL; the `/v1` suffix is added for you. */
+    setPlatformUrl(url) {
+        return NativeXybrid.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.setSpeculativeCloud(enabled);
+    },
+    isSpeculativeCloudEnabled() {
+        return NativeXybrid.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.releaseMemory();
+    },
+    /**
+     * Call {@link releaseMemory} on every OS memory warning (React Native
+     * `AppState` `memoryWarning`, iOS and Android). Returns the unsubscribe
+     * function.
+     */
+    releaseMemoryOnWarning() {
+        const subscription = AppState.addEventListener('memoryWarning', () => {
+            NativeXybrid.releaseMemory().catch(() => { });
+        });
+        return () => subscription.remove();
+    },
+    /** Release least-recently-used idle models before loads under memory pressure. */
+    setAutoRelease(enabled) {
+        return NativeXybrid.setAutoRelease(enabled);
+    },
+    isAutoReleaseEnabled() {
+        return NativeXybrid.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.setBatteryLevel(percent);
+    },
+    clearBatteryLevel() {
+        return NativeXybrid.clearBatteryLevel();
+    },
+    setThermalState(state) {
+        return NativeXybrid.setThermalState(state);
+    },
+    clearThermalState() {
+        return NativeXybrid.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.cacheStatus());
+    },
+    /** Physical entries; a model can appear more than once. */
+    async modelCacheEntries() {
+        return (await NativeXybrid.cacheEntries());
+    },
+    /** Whether `modelId` occupies any cache entry. */
+    hasCachedModelData(modelId) {
+        return NativeXybrid.cacheIsModelCached(modelId);
+    },
+    /** A local path for `modelId`, or `null`. Presence does not mean extracted. */
+    cachedModelPath(modelId) {
+        return NativeXybrid.cacheModelPath(modelId);
+    },
+    /** Models extracted, validated and ready to run offline. */
+    extractedModelIds() {
+        return NativeXybrid.cacheExtractedModelIds();
+    },
+    /** Remove every cache entry for `modelId`. Don't race a load of the same model. */
+    removeCachedModel(modelId) {
+        return NativeXybrid.cacheRemoveModel(modelId);
+    },
+    /** Clear all managed cache storage. Don't race any model load. */
+    clearModelCache() {
+        return NativeXybrid.cacheClear();
+    },
+};

package/lib/typescript/NativeXybrid.d.ts

@@ -0,0 +1,68 @@
+import type { TurboModule } from 'react-native';
+export interface Spec extends TurboModule {
+    initialize(options: Object | null): Promise<void>;
+    sdkVersion(): Promise<string>;
+    hasApiKey(): Promise<boolean>;
+    setProviderApiKey(provider: string, apiKey: string): Promise<void>;
+    setPlatformUrl(url: string): Promise<void>;
+    setSpeculativeCloud(enabled: boolean): Promise<void>;
+    isSpeculativeCloudEnabled(): Promise<boolean>;
+    willSpeculate(modelId: string): Promise<boolean>;
+    releaseMemory(): Promise<number>;
+    setAutoRelease(enabled: boolean): Promise<void>;
+    isAutoReleaseEnabled(): Promise<boolean>;
+    setBatteryLevel(percent: number): Promise<void>;
+    clearBatteryLevel(): Promise<void>;
+    setThermalState(state: string): Promise<void>;
+    clearThermalState(): Promise<void>;
+    cacheStatus(): Promise<Object>;
+    cacheEntries(): Promise<Object[]>;
+    cacheIsModelCached(modelId: string): Promise<boolean>;
+    cacheModelPath(modelId: string): Promise<string | null>;
+    cacheExtractedModelIds(): Promise<string[]>;
+    cacheRemoveModel(modelId: string): Promise<number>;
+    cacheClear(): Promise<number>;
+    jsonSchemaToGbnf(schemaJson: string): Promise<string>;
+    toolResultsEnvelope(userText: string, priorAssistantText: string, results: Object[]): Promise<Object>;
+    dispose(handle: string): Promise<void>;
+    loadModel(source: Object): Promise<string>;
+    modelInfo(model: string): Promise<Object>;
+    isLoaded(model: string): Promise<boolean>;
+    warmup(model: string): Promise<void>;
+    unload(model: string): Promise<void>;
+    isCloudServing(model: string): Promise<boolean>;
+    downloadStatus(model: string): Promise<Object>;
+    awaitDownload(model: string, timeoutMs: number): Promise<Object>;
+    voices(model: string): Promise<Object[]>;
+    defaultVoice(model: string): Promise<Object | null>;
+    voice(model: string, voiceId: string): Promise<Object | null>;
+    run(model: string, envelope: Object, options: Object | null): Promise<Object>;
+    streamStart(model: string, envelope: Object, options: Object | null): Promise<string>;
+    streamNext(stream: string): Promise<Object | null>;
+    createCancelToken(): Promise<string>;
+    cancel(token: string): Promise<void>;
+    createContext(contextId: string | null): Promise<string>;
+    contextPush(context: string, envelope: Object): Promise<void>;
+    contextSetSystem(context: string, envelope: Object): Promise<void>;
+    contextClear(context: string): Promise<void>;
+    contextInfo(context: string): Promise<Object>;
+    contextHistory(context: string): Promise<Object[]>;
+    contextSetMaxHistoryLength(context: string, length: number): Promise<void>;
+    startDownload(modelId: string, platform: string | null): Promise<string>;
+    downloadHandleStatus(download: string): Promise<Object>;
+    downloadHandleError(download: string): Promise<string | null>;
+    cancelDownload(download: string): Promise<void>;
+    loadPipeline(source: Object): Promise<string>;
+    pipelineInfo(pipeline: string): Promise<Object>;
+    runPipeline(pipeline: string, envelope: Object, options: Object | null): Promise<Object>;
+    openStreamingSession(model: string, config: Object | null): Promise<string>;
+    sessionFeed(session: string, samplesBase64: string): Promise<void>;
+    sessionNextPartial(session: string): Promise<Object | null>;
+    sessionFlush(session: string): Promise<string>;
+    sessionReset(session: string): Promise<void>;
+    sessionCancel(session: string): Promise<void>;
+    sessionIsRunning(session: string): Promise<boolean>;
+}
+declare const _default: Spec;
+export default _default;
+//# sourceMappingURL=NativeXybrid.d.ts.map

package/lib/typescript/NativeXybrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeXybrid.d.ts","sourceRoot":"","sources":["../../src/NativeXybrid.ts"],"names":[],"mappings":"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"}

package/lib/typescript/base64.d.ts

@@ -0,0 +1,5 @@
+/** Standard (RFC 4648, padded) base64 of `bytes`. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Base64 of Float32 PCM samples as little-endian bytes. */
+export declare function float32ToBase64(samples: Float32Array | ArrayLike<number>): string;
+//# sourceMappingURL=base64.d.ts.map

package/lib/typescript/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../src/base64.ts"],"names":[],"mappings":"AAOA,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CA4BvD;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAGjF"}

package/lib/typescript/cancel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The part of the standard `AbortSignal` this SDK needs, so any
+ * implementation (React Native's `AbortController`, a polyfill) works.
+ */
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+/** A native cancellation token bound to an `AbortSignal` for one call. */
+export interface CancelBinding {
+    /** Native token handle, or `null` when the call has no signal. */
+    readonly token: string | null;
+    /** Detach from the signal and free the native token. Never rejects. */
+    release(): Promise<void>;
+}
+/**
+ * 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 declare function bindCancel(signal: AbortSignalLike | undefined): Promise<CancelBinding>;
+//# sourceMappingURL=cancel.d.ts.map

package/lib/typescript/cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/cancel.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChE;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,uEAAuE;IACvE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAID;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAkB5F"}

package/lib/typescript/context.d.ts

@@ -0,0 +1,40 @@
+import type { ConversationInfo, Envelope } from './types';
+/**
+ * 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 declare class ConversationContext {
+    /** Opaque native handle. */
+    readonly handle: string;
+    private constructor();
+    /** A new, empty conversation; `id` defaults to a fresh one (telemetry correlation). */
+    static create(id?: string): Promise<ConversationContext>;
+    /** Append a turn. Give it a `role` (see `Envelope.user` / `Envelope.assistant`). */
+    push(envelope: Envelope): Promise<void>;
+    /** Set the persistent system prompt; it survives {@link clear}. */
+    setSystem(system: Envelope | string): Promise<void>;
+    /** Drop the history; the system prompt is kept. */
+    clear(): Promise<void>;
+    /** Id, history length and whether a system prompt is set. */
+    info(): Promise<ConversationInfo>;
+    /** History turns in order, excluding the system prompt. */
+    history(): Promise<Envelope[]>;
+    /** Cap the history; older turns are pruned first, immediately. */
+    setMaxHistoryLength(length: number): Promise<void>;
+    /** Free the native context. Runs already started keep their snapshot. */
+    release(): Promise<void>;
+}
+//# sourceMappingURL=context.d.ts.map

package/lib/typescript/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG1D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAmB;IAE5B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB,OAAO;IAKP,uFAAuF;WAC1E,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI9D,oFAAoF;IACpF,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,mEAAmE;IACnE,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnD,mDAAmD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,6DAA6D;IACvD,IAAI,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIvC,2DAA2D;IACrD,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKpC,kEAAkE;IAClE,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,yEAAyE;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGzB"}

package/lib/typescript/envelope.d.ts

@@ -0,0 +1,51 @@
+import type { AudioEnvelope, EmbeddingEnvelope, Envelope as EnvelopeType, ImageEnvelope, ImageFormat, MessageRole, MultiPartEnvelope, TextEnvelope, ToolResult } from './types';
+/** Input to (and output of) a model. Narrow on `kind`. */
+export type Envelope = EnvelopeType;
+/**
+ * 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 declare const Envelope: {
+    /** A text prompt, or text to speak with an optional TTS voice and speed. */
+    text(text: string, options?: {
+        voiceId?: string;
+        speed?: number;
+        role?: MessageRole;
+    }): TextEnvelope;
+    /** A user turn for a conversation. */
+    user(text: string): TextEnvelope;
+    /** An assistant turn for a conversation (e.g. a model reply you keep). */
+    assistant(text: string): TextEnvelope;
+    /** A system prompt. */
+    system(text: string): TextEnvelope;
+    /** PCM/WAV audio, base64-encoded. Defaults to 16 kHz mono. */
+    audio(bytesBase64: string, options?: {
+        sampleRate?: number;
+        channels?: number;
+    }): AudioEnvelope;
+    /** An embedding vector. */
+    embedding(data: number[]): EmbeddingEnvelope;
+    /**
+     * An encoded image for vision-language models. The bytes are validated
+     * natively at run time (`xybrid_invalid_image` on bad input).
+     */
+    image(bytesBase64: string, format: ImageFormat | "jpg"): ImageEnvelope;
+    /** A user message with image attachments, for vision-language models. */
+    userMessage(text: string, images?: ImageEnvelope[]): MultiPartEnvelope;
+    /**
+     * 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.
+     */
+    toolResults(userText: string, priorAssistantText: string, results: ToolResult[]): Promise<Envelope>;
+};
+//# sourceMappingURL=envelope.d.ts.map

package/lib/typescript/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,QAAQ,IAAI,YAAY,EACxB,aAAa,EACb,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACX,MAAM,SAAS,CAAC;AAQjB,0DAA0D;AAC1D,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,QAAQ;IACnB,4EAA4E;eAEpE,MAAM,YACH;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,WAAW,CAAA;KAAE,GAChE,YAAY;IAIf,sCAAsC;eAC3B,MAAM,GAAG,YAAY;IAIhC,0EAA0E;oBAC1D,MAAM,GAAG,YAAY;IAIrC,uBAAuB;iBACV,MAAM,GAAG,YAAY;IAIlC,8DAA8D;uBAE/C,MAAM,YACV;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAClD,aAAa;IAShB,2BAA2B;oBACX,MAAM,EAAE,GAAG,iBAAiB;IAI5C;;;OAGG;uBACgB,MAAM,UAAU,WAAW,GAAG,KAAK,GAAG,aAAa;IAItE,yEAAyE;sBACvD,MAAM,WAAU,aAAa,EAAE,GAAQ,iBAAiB;IAW1E;;;;;;;;;;;;OAYG;0BAES,MAAM,sBACI,MAAM,WACjB,UAAU,EAAE,GACpB,OAAO,CAAC,QAAQ,CAAC;CAQrB,CAAC"}

package/lib/typescript/errors.d.ts

@@ -0,0 +1,12 @@
+/** Stable error codes for `XybridError.code`. */
+export declare const XybridErrorCodes: readonly ["xybrid_model_not_found", "xybrid_directory_not_found", "xybrid_metadata_not_found", "xybrid_metadata_invalid", "xybrid_load_error", "xybrid_inference_error", "xybrid_aborted_cloud_fallback", "xybrid_streaming_unsupported", "xybrid_not_loaded", "xybrid_config_error", "xybrid_network_error", "xybrid_offline", "xybrid_io_error", "xybrid_cache_error", "xybrid_pipeline_error", "xybrid_circuit_open", "xybrid_rate_limited", "xybrid_timeout", "xybrid_missing_artifact", "xybrid_unsupported_model_capability", "xybrid_unsupported_backend_capability", "xybrid_invalid_image", "xybrid_cancelled", "xybrid_handle", "xybrid_invalid_argument", "xybrid_unknown"];
+export type XybridErrorCode = (typeof XybridErrorCodes)[number];
+/** A rejection raised by the Xybrid native module. */
+export interface XybridError extends Error {
+    code: XybridErrorCode;
+}
+/** Narrow an unknown rejection to a {@link XybridError}. */
+export declare function isXybridError(error: unknown): error is XybridError;
+/** Whether retrying the same call later can succeed (network, rate limit, timeout, offline). */
+export declare function isRetryable(error: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/lib/typescript/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAKA,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,wpBA+BnB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,sDAAsD;AACtD,MAAM,WAAW,WAAY,SAAQ,KAAK;IACxC,IAAI,EAAE,eAAe,CAAC;CACvB;AAID,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAIlE;AAUD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEnD"}