@cubicecho/agent-core 2.25.1 → 4.0.0

package/README.md

@@ -316,7 +316,7 @@ and wrong for what a tool-using run is made of — JSON schemas and tool results
 three characters a token — so a request the guard let through was refused anyway. The divisor is
 learned instead. Every turn `runTurn` answers comes back with the endpoint's exact prompt count for a
 body whose characters were already counted, and `calibrate` keeps that ratio per endpoint and model;
-the next request to the same model is sized by `charsPerTokenFor`, which is `CHARS_PER_TOKEN` (4)
+the next request to the same model is sized by `charsPerTokenFor`, which is four
 until a turn has reported one. It is the highest of the model's last four readings, which is the
 lowest token count: a count that comes out high refuses a run that would have fit, and one that
 comes out low only costs the round trip the guard was saving. A reading from a request carrying an
@@ -349,7 +349,7 @@ large for gpt-4o ... on tokens per min"); that is ruled out and waited through a
 A server still loading the model is waited for on its own clock. llama.cpp answers 503 `Loading
 model` (type `unavailable_error`) until the weights are mapped, thirty to ninety seconds for a large
 model from a cold cache, and a router build says the same while it swaps models; `backoffMs` would
-give up inside fifteen. `isModelLoading` recognises it, and `runTurn` polls every `LOADING_POLL_MS`
+give up inside fifteen. `isModelLoading` recognises it, and `runTurn` polls every three seconds
 for up to `loadingTimeoutMs` (two minutes by default, zero to turn it off) without spending
 `maxRetries`, with one notice at the start. `runAgentLoop` reads it as `loadingTimeoutSeconds` off
 the config. A 503 that says nothing about loading stays on the ordinary backoff.
@@ -985,7 +985,7 @@ not turn the backlog off. `resetEvents` (and `resetAll`) puts the defaults back,
 is not the next one's.
 
 `expandNames`, `carryOver`, `preselection`, `preselectInput` and `preselectSystem` take their caps
-the same way — as a last argument defaulting to `MAX_PER_LOAD` or `MAX_CARRIED`. A resolution
+the same way — as a last argument, which is 12 tools a load and 16 carried unless given. A resolution
 carries the cap it was held to, so `loadResult` tells the model the number it was actually
 measured against rather than the module's own.
 
@@ -1245,7 +1245,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/calibration.d.ts

