@agentick/core 0.0.1

package/dist/engine/execution-graph.js

@@ -0,0 +1,257 @@
+import { ExecutionStatuses, ExecutionTypes, } from "./execution-types";
+/**
+ * Execution graph for tracking parent-child relationships
+ */
+export class ExecutionGraph {
+    executions = new Map();
+    executionsForStatus = new Map();
+    executionsByType = new Map();
+    childrenMap = new Map(); // parentPid -> Set<childPid>
+    /**
+     * Register a new execution
+     */
+    register(handle, parentPid) {
+        const context = {
+            pid: handle.pid,
+            parentPid,
+            rootPid: handle.rootPid,
+            type: handle.type,
+            status: handle.status,
+            startedAt: handle.startedAt,
+            completedAt: handle.completedAt,
+            handle,
+        };
+        this.setExecution(handle, context);
+        // Track parent-child relationship
+        if (parentPid) {
+            if (!this.childrenMap.has(parentPid)) {
+                this.childrenMap.set(parentPid, new Set());
+            }
+            this.childrenMap.get(parentPid).add(handle.pid);
+        }
+    }
+    setExecution(handle, context) {
+        this.executions.set(handle.pid, context);
+        for (const status of ExecutionStatuses) {
+            this.executionsForStatus.get(status)?.delete(handle.pid);
+        }
+        this.executionsByType.get(handle.type)?.delete(handle.pid);
+        const statusSet = this.executionsForStatus.get(handle.status) || new Set();
+        statusSet.add(handle.pid);
+        this.executionsForStatus.set(handle.status, statusSet);
+        const typeSet = this.executionsByType.get(handle.type) || new Set();
+        typeSet.add(handle.pid);
+        this.executionsByType.set(handle.type, typeSet);
+    }
+    /**
+     * Update execution status
+     */
+    updateStatus(pid, status, error, phase) {
+        const context = this.executions.get(pid);
+        if (!context) {
+            return;
+        }
+        context.status = status;
+        context.completedAt =
+            status === "completed" || status === "failed" || status === "cancelled"
+                ? new Date()
+                : undefined;
+        if (error) {
+            context.error = {
+                message: error.message,
+                stack: error.stack,
+                phase,
+            };
+        }
+        this.setExecution(context.handle, context);
+    }
+    /**
+     * Get execution context by PID
+     */
+    get(pid) {
+        return this.executions.get(pid);
+    }
+    /**
+     * Get execution handle by PID
+     */
+    getHandle(pid) {
+        return this.executions.get(pid)?.handle;
+    }
+    /**
+     * Get all child executions for a parent
+     */
+    getChildren(parentPid) {
+        const childPids = this.childrenMap.get(parentPid);
+        if (!childPids) {
+            return [];
+        }
+        return Array.from(childPids)
+            .map((pid) => this.getHandle(pid))
+            .filter((handle) => handle !== undefined);
+    }
+    /**
+     * Get outstanding child executions for a parent (not yet completed)
+     */
+    getOutstandingChildren(parentPid) {
+        return this.getChildren(parentPid).filter((handle) => handle.status === "running");
+    }
+    /**
+     * Get orphaned child executions (parent completed but child still running)
+     */
+    getOrphanedChildren() {
+        const orphaned = [];
+        for (const [_pid, context] of this.executions.entries()) {
+            // Skip root executions
+            if (context.type === "root") {
+                continue;
+            }
+            // Check if parent exists and is completed
+            if (context.parentPid) {
+                const parent = this.executions.get(context.parentPid);
+                if (parent &&
+                    (parent.status === "completed" ||
+                        parent.status === "failed" ||
+                        parent.status === "cancelled") &&
+                    context.status === "running") {
+                    orphaned.push(context.handle);
+                }
+            }
+        }
+        return orphaned;
+    }
+    /**
+     * Get execution tree starting from a root PID
+     */
+    getExecutionTree(rootPid) {
+        const root = this.executions.get(rootPid);
+        if (!root) {
+            return undefined;
+        }
+        return this.buildTreeNode(rootPid);
+    }
+    /**
+     * Build a tree node recursively
+     */
+    buildTreeNode(pid) {
+        const context = this.executions.get(pid);
+        if (!context) {
+            throw new Error(`Execution ${pid} not found`);
+        }
+        const children = this.getChildren(pid).map((child) => this.buildTreeNode(child.pid));
+        return {
+            pid: context.pid,
+            parentPid: context.parentPid,
+            rootPid: context.rootPid,
+            type: context.type,
+            status: context.status,
+            startedAt: context.startedAt,
+            completedAt: context.completedAt,
+            children,
+            metrics: this.getMetricsForContext(context),
+        };
+    }
+    /**
+     * Get metrics for an execution context
+     */
+    getMetricsForContext(context) {
+        const duration = context.completedAt
+            ? context.completedAt.getTime() - context.startedAt.getTime()
+            : Date.now() - context.startedAt.getTime();
+        return {
+            pid: context.pid,
+            parentPid: context.parentPid,
+            rootPid: context.rootPid,
+            type: context.type,
+            status: context.status,
+            startedAt: context.startedAt,
+            completedAt: context.completedAt,
+            duration,
+            tickCount: 0, // TODO: Track tick count
+            error: context.error
+                ? {
+                    message: context.error.message,
+                    phase: context.error.phase,
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Get all active (running) executions
+     */
+    getActiveExecutions() {
+        return this.getExecutionsByStatus("running");
+    }
+    /**
+     * Get all executions
+     */
+    getAllExecutions() {
+        return Array.from(this.executions.values()).map((ctx) => ctx.handle);
+    }
+    /**
+     * Get executions by status
+     */
+    getExecutionsByStatus(status) {
+        return Array.from(this.executionsForStatus.get(status) || [])
+            .map((pid) => this.getHandle(pid))
+            .filter((handle) => handle !== undefined);
+    }
+    /**
+     * Get executions by type
+     */
+    getExecutionsByType(type) {
+        return Array.from(this.executionsByType.get(type) || [])
+            .map((pid) => this.getHandle(pid))
+            .filter((handle) => handle !== undefined);
+    }
+    /**
+     * Remove execution from graph (cleanup)
+     */
+    remove(pid) {
+        const context = this.executions.get(pid);
+        if (!context) {
+            return;
+        }
+        // Remove from parent's children
+        if (context.parentPid) {
+            const children = this.childrenMap.get(context.parentPid);
+            if (children) {
+                children.delete(pid);
+                if (children.size === 0) {
+                    this.childrenMap.delete(context.parentPid);
+                }
+            }
+        }
+        // Remove children references
+        this.childrenMap.delete(pid);
+        // Remove execution
+        this.executions.delete(pid);
+        for (const status of ExecutionStatuses) {
+            this.executionsForStatus.get(status)?.delete(pid);
+        }
+        for (const type of ExecutionTypes) {
+            this.executionsByType.get(type)?.delete(pid);
+        }
+    }
+    /**
+     * Clear all executions
+     */
+    clear() {
+        this.executions.clear();
+        this.executionsForStatus.clear();
+        this.executionsByType.clear();
+        this.childrenMap.clear();
+    }
+    /**
+     * Get count of executions
+     */
+    getCount() {
+        return this.executions.size;
+    }
+    /**
+     * Get count of active executions
+     */
+    getActiveCount() {
+        return this.executionsForStatus.get("running")?.size || 0;
+    }
+}
+//# sourceMappingURL=execution-graph.js.map

package/dist/engine/execution-graph.js.map

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

package/dist/engine/execution-handle.d.ts

@@ -0,0 +1,212 @@
+import { type ExecutionHandle, type ExecutionMessage, type ExecutionStatus, type ExecutionType, type ExecutionMetrics, type ExecutionState, type SignalType } from "./execution-types";
+import type { COMInput } from "../com/types";
+import type { StreamEvent } from "./engine-events";
+import { EventEmitter } from "node:events";
+import type { ProcedureGraph, ProcedureNode } from "@agentick/kernel";
+import { EventBuffer, ExecutionHandleBrand, type ExecutionHandle as KernelExecutionHandle } from "@agentick/kernel";
+import type { COM } from "../com/object-model";
+/**
+ * Concrete implementation of ExecutionHandle
+ * Also implements Kernel's ExecutionHandle<TOutput> for Procedure compatibility
+ */
+export declare class ExecutionHandleImpl extends EventEmitter implements ExecutionHandle, KernelExecutionHandle<COMInput> {
+    readonly [ExecutionHandleBrand]: true;
+    readonly pid: string;
+    readonly parentPid?: string;
+    readonly rootPid: string;
+    readonly type: ExecutionType;
+    status: ExecutionStatus;
+    readonly startedAt: Date;
+    completedAt?: Date;
+    readonly result: Promise<COMInput>;
+    /**
+     * Event buffer for streaming execution events.
+     * Supports dual consumption - multiple iterators can independently consume all events.
+     * This is also exposed as `events` for Kernel ExecutionHandle compatibility.
+     */
+    readonly eventBuffer: EventBuffer<StreamEvent>;
+    readonly events: EventBuffer<StreamEvent>;
+    traceId: string;
+    private resultValue?;
+    private error?;
+    private cancelController?;
+    private completionPromise;
+    private completionResolve?;
+    private completionReject?;
+    private comInstance?;
+    private streamIterator?;
+    private tickCount;
+    private session?;
+    private shutdownHooks;
+    private parentHandle?;
+    private procedureGraph?;
+    private _abortEmitted;
+    private _listenersSetup;
+    constructor(pid: string, rootPid: string, type: ExecutionType, parentPid?: string, parentHandle?: ExecutionHandle);
+    /**
+     * Link the Kernel's result promise to this handle.
+     * When the promise resolves, calls complete(). When it rejects, calls fail().
+     * This connects the Kernel's procedure execution to the Engine's handle lifecycle.
+     */
+    linkKernelResult(kernelResultPromise: Promise<COMInput>): void;
+    /**
+     * Monitor parent status (child executions only)
+     * When parent fails or is cancelled AFTER child is created, abort child.
+     *
+     * Note: If parent completes successfully, child continues running independently.
+     * If parent is already completed/failed when child is created, the child runs independently.
+     */
+    private setupParentStatusMonitor;
+    /**
+     * Set the stream iterator for this execution
+     */
+    setStreamIterator(iterator: AsyncIterable<StreamEvent>): void;
+    /**
+     * Set the cancel controller
+     */
+    setCancelController(controller: AbortController): void;
+    /**
+     * Get the cancel signal (if cancel controller is set)
+     */
+    getCancelSignal(): AbortSignal | undefined;
+    /**
+     * Increment tick count
+     */
+    incrementTick(): void;
+    /**
+     * Mark execution as completed
+     */
+    complete(result: COMInput): void;
+    /**
+     * Mark execution as failed
+     */
+    fail(error: Error): void;
+    /**
+     * Wait for execution to complete
+     */
+    waitForCompletion(options?: {
+        timeout?: number;
+    }): Promise<COMInput>;
+    /**
+     * Cancel the execution (triggers abort signal)
+     */
+    cancel(reason?: string): void;
+    /**
+     * Emit signal for this execution
+     */
+    emitSignal(signal: SignalType, reason?: string, metadata?: Record<string, any>): void;
+    /**
+     * Mark that abort listeners have been set up in iterateTicks.
+     * Called by iterateTicks after setting up listeners to prevent false positives.
+     * Once listeners are set up, future emitSignal('abort') calls won't set _abortEmitted,
+     * and wasAbortEmitted() will return false (since it checks !_listenersSetup).
+     */
+    markListenersSetup(): void;
+    /**
+     * Check if abort signal was already emitted (before listeners were set up)
+     * Used by iterateTicks to detect early abort signals
+     *
+     * Note: Only checks if THIS execution emitted an abort via emitSignal('abort'),
+     * not if the signal is aborted (which could be from a parent signal in forks).
+     * Signal aborted state is checked separately in iterateTicks via ctx.signal.aborted.
+     *
+     * This should only be checked ONCE at the start of iterateTicks, before listeners are set up.
+     */
+    wasAbortEmitted(): boolean;
+    /**
+     * Register graceful shutdown hook for this execution
+     */
+    onShutdown(handler: () => Promise<void> | void): () => void;
+    /**
+     * Run shutdown hooks (called before aborting)
+     */
+    runShutdownHooks(): Promise<void>;
+    /**
+     * Get execution result
+     */
+    getResult(): COMInput | undefined;
+    /**
+     * PromiseLike implementation - allows `await handle` to resolve to COMInput
+     */
+    then<TResult1 = COMInput, TResult2 = never>(onfulfilled?: ((value: COMInput) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Catch handler for errors - same as `.then(undefined, onrejected)`
+     */
+    catch<TResult2 = never>(onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<COMInput | TResult2>;
+    /**
+     * AsyncIterable implementation - allows `for await (const event of handle)`
+     * Delegates to the stream iterator if available.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
+    /**
+     * Abort the execution (alias for cancel)
+     * This is the Kernel ExecutionHandle interface method.
+     */
+    abort(reason?: string): void;
+    /**
+     * Kernel ExecutionHandle<TOutput> compatibility
+     * Maps status to Kernel's status type
+     */
+    getStatus(): "running" | "completed" | "failed" | "cancelled";
+    /**
+     * Stream execution events
+     */
+    stream(): AsyncIterable<StreamEvent>;
+    /**
+     * Get execution metrics
+     */
+    getMetrics(): ExecutionMetrics;
+    /**
+     * Get execution duration
+     */
+    getDuration(): number;
+    /**
+     * Create execution state for persistence
+     */
+    toState(component: any, input: any, currentTick: number, previous?: COMInput): ExecutionState;
+    /**
+     * Set procedure graph for this execution
+     * Called by Engine when execution starts to link execution to its procedure graph
+     */
+    setProcedureGraph(graph: ProcedureGraph): void;
+    /**
+     * Get procedure graph for this execution
+     * Returns undefined if no procedures were executed in this execution's context
+     */
+    getProcedureGraph(): ProcedureGraph | undefined;
+    /**
+     * Get aggregated metrics from all procedures in this execution
+     * Includes both execution-level metrics and procedure-level metrics
+     */
+    getProcedureMetrics(): Record<string, number>;
+    /**
+     * Get procedure nodes for this execution
+     */
+    getProcedureNodes(): ProcedureNode[];
+    /**
+     * Get root procedure node (if any procedures were executed)
+     */
+    getRootProcedureNode(): ProcedureNode | undefined;
+    setComInstance(ctx: COM): void;
+    /**
+     * Set the compile session for message sending.
+     * Called by Engine when execution starts.
+     */
+    setSession(session: {
+        queue: {
+            exec: (message: Omit<ExecutionMessage, "id" | "timestamp">) => Promise<void>;
+        };
+    }): void;
+    /**
+     * Send a message to the running execution.
+     *
+     * The message is delivered immediately to component onMessage hooks,
+     * then queued for availability in TickState.queuedMessages.
+     *
+     * @param message The message to send (id and timestamp are auto-generated)
+     * @throws Error if execution is not running or no active session
+     */
+    send(message: Omit<ExecutionMessage, "id" | "timestamp">): Promise<void>;
+    getComInstance(): COM | undefined;
+}
+//# sourceMappingURL=execution-handle.d.ts.map

package/dist/engine/execution-handle.d.ts.map

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