@vauban-org/agent-sdk 1.2.0 → 1.4.0

package/src/skills/web-search.ts

@@ -6,9 +6,31 @@
  * @public
  */
 import { z } from "zod";
+
+import {
+  retry,
+  RETRY_TRANSIENT,
+  RetryExhaustedError,
+  type RetryConfig,
+} from "../retry/index.js";
 import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+
 import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
 import { withSkillSpan } from "./_otel.js";
+import { readSecret } from "./_secrets.js";
+
+class RetryableHttpError extends Error {
+  constructor(public readonly status: number, public readonly body: string) {
+    super(`HTTP ${status}: ${body.slice(0, 200)}`);
+    this.name = "RetryableHttpError";
+  }
+}
+
+const SEARCH_RETRY: RetryConfig = {
+  ...RETRY_TRANSIENT,
+  retryIf: (err) =>
+    err instanceof RetryableHttpError || err instanceof TypeError,
+};
 
 const inputSchema = z
   .object({
@@ -38,71 +60,131 @@ export const webSearch: Skill<WebSearchInput, WebSearchOutput> = {
       return { results: [], provider: "replay" };
     }
     return withSkillSpan("web_search", async () => {
-      const braveKey = process.env.BRAVE_SEARCH_KEY;
-      const tavilyKey = process.env.TAVILY_API_KEY;
+      const braveKey = readSecret(ctx, "BRAVE_SEARCH_KEY");
+      const tavilyKey = readSecret(ctx, "TAVILY_API_KEY");
       if (!braveKey && !tavilyKey) {
         throw new SkillNotConfiguredError("web_search", [
           "BRAVE_SEARCH_KEY",
           "TAVILY_API_KEY",
         ]);
       }
+
+      // Try Brave first when configured. Retry on 5xx/429. Fall back to
+      // Tavily on any final non-OK (4xx other than 429 short-circuits).
       if (braveKey) {
-        const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(input.query)}&count=${input.limit}`;
-        const res = await fetch(url, {
-          headers: {
-            Accept: "application/json",
-            "X-Subscription-Token": braveKey,
-          },
-        });
-        if (res.ok) {
-          const data = (await res.json()) as {
-            web?: {
+        try {
+          return await retry(
+            async () => {
+              const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(
+                input.query
+              )}&count=${input.limit}`;
+              const res = await fetch(url, {
+                headers: {
+                  Accept: "application/json",
+                  "X-Subscription-Token": braveKey,
+                },
+              });
+              if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                if (res.status >= 500 || res.status === 429) {
+                  throw new RetryableHttpError(res.status, body);
+                }
+                throw new SkillExecutionError(
+                  "web_search",
+                  `brave ${res.status}`,
+                  { status: res.status }
+                );
+              }
+              const data = (await res.json()) as {
+                web?: {
+                  results?: Array<{
+                    title?: string;
+                    url?: string;
+                    description?: string;
+                  }>;
+                };
+              };
+              const results: WebSearchResult[] = (data.web?.results ?? []).map(
+                (r) => ({
+                  title: r.title ?? "",
+                  url: r.url ?? "",
+                  snippet: r.description ?? "",
+                })
+              );
+              return { results, provider: "brave" as const };
+            },
+            { config: SEARCH_RETRY }
+          );
+        } catch (err) {
+          if (!tavilyKey) {
+            const cause =
+              err instanceof RetryExhaustedError ? err.lastError : err;
+            if (cause instanceof RetryableHttpError) {
+              throw new SkillExecutionError(
+                "web_search",
+                `brave ${cause.status} after retries`,
+                { status: cause.status }
+              );
+            }
+            throw cause;
+          }
+          // Brave failed — fall through to Tavily.
+        }
+      }
+
+      // Tavily (primary if no Brave key, else fallback)
+      try {
+        return await retry(
+          async () => {
+            const res = await fetch("https://api.tavily.com/search", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                api_key: tavilyKey,
+                query: input.query,
+                max_results: input.limit,
+              }),
+            });
+            if (!res.ok) {
+              const body = await res.text().catch(() => "");
+              if (res.status >= 500 || res.status === 429) {
+                throw new RetryableHttpError(res.status, body);
+              }
+              throw new SkillExecutionError(
+                "web_search",
+                `tavily ${res.status}`,
+                { status: res.status }
+              );
+            }
+            const data = (await res.json()) as {
               results?: Array<{
                 title?: string;
                 url?: string;
-                description?: string;
+                content?: string;
               }>;
             };
