evo360-types 1.3.141 → 1.3.144

package/dist/types/evo-task-runner/index.ts

@@ -0,0 +1,141 @@
+import type { IFireDoc } from "../shared";
+import type {
+  TaskAutoHandler,
+  TaskExecutionStatus,
+  TaskRetryStrategy,
+} from "../evo-task";
+
+// ======================================================
+// evo-task-runner (Task Runner)
+//
+// This module defines the contracts used by the Task Runner to:
+// - pick due AUTO tasks
+// - dispatch execution requests to handler executors (notifications, ai_agent, ...)
+// - receive async execution reports
+//
+// NOTE:
+// - Task payload schemas live in their respective modules.
+// - This contract is handler-agnostic and safe to share between backend/frontend.
+// ======================================================
+
+// ----- Pub/Sub topic suggestions (logical names)
+export const TaskRunnerTopics = {
+  Tick: "task_runner.tick",
+  ExecuteRequests: "task_runner.execute_requests",
+  ExecutionReports: "task_runner.execution_reports",
+} as const;
+
+export type TaskRunnerTopic =
+  (typeof TaskRunnerTopics)[keyof typeof TaskRunnerTopics];
+
+// ----- Runner tick messages (optional)
+export const TaskRunnerTickReasonEnum = {
+  Schedule: "schedule",
+  Manual: "manual",
+  Recovery: "recovery",
+} as const;
+
+export type TaskRunnerTickReason =
+  (typeof TaskRunnerTickReasonEnum)[keyof typeof TaskRunnerTickReasonEnum];
+
+export interface ITaskRunnerTick {
+  tenant: string;
+  reason: TaskRunnerTickReason;
+  requested_at: Date;
+  // Useful for batch processing controls
+  max_to_claim?: number;
+  look_ahead_seconds?: number; // if you want to include "execute_at <= now + lookahead"
+  [key: string]: unknown;
+}
+
+// ----- Execution request (Runner -> Handler Executor)
+// This message must be idempotent and safe to deliver at-least-once.
+export interface ITaskExecuteRequest {
+  tenant: string;
+
+  // Task identity
+  task_id: string;
+  task_path?: string; // optional Firestore path for convenience
+
+  // What to execute
+  handler: TaskAutoHandler;
+  kind: string; // mirrors task.auto.kind
+  version?: number | string; // mirrors task.auto.version
+
+  // Attempting/Idempotency
+  attempt: number; // 0-based attempt
+  idempotency_key?: string; // should be stable for "same attempt" dispatch
+
+  // Payload (handler-specific)
+  payload: Record<string, unknown>;
+
+  // Correlation / tracing
+  correlation_id?: string;
+  requested_at: Date;
+
+  // Optional execution constraints
+  timeout_ms?: number;
+  [key: string]: unknown;
+}
+
+// ----- Execution report (Handler Executor -> Runner)
+// Handler executors should emit a report for every request (success/failure).
+export interface ITaskExecutionReport {
+  tenant: string;
+
+  // Task identity
+  task_id: string;
+
+  // Execution identity
+  handler: TaskAutoHandler;
+  kind: string;
+  attempt: number;
+  correlation_id?: string;
+
+  // Status/result
+  status: TaskExecutionStatus; // success | error | retry
+
+  started_at: Date;
+  completed_at: Date;
+
+  // Retry hints (Runner remains the source of truth)
+  suggested_retry?: {
+    // If handler believes the error is retryable, it can suggest.
+    // Runner may override based on task.retry policy.
+    retryable: boolean;
+    code?: string | number;
+    message?: string;
+    next_attempt_at?: Date;
+    strategy?: TaskRetryStrategy;
+    backoff_seconds?: number;
+    [key: string]: unknown;
+  };
+
+  // Handler-specific result data
+  result?: Record<string, unknown>;
+
+  // Error data (when status is error/retry)
+  error?: {
+    message: string;
+    code?: string | number;
+    details?: Record<string, unknown>;
+  };
+
+  // Optional provider metadata (e.g. WhatsApp provider message id)
+  provider?: {
+    name?: string;
+    message_id?: string;
+    [key: string]: unknown;
+  };
+
+  [key: string]: unknown;
+}
+
+// ----- Optional: runner audit doc (if you want a central collection for runner events)
+export interface ITaskRunnerEvent extends IFireDoc {
+  tenant: string;
+  type: "tick" | "dispatch" | "report";
+  at: Date;
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.141",
+  "version": "1.3.144",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",