zayra-task-engine 0.0.1

package/src/task.js

@@ -0,0 +1,189 @@
+/**
+ * task.js
+ *
+ * Defines the Task entity (spec sections: "Task Manager System",
+ * "Task Types", "Task State Management") and createStep(), which
+ * builds the Step objects a workflow is made of.
+ *
+ * Intentionally a data class plus state-transition guarding — no
+ * execution, scheduling, or persistence logic lives here. That's
+ * executor.js, scheduler.js, and manager.js.
+ */
+
+import crypto from "node:crypto";
+import { TaskError } from "./errors.js";
+import { TaskType, TaskState, isValidTaskType, isValidTaskState, canTransition } from "./types.js";
+
+/**
+ * Generates a reasonably unique id. Not cryptographically
+ * meaningful — just needs to be unique within this ZAYRA instance's
+ * task engine.
+ * @param {string} prefix
+ * @returns {string}
+ */
+function generateId(prefix) {
+  return `${prefix}_${Date.now().toString(36)}_${crypto.randomBytes(4).toString("hex")}`;
+}
+
+/**
+ * A single step within a task's workflow.
+ * @typedef {object} Step
+ * @property {string} id
+ * @property {string} name
+ * @property {"pending"|"running"|"completed"|"failed"|"skipped"} status
+ * @property {any} action - Arbitrary step definition (e.g. a tool call spec). Task engine doesn't interpret this itself — the injected step runner passed to executor.js does.
+ * @property {any} result
+ * @property {{ name: string, code: string, message: string }|null} error
+ */
+
+/**
+ * Builds a Step from either a plain step name or a full step
+ * definition object, per spec's Workflow System example (a task's
+ * steps can be given as simple strings: "Search information",
+ * "Analyze results", "Generate summary").
+ *
+ * @param {string|object} step
+ * @returns {Step}
+ * @throws {TaskError} If the step has no usable name.
+ */
+export function createStep(step) {
+  const input = typeof step === "string" ? { name: step } : step ?? {};
+
+  if (typeof input.name !== "string" || input.name.trim().length === 0) {
+    throw new TaskError('Step requires a non-empty string "name".');
+  }
+
+  return {
+    id: input.id ?? generateId("step"),
+    name: input.name,
+    status: input.status ?? "pending",
+    action: input.action ?? null,
+    result: input.result ?? null,
+    error: input.error ?? null,
+  };
+}
+
+/**
+ * A unit of work ZAYRA's task engine plans, executes, and tracks.
+ *
+ * @example
+ * const task = new Task({
+ *   name: "Research topic",
+ *   type: TaskType.MULTI_STEP,
+ *   steps: ["Search information", "Analyze results", "Generate summary"],
+ * });
+ */
+export class Task {
+  /**
+   * @param {object} input
+   * @param {string} input.name - Required, non-empty.
+   * @param {string} [input.type=TaskType.SIMPLE] - One of TaskType's values.
+   * @param {string} [input.state=TaskState.CREATED] - One of TaskState's values.
+   * @param {(string|object)[]} [input.steps] - Step names or step definitions. Empty for a simple, single-action task.
+   * @param {object} [input.metadata] - Arbitrary extra data (e.g. required permissions, source, priority).
+   * @param {string} [input.id] - Task id. Auto-generated if omitted.
+   * @throws {TaskError} If required fields are missing or invalid.
+   */
+  constructor(input = {}) {
+    if (typeof input.name !== "string" || input.name.trim().length === 0) {
+      throw new TaskError('Task requires a non-empty string "name".');
+    }
+
+    const type = input.type ?? TaskType.SIMPLE;
+    if (!isValidTaskType(type)) {
+      throw new TaskError(`Invalid task type: "${type}".`);
+    }
+
+    const state = input.state ?? TaskState.CREATED;
+    if (!isValidTaskState(state)) {
+      throw new TaskError(`Invalid task state: "${state}".`);
+    }
+
+    const createdAt = input.createdAt ?? new Date().toISOString();
+
+    this.id = input.id ?? generateId("task");
+    this.name = input.name;
+    this.type = type;
+    this.state = state;
+    this.steps = Array.isArray(input.steps)
+      ? input.steps.map((step) => (step && typeof step === "object" && step.id ? step : createStep(step)))
+      : [];
+    this.currentStepIndex = input.currentStepIndex ?? 0;
+    this.result = input.result ?? null;
+    this.error = input.error ?? null;
+    this.metadata = input.metadata ?? {};
+    this.createdAt = createdAt;
+    this.updatedAt = input.updatedAt ?? createdAt;
+    this.startedAt = input.startedAt ?? null;
+    this.completedAt = input.completedAt ?? null;
+  }
+
+  /** @returns {boolean} Whether this task has a multi-step workflow attached. */
+  get hasWorkflow() {
+    return this.steps.length > 0;
+  }
+
+  /** @returns {Step|null} */
+  get currentStep() {
+    return this.steps[this.currentStepIndex] ?? null;
+  }
+
+  /**
+   * Moves the task to a new state, enforcing the allowed transitions
+   * defined in types.js. Stamps startedAt/completedAt as appropriate.
+   *
+   * @param {string} newState
+   * @throws {TaskError} If the transition isn't allowed from the task's current state.
+   */
+  transitionTo(newState) {
+    if (!canTransition(this.state, newState)) {
+      throw new TaskError(`Cannot transition task "${this.id}" from "${this.state}" to "${newState}".`, {
+        taskId: this.id,
+        code: "INVALID_TRANSITION",
+      });
+    }
+
+    this.state = newState;
+    this.updatedAt = new Date().toISOString();
+
+    if (newState === TaskState.RUNNING && !this.startedAt) {
+      this.startedAt = this.updatedAt;
+    }
+    if ([TaskState.COMPLETED, TaskState.FAILED, TaskState.CANCELLED].includes(newState)) {
+      this.completedAt = this.updatedAt;
+    }
+  }
+
+  /**
+   * Serializes this task to a plain JSON-safe object.
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      name: this.name,
+      type: this.type,
+      state: this.state,
+      steps: this.steps,
+      currentStepIndex: this.currentStepIndex,
+      result: this.result,
+      error: this.error,
+      metadata: this.metadata,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt,
+      startedAt: this.startedAt,
+      completedAt: this.completedAt,
+    };
+  }
+
+  /**
+   * Reconstructs a Task instance from a plain object.
+   * @param {object} data
+   * @returns {Task}
+   */
+  static fromJSON(data) {
+    return new Task(data);
+  }
+}
+
+export default Task;

