@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/dist/providers/provider-error.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Actionable text for opaque provider failures.
+ *
+ * Providers surface upstream HTTP errors verbatim — `403 Your request was
+ * blocked.`, `401 Incorrect API key provided`, `fetch failed` — which reaches
+ * the user as a node error with no hint of which provider failed or what to do
+ * about it. {@link annotateProviderError} appends the provider, the model, and
+ * a short remedy for the status class, leaving the original text at the front
+ * so existing message matching (rate limit, context length) still works.
+ */
+/**
+ * Machine-readable companion to the prose hint. Surfaces that want to *act* on
+ * a failure — reopen provider onboarding on the failing key, say — read this
+ * instead of matching the message text.
+ */
+export interface ProviderFailureDetail {
+    /**
+     * `provider_auth`: the credential was refused. `context_exceeded`: the
+     * request did not fit the model's context window, which a caller holding the
+     * transcript can answer by shortening it and retrying.
+     */
+    code: "provider_auth" | "context_exceeded";
+    /** Provider id as the runtime knows it (e.g. `openai`). */
+    provider: string;
+    /** Secret key holding that provider's credential, when one is registered. */
+    secretKey: string | null;
+}
+/**
+ * The structured detail {@link annotateProviderError} attached, or null when
+ * the error is not a credential failure.
+ */
+export declare function providerFailureDetail(error: unknown): ProviderFailureDetail | null;
+/**
+ * Tag `error` as the provider refusing a request larger than the model's
+ * context window. Kept apart from {@link annotateProviderError}: the prose hint
+ * is written from an HTTP status, while this classification comes from the
+ * provider's own overflow signal.
+ */
+export declare function markContextExceeded<TError>(error: TError, provider: string): TError;
+/**
+ * HTTP status carried by a provider error: a `status`/`statusCode` field when
+ * the provider throws a typed error, otherwise a status token at the start of
+ * the message (`"403 Your request was blocked."`, the shape both the `openai`
+ * SDK and {@link OpenAICompatError} use) or after an explicit `status`/`HTTP`
+ * marker. Bare three-digit numbers elsewhere in the message are ignored — they
+ * are far more often model ids or token counts than statuses.
+ */
+export declare function httpStatusFromError(error: unknown): number | null;
+/**
+ * Append provider context and a remedy to a provider failure, in place. The
+ * original message is kept as the prefix, and the error object (class, status,
+ * stack) is left intact. Aborts and already-annotated errors pass through
+ * untouched. Returns the same error so callers can `throw annotateProviderError(...)`.
+ */
+export declare function annotateProviderError<TError>(error: TError, context: {
+    provider: string;
+    model?: string;
+}): TError;
+//# sourceMappingURL=provider-error.d.ts.map

package/dist/providers/provider-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-error.d.ts","sourceRoot":"","sources":["../../src/providers/provider-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,IAAI,EAAE,eAAe,GAAG,kBAAkB,CAAC;IAC3C,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAgBD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,qBAAqB,GAAG,IAAI,CAG9B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EACxC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,MAAM,CAQR;AAQD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBjE;AAuED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAC1C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,MAAM,CA4BR"}

package/dist/providers/provider-error.js

