@amodalai/runtime 0.1.26 → 0.2.0

package/dist/src/providers/failover.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Provider failover chain.
+ *
+ * Tries each provider in sequence. On failure, logs the error and moves
+ * to the next provider. No retries or backoff within a single provider —
+ * the chain itself IS the retry strategy. If you want retries on the
+ * primary, put the same provider config twice in the chain.
+ *
+ * All providers exhausted → throws ProviderError with context about
+ * every attempt.
+ */
+import type { Logger } from '@amodalai/core';
+import type { LLMProvider, ProviderConfig } from './types.js';
+export interface FailoverChainConfig {
+    /** Primary provider (always first in the chain) */
+    primary: ProviderConfig;
+    /** Fallback providers, tried in order after primary fails */
+    fallbacks?: ProviderConfig[];
+    /** Logger for structured events */
+    logger: Logger;
+    /** Session ID for log context */
+    sessionId?: string;
+}
+/**
+ * Create an LLMProvider that tries a chain of providers in order.
+ *
+ * For generateText: tries each provider sequentially until one succeeds.
+ * For streamText: wraps the fullStream so that if a provider's stream
+ * fails before yielding any events, the next provider is tried. Once
+ * events have been yielded, mid-stream errors propagate (can't restart
+ * a partial stream).
+ */
+export declare function createFailoverProvider(config: FailoverChainConfig): LLMProvider;

package/dist/src/providers/failover.js

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { createProvider } from './create-provider.js';
+import { ProviderError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// createFailoverProvider
+// ---------------------------------------------------------------------------
+/**
+ * Create an LLMProvider that tries a chain of providers in order.
+ *
+ * For generateText: tries each provider sequentially until one succeeds.
+ * For streamText: wraps the fullStream so that if a provider's stream
+ * fails before yielding any events, the next provider is tried. Once
+ * events have been yielded, mid-stream errors propagate (can't restart
+ * a partial stream).
+ */
+export function createFailoverProvider(config) {
+    const chain = [config.primary, ...(config.fallbacks ?? [])];
+    const providers = chain.map((c) => createProvider(c));
+    const primary = providers[0];
+    function logFailure(idx, errorMsg, failedAttempts) {
+        failedAttempts.push({
+            provider: chain[idx].provider,
+            model: chain[idx].model,
+            error: errorMsg,
+        });
+        config.logger.error('provider_call_failed', {
+            session: config.sessionId,
+            provider: `${chain[idx].provider}/${chain[idx].model}`,
+            error: errorMsg,
+            willRetry: idx < providers.length - 1,
+        });
+    }
+    function logSuccess(idx, failedAttempts) {
+        if (idx > 0) {
+            config.logger.warn('provider_failover_used', {
+                session: config.sessionId,
+                failed: failedAttempts.map((a) => `${a.provider}/${a.model}`),
+                succeeded: `${chain[idx].provider}/${chain[idx].model}`,
+            });
+        }
+    }
+    function throwAllFailed(failedAttempts, cause) {
+        throw new ProviderError('All providers failed', {
+            provider: 'failover',
+            context: { attempts: failedAttempts },
+            cause,
+        });
+    }
+    return {
+        model: primary.model,
+        provider: primary.provider,
+        languageModel: primary.languageModel,
+        streamText(opts) {
+            // Deferred promises for usage and text — resolved when stream completes.
+            let resolveUsage;
+            let rejectUsage;
+            const usagePromise = new Promise((res, rej) => {
+                resolveUsage = res;
+                rejectUsage = rej;
+            });
+            let resolveText;
+            let rejectText;
+            const textPromise = new Promise((res, rej) => {
+                resolveText = res;
+                rejectText = rej;
+            });
+            const failedAttempts = [];
+            const fullStream = (async function* () {
+                let lastUsage;
+                const textChunks = [];
+                for (let i = 0; i < providers.length; i++) {
+                    let yieldedAny = false;
+                    try {
+                        const result = providers[i].streamText(opts);
+                        for await (const event of result.fullStream) {
+                            yieldedAny = true;
+                            if (event.type === 'finish')
+                                lastUsage = event.usage;
+                            if (event.type === 'text-delta')
+                                textChunks.push(event.textDelta);
+                            yield event;
+                        }
+                        // Stream completed successfully
+                        logSuccess(i, failedAttempts);
+                        resolveUsage(lastUsage ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 });
+                        resolveText(textChunks.join(''));
+                        return;
+                    }
+                    catch (err) {
+                        const errorMsg = err instanceof Error ? err.message : String(err);
+                        // If we already yielded events, we can't retry — log and propagate
+                        if (yieldedAny) {
+                            logFailure(i, errorMsg, failedAttempts);
+                            rejectUsage(err);
+                            rejectText(err);
+                            throw err;
+                        }
+                        logFailure(i, errorMsg, failedAttempts);
+                        if (i === providers.length - 1) {
+                            rejectUsage(err);
+                            rejectText(err);
+                            throwAllFailed(failedAttempts, err);
+                        }
+                        // Try next provider
+                    }
+                }
+            })();
+            return {
+                fullStream,
+                // textStream derived from fullStream — consumers should use one or the other
+                textStream: (async function* () {
+                    for await (const event of fullStream) {
+                        if (event.type === 'text-delta') {
+                            yield event.textDelta;
+                        }
+                    }
+                })(),
+                usage: usagePromise,
+                text: textPromise,
+            };
+        },
+        async generateText(opts) {
+            const failedAttempts = [];
+            for (let i = 0; i < providers.length; i++) {
+                try {
+                    const result = await providers[i].generateText(opts);
+                    logSuccess(i, failedAttempts);
+                    return result;
+                }
+                catch (err) {
+                    const errorMsg = err instanceof Error ? err.message : String(err);
+                    logFailure(i, errorMsg, failedAttempts);
+                    if (i === providers.length - 1) {
+                        throwAllFailed(failedAttempts, err);
+                    }
+                }
+            }
+            // Unreachable — TypeScript needs this
+            throw new ProviderError('No providers configured', { provider: 'failover' });
+        },
+    };
+}
+//# sourceMappingURL=failover.js.map

