digital-tasks 2.1.3 → 2.3.0

package/src/client.ts

@@ -0,0 +1,268 @@
+/**
+ * RPC Client for digital-tasks
+ *
+ * Connects to a deployed digital-tasks worker via rpc.do,
+ * providing a fully typed client for remote task management.
+ *
+ * @example
+ * ```ts
+ * import { createTaskClient } from 'digital-tasks/client'
+ *
+ * const tasks = createTaskClient('https://digital-tasks.workers.dev')
+ * const task = await tasks.create({ name: 'My Task', description: 'Do something', priority: 'high' })
+ * await tasks.execute(task.id)
+ * await tasks.complete(task.id, { result: 'done' })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { RPC, http } from 'rpc.do'
+
+// ============================================================================
+// Types (mirrored from worker.ts for client-side use)
+// ============================================================================
+
+export type TaskStatus =
+  | 'pending'
+  | 'scheduled'
+  | 'queued'
+  | 'blocked'
+  | 'in_progress'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export type TaskPriority = 'low' | 'normal' | 'high' | 'urgent' | 'critical'
+
+export interface WorkerRef {
+  type: 'agent' | 'human' | 'team' | 'any'
+  id: string
+  name?: string
+}
+
+export interface TaskDependency {
+  type: 'blocked_by'
+  taskId: string
+  satisfied: boolean
+}
+
+export interface TaskProgress {
+  percent: number
+  step?: string
+  updatedAt: Date
+}
+
+export interface TaskAssignment {
+  worker: WorkerRef
+  assignedAt: Date
+}
+
+export interface TaskData<TInput = unknown, TOutput = unknown> {
+  id: string
+  name: string
+  description: string
+  status: TaskStatus
+  priority: TaskPriority
+  input?: TInput
+  output?: TOutput
+  error?: string
+  scheduledFor?: Date
+  deadline?: Date
+  createdAt: Date
+  startedAt?: Date
+  completedAt?: Date
+  progress?: TaskProgress
+  dependencies?: TaskDependency[]
+  assignment?: TaskAssignment
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateTaskOptions<TInput = unknown> {
+  id?: string
+  name: string
+  description: string
+  priority?: TaskPriority
+  input?: TInput
+  scheduledFor?: Date
+  deadline?: Date
+  tags?: string[]
+  metadata?: Record<string, unknown>
+  dependencies?: string[]
+}
+
+export interface ScheduleOptions {
+  priority?: TaskPriority
+}
+
+export interface ExecuteOptions {
+  worker?: WorkerRef
+}
+
+export interface ListOptions {
+  status?: TaskStatus | TaskStatus[]
+  priority?: TaskPriority
+  tags?: string[]
+  search?: string
+  sortBy?: 'createdAt' | 'priority'
+  sortOrder?: 'asc' | 'desc'
+  limit?: number
+  offset?: number
+}
+
+export interface EnqueueOptions {
+  delaySeconds?: number
+}
+
+export interface TaskStats {
+  total: number
+  byStatus: Record<string, number>
+  byPriority: Record<string, number>
+}
+
+// ============================================================================
+// TaskServiceAPI - the RPC interface for the client
+// ============================================================================
+
+/**
+ * The RPC API surface exposed by the digital-tasks worker.
+ *
+ * This interface mirrors the methods on TaskServiceCore (worker.ts)
+ * and is used to type the RPC client proxy.
+ */
+export interface TaskServiceAPI {
+  /** Create a new task */
+  create(options: CreateTaskOptions): Promise<TaskData>
+
+  /** Schedule a task for future execution */
+  schedule(taskId: string, scheduledFor: Date, options?: ScheduleOptions): Promise<TaskData>
+
+  /** Start task execution */
+  execute(taskId: string, options?: ExecuteOptions): Promise<TaskData>
+
+  /** Complete a task with output */
+  complete(taskId: string, output: unknown): Promise<TaskData>
+
+  /** Fail a task with error */
+  fail(taskId: string, error: string | Error): Promise<TaskData>
+
+  /** Get task status */
+  getStatus(taskId: string): Promise<TaskData | null>
+
+  /** Update task progress */
+  updateProgress(taskId: string, percent: number, step?: string): Promise<TaskData>
+
+  /** Cancel a task */
+  cancel(taskId: string, reason?: string): Promise<boolean>
+
+  /** List tasks with optional filtering */
+  list(options?: ListOptions): Promise<TaskData[]>
+
+  /** Get task statistics */
+  getStats(): Promise<TaskStats>
+
+  /** Retry a failed task */
+  retry(taskId: string): Promise<TaskData>
+
+  /** Get tasks that are ready for execution */
+  getReadyTasks(): Promise<TaskData[]>
+
+  /** Get tasks that depend on a given task */
+  getDependants(taskId: string): Promise<TaskData[]>
+
+  /** Enqueue a task for background processing */
+  enqueue(taskId: string, options?: EnqueueOptions): Promise<TaskData>
+
+  /** Dequeue and start the next task */
+  dequeue(): Promise<TaskData | null>
+
+  /** Execute a task with AI */
+  executeWithAI(taskId: string): Promise<TaskData>
+}
+
+// ============================================================================
+// Client Options
+// ============================================================================
+
+/**
+ * Options for creating a task client
+ */
+export interface TaskClientOptions {
+  /** Authentication token or API key */
+  token?: string
+  /** Custom headers to include with requests */
+  headers?: Record<string, string>
+}
+
+// ============================================================================
+// Client Factory
+// ============================================================================
+
+/** Default worker URL for digital-tasks */
+const DEFAULT_URL = 'https://digital-tasks.workers.dev'
+
+/**
+ * Create a typed RPC client for the digital-tasks worker.
+ *
+ * @param url - The URL of the deployed digital-tasks worker
+ * @param options - Optional configuration (auth token, custom headers)
+ * @returns A fully typed RPC client proxy
+ *
+ * @example
+ * ```ts
+ * import { createTaskClient } from 'digital-tasks/client'
+ *
+ * // Connect to a deployed worker
+ * const tasks = createTaskClient('https://digital-tasks.workers.dev')
+ *
+ * // Create and manage tasks
+ * const task = await tasks.create({
+ *   name: 'Analyze data',
+ *   description: 'Run data analysis pipeline',
+ *   priority: 'high',
+ * })
+ *
+ * // Execute the task
+ * await tasks.execute(task.id)
+ *
+ * // Track progress
+ * await tasks.updateProgress(task.id, 50, 'Processing...')
+ *
+ * // Complete with output
+ * await tasks.complete(task.id, { results: [1, 2, 3] })
+ *
+ * // List all completed tasks
+ * const completed = await tasks.list({ status: 'completed' })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With authentication
+ * const tasks = createTaskClient('https://digital-tasks.workers.dev', {
+ *   token: 'my-api-key',
+ * })
+ * ```
+ */
+export function createTaskClient(
+  url: string = DEFAULT_URL,
+  options?: TaskClientOptions
+): TaskServiceAPI {
+  return RPC<TaskServiceAPI>(http(url, options?.token))
+}
+
+/**
+ * Default task client connected to digital-tasks.workers.dev
+ *
+ * @example
+ * ```ts
+ * import client from 'digital-tasks/client'
+ *
+ * const task = await client.create({
+ *   name: 'Quick task',
+ *   description: 'A task using the default client',
+ * })
+ * ```
+ */
+const client: TaskServiceAPI = createTaskClient()
+
+export default client

