kernl 0.12.4 → 0.12.6

package/src/tracing/__tests__/composite.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect, beforeEach } from "vitest";
+
+import { CompositeSubscriber } from "../subscribers/composite";
+import { TestSubscriber } from "./helpers";
+
+describe("CompositeSubscriber", () => {
+  let sub1: TestSubscriber;
+  let sub2: TestSubscriber;
+  let composite: CompositeSubscriber;
+
+  beforeEach(() => {
+    sub1 = new TestSubscriber();
+    sub2 = new TestSubscriber();
+    composite = new CompositeSubscriber([sub1, sub2]);
+  });
+
+  describe("enabled", () => {
+    it("should return true if any subscriber is enabled", () => {
+      sub1.enabledKinds = new Set(["thread"]);
+      sub2.enabledKinds = new Set(["model.call"]);
+
+      expect(composite.enabled({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" })).toBe(true);
+      expect(composite.enabled({ kind: "model.call", provider: "test", modelId: "m1" })).toBe(true);
+    });
+
+    it("should return false if no subscriber is enabled", () => {
+      sub1.enabledKinds = new Set(["thread"]);
+      sub2.enabledKinds = new Set(["thread"]);
+
+      expect(composite.enabled({ kind: "model.call", provider: "test", modelId: "m1" })).toBe(false);
+    });
+
+    it("should return true if all subscribers are enabled (default)", () => {
+      expect(composite.enabled({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" })).toBe(true);
+    });
+  });
+
+  describe("span", () => {
+    it("should create span in all enabled subscribers", () => {
+      const data = { kind: "thread" as const, threadId: "t1", agentId: "a1", namespace: "ns" };
+      composite.span(data, null);
+
+      expect(sub1.spans.size).toBe(1);
+      expect(sub2.spans.size).toBe(1);
+
+      const [, s1] = [...sub1.spans.entries()][0];
+      const [, s2] = [...sub2.spans.entries()][0];
+      expect(s1.data).toEqual(data);
+      expect(s2.data).toEqual(data);
+    });
+
+    it("should return composite span ID", () => {
+      const id = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+      expect(id).toMatch(/^composite_\d+$/);
+    });
+
+    it("should skip disabled subscribers", () => {
+      sub1.enabledKinds = new Set(["thread"]);
+      sub2.enabledKinds = new Set(["model.call"]); // not enabled for thread
+
+      composite.span({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" }, null);
+
+      expect(sub1.spans.size).toBe(1);
+      expect(sub2.spans.size).toBe(0);
+    });
+
+    it("should map parent span IDs correctly", () => {
+      // Create parent
+      const parentId = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      // Create child with parent
+      composite.span({ kind: "model.call", provider: "test", modelId: "m1" }, parentId);
+
+      // Each subscriber should have correct parent mapping
+      const threadSpan1 = sub1.spansOfKind("thread")[0];
+      const modelSpan1 = sub1.spansOfKind("model.call")[0];
+      expect(modelSpan1.parent).toBe(threadSpan1.id);
+
+      const threadSpan2 = sub2.spansOfKind("thread")[0];
+      const modelSpan2 = sub2.spansOfKind("model.call")[0];
+      expect(modelSpan2.parent).toBe(threadSpan2.id);
+    });
+  });
+
+  describe("enter / exit", () => {
+    it("should dispatch to all subscribers", () => {
+      const spanId = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      composite.enter(spanId);
+      expect(sub1.entered.size).toBe(1);
+      expect(sub2.entered.size).toBe(1);
+
+      composite.exit(spanId);
+      expect(sub1.exited.size).toBe(1);
+      expect(sub2.exited.size).toBe(1);
+    });
+
+    it("should skip disabled subscribers", () => {
+      sub2.enabledKinds = new Set(["model.call"]); // not enabled for thread
+
+      const spanId = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      composite.enter(spanId);
+      expect(sub1.entered.size).toBe(1);
+      expect(sub2.entered.size).toBe(0);
+    });
+  });
+
+  describe("record", () => {
+    it("should dispatch to all subscribers", () => {
+      const spanId = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      composite.record(spanId, { state: "running" } as any);
+
+      const sub1SpanId = [...sub1.spans.keys()][0];
+      const sub2SpanId = [...sub2.spans.keys()][0];
+
+      expect(sub1.getRecorded(sub1SpanId)).toHaveLength(1);
+      expect(sub2.getRecorded(sub2SpanId)).toHaveLength(1);
+    });
+  });
+
+  describe("error", () => {
+    it("should dispatch to all subscribers", () => {
+      const spanId = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      const err = new Error("test");
+      composite.error(spanId, err);
+
+      const sub1SpanId = [...sub1.spans.keys()][0];
+      const sub2SpanId = [...sub2.spans.keys()][0];
+
+      expect(sub1.errors.get(sub1SpanId)).toHaveLength(1);
+      expect(sub2.errors.get(sub2SpanId)).toHaveLength(1);
+    });
+  });
+
+  describe("close", () => {
+    it("should dispatch to all subscribers and clean up", () => {
+      const spanId = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      composite.close(spanId);
+
+      expect(sub1.closed.size).toBe(1);
+      expect(sub2.closed.size).toBe(1);
+    });
+  });
+
+  describe("event", () => {
+    it("should dispatch to all subscribers", () => {
+      composite.event({ kind: "thread.error", message: "test" }, null);
+
+      expect(sub1.events).toHaveLength(1);
+      expect(sub2.events).toHaveLength(1);
+    });
+
+    it("should map parent span IDs correctly", () => {
+      const spanId = composite.span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      composite.event({ kind: "thread.error", message: "test" }, spanId);
+
+      const sub1SpanId = [...sub1.spans.keys()][0];
+      const sub2SpanId = [...sub2.spans.keys()][0];
+
+      expect(sub1.events[0].parent).toBe(sub1SpanId);
+      expect(sub2.events[0].parent).toBe(sub2SpanId);
+    });
+
+    it("should handle null parent", () => {
+      composite.event({ kind: "thread.error", message: "test" }, null);
+
+      expect(sub1.events[0].parent).toBeNull();
+      expect(sub2.events[0].parent).toBeNull();
+    });
+  });
+
+  describe("flush", () => {
+    it("should flush all subscribers", async () => {
+      await composite.flush();
+
+      expect(sub1.calls.some((c) => c.method === "flush")).toBe(true);
+      expect(sub2.calls.some((c) => c.method === "flush")).toBe(true);
+    });
+  });
+
+  describe("shutdown", () => {
+    it("should shutdown all subscribers", async () => {
+      await composite.shutdown(5000);
+
+      expect(sub1.calls.some((c) => c.method === "shutdown")).toBe(true);
+      expect(sub2.calls.some((c) => c.method === "shutdown")).toBe(true);
+    });
+  });
+});

package/src/tracing/__tests__/dispatch.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+
+import {
+  span,
+  event,
+  run,
+  current,
+  setSubscriber,
+  clearSubscriber,
+  getSubscriber,
+} from "../dispatch";
+import { NoopSpan, SpanImpl } from "../span";
+import { TestSubscriber } from "./helpers";
+
+describe("dispatch", () => {
+  let subscriber: TestSubscriber;
+
+  beforeEach(() => {
+    subscriber = new TestSubscriber();
+  });
+
+  afterEach(() => {
+    clearSubscriber();
+  });
+
+  describe("setSubscriber / clearSubscriber / getSubscriber", () => {
+    it("should set and get subscriber", () => {
+      expect(getSubscriber()).toBeNull();
+      setSubscriber(subscriber);
+      expect(getSubscriber()).toBe(subscriber);
+    });
+
+    it("should throw if subscriber already set", () => {
+      setSubscriber(subscriber);
+      expect(() => setSubscriber(new TestSubscriber())).toThrow(
+        "Global subscriber already set",
+      );
+    });
+
+    it("should allow re-setting after clear", () => {
+      setSubscriber(subscriber);
+      clearSubscriber();
+      expect(getSubscriber()).toBeNull();
+
+      const newSubscriber = new TestSubscriber();
+      setSubscriber(newSubscriber);
+      expect(getSubscriber()).toBe(newSubscriber);
+    });
+  });
+
+  describe("span", () => {
+    it("should return NoopSpan when no subscriber is set", () => {
+      const s = span({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" });
+      expect(s).toBeInstanceOf(NoopSpan);
+      expect(s.noop()).toBe(true);
+    });
+
+    it("should return NoopSpan when subscriber.enabled returns false", () => {
+      subscriber.enabledKinds = new Set(["model.call"]); // only model.call enabled
+      setSubscriber(subscriber);
+
+      const s = span({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" });
+      expect(s).toBeInstanceOf(NoopSpan);
+      expect(subscriber.spans.size).toBe(0);
+    });
+
+    it("should return SpanImpl when subscriber is set and enabled", () => {
+      setSubscriber(subscriber);
+
+      const s = span({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" });
+      expect(s).toBeInstanceOf(SpanImpl);
+      expect(s.noop()).toBe(false);
+      expect(s.id).toBeDefined();
+    });
+
+    it("should pass span data to subscriber", () => {
+      setSubscriber(subscriber);
+
+      const data = { kind: "thread" as const, threadId: "t1", agentId: "a1", namespace: "ns" };
+      span(data);
+
+      expect(subscriber.spans.size).toBe(1);
+      const [, captured] = [...subscriber.spans.entries()][0];
+      expect(captured.data).toEqual(data);
+    });
+
+    it("should use null parent when parent=null", () => {
+      setSubscriber(subscriber);
+
+      span({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" }, null);
+
+      const [, captured] = [...subscriber.spans.entries()][0];
+      expect(captured.parent).toBeNull();
+    });
+
+    it("should use explicit parent when provided", () => {
+      setSubscriber(subscriber);
+
+      span({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" }, "parent_123");
+
+      const [, captured] = [...subscriber.spans.entries()][0];
+      expect(captured.parent).toBe("parent_123");
+    });
+
+    it("should resolve parent from context when parent='current' (default)", () => {
+      setSubscriber(subscriber);
+
+      // Create parent span
+      const parentSpan = span(
+        { kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" },
+        null,
+      );
+
+      // Create child span within run() context
+      run(parentSpan.id, () => {
+        span({ kind: "model.call", provider: "test", modelId: "m1" });
+      });
+
+      const modelSpans = subscriber.spansOfKind("model.call");
+      expect(modelSpans).toHaveLength(1);
+      expect(modelSpans[0].parent).toBe(parentSpan.id);
+    });
+
+    it("should use null parent when parent='current' but no context", () => {
+      setSubscriber(subscriber);
+
+      // No run() context
+      span({ kind: "thread", threadId: "t1", agentId: "a1", namespace: "ns" });
+
+      const [, captured] = [...subscriber.spans.entries()][0];
+      expect(captured.parent).toBeNull();
+    });
+  });
+
+  describe("run / current", () => {
+    it("should return null when no context", () => {
+      expect(current()).toBeNull();
+    });
+
+    it("should return spanId within run context", () => {
+      const result = run("span_123", () => {
+        return current();
+      });
+      expect(result).toBe("span_123");
+    });
+
+    it("should return to null after run completes", () => {
+      run("span_123", () => {
+        expect(current()).toBe("span_123");
+      });
+      expect(current()).toBeNull();
+    });
+
+    it("should support nested run contexts", () => {
+      const results: (string | null)[] = [];
+
+      run("outer", () => {
+        results.push(current());
+        run("inner", () => {
+          results.push(current());
+        });
+        results.push(current());
+      });
+
+      expect(results).toEqual(["outer", "inner", "outer"]);
+    });
+
+    it("should handle null spanId in run", () => {
+      run("span_123", () => {
+        run(null, () => {
+          expect(current()).toBeNull();
+        });
+      });
+    });
+  });
+
+  describe("event", () => {
+    it("should do nothing when no subscriber is set", () => {
+      // Should not throw
+      event({ kind: "thread.error", message: "test" });
+    });
+
+    it("should emit event to subscriber", () => {
+      setSubscriber(subscriber);
+
+      event({ kind: "thread.error", message: "test error", stack: "stack" });
+
+      expect(subscriber.events).toHaveLength(1);
+      expect(subscriber.events[0].data).toEqual({
+        kind: "thread.error",
+        message: "test error",
+        stack: "stack",
+      });
+    });
+
+    it("should use null parent when parent=null", () => {
+      setSubscriber(subscriber);
+
+      event({ kind: "thread.error", message: "test" }, null);
+
+      expect(subscriber.events[0].parent).toBeNull();
+    });
+
+    it("should use explicit parent when provided", () => {
+      setSubscriber(subscriber);
+
+      event({ kind: "thread.error", message: "test" }, "parent_123");
+
+      expect(subscriber.events[0].parent).toBe("parent_123");
+    });
+
+    it("should resolve parent from context when parent='current' (default)", () => {
+      setSubscriber(subscriber);
+
+      run("span_123", () => {
+        event({ kind: "thread.error", message: "test" });
+      });
+
+      expect(subscriber.events[0].parent).toBe("span_123");
+    });
+  });
+});

package/src/tracing/__tests__/helpers.ts

@@ -0,0 +1,138 @@
+import type { SpanId, SpanData, EventData } from "../types";
+import type { Subscriber } from "../subscriber";
+
+/**
+ * A test subscriber that captures all tracing calls for assertions.
+ */
+export class TestSubscriber implements Subscriber {
+  private nextId = 0;
+
+  // Captured data
+  spans = new Map<SpanId, { data: SpanData; parent: SpanId | null }>();
+  recorded = new Map<SpanId, Partial<SpanData>[]>();
+  errors = new Map<SpanId, Error[]>();
+  events: { data: EventData; parent: SpanId | null }[] = [];
+
+  // Call log for verifying order
+  calls: { method: string; spanId?: SpanId; args?: unknown }[] = [];
+
+  // State tracking
+  entered = new Set<SpanId>();
+  exited = new Set<SpanId>();
+  closed = new Set<SpanId>();
+
+  // Configuration
+  enabledKinds: Set<SpanData["kind"]> | null = null; // null = all enabled
+
+  enabled(data: SpanData): boolean {
+    if (this.enabledKinds === null) return true;
+    return this.enabledKinds.has(data.kind);
+  }
+
+  span(data: SpanData, parent: SpanId | null): SpanId {
+    const id = `test_span_${this.nextId++}`;
+    this.spans.set(id, { data, parent });
+    this.calls.push({ method: "span", spanId: id, args: { data, parent } });
+    return id;
+  }
+
+  enter(spanId: SpanId): void {
+    this.entered.add(spanId);
+    this.calls.push({ method: "enter", spanId });
+  }
+
+  exit(spanId: SpanId): void {
+    this.exited.add(spanId);
+    this.calls.push({ method: "exit", spanId });
+  }
+
+  record(spanId: SpanId, delta: Partial<SpanData>): void {
+    const existing = this.recorded.get(spanId) ?? [];
+    existing.push(delta);
+    this.recorded.set(spanId, existing);
+    this.calls.push({ method: "record", spanId, args: delta });
+  }
+
+  error(spanId: SpanId, err: Error): void {
+    const existing = this.errors.get(spanId) ?? [];
+    existing.push(err);
+    this.errors.set(spanId, existing);
+    this.calls.push({ method: "error", spanId, args: err });
+  }
+
+  close(spanId: SpanId): void {
+    this.closed.add(spanId);
+    this.calls.push({ method: "close", spanId });
+  }
+
+  event(data: EventData, parent: SpanId | null): void {
+    this.events.push({ data, parent });
+    this.calls.push({ method: "event", args: { data, parent } });
+  }
+
+  async flush(): Promise<void> {
+    this.calls.push({ method: "flush" });
+  }
+
+  async shutdown(_timeout?: number): Promise<void> {
+    this.calls.push({ method: "shutdown" });
+  }
+
+  // --- Test helpers ---
+
+  /**
+   * Get all spans of a specific kind.
+   */
+  spansOfKind<K extends SpanData["kind"]>(
+    kind: K,
+  ): Array<{ id: SpanId; data: Extract<SpanData, { kind: K }>; parent: SpanId | null }> {
+    const result: Array<{ id: SpanId; data: Extract<SpanData, { kind: K }>; parent: SpanId | null }> = [];
+    for (const [id, { data, parent }] of this.spans) {
+      if (data.kind === kind) {
+        result.push({ id, data: data as Extract<SpanData, { kind: K }>, parent });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Get events of a specific kind.
+   */
+  eventsOfKind<K extends EventData["kind"]>(
+    kind: K,
+  ): Array<{ data: Extract<EventData, { kind: K }>; parent: SpanId | null }> {
+    return this.events.filter((e) => e.data.kind === kind) as Array<{
+      data: Extract<EventData, { kind: K }>;
+      parent: SpanId | null;
+    }>;
+  }
+
+  /**
+   * Get recorded data for a span.
+   */
+  getRecorded(spanId: SpanId): Partial<SpanData>[] {
+    return this.recorded.get(spanId) ?? [];
+  }
+
+  /**
+   * Check if a span was fully completed (entered, exited, closed).
+   */
+  isComplete(spanId: SpanId): boolean {
+    return this.entered.has(spanId) && this.exited.has(spanId) && this.closed.has(spanId);
+  }
+
+  /**
+   * Reset all captured data.
+   */
+  reset(): void {
+    this.nextId = 0;
+    this.spans.clear();
+    this.recorded.clear();
+    this.errors.clear();
+    this.events = [];
+    this.calls = [];
+    this.entered.clear();
+    this.exited.clear();
+    this.closed.clear();
+  }
+}