zayra-task-engine 0.0.1

package/README.md

@@ -0,0 +1,268 @@
+# zayra-task-engine
+
+The intelligent workflow execution system of **ZAYRA AI**. It manages tasks, multi-step workflows, automations, and their execution states — planning and running the work ZAYRA's AI decides to do, with permission checks in front of every run.
+
+This is version `0.0.1`. It contains **no frontend/UI code, no hardcoded workflows, and no AI provider logic** — only task planning and execution flow.
+
+## Installation
+
+```bash
+npm install zayra-task-engine
+```
+
+## Usage
+
+```js
+import { TaskManager } from "zayra-task-engine";
+
+const tasks = new TaskManager();
+
+const task = tasks.createTask({ name: "Send weekly report" });
+await tasks.startTask(task.id);
+await tasks.completeTask(task.id, { sent: true });
+
+task.state; // "completed"
+```
+
+## Workflows (multi-step tasks)
+
+```js
+const task = tasks.createWorkflow("Research topic", [
+  "Search information",
+  "Analyze results",
+  "Generate summary",
+]);
+
+await tasks.startTask(task.id); // runs each step in order automatically
+
+tasks.getProgress(task.id);
+// { total: 3, completed: 3, failed: 0, remaining: 0, percent: 100 }
+```
+
+Steps run themselves through an injected runner (see **Tool integration** below) — `startTask()` walks the list, stops the whole task at the first failed step, and completes it automatically once every step succeeds.
+
+## Task manager API
+
+```js
+tasks.createTask({ name, type?, steps?, metadata? }); // register, doesn't start
+await tasks.startTask(id);    // permission check -> RUNNING -> runs steps if any
+tasks.pauseTask(id);          // RUNNING -> WAITING
+await tasks.resumeTask(id);   // WAITING -> RUNNING, continues remaining steps
+tasks.cancelTask(id);         // -> CANCELLED, also clears any pending schedule
+await tasks.completeTask(id, result?); // -> COMPLETED, saves to memory if configured
+await tasks.failTask(id, error?);      // -> FAILED
+
+tasks.getTask(id);
+tasks.listTasks({ state?: "running" });
+```
+
+## Task types
+
+```js
+import { TaskType } from "zayra-task-engine";
+
+TaskType.SIMPLE;        // "simple"       - one action, no sub-steps
+TaskType.MULTI_STEP;     // "multi_step"    - an explicit workflow
+TaskType.SCHEDULED;       // "scheduled"      - meant to run via scheduleTask()
+TaskType.AUTOMATION;       // "automation"      - a recurring/triggered task
+TaskType.AI_GENERATED;      // "ai_generated"     - steps planned by an AI orchestrator at start time
+```
+
+`type` doesn't change how a task is executed by itself — it's metadata consumers (and the AI integration below) can act on.
+
+## Task state management
+
+```js
+import { TaskState } from "zayra-task-engine";
+
+TaskState.CREATED;    // just made, not started
+TaskState.RUNNING;     // in progress
+TaskState.WAITING;      // paused, waiting to resume
+TaskState.COMPLETED;     // finished successfully — terminal
+TaskState.FAILED;         // a step or the task itself failed — terminal
+TaskState.CANCELLED;       // cancelled by caller — terminal
+```
+
+Only specific transitions are allowed (enforced by `Task#transitionTo()`, used internally by every manager method): `created -> running|cancelled`, `running -> waiting|completed|failed|cancelled`, `waiting -> running|cancelled`. Trying to move a completed/failed/cancelled task anywhere throws `TaskError`.
+
+## Tool integration
+
+Tasks don't call tools themselves — `TaskManager` accepts an injected `toolRunner` function, typically backed by `zayra-tools`:
+
+```js
+import { TaskManager } from "zayra-task-engine";
+import { ToolRegistry, executeTool } from "zayra-tools";
+
+const toolRegistry = new ToolRegistry();
+// ...register tools...
+
+const tasks = new TaskManager({
+  toolRunner: async (step, { task }) => {
+    const tool = toolRegistry.getTool(step.action.toolName);
+    const result = await executeTool(tool, step.action.input);
+    if (!result.success) throw new Error(result.error.message);
+    return result.data;
+  },
+});
+```
+
+Flow, per spec: **Task -> Tool selection -> Execution -> Result**. `zayra-task-engine` never imports `zayra-tools` directly (see **Design note** below) — `step.action` is whatever shape your `toolRunner` expects.
+
+## AI integration
+
+An AI orchestrator can create tasks, plan their steps, and let the engine execute and monitor them:
+
+```js
+const tasks = new TaskManager({
+  aiOrchestrator: {
+    async planSteps(task) {
+      // ask an AI model what steps this task needs, return step names/definitions
+      return ["Search flights", "Compare prices", "Book cheapest option"];
+    },
+  },
+  toolRunner /* ...as above... */,
+});
+
+const task = tasks.createTask({ name: "Book a flight to Tokyo", type: "ai_generated" });
+await tasks.startTask(task.id); // planSteps() runs first since the task has no steps yet, then they execute
+```
+
+`aiOrchestrator` matches the shape a future `zayra-ai-orchestrator` package would provide — inject any object with a `planSteps(task)` method today.
+
+## Memory integration
+
+```js
+import { MemoryManager } from "zayra-memory";
+
+const memory = new MemoryManager();
+const tasks = new TaskManager({
+  memoryAdapter: { save: (entry) => memory.save(entry) },
+});
+
+await tasks.completeTask(task.id, { summary: "Report sent to 12 recipients" });
+// memory.save() was called with a summary of the completed task
+```
+
+## Security rules
+
+```js
+import { TaskPermissionManager } from "zayra-task-engine";
+
+const permissions = new TaskPermissionManager();
+permissions.blockTaskType("automation");           // block a whole task type
+permissions.grantSystemPermission("network:external");
+permissions.grantUserPermission("network:external"); // both required to actually grant it
+
+const tasks = new TaskManager({ permissions });
+```
+
+`startTask()` always runs the permission check first — a task whose type is blocked, or that declares a `metadata.permissions` requirement not granted by **both** the system and the user, throws `TaskError` and never runs. This is the same allow-if-both-agree model `zayra-tools`' `PermissionManager` uses, so a shared permission set can back both packages.
+
+## Scheduling support
+
+```js
+tasks.scheduleTask(task.id, { delayMs: 60_000 });   // auto-starts in 1 minute
+tasks.scheduleTask(task.id, { at: "2026-08-01T09:00:00Z" });
+
+tasks.unscheduleTask(task.id); // cancel without cancelling the task itself
+```
+
+A minimal timer-based scheduler in `0.0.1` — a placeholder that keeps `TaskScheduler`'s shape stable for a future cron-style/recurring version.
+
+## Events
+
+```js
+import { TaskEvent } from "zayra-task-engine";
+
+tasks.events.on(TaskEvent.CREATED, ({ task }) => console.log(`${task.name} created`));
+tasks.events.on(TaskEvent.STARTED, ({ task }) => console.log(`${task.name} started`));
+tasks.events.on(TaskEvent.COMPLETED, ({ task }) => console.log(`${task.name} completed`));
+tasks.events.on(TaskEvent.FAILED, ({ task }) => console.log(`${task.name} failed`));
+tasks.events.on(TaskEvent.PAUSED, ({ task }) => {});
+tasks.events.on(TaskEvent.RESUMED, ({ task }) => {});
+tasks.events.on(TaskEvent.CANCELLED, ({ task }) => {});
+tasks.events.on(TaskEvent.STEP_STARTED, ({ task, step }) => {});
+tasks.events.on(TaskEvent.STEP_COMPLETED, ({ task, step }) => {});
+```
+
+A small built-in event bus for now — a drop-in placeholder for a future `zayra-events` package, matching the same `on()`/`off()`/`emit()` shape `zayra-plugins` already uses, so this code won't need to change when that lands.
+
+## Errors
+
+- `TaskError` — base error class; carries `err.taskId`
+- `ExecutionError` — a step failed, timed out, or had no runner available; carries `err.stepId`
+- `WorkflowError` — an invalid workflow definition (empty step list, malformed step)
+
+```js
+import { TaskError, ExecutionError, WorkflowError } from "zayra-task-engine";
+
+try {
+  await tasks.startTask(task.id);
+} catch (err) {
+  if (err instanceof TaskError) {
+    console.error(`Task ${err.taskId} failed to start:`, err.message);
+  }
+}
+```
+
+## Design note: dependency-free by convention
+
+Like every other `zayra-*` package, `zayra-task-engine` ships with **zero npm dependencies**, including on its own siblings (`zayra-tools`, `zayra-memory`, `zayra-ai-orchestrator`, `zayra-events`). All of that integration happens through the injected adapters shown above (`toolRunner`, `memoryAdapter`, `aiOrchestrator`, `permissions`) rather than imports. This keeps each package usable standalone, testable without the rest of ZAYRA installed, and free to swap implementations later without touching this package's internals.
+
+## What this package deliberately does NOT do
+
+Per its design rules:
+
+- No frontend/UI code
+- No hardcoded workflows — every workflow is built at runtime from the steps you (or an AI orchestrator) provide
+- No AI provider logic — model calls belong to `zayra-provider` / `zayra-ai-router`, not here
+- No execution of unsafe operations, bypassing of permissions, or exposing of secrets — every `startTask()` runs the permission check first
+
+## Project structure
+
+```
+zayra-task-engine/
+  src/
+    index.js       # public entry point
+    manager.js       # TaskManager — createTask/startTask/pauseTask/resumeTask/cancelTask/completeTask/failTask
+    task.js             # Task entity, createStep(), state-transition guarding
+    workflow.js            # defineWorkflow(), workflowProgress()
+    executor.js               # executeStep() — safe, timeout-aware step execution
+    permissions.js               # TaskPermissionManager — Security Rules
+    scheduler.js                    # TaskScheduler — timer-based scheduling support
+    events.js                         # EventBus + TaskEvent
+    types.js                            # TaskType, TaskState, allowed transitions
+    errors.js                             # TaskError, ExecutionError, WorkflowError
+  package.json
+  README.md
+```
+
+## API reference
+
+### `class TaskManager`
+
+| Method | Description |
+| --- | --- |
+| `new TaskManager(options?)` | `options.permissions`, `options.toolRunner`, `options.memoryAdapter`, `options.aiOrchestrator`, `options.stepTimeoutMs`. |
+| `createTask(input)` | Registers a task. Doesn't start it. |
+| `createWorkflow(name, steps, options?)` | Convenience: creates a `MULTI_STEP` task from step names/definitions. |
+| `startTask(id)` | Permission check, then `RUNNING`; plans steps via `aiOrchestrator` if `AI_GENERATED` with none; runs any steps. |
+| `pauseTask(id)` / `resumeTask(id)` | `RUNNING <-> WAITING`; resuming continues remaining steps. |
+| `cancelTask(id)` | -> `CANCELLED`; also clears any pending schedule. |
+| `completeTask(id, result?)` | -> `COMPLETED`; saves a summary via `memoryAdapter` if configured. |
+| `failTask(id, error?)` | -> `FAILED`. |
+| `getTask(id)` / `listTasks(filter?)` | Access registered tasks. `filter.state` restricts by `TaskState`. |
+| `scheduleTask(id, when)` / `unscheduleTask(id)` | `when: { delayMs? , at? }`. |
+| `getProgress(id)` | `{ total, completed, failed, remaining, percent }`. |
+
+### Other exports
+
+`Task`, `createStep()`, `defineWorkflow()`, `workflowProgress()`, `executeStep()`, `TaskPermissionManager`, `TaskScheduler`, `EventBus`, `TaskEvent`, `TaskType`, `TaskState`, `isValidTaskType()`, `isValidTaskState()`, `canTransition()`, `TaskError`, `ExecutionError`, `WorkflowError`
+
+## Compatibility
+
+Designed to work with `zayra-core`, `zayra-events`, `zayra-tools`, `zayra-memory`, and a future `zayra-ai-orchestrator`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "zayra-task-engine",
+  "version": "0.0.1",
+  "description": "Intelligent workflow execution system for ZAYRA AI — plans, tracks, and runs tasks, multi-step workflows, and automations, with permission checks and event support.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "zayra",
+    "ai",
+    "task-engine",
+    "workflow",
+    "automation",
+    "orchestration",
+    "agent"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {}
+}