@@ -0,0 +1,165 @@
+/**
+ * Actionable text for opaque provider failures.
+ *
+ * Providers surface upstream HTTP errors verbatim — `403 Your request was
+ * blocked.`, `401 Incorrect API key provided`, `fetch failed` — which reaches
+ * the user as a node error with no hint of which provider failed or what to do
+ * about it. {@link annotateProviderError} appends the provider, the model, and
+ * a short remedy for the status class, leaving the original text at the front
+ * so existing message matching (rate limit, context length) still works.
+ */
+import { getProviderSecretKey } from "./provider-registry.js";
+import { isNumber, isObjectLike, isString } from "@nodetool-ai/protocol";
+/** Marks an error already annotated, so nested wrappers don't stack hints. */
+const ANNOTATED = Symbol.for("nodetool.provider.errorAnnotated");
+/** Field carrying {@link ProviderFailureDetail} on an annotated error. */
+const FAILURE_DETAIL = Symbol.for("nodetool.provider.failureDetail");
+/**
+ * The structured detail {@link annotateProviderError} attached, or null when
+ * the error is not a credential failure.
+ */
+export function providerFailureDetail(error) {
+    if (!isObjectLike(error))
+        return null;
+    return error[FAILURE_DETAIL] ?? null;
+}
+/**
+ * Tag `error` as the provider refusing a request larger than the model's
+ * context window. Kept apart from {@link annotateProviderError}: the prose hint
+ * is written from an HTTP status, while this classification comes from the
+ * provider's own overflow signal.
+ */
+export function markContextExceeded(error, provider) {
+    if (!(error instanceof Error))
+        return error;
+    error[FAILURE_DETAIL] = {
+        code: "context_exceeded",
+        provider,
+        secretKey: null
+    };
+    return error;
+}
+function numericStatus(value) {
+    const status = isString(value) ? Number(value) : value;
+    if (!isNumber(status) || !Number.isInteger(status))
+        return null;
+    return status >= 100 && status <= 599 ? status : null;
+}
+/**
+ * HTTP status carried by a provider error: a `status`/`statusCode` field when
+ * the provider throws a typed error, otherwise a status token at the start of
+ * the message (`"403 Your request was blocked."`, the shape both the `openai`
+ * SDK and {@link OpenAICompatError} use) or after an explicit `status`/`HTTP`
+ * marker. Bare three-digit numbers elsewhere in the message are ignored — they
+ * are far more often model ids or token counts than statuses.
+ */
+export function httpStatusFromError(error) {
+    if (!isObjectLike(error))
+        return null;
+    const candidate = error;
+    const direct = numericStatus(candidate.status) ??
+        numericStatus(candidate.statusCode) ??
+        numericStatus(candidate.response?.status);
+    if (direct !== null)
+        return direct;
+    const message = isString(candidate.message) ? candidate.message : "";
+    const leading = message.match(/^\s*(\d{3})\b/);
+    if (leading)
+        return numericStatus(leading[1]);
+    const labelled = message.match(/\b(?:status|http|status code)[:\s]+(\d{3})\b/i);
+    return labelled ? numericStatus(labelled[1]) : null;
+}
+function isAbort(error) {
+    const name = isString(error.name) ? error.name : "";
+    if (name === "AbortError" || name === "TimeoutError")
+        return true;
+    const code = isString(error.code) ? error.code : "";
+    return code === "ABORT_ERR";
+}
+const NETWORK_CODES = new Set([
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ETIMEDOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "CERT_HAS_EXPIRED"
+]);
+function isNetworkFailure(error) {
+    const code = isString(error.code) ? error.code : "";
+    if (NETWORK_CODES.has(code))
+        return true;
+    const message = isString(error.message) ? error.message : "";
+    return /fetch failed|network error|socket hang up/i.test(message);
+}
+/** Remedy for one status class, or null when the status needs no advice. */
+function hintForStatus(status, provider, model) {
+    const target = model ? `${provider}/${model}` : provider;
+    switch (status) {
+        case 401:
+            return `${target} rejected the credentials (401). Add or update the API key for ${provider} in Settings → Models & Providers.`;
+        case 403:
+            return `${target} refused the request (403). The API key may be missing access to this model, restricted to certain referrers or IPs, or blocked in your region — check it in Settings → Models & Providers.`;
+        case 402:
+            return `${target} reports the account is out of credit (402). Top up or check billing with ${provider}.`;
+        case 404:
+            return `${target} does not expose this model (404). Pick another model, or check that your ${provider} account has access to it.`;
+        case 429:
+            return `${target} is rate limiting or out of quota (429). Wait and retry, or check your ${provider} plan limits.`;
+        case 408:
+        case 504:
+            return `${target} timed out (${status}). Retry, or lower the request size.`;
+        default:
+            if (status >= 500) {
+                return `${target} is failing on its side (${status}). Retry in a moment; if it persists, check the ${provider} status page.`;
+            }
+            return null;
+    }
+}
+function hintFor(error, provider, model) {
+    const status = httpStatusFromError(error);
+    if (status !== null)
+        return hintForStatus(status, provider, model);
+    if (isNetworkFailure(error)) {
+        const target = model ? `${provider}/${model}` : provider;
+        return `Could not reach ${target}. Check your internet connection, proxy settings, and — for local providers — that the server is running.`;
+    }
+    return null;
+}
+/**
+ * Append provider context and a remedy to a provider failure, in place. The
+ * original message is kept as the prefix, and the error object (class, status,
+ * stack) is left intact. Aborts and already-annotated errors pass through
+ * untouched. Returns the same error so callers can `throw annotateProviderError(...)`.
+ */
+export function annotateProviderError(error, context) {
+    if (!(error instanceof Error))
+        return error;
+    const candidate = error;
+    if (candidate[ANNOTATED] || isAbort(candidate))
+        return error;
+    // "unknown" is the modality wrappers' placeholder when the params carry no
+    // model id; naming it would read as a model called "unknown".
+    const model = context.model && context.model !== "unknown" ? context.model : "";
+    const hint = hintFor(candidate, context.provider, model);
+    if (!hint)
+        return error;
+    // 401/403 both mean "the credential didn't work" as far as a user is
+    // concerned — one is rejected, the other refused — and both are fixed on the
+    // same screen, so both carry the structured detail.
+    const status = httpStatusFromError(candidate);
+    if (status === 401 || status === 403) {
+        candidate[FAILURE_DETAIL] = {
+            code: "provider_auth",
+            provider: context.provider,
+            secretKey: getProviderSecretKey(context.provider)
+        };
+    }
+    candidate[ANNOTATED] = true;
+    const original = candidate.message.trim();
+    candidate.message = original ? `${original} — ${hint}` : hint;
+    return error;
+}
+//# sourceMappingURL=provider-error.js.map

