kernl 0.12.4 → 0.12.6

package/dist/tracing/subscribers/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../src/tracing/subscribers/console.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAShD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,MAAM,CAAK;IAEnB,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAIjC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAYnD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ3B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO1B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;IAQtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAOzC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAS3B,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,OAAO,CAAC,GAAG;CAeZ"}

package/dist/tracing/subscribers/console.js

@@ -0,0 +1,82 @@
+/**
+ * A simple console subscriber for development and debugging.
+ * Logs span lifecycle events and events to the console.
+ */
+export class ConsoleSubscriber {
+    spans = new Map();
+    nextId = 0;
+    enabled(_data) {
+        return true;
+    }
+    span(data, parent) {
+        const id = `span_${this.nextId++}`;
+        this.spans.set(id, {
+            data,
+            parent,
+            startTime: Date.now(),
+            entered: false,
+        });
+        console.log(`[span:new] ${id} ${data.kind}`, this.fmt(data));
+        return id;
+    }
+    enter(spanId) {
+        const record = this.spans.get(spanId);
+        if (record) {
+            record.entered = true;
+            console.log(`[span:enter] ${spanId} ${record.data.kind}`);
+        }
+    }
+    exit(spanId) {
+        const record = this.spans.get(spanId);
+        if (record) {
+            console.log(`[span:exit] ${spanId} ${record.data.kind}`);
+        }
+    }
+    record(spanId, delta) {
+        const record = this.spans.get(spanId);
+        if (record) {
+            Object.assign(record.data, delta);
+            console.log(`[span:record] ${spanId}`, this.fmt(delta));
+        }
+    }
+    error(spanId, error) {
+        const record = this.spans.get(spanId);
+        if (record) {
+            console.log(`[span:error] ${spanId} ${record.data.kind}`, error.message);
+        }
+    }
+    close(spanId) {
+        const record = this.spans.get(spanId);
+        if (record) {
+            const duration = Date.now() - record.startTime;
+            console.log(`[span:close] ${spanId} ${record.data.kind} (${duration}ms)`);
+            this.spans.delete(spanId);
+        }
+    }
+    event(data, parent) {
+        console.log(`[event] ${data.kind}`, { ...data, parent });
+    }
+    async flush() {
+        // Console subscriber doesn't buffer
+    }
+    async shutdown(_timeout) {
+        this.spans.clear();
+    }
+    fmt(data) {
+        const { kind, ...rest } = data;
+        // Truncate large fields for readability
+        const formatted = {};
+        for (const [key, value] of Object.entries(rest)) {
+            if (typeof value === "string" && value.length > 100) {
+                formatted[key] = value.slice(0, 100) + "...";
+            }
+            else if (Array.isArray(value) && value.length > 3) {
+                formatted[key] = `[${value.length} items]`;
+            }
+            else {
+                formatted[key] = value;
+            }
+        }
+        return formatted;
+    }
+}

package/dist/tracing/types.d.ts

