@combycode/llm-sdk 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,212 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [2.1.0] — 2026-08-17
+
+Minor, not major: everything below is additive or a bug fix, and no export was removed or
+renamed. One caveat worth reading before upgrading — see **`defineTool` optional parameters** under
+Fixed, which tightens an inferred type and can therefore surface a compile error in code that was
+already wrong at runtime.
+
+### Added
+
+- **Lazy tool loading — register a tool without declaring it.** `lazy: true` on `defineTool`, on an
+  `AgentTool`, or on a whole MCP server via `connectMcp(cfg, { lazy: true })`. The tool is registered,
+  namespaced and collision-checked exactly as before, but is not placed in the `tools` array: the
+  model finds it with a built-in `tool_search`, which returns full schemas as data, and runs it
+  through a built-in `call_tool`. Both are declared only when at least one lazy tool exists, so an app
+  that never opts in sees nothing new.
+
+  Measured over 308 tools, six tasks, three reps, both providers: identical correctness, **−72%** cost
+  per task on `claude-haiku-4.5` and **−97%** on `gpt-5.4-nano`, for one extra round trip. The saving
+  is not from caching — it is from never sending the tool block. Schemas arrive in a tool RESULT,
+  which lands after the cached prefix, so the declared array never changes and no discovery event can
+  invalidate it. Promoting tools into the array instead costs **+63%** versus never deferring.
+
+  **It is not always a win.** Below roughly a hundred richly-schema'd tools it costs more than
+  declaring everything, because what remains in the prefix falls under the provider's minimum
+  cacheable size while a search round trip is still paid. There is deliberately no automatic
+  threshold: whether deferring pays depends on schema size, not tool count.
+
+  `ToolCallReport.toolName` names the tool that actually ran, never `call_tool`, and carries
+  `discoveredVia: 'search'`. A new `onToolSearch` hook reports queries, what matched, and — the field
+  worth alerting on — which queries matched nothing. Tuning via `lazyTools: { limit, maxSearches }`.
+
+- **`CostSummary.unpriced` / `.unpricedModels` — a $0.00 total no longer hides a failed lookup.** A
+  model with no catalog entry was priced at zero and summed into every total, so a report read $0.00
+  when it meant "could not price this", and a budget built on that total silently never fired. The
+  per-entry `cost.source: 'unknown'` tag already recorded it; nothing aggregated it. The collector
+  now also emits one `onWarning` per unknown model (`code: 'unpriced_model'`) — once per model, not
+  per request. Genuinely free calls are unaffected: they are priced `'calculated'` at zero with a
+  note. The usual cause is a model id that reaches the provider but is not a catalog key, e.g.
+  `anthropic/claude-haiku-4-5` against the catalog's `anthropic/claude-haiku-4.5`.
+- **`strictSupport(schema, dialect)` — ask whether a schema can satisfy a provider's strict mode.**
+  Returns `{ ok, reason }`, where `reason` names the property or keyword responsible. Exported
+  because the answer differs per provider and was otherwise only discoverable by getting a 400.
+- **`complete({ seed, topK })` and `CompleteResult.error`.** All three existed on `LLMClient` and the
+  agent path but not on the one-shot helper, so a documented example demonstrating them did not
+  compile. `error` surfaces the in-band failure some providers report instead of throwing (OpenAI
+  Responses `status: 'failed'`), which otherwise reads as a successful empty answer.
+
+- **`complete({ cache })` — prompt caching is reachable from the one-shot helper.** `CompleteOptions`
+  had no `cache` field at all, so asking for it did nothing: the option was dropped in silence, with
+  no error and no warning, while `LLMClient` and every adapter supported it fully. It matters most
+  exactly where this helper is convenient — a long system prompt or a large tool block, which sit at
+  the front of the request and are the cheapest part to cache.
+  - Found by a benchmark that reported zero cached tokens for every arm it measured.
+
+### Fixed
+
+- **Any OpenAI tool with an OPTIONAL parameter was rejected outright.** The library forced
+  `strict: true` on every function tool while sending the schema as written. OpenAI's strict mode
+  requires every property to appear in `required`, at every nesting level, and answers a schema that
+  does not with `400 Invalid schema: 'required' is required to be supplied` — never a degraded
+  result. So `defineTool({ optional: [...] })`, a documented feature, could not be used on OpenAI at
+  all, and neither could most MCP servers. The same forcing applied to structured output on both
+  OpenAI APIs.
+
+  On Responses, where strict has long been the default, it is now requested only where the schema
+  can satisfy the provider. Elsewhere it stays OPT-IN — see the next entry. The rules differ per
+  provider, measured live rather than read off the docs:
+
+  | | OpenAI | Anthropic |
+  |---|---|---|
+  | optional properties (not in `required`) | rejected | fine |
+  | `minimum` / `maximum` / `exclusive*` / `multipleOf` / `maxItems` | fine | rejected |
+  | `additionalProperties: true` | rejected | rejected |
+  | `{ type: 'object' }` with no `properties` key | rejected | fine |
+  | more than 20 strict tools per request | fine | rejected |
+
+  Two consequences: a generic router tool — one whose parameter must accept any shape — can never
+  be strict, and past Anthropic's cap the defaulted tools give up strict together rather than the
+  first 20 keeping it by array order. Passing `strict` explicitly still wins in either direction,
+  including past the cap. A no-argument tool is unaffected: `properties: {}` is present but empty,
+  which both providers accept.
+
+  Nothing caught this because nothing executed it: every example declared its tool parameters as
+  required, and the MCP server used throughout the corpus marks everything required. Typecheck,
+  API snapshot, doc-snippet compilation and consumer install all passed on code the API refuses.
+
+- **Strict stays OPT-IN on Anthropic and OpenAI Chat Completions.** It was briefly defaulted on
+  during this cycle and reverted before release, so behaviour on both is unchanged from 2.0.1.
+
+  What decided it: strict makes no measurable difference to argument quality — 40 of 40 calls
+  conformed with it and without it on both providers, including prompts written to pull away from
+  the schema. Its one real effect is that Anthropic then refuses to call a tool that was never
+  declared (10/10 undeclared without it, 0/10 with it), and that only matters when something puts
+  an undeclared tool in front of the model, which ordinary use does not.
+
+  Against that, Anthropic's strict mode carries limits no per-schema check can predict: at most 20
+  strict tools per request, at most 24 optional parameters summed across all strict schemas
+  (nested ones included), and an opaque complexity limit on top — 24 optional parameters spread
+  over four tools compiles, the same 24 in one tool answers "Schema is too complex for
+  compilation". Twelve ordinary tools with five optional parameters each already exceed the second.
+  The first two are aggregates, so they cannot live in a per-schema predicate; the third has no
+  published formula. Opt-in is the only honest default there.
+
+- **`defineTool` typed optional parameters as always present.** Keys listed in `optional` inferred as
+  required in the `execute` args, so `args.unit.toUpperCase()` typechecked and threw at runtime on
+  every call where the model omitted the argument — the expected case for an optional argument. They
+  now infer as `| undefined`.
+
+- **`complete()` sent different options depending on whether `tools` was passed.** The helper has two
+  branches, and the tools branch forwarded only `structured` — silently dropping `providerOptions`,
+  `audio`, `outputModalities` and `serviceTier`, which the no-tools branch honoured. Adding a tool to
+  a working call could therefore change behaviour that has nothing to do with tools. Both branches
+  now forward the same set.
+
+### Added
+
+- **MCP tool definitions carry what the spec publishes.** `McpToolDef` now models `annotations`
+  (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `icons`, `execution`
+  and `_meta`. The data always arrived — `tools/list` results are passed through unparsed — but was
+  untyped, so a host could not act on it without a cast. These stay **host-facing**: no provider's
+  function-tool schema has a field that could carry them, so none is sent to the model.
+  - `execution.taskSupport: 'required'` means the tool MUST be invoked as a task. Task invocation is
+    not implemented, so such a tool cannot be called through this client — the field being visible is
+    what lets a caller see that instead of meeting it as a server error.
+- **MCP `outputSchema` reaches the model when asked for** — `connectMcp(cfg, { validateOutput: true })`.
+  It was read for local validation only, while OpenAI Responses accepts `output_schema` and the
+  library already emitted it for hand-written tools; the two ends were never connected.
+  - **Opt-in, because declaring it is a promise about the RESULT.** OpenAI then rejects the turn
+    — *"expected a JSON string because the function declares output_schema"* — unless the result is
+    JSON matching that schema, so the tool result changes from prose to structured data. MCP returns
+    `structuredContent` exactly when a tool publishes `outputSchema`, and that is now what comes
+    back — under the same flag, so nothing changes for anyone who did not ask for it.
+  - Verified end to end against a live MCP server through OpenAI Responses, in both modes.
+- **`moderate()` now returns the shape of its input.** Overloads: one input (a string, or one
+  content-part array forming a single multimodal item) returns a `ModerationResult`; a list of
+  inputs returns `ModerationResult[]`. The mapping was documented in prose from the start but the
+  signature returned the bare union, so `result.flagged` was a type error and **every documented
+  example failed to compile**. The wide-union overload is kept, so code that already narrows still
+  compiles. No runtime change.
+- **`toolKey` / `describeTool` are exported.** `AgentTool.definition` is a `Tool` union (function
+  tool or builtin), so `.name` does not exist on it; reading a tool's name previously required
+  hand-narrowing at every call site.
+- **`createEngine({ retry })` — retry policy configurable where it belongs.** The machinery existed
+  and worked, but the only way to reach it was hand-building an `HttpRequest`; nothing on
+  `createEngine()` exposed it. Retry is cross-cutting, so it is now an engine-level setting inherited
+  by every queue, with `createEngine({ queues })` for one provider and `HttpRequest.retry` for one
+  request. Nested groups (`backoff`, `perKind`) merge rather than replace, so overriding one knob
+  does not reset the schedule.
+  - New type `RetryPolicyOverride`. `Partial<RetryConfig>` only makes top-level keys optional, so it
+    still demanded a complete `backoff` — the partial override the merge always supported was not
+    expressible. Engine, queue and `mergeRetry` now take the deeper-partial type; strictly wider, so
+    existing config keeps compiling.
+  - Additive: omitting all of it is byte-identical to before.
+
+### Fixed
+
+- **Docs: the per-request retry sample could never compile.** `docs/guide/network.md` showed
+  `complete({ retry: { attempts, initialDelay, maxDelay, expBase, httpStatusCodes } })`. `complete()`
+  takes no `retry` option (`TS2353`), and not one of those field names exists on
+  `RequestRetryOverride` — the real fields are `maxRetries` / `totalTimeoutMs` / `attemptTimeoutMs` /
+  `maxRetryAfterMs` / `backoff{initialMs,maxMs,multiplier,jitter}`, and the override rides on
+  `engine.fetch()`. The feature was always correct; only its documentation was wrong. Same class as
+  the 2.0.0 `agent.run()` defect, on an option object rather than a method, which is why the
+  consumer-surface check did not see it.
+
+- **MCP result cache: `ttlMs: 0` now evicts.** The hint was documented as "immediately stale — not
+  the same as absent", but `set()` funnelled it through the same branch as a missing hint and stored
+  nothing. Any entry already held survived, so a server that said "cache for 60s" and later "stale
+  now" kept being answered from the stale entry for the rest of the original TTL — the instruction
+  was accepted and inert. A non-positive `ttlMs` now drops the entry for that key. Absent hints are
+  unchanged and still leave an existing entry alone, so pre-2026 servers behave exactly as before.
+  - The existing unit test asserted `set(…, { ttlMs: 0 })` returned `false` and `get` was
+    `undefined` — on an *empty* cache, where that holds whether or not the hint does anything. It
+    passed for the wrong reason. Found by writing the MCP protocol example as a consumer.
+
+## [2.0.1] - 2026-08-10
+
+Three defects reported by a consumer within a day of 2.0.0 — all reachable by reading the shipped
+`.d.ts`, none caught by our gate. See the note at the end.
+
+### Fixed
+
+- **`agent.stream()` now carries `phase` on text events.** The raw stream event had it, and the
+  agent mapper *used* it internally to keep commentary out of the answer — then yielded both deltas
+  through one `{ type: 'text', text }` with the phase stripped. A UI streaming those straight
+  through put the model's thinking-aloud into the transcript **as if it were the reply**, with no
+  way to tell them apart. `finalAnswerText()` could not help: it takes a finished message's
+  `content`, not deltas.
+  - Additive: `phase` is **absent** (not `undefined`) when the provider reports none, so every
+    non-codex provider is byte-identical to before.
+- **Docs: `agent.run()` does not exist.** The agent-loop guide recommended it for a non-throwing
+  report. The class exposes `stop` / `complete` / `structuredComplete` / `stream`; the report is
+  reached with `try/catch` + `agent.lastReport`. The guide now shows that.
+- **Docs: the 2.0.0 changelog overstated live commentary.** It said commentary "is still yielded to
+  the consumer (a UI may well want to render it live)" — true only in the sense that the bytes
+  arrived; they were unlabelled, so a UI could not act on them. The 2.0.0 entry now says so and
+  points here.
+
+### Why this got out
+
+The feature was verified end-to-end on the **buffered** path (`finalAnswerText`, `response.text`,
+live-tested against real models) and never once from the **layer most consumers actually call**.
+1778 tests, four MCP transports and two live corpora, and no check that a shipped type was usable
+from `agent.stream()`. The gate was deep where it was pointed and blind where it was not — so the
+release checklist now includes a consumer-surface pass over the published `.d.ts`.
+
 ## [2.0.0] - 2026-08-09
 
 **Upgrading:** three things can require action, and none of them is a provider change — that is the
@@ -250,8 +456,9 @@ with `inputRequiredMaxRounds`.
     silently drop the answer.
   - Streaming carries it too. `phase` is announced once on `response.output_item.added` and belongs
     on every delta of that item, so the parser keeps per-stream item→phase state; concurrent streams
-    cannot leak phases into each other. Commentary is still yielded to the consumer (a UI may well
-    want to render it live) and is preserved in the assembled content as its own phase-tagged part.
+    cannot leak phases into each other. Commentary is yielded to the consumer and preserved in the
+    assembled content as its own phase-tagged part. (In 2.0.0 the agent-layer event dropped the
+    phase, so a UI could not act on it — corrected in 2.0.1.)
   - Nothing is inferred: a model that reports no phase produces parts with no phase, exactly as
     before.
 - **`name` + `namespace` on `function_call_output`.** The tool name is taken from the matching
@@ -417,9 +624,11 @@ interaction or an outright failure from a clean finish.
   error, so the gating is locked by unit tests and was live-verified end to end.
 - **`docs/feature-matrix.json` — the parity matrix.** Every capability an official SDK exposes, how
   each provider spells it, and where we stand, with citations into the version-pinned clones.
-  `scripts/validate-feature-matrix.mjs` runs as part of `bun run lint` and fails the build on a
-  broken citation, an unexplained `partial`/`beta`/`by-design`, or a duplicate id. It backs the
-  site's comparison page and is maintained by the upstream-update cycle.
+
+  > **Corrected 2026-08-10.** This entry also described the release tooling that consumes the
+  > matrix. That does not belong in a library changelog — a consumer of the package cannot see it,
+  > run it, or care about it — and the tool it named did not exist. Only the shipped data is
+  > described here now.
 - **`FinishReason` gains `'pending'`** — non-terminal: the provider accepted the request but has not
   produced a completion (Google Interactions `queued`, OpenAI Responses `queued`/`in_progress` in
   background mode). Treat as "poll/retry", never as a result. *Additive union member: exhaustive

package/dist/agent/context-registry/layers.d.ts

@@ -26,7 +26,13 @@ export declare const LAYER_CHAT_FACTS = "chat.facts";
 export declare const LAYER_EXECUTOR_TOOL_EXAMPLES = "executor.tool-examples";
 /** ContextGuard's compaction summary layer (replaces compacted message ranges). */
 export declare const LAYER_CONTEXT_GUARD_SUMMARY = "context-guard.summary";
+/** How to reach tools that are registered but not declared. Present only while at least
+ *  one lazy tool exists. See `writeLazyToolsProtocol`. */
+export declare const LAYER_LAZY_TOOLS = "agentloop.lazy-tools";
 export declare const PRIORITY_AGENTLOOP_SYSTEM = 10;
+/** Just after the agent's own system text: the model needs to know its tools are not
+ *  listed before anything else it is told about them. */
+export declare const PRIORITY_LAZY_TOOLS = 20;
 export declare const PRIORITY_LEGACY_SYSTEM = 50;
 export declare const PRIORITY_AGENTLOOP_CONTEXT = 100;
 export declare const PRIORITY_MEMORY = 200;
@@ -35,5 +41,18 @@ export declare const PRIORITY_EXECUTOR_TOOL_EXAMPLES = 280;
 export declare const PRIORITY_CONTEXT_GUARD_SUMMARY = 300;
 /** Set the AgentLoop's persona/system layer on a registry (or remove if blank). */
 export declare function writeAgentLoopSystem(registry: ContextRegistry, text: string | undefined, owner: string): void;
+/** Tell the model that its tools are not all listed, and how to reach the rest.
+ *
+ *  Without this the feature under-performs badly and quietly: measured over 24 live runs
+ *  against 308 lazy tools, the model scored 8/12 and 9/12 — sometimes never searching at
+ *  all, more often searching once for a request that needed two capabilities and
+ *  answering from the one tool it found. With the protocol stated, the same tasks and the
+ *  same ranker scored 18/18. The tool descriptions alone are not enough, because a model
+ *  has no reason to suspect a tool exists that it cannot see.
+ *
+ *  Deliberately a few lines and NOT a catalog. A catalog is paid for on every turn for
+ *  the whole conversation, which is most of what makes eager exposure expensive in the
+ *  first place; this is a fixed cost of roughly one sentence. */
+export declare function writeLazyToolsProtocol(registry: ContextRegistry, active: boolean, owner: string): void;
 /** Set the AgentLoop's run-scenario context layer (or remove if blank). */
 export declare function writeAgentLoopContext(registry: ContextRegistry, text: string | undefined, owner: string): void;

package/dist/agent/lazy-tools.d.ts

@@ -0,0 +1,85 @@
+/** Lazy tool loading: `tool_search` + `call_tool`.
+ *
+ *  A tool registered with `lazy: true` is NOT placed in the `tools` array. The model
+ *  finds it by searching, and calls it through `call_tool`. The point is what does NOT
+ *  move: the declared tool array never changes, so no discovery event can invalidate the
+ *  cached prefix. Schemas travel as tool RESULTS, which land in history after the prefix.
+ *
+ *  Measured against declaring everything (308 tools, 6 tasks, 3 reps, both providers —
+ *  `bench/lazy-tools-e2e`): identical correctness (72/72), −72% cost on claude-haiku-4.5
+ *  and −97% on gpt-5.4-nano, at one extra round trip per task.
+ *
+ *  Three details here are load-bearing and each came from a measurement that failed
+ *  first. They are not stylistic:
+ *
+ *  1. `call_tool` is SINGULAR. A batching form — `call_tools({ calls: [...] })` — is
+ *     returned as a JSON *string* rather than an array by claude-haiku about half the
+ *     time (19/30 vs 30/30), because a router's `input` must be open and an open object
+ *     cannot be strict, so no grammar holds the shape. Batching is not lost: the model
+ *     emits several parallel `call_tool` calls in one turn instead.
+ *
+ *  2. `tool_search` REPORTS QUERIES THAT MATCHED NOTHING. Merging results silently makes
+ *     a failed lookup indistinguishable from one whose hits were folded in with the
+ *     others, and the model then answers confidently from the tools it did get. Measured
+ *     on colloquial phrasing: without this, 34/36 recall and 17/18 correct; with it,
+ *     36/36 and 18/18.
+ *
+ *  3. Ranking is deliberately weak, and that is survivable only because the MODEL writes
+ *     the query. Token overlap against raw user text scores 0–1 of 8 on indirect or
+ *     colloquial phrasing (`bench/tool-ranking`). The model's rewriting is what carries
+ *     it. Better ranking would reduce how far that rewriting has to reach; it is not what
+ *     makes the feature work.
+ */
+import type { AgentTool } from './types';
+/** Tuning for lazy tool exposure. Every field is optional; the defaults are what the
+ *  measurements used. */
+export interface LazyToolsConfig {
+    /** Schemas returned per query. Default 5, capped at 20 — the cap is a real bound, not
+     *  a formality: returning everything re-creates the cost the feature exists to avoid. */
+    limit?: number;
+    /** Searches allowed per run. Default 5. Exceeding it returns a tool result saying so
+     *  and leaves the run alive: a model that loops on search should be told, not killed. */
+    maxSearches?: number;
+}
+/** The two names this module owns. Registered like any other tool, so the existing
+ *  collision policy applies to them and there is no second registry. */
+export declare const LAZY_SEARCH_TOOL = "tool_search";
+export declare const LAZY_CALL_TOOL = "call_tool";
+/** Rank candidates by token overlap over name + description + parameter names, with name
+ *  matches weighted double — a query naming the domain should beat a filler whose long
+ *  description happens to share vocabulary. Local and dependency-free by design: no
+ *  embeddings, no network call on the discovery path. */
+export declare function rankTools(query: string, candidates: AgentTool[], limit: number): AgentTool[];
+/** Per-run search budget. Reset at the start of each run, not shared across runs.
+ *
+ *  Internal: deliberately NOT exported from the package. It is wiring between this module
+ *  and `AgentLoop`, and a consumer has no use for it — publishing it would put two types
+ *  in the public API that can never be called usefully from outside. */
+interface LazySearchState {
+    searches: number;
+}
+/** Build the two built-in tools. Returned as ordinary `AgentTool`s so they register,
+ *  dispatch, time out and report through exactly the same path as any other tool.
+ *
+ *  The dependency shape is inline rather than a named interface on purpose: a named type
+ *  in an exported signature lands in the published `.d.ts`, and this one is wiring
+ *  between here and `AgentLoop` that a consumer can never usefully call.
+ *
+ *  `lazyTools` and `eagerNames` are functions, not arrays, because tools can be added
+ *  after construction and search must see them. */
+export declare function createLazyTools(deps: {
+    lazyTools: () => AgentTool[];
+    eagerNames: () => string[];
+    state: LazySearchState;
+    config: LazyToolsConfig;
+    onSearch?: (info: {
+        queries: string[];
+        matched: string[];
+        unmatched: string[];
+    }) => void;
+}): AgentTool[];
+/** The inner tool a `call_tool` invocation targeted, for reporting. Returns null for any
+ *  other call. Traces that attribute every tool call to `call_tool` are useless, and this
+ *  is the one real regression the design causes — so it is fixed at the source. */
+export declare function unwrapLazyCall(toolName: string, args: Record<string, unknown>): string | null;
+export {};

package/dist/agent/loop-config.d.ts

@@ -6,6 +6,7 @@ import type { ConversationHistory } from './history';
 import type { HistorySnapshot } from './history-types';
 import type { ReflectAndRetryConfig } from './reflect-retry';
 import type { AgentTool } from './types';
+import type { LazyToolsConfig } from './lazy-tools';
 import type { Guardrail, ToolInputGuardrail } from './guardrail-types';
 import type { PermissionPolicy } from '../plugins/permissions/policy';
 import type { ApprovalRequest, ApprovalDecision } from './approval-types';
@@ -37,6 +38,14 @@ export interface AgentLoopConfig {
      *  Defaults to `'warn'` so an app that unknowingly has a collision keeps working
      *  (CONSTITUTION.md R4) — the collision just stops being invisible. */
     toolNameCollisionPolicy?: 'warn' | 'error';
+    /** Tuning for tools registered with `lazy: true`. Has no effect when none are — the
+     *  built-in `tool_search` / `call_tool` are declared only if a lazy tool exists, so an
+     *  app that never uses the feature never sees them.
+     *
+     *  There is deliberately no `threshold` here: whether deferring pays depends on the
+     *  SIZE of the tool schemas, not their count, so an automatic cutoff would be guessing.
+     *  Mark tools lazy explicitly. */
+    lazyTools?: LazyToolsConfig;
     /** Self-healing recovery from a recoverable MODEL failure (a malformed tool call, a hallucinated
      *  tool name, a truncated call). The model is given structured guidance naming the attempt and
      *  told not to repeat the same call, then the step is retried within a bounded budget.

package/dist/agent/loop.d.ts

@@ -29,6 +29,13 @@ export declare class AgentLoop {
     private _systemThunk;
     private _context;
     private _tools;
+    private _lazyConfig;
+    /** Per-run search budget, reset at the start of every run. */
+    private _lazyState;
+    /** Installed on the first `lazy` registration and never removed, so the declared tool
+     *  array stays byte-identical for the life of the conversation — which is the entire
+     *  reason the design is cheap. */
+    private _lazyInstalled;
     private _history;
     private _reports;
     private _metadata;
@@ -103,7 +110,26 @@ export declare class AgentLoop {
     private runApprovalGate;
     /** Emit onToolCallComplete, push report, and return success content part. */
     private buildSuccessResult;
-    /** Merge agent's tool definitions with caller-provided tools (caller wins on conflict). */
+    /** Declare `tool_search` + `call_tool`, once, on the first lazy registration.
+     *
+     *  They go through `registerTool` like anything else, so the collision policy covers
+     *  them and there is no second registry to keep in sync. They are never removed: the
+     *  declared array must stay identical for the whole conversation or the cached prefix
+     *  is invalidated, which is the cost the feature exists to avoid. */
+    private installLazyTools;
+    /** Publish (or remove) the "your tools are not all listed" layer.
+     *
+     *  Separate from `installLazyTools` because tools are registered in the constructor
+     *  BEFORE `_history` exists, and the layer lives in the history's registry. The
+     *  constructor calls this again once history is built.
+     *
+     *  The model has no reason to suspect a tool it cannot see, and the failure without
+     *  this is quiet — it answers from whatever it did find. Measured at 8/12 and 9/12
+     *  without the protocol, 18/18 with it, same tasks and same ranker. */
+    private syncLazyProtocol;
+    /** Merge agent's tool definitions with caller-provided tools (caller wins on conflict).
+     *
+     *  Lazy tools are registered but NOT declared — that filter is the whole mechanism. */
     private toolDefinitions;
     private beginRun;
     private finalizeRun;

package/dist/agent/types.d.ts

@@ -1,7 +1,7 @@
 /** Agent-layer shared types — TokenCounter contract used by ContextRegistry,
  *  ConversationHistory, and the ContextMeasurer plugin.
  *  Also defines AgentTool (executable tool) and run-report types. */
-import type { ContentPart, Message } from '../llm/types/messages';
+import type { AssistantPhase, ContentPart, Message } from '../llm/types/messages';
 import type { Tool } from '../llm/types/tools';
 import type { Usage } from '../llm/types/response';
 import type { HistorySnapshot } from './history-types';
@@ -37,6 +37,16 @@ export interface LearnInput {
 export interface AgentTool {
     /** Tool schema sent to the LLM. */
     definition: Tool;
+    /** Register the tool but do NOT declare it: the model finds it with `tool_search` and
+     *  invokes it through `call_tool`. Exposure only — registration, validation and
+     *  collision checking are unchanged, and nothing happens mid-run.
+     *
+     *  Worth it when the tool block is large and a run touches few of them: measured at
+     *  −72% (claude-haiku-4.5) and −97% (gpt-5.4-nano) cost per task across 308 tools, with
+     *  identical correctness, for one extra round trip. NOT worth it for a small tool set —
+     *  below roughly a hundred richly-schema'd tools the saving inverts, because the
+     *  remaining prefix falls under the provider's minimum cacheable size. */
+    lazy?: boolean;
     /** Execute the tool. Return string or structured content. */
     execute: (args: Record<string, unknown>, context: ToolExecutionContext) => Promise<string | ContentPart[]>;
     /** Optional: derive out-of-band metadata from a successful tool result, attached
@@ -73,6 +83,11 @@ export interface ToolCallReport {
     /** Out-of-band metadata from the tool's `customDataExtractor`, if any. Never sent
      *  to the model; present only when an extractor returned a value. */
     customData?: unknown;
+    /** `'search'` when the model reached this tool through `call_tool` after finding it
+     *  with `tool_search`. Absent for a normally-declared tool. `toolName` is the tool that
+     *  actually ran either way — without that unwrapping every lazy call would report
+     *  `call_tool` and attribution would be worthless. */
+    discoveredVia?: 'search';
 }
 export interface StepReport {
     index: number;
@@ -103,9 +118,15 @@ export interface AgentRunReport {
 export type AgentStreamEvent = {
     type: 'step_start';
     step: number;
-} | {
+}
+/** `phase` mirrors the raw stream event: `'commentary'` is the model narrating, anything
+ *  else (usually absent) is the answer. Passed through so a consumer can tell them apart
+ *  LIVE — `finalAnswerText()` only cleans a finished message and cannot touch deltas.
+ *  Absent on every provider that reports no phase, exactly as before. */
+ | {
     type: 'text';
     text: string;
+    phase?: AssistantPhase;
 } | {
     type: 'thinking';
     text: string;

package/dist/bus/hook-map.d.ts

@@ -368,6 +368,19 @@ export interface CostEntry {
     providerEvidence: Record<string, unknown>;
     tags: Record<string, string | undefined>;
 }
+/** One `tool_search` call by the model, when lazy tools are in use.
+ *
+ *  `unmatched` is the field that matters: a query that found nothing is how a
+ *  multi-capability request quietly becomes a partial answer. Watch it to see whether the
+ *  catalog's descriptions actually match the words your users reach for. */
+export interface ToolSearchContext {
+    agentId: string;
+    queries: string[];
+    /** Tool names returned to the model, deduplicated across queries. */
+    matched: string[];
+    /** Queries that matched no tool at all. */
+    unmatched: string[];
+}
 export interface CostEntryContext {
     entry: CostEntry;
     runningTotal: number;
@@ -577,6 +590,7 @@ export interface HookMap {
     onToolCallStart: ToolCallStartContext;
     onToolCallComplete: ToolCallCompleteContext;
     onToolCallError: ToolCallErrorContext;
+    onToolSearch: ToolSearchContext;
     onRunComplete: RunCompleteContext;
     onRunError: RunErrorContext;
     onGuardrailTriggered: GuardrailTriggeredContext;

package/dist/helpers/define-tool.d.ts

@@ -50,17 +50,26 @@ type InferParam<S> = S extends 'string' ? string : S extends 'number' | 'integer
 } ? number : S extends {
     type: 'boolean';
 } ? boolean : unknown;
-type InferArgs<P extends Record<string, ParamSpec>> = {
-    [K in keyof P]: InferParam<P[K]>;
+/** Keys named in `optional` are optional HERE TOO. Typing them as always-present is
+ *  a lie the compiler then helps enforce: `args.unit.toUpperCase()` typechecks and
+ *  throws at runtime whenever the model omits the argument — which, for an argument
+ *  declared optional, is the expected case rather than the edge one. */
+type InferArgs<P extends Record<string, ParamSpec>, O extends keyof P = never> = {
+    [K in Exclude<keyof P, O>]: InferParam<P[K]>;
+} & {
+    [K in Extract<O, keyof P>]?: InferParam<P[K]>;
 };
-export interface DefineToolInput<P extends Record<string, ParamSpec>> {
+export interface DefineToolInput<P extends Record<string, ParamSpec>, O extends keyof P & string = never> {
     name: string;
     description: string;
     /** Object spec — keys are arg names. All keys are treated as required by
      *  default; mark optional ones via `optional: ['x']`. */
     params: P;
-    optional?: ReadonlyArray<keyof P & string>;
-    execute: (args: InferArgs<P>, context: ToolExecutionContext) => Promise<string | ContentPart[]> | string | ContentPart[];
+    optional?: readonly O[];
+    /** Register the tool without declaring it — the model finds it via `tool_search` and
+     *  calls it through `call_tool`. See `AgentTool.lazy`. */
+    lazy?: boolean;
+    execute: (args: InferArgs<P, O>, context: ToolExecutionContext) => Promise<string | ContentPart[]> | string | ContentPart[];
 }
-export declare function defineTool<P extends Record<string, ParamSpec>>(input: DefineToolInput<P>): AgentTool;
+export declare function defineTool<P extends Record<string, ParamSpec>, const O extends keyof P & string = never>(input: DefineToolInput<P, O>): AgentTool;
 export {};

package/dist/helpers/engine.d.ts

@@ -18,7 +18,8 @@
 import { AgentBus } from '../bus/agent-bus';
 import { HookBus } from '../bus/hook-bus';
 import type { ProviderName } from '../llm/types/provider';
-import { NetworkEngine } from '../network/engine';
+import { NetworkEngine, type QueueSettings } from '../network/engine';
+import type { RetryPolicyOverride } from '../network/queue-state-config';
 import type { EngineConnect, EngineFetch, EngineFetchStream, FetchFn } from '../network/types';
 import { Cache } from '../plugins/cache/cache';
 import { CostCollector } from '../plugins/cost-collector/collector';
@@ -94,6 +95,21 @@ export interface EngineConfig {
     /** Per-provider API keys. Helpers consult this when no apiKey is passed
      *  alongside `model: 'provider/...'`. */
     apiKeys?: Partial<Record<ProviderName, string>>;
+    /** Retry policy for every request this engine makes.
+     *
+     *  Retry is a cross-cutting concern, so it is configured once here rather than threaded through
+     *  each call. Anything omitted falls back to the built-in policy (`DEFAULT_RETRY`).
+     *
+     *  ```ts
+     *  createEngine({ retry: { maxRetries: 5, backoff: { initialMs: 200, maxMs: 8_000 } } });
+     *  ```
+     *
+     *  Three layers, narrowest wins: `HttpRequest.retry` (one request) > `queues[name].retry`
+     *  (one provider queue) > this (everything). */
+    retry?: RetryPolicyOverride;
+    /** Per-queue overrides, keyed by queue name (`provider/model` unless routed otherwise).
+     *  Use when one provider needs a different policy from the rest. */
+    queues?: Record<string, QueueSettings>;
     /** Register this engine as the default for `coreRegistry.get()` (used by
      *  helpers when the caller doesn't pass an explicit `engine`). Defaults to
      *  `true` so `createEngine({ ... })` followed by helper calls just works.

package/dist/helpers/mcp.d.ts

@@ -40,6 +40,15 @@ export interface ConnectMcpOptions {
     roots?: McpRoot[] | (() => McpRoot[] | Promise<McpRoot[]>);
     /** Validate tool `structuredContent` against the tool's `outputSchema`. */
     validateOutput?: boolean;
+    /** Register this server's tools WITHOUT declaring them: the model finds them with
+     *  `tool_search` and calls them through `call_tool`. Exposure only — every tool is
+     *  still registered, namespaced and collision-checked exactly as today.
+     *
+     *  This is the common case for the feature, since an MCP server is where a large tool
+     *  block usually comes from. Measured over 308 tools: identical correctness, −72% cost
+     *  per task on claude-haiku-4.5 and −97% on gpt-5.4-nano, for one extra round trip.
+     *  Not worth it for a small server — see `AgentTool.lazy`. */
+    lazy?: boolean;
     /** Send a `ping` every N ms to keep the connection alive (0 = off).
      *  Ignored on a 2026-07-28 session, where `ping` no longer exists. */
     keepAliveMs?: number;

package/dist/helpers/moderate.d.ts

@@ -9,5 +9,17 @@
  *
  *  The moderations endpoint is FREE; an honest-zero cost entry is always emitted
  *  so the cost ledger has a record of each call. HTTP flows through engine.fetch. */
-import type { ModerateOptions, ModerationResult } from './moderate-types';
+import type { ModerateOptions, ModerationContentPart, ModerationResult } from './moderate-types';
+/** One input in, one result out: a single string, or one content-part array that
+ *  together forms a single multimodal item. */
+export declare function moderate(opts: ModerateOptions & {
+    input: string | ModerationContentPart[];
+}): Promise<ModerationResult>;
+/** Many inputs in, one result each, in the same order. */
+export declare function moderate(opts: ModerateOptions & {
+    input: string[] | ModerationContentPart[][];
+}): Promise<ModerationResult[]>;
+/** Fallback for a caller holding the wide `ModerateOptions['input']` union: the
+ *  arity is only knowable at runtime, so the union comes back. Kept so existing
+ *  code that already narrows the result keeps compiling. */
 export declare function moderate(opts: ModerateOptions): Promise<ModerationResult | ModerationResult[]>;