@agentick/core 0.0.1

package/dist/core/event-buffer.js

@@ -0,0 +1,346 @@
+/**
+ * EventBuffer - Typed event stream with channel-based subscriptions
+ *
+ * A streaming primitive that combines EventEmitter's channel model with:
+ * - **Type-safe channels**: Event `type` property IS the channel name
+ * - **Narrowed handlers**: `on('delta', h)` gives handler the narrowed type
+ * - **Dual consumption**: Multiple consumers see all events independently
+ * - **Replay support**: Late subscribers receive buffered events
+ * - **Async iteration**: `for await (const event of buffer)`
+ *
+ * Events must have a `type` property that acts as the channel discriminator.
+ * This aligns with discriminated union patterns common in TypeScript.
+ *
+ * @module tentickle/core/event-buffer
+ */
+/**
+ * Wildcard key for subscribers that receive all events.
+ */
+const WILDCARD = "*";
+/**
+ * EventBuffer enables typed, channel-based event streaming.
+ *
+ * The event's `type` property IS the channel. Subscribing to 'delta'
+ * means you only receive events where `event.type === 'delta'`.
+ *
+ * @example Basic usage with channels
+ * ```typescript
+ * type StreamEvent =
+ *   | { type: 'delta'; value: string }
+ *   | { type: 'complete'; result: any };
+ *
+ * const buffer = new EventBuffer<StreamEvent>();
+ *
+ * // Subscribe to specific channel - handler gets narrowed type
+ * buffer.on('delta', (event) => {
+ *   console.log(event.value); // TypeScript knows: { type: 'delta', value: string }
+ * });
+ *
+ * // Subscribe to all events
+ * buffer.on((event) => {
+ *   console.log(event); // StreamEvent union
+ * });
+ *
+ * // Emit - type can be first arg (event.type omitted) or in event object
+ * buffer.emit('delta', { value: 'Hello' });
+ * buffer.emit({ type: 'complete', result: 42 });
+ * ```
+ *
+ * @example Late subscriber with replay
+ * ```typescript
+ * buffer.emit('delta', { value: 'first' });
+ * buffer.emit('delta', { value: 'second' });
+ *
+ * // Late subscriber gets all past 'delta' events replayed
+ * buffer.onReplay('delta', (e) => console.log(e.value));
+ * // logs: 'first', 'second'
+ * ```
+ *
+ * @example Async iteration
+ * ```typescript
+ * for await (const event of buffer) {
+ *   if (event.type === 'complete') break;
+ *   console.log(event);
+ * }
+ * ```
+ */
+export class EventBuffer {
+    buffer = [];
+    subscribers = new Map();
+    waiters = [];
+    _closed = false;
+    _error = null;
+    // ============================================================================
+    // Push Events
+    // ============================================================================
+    /**
+     * Push an event into the buffer.
+     * Notifies subscribers for this event's type and wildcard subscribers.
+     */
+    push(event) {
+        if (this._closed)
+            return;
+        this.buffer.push(event);
+        // Notify type-specific subscribers
+        const typeSubscribers = this.subscribers.get(event.type);
+        if (typeSubscribers) {
+            for (const handler of typeSubscribers) {
+                handler(event);
+            }
+        }
+        // Notify wildcard subscribers
+        const wildcardSubscribers = this.subscribers.get(WILDCARD);
+        if (wildcardSubscribers) {
+            for (const handler of wildcardSubscribers) {
+                handler(event);
+            }
+        }
+        // Resolve first waiter (FIFO for async iteration)
+        if (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter.resolve(event);
+        }
+    }
+    emit(eventTypeOrEvent, maybeEvent) {
+        let event;
+        if (maybeEvent !== undefined) {
+            if (eventTypeOrEvent === WILDCARD) {
+                // emit("*", fullEvent) - backwards compat, push as-is
+                event = maybeEvent;
+            }
+            else {
+                // Two params: emit('delta', { value: 'hi' })
+                event = { type: eventTypeOrEvent, ...maybeEvent };
+            }
+        }
+        else {
+            // One param: emit({ type: 'delta', value: 'hi' })
+            event = eventTypeOrEvent;
+        }
+        this.push(event);
+        return this.getTotalListenerCount() > 0;
+    }
+    on(eventTypeOrHandler, handler) {
+        if (typeof eventTypeOrHandler === "function") {
+            return this.addSubscriber(WILDCARD, eventTypeOrHandler);
+        }
+        else if (eventTypeOrHandler === WILDCARD) {
+            // "*" is explicit wildcard
+            return this.addSubscriber(WILDCARD, handler);
+        }
+        else {
+            return this.addSubscriber(eventTypeOrHandler, handler);
+        }
+    }
+    once(eventTypeOrHandler, handler) {
+        if (typeof eventTypeOrHandler === "function") {
+            const wrapper = (event) => {
+                this.removeSubscriber(WILDCARD, wrapper);
+                eventTypeOrHandler(event);
+            };
+            return this.addSubscriber(WILDCARD, wrapper);
+        }
+        else if (eventTypeOrHandler === WILDCARD) {
+            const wrapper = (event) => {
+                this.removeSubscriber(WILDCARD, wrapper);
+                handler(event);
+            };
+            return this.addSubscriber(WILDCARD, wrapper);
+        }
+        else {
+            const wrapper = (event) => {
+                this.removeSubscriber(eventTypeOrHandler, wrapper);
+                handler(event);
+            };
+            return this.addSubscriber(eventTypeOrHandler, wrapper);
+        }
+    }
+    off(eventTypeOrHandler, handler) {
+        if (typeof eventTypeOrHandler === "function") {
+            return this.removeSubscriber(WILDCARD, eventTypeOrHandler);
+        }
+        else if (eventTypeOrHandler === WILDCARD) {
+            return this.removeSubscriber(WILDCARD, handler);
+        }
+        else {
+            return this.removeSubscriber(eventTypeOrHandler, handler);
+        }
+    }
+    onReplay(eventTypeOrHandler, handler) {
+        if (typeof eventTypeOrHandler === "function") {
+            // Replay all buffered events
+            for (const event of this.buffer) {
+                eventTypeOrHandler(event);
+            }
+            return this.on(eventTypeOrHandler);
+        }
+        else {
+            // Replay only events of this type
+            for (const event of this.buffer) {
+                if (event.type === eventTypeOrHandler) {
+                    handler(event);
+                }
+            }
+            return this.on(eventTypeOrHandler, handler);
+        }
+    }
+    // ============================================================================
+    // Private Subscription Helpers
+    // ============================================================================
+    addSubscriber(key, handler) {
+        if (!this.subscribers.has(key)) {
+            this.subscribers.set(key, new Set());
+        }
+        this.subscribers.get(key).add(handler);
+        return () => this.removeSubscriber(key, handler);
+    }
+    removeSubscriber(key, handler) {
+        const set = this.subscribers.get(key);
+        if (!set)
+            return false;
+        const deleted = set.delete(handler);
+        if (set.size === 0) {
+            this.subscribers.delete(key);
+        }
+        return deleted;
+    }
+    // ============================================================================
+    // Lifecycle
+    // ============================================================================
+    /**
+     * Close the buffer (no more events).
+     * Completes all async iterators gracefully.
+     */
+    close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        // Complete all waiting iterators
+        for (const waiter of this.waiters) {
+            waiter.reject(new Error("Buffer closed"));
+        }
+        this.waiters = [];
+    }
+    /**
+     * Close with an error.
+     * All waiting iterators will throw this error.
+     */
+    error(err) {
+        if (this._closed)
+            return;
+        this._error = err;
+        this._closed = true;
+        for (const waiter of this.waiters) {
+            waiter.reject(err);
+        }
+        this.waiters = [];
+    }
+    // ============================================================================
+    // State
+    // ============================================================================
+    /** Whether the buffer is closed. */
+    get closed() {
+        return this._closed;
+    }
+    /** Error that closed the buffer (if any). */
+    get errorValue() {
+        return this._error;
+    }
+    /** Number of buffered events. */
+    get length() {
+        return this.buffer.length;
+    }
+    /** Total number of active subscribers across all channels. */
+    get listenerCount() {
+        return this.getTotalListenerCount();
+    }
+    getTotalListenerCount() {
+        let count = 0;
+        for (const set of this.subscribers.values()) {
+            count += set.size;
+        }
+        return count;
+    }
+    getListenerCount(eventType) {
+        const key = eventType ?? WILDCARD;
+        return this.subscribers.get(key)?.size ?? 0;
+    }
+    /** Get all buffered events (readonly). */
+    getBuffer() {
+        return this.buffer;
+    }
+    /** Get buffered events of a specific type. */
+    getBufferByType(eventType) {
+        return this.buffer.filter((e) => e.type === eventType);
+    }
+    /** Convert buffer to array (copy). */
+    toArray() {
+        return [...this.buffer];
+    }
+    // ============================================================================
+    // Async Iteration
+    // ============================================================================
+    /**
+     * Async iterator that replays all events then waits for new ones.
+     *
+     * Multiple iterators can exist simultaneously - each sees all events.
+     */
+    async *[Symbol.asyncIterator]() {
+        let index = 0;
+        while (true) {
+            // Yield buffered events
+            while (index < this.buffer.length) {
+                yield this.buffer[index];
+                index++;
+            }
+            // If closed, we're done
+            if (this._closed) {
+                if (this._error)
+                    throw this._error;
+                return;
+            }
+            // Wait for next event
+            try {
+                const event = await new Promise((resolve, reject) => {
+                    this.waiters.push({ resolve, reject });
+                });
+                yield event;
+                index++;
+            }
+            catch {
+                // Buffer closed or errored
+                if (this._error)
+                    throw this._error;
+                return;
+            }
+        }
+    }
+    /**
+     * Create a filtered async iterator for a specific event type.
+     */
+    async *filter(eventType) {
+        for await (const event of this) {
+            if (event.type === eventType) {
+                yield event;
+            }
+        }
+    }
+    addListener(eventTypeOrHandler, handler) {
+        return this.on(eventTypeOrHandler, handler);
+    }
+    removeListener(eventTypeOrHandler, handler) {
+        return this.off(eventTypeOrHandler, handler);
+    }
+    // ============================================================================
+    // Deprecated Aliases (for migration)
+    // ============================================================================
+    /** @deprecated Use `on()` instead */
+    subscribe(handler) {
+        return this.on(handler);
+    }
+    /** @deprecated Use `onReplay()` instead */
+    subscribeWithReplay(handler) {
+        return this.onReplay(handler);
+    }
+}
+//# sourceMappingURL=event-buffer.js.map

