digital-tasks 2.1.1 → 2.3.0

package/src/task.ts

@@ -11,6 +11,7 @@ import type {
   WorkerRef,
   TaskResult,
   TaskDependency,
+  TaskProgress,
 } from './types.js'
 import { taskQueue } from './queue.js'
 
@@ -27,7 +28,7 @@ function generateTaskId(): string {
  * @example
  * ```ts
  * const task = await createTask({
- *   function: {
+ *   tool: {
  *     type: 'generative',
  *     name: 'summarize',
  *     args: { text: 'The text to summarize' },
@@ -44,6 +45,14 @@ export async function createTask<TInput = unknown, TOutput = unknown>(
 ): Promise<Task<TInput, TOutput>> {
   const now = new Date()
 
+  // Resolve the underlying Tool from either `tool` (preferred) or
+  // the legacy `function` alias. Exactly one path is required; throw
+  // a clear error if neither is set so callers see this at runtime.
+  const tool = options.tool ?? options.function
+  if (!tool) {
+    throw new Error("createTask requires a 'tool' (preferred) or legacy 'function' option")
+  }
+
   // Convert string dependencies to TaskDependency array
   let dependencies: TaskDependency[] | undefined
   if (options.dependencies && options.dependencies.length > 0) {
@@ -54,10 +63,10 @@ export async function createTask<TInput = unknown, TOutput = unknown>(
     }))
   }
 
-  // Determine allowed workers from function type
+  // Determine allowed workers from the Tool's function type
   let allowedWorkers = options.allowedWorkers
   if (!allowedWorkers) {
-    const funcType = options.function.type
+    const funcType = tool.type
     if (funcType === 'human') {
       allowedWorkers = ['human']
     } else if (funcType === 'agentic') {
@@ -69,27 +78,70 @@ export async function createTask<TInput = unknown, TOutput = unknown>(
 
   const task: Task<TInput, TOutput> = {
     id: generateTaskId(),
-    function: options.function,
+    $type: 'Task',
+    // Action supertype: every Task is an Action of some Verb. Default
+    // the verb to the underlying Tool's name when not supplied.
+    verb: tool.name,
+    // Tool is the canonical field (CONTEXT.md). The legacy `function`
+    // alias is populated alongside for the duration of the deprecation
+    // window so older readers continue to work.
+    tool,
+    function: tool,
     status: options.scheduledFor ? 'pending' : 'queued',
     priority: options.priority || 'normal',
-    input: options.input,
     allowedWorkers,
-    dependencies,
-    scheduledFor: options.scheduledFor,
-    deadline: options.deadline,
-    timeout: options.timeout,
-    tags: options.tags,
-    parentId: options.parentId,
-    projectId: options.projectId,
-    metadata: options.metadata,
     createdAt: now,
     events: [],
   }
+  if (options.input !== undefined) {
+    task.input = options.input
+  }
+  if (dependencies !== undefined) {
+    task.dependencies = dependencies
+  }
+  if (options.scheduledFor !== undefined) {
+    task.scheduledFor = options.scheduledFor
+  }
+  if (options.deadline !== undefined) {
+    task.deadline = options.deadline
+  }
+  if (options.timeout !== undefined) {
+    task.timeout = options.timeout
+  }
+  if (options.tags !== undefined) {
+    task.tags = options.tags
+  }
+  if (options.parentId !== undefined) {
+    task.parentId = options.parentId
+  }
+  if (options.projectId !== undefined) {
+    task.projectId = options.projectId
+  }
+  if (options.metadata !== undefined) {
+    task.metadata = options.metadata
+  }
+  // Issue-shaped fields (SVO co-design)
+  if (options.title !== undefined) {
+    task.title = options.title
+  }
+  if (options.body !== undefined) {
+    task.body = options.body
+  }
+  if (options.labels !== undefined) {
+    task.labels = options.labels
+  }
+  if (options.project !== undefined) {
+    task.project = options.project
+  }
+  if (options.assignees !== undefined) {
+    task.assignees = options.assignees
+  }
 
-  // Auto-assign if specified
-  if (options.assignTo) {
+  // Auto-assign if specified (single primary worker takes precedence)
+  const primaryAssignee = options.assignTo ?? options.assignees?.[0]
+  if (primaryAssignee) {
     task.assignment = {
-      worker: options.assignTo,
+      worker: primaryAssignee,
       assignedAt: now,
     }
     task.status = 'assigned'
@@ -97,9 +149,7 @@ export async function createTask<TInput = unknown, TOutput = unknown>(
 
   // Check if blocked by dependencies
   if (dependencies && dependencies.length > 0) {
-    const hasPendingDeps = dependencies.some(
-      (d) => d.type === 'blocked_by' && !d.satisfied
-    )
+    const hasPendingDeps = dependencies.some((d) => d.type === 'blocked_by' && !d.satisfied)
     if (hasPendingDeps) {
       task.status = 'blocked'
     }
@@ -121,10 +171,7 @@ export async function getTask(id: string): Promise<AnyTask | undefined> {
 /**
  * Start working on a task
  */
-export async function startTask(
-  taskId: string,
-  worker: WorkerRef
-): Promise<AnyTask | undefined> {
+export async function startTask(taskId: string, worker: WorkerRef): Promise<AnyTask | undefined> {
   const task = await taskQueue.get(taskId)
   if (!task) return undefined
 
@@ -153,12 +200,15 @@ export async function updateProgress(
   percent: number,
   step?: string
 ): Promise<AnyTask | undefined> {
+  const progressUpdate: Partial<TaskProgress> = {
+    percent,
+    updatedAt: new Date(),
+  }
+  if (step !== undefined) {
+    progressUpdate.step = step
+  }
   return taskQueue.update(taskId, {
-    progress: {
-      percent,
-      step,
-      updatedAt: new Date(),
-    },
+    progress: progressUpdate,
     event: {
       type: 'progress',
       message: step || `Progress: ${percent}%`,
@@ -188,28 +238,27 @@ export async function completeTask<TOutput>(
 
   await taskQueue.complete(taskId, output)
 
+  const metadata: TaskResult<TOutput>['metadata'] = {
+    duration: task.startedAt ? Date.now() - task.startedAt.getTime() : 0,
+    startedAt: task.startedAt || new Date(),
+    completedAt: new Date(),
+  }
+  if (task.assignment?.worker !== undefined) {
+    metadata.worker = task.assignment.worker
+  }
+
   return {
     taskId,
     success: true,
     output,
-    metadata: {
-      duration: task.startedAt
-        ? Date.now() - task.startedAt.getTime()
-        : 0,
-      startedAt: task.startedAt || new Date(),
-      completedAt: new Date(),
-      worker: task.assignment?.worker,
-    },
+    metadata,
   }
 }
 
 /**
  * Fail a task with error
  */
-export async function failTask(
-  taskId: string,
-  error: string | Error
-): Promise<TaskResult> {
+export async function failTask(taskId: string, error: string | Error): Promise<TaskResult> {
   const task = await taskQueue.get(taskId)
   if (!task) {
     return {
@@ -226,6 +275,15 @@ export async function failTask(
 
   await taskQueue.fail(taskId, errorMessage)
 
+  const failMetadata: TaskResult['metadata'] = {
+    duration: task.startedAt ? Date.now() - task.startedAt.getTime() : 0,
+    startedAt: task.startedAt || new Date(),
+    completedAt: new Date(),
+  }
+  if (task.assignment?.worker !== undefined) {
+    failMetadata.worker = task.assignment.worker
+  }
+
   return {
     taskId,
     success: false,
@@ -234,24 +292,14 @@ export async function failTask(
       message: errorMessage,
       details: error instanceof Error ? { stack: error.stack } : undefined,
     },
-    metadata: {
-      duration: task.startedAt
-        ? Date.now() - task.startedAt.getTime()
-        : 0,
-      startedAt: task.startedAt || new Date(),
-      completedAt: new Date(),
-      worker: task.assignment?.worker,
-    },
+    metadata: failMetadata,
   }
 }
 
 /**
  * Cancel a task
  */
-export async function cancelTask(
-  taskId: string,
-  reason?: string
-): Promise<boolean> {
+export async function cancelTask(taskId: string, reason?: string): Promise<boolean> {
   const task = await taskQueue.get(taskId)
   if (!task) return false
 
@@ -274,13 +322,14 @@ export async function addComment(
   comment: string,
   author?: WorkerRef
 ): Promise<AnyTask | undefined> {
-  return taskQueue.update(taskId, {
-    event: {
-      type: 'comment',
-      actor: author,
-      message: comment,
-    },
-  })
+  const event: Omit<import('./types.js').TaskEvent, 'id' | 'timestamp'> = {
+    type: 'comment',
+    message: comment,
+  }
+  if (author !== undefined) {
+    event.actor = author
+  }
+  return taskQueue.update(taskId, { event })
 }
 
 /**
@@ -329,22 +378,37 @@ export async function waitForTask(
     }
 
     if (task.status === 'completed') {
+      const completedMeta: TaskResult['metadata'] = {
+        duration:
+          task.completedAt && task.startedAt
+            ? task.completedAt.getTime() - task.startedAt.getTime()
+            : 0,
+        startedAt: task.startedAt || task.createdAt,
+        completedAt: task.completedAt || new Date(),
+      }
+      if (task.assignment?.worker !== undefined) {
+        completedMeta.worker = task.assignment.worker
+      }
       return {
         taskId,
         success: true,
         output: task.output,
-        metadata: {
-          duration: task.completedAt && task.startedAt
-            ? task.completedAt.getTime() - task.startedAt.getTime()
-            : 0,
-          startedAt: task.startedAt || task.createdAt,
-          completedAt: task.completedAt || new Date(),
-          worker: task.assignment?.worker,
-        },
+        metadata: completedMeta,
       }
     }
 
     if (task.status === 'failed') {
+      const failedMeta: TaskResult['metadata'] = {
+        duration:
+          task.completedAt && task.startedAt
+            ? task.completedAt.getTime() - task.startedAt.getTime()
+            : 0,
+        startedAt: task.startedAt || task.createdAt,
+        completedAt: task.completedAt || new Date(),
+      }
+      if (task.assignment?.worker !== undefined) {
+        failedMeta.worker = task.assignment.worker
+      }
       return {
         taskId,
         success: false,
@@ -352,14 +416,7 @@ export async function waitForTask(
           code: 'TASK_FAILED',
           message: task.error || 'Task failed',
         },
-        metadata: {
-          duration: task.completedAt && task.startedAt
-            ? task.completedAt.getTime() - task.startedAt.getTime()
-            : 0,
-          startedAt: task.startedAt || task.createdAt,
-          completedAt: task.completedAt || new Date(),
-          worker: task.assignment?.worker,
-        },
+        metadata: failedMeta,
       }
     }
 

package/src/types.ts

@@ -1,9 +1,17 @@
 /**
  * Types for digital-tasks
  *
- * Task = Function + metadata (status, progress, assignment, dependencies)
+ * Task = Action + issue-shaped metadata (title, body, comments, labels,
+ * dependencies, assignees, project). A Task is a specialization of an
+ * `Action` (`digital-objects.Action`) with project-management overlay,
+ * per the SVO co-design (`docs/plans/2026-05-05-svo-co-design.md`).
  *
- * Every task is a function call. The function can be:
+ * Every task wraps a callable Verb — historically the `function` field
+ * (an `ai-functions.FunctionDefinition`). Per CONTEXT.md the canonical
+ * name for callable Verbs is **Tool**; `function` is being renamed to
+ * `tool` over time. See the `function` / `tool` fields below.
+ *
+ * The function (now Tool) can be:
  * - Code: generates executable code
  * - Generative: AI generates content (no tools)
  * - Agentic: AI with tools in a loop
@@ -19,6 +27,7 @@ import type {
   AgenticFunctionDefinition,
   HumanFunctionDefinition,
 } from 'ai-functions'
+import type { Action } from 'digital-objects'
 
 // Re-export function types for convenience
 export type {
@@ -29,6 +38,9 @@ export type {
   HumanFunctionDefinition,
 }
 
+// Re-export Action so consumers can see the supertype
+export type { Action }
+
 // ============================================================================
 // Task Status and Priority
 // ============================================================================
@@ -37,15 +49,15 @@ export type {
  * Task lifecycle status
  */
 export type TaskStatus =
-  | 'pending'      // Created but not started
-  | 'queued'       // In queue waiting for worker
-  | 'assigned'     // Assigned to a worker
-  | 'in_progress'  // Being worked on
-  | 'blocked'      // Waiting on dependency
-  | 'review'       // Awaiting review
-  | 'completed'    // Successfully finished
-  | 'failed'       // Failed with error
-  | 'cancelled'    // Cancelled
+  | 'pending' // Created but not started
+  | 'queued' // In queue waiting for worker
+  | 'assigned' // Assigned to a worker
+  | 'in_progress' // Being worked on
+  | 'blocked' // Waiting on dependency
+  | 'review' // Awaiting review
+  | 'completed' // Successfully finished
+  | 'failed' // Failed with error
+  | 'cancelled' // Cancelled
 
 /**
  * Task priority levels
@@ -89,11 +101,11 @@ export interface TaskAssignment {
  * Dependency type
  */
 export type DependencyType =
-  | 'blocks'       // This task blocks another
-  | 'blocked_by'   // This task is blocked by another
-  | 'related_to'   // Related but not blocking
-  | 'parent'       // Parent task
-  | 'child'        // Child subtask
+  | 'blocks' // This task blocks another
+  | 'blocked_by' // This task is blocked by another
+  | 'related_to' // Related but not blocking
+  | 'parent' // Parent task
+  | 'child' // Child subtask
 
 /**
  * Task dependency
@@ -125,7 +137,17 @@ export interface TaskProgress {
  */
 export interface TaskEvent {
   id: string
-  type: 'created' | 'assigned' | 'started' | 'progress' | 'blocked' | 'unblocked' | 'completed' | 'failed' | 'cancelled' | 'comment'
+  type:
+    | 'created'
+    | 'assigned'
+    | 'started'
+    | 'progress'
+    | 'blocked'
+    | 'unblocked'
+    | 'completed'
+    | 'failed'
+    | 'cancelled'
+    | 'comment'
   timestamp: Date
   actor?: WorkerRef
   data?: unknown
@@ -133,23 +155,101 @@ export interface TaskEvent {
 }
 
 // ============================================================================
-// Core Task Interface
+// Comments (issue-shaped child Actions)
 // ============================================================================
 
 /**
- * Task = Function + metadata
+ * Comment - a thin wrapper around a comment posted on a Task.
  *
- * A task wraps a function (code, generative, agentic, or human)
- * with lifecycle management, assignment, and dependencies.
+ * Per the SVO co-design, comments are child Actions of verb 'commented'
+ * whose `cause` role points back at the parent Task's Action id. This
+ * shape is the surfaced view of such an Action for issue-shaped UIs.
  */
-export interface Task<TInput = unknown, TOutput = unknown> {
-  /** Unique task ID */
+export interface Comment {
+  /** Comment id (matches the underlying Action id when persisted) */
   id: string
+  /** Markdown body of the comment */
+  body: string
+  /** Who posted the comment */
+  author?: WorkerRef
+  /** When the comment was posted */
+  createdAt: Date
+}
 
-  /** The function this task executes */
-  function: FunctionDefinition<TInput, TOutput>
+// ============================================================================
+// Core Task Interface
+// ============================================================================
 
-  /** Current status */
+/**
+ * Task = Action + issue-shaped metadata
+ *
+ * A Task is a specialization of `digital-objects.Action` carrying
+ * project-management overlay (title, body, comments, labels,
+ * dependencies, assignees, milestone/project). The Action supertype
+ * provides id/verb/subject/object/roles/data/createdAt/completedAt.
+ *
+ * Status: Action's status taxonomy is lifecycle-only
+ * (pending/active/completed/failed/cancelled). Task's status taxonomy
+ * is project-management shaped (queued/assigned/in_progress/blocked/
+ * review/...). We omit Action's `status` and replace it with the
+ * Task-specific `TaskStatus`. Both supersets share `pending`,
+ * `completed`, `failed`, `cancelled`.
+ *
+ * Verb: every Task is an Action of some Verb. For tasks created via
+ * the legacy `createTask({ function })` path, `verb` defaults to the
+ * function's name (e.g. `'summarize'`).
+ *
+ * Backward compatibility: all previously-valid Task shapes remain
+ * assignable. Newly added fields (title/body/labels/project/assignees/
+ * comments/$type/verb) are optional or have defaults populated by
+ * `createTask`.
+ */
+export type Task<TInput = unknown, TOutput = unknown> = Omit<Action<TInput>, 'status'> & {
+  /** MDXLD type discriminator */
+  $type?: 'Task'
+
+  /**
+   * The Tool (callable Verb) this task executes. This is the canonical
+   * field per CONTEXT.md. `createTask` always populates `tool`; the
+   * legacy `function` alias is also populated during the deprecation
+   * window so existing readers keep working.
+   *
+   * Optional on the type so that older literals constructed with only
+   * `function` still typecheck; in practice every Task has exactly one
+   * underlying callable Verb available via `task.tool ?? task.function`.
+   */
+  tool?: FunctionDefinition<TInput, TOutput>
+
+  /**
+   * Legacy alias for `tool`.
+   *
+   * @deprecated Use `tool` instead. The canonical name for callable
+   * Verbs is **Tool** (see CONTEXT.md). `createTask` continues to
+   * populate this alongside `tool` for the duration of the deprecation
+   * window. Slated for removal in the next major version.
+   */
+  function?: FunctionDefinition<TInput, TOutput>
+
+  /** Issue title (short, single-line) */
+  title?: string
+
+  /** Rich markdown body / description */
+  body?: string
+
+  /** GitHub-issue-shaped labels */
+  labels?: string[]
+
+  /** Milestone or project reference (string ref; cf. `projectId` for
+   *  the durable internal id when a `Project` exists in this package). */
+  project?: string
+
+  /** Comments posted on this task (child Actions of verb 'commented') */
+  comments?: Comment[]
+
+  /** Workers assigned to this task */
+  assignees?: WorkerRef[]
+
+  /** Current task status (specialization — see jsdoc above) */
   status: TaskStatus
 
   /** Priority level */
@@ -166,10 +266,10 @@ export interface Task<TInput = unknown, TOutput = unknown> {
   error?: string
 
   // Assignment
-  /** Who can work on this */
+  /** Worker types permitted to claim this task */
   allowedWorkers?: WorkerType[]
 
-  /** Current assignment */
+  /** Current assignment (single primary worker) */
   assignment?: TaskAssignment
 
   // Dependencies
@@ -181,9 +281,6 @@ export interface Task<TInput = unknown, TOutput = unknown> {
   progress?: TaskProgress
 
   // Timing
-  /** When created */
-  createdAt: Date
-
   /** Scheduled start time */
   scheduledFor?: Date
 
@@ -193,9 +290,6 @@ export interface Task<TInput = unknown, TOutput = unknown> {
   /** When started */
   startedAt?: Date
 
-  /** When completed */
-  completedAt?: Date
-
   /** Timeout in ms */
   timeout?: number
 
@@ -203,7 +297,8 @@ export interface Task<TInput = unknown, TOutput = unknown> {
   /** Parent task ID */
   parentId?: string
 
-  /** Project ID */
+  /** Project ID (internal `Project.id` when this Task belongs to a
+   *  Project in this package; distinct from `project` ref string) */
   projectId?: string
 
   // Metadata
@@ -217,6 +312,18 @@ export interface Task<TInput = unknown, TOutput = unknown> {
   events?: TaskEvent[]
 }
 
+/**
+ * Task dependency tuple — minimal shape from the SVO design doc.
+ *
+ * `TaskDependency` (above) is the richer in-package shape with a
+ * full DependencyType set; `TaskDep` is the issue-shaped pair from
+ * the design doc, retained as a convenience export.
+ */
+export interface TaskDep {
+  taskId: string
+  type: 'blocked_by' | 'related'
+}
+
 /**
  * Any task (for collections)
  */
@@ -231,7 +338,10 @@ export type AnyTask = Task<any, any>
  * Create task from a Code function
  */
 export interface CodeTaskOptions<TInput = unknown, TOutput = unknown> {
-  function: CodeFunctionDefinition<TInput, TOutput>
+  /** Tool (callable Verb) to run. Preferred over `function`. */
+  tool?: CodeFunctionDefinition<TInput, TOutput>
+  /** @deprecated Use `tool` instead. */
+  function?: CodeFunctionDefinition<TInput, TOutput>
   input?: TInput
   priority?: TaskPriority
   assignTo?: WorkerRef
@@ -246,7 +356,10 @@ export interface CodeTaskOptions<TInput = unknown, TOutput = unknown> {
  * Create task from a Generative function
  */
 export interface GenerativeTaskOptions<TInput = unknown, TOutput = unknown> {
-  function: GenerativeFunctionDefinition<TInput, TOutput>
+  /** Tool (callable Verb) to run. Preferred over `function`. */
+  tool?: GenerativeFunctionDefinition<TInput, TOutput>
+  /** @deprecated Use `tool` instead. */
+  function?: GenerativeFunctionDefinition<TInput, TOutput>
   input?: TInput
   priority?: TaskPriority
   assignTo?: WorkerRef
@@ -261,7 +374,10 @@ export interface GenerativeTaskOptions<TInput = unknown, TOutput = unknown> {
  * Create task from an Agentic function
  */
 export interface AgenticTaskOptions<TInput = unknown, TOutput = unknown> {
-  function: AgenticFunctionDefinition<TInput, TOutput>
+  /** Tool (callable Verb) to run. Preferred over `function`. */
+  tool?: AgenticFunctionDefinition<TInput, TOutput>
+  /** @deprecated Use `tool` instead. */
+  function?: AgenticFunctionDefinition<TInput, TOutput>
   input?: TInput
   priority?: TaskPriority
   assignTo?: WorkerRef
@@ -276,7 +392,10 @@ export interface AgenticTaskOptions<TInput = unknown, TOutput = unknown> {
  * Create task from a Human function
  */
 export interface HumanTaskOptions<TInput = unknown, TOutput = unknown> {
-  function: HumanFunctionDefinition<TInput, TOutput>
+  /** Tool (callable Verb) to run. Preferred over `function`. */
+  tool?: HumanFunctionDefinition<TInput, TOutput>
+  /** @deprecated Use `tool` instead. */
+  function?: HumanFunctionDefinition<TInput, TOutput>
   input?: TInput
   priority?: TaskPriority
   assignTo?: WorkerRef
@@ -289,13 +408,22 @@ export interface HumanTaskOptions<TInput = unknown, TOutput = unknown> {
 
 /**
  * Generic task creation options
+ *
+ * Either `tool` (preferred) or the deprecated `function` alias must be
+ * provided. `createTask` normalizes to `tool` and also populates the
+ * legacy `function` alias on the resulting Task for backward compat.
  */
 export interface CreateTaskOptions<TInput = unknown, TOutput = unknown> {
-  function: FunctionDefinition<TInput, TOutput>
+  /** Tool (callable Verb) to run. Preferred over `function`. */
+  tool?: FunctionDefinition<TInput, TOutput>
+  /** @deprecated Use `tool` instead. */
+  function?: FunctionDefinition<TInput, TOutput>
   input?: TInput
   priority?: TaskPriority
   allowedWorkers?: WorkerType[]
   assignTo?: WorkerRef
+  /** Multiple assignees (issue-shaped); first becomes the primary `assignment` */
+  assignees?: WorkerRef[]
   dependencies?: string[]
   scheduledFor?: Date
   deadline?: Date
@@ -304,6 +432,15 @@ export interface CreateTaskOptions<TInput = unknown, TOutput = unknown> {
   parentId?: string
   projectId?: string
   metadata?: Record<string, unknown>
+  // Issue-shaped fields (SVO co-design)
+  /** Issue title (short, single-line) */
+  title?: string
+  /** Rich markdown body / description */
+  body?: string
+  /** GitHub-issue-shaped labels */
+  labels?: string[]
+  /** Milestone or project ref string */
+  project?: string
 }
 
 /**