@agentick/kernel 0.0.1

package/dist/stream.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Type guard to check if an object is an async iterable.
+ *
+ * @param obj - Object to check
+ * @returns `true` if the object has `Symbol.asyncIterator`
+ *
+ * @example
+ * ```typescript
+ * const result = await someFunction();
+ * if (isAsyncIterable(result)) {
+ *   for await (const item of result) {
+ *     console.log(item);
+ *   }
+ * }
+ * ```
+ */
+export { isAsyncIterable } from "./procedure";
+/**
+ * Transform items in an async stream using a mapper function.
+ *
+ * Preserves the current execution context through all iterations.
+ *
+ * @typeParam T - Input item type
+ * @typeParam R - Output item type
+ * @param stream - Source async iterable
+ * @param mapper - Function to transform each item
+ * @returns Async iterable of transformed items
+ *
+ * @example
+ * ```typescript
+ * const numbers = getNumberStream();
+ * const doubled = mapStream(numbers, (n) => n * 2);
+ * for await (const n of doubled) {
+ *   console.log(n);
+ * }
+ * ```
+ *
+ * @example Async mapper
+ * ```typescript
+ * const users = mapStream(userIds, async (id) => {
+ *   return await fetchUser(id);
+ * });
+ * ```
+ */
+export declare function mapStream<T, R>(stream: AsyncIterable<T>, mapper: (item: T) => R | Promise<R>): AsyncIterable<R>;
+/**
+ * Perform side effects on each stream item without modifying the stream.
+ *
+ * @typeParam T - Item type
+ * @param stream - Source async iterable
+ * @param tapper - Side-effect function called for each item
+ * @returns Async iterable yielding the original items
+ *
+ * @example
+ * ```typescript
+ * const logged = tapStream(events, (event) => {
+ *   console.log('Event:', event.type);
+ * });
+ * for await (const event of logged) {
+ *   processEvent(event);
+ * }
+ * ```
+ */
+export declare function tapStream<T>(stream: AsyncIterable<T>, tapper: (item: T) => void | Promise<void>): AsyncIterable<T>;
+/**
+ * Tagged stream item from {@link mergeStreams} when using a Record input.
+ *
+ * @typeParam T - The value type from the stream
+ */
+export interface StreamTag<T> {
+    /** The key from the input Record identifying which stream this came from */
+    source: string;
+    /** The actual value from the stream */
+    value: T;
+}
+/**
+ * Merge multiple async streams into a single stream, yielding items as they arrive.
+ *
+ * Supports two input formats:
+ * - **Array**: Returns items directly (type `T`)
+ * - **Record**: Returns tagged items with source key (type `StreamTag<T>`)
+ *
+ * Handles context propagation, backpressure, and cleanup of all iterators.
+ *
+ * @typeParam T - Item type
+ * @param input - Array of streams or Record mapping names to streams
+ * @returns Merged stream of items (or tagged items for Record input)
+ *
+ * @example Array of streams (untagged)
+ * ```typescript
+ * const merged = mergeStreams([stream1, stream2, stream3]);
+ * for await (const item of merged) {
+ *   console.log(item); // Items from any stream, in arrival order
+ * }
+ * ```
+ *
+ * @example Record of streams (tagged)
+ * ```typescript
+ * const tagged = mergeStreams({ a: stream1, b: stream2 });
+ * for await (const item of tagged) {
+ *   console.log(item.source, item.value); // 'a' or 'b', plus the value
+ * }
+ * ```
+ */
+export declare function mergeStreams<T>(input: AsyncIterable<T>[] | Record<string, AsyncIterable<T>>): AsyncIterable<T | StreamTag<T>>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAuB,SAAS,CAAC,CAAC,EAAE,CAAC,EACnC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAClC,aAAa,CAAC,CAAC,CAAC,CAuBlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAuB,SAAS,CAAC,CAAC,EAChC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxC,aAAa,CAAC,CAAC,CAAC,CAKlB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAC;CACV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAuB,YAAY,CAAC,CAAC,EACnC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,GAC3D,aAAa,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAmEjC"}

package/dist/stream.js

