@llumiverse/core 1.3.0 → 1.4.0-dev.20260629.090753Z

package/src/http-agent.test.ts

@@ -0,0 +1,281 @@
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import {
+    type AIModel,
+    type Completion,
+    type CompletionChunkObject,
+    type DriverOptions,
+    type EmbeddingsOptions,
+    type EmbeddingsResult,
+    type ExecutionOptions,
+    type ModelSearchPayload,
+    PromptRole,
+} from '@llumiverse/common';
+import type { Agent } from 'undici';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AbstractDriver } from './Driver.js';
+import {
+    createAgentBackedFetch,
+    createDriverHttpAgent,
+    DEFAULT_DRIVER_HTTP_TIMEOUTS,
+    mergeDriverHttpTimeoutOptions,
+    resolveDriverHttpTimeouts,
+} from './http-agent.js';
+
+class TestDriver extends AbstractDriver<DriverOptions, string> {
+    provider = 'test';
+
+    getAgent(): Agent {
+        return this.getHttpAgent();
+    }
+
+    getFetch(): typeof fetch {
+        return this.getDriverFetch();
+    }
+
+    async requestTextCompletion(prompt: string, _options: ExecutionOptions): Promise<Completion> {
+        const response = await this.getDriverFetch()(prompt);
+        return {
+            result: [{ type: 'text', value: await response.text() }],
+        };
+    }
+
+    async requestTextCompletionStream(
+        _prompt: string,
+        _options: ExecutionOptions,
+    ): Promise<AsyncIterable<CompletionChunkObject>> {
+        throw new Error('Not implemented');
+    }
+
+    async listModels(_params?: ModelSearchPayload): Promise<AIModel[]> {
+        return [];
+    }
+
+    async validateConnection(): Promise<boolean> {
+        return true;
+    }
+
+    async generateEmbeddings(_options: EmbeddingsOptions): Promise<EmbeddingsResult> {
+        throw new Error('Not implemented');
+    }
+}
+
+type TestServer = {
+    url: string;
+    close: () => Promise<void>;
+};
+
+async function startServer(handler: (req: IncomingMessage, res: ServerResponse) => void): Promise<TestServer> {
+    const server = createServer(handler);
+
+    await new Promise<void>((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Unable to resolve test server port');
+    }
+
+    return {
+        url: `http://127.0.0.1:${(address as AddressInfo).port}`,
+        close: () =>
+            new Promise<void>((resolve, reject) => {
+                server.close((error?: Error) => (error ? reject(error) : resolve()));
+            }),
+    };
+}
+
+describe('driver HTTP agent helpers', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('fills missing timeout options from defaults', () => {
+        expect(resolveDriverHttpTimeouts()).toEqual(DEFAULT_DRIVER_HTTP_TIMEOUTS);
+        expect(
+            resolveDriverHttpTimeouts({
+                headersTimeout: 123,
+                keepAliveTimeout: 456,
+            }),
+        ).toEqual({
+            headersTimeout: 123,
+            bodyTimeout: DEFAULT_DRIVER_HTTP_TIMEOUTS.bodyTimeout,
+            connectTimeout: DEFAULT_DRIVER_HTTP_TIMEOUTS.connectTimeout,
+            keepAliveTimeout: 456,
+        });
+    });
+
+    it('merges per-call timeout overrides without replacing defined defaults with undefined', () => {
+        expect(
+            mergeDriverHttpTimeoutOptions(
+                {
+                    headersTimeout: 1_000,
+                    bodyTimeout: 2_000,
+                    connectTimeout: 300,
+                },
+                {
+                    headersTimeout: undefined,
+                    bodyTimeout: 500,
+                },
+            ),
+        ).toEqual({
+            headersTimeout: 1_000,
+            bodyTimeout: 500,
+            connectTimeout: 300,
+        });
+    });
+
+    it('accepts global Request instances without parsing them as strings', async () => {
+        const server = await startServer((_req, res) => {
+            res.writeHead(200, { 'content-type': 'text/plain' });
+            res.end('ok');
+        });
+        const agent = createDriverHttpAgent();
+        const wrappedFetch = createAgentBackedFetch(agent);
+
+        try {
+            const response = await wrappedFetch(new Request(server.url));
+            await expect(response.text()).resolves.toBe('ok');
+        } finally {
+            await agent.close();
+            await server.close();
+        }
+    });
+
+    it('preserves a global Request body when callers pass undefined init fields', async () => {
+        const server = await startServer((req, res) => {
+            let body = '';
+            req.setEncoding('utf8');
+            req.on('data', (chunk) => {
+                body += chunk;
+            });
+            req.on('end', () => {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(
+                    JSON.stringify({
+                        method: req.method,
+                        body,
+                        contentType: req.headers['content-type'],
+                    }),
+                );
+            });
+        });
+        const agent = createDriverHttpAgent();
+        const wrappedFetch = createAgentBackedFetch(agent);
+        const request = new Request(server.url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ ok: true }),
+        });
+
+        try {
+            const response = await wrappedFetch(request, {
+                method: undefined,
+                body: undefined,
+            });
+            await expect(response.json()).resolves.toEqual({
+                method: 'POST',
+                body: '{"ok":true}',
+                contentType: 'application/json',
+            });
+        } finally {
+            await agent.close();
+            await server.close();
+        }
+    });
+
+    it('enforces headersTimeout through the wrapped fetch', async () => {
+        const server = await startServer((_req, res) => {
+            const timer = setTimeout(() => {
+                if (!res.destroyed) {
+                    res.writeHead(200, { 'content-type': 'text/plain' });
+                    res.end('late');
+                }
+            }, 3_000);
+            res.on('close', () => clearTimeout(timer));
+        });
+        const agent = createDriverHttpAgent({ headersTimeout: 100 });
+        const wrappedFetch = createAgentBackedFetch(agent);
+        const startedAt = Date.now();
+
+        try {
+            await expect(wrappedFetch(server.url)).rejects.toThrow();
+            expect(Date.now() - startedAt).toBeLessThan(2_500);
+        } finally {
+            await agent.close();
+            await server.close();
+        }
+    });
+
+    it('enforces bodyTimeout when a response body stalls', async () => {
+        const server = await startServer((_req, res) => {
+            res.writeHead(200, { 'content-type': 'text/plain' });
+            res.write('first');
+            const timer = setTimeout(() => {
+                if (!res.destroyed) {
+                    res.end('second');
+                }
+            }, 3_000);
+            res.on('close', () => clearTimeout(timer));
+        });
+        const agent = createDriverHttpAgent({ bodyTimeout: 100 });
+        const wrappedFetch = createAgentBackedFetch(agent);
+        const startedAt = Date.now();
+
+        try {
+            const response = await wrappedFetch(server.url);
+            await expect(response.text()).rejects.toThrow();
+            expect(Date.now() - startedAt).toBeLessThan(2_500);
+        } finally {
+            await agent.close();
+            await server.close();
+        }
+    });
+
+    it('reuses and closes the lazy driver HTTP agent', () => {
+        const driver = new TestDriver({});
+        const agent = driver.getAgent();
+        const closeSpy = vi.spyOn(agent, 'close').mockResolvedValue();
+
+        expect(driver.getAgent()).toBe(agent);
+        expect(driver.getFetch()).toBe(driver.getFetch());
+
+        driver.destroy();
+
+        expect(closeSpy).toHaveBeenCalledTimes(1);
+        expect(driver.getAgent()).not.toBe(agent);
+
+        driver.destroy();
+    });
+
+    it('applies per-execution timeout overrides without replacing the cached driver fetch', async () => {
+        const server = await startServer((_req, res) => {
+            const timer = setTimeout(() => {
+                if (!res.destroyed) {
+                    res.writeHead(200, { 'content-type': 'text/plain' });
+                    res.end('late');
+                }
+            }, 3_000);
+            res.on('close', () => clearTimeout(timer));
+        });
+        const driver = new TestDriver({ httpTimeout: { headersTimeout: 2_000 } });
+        const cachedFetch = driver.getFetch();
+        const startedAt = Date.now();
+
+        try {
+            await expect(
+                driver.execute([{ role: PromptRole.user, content: server.url }], {
+                    model: 'test-model',
+                    httpTimeout: { headersTimeout: 100 },
+                }),
+            ).rejects.toThrow();
+            expect(Date.now() - startedAt).toBeLessThan(2_500);
+            expect(driver.getFetch()).toBe(cachedFetch);
+        } finally {
+            driver.destroy();
+            await server.close();
+        }
+    });
+});

