@nathapp/nax-agent 0.1.0

package/dist/native/session/turn-result.js

@@ -0,0 +1,64 @@
+/**
+ * The turn's tail: the warnings emitted once the loop has exited, and the
+ * `TurnResult` assembled from what the loop accumulated.
+ *
+ * Extracted from `turn-loop.ts`, which keeps the `saveTranscript` call that
+ * sits between the two: a write failure there fails the turn, unlike the
+ * best-effort save in the catch, and that distinction belongs with the control
+ * flow rather than in a result builder.
+ */
+import { getSafeLogger } from "#src/infra/index";
+export function logTurnTailWarnings(args) {
+    const { sessionName, completedNormally, spinStopped, roundTrips, timedOut, spinBreaker, invalidCallHalt } = args;
+    // Parity with acp/adapter.ts:555, which warns in exactly this situation. A
+    // native turn that stops here is indistinguishable from a finished one
+    // without this line plus the `turnIncomplete` fact below.
+    if (!completedNormally) {
+        getSafeLogger()?.warn("native-adapter", "turn ended with tool calls outstanding", {
+            sessionName,
+            roundTrips,
+            timedOut,
+            ...(invalidCallHalt !== undefined ? { invalidCallBudgetExceeded: true } : {}),
+        });
+    }
+    if (spinStopped) {
+        getSafeLogger()?.error("native-adapter", "turn ended by the spin breaker", {
+            sessionName,
+            roundTrips,
+            ...spinBreaker?.summary(),
+        });
+    }
+    // nax#2200: the budget halt used to leave no trace but the generic line
+    // above, so a verifier that lost its verdict to three `refs: null` calls read
+    // as a timeout. Name the tool and the property that was rejected.
+    if (invalidCallHalt !== undefined) {
+        getSafeLogger()?.error("native-adapter", "turn ended by the invalid tool call budget", {
+            sessionName,
+            roundTrips,
+            tool: invalidCallHalt.tool,
+            property: invalidCallHalt.property,
+            expected: invalidCallHalt.expected,
+            actual: invalidCallHalt.actual,
+        });
+    }
+}
+export function buildTurnResult(args) {
+    const { output, usage, roundTrips, codingTools, codingToolsCalled, completedNormally, timedOut, spinStopped, invalidCallHalt, interactions, pricingSource, } = args;
+    const rates = usage.rates();
+    return {
+        output,
+        tokenUsage: usage.tokens(),
+        estimatedCostUsd: usage.costUsd(),
+        internalRoundTrips: roundTrips,
+        ...(codingTools.length > 0 ? { codingToolUse: { advertised: codingTools.length, called: codingToolsCalled } } : {}),
+        ...(completedNormally ? {} : { turnIncomplete: true }),
+        ...(timedOut ? { timedOut: true } : {}),
+        ...(spinStopped ? { spinStopped: true } : {}),
+        ...(invalidCallHalt !== undefined
+            ? { invalidCallBudgetExceeded: true, invalidToolCall: invalidCallHalt }
+            : {}),
+        ...(interactions.length > 0 ? { interactions } : {}),
+        ...(pricingSource !== undefined ? { pricingSource } : {}),
+        ...(rates !== undefined ? { rates } : {}),
+    };
+}