package/dist/providers/provider-error.js.map

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

package/dist/providers/provider-generations.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The provider-side generation record: what a provider itself knows about the
+ * media calls an account made, read back from the provider's own API.
+ *
+ * NodeTool keeps its own record of every generation this installation ran —
+ * the `predictions` table behind `nodetool generations`
+ * (docs/media-generation-tracking-design.md). That record is local: it cannot
+ * see a generation made from another machine, from the provider's own web UI,
+ * or from a run whose row was lost, and it carries an estimate until a
+ * reconciler replaces it with the billed amount.
+ *
+ * A provider that keeps its own request history can answer for all of those.
+ * {@link BaseProvider.listGenerations} and {@link BaseProvider.getGeneration}
+ * are where that history is exposed, in one shape across providers, so a
+ * caller reconciling spend or hunting a lost asset does not write a client per
+ * provider. A provider without such an API keeps the base methods and throws
+ * {@link ProviderGenerationsUnsupportedError}, which is a capability answer,
+ * not a failure: `providerCapabilities` reports `list_generations` and
+ * `get_generation` only for the providers that override them.
+ */
+import type { ProviderId } from "./types.js";
+/**
+ * A generation's state at the provider. `unknown` is its own answer: a record
+ * derived from a billing event says a call was charged without saying how it
+ * ended, and reporting that as `completed` would invent an outcome.
+ */
+export type ProviderGenerationStatus = "running" | "completed" | "failed" | "cancelled" | "unknown";
+/** One provider-side generation, in the shape every provider answers with. */
+export interface ProviderGeneration {
+    provider: ProviderId;
+    /** The provider's own request id — what `provider_request_id` holds locally. */
+    request_id: string;
+    /** The endpoint or model that ran, when the provider names one. */
+    model: string | null;
+    status: ProviderGenerationStatus;
+    /** ISO timestamps, as the provider reports them. */
+    created_at: string | null;
+    completed_at: string | null;
+    duration_seconds: number | null;
+    /** What the provider billed, not an estimate. Null when it does not say. */
+    cost: number | null;
+    currency: string | null;
+    quantity: number | null;
+    unit_price: number | null;
+    /** Output media the provider still hosts. Empty when it reports none. */
+    output_urls: string[];
+    /** The generation's own failure, when the provider reports one. */
+    error: string | null;
+}
+/** Filters a provider listing understands. Every field is optional. */
+export interface ProviderGenerationQuery {
+    /** Endpoint / model ids to list, when the provider filters by them. */
+    model?: string | readonly string[];
+    status?: ProviderGenerationStatus;
+    /** ISO timestamp; generations started before it are left out. */
+    since?: string;
+    /** ISO timestamp, exclusive upper bound. */
+    until?: string;
+    limit?: number;
+    /** The `next_cursor` of a previous page. */
+    cursor?: string | null;
+    signal?: AbortSignal;
+}
+export interface ProviderGenerationPage {
+    generations: ProviderGeneration[];
+    next_cursor: string | null;
+    /**
+     * What this page could not answer — a provider whose listing carries cost
+     * but not outcome says so here rather than guessing a status.
+     */
+    note: string | null;
+}
+/** What a single-generation lookup can be told besides the request id. */
+export interface ProviderGenerationLookup {
+    /** The endpoint / model id, when the caller knows it. Narrows the query. */
+    model?: string;
+    signal?: AbortSignal;
+}
+/** Raised by the base methods: this provider exposes no generation history. */
+export declare class ProviderGenerationsUnsupportedError extends Error {
+    readonly provider: string;
+    readonly operation: "list" | "get";
+    constructor(provider: string, operation: "list" | "get");
+}
+/** Whether a thrown value is the "no generation history here" answer. */
+export declare function isProviderGenerationsUnsupported(error: unknown): error is ProviderGenerationsUnsupportedError;
+/**
+ * A generation record with every field present, so each provider's mapper
+ * fills in only what its API reports and nothing is silently absent.
+ */
+export declare function providerGeneration(fields: Partial<ProviderGeneration> & {
+    provider: ProviderId;
+    request_id: string;
+}): ProviderGeneration;
+/** Bound a caller's page size to what a provider's API accepts. */
+export declare function boundedLimit(limit: number | undefined, fallback: number, max: number): number;
+/** The `model` filter as a list, whichever form the caller passed. */
+export declare function modelFilter(model: string | readonly string[] | undefined): string[];
+//# sourceMappingURL=provider-generations.d.ts.map

