Using Tasks

Create and manage structured work items (bugs, features, epics, tasks) with built-in status tracking, comments, tags, and file attachments. The task service is available via ctx.task in agents and c.var.task in routes.

For concepts, hierarchical task patterns, and when-to-use guidance, see Tasks.

Task Lifecycle

Tasks follow a defined status lifecycle:

The aliases 'started', 'completed', and 'closed' are normalized automatically to 'in_progress' or 'done'.

create(params)

Create a new task.

CreateTaskParams fields:

Returns: Promise<Task>

Example

const task = await ctx.task.create({
  title: 'Investigate slow API response times',
  type: 'bug',
  priority: 'high',
  created_id: 'user-001',
  creator: { id: 'user-001', name: 'Monitor Agent', type: 'agent' },
  description: 'P95 latency exceeded 500ms on /api/search',
  metadata: { endpoint: '/api/search', p95ms: 520 },
});
 
ctx.logger.info('Created task %s: %s', task.id, task.title);

get(id)

Get a task by its ID.

Returns: Promise<Task | null> -- null if the task does not exist.

Example

const task = await ctx.task.get('tsk_abc123');
if (task) {
  ctx.logger.info('Task %s is %s (priority: %s)', task.id, task.status, task.priority);
}

list(params?)

List tasks with optional filtering and pagination.

ListTasksParams fields (all optional):

Returns: Promise<ListTasksResult>

interface ListTasksResult {
  tasks: Task[];   // Matching tasks
  total: number;   // Total count before pagination
  limit: number;   // Applied limit
  offset: number;  // Applied offset
}

Example

// List open bugs assigned to an agent
const result = await ctx.task.list({
  status: 'open',
  type: 'bug',
  assigned_id: 'agent-001',
  sort: '-priority',
  limit: 20,
});
 
ctx.logger.info('Found %d of %d bugs', result.tasks.length, result.total);

update(id, params)

Partially update an existing task. Only provided fields are changed.

Returns: Promise<Task>

Example

const updated = await ctx.task.update('tsk_abc123', {
  status: 'in_progress',
  assignee: { id: 'agent-002', name: 'Fix Bot', type: 'agent' },
  priority: 'high',
});
 
ctx.logger.info('Task updated, status: %s', updated.status);

close(id)

Close a task by setting its status to 'done' and recording the closed date.

Returns: Promise<Task>

Example

const closed = await ctx.task.close('tsk_abc123');
ctx.logger.info('Task closed at %s', closed.closed_date);

softDelete(id)

Soft-delete a task, marking it as deleted without permanent removal.

Returns: Promise<Task>

batchDelete(params)

Batch soft-delete tasks matching the given filters. At least one filter must be provided.

BatchDeleteTasksParams fields (all optional, but at least one required):

Returns: Promise<BatchDeleteTasksResult>

interface BatchDeleteTasksResult {
  deleted: { id: string; title: string }[];
  count: number;
}

Example

const result = await ctx.task.batchDelete({
  status: 'cancelled',
  older_than: '4w',
  limit: 100,
});
 
ctx.logger.info('Deleted %d cancelled tasks', result.count);

batchUpdate(params)

Batch update tasks matching the given filters. At least one filter or ids value must be provided, and at least one update field must be provided.

Common fields:

Returns: Promise<BatchUpdateTasksResult>

interface BatchUpdateTasksResult {
  updated: { id: string; title: string; status: TaskStatus; priority: TaskPriority }[];
  count: number;
  dry_run: boolean;
}

batchClose(params)

Batch close tasks matching the given filters by setting their status to 'done' and recording the closed date. At least one filter or ids value must be provided.

Common fields:

Returns: Promise<BatchCloseTasksResult>

interface BatchCloseTasksResult {
  closed: { id: string; title: string; status: TaskStatus; closed_date?: string }[];
  count: number;
  dry_run: boolean;
}

Comments

createComment(taskId, body, userId, author?)

Add a comment to a task.

Returns: Promise<Comment>

Example

const comment = await ctx.task.createComment(
  'tsk_abc123',
  'Root cause identified: missing index on search_queries table',
  'agent-001',
  { id: 'agent-001', name: 'Debug Agent' }
);

listComments(taskId, params?)

List comments on a task with optional pagination.

Returns: Promise<ListCommentsResult> with comments, total, limit, offset.

getComment(commentId)

Get a comment by its ID. Returns: Promise<Comment>

updateComment(commentId, body)

Update a comment's text. Returns: Promise<Comment>

deleteComment(commentId)

Delete a comment. Returns: Promise<void>

Tags

createTag(name, color?)

Create a new tag for categorizing tasks.

Returns: Promise<Tag>

listTags()

List all tags in the organization. Returns: Promise<ListTagsResult> with a tags array.

addTagToTask(taskId, tagId)

Associate a tag with a task. Returns: Promise<void>

removeTagFromTask(taskId, tagId)

Remove a tag from a task. Returns: Promise<void>

listTagsForTask(taskId)

List all tags on a specific task. Returns: Promise<Tag[]>

getTag(tagId) / updateTag(tagId, name, color?) / deleteTag(tagId)

CRUD operations on individual tags.

Attachments

uploadAttachment(taskId, params)

Initiate a file upload. Returns a presigned S3 URL for direct upload.

CreateAttachmentParams fields:

Returns: Promise<PresignUploadResponse>

interface PresignUploadResponse {
  attachment: Attachment;    // The created attachment record
  presigned_url: string;     // PUT this URL to upload the file
  expiry_seconds: number;    // Seconds until the URL expires
}

confirmAttachment(attachmentId)

Confirm that a file upload completed successfully. Returns: Promise<Attachment>

downloadAttachment(attachmentId)

Get a presigned download URL. Returns: Promise<PresignDownloadResponse>

listAttachments(taskId)

List all attachments on a task. Returns: Promise<ListAttachmentsResult>

deleteAttachment(attachmentId)

Delete an attachment. Returns: Promise<void>

Changelog and Activity

changelog(id, params?)

Get the audit trail for a task, showing field-level changes.

Returns: Promise<TaskChangelogResult> with changelog entries, total, limit, offset.

getActivity(params?)

Get task activity time-series data showing daily status counts.

Returns: Promise<TaskActivityResult> with daily data points containing open, inProgress, done, and cancelled counts.

Entity Management

createUser(params) / getUser(userId) / deleteUser(userId)

Manage user entities (human or agent) that can be assigned to tasks.

createProject(params) / getProject(projectId) / deleteProject(projectId)

Manage project entities for organizing tasks.

listUsers() / listProjects()

List all user and project entities referenced in tasks.