-          };
-          const results: WebSearchResult[] = (data.web?.results ?? []).map(
-            (r) => ({
-              title: r.title ?? "",
-              url: r.url ?? "",
-              snippet: r.description ?? "",
-            }),
+            const results: WebSearchResult[] = (data.results ?? []).map(
+              (r) => ({
+                title: r.title ?? "",
+                url: r.url ?? "",
+                snippet: r.content ?? "",
+              })
+            );
+            return { results, provider: "tavily" as const };
+          },
+          { config: SEARCH_RETRY }
+        );
+      } catch (err) {
+        const cause = err instanceof RetryExhaustedError ? err.lastError : err;
+        if (cause instanceof RetryableHttpError) {
+          throw new SkillExecutionError(
+            "web_search",
+            `tavily ${cause.status} after retries`,
+            { status: cause.status }
           );
-          return { results, provider: "brave" };
-        }
-        if (!tavilyKey) {
-          throw new SkillExecutionError("web_search", `brave ${res.status}`, {
-            status: res.status,
-          });
         }
+        throw cause;
       }
-      // Tavily fallback
-      const res = await fetch("https://api.tavily.com/search", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          api_key: tavilyKey,
-          query: input.query,
-          max_results: input.limit,
-        }),
-      });
-      if (!res.ok) {
-        throw new SkillExecutionError("web_search", `tavily ${res.status}`, {
-          status: res.status,
-        });
-      }
-      const data = (await res.json()) as {
-        results?: Array<{ title?: string; url?: string; content?: string }>;
-      };
-      const results: WebSearchResult[] = (data.results ?? []).map((r) => ({
-        title: r.title ?? "",
-        url: r.url ?? "",
-        snippet: r.content ?? "",
-      }));
-      return { results, provider: "tavily" };
     });
   },
 };

package/src/telemetry/bus.test.ts

