@princetheprogrammerbtw/husk 0.1.1 → 0.3.0

package/dist/otel/index.d.ts

@@ -0,0 +1,49 @@
+import { Tracer as Tracer$1 } from '@opentelemetry/api';
+import { T as Tracer, S as SpanOptions, a as SpanContext, b as Span } from '../tracer-y41CTrNG.js';
+
+/**
+ * Husk — OpenTelemetry adapter.
+ *
+ * Bridges Husk's minimal Tracer interface to the real
+ * @opentelemetry/api Tracer. Users who want production observability
+ * install @opentelemetry/api alongside Husk, then use this adapter
+ * to convert their OTel tracer into a Husk Tracer for use with
+ * EventTracer.
+ *
+ * Subpath import: '@princetheprogrammerbtw/husk/otel'
+ *
+ * @opentelemetry/api is declared as an *optional peer* dependency.
+ * If you try to use this subpath without installing OTel, you'll
+ * get a clear import error.
+ *
+ * Usage:
+ *
+ *   // 1. Set up OTel (your existing code)
+ *   import { trace } from '@opentelemetry/api';
+ *   const otelTracer = trace.getTracer('my-app', '1.0.0');
+ *
+ *   // 2. Bridge to Husk
+ *   import { EventTracer } from '@princetheprogrammerbtw/husk';
+ *   import { OtelTracerAdapter } from '@princetheprogrammerbtw/husk/otel';
+ *   const huskTracer = new OtelTracerAdapter(otelTracer);
+ *
+ *   // 3. Wire up the agent
+ *   const agent = new Agent({ model: ... });
+ *   agent.onAny(new EventTracer(huskTracer).onEvent);
+ *
+ *   // 4. Configure your OTel exporter as usual (OTLP, Jaeger, etc.)
+ *   // Husk's events now show up as spans in your backend.
+ */
+
+interface OtelTracerAdapterOptions {
+    /** Optional attribute transformer. Default: pass through. */
+    readonly transformAttribute?: (key: string, value: string | number | boolean | null) => string | number | boolean;
+}
+declare class OtelTracerAdapter implements Tracer {
+    private readonly otel;
+    private readonly options;
+    constructor(otel: Tracer$1, options?: OtelTracerAdapterOptions);
+    startSpan(options: SpanOptions, _parent?: SpanContext): Span;
+}
+
+export { OtelTracerAdapter, type OtelTracerAdapterOptions };

