@rarebit-one/harness-kernel 0.18.0 → 0.19.1

package/dist/models/chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/models/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,QAAQ,EACR,QAAQ,EACT,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,eAAe,EAErB,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAEzC;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,6EAA6E;IAC7E,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,cAAc,CAAA;AAEzC,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;AAElE,wDAAwD;AACxD,eAAO,MAAM,SAAS,SAAS,CAAA;AAE/B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CA6DtF;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,KAAK,IAAI,SAAS,CAE3E;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAElE;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,QAAQ,EAAE,EACjB,KAAK,CAAC,EAAE,QAAQ,EAAE,EAClB,eAAe,CAAC,EAAE,eAAe,GAChC,WAAW,CAQb"}
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/models/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,QAAQ,EACR,QAAQ,EACT,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,eAAe,EAErB,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAEzC;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,cAAc,CAAA;AAEzC,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;AAElE,wDAAwD;AACxD,eAAO,MAAM,SAAS,SAAS,CAAA;AAE/B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAoEtF;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,KAAK,IAAI,SAAS,CAE3E;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAElE;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,QAAQ,EAAE,EACjB,KAAK,CAAC,EAAE,QAAQ,EAAE,EAClB,eAAe,CAAC,EAAE,eAAe,GAChC,WAAW,CAQb"}

package/dist/models/chat.js