package/src/errors.js

@@ -0,0 +1,62 @@
+/**
+ * errors.js
+ *
+ * Custom error hierarchy for zayra-task-engine (spec section: "Error
+ * Handling"). Never fails silently — every error thrown inside this
+ * package is one of these classes.
+ */
+
+/**
+ * Base error class for all zayra-task-engine errors.
+ */
+export class TaskError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [options]
+   * @param {string} [options.code]
+   * @param {string} [options.taskId]
+   * @param {unknown} [options.cause]
+   */
+  constructor(message, options = {}) {
+    super(message);
+
+    this.name = this.constructor.name;
+    this.code = options.code ?? "TASK_ERROR";
+    this.taskId = options.taskId ?? null;
+
+    if (options.cause !== undefined) {
+      this.cause = options.cause;
+    }
+
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Thrown when a step fails to execute, times out, or has no runner
+ * available to execute it.
+ */
+export class ExecutionError extends TaskError {
+  constructor(message, options = {}) {
+    super(message, { code: "EXECUTION_ERROR", ...options });
+    this.stepId = options.stepId ?? null;
+  }
+}
+
+/**
+ * Thrown for invalid workflow definitions — an empty or non-array
+ * step list, or a malformed individual step.
+ */
+export class WorkflowError extends TaskError {
+  constructor(message, options = {}) {
+    super(message, { code: "WORKFLOW_ERROR", ...options });
+  }
+}
+
+export default {
+  TaskError,
+  ExecutionError,
+  WorkflowError,
+};

package/src/events.js

@@ -0,0 +1,124 @@
+/**
+ * events.js
+ *
+ * Event Support (spec section: "Event Support" — zayra-events).
+ *
+ * zayra-events doesn't exist yet as a separate package, so — same
+ * pattern already used by zayra-plugins — this file implements a
+ * small, dependency-free event emitter itself, matching that same
+ * on()/off()/emit() API. Swapping this out for a real zayra-events
+ * client later only means replacing this file's internals; every
+ * other file here only ever calls .on()/.off()/.emit().
+ */
+
+/**
+ * Task lifecycle event names. The spec explicitly lists
+ * task.created / task.started / task.completed / task.failed;
+ * task.paused, task.resumed, task.cancelled, and the per-step events
+ * are natural extensions of the same six task-manager operations
+ * (createTask/startTask/pauseTask/resumeTask/cancelTask/completeTask)
+ * and the workflow step loop.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const TaskEvent = Object.freeze({
+  CREATED: "task.created",
+  STARTED: "task.started",
+  PAUSED: "task.paused",
+  RESUMED: "task.resumed",
+  COMPLETED: "task.completed",
+  FAILED: "task.failed",
+  CANCELLED: "task.cancelled",
+  STEP_STARTED: "task.step.started",
+  STEP_COMPLETED: "task.step.completed",
+});
+
+/**
+ * Minimal synchronous event emitter.
+ *
+ * @example
+ * const events = new EventBus();
+ * events.on(TaskEvent.COMPLETED, ({ task }) => console.log(`${task.name} done`));
+ * events.emit(TaskEvent.COMPLETED, { task });
+ */
+export class EventBus {
+  constructor() {
+    /** @type {Map<string, Set<Function>>} */
+    this._listeners = new Map();
+  }
+
+  /**
+   * @param {string} eventName
+   * @param {(payload: any) => void} handler
+   * @returns {() => void} An unsubscribe function.
+   */
+  on(eventName, handler) {
+    if (typeof handler !== "function") {
+      throw new TypeError("EventBus.on() requires a function handler.");
+    }
+    if (!this._listeners.has(eventName)) {
+      this._listeners.set(eventName, new Set());
+    }
+    this._listeners.get(eventName).add(handler);
+    return () => this.off(eventName, handler);
+  }
+
+  /**
+   * @param {string} eventName
+   * @param {(payload: any) => void} handler
+   * @returns {() => void} An unsubscribe function.
+   */
+  once(eventName, handler) {
+    const wrapped = (payload) => {
+      this.off(eventName, wrapped);
+      handler(payload);
+    };
+    return this.on(eventName, wrapped);
+  }
+
+  /**
+   * @param {string} eventName
+   * @param {(payload: any) => void} handler
+   */
+  off(eventName, handler) {
+    this._listeners.get(eventName)?.delete(handler);
+  }
+
+  /**
+   * Emits an event synchronously. A throwing handler is caught and
+   * logged rather than propagating, so one bad listener can't break
+   * the emit chain or crash the task lifecycle step that triggered it.
+   * @param {string} eventName
+   * @param {any} [payload]
+   */
+  emit(eventName, payload) {
+    const handlers = this._listeners.get(eventName);
+    if (!handlers || handlers.size === 0) {
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        handler(payload);
+      } catch (err) {
+        console.error(`[zayra-task-engine] Event handler for "${eventName}" threw:`, err);
+      }
+    }
+  }
+
+  /** @param {string} eventName @returns {number} */
+  listenerCount(eventName) {
+    return this._listeners.get(eventName)?.size ?? 0;
+  }
+
+  /** @param {string} [eventName] */
+  removeAllListeners(eventName) {
+    if (eventName) {
+      this._listeners.delete(eventName);
+    } else {
+      this._listeners.clear();
+    }
+  }
+}
+
+export default EventBus;