package/dist/otel/index.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// src/otel/index.ts
+var OtelTracerAdapter = class {
+  otel;
+  options;
+  constructor(otel, options = {}) {
+    this.otel = otel;
+    this.options = options;
+  }
+  startSpan(options, _parent) {
+    const otelSpan = this.otel.startSpan(options.name, {
+      kind: mapKind(options.kind),
+      attributes: stringifyAttrs(options.attributes)
+    });
+    return new OtelSpanAdapter(otelSpan, this.options);
+  }
+};
+var OtelSpanAdapter = class {
+  context;
+  otel;
+  constructor(otel, _options) {
+    this.otel = otel;
+    const ctx = otel.spanContext();
+    this.context = {
+      traceId: ctx.traceId,
+      spanId: ctx.spanId
+    };
+  }
+  addEvent(name, attributes) {
+    this.otel.addEvent(name, stringifyAttrs(attributes));
+  }
+  setAttribute(key, value) {
+    this.otel.setAttribute(key, value === null ? "" : value);
+  }
+  recordException(err) {
+    this.otel.recordException(err);
+  }
+  setStatus(status, message) {
+    if (status === "ok") {
+      this.otel.setStatus({ code: 1 });
+    } else {
+      this.otel.setStatus({ code: 2, message: message ?? "error" });
+    }
+  }
+  end(_endTimeNs) {
+    this.otel.end();
+  }
+};
+function mapKind(kind) {
+  switch (kind) {
+    case "client":
+      return 2;
+    case "server":
+      return 1;
+    default:
+      return 0;
+  }
+}
+function stringifyAttrs(attrs) {
+  if (!attrs) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === null || v === void 0) continue;
+    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+      out[k] = v;
+    } else {
+      out[k] = JSON.stringify(v);
+    }
+  }
+  return out;
+}
+
+export { OtelTracerAdapter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/otel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/otel/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Husk — OpenTelemetry adapter.\n *\n * Bridges Husk's minimal Tracer interface to the real\n * @opentelemetry/api Tracer. Users who want production observability\n * install @opentelemetry/api alongside Husk, then use this adapter\n * to convert their OTel tracer into a Husk Tracer for use with\n * EventTracer.\n *\n * Subpath import: '@princetheprogrammerbtw/husk/otel'\n *\n * @opentelemetry/api is declared as an *optional peer* dependency.\n * If you try to use this subpath without installing OTel, you'll\n * get a clear import error.\n *\n * Usage:\n *\n *   // 1. Set up OTel (your existing code)\n *   import { trace } from '@opentelemetry/api';\n *   const otelTracer = trace.getTracer('my-app', '1.0.0');\n *\n *   // 2. Bridge to Husk\n *   import { EventTracer } from '@princetheprogrammerbtw/husk';\n *   import { OtelTracerAdapter } from '@princetheprogrammerbtw/husk/otel';\n *   const huskTracer = new OtelTracerAdapter(otelTracer);\n *\n *   // 3. Wire up the agent\n *   const agent = new Agent({ model: ... });\n *   agent.onAny(new EventTracer(huskTracer).onEvent);\n *\n *   // 4. Configure your OTel exporter as usual (OTLP, Jaeger, etc.)\n *   // Husk's events now show up as spans in your backend.\n */\n\nimport type { Span as OtelSpan, Tracer as OtelTracer } from '@opentelemetry/api';\nimport type {\n  Span as HuskSpan,\n  SpanContext,\n  SpanKind,\n  SpanOptions,\n  Tracer,\n} from '../obs/tracer.js';\n\nexport interface OtelTracerAdapterOptions {\n  /** Optional attribute transformer. Default: pass through. */\n  readonly transformAttribute?: (\n    key: string,\n    value: string | number | boolean | null,\n  ) => string | number | boolean;\n}\n\nexport class OtelTracerAdapter implements Tracer {\n  private readonly otel: OtelTracer;\n  private readonly options: OtelTracerAdapterOptions;\n\n  constructor(otel: OtelTracer, options: OtelTracerAdapterOptions = {}) {\n    this.otel = otel;\n    this.options = options;\n  }\n\n  startSpan(options: SpanOptions, _parent?: SpanContext): HuskSpan {\n    const otelSpan = this.otel.startSpan(options.name, {\n      kind: mapKind(options.kind),\n      attributes: stringifyAttrs(options.attributes),\n    });\n    return new OtelSpanAdapter(otelSpan, this.options);\n  }\n}\n\n// ───────────────────────────────────────────────────────────────────\n// Span adapter\n// ───────────────────────────────────────────────────────────────────\n\nclass OtelSpanAdapter implements HuskSpan {\n  readonly context: SpanContext;\n  private readonly otel: OtelSpan;\n\n  constructor(otel: OtelSpan, _options: OtelTracerAdapterOptions) {\n    this.otel = otel;\n    const ctx = otel.spanContext();\n    this.context = {\n      traceId: ctx.traceId,\n      spanId: ctx.spanId,\n    };\n  }\n\n  addEvent(name: string, attributes?: Record<string, unknown>): void {\n    this.otel.addEvent(name, stringifyAttrs(attributes));\n  }\n\n  setAttribute(key: string, value: string | number | boolean | null): void {\n    // OTel attributes can't be null; encode as empty string.\n    this.otel.setAttribute(key, value === null ? '' : value);\n  }\n\n  recordException(err: Error): void {\n    this.otel.recordException(err);\n  }\n\n  setStatus(status: 'ok' | 'error', message?: string): void {\n    if (status === 'ok') {\n      this.otel.setStatus({ code: 1 }); // OTel SpanStatusCode.OK\n    } else {\n      this.otel.setStatus({ code: 2, message: message ?? 'error' }); // OTel SpanStatusCode.ERROR\n    }\n  }\n\n  end(_endTimeNs?: bigint): void {\n    this.otel.end();\n  }\n}\n\n// ───────────────────────────────────────────────────────────────────\n// Helpers\n// ───────────────────────────────────────────────────────────────────\n\nfunction mapKind(kind: SpanKind | undefined): 0 | 1 | 2 {\n  // OTel SpanKind: 0=INTERNAL, 1=SERVER, 2=CLIENT\n  switch (kind) {\n    case 'client':\n      return 2;\n    case 'server':\n      return 1;\n    default:\n      return 0;\n  }\n}\n\nfunction stringifyAttrs(\n  attrs: Readonly<Record<string, unknown>> | undefined,\n): Record<string, string | number | boolean> {\n  if (!attrs) return {};\n  const out: Record<string, string | number | boolean> = {};\n  for (const [k, v] of Object.entries(attrs)) {\n    if (v === null || v === undefined) continue;\n    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {\n      out[k] = v;\n    } else {\n      out[k] = JSON.stringify(v);\n    }\n  }\n  return out;\n}\n"]}

package/dist/tracer-y41CTrNG.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Husk — observability types (tracer interface).
+ *
+ * A minimal, OTel-inspired tracer interface. Husk's events are mapped
+ * to spans by the mapper in ./tracer.ts. Users can plug in the real
+ * @opentelemetry/api tracer via the adapter (see ./otel-adapter.ts)
+ * or any other compatible backend.
+ *
+ * Design choice: we don't depend on @opentelemetry/api directly. The
+ * interface here is a strict subset of OTel's Span interface (just
+ * what's needed for agent observability). Keeping the dep out of
+ * Husk's core means users who don't need OTel pay nothing for it.
+ *
+ * For users who want full OTel:
+ *   import { trace } from '@opentelemetry/api';
+ *   import { toOtelTracer } from '@princetheprogrammerbtw/husk/otel-adapter';
+ *   agent.onAny(toOtelTracer(trace.getTracer('husk')).onEvent);
+ */
+type SpanKind = 'internal' | 'client' | 'server';
+interface SpanContext {
+    /** Unique trace id (all spans in one agent.run share this). */
+    readonly traceId: string;
+    /** Unique span id. */
+    readonly spanId: string;
+    /** Parent span id, if any. */
+    readonly parentSpanId?: string;
+}
+interface SpanOptions {
+    readonly name: string;
+    readonly kind?: SpanKind;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly startTimeNs?: bigint;
+}
+interface Span {
+    readonly context: SpanContext;
+    /** Record an event (timestamped annotation) on the span. */
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    /** Set or update an attribute on the span. */
+    setAttribute(key: string, value: string | number | boolean | null): void;
+    /** Record an exception. */
+    recordException(err: Error): void;
+    /** Mark the span as failed. */
+    setStatus(status: 'ok' | 'error', message?: string): void;
+    /** End the span. Must be called exactly once. */
+    end(endTimeNs?: bigint): void;
+}
+interface Tracer {
+    /**
+     * Start a new span. If parent is provided, the new span becomes a
+     * child of it. Returns the new span; caller is responsible for
+     * calling .end() on it.
+     */
+    startSpan(options: SpanOptions, parent?: SpanContext): Span;
+}
+/**
+ * A tracer that does nothing. Used when no real tracer is configured.
+ * Zero overhead — every method is a no-op, so the cost is one virtual
+ * call per event.
+ */
+declare class NoopTracer implements Tracer {
+    startSpan(_options: SpanOptions, _parent?: SpanContext): Span;
+}
+
+export { NoopTracer as N, type SpanOptions as S, type Tracer as T, type SpanContext as a, type Span as b, type SpanKind as c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@princetheprogrammerbtw/husk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Provider-agnostic agent harness — memory, tools, sub-agents, and observability wrapped around any LLM.",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,6 +57,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
+    "@opentelemetry/api": "^1.9.1",
     "@types/node": "^22.10.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2"