@cubicecho/agent-core 3.0.0 → 4.1.0

package/README.md

@@ -299,6 +299,23 @@ neither native route gives a number. A server with neither route is latched and
 `/api/v0/models` is also dropped on its own: for the life of the process once it answers 404, 405
 or 501, and for `listingMissMs` after any other error.
 
+A host that sizes the window before each run passes the run's signal as the third argument, so a
+stopped run does not wait on the lookup:
+
+```ts
+const contextLimit = await contextLimitFor({ ...settings, model }, settings.contextLength, { signal });
+```
+
+It rejects with the signal's reason, closes the request it had open, and remembers nothing of the
+lookup. Nothing else makes it reject. `listModels` and `servedWindow` take the same option.
+
+The lookup is also bounded on its own, at ten seconds across the listing and the native routes
+together, or at the endpoint's request timeout where that is shorter. `requestTimeoutSeconds` is
+how long to wait for a model to speak, and an endpoint that accepts the connection and then says
+nothing would otherwise hold the lookup for that long, or for ever where there is none. Past the
+bound `contextLimitFor` answers zero, as it does for a server it could not reach, and
+`listModels` rejects with a `TimeoutError`.
+
 A top-level listing key is trusted without a second opinion, so on a server that puts a trained
 window there, pass `contextLength`. Ollama reports no window on any route this reads, and truncates
 an over-long prompt rather than refusing it, so on Ollama pass `contextLength` or there is no guard
@@ -703,7 +720,7 @@ try {
       store.add(sessionId, turn?.reasoning ? { ...message, reasoning_content: turn.reasoning } : message),
   });
 } catch (error) {
-  const run = failedRun(error); // messages, usage, toolCalls, loaded, used — or undefined
+  const run = failedRun(error); // messages, usage, toolCalls, loaded, used, preselected — or undefined
   if (run) await store.keep(sessionId, { usage: run.usage, loaded: run.loaded });
   if (signal.aborted) return; // a stop, told by the signal as it always was
   if (error instanceof ContextOverflow) return compactAndRetry(run?.messages);
@@ -1195,6 +1212,18 @@ with `tasks.compaction` writing the summary and no falling back to the main mode
 are off by default: a host that already calls `preselect` or compacts in `beforeStep` is not sent
 a second request.
 
+What the loop picked it says twice. A `notice` event names the tools before the first `turn` event
+— `PRESELECTED_NOTICE` and then the names, comma-separated — and the result's `preselected` is the
+shortlist the run opened with, the host's own where it gave one and empty where nothing was picked.
+A run that fails carries it too, beside `loaded` and `used`.
+
+An empty `toolSelectModel` means no preselection, and says nothing about it. A host whose settings
+read `""` as "use the run's model" has to say so in the config it builds:
+
+```ts
+const config = { ...settings, toolSelectModel: settings.toolSelectModel || settings.model };
+```
+
 ```ts
 const result = await runAgentLoop({ config, preselect: { keywords: true }, compact: true, ... });
 ```
@@ -1225,7 +1254,8 @@ OpenRouter `:free` suffix, a typo) would otherwise fetch the listing on every ca
 same zero each time. Half a minute later it asks again, so a model pulled onto a box that has been
 up a week is still picked up without a restart.
 
-Both numbers are defaults. `configureClients` moves them for the process, the way `configureEvents`
+Both numbers are defaults, as is the ten seconds a window lookup is given
+(`lookupTimeoutMs`). `configureClients` moves them for the process, the way `configureEvents`
 and `configureHooks` do — a multi-tenant host raising the pool so tenants stop evicting each other,
 a dev box shortening the miss window so a model it has just pulled shows up sooner:
 
@@ -1245,7 +1275,8 @@ cannot drift. `endpointKey` holds the key in the clear; `endpointId`, its SHA-25
 that is safe to write down.
 
 `resetAll` drops all five, and `reset.ts` names each seam separately for a test that wants one —
-`resetCalibration` for the measured ratios.
+`resetCalibration` for the measured ratios, `resetHints` for the models that refused the
+no-thinking hints.
 
 The latches can outlive the process as well, because otherwise every restart spends one refused
 request per endpoint and model learning the same facts again. `exportCapabilities` returns every