package/src/http-agent.ts

@@ -0,0 +1,177 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { HttpTimeoutOptions } from '@llumiverse/common';
+import { Agent } from 'undici';
+
+/**
+ * Default HTTP timeouts used by {@link createDriverHttpAgent} when the
+ * caller does not override them. These are deliberately tighter than
+ * Node's undici default (5 minutes for headers and body) so a hung
+ * upstream LLM-provider call surfaces in seconds rather than blocking
+ * the whole request budget.
+ *
+ * Drivers with workloads that have legitimate long pauses (image
+ * generation, tool-using agent streams) should pass higher overrides
+ * via {@link HttpTimeoutOptions} rather than relying on the defaults.
+ */
+export const DEFAULT_DRIVER_HTTP_TIMEOUTS: Required<HttpTimeoutOptions> = {
+    headersTimeout: 60_000,
+    bodyTimeout: 60_000,
+    connectTimeout: 10_000,
+    keepAliveTimeout: 30_000,
+};
+
+const scopedHttpAgent = new AsyncLocalStorage<Agent>();
+
+export function resolveDriverHttpTimeouts(opts?: HttpTimeoutOptions): Required<HttpTimeoutOptions> {
+    return {
+        headersTimeout: opts?.headersTimeout ?? DEFAULT_DRIVER_HTTP_TIMEOUTS.headersTimeout,
+        bodyTimeout: opts?.bodyTimeout ?? DEFAULT_DRIVER_HTTP_TIMEOUTS.bodyTimeout,
+        connectTimeout: opts?.connectTimeout ?? DEFAULT_DRIVER_HTTP_TIMEOUTS.connectTimeout,
+        keepAliveTimeout: opts?.keepAliveTimeout ?? DEFAULT_DRIVER_HTTP_TIMEOUTS.keepAliveTimeout,
+    };
+}
+
+export function mergeDriverHttpTimeoutOptions(
+    defaults?: HttpTimeoutOptions,
+    override?: HttpTimeoutOptions,
+): HttpTimeoutOptions | undefined {
+    if (!override) {
+        return defaults;
+    }
+    return {
+        ...(defaults ?? {}),
+        ...stripUndefinedHttpTimeoutOptions(override),
+    };
+}
+
+/**
+ * Build an undici `Agent` configured from {@link HttpTimeoutOptions},
+ * falling back to {@link DEFAULT_DRIVER_HTTP_TIMEOUTS} for unset fields.
+ *
+ * The Agent pools sockets — reuse it for the lifetime of the driver
+ * and close it on `destroy()`.
+ *
+ * Node-only. `@llumiverse/drivers` is itself Node-only in practice
+ * because vertexai/bedrock pull `@google-cloud/*` / `@aws-sdk/*`, so
+ * depending on undici from core is acceptable.
+ */
+export function createDriverHttpAgent(opts?: HttpTimeoutOptions): Agent {
+    const timeouts = resolveDriverHttpTimeouts(opts);
+    return new Agent({
+        headersTimeout: timeouts.headersTimeout,
+        bodyTimeout: timeouts.bodyTimeout,
+        connectTimeout: timeouts.connectTimeout,
+        keepAliveTimeout: timeouts.keepAliveTimeout,
+    });
+}
+
+/**
+ * Wrap the global `fetch` so every request routes through the given Agent.
+ * The returned function is type-compatible with global `fetch`, so it
+ * can be passed directly to SDKs that accept a `fetch` option (OpenAI,
+ * Anthropic, `@google/genai`, Bedrock via Smithy, …) or used as a
+ * drop-in replacement for global `fetch` in drivers that make raw HTTP
+ * calls.
+ *
+ * `@vertesia/api-fetch-client` builds requests with `globalThis.Request`,
+ * while the undici package uses its own `Request` class. Calling
+ * `undici.fetch` directly can parse a global Request as `"[object Request]"`.
+ * Use `globalThis.fetch` (undici-backed in Node/Bun) and pass the undici
+ * dispatcher extension through init so the Agent timeout behavior is still
+ * applied without crossing Request/Response implementations.
+ */
+export function createAgentBackedFetch(agent: Agent): typeof fetch {
+    return ((input: RequestInfo | URL, init?: RequestInit) => {
+        const requestInput =
+            typeof Request !== 'undefined' && input instanceof Request
+                ? normalizeRequestInput(input, init)
+                : { input, init };
+
+        const dispatcher = scopedHttpAgent.getStore() ?? agent;
+        return globalThis.fetch(requestInput.input, {
+            ...(requestInput.init ?? {}),
+            dispatcher,
+        } as RequestInit & { dispatcher?: unknown });
+    }) as unknown as typeof fetch;
+}
+
+export interface DriverHttpAgentScope {
+    run<T>(callback: () => T): T;
+    close(): Promise<void>;
+}
+
+const NOOP_HTTP_AGENT_SCOPE: DriverHttpAgentScope = {
+    run: <T>(callback: () => T): T => callback(),
+    close: () => Promise.resolve(),
+};
+
+export function createDriverHttpAgentScope(
+    defaults?: HttpTimeoutOptions,
+    override?: HttpTimeoutOptions,
+): DriverHttpAgentScope {
+    if (!override) {
+        return NOOP_HTTP_AGENT_SCOPE;
+    }
+
+    const agent = createDriverHttpAgent(mergeDriverHttpTimeoutOptions(defaults, override));
+    return {
+        run: <T>(callback: () => T): T => scopedHttpAgent.run(agent, callback),
+        close: async () => {
+            await agent.close().catch(() => {
+                /* shutdown best-effort */
+            });
+        },
+    };
+}
+
+type NormalizedRequestInput = {
+    input: RequestInfo | URL;
+    init?: RequestInit & { duplex?: 'half' };
+};
+
+function normalizeRequestInput(request: Request, init?: RequestInit): NormalizedRequestInput {
+    const overrides = stripUndefinedRequestInit(init);
+    const requestInit: RequestInit & { duplex?: 'half' } = {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+        signal: request.signal,
+        cache: request.cache,
+        credentials: request.credentials,
+        integrity: request.integrity,
+        keepalive: request.keepalive,
+        mode: request.mode,
+        redirect: request.redirect,
+        referrer: request.referrer,
+        referrerPolicy: request.referrerPolicy,
+    };
+
+    if (request.body) {
+        requestInit.duplex = 'half';
+    }
+
+    return {
+        input: request.url,
+        init: {
+            ...requestInit,
+            ...overrides,
+        },
+    };
+}
+
+function stripUndefinedRequestInit(init?: RequestInit): RequestInit | undefined {
+    if (!init) {
+        return undefined;
+    }
+    const entries = Object.entries(init).filter(([, value]) => value !== undefined);
+    return Object.fromEntries(entries) as RequestInit;
+}
+
+function stripUndefinedHttpTimeoutOptions(opts: HttpTimeoutOptions): HttpTimeoutOptions {
+    const entries = Object.entries(opts).filter(([, value]) => value !== undefined);
+    return Object.fromEntries(entries) as HttpTimeoutOptions;
+}
+
+/** Re-export the undici `Agent` type so driver code can type its agent
+ *  field without adding an extra undici import. */
+export type { Agent as DriverHttpAgent } from 'undici';