@@ -1,4 +1,4 @@
-import { requireCapability, } from "./types.js";
+import { CapabilityError, requireCapability, } from "./types.js";
 /** The kind string every chat model registers under. */
 export const CHAT_KIND = "chat";
 /**
@@ -11,11 +11,13 @@ export const CHAT_KIND = "chat";
  *
  * Capabilities are reported conservatively, from what the `Provider` interface
  * can actually express: it has no streaming method and no attachment channel,
- * so those stay false. `usage` follows the provider's own `reportsUsage`
- * declaration: the SDK-backed adapters set it (their `ConverseResult.usage`
- * becomes `ModelResult.usage`), while a provider that declares nothing — the
- * mock, a custom provider — reports `usage: false` rather than promising
- * accounting it does not deliver.
+ * so those stay false. A request carrying `parts` is refused with a
+ * `CapabilityError` even when `multimodalInput` is passed in `caps`, because
+ * there is no channel to forward them on. `usage` follows the provider's own
+ * `reportsUsage` declaration: the SDK-backed adapters set it (their
+ * `ConverseResult.usage` becomes `ModelResult.usage`), while a provider that
+ * declares nothing — the mock, a custom provider — reports `usage: false`
+ * rather than promising accounting it does not deliver.
  */
 export function chatModel(provider, caps = {}) {
     const resolved = {
@@ -32,6 +34,9 @@ export function chatModel(provider, caps = {}) {
         async invoke(req, ctx) {
             if (req.parts?.length) {
                 requireCapability({ id: provider.name, kind: CHAT_KIND, caps: resolved }, "multimodalInput", "request carries parts");
+                // A declared capability is not a channel: `ConverseRequest` has nowhere
+                // to put an attachment, so forwarding would drop it. Refuse instead.
+                throw new CapabilityError({ id: provider.name, kind: CHAT_KIND, caps: resolved }, "multimodalInput", "declared, but not deliverable: the Provider interface has no attachment channel, so parts would be dropped");
             }
             if (req.tools.length > 0) {
                 requireCapability({ id: provider.name, kind: CHAT_KIND, caps: resolved }, "tools", "request carries tool definitions");

package/dist/models/chat.js.map

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

package/dist/models/retry.d.ts

@@ -0,0 +1,259 @@
+import { type ModelInvocation } from "./types.js";
+/**
+ * Retry and fallback around a model invocation, as an opt-in decorator.
+ *
+ * The kernel leaves transient failures to the vendor SDKs by default. A caller
+ * that needs a policy those SDKs cannot express — a wait that knows the run's
+ * deadline, an honoured `Retry-After`, a named chain of other models to try
+ * once the primary is exhausted — wraps its model in {@link withRetry} and
+ * turns the SDK's own retries off (`providerOptions.maxRetries: 0`), so the two
+ * do not multiply.
+ *
+ * This is infrastructure, not a quality loop: an attempt is repeated only when
+ * the call FAILED (threw), never because its answer was judged poor. And it is
+ * explicit: there is no default fallback chain, so a call that ends up on
+ * another model does so because the caller listed that model.
+ *
+ * It wraps a {@link ModelInvocation} rather than being a `Middleware`
+ * because a fallback chain needs several invocations, and middleware is handed
+ * exactly one `next`. Being payload-generic, it covers every kind the same way
+ * middleware does: a chat model, a detector, a forecaster.
+ */
+/**
+ * What to do after a failed attempt.
+ *
+ * - `retry` — a transient fault: try the same model again after a backoff, and
+ *   move to the next model in the chain once its attempts run out.
+ * - `fallback` — this model will not answer soon: skip its remaining attempts
+ *   and move to the next model at once.
+ * - `fatal` — a fault no other attempt can fix (a bad credential, an invalid
+ *   request): rethrow it unchanged, trying nothing else.
+ */
+export type RetryDecision = "retry" | "fallback" | "fatal";
+/** One model in the chain giving up, or one wait before trying it again. */
+export type RetryEvent = {
+    type: "retry";
+    /** The invocation id that failed and will be tried again. */
+    model: string;
+    /** The attempt on this model that just failed, from 1. */
+    attempt: number;
+    /** How long the wrapper waits before the next attempt. */
+    delayMs: number;
+    /** True when `delayMs` came from the server's `Retry-After`. */
+    retryAfter: boolean;
+    /** The failure. Absent when the wrapper was built with `private: true`. */
+    error?: unknown;
+} | {
+    type: "fallback";
+    /** The invocation id given up on. */
+    from: string;
+    /** The next invocation id in the chain. */
+    to: string;
+    /**
+     * Why `from` was given up on: its retries or wait budget ran out
+     * (`exhausted`), the classifier said `fallback`, or it was skipped
+     * because an earlier call of this wrapper exhausted it (`sticky`).
+     */
+    reason: "exhausted" | "fallback" | "sticky";
+    error?: unknown;
+};
+/**
+ * What the wrapper did on a call that succeeded, reported as `meta.retry` on
+ * the result. Consumers audit which model actually served a call from it.
+ */
+export interface RetryReport {
+    /**
+     * The id of the invocation that answered. When the chain entry that
+     * answered is itself a `withRetry` wrapper, this is the model inside it that
+     * answered, and `attempts`, `fellBackFrom` and `waitedMs` include its calls.
+     */
+    served: string;
+    /** The answering entry's position in this chain: 0 is the primary, n the n-th fallback. */
+    position: number;
+    /** Every call made for this invocation, including the one that answered. */
+    attempts: number;
+    /** Ids of the models tried and given up on, in order; empty when the primary served. */
+    fellBackFrom: string[];
+    /** Total time this invocation spent waiting between attempts. */
+    waitedMs: number;
+}
+/**
+ * Internal: the id of the model that served a call, when a `withRetry` wrapper
+ * reported one on its result. The native loop reads it so a run's `provider`
+ * names the fallback that answered rather than the primary. Not exported from
+ * `index.ts`.
+ */
+export declare function servedBy(meta: Record<string, unknown> | undefined): string | undefined;
+/** Exponential backoff: `baseMs × 2^(retry−1)`, capped at `maxMs`. */
+export interface BackoffOptions {
+    /** The first wait. Default 500. */
+    baseMs?: number;
+    /** The longest single wait. Default 8000. */
+    maxMs?: number;
+    /**
+     * Randomise each wait between half and all of its computed value, so many
+     * callers refused at once do not retry in step. Default true.
+     */
+    jitter?: boolean;
+}
+export interface RetryOptions<Req, Res> {
+    /**
+     * Calls per model, including the first. Default 3 (the SDK default this
+     * replaces: one call plus two retries). 1 means never retry, only fall back.
+     */
+    maxAttempts?: number;
+    /**
+     * The wait before retry `n` (from 1): exponential options, or a function for
+     * a fixed schedule (`(n) => [1000, 2000, 3000][n - 1] ?? 3000`).
+     */
+    backoff?: BackoffOptions | ((retry: number) => number);
+    /**
+     * Wait what the server's `Retry-After` (or `retry-after-ms`) header asks
+     * instead of the computed backoff. Default true. A server wait longer than
+     * the remaining budget is not shortened, since a shortened wait would only
+     * be refused again: that model is given up on and the chain moves on.
+     */
+    respectRetryAfter?: boolean;
+    /**
+     * The longest server-asked wait honoured. Default 60000, as the vendor SDKs
+     * do. A `Retry-After` above it is treated as a wait that does not fit: that
+     * model is given up on and the chain moves on, rather than sleeping for an
+     * implausible hour or day.
+     */
+    maxRetryAfterMs?: number;
+    /** Decide each failure. Default {@link defaultRetryClassifier}. */
+    classify?: (err: unknown) => RetryDecision;
+    /**
+     * The ordered models to try once the primary is given up on. Empty (the
+     * default) means retry only: the kernel never picks a fallback by itself.
+     */
+    fallbacks?: ModelInvocation<Req, Res>[];
+    /**
+     * The absolute deadline (epoch ms) every attempt must finish by, or a
+     * function returning it. The wrapper never starts a wait that would run past
+     * it. The call's context bounds it too: `InvokeContext.budget.deadlineAt`
+     * (which the native loop sets to the run's deadline, so a wrapped model in
+     * `runConversation` or `runAgent` knows how much of the run is left) and
+     * `budget.maxDurationMs` counted from the call's start. The earliest wins.
+     * Set this when the model is called outside the native loop, or when the
+     * caller's own deadline is earlier than the run's.
+     */
+    deadlineAt?: number | (() => number);
+    /**
+     * Time to leave for the call itself: a wait that would leave less than this
+     * before the deadline is not started. Default 0.
+     */
+    minCallMs?: number;
+    /**
+     * The most this wrapper waits in total, summed across every call made
+     * through it. Default unlimited.
+     *
+     * This budget belongs to the INSTANCE and never refills, so build one
+     * wrapper per run or turn when you set it. A wrapper registered once at
+     * startup and shared by every run would spend it on the first rate limit
+     * and never retry again.
+     */
+    waitBudgetMs?: number;
+    /**
+     * Once a model has been given up on because its retries or wait budget ran
+     * out, start every later call of this wrapper at the next model rather than
+     * asking it again (asking a rate-limited model again only adds a refusal
+     * under the same limit). A `fallback` decision does not make it sticky.
+     * Default false.
+     *
+     * Like `waitBudgetMs`, this is instance state that never resets: build one
+     * wrapper per run or turn when you set it. A wrapper with neither option
+     * keeps no state between calls and is safe to share.
+     */
+    stickyFallback?: boolean;
+    /**
+     * The run is private (`RunSpec.private`): its material must stay on the one
+     * model it was given. Retrying that model is allowed; a fallback chain is
+     * refused when the wrapper is built, because a fallback is exactly a way for
+     * the material to reach another model. That includes a primary that is
+     * itself a `withRetry` wrapper with fallbacks; a nested `withRetry` must also
+     * be built `private: true`, or it is refused, since it logs and reports on
+     * its own.
+     *
+     * An upstream error can quote the material, so none of its text leaves the
+     * wrapper by its own hand: `onEvent` receives no `error`, `ctx.log` lines
+     * name the HTTP status at most, and `RetryExhaustedError`'s `failures` and
+     * `cause` hold a narrowed error carrying only that status. A fatal error or
+     * an abort is still rethrown unchanged, exactly as the model threw it; that
+     * error is the caller's to keep off its own channels.
+     *
+     * Caller-declared today: the native engine selects its own provider and
+     * takes no injected model, so a private run cannot reach this wrapper. A
+     * hook that ever lets an engine wrap its model must pass `RunSpec.private`
+     * through here, or this refusal becomes a hope.
+     */
+    private?: boolean;
+    /** Told about each retry and fallback as it happens. A throwing observer is logged and skipped. */
+    onEvent?: (event: RetryEvent) => void;
+    /** Injectable for tests. Must reject with `signal.reason` when it aborts. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Injectable for tests. Default `Date.now`. */
+    now?: () => number;
+    /** Injectable for tests (jitter). Default `Math.random`. */
+    random?: () => number;
+}
+/**
+ * Thrown when every model in the chain failed without a fatal error: the last
+ * failure is its `cause`, every failure is in `failures`. A `fatal` error is
+ * never wrapped, and neither is an abort.
+ */
+export declare class RetryExhaustedError extends Error {
+    /** Each failed call, in order. */
+    readonly failures: {
+        model: string;
+        error: unknown;
+    }[];
+    /** Why the chain stopped: every model was tried, or the deadline left no room for another attempt. */
+    readonly reason: "exhausted" | "deadline";
+    /** Total time spent waiting between those calls. */
+    readonly waitedMs: number;
+    constructor(failures: {
+        model: string;
+        error: unknown;
+    }[], reason: "exhausted" | "deadline", cause: unknown, waitedMs?: number);
+}
+/**
+ * The HTTP status a failed call carries: the SDK error's `status` (or
+ * `statusCode`), else a leading status in its message ("429 Rate limit
+ * exceeded"), which is how some gateways' errors arrive.
+ */
+export declare function errorStatus(err: unknown): number | undefined;
+/**
+ * The wait a failed call's server asked for, in ms: `retry-after-ms`, else
+ * `retry-after` as seconds or an HTTP date. Read from the error's `headers`,
+ * a `Headers` or a plain record, the way the SDKs attach them.
+ */
+export declare function retryAfterMs(err: unknown, now?: number): number | undefined;
+/**
+ * The default classification: rate limits, timeouts, server faults (but not
+ * 501/505) and dropped connections are retried; a nested `withRetry` that ran
+ * out moves this chain to its next model; everything else — auth (401/403), payment
+ * (402), an invalid request (400/404/422), a credential or option the kernel
+ * refused, and any error it cannot recognise — is fatal. Unknown errors are
+ * fatal on purpose: retrying what nobody classified hides it.
+ */
+export declare function defaultRetryClassifier(err: unknown): RetryDecision;
+/**
+ * Wrap a model in retry-and-fallback.
+ *
+ * The returned invocation keeps the primary's `id` and `kind`; its `caps` are
+ * what every model in the chain can do (a capability one fallback lacks is not
+ * advertised), and it streams only when all of them stream. `probe` asks the
+ * primary.
+ *
+ * On success the result is the serving model's, with `meta.retry` set to a
+ * {@link RetryReport}. A streaming call is never retried or sent to a fallback
+ * once its sink has received anything: the caller has already shown that
+ * output, and a second answer spliced after it would be a different reply.
+ *
+ * An abort (the call's `signal`) stops a wait at once and is rethrown as the
+ * signal's reason, the same as an abort mid-request, so the loop still reads
+ * it as a clean stop.
+ */
+export declare function withRetry<Req, Res>(primary: ModelInvocation<Req, Res>, options?: RetryOptions<Req, Res>): ModelInvocation<Req, Res>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/models/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/models/retry.ts"],"names":[],"mappings":"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"}