@nathapp/nax-agent 0.1.0

package/dist/native/complete.js

@@ -0,0 +1,88 @@
+/**
+ * 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 { priceCall } from "#src/cost/core/index";
+import { _adapterDeps, authFields, isProtocolStreamError } from "./adapter-deps.js";
+import { getNativeClient } from "./client.js";
+import { toAdapterFailure } from "./errors.js";
+import { buildRateCard, parseNativeModel, toThinkingLevel } from "./models.js";
+import { nativeSessionId } from "./session-affinity.js";
+export async function nativeComplete(prompt, options, context) {
+    // modelDef.provider is deliberately ignored. resolveModel() INFERS it from
+    // the model name for string entries ("claude..." -> anthropic, else
+    // "unknown"), so it is a guess rather than configuration — and routing a
+    // billed call on a guess is what the protocol gate exists to prevent. The
+    // string is the only source of truth.
+    const { provider, model, effort } = parseNativeModel(options.model.model);
+    const thinking = toThinkingLevel(effort);
+    const client = await getNativeClient(context.catalogOverrides);
+    const resolved = await client.model(provider, model);
+    const controller = new AbortController();
+    const timer = options.timeoutMs !== undefined ? _adapterDeps.setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+        const sessionId = nativeSessionId(context.sessionKey);
+        const result = await client.complete(resolved, {
+            messages: [{ role: "user", content: prompt }],
+            ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+            sessionId,
+            signal: controller.signal,
+            ...(thinking !== undefined ? { thinking } : {}),
+        });
+        const tokenUsage = result.usage;
+        const catalog = client.pricing(resolved);
+        const { rates, source: pricingSource } = buildRateCard(catalog, options.model.pricing);
+        // US-002: stamp the effective `priceCall`-resolved rates so the cost
+        // subscriber can record the same numbers whose arithmetic reproduces
+        // `estimatedCostUsd`. The native path prices unconditionally — even
+        // a zero-token call carries `rates`, so a downstream cost row never
+        // has to guess what priced a no-spend dispatch.
+        //
+        // Single `priceCall` invocation: `costUsd` and `resolvedRates` come
+        // from the same call so they cannot diverge — the verifiability
+        // property the story names ("recorded rates reproduce recorded cost")
+        // would silently break if tier selection ever grew a side channel.
+        const { costUsd: estimatedCostUsd, resolvedRates } = priceCall(tokenUsage, rates);
+        return {
+            output: result.text,
+            tokenUsage,
+            estimatedCostUsd,
+            // exactCostUsd is deliberately unset: nax-ai supplies rates and
+            // computes no cost, so nothing here is exact.
+            // sessionId echoes the one we sent — US-002 lets downstream wiring
+            // (audit, dispatch) stamp it on artifacts without reaching into a
+            // private field.
+            sessionId,
+            // US-003: stamp the branch buildRateCard took so cost rows can tell a
+            // catalog-priced call from a config-overridden one. Single source of
+            // truth — the same override !== undefined predicate the rate card was
+            // chosen on, reported rather than re-derived by the cost subscriber.
+            pricingSource,
+            // US-002: the four per-1M rates that priced this call. See
+            // NativeCompleteResult.rates above.
+            rates: resolvedRates,
+            // US-006: the credential identity the store observed while serving
+            // this call. Absent (not undefined) when it observed nothing.
+            ...authFields(provider),
+        };
+    }
+    catch (err) {
+        // Returned, not rethrown: rethrowing routes through
+        // classifyCompleteException -> parseAgentError, which parses ACP strings
+        // and would discard the typed kind nax-ai just gave us.
+        if (isProtocolStreamError(err)) {
+            return {
+                output: "",
+                tokenUsage: { inputTokens: 0, outputTokens: 0 },
+                estimatedCostUsd: 0,
+                adapterFailure: toAdapterFailure(err.protocolError),
+            };
+        }
+        throw err;
+    }
+    finally {
+        if (timer !== undefined)
+            _adapterDeps.clearTimeout(timer);
+    }
+}

package/dist/native/credentials/chained-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The chained credential store (US-004).
+ *
+ * nax-ai's file store re-reads `~/.nax/credentials` on every read, so a silent
+ * mid-run change can split billing across accounts. This is the seam that
+ * decides which source serves a provider — the exec helper first when one is
+ * configured, the file store otherwise — and remembers, per provider, which one
+ * answered.
+ *
+ * The memory matters because a provider the helper served is the helper's to
+ * manage: writing it to the file store would split one credential across two
+ * stores, and OAuth refresh must keep going through the file store so its
+ * cross-process lock and write-back still apply.
+ */
+import type { CredentialStore, ProviderId } from "@nathapp/nax-ai";
+import type { ExecCredentialSource } from "./exec-source.ts";
+/** The store the run is assembled around: a chain, plus where each provider came from. */
+export interface ChainedCredentialStore extends CredentialStore {
+    /** Which store last served `providerId`, or `undefined` if it was never read. */
+    sourceOf(providerId: ProviderId): "exec" | "file" | undefined;
+    /** The account label the exec source reported for `providerId`, if it served it. */
+    accountOf(providerId: ProviderId): string | undefined;
+}
+export interface ChainedCredentialStoreOptions {
+    /** Tried first, when configured. A decline falls through to the file store. */
+    readonly exec?: ExecCredentialSource;
+    /** The store `~/.nax/credentials` back, and the only one that can be written. */
+    readonly file: CredentialStore;
+}
+export declare function createChainedCredentialStore(options: ChainedCredentialStoreOptions): ChainedCredentialStore;