package/dist/src/providers/failover.js.map

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

package/dist/src/providers/failover.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/src/providers/failover.test.js

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Provider Failover Tests
+ *
+ * Integration tests against real providers (skipped when API keys are
+ * not available). No mocks — calls the real AI SDK through the real
+ * createProvider → createFailoverProvider chain.
+ *
+ * Scenarios:
+ * 1. Primary with invalid key + fallback with valid key → response from fallback
+ * 2. Valid primary → uses primary, no fallback
+ * 3. All providers fail → throws ProviderError with context about all attempts
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createFailoverProvider } from './failover.js';
+import { ProviderError } from '../errors.js';
+import { testProviders, hasAnyProvider } from '../__tests__/test-providers.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeMockLogger() {
+    return {
+        trace: vi.fn(),
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        fatal: vi.fn(),
+        child: vi.fn().mockReturnThis(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Unit tests (no API calls)
+// ---------------------------------------------------------------------------
+describe('createFailoverProvider (unit)', () => {
+    let logger;
+    beforeEach(() => {
+        logger = makeMockLogger();
+    });
+    it('exposes primary model and provider on the returned object', () => {
+        const provider = createFailoverProvider({
+            primary: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: 'fake' },
+            fallbacks: [{ provider: 'openai', model: 'gpt-4o', apiKey: 'fake' }],
+            logger,
+        });
+        expect(provider.model).toBe('claude-sonnet-4-20250514');
+        expect(provider.provider).toBe('anthropic');
+        expect(provider.languageModel).toBeDefined();
+        expect(typeof provider.streamText).toBe('function');
+        expect(typeof provider.generateText).toBe('function');
+    });
+    it('works with a single provider (no fallbacks)', () => {
+        const provider = createFailoverProvider({
+            primary: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: 'fake' },
+            logger,
+        });
+        expect(provider.model).toBe('claude-sonnet-4-20250514');
+    });
+});
+// ---------------------------------------------------------------------------
+// Integration tests (real API calls — skipped without keys)
+// ---------------------------------------------------------------------------
+describe.skipIf(!hasAnyProvider)('createFailoverProvider (integration)', () => {
+    let logger;
+    beforeEach(() => {
+        logger = makeMockLogger();
+    });
+    // ── 1. Primary fails (invalid key) + fallback succeeds ────────────────
+    it('uses fallback when primary has invalid API key', async () => {
+        const fallback = testProviders.cheapest();
+        const invalid = testProviders.invalid(fallback.provider);
+        const provider = createFailoverProvider({
+            primary: invalid,
+            fallbacks: [fallback],
+            logger,
+            sessionId: 'test-failover',
+        });
+        const result = await provider.generateText({
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Reply with exactly: pong' }] }],
+            maxOutputTokens: 10,
+        });
+        expect(result.text.toLowerCase()).toContain('pong');
+        expect(result.usage.inputTokens).toBeGreaterThan(0);
+        expect(result.usage.outputTokens).toBeGreaterThan(0);
+        expect(logger.error).toHaveBeenCalledWith('provider_call_failed', expect.objectContaining({ session: 'test-failover', willRetry: true }));
+        expect(logger.warn).toHaveBeenCalledWith('provider_failover_used', expect.objectContaining({
+            succeeded: `${fallback.provider}/${fallback.model}`,
+        }));
+    }, 30000);
+    // ── 2. Valid primary → uses primary, no fallback ──────────────────────
+    it('uses primary when it succeeds — fallback not touched', async () => {
+        const primary = testProviders.cheapest();
+        const provider = createFailoverProvider({
+            primary,
+            // Fallback has invalid key — would fail if reached
+            fallbacks: [testProviders.invalid(primary.provider)],
+            logger,
+        });
+        const result = await provider.generateText({
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Reply with exactly: ping' }] }],
+            maxOutputTokens: 10,
+        });
+        expect(result.text.toLowerCase()).toContain('ping');
+        expect(logger.error).not.toHaveBeenCalled();
+        expect(logger.warn).not.toHaveBeenCalled();
+    }, 30000);
+    // ── 3. All providers fail → ProviderError with all attempts ───────────
+    it('throws ProviderError with context about all failed attempts', async () => {
+        const provider = createFailoverProvider({
+            primary: testProviders.invalid('anthropic'),
+            fallbacks: [testProviders.invalid('openai')],
+            logger,
+            sessionId: 'test-all-fail',
+        });
+        try {
+            await provider.generateText({
+                messages: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }],
+                maxOutputTokens: 10,
+            });
+            expect.unreachable('should have thrown');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ProviderError);
+            const pe = err;
+            expect(pe.message).toBe('All providers failed');
+            expect(pe.provider).toBe('failover');
+            const attempts = pe.context['attempts'];
+            expect(attempts).toHaveLength(2);
+            expect(attempts[0].provider).toBe('anthropic');
+            expect(attempts[1].provider).toBe('openai');
+        }
+        expect(logger.error).toHaveBeenCalledTimes(2);
+        expect(logger.error).toHaveBeenCalledWith('provider_call_failed', expect.objectContaining({ session: 'test-all-fail', willRetry: true }));
+        expect(logger.error).toHaveBeenCalledWith('provider_call_failed', expect.objectContaining({ willRetry: false }));
+    }, 30000);
+    // ── 4. Streaming failover ─────────────────────────────────────────────
+    it('streaming: uses fallback when primary stream fails', async () => {
+        const fallback = testProviders.cheapest();
+        const invalid = testProviders.invalid(fallback.provider);
+        const provider = createFailoverProvider({
+            primary: invalid,
+            fallbacks: [fallback],
+            logger,
+        });
+        const result = provider.streamText({
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Reply with exactly: stream-ok' }] }],
+            maxOutputTokens: 10,
+        });
+        const events = [];
+        for await (const event of result.fullStream) {
+            events.push(event);
+        }
+        const textDeltas = events.filter((e) => e.type === 'text-delta');
+        expect(textDeltas.length).toBeGreaterThan(0);
+        const text = await result.text;
+        expect(text.length).toBeGreaterThan(0);
+        const usage = await result.usage;
+        expect(usage.inputTokens).toBeGreaterThan(0);
+        expect(logger.error).toHaveBeenCalledWith('provider_call_failed', expect.objectContaining({ willRetry: true }));
+        expect(logger.warn).toHaveBeenCalledWith('provider_failover_used', expect.objectContaining({
+            succeeded: `${fallback.provider}/${fallback.model}`,
+        }));
+    }, 30000);
+});
+//# sourceMappingURL=failover.test.js.map

