@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/retry.d.ts

@@ -1,4 +1,3 @@
-import OpenAI from "openai";
 /**
  * Everything about a request failing that is not about what the request said.
  *
@@ -15,6 +14,7 @@ export declare class EndpointSilent extends Error {
  * The request was bigger than the model will read. Its own class so nothing retries it: sending
  * the same too-large request again is the same refusal, one round trip later.
  *
+ * @remarks
  * `runTurn` raises it from either side of the round trip — its own pre-flight guard, or the
  * endpoint's refusal read back through `isOverflow` — so a caller has one thing to catch whether
  * or not it gave a `contextLimit`. The second carries the endpoint's own message, and the error
@@ -23,143 +23,22 @@ export declare class EndpointSilent extends Error {
 export declare class ContextOverflow extends Error {
     readonly name = "ContextOverflow";
 }
-/**
- * 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit.
- *
- * @param tokens The count to render.
- */
-export declare const compact: (tokens: number) => string;
-/** What the two token estimates below take besides what they measure. */
-export interface TokenEstimateOptions {
-    /**
-     * The divisor, `CHARS_PER_TOKEN` unless given — `charsPerTokenFor` for a model whose reported
-     * usage has calibrated it. A value that is not a number above zero is ignored.
-     */
-    charsPerToken?: number;
-}
-/**
- * How many characters one message is worth: its keys, and its content in whichever shape.
- *
- * @param message The message as it will be sent.
- */
-export declare function messageChars(message: OpenAI.ChatCompletionMessageParam): number;
-/**
- * How many characters a tool array is worth, measured once per array.
- *
- * @param tools The tool definitions as they will be sent. An empty array is worth nothing.
- */
-export declare function toolsChars(tools: OpenAI.ChatCompletionTool[]): number;
-/**
- * How many characters a request is worth: the walk `requestTokens` divides, without the division.
- *
- * What calibration reads a reported prompt count against, since a ratio is only as good as the
- * character count it was taken over agreeing with the one it is later applied to.
- *
- * @param body The request as it was sent, tools included.
- */
-export declare function requestChars(body: OpenAI.ChatCompletionCreateParamsStreaming): number;
-/**
- * What this request will cost the window, in tokens, near enough.
- *
- * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose,
- * and `charsPerTokenFor` for the divisor a model's own reported usage has measured instead.
- *
- * Summed by walking the body rather than by serialising it. `JSON.stringify` on the messages
- * built the entire transcript into a string on every call and threw it away having read nothing
- * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
- * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
- * which the envelope constants put back — one per key and one per content part, rather than one
- * per message, since the keys only some shapes carry and the parts a client appends block by
- * block are most of what a tool-using transcript is made of. What is left is a message's
- * escaping, which is not a constant and is small against an estimate that is already characters
- * over four.
- *
- * @param body The request as it will be sent, tools included.
- * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
- */
-export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming, { charsPerToken }?: TokenEstimateOptions) => number;
-/**
- * What a request is made of, by the part of it a consumer can actually do something about.
- *
- * The question an operator asks is not how big the request is — the total already answers that —
- * but what is filling the window, and the only useful answer names a lever: a system prompt to
- * shorten, a tool list to load on demand instead of declaring whole, a transcript to compact,
- * results to prune. So the cut follows the levers rather than the roles: `toolResults` is exactly
- * what `pruneToolResults` can shrink, and `history` is everything `planCompaction` folds, the
- * arguments of the calls in it included.
- */
-export interface ContextBreakdown {
-    /** Every system and developer message, wherever it sits in the transcript. */
-    system: number;
-    /** The declared tool schemas, which a chat template renders ahead of the system prompt. */
-    tools: number;
-    /** What was said: the user and assistant messages, and the calls the assistant asked for. */
-    history: number;
-    /** What the tools handed back — the `tool` messages, and nothing else. */
-    toolResults: number;
-    /** The four above, summed. */
-    total: number;
-}
-/**
- * What each part of a request is worth in characters, by the same walk `requestTokens` divides.
- *
- * Exact and additive: the parts sum to `total`, which is `requestChars` plus `toolsChars`. The
- * conversion to tokens is `contextTokens`' business, because that is where an estimate and a
- * reported count have to be told apart.
- *
- * @param body The request as it will be sent, tools included.
- */
-export declare function contextChars(body: OpenAI.ChatCompletionCreateParamsStreaming): ContextBreakdown;
-/** What `contextTokens` takes besides the request. */
-export interface ContextBreakdownOptions extends TokenEstimateOptions {
-    /**
-     * The prompt count the endpoint reported for this request, if it has answered. Given one, the
-     * parts are shares of it and the breakdown sums to what was actually charged rather than to an
-     * estimate; left out, they are shares of `requestTokens`.
-     */
-    promptTokens?: number;
-}
-/**
- * What each part of a request costs the window, in tokens, adding up to the whole.
- *
- * Shares rather than four independent estimates, because a readout whose parts do not add up to
- * the total beside them is a readout nobody trusts. Nothing in the round trip reports anything
- * finer than a prompt count — a completion says how many tokens it read and not a word about
- * where they came from — so the proportions are an estimate whatever the total is.
- *
- * Without a reported count the total is `requestTokens`, and the tools are counted the way it and
- * `TurnMetrics.toolSchemaTokens` count them rather than shared out, so the two agree by
- * construction and an operator does not read one number for the tool block in the metrics and a
- * different one here. With a reported count every part is a share of it, the tools included:
- * that number is the server's, and the point of using it is that the parts sum to what was
- * charged.
- *
- * @param body The request as it will be sent, tools included.
- * @param options The divisor, and the reported prompt count when there is one.
- */
-export declare function contextTokens(body: OpenAI.ChatCompletionCreateParamsStreaming, { charsPerToken, promptTokens }?: ContextBreakdownOptions): ContextBreakdown;
-/**
- * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
- *
- * For the arithmetic that weighs part of a transcript against a window — `planCompaction`'s kept
- * tail — where `estimateTokens` on the text alone would leave out the calls and the envelope.
- *
- * @param message The message as it will be sent.
- * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
- */
-export declare const messageTokens: (message: OpenAI.ChatCompletionMessageParam, { charsPerToken }?: TokenEstimateOptions) => number;
 /**
  * Whether a refusal means the request was too big, rather than merely refused.
  *
+ * @param detail - The endpoint's own message.
+ * @returns `true` for an overflow: one of the over-long wordings, beside `token` or `context`.
+ * `false` for anything that reads as a rate limit, whatever else it says.
+ *
+ * @remarks
  * Rate limits are ruled out first: they borrow the same words and mean the opposite, being worth
  * another attempt where an overflow never is.
- *
- * @param detail The endpoint's own message.
  */
 export declare const isOverflow: (detail: string) => boolean;
 /**
  * The smallest window worth believing in, and the floor under `runTurn`'s guard.
  *
+ * @remarks
  * `runTurn`'s `contextLimit` reads it as a sanity check on a number it was handed: below this,
  * the limit is taken for a placeholder — an unset column, a listing that said nothing — rather
  * than a window worth refusing a run over. That is the whole of what reads it; `contextLimitFor`
@@ -176,37 +55,45 @@ export declare const SMALLEST_LIKELY_WINDOW = 8192;
 /**
  * Whether a failed request is worth trying again.
  *
+ * @param error - The rejection, as caught. What is not an SDK error is not transient.
+ * @returns `true` for an `EndpointSilent`, a connection error, a 408, 409 or 429, and any status
+ * of 500 or above; `false` for any other SDK error, one with no status included.
+ *
+ * @remarks
  * The question is whether the request was *refused or lost*, rather than answered with a
  * complaint about its contents: a connection that never landed, a server too busy or too broken
  * to answer, an endpoint that went quiet. A 400 for a malformed tool schema would fail exactly
  * the same way on every attempt, and the two capability cases below are negotiated rather than
  * retried blindly.
- *
- * @param error The rejection, as caught. What is not an SDK error is not transient.
  */
 export declare function isTransient(error: unknown): boolean;
 /**
  * Whether a failure is the endpoint refusing the request as written, rather than losing it.
  *
+ * @param error - The rejection, as caught. What is not an SDK error refuses nothing.
+ * @returns `true` for an SDK error whose status is 400 or 422, and for nothing else.
+ *
+ * @remarks
  * 400 and 422 are what a server says when it read the body and disliked it, which makes them the
  * only statuses worth answering by sending something different. Any 4xx is too wide: 401, 404 and
  * 429 are 4xx and none of them is about the fields, and a 429 is one `isTransient` accepts — a
  * caller that re-sent on it at once doubled the rate against a server that had just asked for less.
  * Catching everything is wider still, since an abort or a connection that never landed then
  * latches off whatever the re-send left out.
- *
- * @param error The rejection, as caught. What is not an SDK error refuses nothing.
  */
 export declare const refusesRequest: (error: unknown) => boolean;
 /**
  * Whether a failure is a local server still loading the model, rather than one failing to serve.
  *
+ * @param error - The rejection, as caught.
+ * @returns `true` for a 503 whose body is of type `unavailable_error`, or whose message says the
+ * model is loading; `false` for any other status and for what is not an SDK error.
+ *
+ * @remarks
  * llama.cpp answers 503 `Loading model` with type `unavailable_error` from the moment it starts
  * until the weights are mapped, and a router build says the same while it swaps models. That is
  * thirty to ninety seconds for a large model from a cold page cache, and `backoffMs` gives up
  * inside fifteen: sized for a busy host, not for one reading a file. A plain 503 is not this.
- *
- * @param error The rejection, as caught.
  */
 export declare function isModelLoading(error: unknown): boolean;
 /** How long to wait between asking a loading server again. */
@@ -214,15 +101,19 @@ export declare const LOADING_POLL_MS = 3000;
 /** How long `runTurn` waits for a model to load unless told otherwise. */
 export declare const LOADING_TIMEOUT_MS = 120000;
 /**
- * Exponential, with jitter so several tasks failing at once do not return in lockstep.
+ * How long to wait before a retry: exponential, with jitter so several tasks failing at once do
+ * not return in lockstep.
  *
- * @param attempt Zero-based. Doubles from 500ms to a ceiling of eight seconds, before jitter.
+ * @param attempt - Zero-based. Doubles from 500ms to a ceiling of eight seconds, before jitter.
+ * @returns Milliseconds, somewhere between half of that wait and all of it, and not a whole number.
  */
 export declare const backoffMs: (attempt: number) => number;
 /**
  * A delay an abort cuts short, rejecting rather than resolving early.
  *
- * @param ms How long to wait.
- * @param signal Abandons the wait. One already aborted rejects without waiting at all.
+ * @param ms - How long to wait.
+ * @param [signal] - Abandons the wait. One already aborted rejects without waiting at all.
+ * @returns A promise that resolves once `ms` has passed, or rejects with the signal's reason — an
+ * `Error` of its own where the signal carries none.
  */
 export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;