ag-ai 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# ag-ai
+
+Provider-neutral AI client and cluster runtime for the
+[rpi-mega](https://github.com/andreigec/rpi-mega) cluster.
+
+## Target layout (subpath exports)
+
+| Subpath         | Contents                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| `ag-ai`         | Client SDK: generate, generateText, promptDirect, promptImage, models |
+| `ag-ai/client`  | Client SDK entry point                                                |
+| `ag-ai/runtime` | Cluster runtime: generation protocol, store, server, bridge (ESM)     |
+| `ag-ai/k8s`     | Cluster plugin descriptor (`ClusterPlugin`)                           |
+| `ag-ai/image`   | Neutral image-output adapter (provider per implementation)            |
+
+The client compiles to CommonJS. The runtime is hand-authored ESM and shipped
+as-is, because it runs inside the pod with no build step.
+
+## Boundaries
+
+- No prompts. Prompt templates belong to consumers (gec.dev, bolt.garden, …).
+- No secrets, secret names, SSM paths, or cluster addresses.
+- Provider keys are declared as logical names and resolved by `rpi-mega`.
+- Codex is not used. The executor is OpenCode; the image adapter is separate
+  because OpenCode has no image-generation output.
+
+## Tooling
+
+Formatting and linting use `e7-oxfmt` / `e7-oxlint` from
+`eslint-config-e7npm`. Dependency updates run through Renovate via
+`github>andreigec/renovate`.

package/dist/client/adapters/cluster.d.ts

@@ -0,0 +1,12 @@
+import type { AIClientDependencies, AIEndpoint, AIModel, AIRequest, GenerationResult } from '../types';
+export type ClusterAdapterConfig = {
+    endpoint: AIEndpoint;
+    dependencies?: AIClientDependencies;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+};
+/** Validate and normalize the direct private LAN endpoint used by the ag-ai cluster. */
+export declare const normalizeClusterEndpoint: (endpoint: AIEndpoint) => AIEndpoint;
+export declare const generateCluster: (request: AIRequest, config: ClusterAdapterConfig) => Promise<GenerationResult>;
+export declare const listClusterModels: (endpoint: AIEndpoint, dependencies?: AIClientDependencies) => Promise<AIModel[]>;

package/dist/client/adapters/cluster.js

@@ -0,0 +1,567 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listClusterModels = exports.generateCluster = exports.normalizeClusterEndpoint = void 0;
+const node_crypto_1 = require("node:crypto");
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+const DEFAULT_MAX_POLL_INTERVAL_MS = 2000;
+const CREATE_RETRY_DELAY_MS = 1000;
+const CANCEL_TIMEOUT_MS = 1000;
+const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+const TERMINAL_SUCCESS_STATUSES = new Set(['completed']);
+const TERMINAL_FAILURE_STATUSES = new Set(['failed', 'cancelled', 'unknown']);
+const PENDING_STATUSES = new Set(['queued', 'running', 'cancelling']);
+class ClusterHTTPError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'ClusterHTTPError';
+        this.status = status;
+    }
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const getString = (record, key) => {
+    const value = record[key];
+    return typeof value === 'string' ? value : undefined;
+};
+const getRecord = (record, key) => {
+    const value = record[key];
+    return isRecord(value) ? value : undefined;
+};
+const getErrorMessage = (body, fallback) => {
+    if (!isRecord(body))
+        return fallback;
+    const error = body.error;
+    if (typeof error === 'string' && error.trim().length > 0)
+        return error;
+    if (isRecord(error)) {
+        const message = getString(error, 'message');
+        if (message && message.trim().length > 0)
+            return message;
+    }
+    const message = getString(body, 'message');
+    return message && message.trim().length > 0 ? message : fallback;
+};
+const parseIPv4 = (hostname) => {
+    const octets = hostname.split('.');
+    if (octets.length !== 4 || octets.some((octet) => !/^\d{1,3}$/.test(octet)))
+        return undefined;
+    const numbers = octets.map((octet) => Number(octet));
+    return numbers.every((octet) => octet >= 0 && octet <= 255) ? numbers : undefined;
+};
+const isPrivateIPv4 = (hostname) => {
+    const octets = parseIPv4(hostname);
+    if (!octets)
+        return false;
+    const [first, second] = octets;
+    return (first === 10 ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168));
+};
+/** Validate and normalize the direct private LAN endpoint used by the ag-ai cluster. */
+const normalizeClusterEndpoint = (endpoint) => {
+    const candidate = endpoint;
+    if (!isRecord(candidate) || candidate.protocol !== 'ag-ai') {
+        throw new Error('Unsupported AI endpoint protocol');
+    }
+    const rawURL = candidate.url;
+    const rawToken = candidate.token;
+    if (typeof rawURL !== 'string' || rawURL.trim().length === 0) {
+        throw new Error('AI endpoint URL is required');
+    }
+    if (typeof rawToken !== 'string' || rawToken.trim().length === 0) {
+        throw new Error('AI endpoint token is required');
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawURL);
+    }
+    catch {
+        throw new Error('AI endpoint URL is invalid');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error('AI endpoint URL must use HTTP or HTTPS');
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error('AI endpoint URL must not contain credentials, query, or fragment');
+    }
+    if (!isPrivateIPv4(parsed.hostname)) {
+        throw new Error('AI endpoint must use a private LAN IPv4 address');
+    }
+    const path = parsed.pathname.replace(/\/+$/, '');
+    if (path !== '' && path !== '/v1') {
+        throw new Error('AI endpoint URL path must be empty or /v1');
+    }
+    parsed.pathname = '/v1';
+    parsed.search = '';
+    parsed.hash = '';
+    return { protocol: 'ag-ai', url: parsed.toString().replace(/\/$/, ''), token: rawToken.trim() };
+};
+exports.normalizeClusterEndpoint = normalizeClusterEndpoint;
+const defaultSleep = (milliseconds) => new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+});
+const getDependencies = (dependencies) => ({
+    fetch: dependencies?.fetch ?? globalThis.fetch,
+    sleep: dependencies?.sleep ?? defaultSleep,
+    now: dependencies?.now ?? (() => Date.now()),
+    createIdempotencyKey: dependencies?.createIdempotencyKey ?? node_crypto_1.randomUUID,
+});
+const throwIfAborted = (signal) => {
+    if (signal?.aborted) {
+        throw new Error('generation aborted');
+    }
+};
+const createAbortError = () => {
+    const error = new Error('AI request aborted');
+    error.name = 'AbortError';
+    return error;
+};
+const awaitWithSignal = async (promise, signal) => {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        throw createAbortError();
+    const abort = new Promise((_, reject) => {
+        const onAbort = () => reject(createAbortError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        void promise.then(() => signal.removeEventListener('abort', onAbort), () => signal.removeEventListener('abort', onAbort));
+    });
+    return Promise.race([promise, abort]);
+};
+const responseJSON = async (response, signal) => {
+    const contentLength = response.headers.get('content-length');
+    if (contentLength !== null && Number(contentLength) > MAX_RESPONSE_BYTES) {
+        throw new Error('AI response body is too large');
+    }
+    const body = response.body;
+    if (body === null)
+        return undefined;
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            // oxlint-disable-next-line no-await-in-loop -- response bytes must be bounded sequentially
+            const chunk = await awaitWithSignal(reader.read(), signal);
+            if (chunk.done)
+                break;
+            total += chunk.value.byteLength;
+            if (total > MAX_RESPONSE_BYTES)
+                throw new Error('AI response body is too large');
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return undefined;
+    }
+};
+const fetchJSON = async ({ fetch, url, headers, method, body, signal, }) => {
+    const response = await awaitWithSignal(fetch(url, {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body }),
+        redirect: 'manual',
+        ...(signal === undefined ? {} : { signal }),
+    }), signal);
+    const payload = await responseJSON(response, signal);
+    if (!response.ok) {
+        throw new ClusterHTTPError(response.status, getErrorMessage(payload, `AI endpoint returned HTTP ${response.status}`));
+    }
+    return payload;
+};
+const isRetryable = (error) => {
+    if (error instanceof ClusterHTTPError)
+        return error.status === 429 || error.status >= 500;
+    return error instanceof Error && error.name !== 'AbortError';
+};
+const withCreateRetry = async (operation, sleep, signal) => {
+    try {
+        const result = await operation();
+        return result;
+    }
+    catch (error) {
+        if (!isRetryable(error))
+            throw error;
+        // oxlint-disable-next-line no-await-in-loop -- retry delay precedes the one allowed replay
+        await awaitWithSignal(sleep(CREATE_RETRY_DELAY_MS), signal);
+        throwIfAborted(signal);
+        return operation();
+    }
+};
+const isBase64 = (value) => value.length > 0 &&
+    value.length % 4 === 0 &&
+    /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+const parseOutputPart = (value) => {
+    if (!isRecord(value))
+        throw new Error('AI result contains an invalid output part');
+    const type = getString(value, 'type');
+    if (type === 'text') {
+        const text = getString(value, 'text');
+        if (text === undefined)
+            throw new Error('AI text output is missing text');
+        return { type, text };
+    }
+    if (type !== 'image' && type !== 'audio' && type !== 'video' && type !== 'file') {
+        throw new Error('AI result contains an unsupported output part');
+    }
+    const mimeType = getString(value, 'mimeType');
+    const data = getString(value, 'data');
+    if (!mimeType || data === undefined || !isBase64(data)) {
+        throw new Error('AI media output is missing MIME type or data');
+    }
+    if (type !== 'file' && !mimeType.toLowerCase().startsWith(`${type}/`)) {
+        throw new Error('AI media output type does not match its MIME type');
+    }
+    const name = getString(value, 'name');
+    return name === undefined ? { type, mimeType, data } : { type, mimeType, data, name };
+};
+const parseJob = (value) => {
+    if (!isRecord(value))
+        throw new Error('AI endpoint returned an invalid job');
+    const id = getString(value, 'id');
+    const status = getString(value, 'status');
+    if (!id || !status)
+        throw new Error('AI job is missing id or status');
+    return value;
+};
+const parseResult = (job) => {
+    const result = getRecord(job, 'result');
+    if (!result)
+        throw new Error('AI successful job is missing its result');
+    const rawOutput = result.output;
+    if (!Array.isArray(rawOutput))
+        throw new Error('AI result is missing typed output parts');
+    const model = getString(result, 'model');
+    if (!model || model.trim().length === 0)
+        throw new Error('AI result is missing its actual model');
+    const generatedAtValue = result.generatedAt;
+    if (typeof generatedAtValue !== 'number' ||
+        !Number.isSafeInteger(generatedAtValue) ||
+        generatedAtValue < 0) {
+        throw new Error('AI result is missing a valid generatedAt timestamp');
+    }
+    const rawUsage = result.usage;
+    let usage;
+    if (rawUsage !== undefined) {
+        if (!isRecord(rawUsage))
+            throw new Error('AI result usage is invalid');
+        const inputTokens = rawUsage.inputTokens;
+        const outputTokens = rawUsage.outputTokens;
+        const totalTokens = rawUsage.totalTokens;
+        if (typeof inputTokens !== 'number' ||
+            !Number.isSafeInteger(inputTokens) ||
+            inputTokens < 0 ||
+            typeof outputTokens !== 'number' ||
+            !Number.isSafeInteger(outputTokens) ||
+            outputTokens < 0 ||
+            typeof totalTokens !== 'number' ||
+            !Number.isSafeInteger(totalTokens) ||
+            totalTokens < 0) {
+            throw new Error('AI result usage is invalid');
+        }
+        usage = { inputTokens, outputTokens, totalTokens };
+    }
+    return {
+        output: rawOutput.map(parseOutputPart),
+        model,
+        generatedAt: generatedAtValue,
+        ...(usage === undefined ? {} : { usage }),
+    };
+};
+const getFailureMessage = (job) => {
+    const error = job.error;
+    const status = getString(job, 'status');
+    if (status === 'unknown') {
+        const detail = getErrorMessage(error, 'execution outcome is unknown');
+        return `AI generation outcome is uncertain; do not retry automatically: ${detail}`;
+    }
+    return getErrorMessage(error, 'AI generation failed');
+};
+const endpointHeaders = (endpoint, idempotencyKey) => ({
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${endpoint.token}`,
+    ...(idempotencyKey === undefined ? {} : { 'Idempotency-Key': idempotencyKey }),
+});
+const jobURL = (endpoint, id) => `${endpoint.url}/jobs${id === undefined ? '' : `/${encodeURIComponent(id)}`}`;
+const cancelJob = async (endpoint, id, fetch) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CANCEL_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${jobURL(endpoint, id)}/cancel`, {
+            method: 'POST',
+            headers: endpointHeaders(endpoint),
+            redirect: 'manual',
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new ClusterHTTPError(response.status, `AI cancellation returned HTTP ${response.status}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+const abortWithCancellation = async (endpoint, id, fetch, reason) => {
+    try {
+        await Promise.race([
+            cancelJob(endpoint, id, fetch),
+            new Promise((resolve) => setTimeout(resolve, CANCEL_TIMEOUT_MS)),
+        ]);
+    }
+    catch {
+        // Preserve the original abort or timeout reason when best-effort cancellation fails.
+    }
+    throw reason;
+};
+const createOperationAbort = (request, timeoutMs) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    const onAbort = () => controller.abort();
+    request.signal?.addEventListener('abort', onAbort, { once: true });
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            request.signal?.removeEventListener('abort', onAbort);
+        },
+    };
+};
+const generateCluster = async (request, config) => {
+    const endpoint = (0, exports.normalizeClusterEndpoint)(config.endpoint);
+    const dependencies = getDependencies(config.dependencies);
+    const timeoutMs = request.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxPollIntervalMs = config.maxPollIntervalMs ?? DEFAULT_MAX_POLL_INTERVAL_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new Error('generation timeout must be positive');
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+        throw new Error('poll interval must be positive');
+    }
+    if (!Number.isFinite(maxPollIntervalMs) || maxPollIntervalMs < pollIntervalMs) {
+        throw new Error('maximum poll interval is invalid');
+    }
+    throwIfAborted(request.signal);
+    const operationAbort = createOperationAbort(request, timeoutMs);
+    let jobId;
+    const deadline = dependencies.now() + timeoutMs;
+    const abortError = () => request.signal?.aborted ? new Error('generation aborted') : new Error('generation timed out');
+    try {
+        const idempotencyKey = dependencies.createIdempotencyKey();
+        if (idempotencyKey.trim().length === 0)
+            throw new Error('idempotency key is empty');
+        const body = {
+            version: 1,
+            input: request.input,
+            output: request.output ?? ['text'],
+            ...(request.instructions === undefined ? {} : { instructions: request.instructions }),
+            ...(request.model === undefined ? {} : { model: request.model }),
+            ...(request.model === undefined && request.prefer !== undefined
+                ? { prefer: request.prefer }
+                : {}),
+            ...(request.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: request.reasoningEffort }),
+            ...(request.maxOutputTokens === undefined
+                ? {}
+                : { maxOutputTokens: request.maxOutputTokens }),
+            ...(request.outputSchema === undefined ? {} : { outputSchema: request.outputSchema }),
+            ...(request.webSearch === undefined ? {} : { webSearch: request.webSearch }),
+        };
+        const created = parseJob(await withCreateRetry(() => fetchJSON({
+            fetch: dependencies.fetch,
+            url: jobURL(endpoint),
+            headers: endpointHeaders(endpoint, idempotencyKey),
+            method: 'POST',
+            body: JSON.stringify(body),
+            signal: operationAbort.signal,
+        }), dependencies.sleep, operationAbort.signal));
+        jobId = getString(created, 'id');
+        if (!jobId)
+            throw new Error('AI job is missing its id');
+        const status = getString(created, 'status');
+        if (!status)
+            throw new Error('AI job is missing its status');
+        if (TERMINAL_FAILURE_STATUSES.has(status))
+            throw new Error(getFailureMessage(created));
+        if (!PENDING_STATUSES.has(status) && !TERMINAL_SUCCESS_STATUSES.has(status)) {
+            throw new Error(`Unknown AI job status: ${status}`);
+        }
+        let delay = TERMINAL_SUCCESS_STATUSES.has(status) ? 0 : pollIntervalMs;
+        const maxPollAttempts = Math.max(1, Math.ceil(timeoutMs / pollIntervalMs)) + 2;
+        let pollAttempts = 0;
+        while (pollAttempts < maxPollAttempts) {
+            if (dependencies.now() >= deadline) {
+                return abortWithCancellation(endpoint, jobId, dependencies.fetch, new Error('generation timed out'));
+            }
+            if (delay > 0) {
+                // oxlint-disable-next-line no-await-in-loop -- polling must remain sequential
+                await awaitWithSignal(dependencies.sleep(Math.min(delay, Math.max(0, deadline - dependencies.now()))), operationAbort.signal);
+            }
+            if (operationAbort.signal.aborted) {
+                return abortWithCancellation(endpoint, jobId, dependencies.fetch, abortError());
+            }
+            if (dependencies.now() >= deadline) {
+                return abortWithCancellation(endpoint, jobId, dependencies.fetch, new Error('generation timed out'));
+            }
+            let current;
+            pollAttempts += 1;
+            try {
+                current = parseJob(
+                // oxlint-disable-next-line no-await-in-loop -- each poll depends on the prior status
+                await fetchJSON({
+                    fetch: dependencies.fetch,
+                    url: jobURL(endpoint, jobId),
+                    headers: endpointHeaders(endpoint),
+                    method: 'GET',
+                    signal: operationAbort.signal,
+                }));
+            }
+            catch (error) {
+                if (!isRetryable(error))
+                    throw error;
+                const retryDelay = Math.max(pollIntervalMs, delay);
+                // oxlint-disable-next-line no-await-in-loop -- backoff precedes the next status check
+                await awaitWithSignal(dependencies.sleep(retryDelay), operationAbort.signal);
+                delay = Math.min(maxPollIntervalMs, retryDelay * 2);
+                continue;
+            }
+            const currentStatus = getString(current, 'status');
+            if (!currentStatus)
+                throw new Error('AI job is missing its status');
+            if (TERMINAL_SUCCESS_STATUSES.has(currentStatus)) {
+                return parseResult(current);
+            }
+            if (TERMINAL_FAILURE_STATUSES.has(currentStatus))
+                throw new Error(getFailureMessage(current));
+            if (!PENDING_STATUSES.has(currentStatus)) {
+                throw new Error(`Unknown AI job status: ${currentStatus}`);
+            }
+            delay = Math.min(maxPollIntervalMs, Math.max(pollIntervalMs, delay * 2));
+        }
+        return abortWithCancellation(endpoint, jobId, dependencies.fetch, new Error('generation timed out'));
+    }
+    catch (error) {
+        if (operationAbort.signal.aborted && jobId !== undefined) {
+            return abortWithCancellation(endpoint, jobId, dependencies.fetch, abortError());
+        }
+        if (operationAbort.signal.aborted)
+            throw abortError();
+        throw error;
+    }
+    finally {
+        operationAbort.cleanup();
+    }
+};
+exports.generateCluster = generateCluster;
+const MODEL_MODALITIES = new Set(['text', 'image', 'audio', 'video', 'file']);
+const getModelId = (record) => {
+    for (const key of ['id', 'name', 'model', 'modelId']) {
+        const value = getString(record, key)?.trim();
+        if (value !== undefined && value.length > 0)
+            return value;
+    }
+    return undefined;
+};
+const parseStringList = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    return [
+        ...new Set(value.flatMap((item) => {
+            if (typeof item === 'string') {
+                const normalized = item.trim();
+                return normalized.length > 0 ? [normalized] : [];
+            }
+            if (isRecord(item)) {
+                const normalized = getString(item, 'reasoningEffort')?.trim();
+                return normalized === undefined || normalized.length === 0 ? [] : [normalized];
+            }
+            return [];
+        })),
+    ];
+};
+const parseModalities = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    return [
+        ...new Set(value.flatMap((item) => {
+            if (typeof item !== 'string')
+                return [];
+            const normalized = item.trim();
+            return MODEL_MODALITIES.has(normalized) ? [normalized] : [];
+        })),
+    ];
+};
+const parsePreferences = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    return [
+        ...new Set(value.filter((item) => item === 'fast' || item === 'quality')),
+    ];
+};
+const parseModel = (value) => {
+    if (typeof value === 'string') {
+        const id = value.trim();
+        return id.length === 0 ? undefined : { id };
+    }
+    if (!isRecord(value))
+        return undefined;
+    const id = getModelId(value);
+    if (id === undefined)
+        return undefined;
+    const capabilities = getRecord(value, 'capabilities') ?? value;
+    const model = { id };
+    const inputModalities = parseModalities(capabilities.inputModalities);
+    const outputModalities = parseModalities(capabilities.outputModalities);
+    const supportedReasoningEfforts = parseStringList(capabilities.supportedReasoningEfforts ?? capabilities.reasoningEfforts);
+    const defaultReasoningEffort = getString(capabilities, 'defaultReasoningEffort')?.trim();
+    const prefer = parsePreferences(capabilities.prefer ?? capabilities.preferences);
+    if (inputModalities !== undefined)
+        model.inputModalities = inputModalities;
+    if (outputModalities !== undefined)
+        model.outputModalities = outputModalities;
+    if (supportedReasoningEfforts !== undefined) {
+        model.supportedReasoningEfforts = supportedReasoningEfforts;
+    }
+    if (defaultReasoningEffort !== undefined && defaultReasoningEffort.length > 0) {
+        model.defaultReasoningEffort = defaultReasoningEffort;
+    }
+    if (prefer !== undefined)
+        model.prefer = prefer;
+    for (const key of ['webSearch', 'isDefault', 'ready']) {
+        const flag = capabilities[key];
+        if (typeof flag === 'boolean')
+            model[key] = flag;
+    }
+    return model;
+};
+const listClusterModels = async (endpoint, dependencies) => {
+    const normalizedEndpoint = (0, exports.normalizeClusterEndpoint)(endpoint);
+    const { fetch } = getDependencies(dependencies);
+    const payload = await fetchJSON({
+        fetch,
+        url: `${normalizedEndpoint.url}/models`,
+        headers: endpointHeaders(normalizedEndpoint),
+        method: 'GET',
+    });
+    const models = isRecord(payload) ? payload.models : payload;
+    if (!Array.isArray(models))
+        throw new Error('AI models response is invalid');
+    return models.map(parseModel).filter((model) => model !== undefined);
+};
+exports.listClusterModels = listClusterModels;

package/dist/client/adapters/google.d.ts

@@ -0,0 +1,12 @@
+import { GoogleGenAI } from '@google/genai';
+import { resetModelBackoff } from '../quota';
+import type { AIClientDependencies, AIModel, AIRequest, GenerationResult } from '../types';
+export type GoogleAdapterConfig = {
+    dependencies?: AIClientDependencies;
+    createAI?: (apiKey: string) => GoogleGenAI;
+};
+export declare const generateGoogle: (request: AIRequest, config?: GoogleAdapterConfig) => Promise<GenerationResult>;
+export declare const listGoogleModels: (dependencies?: AIClientDependencies) => Promise<AIModel[]>;
+export { resetModelBackoff };
+/** Test seam: reset adapter clients, model cache, and per-model rate-limit backoff. */
+export declare const resetGoogleAdapterForTests: () => void;