@axlsdk/axl 0.24.0 → 0.24.2

package/dist/index.d.cts

@@ -151,6 +151,7 @@ declare function summarizeModelInput(input: ModelInput): string;
  * {@link AccountingReason}, which makes the scope `incomplete` and makes
  * `knownCost` an explicit lower bound.
  */
+
 /**
  * How much of the declared/instrumented scope the numbers actually cover.
  *
@@ -158,8 +159,9 @@ declare function summarizeModelInput(input: ModelInput): string;
  *
  * - `'complete'` — every operation in the scope reached a terminal state with a
  *   usable charge (including known $0).
- * - `'incomplete'` — at least one operation settled without a usable charge;
- *   `knownCost` is a lower bound and `reasons` says why.
+ * - `'incomplete'` — at least one operation lacked a usable charge, or the
+ *   scope detected work from an incompatible loaded copy; `knownCost` is a
+ *   lower bound and `reasons` says why.
  * - `'unverified'` — reserved for READERS of artifacts that carry no
  *   accounting at all (legacy eval results). A live scope never produces it.
  */
@@ -185,9 +187,8 @@ type AccountingReason =
 /** An external operation finished without calling `report.setCost()`. */
  | 'external_unreported'
 /**
- * A consumer ran work with no accounting scope available (e.g. `@axlsdk/eval`
- * driving a runtime that predates `trackOutcome`). Core defines the name only
- * — no core producer emits it.
+ * A consumer ran work with no accounting scope available, or another loaded
+ * copy attempted work under a scope whose accounting protocol it cannot join.
  */
  | 'uninstrumented';
 /** The instrumented boundaries that can open an operation. */