package/dist/native/credentials/chained-store.js

@@ -0,0 +1,68 @@
+/**
+ * The chained credential store (US-004).
+ *
+ * nax-ai's file store re-reads `~/.nax/credentials` on every read, so a silent
+ * mid-run change can split billing across accounts. This is the seam that
+ * decides which source serves a provider — the exec helper first when one is
+ * configured, the file store otherwise — and remembers, per provider, which one
+ * answered.
+ *
+ * The memory matters because a provider the helper served is the helper's to
+ * manage: writing it to the file store would split one credential across two
+ * stores, and OAuth refresh must keep going through the file store so its
+ * cross-process lock and write-back still apply.
+ */
+import { NaxError } from "#src/infra/index";
+export function createChainedCredentialStore(options) {
+    /** Providers this process has read, and the source that answered. */
+    const served = new Map();
+    /** The refusal for a write against a provider the helper owns. */
+    function managedByHelper(providerId, operation) {
+        return new NaxError(`[credentials] Cannot ${operation} the credential for ${providerId}: the exec helper owns it.`, "CREDENTIAL_MANAGED_BY_HELPER", { stage: "credentials", providerId, operation });
+    }
+    /** Read the file store, reporting a failure under one code. */
+    async function readFileStore(providerId) {
+        try {
+            return await options.file.read(providerId);
+        }
+        catch (cause) {
+            const error = new NaxError(`[credentials] The credential file could not be read for ${providerId}.`, "CREDENTIAL_FILE_UNREADABLE", { stage: "credentials", providerId, cause });
+            // Also on the error itself: `context.cause` is where nax puts a cause, and
+            // `Error.cause` is what a generic cause-chain walk (nax-ai's ProtocolError,
+            // the credential-fault classifier) reads. Both spellings, one error.
+            error.cause = cause;
+            throw error;
+        }
+    }
+    return {
+        async read(providerId) {
+            if (options.exec !== undefined) {
+                const credential = await options.exec.read(providerId);
+                if (credential !== undefined) {
+                    served.set(providerId, "exec");
+                    return credential;
+                }
+            }
+            const credential = await readFileStore(providerId);
+            // Recorded even when the file store held nothing: the decline is what
+            // makes the file store this provider's source for the process's lifetime.
+            served.set(providerId, "file");
+            return credential;
+        },
+        // Both refusals are synchronous throws, not rejections: the store is asked
+        // to write and answers "no" without doing anything, and a caller that only
+        // holds the returned promise would otherwise see an unhandled rejection.
+        modify(providerId, fn) {
+            if (served.get(providerId) === "exec")
+                throw managedByHelper(providerId, "modify");
+            return options.file.modify(providerId, fn);
+        },
+        delete(providerId) {
+            if (served.get(providerId) === "exec")
+                throw managedByHelper(providerId, "delete");
+            return options.file.delete(providerId);
+        },
+        sourceOf: (providerId) => served.get(providerId),
+        accountOf: (providerId) => (served.get(providerId) === "exec" ? options.exec?.accountOf(providerId) : undefined),
+    };
+}

