@agentick/core 0.0.1

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

@@ -0,0 +1,248 @@
+import type { EventEmitter } from "node:events";
+import type { EngineInput, COMInput } from "../com/types";
+import type { ComponentDefinition } from "../component/component";
+import type { ProcedureGraph } from "@agentick/kernel";
+/**
+ * Signal types for execution and engine signals
+ */
+export type SignalType = "abort" | "interrupt" | "pause" | "resume" | "shutdown" | string;
+/**
+ * Signal event structure
+ */
+export interface SignalEvent {
+    type: SignalType;
+    source: "engine" | "execution" | "parent" | "external";
+    pid?: string;
+    parentPid?: string;
+    reason?: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Execution message for communication with running executions.
+ *
+ * Messages can be sent to a running execution via:
+ * - RuntimeSession.sendMessage() - Direct programmatic injection
+ * - ExecutionHandle.send() - Via handle reference
+ * - Channel events with type='message' - From client
+ *
+ * Messages are delivered immediately to component onMessage hooks,
+ * then queued for availability in TickState.queuedMessages.
+ */
+export interface ExecutionMessage {
+    /**
+     * Unique message ID (auto-generated if not provided)
+     */
+    id: string;
+    /**
+     * User-defined message type (e.g., 'user_feedback', 'interrupt', 'tool_response')
+     */
+    type: string;
+    /**
+     * Message payload
+     */
+    content: unknown;
+    /**
+     * When the message was received (auto-generated)
+     */
+    timestamp: number;
+    /**
+     * Optional metadata (source, channel, etc.)
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Execution status
+ */
+export type ExecutionStatus = "running" | "completed" | "failed" | "cancelled" | "pending";
+export declare const ExecutionStatuses: ExecutionStatus[];
+/**
+ * Execution type
+ */
+export type ExecutionType = "root" | "child";
+export declare const ExecutionTypes: ExecutionType[];
+/**
+ * Execution state for persistence and recovery
+ */
+export interface ExecutionState {
+    pid: string;
+    parentPid?: string;
+    rootPid: string;
+    type: ExecutionType;
+    status: ExecutionStatus;
+    input: EngineInput;
+    component: ComponentDefinition;
+    currentTick: number;
+    previous?: COMInput;
+    startedAt: Date;
+    completedAt?: Date;
+    error?: {
+        message: string;
+        stack?: string;
+        phase?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Execution handle for managing an execution lifecycle
+ * Extends EventEmitter for signal handling
+ */
+export interface ExecutionHandle extends EventEmitter {
+    /**
+     * Process ID (unique identifier for this execution)
+     */
+    pid: string;
+    /**
+     * Parent process ID (if this is a child execution)
+     */
+    parentPid?: string;
+    /**
+     * Root process ID (top-level execution)
+     */
+    rootPid: string;
+    /**
+     * Execution status
+     */
+    status: ExecutionStatus;
+    /**
+     * Execution type
+     */
+    type: ExecutionType;
+    /**
+     * When execution started
+     */
+    startedAt: Date;
+    /**
+     * When execution completed (if completed)
+     */
+    completedAt?: Date;
+    /**
+     * Wait for execution to complete
+     */
+    waitForCompletion(options?: {
+        timeout?: number;
+    }): Promise<COMInput>;
+    /**
+     * Cancel the execution (triggers abort signal)
+     */
+    cancel(reason?: string): void;
+    /**
+     * Get execution result (if completed)
+     */
+    getResult(): COMInput | undefined;
+    /**
+     * Stream execution events
+     */
+    stream(): AsyncIterable<any>;
+    /**
+     * Get execution metrics
+     */
+    getMetrics(): ExecutionMetrics;
+    /**
+     * Get execution duration in milliseconds
+     */
+    getDuration(): number;
+    /**
+     * Get the cancel signal (if cancel controller is set)
+     */
+    getCancelSignal(): AbortSignal | undefined;
+    /**
+     * Get procedure graph for this execution (if procedures were executed)
+     * 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>;
+    /**
+     * Emit signal for this execution (and its children)
+     */
+    emitSignal(signal: SignalType, reason?: string, metadata?: Record<string, any>): void;
+    /**
+     * Register graceful shutdown hook for this execution
+     */
+    onShutdown(handler: () => Promise<void> | 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>;
+}
+/**
+ * Execution metrics
+ */
+export interface ExecutionMetrics {
+    pid: string;
+    parentPid?: string;
+    rootPid: string;
+    type: ExecutionType;
+    status: ExecutionStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    duration: number;
+    tickCount: number;
+    error?: {
+        message: string;
+        phase?: string;
+    };
+}
+/**
+ * Execution tree node
+ */
+export interface ExecutionTreeNode {
+    pid: string;
+    parentPid?: string;
+    rootPid: string;
+    type: ExecutionType;
+    status: ExecutionStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    children: ExecutionTreeNode[];
+    metrics: ExecutionMetrics;
+}
+/**
+ * Engine metrics
+ */
+export interface EngineMetrics {
+    /**
+     * Number of active executions
+     */
+    activeExecutions: number;
+    /**
+     * Total number of executions (including completed)
+     */
+    totalExecutions: number;
+    /**
+     * Executions by status
+     */
+    executionsByStatus: Record<ExecutionStatus, number>;
+    /**
+     * Executions by type
+     */
+    executionsByType: Record<ExecutionType, number>;
+    /**
+     * Average execution duration (ms)
+     */
+    averageExecutionTime: number;
+    /**
+     * Memory usage
+     */
+    memoryUsage: NodeJS.MemoryUsage;
+    /**
+     * Timestamp of metrics collection
+     */
+    timestamp: Date;
+}
+/**
+ * Generate a unique process ID (execution identifier)
+ * @param _prefix - Deprecated, ignored. Kept for backwards compatibility.
+ */
+export declare function generatePid(_prefix?: string): string;
+//# sourceMappingURL=execution-types.d.ts.map

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

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

package/dist/engine/execution-types.js

@@ -0,0 +1,23 @@
+import { randomUUID } from "crypto";
+export const ExecutionStatuses = [
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+    "pending",
+];
+export const ExecutionTypes = ["root", "child"];
+/**
+ * Generate a unique process ID (execution identifier)
+ * @param _prefix - Deprecated, ignored. Kept for backwards compatibility.
+ */
+export function generatePid(_prefix) {
+    try {
+        return randomUUID();
+    }
+    catch {
+        // Fallback if crypto.randomUUID is not available
+        return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+    }
+}
+//# sourceMappingURL=execution-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execution-types.js","sourceRoot":"","sources":["../../src/engine/execution-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAwEpC,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,SAAS;IACT,WAAW;IACX,QAAQ;IACR,WAAW;IACX,SAAS;CACV,CAAC;AAMF,MAAM,CAAC,MAAM,cAAc,GAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAgNjE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,IAAI,CAAC;QACH,OAAO,UAAU,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;QACjD,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,CAAC;AACH,CAAC"}

package/dist/engine/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Engine Types and Utilities
+ *
+ * This module exports the essential types for execution:
+ * - ExecutionHandle - The handle returned by session.render()
+ * - ExecutionMessage, ExecutionHandle - Core execution types
+ * - StreamEvent - Event types for streaming
+ * - ToolExecutor - Tool execution utilities
+ *
+ * Note: The Engine class has been replaced by SessionImpl.
+ * Use createApp() and session.render() for execution.
+ *
+ * @module agentick/engine
+ */
+export * from "./execution-handle";
+export * from "./execution-types";
+export { StopReason, isModelStreamEvent, isOrchestrationStreamEvent, isDeltaEvent, isFinalEvent, generateEventId, createEventBase, createExecutionStartEvent, createExecutionEndEvent, createTickStartEvent, createTickEndEvent, createToolCallEvent, createToolResultEvent, createToolConfirmationRequiredEvent, createToolConfirmationResultEvent, createEngineErrorEvent, } from "./engine-events";
+export type { StreamEventBase, ModelStreamEvent, OrchestrationStreamEvent, ResultStreamEvent, CompiledEvent, ModelRequestEvent, ModelResponseEvent, StreamEvent, } from "./engine-events";
+export type { EngineResponse, COMSection, COMTimelineEntry } from "./engine-response";
+export { ToolExecutor } from "./tool-executor";
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,cAAc,oBAAoB,CAAC;AAGnC,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,eAAe,EACf,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,mCAAmC,EACnC,iCAAiC,EACjC,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGtF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/engine/index.js

@@ -0,0 +1,23 @@
+/**
+ * Engine Types and Utilities
+ *
+ * This module exports the essential types for execution:
+ * - ExecutionHandle - The handle returned by session.render()
+ * - ExecutionMessage, ExecutionHandle - Core execution types
+ * - StreamEvent - Event types for streaming
+ * - ToolExecutor - Tool execution utilities
+ *
+ * Note: The Engine class has been replaced by SessionImpl.
+ * Use createApp() and session.render() for execution.
+ *
+ * @module agentick/engine
+ */
+// Execution Handle
+export * from "./execution-handle";
+// Execution Types
+export * from "./execution-types";
+// Events
+export { StopReason, isModelStreamEvent, isOrchestrationStreamEvent, isDeltaEvent, isFinalEvent, generateEventId, createEventBase, createExecutionStartEvent, createExecutionEndEvent, createTickStartEvent, createTickEndEvent, createToolCallEvent, createToolResultEvent, createToolConfirmationRequiredEvent, createToolConfirmationResultEvent, createEngineErrorEvent, } from "./engine-events";
+// Tool Executor
+export { ToolExecutor } from "./tool-executor";
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,mBAAmB;AACnB,cAAc,oBAAoB,CAAC;AAEnC,kBAAkB;AAClB,cAAc,mBAAmB,CAAC;AAElC,SAAS;AACT,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,eAAe,EACf,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,mCAAmC,EACnC,iCAAiC,EACjC,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAezB,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/engine/tool-confirmation-coordinator.d.ts

@@ -0,0 +1,74 @@
+import type { ToolConfirmationResult } from "../tool/tool";
+/**
+ * ToolConfirmationCoordinator - Manages tool confirmation requests
+ *
+ * Handles waiting for user confirmation before executing tools that have
+ * requiresConfirmation enabled. Similar pattern to ClientToolCoordinator
+ * but for confirmation flow instead of tool results.
+ *
+ * Flow:
+ * 1. ToolExecutor checks if tool requiresConfirmation
+ * 2. If true, calls waitForConfirmation() which blocks
+ * 3. Engine yields 'tool_confirmation_required' event to client
+ * 4. Client shows confirmation UI to user
+ * 5. User confirms/denies (with optional "always" flag)
+ * 6. Client sends confirmation via /api/channels/tool-confirmation
+ * 7. Server calls resolveConfirmation() which unblocks the promise
+ * 8. ToolExecutor proceeds or skips based on confirmation
+ */
+export declare class ToolConfirmationCoordinator {
+    private pendingConfirmations;
+    /**
+     * Wait for user confirmation for a tool call.
+     * Returns a promise that resolves when user confirms/denies.
+     *
+     * Note: No timeout by default - waits indefinitely for user response.
+     * The tool is simply not executed if no confirmation is received.
+     *
+     * @param toolUseId - ID of the tool call awaiting confirmation
+     * @param toolName - Name of the tool (for result)
+     * @returns Promise that resolves with confirmation result
+     */
+    waitForConfirmation(toolUseId: string, _toolName: string): Promise<ToolConfirmationResult>;
+    /**
+     * Check if there's a pending confirmation for a tool call.
+     *
+     * @param toolUseId - ID of the tool call
+     * @returns true if confirmation is pending
+     */
+    hasPendingConfirmation(toolUseId: string): boolean;
+    /**
+     * Resolve a pending confirmation with user's response.
+     * Called when client sends confirmation via /api/channels/tool-confirmation.
+     *
+     * @param toolUseId - ID of the tool call
+     * @param confirmed - Whether user confirmed the execution
+     * @param always - Whether to remember this decision
+     * @returns The confirmation result, or null if no pending confirmation found
+     */
+    resolveConfirmation(toolUseId: string, confirmed: boolean, always?: boolean): ToolConfirmationResult | null;
+    /**
+     * Resolve a pending confirmation with full result (including tool name).
+     * Used internally when we have all the context.
+     *
+     * @param result - Full confirmation result
+     * @returns true if resolved, false if no pending confirmation found
+     */
+    resolveConfirmationWithResult(result: ToolConfirmationResult): boolean;
+    /**
+     * Cancel a pending confirmation (e.g., execution cancelled).
+     *
+     * @param toolUseId - ID of the tool call to cancel
+     */
+    cancelConfirmation(toolUseId: string): void;
+    /**
+     * Cancel all pending confirmations (e.g., engine shutdown).
+     */
+    cancelAll(): void;
+    /**
+     * Get the number of pending confirmations.
+     * Useful for debugging and testing.
+     */
+    getPendingCount(): number;
+}
+//# sourceMappingURL=tool-confirmation-coordinator.d.ts.map

package/dist/engine/tool-confirmation-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-confirmation-coordinator.d.ts","sourceRoot":"","sources":["../../src/engine/tool-confirmation-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAkB3D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,oBAAoB,CAAuD;IAEnF;;;;;;;;;;OAUG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAahG;;;;;OAKG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIlD;;;;;;;;OAQG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,EAClB,MAAM,GAAE,OAAe,GACtB,sBAAsB,GAAG,IAAI;IAqBhC;;;;;;OAMG;IACH,6BAA6B,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO;IAWtE;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQ3C;;OAEG;IACH,SAAS,IAAI,IAAI;IAOjB;;;OAGG;IACH,eAAe,IAAI,MAAM;CAG1B"}

package/dist/engine/tool-confirmation-coordinator.js

@@ -0,0 +1,137 @@
+/**
+ * Deferred promise pattern for async coordination
+ */
+class Deferred {
+    promise;
+    resolve;
+    reject;
+    constructor() {
+        this.promise = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+    }
+}
+/**
+ * ToolConfirmationCoordinator - Manages tool confirmation requests
+ *
+ * Handles waiting for user confirmation before executing tools that have
+ * requiresConfirmation enabled. Similar pattern to ClientToolCoordinator
+ * but for confirmation flow instead of tool results.
+ *
+ * Flow:
+ * 1. ToolExecutor checks if tool requiresConfirmation
+ * 2. If true, calls waitForConfirmation() which blocks
+ * 3. Engine yields 'tool_confirmation_required' event to client
+ * 4. Client shows confirmation UI to user
+ * 5. User confirms/denies (with optional "always" flag)
+ * 6. Client sends confirmation via /api/channels/tool-confirmation
+ * 7. Server calls resolveConfirmation() which unblocks the promise
+ * 8. ToolExecutor proceeds or skips based on confirmation
+ */
+export class ToolConfirmationCoordinator {
+    pendingConfirmations = new Map();
+    /**
+     * Wait for user confirmation for a tool call.
+     * Returns a promise that resolves when user confirms/denies.
+     *
+     * Note: No timeout by default - waits indefinitely for user response.
+     * The tool is simply not executed if no confirmation is received.
+     *
+     * @param toolUseId - ID of the tool call awaiting confirmation
+     * @param toolName - Name of the tool (for result)
+     * @returns Promise that resolves with confirmation result
+     */
+    async waitForConfirmation(toolUseId, _toolName) {
+        // Create deferred promise for this confirmation
+        const deferred = new Deferred();
+        this.pendingConfirmations.set(toolUseId, deferred);
+        try {
+            return await deferred.promise;
+        }
+        finally {
+            // Cleanup (in case of cancellation)
+            this.pendingConfirmations.delete(toolUseId);
+        }
+    }
+    /**
+     * Check if there's a pending confirmation for a tool call.
+     *
+     * @param toolUseId - ID of the tool call
+     * @returns true if confirmation is pending
+     */
+    hasPendingConfirmation(toolUseId) {
+        return this.pendingConfirmations.has(toolUseId);
+    }
+    /**
+     * Resolve a pending confirmation with user's response.
+     * Called when client sends confirmation via /api/channels/tool-confirmation.
+     *
+     * @param toolUseId - ID of the tool call
+     * @param confirmed - Whether user confirmed the execution
+     * @param always - Whether to remember this decision
+     * @returns The confirmation result, or null if no pending confirmation found
+     */
+    resolveConfirmation(toolUseId, confirmed, always = false) {
+        const pending = this.pendingConfirmations.get(toolUseId);
+        if (!pending) {
+            return null;
+        }
+        // Build result
+        const result = {
+            toolUseId,
+            toolName: "", // Will be filled by caller who has access to tool metadata
+            confirmed,
+            always,
+        };
+        // Resolve the promise
+        this.pendingConfirmations.delete(toolUseId);
+        pending.resolve(result);
+        return result;
+    }
+    /**
+     * Resolve a pending confirmation with full result (including tool name).
+     * Used internally when we have all the context.
+     *
+     * @param result - Full confirmation result
+     * @returns true if resolved, false if no pending confirmation found
+     */
+    resolveConfirmationWithResult(result) {
+        const pending = this.pendingConfirmations.get(result.toolUseId);
+        if (!pending) {
+            return false;
+        }
+        this.pendingConfirmations.delete(result.toolUseId);
+        pending.resolve(result);
+        return true;
+    }
+    /**
+     * Cancel a pending confirmation (e.g., execution cancelled).
+     *
+     * @param toolUseId - ID of the tool call to cancel
+     */
+    cancelConfirmation(toolUseId) {
+        const deferred = this.pendingConfirmations.get(toolUseId);
+        if (deferred) {
+            this.pendingConfirmations.delete(toolUseId);
+            deferred.reject(new Error(`Tool confirmation cancelled: ${toolUseId}`));
+        }
+    }
+    /**
+     * Cancel all pending confirmations (e.g., engine shutdown).
+     */
+    cancelAll() {
+        for (const [toolUseId, deferred] of this.pendingConfirmations.entries()) {
+            deferred.reject(new Error(`Tool confirmation cancelled: ${toolUseId}`));
+        }
+        this.pendingConfirmations.clear();
+    }
+    /**
+     * Get the number of pending confirmations.
+     * Useful for debugging and testing.
+     */
+    getPendingCount() {
+        return this.pendingConfirmations.size;
+    }
+}
+//# sourceMappingURL=tool-confirmation-coordinator.js.map

package/dist/engine/tool-confirmation-coordinator.js.map

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