package/dist/native/session/turn-retry.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Bounded transport-fault retry for the native turn loop (nax#1870).
+ *
+ * A mid-stream provider stall (OpenRouter's "Upstream idle timeout exceeded",
+ * a bare 502/503) surfaces to `runNativeTurn` as a throw from `deps.complete`.
+ * Retrying it here is safe, and safe nowhere else:
+ *
+ * - `@nathapp/nax-ai`'s own retry (protocols/retry.ts, same repo family as
+ *   this file — its doc comments are this file's model) is gated on
+ *   `emitted`: the moment any event is yielded, retry is off for that
+ *   attempt, because retrying past a `usage` event would double-bill. A
+ *   mid-stream stall is therefore structurally out of its reach.
+ * - A run-kind op's declarative `retry` (`sendWithParseRetry`,
+ *   src/operations/call.ts) has no try/catch around the call at all — a
+ *   transport throw propagates straight past it, untouched.
+ * - The turn loop can, cheaply: on a throw from `deps.complete`, `messages`
+ *   is unchanged (the failed response was never appended) and no tool from
+ *   that round trip has executed (tools run only after `complete` returns),
+ *   so an immediate re-issue costs one round trip against the alternative of
+ *   discarding the whole session.
+ *
+ * This is the native counterpart to `agent.acp.promptRetries`: acpx's
+ * spawned process absorbs a provider stall before nax ever observes it;
+ * native has no such process, so nax is the harness that must.
+ *
+ * Detection is structural, matching turn-loop.ts's `isContextOverflow` and
+ * adapter-deps.ts's `isProtocolStreamError`: nax-ai's error class is not
+ * importable outside src/agents/native/ (check-nax-ai-imports.ts), so only
+ * the shape — a `protocolError.kind` string — is inspected, never the class.
+ */
+/** Total call attempts including the first (2 = one retry, 3 = two retries). */
+export interface TurnRetryConfig {
+    readonly maxAttempts: number;
+    /** Base delay for exponential backoff with jitter, in ms, when the provider gives no retryAfter. */
+    readonly baseDelayMs: number;
+}
+/** The minimal shape this module reads off a thrown protocol fault. */
+interface RetryableProtocolError {
+    readonly protocolError: {
+        readonly kind: string;
+        readonly message: string;
+        /** Seconds, when the provider signals one (nax-ai types.ts ProtocolError.retryAfter). */
+        readonly retryAfter?: number;
+        readonly status?: number;
+        readonly cause?: unknown;
+    };
+}
+export declare function isRetryableTransportFault(err: unknown): err is RetryableProtocolError;
+/** Whether another attempt is allowed at all, independent of the error's kind. */
+export declare function canAttemptTurnRetry(retryIndex: number, config: TurnRetryConfig): boolean;
+/**
+ * How long to wait before the next attempt. The provider's own `retryAfter`
+ * wins when set — it knows its own recovery time better than a guessed
+ * backoff does — otherwise equal-jitter exponential backoff from
+ * `baseDelayMs`.
+ *
+ * `remainingMs` caps whatever that produces. A 503 can advertise a recovery
+ * window far longer than the turn has left, and sleeping it out would spend
+ * wall clock the budget has already declared gone — the attempt after it
+ * aborts immediately anyway, because TurnDeadline.remainingMs() clamps to 0
+ * and session-adapter.ts arms the call's AbortController with it. Absent means
+ * the turn is unbounded (TurnDeadline's UNBOUNDED), so nothing caps the wait.
+ */
+export declare function turnRetryDelayMs(err: RetryableProtocolError, retryIndex: number, config: TurnRetryConfig, random?: () => number, remainingMs?: number): number;
+/**
+ * Whether the wait is worth taking at all.
+ *
+ * turnRetryDelayMs clamps to `remainingMs`, which alone produces the worst
+ * outcome available: a provider advertising 300s against 30s of budget sleeps
+ * the 30s, re-issues, and aborts immediately, having spent the remaining
+ * wall clock to learn nothing. Refusing outright surfaces the failure while
+ * budget remains for the layer above to act on it.
+ *
+ * An absent `remainingMs` means the turn is unbounded (TurnDeadline's
+ * UNBOUNDED), so there is no budget to exceed and the wait is always allowed.
+ */
+export declare function turnRetryFitsBudget(delayMs: number, remainingMs: number | undefined): boolean;
+/**
+ * A sleep that resolves early, and rejects, when `signal` fires — mirrors
+ * nax-ai's retry.ts `abortableSleep` so a pending backoff cannot outlive the
+ * caller's own cancellation and go on to start a request nobody wants.
+ */
+export declare function abortableSleep(ms: number, sleep: (ms: number) => Promise<void>, signal?: AbortSignal): Promise<void>;
+/** The real timer. Named and exported so the only production wiring of it is one reference. */
+export declare function realSleep(ms: number): Promise<void>;
+export interface TurnRetryDeps<T> {
+    /** Re-issues the round trip. Called once per retry, never for the triggering attempt. */
+    readonly attempt: () => Promise<T>;
+    readonly config: TurnRetryConfig;
+    /** Whole-turn wall-clock budget. Absent means unbounded, matching TurnDeps.deadline. */
+    readonly deadline?: {
+        expired(): boolean;
+        remainingMs(): number | undefined;
+    };
+    readonly signal?: AbortSignal;
+    /**
+     * The sleep used for backoff. Deliberately REQUIRED and without a default:
+     * a real timer here is production wiring (turn-loop.ts passes `realSleep`),
+     * and leaving it optional let a test omit it and silently wait out a real
+     * multi-second backoff. Required makes that a compile error instead.
+     */
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Injectable jitter source, for deterministic tests. Defaults to Math.random. */
+    readonly random?: () => number;
+    /** Fired once per retry, before the backoff delay, with a 1-based retry number. */
+    readonly onRetry?: (retryNumber: number, delayMs: number, fault: RetryableProtocolError) => void;
+}
+/**
+ * Retries `attempt` while the thrown error is a transport/overloaded fault,
+ * bounded by `config.maxAttempts`, the deadline and the abort signal.
+ *
+ * Exhaustion, a non-retryable error, an expired deadline or an aborted
+ * signal all rethrow the triggering error EXACTLY as thrown — never wrapped
+ * or mutated. `runNativeTurn` records failure usage against the error's own
+ * identity in a WeakMap (`readNativeTurnFailureUsage`), and adapter-deps.ts's
+ * `isProtocolStreamError` guard depends on the error keeping its own shape;
+ * both would silently break if this function rethrew a new object.
+ */
+export declare function retryTransportFault<T>(firstError: unknown, deps: TurnRetryDeps<T>): Promise<T>;
+export {};