package/dist/native/credentials/change-guard.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Credential change guard (US-002).
+ *
+ * A running nax re-reads `~/.nax/credentials` on every LLM request, so one
+ * story can be billed to two accounts with nothing in the run log to show it.
+ * The guard observes each read, compares the credential's identity with the one
+ * it last served, and either warns or refuses — never logging the credential
+ * itself, and never comparing the volatile parts of an OAuth credential.
+ *
+ * `read` is the only method wrapped. `modify` and `delete` pass straight
+ * through: a write is not a change of who is being billed.
+ */
+import type { CredentialStore, ProviderId } from "@nathapp/nax-ai";
+import type { CredentialAuthConfig } from "#src/infra/index";
+import type { AuthStamp } from "#src/session/session-types";
+/**
+ * Where a credential came from, as reported by `describe`. `AuthStamp` without
+ * the fingerprint — the guard computes that itself from the credential.
+ */
+export interface CredentialOrigin {
+    source: "file" | "exec";
+    account?: string;
+}
+export interface ChangeGuardOptions {
+    /** `warn` adopts the new identity and serves it; `refuse` throws instead. */
+    onChange: CredentialAuthConfig["onChange"];
+    /**
+     * Where the credential read from `inner` came from. Called immediately after
+     * each successful read, because the credential itself carries no provenance.
+     * `undefined` means the source could not be described — recorded as `file`.
+     */
+    describe(providerId: ProviderId): CredentialOrigin | undefined;
+}
+/** The credential store, with the identity of whatever it last served. */
+export interface GuardedCredentialStore extends CredentialStore {
+    /**
+     * The last identity observed for `providerId`, or `undefined` if it was never
+     * read. Updated on every read, including one that logged nothing because the
+     * fingerprint was unchanged.
+     */
+    servedAuth(providerId: ProviderId): AuthStamp | undefined;
+}
+/**
+ * Wrap `inner` in a change guard.
+ *
+ * The guard keeps one identity per provider for the life of the process. Under
+ * `onChange: "refuse"` a changed credential is never adopted, so the provider
+ * stays refused until the credential is restored — every later read refuses too,
+ * which is the point: the run must not quietly continue on a different account.
+ */
+export declare function createChangeGuard(inner: CredentialStore, options: ChangeGuardOptions): GuardedCredentialStore;

package/dist/native/credentials/change-guard.js

