@cubicecho/agent-core 3.0.0 → 4.1.0

package/dist/index.d.ts

@@ -9,33 +9,33 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
-export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, runAgentLoop, type StepWindow, } from './agent-loop.ts';
-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 { type AgentConfig, type Endpoint, type ModelParams, type RetryPolicy, ToolDiscovery, type ToolPolicy, } from './config.ts';
-export { type ContinueTurnOptions, continueTurn, isContinuable, } 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 { 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 { preview } from './run-calls.ts';
-export { type RunTurnOptions, runTurn } from './run-turn.ts';
-export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from './runtime.ts';
-export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from './schema-compat.ts';
-export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, taskCall, tryAsk, } from './side-task.ts';
-export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from './snapshot.ts';
-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 { 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';
+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 './context/compaction.ts';
+export { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type LedgerRequest, rebaseLedger, recordRequest, type TokenLedger, tokensBetween, } from './context/ledger.ts';
+export { type AgentConfig, type Endpoint, type ModelParams, type RetryPolicy, ToolDiscovery, type ToolPolicy, } from './core/config.ts';
+export { calibrate, charsPerTokenFor, resetCalibration } from './endpoint/calibration.ts';
+export { type Capabilities, capabilitiesFor, EFFORT_LADDER, EFFORT_NONE, EFFORT_OFF, effortFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from './endpoint/capabilities.ts';
+export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, firstTokenMs, getClient, type LookupOptions, listModels, type ModelInfo, NO_KEY, resetClients, resolveApiKey, servedWindow, timeoutMs, } from './endpoint/client.ts';
+export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from './endpoint/schema-compat.ts';
+export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/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/hooks.ts';
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, } from './run/agent-loop.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 './run/events.ts';
+export { buildBody } from './run/request-body.ts';
+export { preview } from './run/run-calls.ts';
+export { resetAll } from './runtime/reset.ts';
+export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from './runtime/runtime.ts';
+export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from './runtime/snapshot.ts';
+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/spec.ts';
+export type { CatalogServer } from './tools/catalog.ts';
+export { type KeywordPreselection, type KeywordPreselectOptions, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, type ToolMatch, } from './tools/preselect.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 './tools/tool-loading.ts';
+export { type ContinueTurnOptions, continueTurn, } from './turn/continuation.ts';
+export { type RunTurnOptions, runTurn } from './turn/run-turn.ts';
+export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, taskCall, tryAsk, } from './turn/side-task.ts';
+export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './wire/errors.ts';
+export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './wire/retry.ts';
+export { CacheBreakReason, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './wire/stream.ts';
+export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, SPLIT_OUTPUT, SPLIT_REASONING, type Split, stripThinking, THINK_FENCE, } from './wire/thinking.ts';
+export { type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, } from './wire/tokens.ts';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';
+export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.ts';

package/dist/index.js

@@ -9,32 +9,32 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
-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, 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 { ToolDiscovery, } from './config.js';
-export { continueTurn, isContinuable, } 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 { 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 { preview } from './run-calls.js';
-export { runTurn } from './run-turn.js';
-export { createRuntime, defaultRuntime } from './runtime.js';
-export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from './schema-compat.js';
-export { ask, askJson, clean, listLines, parseJson, resetHints, taskCall, tryAsk, } from './side-task.js';
-export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from './snapshot.js';
-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 { 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';
+export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, } from './context/compaction.js';
+export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from './context/ledger.js';
+export { ToolDiscovery, } from './core/config.js';
+export { calibrate, charsPerTokenFor, resetCalibration } from './endpoint/calibration.js';
+export { capabilitiesFor, EFFORT_LADDER, EFFORT_NONE, EFFORT_OFF, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from './endpoint/capabilities.js';
+export { configureClients, contextLimitFor, endpointId, endpointKey, firstTokenMs, getClient, listModels, NO_KEY, resetClients, resolveApiKey, servedWindow, timeoutMs, } from './endpoint/client.js';
+export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from './endpoint/schema-compat.js';
+export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/hook-events.js';
+export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks/hooks.js';
+export { PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, } from './run/agent-loop.js';
+export { configureEvents, emit, endRun, fold, history, RunEventKind, RunOutcome, resetEvents, runMetrics, watch, } from './run/events.js';
+export { buildBody } from './run/request-body.js';
+export { preview } from './run/run-calls.js';
+export { resetAll } from './runtime/reset.js';
+export { createRuntime, defaultRuntime } from './runtime/runtime.js';
+export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from './runtime/snapshot.js';
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from './spec/spec.js';
+export { PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, } from './tools/preselect.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 './tools/tool-loading.js';
+export { continueTurn, } from './turn/continuation.js';
+export { runTurn } from './turn/run-turn.js';
+export { ask, askJson, clean, listLines, parseJson, resetHints, taskCall, tryAsk, } from './turn/side-task.js';
+export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './wire/errors.js';
+export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './wire/retry.js';
+export { CacheBreakReason, streamTurn, } from './wire/stream.js';
+export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, SPLIT_OUTPUT, SPLIT_REASONING, stripThinking, THINK_FENCE, } from './wire/thinking.js';
+export { compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, } from './wire/tokens.js';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ToolArgumentsError, } from './wire/tool-calls.js';
+export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.js';