package/dist/native/session/turn-retry.js

@@ -0,0 +1,182 @@
+/**
+ * Bounded transport-fault retry for the native turn loop (nax#1870).
+ *
+ * A mid-stream provider stall (OpenRouter's "Upstream idle timeout exceeded",
+ * a bare 502/503) surfaces to `runNativeTurn` as a throw from `deps.complete`.
+ * Retrying it here is safe, and safe nowhere else:
+ *
+ * - `@nathapp/nax-ai`'s own retry (protocols/retry.ts, same repo family as
+ *   this file — its doc comments are this file's model) is gated on
+ *   `emitted`: the moment any event is yielded, retry is off for that
+ *   attempt, because retrying past a `usage` event would double-bill. A
+ *   mid-stream stall is therefore structurally out of its reach.
+ * - A run-kind op's declarative `retry` (`sendWithParseRetry`,
+ *   src/operations/call.ts) has no try/catch around the call at all — a
+ *   transport throw propagates straight past it, untouched.
+ * - The turn loop can, cheaply: on a throw from `deps.complete`, `messages`
+ *   is unchanged (the failed response was never appended) and no tool from
+ *   that round trip has executed (tools run only after `complete` returns),
+ *   so an immediate re-issue costs one round trip against the alternative of
+ *   discarding the whole session.
+ *
+ * This is the native counterpart to `agent.acp.promptRetries`: acpx's
+ * spawned process absorbs a provider stall before nax ever observes it;
+ * native has no such process, so nax is the harness that must.
+ *
+ * Detection is structural, matching turn-loop.ts's `isContextOverflow` and
+ * adapter-deps.ts's `isProtocolStreamError`: nax-ai's error class is not
+ * importable outside src/agents/native/ (check-nax-ai-imports.ts), so only
+ * the shape — a `protocolError.kind` string — is inspected, never the class.
+ */
+import { credentialFaultCode } from "../errors.js";
+/**
+ * Kinds this module retries. "auth" and "bad-request" are terminal --
+ * retrying cannot help. "context-overflow" keeps its existing, dedicated
+ * compaction-retry path in turn-loop.ts and must never be handled here.
+ *
+ * "rate-limit" belongs here, not at the manager. It was previously excluded
+ * and deferred to the manager-tier defaultRetryStrategy, but that handler sits
+ * inside runWithFallback's "swap declined" branch, and on the native transport
+ * the swap gate accepts rather than declines -- so control left the branch
+ * before reaching it. The wait is also cheapest here: on a throw from
+ * deps.complete the messages array is unchanged and no tool has executed, so a
+ * re-issue costs one round trip rather than a whole hop and a fresh session.
+ */
+const RETRYABLE_KINDS = new Set(["transport", "overloaded", "rate-limit"]);
+export function isRetryableTransportFault(err) {
+    if (typeof err !== "object" || err === null || !("protocolError" in err))
+        return false;
+    const { protocolError } = err;
+    if (typeof protocolError?.kind !== "string" || !RETRYABLE_KINDS.has(protocolError.kind))
+        return false;
+    return credentialFaultCode({ kind: protocolError.kind, cause: protocolError.cause }) === undefined;
+}
+/** Whether another attempt is allowed at all, independent of the error's kind. */
+export function canAttemptTurnRetry(retryIndex, config) {
+    return retryIndex < config.maxAttempts - 1;
+}
+/**
+ * Equal jitter (AWS's "Exponential Backoff And Jitter"): half of
+ * `base * 2^retryIndex` fixed, half uniformly random, so concurrent retries
+ * spread out instead of synchronising on the same step while still keeping a
+ * floor. Full jitter's [0, ceiling] range was rejected: its lower bound lets
+ * a retry re-issue almost instantly against a provider that has just stalled
+ * or reported itself overloaded, which is the one thing backoff exists to
+ * avoid. nax-ai's own retry.ts omits jitter entirely because it hands
+ * concurrency policy to its consumer — this module IS that consumer, so the
+ * jitter belongs here.
+ */
+function backoffMs(retryIndex, baseDelayMs, random) {
+    const half = (baseDelayMs * 2 ** retryIndex) / 2;
+    return Math.floor(half + random() * half);
+}
+/**
+ * How long to wait before the next attempt. The provider's own `retryAfter`
+ * wins when set — it knows its own recovery time better than a guessed
+ * backoff does — otherwise equal-jitter exponential backoff from
+ * `baseDelayMs`.
+ *
+ * `remainingMs` caps whatever that produces. A 503 can advertise a recovery
+ * window far longer than the turn has left, and sleeping it out would spend
+ * wall clock the budget has already declared gone — the attempt after it
+ * aborts immediately anyway, because TurnDeadline.remainingMs() clamps to 0
+ * and session-adapter.ts arms the call's AbortController with it. Absent means
+ * the turn is unbounded (TurnDeadline's UNBOUNDED), so nothing caps the wait.
+ */
+export function turnRetryDelayMs(err, retryIndex, config, random = Math.random, remainingMs) {
+    const { retryAfter } = err.protocolError;
+    const delayMs = retryAfter !== undefined ? retryAfter * 1000 : backoffMs(retryIndex, config.baseDelayMs, random);
+    return remainingMs === undefined ? delayMs : Math.min(delayMs, remainingMs);
+}
+/**
+ * Whether the wait is worth taking at all.
+ *
+ * turnRetryDelayMs clamps to `remainingMs`, which alone produces the worst
+ * outcome available: a provider advertising 300s against 30s of budget sleeps
+ * the 30s, re-issues, and aborts immediately, having spent the remaining
+ * wall clock to learn nothing. Refusing outright surfaces the failure while
+ * budget remains for the layer above to act on it.
+ *
+ * An absent `remainingMs` means the turn is unbounded (TurnDeadline's
+ * UNBOUNDED), so there is no budget to exceed and the wait is always allowed.
+ */
+export function turnRetryFitsBudget(delayMs, remainingMs) {
+    return remainingMs === undefined || delayMs <= remainingMs;
+}
+function abortError(signal) {
+    return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+/**
+ * A sleep that resolves early, and rejects, when `signal` fires — mirrors
+ * nax-ai's retry.ts `abortableSleep` so a pending backoff cannot outlive the
+ * caller's own cancellation and go on to start a request nobody wants.
+ */
+export function abortableSleep(ms, sleep, signal) {
+    if (signal === undefined)
+        return sleep(ms);
+    if (signal.aborted)
+        return Promise.reject(abortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        sleep(ms).then(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, reject);
+    });
+}
+/** The real timer. Named and exported so the only production wiring of it is one reference. */
+export function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retries `attempt` while the thrown error is a transport/overloaded fault,
+ * bounded by `config.maxAttempts`, the deadline and the abort signal.
+ *
+ * Exhaustion, a non-retryable error, an expired deadline or an aborted
+ * signal all rethrow the triggering error EXACTLY as thrown — never wrapped
+ * or mutated. `runNativeTurn` records failure usage against the error's own
+ * identity in a WeakMap (`readNativeTurnFailureUsage`), and adapter-deps.ts's
+ * `isProtocolStreamError` guard depends on the error keeping its own shape;
+ * both would silently break if this function rethrew a new object.
+ */
+export async function retryTransportFault(firstError, deps) {
+    const { sleep } = deps;
+    const random = deps.random ?? Math.random;
+    let err = firstError;
+    let retryIndex = 0;
+    for (;;) {
+        if (!isRetryableTransportFault(err))
+            throw err;
+        if (!canAttemptTurnRetry(retryIndex, deps.config))
+            throw err;
+        if (deps.deadline?.expired() === true || deps.signal?.aborted === true)
+            throw err;
+        const fault = err;
+        // Computed WITHOUT the remainingMs clamp: the value that decides whether the
+        // wait is affordable must be the provider's own, not one already reduced to
+        // fit. Clamping alone spends the whole remaining budget on a wait that cannot
+        // succeed, and the attempt after it aborts immediately.
+        const remainingMs = deps.deadline?.remainingMs();
+        const delayMs = turnRetryDelayMs(fault, retryIndex, deps.config, random);
+        if (!turnRetryFitsBudget(delayMs, remainingMs))
+            throw fault;
+        deps.onRetry?.(retryIndex + 1, delayMs, fault);
+        try {
+            await abortableSleep(delayMs, sleep, deps.signal);
+        }
+        catch {
+            // The abort during backoff IS the reason to stop; the transport fault
+            // that triggered the retry is still the honest cause to surface, not
+            // the abort itself.
+            throw fault;
+        }
+        try {
+            return await deps.attempt();
+        }
+        catch (nextErr) {
+            err = nextErr;
+            retryIndex += 1;
+        }
+    }
+}

