@amodalai/runtime 0.2.0 → 0.2.1

package/dist/src/events/events-route.test.js

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import express from 'express';
+import { RuntimeEventBus } from './event-bus.js';
+import { createEventsRouter } from './events-route.js';
+function startServer(bus) {
+    const app = express();
+    app.use(createEventsRouter({ bus, heartbeatMs: 60_000 }));
+    return new Promise((resolve) => {
+        const server = app.listen(0, () => {
+            const address = server.address();
+            const port = address && typeof address === 'object' ? address.port : 0;
+            resolve({ port, server, bus });
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+}
+async function collectEvents(url, expected, opts = {}) {
+    const headers = { Accept: 'text/event-stream' };
+    if (opts.lastEventId)
+        headers['Last-Event-ID'] = opts.lastEventId;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs ?? 2000);
+    const res = await fetch(url, { headers, signal: controller.signal });
+    if (!res.body)
+        throw new Error('no response body');
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    const collected = [];
+    let buffer = '';
+    try {
+        while (collected.length < expected) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buffer.indexOf('\n\n')) !== -1) {
+                const frame = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                const dataLine = frame.split('\n').find((l) => l.startsWith('data:'));
+                if (dataLine) {
+                    const json = dataLine.slice(5).trim();
+                    collected.push(JSON.parse(json));
+                    if (collected.length >= expected)
+                        break;
+                }
+            }
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        controller.abort();
+        reader.cancel().catch(() => { });
+    }
+    return collected;
+}
+describe('events SSE route', () => {
+    let harness = null;
+    afterEach(async () => {
+        if (harness) {
+            await closeServer(harness.server);
+            harness = null;
+        }
+    });
+    it('streams emitted events to connected clients', async () => {
+        const bus = new RuntimeEventBus();
+        harness = await startServer(bus);
+        const url = `http://127.0.0.1:${String(harness.port)}/api/events`;
+        const eventsPromise = collectEvents(url, 2, { timeoutMs: 2000 });
+        setTimeout(() => {
+            bus.emit({ type: 'session_created', sessionId: 's1', appId: 'local' });
+            bus.emit({ type: 'manifest_changed' });
+        }, 50);
+        const events = await eventsPromise;
+        expect(events).toHaveLength(2);
+        expect(events[0]?.['type']).toBe('session_created');
+        expect(events[0]?.['seq']).toBe(1);
+        expect(events[1]?.['type']).toBe('manifest_changed');
+        expect(events[1]?.['seq']).toBe(2);
+    });
+    it('replays buffered events matching Last-Event-ID', async () => {
+        const bus = new RuntimeEventBus();
+        harness = await startServer(bus);
+        const url = `http://127.0.0.1:${String(harness.port)}/api/events`;
+        bus.emit({ type: 'session_created', sessionId: 's1', appId: 'local' });
+        bus.emit({ type: 'session_created', sessionId: 's2', appId: 'local' });
+        bus.emit({ type: 'session_created', sessionId: 's3', appId: 'local' });
+        const events = await collectEvents(url, 2, { lastEventId: '1', timeoutMs: 2000 });
+        expect(events).toHaveLength(2);
+        expect(events[0]?.['seq']).toBe(2);
+        expect(events[1]?.['seq']).toBe(3);
+    });
+    it('includes id and event headers in SSE frames', async () => {
+        const bus = new RuntimeEventBus();
+        harness = await startServer(bus);
+        const url = `http://127.0.0.1:${String(harness.port)}/api/events`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 2000);
+        const res = await fetch(url, {
+            headers: { Accept: 'text/event-stream' },
+            signal: controller.signal,
+        });
+        if (!res.body)
+            throw new Error('no response body');
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        setTimeout(() => {
+            bus.emit({ type: 'manifest_changed' });
+        }, 50);
+        let raw = '';
+        while (!raw.includes('\n\n')) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            raw += decoder.decode(value, { stream: true });
+        }
+        clearTimeout(timeout);
+        controller.abort();
+        reader.cancel().catch(() => { });
+        expect(raw).toContain('id: 1');
+        expect(raw).toContain('event: manifest_changed');
+        expect(raw).toContain('data: {"type":"manifest_changed"');
+    });
+});
+//# sourceMappingURL=events-route.test.js.map

package/dist/src/events/events-route.test.js.map

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