package/dist/{compaction.d.ts → context/compaction.d.ts}

@@ -1,7 +1,7 @@
 import type OpenAI from 'openai';
-import type { Endpoint } from './config.ts';
-import { type HookContext, type HookRunner, type OnNote } from './hooks.ts';
-import { type SideTaskOptions } from './side-task.ts';
+import type { Endpoint } from '../core/config.ts';
+import { type HookContext, type HookRunner, type OnNote } from '../hooks/hooks.ts';
+import { type SideTaskOptions } from '../turn/side-task.ts';
 /**
  * Keeping a long run inside its window: stale tool results cleared, and the oldest stretch folded
  * into a summary the model writes itself.
@@ -186,7 +186,7 @@ export declare function summaryInput(plan: CompactionPlan): string;
  * @param model - The model to write it, which may be a smaller one than the run's.
  * @param [options] - Cancellation and notices, and the instruction and ceiling the summary is
  * written under.
- * @returns A function from `summaryInput`'s text to the summary. It rejects as `ask` does, and
+ * @returns A function from the text of what is being folded to the summary. It rejects as `ask` does, and
  * resolves with an empty string where the model wrote nothing.
  */
 export declare const summariser: (config: Endpoint, model: string, { system, maxTokens, ...options }?: SideTaskOptions & {
@@ -233,7 +233,7 @@ export interface CompactionRunOptions {
  *
  * @param messages - The transcript the plan was made for. Read only, and only for the hooks.
  * @param plan - What `planCompaction` returned for it.
- * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * @param summarise - Writes the summary from the text it is handed. See `summariser`. Not called
  * when a hook vetoes.
  * @param [options] - Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
  * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
@@ -292,7 +292,7 @@ export declare const requestIndex: (index: number, record?: Pick<CompactionRecor
  *
  * @param messages - The transcript the plan was made for. Not written to.
  * @param plan - What `planCompaction` returned for it.
- * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * @param summarise - Writes the summary from the text it is handed. See `summariser`. Not called
  * when a hook vetoes.
  * @param [options] - Hooks to tell and whether the window is already past. See
  * `CompactionRunOptions`.

package/dist/{compaction.js → context/compaction.js}

@@ -1,9 +1,9 @@
-import { HookEvent } from './hook-events.js';
-import { consult, notify, textOf, turnMessages } from './hooks.js';
-import { ask } from './side-task.js';
-import { messageTokens } from './tokens.js';
-import { holdsDefinitions } from './tool-loading.js';
-import { FUNCTION_TOOL, Role } from './wire.js';
+import { HookEvent } from '../hooks/hook-events.js';
+import { consult, notify, textOf, turnMessages, } from '../hooks/hooks.js';
+import { holdsDefinitions } from '../tools/tool-loading.js';
+import { ask } from '../turn/side-task.js';
+import { messageTokens } from '../wire/tokens.js';
+import { FUNCTION_TOOL, Role } from '../wire/wire.js';
 /** The fraction of the window in use before a summary is worth its own round trip. */
 export const COMPACT_AT = 0.75;
 /** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
@@ -252,7 +252,7 @@ export function summaryInput(plan) {
  * @param model - The model to write it, which may be a smaller one than the run's.
  * @param [options] - Cancellation and notices, and the instruction and ceiling the summary is
  * written under.
- * @returns A function from `summaryInput`'s text to the summary. It rejects as `ask` does, and
+ * @returns A function from the text of what is being folded to the summary. It rejects as `ask` does, and
  * resolves with an empty string where the model wrote nothing.
  */
 export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = SUMMARY_TOKENS, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
@@ -261,7 +261,7 @@ export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens =
  *
  * @param messages - The transcript the plan was made for. Read only, and only for the hooks.
  * @param plan - What `planCompaction` returned for it.
- * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * @param summarise - Writes the summary from the text it is handed. See `summariser`. Not called
  * when a hook vetoes.
  * @param [options] - Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
  * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
@@ -357,7 +357,7 @@ export const requestIndex = (index, record, head = 0) => {
  *
  * @param messages - The transcript the plan was made for. Not written to.
  * @param plan - What `planCompaction` returned for it.
- * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * @param summarise - Writes the summary from the text it is handed. See `summariser`. Not called
  * when a hook vetoes.
  * @param [options] - Hooks to tell and whether the window is already past. See
  * `CompactionRunOptions`.

package/dist/{ledger.d.ts → context/ledger.d.ts}

@@ -1,6 +1,6 @@
 import type OpenAI from 'openai';
-import type { TurnUsage } from './stream.ts';
-import { type TokenEstimateOptions } from './tokens.ts';
+import type { TurnUsage } from '../wire/stream.ts';
+import { type TokenEstimateOptions } from '../wire/tokens.ts';
 /**
  * What stretches of a transcript cost, read off the prompt counts the server already reported.
  *

package/dist/{ledger.js → context/ledger.js}

@@ -1,6 +1,6 @@
-import { CacheBreakReason } from './stream.js';
-import { messageChars, messageTokens } from './tokens.js';
-import { Role } from './wire.js';
+import { CacheBreakReason } from '../wire/stream.js';
+import { messageChars, messageTokens } from '../wire/tokens.js';
+import { Role } from '../wire/wire.js';
 /**
  * Whether two messages say the same thing, by identity first since most of a transcript is.
  *

package/dist/{guards.d.ts → core/guards.d.ts}

@@ -37,12 +37,11 @@ interface Lookup<K, V> {
  *
  * @param map - Where to look. Gains an entry on a miss, which is the point of calling this.
  * @param key - What to look under.
- * @param create - Builds the value on a miss, and is not called on a hit. A stored `undefined`
- * reads as a miss, so one that returns it is called every time.
+ * @param create - Builds the value on a miss, and is not called on a hit.
  * @returns What the map holds under the key afterwards: the held value itself on a hit, what
  * `create` returned on a miss.
  */
-export declare function getOrCreate<K, V>(map: Lookup<K, V>, key: K, create: () => V): V;
+export declare function getOrCreate<K, V extends {}>(map: Lookup<K, V>, key: K, create: () => V): V;
 /**
  * A count and its noun, plural unless the count is one: `1 tool`, `3 tools`.
  *

package/dist/{guards.js → core/guards.js}

@@ -32,8 +32,7 @@ export const isPositive = (value) => typeof value === 'number' && value > 0;
  *
  * @param map - Where to look. Gains an entry on a miss, which is the point of calling this.
  * @param key - What to look under.
- * @param create - Builds the value on a miss, and is not called on a hit. A stored `undefined`
- * reads as a miss, so one that returns it is called every time.
+ * @param create - Builds the value on a miss, and is not called on a hit.
  * @returns What the map holds under the key afterwards: the held value itself on a hit, what
  * `create` returned on a miss.
  */

package/dist/{scope.d.ts → core/scope.d.ts}

@@ -5,7 +5,7 @@
  * A map rather than a record of named caches, so a module that grows a cache declares it where
  * it is used and `runtime.ts` does not have to hear about it.
  */
-export type Scope = Map<symbol, unknown>;
+export type Scope = Map<symbol, NonNullable<unknown>>;
 /** The default runtime's scope: what the top-level functions use when no runtime is running. */
 export declare const rootScope: Scope;
 /**
@@ -23,7 +23,7 @@ export declare const currentScope: () => Scope;
  */
 export declare const inScope: <T>(scope: Scope, fn: () => T) => T;
 /** One module's state, read from whichever scope is current. See `scoped`. */
-export interface Scoped<T> {
+export interface Scoped<T extends {}> {
     /** The current scope's copy, made on first use. */
     (): T;
     /** Drops the current scope's copy, so the next read makes a fresh one. */
@@ -41,7 +41,7 @@ export interface Scoped<T> {
  * and each use reads `cache()`. The copy is made lazily, so a runtime pays only for the modules
  * it touches.
  */
-export declare function scoped<T>(create: () => T): Scoped<T>;
+export declare function scoped<T extends {}>(create: () => T): Scoped<T>;
 /**
  * Writes what a caller gave onto the settings in force, field by field, skipping what is unusable.
  *

package/dist/{calibration.js → endpoint/calibration.js}

@@ -1,7 +1,7 @@
-import { getOrCreate } from './guards.js';
-import { scoped } from './scope.js';
-import { CHARS_PER_TOKEN, requestChars, toolsChars } from './tokens.js';
-import { PartType } from './wire.js';
+import { getOrCreate } from '../core/guards.js';
+import { scoped } from '../core/scope.js';
+import { CHARS_PER_TOKEN, requestChars, toolsChars } from '../wire/tokens.js';
+import { PartType } from '../wire/wire.js';
 /**
  * How many characters a token is worth on one model, learned from what its endpoint reports.
  *

package/dist/{capabilities.d.ts → endpoint/capabilities.d.ts}

@@ -1,5 +1,5 @@
-import type { EndpointIdentity } from './config.ts';
-import type { Produced } from './stream.ts';
+import type { EndpointIdentity } from '../core/config.ts';
+import type { Produced } from '../wire/stream.ts';
 /**
  * What an endpoint turned out not to support, and answering it when it says so.
  *

package/dist/{capabilities.js → endpoint/capabilities.js}

@@ -1,8 +1,8 @@
+import { getOrCreate } from '../core/guards.js';
+import { scoped } from '../core/scope.js';
+import { errorMessage } from '../wire/errors.js';
 import { endpointId } from './client.js';
-import { errorMessage } from './errors.js';
-import { getOrCreate } from './guards.js';
 import { isGrammarError } from './schema-compat.js';
-import { scoped } from './scope.js';
 /**
  * A model's on/off flags as it starts out, every one optimistic.
  *

package/dist/{client.d.ts → endpoint/client.d.ts}

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { Endpoint, EndpointIdentity, RetryPolicy } from './config.ts';
+import type { Endpoint, EndpointIdentity, RetryPolicy } from '../core/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
@@ -36,6 +36,11 @@ export interface ClientPoolOptions {
      * missing route — is taken at its word before the endpoint is asked again.
      */
     listingMissMs?: number;
+    /**
+     * How long, in milliseconds, one `contextLimitFor`, `servedWindow` or `listModels` may take over
+     * all of its requests. An endpoint's own request timeout still applies where it is shorter.
+     */
+    lookupTimeoutMs?: number;
 }
 /**
  * Changes what the client pool is held to, for a process whose endpoints are not shaped like the
@@ -43,8 +48,8 @@ export interface ClientPoolOptions {
  *
  * @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`.
+ * above zero: as `maxClients` it lifts the bound, as `listingMissMs` a miss is never asked about
+ * again until `resetClients`, and as `lookupTimeoutMs` a lookup waits out the request timeout.
  * @returns Everything in force afterwards, including what this call did not change.
  *
  * @remarks
@@ -145,13 +150,19 @@ export declare const modelKey: (endpoint: string, model: string) => string;
  * is how a host finds its own endpoint's entry in a `CapabilitySnapshot`.
  */
 export declare const endpointId: (config: EndpointIdentity) => string;
+/** What a lookup takes besides the endpoint: `listModels`, `servedWindow` and `contextLimitFor`. */
+export interface LookupOptions {
+    /** Abandons the lookup, which then rejects with the signal's reason and remembers nothing. */
+    signal?: AbortSignal;
+}
 /**
  * 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.
+ * @param [options] - Cancellation. See `LookupOptions`.
+ * @returns The window in tokens, or zero where none was found. Rejects only with the reason of
+ * `options.signal`: 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
@@ -169,21 +180,26 @@ export declare const endpointId: (config: EndpointIdentity) => string;
  */
 export declare function servedWindow(config: Endpoint & {
     model: string;
-}): Promise<number>;
+}, { signal }?: LookupOptions): Promise<number>;
 /**
  * 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.
- * @returns The models in order of id, whatever order the endpoint listed them in.
+ * @param [options] - Cancellation. See `LookupOptions`.
+ * @returns The models in order of id, whatever order the endpoint listed them in. Rejects with the
+ * reason of `options.signal` where that stopped it, a `TimeoutError` at `lookupTimeoutMs`, and the
+ * request's own error otherwise.
  */
-export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
+export declare function listModels(config: Endpoint, { signal }?: LookupOptions): 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.
+ * @param [options] - Cancellation. See `LookupOptions`.
+ * @returns The window in tokens, or zero. Rejects only with the reason of `options.signal`: a
+ * listing or a native route that failed, or the lookup running out of `lookupTimeoutMs`, is an
+ * unknown window.
  *
  * @remarks
  * `declared` is the operator's own number, and it wins outright: an endpoint can report the
@@ -206,7 +222,7 @@ export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
  */
 export declare function contextLimitFor(config: Endpoint & {
     model: string;
-}, declared?: number): Promise<number>;
+}, declared?: number, { signal }?: LookupOptions): Promise<number>;
 /**
  * Forgets every cached client and listing, and puts `configureClients` back to the defaults. For
  * tests, and for a settings change under test.

package/dist/{client.js → endpoint/client.js}

@@ -1,9 +1,9 @@
 import OpenAI from 'openai';
-import { digestOf } from './digest.js';
-import { byCodeUnit, isPositive } from './guards.js';
-import { MS_PER_SECOND } from './platform.js';
-import { assignSettings, scoped } from './scope.js';
-import { HttpStatus } from './wire.js';
+import { digestOf } from '../core/digest.js';
+import { byCodeUnit, isPositive } from '../core/guards.js';
+import { MS_PER_SECOND } from '../core/platform.js';
+import { assignSettings, scoped } from '../core/scope.js';
+import { HttpStatus } from '../wire/wire.js';
 /**
  * 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
@@ -73,10 +73,19 @@ const clients = scoped(() => new Map());
 const MAX_CLIENTS = 32;
 /** How long a model an endpoint did not list stays unlisted before it is asked about again. */
 const LISTING_MISS_MS = 30_000;
+/**
+ * How long a window lookup may take in all, until `configureClients` moves it.
+ *
+ * @remarks
+ * Its own number because `requestTimeoutSeconds` is how long to wait for a model to speak, and a
+ * listing that has not answered in ten seconds is not going to.
+ */
+const LOOKUP_TIMEOUT_MS = 10_000;
 /** The numbers this module was written with. */
 const CLIENT_DEFAULTS = {
     maxClients: MAX_CLIENTS,
     listingMissMs: LISTING_MISS_MS,
+    lookupTimeoutMs: LOOKUP_TIMEOUT_MS,
 };
 /** What is in force now. Read where it is used, so a change applies from the next call. */
 const poolLimits = scoped(() => ({ ...CLIENT_DEFAULTS }));
@@ -100,8 +109,8 @@ const evict = () => {
  *
  * @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`.
+ * above zero: as `maxClients` it lifts the bound, as `listingMissMs` a miss is never asked about
+ * again until `resetClients`, and as `lookupTimeoutMs` a lookup waits out the request timeout.
  * @returns Everything in force afterwards, including what this call did not change.
  *
  * @remarks
@@ -339,8 +348,20 @@ const refused = (endpoint) => {
     const refusal = refusals().get(endpoint);
     return refusal !== undefined && (refusal.gone || Date.now() - refusal.at < poolLimits().listingMissMs);
 };
-/** How long a probe may take before the window is taken from the listing instead. */
-const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * The signal every request of one lookup is made under, so the lookup is bounded as a whole.
+ *
+ * @param config - Read for `requestTimeoutSeconds`, which bounds the lookup where it is shorter
+ * than `lookupTimeoutMs`.
+ * @param [signal] - The caller's own, which aborts the lookup with its reason.
+ * @returns A signal that fires with a `TimeoutError` at the bound or with the caller's reason,
+ * whichever is first. Never fires where neither is set.
+ */
+const lookupSignal = (config, signal) => {
+    const boundMs = Math.min(timeoutMs(config) ?? Number.POSITIVE_INFINITY, poolLimits().lookupTimeoutMs);
+    const bound = Number.isFinite(boundMs) ? [AbortSignal.timeout(boundMs)] : [];
+    return AbortSignal.any([...bound, ...(signal ? [signal] : [])]);
+};
 /**
  * The server root behind an OpenAI-compatible base URL, which is where the native APIs live.
  *
@@ -358,9 +379,9 @@ const NOT_THERE = new Set([
 /**
  * Asks one native endpoint.
  *
- * @param config - The endpoint. Its key goes as a bearer token where it has one, and its request
- * timeout bounds the wait — `PROBE_TIMEOUT_MS` where it has none.
+ * @param config - The endpoint. Its key goes as a bearer token where it has one.
  * @param path - The route and its query, from the server root rather than from the base URL.
+ * @param within - The lookup's signal. Fired, the request throws as an unreachable server does.
  * @returns How the server answered, with `body` only for a 2xx that parsed as JSON.
  *
  * @remarks
@@ -368,11 +389,11 @@ const NOT_THERE = new Set([
  * without the route; `body` is absent for both, and for a 2xx that was not JSON. A server that
  * could not be reached throws.
  */
-async function probe(config, path) {
+async function probe(config, path, within) {
     const apiKey = config.apiKey || undefined;
     const response = await fetch(`${rootOf(config.baseUrl)}${path}`, {
         headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {},
-        signal: AbortSignal.timeout(timeoutMs(config) ?? PROBE_TIMEOUT_MS),
+        signal: within,
     });
     if (!response.ok) {
         return { failed: true, missing: NOT_THERE.has(response.status) };
@@ -389,8 +410,9 @@ async function probe(config, path) {
  * 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.
+ * @param [options] - Cancellation. See `LookupOptions`.
+ * @returns The window in tokens, or zero where none was found. Rejects only with the reason of
+ * `options.signal`: 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
@@ -406,7 +428,19 @@ async function probe(config, path) {
  *
  * The listing is not read here; `contextLimitFor` reads it first and comes here after.
  */
-export async function servedWindow(config) {
+export async function servedWindow(config, { signal } = {}) {
+    const window = await readServed(config, lookupSignal(config, signal));
+    signal?.throwIfAborted();
+    return window;
+}
+/**
+ * `servedWindow` under a lookup's signal, which `contextLimitFor` shares with its listing.
+ *
+ * @param config - The endpoint, plus the model whose window is wanted.
+ * @param within - The lookup's signal. Fired, the answer is zero and nothing is remembered.
+ * @returns The window in tokens, or zero where none was found. Never rejects.
+ */
+async function readServed(config, within) {
     const endpoint = endpointKey(config);
     if (unserved().has(endpoint)) {
         return 0;
@@ -419,12 +453,12 @@ export async function servedWindow(config) {
     let window = 0;
     try {
         // Named, for a llama.cpp router serving several models; a single-model server ignores it.
-        const props = await probe(config, `/props?model=${encodeURIComponent(config.model)}`);
+        const props = await probe(config, `/props?model=${encodeURIComponent(config.model)}`, within);
         const settings = props.body?.default_generation_settings;
         window = positive(settings?.n_ctx);
         if (!window) {
             if (!refused(endpoint)) {
-                const lmstudio = await probe(config, '/api/v0/models');
+                const lmstudio = await probe(config, '/api/v0/models', within);
                 if (lmstudio.failed) {
                     refusals().set(endpoint, { at: Date.now(), gone: lmstudio.missing });
                 }
@@ -453,10 +487,29 @@ export async function servedWindow(config) {
  * 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.
- * @returns The models in order of id, whatever order the endpoint listed them in.
+ * @param [options] - Cancellation. See `LookupOptions`.
+ * @returns The models in order of id, whatever order the endpoint listed them in. Rejects with the
+ * reason of `options.signal` where that stopped it, a `TimeoutError` at `lookupTimeoutMs`, and the
+ * request's own error otherwise.
  */
-export async function listModels(config) {
-    const { data } = await getClient(config).models.list();
+export function listModels(config, { signal } = {}) {
+    return readListing(config, lookupSignal(config, signal));
+}
+/**
+ * `listModels` under a lookup's signal, which `contextLimitFor` shares with the native routes.
+ *
+ * @param config - The endpoint to ask.
+ * @param within - The lookup's signal. Fired, the listing rejects with its reason.
+ * @returns The models in order of id. A listing that fails leaves the last one remembered.
+ */
+async function readListing(config, within) {
+    const { data } = await getClient(config)
+        .models.list({ signal: within })
+        .catch((error) => {
+        // The SDK throws an abort error of its own, whatever the signal's reason was.
+        within.throwIfAborted();
+        throw error;
+    });
     const trained = new Set();
     const models = [];
     for (const model of data) {
@@ -477,8 +530,10 @@ export async function listModels(config) {
  *
  * @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.
+ * @param [options] - Cancellation. See `LookupOptions`.
+ * @returns The window in tokens, or zero. Rejects only with the reason of `options.signal`: a
+ * listing or a native route that failed, or the lookup running out of `lookupTimeoutMs`, is an
+ * unknown window.
  *
  * @remarks
  * `declared` is the operator's own number, and it wins outright: an endpoint can report the
@@ -499,11 +554,13 @@ export async function listModels(config) {
  * 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.
  */
-export async function contextLimitFor(config, declared = 0) {
+export async function contextLimitFor(config, declared = 0, { signal } = {}) {
     if (declared > 0) {
         return declared;
     }
     const key = endpointKey(config);
+    // One signal for the listing and the native routes, so three silent requests wait once.
+    const within = lookupSignal(config, signal);
     const listed = () => listings()
         .get(key)
         ?.find((model) => model.id === config.model);
@@ -523,7 +580,8 @@ export async function contextLimitFor(config, declared = 0) {
         if (asked === undefined || Date.now() - asked >= poolLimits().listingMissMs) {
             // A failure is not remembered: an endpoint that was down when the last run started is not
             // an endpoint with no models, and a window nobody could ask about is not a failed run.
-            const answered = await listModels(config).then(() => true, () => false);
+            const answered = await readListing(config, within).then(() => true, () => false);
+            signal?.throwIfAborted();
             // Recorded where the endpoint was actually asked, and only there. Stamping it on the calls
             // that skipped the request would push the deadline out ahead of any caller polling faster
             // than the interval, which is a memory that never expires rather than one that expires in
@@ -545,7 +603,8 @@ export async function contextLimitFor(config, declared = 0) {
     if (fromListing > 0 && !trainedOnly().get(key)?.has(config.model)) {
         return fromListing;
     }
-    const window = await servedWindow(config);
+    const window = await readServed(config, within);
+    signal?.throwIfAborted();
     return window > 0 ? window : fromListing;
 }
 /**

package/dist/{schema-compat.js → endpoint/schema-compat.js}

@@ -1,5 +1,5 @@
-import { getOrCreate, isRecord } from './guards.js';
-import { FUNCTION_TOOL, SchemaType } from './wire.js';
+import { getOrCreate, isRecord } from '../core/guards.js';
+import { FUNCTION_TOOL, SchemaType } from '../wire/wire.js';
 /** Lookahead and lookbehind: `(?=`, `(?!`, `(?<=`, `(?<!`. */
 const LOOKAROUND = /\(\?<?[=!]/;
 const PRIMITIVES = new Set(Object.values(SchemaType));

package/dist/{hooks.js → hooks/hooks.js}

@@ -1,10 +1,10 @@
-import { digestOf } from './digest.js';
-import { errorMessage } from './errors.js';
-import { isPositive } from './guards.js';
+import { digestOf } from '../core/digest.js';
+import { isPositive } from '../core/guards.js';
+import { assignSettings, scoped } from '../core/scope.js';
+import { errorMessage } from '../wire/errors.js';
+import { CHARS_PER_TOKEN, estimateTokens } from '../wire/tokens.js';
+import { PartType, Role } from '../wire/wire.js';
 import { INJECT_EVENTS } from './hook-events.js';
-import { assignSettings, scoped } from './scope.js';
-import { CHARS_PER_TOKEN, estimateTokens } from './tokens.js';
-import { PartType, Role } from './wire.js';
 /**
  * The most context all of a request's hooks add between them by default, in estimated tokens.
  *