@@ -0,0 +1,77 @@
+import type { LanguageModelItem, LanguageModelTool, LanguageModelUsage, LanguageModelFinishReason, LanguageModelResponseItem, LanguageModelRequestSettings, LanguageModelResponseType, SharedWarning, ToolCallState } from "@kernl-sdk/protocol";
+import { ThreadState } from "../internal.js";
+export type SpanId = string;
+export interface ThreadSpan {
+    kind: "thread";
+    threadId: string;
+    agentId: string;
+    namespace: string;
+    context?: unknown;
+    state?: ThreadState;
+    result?: unknown;
+    error?: string;
+}
+export interface ModelCallSpan {
+    kind: "model.call";
+    provider: string;
+    modelId: string;
+    request?: {
+        input: LanguageModelItem[];
+        settings?: LanguageModelRequestSettings;
+        responseType?: LanguageModelResponseType;
+        tools?: LanguageModelTool[];
+    };
+    response?: {
+        content: LanguageModelResponseItem[];
+        finishReason: LanguageModelFinishReason;
+        usage?: LanguageModelUsage;
+        warnings?: SharedWarning[];
+    };
+}
+export interface ToolCallSpan {
+    kind: "tool.call";
+    toolId: string;
+    callId: string;
+    args?: Record<string, unknown>;
+    state?: ToolCallState;
+    result?: string;
+    error?: string | null;
+}
+export type SpanData = ThreadSpan | ModelCallSpan | ToolCallSpan;
+export type SpanKind = SpanData["kind"];
+export interface ThreadErrorEvent {
+    kind: "thread.error";
+    message: string;
+    stack?: string;
+}
+export interface ThreadAbortedEvent {
+    kind: "thread.aborted";
+    reason?: string;
+}
+export interface ThreadGuardrailTriggeredEvent {
+    kind: "thread.guardrail_triggered";
+    name: string;
+    type: "input" | "output";
+    passed: boolean;
+    reason?: string;
+}
+export interface ToolApprovalRequestedEvent {
+    kind: "tool.approval_requested";
+    toolId: string;
+    callId: string;
+}
+export interface ToolApprovalGrantedEvent {
+    kind: "tool.approval_granted";
+    toolId: string;
+    callId: string;
+    approver?: string;
+}
+export interface ToolApprovalDeniedEvent {
+    kind: "tool.approval_denied";
+    toolId: string;
+    callId: string;
+    reason?: string;
+}
+export type EventData = ThreadErrorEvent | ThreadAbortedEvent | ThreadGuardrailTriggeredEvent | ToolApprovalRequestedEvent | ToolApprovalGrantedEvent | ToolApprovalDeniedEvent;
+export type EventKind = EventData["kind"];
+//# sourceMappingURL=types.d.ts.map

package/dist/tracing/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tracing/types.ts"],"names":[],"mappings":"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"}

package/dist/tracing/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -29,6 +29,10 @@
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
+    },
+    "./tracing": {
+      "types": "./dist/tracing/index.d.ts",
+      "import": "./dist/tracing/index.js"
     }
   },
   "dependencies": {

package/src/agent.ts

@@ -115,6 +115,7 @@ export class Agent<
         tid: options?.threadId,
         namespace: options?.namespace,
         storage: this.kernl.storage?.threads,
+        abort: options?.abort,
       });
       return this.kernl.spawn(thread);
     }
@@ -186,6 +187,7 @@ export class Agent<
         tid: options?.threadId,
         namespace: options?.namespace,
         storage: this.kernl.storage?.threads,
+        abort: options?.abort,
       });
       yield* this.kernl.spawnStream(thread);
       return;

package/src/index.ts

@@ -102,3 +102,4 @@ export type {
   MemoryByte,
   MemoryByteCodec,
 } from "./memory";
+

package/src/kernl/kernl.ts

@@ -12,6 +12,7 @@ import {
   MemoryIndexHandle,
   buildMemoryIndexSchema,
 } from "@/memory";
+import { setSubscriber, clearSubscriber, type Subscriber } from "@/tracing";
 
 import { logger } from "@/lib/logger";
 import { RThreads } from "@/api/resources/threads";
@@ -33,6 +34,7 @@ export class Kernl extends KernlHooks {
   private readonly _models: ModelRegistry;
   private readonly _memopts: MemoryOptions | undefined;
   private readonly _storopts: StorageOptions | undefined;
+  private readonly _subscriber: Subscriber | null = null;
 
   readonly storage: KernlStorage;
   athreads: Map<string, Thread<any, any>> = new Map(); /* active threads */
@@ -60,6 +62,12 @@ export class Kernl extends KernlHooks {
     this.threads = new RThreads(this.storage.threads);
     this.agents = new RAgents(this._agents);
     this.memories = this.initmem();
+
+    // wire tracing
+    if (options.tracer) {
+      this._subscriber = options.tracer;
+      setSubscriber(this._subscriber);
+    }
   }
 
   /**
@@ -196,4 +204,17 @@ export class Kernl extends KernlHooks {
       encoder,
     });
   }
+
+  /**
+   * Gracefully shutdown the Kernl instance.
+   * Flushes and shuts down tracing subscribers, closes storage connections.
+   */
+  async shutdown(timeout?: number): Promise<void> {
+    if (this._subscriber) {
+      await this._subscriber.flush();
+      await this._subscriber.shutdown(timeout);
+      clearSubscriber();
+    }
+    // TODO: close storage connections when storage supports it
+  }
 }

package/src/kernl/types.ts

