@amodalai/runtime 0.1.26 → 0.2.1

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/search-provider.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { WebToolsConfig } from '@amodalai/types';
+/** Default Gemini model for search + urlContext when none is configured. */
+export declare const DEFAULT_SEARCH_MODEL = "gemini-3-flash-preview";
+/** A single grounded source citation (from googleSearch or urlContext). */
+export interface SearchSource {
+    /** Fully-qualified source URL. */
+    uri: string;
+    /** Human-readable title if the provider supplied one. */
+    title?: string;
+}
+/** Result of a grounded search query. */
+export interface SearchResult {
+    /** Synthesized answer text from the model. */
+    text: string;
+    /** Source URLs the answer was grounded in (may be empty). */
+    sources: SearchSource[];
+}
+/** Result of a grounded URL fetch. */
+export interface FetchResult {
+    /** Extracted page content as markdown (or summary if `prompt` was provided). */
+    text: string;
+    /** URLs that were actually retrieved by urlContext (usually 1, may be 0 on failure). */
+    retrievedUrls: string[];
+}
+/** Options for a single search call. */
+export interface SearchOptions {
+    /** Abort signal for cancellation/timeout. */
+    signal?: AbortSignal;
+}
+/** Options for a single fetch call. */
+export interface FetchOptions {
+    /** Extraction prompt — what to pull from the page. Defaults to "render as markdown". */
+    prompt?: string;
+    /** Abort signal for cancellation/timeout. */
+    signal?: AbortSignal;
+}
+/**
+ * Narrow, purpose-specific interface for grounded search + fetch.
+ *
+ * Not an `LLMProvider` — it returns grounding metadata that `LLMProvider`
+ * doesn't surface. Tool executors (`web_search`, `fetch_url`) depend on
+ * this interface, not on the concrete AI SDK types.
+ */
+export interface SearchProvider {
+    /** Run a grounded search query. */
+    search(query: string, opts?: SearchOptions): Promise<SearchResult>;
+    /** Fetch + extract content from a URL using urlContext grounding. */
+    fetchUrl(url: string, opts?: FetchOptions): Promise<FetchResult>;
+    /** Model identifier used for introspection/logging. */
+    readonly model: string;
+}
+/**
+ * Create a SearchProvider from webTools config.
+ *
+ * Throws `ConfigError` when the provider string is unsupported. All
+ * current config values go through Zod validation at load time, so this
+ * is defensive rather than user-facing.
+ */
+export declare function createSearchProvider(config: WebToolsConfig): SearchProvider;