@@ -0,0 +1,136 @@
+/**
+ * Credential change guard (US-002).
+ *
+ * A running nax re-reads `~/.nax/credentials` on every LLM request, so one
+ * story can be billed to two accounts with nothing in the run log to show it.
+ * The guard observes each read, compares the credential's identity with the one
+ * it last served, and either warns or refuses — never logging the credential
+ * itself, and never comparing the volatile parts of an OAuth credential.
+ *
+ * `read` is the only method wrapped. `modify` and `delete` pass straight
+ * through: a write is not a change of who is being billed.
+ */
+import { getSafeLogger, NaxError } from "#src/infra/index";
+import { fingerprintCredential } from "./fingerprint.js";
+/**
+ * `api-key` → `api-key`, both carrying an account label, different labels: a
+ * different account is serving the same provider, whichever way the key moved.
+ */
+function accountLabelChanged(previous, next) {
+    return (previous.kind === "api-key" &&
+        next.kind === "api-key" &&
+        previous.account !== undefined &&
+        next.account !== undefined &&
+        previous.account !== next.account);
+}
+/**
+ * Classify a read against the stored identity.
+ *
+ * `renewed` is the "this is routine" verdict: an OAuth refresh-token rotation,
+ * which any nax process on the machine produces, or a rotating `api-key` whose
+ * account label is unchanged (the exec helper hands out short-lived keys). It is
+ * deliberately not a change — refusing it would break normal operation.
+ */
+function classify(previous, next) {
+    if (accountLabelChanged(previous, next))
+        return "changed";
+    if (previous.fingerprint === next.fingerprint)
+        return "same";
+    if (previous.kind !== next.kind)
+        return "changed";
+    if (next.kind === "oauth")
+        return "renewed";
+    if (previous.account !== undefined && next.account !== undefined)
+        return "renewed";
+    return "changed";
+}
+/** The identity fields every credential event carries. */
+function identityData(providerId, identity) {
+    return {
+        providerId,
+        kind: identity.kind,
+        source: identity.source,
+        fingerprint: identity.fingerprint,
+        ...(identity.account !== undefined ? { account: identity.account } : {}),
+    };
+}
+/** The identity fields plus what it replaced — for `changed` and `renewed`. */
+function replacementData(providerId, identity, previous) {
+    return {
+        ...identityData(providerId, identity),
+        previousFingerprint: previous.fingerprint,
+        ...(previous.account !== undefined ? { previousAccount: previous.account } : {}),
+    };
+}
+function toStamp(identity) {
+    return {
+        fingerprint: identity.fingerprint,
+        source: identity.source,
+        ...(identity.account !== undefined ? { account: identity.account } : {}),
+    };
+}
+/**
+ * Wrap `inner` in a change guard.
+ *
+ * The guard keeps one identity per provider for the life of the process. Under
+ * `onChange: "refuse"` a changed credential is never adopted, so the provider
+ * stays refused until the credential is restored — every later read refuses too,
+ * which is the point: the run must not quietly continue on a different account.
+ */
+export function createChangeGuard(inner, options) {
+    const identities = new Map();
+    async function read(providerId) {
+        const credential = await inner.read(providerId);
+        // An absent credential says nothing about identity; leave the stored one be.
+        if (credential === undefined)
+            return undefined;
+        const described = options.describe(providerId);
+        const identity = {
+            kind: credential.kind,
+            fingerprint: await fingerprintCredential(credential),
+            source: described?.source ?? "file",
+            ...(described?.account !== undefined ? { account: described.account } : {}),
+        };
+        const previous = identities.get(providerId);
+        if (previous === undefined) {
+            getSafeLogger()?.info("credentials", "credential.resolved", identityData(providerId, identity));
+            identities.set(providerId, identity);
+            return credential;
+        }
+        const verdict = classify(previous, identity);
+        if (verdict === "renewed") {
+            getSafeLogger()?.info("credentials", "credential.renewed", replacementData(providerId, identity, previous));
+        }
+        else if (verdict === "changed") {
+            getSafeLogger()?.warn("credentials", "credential.changed", {
+                ...replacementData(providerId, identity, previous),
+                onChange: options.onChange,
+            });
+            if (options.onChange === "refuse") {
+                throw new NaxError(`[credentials] Credential for ${providerId} changed from ${previous.fingerprint} to ${identity.fingerprint}`, "CREDENTIAL_CHANGED", {
+                    stage: "credentials",
+                    providerId,
+                    kind: identity.kind,
+                    source: identity.source,
+                    fingerprint: identity.fingerprint,
+                    previousFingerprint: previous.fingerprint,
+                });
+            }
+        }
+        // Adopt what this read observed even when nothing was logged: an identical
+        // fingerprint can still arrive from a different source or account label, and
+        // servedAuth promises the *last observed* identity, not the first. A refused
+        // change never reaches here, which is what keeps the provider refused.
+        identities.set(providerId, identity);
+        return credential;
+    }
+    return {
+        read,
+        modify: (providerId, fn) => inner.modify(providerId, fn),
+        delete: (providerId) => inner.delete(providerId),
+        servedAuth: (providerId) => {
+            const identity = identities.get(providerId);
+            return identity === undefined ? undefined : toStamp(identity);
+        },
+    };
+}

