@dexto/orchestration 1.5.8

package/dist/types.d.cts

@@ -0,0 +1,165 @@
+/**
+ * Orchestration Types
+ *
+ * Core type definitions for the agent orchestration layer.
+ * Defines tasks, signals, wait conditions, and agent states.
+ */
+/**
+ * Task result from agent or process execution
+ */
+interface TaskResult {
+    success: boolean;
+    response?: string;
+    error?: string;
+    agentId?: string;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+}
+/**
+ * Process result from shell command execution
+ */
+interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    duration?: number;
+}
+/**
+ * Task types - discriminated union of different background task kinds
+ */
+type Task = {
+    type: 'agent';
+    taskId: string;
+    agentId: string;
+    taskDescription: string;
+    promise: Promise<TaskResult>;
+} | {
+    type: 'process';
+    taskId: string;
+    processId: string;
+    command: string;
+    promise: Promise<ProcessResult>;
+} | {
+    type: 'generic';
+    taskId: string;
+    description: string;
+    promise: Promise<unknown>;
+};
+/**
+ * Task lifecycle status
+ */
+type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Entry in the task registry tracking a background task
+ */
+interface TaskEntry {
+    task: Task;
+    status: TaskStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    result?: unknown;
+    error?: string;
+    /** If true, auto-trigger agent turn on completion */
+    notify?: boolean;
+    /** Timeout handle for this task (if set) */
+    timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+}
+/**
+ * Signal types - events that trigger state transitions
+ */
+type Signal = {
+    type: 'task:completed';
+    taskId: string;
+    result: unknown;
+} | {
+    type: 'task:failed';
+    taskId: string;
+    error: string;
+} | {
+    type: 'task:cancelled';
+    taskId: string;
+} | {
+    type: 'timeout';
+    conditionId: string;
+} | {
+    type: 'user:input';
+    content: string;
+    sessionId: string;
+} | {
+    type: 'external';
+    source: string;
+    data: unknown;
+};
+/**
+ * Extract signal type string
+ */
+type SignalType = Signal['type'];
+/**
+ * Wait conditions - composable conditions for suspension
+ */
+type WaitCondition = {
+    type: 'task';
+    taskId: string;
+} | {
+    type: 'any';
+    conditions: WaitCondition[];
+} | {
+    type: 'all';
+    conditions: WaitCondition[];
+} | {
+    type: 'timeout';
+    ms: number;
+    conditionId: string;
+} | {
+    type: 'race';
+    task: WaitCondition;
+    timeout: WaitCondition;
+};
+/**
+ * Agent loop states
+ */
+type AgentState = 'idle' | 'processing' | 'waiting';
+/**
+ * Task info returned by list/check operations (without internal promise)
+ */
+interface TaskInfo {
+    taskId: string;
+    type: Task['type'];
+    status: TaskStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    duration?: number;
+    description?: string;
+    result?: unknown;
+    error?: string;
+    cancelReason?: string;
+}
+/**
+ * Filter options for listing tasks
+ */
+interface TaskFilter {
+    status?: TaskStatus | TaskStatus[];
+    type?: Task['type'];
+}
+/**
+ * Result from waiting on a condition
+ */
+interface WaitResult {
+    signal: Signal;
+    /** For 'all' conditions, contains all signals */
+    allSignals?: Signal[];
+}
+/**
+ * Options for registering a task
+ */
+interface RegisterTaskOptions {
+    /** Auto-trigger agent turn on completion */
+    notify?: boolean;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+
+export type { AgentState, ProcessResult, RegisterTaskOptions, Signal, SignalType, Task, TaskEntry, TaskFilter, TaskInfo, TaskResult, TaskStatus, WaitCondition, WaitResult };

package/dist/types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Orchestration Types
+ *
+ * Core type definitions for the agent orchestration layer.
+ * Defines tasks, signals, wait conditions, and agent states.
+ */
+/**
+ * Task result from agent or process execution
+ */
+interface TaskResult {
+    success: boolean;
+    response?: string;
+    error?: string;
+    agentId?: string;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+}
+/**
+ * Process result from shell command execution
+ */
+interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    duration?: number;
+}
+/**
+ * Task types - discriminated union of different background task kinds
+ */
+type Task = {
+    type: 'agent';
+    taskId: string;
+    agentId: string;
+    taskDescription: string;
+    promise: Promise<TaskResult>;
+} | {
+    type: 'process';
+    taskId: string;
+    processId: string;
+    command: string;
+    promise: Promise<ProcessResult>;
+} | {
+    type: 'generic';
+    taskId: string;
+    description: string;
+    promise: Promise<unknown>;
+};
+/**
+ * Task lifecycle status
+ */
+type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Entry in the task registry tracking a background task
+ */
+interface TaskEntry {
+    task: Task;
+    status: TaskStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    result?: unknown;
+    error?: string;
+    /** If true, auto-trigger agent turn on completion */
+    notify?: boolean;
+    /** Timeout handle for this task (if set) */
+    timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+}
+/**
+ * Signal types - events that trigger state transitions
+ */
+type Signal = {
+    type: 'task:completed';
+    taskId: string;
+    result: unknown;
+} | {
+    type: 'task:failed';
+    taskId: string;
+    error: string;
+} | {
+    type: 'task:cancelled';
+    taskId: string;
+} | {
+    type: 'timeout';
+    conditionId: string;
+} | {
+    type: 'user:input';
+    content: string;
+    sessionId: string;
+} | {
+    type: 'external';
+    source: string;
+    data: unknown;
+};
+/**
+ * Extract signal type string
+ */
+type SignalType = Signal['type'];
+/**
+ * Wait conditions - composable conditions for suspension
+ */
+type WaitCondition = {
+    type: 'task';
+    taskId: string;
+} | {
+    type: 'any';
+    conditions: WaitCondition[];
+} | {
+    type: 'all';
+    conditions: WaitCondition[];
+} | {
+    type: 'timeout';
+    ms: number;
+    conditionId: string;
+} | {
+    type: 'race';
+    task: WaitCondition;
+    timeout: WaitCondition;
+};
+/**
+ * Agent loop states
+ */
+type AgentState = 'idle' | 'processing' | 'waiting';
+/**
+ * Task info returned by list/check operations (without internal promise)
+ */
+interface TaskInfo {
+    taskId: string;
+    type: Task['type'];
+    status: TaskStatus;
+    startedAt: Date;
+    completedAt?: Date;
+    duration?: number;
+    description?: string;
+    result?: unknown;
+    error?: string;
+    cancelReason?: string;
+}
+/**
+ * Filter options for listing tasks
+ */
+interface TaskFilter {
+    status?: TaskStatus | TaskStatus[];
+    type?: Task['type'];
+}
+/**
+ * Result from waiting on a condition
+ */
+interface WaitResult {
+    signal: Signal;
+    /** For 'all' conditions, contains all signals */
+    allSignals?: Signal[];
+}
+/**
+ * Options for registering a task
+ */
+interface RegisterTaskOptions {
+    /** Auto-trigger agent turn on completion */
+    notify?: boolean;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+
+export type { AgentState, ProcessResult, RegisterTaskOptions, Signal, SignalType, Task, TaskEntry, TaskFilter, TaskInfo, TaskResult, TaskStatus, WaitCondition, WaitResult };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dexto/orchestration",
+  "version": "1.5.8",
+  "description": "Agent orchestration layer for background task management, event-driven completion handling, and async workflows",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "dexto",
+    "orchestration",
+    "background-tasks",
+    "async",
+    "multi-agent",
+    "workflow"
+  ],
+  "dependencies": {
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}