Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

feat(api): list_issues filters the issues held up by an open blocker (#758)

Pasqual Troncone85fbf9d8f498
diff --git a/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts b/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts
index 19d32807..f5c986b9 100644
--- a/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts
+++ b/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts
@@ -417,6 +417,33 @@ describe('internal agent route tools', () => {
const context = await run(tools, 'get_project');
expect(context).toMatchObject({ columns: expect.any(Array) });
});
+
+ // A block is a relation, not text, so search_issues cannot find it.
+ it('blocked lists the issues an open issue is blocking, not those of a closed one', async () => {
+ const { asOwner } = await setup();
+ const view = await asOwner.projects({ projectKey: 'MKT' }).get();
+ const columns = view.data?.columns ?? [];
+ const openId = columns.find((c) => c.stateType === 'backlog')?.id;
+ const doneId = columns.find((c) => c.stateType === 'completed')?.id;
+ if (openId === undefined || doneId === undefined) throw new Error('Missing columns');
+ const tools = await toolsFor(asOwner, ['create_issue', 'link_issues']);
+ const make = async (title: string, columnId: number) =>
+ ((await run(tools, 'create_issue', { columnId, title })) as { id: number }).id;
+ const openBlocker = await make('Open blocker', openId);
+ const held = await make('Held up', openId);
+ const doneBlocker = await make('Done blocker', doneId);
+ const freed = await make('No longer held up', openId);
+ await run(tools, 'link_issues', {
+ issueId: held,
+ targetIssueId: openBlocker,
+ kind: 'blocked_by',
+ });
+ await run(tools, 'link_issues', { issueId: doneBlocker, targetIssueId: freed, kind: 'blocks' });
+
+ const result = (await run(tools, 'list_issues', { blocked: 'true' })) as { title: string }[];
+
+ expect(result.map((i) => i.title)).toEqual(['Held up']);
+ });
});
// A run works in one project, and its tools are bound to it: an object addressed by id
diff --git a/apps/api/src/modules/agents/core/issue-query.ts b/apps/api/src/modules/agents/core/issue-query.ts
index 57f187b7..a690d886 100644
--- a/apps/api/src/modules/agents/core/issue-query.ts
+++ b/apps/api/src/modules/agents/core/issue-query.ts
@@ -56,6 +56,7 @@ export const issueQuerySchema = z.object({
.describe('Label ids from get_project. An issue must contain every supplied label.'),
dueFrom: date.optional().describe('Inclusive earliest due date in YYYY-MM-DD format.'),
dueTo: date.optional().describe('Inclusive latest due date in YYYY-MM-DD format.'),
+ blocked: z.boolean().optional().describe('Only issues that an issue still open is blocking.'),
limit: z
.number()
.int()
diff --git a/apps/api/src/modules/agents/core/runtime/tools/catalog.ts b/apps/api/src/modules/agents/core/runtime/tools/catalog.ts
index b83f126f..35084b4f 100644
--- a/apps/api/src/modules/agents/core/runtime/tools/catalog.ts
+++ b/apps/api/src/modules/agents/core/runtime/tools/catalog.ts
@@ -350,7 +350,7 @@ export const ALWAYS_ON_ACTIONS: ToolMeta[] = [
group: 'issues',
label: 'List issues by filters',
description:
- 'List issues filtered by state, type, assignee, priority, label, due date, or when they were created or updated.',
+ 'List issues filtered by state, type, assignee, priority, label, due date, when they were created or updated, or blocked.',
always: true,
},
{
diff --git a/apps/api/src/modules/issues/__tests__/integration/issues.test.ts b/apps/api/src/modules/issues/__tests__/integration/issues.test.ts
index 0efeeb4f..5acf87ea 100644
--- a/apps/api/src/modules/issues/__tests__/integration/issues.test.ts
+++ b/apps/api/src/modules/issues/__tests__/integration/issues.test.ts
@@ -1286,6 +1286,83 @@ describe('issues', () => {
expect(ids).not.toContain(onlyA.id);
});
+ // A block is a relation between two issues, which no text search reaches.
+ describe('blocked', () => {
+ async function blockedSetup() {
+ const { asOwner } = await setupProject();
+ const view = await asOwner.projects({ projectKey: 'MKT' }).get();
+ const column = (stateType: string) =>
+ view.data!.columns.find((c) => c.stateType === stateType)!.id;
+ const make = async (title: string, stateType = 'backlog', patch = {}) =>
+ (await createIssue(asOwner, column(stateType), { title, ...patch })).data!.id;
+ const block = (blocker: number, held: number) =>
+ asOwner.issues({ issueId: blocker }).links.post({ targetIssueId: held, kind: 'blocks' });
+ const blockedTitles = async (query: Record<string, string> = { blocked: 'true' }) =>
+ (await list(asOwner, query)).data!.map((i) => i.title);
+ return { asOwner, make, block, blockedTitles };
+ }
+
+ it('lists the issues an open issue blocks, not the blocker or an unlinked issue', async () => {
+ const { make, block, blockedTitles } = await blockedSetup();
+ const blocker = await make('Blocker', 'started');
+ await block(blocker, await make('Held up'));
+ await make('Free');
+
+ expect(await blockedTitles()).toEqual(['Held up']);
+ });
+
+ it('reads the relation from either side', async () => {
+ const { asOwner, make, blockedTitles } = await blockedSetup();
+ const blocker = await make('Blocker');
+ const held = await make('Held up');
+ await asOwner
+ .issues({ issueId: held })
+ .links.post({ targetIssueId: blocker, kind: 'blocked_by' });
+
+ expect(await blockedTitles()).toEqual(['Held up']);
+ });
+
+ it('leaves out an issue whose blocker is completed, canceled or archived', async () => {
+ const { asOwner, make, block, blockedTitles } = await blockedSetup();
+ await block(await make('Done', 'completed'), await make('After done'));
+ await block(await make('Dropped', 'canceled'), await make('After dropped'));
+ const archived = await make('Archived');
+ await block(archived, await make('After archived'));
+ await asOwner.issues({ issueId: archived }).archive.post();
+
+ expect(await blockedTitles()).toEqual([]);
+ });
+
+ it('keeps an issue that one of its blockers still holds up', async () => {
+ const { make, block, blockedTitles } = await blockedSetup();
+ const held = await make('Held up');
+ await block(await make('Done', 'completed'), held);
+ await block(await make('Open'), held);
+
+ expect(await blockedTitles()).toEqual(['Held up']);
+ });
+
+ it('combines with the other filters', async () => {
+ const { make, block, blockedTitles } = await blockedSetup();
+ const blocker = await make('Blocker');
+ await block(blocker, await make('Held up'));
+ const urgent = await make('Held up, urgent', 'backlog', { priority: 'urgent' });
+ await block(blocker, urgent);
+
+ expect(await blockedTitles({ blocked: 'true', priority: 'urgent' })).toEqual([
+ 'Held up, urgent',
+ ]);
+ });
+
+ it('does not filter for any other value', async () => {
+ const { make, block, blockedTitles } = await blockedSetup();
+ await block(await make('Blocker'), await make('Held up'));
+
+ expect((await blockedTitles({ blocked: 'false' })).sort()).toEqual(['Blocker', 'Held up']);
+ expect((await blockedTitles({ blocked: '' })).sort()).toEqual(['Blocker', 'Held up']);
+ });
+ });
+
it('ignores placeholder 0 ids and empty strings (LLM-filled defaults)', async () => {
const { asOwner, columnId } = await setupProject();
const one = (await createIssue(asOwner, columnId, { title: 'Real one' })).data!;
diff --git a/apps/api/src/modules/issues/index.ts b/apps/api/src/modules/issues/index.ts
index a7a8ed34..2566453b 100644
--- a/apps/api/src/modules/issues/index.ts
+++ b/apps/api/src/modules/issues/index.ts
@@ -486,6 +486,7 @@ export const issueRoutes = new Elysia({ name: 'issues', detail: { tags: ['Issues
createdTo: instantParam('createdTo', query.createdTo),
updatedFrom: instantParam('updatedFrom', query.updatedFrom),
updatedTo: instantParam('updatedTo', query.updatedTo),
+ blocked: query.blocked === 'true',
limit,
},
{ includeArchived: query.includeArchived === 'true' },
@@ -499,7 +500,7 @@ export const issueRoutes = new Elysia({ name: 'issues', detail: { tags: ['Issues
detail: {
summary: 'List issues by filters',
description:
- "List a project's issues by field filters, most recently updated first. Each issue carries createdAt, updatedAt, completedAt, statusSince (when it entered its current column), estimateMinutes, loggedMinutes and its parent's identifier and title.",
+ "List a project's issues by field filters, most recently updated first. Each issue carries createdAt, updatedAt, completedAt, statusSince (when it entered its current column), estimateMinutes, loggedMinutes and its parent's identifier and title. blocked=true lists the issues held up by an issue still open, through a blocks relation.",
...mcpTool('list_issues'),
},
},
diff --git a/apps/api/src/modules/issues/model.ts b/apps/api/src/modules/issues/model.ts
index 39484c6a..e9f26edd 100644
--- a/apps/api/src/modules/issues/model.ts
+++ b/apps/api/src/modules/issues/model.ts
@@ -578,6 +578,13 @@ export const listIssuesQuery = t.Object({
createdTo: instantQuery('Exclusive latest creation time.'),
updatedFrom: instantQuery('Inclusive earliest last-update time.'),
updatedTo: instantQuery('Exclusive latest last-update time.'),
+ blocked: t.Optional(
+ t.String({
+ description:
+ "'true' for issues another issue is blocking while it is still open (not in a " +
+ 'completed or canceled column, not archived).',
+ }),
+ ),
includeArchived: t.Optional(
t.String({ description: "'true' to include archived issues. Default false." }),
),
diff --git a/apps/api/src/modules/issues/service.ts b/apps/api/src/modules/issues/service.ts
index 11ad695d..e4c330c9 100644
--- a/apps/api/src/modules/issues/service.ts
+++ b/apps/api/src/modules/issues/service.ts
@@ -17,7 +17,9 @@ import {
initiative,
cycle,
team,
+ issueLink,
} from '@repo/db';
+import { alias } from 'drizzle-orm/pg-core';
import {
and,
eq,
@@ -501,6 +503,28 @@ export async function searchIssues(
if (filters.updatedFrom) conds.push(gte(issue.updatedAt, filters.updatedFrom));
if (filters.updatedTo) conds.push(lt(issue.updatedAt, filters.updatedTo));
+ if (filters.blocked) {
+ const blocker = alias(issue, 'blocker');
+ const blockerColumn = alias(projectColumn, 'blocker_column');
+ conds.push(
+ exists(
+ db
+ .select({ one: sql`1` })
+ .from(issueLink)
+ .innerJoin(blocker, eq(blocker.id, issueLink.sourceIssueId))
+ .innerJoin(blockerColumn, eq(blockerColumn.id, blocker.columnId))
+ .where(
+ and(
+ eq(issueLink.targetIssueId, issue.id),
+ eq(issueLink.kind, 'blocks'),
+ isNull(blocker.archivedAt),
+ notInArray(blockerColumn.stateType, ['completed', 'canceled']),
+ ),
+ ),
+ ),
+ );
+ }
+
const base = db
.select(hitColumns)
.from(issue)