package/dist/src/providers/search-provider.js

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Search provider: dedicated Gemini Flash instance for web_search + fetch_url.
+ *
+ * This is SEPARATE from the main LLM provider. Regardless of what model the
+ * agent is using (Anthropic/OpenAI/Google), web search and URL fetch always
+ * route through a Gemini Flash call with Google Search + urlContext grounding
+ * enabled. That gives us synthesized answers with cited URLs without paying
+ * the main-model rate and without coupling search to the main provider.
+ *
+ * Deviation from the implementation plan: the plan said to return an
+ * `LLMProvider` wrapper, but `LLMProvider.generateText` doesn't expose
+ * `providerMetadata`, which is where grounding sources live. Rather than
+ * pollute `LLMProvider` with Google-specific fields, we return a narrow
+ * purpose-specific interface with `search()` and `fetchUrl()` methods that
+ * yield `{ text, sources }` shaped results.
+ */
+import { generateText } from 'ai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { ConfigError, ProviderError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default Gemini model for search + urlContext when none is configured. */
+export const DEFAULT_SEARCH_MODEL = 'gemini-3-flash-preview';
+/**
+ * Preamble prepended to every grounded search query. Biases Gemini toward
+ * authoritative sources and precise citation. ~30 tokens per call.
+ */
+const SEARCH_SYSTEM_PREAMBLE = 'Prefer authoritative sources: official documentation, GitHub, package registries, release notes. ' +
+    'When asked for a version number, date, or other exact value, cite it directly from the source. ' +
+    'If sources disagree, say so.';
+/** Tool names required by the Google provider — must match SDK expectations. */
+const GOOGLE_SEARCH_TOOL_NAME = 'google_search';
+const URL_CONTEXT_TOOL_NAME = 'url_context';
+function extractGoogleMetadata(providerMetadata) {
+    if (!providerMetadata)
+        return undefined;
+    const google = providerMetadata['google'];
+    if (!google || typeof google !== 'object')
+        return undefined;
+    return google;
+}
+function extractSources(metadata) {
+    const chunks = metadata?.groundingMetadata?.groundingChunks;
+    if (!Array.isArray(chunks))
+        return [];
+    const sources = [];
+    for (const chunk of chunks) {
+        const uri = chunk.web?.uri;
+        if (typeof uri === 'string' && uri.length > 0) {
+            sources.push({
+                uri,
+                ...(chunk.web?.title ? { title: chunk.web.title } : {}),
+            });
+        }
+    }
+    return sources;
+}
+/**
+ * Extract an HTTP status code from an AI SDK error if present. The SDK wraps
+ * provider failures in `AI_APICallError` which carries `statusCode`. We use
+ * this to classify failures into auth/quota/transient for the tool executors.
+ */
+function extractStatusCode(err) {
+    if (err && typeof err === 'object' && 'statusCode' in err) {
+        const code = err.statusCode;
+        if (typeof code === 'number')
+            return code;
+    }
+    // Error wrapper — check cause
+    if (err instanceof Error && err.cause)
+        return extractStatusCode(err.cause);
+    return undefined;
+}
+function extractRetrievedUrls(metadata) {
+    const entries = metadata?.urlContextMetadata?.urlMetadata;
+    if (!Array.isArray(entries))
+        return [];
+    const urls = [];
+    for (const entry of entries) {
+        if (typeof entry.retrievedUrl === 'string' && entry.retrievedUrl.length > 0) {
+            urls.push(entry.retrievedUrl);
+        }
+    }
+    return urls;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a SearchProvider from webTools config.
+ *
+ * Throws `ConfigError` when the provider string is unsupported. All
+ * current config values go through Zod validation at load time, so this
+ * is defensive rather than user-facing.
+ */
+export function createSearchProvider(config) {
+    if (config.provider !== 'google') {
+        throw new ConfigError(`Unsupported webTools provider: ${config.provider}`, {
+            key: 'webTools.provider',
+            suggestion: 'Only "google" is supported today.',
+        });
+    }
+    const google = createGoogleGenerativeAI({ apiKey: config.apiKey });
+    const modelId = config.model ?? DEFAULT_SEARCH_MODEL;
+    const model = google(modelId);
+    return {
+        model: modelId,
+        async search(query, opts) {
+            try {
+                const result = await generateText({
+                    model,
+                    system: SEARCH_SYSTEM_PREAMBLE,
+                    prompt: query,
+                    tools: {
+                        [GOOGLE_SEARCH_TOOL_NAME]: google.tools.googleSearch({}),
+                    },
+                    ...(opts?.signal ? { abortSignal: opts.signal } : {}),
+                });
+                const metadata = extractGoogleMetadata(result.providerMetadata);
+                return {
+                    text: result.text,
+                    sources: extractSources(metadata),
+                };
+            }
+            catch (err) {
+                const statusCode = extractStatusCode(err);
+                throw new ProviderError('Grounded search failed', {
+                    provider: 'google',
+                    ...(statusCode !== undefined ? { statusCode } : {}),
+                    retryable: statusCode !== undefined && statusCode >= 500,
+                    context: { model: modelId, operation: 'search' },
+                    cause: err,
+                });
+            }
+        },
+        async fetchUrl(url, opts) {
+            const prompt = opts?.prompt
+                ? `Fetch ${url} and ${opts.prompt}. Respond with the result.`
+                : `Fetch ${url} and render the page content as markdown. Preserve headings, links, and lists.`;
+            try {
+                const result = await generateText({
+                    model,
+                    prompt,
+                    tools: {
+                        [URL_CONTEXT_TOOL_NAME]: google.tools.urlContext({}),
+                    },
+                    ...(opts?.signal ? { abortSignal: opts.signal } : {}),
+                });
+                const metadata = extractGoogleMetadata(result.providerMetadata);
+                return {
+                    text: result.text,
+                    retrievedUrls: extractRetrievedUrls(metadata),
+                };
+            }
+            catch (err) {
+                const statusCode = extractStatusCode(err);
+                throw new ProviderError('Grounded URL fetch failed', {
+                    provider: 'google',
+                    ...(statusCode !== undefined ? { statusCode } : {}),
+                    retryable: statusCode !== undefined && statusCode >= 500,
+                    context: { model: modelId, operation: 'fetchUrl', url },
+                    cause: err,
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=search-provider.js.map

package/dist/src/providers/search-provider.js.map

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

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

@@ -0,0 +1,118 @@
+/**
+ * @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;
+    /**
+     * Optional provider-native token counter. When implemented, the runtime
+     * uses this to decide when to compact context (more accurate than the
+     * default 4-chars-per-token heuristic). Implementations should be cheap
+     * and synchronous — return an estimate based on a local tokenizer, not
+     * an API call.
+     */
+    countTokens?(messages: ModelMessage[]): number;
+}
+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;
@@ -53,9 +54,16 @@ export declare const AIStreamRequestSchema: z.ZodObject<{
     session_id: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodString>;
     deploy_id: z.ZodOptional<z.ZodString>;
+    /**
+     * Optional session-wide **token** budget cap (cumulative across all
+     * turns; soft ceiling — single turns can overshoot by maxOutputTokens
+     * + tool result sizes). Applied only when this request creates a new
+     * session. Distinct from the LLM-API per-call max_tokens.
+     */
+    max_session_tokens: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     messages: {
-        role: "user" | "assistant" | "system";
+        role: "system" | "user" | "assistant";
         content?: string | undefined;
         parts?: {
             type: string;
@@ -65,9 +73,10 @@ export declare const AIStreamRequestSchema: z.ZodObject<{
     session_id?: string | undefined;
     role?: string | undefined;
     deploy_id?: string | undefined;
+    max_session_tokens?: number | undefined;
 }, {
     messages: {
-        role: "user" | "assistant" | "system";
+        role: "system" | "user" | "assistant";
         content?: string | undefined;
         parts?: {
             type: string;
@@ -77,6 +86,7 @@ export declare const AIStreamRequestSchema: z.ZodObject<{
     session_id?: string | undefined;
     role?: string | undefined;
     deploy_id?: string | undefined;
+    max_session_tokens?: number | undefined;
 }>;
 export type AIStreamRequest = z.infer<typeof AIStreamRequestSchema>;
 interface UIMessageStart {
@@ -152,9 +162,17 @@ 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;
+    /** Server-side summarizer hook passed into every runMessage call. */
+    summarizeToolResult?: (opts: {
+        toolName: string;
+        content: string;
+        signal: AbortSignal;
+    }) => Promise<string>;
 }
 export declare function createAIStreamRouter(options: AIStreamRouterOptions): Router;
 export {};