package/dist/native/credentials/exec-source.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Exec credential source (US-003).
+ *
+ * Credentials can come from a helper process instead of the credential file. The
+ * helper is a public contract, because koda depends on it:
+ *
+ *   invocation  argv `[...command, "get"]`, no shell, stdin a pipe, nax's
+ *               environment inherited (as git credential helpers do)
+ *   request     one JSON line on stdin, then stdin is closed:
+ *               `{"version":1,"providerId":"anthropic"}`
+ *   credential  exit 0, stdout `{"version":1,"kind":"api-key","key":"…",
+ *               "expiresAt":…,"account":"…"}` — the last two optional
+ *   decline     exit 0, stdout `{"version":1,"decline":true}` — "not mine"
+ *   failure     non-zero exit, timeout, spawn error → CREDENTIAL_HELPER_FAILED
+ *               a malformed reply → CREDENTIAL_HELPER_INVALID
+ *
+ * The wire contract lives in helper-protocol.ts, the process boundary (spawn,
+ * bounded streams, both kill switches) in helper-process.ts; this module is the
+ * part that caches leases, decides freshness, falls back to the last good lease,
+ * and never logs the key.
+ *
+ * `modify` and `delete` throw: the helper owns the credential. US-003 refuses a
+ * provider that switches source mid-process rather than supporting it, so a
+ * decline for a provider that already holds a lease is invalid, not a fallback.
+ */
+import type { CredentialStore, ProviderId } from "@nathapp/nax-ai";
+export { AUTH_HELPER_STDERR_MAX_BYTES, AUTH_HELPER_STDOUT_MAX_BYTES } from "./helper-process.ts";
+/**
+ * A lease closer to expiry than this is accepted but never fresh: the next read
+ * spawns the helper again, so a run cannot be left holding a key that expires
+ * mid-call. Not configurable (US-003 scope).
+ */
+export declare const LEASE_FRESHNESS_MS = 60000;
+export interface ExecCredentialSourceOptions {
+    /** The helper executable, plus any leading argv. `"get"` is appended per call. */
+    readonly command: readonly string[];
+    /** Hard deadline for one helper call. Defaults to the config schema's 10s. */
+    readonly timeoutMs?: number;
+    /** Clock for lease expiry. Defaults to `Date.now`; tests inject one instead of waiting out a lease. */
+    readonly now?: () => number;
+}
+/**
+ * The exec source as the store seam sees it. `accountOf` exposes the current
+ * lease's non-secret account label separately, because `read` may only return
+ * the `{ kind, key }` shape nax-ai's `StoredCredential` allows.
+ */
+export interface ExecCredentialSource extends CredentialStore {
+    accountOf(providerId: ProviderId): string | undefined;
+}
+export declare function createExecCredentialSource(options: ExecCredentialSourceOptions): ExecCredentialSource;

package/dist/native/credentials/exec-source.js

