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

package/dist/providers/provider-call-failure.js

@@ -0,0 +1,132 @@
+/**
+ * Turns a thrown provider error into the `provider_call_failed` message the
+ * UI reports with.
+ *
+ * A user who hits a 429 sees prose. What a maintainer needs is the provider,
+ * the model, the status, the request id and the payload that was sent — and
+ * asking the user to reconstruct that from a toast is how bug reports arrive
+ * useless. {@link buildProviderCallFailure} assembles it once, at the same
+ * place {@link logProviderRequestFailure} logs it, so every surface reports
+ * the same record.
+ */
+import { isObjectLike, isString } from "@nodetool-ai/protocol";
+import { httpStatusFromError } from "./provider-error.js";
+import { sanitizeForLog } from "./provider-request-log.js";
+/** Strings in the reported request are capped harder than in a server log. */
+const WIRE_SANITIZE = {
+    maxStringLength: 400,
+    maxArrayLength: 40,
+    maxDepth: 8
+};
+const NETWORK_CODES = new Set([
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ETIMEDOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "CERT_HAS_EXPIRED"
+]);
+export function providerFailureKind(error) {
+    const status = httpStatusFromError(error);
+    if (status !== null) {
+        if (status === 401 || status === 403)
+            return "auth";
+        if (status === 402)
+            return "payment";
+        if (status === 404)
+            return "not_found";
+        if (status === 429)
+            return "rate_limit";
+        if (status === 408 || status === 504)
+            return "timeout";
+        if (status >= 500)
+            return "server";
+        if (status >= 400)
+            return "client";
+    }
+    if (!isObjectLike(error))
+        return "unknown";
+    const candidate = error;
+    const code = isString(candidate.code) ? candidate.code : "";
+    if (NETWORK_CODES.has(code))
+        return "network";
+    const name = isString(candidate.name) ? candidate.name : "";
+    if (name === "TimeoutError")
+        return "timeout";
+    const message = isString(candidate.message) ? candidate.message : "";
+    if (/fetch failed|network error|socket hang up/i.test(message)) {
+        return "network";
+    }
+    return "unknown";
+}
+/**
+ * Provider-side request id, under any of the names the SDKs use for it. It is
+ * what a provider's support asks for first, so it is worth digging out.
+ */
+export function providerRequestId(error) {
+    if (!isObjectLike(error))
+        return null;
+    const candidate = error;
+    const headers = isObjectLike(candidate.headers)
+        ? candidate.headers
+        : undefined;
+    const sources = [
+        candidate.request_id,
+        candidate.requestID,
+        candidate.requestId,
+        headers?.["x-request-id"],
+        headers?.["x-amzn-requestid"],
+        headers?.["cf-ray"]
+    ];
+    for (const value of sources) {
+        if (isString(value) && value.trim() !== "")
+            return value;
+    }
+    return null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The message a surface reports with. `null` for a caller cancellation. */
+export function buildProviderCallFailure(input, now = new Date()) {
+    if (isAbort(input.error))
+        return null;
+    const hasWire = input.request !== undefined && input.request !== null;
+    const payload = hasWire ? input.request : input.nodetoolArgs;
+    const status = httpStatusFromError(input.error);
+    const name = isObjectLike(input.error)
+        ? input.error.name
+        : undefined;
+    return {
+        type: "provider_call_failed",
+        provider: input.provider,
+        model: input.model && input.model !== "unknown" ? input.model : null,
+        operation: input.operation,
+        kind: providerFailureKind(input.error),
+        status,
+        message: errorMessage(input.error),
+        error_name: isString(name) ? name : null,
+        request_id: providerRequestId(input.error),
+        duration_ms: input.startedAt !== undefined ? Date.now() - input.startedAt : null,
+        request_source: payload === undefined ? null : hasWire ? "wire" : "nodetool-args",
+        request: payload === undefined ? null : sanitizeForLog(payload, WIRE_SANITIZE),
+        // Left null: the relay stamps the run onto every outbound message, and a
+        // provider has no idea which workflow or job called it.
+        workflow_id: null,
+        job_id: null,
+        timestamp: now.toISOString()
+    };
+}
+/** A cancelled call is not a failure to report. */
+function isAbort(error) {
+    if (!isObjectLike(error))
+        return false;
+    const candidate = error;
+    if (isString(candidate.name) && /abort/i.test(candidate.name))
+        return true;
+    return candidate.code === 20 || candidate.code === "ABORT_ERR";
+}
+//# sourceMappingURL=provider-call-failure.js.map

package/dist/providers/provider-call-failure.js.map

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

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;AAaH;;;;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;AA6ED;;;;;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,171 @@
+/**
+ * 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 { PROVIDER_IDS, 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:
+            if (provider === PROVIDER_IDS.CODEX) {
+                return `${target} rejected the ChatGPT sign-in (401). The sign-in expired: sign in to Codex again in Settings → Models & Providers.`;
+            }
+            if (provider === PROVIDER_IDS.CLAUDE_AGENT_SDK) {
+                return `${target} rejected the Claude sign-in (401). The sign-in expired: sign in to Claude again in Settings → Models & Providers.`;
+            }
+            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: only the providers that implement them declare
+ * `list_generations` and `get_generation`.
+ */
+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: only the providers that implement them declare
+ * `list_generations` and `get_generation`.
+ */
+/** 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"}