package/dist/src/providers/failover.test.js.map

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

package/dist/src/providers/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Provider abstraction wrapping the Vercel AI SDK.
+ *
+ * This is the boundary between Amodal code and the AI SDK. The rest of
+ * the runtime talks to LLMProvider, never to the SDK directly. This lets
+ * us swap SDK versions, add new providers, or intercept calls (logging,
+ * retries, cost tracking) in one place.
+ */
+import type { LanguageModel, ModelMessage, Tool, ToolChoice, ToolSet } from 'ai';
+export interface StreamTextOptions {
+    messages: ModelMessage[];
+    system?: string;
+    tools?: Record<string, Tool>;
+    toolChoice?: ToolChoice<ToolSet>;
+    maxOutputTokens?: number;
+    temperature?: number;
+    abortSignal?: AbortSignal;
+}
+export interface GenerateTextOptions {
+    messages: ModelMessage[];
+    system?: string;
+    tools?: Record<string, Tool>;
+    toolChoice?: ToolChoice<ToolSet>;
+    maxOutputTokens?: number;
+    temperature?: number;
+    abortSignal?: AbortSignal;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    cacheCreationInputTokens?: number;
+    totalTokens: number;
+}
+export interface StreamTextResult {
+    /** The full text stream — yields string chunks */
+    textStream: AsyncIterable<string>;
+    /** The full event stream — yields structured events including tool calls */
+    fullStream: AsyncIterable<StreamEvent>;
+    /** Resolves when the stream is complete with final usage */
+    usage: PromiseLike<TokenUsage>;
+    /** Resolves with the complete response text */
+    text: PromiseLike<string>;
+}
+export type StreamEvent = {
+    type: 'text-delta';
+    textDelta: string;
+} | {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+} | {
+    type: 'finish';
+    usage: TokenUsage;
+} | {
+    type: 'error';
+    error: unknown;
+};
+export interface GenerateTextResult {
+    text: string;
+    toolCalls: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: Record<string, unknown>;
+    }>;
+    usage: TokenUsage;
+    finishReason: 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other';
+}
+/**
+ * Unified LLM provider interface.
+ *
+ * Wraps the Vercel AI SDK so the rest of the runtime never imports `ai`
+ * directly. Implementations exist for Anthropic, OpenAI, Google, and
+ * any OpenAI-compatible provider (DeepSeek, Groq, Mistral, etc.).
+ */
+export interface LLMProvider {
+    /** Stream a text/tool response from the LLM */
+    streamText(opts: StreamTextOptions): StreamTextResult;
+    /** Generate a complete text response (non-streaming) */
+    generateText(opts: GenerateTextOptions): Promise<GenerateTextResult>;
+    /** The model identifier (e.g., 'claude-sonnet-4-20250514') */
+    readonly model: string;
+    /** The provider name (e.g., 'anthropic', 'openai', 'google') */
+    readonly provider: string;
+    /** The underlying AI SDK LanguageModel instance (for advanced use) */
+    readonly languageModel: LanguageModel;
+}
+export interface ProviderConfig {
+    /** Provider name: 'anthropic', 'openai', 'google', 'deepseek', etc. */
+    provider: string;
+    /** Model name: 'claude-sonnet-4-20250514', 'gpt-4o', etc. */
+    model: string;
+    /** API key (resolved from env or credentials) */
+    apiKey?: string;
+    /** Custom base URL (for self-hosted or proxy endpoints) */
+    baseUrl?: string;
+    /** AWS region (for Bedrock) */
+    region?: string;
+}