@@ -3,6 +3,7 @@ import { SearchIndex } from "@kernl-sdk/retrieval";
 
 import { BaseAgent } from "@/agent/base";
 import { KernlStorage } from "@/storage";
+import type { Subscriber } from "@/tracing";
 
 /**
  * Storage configuration for Kernl.
@@ -82,6 +83,12 @@ export interface KernlOptions {
    * Memory system configuration.
    */
   memory?: MemoryOptions;
+
+  /**
+   * Tracer for observability. Receives span and event data.
+   * Use CompositeTracer to fan out to multiple backends.
+   */
+  tracer?: Subscriber;
 }
 
 /**

package/src/mcp/http.ts

@@ -77,7 +77,6 @@ export class MCPServerStreamableHttp extends BaseMCPServer {
       throw e;
     }
 
-    this.logger.debug(`Connected to MCP server: ${this.id}`);
   }
 
   /**
@@ -107,7 +106,6 @@ export class MCPServerStreamableHttp extends BaseMCPServer {
     }
 
     const response = await this.session.listTools();
-    this.logger.debug(`Listed tools: ${JSON.stringify(response)}`);
     return ListToolsResultSchema.parse(response).tools;
   }
 
@@ -136,12 +134,6 @@ export class MCPServerStreamableHttp extends BaseMCPServer {
     );
 
     const parsed = CallToolResultSchema.parse(response);
-    const result = parsed.content;
-
-    this.logger.debug(
-      `Called tool ${toolName} (args: ${JSON.stringify(args)}, result: ${JSON.stringify(result)})`,
-    );
-
-    return result as CallToolResultContent;
+    return parsed.content as CallToolResultContent;
   }
 }

package/src/mcp/sse.ts

@@ -66,8 +66,6 @@ export class MCPServerSSE extends BaseMCPServer {
       await this.close();
       throw e;
     }
-
-    this.logger.debug(`Connected to MCP server: ${this.id}`);
   }
 
   /**
@@ -83,7 +81,6 @@ export class MCPServerSSE extends BaseMCPServer {
     }
 
     const response = await this.session.listTools();
-    this.logger.debug(`Listed tools: ${JSON.stringify(response)}`);
     return ListToolsResultSchema.parse(response).tools;
   }
 
@@ -112,13 +109,7 @@ export class MCPServerSSE extends BaseMCPServer {
     );
 
     const parsed = CallToolResultSchema.parse(response);
-    const result = parsed.content;
-
-    this.logger.debug(
-      `Called tool ${toolName} (args: ${JSON.stringify(args)}, result: ${JSON.stringify(result)})`,
-    );
-
-    return result as CallToolResultContent;
+    return parsed.content as CallToolResultContent;
   }
 
   /**

package/src/mcp/stdio.ts

@@ -62,8 +62,6 @@ export class MCPServerStdio extends BaseMCPServer {
       this.serverInitializeResult = {
         serverInfo: { name: this.id, version: "1.0.0" },
       } as InitializeResult;
-
-      this.logger.debug(`Connected to MCP server: ${this.id}`);
     } catch (e) {
       this.logger.error("Error initializing MCP server:", e);
       await this.close();
@@ -82,7 +80,6 @@ export class MCPServerStdio extends BaseMCPServer {
     }
 
     const response = await this.session.listTools();
-    this.logger.debug(`Listed tools: ${JSON.stringify(response)}`);
     return ListToolsResultSchema.parse(response).tools;
   }
 
@@ -111,13 +108,7 @@ export class MCPServerStdio extends BaseMCPServer {
     );
 
     const parsed = CallToolResultSchema.parse(response);
-    const result = parsed.content;
-
-    this.logger.debug(
-      `Called tool ${toolName} (args: ${JSON.stringify(args)}, result: ${JSON.stringify(result)})`,
-    );
-
-    return result as CallToolResultContent;
+    return parsed.content as CallToolResultContent;
   }
 
   /**

package/src/task.ts

@@ -8,7 +8,6 @@ import type { Thread } from "@/thread";
  */
 export class Task<TContext = UnknownContext, TResult = unknown> {
   id: string /* unique identifier for this task (pid) */;
-  // tgid: string | null; /* task groupid */
   // prio: TaskPriority;
   instructions:
     | string

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;
 }
 
 /**