@agentick/core 0.0.1

package/dist/core/channel.js

@@ -0,0 +1,199 @@
+import { EventEmitter } from "node:events";
+import { Context } from "./context";
+import { Telemetry } from "./telemetry";
+/**
+ * Core Channel primitive.
+ * Works standalone in any Node environment.
+ * Uses EventEmitter internally for pub/sub.
+ */
+export class Channel {
+    name;
+    emitter = new EventEmitter();
+    pendingRequests = new Map();
+    // Store recent responses to handle race conditions (response before wait)
+    recentResponses = new Map();
+    constructor(name) {
+        this.name = name;
+    }
+    /**
+     * Publish an event to the channel.
+     */
+    publish(event) {
+        // Ensure channel name matches
+        const normalizedEvent = {
+            ...event,
+            channel: this.name,
+            metadata: {
+                timestamp: Date.now(),
+                ...event.metadata,
+            },
+        };
+        // Track channel events as metrics
+        const ctx = Context.tryGet();
+        if (ctx?.procedureGraph && ctx.procedurePid) {
+            const node = ctx.procedureGraph.get(ctx.procedurePid);
+            if (node) {
+                // Track as metric in node
+                node.addMetric(`channel.${this.name}.events`, 1);
+                // Also track in context metrics (for consistency)
+                if (ctx.metrics) {
+                    ctx.metrics[`channel.${this.name}.events`] =
+                        (ctx.metrics[`channel.${this.name}.events`] || 0) + 1;
+                }
+                // Send to telemetry immediately
+                Telemetry.getCounter(`channel.${this.name}.events`).add(1, {
+                    channel: this.name,
+                    event_type: normalizedEvent.type,
+                    procedure: node.name || "anonymous",
+                    procedure_pid: node.pid,
+                });
+            }
+        }
+        // Emit to all subscribers
+        this.emitter.emit("event", normalizedEvent);
+        // If this is a response, resolve any pending requests or store for later
+        if (normalizedEvent.type === "response" && normalizedEvent.id) {
+            const responseId = normalizedEvent.id; // Type guard
+            const pending = this.pendingRequests.get(responseId);
+            if (pending) {
+                clearTimeout(pending.timeout);
+                this.pendingRequests.delete(responseId);
+                pending.resolve(normalizedEvent);
+            }
+            else {
+                // Store response in case waitForResponse is called later (race condition)
+                this.recentResponses.set(responseId, normalizedEvent);
+                // Clean up after 5 seconds
+                setTimeout(() => {
+                    this.recentResponses.delete(responseId);
+                }, 5000);
+            }
+        }
+    }
+    /**
+     * Subscribe to events on this channel.
+     * @returns Unsubscribe function
+     */
+    subscribe(handler) {
+        this.emitter.on("event", handler);
+        return () => {
+            this.emitter.off("event", handler);
+        };
+    }
+    /**
+     * Wait for a response to a specific request.
+     * Used by tools/components for bidirectional communication.
+     *
+     * @param requestId The request ID to wait for
+     * @param timeoutMs Timeout in milliseconds (default: 30000)
+     * @returns Promise that resolves when response is received
+     */
+    waitForResponse(requestId, timeoutMs = 30000) {
+        return new Promise((resolve, reject) => {
+            // Check if response was already received (race condition: response before wait)
+            const cachedResponse = this.recentResponses.get(requestId);
+            if (cachedResponse) {
+                this.recentResponses.delete(requestId);
+                resolve(cachedResponse);
+                return;
+            }
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new Error(`Channel "${this.name}": Request "${requestId}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingRequests.set(requestId, {
+                resolve,
+                reject,
+                timeout,
+            });
+            // Subscribe to catch responses that arrive after we set up the pending request
+            const unsubscribe = this.subscribe((event) => {
+                if (event.type === "response" && event.id === requestId) {
+                    unsubscribe();
+                    clearTimeout(timeout);
+                    this.pendingRequests.delete(requestId);
+                    resolve(event);
+                }
+            });
+        });
+    }
+    /**
+     * Get the number of active subscribers.
+     */
+    getSubscriberCount() {
+        return this.emitter.listenerCount("event");
+    }
+    /**
+     * Cleanup: remove all subscribers and pending requests.
+     */
+    destroy() {
+        // Reject all pending requests
+        for (const [requestId, pending] of this.pendingRequests.entries()) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error(`Channel "${this.name}" destroyed while waiting for request "${requestId}"`));
+        }
+        this.pendingRequests.clear();
+        // Clear cached responses
+        this.recentResponses.clear();
+        // Remove all listeners
+        this.emitter.removeAllListeners();
+    }
+}
+/**
+ * Channel session manages a collection of channels.
+ * Sessions persist across multiple engine executions.
+ */
+export class ChannelSession {
+    id;
+    channels = new Map();
+    createdAt;
+    lastActivity;
+    constructor(id) {
+        this.id = id;
+        this.createdAt = Date.now();
+        this.lastActivity = Date.now();
+    }
+    /**
+     * Get or create a channel within this session.
+     */
+    getChannel(name) {
+        if (!this.channels.has(name)) {
+            this.channels.set(name, new Channel(name));
+        }
+        this.lastActivity = Date.now();
+        return this.channels.get(name);
+    }
+    /**
+     * Remove a channel from the session.
+     */
+    removeChannel(name) {
+        const channel = this.channels.get(name);
+        if (channel) {
+            channel.destroy();
+            this.channels.delete(name);
+        }
+    }
+    /**
+     * Default session ID generator.
+     * Uses user context + conversation ID or trace ID.
+     * Users can override this via ChannelService config.
+     */
+    static generateId(ctx) {
+        const userId = ctx.user?.id || "anonymous";
+        // Use conversationId if present and not 'na', otherwise fall back to traceId
+        const conversationId = ctx.metadata["conversationId"] && ctx.metadata["conversationId"] !== "na"
+            ? ctx.metadata["conversationId"]
+            : ctx.traceId;
+        return `${userId}-${conversationId}`;
+    }
+    /**
+     * Cleanup all channels in the session.
+     */
+    destroy() {
+        for (const channel of this.channels.values()) {
+            channel.destroy();
+        }
+        this.channels.clear();
+    }
+}
+//# sourceMappingURL=channel.js.map

package/dist/core/channel.js.map

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

package/dist/core/context.d.ts

@@ -0,0 +1,412 @@
+import { EventEmitter } from "node:events";
+import { type ChannelServiceInterface } from "./channel";
+import { ProcedureGraph } from "./procedure-graph";
+import type { ProcedureNode } from "./procedure-graph";
+import type { Middleware } from "./procedure";
+/**
+ * User information associated with the current execution context.
+ *
+ * This is typically populated from authentication/authorization systems
+ * and flows through all operations via the `KernelContext`.
+ *
+ * @example
+ * ```typescript
+ * const ctx = Context.create({
+ *   user: {
+ *     id: 'user-123',
+ *     tenantId: 'tenant-abc',
+ *     roles: ['admin', 'editor'],
+ *     email: 'user@example.com', // Custom fields allowed
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link KernelContext.user} - Where user context is stored
+ */
+export interface UserContext {
+    /** Unique identifier for the user */
+    id: string;
+    /** Multi-tenant organization identifier */
+    tenantId?: string;
+    /** User's roles for authorization */
+    roles?: string[];
+    /** Additional user properties (extensible) */
+    [key: string]: any;
+}
+/**
+ * Event emitted during procedure execution.
+ *
+ * Events are emitted to both the global request bus (`ctx.events`)
+ * and the operation handle (`ctx.executionHandle`) if present.
+ *
+ * @example
+ * ```typescript
+ * ctx.events.on('stream:chunk', (event: ExecutionEvent) => {
+ *   console.log(`[${event.source}] ${event.type}:`, event.payload);
+ * });
+ *
+ * // Listen to all events
+ * ctx.events.on('*', (event: ExecutionEvent) => {
+ *   console.log(`Event: ${event.type}`);
+ * });
+ * ```
+ *
+ * @see {@link Context.emit} - Emit events to the current context
+ */
+export interface ExecutionEvent {
+    /** Event type (e.g., 'stream:chunk', 'procedure:error') */
+    type: string;
+    /** Event payload data */
+    payload: any;
+    /** Unix timestamp when the event occurred */
+    timestamp: number;
+    /** Source of the event (e.g., 'agent:sales', 'model:openai') */
+    source: string;
+    /** Trace ID for correlation (distributed tracing) */
+    traceId: string;
+    /** Request ID for this execution context */
+    requestId?: string;
+    /** Execution ID from context (auto-populated if available) */
+    executionId?: string;
+    /** Parent execution ID for nested executions (fork, spawn, component_tool) */
+    parentExecutionId?: string;
+    /** Procedure ID from context (auto-populated if available) */
+    procedureId?: string;
+    /** Current tick number if in a tick context */
+    tick?: number;
+    /** User ID from context (for attribution and multi-tenant filtering) */
+    userId?: string;
+    /** Tenant ID from context (for multi-tenant dashboards) */
+    tenantId?: string;
+}
+/**
+ * Extensible metadata storage within the context.
+ *
+ * Use this to store application-specific data that should flow
+ * through the execution context.
+ *
+ * @example
+ * ```typescript
+ * const ctx = Context.create({
+ *   metadata: {
+ *     conversationId: 'conv-123',
+ *     feature_flags: { beta: true },
+ *   }
+ * });
+ *
+ * // Access later
+ * const convId = Context.get().metadata.conversationId;
+ * ```
+ */
+export interface ContextMetadata extends Record<string, any> {
+}
+/**
+ * Metrics accumulated during procedure execution.
+ *
+ * Metrics are automatically propagated from child procedures to parents
+ * when execution completes.
+ *
+ * @example
+ * ```typescript
+ * // In a procedure
+ * addMetric(ctx, 'tokens.input', 100);
+ * addMetric(ctx, 'api_calls', 1);
+ *
+ * // After execution, parent has accumulated metrics
+ * const totalTokens = ctx.metrics['tokens.input'];
+ * ```
+ *
+ * @see {@link addMetric} - Accumulate a metric value
+ * @see {@link getUsageMetrics} - Get token usage metrics
+ */
+export interface ContextMetrics extends Record<string, any> {
+}
+/**
+ * Execution context that flows through all async operations via AsyncLocalStorage.
+ *
+ * The `KernelContext` contains all state needed during execution:
+ * - Identity and tracing (requestId, traceId, user)
+ * - Event buses (events, executionHandle)
+ * - Cancellation (signal)
+ * - Communication (channels)
+ * - Execution tracking (procedureGraph, procedurePid, origin)
+ * - Extensible storage (metadata, metrics)
+ *
+ * Access the current context with `Context.get()` from anywhere in your code -
+ * no need to pass it explicitly through function calls.
+ *
+ * @example Creating and running with context
+ * ```typescript
+ * const ctx = Context.create({
+ *   user: { id: 'user-1' },
+ *   metadata: { conversationId: 'conv-123' }
+ * });
+ *
+ * await Context.run(ctx, async () => {
+ *   // Context is available here and in all async calls
+ *   const current = Context.get();
+ *   console.log(current.user?.id); // 'user-1'
+ * });
+ * ```
+ *
+ * @example Extending for your application
+ * ```typescript
+ * interface AppContext extends KernelContext {
+ *   customHandle?: MyCustomHandle;
+ *   appMetadata: AppSpecificMetadata;
+ * }
+ * ```
+ *
+ * @see {@link Context} - Static methods to create/access context
+ * @see {@link UserContext} - User information structure
+ */
+export interface KernelContext {
+    /** Unique identifier for this request/execution */
+    requestId: string;
+    /** Correlation ID for distributed tracing */
+    traceId: string;
+    /** User information (from auth) */
+    user?: UserContext;
+    /** Application-specific metadata */
+    metadata: ContextMetadata;
+    /** Accumulated execution metrics */
+    metrics: ContextMetrics;
+    /** Global request event bus for subscribing to all events */
+    events: EventEmitter;
+    /** Abort signal for cooperative cancellation */
+    signal?: AbortSignal;
+    /** Operation-specific event emitter (from `.withHandle()`) */
+    executionHandle?: EventEmitter;
+    /**
+     * Channel service for bidirectional communication (optional).
+     * Injected by Engine when channels are configured.
+     * Tools and components can access channels via this service.
+     */
+    channels?: ChannelServiceInterface;
+    /**
+     * Procedure graph for tracking procedure execution hierarchy.
+     * Automatically initialized when first procedure is executed.
+     */
+    procedureGraph?: ProcedureGraph;
+    /**
+     * Current procedure PID (for tracking nested procedures).
+     */
+    procedurePid?: string;
+    /** Current procedure node in the graph */
+    procedureNode?: ProcedureNode;
+    /**
+     * Origin procedure node - the root procedure that initiated this execution chain.
+     * Undefined for the root procedure itself (since it IS the origin).
+     * Set automatically by ExecutionTracker when procedures are executed.
+     */
+    origin?: ProcedureNode;
+    /**
+     * Current execution ID. Set when entering an execution boundary.
+     * All procedures within this execution share this ID.
+     */
+    executionId?: string;
+    /**
+     * Type of execution at this boundary (e.g., 'engine', 'model', 'component_tool', 'fork', 'spawn').
+     * Only meaningful at execution boundaries.
+     */
+    executionType?: string;
+    /**
+     * Parent execution ID for nested executions (e.g., component_tool called from engine).
+     * Enables DevTools to show execution hierarchy.
+     */
+    parentExecutionId?: string;
+    /**
+     * Current tick number (set by engine during tick loop).
+     * Enables events to include tick context for correlation.
+     */
+    tick?: number;
+    /**
+     * Middleware registry for procedure execution.
+     * Procedures read this at execution time to get instance-level middleware.
+     * Typically set by createApp() from the Tentickle instance.
+     */
+    middleware?: {
+        getMiddlewareFor(procedureName: string): Middleware[];
+    };
+    /**
+     * Type brand for context detection
+     */
+    [KERNEL_CONTEXT_SYMBOL]?: boolean;
+}
+/**
+ * Static class for managing execution context via AsyncLocalStorage.
+ *
+ * Context flows automatically through all async operations without explicit passing.
+ * Use `Context.run()` to establish context, and `Context.get()` to access it.
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Create and run with context
+ * const ctx = Context.create({ user: { id: 'user-1' } });
+ * await Context.run(ctx, async () => {
+ *   const current = Context.get();
+ *   console.log(current.user?.id); // 'user-1'
+ *
+ *   // Context flows to nested calls
+ *   await someAsyncFunction(); // Can access Context.get() inside
+ * });
+ * ```
+ *
+ * @example Parallel execution with child contexts
+ * ```typescript
+ * // Each parallel task gets its own context to avoid races
+ * const [a, b] = await Promise.all([
+ *   Context.fork({ procedurePid: 'task-1' }, () => doTask1()),
+ *   Context.fork({ procedurePid: 'task-2' }, () => doTask2()),
+ * ]);
+ * ```
+ *
+ * @example Emitting events
+ * ```typescript
+ * // Events go to both global bus and operation handle
+ * Context.emit('progress', { percent: 50 }, 'my-tool');
+ * ```
+ *
+ * @see {@link KernelContext} - The context interface
+ * @see {@link context} - Brand an object as context for procedure detection
+ */
+export declare class Context {
+    /**
+     * Creates a new root context with default values.
+     *
+     * @param overrides - Partial context to merge with defaults
+     * @returns A new KernelContext
+     *
+     * @example
+     * ```typescript
+     * const ctx = Context.create({
+     *   user: { id: 'user-1' },
+     *   metadata: { feature: 'chat' }
+     * });
+     * ```
+     */
+    static create(overrides?: Partial<Omit<KernelContext, "events">>): KernelContext;
+    static brand(ctx: Partial<KernelContext>): KernelContext;
+    /**
+     * Runs a function within the given context.
+     * All async operations within `fn` will have access to this context.
+     *
+     * @param context - The context to run within
+     * @param fn - Async function to execute
+     * @returns The result of the function
+     */
+    static run<T>(ctx: Partial<KernelContext>, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Creates a child context that inherits from the current context (or creates a new root).
+     * The child context is a shallow copy - objects like `events`, `procedureGraph`, and `channels`
+     * are shared with the parent (intentionally, for coordination).
+     *
+     * Scalar values like `procedurePid`, `procedureNode`, and `origin` can be safely
+     * overridden in the child without affecting the parent.
+     *
+     * @param overrides - Properties to override in the child context
+     * @returns A new context object inheriting from the current context
+     *
+     * @example
+     * ```typescript
+     * // Create child context with new procedure ID
+     * const childCtx = Context.child({ procedurePid: 'new-pid' });
+     * await Context.run(childCtx, async () => {
+     *   // This context has its own procedurePid but shares events, graph, etc.
+     * });
+     * ```
+     */
+    static child(overrides?: Partial<KernelContext>): KernelContext;
+    /**
+     * Creates a child context and runs a function within it.
+     * Convenience method combining `child()` and `run()`.
+     *
+     * This is the safe way to run parallel procedures - each gets its own
+     * context object so mutations don't race.
+     *
+     * @param overrides - Properties to override in the child context
+     * @param fn - Function to run within the child context
+     * @returns The result of the function
+     *
+     * @example
+     * ```typescript
+     * // Run parallel procedures safely
+     * const [result1, result2] = await Promise.all([
+     *   Context.fork({ procedurePid: 'proc-1' }, async () => doWork1()),
+     *   Context.fork({ procedurePid: 'proc-2' }, async () => doWork2()),
+     * ]);
+     * ```
+     */
+    static fork<T>(overrides: Partial<KernelContext>, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Gets the current context. Throws if not found.
+     */
+    static get(): KernelContext;
+    /**
+     * Gets the current context or returns undefined if not found.
+     */
+    static tryGet(): KernelContext | undefined;
+    /**
+     * Set the current tick number in the context.
+     * Called by the engine at the start of each tick.
+     */
+    static setTick(tick: number): void;
+    /**
+     * Helper to emit an event on the current context.
+     * Events are broadcast to:
+     * 1. The context's local event bus (ctx.events)
+     * 2. The operation handle (ctx.executionHandle) if present
+     * 3. All global subscribers registered via subscribeGlobal()
+     */
+    static emit(type: string, payload: any, source?: string): void;
+    /**
+     * Subscribe to ALL context events globally.
+     * This is useful for observability tools like DevTools that need to see
+     * all procedure:start/end/error events across all contexts.
+     *
+     * @param handler - Callback that receives every event with its context
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = Context.subscribeGlobal((event, ctx) => {
+     *   if (event.type === 'procedure:start') {
+     *     console.log(`Procedure ${event.payload.name} started`);
+     *   }
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    static subscribeGlobal(handler: (event: ExecutionEvent, ctx: KernelContext) => void): () => void;
+    /**
+     * Check if there are any global subscribers.
+     * Useful for conditional event emission to avoid overhead when no one is listening.
+     */
+    static hasGlobalSubscribers(): boolean;
+}
+export declare class ContextProvider {
+    withContext<T>(context: KernelContext, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Symbol used to brand context objects for deterministic detection.
+ * This allows procedures to distinguish context from regular arguments.
+ */
+export declare const KERNEL_CONTEXT_SYMBOL: unique symbol;
+/**
+ * Brand a context object with a Symbol for deterministic detection.
+ * This allows procedures to deterministically identify context vs regular args.
+ *
+ * @example
+ * ```typescript
+ * await proc(input, agent, context({ traceId: "123" }));
+ * ```
+ */
+export declare function context(ctx: Partial<KernelContext>): Partial<KernelContext>;
+/**
+ * Check if an object is a branded context (deterministic check via Symbol).
+ * This is 100% reliable - no heuristics needed.
+ */
+export declare function isKernelContext(obj: any): obj is Partial<KernelContext>;
+//# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

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