@combycode/llm-sdk 2.0.1 → 2.2.0

package/dist/index.js

@@ -114,6 +114,86 @@ var REDACTED = "***REDACTED***";
 var SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set(["key", "api_key", "access_token", "token"]);
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set(["authorization", "x-goog-api-key", "x-api-key", "api-key"]);
 var MAX_ERROR_RAW_CHARS = 512;
+var OTLP_SPAN_KIND = { internal: 1, client: 3 };
+var OTLP_KIND_BY_SPAN = {
+  llm: OTLP_SPAN_KIND.client,
+  http: OTLP_SPAN_KIND.client,
+  mcp: OTLP_SPAN_KIND.client,
+  media: OTLP_SPAN_KIND.client,
+  agent: OTLP_SPAN_KIND.internal,
+  tool: OTLP_SPAN_KIND.internal,
+  other: OTLP_SPAN_KIND.internal
+};
+function fnv1a32(input, seed) {
+  let h = seed >>> 0;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h >>> 0;
+}
+var isHex = (value, chars) => value.length === chars && /^[0-9a-f]+$/.test(value);
+function toOtlpId(input, bytes) {
+  let out = "";
+  for (let i = 0; i < bytes / 4; i++) {
+    out += fnv1a32(input, 2166136261 + i * 2654435769 >>> 0).toString(16).padStart(8, "0");
+  }
+  return /^0+$/.test(out) ? `${out.slice(0, -1)}1` : out;
+}
+function toOtlpValue(value) {
+  if (typeof value === "boolean") return { boolValue: value };
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  if (typeof value === "string") return { stringValue: value };
+  if (value === null || value === void 0) return { stringValue: "" };
+  return { stringValue: typeof value === "object" ? JSON.stringify(value) : String(value) };
+}
+var SPAN_NAME_SUBJECT = {
+  chat: "gen_ai.request.model",
+  invoke_agent: "gen_ai.agent.name",
+  execute_tool: "gen_ai.tool.name"
+};
+function otlpSpanName(span) {
+  const op = span.attributes["gen_ai.operation.name"];
+  if (typeof op !== "string") return span.name;
+  const subject = SPAN_NAME_SUBJECT[op] ? span.attributes[SPAN_NAME_SUBJECT[op]] : void 0;
+  return typeof subject === "string" && subject ? `${op} ${subject}` : op;
+}
+function toMessageList(payload, defaultRole) {
+  if (payload == null) return [];
+  if (typeof payload === "string") {
+    return payload ? [{ role: defaultRole, content: payload }] : [];
+  }
+  if (Array.isArray(payload)) {
+    const parts2 = payload;
+    if (parts2.length > 0 && parts2[0] && "role" in parts2[0]) {
+      return parts2.map((m) => ({ role: String(m.role ?? defaultRole), content: contentToText(m.content) })).filter((m) => m.content);
+    }
+    const text2 = contentToText(parts2);
+    return text2 ? [{ role: defaultRole, content: text2 }] : [];
+  }
+  const text = contentToText(payload);
+  return text ? [{ role: defaultRole, content: text }] : [];
+}
+function contentToText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => {
+    const p = part;
+    return typeof p?.text === "string" ? p.text : "";
+  }).filter(Boolean).join("");
+}
+var EVENT_TYPE_BY_KIND = {
+  agent: "agent",
+  tool: "tool",
+  llm: "llm",
+  http: "http",
+  mcp: "mcp",
+  media: "media",
+  other: "other"
+};
+var SAMPLE_SEED = 2654435769;
 var CATEGORY = {
   // Network
   onEnqueue: "network",
@@ -182,10 +262,29 @@ function traceIdsOf(ctx) {
   const t = c?.trace ?? c?.ctx ?? c;
   return {
     sessionId: t?.sessionId,
-    requestId: t?.requestId
+    requestId: t?.requestId,
+    /** W3C parent context, when the app is already inside a trace of its own. */
+    traceparent: t?.traceparent,
+    // `gen_ai.conversation.id` in the semantic conventions — the thread a turn
+    // belongs to, which is what lets a backend group turns into one conversation.
+    // AgentLoop sets it from the history id; a bare client call has none.
+    conversationId: t?.conversationId
   };
 }
-var traceKey = (ids) => ids.requestId ? `${ids.sessionId ?? "?"}:${ids.requestId}` : void 0;
+function parseTraceparent(value) {
+  if (!value) return null;
+  const m = /^[0-9a-f]{2}-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/.exec(value.trim().toLowerCase());
+  if (!m) return null;
+  const [, traceId, spanId] = m;
+  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) return null;
+  return { traceId, spanId };
+}
+var CONTAINER_SPANS = /* @__PURE__ */ new Set(["agent.run", "tool.call"]);
+var traceKey = (ids) => {
+  const parent = parseTraceparent(ids.traceparent);
+  if (parent) return parent.traceId;
+  return ids.requestId ? `${ids.sessionId ?? "?"}:${ids.requestId}` : void 0;
+};
 var TelemetryAdapter = class {
   events = [];
   spans = [];
@@ -206,17 +305,138 @@ var TelemetryAdapter = class {
   /** Service identity stamped on exported telemetry. */
   resource;
   seq = 0;
+  /** Discriminator for POINT spans (media, mcp connect/tool), whose natural keys are
+   *  not unique — the same server reconnects, a run emits two images, two tool calls
+   *  land in one millisecond. A duplicate span id inside a trace is invalid OTLP and
+   *  the backend silently keeps only one. */
+  spanSeq = 0;
+  /** Per trace: the app's span from a `traceparent`, and the CONTAINER spans currently
+   *  open on it. Together they decide what a new span hangs under — see `parentFor`.
+   *  Both are cleared once a trace has nothing open, so a long-lived process does not
+   *  accumulate an entry per conversation forever.
+   *
+   *  A list, not a single slot: an agent nested in a tool call (C2 inside C1's tool) is a
+   *  second run on the SAME trace, and with one slot it overwrote its own parent and then
+   *  deleted it on close — leaving the rest of the outer run parentless. */
+  appParent = /* @__PURE__ */ new Map();
+  containers = /* @__PURE__ */ new Map();
   latSum = 0;
   open = /* @__PURE__ */ new Map();
   maxEvents;
   includeSensitiveData;
   unsub;
+  /** Subscribers, each with its own filter. Re-parenting is computed PER SINK: two
+   *  consumers asking for different types each get a tree that is correct for them. */
+  sinks = [];
+  content;
+  sampleRate;
+  /** spanId → its parent and type, for EVERY span including filtered ones — walking up
+   *  past a dropped ancestor is the whole point, so the dropped ones must still be here.
+   *  Bounded, because a long-lived process would otherwise remember every span it ever
+   *  saw. */
+  lineage = /* @__PURE__ */ new Map();
+  maxLineage;
+  msgSeq = 0;
   constructor(hooks, opts = {}) {
     this.maxEvents = opts.maxEvents ?? 2e3;
     this.includeSensitiveData = opts.includeSensitiveData ?? true;
     this.resource = opts.resource ?? { serviceName: "unknown_service" };
+    this.content = opts.content ?? "none";
+    this.sampleRate = opts.sample ?? 1;
+    this.maxLineage = this.maxEvents * 2;
+    if (opts.onTrace) this.onTrace({ types: opts.types }, opts.onTrace);
     this.unsub = hooks.onAny((name, ctx) => this.handle(name, ctx));
   }
+  onTrace(filterOrHandler, maybeHandler) {
+    const handler = typeof filterOrHandler === "function" ? filterOrHandler : maybeHandler;
+    if (!handler) throw new Error("onTrace requires a handler");
+    const filter = typeof filterOrHandler === "function" ? {} : filterOrHandler;
+    const sink = { types: filter.types ? new Set(filter.types) : void 0, handler };
+    this.sinks.push(sink);
+    return () => {
+      const at = this.sinks.indexOf(sink);
+      if (at !== -1) this.sinks.splice(at, 1);
+    };
+  }
+  /** Record a finished span and hand it to the subscribers. Every span reaches the store
+   *  through here, so there is one place where an event can be missed rather than five. */
+  recordSpan(span) {
+    this.spans.push(span);
+    const type = EVENT_TYPE_BY_KIND[span.kind];
+    if (!this.lineage.has(span.spanId)) this.remember(span.spanId, span.parentSpanId, type);
+    this.dispatch({
+      type,
+      traceId: span.traceId,
+      spanId: span.spanId,
+      parentSpanId: span.parentSpanId,
+      name: otlpSpanName(span),
+      startTime: span.startTime,
+      endTime: span.endTime,
+      durationMs: span.durationMs,
+      status: span.status,
+      attributes: span.attributes
+    });
+  }
+  remember(spanId, parentSpanId, type) {
+    this.lineage.set(spanId, { parentSpanId, type });
+    if (this.lineage.size > this.maxLineage) {
+      const oldest = this.lineage.keys().next().value;
+      if (oldest !== void 0) this.lineage.delete(oldest);
+    }
+  }
+  dispatch(event) {
+    if (this.sinks.length === 0) return;
+    if (!this.isSampled(event.traceId)) return;
+    for (const sink of this.sinks) {
+      if (sink.types && !sink.types.has(event.type)) continue;
+      const parentSpanId = sink.types ? this.survivingParent(event.parentSpanId, sink.types) : event.parentSpanId;
+      sink.handler(parentSpanId === event.parentSpanId ? event : { ...event, parentSpanId });
+    }
+  }
+  /** The nearest ancestor this subscriber actually receives. Without this, filtering out
+   *  `http` would leave its children pointing at a span that never arrives, and a backend
+   *  renders a dangling parent as a separate root. */
+  survivingParent(parentSpanId, types) {
+    let id = parentSpanId;
+    while (id) {
+      const node = this.lineage.get(id);
+      if (!node) return void 0;
+      if (types.has(node.type)) return id;
+      id = node.parentSpanId;
+    }
+    return void 0;
+  }
+  /** Hashed rather than random, so the same trace samples the same way in every process
+   *  and a trace shared by two services is kept or dropped by both. */
+  isSampled(traceId) {
+    if (this.sampleRate >= 1) return true;
+    if (this.sampleRate <= 0) return false;
+    return fnv1a32(traceId, SAMPLE_SEED) / 4294967296 < this.sampleRate;
+  }
+  /** Conversation content, as its own event so it can be routed somewhere different from
+   *  the spans — a debug store, not the metrics backend. */
+  emitMessage(span, direction, payload) {
+    if (this.sinks.length === 0) return;
+    const messages = toMessageList(payload, direction === "input" ? "user" : "assistant");
+    if (messages.length === 0) return;
+    const chars = messages.reduce((n, m) => n + m.content.length, 0);
+    this.dispatch({
+      type: "message",
+      traceId: span.traceId,
+      spanId: `${span.spanId}:msg${this.msgSeq++}`,
+      parentSpanId: span.spanId,
+      name: `message.${direction}`,
+      startTime: Date.now(),
+      status: "unset",
+      attributes: clean({
+        "message.direction": direction,
+        "message.count": messages.length,
+        "message.chars": chars,
+        // Opt-In in the spec, and off by default here for the same reason.
+        [`gen_ai.${direction}.messages`]: this.content === "full" ? messages : void 0
+      })
+    });
+  }
   /** Stop tapping the bus. */
   destroy() {
     this.unsub();
@@ -224,6 +444,8 @@ var TelemetryAdapter = class {
   handle(name, ctx) {
     const ids = traceIdsOf(ctx);
     const traceId = traceKey(ids);
+    const parent = parseTraceparent(ids.traceparent);
+    if (parent && traceId) this.appParent.set(traceId, parent.spanId);
     this.events.push({
       seq: this.seq++,
       time: Date.now(),
@@ -246,20 +468,27 @@ var TelemetryAdapter = class {
           this.metrics.outputTokens += usage.outputTokens ?? 0;
         }
         if (traceId) {
+          const responseModel = c.response?.model;
           const attrs = {
-            "gen_ai.provider": c.provider,
-            "gen_ai.model": c.model,
+            "gen_ai.provider.name": c.provider,
+            "gen_ai.operation.name": "chat",
+            "gen_ai.request.model": c.model,
+            // The model that actually answered, which can differ from the one asked
+            // for (an alias resolving to a dated snapshot, a router picking a peer).
+            "gen_ai.response.model": responseModel,
+            "gen_ai.conversation.id": ids.conversationId,
             "gen_ai.usage.input_tokens": usage?.inputTokens,
             "gen_ai.usage.output_tokens": usage?.outputTokens
           };
           const key = `llm:${traceId}`;
+          let llmSpan;
           if (this.open.has(key)) {
-            this.closeSpan(key, "ok", attrs);
+            llmSpan = this.closeSpan(key, "ok", attrs);
           } else {
             const http = [...this.spans].reverse().find((s) => s.traceId === traceId && s.kind === "http");
             const start = http?.startTime ?? Date.now();
             const end = Date.now();
-            this.spans.push({
+            llmSpan = {
               traceId,
               spanId: key,
               name: "llm.request",
@@ -269,7 +498,12 @@ var TelemetryAdapter = class {
               durationMs: end - start,
               status: "ok",
               attributes: clean(attrs)
-            });
+            };
+            this.recordSpan(llmSpan);
+          }
+          if (llmSpan) {
+            const response = c.response;
+            this.emitMessage(llmSpan, "output", response?.content ?? response?.text);
           }
         }
         break;
@@ -315,9 +549,11 @@ var TelemetryAdapter = class {
         this.metrics.mediaGenerated += c.count ?? 1;
         if (traceId) {
           const now = Date.now();
-          this.spans.push({
+          this.recordSpan({
             traceId,
-            spanId: `media:${traceId}`,
+            // One run can generate several images; `media:${traceId}` would give them
+            // all the same span id, which is invalid within a trace.
+            spanId: `media:${traceId}:${this.spanSeq++}`,
             name: "media.generate",
             kind: "media",
             startTime: now,
@@ -332,10 +568,21 @@ var TelemetryAdapter = class {
       case "onRunStart": {
         const runId = c.runId;
         if (runId) {
-          this.openSpan(`agent:${runId}`, runId, "agent.run", "agent", {
-            "agent.id": c.agentId,
-            "agent.model": c.model
+          const runSpan = this.openSpan(`agent:${runId}`, traceId ?? runId, "agent.run", "agent", {
+            // The host's own attributes go FIRST so ours win on a key collision: a stray
+            // `gen_ai.*` key in a caller's bag must not be able to rewrite the identity
+            // of the span.
+            ...c.attributes,
+            "gen_ai.operation.name": "invoke_agent",
+            // Named when the agent was given a label; the exported span is then
+            // `invoke_agent {label}` rather than the bare operation.
+            "gen_ai.agent.name": c.label,
+            "gen_ai.agent.id": c.agentId,
+            "gen_ai.request.model": c.model,
+            // Ours, not a convention attribute — the GenAI spec has no term for it.
+            "agent.source": c.source
           });
+          this.emitMessage(runSpan, "input", c.userMessage);
         }
         break;
       }
@@ -362,9 +609,11 @@ var TelemetryAdapter = class {
       case "onToolCallStart": {
         const callId = c.callId;
         if (callId) {
-          this.openSpan(`tool:${callId}`, callId, "tool.call", "tool", {
-            "tool.name": c.toolName,
-            "agent.id": c.agentId
+          this.openSpan(`tool:${callId}`, traceId ?? callId, "tool.call", "tool", {
+            "gen_ai.operation.name": "execute_tool",
+            "gen_ai.tool.name": c.toolName,
+            "gen_ai.tool.call.id": callId,
+            "gen_ai.agent.id": c.agentId
           });
         }
         break;
@@ -373,7 +622,7 @@ var TelemetryAdapter = class {
         const callId = c.callId;
         if (callId) {
           this.closeSpan(`tool:${callId}`, "ok", {
-            "tool.name": c.toolName,
+            "gen_ai.tool.name": c.toolName,
             "tool.latency_ms": c.latencyMs
           });
         }
@@ -383,7 +632,7 @@ var TelemetryAdapter = class {
         const callId = c.callId;
         if (callId) {
           this.closeSpan(`tool:${callId}`, "error", {
-            "tool.name": c.toolName,
+            "gen_ai.tool.name": c.toolName,
             "tool.error": c.error?.message
           });
         }
@@ -394,9 +643,17 @@ var TelemetryAdapter = class {
         const server = c.server;
         if (server) {
           const now = Date.now();
-          this.spans.push({
-            traceId: server,
-            spanId: `mcp:connect:${server}`,
+          this.recordSpan({
+            // A connect usually happens at startup, outside any run, so there is often
+            // no trace to join — but keying the trace by server name merged every
+            // reconnect over the process lifetime into one trace. Falls back to a span
+            // of its own instead.
+            traceId: traceId ?? `mcp:connect:${server}:${this.spanSeq}`,
+            // `${server}` alone repeats on every reconnect, and a duplicate span id
+            // within a trace is invalid OTLP — the backend keeps one and drops the
+            // rest. The counter is monotonic where a timestamp is not: two connects
+            // inside the same millisecond would still collide.
+            spanId: `mcp:connect:${server}:${this.spanSeq++}`,
             name: "mcp.connect",
             kind: "mcp",
             startTime: now,
@@ -418,9 +675,14 @@ var TelemetryAdapter = class {
         if (server && tool) {
           const now = Date.now();
           const lat = c.latencyMs;
-          this.spans.push({
-            traceId: server,
-            spanId: `mcp:tool:${server}:${tool}:${now}`,
+          this.recordSpan({
+            // An MCP tool call happens INSIDE a run, so it belongs to that run's trace.
+            // Keying it by server put every call to one server in a single eternal
+            // trace, and none of them with the agent that made the call.
+            traceId: traceId ?? `mcp:${server}`,
+            // A timestamp is not a unique key: two tool calls in the same millisecond
+            // share it. The counter is.
+            spanId: `mcp:tool:${server}:${tool}:${this.spanSeq++}`,
             name: "mcp.tool_call",
             kind: "mcp",
             startTime: now - (lat ?? 0),
@@ -438,10 +700,33 @@ var TelemetryAdapter = class {
       }
     }
   }
+  /** What a new span on this trace hangs under: the innermost container still open on
+   *  it, else the app's span, else nothing (we are the root).
+   *
+   *  A container wins over the app's span because an LLM call made during a run belongs
+   *  to that run — attaching it straight to the app would flatten the very nesting the
+   *  tree exists to show. A span joins the stack only after it is built, so nothing can
+   *  become its own parent, and a run nested in a tool call lands under that tool call —
+   *  exactly where it happened.
+   *
+   *  Limit worth naming: with tools running in parallel two `tool.call` spans are open at
+   *  once and "innermost" is merely the more recent one. Attributing a nested run to the
+   *  right sibling needs real async context propagation, which this adapter does not
+   *  have; sequential tools, the common case, are exact. */
+  parentFor(traceId) {
+    const stack = this.containers.get(traceId);
+    return stack?.[stack.length - 1] ?? this.appParent.get(traceId);
+  }
   openSpan(key, traceId, spanName, kind, attributes) {
+    const parentSpanId = this.parentFor(traceId);
     const span = {
       traceId,
-      spanId: key,
+      ...parentSpanId ? { parentSpanId } : {},
+      // The KEY pairs open with close (`llm:${traceId}`); the SPAN ID must be unique.
+      // Those were the same string until a run stopped fragmenting into one trace per
+      // call — at which point every LLM call in a run produced the identical key, and
+      // the collision merged them into one span at the collector.
+      spanId: `${key}#${this.spanSeq++}`,
       name: spanName,
       kind,
       startTime: Date.now(),
@@ -449,17 +734,33 @@ var TelemetryAdapter = class {
       attributes
     };
     this.open.set(key, span);
+    this.remember(span.spanId, parentSpanId, EVENT_TYPE_BY_KIND[kind]);
+    if (CONTAINER_SPANS.has(spanName)) {
+      const stack = this.containers.get(traceId);
+      if (stack) stack.push(span.spanId);
+      else this.containers.set(traceId, [span.spanId]);
+    }
     return span;
   }
   closeSpan(key, status, attributes) {
     const span = this.open.get(key);
-    if (!span) return;
+    if (!span) return void 0;
+    const stack = this.containers.get(span.traceId);
+    if (stack) {
+      const at = stack.lastIndexOf(span.spanId);
+      if (at !== -1) stack.splice(at, 1);
+      if (stack.length === 0) {
+        this.containers.delete(span.traceId);
+        this.appParent.delete(span.traceId);
+      }
+    }
     span.endTime = Date.now();
     span.durationMs = span.endTime - span.startTime;
     span.status = status;
     Object.assign(span.attributes, clean(attributes));
     this.open.delete(key);
-    this.spans.push(span);
+    this.recordSpan(span);
+    return span;
   }
   recordLatency(ms) {
     if (typeof ms !== "number") return;
@@ -509,14 +810,27 @@ var TelemetryAdapter = class {
             {
               scope: { name: "combycode.telemetry" },
               spans: this.spans.map((s) => ({
-                traceId: s.traceId,
-                spanId: s.spanId,
-                name: s.name,
+                // An app-supplied trace id is ALREADY a real 32-hex id — hashing it
+                // would produce a different trace and defeat the whole point of
+                // accepting a parent.
+                traceId: isHex(s.traceId, 32) ? s.traceId : toOtlpId(s.traceId, 16),
+                // Scoped by trace: two conversations can each hold a span keyed
+                // `llm:…`, and colliding their ids would merge unrelated traces.
+                spanId: toOtlpId(`${s.traceId}|${s.spanId}`, 8),
+                // The app's own span id arrives as hex and passes through; one of ours
+                // is hashed exactly as it was when we emitted it, so the link matches.
+                ...s.parentSpanId ? {
+                  parentSpanId: isHex(s.parentSpanId, 16) ? s.parentSpanId : toOtlpId(`${s.traceId}|${s.parentSpanId}`, 8)
+                } : {},
+                name: otlpSpanName(s),
                 startTimeUnixNano: Math.round(s.startTime * 1e6),
                 endTimeUnixNano: Math.round((s.endTime ?? s.startTime) * 1e6),
-                kind: s.kind,
+                kind: OTLP_KIND_BY_SPAN[s.kind] ?? OTLP_SPAN_KIND.internal,
                 status: { code: s.status === "error" ? 2 : s.status === "ok" ? 1 : 0 },
-                attributes: Object.entries(s.attributes).map(([key, value]) => ({ key, value: { stringValue: String(value) } }))
+                attributes: Object.entries(s.attributes).map(([key, value]) => ({
+                  key,
+                  value: toOtlpValue(value)
+                }))
               }))
             }
           ]
@@ -2703,12 +3017,15 @@ var NetworkEngine = class {
   hooks;
   fetchFn;
   connectFn;
+  /** Engine-wide retry policy, inherited by every queue created from here. */
+  defaultRetry;
   settings = /* @__PURE__ */ new Map();
   queues = /* @__PURE__ */ new Map();
   constructor(config) {
     this.hooks = config?.hooks ?? new HookBus();
     this.fetchFn = config?.fetch ?? globalThis.fetch.bind(globalThis);
     this.connectFn = config?.connect ?? defaultConnectFn;
+    this.defaultRetry = config?.retry;
     if (config?.queues) {
       for (const [name, settings] of Object.entries(config.queues)) {
         this.settings.set(name, settings);
@@ -2790,12 +3107,18 @@ var NetworkEngine = class {
       ...FALLBACK_LIMITS,
       ...settings.limits
     };
+    const retry = this.defaultRetry || settings.retry ? {
+      ...this.defaultRetry,
+      ...settings.retry,
+      ...this.defaultRetry?.backoff || settings.retry?.backoff ? { backoff: { ...this.defaultRetry?.backoff, ...settings.retry?.backoff } } : {},
+      ...this.defaultRetry?.perKind || settings.retry?.perKind ? { perKind: { ...this.defaultRetry?.perKind, ...settings.retry?.perKind } } : {}
+    } : void 0;
     const config = {
       queueName,
       fetch: this.fetchFn,
       hooks: this.hooks,
       limits,
-      retry: settings.retry,
+      retry,
       queue: settings.queue
     };
     queue = new QueueState(config);
@@ -2872,6 +3195,62 @@ function ensureAdditionalProperties(schema) {
   }
   return result;
 }
+var ANTHROPIC_UNSUPPORTED = /* @__PURE__ */ new Set([
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "maxItems"
+]);
+function strictSupport(schema, dialect) {
+  const visit = (node, path) => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return null;
+    const n = node;
+    const at = path || "(root)";
+    if (typeof n.$ref === "string") return `${at}: '$ref' cannot be verified without resolution`;
+    if (dialect === "anthropic") {
+      for (const key of Object.keys(n)) {
+        if (ANTHROPIC_UNSUPPORTED.has(key)) return `${at}: '${key}' is not supported under strict`;
+      }
+    }
+    const props = n.properties;
+    if (n.additionalProperties !== void 0 && n.additionalProperties !== false) {
+      return `${at}: 'additionalProperties' must be false under strict`;
+    }
+    if (dialect === "openai") {
+      if (n.type === "object" && props === void 0) {
+        return `${at}: an object schema with no 'properties' cannot be strict (a free-form object is not expressible)`;
+      }
+    }
+    if (props && typeof props === "object") {
+      if (dialect === "openai") {
+        const required = new Set(Array.isArray(n.required) ? n.required : []);
+        const missing = Object.keys(props).filter((k) => !required.has(k));
+        if (missing.length > 0) return `${at}: ${missing.join(", ")} not listed in 'required'`;
+      }
+      for (const [key, val] of Object.entries(props)) {
+        const r = visit(val, path ? `${path}.${key}` : key);
+        if (r) return r;
+      }
+    }
+    for (const key of ["items", "additionalProperties"]) {
+      const r = visit(n[key], path ? `${path}.${key}` : key);
+      if (r) return r;
+    }
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+      const branches = n[key];
+      if (!Array.isArray(branches)) continue;
+      for (const [i, sub] of branches.entries()) {
+        const r = visit(sub, `${at}.${key}[${i}]`);
+        if (r) return r;
+      }
+    }
+    return null;
+  };
+  const reason = visit(schema, "");
+  return reason ? { ok: false, reason } : { ok: true };
+}
 
 // src/llm/providers/anthropic/catalog.json
 var catalog_default = {
@@ -25082,7 +25461,7 @@ function extractSystem(messages) {
   const rest = [];
   for (const m of messages) {
     if (m.role === "system") {
-      const text = typeof m.content === "string" ? m.content : contentToText(m.content);
+      const text = typeof m.content === "string" ? m.content : contentToText2(m.content);
       if (text) systemTexts.push(text);
     } else {
       rest.push(m);
@@ -25093,7 +25472,7 @@ function extractSystem(messages) {
     messages: rest
   };
 }
-function contentToText(content) {
+function contentToText2(content) {
   return content.filter((p) => p.type === "text").map((p) => p.text).join("\n");
 }
 function parseStructured(text) {
@@ -25375,7 +25754,15 @@ var LLMClient = class {
         signal: options.signal,
         provider: this.provider,
         model: this.model,
-        trace: { sessionId: ctx.sessionId, requestId: ctx.requestId, callId: ctx.callId }
+        // Every trace field, not a hand-picked three: `traceparent` rides with the ids,
+        // and picking fields here is what left the HTTP spans rooting a trace of their
+        // own while the LLM span they belong to had joined the caller's.
+        trace: {
+          sessionId: ctx.sessionId,
+          requestId: ctx.requestId,
+          callId: ctx.callId,
+          traceparent: ctx.traceparent
+        }
       };
       response = await this.fetchFn(httpReq, {
         queueName: this.queueName,
@@ -25503,7 +25890,15 @@ var LLMClient = class {
       stream: true,
       provider: this.provider,
       model: this.model,
-      trace: { sessionId: ctx.sessionId, requestId: ctx.requestId, callId: ctx.callId }
+      // Every trace field, not a hand-picked three: `traceparent` rides with the ids,
+      // and picking fields here is what left the HTTP spans rooting a trace of their
+      // own while the LLM span they belong to had joined the caller's.
+      trace: {
+        sessionId: ctx.sessionId,
+        requestId: ctx.requestId,
+        callId: ctx.callId,
+        traceparent: ctx.traceparent
+      }
     };
     const start = performance.now();
     let text = "";
@@ -25985,12 +26380,16 @@ var AnthropicAdapter = class {
           }
           return null;
         }
+        const strict = t.strict === true;
+        const params = ensureAdditionalProperties(t.parameters);
         const tool = {
           name: t.name,
           description: t.description,
-          input_schema: t.parameters
+          // Only the strict path was measured with `additionalProperties: false`
+          // applied; without strict the schema goes out untouched, as before.
+          input_schema: strict ? params : t.parameters
         };
-        if (t.strict) tool.strict = true;
+        if (strict) tool.strict = true;
         if ((t.cache || shouldCacheTools) && i === req.tools.length - 1) {
           tool.cache_control = { type: "ephemeral" };
         }
@@ -28039,15 +28438,19 @@ var OpenAIAdapter = class {
       };
     }
     if (req.tools?.length) {
-      body.tools = req.tools.filter(isFunctionTool).map((t) => ({
-        type: "function",
-        function: {
-          name: t.name,
-          description: t.description,
-          parameters: t.parameters,
-          ...t.strict ? { strict: true } : {}
-        }
-      }));
+      body.tools = req.tools.filter(isFunctionTool).map((t) => {
+        const params = ensureAdditionalProperties(t.parameters);
+        const strict = t.strict === true;
+        return {
+          type: "function",
+          function: {
+            name: t.name,
+            description: t.description,
+            parameters: strict ? params : t.parameters,
+            ...strict ? { strict: true } : {}
+          }
+        };
+      });
     }
     if (req.toolChoice) {
       if (typeof req.toolChoice === "string") body.tool_choice = req.toolChoice;
@@ -28057,12 +28460,14 @@ var OpenAIAdapter = class {
       body.reasoning = { effort: req.thinking.effort ?? "medium" };
     }
     if (req.structured) {
+      const schema = ensureAdditionalProperties(req.structured.schema);
+      const strict = req.structured.strict ?? strictSupport(schema, "openai").ok;
       body.response_format = {
         type: "json_schema",
         json_schema: {
           name: req.structured.name ?? "response",
-          schema: req.structured.schema,
-          strict: req.structured.strict ?? true
+          schema: strict ? schema : req.structured.schema,
+          strict
         }
       };
     }
@@ -28962,12 +29367,13 @@ var OpenAIResponsesAdapter = class {
     if (req.tools?.length) {
       body.tools = req.tools.map((t) => {
         if (isFunctionTool(t)) {
+          const params = ensureAdditionalProperties(t.parameters);
           return {
             type: "function",
             name: t.name,
             description: t.description,
-            parameters: ensureAdditionalProperties(t.parameters),
-            strict: t.strict ?? true,
+            parameters: params,
+            strict: t.strict ?? strictSupport(params, "openai").ok,
             // Programmatic tool calling (Responses): who may call it + return schema.
             ...t.allowedCallers ? { allowed_callers: t.allowedCallers } : {},
             ...t.outputSchema ? { output_schema: t.outputSchema } : {}
@@ -28988,12 +29394,13 @@ var OpenAIResponsesAdapter = class {
       }
     }
     if (req.structured) {
+      const schema = ensureAdditionalProperties(req.structured.schema);
       body.text = {
         format: {
           type: "json_schema",
           name: req.structured.name ?? "response",
-          schema: ensureAdditionalProperties(req.structured.schema),
-          strict: req.structured.strict ?? true
+          schema,
+          strict: req.structured.strict ?? strictSupport(schema, "openai").ok
         }
       };
     }
@@ -30587,7 +30994,9 @@ var LAYER_MEMORY = "memory";
 var LAYER_CHAT_FACTS = "chat.facts";
 var LAYER_EXECUTOR_TOOL_EXAMPLES = "executor.tool-examples";
 var LAYER_CONTEXT_GUARD_SUMMARY = "context-guard.summary";
+var LAYER_LAZY_TOOLS = "agentloop.lazy-tools";
 var PRIORITY_AGENTLOOP_SYSTEM = 10;
+var PRIORITY_LAZY_TOOLS = 20;
 var PRIORITY_LEGACY_SYSTEM = 50;
 var PRIORITY_AGENTLOOP_CONTEXT = 100;
 var PRIORITY_MEMORY = 200;
@@ -30605,6 +31014,17 @@ function writeAgentLoopSystem(registry, text, owner) {
     owner
   });
 }
+function writeLazyToolsProtocol(registry, active, owner) {
+  if (!active) {
+    registry.remove(LAYER_LAZY_TOOLS);
+    return;
+  }
+  registry.set(
+    LAYER_LAZY_TOOLS,
+    "Not all of your tools are listed. Use `tool_search` to find the ones you need \u2014 it returns their exact names and full argument schemas \u2014 then run them with `call_tool`. Search for every capability the request needs in ONE call, passing several queries. If the result reports a query as unmatched, search again with different words before answering; never answer as if a capability you could not find does not matter.",
+    { priority: PRIORITY_LAZY_TOOLS, tags: ["system"], owner }
+  );
+}
 function writeAgentLoopContext(registry, text, owner) {
   if (!text) {
     registry.remove(LAYER_AGENTLOOP_CONTEXT);
@@ -30956,6 +31376,175 @@ ${text}` : text;
   }
 };
 
+// src/agent/lazy-tools.ts
+var DEFAULT_LIMIT = 5;
+var MAX_LIMIT = 20;
+var DEFAULT_MAX_SEARCHES = 5;
+var LAZY_SEARCH_TOOL = "tool_search";
+var LAZY_CALL_TOOL = "call_tool";
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "of",
+  "for",
+  "to",
+  "in",
+  "on",
+  "and",
+  "or",
+  "is",
+  "it",
+  "that",
+  "this",
+  "with",
+  "return",
+  "returns",
+  "my",
+  "me",
+  "do",
+  "we",
+  "i",
+  "how",
+  "many",
+  "much",
+  "what",
+  "when",
+  "has",
+  "have",
+  "need",
+  "any",
+  "get",
+  "can",
+  "you",
+  "are",
+  "was",
+  "been",
+  "does",
+  "did",
+  "should",
+  "from",
+  "by",
+  "at",
+  "as",
+  "be"
+]);
+function tokenize(s) {
+  return s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2 && !STOP_WORDS.has(w));
+}
+var isFn = (t) => "name" in t;
+var nameOf = (t) => isFn(t.definition) ? t.definition.name : "";
+function rankTools(query, candidates, limit) {
+  const q = new Set(tokenize(query));
+  if (q.size === 0) return [];
+  const scored = [];
+  for (const tool of candidates) {
+    const def = tool.definition;
+    if (!isFn(def)) continue;
+    const props = Object.keys(
+      def.parameters?.properties ?? {}
+    );
+    let score = 0;
+    for (const w of tokenize(`${def.name} ${def.description ?? ""} ${props.join(" ")}`)) {
+      if (q.has(w)) score++;
+    }
+    for (const w of tokenize(def.name)) if (q.has(w)) score += 2;
+    if (score > 0) scored.push({ tool, score });
+  }
+  return scored.sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.tool);
+}
+function createLazyTools(deps) {
+  const limit = Math.min(deps.config.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+  const maxSearches = deps.config.maxSearches ?? DEFAULT_MAX_SEARCHES;
+  const search = {
+    definition: {
+      type: "function",
+      name: LAZY_SEARCH_TOOL,
+      description: "Find the tools you need. Returns their exact names and full argument schemas. Pass every capability you need as a separate query in one call.",
+      parameters: {
+        type: "object",
+        properties: {
+          queries: {
+            type: "array",
+            items: { type: "string" },
+            description: "One phrase per capability you need, in your own words."
+          }
+        },
+        required: ["queries"]
+      }
+    },
+    execute: async (args) => {
+      deps.state.searches++;
+      if (deps.state.searches > maxSearches) {
+        return JSON.stringify({
+          error: `Search budget exhausted (${maxSearches} searches per run). Use the tools you already found.`
+        });
+      }
+      const raw = args.queries;
+      const queries = (Array.isArray(raw) ? raw : [raw]).filter((q) => typeof q === "string" && q.trim().length > 0);
+      if (queries.length === 0) {
+        return JSON.stringify({ tools: [], error: "Pass at least one query string in `queries`." });
+      }
+      const candidates = deps.lazyTools();
+      const hits = /* @__PURE__ */ new Map();
+      const unmatched = [];
+      for (const q of queries) {
+        const found = rankTools(q, candidates, limit);
+        if (found.length === 0) unmatched.push(q);
+        for (const t of found) hits.set(nameOf(t), t);
+      }
+      deps.onSearch?.({ queries, matched: [...hits.keys()], unmatched });
+      return JSON.stringify({
+        tools: [...hits.values()].map((t) => t.definition),
+        ...unmatched.length > 0 ? {
+          unmatched,
+          hint: "These queries matched no tool. Search again for them using different words, or tell the user the capability is unavailable."
+        } : {}
+      });
+    }
+  };
+  const call = {
+    definition: {
+      type: "function",
+      name: LAZY_CALL_TOOL,
+      description: "Call one tool returned by tool_search. Pass its exact name and its own arguments as `input`. To use several tools, call this several times in the same turn.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Exact tool name from tool_search." },
+          input: {
+            type: "object",
+            description: "That tool's own arguments, as an object.",
+            additionalProperties: true
+          }
+        },
+        required: ["name", "input"]
+      }
+    },
+    execute: async (args, ctx) => {
+      const name = String(args.name ?? "");
+      const target = deps.lazyTools().find((t) => nameOf(t) === name);
+      if (!target) {
+        if (deps.eagerNames().includes(name)) {
+          return `"${name}" is already available as a normal tool \u2014 call it directly, not through ${LAZY_CALL_TOOL}.`;
+        }
+        return `No tool named "${name}". Call ${LAZY_SEARCH_TOOL} first and use a name exactly as returned.`;
+      }
+      const input = args.input;
+      if (input !== void 0 && (typeof input !== "object" || input === null || Array.isArray(input))) {
+        return `\`input\` must be an object of ${name}'s arguments, not ${Array.isArray(input) ? "an array" : typeof input}.`;
+      }
+      return target.execute(input ?? {}, ctx);
+    }
+  };
+  return [search, call];
+}
+function unwrapLazyCall(toolName, args) {
+  if (toolName !== LAZY_CALL_TOOL) return null;
+  const inner = args.name;
+  return typeof inner === "string" && inner.length > 0 ? inner : null;
+}
+
 // src/agent/tool-key.ts
 function toolKey(tool) {
   return isFunctionTool(tool.definition) ? tool.definition.name : tool.definition.type;
@@ -31216,12 +31805,25 @@ async function handleToolError(e, tc, hooks, runId, agentId, step, metrics, repo
 // src/agent/loop.ts
 var AgentLoop = class _AgentLoop {
   id;
+  /** Human name, surfaced as `gen_ai.agent.name` — see AgentLoopConfig.label. */
+  label;
+  /** Which part of the host system this agent belongs to. */
+  source;
+  /** Extra attributes stamped on this agent's spans. */
+  attributes;
   client;
   hooks;
   _system;
   _systemThunk = null;
   _context;
   _tools;
+  _lazyConfig = {};
+  /** Per-run search budget, reset at the start of every run. */
+  _lazyState = { searches: 0 };
+  /** 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. */
+  _lazyInstalled = false;
   _history;
   _reports = [];
   _metadata = {};
@@ -31269,6 +31871,7 @@ var AgentLoop = class _AgentLoop {
     this._checkpoint = config.checkpoint ?? null;
     this._collisionPolicy = config.toolNameCollisionPolicy ?? "warn";
     this._reflectRetry = config.reflectAndRetry ? new ReflectAndRetryPolicy(config.reflectAndRetry) : null;
+    this._lazyConfig = config.lazyTools ?? {};
     this._tools = /* @__PURE__ */ new Map();
     for (const t of config.tools ?? []) {
       this.registerTool(t);
@@ -31281,8 +31884,12 @@ var AgentLoop = class _AgentLoop {
       this._history = new ConversationHistory();
     }
     this.id = this._history.id;
+    this.label = config.label;
+    this.source = config.source;
+    this.attributes = config.attributes;
     writeAgentLoopSystem(this._history.registry, this._system, "agent-loop");
     writeAgentLoopContext(this._history.registry, this._context, "agent-loop");
+    this.syncLazyProtocol();
     this.hooks.emitSync("onAgentCreate", {
       agentId: this.id,
       clientId: this.client.id,
@@ -31369,6 +31976,7 @@ var AgentLoop = class _AgentLoop {
       });
     }
     this._tools.set(key, tool);
+    if (tool.lazy) this.installLazyTools();
   }
   removeTool(name) {
     this._tools.delete(name);
@@ -31383,7 +31991,7 @@ var AgentLoop = class _AgentLoop {
   }
   // ─── complete (non-streaming) ───────────────────────────────────────────
   async complete(input, options = {}) {
-    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input);
+    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input, options.ctx);
     const steps = [];
     const totalUsage = emptyUsage();
     let totalLlmTimeMs = 0;
@@ -31435,7 +32043,23 @@ var AgentLoop = class _AgentLoop {
           thinking: options.thinking ?? this._thinking,
           cache: options.cache ?? this._cache,
           tools: this.toolDefinitions(options),
-          ctx: { ...options.ctx, conversationId: this._history.id },
+          ctx: {
+            // The RUN's trace, handed down to every LLM call it makes.
+            //
+            // Without this the agent kept `runTrace` to itself: its own spans used it
+            // while each `client.complete()` fell through to mint-if-absent and
+            // invented a fresh `requestId`. Since the trace id is `sessionId:requestId`,
+            // one conversation arrived at the backend as SEVERAL unrelated traces —
+            // measured against a real collector: a single turn with one tool call
+            // produced six. Correlation is the whole point of a trace id, so this is
+            // the one thing it must not get wrong.
+            ...runTrace,
+            conversationId: this._history.id,
+            // A caller's explicit ctx wins over all of the above: an app that already
+            // owns a request id or a conversation id has better information than we do,
+            // and silently overwriting it is how its telemetry stops joining up.
+            ...options.ctx
+          },
           signal: options.signal ?? this._abortController?.signal
         });
         const stepLatency = performance.now() - stepStart;
@@ -31603,7 +32227,7 @@ var AgentLoop = class _AgentLoop {
   }
   // ─── stream ─────────────────────────────────────────────────────────────
   async *stream(input, options = {}) {
-    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input);
+    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input, options.ctx);
     const steps = [];
     const totalUsage = emptyUsage();
     let totalLlmTimeMs = 0;
@@ -31659,7 +32283,23 @@ var AgentLoop = class _AgentLoop {
           thinking: options.thinking ?? this._thinking,
           cache: options.cache ?? this._cache,
           tools: this.toolDefinitions(options),
-          ctx: { ...options.ctx, conversationId: this._history.id },
+          ctx: {
+            // The RUN's trace, handed down to every LLM call it makes.
+            //
+            // Without this the agent kept `runTrace` to itself: its own spans used it
+            // while each `client.complete()` fell through to mint-if-absent and
+            // invented a fresh `requestId`. Since the trace id is `sessionId:requestId`,
+            // one conversation arrived at the backend as SEVERAL unrelated traces —
+            // measured against a real collector: a single turn with one tool call
+            // produced six. Correlation is the whole point of a trace id, so this is
+            // the one thing it must not get wrong.
+            ...runTrace,
+            conversationId: this._history.id,
+            // A caller's explicit ctx wins over all of the above: an app that already
+            // owns a request id or a conversation id has better information than we do,
+            // and silently overwriting it is how its telemetry stops joining up.
+            ...options.ctx
+          },
           signal: options.signal ?? this._abortController?.signal
         })) {
           const toYield = accumulateStreamEvent(event, state);
@@ -31871,7 +32511,7 @@ var AgentLoop = class _AgentLoop {
         arguments: tc.arguments,
         callId: tc.id,
         step,
-        trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id }
+        trace: { ...runTrace, callId: tc.id }
       });
       if (!decision.pass) {
         return this.buildDeniedResult(tc, decision.reason, reports);
@@ -31891,7 +32531,7 @@ var AgentLoop = class _AgentLoop {
       }
     }
     try {
-      const baseCtx = { step, callId: tc.id, metrics, trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id } };
+      const baseCtx = { step, callId: tc.id, metrics, trace: { ...runTrace, callId: tc.id } };
       const result = await executeWithTimeout(lookup.tool, tc, baseCtx, this._toolTimeout);
       return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace, lookup.tool, baseCtx);
     } catch (e) {
@@ -31949,7 +32589,7 @@ var AgentLoop = class _AgentLoop {
       arguments: tc.arguments,
       reason,
       step,
-      trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id }
+      trace: { ...runTrace, callId: tc.id }
     };
     const pending = {
       callId: tc.id,
@@ -31982,7 +32622,7 @@ var AgentLoop = class _AgentLoop {
         return this.buildOverriddenResult(tc, decision.overrideResult, reports);
       }
       try {
-        const baseCtx = { step, callId: tc.id, metrics, trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id } };
+        const baseCtx = { step, callId: tc.id, metrics, trace: { ...runTrace, callId: tc.id } };
         const result = await executeWithTimeout(tool, tc, baseCtx, this._toolTimeout);
         return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace, tool, baseCtx);
       } catch (e) {
@@ -32019,31 +32659,71 @@ var AgentLoop = class _AgentLoop {
       metrics,
       trace: runTrace
     });
+    const inner = unwrapLazyCall(tc.name, tc.arguments);
     reports.push({
       callId: tc.id,
-      toolName: tc.name,
+      toolName: inner ?? tc.name,
       arguments: tc.arguments,
       resultSizeBytes: resultStr.length,
       latencyMs,
       skipped: false,
       error: null,
       metrics: Object.fromEntries(metrics),
+      ...inner ? { discoveredVia: "search" } : {},
       ...customData !== void 0 ? { customData } : {}
     });
     return { type: "tool_result", id: tc.id, content: resultStr };
   }
-  /** 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. */
+  installLazyTools() {
+    if (this._lazyInstalled) return;
+    this._lazyInstalled = true;
+    for (const t of createLazyTools({
+      lazyTools: () => [...this._tools.values()].filter((t2) => t2.lazy),
+      eagerNames: () => [...this._tools.entries()].filter(([, t2]) => !t2.lazy).map(([key]) => key),
+      state: this._lazyState,
+      config: this._lazyConfig,
+      onSearch: (info) => {
+        void this.hooks.emit("onToolSearch", { agentId: this.id, ...info });
+      }
+    })) {
+      this.registerTool(t);
+    }
+    this.syncLazyProtocol();
+  }
+  /** 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. */
+  syncLazyProtocol() {
+    if (!this._history) return;
+    writeLazyToolsProtocol(this._history.registry, this._lazyInstalled, "agent-loop");
+  }
+  /** 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. */
   toolDefinitions(options) {
-    const own = [...this._tools.values()].map((t) => t.definition);
+    const own = [...this._tools.values()].filter((t) => !t.lazy).map((t) => t.definition);
     if (options.tools) return [...own, ...options.tools];
     return own.length > 0 ? own : void 0;
   }
   // ─── Run helpers ────────────────────────────────────────────────────────
-  async beginRun(input) {
+  async beginRun(input, callerCtx) {
     if (this._running) throw new Error("AgentLoop is already running");
     this._running = true;
     this._stopRequested = false;
     this._abortController = new AbortController();
+    this._lazyState.searches = 0;
     if (this._systemThunk) {
       const next = await this._systemThunk();
       if (next !== this._system) {
@@ -32055,10 +32735,23 @@ var AgentLoop = class _AgentLoop {
     const startedAt = Date.now();
     const startPerf = performance.now();
     const userMessageText = typeof input === "string" ? input : Array.isArray(input) && input.length > 0 && "role" in input[0] ? contentText(input[input.length - 1].content) : contentText(input);
-    const runTrace = { sessionId: this.id, requestId: runId };
+    const runTrace = {
+      sessionId: callerCtx?.sessionId ?? this.id,
+      requestId: callerCtx?.requestId ?? runId,
+      // The caller's span travels WITH the ids, for the same reason they do: `agent.run`,
+      // every `tool.call`, and any agent nested inside a tool reach the telemetry through
+      // `runTrace` and nothing else. While this field was missing from it only the LLM
+      // calls joined the app's trace — they are built from the caller's ctx directly —
+      // and the run that made them sat in a second, unrelated one. Measured against a
+      // live backend; the unit tests fed the hooks directly and never saw it.
+      ...callerCtx?.traceparent ? { traceparent: callerCtx.traceparent } : {}
+    };
     await this.hooks.emit("onRunStart", {
       runId,
       agentId: this.id,
+      label: this.label,
+      source: this.source,
+      attributes: this.attributes,
       userMessage: input,
       model: this.client.model,
       system: this._history.system,
@@ -32113,7 +32806,7 @@ var AgentLoop = class _AgentLoop {
       if (g.kind !== "input") continue;
       const decision = await g.check({
         kind: "input",
-        trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId },
+        trace: { ...runTrace },
         step,
         messages,
         system
@@ -32141,7 +32834,7 @@ var AgentLoop = class _AgentLoop {
       if (g.kind !== "output") continue;
       const decision = await g.check({
         kind: "output",
-        trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId },
+        trace: { ...runTrace },
         step,
         response
       });
@@ -33017,9 +33710,16 @@ function summarize(entries) {
     reasoning: 0,
     total: 0,
     tokens: { input: 0, output: 0, cached: 0, cacheWrite: 0, reasoning: 0 },
-    entries: entries.length
+    entries: entries.length,
+    unpriced: 0,
+    unpricedModels: []
   };
   for (const e of entries) {
+    if (e.cost.source === "unknown") {
+      s.unpriced++;
+      const key = `${e.provider}/${e.model}`;
+      if (!s.unpricedModels.includes(key)) s.unpricedModels.push(key);
+    }
     s.input += e.cost.input;
     s.output += e.cost.output;
     s.cacheRead += e.cost.cacheRead;
@@ -33045,6 +33745,8 @@ var CostCollector = class {
   budgets = [];
   triggeredThresholds = /* @__PURE__ */ new Map();
   _runningTotal = 0;
+  /** Models already reported as unpriced, so the warning fires once rather than per call. */
+  warnedUnpriced = /* @__PURE__ */ new Set();
   watchedAgents = /* @__PURE__ */ new Set();
   unsub = null;
   unsubMedia = null;
@@ -33177,6 +33879,7 @@ var CostCollector = class {
     };
     this.ledger.push(entry);
     this._runningTotal += cost.total;
+    this.noteIfUnpriced(entry);
     this.hooks.emitSync("onCostEntry", { entry, runningTotal: this._runningTotal });
     this.checkBudgets(entry);
   }
@@ -33222,9 +33925,31 @@ var CostCollector = class {
     };
     this.ledger.push(entry);
     this._runningTotal += cost.total;
+    this.noteIfUnpriced(entry);
     this.hooks.emitSync("onCostEntry", { entry, runningTotal: this._runningTotal });
     this.checkBudgets(entry);
   }
+  /** A total of exactly 0 because the model is not in the catalog reads identically to a
+   *  total of 0 because the call was free — and it silently under-counts every budget
+   *  and report built on it. `source: 'unknown'` already records the difference per
+   *  entry, but nothing aggregated it, so a whole benchmark run once reported $0.00000
+   *  for a live provider and looked like a free arm.
+   *
+   *  Fires once per provider/model: an unpriced model is a configuration fact, not a
+   *  per-request event, and repeating it on every call would train the reader to ignore
+   *  it. Free calls are priced 'calculated' with an explicit note, so they stay silent. */
+  noteIfUnpriced(entry) {
+    if (entry.cost.source !== "unknown") return;
+    const key = `${entry.provider}/${entry.model}`;
+    if (this.warnedUnpriced.has(key)) return;
+    this.warnedUnpriced.add(key);
+    this.hooks.emitSync("onWarning", {
+      source: "cost",
+      code: "unpriced_model",
+      message: `No catalog pricing for ${key} \u2014 its cost is reported as 0, which is not the same as free. Check the model id against the catalog, or add pricing for it.`,
+      details: { provider: entry.provider, model: entry.model }
+    });
+  }
   checkBudgets(entry) {
     for (const budget of this.budgets) {
       if (!matchesScope(entry, budget.scope)) continue;
@@ -34269,11 +34994,12 @@ function createEngine(config = {}) {
   const persistence = resolvePersistence(config.persistence);
   const cache2 = resolveCache(config.cache);
   const catalog = resolveCatalog(config.catalog);
-  const network = new NetworkEngine({ hooks, fetch: config.fetch });
+  const network = new NetworkEngine({ hooks, fetch: config.fetch, retry: config.retry, queues: config.queues });
   const fetchBound = (req, options) => network.fetch(req, options);
   const fetchStreamBound = (req, options) => network.fetchStream(req, options);
   const connectBound = (req) => network.connect(req);
   const cost = new CostCollector({ hooks, catalog });
+  const telemetry = config.telemetry ? new TelemetryAdapter(hooks, config.telemetry) : null;
   const handle = {
     sessionId,
     hooks,
@@ -34286,9 +35012,11 @@ function createEngine(config = {}) {
     connect: connectBound,
     catalog,
     cost,
+    telemetry,
     apiKeys: config.apiKeys ?? {},
     destroy() {
       cost.destroy();
+      telemetry?.destroy();
       network.destroy();
     }
   };
@@ -37562,6 +38290,7 @@ function defineTool(input) {
     if (!optional.has(key)) required.push(key);
   }
   return {
+    ...input.lazy ? { lazy: true } : {},
     definition: {
       name: input.name,
       description: input.description,
@@ -38050,7 +38779,14 @@ async function complete(opts) {
         temperature: opts.temperature
       });
       res = await loop.complete(input, {
-        structured: opts.structured
+        structured: opts.structured,
+        providerOptions: opts.providerOptions,
+        audio: opts.audio,
+        outputModalities: opts.outputModalities,
+        serviceTier,
+        cache: opts.cache,
+        topK: opts.topK,
+        seed: opts.seed
       });
     } else {
       res = await llm.complete(input, {
@@ -38061,12 +38797,16 @@ async function complete(opts) {
         providerOptions: opts.providerOptions,
         audio: opts.audio,
         outputModalities: opts.outputModalities,
-        serviceTier
+        serviceTier,
+        cache: opts.cache,
+        topK: opts.topK,
+        seed: opts.seed
       });
     }
     const result = {
       text: res.text,
       response: res,
+      ...res.error ? { error: res.error } : {},
       // Bound to this call's client (same provider/model/key/engine).
       retrieveFile: (file) => llm.retrieveFile(file),
       streamFile: (file) => llm.streamFile(file)
@@ -38412,10 +39152,21 @@ var McpResultCache = class {
     }
     return hit.value;
   }
-  /** Store only when the server actually asked for it. Returns whether anything was stored. */
+  /** Store only when the server actually asked for it. Returns whether anything was stored.
+   *
+   *  A non-positive `ttlMs` is an instruction, not a missing value: the server is saying *do not
+   *  reuse this*. Any entry already held under that key is dropped, so the next `get` re-fetches.
+   *  Without the eviction the hint is inert — a server that first said "cache for 60s" and then
+   *  says "stale now" would keep being answered from the stale entry for the rest of the original
+   *  TTL. Absent hints are different and must stay different: they carry no instruction, so an
+   *  existing entry is left alone and pre-2026 servers behave exactly as before. */
   set(key, value, hints, now = Date.now()) {
     const ttl = hints?.ttlMs;
-    if (typeof ttl !== "number" || !Number.isFinite(ttl) || ttl <= 0) return false;
+    if (typeof ttl === "number" && Number.isFinite(ttl) && ttl <= 0) {
+      this.entries.delete(key);
+      return false;
+    }
+    if (typeof ttl !== "number" || !Number.isFinite(ttl)) return false;
     this.entries.set(key, {
       value,
       expiresAt: now + ttl,
@@ -39573,11 +40324,23 @@ function mcpPromptToMessages(result) {
 }
 function mcpToolToAgentTool(client, tool, namespace, opts = {}) {
   return {
+    ...opts.lazy ? { lazy: true } : {},
     definition: {
       type: "function",
       name: `${namespace}__${tool.name}`,
       description: tool.description ?? tool.title ?? tool.name,
-      parameters: tool.inputSchema ?? { type: "object", properties: {} }
+      parameters: tool.inputSchema ?? { type: "object", properties: {} },
+      // MCP publishes a schema for the tool's structured output and OpenAI
+      // Responses accepts one (`output_schema`), so the model can reason over the
+      // shape it will get back.
+      //
+      // Gated on `validateOutput` because declaring it is a PROMISE, not a hint:
+      // the provider then requires the result to be JSON matching the schema, so
+      // the tool result changes from prose to structured data. Forwarding it
+      // unconditionally would silently reshape every existing MCP tool result —
+      // and did, until a live round trip through OpenAI Responses failed. Anyone
+      // asking for output validation has already opted into that contract.
+      ...opts.validateOutput && tool.outputSchema ? { outputSchema: tool.outputSchema } : {}
     },
     execute: async (args, ctx) => {
       const res = await client.callTool(tool.name, args, ctx.trace);
@@ -39585,6 +40348,9 @@ function mcpToolToAgentTool(client, tool, namespace, opts = {}) {
         const errors = validateJsonSchema(tool.outputSchema, res.structuredContent);
         if (errors.length > 0) return `Tool output failed schema validation: ${errors.slice(0, 5).join("; ")}`;
       }
+      if (opts.validateOutput && tool.outputSchema && res.structuredContent !== void 0 && !res.isError) {
+        return JSON.stringify(res.structuredContent);
+      }
       return mcpContentToResult(res);
     }
   };
@@ -40321,7 +41087,9 @@ async function connectMcp(config, opts = {}) {
   const refresh = async (c) => {
     const defs = await c.listTools();
     tools.length = 0;
-    for (const d of defs) tools.push(mcpToolToAgentTool(c, d, ns, { validateOutput: opts.validateOutput }));
+    for (const d of defs) {
+      tools.push(mcpToolToAgentTool(c, d, ns, { validateOutput: opts.validateOutput, lazy: opts.lazy }));
+    }
   };
   const sampler = opts.sampling ? samplingHandler(opts.sampling) : null;
   const capabilities = {};
@@ -42853,6 +43621,8 @@ export {
   LAYER_EXECUTOR_TOOL_EXAMPLES,
   LAYER_LEGACY_SYSTEM,
   LAYER_MEMORY,
+  LAZY_CALL_TOOL,
+  LAZY_SEARCH_TOOL,
   LLMClient,
   LLMError,
   LLM_DEF_KEY,
@@ -42980,6 +43750,7 @@ export {
   defineLLMTool,
   defineTool,
   delegate,
+  describeTool,
   discoverMetadata,
   dispatch,
   embed,
@@ -43041,6 +43812,7 @@ export {
   parseSSEStream,
   parseToolId,
   pcmToWav,
+  rankTools,
   readFactsLayer,
   reflectionGuidance,
   refreshTokens,
@@ -43058,7 +43830,9 @@ export {
   selectVariant,
   shellGlob,
   sniffImageMime,
+  strictSupport,
   submitBatch,
+  toolKey,
   transcribe,
   trimReplacer,
   tryParseToolId,