Task Lists

import {
  tasklist, getTaskList, getTaskListByPlan,
  deriveTaskListStatus,
  taskListAgent, taskWorker,
  createTaskListTool,
} from '@crux/core/tasks'
import type {
  TaskList, TaskListStatus, TaskListHandle, CreateTaskListInput,
  Task, TaskStatus, TaskUpdate, CreateTaskInput,
  TaskListAgent, TaskListAgentOptions,
  TaskWorker, TaskWorkerOptions,
} from '@crux/core/tasks'

// Track work for a chat thread
const handle = await tasklist({
  metadata: { threadId: 'thread-abc' },
})

// Track a data processing pipeline
const handle = await tasklist({
  metadata: { pipelineId: 'etl-daily-2025-03-25' },
})

// Track user onboarding steps
const handle = await tasklist({
  metadata: { userId: 'user-123', flow: 'onboarding' },
})

const handle = await tasklist({ planId: p.id })
await handle.addTask({ id: 'research', label: 'Research sources' })
await handle.updateTask('research', { status: 'completed' })

// Standalone task list — no plan needed
const handle = await tasklist({
  metadata: { threadId: 'thread-abc', purpose: 'data-pipeline' },
})

## Tasks (2/4)
✓ Research sources — completed [researcher]
✓ Create outline — completed
⟳ Write draft — in_progress "Writing section 2 of 4..."
○ Review and polish — pending

## Your Assignment
**Task:** Write introduction (assigned to writer / claude-sonnet-4-20250514)
**Description:** Write a compelling introduction that hooks the reader
**Status:** pending

## Guidelines
- Call `startTask` when you begin working on this task.
- Use `reportProgress` to report what you are doing as you work.
- Call `completeTask` when finished, optionally providing a structured result.
- Call `failTask` if you encounter an unrecoverable issue, with an error message.

// Orchestrator dispatches work to multiple workers
for (const task of tasks) {
  const worker = taskWorker(taskList.id, task.id)

  const workerPrompt = prompt({
    use: [planAgent.asContext(), worker.asContext()],
    tools: worker.asTools(),
    system: 'Complete your assigned task.',
  })

  await generate(workerPrompt, { model: myModel, input: {} })
}

// Task list agent — custom task summary
const agent = taskListAgent(taskList.id, {
  renderContext: (tasks) => {
    const done = tasks.filter(t => t.status === 'completed').length
    return `<tasks progress="${done}/${tasks.length}">\n${tasks.map(t =>
      `  <task id="${t.id}" status="${t.status}">${t.label}</task>`
    ).join('\n')}\n</tasks>`
  },
})

// Task worker — custom assignment rendering
const worker = taskWorker(taskList.id, 'research', {
  renderContext: (task, allTasks) =>
    `You are working on: "${task.label}"\n` +
    `Overall progress: ${allTasks.filter(t => t.status === 'completed').length}/${allTasks.length} tasks done.`,
})

const worker = taskWorker(taskList.id, 'research', {
  guidelines: [
    'Start by calling `startTask`.',
    'Report findings as you discover them using `reportProgress`.',
    'When you have at least 5 sources, call `completeTask` with a JSON result.',
    'If no sources are found after exhaustive search, call `failTask`.',
  ].join('\n- '),
})

const { startTask, completeTask, ...rest } = worker.asTools()

const tools = {
  ...rest,
  startTask: {
    ...startTask,
    description: 'Signal that you are beginning the research phase.',
  },
  completeTask: {
    ...completeTask,
    description: 'Submit your research findings. Include a "sources" array in the result.',
  },
}

const agent = taskListAgent(taskList.id)

// Monitor only:
const { listTasks } = agent.asTools()

// Full management:
const tools = agent.asTools()
prompt({ tools })

const worker = taskWorker(taskList.id, 'write-intro')
prompt({
  use: [worker.asContext()],
  tools: worker.asTools(),
})

// Basic
const tools = { createTaskList: createTaskListTool() }

// With template
const tools = {
  createTaskList: createTaskListTool({
    template: 'Tasks should follow: research, draft, review, publish',
  }),
}

type TaskListStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'discarded'

type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped' | 'cancelled'

interface ToolDef {
  description: string
  parameters: z.ZodType
  execute: (args: Record<string, unknown>) => Promise<string>
}

interface CreateTaskListInput {
  planId?: string
  metadata?: Record<string, unknown>
}

interface CreateTaskInput {
  id: string        // user-provided meaningful ID
  label: string
  description?: string
  assignee?: { agent?: string; model?: string }
}

interface TaskUpdate {
  status?: TaskStatus
  progress?: string
  assignee?: { agent?: string; model?: string }
  result?: unknown
  error?: string
  durationMs?: number
}

1. tasklist()                  → list status: 'pending'
2. addTask('a')               → list status: 'pending'    (no task has started)
3. addTask('b')               → list status: 'pending'
4. updateTask('a', in_progress) → list status: 'in_progress' (a task started)
5. updateTask('a', completed)   → list status: 'in_progress' (b still pending)
6. updateTask('b', in_progress) → list status: 'in_progress'
7. updateTask('b', completed)   → list status: 'completed'   (all done!)

6. updateTask('b', failed)    → list status: 'failed'     (a task failed, none in_progress)

5. updateTask('b', failed)    → list status: 'in_progress' (a is still working)
6. updateTask('a', completed) → list status: 'failed'      (b failed, nothing in_progress)

import {
  tasklist,
  taskListAgent, taskWorker,
} from '@crux/core/tasks'

// 1. Create a task list (standalone or linked to a plan)
const handle = await tasklist({
  metadata: { purpose: 'blog-post-pipeline' },
})

// 2. Add tasks with meaningful IDs
await handle.addTask({ id: 'research', label: 'Research sources', assignee: { model: 'gpt-4.1' } })
await handle.addTask({ id: 'outline', label: 'Create outline' })
await handle.addTask({ id: 'write', label: 'Write draft' })
await handle.addTask({ id: 'review', label: 'Review and polish' })

// 3. Create agent handles for LLM integration
const taskListAgent = taskListAgent(handle.id)
const worker = taskWorker(handle.id, 'research')

// 4. Use in prompts
prompt({
  use: [worker.asContext()],
  tools: { ...worker.asTools(), ...taskListAgent.asTools() },
})