@halo-sdk/otel 1.0.0

package/README.md

@@ -0,0 +1,20 @@
+# @halo-sdk/otel
+
+Observability & resilience decorators for Halo SDK adapters. Both are composable `ModelAdapter` wrappers — stack them with `@halo-sdk/gateway` in any order.
+
+```ts
+import { withRetry, withTelemetry } from "@halo-sdk/otel";
+
+const adapter = withTelemetry(withRetry(base, { maxRetries: 3 }), {
+  system: "anthropic",
+  onSpan: (span) => exporter.record(span), // bridge to your OTel exporter
+});
+```
+
+## `withTelemetry(adapter, { onSpan, system? })`
+
+Times each `chat`/`stream` call and hands `onSpan` a `GenAISpan` shaped after the OpenTelemetry GenAI semantic conventions (`gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens` / `output_tokens`, plus `halo.cache.*` attributes). Dependency-free — it does not import `@opentelemetry/*`; you bridge spans to whatever exporter you use.
+
+## `withRetry(adapter, { maxRetries?, baseDelayMs?, isRetryable? })`
+
+Exponential-backoff retries on transient errors. Retries `chat`, and `stream` failures that happen **before the first chunk** (retrying mid-stream would duplicate emitted output). Pass `baseDelayMs: 0` and a custom `sleep` for deterministic tests.