package/dist/providers/provider-generations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-generations.d.ts","sourceRoot":"","sources":["../../src/providers/provider-generations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,SAAS,GACT,WAAW,GACX,QAAQ,GACR,WAAW,GACX,SAAS,CAAC;AAEd,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,UAAU,CAAC;IACrB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,wBAAwB,CAAC;IACjC,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yEAAyE;IACzE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,+EAA+E;AAC/E,qBAAa,mCAAoC,SAAQ,KAAK;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAEnC,YAAY,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,EAQtD;CACF;AAED,yEAAyE;AACzE,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,mCAAmC,CAE9C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG;IACpC,QAAQ,EAAE,UAAU,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB,GACA,kBAAkB,CAgBpB;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,MAAM,CAGR;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,GAC5C,MAAM,EAAE,CAIV"}

package/dist/providers/provider-generations.js

@@ -0,0 +1,71 @@
+/**
+ * The provider-side generation record: what a provider itself knows about the
+ * media calls an account made, read back from the provider's own API.
+ *
+ * NodeTool keeps its own record of every generation this installation ran —
+ * the `predictions` table behind `nodetool generations`
+ * (docs/media-generation-tracking-design.md). That record is local: it cannot
+ * see a generation made from another machine, from the provider's own web UI,
+ * or from a run whose row was lost, and it carries an estimate until a
+ * reconciler replaces it with the billed amount.
+ *
+ * A provider that keeps its own request history can answer for all of those.
+ * {@link BaseProvider.listGenerations} and {@link BaseProvider.getGeneration}
+ * are where that history is exposed, in one shape across providers, so a
+ * caller reconciling spend or hunting a lost asset does not write a client per
+ * provider. A provider without such an API keeps the base methods and throws
+ * {@link ProviderGenerationsUnsupportedError}, which is a capability answer,
+ * not a failure: `providerCapabilities` reports `list_generations` and
+ * `get_generation` only for the providers that override them.
+ */
+/** Raised by the base methods: this provider exposes no generation history. */
+export class ProviderGenerationsUnsupportedError extends Error {
+    provider;
+    operation;
+    constructor(provider, operation) {
+        super(`${provider} does not expose provider-side generations (${operation}). ` +
+            `Read the local record with the generations capabilities instead.`);
+        this.name = "ProviderGenerationsUnsupportedError";
+        this.provider = provider;
+        this.operation = operation;
+    }
+}
+/** Whether a thrown value is the "no generation history here" answer. */
+export function isProviderGenerationsUnsupported(error) {
+    return error instanceof ProviderGenerationsUnsupportedError;
+}
+/**
+ * A generation record with every field present, so each provider's mapper
+ * fills in only what its API reports and nothing is silently absent.
+ */
+export function providerGeneration(fields) {
+    return {
+        provider: fields.provider,
+        request_id: fields.request_id,
+        model: fields.model ?? null,
+        status: fields.status ?? "unknown",
+        created_at: fields.created_at ?? null,
+        completed_at: fields.completed_at ?? null,
+        duration_seconds: fields.duration_seconds ?? null,
+        cost: fields.cost ?? null,
+        currency: fields.currency ?? null,
+        quantity: fields.quantity ?? null,
+        unit_price: fields.unit_price ?? null,
+        output_urls: fields.output_urls ?? [],
+        error: fields.error ?? null
+    };
+}
+/** Bound a caller's page size to what a provider's API accepts. */
+export function boundedLimit(limit, fallback, max) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return fallback;
+    return Math.min(Math.max(1, Math.floor(limit)), max);
+}
+/** The `model` filter as a list, whichever form the caller passed. */
+export function modelFilter(model) {
+    if (model === undefined)
+        return [];
+    const list = Array.isArray(model) ? [...model] : [String(model)];
+    return list.filter((id) => id.length > 0);
+}
+//# sourceMappingURL=provider-generations.js.map

