@makaio/framework 1.0.0-dev-1781023871421 → 1.0.0-dev-1781081952714

package/dist/package-BSnp1zOR.d.mts

@@ -0,0 +1,372 @@
+import { IMakaioBus } from "@makaio/framework/bus";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+import { ExtensionContext, IWorkflowRunner, IWorkflowTriggerTypeRegistry, MakaioNodeExtension, StationHandler, StepRunnerBusAuth, StepRunnerPlatformDefaults, WorkflowDefinition } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+import { MakaioDatabase } from "@makaio/framework/storage/drizzle";
+
+//#region subsystems/workflow-engine/src/storage/handler.d.ts
+/**
+ * Registers all Drizzle-based workflow storage handlers with the bus.
+ *
+ * Handles:
+ * - Definition CRUD: get, set, delete, list
+ * - Execution CRUD: getExecution, setExecution, updateExecution, listExecutions
+ * - Frame CRUD: setFrame, getFrame, listFrames
+ * - Gate instance CRUD: setGateInstance, getGateInstance, listGateInstances
+ * - Span CRUD: setSpan, listSpans
+ * - Execution link CRUD: setExecutionLink, listExecutionLinks
+ * - Run context CRUD: setRunContext, getRunContext
+ * - WorkLog projection: worklog.get, worklog.list, worklog.changed (event-driven)
+ * @param bus - MakaioBus instance for message handling
+ * @param db - Drizzle database instance
+ * @param _ctx - Extension context (unused; reserved for future use)
+ * @returns Cleanup function to unregister all handlers
+ */
+declare function registerDrizzleWorkflowStorage(bus: IMakaioBus, db: MakaioDatabase, _ctx: ExtensionContext): () => void;
+//#endregion
+//#region subsystems/workflow-engine/src/types.d.ts
+/**
+ * Configuration for the workflow executor.
+ */
+interface ExecutorConfig {
+  /** Timeout for individual step execution in ms. */
+  stepTimeoutMs: number;
+  /** Cooldown between steps in ms. */
+  stepCooldownMs: number;
+  /** Bus server WebSocket URL for runner worker connections. */
+  busUrl?: string;
+  /** Bus authentication strategy for runner worker connections. */
+  busAuth: StepRunnerBusAuth;
+  /** Platform-level defaults (cwd, env) for runner process creation. */
+  platformDefaults: StepRunnerPlatformDefaults;
+  /** Grace period in ms before forceKill is issued after cooperative abort. */
+  cancelTimeoutMs: number;
+  /**
+   * Absolute path to the Makaio data-home directory.
+   *
+   * Forwarded to workflow workers as `context.makaioHome` so workers can
+   * locate stored config, keys, and installed extensions. When omitted the
+   * executor derives a default from the `MAKAIO_HOME` environment variable
+   * or `~/.makaio`.
+   */
+  makaioHome?: string;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/workflow-executor.d.ts
+/**
+ * Core workflow executor service.
+ *
+ * Orchestrates workflow execution lifecycle:
+ * - Creates coordinator session for each execution
+ * - Executes steps via the mutable DAG scheduler
+ * - Spawns subagents for each step
+ * - Tracks progress and emits lifecycle events
+ * - Manages cancellation and cleanup
+ */
+declare class WorkflowExecutor extends BaseService {
+  /** Drizzle storage handler registration for the composition root. */
+  static readonly storage: {
+    readonly drizzle: typeof registerDrizzleWorkflowStorage;
+  };
+  private readonly config;
+  private readonly activeExecutions;
+  private readonly executionTasks;
+  private readonly shellAbortControllers;
+  private readonly activeRunnerSteps;
+  private readonly gateTimeoutScheduler;
+  private readonly resumeDispatches;
+  /**
+   * Per-execution abort controllers used to cancel workflow-level runners.
+   * Keyed by execution ID; only populated when a {@link IWorkflowRunner} is used.
+   */
+  private readonly workflowAbortControllers;
+  private readonly workflowRunner?;
+  private triggerTypeRegistry?;
+  /**
+   * Create a new workflow executor.
+   * @param bus - The message bus for communication
+   * @param config - Optional partial configuration (merged with defaults)
+   * @param workflowRunner - Optional workflow-level runner for isolated execution
+   */
+  constructor(bus: IMakaioBus, config?: Partial<ExecutorConfig>, workflowRunner?: IWorkflowRunner);
+  /**
+   * Set the trigger type registry for listTriggerTypes support.
+   * @param registry - Trigger type registry instance
+   */
+  setTriggerTypeRegistry(registry: IWorkflowTriggerTypeRegistry): void;
+  /**
+   * Retrieve the registry set via {@link setTriggerTypeRegistry}.
+   *
+   * The composition root calls this after boot to wire
+   * `setWorkflowTriggerTypeRegistry` from `@makaio/kernel-core`.
+   * @returns The trigger type registry, or `undefined` if not yet set.
+   */
+  getTriggerTypeRegistry(): IWorkflowTriggerTypeRegistry | undefined;
+  /**
+   * Register all bus handlers via BaseService lifecycle.
+   * Called once by `init()` — idempotency is handled by BaseService.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Release in-flight executions and abort shell processes.
+   * Called by `destroy()` before handler unsubscription.
+   */
+  protected onDestroy(): Promise<void>;
+  /**
+   * Build a {@link FinalizerDeps} bundle from current instance state.
+   *
+   * Extracted to avoid duplicating the same field enumeration across the cancel
+   * handler, the shutdown path, and the runner rejection catch path.
+   * @returns Finalizer dependency bundle.
+   */
+  private buildFinalizerDeps;
+  /**
+   * Build a {@link RunnerTaskDeps} bundle for delegating to
+   * {@link buildExecutionTask} or {@link buildFileExecutionTask}.
+   * @param workflowRunner - The runner instance to use (always defined at these call sites).
+   * @returns Runner task dependency bundle.
+   */
+  private buildRunnerTaskDeps;
+  /**
+   * Resolve the workspace root inherited from a parent session.
+   *
+   * Coordinator sessions are created with this target working directory so
+   * in-process shell steps and workflow-level workers share the same workspace.
+   * @param parentSessionId - Optional parent session identifier.
+   * @returns Parent session working directory, or the executor default cwd.
+   */
+  private resolveExecutionWorkspaceRoot;
+  /**
+   * Build the {@link StartExecutionDeps} bundle used by {@link startExecution}
+   * and {@link startFileExecution}.
+   * @returns Start execution dependency bundle.
+   */
+  private buildStartDeps;
+  /** Register execution control handlers (start, cancel). */
+  private registerExecutionHandlers;
+  /** Register timeout wakeup handlers for parked gates. */
+  private registerGateTimeoutHandlers;
+  /**
+   * Rebuild timeout wakeups for exit-based gates left waiting across executor restarts.
+   *
+   * Gate rows persist the effective timeout policy captured when the reviewer
+   * prompt opened, so rehydration does not depend on the current workflow
+   * definition or a definition snapshot being available. Expired deadlines are
+   * scheduled with zero delay and redispatched by the same persisted-gate
+   * timeout path used for live suspensions.
+   */
+  private rehydratePausedGateTimeouts;
+  /**
+   * Main execution loop — drives the primitive runtime over the workflow's
+   * root sequence node.
+   *
+   * Creates a per-execution `RuntimeContext` and `AbortController`, then
+   * delegates to {@link executeSequence} to walk the node tree. The abort
+   * controller is registered in `workflowAbortControllers` so the cancel
+   * handler can interrupt a running execution.
+   * @param executionId - The execution ID.
+   */
+  private runExecution;
+  /**
+   * Accept a gate response for an execution that is paused in storage.
+   *
+   * Checks that the execution is paused, the response targets a waiting gate
+   * frame directly or by a unique gate node, and the submitted resume data
+   * matches the persisted gate schema. On a valid response, updates the gate
+   * instance to its resolved state and triggers a resume dispatch via
+   * {@link resumePausedExecution}.
+   *
+   * Returns `false` without modifying state when the execution is not paused
+   * or the gate response is ambiguous or invalid, allowing the bus to continue
+   * to the next handler.
+   * @param payload - Gate response payload from the bus request context.
+   * @returns `true` when the gate was accepted and resume dispatched; `false` otherwise.
+   */
+  private respondToPausedGate;
+  /**
+   * Transition a paused execution back to running and re-dispatch it through
+   * the configured runner infrastructure.
+   * @param executionId - Execution to resume.
+   */
+  private resumePausedExecution;
+  /**
+   * Dispatch a paused execution once durable resume state is available.
+   * @param executionId - Execution to resume.
+   * @returns True when a runner task was launched.
+   */
+  private dispatchPausedExecutionResume;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/cron-trigger-evaluator.d.ts
+/**
+ * Schedules and fires cron triggers for workflows on `'main-dev-machine'` role machines.
+ *
+ * On `init`, loads all workflow definitions with `cron` triggers and schedules
+ * them via croner. Subscribes to workflow CRUD events to keep the schedule
+ * index live.
+ *
+ * Each cron trigger fires `WorkflowSubjects.start` with the workflow ID and
+ * a `triggerPayload` containing the scheduled fire time.
+ *
+ * ## Role partitioning
+ *
+ * Only machines with role `'main-dev-machine'` should run this evaluator.
+ * Server-role machines rely on the relay-side `CronEvaluator` for routing.
+ * @example
+ * ```typescript
+ * if (machineRole === 'main-dev-machine') {
+ *   const evaluator = new CronTriggerEvaluator(bus);
+ *   await evaluator.init();
+ *   // ...on shutdown:
+ *   evaluator.destroy();
+ * }
+ * ```
+ */
+declare class CronTriggerEvaluator {
+  private readonly bus;
+  private readonly cleanupFns;
+  private initialized;
+  /**
+   * Active cron jobs keyed by `{workflowId}:{triggerIndex}`.
+   */
+  private readonly jobs;
+  /**
+   * @param bus - The shared bus instance
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Initialize the evaluator.
+   *
+   * Idempotent: calling `init()` on an already-initialized evaluator is a no-op.
+   */
+  init(): Promise<void>;
+  /**
+   * Destroy the evaluator, stopping all cron jobs and removing all subscriptions.
+   *
+   * Idempotent: calling `destroy()` on a non-initialized evaluator is a no-op.
+   */
+  destroy(): void;
+  activeJobCount(): number;
+  /**
+   * Load all existing workflow definitions and schedule their cron triggers.
+   */
+  private loadExistingTriggers;
+  /**
+   * Schedule all `cron` triggers found in a workflow definition.
+   * @param workflow - Workflow definition to schedule
+   */
+  private scheduleWorkflow;
+  /**
+   * Stop and remove all cron jobs for a given workflow.
+   * @param workflowId - Workflow identifier to unschedule
+   */
+  private unscheduleWorkflow;
+  /**
+   * Stop and remove a single cron job by key.
+   * @param key - Job key (`{workflowId}:{triggerIndex}`)
+   */
+  private stopJob;
+  /**
+   * Stop all active cron jobs and clear the jobs map.
+   */
+  private stopAllJobs;
+  /**
+   * Fire a cron trigger by requesting workflow start.
+   *
+   * Errors are logged but not propagated — cron jobs are fire-and-forget.
+   * @param workflowId - Workflow to start
+   * @param triggerIndex - Index of the trigger that fired
+   */
+  private fireTrigger;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/workflow-engine-service.d.ts
+/**
+ * Options for constructing a {@link WorkflowEngineService}.
+ *
+ * All fields are optional — when omitted the service uses the in-process
+ * workflow scheduler and default executor config.
+ */
+interface WorkflowEngineServiceOptions {
+  /**
+   * Workflow-level runner for dispatching full workflow executions to an
+   * isolated environment (worker thread pool, child process, container).
+   *
+   * When provided the executor delegates each new execution to this runner
+   * instead of running it in-process via the DAG scheduler.
+   * When omitted, execution falls back to the in-process DAG scheduler.
+   */
+  workflowRunner?: IWorkflowRunner;
+  /** Partial executor configuration merged with defaults. */
+  executorConfig?: Partial<ExecutorConfig>;
+}
+/**
+ * Workflow engine package service.
+ *
+ * Owns the boot lifecycle for the workflow executor and trigger evaluators so
+ * stored triggers become active during normal runtime package startup.
+ */
+declare class WorkflowEngineService extends BaseService {
+  private readonly workflowExecutor;
+  private readonly busEventTriggerEvaluator;
+  private readonly cronTriggerEvaluator;
+  /**
+   * @param bus - Shared runtime bus.
+   * @param options - Optional workflow runner and executor config overrides.
+   */
+  constructor(bus: IMakaioBus, options?: WorkflowEngineServiceOptions);
+  /**
+   * Executor owned by this package service.
+   * @returns Workflow executor instance.
+   */
+  get executor(): WorkflowExecutor;
+  /**
+   * Cron evaluator owned by this package service.
+   * @returns Cron trigger evaluator instance.
+   */
+  get cronTriggers(): CronTriggerEvaluator;
+  /**
+   * Set the trigger type registry used by executor request handlers.
+   * @param registry - Trigger type registry instance.
+   */
+  setTriggerTypeRegistry(registry: IWorkflowTriggerTypeRegistry): void;
+  /**
+   * Retrieve the executor trigger type registry.
+   * @returns Trigger type registry, or `undefined` when none is set.
+   */
+  getTriggerTypeRegistry(): IWorkflowTriggerTypeRegistry | undefined;
+  /**
+   * Initialize executor handlers before trigger evaluators can fire starts.
+   * @returns Promise that resolves once all child services are initialized.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Tear down child services in reverse boot order.
+   * @returns Promise that resolves once all child services are destroyed.
+   */
+  private destroyOwnedServices;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/package.d.ts
+/** Typed package token for retrieving the workflow engine package service. */
+declare const WorkflowEngineToken: _$_makaio_contracts0.ExtensionToken<WorkflowEngineService>;
+/**
+ * Create a workflow engine package manifest with optional runtime overrides.
+ *
+ * The returned manifest registers the `WorkflowEngineService` as the package
+ * service, wires Drizzle storage handlers, and forwards the provided options
+ * to the executor so that composition roots can inject a workflow-level runner
+ * or executor configuration (e.g. busUrl, busAuth, platformDefaults).
+ * @param options - Optional workflow runner and executor config overrides.
+ * @returns A `MakaioNodeExtension` manifest for the workflow engine subsystem.
+ */
+declare function createWorkflowEnginePackage(options?: WorkflowEngineServiceOptions): MakaioNodeExtension<IMakaioBus>;
+/**
+ * Default workflow engine package manifest (no runtime overrides).
+ *
+ * Equivalent to `createWorkflowEnginePackage()` with no arguments. Preserved
+ * for existing consumers that reference the static constant directly.
+ */
+declare const workflowEnginePackage: MakaioNodeExtension<IMakaioBus>;
+//#endregion
+export { WorkflowExecutor as a, WorkflowEngineService as i, createWorkflowEnginePackage as n, registerDrizzleWorkflowStorage as o, workflowEnginePackage as r, WorkflowEngineToken as t };

package/dist/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@makaio/framework",
+  "version": "1.0.0-dev-1781081952714",
+  "type": "module"
+}