kernl 0.12.3 → 0.12.6

package/src/thread/thread.ts

@@ -7,6 +7,14 @@ import { Context } from "@/context";
 import type { Task } from "@/task";
 import type { ResolvedAgentResponse } from "@/guardrail";
 import type { ThreadStore } from "@/storage";
+import {
+  span,
+  event,
+  run,
+  type Span,
+  type ModelCallSpan,
+  type ToolCallSpan,
+} from "@/tracing";
 
 import { logger } from "@/lib/logger";
 
@@ -22,6 +30,7 @@ import {
   LanguageModelStreamEvent,
   type LanguageModelUsage,
   type LanguageModelFinishReason,
+  type LanguageModelResponseItem,
 } from "@kernl-sdk/protocol";
 import { randomID, filter } from "@kernl-sdk/shared/lib";
 
@@ -111,8 +120,9 @@ export class Thread<
   private history: ThreadEvent[] /* history representing the event log for the thread */;
   private tickres?: ResolvedAgentResponse<TOutput>; /* final result from terminal tick */
 
-  private abort?: AbortController;
+  private _abort?: AbortSignal;
   private storage?: ThreadStore;
+  private _span?: Span; /* tracing span for current execution */
 
   constructor(options: ThreadOptions<TContext, TOutput>) {
     this.tid = options.tid ?? `tid_${randomID()}`;
@@ -134,6 +144,7 @@ export class Thread<
     this.cpbuf = [];
     this.persisted = options.persisted ?? false;
     this.history = options.history ?? [];
+    this._abort = options.abort;
 
     // seek to latest seq (not persisted)
     if (this.history.length > 0) {
@@ -168,24 +179,42 @@ export class Thread<
    *   - Exactly one thread.stop (with result on success, error on failure)
    */
   async *stream(): AsyncIterable<ThreadStreamEvent> {
-    if (this.state === RUNNING && this.abort) {
+    if (this.state === RUNNING) {
       throw new Error("thread already running");
     }
 
     this.state = RUNNING;
-    this.abort = new AbortController();
     this.tickres = undefined; // reset for this run
 
     await this.checkpoint(); /* c1: persist RUNNING state + initial input */
 
-    this.emit("thread.start");
+    // create thread span (root span for this execution)
+    this._span = span(
+      {
+        kind: "thread",
+        threadId: this.tid,
+        agentId: this.agent.id,
+        namespace: this.namespace,
+        context: this.context.context,
+      },
+      null,
+    );
+    this._span.enter();
 
+    this.emit("thread.start");
     yield { kind: "stream.start" }; // always yield start immediately
 
     try {
       yield* this._execute();
+      this._span.record({ state: "stopped", result: this.tickres });
       this.emit("thread.stop", { state: STOPPED, result: this.tickres });
     } catch (err) {
+      this._span.error(err instanceof Error ? err : new Error(String(err)));
+      event({
+        kind: "thread.error",
+        message: err instanceof Error ? err.message : String(err),
+        stack: err instanceof Error ? err.stack : undefined,
+      });
       this.emit("thread.stop", {
         state: STOPPED,
         error: err instanceof Error ? err.message : String(err),
@@ -193,7 +222,9 @@ export class Thread<
       throw err;
     } finally {
       this.state = STOPPED;
-      this.abort = undefined;
+      this._span.close();
+      // (TODO): questionable whether this should be undefined. perhaps a single thread should exit + resume..
+      this._span = undefined;
       await this.checkpoint(); /* c4: final checkpoint - persist STOPPED state */
     }
   }
@@ -208,7 +239,7 @@ export class Thread<
     for (;;) {
       let err: Error | undefined = undefined;
 
-      if (this.abort?.signal.aborted) {
+      if (this._abort?.aborted) {
         return;
       }
 
@@ -286,37 +317,70 @@ export class Thread<
 
     const req = await this.prepareModelRequest(this.history);
 
+    const s = span<ModelCallSpan>(
+      {
+        kind: "model.call",
+        provider: this.model.provider,
+        modelId: this.model.modelId,
+        request: {
+          input: req.input,
+          settings: req.settings,
+          responseType: req.responseType,
+          tools: req.tools,
+        },
+      },
+      this._span!.id,
+    );
+    s.enter();
+
     this.emit("model.call.start", { settings: req.settings ?? {} });
 
+    // tracing / observability
+    const content: LanguageModelResponseItem[] = [];
     let usage: LanguageModelUsage | undefined;
-    let finishReason: LanguageModelFinishReason = { unified: "other", raw: undefined };
+    let finishReason: LanguageModelFinishReason = {
+      unified: "other",
+      raw: undefined,
+    };
 
     try {
       if (this.model.stream) {
-        for await (const event of this.model.stream(req)) {
-          if (event.kind === "finish") {
-            usage = event.usage;
-            finishReason = event.finishReason;
+        for await (const e of this.model.stream(req)) {
+          if (e.kind === "finish") {
+            usage = e.usage;
+            finishReason = e.finishReason;
           }
-          yield event;
+          if (notDelta(e)) content.push(e as LanguageModelResponseItem);
+          yield e;
         }
       } else {
         // fallback: blocking generate, yield events as batch
         const res = await this.model.generate(req);
         usage = res.usage;
         finishReason = res.finishReason;
-        for (const event of res.content) {
-          yield event;
+        for (const e of res.content) {
+          content.push(e);
+          yield e;
         }
       }
 
+      s.record({
+        response: {
+          content,
+          finishReason,
+          usage,
+        },
+      });
       this.emit("model.call.end", { finishReason, usage });
     } catch (error) {
+      s.error(error instanceof Error ? error : new Error(String(error)));
       this.emit("model.call.end", { finishReason: "error" });
       yield {
         kind: "error",
         error: error instanceof Error ? error : new Error(String(error)),
       };
+    } finally {
+      s.close();
     }
   }
 
@@ -390,12 +454,12 @@ export class Thread<
   }
 
   /**
-   * Cancel the running thread
+   * Abort the running thread.
    *
-   * TODO: Emit thread.stop when cancelled (neither result nor error set)
+   * @throws {Error} Not implemented - use AbortSignal via options instead
    */
-  cancel() {
-    this.abort?.abort();
+  abort() {
+    throw new Error("Not implemented: use AbortSignal via ThreadExecuteOptions");
   }
 
   /**
@@ -478,6 +542,18 @@ export class Thread<
       calls.map(async (call: ToolCall) => {
         const parsedArgs = JSON.parse(call.arguments || "{}");
 
+        // create tool.call span
+        const s = span<ToolCallSpan>(
+          {
+            kind: "tool.call",
+            toolId: call.toolId,
+            callId: call.callId,
+            args: parsedArgs,
+          },
+          this._span!.id,
+        );
+        s.enter();
+
         this.emit("tool.call.start", {
           toolId: call.toolId,
           callId: call.callId,
@@ -501,16 +577,20 @@ export class Thread<
           const ctx = new Context(this.namespace, this.context.context);
           ctx.agent = this.agent;
           ctx.approve(call.callId); // mark this call as approved
+
           const res = await tool.invoke(ctx, call.arguments, call.callId);
 
+          s.record({
+            state: res.state,
+            result: res.result,
+            error: res.error,
+          });
+
           this.emit("tool.call.end", {
             toolId: call.toolId,
             callId: call.callId,
             state: res.state,
-            result:
-              typeof res.result === "string"
-                ? res.result
-                : JSON.stringify(res.result),
+            result: res.result,
             error: res.error,
           });
 
@@ -523,11 +603,15 @@ export class Thread<
             error: res.error,
           };
         } catch (error) {
+          const errMsg = error instanceof Error ? error.message : String(error);
+          s.error(error instanceof Error ? error : new Error(errMsg));
+          s.record({ state: "failed", error: errMsg });
+
           this.emit("tool.call.end", {
             toolId: call.toolId,
             callId: call.callId,
             state: FAILED,
-            error: error instanceof Error ? error.message : String(error),
+            error: errMsg,
           });
 
           return {
@@ -536,8 +620,10 @@ export class Thread<
             toolId: call.toolId,
             state: FAILED,
             result: undefined as any,
-            error: error instanceof Error ? error.message : String(error),
+            error: errMsg,
           };
+        } finally {
+          s.close();
         }
       }),
     );
@@ -598,6 +684,7 @@ export class Thread<
       settings,
       tools,
       responseType,
+      abort: this._abort,
     };
   }
 }

package/src/thread/types.ts

@@ -219,6 +219,11 @@ export interface ThreadOptions<
    * hydrating from a store. Callers creating new threads should omit it.
    */
   persisted?: boolean;
+  /**
+   * Abort signal for cancelling thread execution.
+   * When aborted, the thread will stop at the next safe point.
+   */
+  abort?: AbortSignal;
 }
 
 /**

package/src/tool/tool.ts

@@ -84,7 +84,7 @@ export class FunctionTool<
   readonly description: string;
   readonly parameters?: TParameters;
   readonly mode: "blocking" | "async";
-  private execute: ToolExecuteFunction<TContext, TParameters, TResult>;
+  execute: ToolExecuteFunction<TContext, TParameters, TResult>;
 
   errorfn: ToolErrorFunction | null;
   requiresApproval: ToolApprovalFunction<TParameters>;

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);
+    });
+  });
+});