@combycode/llm-sdk 2.0.1 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,290 @@ 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.2.0] — 2026-08-17
+
+### Added
+
+- **Agents can be named: `label`, `source` and an `attributes` bag.** An unlabelled agent
+  exported as a bare `invoke_agent` carrying only a per-process id, so a trace could not say
+  which agent ran or be compared across runs. `label` becomes `gen_ai.agent.name` and names
+  the span (`invoke_agent briefing`); `source` records which part of the host system the
+  agent belongs to, as free text because the taxonomy is the application's; `attributes`
+  stamps anything else onto the run. Library attributes win on a key collision, so the bag
+  cannot rewrite what a span claims to be.
+
+- **`onTrace` -- an event surface, so this SDK can be one source in a bigger pipeline.**
+  Configure it at `createEngine({ telemetry: { types, content, sample, onTrace } })` and take
+  the levels you want: an operator reading business traces does not want our HTTP retries,
+  and an SDK that ships its own exporter just competes with the pipeline they already run.
+  Events carry `traceId` / `spanId` / `parentSpanId`, so a consumer pushes them straight
+  into their own tracer. Nothing is sent anywhere by the library.
+
+  Filtering **splices** the tree rather than punching holes in it -- drop `http` and its
+  children re-parent to the nearest ancestor that subscriber still receives, because a
+  dangling parent renders as a second root. Sampling is per **trace**, hashed from the
+  trace id so two services sharing one agree without coordinating; sampling per span would
+  shred every tree it touched. Conversation content is off by default and rides on
+  `message` events only, never on spans, so spans can go to a metrics backend without
+  carrying prompts into it.
+
+- **The SDK can run inside your application's trace.** Pass `ctx.traceparent` -- the W3C header
+  shape -- and every span the run emits joins that trace and hangs under that span instead of
+  rooting one of its own. A business chain and the model calls it triggers now arrive as one
+  request rather than two unrelated traces. A malformed header is ignored rather than fatal.
+
+### Changed
+
+- **Exported spans follow the GenAI semantic conventions.** `agent.run` and `tool.call` export as
+  `invoke_agent` and `execute_tool {name}`, carrying `gen_ai.operation.name`, `gen_ai.agent.id`,
+  `gen_ai.tool.name` and `gen_ai.tool.call.id`. Names only this library understood forced every
+  consumer to write its own mapping; a backend that speaks the conventions now recognises the work
+  without one. Internal names are unchanged, so `snapshot()` and the sandbox sidebar group as
+  before.
+
+  **If you read span attributes,** three keys moved: `tool.name` → `gen_ai.tool.name`,
+  `agent.id` → `gen_ai.agent.id`, `agent.model` → `gen_ai.request.model`. Span *names* in
+  `snapshot()` are untouched; only the exported ones changed.
+
+### Fixed
+
+- **Spans had no parent, so a backend drew a flat list instead of a tree.** Every span was a
+  sibling, and a turn read as "nine things happened" rather than "a run, which called a tool, which
+  asked a second model". Spans now carry `parentSpanId`, resolved to the innermost enclosing
+  `agent.run` / `tool.call`, else the caller's span, else none.
+
+- **An agent nested inside a tool call orphaned the run around it.** The enclosing span was tracked
+  as one slot per trace, so a second run on the same trace overwrote it and then deleted it on
+  close, leaving the rest of the outer run parentless. It is a stack now, and a container is removed
+  by id rather than popped, because parallel tool calls close out of order.
+
+- **`traceparent` was dropped at two layers, each by hand-picking fields off the trace.** `beginRun`
+  built `{ sessionId, requestId }` and `LLMClient` handed `{ sessionId, requestId, callId }` to the
+  network layer. One request became three traces: the model calls joined the caller's, while
+  `agent.run`, every `tool.call`, every nested agent and every `http.request` rooted their own. The
+  trace now travels whole, and `RunTrace` replaces a shape written inline at eleven signatures.
+
+- **One agent run arrived as several unrelated traces.** The agent built a `runTrace` for its own
+  spans and never handed it to the LLM calls it made, so each call fell through to mint-if-absent and
+  invented its own `requestId`. Since the trace id is `sessionId:requestId`, a single conversation
+  fragmented: measured against a live Grafana Tempo endpoint, one turn with one tool call produced
+  SIX traces. Every span looked correct on its own, which is why it survived until telemetry was
+  pointed at a real backend.
+
+- **A caller's own trace ids were discarded, then half-honoured.** `ctx.sessionId` / `ctx.requestId`
+  now win over the agent's, and the run trace is derived in ONE place from them — deriving it
+  separately for agent spans and LLM calls meant a caller passing only `sessionId` split the run in
+  two. `ctx.conversationId` likewise wins over the history id instead of being silently overwritten.
+
+- **`agent.run` and `tool.call` spans used an entity id as the trace id** — the run id and the tool
+  call id respectively — putting them in a different trace from the work they describe. One span's
+  trace id was literally `t1`. MCP spans keyed their trace by server name, merging every call to a
+  server over the process lifetime into one eternal trace.
+
+- **Span ids collided once a run shared one trace.** The span KEY (`llm:${traceId}`) doubled as the
+  span ID, so every LLM call in a run emitted the same id and the collector merged them into one
+  span. Key and id are now separate.
+
+
+
+
+- **`toOtlpTraces()` produced JSON that only LOOKED like OTLP, and no collector would accept it.**
+  Trace ids went out as `s:r` and span ids as `llm:s:r` where the protocol requires 16- and 8-byte
+  hex; `kind` was the string `'llm'` where it must be the int enum; and every attribute value was
+  `String(value)`, so `gen_ai.usage.input_tokens` arrived as text and could not be summed by any
+  backend. Ids are now derived deterministically from the readable internal ones, so a trace split
+  across two exports still joins up.
+
+- **LLM spans used attribute names no backend recognises.** `gen_ai.provider` / `gen_ai.model` are
+  not in the OTel GenAI semantic conventions; the required names are `gen_ai.provider.name` and
+  `gen_ai.operation.name`, with `gen_ai.request.model`. A span carrying the old names is not
+  identified as a model call at all. Adds `gen_ai.response.model` (the model that actually answered,
+  which an alias can change) and `gen_ai.conversation.id` (the agent's history id).
+
+- **Point spans could share an id, and the backend silently dropped the duplicates.**
+  `mcp:connect:${server}` repeated on every reconnect and `media:${traceId}` repeated for a second
+  image in the same run; `mcp:tool:…:${Date.now()}` collided for two calls in one millisecond. A
+  duplicate span id within a trace is invalid OTLP, so those runs looked like they did less work
+  than they did.
+
+  The in-memory model is unchanged — `snapshot()` still returns readable ids and the domain `kind`,
+  which is what the sandbox groups by. Only the export is translated.
+
+## [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
@@ -449,9 +733,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';
@@ -13,6 +14,25 @@ import type { Persistence } from '../plugins/persistence/types';
 export interface AgentLoopConfig {
     /** LLM client. AgentLoop reads `client.model` and uses `client.complete`/`client.stream`. */
     client: LLMClient;
+    /** Human name for this agent, e.g. `'briefing'`. Without it telemetry only has the
+     *  agent's generated id, and a trace reads as `invoke_agent` with no clue which of your
+     *  agents ran — the ids differ per process, so they cannot be compared across runs
+     *  either. With it the span becomes `invoke_agent briefing` and carries
+     *  `gen_ai.agent.name`, which is what the conventions ask for. */
+    label?: string;
+    /** Which part of YOUR system this agent belongs to, e.g. `'customer'`, `'moderation'`.
+     *
+     *  Free text rather than a fixed set, because the taxonomy is the application's: a
+     *  library cannot know whether you divide by product surface, team, or bounded context,
+     *  and forcing our categories on you would only make you encode yours inside a `label`.
+     *  Exported as `agent.source` — our attribute, not a convention one; the GenAI spec has
+     *  no term for it. */
+    source?: string;
+    /** Extra attributes stamped on this agent's span, for whatever the fixed fields do not
+     *  cover — tenant, tier, experiment arm. Keys are used verbatim, so namespace them
+     *  (`app.tenant`) to stay clear of convention attributes; ours win on a collision, so a
+     *  stray key here cannot corrupt `gen_ai.*`. */
+    attributes?: Record<string, string | number | boolean>;
     /** Persona / role text for the agent. Stored as the `agentloop.system` registry
      *  layer (priority 10). Composed with other system-tagged layers when sending.
      *  When passed as a function, it is re-evaluated at the start of every
@@ -37,6 +57,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-internals.d.ts

@@ -7,6 +7,19 @@ import type { StreamEvent } from '../llm/types/stream';
 import type { TraceContext } from '../network/types';
 import type { AgentStreamEvent, AgentTool, ToolCallReport, ToolExecutionContext } from './types';
 import type { StepState } from './loop-step-state';
+/** The trace one agent run belongs to — resolved once in `beginRun` and handed to
+ *  everything the run emits: its own span, its LLM calls, its tool calls, and any agent
+ *  nested inside a tool.
+ *
+ *  Not a bare `TraceContext` because `sessionId`/`requestId` are always resolved here
+ *  (mint-if-absent), while `traceparent` appears only when the caller runs us inside a
+ *  span of its own. Named rather than written inline because the shape was repeated at
+ *  eleven signatures — and adding a field to ten of them is how a run ends up split
+ *  across two traces. */
+export type RunTrace = TraceContext & {
+    sessionId: string;
+    requestId: string;
+};
 /** Create a fresh StepState for the start of a streaming step. */
 export declare function makeStepState(): StepState;
 /** Accumulate one SSE StreamEvent into StepState.

package/dist/agent/loop.d.ts

@@ -23,12 +23,25 @@ import type { PermissionPolicy } from '../plugins/permissions/policy';
 import type { ApprovalRequest, ApprovalDecision, PendingToolCall } from './approval-types';
 export declare class AgentLoop {
     readonly id: string;
+    /** Human name, surfaced as `gen_ai.agent.name` — see AgentLoopConfig.label. */
+    readonly label?: string;
+    /** Which part of the host system this agent belongs to. */
+    readonly source?: string;
+    /** Extra attributes stamped on this agent's spans. */
+    readonly attributes?: Record<string, string | number | boolean>;
     readonly client: LLMClient;
     readonly hooks: HookBus;
     private _system;
     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 +116,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

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

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

@@ -226,6 +226,12 @@ export interface AgentDestroyContext {
 export interface RunStartContext {
     runId: string;
     agentId: string;
+    /** Human name for the agent, when one was configured. */
+    label?: string;
+    /** Which part of the host system the agent belongs to. */
+    source?: string;
+    /** Extra attributes the host stamped on this agent. */
+    attributes?: Record<string, string | number | boolean>;
     userMessage: string | ContentPart[] | Message[];
     model: string;
     system?: string;
@@ -368,6 +374,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 +596,7 @@ export interface HookMap {
     onToolCallStart: ToolCallStartContext;
     onToolCallComplete: ToolCallCompleteContext;
     onToolCallError: ToolCallErrorContext;
+    onToolSearch: ToolSearchContext;
     onRunComplete: RunCompleteContext;
     onRunError: RunErrorContext;
     onGuardrailTriggered: GuardrailTriggeredContext;