package/dist/providers/provider-generations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-generations.js","sourceRoot":"","sources":["../../src/providers/provider-generations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuEH,+EAA+E;AAC/E,MAAM,OAAO,mCAAoC,SAAQ,KAAK;IACnD,QAAQ,CAAS;IACjB,SAAS,CAAiB;IAEnC,YAAY,QAAgB,EAAE,SAAyB;QACrD,KAAK,CACH,GAAG,QAAQ,+CAA+C,SAAS,KAAK;YACtE,kEAAkE,CACrE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qCAAqC,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,UAAU,gCAAgC,CAC9C,KAAc;IAEd,OAAO,KAAK,YAAY,mCAAmC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAGC;IAED,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,SAAS;QAClC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;QACrC,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;QACzC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,IAAI;QACjD,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;QACrC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;KAC5B,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,YAAY,CAC1B,KAAyB,EACzB,QAAgB,EAChB,GAAW;IAEX,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACpE,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,WAAW,CACzB,KAA6C;IAE7C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/providers/provider-queue.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Provider-neutral contracts for queue-backed generation adapters.
+ *
+ * The runtime deliberately owns no persistence or generation lifecycle here.
+ * Hosts can bind the returned submission to their durable attempt before
+ * waiting, while provider adapters remain responsible for transport only.
+ */
+export interface ProviderQueueSubmission {
+    readonly provider: string;
+    readonly endpoint: string;
+    readonly providerRequestId: string;
+    readonly statusLocator?: string;
+    readonly resultLocator?: string;
+    readonly cancelLocator?: string;
+}
+export interface ProviderQueueBinding extends ProviderQueueSubmission {
+    /** The exact endpoint and request id that were persisted by the host. */
+    readonly bound: true;
+}
+export type ProviderQueueState = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+export interface ProviderQueueObservation<TResult = unknown> {
+    readonly provider: string;
+    readonly endpoint: string;
+    readonly providerRequestId: string;
+    readonly state: ProviderQueueState;
+    readonly result?: TResult;
+    readonly error?: unknown;
+    readonly rawStatus?: unknown;
+}
+/**
+ * A provider has returned an explicit terminal observation. Transport errors,
+ * poll timeouts, and local decode/storage failures must not be represented by
+ * this error because they leave the durable attempt recoverable.
+ */
+export declare class ProviderQueueTerminalError extends Error {
+    readonly provider: string;
+    readonly providerRequestId: string;
+    readonly state: Extract<ProviderQueueState, "failed" | "cancelled">;
+    readonly observation?: ProviderQueueObservation | undefined;
+    readonly authoritativeProviderTerminal: true;
+    constructor(provider: string, providerRequestId: string, state: Extract<ProviderQueueState, "failed" | "cancelled">, observation?: ProviderQueueObservation | undefined);
+}
+export interface ProviderQueueWaitOptions {
+    readonly signal?: AbortSignal;
+    readonly onUpdate?: (observation: ProviderQueueObservation) => void;
+    readonly pollIntervalMs?: number;
+}
+/**
+ * A small adapter surface that can be backed by an ephemeral host today and
+ * a durable generation worker later. `bind` is intentionally explicit even
+ * when the provider returns its id in the submit response.
+ */
+export interface ProviderQueueAdapter<TInput = unknown, TResult = unknown> {
+    readonly provider: string;
+    submit(input: TInput): Promise<ProviderQueueSubmission>;
+    bind(submission: ProviderQueueSubmission): Promise<ProviderQueueBinding>;
+    wait(binding: ProviderQueueBinding, options?: ProviderQueueWaitOptions): Promise<ProviderQueueObservation<TResult>>;
+    cancel(binding: ProviderQueueBinding, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+//# sourceMappingURL=provider-queue.d.ts.map

package/dist/providers/provider-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-queue.d.ts","sourceRoot":"","sources":["../../src/providers/provider-queue.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,oBAAqB,SAAQ,uBAAuB;IACnE,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,SAAS,GACT,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,WAAW,wBAAwB,CAAC,OAAO,GAAG,OAAO;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAIjD,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,iBAAiB,EAAE,MAAM;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,kBAAkB,EAAE,QAAQ,GAAG,WAAW,CAAC;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB;IANjD,QAAQ,CAAC,6BAA6B,OAAiB;IAEvD,YACW,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,MAAM,EACzB,KAAK,EAAE,OAAO,CAAC,kBAAkB,EAAE,QAAQ,GAAG,WAAW,CAAC,EAC1D,WAAW,CAAC,EAAE,wBAAwB,YAAA,EAMhD;CACF;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,wBAAwB,KAAK,IAAI,CAAC;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU,EAAE,uBAAuB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzE,IAAI,CACF,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,MAAM,CACJ,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/providers/provider-queue.js

@@ -0,0 +1,28 @@
+/**
+ * Provider-neutral contracts for queue-backed generation adapters.
+ *
+ * The runtime deliberately owns no persistence or generation lifecycle here.
+ * Hosts can bind the returned submission to their durable attempt before
+ * waiting, while provider adapters remain responsible for transport only.
+ */
+/**
+ * A provider has returned an explicit terminal observation. Transport errors,
+ * poll timeouts, and local decode/storage failures must not be represented by
+ * this error because they leave the durable attempt recoverable.
+ */
+export class ProviderQueueTerminalError extends Error {
+    provider;
+    providerRequestId;
+    state;
+    observation;
+    authoritativeProviderTerminal = true;
+    constructor(provider, providerRequestId, state, observation) {
+        super(`Provider queue request ${providerRequestId} did not succeed (${state})`);
+        this.provider = provider;
+        this.providerRequestId = providerRequestId;
+        this.state = state;
+        this.observation = observation;
+        this.name = "ProviderQueueTerminalError";
+    }
+}
+//# sourceMappingURL=provider-queue.js.map

package/dist/providers/provider-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-queue.js","sourceRoot":"","sources":["../../src/providers/provider-queue.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiCH;;;;GAIG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAIxC,QAAQ;IACR,iBAAiB;IACjB,KAAK;IACL,WAAW;IANb,6BAA6B,GAAG,IAAa,CAAC;IAEvD,YACW,QAAgB,EAChB,iBAAyB,EACzB,KAA0D,EAC1D,WAAsC;QAE/C,KAAK,CACH,0BAA0B,iBAAiB,qBAAqB,KAAK,GAAG,CACzE,CAAC;wBAPO,QAAQ;iCACR,iBAAiB;qBACjB,KAAK;2BACL,WAAW;QAKpB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}

package/dist/providers/provider-registry.d.ts

@@ -1,24 +1,43 @@
 import type { BaseProvider } from "./base-provider.js";
-interface ProviderRegistration {
-    cls: new (...args: any[]) => BaseProvider;
+/** A provider class as the registry constructs it: from its resolved kwargs. */
+type ProviderConstructor = new (kwargs: Record<string, unknown>) => BaseProvider;
+export type ProviderAccess = "in_process" | "local_service" | "remote_api";
+export interface ProviderRegistrationMetadata {
+    /** Describes where model inference runs, independently from cache state. */
+    access: ProviderAccess;
+    displayName: string;
+}
+export interface ProviderRegistration {
+    cls: ProviderConstructor;
     kwargs: Record<string, unknown>;
+    optionalKwargs: Record<string, unknown>;
+    metadata: ProviderRegistrationMetadata;
 }
-type SecretResolver = (key: string, userId: string) => Promise<string | null | undefined> | string | null | undefined;
-export declare function registerProvider(providerId: string, cls: new (...args: any[]) => BaseProvider, kwargs?: Record<string, unknown>): void;
-export declare function getRegisteredProvider(providerId: string): ProviderRegistration | null;
 /**
- * Set a secret resolver so that providers can resolve API keys from
- * sources beyond process.env (e.g. encrypted secrets DB).
- *
- * The resolver receives (secretKey, userId) so secrets are resolved per-user.
+ * Resolve a credential by name. Callers bind any user/account identity into
+ * the closure before passing it in — this module deliberately has no notion
+ * of users or storage backends.
  */
-export declare function setSecretResolver(resolver: SecretResolver): void;
-export declare function getProvider(providerId: string, userId?: string): Promise<BaseProvider>;
-export declare function clearProviderCache(): number;
+export type GetSecret = (key: string) => Promise<string | null | undefined> | string | null | undefined;
+export declare function registerProvider(providerId: string, cls: ProviderConstructor, kwargs?: Record<string, unknown>, optionalKwargs?: Record<string, unknown>, metadata?: Partial<ProviderRegistrationMetadata>): void;
+export declare function getRegisteredProvider(providerId: string): ProviderRegistration | null;
 export declare function listRegisteredProviderIds(): string[];
+/** Remove a provider from the registry. Returns true if one was removed. */
+export declare function unregisterProvider(providerId: string): boolean;
+/** `process.env[key]`, falling back to the names that vendor's SDK uses. */
+export declare function readCredentialEnv(key: string): string | undefined;
+/** Resolve one credential exactly as provider construction does. */
+export declare function resolveCredentialValue(key: string, getSecret: GetSecret): Promise<string | undefined>;
+/**
+ * Build a fresh provider instance, resolving any unset credential kwargs via
+ * `getSecret` first, then `process.env` as fallback. The caller owns any
+ * caching — instance reuse is a property of a ProcessingContext, not a module
+ * global.
+ */
+export declare function getProvider(providerId: string, getSecret: GetSecret): Promise<BaseProvider>;
 /** Get the secret key name required by a provider (e.g. "OPENAI_API_KEY"), or null. */
 export declare function getProviderSecretKey(providerId: string): string | null;
-/** Check if a provider has credentials available for a given user (DB, env, or is local). */
-export declare function isProviderConfigured(providerId: string, userId?: string): Promise<boolean>;
+/** Check if a provider's required credentials are resolvable. */
+export declare function isProviderConfigured(providerId: string, getSecret: GetSecret): Promise<boolean>;
 export {};
 //# sourceMappingURL=provider-registry.d.ts.map

package/dist/providers/provider-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-registry.d.ts","sourceRoot":"","sources":["../../src/providers/provider-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,UAAU,oBAAoB;IAC5B,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,YAAY,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,KAAK,cAAc,GAAG,CACpB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAOpE,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,YAAY,EACzC,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,IAAI,CAEN;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,GACjB,oBAAoB,GAAG,IAAI,CAE7B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAIhE;AAED,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,SAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAoCvB;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAetE;AAED,6FAA6F;AAC7F,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,MAAM,SAAM,GACX,OAAO,CAAC,OAAO,CAAC,CA6ClB"}
+{"version":3,"file":"provider-registry.d.ts","sourceRoot":"","sources":["../../src/providers/provider-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD,gFAAgF;AAChF,KAAK,mBAAmB,GAAG,KACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,YAAY,CAAC;AAElB,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,CAAC;AAE3E,MAAM,WAAW,4BAA4B;IAC3C,4EAA4E;IAC5E,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,mBAAmB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIhC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,EAAE,4BAA4B,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,KACR,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAIpE,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,mBAAmB,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,cAAc,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAC5C,QAAQ,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACnD,IAAI,CAUN;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,GACjB,oBAAoB,GAAG,IAAI,CAE7B;AAED,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9D;AAeD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQjE;AAED,oEAAoE;AACpE,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,YAAY,CAAC,CAuCvB;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAatE;AAED,iEAAiE;AACjE,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,OAAO,CAAC,CA+BlB"}