🔨 chore(task): add task.groupList API for kanban view (#13507)

* ✨ feat(task): add task.groupList API for kanban board view

Support querying tasks grouped by status in a single request, with per-group independent pagination. Returns array structure with hasMore/limit/offset for each group.

LOBE-6589

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

* 🐛 fix(task): bound groupList groups and statuses array size

Prevent query storms from oversized requests by capping groups to 20
and statuses per group to 10.

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

* 🔧 chore(task): reduce groupList max groups from 20 to 10

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

---------

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

packages/database/src/models/__tests__/task.test.ts

@@ -264,6 +264,97 @@ describe('TaskModel', () => {
     });
   });
 
+  describe('groupList', () => {
+    it('should return grouped tasks by status', async () => {
+      const model = new TaskModel(serverDB, userId);
+
+      // Create tasks with different statuses
+      const t1 = await model.create({ instruction: 'Backlog task' });
+      const t2 = await model.create({ instruction: 'Running task' });
+      await model.updateStatus(t2.id, 'running', { startedAt: new Date() });
+      const t3 = await model.create({ instruction: 'Paused task' });
+      await model.updateStatus(t3.id, 'paused');
+      const t4 = await model.create({ instruction: 'Failed task' });
+      await model.updateStatus(t4.id, 'failed', { error: 'err' });
+      const t5 = await model.create({ instruction: 'Completed task' });
+      await model.updateStatus(t5.id, 'completed', { completedAt: new Date() });
+
+      const result = await model.groupList({
+        groups: [
+          { key: 'backlog', statuses: ['backlog'] },
+          { key: 'running', statuses: ['running'] },
+          { key: 'needsInput', statuses: ['paused', 'failed'] },
+          { key: 'done', statuses: ['completed'] },
+        ],
+      });
+
+      expect(result).toHaveLength(4);
+
+      const backlog = result.find((g) => g.key === 'backlog')!;
+      expect(backlog.total).toBe(1);
+      expect(backlog.tasks).toHaveLength(1);
+      expect(backlog.hasMore).toBe(false);
+
+      const running = result.find((g) => g.key === 'running')!;
+      expect(running.total).toBe(1);
+      expect(running.tasks).toHaveLength(1);
+
+      const needsInput = result.find((g) => g.key === 'needsInput')!;
+      expect(needsInput.total).toBe(2);
+      expect(needsInput.tasks).toHaveLength(2);
+
+      const done = result.find((g) => g.key === 'done')!;
+      expect(done.total).toBe(1);
+      expect(done.tasks).toHaveLength(1);
+    });
+
+    it('should support per-group pagination', async () => {
+      const model = new TaskModel(serverDB, userId);
+
+      // Create 3 backlog tasks
+      await model.create({ instruction: 'Backlog 1' });
+      await model.create({ instruction: 'Backlog 2' });
+      await model.create({ instruction: 'Backlog 3' });
+
+      const result = await model.groupList({
+        groups: [{ key: 'backlog', limit: 2, offset: 0, statuses: ['backlog'] }],
+      });
+
+      const backlog = result[0];
+      expect(backlog.total).toBe(3);
+      expect(backlog.tasks).toHaveLength(2);
+      expect(backlog.hasMore).toBe(true);
+      expect(backlog.limit).toBe(2);
+      expect(backlog.offset).toBe(0);
+
+      // Fetch next page
+      const page2 = await model.groupList({
+        groups: [{ key: 'backlog', limit: 2, offset: 2, statuses: ['backlog'] }],
+      });
+
+      const backlogP2 = page2[0];
+      expect(backlogP2.tasks).toHaveLength(1);
+      expect(backlogP2.hasMore).toBe(false);
+      expect(backlogP2.offset).toBe(2);
+    });
+
+    it('should filter by assigneeAgentId', async () => {
+      const agentId = await createAgent('group-list-agent');
+      const model = new TaskModel(serverDB, userId);
+
+      await model.create({ assigneeAgentId: agentId, instruction: 'Assigned' });
+      await model.create({ instruction: 'Unassigned' });
+
+      const result = await model.groupList({
+        assigneeAgentId: agentId,
+        groups: [{ key: 'backlog', statuses: ['backlog'] }],
+      });
+
+      expect(result[0].total).toBe(1);
+      expect(result[0].tasks).toHaveLength(1);
+    });
+  });
+
   describe('findSubtasks', () => {
     it('should find direct subtasks', async () => {
       const model = new TaskModel(serverDB, userId);

packages/database/src/models/task.ts

@@ -140,6 +140,78 @@ export class TaskModel {
 
   // ========== Query ==========
 
+  async groupList(options: {
+    assigneeAgentId?: string;
+    groups: Array<{
+      key: string;
+      limit?: number;
+      offset?: number;
+      statuses: string[];
+    }>;
+    parentTaskId?: string | null;
+  }): Promise<
+    Array<{
+      hasMore: boolean;
+      key: string;
+      limit: number;
+      offset: number;
+      tasks: TaskItem[];
+      total: number;
+    }>
+  > {
+    const { groups, assigneeAgentId, parentTaskId } = options;
+
+    const baseConditions = [eq(tasks.createdByUserId, this.userId)];
+    if (assigneeAgentId) baseConditions.push(eq(tasks.assigneeAgentId, assigneeAgentId));
+    if (parentTaskId === null) {
+      baseConditions.push(isNull(tasks.parentTaskId));
+    } else if (parentTaskId) {
+      baseConditions.push(eq(tasks.parentTaskId, parentTaskId));
+    }
+
+    // Collect all statuses for a single aggregated count query
+    const allStatuses = Array.from(new Set(groups.flatMap((g) => g.statuses)));
+    const countResult = await this.db
+      .select({ count: sql<number>`count(*)`, status: tasks.status })
+      .from(tasks)
+      .where(and(...baseConditions, inArray(tasks.status, allStatuses)))
+      .groupBy(tasks.status);
+
+    const countByStatus: Record<string, number> = {};
+    for (const row of countResult) {
+      countByStatus[row.status] = Number(row.count);
+    }
+
+    // Query each group's tasks in parallel
+    const results = await Promise.all(
+      groups.map(async (group) => {
+        const limit = group.limit ?? 50;
+        const offset = group.offset ?? 0;
+
+        const groupTasks = await this.db
+          .select()
+          .from(tasks)
+          .where(and(...baseConditions, inArray(tasks.status, group.statuses)))
+          .orderBy(desc(tasks.createdAt))
+          .limit(limit)
+          .offset(offset);
+
+        const total = group.statuses.reduce((sum, s) => sum + (countByStatus[s] || 0), 0);
+
+        return {
+          hasMore: offset + groupTasks.length < total,
+          key: group.key,
+          limit,
+          offset,
+          tasks: groupTasks,
+          total,
+        };
+      }),
+    );
+
+    return results;
+  }
+
   async list(options?: {
     assigneeAgentId?: string;
     limit?: number;

src/server/routers/lambda/task.ts

@@ -68,6 +68,22 @@ const listSchema = z.object({
   status: z.string().optional(),
 });
 
+const groupListSchema = z.object({
+  assigneeAgentId: z.string().optional(),
+  groups: z
+    .array(
+      z.object({
+        key: z.string(),
+        limit: z.number().min(1).max(100).default(50),
+        offset: z.number().min(0).default(0),
+        statuses: z.array(z.string()).min(1).max(10),
+      }),
+    )
+    .min(1)
+    .max(10),
+  parentTaskId: z.string().nullable().optional(),
+});
+
 // Helper: build task prompt with handoff context from previous topics
 async function buildTaskPrompt(
   task: Awaited<ReturnType<TaskModel['findById']>> & {},
@@ -686,6 +702,21 @@ export const taskRouter = router({
     }
   }),
 
+  groupList: taskProcedure.input(groupListSchema).query(async ({ input, ctx }) => {
+    try {
+      const model = ctx.taskModel;
+      const groups = await model.groupList(input);
+      return { data: groups, success: true };
+    } catch (error) {
+      console.error('[task:groupList]', error);
+      throw new TRPCError({
+        cause: error,
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'Failed to fetch grouped tasks',
+      });
+    }
+  }),
+
   list: taskProcedure.input(listSchema).query(async ({ input, ctx }) => {
     try {
       const model = ctx.taskModel;