@@ -0,0 +1,231 @@
+/**
+ * TelemetryBus — fanout, isolation, backpressure tests.
+ *
+ * Ref: command-center:sprint-693:telemetry-bus
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+import { createTelemetryBus } from "./bus.js";
+import type { TelemetrySink } from "./port.js";
+
+function makeSink(
+  name: string,
+  behavior: "ok" | "throw" = "ok"
+): TelemetrySink {
+  const calls = { start: 0, step: 0, finish: 0 };
+  return {
+    name,
+    async start() {
+      calls.start += 1;
+      if (behavior === "throw") throw new Error(`${name}.start failed`);
+    },
+    async step() {
+      calls.step += 1;
+      if (behavior === "throw") throw new Error(`${name}.step failed`);
+    },
+    async finish() {
+      calls.finish += 1;
+      if (behavior === "throw") throw new Error(`${name}.finish failed`);
+    },
+    // expose counters via name munging — vitest reads `(sink as any).calls`
+    // @ts-expect-error — test affordance
+    calls,
+  };
+}
+
+const RUN_START = {
+  runId: "11111111-1111-1111-1111-111111111111",
+  agentId: "agent-x",
+  agentVersion: "1.0.0",
+  model: "test",
+  provider: "test",
+  startedAt: "2026-05-16T17:00:00.000Z",
+};
+
+const STEP_DELTA = {
+  stepIndex: 0,
+  kind: "observe",
+  status: "completed" as const,
+  inputTokens: 10,
+  outputTokens: 20,
+  costUsd: 0.001,
+};
+
+const FINISH = {
+  status: "success" as const,
+  finishedAt: "2026-05-16T17:00:05.000Z",
+};
+
+describe("createTelemetryBus", () => {
+  it("returns a NOOP sink when sinks=[]", async () => {
+    const bus = createTelemetryBus({ sinks: [] });
+    expect(bus.name).toBe("noop");
+    await expect(bus.start(RUN_START)).resolves.toBeUndefined();
+    expect(bus.counters.dispatched).toBe(0);
+  });
+
+  it("fans out start/step/finish to every sink (blocking mode)", async () => {
+    const a = makeSink("a");
+    const b = makeSink("b");
+    const bus = createTelemetryBus({
+      sinks: [a, b],
+      nonBlocking: false,
+    });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, STEP_DELTA);
+    await bus.finish(RUN_START.runId, FINISH);
+
+    // @ts-expect-error — test affordance
+    expect(a.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    // @ts-expect-error — test affordance
+    expect(b.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    expect(bus.counters.dispatched).toBe(6); // 3 events × 2 sinks
+    expect(bus.counters.sinkErrors).toBe(0);
+  });
+
+  it("isolates failures — one sink throwing does not affect others", async () => {
+    const good = makeSink("good");
+    const bad = makeSink("bad", "throw");
+    const warn = vi.fn();
+    const bus = createTelemetryBus({
+      sinks: [good, bad],
+      logger: { warn, error: () => {} },
+      nonBlocking: false,
+    });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, STEP_DELTA);
+    await bus.finish(RUN_START.runId, FINISH);
+
+    // @ts-expect-error
+    expect(good.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    // @ts-expect-error
+    expect(bad.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    expect(bus.counters.sinkErrors).toBe(3);
+    expect(warn).toHaveBeenCalledTimes(3);
+    expect(warn.mock.calls[0]![1]).toMatch(/isolated/);
+  });
+
+  it("backpressure: drops oldest events when queue exceeds maxQueueDepth", async () => {
+    // Pending-resolver sink — caller controls when each call resolves.
+    const pending: Array<() => void> = [];
+    const blockingSink: TelemetrySink = {
+      name: "slow",
+      async start() {
+        await new Promise<void>((res) => {
+          pending.push(res);
+        });
+      },
+      async step() {},
+      async finish() {},
+    };
+    const warn = vi.fn();
+    const bus = createTelemetryBus({
+      sinks: [blockingSink],
+      logger: { warn, error: () => {} },
+      nonBlocking: true,
+      maxQueueDepth: 3,
+    });
+
+    // Enqueue 6 starts — 1 enters dispatch and blocks; the next 3 fill the
+    // queue; the 5th and 6th cause overflow (drop oldest).
+    for (let i = 0; i < 6; i++) {
+      await bus.start({ ...RUN_START, runId: `run-${i}` });
+    }
+    expect(bus.counters.dropped).toBeGreaterThanOrEqual(1);
+
+    // Release all pending dispatches so flush() resolves.
+    while (pending.length > 0 || bus.counters.dispatched < 4) {
+      const r = pending.shift();
+      r?.();
+      await new Promise((res) => setTimeout(res, 0));
+    }
+    await bus.flush();
+  }, 10_000);
+
+  it("non-blocking mode returns immediately", async () => {
+    let resolveSink: (() => void) | undefined;
+    const sink: TelemetrySink = {
+      name: "slow",
+      async start() {
+        await new Promise<void>((res) => {
+          resolveSink = res;
+        });
+      },
+      async step() {},
+      async finish() {},
+    };
+    const bus = createTelemetryBus({ sinks: [sink], nonBlocking: true });
+
+    const t0 = Date.now();
+    await bus.start(RUN_START); // should return immediately
+    const elapsed = Date.now() - t0;
+    expect(elapsed).toBeLessThan(50);
+    expect(bus.counters.dispatched).toBe(0); // not dispatched yet
+
+    resolveSink?.();
+    await bus.flush();
+  });
+
+  it("flush awaits in-flight dispatches", async () => {
+    const sink = makeSink("a");
+    const bus = createTelemetryBus({ sinks: [sink], nonBlocking: true });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, STEP_DELTA);
+    await bus.finish(RUN_START.runId, FINISH);
+    await bus.flush();
+
+    // @ts-expect-error
+    expect(sink.calls).toEqual({ start: 1, step: 1, finish: 1 });
+    expect(bus.counters.dispatched).toBe(3);
+  });
+
+  it("preserves FIFO order per sink", async () => {
+    const events: string[] = [];
+    const sink: TelemetrySink = {
+      name: "ordered",
+      async start(e) {
+        events.push(`start:${e.runId}`);
+      },
+      async step(runId, d) {
+        events.push(`step:${runId}:${d.stepIndex}`);
+      },
+      async finish(runId) {
+        events.push(`finish:${runId}`);
+      },
+    };
+    const bus = createTelemetryBus({ sinks: [sink], nonBlocking: true });
+
+    await bus.start(RUN_START);
+    await bus.step(RUN_START.runId, { ...STEP_DELTA, stepIndex: 0 });
+    await bus.step(RUN_START.runId, { ...STEP_DELTA, stepIndex: 1 });
+    await bus.finish(RUN_START.runId, FINISH);
+    await bus.flush();
+
+    expect(events).toEqual([
+      `start:${RUN_START.runId}`,
+      `step:${RUN_START.runId}:0`,
+      `step:${RUN_START.runId}:1`,
+      `finish:${RUN_START.runId}`,
+    ]);
+  });
+
+  it("counts dispatched accurately under mixed success/failure", async () => {
+    const good = makeSink("good");
+    const bad = makeSink("bad", "throw");
+    const bus = createTelemetryBus({
+      sinks: [good, bad],
+      nonBlocking: false,
+      logger: { warn: () => {}, error: () => {} },
+    });
+
+    await bus.start(RUN_START);
+    await bus.finish(RUN_START.runId, FINISH);
+
+    expect(bus.counters.dispatched).toBe(2); // good's 2 events
+    expect(bus.counters.sinkErrors).toBe(2); // bad's 2 events
+  });
+});

package/src/telemetry/bus.ts

@@ -0,0 +1,241 @@
+/**
+ * TelemetryBus — fanout to multiple {@link TelemetrySink}s, non-blocking.
+ *
+ * Invariants :
+ *   1. Sink failures are ISOLATED — one sink throwing never affects the others
+ *      nor the host agent loop. Failures are logged via the bus logger.
+ *   2. The bus itself implements {@link TelemetrySink}, so it can be passed
+ *      transparently to consumers expecting a single sink (composition).
+ *   3. When `nonBlocking: true` (default), `start`/`step`/`finish` return
+ *      immediately and dispatch in background. Errors surface via the logger.
+ *   4. Backpressure : if internal queue > `maxQueueDepth`, oldest events are
+ *      dropped and counted.
+ *
+ * Ref: command-center:sprint-693:telemetry-bus
+ */
+
+import {
+  NOOP_TELEMETRY_SINK,
+  type TelemetryRunFinish,
+  type TelemetryRunStart,
+  type TelemetryRunStep,
+  type TelemetrySink,
+} from "./port.js";
+
+// ─── Minimal logger interface (avoid SDK dep) ────────────────────────────────
+
+export interface TelemetryLogger {
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+}
+
+const NOOP_LOGGER: TelemetryLogger = {
+  warn: () => {
+    /* no-op */
+  },
+  error: () => {
+    /* no-op */
+  },
+};
+
+// ─── Bus options ─────────────────────────────────────────────────────────────
+
+export interface TelemetryBusOptions {
+  sinks: readonly TelemetrySink[];
+  /** Pino-compatible logger. Defaults to no-op. */
+  logger?: TelemetryLogger;
+  /**
+   * When true (default), `start/step/finish` resolve immediately and dispatch
+   * in background. Set false in tests for deterministic assertions.
+   */
+  nonBlocking?: boolean;
+  /**
+   * Max number of in-flight events per sink before dropping oldest.
+   * Defaults to 1000.
+   */
+  maxQueueDepth?: number;
+}
+
+// ─── Telemetry counters (exposed for Prometheus or tests) ────────────────────
+
+export interface TelemetryCounters {
+  /** Events dropped due to queue overflow. */
+  readonly dropped: number;
+  /** Sink errors caught and isolated. */
+  readonly sinkErrors: number;
+  /** Events successfully dispatched. */
+  readonly dispatched: number;
+}
+
+// ─── Implementation ──────────────────────────────────────────────────────────
+
+interface PendingEvent {
+  kind: "start" | "step" | "finish";
+  exec: (sink: TelemetrySink) => Promise<unknown>;
+}
+
+class TelemetryBusImpl implements TelemetrySink {
+  readonly name = "telemetry-bus";
+
+  private readonly _sinks: readonly TelemetrySink[];
+  private readonly _logger: TelemetryLogger;
+  private readonly _nonBlocking: boolean;
+  private readonly _maxQueueDepth: number;
+  /** Per-sink queue of pending events (FIFO). */
+  private readonly _queues: PendingEvent[][];
+  /** Per-sink drain promise (single-flight). */
+  private readonly _draining: Array<Promise<void> | null>;
+
+  private _dropped = 0;
+  private _sinkErrors = 0;
+  private _dispatched = 0;
+
+  constructor(opts: TelemetryBusOptions) {
+    this._sinks = opts.sinks;
+    this._logger = opts.logger ?? NOOP_LOGGER;
+    this._nonBlocking = opts.nonBlocking ?? true;
+    this._maxQueueDepth = opts.maxQueueDepth ?? 1000;
+    this._queues = this._sinks.map(() => []);
+    this._draining = this._sinks.map(() => null);
+  }
+
+  get counters(): TelemetryCounters {
+    return {
+      dropped: this._dropped,
+      sinkErrors: this._sinkErrors,
+      dispatched: this._dispatched,
+    };
+  }
+
+  async start(event: TelemetryRunStart): Promise<void> {
+    return this._fanout({
+      kind: "start",
+      exec: (s) => s.start(event),
+    });
+  }
+
+  async step(runId: string, delta: TelemetryRunStep): Promise<void> {
+    return this._fanout({
+      kind: "step",
+      exec: (s) => s.step(runId, delta),
+    });
+  }
+
+  async finish(runId: string, event: TelemetryRunFinish): Promise<void> {
+    return this._fanout({
+      kind: "finish",
+      exec: (s) => s.finish(runId, event),
+    });
+  }
+
+  async flush(): Promise<void> {
+    await Promise.all([
+      ...this._draining.map((p) => p ?? Promise.resolve()),
+      ...this._sinks.map((s) =>
+        s.flush?.().catch((err) => {
+          this._sinkErrors += 1;
+          this._logger.warn(
+            { sink: s.name, err: errorMessage(err) },
+            "telemetry-bus: flush failed"
+          );
+        })
+      ),
+    ]);
+  }
+
+  // ── internal ───────────────────────────────────────────────────────────────
+
+  private async _fanout(evt: PendingEvent): Promise<void> {
+    if (this._nonBlocking) {
+      // Enqueue on each sink, kick drain in background.
+      this._sinks.forEach((_, i) => this._enqueue(i, evt));
+      return;
+    }
+    // Blocking mode (tests) — dispatch sequentially and surface errors via log.
+    await Promise.all(this._sinks.map((sink) => this._dispatchOne(sink, evt)));
+  }
+
+  private _enqueue(sinkIdx: number, evt: PendingEvent): void {
+    const queue = this._queues[sinkIdx]!;
+    if (queue.length >= this._maxQueueDepth) {
+      queue.shift(); // drop oldest
+      this._dropped += 1;
+      const sink = this._sinks[sinkIdx]!;
+      this._logger.warn(
+        { sink: sink.name, depth: queue.length, dropped: this._dropped },
+        "telemetry-bus: queue overflow, oldest dropped"
+      );
+    }
+    queue.push(evt);
+    void this._drain(sinkIdx);
+  }
+
+  private async _drain(sinkIdx: number): Promise<void> {
+    if (this._draining[sinkIdx]) return;
+    const sink = this._sinks[sinkIdx]!;
+    const queue = this._queues[sinkIdx]!;
+
+    const promise = (async () => {
+      while (queue.length > 0) {
+        const evt = queue.shift()!;
+        await this._dispatchOne(sink, evt);
+      }
+    })();
+    this._draining[sinkIdx] = promise;
+    try {
+      await promise;
+    } finally {
+      this._draining[sinkIdx] = null;
+    }
+  }
+
+  private async _dispatchOne(
+    sink: TelemetrySink,
+    evt: PendingEvent
+  ): Promise<void> {
+    try {
+      await evt.exec(sink);
+      this._dispatched += 1;
+    } catch (err) {
+      this._sinkErrors += 1;
+      this._logger.warn(
+        {
+          sink: sink.name,
+          kind: evt.kind,
+          err: errorMessage(err),
+        },
+        "telemetry-bus: sink dispatch failed (isolated)"
+      );
+    }
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Build a TelemetryBus that fans events to all sinks non-blockingly.
+ *
+ * If `sinks` is empty, returns {@link NOOP_TELEMETRY_SINK} so callers never
+ * need to null-check.
+ */
+export function createTelemetryBus(
+  opts: TelemetryBusOptions
+): TelemetrySink & { counters: TelemetryCounters; flush(): Promise<void> } {
+  if (opts.sinks.length === 0) {
+    // Wrap NOOP with stub counters + flush for type consistency.
+    return {
+      ...NOOP_TELEMETRY_SINK,
+      counters: { dropped: 0, sinkErrors: 0, dispatched: 0 },
+      async flush() {
+        /* no-op */
+      },
+    };
+  }
+  return new TelemetryBusImpl(opts);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}