package/dist/{agent-loop.d.ts → run/agent-loop.d.ts}

@@ -1,17 +1,17 @@
 import type OpenAI from 'openai';
-import type { CatalogServer } from './catalog.ts';
-import { type CompactionOptions } from './compaction.ts';
-import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from './config.ts';
+import { type CompactionOptions } from '../context/compaction.ts';
+import { type TokenLedger } from '../context/ledger.ts';
+import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from '../core/config.ts';
+import { HookEvent } from '../hooks/hook-events.ts';
+import { type HookContext, type HookNote, type HookRunner, type OnNote } from '../hooks/hooks.ts';
+import type { CatalogServer } from '../tools/catalog.ts';
+import { type KeywordPreselectOptions } from '../tools/preselect.ts';
+import { type ToolOrder } from '../tools/tool-loading.ts';
+import { type SideTask } from '../turn/side-task.ts';
+import { type Turn, type TurnUsage } from '../wire/stream.ts';
+import { type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
 import { type RunEventInput, type RunMetrics } from './events.ts';
-import { HookEvent } from './hook-events.ts';
-import { type HookContext, type HookNote, type HookRunner, type OnNote } from './hooks.ts';
-import { type TokenLedger } from './ledger.ts';
-import { type KeywordPreselectOptions } from './preselect.ts';
 import { type ToolDispatch } from './run-calls.ts';
-import { type SideTask } from './side-task.ts';
-import { type Turn, type TurnUsage } from './stream.ts';
-import { type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from './tool-calls.ts';
-import { type ToolOrder } from './tool-loading.ts';
 /**
  * The loop above a turn: send, run the tools the model asked for, send again, until it stops
  * asking.
@@ -181,7 +181,9 @@ export interface AgentLoopOptions {
      *
      * `true` takes `preselect`'s defaults; an object passes `keywords` and `maxPerLoad` through.
      * Its notices arrive as `notice` events, and a preselection that fails picks nothing rather
-     * than ending the run. It runs before the hooks gather, not beside them.
+     * than ending the run. What it picked is a notice too, `PRESELECTED_NOTICE` and the names,
+     * before the first `turn` event, and is the result's `preselected`. It runs before the hooks
+     * gather, not beside them.
      */
     preselect?: boolean | {
         keywords?: boolean | KeywordPreselectOptions;
@@ -352,6 +354,11 @@ export interface AgentLoopResult {
     loaded: string[];
     /** The tools the model actually called, `load_tools` excluded and `call_tool` looked through. */
     used: string[];
+    /**
+     * The shortlist the run opened with, as the host's `preselected` gave it or the loop's own
+     * preselection picked it. Empty in eager mode, and where nothing was picked.
+     */
+    preselected: string[];
     /** The hooks' notes from before the first request. */
     notes: HookNote[];
     /**
@@ -400,10 +407,10 @@ export interface AgentLoopResult {
  * and the ledger. See `AgentLoopResult`.
  *
  * @remarks
- * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded` and
- * `used` — because the steps before a failure were real and a host that stores its transcript
- * has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an overflow is
- * an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
+ * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
+ * and `preselected` — because the steps before a failure were real and a host that stores its
+ * transcript has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an
+ * overflow is an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
  * `AgentLoopError` with what was caught as its `cause` and its message as its own; `failedRun`
  * reads the run off any of the three. A failure while a step's tools run leaves the transcript
  * well-formed: the results that came back are kept, and each call without one is answered with a
@@ -439,3 +446,5 @@ export interface AgentLoopResult {
  * run's `temperature` or `maxTokens`.
  */
 export declare function runAgentLoop(options: AgentLoopOptions): Promise<AgentLoopResult>;
+/** What opens the notice naming the loop's own picks, ahead of the names. */
+export declare const PRESELECTED_NOTICE = "tools picked before the run: ";

package/dist/{agent-loop.js → run/agent-loop.js}

@@ -1,26 +1,26 @@
-import { charsPerTokenFor } from './calibration.js';
-import { capabilitiesFor, modelCapabilitiesFor, } from './capabilities.js';
-import { firstTokenMs, getClient, loadingMs, timeoutMs } from './client.js';
-import { compactTranscript, planCompaction, summariser } from './compaction.js';
-import { ToolDiscovery } from './config.js';
-import { continueTurn } from './continuation.js';
-import { AgentLoopError, AgentLoopOverflow, errorMessage, ToolIterationLimit, } from './errors.js';
+import { compactTranscript, planCompaction, summariser } from '../context/compaction.js';
+import { breakReason, rebaseLedger, recordRequest, } from '../context/ledger.js';
+import { ToolDiscovery } from '../core/config.js';
+import { counted } from '../core/guards.js';
+import { charsPerTokenFor } from '../endpoint/calibration.js';
+import { capabilitiesFor, modelCapabilitiesFor, } from '../endpoint/capabilities.js';
+import { firstTokenMs, getClient, loadingMs, timeoutMs } from '../endpoint/client.js';
+import { HookEvent } from '../hooks/hook-events.js';
+import { configureHooks, gather, notify, turnIndex, turnMessages, withContext, } from '../hooks/hooks.js';
+import { preselect } from '../tools/preselect.js';
+import { CALL_TOOL, catalogPrompt, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, orderTools, PROXY_TOOLS, proxyCatalogPrompt, toolName, } from '../tools/tool-loading.js';
+import { continueTurn } from '../turn/continuation.js';
+import { runTurn } from '../turn/run-turn.js';
+import { taskCall, tryAsk } from '../turn/side-task.js';
+import { AgentLoopError, AgentLoopOverflow, errorMessage, ToolIterationLimit, } from '../wire/errors.js';
+import { ContextOverflow } from '../wire/retry.js';
+import { addCounts, noUsage } from '../wire/stream.js';
+import { contextTokens, toolsChars } from '../wire/tokens.js';
+import { recoverToolCalls, } from '../wire/tool-calls.js';
+import { FinishReason, PartType, Role } from '../wire/wire.js';
 import { RunEventKind, RunOutcome, runMetrics, stamp, } from './events.js';
-import { counted } from './guards.js';
-import { HookEvent } from './hook-events.js';
-import { configureHooks, gather, notify, turnIndex, turnMessages, withContext, } from './hooks.js';
-import { breakReason, rebaseLedger, recordRequest, } from './ledger.js';
-import { preselect } from './preselect.js';
 import { buildBody } from './request-body.js';
-import { ContextOverflow } from './retry.js';
 import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, } from './run-calls.js';
-import { runTurn } from './run-turn.js';
-import { taskCall, tryAsk } from './side-task.js';
-import { addCounts, noUsage } from './stream.js';
-import { contextTokens, toolsChars } from './tokens.js';
-import { recoverToolCalls, } from './tool-calls.js';
-import { CALL_TOOL, catalogPrompt, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, orderTools, PROXY_TOOLS, proxyCatalogPrompt, toolName, } from './tool-loading.js';
-import { FinishReason, PartType, Role } from './wire.js';
 /** The `preselectRouting` that sends the first step the shortlist alone. */
 export const PRESELECT_EXCLUSIVE = 'exclusive';
 /** The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other. */
@@ -71,10 +71,10 @@ function cacheDiagnosis(previous, next, usage) {
  * and the ledger. See `AgentLoopResult`.
  *
  * @remarks
- * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded` and
- * `used` — because the steps before a failure were real and a host that stores its transcript
- * has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an overflow is
- * an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
+ * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
+ * and `preselected` — because the steps before a failure were real and a host that stores its
+ * transcript has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an
+ * overflow is an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
  * `AgentLoopError` with what was caught as its `cause` and its message as its own; `failedRun`
  * reads the run off any of the three. A failure while a step's tools run leaves the transcript
  * well-formed: the results that came back are kept, and each call without one is answered with a
@@ -118,6 +118,7 @@ export async function runAgentLoop(options) {
             toolCalls: [],
             loaded: [],
             used: [],
+            preselected: [],
         }),
     };
     let result;
@@ -285,6 +286,8 @@ function recorder(heard) {
     };
     return { recorded, onEvent };
 }
+/** What opens the notice naming the loop's own picks, ahead of the names. */
+export const PRESELECTED_NOTICE = 'tools picked before the run: ';
 /**
  * How this run finds its tools, and what it starts with in hand: the loop's own preselection
  * where it was asked for and the host has not already decided, and what an earlier question
@@ -292,7 +295,8 @@ function recorder(heard) {
  *
  * @param options - The run's options. Read for the discovery mode, the catalogue, `loaded`,
  * `preselected` and `preselect`.
- * @param notice - Hears what the loop's own preselection has to say.
+ * @param notice - Hears what the loop's own preselection has to say, and then what it picked,
+ * by name. A shortlist the host gave is not told back to it.
  * @returns `proxied` and `onDemand`, the second true of both modes and both false where `catalog`
  * is empty; `preselected`, the shortlist, empty in eager mode; and `loaded`, a new set of what was
  * carried and then the shortlist — empty when eager or proxied.
@@ -309,6 +313,9 @@ async function discovery(options, notice) {
     let preselected = [];
     if (onDemand && chooses) {
         preselected = await chooseTools(options, notice);
+        if (preselected.length > 0) {
+            notice(`${PRESELECTED_NOTICE}${preselected.join(', ')}`);
+        }
     }
     else if (onDemand) {
         preselected = [...(options.preselected ?? [])];
@@ -450,6 +457,7 @@ async function runSteps(options, standing) {
         // As the result would have said it: proxied, nothing is loaded that the history does not hold.
         loaded: proxied ? [] : [...loaded],
         used: [...used],
+        preselected: [...preselected],
     });
     const announce = announcer(onMessage);
     // Held by reference rather than by index, so a `beforeStep` that folds the head into a summary
@@ -639,6 +647,7 @@ async function runSteps(options, standing) {
                 toolCalls,
                 loaded: proxied ? [] : [...loaded],
                 used: [...used],
+                preselected: [...preselected],
                 notes: gathered.notes,
                 context: gathered.context,
                 preface,

package/dist/{events.d.ts → run/events.d.ts}

@@ -1,6 +1,6 @@
-import type { TokenLedger } from './ledger.ts';
-import type { TurnUsage } from './stream.ts';
-import { CacheBreakReason } from './stream.ts';
+import type { TokenLedger } from '../context/ledger.ts';
+import type { TurnUsage } from '../wire/stream.ts';
+import { CacheBreakReason } from '../wire/stream.ts';
 /**
  * What a run is doing, while it is doing it.
  *

package/dist/{events.js → run/events.js}

@@ -1,9 +1,9 @@
-import { getOrCreate } from './guards.js';
-import { ABORT_EVENT, MS_PER_MINUTE } from './platform.js';
-import { assignSettings, scoped } from './scope.js';
-import { CacheBreakReason } from './stream.js';
-import { LOAD_TOOLS } from './tool-loading.js';
-import { FinishReason } from './wire.js';
+import { getOrCreate } from '../core/guards.js';
+import { ABORT_EVENT, MS_PER_MINUTE } from '../core/platform.js';
+import { assignSettings, scoped } from '../core/scope.js';
+import { LOAD_TOOLS } from '../tools/tool-loading.js';
+import { CacheBreakReason } from '../wire/stream.js';
+import { FinishReason } from '../wire/wire.js';
 /** How many minutes an unended run's events are kept, absent a `retainUnendedMs`. */
 const RETAIN_UNENDED_MINUTES = 30;
 /** The numbers a run of the shape this bus was written for wants. */

package/dist/{request-body.d.ts → run/request-body.d.ts}

@@ -1,7 +1,7 @@
 import type OpenAI from 'openai';
-import { type Capabilities, type ModelCapabilities } from './capabilities.ts';
-import { type ModelParams } from './config.ts';
-import { type ToolOrder } from './tool-loading.ts';
+import { type ModelParams } from '../core/config.ts';
+import { type Capabilities, type ModelCapabilities } from '../endpoint/capabilities.ts';
+import { type ToolOrder } from '../tools/tool-loading.ts';
 /**
  * The one place a streamed request's body is decided from a config and what the endpoint and
  * the model have refused.

package/dist/{request-body.js → run/request-body.js}

@@ -1,7 +1,7 @@
-import { ceilingAndTemperature, effortFor } from './capabilities.js';
-import { RESERVED_BODY_FIELDS } from './config.js';
-import { relaxTools, sanitizeTools } from './schema-compat.js';
-import { orderTools } from './tool-loading.js';
+import { RESERVED_BODY_FIELDS } from '../core/config.js';
+import { ceilingAndTemperature, effortFor, } from '../endpoint/capabilities.js';
+import { relaxTools, sanitizeTools } from '../endpoint/schema-compat.js';
+import { orderTools } from '../tools/tool-loading.js';
 /**
  * The one place a streamed request's body is decided from a config and what the endpoint and
  * the model have refused.

package/dist/{run-calls.d.ts → run/run-calls.d.ts}

@@ -1,8 +1,8 @@
 import type OpenAI from 'openai';
-import type { CatalogServer } from './catalog.ts';
+import type { CatalogServer } from '../tools/catalog.ts';
+import type { Turn } from '../wire/stream.ts';
+import { type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
 import type { RunEventInput } from './events.ts';
-import type { Turn } from './stream.ts';
-import { type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from './tool-calls.ts';
 /**
  * The tools between two turns: a step's calls read, run and written into the transcript.
  *

package/dist/{run-calls.js → run/run-calls.js}

@@ -1,8 +1,8 @@
-import { errorMessage } from './errors.js';
+import { CALL_TOOL, expandNames, inCatalog, LOAD_TOOLS, loadResult, proxiedCall, proxyLoadResult, requestedNames, shownCall, toolName, } from '../tools/tool-loading.js';
+import { errorMessage } from '../wire/errors.js';
+import { parseToolArguments, } from '../wire/tool-calls.js';
+import { FUNCTION_TOOL, Role } from '../wire/wire.js';
 import { RunEventKind } from './events.js';
-import { parseToolArguments, } from './tool-calls.js';
-import { CALL_TOOL, expandNames, inCatalog, LOAD_TOOLS, loadResult, proxiedCall, proxyLoadResult, requestedNames, shownCall, toolName, } from './tool-loading.js';
-import { FUNCTION_TOOL, Role } from './wire.js';
 /**
  * The tools between two turns: a step's calls read, run and written into the transcript.
  *

package/dist/{reset.js → runtime/reset.js}

@@ -1,9 +1,9 @@
-import { resetCalibration } from './calibration.js';
-import { resetCapabilities } from './capabilities.js';
-import { resetClients } from './client.js';
-import { resetEvents } from './events.js';
-import { resetHooks } from './hooks.js';
-import { resetHints } from './side-task.js';
+import { resetCalibration } from '../endpoint/calibration.js';
+import { resetCapabilities } from '../endpoint/capabilities.js';
+import { resetClients } from '../endpoint/client.js';
+import { resetHooks } from '../hooks/hooks.js';
+import { resetEvents } from '../run/events.js';
+import { resetHints } from '../turn/side-task.js';
 /**
  * Forgets everything this package remembers between calls.
  *

package/dist/{runtime.d.ts → runtime/runtime.d.ts}

@@ -1,15 +1,15 @@
-import { runAgentLoop } from './agent-loop.ts';
-import { calibrate, charsPerTokenFor, resetCalibration } from './calibration.ts';
-import { capabilitiesFor, expireCapabilities, resetCapabilities } from './capabilities.ts';
-import { type ClientPoolOptions, configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow } from './client.ts';
-import { compactTranscript, runCompaction, summariser } from './compaction.ts';
-import { continueTurn } from './continuation.ts';
-import { configureEvents, type EventBusOptions, emit, endRun, history, resetEvents, watch } from './events.ts';
-import { assembleContext, configureHooks, consult, gather, type HookOptions, notify, resetHooks, withContext } from './hooks.ts';
-import { preselect } from './preselect.ts';
+import { compactTranscript, runCompaction, summariser } from '../context/compaction.ts';
+import { calibrate, charsPerTokenFor, resetCalibration } from '../endpoint/calibration.ts';
+import { capabilitiesFor, expireCapabilities, resetCapabilities } from '../endpoint/capabilities.ts';
+import { type ClientPoolOptions, configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow } from '../endpoint/client.ts';
+import { assembleContext, configureHooks, consult, gather, type HookOptions, notify, resetHooks, withContext } from '../hooks/hooks.ts';
+import { runAgentLoop } from '../run/agent-loop.ts';
+import { configureEvents, type EventBusOptions, emit, endRun, history, resetEvents, watch } from '../run/events.ts';
+import { preselect } from '../tools/preselect.ts';
+import { continueTurn } from '../turn/continuation.ts';
+import { runTurn } from '../turn/run-turn.ts';
+import { ask, askJson, resetHints, tryAsk } from '../turn/side-task.ts';
 import { resetAll } from './reset.ts';
-import { runTurn } from './run-turn.ts';
-import { ask, askJson, resetHints, tryAsk } from './side-task.ts';
 import { exportCapabilities, importCapabilities } from './snapshot.ts';
 /**
  * Every exported function that reads or writes what a runtime remembers, itself or through what

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

@@ -1,16 +1,16 @@
-import { runAgentLoop } from './agent-loop.js';
-import { calibrate, charsPerTokenFor, resetCalibration } from './calibration.js';
-import { capabilitiesFor, expireCapabilities, resetCapabilities } from './capabilities.js';
-import { configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow, } from './client.js';
-import { compactTranscript, runCompaction, summariser } from './compaction.js';
-import { continueTurn } from './continuation.js';
-import { configureEvents, emit, endRun, history, resetEvents, watch } from './events.js';
-import { assembleContext, configureHooks, consult, gather, notify, resetHooks, withContext, } from './hooks.js';
-import { preselect } from './preselect.js';
+import { compactTranscript, runCompaction, summariser } from '../context/compaction.js';
+import { inScope, rootScope } from '../core/scope.js';
+import { calibrate, charsPerTokenFor, resetCalibration } from '../endpoint/calibration.js';
+import { capabilitiesFor, expireCapabilities, resetCapabilities } from '../endpoint/capabilities.js';
+import { configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow, } from '../endpoint/client.js';
+import { assembleContext, configureHooks, consult, gather, notify, resetHooks, withContext, } from '../hooks/hooks.js';
+import { runAgentLoop } from '../run/agent-loop.js';
+import { configureEvents, emit, endRun, history, resetEvents, watch } from '../run/events.js';
+import { preselect } from '../tools/preselect.js';
+import { continueTurn } from '../turn/continuation.js';
+import { runTurn } from '../turn/run-turn.js';
+import { ask, askJson, resetHints, tryAsk } from '../turn/side-task.js';
 import { resetAll } from './reset.js';
-import { runTurn } from './run-turn.js';
-import { inScope, rootScope } from './scope.js';
-import { ask, askJson, resetHints, tryAsk } from './side-task.js';
 import { exportCapabilities, importCapabilities } from './snapshot.js';
 /**
  * Every exported function that reads or writes what a runtime remembers, itself or through what

package/dist/{snapshot.js → runtime/snapshot.js}

@@ -1,7 +1,7 @@
-import { capabilitiesById, knownCapabilities, MODEL_FLAGS, modelCapabilitiesFor, OPTIMISTIC_MODEL, } from './capabilities.js';
-import { modelKey } from './client.js';
-import { isRecord } from './guards.js';
-import { refusedHints } from './side-task.js';
+import { isRecord } from '../core/guards.js';
+import { capabilitiesById, knownCapabilities, MODEL_FLAGS, modelCapabilitiesFor, OPTIMISTIC_MODEL, } from '../endpoint/capabilities.js';
+import { modelKey } from '../endpoint/client.js';
+import { refusedHints } from '../turn/side-task.js';
 /**
  * What endpoints and models refused, carried across a restart.
  *

package/dist/{spec.d.ts → spec/spec.d.ts}

@@ -1,5 +1,5 @@
-import { type AgentConfig, type Endpoint } from './config.ts';
-import { HookEvent } from './hook-events.ts';
+import { type AgentConfig, type Endpoint } from '../core/config.ts';
+import { HookEvent } from '../hooks/hook-events.ts';
 /**
  * A JSON document that defines an agent, and the rules for reading one.
  *

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

@@ -1,6 +1,6 @@
-import { RESERVED_BODY_FIELDS, ToolDiscovery } from './config.js';
-import { isRecord } from './guards.js';
-import { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hook-events.js';
+import { RESERVED_BODY_FIELDS, ToolDiscovery } from '../core/config.js';
+import { isRecord } from '../core/guards.js';
+import { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from '../hooks/hook-events.js';
 /**
  * A JSON document that defines an agent, and the rules for reading one.
  *

package/dist/{preselect.d.ts → tools/preselect.d.ts}

@@ -1,6 +1,6 @@
-import type { OnNotice } from './capabilities.ts';
+import type { Endpoint } from '../core/config.ts';
+import type { OnNotice } from '../endpoint/capabilities.ts';
 import type { CatalogServer } from './catalog.ts';
-import type { Endpoint } from './config.ts';
 /**
  * The system prompt a preselector is given, holding it to the cap its answer will be held to.
  *
@@ -176,8 +176,9 @@ export interface PreselectOptions {
  * The tools a request is likely to need, picked by a small model before the run starts, or none.
  *
  * @param config - The endpoint the preselector is reached through.
- * @param model - The preselector. An empty name picks nothing, which is what `toolSelectModel`
- * means by empty.
+ * @param model - The preselector. An empty name picks nothing, silently, which is what
+ * `toolSelectModel` means by empty: a host whose settings read `""` as "the run's model" passes
+ * `toolSelectModel: settings.toolSelectModel || settings.model`.
  * @param catalog - The servers to choose from.
  * @param prompt - The request being planned for. Only its head is read; see `preselectInput`.
  * @param [options] - Cancellation, notices, the reply ceiling, the temperature and reasoning effort

package/dist/{preselect.js → tools/preselect.js}

@@ -1,7 +1,7 @@
-import { byCodeUnit, counted, isRecord } from './guards.js';
-import { askJson, tryAsk } from './side-task.js';
+import { byCodeUnit, counted, isRecord } from '../core/guards.js';
+import { askJson, tryAsk } from '../turn/side-task.js';
+import { SchemaType } from '../wire/wire.js';
 import { catalogList, expandNames, MAX_PER_LOAD } from './tool-loading.js';
-import { SchemaType } from './wire.js';
 /**
  * Choosing a run's tools before it starts, from the request and the catalogue's names.
  *
@@ -243,8 +243,9 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
  * The tools a request is likely to need, picked by a small model before the run starts, or none.
  *
  * @param config - The endpoint the preselector is reached through.
- * @param model - The preselector. An empty name picks nothing, which is what `toolSelectModel`
- * means by empty.
+ * @param model - The preselector. An empty name picks nothing, silently, which is what
+ * `toolSelectModel` means by empty: a host whose settings read `""` as "the run's model" passes
+ * `toolSelectModel: settings.toolSelectModel || settings.model`.
  * @param catalog - The servers to choose from.
  * @param prompt - The request being planned for. Only its head is read; see `preselectInput`.
  * @param [options] - Cancellation, notices, the reply ceiling, the temperature and reasoning effort

package/dist/{tool-loading.js → tools/tool-loading.js}

@@ -1,6 +1,6 @@
-import { byCodeUnit, isRecord } from './guards.js';
-import { ARGUMENT_PREVIEW_CHARS } from './tool-calls.js';
-import { FUNCTION_TOOL, SchemaType } from './wire.js';
+import { byCodeUnit, isRecord } from '../core/guards.js';
+import { ARGUMENT_PREVIEW_CHARS } from '../wire/tool-calls.js';
+import { FUNCTION_TOOL, SchemaType } from '../wire/wire.js';
 /**
  * On-demand tool loading.
  *