package/src/index.ts

@@ -1,5 +1,7 @@
-export * from "@llumiverse/common";
-export * from "./conversation-utils.js";
-export * from "./Driver.js";
-export * from "./json.js";
-export * from "./stream.js";
+export * from '@llumiverse/common';
+export * from './conversation-utils.js';
+export type { AbstractDriver, Driver } from './Driver.js';
+export * from './embeddings.js';
+export * from './json.js';
+export * from './logger.js';
+export * from './stream.js';

package/src/json.ts

@@ -1,9 +1,9 @@
-import { JSONValue } from "@llumiverse/common";
+import type { JSONValue } from '@llumiverse/common';
 import { jsonrepair } from 'jsonrepair';
 
 function extractJsonFromText(text: string): string {
-    const start = text.indexOf("{");
-    const end = text.lastIndexOf("}");
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
     return text.substring(start, end + 1);
 }
 
@@ -15,11 +15,12 @@ export function parseJSON(text: string): JSONValue {
     text = text.trim();
     try {
         return JSON.parse(text);
-    } catch (err: any) {
+    } catch (err: unknown) {
         // use a relaxed parser
         try {
             return JSON.parse(jsonrepair(text));
-        } catch (err2: any) { // throw the original error
+        } catch {
+            // throw the original error
             throw err;
         }
     }

package/src/logger.ts

@@ -0,0 +1,42 @@
+import type { Logger } from '@llumiverse/common';
+
+// Helper to create logger methods that support both message-only and object-first signatures.
+function createConsoleLoggerMethod(consoleMethod: (...args: unknown[]) => void): Logger['info'] {
+    return ((objOrMsg: unknown, msgOrNever?: string, ...args: (string | number | boolean)[]) => {
+        if (typeof objOrMsg === 'string') {
+            // Message-only: logger.info("message", ...args)
+            consoleMethod(objOrMsg, msgOrNever, ...args);
+        } else if (msgOrNever !== undefined) {
+            // Object-first: logger.info({ obj }, "message", ...args)
+            consoleMethod(msgOrNever, objOrMsg, ...args);
+        } else {
+            // Object-only: logger.info({ obj })
+            consoleMethod(objOrMsg, ...args);
+        }
+    }) as Logger['info'];
+}
+
+const ConsoleLogger: Logger = {
+    debug: createConsoleLoggerMethod(console.debug.bind(console)),
+    info: createConsoleLoggerMethod(console.info.bind(console)),
+    warn: createConsoleLoggerMethod(console.warn.bind(console)),
+    error: createConsoleLoggerMethod(console.error.bind(console)),
+};
+
+const noop = () => void 0;
+const NoopLogger: Logger = {
+    debug: noop as Logger['debug'],
+    info: noop as Logger['info'],
+    warn: noop as Logger['warn'],
+    error: noop as Logger['error'],
+};
+
+export function createLogger(logger: Logger | 'console' | undefined) {
+    if (logger === 'console') {
+        return ConsoleLogger;
+    } else if (logger) {
+        return logger;
+    } else {
+        return NoopLogger;
+    }
+}

package/src/resolver.ts

@@ -6,31 +6,34 @@
  * @param name the name of the property.
  * @returns the property value
  */
-function _prop(object: any, name: string) {
-    if (object === undefined) {
+function _prop(object: unknown, name: string): unknown {
+    if (object === undefined || object === null) {
         return undefined;
     }
     if (Array.isArray(object)) {
         const index = +name;
-        if (isNaN(index)) {
+        if (Number.isNaN(index)) {
             // map array to property
-            return object.map(item => item[name]);
+            return object.map((item) =>
+                item && typeof item === 'object' ? (item as Record<string, unknown>)[name] : undefined,
+            );
         } else {
             return object[index];
         }
+    } else if (typeof object === 'object') {
+        return (object as Record<string, unknown>)[name];
     } else {
-        return object[name];
+        return undefined;
     }
-
 }
 
-export function resolveField(object: any, path: string[]) {
-    let p = object as any;
+export function resolveField(object: unknown, path: string[]): unknown {
+    let p: unknown = object;
     if (!p) return p;
     if (!path.length) return p;
     const last = path.length - 1;
     for (let i = 0; i < last; i++) {
-        p = _prop(p, path[i])
+        p = _prop(p, path[i]);
         if (!p) {
             return undefined;
         }

package/src/stream.ts

@@ -1,4 +1,3 @@
-
 export async function readStreamAsBase64(stream: ReadableStream): Promise<string> {
     const uint8Array = await readStreamAsUint8Array(stream);
     return Buffer.from(uint8Array).toString('base64');
@@ -12,20 +11,20 @@ export async function readStreamAsString(stream: ReadableStream): Promise<string
 export async function readStreamAsUint8Array(stream: ReadableStream): Promise<Uint8Array> {
     const chunks: Uint8Array[] = [];
     let totalLength = 0;
-    
+
     for await (const chunk of stream) {
         const uint8Chunk = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
-        
+
         chunks.push(uint8Chunk);
         totalLength += uint8Chunk.length;
     }
-    
+
     const combined = new Uint8Array(totalLength);
     let offset = 0;
     for (const chunk of chunks) {
         combined.set(chunk, offset);
         offset += chunk.length;
     }
-    
+
     return combined;
 }