Tasks

A Task is the atomic unit of work in DevTeam Orchestrator. Each task sends a prompt to a model, optionally with context and tools, and returns a result.

createTask

Submit a new task for execution.

const task = await client.createTask(options: CreateTaskOptions): Promise<Task>;

Parameters

interface CreateTaskOptions {
  /** The prompt to send to the model. */
  prompt: string;
 
  /** Model to use. Default: client's defaultModel. */
  model?: string;
 
  /** Task queue to submit to. Default: client's defaultQueue. */
  queue?: string;
 
  /** System prompt / instructions. */
  systemPrompt?: string;
 
  /** Additional context passed to the model. */
  context?: Record<string, unknown>;
 
  /** Priority (1-10, higher = more urgent). Default: 5 */
  priority?: number;
 
  /** Task timeout in milliseconds. Default: 300000 (5 min) */
  timeoutMs?: number;
 
  /** Tags for filtering and organization. */
  tags?: string[];
 
  /** Callback URL for webhook notification on completion. */
  callbackUrl?: string;
 
  /** HITL configuration for this task. */
  hitl?: {
    required?: boolean;
    confidenceThreshold?: number;
    timeoutMs?: number;
  };
 
  /** Maximum tokens for the response. */
  maxTokens?: number;
 
  /** Temperature for model sampling (0-1). */
  temperature?: number;
 
  /** Parent plan execution ID (set automatically for plan steps). */
  planExecutionId?: string;
 
  /** Idempotency key to prevent duplicate submissions. */
  idempotencyKey?: string;
}

Example

const task = await client.createTask({
  prompt: 'Analyze this contract for liability risks and summarize findings.',
  model: 'opus',
  queue: 'gpu-queue',
  systemPrompt: 'You are a senior legal analyst specializing in commercial contracts.',
  context: {
    contractText: '...',
    jurisdiction: 'New York',
  },
  priority: 8,
  timeoutMs: 60_000,
  tags: ['legal', 'contract-review', 'high-priority'],
  maxTokens: 4096,
  temperature: 0.3,
});
 
console.log(task.id);     // 'dt_task_abc123'
console.log(task.status); // 'pending'

Return Value

interface Task {
  id: string;
  status: TaskStatus;
  model: string;
  queue: string;
  priority: number;
  tags: string[];
  createdAt: string;      // ISO 8601
  startedAt?: string;
  completedAt?: string;
  output?: string;
  error?: string;
  usage?: TokenUsage;
  metadata?: Record<string, unknown>;
}
 
type TaskStatus =
  | 'pending'
  | 'queued'
  | 'running'
  | 'completed'
  | 'failed'
  | 'cancelled'
  | 'awaiting_approval'
  | 'rejected';

getTaskStatus

Retrieve the current status of a task.

const status = await client.getTaskStatus(taskId: string): Promise<Task>;

Example

const task = await client.getTaskStatus('dt_task_abc123');
 
if (task.status === 'completed') {
  console.log('Output:', task.output);
  console.log('Tokens used:', task.usage);
} else if (task.status === 'failed') {
  console.error('Error:', task.error);
}

waitForTask

Block until a task reaches a terminal state (completed, failed, cancelled, or rejected).

const result = await client.waitForTask(
  taskId: string,
  options?: WaitOptions
): Promise<Task>;

Options

interface WaitOptions {
  /** Maximum time to wait in milliseconds. Default: 300000 (5 min) */
  timeoutMs?: number;
 
  /** Polling interval in milliseconds. Default: 1000 */
  pollIntervalMs?: number;
 
  /** Callback invoked on each poll with current status. */
  onProgress?: (task: Task) => void;
}

Example

const result = await client.waitForTask('dt_task_abc123', {
  timeoutMs: 60_000,
  pollIntervalMs: 2_000,
  onProgress: (task) => {
    console.log(`Status: ${task.status}`);
  },
});
 
console.log('Final output:', result.output);

If the task does not complete within timeoutMs, a TimeoutError is thrown. The task itself continues running on the server -- only the local wait is cancelled.

cancelTask

Cancel a pending or running task.

await client.cancelTask(taskId: string): Promise<void>;

Example

const task = await client.createTask({ prompt: 'Long running analysis...' });
 
// Cancel after 5 seconds
setTimeout(async () => {
  await client.cancelTask(task.id);
  console.log('Task cancelled');
}, 5_000);

⚠️

Cancelling a running task is best-effort. The worker may have already begun processing. Cancellation is guaranteed only for tasks in pending or queued state.

listTasks

List tasks with filtering and pagination.

const tasks = await client.listTasks(options?: ListTasksOptions): Promise<TaskList>;

Options

interface ListTasksOptions {
  status?: TaskStatus | TaskStatus[];
  model?: string;
  queue?: string;
  tags?: string[];
  createdAfter?: string;   // ISO 8601
  createdBefore?: string;  // ISO 8601
  limit?: number;          // Default: 20, max: 100
  offset?: number;
  orderBy?: 'createdAt' | 'completedAt' | 'priority';
  order?: 'asc' | 'desc';
}

Example

const { tasks, total } = await client.listTasks({
  status: ['completed', 'failed'],
  tags: ['legal'],
  limit: 50,
  orderBy: 'createdAt',
  order: 'desc',
});
 
console.log(`Found ${total} tasks`);
tasks.forEach((t) => console.log(t.id, t.status));

Batch Operations

createBatch

Submit multiple tasks at once:

const tasks = await client.createBatch([
  { prompt: 'Summarize document A', model: 'sonnet' },
  { prompt: 'Summarize document B', model: 'sonnet' },
  { prompt: 'Summarize document C', model: 'sonnet' },
]);
 
console.log(`Created ${tasks.length} tasks`);
// tasks[0].id, tasks[1].id, tasks[2].id

waitForBatch

Wait for all tasks in a batch:

const results = await client.waitForBatch(
  tasks.map((t) => t.id),
  { timeoutMs: 120_000 }
);
 
results.forEach((r) => {
  console.log(r.id, r.status, r.output?.slice(0, 100));
});

Next Steps

Plans & DAGs -- Chain tasks into workflows
Fan-Out -- Parallel task execution
HITL -- Human approval workflows

Client Plans & DAGs