package/src/executor.js

@@ -0,0 +1,110 @@
+/**
+ * executor.js
+ *
+ * Safe step execution (spec sections: "Tool Integration" — Task ->
+ * Tool selection -> Execution -> Result — and "Error Handling":
+ * failed steps, timeouts).
+ *
+ * zayra-tools already exists as a sibling package, but per this
+ * project's convention every zayra-* package ships with zero npm
+ * dependencies on its siblings (see each package.json's empty
+ * "dependencies") — integration happens through dependency injection
+ * instead. Callers pass a `runner(step, context)` function (e.g. one
+ * backed by zayra-tools' ToolRegistry + executeTool()); this module
+ * just adds the safety net around it: an optional timeout, and a
+ * standard { success, data, error } result that never throws —
+ * matching zayra-tools' own executeTool() result shape.
+ */
+
+import { ExecutionError } from "./errors.js";
+
+/**
+ * @typedef {object} StepResult
+ * @property {boolean} success
+ * @property {any} data
+ * @property {{ name: string, code: string, message: string }|null} error
+ */
+
+/**
+ * Serializes any thrown value into the result format's `error` shape.
+ * @param {unknown} err
+ * @returns {{ name: string, code: string, message: string }}
+ */
+function serializeError(err) {
+  if (err instanceof Error) {
+    return {
+      name: err.name,
+      code: err.code ?? "EXECUTION_ERROR",
+      message: err.message,
+    };
+  }
+  return { name: "Error", code: "EXECUTION_ERROR", message: String(err) };
+}
+
+/**
+ * Races a promise against a timeout, rejecting with an ExecutionError
+ * if the timeout wins.
+ * @param {Promise<any>} promise
+ * @param {number} timeoutMs
+ * @param {string} stepId
+ * @returns {Promise<any>}
+ */
+function withTimeout(promise, timeoutMs, stepId) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new ExecutionError(`Step timed out after ${timeoutMs}ms.`, { stepId, code: "TIMEOUT" }));
+    }, timeoutMs);
+
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
+
+/**
+ * Executes a single step through an injected runner function,
+ * enforcing an optional timeout and normalizing the result. Never
+ * rejects.
+ *
+ * @param {import("./task.js").Step} step
+ * @param {(step: import("./task.js").Step, context: object) => Promise<any>} runner - Injected step runner, e.g. one that looks up a tool by `step.action` and calls zayra-tools' executeTool().
+ * @param {object} [context] - Passed through to the runner (e.g. `{ task }`).
+ * @param {number} [timeoutMs] - Optional timeout in ms. Omit/0 for no timeout.
+ * @returns {Promise<StepResult>}
+ */
+export async function executeStep(step, runner, context = {}, timeoutMs) {
+  if (typeof runner !== "function") {
+    const err = new ExecutionError(
+      `No step runner was provided for step "${step.name}" (expected a function).`,
+      { stepId: step.id }
+    );
+    return { success: false, data: null, error: serializeError(err) };
+  }
+
+  try {
+    const data = timeoutMs
+      ? await withTimeout(runner(step, context), timeoutMs, step.id)
+      : await runner(step, context);
+    return { success: true, data: data === undefined ? null : data, error: null };
+  } catch (err) {
+    const wrapped =
+      err instanceof ExecutionError
+        ? err
+        : new ExecutionError(`Step "${step.name}" failed: ${err.message}`, {
+            stepId: step.id,
+            cause: err,
+          });
+    return { success: false, data: null, error: serializeError(wrapped) };
+  }
+}
+
+export default {
+  executeStep,
+};

package/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * index.js
+ *
+ * Public entry point for the zayra-task-engine package.
+ *
+ * Anything a consumer needs should be exported from here — they
+ * should never need to import from "zayra-task-engine/src/...". This
+ * keeps the internal file layout free to change without breaking
+ * zayra-core, zayra-ai-orchestrator, zayra-tools, or zayra-memory
+ * integrations built against this package.
+ */
+
+export { TaskManager } from "./manager.js";
+export { Task, createStep } from "./task.js";
+export { defineWorkflow, workflowProgress } from "./workflow.js";
+export { executeStep } from "./executor.js";
+export { TaskPermissionManager } from "./permissions.js";
+export { TaskScheduler } from "./scheduler.js";
+export { EventBus, TaskEvent } from "./events.js";
+export { TaskType, TaskState, isValidTaskType, isValidTaskState, canTransition } from "./types.js";
+export { TaskError, ExecutionError, WorkflowError } from "./errors.js";
+
+export { TaskManager as default } from "./manager.js";