package/src/index.ts

@@ -1,19 +1,21 @@
 /**
  * digital-tasks - Task management primitives for digital workers
  *
- * Task = Function + metadata (status, progress, assignment, dependencies)
+ * Task = Tool + metadata (status, progress, assignment, dependencies)
  *
- * Every task wraps a function (code, generative, agentic, or human)
- * with lifecycle management, worker assignment, and dependency tracking.
+ * Every task wraps a Tool (a callable Verb of type code, generative,
+ * agentic, or human) with lifecycle management, worker assignment, and
+ * dependency tracking. The `function` field is a deprecated alias for
+ * `tool` retained for backward compatibility.
  *
  * ## Quick Start
  *
  * ```ts
  * import { Task, createTask, taskQueue } from 'digital-tasks'
  *
- * // Create a task from a function
+ * // Create a task from a Tool
  * const task = await createTask({
- *   function: {
+ *   tool: {
  *     type: 'generative',
  *     name: 'summarize',
  *     args: { text: 'The text to summarize' },
@@ -79,13 +81,17 @@ export type {
   WorkerRef,
   WorkerType,
   TaskDependency,
+  TaskDep,
   DependencyType,
   TaskProgress,
   TaskEvent,
+  Comment,
   CreateTaskOptions,
   UpdateTaskOptions,
   TaskQuery,
   TaskQueueStats,
+  // Action supertype (re-exported from digital-objects)
+  Action,
   // Function types (re-exported from ai-functions)
   FunctionDefinition,
   CodeFunctionDefinition,
@@ -154,8 +160,4 @@ export {
 
 export type { SerializeOptions } from './markdown.js'
 
-export {
-  parseMarkdown,
-  toMarkdown,
-  syncStatusFromMarkdown,
-} from './markdown.js'
+export { parseMarkdown, toMarkdown, syncStatusFromMarkdown } from './markdown.js'

package/src/markdown.ts

@@ -49,6 +49,7 @@ import type {
   ParallelGroup,
   SequentialGroup,
   ExecutionMode,
+  CreateProjectOptions,
 } from './project.js'
 import { task, parallel, sequential, createProject } from './project.js'
 
@@ -61,8 +62,8 @@ import { task, parallel, sequential, createProject } from './project.js'
  */
 const STATUS_MARKERS: Record<string, TaskStatus> = {
   ' ': 'pending',
-  'x': 'completed',
-  'X': 'completed',
+  x: 'completed',
+  X: 'completed',
   '-': 'in_progress',
   '~': 'blocked',
   '!': 'failed',
@@ -93,7 +94,7 @@ const PRIORITY_MARKERS: Record<string, TaskPriority> = {
   '!': 'urgent',
   '^': 'high',
   '': 'normal',
-  'v': 'low',
+  v: 'low',
 }
 
 // ============================================================================
@@ -135,20 +136,23 @@ function parseLine(line: string): ParsedLine {
   const raw = line
 
   // Count leading spaces for indent (2 spaces = 1 level)
-  const leadingSpaces = line.match(/^(\s*)/)?.[1].length || 0
+  const leadingSpacesMatch = line.match(/^(\s*)/)
+  const leadingSpaces = leadingSpacesMatch?.[1]?.length ?? 0
   const indent = Math.floor(leadingSpaces / 2)
   const trimmed = line.slice(leadingSpaces)
 
   // Check for heading
   const headingMatch = trimmed.match(/^(#{1,6})\s+(.+)$/)
   if (headingMatch) {
+    const matchedHashes = headingMatch[1]!
+    const matchedTitle = headingMatch[2]!
     return {
       indent,
       isTask: false,
       isOrdered: false,
-      title: headingMatch[2].trim(),
+      title: matchedTitle.trim(),
       isHeading: true,
-      headingLevel: headingMatch[1].length,
+      headingLevel: matchedHashes.length,
       raw,
     }
   }
@@ -156,8 +160,8 @@ function parseLine(line: string): ParsedLine {
   // Check for unordered task: - [ ] or - [x] etc.
   const unorderedMatch = trimmed.match(/^[-*]\s+\[([^\]]*)\]\s*(.*)$/)
   if (unorderedMatch) {
-    const marker = unorderedMatch[1]
-    let title = unorderedMatch[2].trim()
+    const marker = unorderedMatch[1]!
+    let title = unorderedMatch[2]!.trim()
     let priority: TaskPriority = 'normal'
 
     // Check for priority marker at start of title
@@ -179,7 +183,7 @@ function parseLine(line: string): ParsedLine {
       indent,
       isTask: true,
       isOrdered: false,
-      status: STATUS_MARKERS[marker] || 'pending',
+      status: STATUS_MARKERS[marker] ?? 'pending',
       priority,
       title,
       isHeading: false,
@@ -190,8 +194,9 @@ function parseLine(line: string): ParsedLine {
   // Check for ordered task: 1. [ ] or 1. [x] etc.
   const orderedMatch = trimmed.match(/^(\d+)\.\s+\[([^\]]*)\]\s*(.*)$/)
   if (orderedMatch) {
-    const marker = orderedMatch[2]
-    let title = orderedMatch[3].trim()
+    const orderNum = orderedMatch[1]!
+    const marker = orderedMatch[2]!
+    let title = orderedMatch[3]!.trim()
     let priority: TaskPriority = 'normal'
 
     // Check for priority marker
@@ -213,8 +218,8 @@ function parseLine(line: string): ParsedLine {
       indent,
       isTask: true,
       isOrdered: true,
-      orderNumber: parseInt(orderedMatch[1], 10),
-      status: STATUS_MARKERS[marker] || 'pending',
+      orderNumber: parseInt(orderNum, 10),
+      status: STATUS_MARKERS[marker] ?? 'pending',
       priority,
       title,
       isHeading: false,
@@ -247,7 +252,7 @@ function parseTasksAtIndent(
   let modeSet = false
 
   while (index < lines.length) {
-    const line = lines[index]
+    const line = lines[index]!
 
     // Stop if we've gone back to a lower indent level
     if (line.indent < baseIndent && (line.isTask || line.isHeading)) {
@@ -269,20 +274,21 @@ function parseTasksAtIndent(
       }
 
       // Parse subtasks
-      const { tasks: subtasks, nextIndex } = parseTasksAtIndent(
-        lines,
-        index + 1,
-        baseIndent + 1
-      )
-
-      const taskDef = task(line.title, {
-        priority: line.priority,
-        subtasks: subtasks.length > 0 ? subtasks : undefined,
+      const { tasks: subtasks, nextIndex } = parseTasksAtIndent(lines, index + 1, baseIndent + 1)
+
+      const taskOptions: Partial<Omit<TaskDefinition, '__type' | 'title'>> = {
         metadata: {
           _originalStatus: line.status,
           _lineNumber: index,
         },
-      })
+      }
+      if (line.priority !== undefined) {
+        taskOptions.priority = line.priority
+      }
+      if (subtasks.length > 0) {
+        taskOptions.subtasks = subtasks
+      }
+      const taskDef = task(line.title, taskOptions)
 
       tasks.push(taskDef)
       index = nextIndex
@@ -324,9 +330,9 @@ export function parseMarkdown(markdown: string): Project {
   const allTasks: TaskNode[] = []
 
   // Find project name from first h1
-  const h1Index = lines.findIndex(l => l.isHeading && l.headingLevel === 1)
+  const h1Index = lines.findIndex((l) => l.isHeading && l.headingLevel === 1)
   if (h1Index !== -1) {
-    projectName = lines[h1Index].title
+    projectName = lines[h1Index]!.title
   }
 
   // Process sections and tasks
@@ -334,7 +340,7 @@ export function parseMarkdown(markdown: string): Project {
   let index = 0
 
   while (index < lines.length) {
-    const line = lines[index]
+    const line = lines[index]!
 
     // New section (h2)
     if (line.isHeading && line.headingLevel === 2) {
@@ -353,7 +359,7 @@ export function parseMarkdown(markdown: string): Project {
 
       const modeMatch = sectionName.match(/\((parallel|sequential)\)\s*$/i)
       if (modeMatch) {
-        sectionMode = modeMatch[1].toLowerCase() as ExecutionMode
+        sectionMode = modeMatch[1]!.toLowerCase() as ExecutionMode
         sectionName = sectionName.replace(/\s*\((parallel|sequential)\)\s*$/i, '')
       }
 
@@ -396,11 +402,15 @@ export function parseMarkdown(markdown: string): Project {
     }
   }
 
-  return createProject({
+  const projectOptions: CreateProjectOptions = {
     name: projectName,
-    description: projectDescription,
     tasks: allTasks,
-  })
+  }
+  if (projectDescription !== undefined) {
+    projectOptions.description = projectDescription
+  }
+
+  return createProject(projectOptions)
 }
 
 // ============================================================================
@@ -435,13 +445,13 @@ function serializeTaskNode(
 
   if (node.__type === 'task') {
     const taskDef = node as TaskDefinition
-    const status = (taskDef.metadata?._originalStatus as TaskStatus) || 'pending'
+    const status = (taskDef.metadata?.['_originalStatus'] as TaskStatus) || 'pending'
     const marker = options.includeStatus !== false ? STATUS_TO_MARKER[status] : ' '
 
     let prefix: string
     if (isSequential) {
       // Use numbered list for sequential
-      const num = (taskDef.metadata?._sequenceNumber as number) || 1
+      const num = (taskDef.metadata?.['_sequenceNumber'] as number) || 1
       prefix = `${num}. [${marker}]`
     } else {
       // Use bullet for parallel
@@ -450,11 +460,16 @@ function serializeTaskNode(
 
     let title = taskDef.title
     if (options.includePriority && taskDef.priority && taskDef.priority !== 'normal') {
-      const priorityMarker = taskDef.priority === 'critical' ? '!!'
-        : taskDef.priority === 'urgent' ? '!'
-        : taskDef.priority === 'high' ? '^'
-        : taskDef.priority === 'low' ? 'v'
-        : ''
+      const priorityMarker =
+        taskDef.priority === 'critical'
+          ? '!!'
+          : taskDef.priority === 'urgent'
+          ? '!'
+          : taskDef.priority === 'high'
+          ? '^'
+          : taskDef.priority === 'low'
+          ? 'v'
+          : ''
       title = `${priorityMarker}${title}`
     }
 
@@ -471,7 +486,7 @@ function serializeTaskNode(
     let seqNum = 1
     for (const child of group.tasks) {
       if (child.__type === 'task') {
-        (child as TaskDefinition).metadata = {
+        ;(child as TaskDefinition).metadata = {
           ...(child as TaskDefinition).metadata,
           _sequenceNumber: seqNum++,
         }
@@ -483,7 +498,7 @@ function serializeTaskNode(
     let seqNum = 1
     for (const child of group.tasks) {
       if (child.__type === 'task') {
-        (child as TaskDefinition).metadata = {
+        ;(child as TaskDefinition).metadata = {
           ...(child as TaskDefinition).metadata,
           _sequenceNumber: seqNum++,
         }
@@ -558,10 +573,7 @@ export function toMarkdown(project: Project, options: SerializeOptions = {}): st
  * Update task statuses in a project from markdown
  * (Useful for syncing when markdown is edited externally)
  */
-export function syncStatusFromMarkdown(
-  project: Project,
-  markdown: string
-): Project {
+export function syncStatusFromMarkdown(project: Project, markdown: string): Project {
   const parsed = parseMarkdown(markdown)
 
   // Build a map of task titles to statuses from parsed markdown
@@ -570,7 +582,7 @@ export function syncStatusFromMarkdown(
   function collectStatuses(node: TaskNode) {
     if (node.__type === 'task') {
       const taskDef = node as TaskDefinition
-      const status = taskDef.metadata?._originalStatus as TaskStatus
+      const status = taskDef.metadata?.['_originalStatus'] as TaskStatus
       if (status) {
         statusMap.set(taskDef.title, status)
       }
@@ -590,14 +602,17 @@ export function syncStatusFromMarkdown(
     if (node.__type === 'task') {
       const taskDef = node as TaskDefinition
       const newStatus = statusMap.get(taskDef.title)
-      return {
+      const result: TaskDefinition = {
         ...taskDef,
         metadata: {
           ...taskDef.metadata,
-          _originalStatus: newStatus || taskDef.metadata?._originalStatus,
+          _originalStatus: newStatus || taskDef.metadata?.['_originalStatus'],
         },
-        subtasks: taskDef.subtasks?.map(updateStatuses),
       }
+      if (taskDef.subtasks) {
+        result.subtasks = taskDef.subtasks.map(updateStatuses)
+      }
+      return result
     } else if (node.__type === 'parallel') {
       const group = node as ParallelGroup
       return {