zayra-task-engine 0.0.1

package/src/manager.js

@@ -0,0 +1,328 @@
+/**
+ * manager.js
+ *
+ * TaskManager (spec sections: "Task Manager System", "AI
+ * Integration", "Workflow System", "Tool Integration", "Memory
+ * Integration", "Scheduling Support"). The single class consumers of
+ * zayra-task-engine interact with.
+ *
+ * Everything zayra-task-engine integrates with — an AI orchestrator,
+ * zayra-tools, zayra-memory, a permission source — is accepted as an
+ * injected adapter, never imported directly. This keeps the package
+ * dependency-free (matching every other zayra-* package's empty
+ * "dependencies") and means none of those integrated packages need
+ * to exist yet for this one to work standalone.
+ *
+ * Per spec's "Important Rules": no frontend/UI code, no hardcoded
+ * workflows, no AI provider logic lives here — only planning and
+ * execution flow.
+ */
+
+import { Task } from "./task.js";
+import { defineWorkflow, workflowProgress } from "./workflow.js";
+import { executeStep } from "./executor.js";
+import { TaskPermissionManager } from "./permissions.js";
+import { TaskScheduler } from "./scheduler.js";
+import { EventBus, TaskEvent } from "./events.js";
+import { TaskType, TaskState } from "./types.js";
+import { TaskError } from "./errors.js";
+
+export class TaskManager {
+  /**
+   * @param {object} [options]
+   * @param {TaskPermissionManager} [options.permissions] - Injected permission manager. A permissive default (nothing blocked, no permissions required) is created if omitted.
+   * @param {(step: object, context: object) => Promise<any>} [options.toolRunner] - Injected step runner, typically backed by zayra-tools' ToolRegistry + executeTool(). Required for any task whose steps carry an `action` that needs a real tool call.
+   * @param {{ save: (entry: object) => Promise<any> }} [options.memoryAdapter] - Injected zayra-memory-shaped adapter. If given, `completeTask()` saves a summary of the finished task through it.
+   * @param {{ planSteps?: (task: Task) => Promise<(string|object)[]> }} [options.aiOrchestrator] - Injected zayra-ai-orchestrator-shaped adapter. If given, `startTask()` calls `planSteps(task)` to generate steps for AI_GENERATED tasks created with no steps of their own.
+   * @param {number} [options.stepTimeoutMs] - Default per-step execution timeout, in ms.
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, Task>} */
+    this.tasks = new Map();
+    this.events = new EventBus();
+    this.permissions = options.permissions ?? new TaskPermissionManager();
+    this.toolRunner = options.toolRunner ?? null;
+    this.memoryAdapter = options.memoryAdapter ?? null;
+    this.aiOrchestrator = options.aiOrchestrator ?? null;
+    this.scheduler = new TaskScheduler();
+    this.stepTimeoutMs = options.stepTimeoutMs;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Task Manager System: createTask / startTask / pauseTask /           */
+  /* resumeTask / cancelTask / completeTask                              */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * Creates and registers a new task. Does not start it.
+   *
+   * @param {object} input - Same shape as the Task constructor: { name, type?, steps?, metadata? }.
+   * @returns {Task}
+   * @throws {TaskError} If the input is invalid.
+   */
+  createTask(input = {}) {
+    const task = new Task(input);
+    this.tasks.set(task.id, task);
+    this.events.emit(TaskEvent.CREATED, { task });
+    return task;
+  }
+
+  /**
+   * Convenience for the spec's "Workflow System" example: creates a
+   * multi-step task directly from an ordered list of step names or
+   * definitions.
+   *
+   * @example
+   * manager.createWorkflow("Research topic", [
+   *   "Search information",
+   *   "Analyze results",
+   *   "Generate summary",
+   * ]);
+   *
+   * @param {string} name
+   * @param {(string|object)[]} steps
+   * @param {object} [options] - Extra Task fields (type, metadata, etc.). type defaults to MULTI_STEP.
+   * @returns {Task}
+   */
+  createWorkflow(name, steps, options = {}) {
+    const normalizedSteps = defineWorkflow(steps);
+    return this.createTask({
+      ...options,
+      name,
+      type: options.type ?? TaskType.MULTI_STEP,
+      steps: normalizedSteps,
+    });
+  }
+
+  /**
+   * @param {string} taskId
+   * @returns {Task}
+   * @throws {TaskError} If no task with that id exists.
+   */
+  getTask(taskId) {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      throw new TaskError(`No task found with id "${taskId}".`, { taskId });
+    }
+    return task;
+  }
+
+  /**
+   * @param {object} [options]
+   * @param {string} [options.state] - Restrict to a single TaskState.
+   * @returns {Task[]}
+   */
+  listTasks(options = {}) {
+    const all = [...this.tasks.values()];
+    return options.state ? all.filter((task) => task.state === options.state) : all;
+  }
+
+  /**
+   * Starts a task: runs the permission check (per "Security Rules" —
+   * a task is never executed without passing this first), transitions
+   * it to RUNNING, and — for an AI_GENERATED task created with no
+   * steps — asks the injected AI orchestrator to plan them ("AI
+   * Integration": create tasks, plan steps, execute actions, monitor
+   * progress). A task with steps then runs each one in order; a
+   * plain task with no steps just becomes RUNNING and waits for the
+   * caller to call completeTask()/failTask() once its single action
+   * is done.
+   *
+   * @param {string} taskId
+   * @returns {Promise<Task>}
+   * @throws {TaskError} If the task doesn't exist, isn't in a startable state, or is blocked by the permission check.
+   */
+  async startTask(taskId) {
+    const task = this.getTask(taskId);
+
+    const check = this.permissions.checkTask(task);
+    if (!check.allowed) {
+      throw new TaskError(`Task "${taskId}" was blocked by the permission check (${check.reason}).`, {
+        taskId,
+        code: "PERMISSION_DENIED",
+      });
+    }
+
+    if (task.type === TaskType.AI_GENERATED && task.steps.length === 0 && this.aiOrchestrator?.planSteps) {
+      const planned = await this.aiOrchestrator.planSteps(task);
+      task.steps = defineWorkflow(planned);
+    }
+
+    task.transitionTo(TaskState.RUNNING);
+    this.events.emit(TaskEvent.STARTED, { task });
+
+    if (task.hasWorkflow) {
+      await this._runSteps(task);
+    }
+
+    return task;
+  }
+
+  /**
+   * Runs a task's remaining steps in order (spec's "Workflow System"
+   * step sequence), stopping early if the task is paused or
+   * cancelled mid-run, and failing/completing the task automatically
+   * based on the outcome.
+   * @param {Task} task
+   * @private
+   */
+  async _runSteps(task) {
+    for (let i = task.currentStepIndex; i < task.steps.length; i++) {
+      if (task.state !== TaskState.RUNNING) {
+        return; // paused or cancelled since the loop started
+      }
+
+      const step = task.steps[i];
+      task.currentStepIndex = i;
+      step.status = "running";
+      this.events.emit(TaskEvent.STEP_STARTED, { task, step });
+
+      const result = await executeStep(step, this.toolRunner, { task }, this.stepTimeoutMs);
+
+      if (result.success) {
+        step.status = "completed";
+        step.result = result.data;
+        this.events.emit(TaskEvent.STEP_COMPLETED, { task, step });
+      } else {
+        step.status = "failed";
+        step.error = result.error;
+        await this.failTask(task.id, result.error);
+        return;
+      }
+    }
+
+    if (task.state === TaskState.RUNNING) {
+      await this.completeTask(task.id);
+    }
+  }
+
+  /**
+   * Pauses a running task (moves it to WAITING).
+   * @param {string} taskId
+   * @returns {Task}
+   */
+  pauseTask(taskId) {
+    const task = this.getTask(taskId);
+    task.transitionTo(TaskState.WAITING);
+    this.events.emit(TaskEvent.PAUSED, { task });
+    return task;
+  }
+
+  /**
+   * Resumes a paused (WAITING) task, continuing any remaining
+   * workflow steps from where it left off.
+   * @param {string} taskId
+   * @returns {Promise<Task>}
+   */
+  async resumeTask(taskId) {
+    const task = this.getTask(taskId);
+    task.transitionTo(TaskState.RUNNING);
+    this.events.emit(TaskEvent.RESUMED, { task });
+
+    if (task.hasWorkflow) {
+      await this._runSteps(task);
+    }
+
+    return task;
+  }
+
+  /**
+   * Cancels a task and clears any pending schedule for it.
+   * @param {string} taskId
+   * @returns {Task}
+   */
+  cancelTask(taskId) {
+    const task = this.getTask(taskId);
+    this.scheduler.cancel(taskId);
+    task.transitionTo(TaskState.CANCELLED);
+    this.events.emit(TaskEvent.CANCELLED, { task });
+    return task;
+  }
+
+  /**
+   * Marks a task completed, and — if a memory adapter was injected —
+   * saves a summary of its result for future context ("Memory
+   * Integration": completed tasks support storing useful information
+   * through zayra-memory).
+   *
+   * @param {string} taskId
+   * @param {any} [result] - Final result to attach to the task, if not already set by its steps.
+   * @returns {Promise<Task>}
+   */
+  async completeTask(taskId, result) {
+    const task = this.getTask(taskId);
+
+    if (result !== undefined) {
+      task.result = result;
+    }
+
+    task.transitionTo(TaskState.COMPLETED);
+    this.events.emit(TaskEvent.COMPLETED, { task });
+
+    if (this.memoryAdapter?.save) {
+      await this.memoryAdapter.save({
+        content: `Completed task "${task.name}" (${task.type}).`,
+        metadata: { taskId: task.id, taskType: task.type, result: task.result },
+      });
+    }
+
+    return task;
+  }
+
+  /**
+   * Marks a task failed.
+   * @param {string} taskId
+   * @param {Error|{ name?: string, message?: string }|any} [error]
+   * @returns {Promise<Task>}
+   */
+  async failTask(taskId, error) {
+    const task = this.getTask(taskId);
+    task.error = error instanceof Error ? { name: error.name, message: error.message } : (error ?? null);
+    task.transitionTo(TaskState.FAILED);
+    this.events.emit(TaskEvent.FAILED, { task });
+    return task;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Scheduling Support                                                   */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * Schedules a task to auto-start later. Intended for tasks created
+   * with type TaskType.SCHEDULED, though this isn't enforced.
+   *
+   * @param {string} taskId
+   * @param {{ delayMs?: number, at?: string|Date }} when
+   * @returns {Task}
+   */
+  scheduleTask(taskId, when) {
+    const task = this.getTask(taskId);
+    this.scheduler.schedule(taskId, () => {
+      this.startTask(taskId).catch((err) => this.failTask(taskId, err));
+    }, when);
+    return task;
+  }
+
+  /**
+   * Cancels a task's pending schedule without cancelling the task
+   * itself.
+   * @param {string} taskId
+   */
+  unscheduleTask(taskId) {
+    this.scheduler.cancel(taskId);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Progress                                                             */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * @param {string} taskId
+   * @returns {{ total: number, completed: number, failed: number, remaining: number, percent: number }}
+   */
+  getProgress(taskId) {
+    return workflowProgress(this.getTask(taskId).steps);
+  }
+}
+
+export default TaskManager;

package/src/permissions.js

@@ -0,0 +1,113 @@
+/**
+ * permissions.js
+ *
+ * Security Rules (spec section: "Security Rules"). Tasks must not
+ * execute unsafe operations, bypass permissions, or expose secrets —
+ * this module is the permission check that manager.js runs before
+ * starting any task.
+ *
+ * Deliberately the same shape as zayra-tools' PermissionManager (a
+ * permission is only granted if both the system and the user allow
+ * it), so a single set of granted permissions can be shared across
+ * both packages by an integrating application if it chooses to.
+ */
+
+/**
+ * @typedef {object} TaskPermissionCheckResult
+ * @property {boolean} allowed
+ * @property {string[]} missing - Required permissions that weren't granted (empty if allowed, or if the task type itself was blocked rather than missing a specific permission).
+ * @property {string|null} reason - "blocked_type" | "missing_permissions" | null
+ */
+
+/**
+ * Tracks which task types may run and which permissions have been
+ * granted, and checks a task's requirements against both.
+ *
+ * A task declares the permissions it needs via
+ * `task.metadata.permissions` (e.g. `["filesystem:write",
+ * "network:external"]`) — a task with no declared permissions is
+ * allowed to run as long as its type isn't blocked.
+ *
+ * @example
+ * const permissions = new TaskPermissionManager();
+ * permissions.grantSystemPermission("network:external");
+ * permissions.grantUserPermission("network:external");
+ * permissions.checkTask(task); // { allowed: true, missing: [], reason: null }
+ */
+export class TaskPermissionManager {
+  /**
+   * @param {object} [options]
+   * @param {string[]} [options.blockedTaskTypes] - Task types that may never run, e.g. ["automation"].
+   * @param {string[]} [options.userPermissions] - Permission strings the user has granted.
+   * @param {string[]} [options.systemPermissions] - Permission strings the system/environment allows.
+   */
+  constructor(options = {}) {
+    this.blockedTaskTypes = new Set(options.blockedTaskTypes ?? []);
+    this.userPermissions = new Set(options.userPermissions ?? []);
+    this.systemPermissions = new Set(options.systemPermissions ?? []);
+  }
+
+  /**
+   * A permission is granted only if both the system and the user
+   * allow it.
+   * @param {string} permission
+   * @returns {boolean}
+   */
+  hasPermission(permission) {
+    return this.systemPermissions.has(permission) && this.userPermissions.has(permission);
+  }
+
+  /**
+   * Checks whether a task's type is allowed to run at all, and
+   * whether every permission it declares has been granted.
+   *
+   * @param {import("./task.js").Task} task
+   * @returns {TaskPermissionCheckResult}
+   */
+  checkTask(task) {
+    if (this.blockedTaskTypes.has(task.type)) {
+      return { allowed: false, missing: [], reason: "blocked_type" };
+    }
+
+    const required = Array.isArray(task.metadata?.permissions) ? task.metadata.permissions : [];
+    const missing = required.filter((permission) => !this.hasPermission(permission));
+
+    if (missing.length > 0) {
+      return { allowed: false, missing, reason: "missing_permissions" };
+    }
+
+    return { allowed: true, missing: [], reason: null };
+  }
+
+  /** @param {string} type */
+  blockTaskType(type) {
+    this.blockedTaskTypes.add(type);
+  }
+
+  /** @param {string} type */
+  allowTaskType(type) {
+    this.blockedTaskTypes.delete(type);
+  }
+
+  /** @param {string} permission */
+  grantUserPermission(permission) {
+    this.userPermissions.add(permission);
+  }
+
+  /** @param {string} permission */
+  revokeUserPermission(permission) {
+    this.userPermissions.delete(permission);
+  }
+
+  /** @param {string} permission */
+  grantSystemPermission(permission) {
+    this.systemPermissions.add(permission);
+  }
+
+  /** @param {string} permission */
+  revokeSystemPermission(permission) {
+    this.systemPermissions.delete(permission);
+  }
+}
+
+export default TaskPermissionManager;

package/src/scheduler.js

@@ -0,0 +1,90 @@
+/**
+ * scheduler.js
+ *
+ * Scheduling Support (spec section: "Scheduling Support") — prepared
+ * support for timers, scheduled execution, and background tasks.
+ *
+ * Deliberately minimal in 0.0.1: a delay- or absolute-time-based
+ * setTimeout scheduler, matching "Prepare support for" rather than
+ * shipping a full cron system. A later version can swap this for
+ * recurring/cron-style schedules without changing TaskScheduler's
+ * public shape (schedule/cancel/isScheduled/clear).
+ */
+
+import { TaskError } from "./errors.js";
+
+/**
+ * Schedules callbacks to run later, keyed by task id so a task can
+ * never have two pending schedules at once.
+ *
+ * @example
+ * const scheduler = new TaskScheduler();
+ * scheduler.schedule(task.id, () => manager.startTask(task.id), { delayMs: 60_000 });
+ */
+export class TaskScheduler {
+  constructor() {
+    /** @type {Map<string, NodeJS.Timeout>} */
+    this._timers = new Map();
+  }
+
+  /**
+   * Schedules a callback to run once, either after a delay or at an
+   * absolute time. Replaces any existing schedule for the same
+   * taskId.
+   *
+   * @param {string} taskId
+   * @param {() => void} callback
+   * @param {object} when
+   * @param {number} [when.delayMs] - Milliseconds from now.
+   * @param {string|Date} [when.at] - Absolute time to run at.
+   * @throws {TaskError} If neither delayMs nor at is given.
+   */
+  schedule(taskId, callback, when = {}) {
+    let delayMs = when.delayMs;
+
+    if (delayMs === undefined && when.at) {
+      const target = when.at instanceof Date ? when.at : new Date(when.at);
+      delayMs = target.getTime() - Date.now();
+    }
+
+    if (typeof delayMs !== "number" || Number.isNaN(delayMs)) {
+      throw new TaskError('scheduleTask() requires "delayMs" or an "at" time.', { taskId });
+    }
+
+    this.cancel(taskId);
+
+    const timer = setTimeout(() => {
+      this._timers.delete(taskId);
+      callback();
+    }, Math.max(0, delayMs));
+
+    this._timers.set(taskId, timer);
+  }
+
+  /**
+   * Cancels a task's pending schedule, if any. Safe to call for a
+   * taskId with no schedule.
+   * @param {string} taskId
+   */
+  cancel(taskId) {
+    const timer = this._timers.get(taskId);
+    if (timer) {
+      clearTimeout(timer);
+      this._timers.delete(taskId);
+    }
+  }
+
+  /** @param {string} taskId @returns {boolean} */
+  isScheduled(taskId) {
+    return this._timers.has(taskId);
+  }
+
+  /** Cancels every pending schedule — used on shutdown. */
+  clear() {
+    for (const taskId of this._timers.keys()) {
+      this.cancel(taskId);
+    }
+  }
+}
+
+export default TaskScheduler;