kernl 0.12.3 → 0.12.6

package/src/tracing/subscribers/console.ts

@@ -0,0 +1,101 @@
+import type { SpanId, SpanData, EventData } from "../types";
+import type { Subscriber } from "../subscriber";
+
+interface SpanRecord {
+  data: SpanData;
+  parent: SpanId | null;
+  startTime: number;
+  entered: boolean;
+}
+
+/**
+ * A simple console subscriber for development and debugging.
+ * Logs span lifecycle events and events to the console.
+ */
+export class ConsoleSubscriber implements Subscriber {
+  private spans = new Map<SpanId, SpanRecord>();
+  private nextId = 0;
+
+  enabled(_data: SpanData): boolean {
+    return true;
+  }
+
+  span(data: SpanData, parent: SpanId | null): SpanId {
+    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: SpanId): void {
+    const record = this.spans.get(spanId);
+    if (record) {
+      record.entered = true;
+      console.log(`[span:enter] ${spanId} ${record.data.kind}`);
+    }
+  }
+
+  exit(spanId: SpanId): void {
+    const record = this.spans.get(spanId);
+    if (record) {
+      console.log(`[span:exit] ${spanId} ${record.data.kind}`);
+    }
+  }
+
+  record(spanId: SpanId, delta: Partial<SpanData>): void {
+    const record = this.spans.get(spanId);
+    if (record) {
+      Object.assign(record.data, delta);
+      console.log(`[span:record] ${spanId}`, this.fmt(delta));
+    }
+  }
+
+  error(spanId: SpanId, error: Error): void {
+    const record = this.spans.get(spanId);
+    if (record) {
+      console.log(`[span:error] ${spanId} ${record.data.kind}`, error.message);
+    }
+  }
+
+  close(spanId: SpanId): void {
+    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: EventData, parent: SpanId | null): void {
+    console.log(`[event] ${data.kind}`, { ...data, parent });
+  }
+
+  async flush(): Promise<void> {
+    // Console subscriber doesn't buffer
+  }
+
+  async shutdown(_timeout?: number): Promise<void> {
+    this.spans.clear();
+  }
+
+  private fmt(data: Partial<SpanData>): Record<string, unknown> {
+    const { kind, ...rest } = data as any;
+    // Truncate large fields for readability
+    const formatted: Record<string, unknown> = {};
+    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/src/tracing/types.ts

@@ -0,0 +1,115 @@
+import type {
+  LanguageModelItem,
+  LanguageModelTool,
+  LanguageModelUsage,
+  LanguageModelFinishReason,
+  LanguageModelResponseItem,
+  LanguageModelRequestSettings,
+  LanguageModelResponseType,
+  SharedWarning,
+  ToolCallState,
+} from "@kernl-sdk/protocol";
+
+import { ThreadState } from "@/internal";
+
+// -----------------------------------------------------------------------------
+// Span Data
+// -----------------------------------------------------------------------------
+
+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"];
+
+// -----------------------------------------------------------------------------
+// Event Data
+// -----------------------------------------------------------------------------
+
+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"];
+

package/dist/trace/processor.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=processor.d.ts.map

package/dist/trace/processor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../src/trace/processor.ts"],"names":[],"mappings":""}

package/dist/trace/processor.js

@@ -1 +0,0 @@
-"use strict";

package/dist/trace/traces.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=traces.d.ts.map

package/dist/trace/traces.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"traces.d.ts","sourceRoot":"","sources":["../../src/trace/traces.ts"],"names":[],"mappings":""}

package/dist/trace/traces.js

@@ -1,73 +0,0 @@
-"use strict";
-// import { defaultProcessor, TracingProcessor } from "./processor.js";
-// import { generateTraceId } from "./utils.js";
-// export type TraceOptions = {
-//   traceId?: string;
-//   name?: string;
-//   groupId?: string;
-//   metadata?: Record<string, any>;
-//   started?: boolean;
-// };
-// export class Trace {
-//   public type = "trace" as const;
-//   public traceId: string;
-//   public name: string;
-//   public groupId: string | null = null;
-//   public metadata?: Record<string, any>;
-//   #processor: TracingProcessor;
-//   #started: boolean;
-//   constructor(options: TraceOptions, processor?: TracingProcessor) {
-//     this.traceId = options.traceId ?? generateTraceId();
-//     this.name = options.name ?? "Agent workflow";
-//     this.groupId = options.groupId ?? null;
-//     this.metadata = options.metadata ?? {};
-//     this.#processor = processor ?? defaultProcessor();
-//     this.#started = options.started ?? false;
-//   }
-//   async start() {
-//     if (this.#started) {
-//       return;
-//     }
-//     this.#started = true;
-//     await this.#processor.onTraceStart(this);
-//   }
-//   async end() {
-//     if (!this.#started) {
-//       return;
-//     }
-//     this.#started = false;
-//     await this.#processor.onTraceEnd(this);
-//   }
-//   clone(): Trace {
-//     return new Trace({
-//       traceId: this.traceId,
-//       name: this.name,
-//       groupId: this.groupId ?? undefined,
-//       metadata: this.metadata,
-//       started: this.#started,
-//     });
-//   }
-//   toJSON(): object | null {
-//     return {
-//       object: this.type,
-//       id: this.traceId,
-//       workflow_name: this.name, // (TODO): why workflow?
-//       group_id: this.groupId,
-//       metadata: this.metadata,
-//     };
-//   }
-// }
-// export class NoopTrace extends Trace {
-//   constructor() {
-//     super({});
-//   }
-//   async start(): Promise<void> {
-//     return;
-//   }
-//   async end(): Promise<void> {
-//     return;
-//   }
-//   toJSON(): object | null {
-//     return null;
-//   }
-// }

package/dist/trace/utils.d.ts

@@ -1,22 +0,0 @@
-/**
- * Generate a trace ID using 16 random bytes (128-bit, 32 hex chars).
- * @returns A trace ID prefixed with `trace_`.
- */
-export declare function generateTraceId(): string;
-/**
- * Generate a span ID using 12 random bytes (96-bit, 24 hex chars).
- * @returns A span ID prefixed with `span_`.
- */
-export declare function generateSpanId(): string;
-/**
- * Generate a group ID using 12 random bytes (96-bit, 24 hex chars).
- * @returns A group ID prefixed with `group_`.
- */
-export declare function generateGroupId(): string;
-/**
- * Remove fields that start with an underscore from an object.
- * @param obj - The object to remove private fields from.
- * @returns A new object with private fields removed.
- */
-export declare function removePrivateFields(obj: Record<string, any>): Record<string, any>;
-//# sourceMappingURL=utils.d.ts.map

package/dist/trace/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/trace/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACvB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAIrB"}

package/dist/trace/utils.js

@@ -1,30 +0,0 @@
-import { randomID } from "@kernl-sdk/shared/lib";
-/**
- * Generate a trace ID using 16 random bytes (128-bit, 32 hex chars).
- * @returns A trace ID prefixed with `trace_`.
- */
-export function generateTraceId() {
-    return `trace_${randomID(16)}`;
-}
-/**
- * Generate a span ID using 12 random bytes (96-bit, 24 hex chars).
- * @returns A span ID prefixed with `span_`.
- */
-export function generateSpanId() {
-    return `span_${randomID(12)}`;
-}
-/**
- * Generate a group ID using 12 random bytes (96-bit, 24 hex chars).
- * @returns A group ID prefixed with `group_`.
- */
-export function generateGroupId() {
-    return `group_${randomID(12)}`;
-}
-/**
- * Remove fields that start with an underscore from an object.
- * @param obj - The object to remove private fields from.
- * @returns A new object with private fields removed.
- */
-export function removePrivateFields(obj) {
-    return Object.fromEntries(Object.entries(obj).filter(([key]) => !key.startsWith("_")));
-}

package/src/trace/traces.ts

@@ -1,86 +0,0 @@
-// import { defaultProcessor, TracingProcessor } from "./processor";
-// import { generateTraceId } from "./utils";
-
-// export type TraceOptions = {
-//   traceId?: string;
-//   name?: string;
-//   groupId?: string;
-//   metadata?: Record<string, any>;
-//   started?: boolean;
-// };
-
-// export class Trace {
-//   public type = "trace" as const;
-//   public traceId: string;
-//   public name: string;
-//   public groupId: string | null = null;
-//   public metadata?: Record<string, any>;
-
-//   #processor: TracingProcessor;
-//   #started: boolean;
-
-//   constructor(options: TraceOptions, processor?: TracingProcessor) {
-//     this.traceId = options.traceId ?? generateTraceId();
-//     this.name = options.name ?? "Agent workflow";
-//     this.groupId = options.groupId ?? null;
-//     this.metadata = options.metadata ?? {};
-//     this.#processor = processor ?? defaultProcessor();
-//     this.#started = options.started ?? false;
-//   }
-
-//   async start() {
-//     if (this.#started) {
-//       return;
-//     }
-
-//     this.#started = true;
-//     await this.#processor.onTraceStart(this);
-//   }
-
-//   async end() {
-//     if (!this.#started) {
-//       return;
-//     }
-
-//     this.#started = false;
-//     await this.#processor.onTraceEnd(this);
-//   }
-
-//   clone(): Trace {
-//     return new Trace({
-//       traceId: this.traceId,
-//       name: this.name,
-//       groupId: this.groupId ?? undefined,
-//       metadata: this.metadata,
-//       started: this.#started,
-//     });
-//   }
-
-//   toJSON(): object | null {
-//     return {
-//       object: this.type,
-//       id: this.traceId,
-//       workflow_name: this.name, // (TODO): why workflow?
-//       group_id: this.groupId,
-//       metadata: this.metadata,
-//     };
-//   }
-// }
-
-// export class NoopTrace extends Trace {
-//   constructor() {
-//     super({});
-//   }
-
-//   async start(): Promise<void> {
-//     return;
-//   }
-
-//   async end(): Promise<void> {
-//     return;
-//   }
-
-//   toJSON(): object | null {
-//     return null;
-//   }
-// }

package/src/trace/utils.ts

@@ -1,38 +0,0 @@
-import { randomID } from "@kernl-sdk/shared/lib";
-
-/**
- * Generate a trace ID using 16 random bytes (128-bit, 32 hex chars).
- * @returns A trace ID prefixed with `trace_`.
- */
-export function generateTraceId(): string {
-  return `trace_${randomID(16)}`;
-}
-
-/**
- * Generate a span ID using 12 random bytes (96-bit, 24 hex chars).
- * @returns A span ID prefixed with `span_`.
- */
-export function generateSpanId(): string {
-  return `span_${randomID(12)}`;
-}
-
-/**
- * Generate a group ID using 12 random bytes (96-bit, 24 hex chars).
- * @returns A group ID prefixed with `group_`.
- */
-export function generateGroupId(): string {
-  return `group_${randomID(12)}`;
-}
-
-/**
- * Remove fields that start with an underscore from an object.
- * @param obj - The object to remove private fields from.
- * @returns A new object with private fields removed.
- */
-export function removePrivateFields(
-  obj: Record<string, any>,
-): Record<string, any> {
-  return Object.fromEntries(
-    Object.entries(obj).filter(([key]) => !key.startsWith("_")),
-  );
-}