@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import OpenAI from "openai";
-import type { Endpoint } from "./config.ts";
+import OpenAI from 'openai';
+import type { Endpoint, EndpointIdentity, RetryPolicy } from './config.ts';
 /**
  * The SDK insists on a non-empty key even where the server will not look at it. This is what it
  * gets. It also reads as "this endpoint has no key" at a call site, which an empty string does
@@ -7,11 +7,25 @@ import type { Endpoint } from "./config.ts";
  */
 export declare const NO_KEY = "agent-core";
 /**
- * Zero, less, or absent means no limit, which the SDK spells as `undefined`.
+ * An endpoint's request timeout in the SDK's spelling: milliseconds, and `undefined` for no limit.
  *
- * @param config Read for `requestTimeoutSeconds` alone.
+ * @param config - Read for `requestTimeoutSeconds` alone. Zero, less, or absent means no limit.
+ * @returns The request timeout in milliseconds, or `undefined` for no limit.
  */
-export declare const timeoutMs: (config: Pick<Endpoint, "requestTimeoutSeconds">) => number | undefined;
+export declare const timeoutMs: (config: Pick<Endpoint, 'requestTimeoutSeconds'>) => number | undefined;
+/**
+ * How long to wait out a model that is still loading, in milliseconds — `undefined` where the
+ * config has no opinion, and zero where it says not to wait at all.
+ *
+ * @param config - Read for `loadingTimeoutSeconds` alone. Zero or less is no wait.
+ * @returns Milliseconds: `undefined` only where the field is absent, and zero where it is zero or
+ * less.
+ *
+ * @remarks
+ * Zero rather than the SDK's `undefined` for "no wait", because here absent already means
+ * something else: `runTurn`'s own default.
+ */
+export declare const loadingMs: (config: Pick<RetryPolicy, 'loadingTimeoutSeconds'>) => number | undefined;
 /** What the client pool is held to across a process. Every field optional; see `configureClients`. */
 export interface ClientPoolOptions {
     /** How many endpoints' clients are kept at once. The least recently asked for goes first. */
@@ -27,6 +41,13 @@ export interface ClientPoolOptions {
  * Changes what the client pool is held to, for a process whose endpoints are not shaped like the
  * deployments these defaults were chosen for.
  *
+ * @param [options] - The bounds to change. A field left out — or given anything that is not a number
+ * above zero — keeps what it has, so a half-built config narrows nothing. `Infinity` is a number
+ * above zero: as `maxClients` it lifts the bound, and as `listingMissMs` a miss is never asked
+ * about again until `resetClients`.
+ * @returns Everything in force afterwards, including what this call did not change.
+ *
+ * @remarks
  * One setting per runtime for the same reason `configureEvents` is: the pool is one thing per
  * runtime, and its size is a deployment's setting, said once at startup. A multi-tenant host
  * keying on a key per user raises `maxClients` so its tenants stop evicting each other's
@@ -36,12 +57,6 @@ export interface ClientPoolOptions {
  * A `maxClients` below the pool's current size evicts down to it at once, least recently asked
  * for first, as the next `getClient` would have. A shorter `listingMissMs` applies to misses
  * already remembered, since each is a timestamp compared against it when read.
- *
- * @param options The bounds to change. A field left out — or given anything that is not a number
- * above zero — keeps what it has, so a half-built config narrows nothing. `Infinity` is a number
- * above zero: as `maxClients` it lifts the bound, and as `listingMissMs` a miss is never asked
- * about again until `resetClients`.
- * @returns Everything in force afterwards, including what this call did not change.
  */
 export declare function configureClients(options?: ClientPoolOptions): Required<ClientPoolOptions>;
 /** How many idle windows the first chunk gets when `firstTokenSeconds` is not given. */
@@ -49,12 +64,19 @@ export declare const FIRST_TOKEN_FACTOR = 5;
 /**
  * The wait for a streamed turn's first chunk, in the SDK's spelling: `undefined` is no limit.
  *
- * @param config Read for `firstTokenSeconds`, and `requestTimeoutSeconds` where that is absent.
+ * @param config - Read for `firstTokenSeconds`, and `requestTimeoutSeconds` where that is absent.
+ * @returns Milliseconds. `firstTokenSeconds` where it is given, zero or less being no limit;
+ * otherwise `FIRST_TOKEN_FACTOR` request timeouts, and no limit where the request has none.
  */
-export declare const firstTokenMs: (config: Pick<Endpoint, "requestTimeoutSeconds" | "firstTokenSeconds">) => number | undefined;
+export declare const firstTokenMs: (config: Pick<Endpoint, 'requestTimeoutSeconds' | 'firstTokenSeconds'>) => number | undefined;
 /**
  * The client for an endpoint, built once and kept.
  *
+ * @param config - Where to send requests and how long to wait. An absent `apiKey` becomes `NO_KEY`.
+ * @returns The pooled client: the same object for the same base URL, key and timeout, until it is
+ * evicted or `resetClients` runs. Asking for it makes it the last in line to be evicted.
+ *
+ * @remarks
  * Pooled on the three fields that change how a request is sent, so agents sharing a server share
  * a connection and agents on different servers never share a client.
  *
@@ -64,13 +86,12 @@ export declare const firstTokenMs: (config: Pick<Endpoint, "requestTimeoutSecond
  * connection pools rather than sharing them and holding every one of them — `maxClients` keeps
  * that from being unbounded, and it is the point at which a client of your own, built and held
  * per tenant, is the better answer than this.
- *
- * @param config Where to send requests and how long to wait. An absent `apiKey` becomes `NO_KEY`.
  */
 export declare function getClient(config: Endpoint): OpenAI;
 /**
  * A model an endpoint offers, and what it says the model will read. Zero means it did not say.
  *
+ * @remarks
  * The number is whatever the listing carried, which from llama.cpp is the trained window rather
  * than the served one; `contextLimitFor` is the lookup that knows the difference.
  */
@@ -82,6 +103,13 @@ export interface ModelInfo {
  * What counts as one endpoint, everywhere in this package that has to remember something about
  * one — the model listings, `capabilities`, and the no-thinking hints in `side-task`.
  *
+ * @param config - Read for `baseUrl` and `apiKey` alone, and the key is optional here where
+ * `Endpoint` requires it — `capabilitiesFor` is handed a URL and maybe a key rather than a whole
+ * config, and absent and empty already mean the same thing. The timeout is deliberately not in
+ * it; see `listings`.
+ * @returns The URL and the key as one JSON string, the key in the clear.
+ *
+ * @remarks
  * The URL and the key together, because the key is part of what is on the other end rather than
  * only how it is paid for: a router is free to send two keys to two different backends, and then
  * what one of them refused is not a fact about the other. Absent reads as `NO_KEY`, so an
@@ -91,34 +119,41 @@ export interface ModelInfo {
  * is impossible in a URL or a key, and two endpoints must never collide on one entry. A host
  * keeping its own per-endpoint state keys it on this rather than on a copy of it, so the two
  * cannot drift apart. It holds the key in the clear; `endpointId` is the one to write down.
+ */
+export declare const endpointKey: (config: EndpointIdentity) => string;
+/**
+ * One model on one endpoint, as every per-model cache keys it: stringified, so neither half runs
+ * into the other.
  *
- * @param config Read for `baseUrl` and `apiKey` alone, and the key is optional here where
- * `Endpoint` requires it — `capabilitiesFor` is handed a URL and maybe a key rather than a whole
- * config, and absent and empty already mean the same thing. The timeout is deliberately not in
- * it; see `listings`.
+ * @param endpoint - Whatever the cache names an endpoint by — `endpointKey` here, `endpointId`
+ * where the key may be written down.
+ * @param model - The model's name as the endpoint knows it.
+ * @returns The pair as a JSON array, which `JSON.parse` takes apart again.
  */
-export declare const endpointKey: (config: {
-    baseUrl: string;
-    apiKey?: string;
-}) => string;
+export declare const modelKey: (endpoint: string, model: string) => string;
 /**
  * `endpointKey` hashed, for the remembered facts that can leave the process.
  *
+ * @param config - Read for `baseUrl` and `apiKey` alone, as `endpointKey` reads it.
+ * @returns The digest of that endpoint's `endpointKey`: the same for the same URL and key in any
+ * process, and no key to be read out of it.
+ *
+ * @remarks
  * What an endpoint refused is exported by `exportCapabilities` to be written into a settings row
  * or a file, and a key inside that blob is a credential copied somewhere nobody meant to keep one.
  * A digest identifies the same endpoint on the next boot without saying what the key was, and it
  * is how a host finds its own endpoint's entry in a `CapabilitySnapshot`.
- *
- * @param config Read for `baseUrl` and `apiKey` alone, as `endpointKey` reads it.
  */
-export declare const endpointId: (config: {
-    baseUrl: string;
-    apiKey?: string;
-}) => string;
+export declare const endpointId: (config: EndpointIdentity) => string;
 /**
  * The window a local server's own API says it is serving a model in, for the servers whose
  * listing does not say.
  *
+ * @param config - The endpoint, plus the model whose window is wanted.
+ * @returns The window in tokens, or zero where none was found. Never rejects: a server that could
+ * not be reached answers zero too.
+ *
+ * @remarks
  * llama.cpp reports it on `/props` as `default_generation_settings.n_ctx`, per slot, and LM
  * Studio on `/api/v0/models` as `loaded_context_length` while the model is loaded. Both differ
  * from the trained window in the case that matters, a model started in a smaller one than it was
@@ -131,8 +166,6 @@ export declare const endpointId: (config: {
  * other error. A server that could not be reached is not remembered at all.
  *
  * The listing is not read here; `contextLimitFor` reads it first and comes here after.
- *
- * @param config The endpoint, plus the model whose window is wanted.
  */
 export declare function servedWindow(config: Endpoint & {
     model: string;
@@ -140,12 +173,19 @@ export declare function servedWindow(config: Endpoint & {
 /**
  * Asks an endpoint what it serves, and remembers the answer.
  *
- * @param config The endpoint to ask. Remembered per base URL and key, not per model.
+ * @param config - The endpoint to ask. Remembered per base URL and key, not per model.
+ * @returns The models in order of id, whatever order the endpoint listed them in.
  */
 export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
 /**
  * How much a model will read, in tokens. Zero means nobody knows.
  *
+ * @param config - The endpoint, plus the model whose window is wanted.
+ * @param [declared] - The operator's own number. Above zero it wins and the endpoint is not asked.
+ * @returns The window in tokens, or zero. Never rejects: a listing or a native route that failed
+ * is an unknown window.
+ *
+ * @remarks
  * `declared` is the operator's own number, and it wins outright: an endpoint can report the
  * window a model was *built* with while serving it in a much smaller one — llama.cpp will
  * happily load a 256k model at `-c 16384` and go on listing it as 256k — and a run refused on
@@ -163,9 +203,6 @@ export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
  * are two more requests that a server stating its window in the listing never needed. Asked
  * first, they were also asked again every `listingMissMs` for the life of the process on a server
  * whose `/props` answers without a window, by any host that sizes the window per turn.
- *
- * @param config The endpoint, plus the model whose window is wanted.
- * @param declared The operator's own number. Above zero it wins and the endpoint is not asked.
  */
 export declare function contextLimitFor(config: Endpoint & {
     model: string;
@@ -175,3 +212,35 @@ export declare function contextLimitFor(config: Endpoint & {
  * tests, and for a settings change under test.
  */
 export declare function resetClients(): void;
+/**
+ * A base URL as two settings rows would agree on it: trimmed, without the trailing slash.
+ *
+ * @param a - The URL as one row has it.
+ * @param b - The URL as the other has it.
+ * @returns `true` where the two differ in nothing but surrounding whitespace and trailing slashes.
+ * Case counts, and so does a `/v1`.
+ */
+export declare const sameUrl: (a: string, b: string) => boolean;
+/**
+ * The key to send, where an endpoint may inherit one from the settings it overrides.
+ *
+ * @param own - The endpoint as the agent or profile states it. Its own key always wins. An empty or
+ * absent `baseUrl` is one that inherits the endpoint too.
+ * @param [inherited] - The settings it overrides. Absent treats `own` as the configured endpoint, so
+ * only its key and the environment's are in play.
+ * @param [env] - Where `OPENAI_API_KEY` is read from.
+ * @returns The key, never empty: `own`'s, else `NO_KEY` for an endpoint other than the inherited
+ * one, else the inherited key, then the environment's, then `NO_KEY`.
+ *
+ * @remarks
+ * A credential issued for one endpoint has no business being posted to another. A profile that
+ * names its own `baseUrl` and no key of its own is sent `NO_KEY` — not the operator's key, and
+ * not `$OPENAI_API_KEY` — because "I pointed an agent at a friend's server and it sent my OpenAI
+ * key" is not a mistake worth being able to make, and a local server wants no key anyway. One on
+ * the same endpoint inherits the key as it inherits everything else, and the environment is the
+ * last word on the endpoint that was configured rather than overridden.
+ */
+export declare function resolveApiKey(own: {
+    baseUrl?: string;
+    apiKey?: string;
+}, inherited?: EndpointIdentity, env?: Record<string, string | undefined>): string;