@agentick/core 0.0.1 → 0.1.9

package/dist/core/context.d.ts

@@ -1,412 +0,0 @@
-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

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