@@ -0,0 +1,186 @@
+import { Context } from "./context";
+/**
+ * Type guard to check if an object is an async iterable.
+ *
+ * @param obj - Object to check
+ * @returns `true` if the object has `Symbol.asyncIterator`
+ *
+ * @example
+ * ```typescript
+ * const result = await someFunction();
+ * if (isAsyncIterable(result)) {
+ *   for await (const item of result) {
+ *     console.log(item);
+ *   }
+ * }
+ * ```
+ */
+export { isAsyncIterable } from "./procedure";
+/**
+ * Transform items in an async stream using a mapper function.
+ *
+ * Preserves the current execution context through all iterations.
+ *
+ * @typeParam T - Input item type
+ * @typeParam R - Output item type
+ * @param stream - Source async iterable
+ * @param mapper - Function to transform each item
+ * @returns Async iterable of transformed items
+ *
+ * @example
+ * ```typescript
+ * const numbers = getNumberStream();
+ * const doubled = mapStream(numbers, (n) => n * 2);
+ * for await (const n of doubled) {
+ *   console.log(n);
+ * }
+ * ```
+ *
+ * @example Async mapper
+ * ```typescript
+ * const users = mapStream(userIds, async (id) => {
+ *   return await fetchUser(id);
+ * });
+ * ```
+ */
+export async function* mapStream(stream, mapper) {
+    // Ensure we iterate inside the current context
+    const ctx = Context.tryGet();
+    const iterator = stream[Symbol.asyncIterator]();
+    try {
+        while (true) {
+            const next = ctx ? await Context.run(ctx, () => iterator.next()) : await iterator.next();
+            if (next.done)
+                break;
+            const mapped = ctx
+                ? await Context.run(ctx, async () => mapper(next.value))
+                : await mapper(next.value);
+            yield mapped;
+        }
+    }
+    finally {
+        if (iterator.return) {
+            if (ctx)
+                await Context.run(ctx, () => iterator.return());
+            else
+                await iterator.return();
+        }
+    }
+}
+/**
+ * Perform side effects on each stream item without modifying the stream.
+ *
+ * @typeParam T - Item type
+ * @param stream - Source async iterable
+ * @param tapper - Side-effect function called for each item
+ * @returns Async iterable yielding the original items
+ *
+ * @example
+ * ```typescript
+ * const logged = tapStream(events, (event) => {
+ *   console.log('Event:', event.type);
+ * });
+ * for await (const event of logged) {
+ *   processEvent(event);
+ * }
+ * ```
+ */
+export async function* tapStream(stream, tapper) {
+    yield* mapStream(stream, async (item) => {
+        await tapper(item);
+        return item;
+    });
+}
+/**
+ * Merge multiple async streams into a single stream, yielding items as they arrive.
+ *
+ * Supports two input formats:
+ * - **Array**: Returns items directly (type `T`)
+ * - **Record**: Returns tagged items with source key (type `StreamTag<T>`)
+ *
+ * Handles context propagation, backpressure, and cleanup of all iterators.
+ *
+ * @typeParam T - Item type
+ * @param input - Array of streams or Record mapping names to streams
+ * @returns Merged stream of items (or tagged items for Record input)
+ *
+ * @example Array of streams (untagged)
+ * ```typescript
+ * const merged = mergeStreams([stream1, stream2, stream3]);
+ * for await (const item of merged) {
+ *   console.log(item); // Items from any stream, in arrival order
+ * }
+ * ```
+ *
+ * @example Record of streams (tagged)
+ * ```typescript
+ * const tagged = mergeStreams({ a: stream1, b: stream2 });
+ * for await (const item of tagged) {
+ *   console.log(item.source, item.value); // 'a' or 'b', plus the value
+ * }
+ * ```
+ */
+export async function* mergeStreams(input) {
+    const ctx = Context.tryGet();
+    let streams;
+    let tags = null;
+    if (Array.isArray(input)) {
+        streams = input;
+    }
+    else {
+        tags = Object.keys(input);
+        streams = Object.values(input);
+    }
+    // Wrap iterators to run in context
+    const iterators = streams.map((s) => {
+        const iter = s[Symbol.asyncIterator]();
+        return {
+            next: () => (ctx ? Context.run(ctx, () => iter.next()) : iter.next()),
+            return: () => (ctx && iter.return ? Context.run(ctx, () => iter.return()) : iter.return?.()),
+            instance: iter,
+        };
+    });
+    try {
+        // Map of active promises to their iterator index
+        const nextPromises = new Map();
+        // Initialize all iterators
+        for (let i = 0; i < iterators.length; i++) {
+            nextPromises.set(i, iterators[i].next());
+        }
+        while (nextPromises.size > 0) {
+            // Create a race between all active promises
+            const racePromises = Array.from(nextPromises.entries()).map(async ([index, promise]) => {
+                try {
+                    const result = await promise;
+                    return { index, result };
+                }
+                catch (error) {
+                    return { index, error };
+                }
+            });
+            const { index, result, error } = await Promise.race(racePromises);
+            if (error) {
+                throw error;
+            }
+            if (result.done) {
+                nextPromises.delete(index);
+            }
+            else {
+                // If tagged, wrap in tag object. Else yield raw.
+                if (tags) {
+                    yield { source: tags[index], value: result.value };
+                }
+                else {
+                    yield result.value;
+                }
+                // Refill
+                nextPromises.set(index, iterators[index].next());
+            }
+        }
+    }
+    finally {
+        // Ensure all iterators are closed
+        await Promise.all(iterators.map((iter) => iter.return()));
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

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

package/dist/telemetry.d.ts

@@ -0,0 +1,182 @@
+/**
+ * A span represents a unit of work or operation within a trace.
+ * Spans track timing, attributes, and errors for observability.
+ *
+ * @example
+ * ```typescript
+ * const span = Telemetry.startSpan('database-query');
+ * try {
+ *   span.setAttribute('query', 'SELECT * FROM users');
+ *   const result = await db.query(...);
+ *   span.setAttribute('rowCount', result.length);
+ * } catch (error) {
+ *   span.recordError(error);
+ *   throw error;
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+export interface Span {
+    /** End the span, recording its duration. */
+    end(): void;
+    /** Set an attribute on the span for filtering/analysis. */
+    setAttribute(key: string, value: any): void;
+    /** Record an error that occurred during this span. */
+    recordError(error: any): void;
+}
+/**
+ * Attributes for metrics, used for filtering and grouping.
+ *
+ * @example
+ * ```typescript
+ * counter.add(1, { model: 'gpt-4', status: 'success' });
+ * ```
+ */
+export interface MetricAttributes {
+    [key: string]: string | number | boolean;
+}
+/**
+ * A counter metric that only increases (e.g., request count, error count).
+ *
+ * @example
+ * ```typescript
+ * const requestCounter = Telemetry.getCounter('requests', 'count', 'Total requests');
+ * requestCounter.add(1, { endpoint: '/api/chat' });
+ * ```
+ */
+export interface Counter {
+    /** Add a value to the counter. */
+    add(value: number, attributes?: MetricAttributes): void;
+}
+/**
+ * A histogram metric for recording distributions (e.g., latency, sizes).
+ *
+ * @example
+ * ```typescript
+ * const latencyHistogram = Telemetry.getHistogram('latency', 'ms', 'Request latency');
+ * latencyHistogram.record(150, { endpoint: '/api/chat' });
+ * ```
+ */
+export interface Histogram {
+    /** Record a value in the histogram. */
+    record(value: number, attributes?: MetricAttributes): void;
+}
+/**
+ * Interface for telemetry providers (e.g., OpenTelemetry, DataDog).
+ *
+ * Implement this interface to integrate with your observability platform.
+ *
+ * @example
+ * ```typescript
+ * import { trace, metrics } from '@opentelemetry/api';
+ *
+ * const otelProvider: TelemetryProvider = {
+ *   startTrace(name) { return trace.getTracer('agentick').startSpan(name).spanContext().traceId; },
+ *   startSpan(name) { return trace.getTracer('agentick').startSpan(name); },
+ *   // ... implement other methods
+ * };
+ *
+ * Telemetry.setProvider(otelProvider);
+ * ```
+ */
+export interface TelemetryProvider {
+    /** Start a new trace and return its ID. */
+    startTrace(name: string): string;
+    /** Start a new span within the current trace. */
+    startSpan(name: string): Span;
+    /** Record an error in the current trace/span. */
+    recordError(error: any): void;
+    /** End the current trace. */
+    endTrace(): void;
+    /** Get or create a counter metric. */
+    getCounter(name: string, unit?: string, description?: string): Counter;
+    /** Get or create a histogram metric. */
+    getHistogram(name: string, unit?: string, description?: string): Histogram;
+}
+/**
+ * Global telemetry service for tracing, spans, and metrics.
+ *
+ * By default, uses a no-op provider. Call `Telemetry.setProvider()` to integrate
+ * with your observability platform (OpenTelemetry, DataDog, etc.).
+ *
+ * ## Traces and Spans
+ *
+ * Traces represent end-to-end operations. Spans are units of work within a trace.
+ *
+ * ```typescript
+ * const traceId = Telemetry.startTrace('agent-execution');
+ * const span = Telemetry.startSpan('model-call');
+ * try {
+ *   // ... do work
+ *   span.setAttribute('model', 'gpt-4');
+ * } finally {
+ *   span.end();
+ * }
+ * Telemetry.endTrace();
+ * ```
+ *
+ * ## Metrics
+ *
+ * Counters track cumulative values. Histograms track distributions.
+ *
+ * ```typescript
+ * const tokenCounter = Telemetry.getCounter('tokens', 'count', 'Token usage');
+ * tokenCounter.add(150, { model: 'gpt-4', type: 'input' });
+ *
+ * const latency = Telemetry.getHistogram('latency', 'ms', 'Response time');
+ * latency.record(250);
+ * ```
+ *
+ * @see {@link TelemetryProvider} - Implement this to add a custom provider
+ */
+export declare class Telemetry {
+    private static provider;
+    /**
+     * Set the telemetry provider for all Agentick operations.
+     * @param provider - The telemetry provider implementation
+     */
+    static setProvider(provider: TelemetryProvider): void;
+    /**
+     * Reset to the default no-op provider.
+     */
+    static resetProvider(): void;
+    /**
+     * Start a new trace.
+     * @param name - Name of the trace (e.g., 'agent-execution')
+     * @returns The trace ID
+     */
+    static startTrace(name?: string): string;
+    /**
+     * Start a new span within the current trace.
+     * @param name - Name of the span (e.g., 'model-call', 'tool-execution')
+     * @returns A Span object to track the operation
+     */
+    static startSpan(name: string): Span;
+    /**
+     * Record an error in the current trace/span.
+     * @param error - The error to record
+     */
+    static recordError(error: any): void;
+    /**
+     * End the current trace.
+     */
+    static endTrace(): void;
+    /**
+     * Get or create a counter metric.
+     * @param name - Metric name (e.g., 'agentick.tokens')
+     * @param unit - Unit of measurement (e.g., 'count', 'bytes')
+     * @param description - Human-readable description
+     * @returns A Counter instance
+     */
+    static getCounter(name: string, unit?: string, description?: string): Counter;
+    /**
+     * Get or create a histogram metric.
+     * @param name - Metric name (e.g., 'agentick.latency')
+     * @param unit - Unit of measurement (e.g., 'ms', 'bytes')
+     * @param description - Human-readable description
+     * @returns A Histogram instance
+     */
+    static getHistogram(name: string, unit?: string, description?: string): Histogram;
+}
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,IAAI;IACnB,4CAA4C;IAC5C,GAAG,IAAI,IAAI,CAAC;IACZ,2DAA2D;IAC3D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;IAC5C,sDAAsD;IACtD,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB,kCAAkC;IAClC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,iDAAiD;IACjD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iDAAiD;IACjD,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;IAC9B,6BAA6B;IAC7B,QAAQ,IAAI,IAAI,CAAC;IACjB,sCAAsC;IACtC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvE,wCAAwC;IACxC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5E;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAyC;IAEhE;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAIrD;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,GAAE,MAAoB,GAAG,MAAM;IAIrD;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAIpC;;OAEG;IACH,MAAM,CAAC,QAAQ,IAAI,IAAI;IAIvB;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO;IAI7E;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS;CAGlF"}

package/dist/telemetry.js

@@ -0,0 +1,124 @@
+class NoOpProvider {
+    startTrace(_name) {
+        return `trace-${crypto.randomUUID()}`;
+    }
+    startSpan(_name) {
+        return {
+            end: () => { },
+            setAttribute: () => { },
+            recordError: () => { },
+        };
+    }
+    recordError(error) {
+        console.error("Telemetry Error:", error);
+    }
+    endTrace() { }
+    getCounter(_name) {
+        return { add: () => { } };
+    }
+    getHistogram(_name) {
+        return { record: () => { } };
+    }
+}
+/**
+ * Global telemetry service for tracing, spans, and metrics.
+ *
+ * By default, uses a no-op provider. Call `Telemetry.setProvider()` to integrate
+ * with your observability platform (OpenTelemetry, DataDog, etc.).
+ *
+ * ## Traces and Spans
+ *
+ * Traces represent end-to-end operations. Spans are units of work within a trace.
+ *
+ * ```typescript
+ * const traceId = Telemetry.startTrace('agent-execution');
+ * const span = Telemetry.startSpan('model-call');
+ * try {
+ *   // ... do work
+ *   span.setAttribute('model', 'gpt-4');
+ * } finally {
+ *   span.end();
+ * }
+ * Telemetry.endTrace();
+ * ```
+ *
+ * ## Metrics
+ *
+ * Counters track cumulative values. Histograms track distributions.
+ *
+ * ```typescript
+ * const tokenCounter = Telemetry.getCounter('tokens', 'count', 'Token usage');
+ * tokenCounter.add(150, { model: 'gpt-4', type: 'input' });
+ *
+ * const latency = Telemetry.getHistogram('latency', 'ms', 'Response time');
+ * latency.record(250);
+ * ```
+ *
+ * @see {@link TelemetryProvider} - Implement this to add a custom provider
+ */
+export class Telemetry {
+    static provider = new NoOpProvider();
+    /**
+     * Set the telemetry provider for all Agentick operations.
+     * @param provider - The telemetry provider implementation
+     */
+    static setProvider(provider) {
+        this.provider = provider;
+    }
+    /**
+     * Reset to the default no-op provider.
+     */
+    static resetProvider() {
+        this.provider = new NoOpProvider();
+    }
+    /**
+     * Start a new trace.
+     * @param name - Name of the trace (e.g., 'agent-execution')
+     * @returns The trace ID
+     */
+    static startTrace(name = "operation") {
+        return this.provider.startTrace(name);
+    }
+    /**
+     * Start a new span within the current trace.
+     * @param name - Name of the span (e.g., 'model-call', 'tool-execution')
+     * @returns A Span object to track the operation
+     */
+    static startSpan(name) {
+        return this.provider.startSpan(name);
+    }
+    /**
+     * Record an error in the current trace/span.
+     * @param error - The error to record
+     */
+    static recordError(error) {
+        this.provider.recordError(error);
+    }
+    /**
+     * End the current trace.
+     */
+    static endTrace() {
+        this.provider.endTrace();
+    }
+    /**
+     * Get or create a counter metric.
+     * @param name - Metric name (e.g., 'agentick.tokens')
+     * @param unit - Unit of measurement (e.g., 'count', 'bytes')
+     * @param description - Human-readable description
+     * @returns A Counter instance
+     */
+    static getCounter(name, unit, description) {
+        return this.provider.getCounter(name, unit, description);
+    }
+    /**
+     * Get or create a histogram metric.
+     * @param name - Metric name (e.g., 'agentick.latency')
+     * @param unit - Unit of measurement (e.g., 'ms', 'bytes')
+     * @param description - Human-readable description
+     * @returns A Histogram instance
+     */
+    static getHistogram(name, unit, description) {
+        return this.provider.getHistogram(name, unit, description);
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAqGA,MAAM,YAAY;IAChB,UAAU,CAAC,KAAa;QACtB,OAAO,SAAS,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;IACxC,CAAC;IACD,SAAS,CAAC,KAAa;QACrB,OAAO;YACL,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC;YACb,YAAY,EAAE,GAAG,EAAE,GAAE,CAAC;YACtB,WAAW,EAAE,GAAG,EAAE,GAAE,CAAC;SACtB,CAAC;IACJ,CAAC;IACD,WAAW,CAAC,KAAU;QACpB,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,QAAQ,KAAU,CAAC;IACnB,UAAU,CAAC,KAAa;QACtB,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAC3B,CAAC;IACD,YAAY,CAAC,KAAa;QACxB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,OAAO,SAAS;IACZ,MAAM,CAAC,QAAQ,GAAsB,IAAI,YAAY,EAAE,CAAC;IAEhE;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,QAA2B;QAC5C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa;QAClB,IAAI,CAAC,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,OAAe,WAAW;QAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,IAAY;QAC3B,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,KAAU;QAC3B,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAQ;QACb,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,IAAY,EAAE,IAAa,EAAE,WAAoB;QACjE,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,IAAY,EAAE,IAAa,EAAE,WAAoB;QACnE,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAC7D,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Kernel Testing Utilities
+ *
+ * Provides `createTestProcedure` — a lightweight Procedure stub for testing
+ * code that *consumes* procedures without needing real middleware, context
+ * propagation, or execution tracking.
+ *
+ * @example
+ * ```typescript
+ * import { createTestProcedure } from "@agentick/kernel/testing";
+ *
+ * const proc = createTestProcedure({ handler: async (x: number) => x * 2 });
+ * const result = await proc(5).result;  // 10
+ * expect(proc._callCount).toBe(1);
+ * expect(proc._lastArgs).toEqual([5]);
+ * ```
+ *
+ * @module @agentick/kernel/testing
+ */
+import type { Procedure } from "./procedure";
+export interface TestProcedureOptions<TFn extends (...args: any[]) => any> {
+    /** Handler function (default: () => undefined) */
+    handler?: TFn;
+    /** Name for debugging */
+    name?: string;
+}
+export interface TestProcedure<TFn extends (...args: any[]) => any> extends Procedure<TFn, true> {
+    /** Every call recorded: { args, timestamp } */
+    _calls: Array<{
+        args: any[];
+        timestamp: number;
+    }>;
+    /** Shorthand for _calls.length */
+    readonly _callCount: number;
+    /** Shorthand for _calls.at(-1)?.args */
+    readonly _lastArgs: any[] | undefined;
+    /** Override return value for the NEXT call only (reverts after) */
+    respondWith(value: ReturnType<TFn> | (() => ReturnType<TFn>)): void;
+    /** Override return value for ALL subsequent calls */
+    setResponse(value: ReturnType<TFn> | (() => ReturnType<TFn>)): void;
+    /** Clear _calls and all overrides */
+    reset(): void;
+}
+/**
+ * Create a test procedure stub.
+ *
+ * Callable + branded with `PROCEDURE_SYMBOL` so `isProcedure()` returns true.
+ * Returns `ProcedurePromise` so `.result` chaining works.
+ *
+ * Chainable methods (`.use()`, `.withContext()`, etc.) are no-ops returning self.
+ * This is intentional — test procedures are for testing code that *calls*
+ * procedures, not for testing middleware.
+ */
+export declare function createTestProcedure<TFn extends (...args: any[]) => any>(options?: TestProcedureOptions<TFn>): TestProcedure<TFn>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAM/D,MAAM,WAAW,oBAAoB,CAAC,GAAG,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IACvE,kDAAkD;IAClD,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa,CAAC,GAAG,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAE,SAAQ,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC;IAC9F,+CAA+C;IAC/C,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC;IACtC,mEAAmE;IACnE,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;IACpE,qDAAqD;IACrD,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;IACpE,qCAAqC;IACrC,KAAK,IAAI,IAAI,CAAC;CACf;AAMD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrE,OAAO,GAAE,oBAAoB,CAAC,GAAG,CAAM,GACtC,aAAa,CAAC,GAAG,CAAC,CA6EpB"}