@nathapp/nax-agent 0.1.0

package/dist/native/auth.js

@@ -0,0 +1,362 @@
+/**
+ * Obtaining and managing credentials, in nax's vocabulary.
+ *
+ * This file and its siblings are the only place in src/ permitted to import
+ * nax-ai (packages/repo-tooling/scripts/check-nax-ai-imports.ts). Nothing it exports carries a
+ * nax-ai type, so src/cli/auth.ts can consume it without breaching that gate.
+ */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ambientAuthAvailable, defaultProviders, login, } from "@nathapp/nax-ai";
+import { NaxError } from "#src/infra/index";
+import { naxCredentialStore, readStoredEntries } from "./credentials/index.js";
+/**
+ * Deliberately dumb: the two vocabularies are one-for-one by design, so this
+ * is a rename boundary rather than a translation with opinions. Both sides use
+ * kebab-case, so the names pass straight through.
+ */
+export function toLoginInteraction(interaction) {
+    return {
+        prompt: async (prompt) => interaction.prompt(prompt),
+        notify: (event) => interaction.notify(event),
+    };
+}
+/**
+ * Cancellation is not a failure, and the CLI needs to tell them apart to exit
+ * 130 silently. A marker class rather than a code match: an exit status should
+ * not depend on message text.
+ */
+export class AuthCancelledError extends Error {
+    providerId;
+    constructor(providerId) {
+        super(`Login for "${providerId}" was cancelled`);
+        this.providerId = providerId;
+        this.name = "AuthCancelledError";
+    }
+}
+/** Test seam, following the _clientDeps precedent. */
+export const _authDeps = {
+    login,
+    ambientAuthAvailable,
+    providerIds: async () => (await defaultProviders()).map((provider) => provider.id),
+    /**
+     * Injectable timer pair — lets tests drive `anyAmbientCredential`'s
+     * expiry branch off a virtual clock instead of waiting the full 2s
+     * production timeout. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps`.
+     *
+     * @internal
+     */
+    setTimeout: ((fn, ms) => setTimeout(fn, ms)),
+    clearTimeout: ((id) => clearTimeout(id)),
+};
+/**
+ * nax-ai's errors are mapped here rather than in the CLI, so its type names
+ * stay behind this directory's boundary.
+ *
+ * A prohibited flow keeps its message: the recorded reason is the whole point
+ * of the policy file, and a generic failure would discard it.
+ */
+function toNaxError(error, providerId) {
+    if (error instanceof Error) {
+        // Nax's own prompts reject with PromptCancelledError from inside the
+        // interaction callback, so it surfaces here rather than being converted
+        // by nax-ai's login() — that conversion only fires on an aborted signal,
+        // and runLogin never threads one.
+        if (error.name === "LoginCancelledError" || error.name === "PromptCancelledError") {
+            return new AuthCancelledError(providerId);
+        }
+        if (error.name === "OAuthFlowProhibitedError") {
+            return new NaxError(error.message, "AUTH_OAUTH_PROHIBITED", { providerId });
+        }
+        if (error.name === "AuthMethodUnavailableError") {
+            // "requested" separates "this provider offers nothing we can run" from
+            // "it offers something, just not the --method you asked for". Collapsing
+            // them tells a user whose provider supports oauth that nothing is
+            // available, and sends them to a config problem that does not exist.
+            const requested = error.requested;
+            return new NaxError(requested === undefined
+                ? `No login method is available for "${providerId}".`
+                : `"${providerId}" does not offer "${requested}" login. Omit --method to see what it does offer.`, "AUTH_METHOD_UNAVAILABLE", { providerId, ...(requested !== undefined ? { requested } : {}) });
+        }
+        return new NaxError(`Login for "${providerId}" failed: ${error.message}`, "AUTH_LOGIN_FAILED", { providerId });
+    }
+    return new NaxError(`Login for "${providerId}" failed.`, "AUTH_LOGIN_FAILED", { providerId });
+}
+/**
+ * Obtain a credential and write it to the store.
+ *
+ * `method` is forwarded, not interpreted: nax-ai owns the table of what each
+ * provider offers and rejects an unavailable choice itself. Omitted, it runs
+ * its own selection prompt. Deciding here is how the two drift apart.
+ *
+ * The result is reported exactly as returned. kind is never derived from
+ * method — M5's design predicted openrouter would report kind "api-key" and
+ * its live run reported "oauth".
+ */
+export async function runLogin(providerId, interaction, method) {
+    try {
+        const result = await _authDeps.login({
+            providerId,
+            credentials: naxCredentialStore(),
+            interaction: toLoginInteraction(interaction),
+            ...(method !== undefined ? { method } : {}),
+        });
+        return { providerId: result.providerId, method: result.method, kind: result.kind };
+    }
+    catch (error) {
+        throw toNaxError(error, providerId);
+    }
+}
+export const DEFAULT_PI_AUTH_PATH = join(homedir(), ".pi", "agent", "auth.json");
+/**
+ * pi's on-disk shape is flat and snake-cased; the store's is versioned and
+ * kebab-cased. accountId is deliberately dropped: pi derives it from the
+ * access-token JWT at request time rather than trusting what is stored, and
+ * nax-ai's own credential round-trip already drops it.
+ */
+function fromPiEntry(entry) {
+    if (entry.type === "api_key" && typeof entry.key === "string") {
+        return { kind: "api-key", key: entry.key };
+    }
+    if (entry.type === "oauth" &&
+        typeof entry.access === "string" &&
+        typeof entry.refresh === "string" &&
+        typeof entry.expires === "number") {
+        return { kind: "oauth", access: entry.access, refresh: entry.refresh, expires: entry.expires };
+    }
+    return undefined;
+}
+/**
+ * Bring pi's credentials across.
+ *
+ * Existing entries are skipped rather than overwritten: import plausibly runs
+ * after a fresh login, and silently replacing a credential just obtained would
+ * be the worst kind of quiet data loss.
+ *
+ * The presence check happens inside modify()'s callback, not before it: that
+ * is what holds the store's cross-process lock across the whole
+ * read-modify-write. Deciding "already present" from a separate, unlocked
+ * read would race a concurrent login completing between the two calls.
+ */
+export async function importPiCredentials(options) {
+    const path = options?.from ?? DEFAULT_PI_AUTH_PATH;
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new NaxError(`No credential file to import at ${path}.`, "AUTH_IMPORT_SOURCE_MISSING", {
+                path,
+                cause: error,
+            });
+        }
+        throw new NaxError(`The file at ${path} could not be read.`, "AUTH_IMPORT_SOURCE_UNREADABLE", {
+            path,
+            cause: error,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new NaxError(`The file at ${path} is not valid JSON.`, "AUTH_IMPORT_SOURCE_UNREADABLE", {
+            path,
+            cause: error,
+        });
+    }
+    const store = naxCredentialStore();
+    const outcomes = [];
+    for (const providerId of Object.keys(parsed).sort()) {
+        const entry = parsed[providerId];
+        const credential = entry === undefined ? undefined : fromPiEntry(entry);
+        if (credential === undefined) {
+            outcomes.push({ providerId, status: "unsupported" });
+            continue;
+        }
+        let status = "imported";
+        await store.modify(providerId, async (existing) => {
+            if (existing !== undefined && options?.force !== true) {
+                status = "skipped";
+                return existing;
+            }
+            return credential;
+        });
+        outcomes.push({ providerId, status });
+    }
+    return outcomes;
+}
+export async function listStoredProviders() {
+    return readStoredEntries();
+}
+/**
+ * Removal, not revocation. pi has no revocation anywhere — its own types
+ * define logout as deletion — so the provider-side token stays live until it
+ * expires. Callers must not describe this as logging out.
+ */
+export async function removeStoredProvider(providerId) {
+    await naxCredentialStore().delete(providerId);
+}
+export function authImportOutcomeLabel(status) {
+    if (status === "imported")
+        return "imported";
+    if (status === "skipped")
+        return "skipped, already present";
+    return "unsupported credential type";
+}
+/**
+ * Of these providers, which would ambient auth satisfy on its own?
+ *
+ * A stored credential owns its provider in pi's resolution order, so any
+ * provider named here has a working environment variable that the stored
+ * credential is shadowing. This only ever decorates a diagnostic, so a failing
+ * probe reports nothing rather than breaking the command around it.
+ */
+export async function ambientShadows(providerIds) {
+    const checked = await Promise.all(providerIds.map(async (providerId) => {
+        try {
+            return (await _authDeps.ambientAuthAvailable(providerId)) ? providerId : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    return checked.filter((id) => id !== undefined);
+}
+/**
+ * Of these providers, which have NO credential at all — neither stored nor
+ * ambient?
+ *
+ * Asked for the providers the default native tier map names, so an install
+ * whose only credential belongs to another provider fails before a billed call
+ * rather than at the first request.
+ *
+ * What counts as "has a credential": a credential the assembled store serves
+ * for that provider, or nax-ai's ambient probe answering true. That probe
+ * swallows its own check/resolve errors and answers false, so a provider whose
+ * resolution fails IS reported missing — the caller must exclude providers it
+ * knows authenticate some other way (catalog overrides). The two cases here
+ * that do not guess "no" are the ones this function can see: an unreadable
+ * store, and a sweep that outlives AMBIENT_PROBE_TIMEOUT_MS (pi's resolve()
+ * "may execute commands") — both report nothing missing.
+ *
+ * US-004: "has a stored credential" is a read through `naxCredentialStore()`,
+ * per provider, rather than a listing of the file. With an exec helper
+ * configured only the store knows which source serves a provider, and a helper
+ * failure (CREDENTIAL_HELPER_FAILED, CREDENTIAL_HELPER_INVALID) or a refused
+ * change (CREDENTIAL_CHANGED) is a run-level fault, not a missing credential —
+ * it propagates and refuses the run. The reads also record each provider's
+ * baseline (`credential.resolved`) before any story starts, which is what the
+ * guard later compares against. They happen before, and outside, the ambient
+ * sweep's race below, so a helper slower than the sweep's timeout is still
+ * asked — and they are issued as one batch, so N helper-served providers cost
+ * the slowest helper rather than the sum of all of them.
+ */
+export async function providersWithoutCredentials(providerIds) {
+    const unique = [...new Set(providerIds)];
+    const store = naxCredentialStore();
+    const stored = new Set();
+    // `allSettled`, not `all`: a rejection here is fatal for the run, and `all`
+    // would return the moment the first one failed while every sibling read kept
+    // going — leaving up to N-1 helper subprocesses alive for their own full
+    // timeout, still writing `credential.resolved` entries and guard baselines for
+    // a caller that has already thrown. Settling first costs nothing on the happy
+    // path (it is one batch either way) and makes the failure path clean.
+    // (These reads sit outside the ambient race below on purpose — a helper slower
+    // than AMBIENT_PROBE_TIMEOUT_MS is still asked.)
+    const served = await Promise.allSettled(unique.map(async (providerId) => ({ providerId, credential: await store.read(providerId) })));
+    for (const outcome of served) {
+        if (outcome.status === "rejected") {
+            // A damaged credential file stays "unknown", which is the behaviour this
+            // check has always had: reporting the provider missing would look exactly
+            // like "you have no credentials" for a file that is merely unreadable.
+            if (outcome.reason instanceof NaxError && outcome.reason.code === "CREDENTIAL_FILE_UNREADABLE")
+                return [];
+            throw outcome.reason;
+        }
+        if (outcome.value.credential !== undefined)
+            stored.add(outcome.value.providerId);
+    }
+    const sweep = Promise.all(unique
+        .filter((providerId) => !stored.has(providerId))
+        .map(async (providerId) => {
+        try {
+            return (await _authDeps.ambientAuthAvailable(providerId)) ? undefined : providerId;
+        }
+        catch {
+            return undefined;
+        }
+    })).then((missing) => missing.filter((id) => id !== undefined));
+    let timer;
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => resolve([]), AMBIENT_PROBE_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([sweep, expiry]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * How long the whole ambient sweep may take before it gives up and reports
+ * "credentialed".
+ *
+ * Measured today the sweep is ~17ms: the catalog is memoised upstream after a
+ * ~15ms first load, and 39 ambient probes take ~2ms because no bundled pi
+ * provider defines check() and every resolve() reads environment variables and
+ * credential files only. That is a snapshot, not a guarantee — pi's own
+ * contract warns resolve() "may execute commands", and sweeping the catalog
+ * amplifies that across every provider.
+ */
+const AMBIENT_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * Is ANY provider satisfied by ambient auth alone?
+ *
+ * Deliberately not "is provider X satisfied": the caller
+ * (NativeAgentAdapter.hasCredentials) has no provider to ask about, because
+ * the model — and so the provider — is chosen per request.
+ *
+ * Expiry resolves TRUE, not false. Pruning an agent that would have worked
+ * kills a run; reporting one that cannot authenticate costs a single
+ * request-time auth error that is already mapped and handled. Where this
+ * cannot answer, it must not guess "no".
+ */
+export async function anyAmbientCredential() {
+    let timer;
+    const sweep = (async () => {
+        const ids = await _authDeps.providerIds();
+        if (ids.length === 0)
+            return false;
+        // Resolve on the first success rather than awaiting every probe, so one
+        // satisfied provider does not wait behind a slow one.
+        return new Promise((resolve) => {
+            let outstanding = ids.length;
+            const settleOne = (satisfied) => {
+                if (satisfied)
+                    resolve(true);
+                else if (--outstanding === 0)
+                    resolve(false);
+            };
+            for (const id of ids) {
+                _authDeps.ambientAuthAvailable(id).then((ok) => settleOne(ok), 
+                // A probe that throws is not a satisfied provider. It is also not a
+                // reason to fail the sweep: the other providers still count.
+                () => settleOne(false));
+            }
+        });
+    })();
+    const expiry = new Promise((resolve) => {
+        timer = _authDeps.setTimeout(() => resolve(true), AMBIENT_PROBE_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([sweep, expiry]);
+    }
+    finally {
+        if (timer !== undefined)
+            _authDeps.clearTimeout(timer);
+    }
+}

package/dist/native/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The nax-ai client, built once per process.
+ *
+ * defaultProviders() loads nax-ai's bundled catalog (~1290 models), so building per
+ * call would pay that cost on every completion. The build is memoised, but a
+ * FAILED build is not: a transient failure must not poison the process.
+ *
+ * This file and its siblings are the only place in src/ permitted to import
+ * nax-ai (packages/repo-tooling/scripts/check-nax-ai-imports.ts).
+ */
+import { type Client, defaultProtocols } from "@nathapp/nax-ai";
+import type { ProviderCatalogOverride } from "#src/config/catalog-overrides";
+/** The catalog overrides a native client is built with (`agent.native.catalogOverrides`). */
+export type NativeCatalogOverrides = readonly ProviderCatalogOverride[];
+/**
+ * Options for `buildNativeClient`. Production callers leave this empty —
+ * every field has a sensible nax-ai default. The seam exists so tests can
+ * opt out of paths the production retry policy was never meant to exercise.
+ */
+export interface BuildNativeClientOptions {
+    /**
+     * Transport-fault retry budget (nax-ai's `ClientOptions.transportRetries`,
+     * default 2). Tests that want a single attempt pass `0`; the production
+     * 2-retry schedule sleeps through 250ms + 500ms of backoff on the first
+     * thrown "Provider is not configured" / 5xx, which is most of the wall-clock
+     * in tests that intentionally fail at the protocol boundary.
+     */
+    readonly transportRetries?: number;
+}
+/**
+ * The real builder. Exported on its own — not just as `_clientDeps.build` —
+ * because test/preload.ts overwrites `_clientDeps.build` with a sentinel
+ * before any test file loads (to stop a real client leaking into the
+ * module-level cache across files), which would otherwise make this
+ * synchronous, no-network construction path uncoverable by any test.
+ */
+export declare function buildNativeClient(catalogOverrides?: readonly ProviderCatalogOverride[], options?: BuildNativeClientOptions): Promise<Client>;
+/**
+ * Test seam. `build` is replaced in tests so no catalog is loaded and no
+ * network is reached. `defaultProtocols` is separately injectable so a test can
+ * observe what buildNativeClient passes it (the credentials wiring above)
+ * without loading the real catalog — see client.test.ts.
+ */
+export declare const _clientDeps: {
+    build: typeof buildNativeClient;
+    defaultProtocols: typeof defaultProtocols;
+};
+export declare function getNativeClient(catalogOverrides?: NativeCatalogOverrides): Promise<Client>;
+/** Clears the memo. Tests only. */
+export declare function _resetNativeClient(): void;

package/dist/native/client.js

@@ -0,0 +1,174 @@
+/**
+ * The nax-ai client, built once per process.
+ *
+ * defaultProviders() loads nax-ai's bundled catalog (~1290 models), so building per
+ * call would pay that cost on every completion. The build is memoised, but a
+ * FAILED build is not: a transient failure must not poison the process.
+ *
+ * This file and its siblings are the only place in src/ permitted to import
+ * nax-ai (packages/repo-tooling/scripts/check-nax-ai-imports.ts).
+ */
+import { createHash } from "node:crypto";
+import { createClient, defaultProtocols, defaultProviders } from "@nathapp/nax-ai";
+import { NaxError } from "#src/infra/index";
+import { byCodePoint } from "#src/internal/sort";
+import { naxCredentialStore } from "./credentials/index.js";
+import { toProviderOverrides } from "./models.js";
+/**
+ * How nax names itself to a provider that reports on the calling application.
+ *
+ * nax-ai owns which vendor spells this in which header — OpenRouter reads
+ * `HTTP-Referer` and `X-Title` into the `app_id`, `origin` and `http_referer`
+ * fields of every generation record — and nax owns only the identity. Without
+ * it, the sole identifying header on the wire is pi-ai's hardcoded
+ * `User-Agent: pi (<platform> <release>; <arch>)`, which every pi-ai consumer
+ * sends, so nax traffic cannot be told apart from anything else in the provider
+ * account paying for it.
+ *
+ * A literal rather than a read of package.json: the bundle is built with
+ * `bun build --target bun` and does not carry a package.json to read at
+ * runtime. No version in the name — a display name that changed every release
+ * would split one application into many rows on a provider's dashboard.
+ */
+const NAX_CLIENT_APP = { name: "nax", url: "https://github.com/nathapp-io/nax" };
+/**
+ * The real builder. Exported on its own — not just as `_clientDeps.build` —
+ * because test/preload.ts overwrites `_clientDeps.build` with a sentinel
+ * before any test file loads (to stop a real client leaking into the
+ * module-level cache across files), which would otherwise make this
+ * synchronous, no-network construction path uncoverable by any test.
+ */
+export async function buildNativeClient(catalogOverrides = [], options = {}) {
+    return createClient({
+        providers: await defaultProviders(),
+        // The factory form, not the entries form: nax-ai has TWO catalogs — the
+        // client's, which `model()` and `pricing()` read, and the protocol layer's,
+        // which request-time resolution reads — and an override has to reach both.
+        // Entries built without it reproduce #1982 exactly: the model resolves and
+        // prices happily, then throws `Unknown model ... in the pi-ai catalog` on
+        // the first real request. createClient hands the factory the array it was
+        // constructed with, so the two sides cannot disagree — and nax-ai 0.1.11
+        // rejects at construction a client whose entries never heard about an
+        // override the client itself declared (nax-ai#36).
+        protocols: ({ providerOverrides }) => _clientDeps.defaultProtocols({
+            // The credential seam: pi resolves the store first, then ambient sources
+            // (env vars, AWS profiles, ADC), so a stored credential owns its provider
+            // and CI with only an environment variable keeps working. Passing it here
+            // is what makes `nax auth login` reach a run. This is the only inlet:
+            // ClientOptions once carried a `credentials` field that createClient
+            // never read, and nax-ai 0.1.4 removed it for exactly that reason.
+            credentials: naxCredentialStore(),
+            // Construction-time, like `credentials`: the identity is a constant of
+            // the process, so nax-ai takes it here rather than on every request.
+            clientApp: NAX_CLIENT_APP,
+            providerOverrides,
+        }),
+        // nax-ai applies these last (`normaliseCatalog`), replacing any bundled
+        // entry with the same id and lazily creating the provider bucket when the
+        // id is unknown to pi-ai — that is what makes a model newer than the
+        // snapshot resolvable (#1982). Omitted entirely when empty so the
+        // no-override path stays byte-identical to before.
+        ...(catalogOverrides.length > 0 ? { providerOverrides: toProviderOverrides(catalogOverrides) } : {}),
+        // nax-ai defaults `transportRetries` to 2 (250ms + 500ms backoff).
+        // Passed through verbatim when the caller asks, omitted when it doesn't,
+        // so the production path stays byte-identical to before this seam.
+        ...(options.transportRetries !== undefined ? { transportRetries: options.transportRetries } : {}),
+    });
+}
+/**
+ * Test seam. `build` is replaced in tests so no catalog is loaded and no
+ * network is reached. `defaultProtocols` is separately injectable so a test can
+ * observe what buildNativeClient passes it (the credentials wiring above)
+ * without loading the real catalog — see client.test.ts.
+ */
+export const _clientDeps = {
+    build: buildNativeClient,
+    defaultProtocols,
+};
+/**
+ * Recursively rebuild plain objects with keys sorted by code point. Array
+ * order is preserved — model lists keep their declared order because nax-ai
+ * replaces entries by id and a duplicate id is last-wins. Built with
+ * `Object.fromEntries` (not key assignment) so a header literally named
+ * `__proto__` survives as an own property instead of being swallowed by the
+ * prototype setter.
+ */
+function canonicalise(value) {
+    if (Array.isArray(value))
+        return value.map((item) => canonicalise(item));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => byCodePoint(a, b))
+            .map(([key, val]) => [key, canonicalise(val)]));
+    }
+    return value;
+}
+/**
+ * Deterministic serialisation of an override set (nax#2025): overrides sorted
+ * by provider and object keys sorted by code point (`byCodePoint`, per CTX-5 —
+ * the ordering feeds both the cache key and the digest, so it must be stable
+ * across locales and ICU versions), so two sets that differ only in listing
+ * order or header key order — semantically identical on the nax-ai side —
+ * serialise identically. Two overrides with the SAME provider keep their
+ * declared order: duplicate providers are last-wins by design, so their
+ * relative order is part of the semantics.
+ */
+function canonicalOverrideKey(overrides) {
+    const sorted = [...overrides].sort((a, b) => byCodePoint(a.provider, b.provider));
+    return JSON.stringify(canonicalise(sorted));
+}
+/** Hex prefix length of the set digest used in error summaries. */
+const DIGEST_LENGTH = 12;
+/**
+ * Secret-free summary of an override set for error context: provider names,
+ * header key NAMES (never values — an `Authorization` header is a credential,
+ * nax#2025), and a digest of the canonical key so sets that differ only in
+ * redacted material stay distinguishable.
+ *
+ * The digest is an IDENTIFIER, not a security boundary: it hashes the raw
+ * canonical key, so it must only ever appear next to the sanitised summary —
+ * never logged beside the redacted-but-inferable override set.
+ */
+function summariseOverrides(overrides) {
+    return {
+        providers: overrides.map((o) => o.provider).sort(),
+        headerKeys: [...new Set(overrides.flatMap((o) => Object.keys(o.headers ?? {})))].sort(),
+        digest: createHash("sha256").update(canonicalOverrideKey(overrides)).digest("hex").slice(0, DIGEST_LENGTH),
+    };
+}
+let cached;
+/** Override set the cached build was created for — kept for secret-free summarising. */
+let cachedOverrides;
+/** Serialised override set the cached build was created for. */
+let cachedOverridesKey;
+export async function getNativeClient(catalogOverrides = []) {
+    const overridesKey = canonicalOverrideKey(catalogOverrides);
+    if (cached !== undefined && overridesKey !== cachedOverridesKey) {
+        // The client is a constant of the process (catalog load is ~50ms / ~650KB),
+        // so overrides must be collected into ONE set before the first build. A
+        // silent second build would swap the client under in-flight sessions.
+        throw new NaxError("The native client was already built for a different catalog-override set. " +
+            "Collect every override into one agent.native.catalogOverrides list instead of varying them per call.", "NATIVE_CLIENT_OVERRIDES_MISMATCH", { builtFor: summariseOverrides(cachedOverrides ?? []), requested: summariseOverrides(catalogOverrides) });
+    }
+    if (cached === undefined) {
+        // Shallow copy: the caller's array may later be mutated (e.g. a push), which
+        // would mislabel `builtFor` — the summary must describe the set that was built.
+        cachedOverrides = [...catalogOverrides];
+        cachedOverridesKey = overridesKey;
+        // Cache the promise, not the value, so concurrent callers share one build.
+        // Drop it on rejection: a failed catalog load should not be permanent.
+        cached = _clientDeps.build(catalogOverrides).catch((err) => {
+            cached = undefined;
+            cachedOverrides = undefined;
+            cachedOverridesKey = undefined;
+            throw err;
+        });
+    }
+    return cached;
+}
+/** Clears the memo. Tests only. */
+export function _resetNativeClient() {
+    cached = undefined;
+    cachedOverrides = undefined;
+    cachedOverridesKey = undefined;
+}

package/dist/native/complete.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One-shot completion over nax-ai, with no session (S1 port 2). Package-owned
+ * options: the caller passes a `SessionModel` whose pricing is already in the
+ * standard vocabulary, and the per-adapter one-shot session key.
+ */
+import type { AdapterFailure } from "#src/session/adapter-failure";
+import type { AuthStamp, SessionModel } from "#src/session/session-types";
+import type { PricingRates, TokenUsage } from "../cost/standard-types.ts";
+import { type NativeCatalogOverrides } from "./client.ts";
+export interface NativeCompleteOptions {
+    readonly model: SessionModel;
+    readonly maxTokens?: number;
+    readonly timeoutMs?: number;
+}
+export interface NativeCompleteContext {
+    readonly catalogOverrides: NativeCatalogOverrides;
+    /**
+     * The caller's one-shot session key (`newSessionKey()`), held per adapter
+     * instance so a run's one-shots share a backend and keep a cache warm.
+     */
+    readonly sessionKey: string;
+}
+export interface NativeCompleteResult {
+    output: string;
+    tokenUsage: TokenUsage;
+    estimatedCostUsd: number;
+    sessionId?: string;
+    pricingSource?: "catalog-rates" | "config-override";
+    rates?: PricingRates;
+    auth?: AuthStamp;
+    adapterFailure?: AdapterFailure;
+}
+export declare function nativeComplete(prompt: string, options: NativeCompleteOptions, context: NativeCompleteContext): Promise<NativeCompleteResult>;