package/dist/native/session/turn-tool-batch.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The per-batch tool-call loop of the native turn loop.
+ *
+ * One assistant message may carry several tool calls; this module answers every
+ * one of them, applying the six distinct rules the loop has accumulated. It is
+ * the largest move out of `turn-loop.ts` and the one with the most invariants,
+ * so it is extracted unchanged: the rules are the point, not the plumbing.
+ *
+ * The batch owns a mutable copy of the transcript for its duration and returns
+ * the final array; `interactions` and `codingToolsCalled` accumulate locally and
+ * come back as NEW entries, so the caller appends rather than the batch
+ * mutating turn-lifetime arrays it does not own.
+ *
+ * `spinWarned` is a snapshot: it is set by the spin breaker's `onSpinStop`
+ * callback during this batch only in tandem with a `terminate` outcome, which
+ * breaks the batch immediately — so no later call in the same batch needs the
+ * flipped value. The batch reports the resulting `spinStopped` back out.
+ */
+import type { ToolCall, ToolDefinition } from "@nathapp/nax-ai";
+import type { SpinBreaker } from "#src/infra/spin-breaker/index";
+import type { InteractionExchange, SendTurnOpts } from "#src/session/session-types";
+import type { TranscriptMessage as NativeTranscriptMessage } from "./compaction.ts";
+import { type InvalidCallBudget } from "./handle-invalid-tool-call.ts";
+import type { LoopEventRegistry } from "./loop-events/index.ts";
+import type { TurnDeps } from "./turn-types.ts";
+export interface ToolBatchResult {
+    readonly messages: readonly NativeTranscriptMessage[];
+    /** Only the exchanges recorded in THIS batch; the caller appends them. */
+    readonly interactions: readonly InteractionExchange[];
+    /** Only the coding tools called in THIS batch; the caller appends them. */
+    readonly codingToolsCalled: readonly string[];
+    /** The caller breaks out of the while loop on either. */
+    readonly spinStopped: boolean;
+    readonly budgetExceeded: boolean;
+    /**
+     * US-002: the turn signal (`deps.signal`) was aborted during this batch.
+     * True means the batch answered this-and-later calls with the synthetic
+     * "Not run: the turn was cancelled." result and stopped dispatching; the
+     * loop throws the abort reason instead of continuing to another round trip.
+     * False (never aborted) preserves the pre-feature shape exactly.
+     */
+    readonly cancelled: boolean;
+}
+export interface ToolBatchArgs {
+    readonly messages: readonly NativeTranscriptMessage[];
+    readonly toolCalls: readonly ToolCall[];
+    readonly tools: readonly ToolDefinition[];
+    readonly codingToolNames: ReadonlySet<string>;
+    readonly roundTrips: number;
+    readonly opts: SendTurnOpts;
+    readonly deps: TurnDeps;
+    readonly loopEvents: LoopEventRegistry;
+    readonly invalidCallBudget: InvalidCallBudget;
+    readonly spinBreaker: SpinBreaker | undefined;
+    readonly maxInteractions: number;
+    /** Snapshot of the loop's `spinWarned` at batch dispatch. */
+    readonly spinWarned: boolean;
+    /** Exchanges already recorded this turn, so the ask_human budget is turn-lifetime, not per-batch. */
+    readonly interactionsSoFar: number;
+}
+export declare function runToolBatch(args: ToolBatchArgs): Promise<ToolBatchResult>;