package/dist/src/providers/types.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/routes/ai-stream.d.ts

@@ -1,14 +1,14 @@
 /**
  * @license
- * Copyright 2025 Amodal Labs, Inc.
+ * Copyright 2026 Amodal Labs, Inc.
  * SPDX-License-Identifier: MIT
  */
 /**
  * Vercel AI SDK UI Message Stream Protocol adapter.
  *
  * Accepts requests in the Vercel AI SDK format, feeds the user message into
- * the existing `streamMessage()` async generator, and translates every
- * `SSEEvent` into the UI Message Stream Protocol that `@ai-sdk/react`'s
+ * the standalone session manager's `runMessage()` generator, and translates
+ * every `SSEEvent` into the UI Message Stream Protocol that `@ai-sdk/react`'s
  * `useChat` hook expects.
  *
  * Protocol spec: events are newline-delimited JSON objects prefixed with
@@ -18,9 +18,10 @@
 import { Router } from 'express';
 import { z } from 'zod';
 import type { AuthContext } from '../middleware/auth.js';
-import type { SessionManager } from '../session/session-manager.js';
-import { type StreamHooks } from '../session/session-runner.js';
+import type { StandaloneSessionManager } from '../session/manager.js';
+import type { StreamHooks } from '../session/stream-hooks.js';
 import { type SSEEvent } from '../types.js';
+import type { BundleResolver, SharedResources } from './session-resolver.js';
 export declare const AIStreamRequestSchema: z.ZodObject<{
     messages: z.ZodArray<z.ZodObject<{
         role: z.ZodEnum<["user", "assistant", "system"]>;
@@ -36,14 +37,14 @@ export declare const AIStreamRequestSchema: z.ZodObject<{
         }>, "many">>;
         content: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        role: "user" | "assistant" | "system";
+        role: "system" | "user" | "assistant";
         content?: string | undefined;
         parts?: {
             type: string;
             text?: string | undefined;
         }[] | undefined;
     }, {
-        role: "user" | "assistant" | "system";
+        role: "system" | "user" | "assistant";
         content?: string | undefined;
         parts?: {
             type: string;
@@ -55,7 +56,7 @@ export declare const AIStreamRequestSchema: z.ZodObject<{
     deploy_id: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     messages: {
-        role: "user" | "assistant" | "system";
+        role: "system" | "user" | "assistant";
         content?: string | undefined;
         parts?: {
             type: string;
@@ -67,7 +68,7 @@ export declare const AIStreamRequestSchema: z.ZodObject<{
     deploy_id?: string | undefined;
 }, {
     messages: {
-        role: "user" | "assistant" | "system";
+        role: "system" | "user" | "assistant";
         content?: string | undefined;
         parts?: {
             type: string;
@@ -152,7 +153,9 @@ interface AdapterState {
 export declare function translateEvent(event: SSEEvent, state: AdapterState): UIStreamEvent[];
 export declare function extractUserMessage(messages: AIStreamRequest['messages']): string;
 export interface AIStreamRouterOptions {
-    sessionManager: SessionManager;
+    sessionManager: StandaloneSessionManager;
+    bundleResolver: BundleResolver;
+    shared: SharedResources;
     /** Factory that builds per-request stream hooks from the auth context */
     createStreamHooks?: (auth?: AuthContext) => StreamHooks;
 }