package/dist/src/events/store-event-wrapper.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Wraps a `StoreBackend` so every successful write emits a `store_updated`
+ * event to the runtime event bus. Read operations pass through unchanged.
+ *
+ * Instrumenting at the backend level (rather than each call site: tools,
+ * REST routes, admin file tools, task execution) means we cover every
+ * write path through one seam.
+ */
+import type { StoreBackend, RuntimeEventPayload } from '@amodalai/types';
+interface StoreEventSink {
+    emit: (payload: RuntimeEventPayload) => unknown;
+}
+export declare function wrapStoreBackendWithEvents(inner: StoreBackend, bus: StoreEventSink): StoreBackend;
+export {};

package/dist/src/events/store-event-wrapper.js

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export function wrapStoreBackendWithEvents(inner, bus) {
+    return {
+        initialize(stores) {
+            return inner.initialize(stores);
+        },
+        get(appId, store, key) {
+            return inner.get(appId, store, key);
+        },
+        list(appId, store, opts) {
+            return inner.list(appId, store, opts);
+        },
+        history(appId, store, key) {
+            return inner.history(appId, store, key);
+        },
+        async put(appId, store, key, payload, meta) {
+            const result = await inner.put(appId, store, key, payload, meta);
+            bus.emit({
+                type: 'store_updated',
+                storeName: store,
+                operation: 'put',
+            });
+            return result;
+        },
+        async delete(appId, store, key) {
+            const result = await inner.delete(appId, store, key);
+            if (result) {
+                bus.emit({
+                    type: 'store_updated',
+                    storeName: store,
+                    operation: 'delete',
+                });
+            }
+            return result;
+        },
+        async purgeExpired(appId, store) {
+            const count = await inner.purgeExpired(appId, store);
+            if (count > 0) {
+                bus.emit({
+                    type: 'store_updated',
+                    storeName: store ?? '*',
+                    operation: 'delete',
+                    count,
+                });
+            }
+            return count;
+        },
+        close() {
+            return inner.close();
+        },
+    };
+}
+//# sourceMappingURL=store-event-wrapper.js.map

package/dist/src/events/store-event-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-event-wrapper.js","sourceRoot":"","sources":["../../../src/events/store-event-wrapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,MAAM,UAAU,0BAA0B,CACxC,KAAmB,EACnB,GAAmB;IAEnB,OAAO;QACL,UAAU,CAAC,MAAqB;YAC9B,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,GAAG,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW;YAC3C,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,CAAC,KAAa,EAAE,KAAa,EAAE,IAAuB;YACxD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW;YAC/C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,GAAG,CACP,KAAa,EACb,KAAa,EACb,GAAW,EACX,OAAgC,EAChC,IAAgC;YAEhC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YACjE,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW;YACpD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;YACrD,IAAI,MAAM,EAAE,CAAC;gBACX,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,eAAe;oBACrB,SAAS,EAAE,KAAK;oBAChB,SAAS,EAAE,QAAQ;iBACpB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,KAAa,EAAE,KAAc;YAC9C,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACrD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,eAAe;oBACrB,SAAS,EAAE,KAAK,IAAI,GAAG;oBACvB,SAAS,EAAE,QAAQ;oBACnB,KAAK;iBACN,CAAC,CAAC;YACL,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,KAAK;YACH,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/events/store-event-wrapper.test.d.ts

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

