lobehub/packages/database/src/models/task.ts
Arvin Xu 093fa7bcae
feat: support agent tasks system (#13289)
*  feat: agent task system — CLI, review rubrics, workspace, comments, brief tool split

support import md

Major changes:
- Split task CLI into modular files (task/, lifecycle, topic, doc, review, checkpoint, dep)
- Split builtin-tool-task into task + brief tools (conditional injection)
- Task review uses EvalBenchmarkRubric from @lobechat/eval-rubric
- Task workspace: documents auto-pin via Notebook, tree view with folders
- Task comments system (task_comments table)
- Task topics: dedicated TaskTopicModel with userId, handoff fields, review results
- Heartbeat timeout auto-detection in detail API
- Run idempotency (reject duplicate runs) + error rollback
- Topic cancel/delete by topicId only (no taskId needed)
- Integration tests for task router (13 tests)
- interruptOperation fix (string param, not object)
- Global TRPC error handler in CLI

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

task document workflow

task handoff loop

🗃️ chore: consolidate task system migrations into single 0095

Merged 7 separate migrations (0095-0101) into one:
- tasks, briefs, task_comments, task_dependencies, task_documents, task_topics tables
- All fields including sort_order, resolved_action/comment, review fields
- Idempotent CREATE TABLE IF NOT EXISTS, DROP/ADD CONSTRAINT, CREATE INDEX IF NOT EXISTS

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix interruptOperation

topic auto review workflow

topic handoff workflow

finish run topic and brief workflow

support task tool

improve task schema

update

 feat: add onComplete hook to task.run for completion callbacks

When agent execution completes, the hook:
- Updates task heartbeat
- Creates a result Brief (on success) with assistant content summary
- Creates an error Brief (on failure) with error message
- Supports both local (handler) and production (webhook) modes

Uses the new Agent Runtime Hooks system instead of raw stepCallbacks.

LOBE-6160 LOBE-6208

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add Review system — LLM-as-Judge automated review

Task review uses an independent LLM call to evaluate topic output
quality against configurable criteria with pass/fail thresholds.

- TaskReviewService: structured LLM review via generateObject,
  auto-resolves model/provider from user's system agent defaults
- Model: getReviewConfig, updateReviewConfig on TaskModel
- Router: getReview, updateReview, runReview procedures
- CLI: `task review set/view/run` commands
- Auto-creates Brief with review results

LOBE-6165

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add TaskScheduler, multi-topic execution, and handoff context

- TaskScheduler: interface + Local implementation (setTimeout-based),
  following QueueService dual-mode pattern
- Multi-topic execution: `task run --topics N --delay S` runs N topics
  in sequence with optional delay between them
- Handoff context: buildTaskPrompt() queries previous topics by
  metadata.taskId and injects handoff summaries into the next topic's
  prompt (sliding window: latest full, older summaries only)
- Heartbeat auto-update between topics

LOBE-6161

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add Heartbeat watchdog + heartbeat CLI

Watchdog scans running tasks with expired heartbeats, marks them as
failed, and creates urgent error Briefs. Heartbeat CLI allows manual
heartbeat reporting for testing.

- Model: refactored to use Drizzle operators (isNull, isNotNull, ne)
  instead of raw SQL where possible; fixed findStuckTasks to skip
  tasks without heartbeat data
- Router: heartbeat (manual report), watchdog (scan + fail + brief)
- Router: updateSchema now includes heartbeatInterval, heartbeatTimeout
- CLI: `task heartbeat <id>`, `task watchdog`, `task edit` with
  --heartbeat-timeout, --heartbeat-interval, --description

LOBE-6161

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

♻️ refactor: move CheckpointConfig to @lobechat/types

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add task run — trigger agent execution for tasks

Task.run creates a topic, triggers AiAgentService.execAgent with task
context, and streams results via SSE. Supports both agentId and slug.

- Service: added taskId to ExecAgentParams, included in topic metadata
- Router: task.run procedure — resolves agent, builds prompt, calls execAgent,
  updates topic count and heartbeat
- CLI: `task run <id>` command with SSE streaming, --prompt, --verbose

LOBE-6160

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add Checkpoint system for task review gates

Checkpoint allows configuring pause points in task execution flow.
Supports beforeIds (pause before subtask starts) and afterIds (pause
after subtask completes) on parent tasks.

- Model: CheckpointConfig type, getCheckpointConfig, updateCheckpointConfig,
  shouldPauseBeforeStart, shouldPauseAfterComplete
- Router: getCheckpoint, updateCheckpoint procedures; integrated with
  updateStatus for automatic checkpoint triggering
- CLI: `task checkpoint view/set` commands with --before, --after,
  --topic-before, --topic-after, --on-agent-request options
- Tests: 3 new checkpoint tests (37 total)

LOBE-6162

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add dependency unlocking on task completion

When a task completes, automatically check and unlock blocked tasks
whose dependencies are all satisfied (backlog → running). Also notify
when all subtasks of a parent are completed.

- Model: getUnlockedTasks, areAllSubtasksCompleted (Drizzle, no raw SQL)
- Router: updateStatus hook triggers unlocking on completion
- CLI: shows unlocked tasks and parent completion notification
- Tests: 3 new tests (34 total)

LOBE-6164

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add Brief system — schema, model, router, CLI

Brief is a universal Agent-to-User reporting mechanism, not limited to
Tasks. CronJobs, Agents, and future systems can all produce Briefs.

- Schema: briefs table with polymorphic source (taskId, cronJobId, agentId)
- Model: BriefModel with CRUD, listUnresolved (Daily Brief), markRead, resolve
- Router: TRPC brief router with taskId identifier resolution
- CLI: `lh brief` command (list/view/read/resolve)
- Tests: 11 model tests
- Migration: 0096_add_briefs_table.sql

LOBE-6163

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

 feat: add Task system — schema, model, router, CLI

Implement the foundational Task system for managing long-running,
multi-topic agent tasks with subtask trees and dependency chains.

- Schema: tasks, task_dependencies, task_documents tables
- Model: TaskModel with CRUD, tree queries, heartbeat, dependencies, document pinning
- Router: TRPC task router with identifier/id resolution
- CLI: `lh task` command (list/view/create/edit/delete/start/pause/resume/complete/cancel/tree/dep)
- Tests: 31 model tests
- Migration: 0095_add_task_tables.sql

LOBE-6036 LOBE-6054

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* update

* 🐛 fix: update brief model import path and add raw-md vitest plugin

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: eslint import sort in vitest config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: brief ID validation, auto-review retry, and continueTopicId operationId

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: task integration tests — create test agent for FK, fix children spread

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: task integration tests — correct identifier prefix and agent ID

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: remove unused toolsActivatorRuntime import

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: create real topic in task integration tests to satisfy FK constraint

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: type errors in task prompt tests, handoff schema, and activity mapping

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix: create real agent/topic/brief records in database model tests for FK constraints

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 17:43:51 +08:00

523 lines
16 KiB
TypeScript

import type {
CheckpointConfig,
WorkspaceData,
WorkspaceDocNode,
WorkspaceTreeNode,
} from '@lobechat/types';
import { and, desc, eq, inArray, isNotNull, isNull, ne, sql } from 'drizzle-orm';
import type { NewTask, NewTaskComment, TaskCommentItem, TaskItem } from '../schemas/task';
import { taskComments, taskDependencies, taskDocuments, tasks } from '../schemas/task';
import type { LobeChatDatabase } from '../type';
export class TaskModel {
private readonly userId: string;
private readonly db: LobeChatDatabase;
constructor(db: LobeChatDatabase, userId: string) {
this.db = db;
this.userId = userId;
}
// ========== CRUD ==========
async create(
data: Omit<NewTask, 'id' | 'identifier' | 'seq' | 'createdByUserId'> & {
identifierPrefix?: string;
},
): Promise<TaskItem> {
const { identifierPrefix = 'T', ...rest } = data;
// Retry loop to handle concurrent creates (parallel tool calls)
const maxRetries = 5;
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
// Get next seq for this user
const seqResult = await this.db
.select({ maxSeq: sql<number>`COALESCE(MAX(${tasks.seq}), 0)` })
.from(tasks)
.where(eq(tasks.createdByUserId, this.userId));
const nextSeq = Number(seqResult[0].maxSeq) + 1;
const identifier = `${identifierPrefix}-${nextSeq}`;
const result = await this.db
.insert(tasks)
.values({
...rest,
createdByUserId: this.userId,
identifier,
seq: nextSeq,
} as NewTask)
.returning();
return result[0];
} catch (error: any) {
// Retry on unique constraint violation (concurrent seq conflict)
// Check error itself, cause, and stringified message for PG error code 23505
const errStr =
String(error?.message || '') +
String(error?.cause?.code || '') +
String(error?.code || '');
const isUniqueViolation =
errStr.includes('23505') || errStr.includes('unique') || errStr.includes('duplicate');
if (isUniqueViolation && attempt < maxRetries - 1) {
continue;
}
throw error;
}
}
throw new Error('Failed to create task after max retries');
}
async findById(id: string): Promise<TaskItem | null> {
const result = await this.db
.select()
.from(tasks)
.where(and(eq(tasks.id, id), eq(tasks.createdByUserId, this.userId)))
.limit(1);
return result[0] || null;
}
async findByIds(ids: string[]): Promise<TaskItem[]> {
if (ids.length === 0) return [];
return this.db
.select()
.from(tasks)
.where(and(inArray(tasks.id, ids), eq(tasks.createdByUserId, this.userId)));
}
// Resolve id or identifier (e.g. 'T-1') to a task
async resolve(idOrIdentifier: string): Promise<TaskItem | null> {
if (idOrIdentifier.startsWith('task_')) return this.findById(idOrIdentifier);
return this.findByIdentifier(idOrIdentifier.toUpperCase());
}
async findByIdentifier(identifier: string): Promise<TaskItem | null> {
const result = await this.db
.select()
.from(tasks)
.where(and(eq(tasks.identifier, identifier), eq(tasks.createdByUserId, this.userId)))
.limit(1);
return result[0] || null;
}
async update(
id: string,
data: Partial<Omit<NewTask, 'id' | 'identifier' | 'seq' | 'createdByUserId'>>,
): Promise<TaskItem | null> {
const result = await this.db
.update(tasks)
.set({ ...data, updatedAt: new Date() })
.where(and(eq(tasks.id, id), eq(tasks.createdByUserId, this.userId)))
.returning();
return result[0] || null;
}
async delete(id: string): Promise<boolean> {
const result = await this.db
.delete(tasks)
.where(and(eq(tasks.id, id), eq(tasks.createdByUserId, this.userId)))
.returning();
return result.length > 0;
}
async deleteAll(): Promise<number> {
const result = await this.db
.delete(tasks)
.where(eq(tasks.createdByUserId, this.userId))
.returning();
return result.length;
}
// ========== Query ==========
async list(options?: {
assigneeAgentId?: string;
limit?: number;
offset?: number;
parentTaskId?: string | null;
status?: string;
}): Promise<{ tasks: TaskItem[]; total: number }> {
const { status, parentTaskId, assigneeAgentId, limit = 50, offset = 0 } = options || {};
const conditions = [eq(tasks.createdByUserId, this.userId)];
if (status) conditions.push(eq(tasks.status, status));
if (assigneeAgentId) conditions.push(eq(tasks.assigneeAgentId, assigneeAgentId));
if (parentTaskId === null) {
conditions.push(isNull(tasks.parentTaskId));
} else if (parentTaskId) {
conditions.push(eq(tasks.parentTaskId, parentTaskId));
}
const where = and(...conditions);
const countResult = await this.db
.select({ count: sql<number>`count(*)` })
.from(tasks)
.where(where);
const taskList = await this.db
.select()
.from(tasks)
.where(where)
.orderBy(desc(tasks.createdAt))
.limit(limit)
.offset(offset);
return { tasks: taskList, total: Number(countResult[0].count) };
}
/**
* Batch update sortOrder for multiple tasks.
* @param order Array of { id, sortOrder } pairs
*/
async reorder(order: Array<{ id: string; sortOrder: number }>): Promise<void> {
for (const item of order) {
await this.db
.update(tasks)
.set({ sortOrder: item.sortOrder, updatedAt: new Date() })
.where(and(eq(tasks.id, item.id), eq(tasks.createdByUserId, this.userId)));
}
}
async findSubtasks(parentTaskId: string): Promise<TaskItem[]> {
return this.db
.select()
.from(tasks)
.where(and(eq(tasks.parentTaskId, parentTaskId), eq(tasks.createdByUserId, this.userId)))
.orderBy(tasks.sortOrder, tasks.seq);
}
// Recursive query to get full task tree
async getTaskTree(rootTaskId: string): Promise<TaskItem[]> {
const result = await this.db.execute(sql`
WITH RECURSIVE task_tree AS (
SELECT * FROM tasks WHERE id = ${rootTaskId} AND created_by_user_id = ${this.userId}
UNION ALL
SELECT t.* FROM tasks t
JOIN task_tree tt ON t.parent_task_id = tt.id
)
SELECT * FROM task_tree
`);
return result.rows as TaskItem[];
}
// ========== Status ==========
async updateStatus(
id: string,
status: string,
extra?: { completedAt?: Date; error?: string | null; startedAt?: Date },
): Promise<TaskItem | null> {
return this.update(id, { status, ...extra });
}
async batchUpdateStatus(ids: string[], status: string): Promise<number> {
const result = await this.db
.update(tasks)
.set({ status, updatedAt: new Date() })
.where(and(inArray(tasks.id, ids), eq(tasks.createdByUserId, this.userId)))
.returning();
return result.length;
}
// ========== Checkpoint ==========
getCheckpointConfig(task: TaskItem): CheckpointConfig {
return (task.config as Record<string, any>)?.checkpoint || {};
}
async updateCheckpointConfig(id: string, checkpoint: CheckpointConfig): Promise<TaskItem | null> {
const task = await this.findById(id);
if (!task) return null;
const config = { ...(task.config as Record<string, any>), checkpoint };
return this.update(id, { config });
}
// ========== Review Config ==========
getReviewConfig(task: TaskItem): Record<string, any> | undefined {
return (task.config as Record<string, any>)?.review;
}
async updateReviewConfig(id: string, review: Record<string, any>): Promise<TaskItem | null> {
const task = await this.findById(id);
if (!task) return null;
const config = { ...(task.config as Record<string, any>), review };
return this.update(id, { config });
}
// Check if a task should pause after a topic completes
// Default: pause (when no checkpoint config is set)
// Explicit: pause only if topic.after is true
shouldPauseOnTopicComplete(task: TaskItem): boolean {
const checkpoint = this.getCheckpointConfig(task);
const hasAnyConfig = Object.keys(checkpoint).length > 0;
return hasAnyConfig ? !!checkpoint.topic?.after : true;
}
// Check if a task should be paused before starting (parent's tasks.beforeIds)
shouldPauseBeforeStart(parentTask: TaskItem, childIdentifier: string): boolean {
const checkpoint = this.getCheckpointConfig(parentTask);
return checkpoint.tasks?.beforeIds?.includes(childIdentifier) ?? false;
}
// Check if a task should be paused after completing (parent's tasks.afterIds)
shouldPauseAfterComplete(parentTask: TaskItem, childIdentifier: string): boolean {
const checkpoint = this.getCheckpointConfig(parentTask);
return checkpoint.tasks?.afterIds?.includes(childIdentifier) ?? false;
}
// ========== Heartbeat ==========
async updateHeartbeat(id: string): Promise<void> {
await this.db
.update(tasks)
.set({ lastHeartbeatAt: new Date(), updatedAt: new Date() })
.where(eq(tasks.id, id));
}
// Find stuck tasks (running but heartbeat timed out)
// Only checks tasks that have both lastHeartbeatAt and heartbeatTimeout set
static async findStuckTasks(db: LobeChatDatabase): Promise<TaskItem[]> {
return db
.select()
.from(tasks)
.where(
and(
eq(tasks.status, 'running'),
isNotNull(tasks.lastHeartbeatAt),
isNotNull(tasks.heartbeatTimeout),
sql`${tasks.lastHeartbeatAt} < now() - make_interval(secs => ${tasks.heartbeatTimeout})`,
),
);
}
// ========== Dependencies ==========
async addDependency(taskId: string, dependsOnId: string, type: string = 'blocks'): Promise<void> {
await this.db
.insert(taskDependencies)
.values({ dependsOnId, taskId, type, userId: this.userId })
.onConflictDoNothing();
}
async removeDependency(taskId: string, dependsOnId: string): Promise<void> {
await this.db
.delete(taskDependencies)
.where(
and(eq(taskDependencies.taskId, taskId), eq(taskDependencies.dependsOnId, dependsOnId)),
);
}
async getDependencies(taskId: string) {
return this.db.select().from(taskDependencies).where(eq(taskDependencies.taskId, taskId));
}
async getDependenciesByTaskIds(taskIds: string[]) {
if (taskIds.length === 0) return [];
return this.db.select().from(taskDependencies).where(inArray(taskDependencies.taskId, taskIds));
}
async getDependents(taskId: string) {
return this.db.select().from(taskDependencies).where(eq(taskDependencies.dependsOnId, taskId));
}
// Check if all dependencies of a task are completed
async areAllDependenciesCompleted(taskId: string): Promise<boolean> {
const result = await this.db
.select({ count: sql<number>`count(*)` })
.from(taskDependencies)
.innerJoin(tasks, eq(taskDependencies.dependsOnId, tasks.id))
.where(
and(
eq(taskDependencies.taskId, taskId),
eq(taskDependencies.type, 'blocks'),
ne(tasks.status, 'completed'),
),
);
return Number(result[0].count) === 0;
}
// Find tasks that are now unblocked after a dependency completes
async getUnlockedTasks(completedTaskId: string): Promise<TaskItem[]> {
// Find all tasks that depend on the completed task
const dependents = await this.getDependents(completedTaskId);
const unlocked: TaskItem[] = [];
for (const dep of dependents) {
if (dep.type !== 'blocks') continue;
// Check if ALL dependencies of this task are now completed
const allDone = await this.areAllDependenciesCompleted(dep.taskId);
if (!allDone) continue;
// Get the task itself — only unlock if it's in backlog
const task = await this.findById(dep.taskId);
if (task && task.status === 'backlog') {
unlocked.push(task);
}
}
return unlocked;
}
// Check if all subtasks of a parent task are completed
async areAllSubtasksCompleted(parentTaskId: string): Promise<boolean> {
const result = await this.db
.select({ count: sql<number>`count(*)` })
.from(tasks)
.where(
and(
eq(tasks.parentTaskId, parentTaskId),
ne(tasks.status, 'completed'),
eq(tasks.createdByUserId, this.userId),
),
);
return Number(result[0].count) === 0;
}
// ========== Documents (MVP Workspace) ==========
async pinDocument(taskId: string, documentId: string, pinnedBy: string = 'agent'): Promise<void> {
await this.db
.insert(taskDocuments)
.values({ documentId, pinnedBy, taskId, userId: this.userId })
.onConflictDoNothing();
}
async unpinDocument(taskId: string, documentId: string): Promise<void> {
await this.db
.delete(taskDocuments)
.where(and(eq(taskDocuments.taskId, taskId), eq(taskDocuments.documentId, documentId)));
}
async getPinnedDocuments(taskId: string) {
return this.db
.select()
.from(taskDocuments)
.where(eq(taskDocuments.taskId, taskId))
.orderBy(taskDocuments.createdAt);
}
// Get all pinned docs from a task tree (recursive), returns nodeMap + tree structure
async getTreePinnedDocuments(rootTaskId: string): Promise<WorkspaceData> {
const result = await this.db.execute(sql`
WITH RECURSIVE task_tree AS (
SELECT id, identifier FROM tasks WHERE id = ${rootTaskId}
UNION ALL
SELECT t.id, t.identifier FROM tasks t
JOIN task_tree tt ON t.parent_task_id = tt.id
)
SELECT td.*, tt.id as source_task_id, tt.identifier as source_task_identifier,
d.title as document_title, d.file_type as document_file_type, d.parent_id as document_parent_id,
d.total_char_count as document_char_count, d.updated_at as document_updated_at
FROM task_documents td
JOIN task_tree tt ON td.task_id = tt.id
LEFT JOIN documents d ON td.document_id = d.id
ORDER BY td.created_at
`);
// Build nodeMap
const nodeMap: Record<string, WorkspaceDocNode> = {};
const docIds = new Set<string>();
for (const row of result.rows as any[]) {
const docId = row.document_id;
docIds.add(docId);
nodeMap[docId] = {
charCount: row.document_char_count,
createdAt: row.created_at,
fileType: row.document_file_type,
parentId: row.document_parent_id,
pinnedBy: row.pinned_by,
sourceTaskIdentifier: row.source_task_id !== rootTaskId ? row.source_task_identifier : null,
title: row.document_title || 'Untitled',
updatedAt: row.document_updated_at,
};
}
// Build tree (children as id references)
type TreeNode = WorkspaceTreeNode;
const childrenMap = new Map<string | null, TreeNode[]>();
for (const docId of docIds) {
const node = nodeMap[docId];
const parentId = node.parentId && docIds.has(node.parentId) ? node.parentId : null;
const list = childrenMap.get(parentId) || [];
list.push({ children: [], id: docId });
childrenMap.set(parentId, list);
}
const buildTree = (parentId: string | null): TreeNode[] => {
const nodes = childrenMap.get(parentId) || [];
for (const node of nodes) {
node.children = buildTree(node.id);
}
return nodes;
};
return { nodeMap, tree: buildTree(null) };
}
// ========== Topic Management ==========
async incrementTopicCount(id: string): Promise<void> {
await this.db
.update(tasks)
.set({
totalTopics: sql`${tasks.totalTopics} + 1`,
updatedAt: new Date(),
})
.where(eq(tasks.id, id));
}
async updateCurrentTopic(id: string, topicId: string): Promise<void> {
await this.db
.update(tasks)
.set({ currentTopicId: topicId, updatedAt: new Date() })
.where(eq(tasks.id, id));
}
// ========== Comments ==========
async addComment(data: Omit<NewTaskComment, 'id'>): Promise<TaskCommentItem> {
const [comment] = await this.db.insert(taskComments).values(data).returning();
return comment;
}
// ========== Comments ==========
async getComments(taskId: string): Promise<TaskCommentItem[]> {
return this.db
.select()
.from(taskComments)
.where(eq(taskComments.taskId, taskId))
.orderBy(taskComments.createdAt);
}
async deleteComment(id: string): Promise<boolean> {
const result = await this.db
.delete(taskComments)
.where(and(eq(taskComments.id, id), eq(taskComments.userId, this.userId)))
.returning();
return result.length > 0;
}
}