@cubicecho/agent-core 3.0.0 → 4.0.0

package/README.md

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

@@ -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/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

@@ -14,9 +14,9 @@ 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, 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 { 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';
@@ -25,7 +25,7 @@ export { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type Ledger
 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, 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 { 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, 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

@@ -13,9 +13,9 @@ export { PRESELECT_APPEND, PRESELECT_EXCLUSIVE, runAgentLoop, } from './agent-lo
 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, 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 { 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';
@@ -24,7 +24,7 @@ export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from './led
 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, 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 { 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, 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/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/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

@@ -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
@@ -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.
  */

package/dist/tokens.js

@@ -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
@@ -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.
  */

package/llms.txt

@@ -90,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
 
@@ -109,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
 
@@ -222,7 +220,6 @@ Everything about a request failing that is not about what the request said.
 - `isOverflow` — Whether a refusal means the request was too big, rather than merely refused.
 - `isTransient` — Whether a failed request is worth trying again.
 - `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
 
@@ -350,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "3.0.0",
+  "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",