package/src/types.js

@@ -0,0 +1,87 @@
+/**
+ * types.js
+ *
+ * Task Types + Task State Management (spec sections: "Task Types",
+ * "Task State Management"). Plain enums and validators — no
+ * behavior lives here, just the vocabulary every other file in this
+ * package shares.
+ */
+
+/**
+ * What kind of task this is, per spec's "Task Types" section.
+ * @readonly
+ * @enum {string}
+ */
+export const TaskType = Object.freeze({
+  SIMPLE: "simple",
+  MULTI_STEP: "multi_step",
+  SCHEDULED: "scheduled",
+  AUTOMATION: "automation",
+  AI_GENERATED: "ai_generated",
+});
+
+/**
+ * Task lifecycle state, per spec's "Task State Management" section.
+ *
+ * Note: pauseTask()/resumeTask() move a task between RUNNING and
+ * WAITING. The spec's state list has no separate "paused" state, so
+ * WAITING doubles as "paused, waiting to resume" — this keeps the
+ * state machine exactly matching what the spec asked for instead of
+ * inventing an extra state.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const TaskState = Object.freeze({
+  CREATED: "created",
+  RUNNING: "running",
+  WAITING: "waiting",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+});
+
+/** @param {string} type @returns {boolean} */
+export function isValidTaskType(type) {
+  return Object.values(TaskType).includes(type);
+}
+
+/** @param {string} state @returns {boolean} */
+export function isValidTaskState(state) {
+  return Object.values(TaskState).includes(state);
+}
+
+/**
+ * Allowed state transitions. Anything not listed here is rejected by
+ * Task#transitionTo() (see task.js) — so an already-completed task
+ * can't be restarted, a cancelled task can't be resumed, a failed
+ * task can't be resumed, etc.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const TASK_STATE_TRANSITIONS = Object.freeze({
+  [TaskState.CREATED]: [TaskState.RUNNING, TaskState.CANCELLED],
+  [TaskState.RUNNING]: [TaskState.WAITING, TaskState.COMPLETED, TaskState.FAILED, TaskState.CANCELLED],
+  [TaskState.WAITING]: [TaskState.RUNNING, TaskState.CANCELLED],
+  [TaskState.COMPLETED]: [],
+  [TaskState.FAILED]: [],
+  [TaskState.CANCELLED]: [],
+});
+
+/**
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  return Array.isArray(TASK_STATE_TRANSITIONS[from]) && TASK_STATE_TRANSITIONS[from].includes(to);
+}
+
+export default {
+  TaskType,
+  TaskState,
+  isValidTaskType,
+  isValidTaskState,
+  TASK_STATE_TRANSITIONS,
+  canTransition,
+};

package/src/workflow.js

@@ -0,0 +1,60 @@
+/**
+ * workflow.js
+ *
+ * Workflow System (spec section: "Workflow System"). A workflow is
+ * an ordered list of step definitions attached to a task — this
+ * module validates and builds that shape, matching the spec's
+ * example:
+ *
+ *   Task: Research topic
+ *   Steps: 1. Search information  2. Analyze results  3. Generate summary
+ */
+
+import { WorkflowError } from "./errors.js";
+import { createStep } from "./task.js";
+
+/**
+ * Validates and normalizes a list of step definitions into Step
+ * objects, ready to attach to a Task (directly, or via
+ * TaskManager.createWorkflow()).
+ *
+ * @param {(string|object)[]} steps
+ * @returns {import("./task.js").Step[]}
+ * @throws {WorkflowError} If steps isn't a non-empty array, or a step definition is invalid.
+ */
+export function defineWorkflow(steps) {
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw new WorkflowError("A workflow requires a non-empty array of steps.");
+  }
+
+  try {
+    return steps.map((step) => createStep(step));
+  } catch (err) {
+    throw new WorkflowError(`Invalid workflow step: ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Computes a workflow's progress from its current steps.
+ *
+ * @param {import("./task.js").Step[]} steps
+ * @returns {{ total: number, completed: number, failed: number, remaining: number, percent: number }}
+ */
+export function workflowProgress(steps) {
+  const total = steps.length;
+  const completed = steps.filter((step) => step.status === "completed").length;
+  const failed = steps.filter((step) => step.status === "failed").length;
+
+  return {
+    total,
+    completed,
+    failed,
+    remaining: total - completed - failed,
+    percent: total === 0 ? 0 : Math.round((completed / total) * 100),
+  };
+}
+
+export default {
+  defineWorkflow,
+  workflowProgress,
+};