@@ -0,0 +1,222 @@
+/**
+ * Exec credential source (US-003).
+ *
+ * Credentials can come from a helper process instead of the credential file. The
+ * helper is a public contract, because koda depends on it:
+ *
+ *   invocation  argv `[...command, "get"]`, no shell, stdin a pipe, nax's
+ *               environment inherited (as git credential helpers do)
+ *   request     one JSON line on stdin, then stdin is closed:
+ *               `{"version":1,"providerId":"anthropic"}`
+ *   credential  exit 0, stdout `{"version":1,"kind":"api-key","key":"…",
+ *               "expiresAt":…,"account":"…"}` — the last two optional
+ *   decline     exit 0, stdout `{"version":1,"decline":true}` — "not mine"
+ *   failure     non-zero exit, timeout, spawn error → CREDENTIAL_HELPER_FAILED
+ *               a malformed reply → CREDENTIAL_HELPER_INVALID
+ *
+ * The wire contract lives in helper-protocol.ts, the process boundary (spawn,
+ * bounded streams, both kill switches) in helper-process.ts; this module is the
+ * part that caches leases, decides freshness, falls back to the last good lease,
+ * and never logs the key.
+ *
+ * `modify` and `delete` throw: the helper owns the credential. US-003 refuses a
+ * provider that switches source mid-process rather than supporting it, so a
+ * decline for a provider that already holds a lease is invalid, not a fallback.
+ */
+import { getSafeLogger, NaxError } from "#src/infra/index";
+import { runHelper } from "./helper-process.js";
+import { parseReply } from "./helper-protocol.js";
+export { AUTH_HELPER_STDERR_MAX_BYTES, AUTH_HELPER_STDOUT_MAX_BYTES } from "./helper-process.js";
+/**
+ * A lease closer to expiry than this is accepted but never fresh: the next read
+ * spawns the helper again, so a run cannot be left holding a key that expires
+ * mid-call. Not configurable (US-003 scope).
+ */
+export const LEASE_FRESHNESS_MS = 60_000;
+/** Mirrors AuthConfigSchema's `auth.exec.timeoutMs` default; this module is not config-aware. */
+const DEFAULT_HELPER_TIMEOUT_MS = 10_000;
+/** A failure outcome, with the code it is reported under. */
+function failureOf(code, parts) {
+    return { kind: "failure", failure: { code, ...parts } };
+}
+/**
+ * Translate what the process boundary saw into a helper outcome.
+ *
+ * The two kill switches do not share a code: a deadline that passed is a failed
+ * helper, while stdout past its cap is a malformed reply. Both killed the
+ * process, so its own exit code is not the verdict in either case.
+ */
+function outcomeOf(result) {
+    switch (result.kind) {
+        case "spawn-failed":
+            return failureOf("CREDENTIAL_HELPER_FAILED", {
+                detail: result.detail,
+                timedOut: false,
+                stderr: result.stderr,
+                cause: result.cause,
+            });
+        case "no-answer":
+            return failureOf("CREDENTIAL_HELPER_FAILED", {
+                detail: result.detail,
+                timedOut: false,
+                stderr: result.stderr,
+            });
+        case "timed-out":
+            return failureOf("CREDENTIAL_HELPER_FAILED", { detail: result.detail, timedOut: true, stderr: result.stderr });
+        case "stdout-over-cap":
+            return failureOf("CREDENTIAL_HELPER_INVALID", {
+                detail: result.detail,
+                timedOut: false,
+                stderr: result.stderr,
+            });
+        case "exited": {
+            if (result.exitCode !== 0) {
+                return failureOf("CREDENTIAL_HELPER_FAILED", {
+                    detail: `exited with code ${result.exitCode}`,
+                    timedOut: false,
+                    stderr: result.stderr,
+                    exitCode: result.exitCode,
+                });
+            }
+            const reply = parseReply(result.stdout);
+            if (reply.kind === "invalid") {
+                return failureOf("CREDENTIAL_HELPER_INVALID", {
+                    detail: reply.detail,
+                    timedOut: false,
+                    stderr: result.stderr,
+                });
+            }
+            return reply;
+        }
+    }
+}
+/** The message a thrown helper failure carries. */
+function failureMessage(providerId, failure) {
+    return `[credentials] The credential helper for ${providerId} ${failure.detail}`;
+}
+export function createExecCredentialSource(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_HELPER_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    /** The lease in force: what a fresh read is served from. */
+    const leases = new Map();
+    /** The last credential the helper handed out, kept for the failure branch. */
+    const lastGood = new Map();
+    /** Providers this process has already heard a decline for. */
+    const declined = new Set();
+    /** The helper call already running per provider — single-flight. */
+    const inFlight = new Map();
+    /** Providers whose current consecutive-failure streak has already been logged. */
+    const failureLogged = new Set();
+    /** Only the two fields nax-ai's StoredCredential allows; the account label travels separately. */
+    function credentialOf(lease) {
+        return { kind: "api-key", key: lease.key };
+    }
+    function isFresh(lease, now) {
+        return lease.expiresAt === undefined || lease.expiresAt - now > LEASE_FRESHNESS_MS;
+    }
+    /**
+     * The last good lease, only while it has not expired. A helper that has gone
+     * away mid-run must not leave every request using a key the provider rejects.
+     */
+    function servedLastGood(providerId, now) {
+        const lease = lastGood.get(providerId);
+        return lease?.expiresAt !== undefined && lease.expiresAt > now ? lease : undefined;
+    }
+    /**
+     * The failure branch. `credential.helper_failed` is logged once per
+     * consecutive-failure streak — a helper that keeps failing must not fill the
+     * run log, and the streak resets on the next credential it serves.
+     */
+    function handleFailure(providerId, failure) {
+        const fallback = servedLastGood(providerId, now());
+        if (!failureLogged.has(providerId)) {
+            failureLogged.add(providerId);
+            getSafeLogger()?.warn("credentials", "credential.helper_failed", {
+                providerId,
+                code: failure.code,
+                ...(failure.exitCode !== undefined ? { exitCode: failure.exitCode } : {}),
+                timedOut: failure.timedOut,
+                stderr: failure.stderr,
+                servedLastGood: fallback !== undefined,
+            });
+        }
+        if (fallback !== undefined)
+            return credentialOf(fallback);
+        throw new NaxError(failureMessage(providerId, failure), failure.code, {
+            stage: "credentials",
+            providerId,
+            timedOut: failure.timedOut,
+            ...(failure.exitCode !== undefined ? { exitCode: failure.exitCode } : {}),
+            ...(failure.cause !== undefined ? { cause: failure.cause } : {}),
+        });
+    }
+    /** Apply one helper outcome to the provider's state. */
+    function applyOutcome(providerId, outcome) {
+        if (outcome.kind === "failure")
+            return handleFailure(providerId, outcome.failure);
+        if (outcome.kind === "decline") {
+            // A provider never switches source mid-process: once it holds a lease, a
+            // decline is a contradiction, not a fallback to the file.
+            if (leases.has(providerId)) {
+                return handleFailure(providerId, {
+                    code: "CREDENTIAL_HELPER_INVALID",
+                    detail: "declined for a provider that already holds a lease",
+                    timedOut: false,
+                    stderr: "",
+                });
+            }
+            declined.add(providerId);
+            return undefined;
+        }
+        leases.set(providerId, outcome.lease);
+        lastGood.set(providerId, outcome.lease);
+        failureLogged.delete(providerId);
+        return credentialOf(outcome.lease);
+    }
+    async function callHelper(providerId) {
+        return applyOutcome(providerId, outcomeOf(await runHelper(options.command, providerId, timeoutMs)));
+    }
+    async function read(providerId) {
+        // 1. A decline this process already heard: the helper is not this
+        //    provider's source, and asking again would only spawn it anew.
+        if (declined.has(providerId))
+            return undefined;
+        // 2. A fresh lease, without spawning. A lease with no expiry never goes
+        //    stale, so the helper runs once per process for that provider.
+        const lease = leases.get(providerId);
+        if (lease !== undefined && isFresh(lease, now()))
+            return credentialOf(lease);
+        // 3. Single-flight: a second read for the same provider joins the call
+        //    already running instead of spawning a second helper.
+        const running = inFlight.get(providerId);
+        if (running !== undefined)
+            return running;
+        // 4. Spawn. The map is set before the first await, so a concurrent read
+        //    cannot miss it.
+        const pending = callHelper(providerId);
+        inFlight.set(providerId, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            if (inFlight.get(providerId) === pending)
+                inFlight.delete(providerId);
+        }
+    }
+    function managedByHelper(providerId, operation) {
+        return new NaxError(`[credentials] Cannot ${operation} the credential for ${providerId}: the exec helper owns it.`, "CREDENTIAL_MANAGED_BY_HELPER", { stage: "credentials", providerId, operation });
+    }
+    return {
+        read,
+        // Synchronous throws, not rejections: the helper owns the credential, so the
+        // refusal is the whole answer and no work is done — a caller holding only
+        // the returned promise would otherwise see an unhandled rejection.
+        modify(providerId) {
+            throw managedByHelper(providerId, "modify");
+        },
+        delete(providerId) {
+            throw managedByHelper(providerId, "delete");
+        },
+        accountOf: (providerId) => leases.get(providerId)?.account,
+    };
+}