@@ -1,13 +1,13 @@
 import type OpenAI from 'openai';
 import type { Capabilities } from './capabilities.ts';
 /**
- * The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn
+ * The characters per token to size a request to this model with, four until a turn
  * has reported one.
  *
  * @param supports - The endpoint, as `capabilitiesFor` hands it over.
  * @param model - The name the endpoint knows the model as, as it goes in the body.
  * @returns The highest of the readings held for the model in the current runtime, or
- * `CHARS_PER_TOKEN` where it holds none.
+ * four where it holds none.
  *
  * @remarks
  * The highest of the model's last few readings rather than their mean. The estimate guards a

package/dist/calibration.js

@@ -32,13 +32,13 @@ const PLAUSIBLE = { least: 1, most: 8 };
  */
 const readings = scoped(() => new WeakMap());
 /**
- * The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn
+ * The characters per token to size a request to this model with, four until a turn
  * has reported one.
  *
  * @param supports - The endpoint, as `capabilitiesFor` hands it over.
  * @param model - The name the endpoint knows the model as, as it goes in the body.
  * @returns The highest of the readings held for the model in the current runtime, or
- * `CHARS_PER_TOKEN` where it holds none.
+ * four where it holds none.
  *
  * @remarks
  * The highest of the model's last few readings rather than their mean. The estimate guards a

package/dist/client.d.ts

@@ -66,7 +66,7 @@ export declare const FIRST_TOKEN_FACTOR = 5;
  *
  * @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.
+ * otherwise five request timeouts, and no limit where the request has none.
  */
 export declare const firstTokenMs: (config: Pick<Endpoint, 'requestTimeoutSeconds' | 'firstTokenSeconds'>) => number | undefined;
 /**

package/dist/client.js

@@ -127,7 +127,7 @@ export const FIRST_TOKEN_FACTOR = 5;
  *
  * @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.
+ * otherwise five request timeouts, and no limit where the request has none.
  */
 export const firstTokenMs = (config) => {
     if (config.firstTokenSeconds === undefined) {

package/dist/compaction.d.ts

@@ -107,7 +107,7 @@ export interface CompactionOptions {
      * The divisor the default `estimate` uses — `charsPerTokenFor` the model, for a transcript
      * weighed the way `runTurn` sizes its requests. Ignored beside an `estimate` of the caller's own.
      *
-     * @defaultValue `CHARS_PER_TOKEN`
+     * @defaultValue `4`
      */
     charsPerToken?: number;
     /**
@@ -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

@@ -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/config.d.ts

@@ -36,7 +36,7 @@ export interface Endpoint {
     /**
      * How long a streamed turn may wait for its first chunk. Zero or less is no limit.
      *
-     * @defaultValue `FIRST_TOKEN_FACTOR` times `requestTimeoutSeconds`
+     * @defaultValue Five times `requestTimeoutSeconds`
      *
      * @remarks
      * Its own number because the first wait is prefill, and on a local server prefill of a long

package/dist/continuation.d.ts

@@ -50,8 +50,8 @@ export declare const isContinuable: (turn: Turn) => boolean;
  * continuation's `finishReason` and tool calls.
  *
  * @remarks
- * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
- * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
+ * Only a turn cut off at the ceiling, with an answer begun and no tool call in it, is continued;
+ * any other comes back as it was. Content and reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
  * across the requests with `continuations` counting them. The continuation is read as starting in
  * the answer, whatever `startInReasoning` says: a template that opens a fence for a fresh reply
  * does not open one for a prefill. Its tokens reach `onOutput` as they arrive, so a watcher sees

package/dist/continuation.js

@@ -112,8 +112,8 @@ function joinUsage(first, next) {
  * continuation's `finishReason` and tool calls.
  *
  * @remarks
- * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
- * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
+ * Only a turn cut off at the ceiling, with an answer begun and no tool call in it, is continued;
+ * any other comes back as it was. Content and reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
  * across the requests with `continuations` counting them. The continuation is read as starting in
  * the answer, whatever `startInReasoning` says: a template that opens a fence for a fresh reply
  * does not open one for a prefill. Its tokens reach `onOutput` as they arrive, so a watcher sees

package/dist/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

@@ -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/index.d.ts

@@ -13,19 +13,19 @@ export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type
 export { calibrate, charsPerTokenFor, resetCalibration } from './calibration.ts';
 export { type Capabilities, capabilitiesFor, EFFORT_LADDER, EFFORT_NONE, EFFORT_OFF, effortFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from './capabilities.ts';
 export type { CatalogServer } from './catalog.ts';
-export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, type ModelInfo, NO_KEY, resetClients, resolveApiKey, servedWindow, timeoutMs, } from './client.ts';
-export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from './compaction.ts';
+export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, firstTokenMs, getClient, listModels, type ModelInfo, NO_KEY, resetClients, resolveApiKey, servedWindow, timeoutMs, } from './client.ts';
+export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, } from './compaction.ts';
 export { type AgentConfig, type Endpoint, type ModelParams, type RetryPolicy, ToolDiscovery, type ToolPolicy, } from './config.ts';
-export { type ContinueTurnOptions, continueTurn, isContinuable, } from './continuation.ts';
+export { type ContinueTurnOptions, continueTurn, } from './continuation.ts';
 export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './errors.ts';
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, RunEventKind, type RunMetrics, type RunMetricsOptions, RunOutcome, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from './events.ts';
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hook-events.ts';
 export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, type HookContext, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks.ts';
 export { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type LedgerRequest, rebaseLedger, recordRequest, type TokenLedger, tokensBetween, } from './ledger.ts';
-export { KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, type ToolMatch, } from './preselect.ts';
+export { type KeywordPreselection, type KeywordPreselectOptions, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, type ToolMatch, } from './preselect.ts';
 export { buildBody } from './request-body.ts';
 export { resetAll } from './reset.ts';
-export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, SMALLEST_LIKELY_WINDOW, sleep, } from './retry.ts';
+export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './retry.ts';
 export { preview } from './run-calls.ts';
 export { type RunTurnOptions, runTurn } from './run-turn.ts';
 export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from './runtime.ts';
@@ -35,7 +35,7 @@ export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnap
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from './spec.ts';
 export { CacheBreakReason, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './stream.ts';
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, SPLIT_OUTPUT, SPLIT_REASONING, type Split, stripThinking, THINK_FENCE, } from './thinking.ts';
-export { CHARS_PER_TOKEN, type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, toolsChars, } from './tokens.ts';
+export { type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, } from './tokens.ts';
 export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult, } from './tool-calls.ts';
-export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolOrder, } from './tool-loading.ts';
+export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolOrder, } from './tool-loading.ts';
 export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire.ts';

package/dist/index.js

@@ -12,19 +12,19 @@
 export { PRESELECT_APPEND, PRESELECT_EXCLUSIVE, runAgentLoop, } from './agent-loop.js';
 export { calibrate, charsPerTokenFor, resetCalibration } from './calibration.js';
 export { capabilitiesFor, EFFORT_LADDER, EFFORT_NONE, EFFORT_OFF, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from './capabilities.js';
-export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, resolveApiKey, servedWindow, timeoutMs, } from './client.js';
-export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from './compaction.js';
+export { configureClients, contextLimitFor, endpointId, endpointKey, firstTokenMs, getClient, listModels, NO_KEY, resetClients, resolveApiKey, servedWindow, timeoutMs, } from './client.js';
+export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, } from './compaction.js';
 export { ToolDiscovery, } from './config.js';
-export { continueTurn, isContinuable, } from './continuation.js';
+export { continueTurn, } from './continuation.js';
 export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './errors.js';
 export { configureEvents, emit, endRun, fold, history, RunEventKind, RunOutcome, resetEvents, runMetrics, watch, } from './events.js';
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hook-events.js';
 export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks.js';
 export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from './ledger.js';
-export { KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, } from './preselect.js';
+export { PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, } from './preselect.js';
 export { buildBody } from './request-body.js';
 export { resetAll } from './reset.js';
-export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, SMALLEST_LIKELY_WINDOW, sleep, } from './retry.js';
+export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './retry.js';
 export { preview } from './run-calls.js';
 export { runTurn } from './run-turn.js';
 export { createRuntime, defaultRuntime } from './runtime.js';
@@ -34,7 +34,7 @@ export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, }
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from './spec.js';
 export { CacheBreakReason, streamTurn, } from './stream.js';
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, SPLIT_OUTPUT, SPLIT_REASONING, stripThinking, THINK_FENCE, } from './thinking.js';
-export { CHARS_PER_TOKEN, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, toolsChars, } from './tokens.js';
+export { compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, } from './tokens.js';
 export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ToolArgumentsError, } from './tool-calls.js';
-export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from './tool-loading.js';
+export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from './tool-loading.js';
 export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire.js';

package/dist/preselect.d.ts

@@ -66,29 +66,6 @@ export declare const preselectInput: (catalog: CatalogServer[], prompt: string,
  * more than `maxPerLoad`. Empty where nothing resolved.
  */
 export declare function preselection(names: unknown, catalog: CatalogServer[], maxPerLoad?: number): string[];
-/**
- * The least a best match may score and still be acted on without a model.
- *
- * @remarks
- * A BM25 score, so it is read against the shape of the corpus rather than as a percentage: a
- * query term carried by half the catalogue is worth about 0.7, and one carried by a single tool
- * about 3. One at this floor is therefore "something more distinctive than a word every other
- * tool uses", which is the weakest evidence worth skipping a round trip on.
- *
- * A term is distinctive only against other terms, so a catalogue of three or four tools rarely
- * clears it. That is the right answer rather than a gap: a catalogue that small is not costing
- * enough tokens to be worth choosing from in the first place.
- */
-export declare const KEYWORD_MIN_SCORE = 1;
-/**
- * How far the best unpicked tool must fall below the last picked one for the cut to count clean.
- *
- * @remarks
- * Half. The cap is the only reason a hit is dropped, so a hit just underneath it scoring nearly
- * as much as one just above means the ranking chose arbitrarily, which is exactly the case a
- * model should be spent on.
- */
-export declare const KEYWORD_DROPOFF = 0.5;
 /** One tool's score against a request. */
 export interface ToolMatch {
     name: string;
@@ -109,19 +86,19 @@ export interface KeywordPreselectOptions {
     /**
      * The most to pick. The same cap the model is held to.
      *
-     * @defaultValue `MAX_PER_LOAD`
+     * @defaultValue `12`
      */
     maxPerLoad?: number;
     /**
      * The floor under a confident best match.
      *
-     * @defaultValue `KEYWORD_MIN_SCORE`
+     * @defaultValue `1`
      */
     minScore?: number;
     /**
      * The gap a confident cut needs.
      *
-     * @defaultValue `KEYWORD_DROPOFF`
+     * @defaultValue `0.5`
      */
     dropoff?: number;
     /**
@@ -184,7 +161,7 @@ export interface PreselectOptions {
     /**
      * The most tools the choice may name.
      *
-     * @defaultValue `MAX_PER_LOAD`
+     * @defaultValue `12`
      */
     maxPerLoad?: number;
     /**

package/dist/preselect.js

@@ -112,7 +112,7 @@ const IDF_SMOOTHING = 0.5;
  * clears it. That is the right answer rather than a gap: a catalogue that small is not costing
  * enough tokens to be worth choosing from in the first place.
  */
-export const KEYWORD_MIN_SCORE = 1;
+const KEYWORD_MIN_SCORE = 1;
 /**
  * How far the best unpicked tool must fall below the last picked one for the cut to count clean.
  *
@@ -121,7 +121,7 @@ export const KEYWORD_MIN_SCORE = 1;
  * as much as one just above means the ranking chose arbitrarily, which is exactly the case a
  * model should be spent on.
  */
-export const KEYWORD_DROPOFF = 0.5;
+const KEYWORD_DROPOFF = 0.5;
 /** The longest word `terms` leaves its trailing `s` on: `bus` and `was` are not plurals. */
 const SHORTEST_PLURAL = 3;
 /** What the preselector's reply schema is called on the wire. */

package/dist/retry.d.ts

@@ -91,7 +91,7 @@ export declare const refusesRequest: (error: unknown) => boolean;
  *
  * @remarks
  * An abort reaches a catch in two shapes. The SDK raises its own class when a request in flight is
- * cancelled, and `sleep` rejects with the signal's reason when the cancel lands between attempts.
+ * cancelled, and the wait between attempts rejects with the signal's reason when the cancel lands there.
  * A catch that knew only the first reported the second as a failure. A signal aborted with a
  * reason of the caller's own making is not recognised, since only the error is looked at: a
  * catch that holds the signal asks it as well, as `tryAsk` does.

package/dist/retry.js

@@ -135,7 +135,7 @@ export const refusesRequest = (error) => error instanceof OpenAI.APIError &&
  *
  * @remarks
  * An abort reaches a catch in two shapes. The SDK raises its own class when a request in flight is
- * cancelled, and `sleep` rejects with the signal's reason when the cancel lands between attempts.
+ * cancelled, and the wait between attempts rejects with the signal's reason when the cancel lands there.
  * A catch that knew only the first reported the second as a failure. A signal aborted with a
  * reason of the caller's own making is not recognised, since only the error is looked at: a
  * catch that holds the signal asks it as well, as `tryAsk` does.

package/dist/run-turn.d.ts

@@ -75,10 +75,10 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, 'produced'> {
      * How long to wait on a server answering that the model is still loading; zero gives up on the
      * first such answer like any other 503.
      *
-     * @defaultValue `LOADING_TIMEOUT_MS`
+     * @defaultValue `120000`
      *
      * @remarks
-     * Polled every `LOADING_POLL_MS` without spending `maxRetries`, and announced once rather than
+     * Polled every three seconds without spending `maxRetries`, and announced once rather than
      * per poll. A consumer that starts alongside its llama.cpp, or asks a router for a model it
      * has to swap in, meets this on its first request every time.
      */

package/dist/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/tokens.d.ts

@@ -13,7 +13,7 @@ export declare const CHARS_PER_TOKEN = 4;
  * vocabulary either.
  *
  * @param text - Prose or serialised JSON — both counted the same way, which is why JSON reads low.
- * @returns The length over `CHARS_PER_TOKEN`, rounded up: zero for an empty string, and one for
+ * @returns The length over four, rounded up: zero for an empty string, and one for
  * anything shorter than a token.
  *
  * @remarks
@@ -46,7 +46,7 @@ export interface TokenEstimateOptions {
      * The divisor — `charsPerTokenFor` for a model whose reported usage has calibrated it. A value
      * that is not a number above zero is ignored.
      *
-     * @defaultValue `CHARS_PER_TOKEN`
+     * @defaultValue `4`
      */
     charsPerToken?: number;
 }
@@ -72,7 +72,7 @@ export declare function toolsChars(tools: OpenAI.ChatCompletionTool[]): number;
  *
  * @param body - The request as it was sent, tools included.
  * @returns The sum of `messageChars` over the messages. The tools are not in it, whether or not
- * the body carries them; `toolsChars` counts those.
+ * the body carries them; `contextChars` counts those, under `tools`.
  *
  * @remarks
  * What calibration reads a reported prompt count against, since a ratio is only as good as the
@@ -83,7 +83,7 @@ export declare function requestChars(body: OpenAI.ChatCompletionCreateParamsStre
  * What this request will cost the window, in tokens, near enough.
  *
  * @param body - The request as it will be sent, tools included.
- * @param [options] - The divisor, `CHARS_PER_TOKEN` when none is given.
+ * @param [options] - The divisor, four when none is given.
  * @returns Whole tokens: the messages' and the tools', each rounded up on its own and added.
  *
  * @remarks
@@ -132,7 +132,7 @@ export interface ContextBreakdown {
  * that is neither that nor a `tool` message as `history`.
  *
  * @remarks
- * Exact and additive: the parts sum to `total`, which is `requestChars` plus `toolsChars`. The
+ * Exact and additive: the parts sum to `total`, which is `requestChars` plus the characters of the tools. The
  * conversion to tokens is `contextTokens`' business, because that is where an estimate and a
  * reported count have to be told apart.
  */
@@ -172,7 +172,7 @@ export declare function contextTokens(body: OpenAI.ChatCompletionCreateParamsStr
  * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
  *
  * @param message - The message as it will be sent.
- * @param [options] - The divisor, `CHARS_PER_TOKEN` when none is given.
+ * @param [options] - The divisor, four when none is given.
  * @returns `messageChars` over the divisor, rounded up per message, where `requestTokens` rounds
  * once over them all.
  *

package/dist/tokens.js

@@ -13,7 +13,7 @@ export const CHARS_PER_TOKEN = 4;
  * vocabulary either.
  *
  * @param text - Prose or serialised JSON — both counted the same way, which is why JSON reads low.
- * @returns The length over `CHARS_PER_TOKEN`, rounded up: zero for an empty string, and one for
+ * @returns The length over four, rounded up: zero for an empty string, and one for
  * anything shorter than a token.
  *
  * @remarks
@@ -80,7 +80,7 @@ const REASONING_ALT_KEY = 15;
  * The divisor an option asked for, or the fallback when it asked for nothing usable.
  *
  * @param charsPerToken - What the caller gave. Absent, zero, negative or `NaN` is nothing usable.
- * @returns `charsPerToken` when it is above zero, otherwise `CHARS_PER_TOKEN`.
+ * @returns `charsPerToken` when it is above zero, otherwise four.
  */
 const divisor = (charsPerToken) => charsPerToken !== undefined && charsPerToken > 0 ? charsPerToken : CHARS_PER_TOKEN;
 /**
@@ -180,7 +180,7 @@ export function toolsChars(tools) {
  *
  * @param body - The request as it was sent, tools included.
  * @returns The sum of `messageChars` over the messages. The tools are not in it, whether or not
- * the body carries them; `toolsChars` counts those.
+ * the body carries them; `contextChars` counts those, under `tools`.
  *
  * @remarks
  * What calibration reads a reported prompt count against, since a ratio is only as good as the
@@ -197,7 +197,7 @@ export function requestChars(body) {
  * What this request will cost the window, in tokens, near enough.
  *
  * @param body - The request as it will be sent, tools included.
- * @param [options] - The divisor, `CHARS_PER_TOKEN` when none is given.
+ * @param [options] - The divisor, four when none is given.
  * @returns Whole tokens: the messages' and the tools', each rounded up on its own and added.
  *
  * @remarks
@@ -232,7 +232,7 @@ const PARTS = ['system', 'tools', 'history', 'toolResults'];
  * that is neither that nor a `tool` message as `history`.
  *
  * @remarks
- * Exact and additive: the parts sum to `total`, which is `requestChars` plus `toolsChars`. The
+ * Exact and additive: the parts sum to `total`, which is `requestChars` plus the characters of the tools. The
  * conversion to tokens is `contextTokens`' business, because that is where an estimate and a
  * reported count have to be told apart.
  */
@@ -327,7 +327,7 @@ export function contextTokens(body, { charsPerToken, promptTokens } = {}) {
  * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
  *
  * @param message - The message as it will be sent.
- * @param [options] - The divisor, `CHARS_PER_TOKEN` when none is given.
+ * @param [options] - The divisor, four when none is given.
  * @returns `messageChars` over the divisor, rounded up per message, where `requestTokens` rounds
  * once over them all.
  *

package/llms.txt

@@ -27,7 +27,7 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 How many characters a token is worth on one model, learned from what its endpoint reports.
 
 - `calibrate` — Takes one reading from a request that was answered, so the next one to this model is sized by it.
-- `charsPerTokenFor` — The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn has reported one.
+- `charsPerTokenFor` — The characters per token to size a request to this model with, four until a turn has reported one.
 - `resetCalibration` — Forgets every reading, so the next request is sized at `CHARS_PER_TOKEN` again.
 
 ### capabilities
@@ -60,7 +60,6 @@ The contract between whatever holds the tools and the loop that offers them to a
 - `contextLimitFor` — How much a model will read, in tokens.
 - `endpointId` — `endpointKey` hashed, for the remembered facts that can leave the process.
 - `endpointKey` — 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`.
-- `FIRST_TOKEN_FACTOR` — How many idle windows the first chunk gets when `firstTokenSeconds` is not given.
 - `firstTokenMs` — The wait for a streamed turn's first chunk, in the SDK's spelling: `undefined` is no limit.
 - `getClient` — The client for an endpoint, built once and kept.
 - `listModels` — Asks an endpoint what it serves, and remembers the answer.
@@ -91,7 +90,6 @@ Keeping a long run inside its window: stale tool results cleared, and the oldest
 - `SUMMARY_LEAD` — How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
 - `SUMMARY_PROMPT` — The summariser's instruction when the caller gives none.
 - `summariser` — A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
-- `summaryInput` — What the summariser is handed for a plan: the earlier summary if there was one, then each message as its role and at most 4000 characters of its text.
 
 ### config
 
@@ -110,7 +108,6 @@ Picking up an answer the token ceiling cut off, instead of keeping half of it.
 
 - `ContinueTurnOptions` (type) — What `continueTurn` takes besides what `runTurn` does.
 - `continueTurn` — Carries on an answer the token ceiling cut off, by sending the transcript again with the answer so far as a trailing assistant message, and joins the pieces into one turn.
-- `isContinuable` — Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun and no tool call in it.
 
 ### errors
 
@@ -193,8 +190,6 @@ What stretches of a transcript cost, read off the prompt counts the server alrea
 
 Choosing a run's tools before it starts, from the request and the catalogue's names.
 
-- `KEYWORD_DROPOFF` — How far the best unpicked tool must fall below the last picked one for the cut to count clean.
-- `KEYWORD_MIN_SCORE` — The least a best match may score and still be acted on without a model.
 - `KeywordPreselection` (type) — What `preselectByKeywords` found.
 - `KeywordPreselectOptions` (type) — What `preselectByKeywords` takes besides the catalogue and the request.
 - `PRESELECT_SCHEMA` — The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
@@ -224,10 +219,7 @@ Everything about a request failing that is not about what the request said.
 - `isModelLoading` — Whether a failure is a local server still loading the model, rather than one failing to serve.
 - `isOverflow` — Whether a refusal means the request was too big, rather than merely refused.
 - `isTransient` — Whether a failed request is worth trying again.
-- `LOADING_POLL_MS` — How long to wait between asking a loading server again.
-- `LOADING_TIMEOUT_MS` — How long `runTurn` waits for a model to load unless told otherwise.
 - `SMALLEST_LIKELY_WINDOW` — The smallest window worth believing in, and the floor under `runTurn`'s guard.
-- `sleep` — A delay an abort cuts short, rejecting rather than resolving early.
 
 ### run-calls
 
@@ -345,7 +337,6 @@ Telling a model's scratchpad from its answer when both arrive in `content`.
 
 ### tokens
 
-- `CHARS_PER_TOKEN` — The characters one token is taken to be, where nothing has measured it.
 - `ContextBreakdown` (type) — What a request is made of, by the part of it a consumer can actually do something about.
 - `ContextBreakdownOptions` (type) — What `contextTokens` takes besides the request.
 - `compact` — A token count as a message shows it: 1234 → "1.2k".
@@ -356,7 +347,6 @@ Telling a model's scratchpad from its answer when both arrive in `content`.
 - `requestChars` — How many characters a request is worth: the walk `requestTokens` divides, without the division.
 - `requestTokens` — What this request will cost the window, in tokens, near enough.
 - `TokenEstimateOptions` (type) — What the two token estimates below take besides what they measure.
-- `toolsChars` — How many characters a tool array is worth, measured once per array.
 
 ### tool-calls
 
@@ -385,8 +375,6 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 - `LOAD_TOOLS_DEFINITION` — One object for the life of the process — the agent loop asks for it on every iteration.
 - `loadedTools` — A tool array with newly loaded definitions appended, in the order they were loaded.
 - `loadResult` — What `load_tools` reports back: the descriptions, now that they are worth their tokens.
-- `MAX_CARRIED` — The most a conversation carries between turns.
-- `MAX_PER_LOAD` — The most a single `load_tools` call may pull in.
 - `orderTools` — The tool array in a stable order, so the same set of tools renders the same way twice.
 - `PROXY_TOOLS` — The whole tool array of a proxied run, `load_tools` then `call_tool`, frozen because it is shared.
 - `proxiedCall` — The tool a `call_tool` names and the arguments to run it with, or a throw the model can read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.25.1",
+  "version": "4.0.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",
@@ -46,10 +46,10 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/llms-txt.mjs",
-    "prepare": "npm run build",
+    "prepack": "npm run build",
     "check": "npm run check:biome && npm run check:types",
     "check:biome": "biome check --write .",
-    "check:types": "tsc -p tsconfig.tests.json",
+    "check:types": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "llms": "node scripts/llms-txt.mjs",