package/dist/src/events/store-event-wrapper.test.js

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { wrapStoreBackendWithEvents } from './store-event-wrapper.js';
+import { RuntimeEventBus } from './event-bus.js';
+function makeStubBackend(overrides = {}) {
+    return {
+        initialize: vi.fn().mockResolvedValue(undefined),
+        get: vi.fn().mockResolvedValue(null),
+        list: vi.fn().mockResolvedValue({ rows: [], total: 0 }),
+        history: vi.fn().mockResolvedValue([]),
+        put: vi.fn().mockResolvedValue({ version: 1, stale: false }),
+        delete: vi.fn().mockResolvedValue(true),
+        purgeExpired: vi.fn().mockResolvedValue(0),
+        close: vi.fn().mockResolvedValue(undefined),
+        ...overrides,
+    };
+}
+describe('wrapStoreBackendWithEvents', () => {
+    it('emits store_updated on successful put', async () => {
+        const bus = new RuntimeEventBus();
+        const emits = [];
+        bus.subscribe((e) => emits.push({ type: e.type, storeName: e.storeName, operation: e.operation }));
+        const wrapped = wrapStoreBackendWithEvents(makeStubBackend(), bus);
+        await wrapped.put('local', 'leads', 'k1', { x: 1 }, {});
+        expect(emits).toHaveLength(1);
+        expect(emits[0]).toEqual({ type: 'store_updated', storeName: 'leads', operation: 'put' });
+    });
+    it('emits store_updated on successful delete', async () => {
+        const bus = new RuntimeEventBus();
+        const emits = [];
+        bus.subscribe((e) => emits.push(e));
+        const wrapped = wrapStoreBackendWithEvents(makeStubBackend(), bus);
+        await wrapped.delete('local', 'leads', 'k1');
+        expect(emits).toHaveLength(1);
+        expect(emits[0]?.['type']).toBe('store_updated');
+        expect(emits[0]?.['operation']).toBe('delete');
+    });
+    it('does NOT emit on delete that returns false (not found)', async () => {
+        const bus = new RuntimeEventBus();
+        const emits = [];
+        bus.subscribe((e) => emits.push(e));
+        const wrapped = wrapStoreBackendWithEvents(makeStubBackend({ delete: vi.fn().mockResolvedValue(false) }), bus);
+        await wrapped.delete('local', 'leads', 'missing');
+        expect(emits).toHaveLength(0);
+    });
+    it('emits store_updated with count on purgeExpired', async () => {
+        const bus = new RuntimeEventBus();
+        const emits = [];
+        bus.subscribe((e) => emits.push(e));
+        const wrapped = wrapStoreBackendWithEvents(makeStubBackend({ purgeExpired: vi.fn().mockResolvedValue(3) }), bus);
+        await wrapped.purgeExpired('local', 'leads');
+        expect(emits).toHaveLength(1);
+        expect(emits[0]?.['count']).toBe(3);
+        expect(emits[0]?.['storeName']).toBe('leads');
+    });
+    it('does NOT emit on purgeExpired that deletes nothing', async () => {
+        const bus = new RuntimeEventBus();
+        const emits = [];
+        bus.subscribe((e) => emits.push(e));
+        const wrapped = wrapStoreBackendWithEvents(makeStubBackend(), bus);
+        await wrapped.purgeExpired('local');
+        expect(emits).toHaveLength(0);
+    });
+    it('passes read operations through unchanged without emitting', async () => {
+        const bus = new RuntimeEventBus();
+        const emits = [];
+        bus.subscribe((e) => emits.push(e));
+        const inner = makeStubBackend();
+        const wrapped = wrapStoreBackendWithEvents(inner, bus);
+        await wrapped.get('local', 'leads', 'k1');
+        await wrapped.list('local', 'leads');
+        await wrapped.history('local', 'leads', 'k1');
+        expect(emits).toHaveLength(0);
+        expect(inner.get).toHaveBeenCalled();
+        expect(inner.list).toHaveBeenCalled();
+        expect(inner.history).toHaveBeenCalled();
+    });
+    it('propagates put/delete errors without emitting', async () => {
+        const bus = new RuntimeEventBus();
+        const emits = [];
+        bus.subscribe((e) => emits.push(e));
+        const wrapped = wrapStoreBackendWithEvents(makeStubBackend({ put: vi.fn().mockRejectedValue(new Error('disk full')) }), bus);
+        await expect(wrapped.put('local', 'leads', 'k1', {}, {})).rejects.toThrow('disk full');
+        expect(emits).toHaveLength(0);
+    });
+});
+//# sourceMappingURL=store-event-wrapper.test.js.map

package/dist/src/events/store-event-wrapper.test.js.map

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

package/dist/src/middleware/auth.d.ts

@@ -12,10 +12,8 @@ export interface AuthContext {
     apiKey?: string;
     /** Raw Bearer token (JWT or ak_ key) for forwarding to platform API */
     token?: string;
-    orgId: string;
     applicationId: string;
     authMethod: string;
-    actor?: string;
 }
 /**
  * Get the auth context from response locals.

package/dist/src/middleware/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAEvC;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAa;IAC1C,uEAAuE;IACvE,OAAO,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAA4B,CAAC;AACjE,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAEvC;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAa;IAC1C,uEAAuE;IACvE,OAAO,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAA4B,CAAC;AACjE,CAAC"}

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

@@ -95,6 +95,14 @@ export interface LLMProvider {
     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. */