@cubicecho/agent-core 4.0.0 → 4.2.0

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, } from './compaction.js';
-export { ToolDiscovery, } from './config.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 { 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, } 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, } 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, findSpecSecrets, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SecretSign, 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.
  *
@@ -359,7 +359,47 @@ export interface ExportSpecOptions {
  * The property worth keeping is that **a redacted spec is still a valid spec** — it parses, it
  * resolves, and what comes back is the same agent pointed at the same servers, needing only the
  * credentials the importing host supplies itself. So a bundled server loses its `env` and its
- * `headers` and nothing else, and nothing outside `bundle` is touched: the format has no
- * credential field at any depth, which is the reason there is nothing else to strip.
+ * `headers` and nothing else, and nothing outside `bundle` is touched: those two are the only
+ * fields the format gives a credential. A server can still carry one where the format gives it no
+ * field — an `--api-key` among its `args`, a token in its `url` — and that is kept, because
+ * cutting it would point the agent at a different server. `findSpecSecrets` says where to look.
  */
 export declare function exportSpec(spec: AgentSpec, { secrets }?: ExportSpecOptions): AgentSpec;
+/** Why `findSpecSecrets` named a place. */
+export declare const SecretSign: {
+    /** A URL with a user or a password before its host. */
+    readonly Userinfo: 'userinfo';
+    /** A URL query parameter whose name reads as a credential's. */
+    readonly Query: 'query';
+    /** The value of a command-line flag, or of a header written as `Name: value`, so named. */
+    readonly Flag: 'flag';
+    /** A value with the shape of a credential: a known key prefix, or `Bearer` and a token. */
+    readonly Value: 'value';
+    /** A key of the server itself whose name reads as a credential's. */
+    readonly Field: 'field';
+};
+/** Any one of the reasons in `SecretSign`. */
+export type SecretSign = (typeof SecretSign)[keyof typeof SecretSign];
+/** One place `findSpecSecrets` thinks a credential may be, and never the credential. */
+export interface SecretHint {
+    /** Where, in `parseSpec`'s spelling: `bundle.mcpServers[0].args[2]`. */
+    path: string;
+    /** The server's slug, or its id where it has no slug. */
+    server: string;
+    sign: SecretSign;
+}
+/**
+ * Where a document's bundled servers may still carry a credential after `exportSpec`.
+ *
+ * @param spec - A document, exported or not: `env` and `headers` are not reported either way,
+ * since `exportSpec` strips them.
+ * @returns One hint for each suspect place, in document order, each naming where and why and
+ * none holding the value. Empty for a document with no bundle.
+ *
+ * @remarks
+ * A host calls this before it offers an export as safe to share, and warns with what comes back.
+ * It reads a server's `url`, its `command` and `args`, and the names of its other keys, and is a
+ * guess both ways: a credential in a positional argument with no telling prefix is missed, and a
+ * flag called `--keyboard` is named. A `${VAR}` is a reference and is never named.
+ */
+export declare function findSpecSecrets(spec: AgentSpec): SecretHint[];