package/dist/core/event-buffer.js.map

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

package/dist/core/execution-helpers.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Execution Helpers
+ *
+ * Utilities for understanding execution context - whether an execution
+ * is standalone, nested, what originated it, etc.
+ *
+ * Useful for persistence, logging, and conditional behavior based on
+ * execution hierarchy.
+ */
+import { type KernelContext } from "./context";
+import type { ProcedureNode } from "./procedure-graph";
+/**
+ * Check if this is a standalone (root) execution or nested within another.
+ *
+ * @example
+ * ```typescript
+ * if (isStandaloneExecution(ctx)) {
+ *   // Create new execution record
+ * } else {
+ *   // Link to parent execution
+ * }
+ * ```
+ */
+export declare function isStandaloneExecution(ctx: KernelContext): boolean;
+/**
+ * Check if this execution is nested within another procedure.
+ * Opposite of isStandaloneExecution.
+ */
+export declare function isNestedExecution(ctx: KernelContext): boolean;
+/**
+ * Get the name of the procedure that originated this execution chain.
+ * Returns the origin's name if nested, or current procedure name if standalone.
+ *
+ * @example
+ * ```typescript
+ * const origin = getOriginName(ctx);
+ * // 'engine:stream', 'engine:execute', 'model:generate', etc.
+ * ```
+ */
+export declare function getOriginName(ctx: KernelContext): string | undefined;
+/**
+ * Get the origin procedure node if this is a nested execution.
+ * Returns undefined for standalone executions.
+ */
+export declare function getOriginNode(ctx: KernelContext): ProcedureNode | undefined;
+/**
+ * Check if this execution is within an engine execution (engine:execute or engine:stream).
+ * Useful for persistence to know if engine is handling top-level tracking.
+ *
+ * @example
+ * ```typescript
+ * if (isWithinEngine(ctx)) {
+ *   // Engine handles execution record - just track model-specific stuff
+ * } else {
+ *   // Standalone model call - need full tracking
+ * }
+ * ```
+ */
+export declare function isWithinEngine(ctx: KernelContext): boolean;
+/**
+ * Check if this execution has an ancestor with a specific procedure name.
+ *
+ * @example
+ * ```typescript
+ * if (hasAncestorNamed(ctx, 'engine:stream')) {
+ *   // We're inside a streaming execution
+ * }
+ * ```
+ */
+export declare function hasAncestorNamed(ctx: KernelContext, name: string): boolean;
+/**
+ * Check if this execution has an ancestor matching a predicate.
+ *
+ * @example
+ * ```typescript
+ * if (hasAncestorMatching(ctx, n => n.metadata?.type === 'agent')) {
+ *   // We're inside an agent execution
+ * }
+ * ```
+ */
+export declare function hasAncestorMatching(ctx: KernelContext, predicate: (node: ProcedureNode) => boolean): boolean;
+/**
+ * Get the parent procedure node if one exists.
+ */
+export declare function getParentNode(ctx: KernelContext): ProcedureNode | undefined;
+/**
+ * Get the parent procedure's PID if one exists.
+ */
+export declare function getParentPid(ctx: KernelContext): string | undefined;
+/**
+ * Get the root procedure ID (the origin of this execution chain).
+ * Returns current PID if this is a standalone execution.
+ */
+export declare function getRootPid(ctx: KernelContext): string | undefined;
+/**
+ * Get execution hierarchy info - useful for logging and persistence.
+ *
+ * @example
+ * ```typescript
+ * const info = getExecutionInfo(ctx);
+ * // {
+ * //   pid: 'abc-123',
+ * //   parentPid: 'def-456',
+ * //   rootPid: 'ghi-789',
+ * //   name: 'model:generate',
+ * //   originName: 'engine:stream',
+ * //   isStandalone: false,
+ * //   isWithinEngine: true,
+ * //   depth: 2
+ * // }
+ * ```
+ */
+export declare function getExecutionInfo(ctx: KernelContext): {
+    pid: string | undefined;
+    parentPid: string | undefined;
+    rootPid: string | undefined;
+    name: string | undefined;
+    originName: string | undefined;
+    isStandalone: boolean;
+    isWithinEngine: boolean;
+    depth: number;
+};
+/**
+ * Options for withExecution helper.
+ */
+export interface WithExecutionOptions {
+    /**
+     * Human-readable name for this execution (shown in DevTools).
+     */
+    name: string;
+    /**
+     * Execution type for categorization (e.g., 'summarization', 'validation').
+     * Shown as a badge in DevTools.
+     * @default 'custom'
+     */
+    type?: string;
+    /**
+     * Additional metadata to attach to the execution.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create a named execution boundary around an operation.
+ *
+ * Use this to mark semantically meaningful operations that should appear
+ * as distinct executions in DevTools. The execution will be linked as a
+ * child of the current execution (if any).
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with just a name
+ * const summary = await withExecution("Summarize Context", async () => {
+ *   return model.generate(summarizePrompt);
+ * });
+ *
+ * // With options
+ * const result = await withExecution({
+ *   name: "Validate Response",
+ *   type: "validation",
+ *   metadata: { validator: "schema" },
+ * }, async () => {
+ *   return validateSchema(response);
+ * });
+ *
+ * // In a hook
+ * onAfterCompile: async (ctx) => {
+ *   await withExecution("Context Compaction", async () => {
+ *     const summary = await model.generate(compactPrompt);
+ *     ctx.updateContext(summary);
+ *   });
+ * }
+ * ```
+ *
+ * @param nameOrOptions - Execution name string or options object
+ * @param fn - The async function to execute within this boundary
+ * @returns The result of the function
+ */
+export declare function withExecution<T>(nameOrOptions: string | WithExecutionOptions, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=execution-helpers.d.ts.map

package/dist/core/execution-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-helpers.d.ts","sourceRoot":"","sources":["../../src/core/execution-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAEjE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,CAE3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAS1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,GAC1C,OAAO,CAMT;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,CAE3E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAEnE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG;IACpD,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACf,CAmBA;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,aAAa,EAAE,MAAM,GAAG,oBAAoB,EAC5C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}