@@ -216,7 +217,7 @@ type Accounting = {
     /** Sum of settled, usable, disjoint charges. Never includes caller aggregates. */
     knownCost: number;
     completeness: AccountingCompleteness;
-    /** Reason → count of operations carrying it. Empty object when complete. */
+    /** Reason → count of unresolved operations or coverage failures. */
     reasons: Partial<Record<AccountingReason, number>>;
     usage: AccountingUsage;
     operations: {
@@ -229,7 +230,7 @@ type Accounting = {
         total: number;
         /** Terminal with a usable cost, including a known $0. */
         settled: number;
-        /** Terminal or abandoned without a usable cost. Drives `completeness`. */
+        /** Terminal or abandoned without a usable cost. Coverage failures can also make `incomplete`. */
         unknown: number;
         /** Refused admission — never dispatched, contributes nothing anywhere. */
         denied: number;
@@ -423,6 +424,8 @@ type ToolChoice = 'auto' | 'none' | 'required' | {
  */
 type ChatOptions = {
     model: string;
+    /** @internal Full URI of a `ctx.ask` agent turn for cross-runtime diagnostics. */
+    accountingModelUri?: string;
     temperature?: number;
     tools?: ToolDefinition[];
     maxTokens?: number;
@@ -2121,7 +2124,6 @@ declare class EventStreamOverflowError extends Error {
     readonly cause?: unknown;
     constructor(maxQueued: number, eventType: string, cause?: unknown);
 }
-/** A known tool failure whose author-provided model message is safe to expose. */
 declare class ToolFailure extends AxlError {
     readonly modelMessage: string;
     readonly cause?: unknown;
@@ -3012,7 +3014,8 @@ type RateLimitConfig = {
      * `adaptive`), a call first waits out any active rate-limit brake and only
      * then starts this clock; a call already queued when a brake begins keeps
      * its clock running through it. A retry's re-acquire after a rate-limit 429
-     * is exempt: it is bounded by `maxRateLimitRetries` and the ask's `timeout`.
+     * is exempt: it is bounded by `maxRateLimitRetries`, or by the ask's abort
+     * signal when the caller needs a strict deadline.
      */
     acquireTimeoutMs?: number;
     /**
@@ -3025,12 +3028,10 @@ type RateLimitConfig = {
      * recovered linearly on success, dropped once traffic stays well below it;
      * tuning is internal) until it reopens. Nothing waits before the first 429.
      *
-     * Only first-party OpenAI (`openai:`, `openai-responses:`) and Anthropic at
-     * the vendor's default endpoint origin read the 429 body: there a spend-cap
-     * 429 fails fast, and a low quota header holds recovery. Everywhere else
-     * (Gemini, OpenAI-compatible presets, a proxy or gateway `baseUrl`) every
-     * 429 is a rate limit, so a spend-cap or daily-quota 429 fails only once
-     * `maxRateLimitRetries` is spent.
+     * First-party OpenAI, Anthropic, and Gemini at their vendor origins read
+     * 429 bodies: explicit terminal quota/billing limits fail fast. Only OpenAI
+     * and Anthropic read 2xx quota hints. Unrecognized Gemini 429s, presets,
+     * and proxy/gateway origins retry as rate limits.
      *
      * `false` restores the plain behavior: a 429 shares the transient retry
      * budget, holds up no other call, and nothing is paced. Ignored by a
@@ -3225,10 +3226,10 @@ type QuotaDialect = {
  * share one predicate, `Date.now() < brakeUntil`. A scope that does not adapt
  * never brakes, so it behaves exactly as a plain `RateLimiter`.
  *
- * Adapting needs no quota dialect. A dialect (first-party OpenAI and Anthropic
- * at the vendor origin, see `quota.ts`) adds only two vendor-specific extras:
- * spend-cap classification of a 429 body, and the 2xx quota hint that holds
- * recovery. Without one, every 429 is treated as a rate limit and the hint is
+ * Adapting needs no quota dialect. A dialect (first-party OpenAI, Anthropic,
+ * or Gemini at the vendor origin, see `quota.ts`) adds classification of a
+ * 429 body; OpenAI and Anthropic also provide 2xx quota hints. Without one,
+ * every 429 is treated as a rate limit and the hint is
  * never read, so recovery and reopening proceed as if the account were healthy.
  */
 declare class ScopeGovernor extends RateLimiter {
@@ -5840,7 +5841,7 @@ type ModelTimingRollup = Record<string, {
     /** Timed calls that reported a `firstTokenMs` — the denominator for it. */
     firstTokenCalls?: number;
     /**
-     * The per-call blocks the sums were built from, in event order.
+     * The per-call blocks the sums were built from, in settlement order.
      * `length === calls`. Present only under `captureTimingSamples`, because
      * retaining it is O(calls) in memory and the sums alone are O(models) — a
      * caller that needs a real DISTRIBUTION (percentiles, min/max) cannot
@@ -6517,8 +6518,9 @@ declare class AxlRuntime extends EventEmitter {
      * new paid operations once known spend reaches the limit. Already-dispatched
      * work still settles and is still counted.
      *
-     * `metadata`, `modelTiming` and `traces` remain EVENT-derived and therefore
-     * depend on trace configuration; `accounting` never does.
+     * Model metadata and timing share the settlement scope with accounting, so
+     * they cross runtimes and compatible ESM/CJS copies. Workflow names and
+     * captured traces still come from this runtime's events.
      */
     trackOutcome<T>(fn: () => Promise<T>, options?: TrackOutcomeOptions): Promise<TrackedOutcome<T>>;
     /**

package/dist/index.d.ts

@@ -151,6 +151,7 @@ declare function summarizeModelInput(input: ModelInput): string;
  * {@link AccountingReason}, which makes the scope `incomplete` and makes
  * `knownCost` an explicit lower bound.
  */
+
 /**
  * How much of the declared/instrumented scope the numbers actually cover.
  *
@@ -158,8 +159,9 @@ declare function summarizeModelInput(input: ModelInput): string;
  *
  * - `'complete'` — every operation in the scope reached a terminal state with a
  *   usable charge (including known $0).
- * - `'incomplete'` — at least one operation settled without a usable charge;
- *   `knownCost` is a lower bound and `reasons` says why.
+ * - `'incomplete'` — at least one operation lacked a usable charge, or the
+ *   scope detected work from an incompatible loaded copy; `knownCost` is a
+ *   lower bound and `reasons` says why.
  * - `'unverified'` — reserved for READERS of artifacts that carry no
  *   accounting at all (legacy eval results). A live scope never produces it.
  */
@@ -185,9 +187,8 @@ type AccountingReason =
 /** An external operation finished without calling `report.setCost()`. */
  | 'external_unreported'
 /**
- * A consumer ran work with no accounting scope available (e.g. `@axlsdk/eval`
- * driving a runtime that predates `trackOutcome`). Core defines the name only
- * — no core producer emits it.
+ * A consumer ran work with no accounting scope available, or another loaded
+ * copy attempted work under a scope whose accounting protocol it cannot join.
  */
  | 'uninstrumented';
 /** The instrumented boundaries that can open an operation. */
@@ -216,7 +217,7 @@ type Accounting = {
     /** Sum of settled, usable, disjoint charges. Never includes caller aggregates. */
     knownCost: number;
     completeness: AccountingCompleteness;
-    /** Reason → count of operations carrying it. Empty object when complete. */
+    /** Reason → count of unresolved operations or coverage failures. */
     reasons: Partial<Record<AccountingReason, number>>;
     usage: AccountingUsage;
     operations: {
@@ -229,7 +230,7 @@ type Accounting = {
         total: number;
         /** Terminal with a usable cost, including a known $0. */
         settled: number;
-        /** Terminal or abandoned without a usable cost. Drives `completeness`. */
+        /** Terminal or abandoned without a usable cost. Coverage failures can also make `incomplete`. */
         unknown: number;
         /** Refused admission — never dispatched, contributes nothing anywhere. */
         denied: number;
@@ -423,6 +424,8 @@ type ToolChoice = 'auto' | 'none' | 'required' | {
  */
 type ChatOptions = {
     model: string;
+    /** @internal Full URI of a `ctx.ask` agent turn for cross-runtime diagnostics. */
+    accountingModelUri?: string;
     temperature?: number;
     tools?: ToolDefinition[];
     maxTokens?: number;
@@ -2121,7 +2124,6 @@ declare class EventStreamOverflowError extends Error {
     readonly cause?: unknown;
     constructor(maxQueued: number, eventType: string, cause?: unknown);
 }
-/** A known tool failure whose author-provided model message is safe to expose. */
 declare class ToolFailure extends AxlError {
     readonly modelMessage: string;
     readonly cause?: unknown;
@@ -3012,7 +3014,8 @@ type RateLimitConfig = {
      * `adaptive`), a call first waits out any active rate-limit brake and only
      * then starts this clock; a call already queued when a brake begins keeps
      * its clock running through it. A retry's re-acquire after a rate-limit 429
-     * is exempt: it is bounded by `maxRateLimitRetries` and the ask's `timeout`.
+     * is exempt: it is bounded by `maxRateLimitRetries`, or by the ask's abort
+     * signal when the caller needs a strict deadline.
      */
     acquireTimeoutMs?: number;
     /**
@@ -3025,12 +3028,10 @@ type RateLimitConfig = {
      * recovered linearly on success, dropped once traffic stays well below it;
      * tuning is internal) until it reopens. Nothing waits before the first 429.
      *
-     * Only first-party OpenAI (`openai:`, `openai-responses:`) and Anthropic at
-     * the vendor's default endpoint origin read the 429 body: there a spend-cap
-     * 429 fails fast, and a low quota header holds recovery. Everywhere else
-     * (Gemini, OpenAI-compatible presets, a proxy or gateway `baseUrl`) every
-     * 429 is a rate limit, so a spend-cap or daily-quota 429 fails only once
-     * `maxRateLimitRetries` is spent.
+     * First-party OpenAI, Anthropic, and Gemini at their vendor origins read
+     * 429 bodies: explicit terminal quota/billing limits fail fast. Only OpenAI
+     * and Anthropic read 2xx quota hints. Unrecognized Gemini 429s, presets,
+     * and proxy/gateway origins retry as rate limits.
      *
      * `false` restores the plain behavior: a 429 shares the transient retry
      * budget, holds up no other call, and nothing is paced. Ignored by a
@@ -3225,10 +3226,10 @@ type QuotaDialect = {
  * share one predicate, `Date.now() < brakeUntil`. A scope that does not adapt
  * never brakes, so it behaves exactly as a plain `RateLimiter`.
  *
- * Adapting needs no quota dialect. A dialect (first-party OpenAI and Anthropic
- * at the vendor origin, see `quota.ts`) adds only two vendor-specific extras:
- * spend-cap classification of a 429 body, and the 2xx quota hint that holds
- * recovery. Without one, every 429 is treated as a rate limit and the hint is
+ * Adapting needs no quota dialect. A dialect (first-party OpenAI, Anthropic,
+ * or Gemini at the vendor origin, see `quota.ts`) adds classification of a
+ * 429 body; OpenAI and Anthropic also provide 2xx quota hints. Without one,
+ * every 429 is treated as a rate limit and the hint is
  * never read, so recovery and reopening proceed as if the account were healthy.
  */
 declare class ScopeGovernor extends RateLimiter {
@@ -5840,7 +5841,7 @@ type ModelTimingRollup = Record<string, {
     /** Timed calls that reported a `firstTokenMs` — the denominator for it. */
     firstTokenCalls?: number;
     /**
-     * The per-call blocks the sums were built from, in event order.
+     * The per-call blocks the sums were built from, in settlement order.
      * `length === calls`. Present only under `captureTimingSamples`, because
      * retaining it is O(calls) in memory and the sums alone are O(models) — a
      * caller that needs a real DISTRIBUTION (percentiles, min/max) cannot
@@ -6517,8 +6518,9 @@ declare class AxlRuntime extends EventEmitter {
      * new paid operations once known spend reaches the limit. Already-dispatched
      * work still settles and is still counted.
      *
-     * `metadata`, `modelTiming` and `traces` remain EVENT-derived and therefore
-     * depend on trace configuration; `accounting` never does.
+     * Model metadata and timing share the settlement scope with accounting, so
+     * they cross runtimes and compatible ESM/CJS copies. Workflow names and
+     * captured traces still come from this runtime's events.
      */
     trackOutcome<T>(fn: () => Promise<T>, options?: TrackOutcomeOptions): Promise<TrackedOutcome<T>>;
     /**