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.

refactor(api): let an extending build refuse internal agent work (#557)

Croff1e2e0d20f590
diff --git a/apps/api/AGENTS.md b/apps/api/AGENTS.md
index 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 run
waits 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 the
webhooks 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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_id
LEFT 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.ts
new file mode 100644
index 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.ts
index 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.