⭐️⭐️⭐️ 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.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
refactor(api): let an extending build refuse internal agent work (#557)
Croff1e2e0d20f590
diff --git a/apps/api/AGENTS.md b/apps/api/AGENTS.mdindex 18ce284f..9d5e1e8b 100644--- a/apps/api/AGENTS.md+++ b/apps/api/AGENTS.md@@ -283,6 +283,9 @@ undoes one.answers 409 to an update; only a delete goes through.- `setRunAdmission` (`modules/agents/core/run-admission.ts`): the seconds a claimed runwaits before it starts, asked in the poller and in a runner's claim.+- `setRunRefusal` (`modules/agents/core/run-refusal.ts`): whether an internal agent works+ at all, asked in the poller before a queued run starts and in `prepareRun` before a chat+ answer. A reason fails the run without a retry, and answers the chat with 403.- `onProjectEvent` (`modules/webhooks/emit.ts`): every issue and comment event thewebhooks get, inside the request that caused it.diff --git a/apps/api/src/modules/agents/core/__tests__/integration/run-refusal.test.ts b/apps/api/src/modules/agents/core/__tests__/integration/run-refusal.test.tsnew file mode 100644index 00000000..71b12b8b--- /dev/null+++ b/apps/api/src/modules/agents/core/__tests__/integration/run-refusal.test.ts@@ -0,0 +1,87 @@+import { describe, it, expect, afterEach, beforeEach } from 'bun:test';+import { db, agentRun, issueActivity } from '@repo/db';+import { and, eq } from 'drizzle-orm';+import { authedApi } from '#tests/helpers/app';+import { signUpTestUser } from '#tests/helpers/auth';+import { resetDb } from '#tests/helpers/db';+import { createAgent } from '#tests/helpers/agents';+import { processAgentRuns } from '../../run-poller';+import { setRunRefusal, type InternalWork } from '../../run-refusal';++// The agent has no model credential, so work let through fails on the model rather than+// calling one.++const REASON = 'The agent budget is spent';++async function setup() {+ const owner = await signUpTestUser({ name: 'Owner' });+ const asOwner = authedApi(owner.cookie);+ const project = (await asOwner.projects.post({ key: 'MKT', name: 'Marketing' })).data!;+ const columnId = (await asOwner.projects({ projectKey: 'MKT' }).get()).data!.columns[0].id;+ const agent = (+ await createAgent(asOwner, 'MKT', { name: 'Bot', username: 'bot', kind: 'internal' })+ ).data!.agent;+ const issue = (+ await asOwner.projects({ projectKey: 'MKT' }).issues.post({ columnId, title: 'Task' })+ ).data!;+ return { owner, asOwner, project, agent, issue };+}++describe('agent run refusal', () => {+ beforeEach(resetDb);+ afterEach(() => setRunRefusal());++ it('fails a refused mention run with the reason, before it starts', async () => {+ const { owner, asOwner, project, agent, issue } = await setup();+ await asOwner.issues({ issueId: issue.id }).comments.post({ body: `please review @bot` });+ const asked: InternalWork[] = [];+ setRunRefusal(async (work) => {+ asked.push(work);+ return REASON;+ });++ await processAgentRuns();++ expect(asked).toEqual([+ { agentId: agent.id, teamId: project.teamId, projectId: project.id, userId: owner.userId },+ ]);+ const [run] = await db.select().from(agentRun).where(eq(agentRun.issueId, issue.id));+ expect(run).toMatchObject({ status: 'failed', attempts: 1, lastError: REASON });+ const started = await db+ .select()+ .from(issueActivity)+ .where(and(eq(issueActivity.issueId, issue.id), eq(issueActivity.action, 'agent_started')));+ expect(started).toEqual([]);+ });++ it('starts a run the extension lets through', async () => {+ const { asOwner, issue } = await setup();+ await asOwner.issues({ issueId: issue.id }).comments.post({ body: `please review @bot` });+ setRunRefusal(async () => null);++ await processAgentRuns();++ const [run] = await db.select().from(agentRun).where(eq(agentRun.issueId, issue.id));+ expect(run).toMatchObject({ attempts: 1, lastError: 'Agent has no model credential set' });+ });++ it('answers a refused chat with the reason', async () => {+ const { owner, asOwner, project, agent } = await setup();+ const asked: InternalWork[] = [];+ setRunRefusal(async (work) => {+ asked.push(work);+ return REASON;+ });++ const res = await asOwner+ .projects({ projectKey: 'MKT' })+ ['ai-agents']({ agentId: agent.id })+ .run.post({ prompt: 'hi' });++ expect(res.status).toBe(403);+ expect(res.error?.value).toMatchObject({ error: REASON, code: 'run_refused' });+ expect(asked).toEqual([+ { agentId: agent.id, teamId: project.teamId, projectId: project.id, userId: owner.userId },+ ]);+ });+});diff --git a/apps/api/src/modules/agents/core/run-poller.ts b/apps/api/src/modules/agents/core/run-poller.tsindex 1dfa06f4..5c355f31 100644--- a/apps/api/src/modules/agents/core/run-poller.ts+++ b/apps/api/src/modules/agents/core/run-poller.ts@@ -5,6 +5,7 @@ import { getLimits } from '#shared/limits';import { framePrompt, peopleContext, runModePreamble } from './prompt/framing';import { agentRunStarted, recordAgentRunFinished } from './run-activity';import { runAdmissionDelay } from './run-admission';+import { runRefusal } from './run-refusal';import {agentRunConfig,claimDueRuns,@@ -33,7 +34,8 @@ export async function processAgentRuns(): Promise<void> {}async function processRun(run: ClaimedRun): Promise<void> {- const workspaceId = await teamWorkspaceId(await getProjectTeamId(run.projectId), db);+ const teamId = await getProjectTeamId(run.projectId);+ const workspaceId = await teamWorkspaceId(teamId, db);const { maxConcurrentRuns, maxRunSeconds } = await getLimits(workspaceId);if (maxConcurrentRuns > 0 && (await countRunsAhead(workspaceId, run.id)) >= maxConcurrentRuns) {await deferRun(run.id, DEFERRED_RETRY_SECONDS);@@ -44,6 +46,18 @@ async function processRun(run: ClaimedRun): Promise<void> {await deferRun(run.id, wait);return;}+ // Refused before anything is recorded on the issue, and not retried: the attempt would+ // be refused for the same reason.+ const refused = await runRefusal({+ agentId: run.agentId,+ teamId,+ projectId: run.projectId,+ userId: run.requesterUserId,+ });+ if (refused) {+ await markRunFailed(run.id, refused);+ return;+ }// The issue's timeline entries are written here, where the agent's work actually// starts and ends. A failure that will be retried is not the end of the run, so only// the last attempt logs one.diff --git a/apps/api/src/modules/agents/core/run-queue.ts b/apps/api/src/modules/agents/core/run-queue.tsindex 16d10bbc..e5ad794f 100644--- a/apps/api/src/modules/agents/core/run-queue.ts+++ b/apps/api/src/modules/agents/core/run-queue.ts@@ -110,13 +110,14 @@ export interface ClaimedRun {issueIdentifier: string | null;issueTitle: string | null;// The issue's assignee (the responsible human) and, for a mention run, the author of- // the comment that mentioned the agent (from the source activity's name snapshot).- // Each carries the handle the agent tags them by. Any may be null: no assignee, a- // deleted user, or a run with no source comment.+ // the comment that mentioned the agent (from the source activity's name snapshot) with+ // their account. Each carries the handle the agent tags them by. Any may be null: no+ // assignee, a deleted user, or a run with no source comment.assigneeName: string | null;assigneeUsername: string | null;requesterName: string | null;requesterUsername: string | null;+ requesterUserId: string | null;// The comments the source comment replies to, oldest first, when it is a reply.// Null for a top-level mention or a delegation.threadContext: string | null;@@ -172,7 +173,8 @@ export async function claimDueRuns(): Promise<ClaimedRun[]> {(SELECT COALESCE(u.username, ag.username)FROM issue_activity a JOIN "user" u ON u.id = a.actor_user_idLEFT JOIN ai_agent ag ON ag.user_id = u.id- WHERE a.id = r.source_activity_id) AS "requesterUsername"+ WHERE a.id = r.source_activity_id) AS "requesterUsername",+ (SELECT actor_user_id FROM issue_activity a WHERE a.id = r.source_activity_id) AS "requesterUserId"`);const runs = rows as unknown as ClaimedRun[];return Promise.all(diff --git a/apps/api/src/modules/agents/core/run-refusal.ts b/apps/api/src/modules/agents/core/run-refusal.tsnew file mode 100644index 00000000..4c4a3b38--- /dev/null+++ b/apps/api/src/modules/agents/core/run-refusal.ts@@ -0,0 +1,29 @@+// Whether an internal agent may do a piece of work at all, asked of an extension of the+// api before the work reaches the model: in the poller before a queued run starts, and+// in prepareRun before a chat answer. A reason refuses it: the queued run fails with the+// reason and is not retried, the chat answers with it. A self-hosted instance refuses+// nothing. An external agent works on its own machine and is never asked about.++export interface InternalWork {+ agentId: number;+ teamId: number;+ projectId: number;+ // Who asked for the work: the member of a chat, or the author of the comment that+ // mentioned the agent. Null for work nobody asked for in person, such as a delegation+ // or a schedule's run.+ userId: string | null;+}++type RunRefusal = (work: InternalWork) => Promise<string | null>;++const refuseNothing: RunRefusal = async () => null;++let refusal = refuseNothing;++export function setRunRefusal(next = refuseNothing): void {+ refusal = next;+}++export function runRefusal(work: InternalWork): Promise<string | null> {+ return refusal(work);+}diff --git a/apps/api/src/modules/agents/core/runtime/index.ts b/apps/api/src/modules/agents/core/runtime/index.tsindex 19eb0171..ea41db59 100644--- a/apps/api/src/modules/agents/core/runtime/index.ts+++ b/apps/api/src/modules/agents/core/runtime/index.ts@@ -17,6 +17,7 @@ import { buildLocalTools } from './tools/local';import { buildSkillTool, skillsPreamble } from './skill-runtime';import { buildMemory, ensureThread, DEFAULT_LAST_MESSAGES } from './memory';import { getMastra } from './observability';+import { runRefusal } from '../run-refusal';import { toolArgsText, toolText } from '../../chat-parts';import { recordContextUsage, type ContextUsage } from '../../chat-usage';import { isChatThreadId, newChatThreadId } from './thread-ids';@@ -291,6 +292,16 @@ async function prepareRun(if (row.kind !== 'internal') {throw new HttpError(400, 'Only internal agents can be run');}+ // A queued run was asked about in the poller, before it was recorded as started.+ if (opts.runId == null) {+ const refused = await runRefusal({+ agentId: row.id,+ teamId: row.teamId,+ projectId,+ userId: opts.callerUserId,+ });+ if (refused) throw new HttpError(403, refused, 'run_refused');+ }// A chat run with no threadId starts a new conversation; every other run continues// the thread its caller named (see thread-ids). Without memory every run is a// conversation of its own, which is what the model's session id follows.