package/dist/index.cjs

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  withRetry: () => withRetry,
+  withTelemetry: () => withTelemetry
+});
+module.exports = __toCommonJS(index_exports);
+function spanAttributes(adapter, system, operation, usage) {
+  const attrs = {
+    "gen_ai.system": system,
+    "gen_ai.operation.name": operation,
+    "gen_ai.request.model": adapter.modelId
+  };
+  if (usage) {
+    attrs["gen_ai.usage.input_tokens"] = usage.promptTokens;
+    attrs["gen_ai.usage.output_tokens"] = usage.completionTokens;
+    if (usage.caching) {
+      attrs["halo.cache.hit_tokens"] = usage.caching.hitTokens;
+      attrs["halo.cache.miss_tokens"] = usage.caching.missTokens;
+      attrs["halo.cache.hit_rate"] = usage.caching.hitRate;
+    }
+  }
+  return attrs;
+}
+function withTelemetry(adapter, opts) {
+  const system = opts.system ?? adapter.modelId;
+  const now = opts.now ?? (() => Date.now());
+  return {
+    ...passthrough(adapter),
+    async chat(params) {
+      const start = now();
+      try {
+        const result = await adapter.chat(params);
+        opts.onSpan({
+          name: "chat",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "chat", result.usage),
+          durationMs: now() - start
+        });
+        return result;
+      } catch (err) {
+        opts.onSpan({
+          name: "chat",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "chat"),
+          durationMs: now() - start,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+    },
+    async *stream(params) {
+      const start = now();
+      let usage;
+      try {
+        for await (const chunk of adapter.stream(params)) {
+          if (chunk.type === "done") usage = chunk.usage;
+          yield chunk;
+        }
+        opts.onSpan({
+          name: "stream",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "stream", usage),
+          durationMs: now() - start
+        });
+      } catch (err) {
+        opts.onSpan({
+          name: "stream",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "stream", usage),
+          durationMs: now() - start,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+    }
+  };
+}
+var defaultSleep = (ms) => ms <= 0 ? Promise.resolve() : new Promise((r) => setTimeout(r, ms));
+function withRetry(adapter, opts) {
+  const maxRetries = opts?.maxRetries ?? 2;
+  const baseDelay = opts?.baseDelayMs ?? 200;
+  const isRetryable = opts?.isRetryable ?? (() => true);
+  const sleep = opts?.sleep ?? defaultSleep;
+  async function run(fn) {
+    let lastErr = new Error("retry failed");
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+        if (attempt === maxRetries || !isRetryable(lastErr)) throw lastErr;
+        await sleep(baseDelay * 2 ** attempt);
+      }
+    }
+    throw lastErr;
+  }
+  return {
+    ...passthrough(adapter),
+    chat(params) {
+      return run(() => adapter.chat(params));
+    },
+    async *stream(params) {
+      const gen = await run(async () => {
+        const g = adapter.stream(params);
+        const first = await g.next();
+        return { g, first };
+      });
+      if (!gen.first.done) yield gen.first.value;
+      yield* gen.g;
+    }
+  };
+}
+function passthrough(adapter) {
+  const base = {
+    modelId: adapter.modelId,
+    contextWindow: adapter.contextWindow,
+    capabilities: adapter.capabilities
+  };
+  if (adapter.pricing) base.pricing = adapter.pricing;
+  if (adapter.keepAlive) base.keepAlive = adapter.keepAlive.bind(adapter);
+  return base;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  withRetry,
+  withTelemetry
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n  ChatParams,\n  ModelAdapter,\n  ModelCapabilities,\n  PricingInfo,\n  TurnChunk,\n  Usage,\n} from \"@halo-sdk/core\";\n\n// ── Telemetry ──\n\n/** A finished span, shaped after the OpenTelemetry GenAI semantic conventions. */\nexport interface GenAISpan {\n  name: string;\n  /** OTel GenAI semconv attributes (`gen_ai.*`). */\n  attributes: Record<string, string | number | boolean>;\n  durationMs: number;\n  error?: string;\n}\n\nexport interface TelemetryOptions {\n  /** Provider/system label → `gen_ai.system` (e.g. \"anthropic\"). Default: modelId. */\n  system?: string;\n  /** Operation label → `gen_ai.operation.name`. Default per method. */\n  operation?: string;\n  /** Receives each finished span. Bridge to an OTel exporter or a logger. */\n  onSpan: (span: GenAISpan) => void;\n  /** Clock for durations (tests). Default `Date.now`. */\n  now?: () => number;\n}\n\nfunction spanAttributes(\n  adapter: ModelAdapter,\n  system: string,\n  operation: string,\n  usage?: Usage,\n): Record<string, string | number | boolean> {\n  const attrs: Record<string, string | number | boolean> = {\n    \"gen_ai.system\": system,\n    \"gen_ai.operation.name\": operation,\n    \"gen_ai.request.model\": adapter.modelId,\n  };\n  if (usage) {\n    attrs[\"gen_ai.usage.input_tokens\"] = usage.promptTokens;\n    attrs[\"gen_ai.usage.output_tokens\"] = usage.completionTokens;\n    if (usage.caching) {\n      attrs[\"halo.cache.hit_tokens\"] = usage.caching.hitTokens;\n      attrs[\"halo.cache.miss_tokens\"] = usage.caching.missTokens;\n      attrs[\"halo.cache.hit_rate\"] = usage.caching.hitRate;\n    }\n  }\n  return attrs;\n}\n\n/**\n * Wrap a {@link ModelAdapter} with OpenTelemetry GenAI-semconv telemetry.\n *\n * Each `chat`/`stream` call produces a {@link GenAISpan} (timed, with\n * `gen_ai.*` token attributes and Halo cache attributes) handed to `onSpan` —\n * bridge it to an OTel exporter or any sink. Dependency-free: it does not import\n * `@opentelemetry/*`, so it adds no weight unless you wire a real exporter.\n */\nexport function withTelemetry(adapter: ModelAdapter, opts: TelemetryOptions): ModelAdapter {\n  const system = opts.system ?? adapter.modelId;\n  const now = opts.now ?? (() => Date.now());\n\n  return {\n    ...passthrough(adapter),\n    async chat(params: ChatParams) {\n      const start = now();\n      try {\n        const result = await adapter.chat(params);\n        opts.onSpan({\n          name: \"chat\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"chat\", result.usage),\n          durationMs: now() - start,\n        });\n        return result;\n      } catch (err: unknown) {\n        opts.onSpan({\n          name: \"chat\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"chat\"),\n          durationMs: now() - start,\n          error: err instanceof Error ? err.message : String(err),\n        });\n        throw err instanceof Error ? err : new Error(String(err));\n      }\n    },\n    async *stream(params: ChatParams): AsyncGenerator<TurnChunk> {\n      const start = now();\n      let usage: Usage | undefined;\n      try {\n        for await (const chunk of adapter.stream(params)) {\n          if (chunk.type === \"done\") usage = chunk.usage;\n          yield chunk;\n        }\n        opts.onSpan({\n          name: \"stream\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"stream\", usage),\n          durationMs: now() - start,\n        });\n      } catch (err: unknown) {\n        opts.onSpan({\n          name: \"stream\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"stream\", usage),\n          durationMs: now() - start,\n          error: err instanceof Error ? err.message : String(err),\n        });\n        throw err instanceof Error ? err : new Error(String(err));\n      }\n    },\n  };\n}\n\n// ── Retry ──\n\nexport interface RetryOptions {\n  /** Max additional attempts after the first. Default 2. */\n  maxRetries?: number;\n  /** Base backoff in ms (doubles each attempt). Default 200. Set 0 in tests. */\n  baseDelayMs?: number;\n  /** Decide whether an error is worth retrying. Default: retry everything. */\n  isRetryable?: (error: Error) => boolean;\n  /** Sleep impl (tests). Default real setTimeout. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst defaultSleep = (ms: number): Promise<void> =>\n  ms <= 0 ? Promise.resolve() : new Promise((r) => setTimeout(r, ms));\n\n/**\n * Wrap a {@link ModelAdapter} with exponential-backoff retries on transient\n * errors. Retries `chat`, and `stream` failures that occur **before the first\n * chunk** (retrying mid-stream would duplicate already-emitted output).\n */\nexport function withRetry(adapter: ModelAdapter, opts?: RetryOptions): ModelAdapter {\n  const maxRetries = opts?.maxRetries ?? 2;\n  const baseDelay = opts?.baseDelayMs ?? 200;\n  const isRetryable = opts?.isRetryable ?? (() => true);\n  const sleep = opts?.sleep ?? defaultSleep;\n\n  async function run<T>(fn: () => Promise<T>): Promise<T> {\n    let lastErr: Error = new Error(\"retry failed\");\n    for (let attempt = 0; attempt <= maxRetries; attempt++) {\n      try {\n        return await fn();\n      } catch (err: unknown) {\n        lastErr = err instanceof Error ? err : new Error(String(err));\n        if (attempt === maxRetries || !isRetryable(lastErr)) throw lastErr;\n        await sleep(baseDelay * 2 ** attempt);\n      }\n    }\n    throw lastErr;\n  }\n\n  return {\n    ...passthrough(adapter),\n    chat(params: ChatParams) {\n      return run(() => adapter.chat(params));\n    },\n    async *stream(params: ChatParams): AsyncGenerator<TurnChunk> {\n      // Retry only the initial connection (first chunk); then stream straight through.\n      const gen = await run(async () => {\n        const g = adapter.stream(params);\n        const first = await g.next();\n        return { g, first };\n      });\n      if (!gen.first.done) yield gen.first.value;\n      yield* gen.g;\n    },\n  };\n}\n\n/** Copy the non-method surface (identity, capabilities, pricing, keepAlive). */\nfunction passthrough(adapter: ModelAdapter): {\n  modelId: string;\n  contextWindow: number;\n  capabilities: ModelCapabilities;\n  pricing?: PricingInfo;\n  keepAlive?: ModelAdapter[\"keepAlive\"];\n} {\n  const base: {\n    modelId: string;\n    contextWindow: number;\n    capabilities: ModelCapabilities;\n    pricing?: PricingInfo;\n    keepAlive?: ModelAdapter[\"keepAlive\"];\n  } = {\n    modelId: adapter.modelId,\n    contextWindow: adapter.contextWindow,\n    capabilities: adapter.capabilities,\n  };\n  if (adapter.pricing) base.pricing = adapter.pricing;\n  if (adapter.keepAlive) base.keepAlive = adapter.keepAlive.bind(adapter);\n  return base;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import type { ModelAdapter } from "@halo-sdk/core";
+/** A finished span, shaped after the OpenTelemetry GenAI semantic conventions. */
+export interface GenAISpan {
+    name: string;
+    /** OTel GenAI semconv attributes (`gen_ai.*`). */
+    attributes: Record<string, string | number | boolean>;
+    durationMs: number;
+    error?: string;
+}
+export interface TelemetryOptions {
+    /** Provider/system label → `gen_ai.system` (e.g. "anthropic"). Default: modelId. */
+    system?: string;
+    /** Operation label → `gen_ai.operation.name`. Default per method. */
+    operation?: string;
+    /** Receives each finished span. Bridge to an OTel exporter or a logger. */
+    onSpan: (span: GenAISpan) => void;
+    /** Clock for durations (tests). Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Wrap a {@link ModelAdapter} with OpenTelemetry GenAI-semconv telemetry.
+ *
+ * Each `chat`/`stream` call produces a {@link GenAISpan} (timed, with
+ * `gen_ai.*` token attributes and Halo cache attributes) handed to `onSpan` —
+ * bridge it to an OTel exporter or any sink. Dependency-free: it does not import
+ * `@opentelemetry/*`, so it adds no weight unless you wire a real exporter.
+ */
+export declare function withTelemetry(adapter: ModelAdapter, opts: TelemetryOptions): ModelAdapter;
+export interface RetryOptions {
+    /** Max additional attempts after the first. Default 2. */
+    maxRetries?: number;
+    /** Base backoff in ms (doubles each attempt). Default 200. Set 0 in tests. */
+    baseDelayMs?: number;
+    /** Decide whether an error is worth retrying. Default: retry everything. */
+    isRetryable?: (error: Error) => boolean;
+    /** Sleep impl (tests). Default real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Wrap a {@link ModelAdapter} with exponential-backoff retries on transient
+ * errors. Retries `chat`, and `stream` failures that occur **before the first
+ * chunk** (retrying mid-stream would duplicate already-emitted output).
+ */
+export declare function withRetry(adapter: ModelAdapter, opts?: RetryOptions): ModelAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,EAKb,MAAM,gBAAgB,CAAC;AAIxB,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAClC,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAyBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAkDzF;AAID,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACxC,mDAAmD;IACnD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAKD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,YAAY,CAoClF"}

package/dist/index.js

@@ -0,0 +1,118 @@
+// src/index.ts
+function spanAttributes(adapter, system, operation, usage) {
+  const attrs = {
+    "gen_ai.system": system,
+    "gen_ai.operation.name": operation,
+    "gen_ai.request.model": adapter.modelId
+  };
+  if (usage) {
+    attrs["gen_ai.usage.input_tokens"] = usage.promptTokens;
+    attrs["gen_ai.usage.output_tokens"] = usage.completionTokens;
+    if (usage.caching) {
+      attrs["halo.cache.hit_tokens"] = usage.caching.hitTokens;
+      attrs["halo.cache.miss_tokens"] = usage.caching.missTokens;
+      attrs["halo.cache.hit_rate"] = usage.caching.hitRate;
+    }
+  }
+  return attrs;
+}
+function withTelemetry(adapter, opts) {
+  const system = opts.system ?? adapter.modelId;
+  const now = opts.now ?? (() => Date.now());
+  return {
+    ...passthrough(adapter),
+    async chat(params) {
+      const start = now();
+      try {
+        const result = await adapter.chat(params);
+        opts.onSpan({
+          name: "chat",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "chat", result.usage),
+          durationMs: now() - start
+        });
+        return result;
+      } catch (err) {
+        opts.onSpan({
+          name: "chat",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "chat"),
+          durationMs: now() - start,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+    },
+    async *stream(params) {
+      const start = now();
+      let usage;
+      try {
+        for await (const chunk of adapter.stream(params)) {
+          if (chunk.type === "done") usage = chunk.usage;
+          yield chunk;
+        }
+        opts.onSpan({
+          name: "stream",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "stream", usage),
+          durationMs: now() - start
+        });
+      } catch (err) {
+        opts.onSpan({
+          name: "stream",
+          attributes: spanAttributes(adapter, system, opts.operation ?? "stream", usage),
+          durationMs: now() - start,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+    }
+  };
+}
+var defaultSleep = (ms) => ms <= 0 ? Promise.resolve() : new Promise((r) => setTimeout(r, ms));
+function withRetry(adapter, opts) {
+  const maxRetries = opts?.maxRetries ?? 2;
+  const baseDelay = opts?.baseDelayMs ?? 200;
+  const isRetryable = opts?.isRetryable ?? (() => true);
+  const sleep = opts?.sleep ?? defaultSleep;
+  async function run(fn) {
+    let lastErr = new Error("retry failed");
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+        if (attempt === maxRetries || !isRetryable(lastErr)) throw lastErr;
+        await sleep(baseDelay * 2 ** attempt);
+      }
+    }
+    throw lastErr;
+  }
+  return {
+    ...passthrough(adapter),
+    chat(params) {
+      return run(() => adapter.chat(params));
+    },
+    async *stream(params) {
+      const gen = await run(async () => {
+        const g = adapter.stream(params);
+        const first = await g.next();
+        return { g, first };
+      });
+      if (!gen.first.done) yield gen.first.value;
+      yield* gen.g;
+    }
+  };
+}
+function passthrough(adapter) {
+  const base = {
+    modelId: adapter.modelId,
+    contextWindow: adapter.contextWindow,
+    capabilities: adapter.capabilities
+  };
+  if (adapter.pricing) base.pricing = adapter.pricing;
+  if (adapter.keepAlive) base.keepAlive = adapter.keepAlive.bind(adapter);
+  return base;
+}
+export {
+  withRetry,
+  withTelemetry
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n  ChatParams,\n  ModelAdapter,\n  ModelCapabilities,\n  PricingInfo,\n  TurnChunk,\n  Usage,\n} from \"@halo-sdk/core\";\n\n// ── Telemetry ──\n\n/** A finished span, shaped after the OpenTelemetry GenAI semantic conventions. */\nexport interface GenAISpan {\n  name: string;\n  /** OTel GenAI semconv attributes (`gen_ai.*`). */\n  attributes: Record<string, string | number | boolean>;\n  durationMs: number;\n  error?: string;\n}\n\nexport interface TelemetryOptions {\n  /** Provider/system label → `gen_ai.system` (e.g. \"anthropic\"). Default: modelId. */\n  system?: string;\n  /** Operation label → `gen_ai.operation.name`. Default per method. */\n  operation?: string;\n  /** Receives each finished span. Bridge to an OTel exporter or a logger. */\n  onSpan: (span: GenAISpan) => void;\n  /** Clock for durations (tests). Default `Date.now`. */\n  now?: () => number;\n}\n\nfunction spanAttributes(\n  adapter: ModelAdapter,\n  system: string,\n  operation: string,\n  usage?: Usage,\n): Record<string, string | number | boolean> {\n  const attrs: Record<string, string | number | boolean> = {\n    \"gen_ai.system\": system,\n    \"gen_ai.operation.name\": operation,\n    \"gen_ai.request.model\": adapter.modelId,\n  };\n  if (usage) {\n    attrs[\"gen_ai.usage.input_tokens\"] = usage.promptTokens;\n    attrs[\"gen_ai.usage.output_tokens\"] = usage.completionTokens;\n    if (usage.caching) {\n      attrs[\"halo.cache.hit_tokens\"] = usage.caching.hitTokens;\n      attrs[\"halo.cache.miss_tokens\"] = usage.caching.missTokens;\n      attrs[\"halo.cache.hit_rate\"] = usage.caching.hitRate;\n    }\n  }\n  return attrs;\n}\n\n/**\n * Wrap a {@link ModelAdapter} with OpenTelemetry GenAI-semconv telemetry.\n *\n * Each `chat`/`stream` call produces a {@link GenAISpan} (timed, with\n * `gen_ai.*` token attributes and Halo cache attributes) handed to `onSpan` —\n * bridge it to an OTel exporter or any sink. Dependency-free: it does not import\n * `@opentelemetry/*`, so it adds no weight unless you wire a real exporter.\n */\nexport function withTelemetry(adapter: ModelAdapter, opts: TelemetryOptions): ModelAdapter {\n  const system = opts.system ?? adapter.modelId;\n  const now = opts.now ?? (() => Date.now());\n\n  return {\n    ...passthrough(adapter),\n    async chat(params: ChatParams) {\n      const start = now();\n      try {\n        const result = await adapter.chat(params);\n        opts.onSpan({\n          name: \"chat\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"chat\", result.usage),\n          durationMs: now() - start,\n        });\n        return result;\n      } catch (err: unknown) {\n        opts.onSpan({\n          name: \"chat\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"chat\"),\n          durationMs: now() - start,\n          error: err instanceof Error ? err.message : String(err),\n        });\n        throw err instanceof Error ? err : new Error(String(err));\n      }\n    },\n    async *stream(params: ChatParams): AsyncGenerator<TurnChunk> {\n      const start = now();\n      let usage: Usage | undefined;\n      try {\n        for await (const chunk of adapter.stream(params)) {\n          if (chunk.type === \"done\") usage = chunk.usage;\n          yield chunk;\n        }\n        opts.onSpan({\n          name: \"stream\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"stream\", usage),\n          durationMs: now() - start,\n        });\n      } catch (err: unknown) {\n        opts.onSpan({\n          name: \"stream\",\n          attributes: spanAttributes(adapter, system, opts.operation ?? \"stream\", usage),\n          durationMs: now() - start,\n          error: err instanceof Error ? err.message : String(err),\n        });\n        throw err instanceof Error ? err : new Error(String(err));\n      }\n    },\n  };\n}\n\n// ── Retry ──\n\nexport interface RetryOptions {\n  /** Max additional attempts after the first. Default 2. */\n  maxRetries?: number;\n  /** Base backoff in ms (doubles each attempt). Default 200. Set 0 in tests. */\n  baseDelayMs?: number;\n  /** Decide whether an error is worth retrying. Default: retry everything. */\n  isRetryable?: (error: Error) => boolean;\n  /** Sleep impl (tests). Default real setTimeout. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst defaultSleep = (ms: number): Promise<void> =>\n  ms <= 0 ? Promise.resolve() : new Promise((r) => setTimeout(r, ms));\n\n/**\n * Wrap a {@link ModelAdapter} with exponential-backoff retries on transient\n * errors. Retries `chat`, and `stream` failures that occur **before the first\n * chunk** (retrying mid-stream would duplicate already-emitted output).\n */\nexport function withRetry(adapter: ModelAdapter, opts?: RetryOptions): ModelAdapter {\n  const maxRetries = opts?.maxRetries ?? 2;\n  const baseDelay = opts?.baseDelayMs ?? 200;\n  const isRetryable = opts?.isRetryable ?? (() => true);\n  const sleep = opts?.sleep ?? defaultSleep;\n\n  async function run<T>(fn: () => Promise<T>): Promise<T> {\n    let lastErr: Error = new Error(\"retry failed\");\n    for (let attempt = 0; attempt <= maxRetries; attempt++) {\n      try {\n        return await fn();\n      } catch (err: unknown) {\n        lastErr = err instanceof Error ? err : new Error(String(err));\n        if (attempt === maxRetries || !isRetryable(lastErr)) throw lastErr;\n        await sleep(baseDelay * 2 ** attempt);\n      }\n    }\n    throw lastErr;\n  }\n\n  return {\n    ...passthrough(adapter),\n    chat(params: ChatParams) {\n      return run(() => adapter.chat(params));\n    },\n    async *stream(params: ChatParams): AsyncGenerator<TurnChunk> {\n      // Retry only the initial connection (first chunk); then stream straight through.\n      const gen = await run(async () => {\n        const g = adapter.stream(params);\n        const first = await g.next();\n        return { g, first };\n      });\n      if (!gen.first.done) yield gen.first.value;\n      yield* gen.g;\n    },\n  };\n}\n\n/** Copy the non-method surface (identity, capabilities, pricing, keepAlive). */\nfunction passthrough(adapter: ModelAdapter): {\n  modelId: string;\n  contextWindow: number;\n  capabilities: ModelCapabilities;\n  pricing?: PricingInfo;\n  keepAlive?: ModelAdapter[\"keepAlive\"];\n} {\n  const base: {\n    modelId: string;\n    contextWindow: number;\n    capabilities: ModelCapabilities;\n    pricing?: PricingInfo;\n    keepAlive?: ModelAdapter[\"keepAlive\"];\n  } = {\n    modelId: adapter.modelId,\n    contextWindow: adapter.contextWindow,\n    capabilities: adapter.capabilities,\n  };\n  if (adapter.pricing) base.pricing = adapter.pricing;\n  if (adapter.keepAlive) base.keepAlive = adapter.keepAlive.bind(adapter);\n  return base;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@halo-sdk/otel",
+  "version": "1.0.0",
+  "description": "Observability & resilience decorators for Halo SDK adapters — OpenTelemetry GenAI spans + retry/backoff",
+  "keywords": [
+    "ai",
+    "llm",
+    "observability",
+    "opentelemetry",
+    "resilience",
+    "retry"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halo-sdk/halo-ai",
+    "directory": "packages/otel"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "@halo-sdk/core": "1.1.0"
+  },
+  "peerDependencies": {
+    "@halo-sdk/core": ">=1.1.0"
+  },
+  "scripts": {
+    "build": "tsc --build --emitDeclarationOnly && tsup",
+    "dev": "tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "publint": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}