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 add to an internal agent before it works (#797)

Croff1539fe7a8504
diff --git a/apps/api/src/modules/agents/core/__tests__/integration/agent-build.test.ts b/apps/api/src/modules/agents/core/__tests__/integration/agent-build.test.ts
new file mode 100644
index 00000000..3979529f
--- /dev/null
+++ b/apps/api/src/modules/agents/core/__tests__/integration/agent-build.test.ts
@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { authedApi, createProject } from '#tests/helpers/app';
+import { signUpTestUser } from '#tests/helpers/auth';
+import { resetDb } from '#tests/helpers/db';
+import { createAgent } from '#tests/helpers/agents';
+import { createCredential } from '#tests/helpers/integrations';
+import { enqueueAgentRun } from '../../run-queue';
+import { processAgentRuns } from '../../run-poller';
+import { streamAgent } from '../../runtime';
+import { getMastra } from '../../runtime/observability';
+import { setAgentBuild, type AgentWork } from '../../agent-build';
+
+// An OpenAI-compatible model that answers at once and keeps what each call was sent: the
+// instructions and the tools are how the agent an extension built shows.
+let sent: {
+ messages: { role: string; content: unknown }[];
+ tools?: { function: { name: string } }[];
+}[] = [];
+
+function reply(stream: boolean): Response {
+ const usage = { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 };
+ if (!stream) {
+ return Response.json({
+ id: 'x',
+ object: 'chat.completion',
+ created: 0,
+ model: 'm',
+ choices: [
+ { index: 0, finish_reason: 'stop', message: { role: 'assistant', content: 'Done.' } },
+ ],
+ usage,
+ });
+ }
+ const chunk = (choice: object, extra: object = {}) =>
+ `data: ${JSON.stringify({ id: 'x', object: 'chat.completion.chunk', created: 0, model: 'm', choices: [{ index: 0, ...choice }], ...extra })}\n\n`;
+ const body =
+ chunk({ delta: { role: 'assistant', content: 'Done.' } }) +
+ chunk({ delta: {}, finish_reason: 'stop' }, { usage });
+ return new Response(`${body}data: [DONE]\n\n`, {
+ headers: { 'content-type': 'text/event-stream' },
+ });
+}
+
+const toolsSent = () => (sent.at(-1)?.tools ?? []).map((tool) => tool.function.name);
+const systemSent = () =>
+ (sent.at(-1)?.messages ?? [])
+ .filter((message) => message.role === 'system')
+ .map((message) => String(message.content))
+ .join('\n');
+
+describe('agent build extension', () => {
+ let endpoint: ReturnType<typeof Bun.serve>;
+
+ beforeEach(async () => {
+ await resetDb();
+ sent = [];
+ endpoint = Bun.serve({
+ port: 0,
+ fetch: async (req) => {
+ const body = (await req.json()) as (typeof sent)[number] & { stream?: boolean };
+ sent.push(body);
+ return reply(Boolean(body.stream));
+ },
+ });
+ });
+
+ afterEach(async () => {
+ setAgentBuild();
+ await endpoint.stop(true);
+ await getMastra().observability.flush();
+ });
+
+ async function setup() {
+ const owner = await signUpTestUser({ name: 'Owner' });
+ const asOwner = authedApi(owner.cookie);
+ await createProject(asOwner, { key: 'MKT', name: 'Marketing' });
+ const view = await asOwner.projects({ projectKey: 'MKT' }).get();
+ const credentialId = await createCredential(asOwner, 'MKT', {
+ integrationKey: 'openai-compatible',
+ credential: { apiKey: 'sk-test', baseUrl: `http://localhost:${endpoint.port}/v1` },
+ });
+ const agent = (
+ await createAgent(asOwner, 'MKT', {
+ name: 'Bot',
+ username: 'bot',
+ kind: 'internal',
+ modelCredentialId: credentialId,
+ model: 'any-model',
+ })
+ ).data!.agent;
+ return { owner, asOwner, view, agent };
+ }
+
+ async function runOnIssue() {
+ const { asOwner, view, agent } = await setup();
+ const issue = (
+ await asOwner
+ .projects({ projectKey: 'MKT' })
+ .issues.post({ columnId: view.data!.columns[0].id, title: 'Task' })
+ ).data!;
+ await enqueueAgentRun({
+ agentId: agent.id,
+ projectId: agent.projects[0].id,
+ issueId: issue.id,
+ sourceActivityId: null,
+ prompt: 'do it',
+ });
+ await processAgentRuns();
+ return { agent, issue };
+ }
+
+ it('builds the agent as the core assembles it without an extension', async () => {
+ await runOnIssue();
+ expect(sent).toHaveLength(1);
+ expect(toolsSent()).toContain('get_project');
+ expect(toolsSent()).not.toContain('add_issue_watcher');
+ });
+
+ it('hands a queued run to the extension and makes the agent from what it returns', async () => {
+ const seen: Omit<AgentWork, 'routeTools'>[] = [];
+ setAgentBuild((config, { routeTools, ...work }) => {
+ seen.push(work);
+ return {
+ ...config,
+ instructions: `${String(config.instructions)}\n\nFollow the house rules.`,
+ tools: { ...config.tools, ...routeTools(['add_issue_watcher', 'no_such_tool']) },
+ };
+ });
+
+ const { agent, issue } = await runOnIssue();
+
+ expect(seen).toEqual([
+ {
+ agentId: agent.id,
+ teamId: agent.teamId,
+ projectId: agent.projects[0].id,
+ runId: expect.any(Number),
+ trigger: 'delegation',
+ issueId: issue.id,
+ },
+ ]);
+ expect(systemSent()).toContain('Follow the house rules.');
+ expect(toolsSent()).toContain('add_issue_watcher');
+ expect(toolsSent()).toContain('get_project');
+ expect(toolsSent()).not.toContain('no_such_tool');
+ });
+
+ it('hands a chat answer to the extension without a run', async () => {
+ const { owner, agent } = await setup();
+ const seen: Omit<AgentWork, 'routeTools'>[] = [];
+ setAgentBuild((config, { routeTools: _, ...work }) => {
+ seen.push(work);
+ return config;
+ });
+
+ for await (const _event of streamAgent(agent.id, agent.projects[0].id, 'hello', {
+ callerUserId: owner.userId,
+ }));
+
+ expect(seen).toEqual([
+ {
+ agentId: agent.id,
+ teamId: agent.teamId,
+ projectId: agent.projects[0].id,
+ runId: undefined,
+ trigger: undefined,
+ issueId: undefined,
+ },
+ ]);
+ });
+});
diff --git a/apps/api/src/modules/agents/core/agent-build.ts b/apps/api/src/modules/agents/core/agent-build.ts
new file mode 100644
index 00000000..3aade834
--- /dev/null
+++ b/apps/api/src/modules/agents/core/agent-build.ts
@@ -0,0 +1,37 @@
+import type { AgentConfig } from '@mastra/core/agent';
+import type { createTool } from '@mastra/core/tools';
+import type { AgentRunTrigger } from '../model';
+
+// How an extension of the api builds on an internal agent before it works, in a queued run
+// or a chat answer: it is handed the config the core assembled (the instructions, the tools,
+// the memory) with what the agent is about to do, and returns the config the agent is made
+// with, which takes whatever Mastra's Agent takes, input and output processors among them.
+// A self-hosted instance keeps the core's. An external agent is built by its runner on the
+// operator's machine and never comes here.
+
+export interface AgentWork {
+ agentId: number;
+ teamId: number;
+ projectId: number;
+ // The queued run the agent does and what triggered it; absent for a chat answer.
+ runId?: number;
+ trigger?: AgentRunTrigger;
+ issueId?: number | null;
+ // Tools for the routes tagged mcpTool() under these names, bound to the agent's project
+ // and called with its key, as its own route tools are. A name no route has is left out.
+ routeTools: (names: string[]) => Record<string, ReturnType<typeof createTool>>;
+}
+
+type AgentBuild = (config: AgentConfig, work: AgentWork) => AgentConfig | Promise<AgentConfig>;
+
+const keepConfig: AgentBuild = (config) => config;
+
+let build = keepConfig;
+
+export function setAgentBuild(next = keepConfig): void {
+ build = next;
+}
+
+export async function buildOnAgent(config: AgentConfig, work: AgentWork): Promise<AgentConfig> {
+ return build(config, work);
+}
diff --git a/apps/api/src/modules/agents/core/runtime/index.ts b/apps/api/src/modules/agents/core/runtime/index.ts
index 20f3606c..caa74168 100644
--- a/apps/api/src/modules/agents/core/runtime/index.ts
+++ b/apps/api/src/modules/agents/core/runtime/index.ts
@@ -1,5 +1,5 @@
import { randomUUID } from 'node:crypto';
-import { Agent, type AgentExecutionOptions } from '@mastra/core/agent';
+import { Agent, type AgentConfig, type AgentExecutionOptions } from '@mastra/core/agent';
import type { TracingOptions } from '@mastra/core/observability';
import {
assertChatEnabled,
@@ -13,12 +13,13 @@ import { getCredentialSecret } from '../../integrations/service';
import { listAgentSkills } from '../../skills/service';
import { listAgentToolsForRun } from '../../tools/service';
import { buildCustomTools } from './tools/custom-tools';
-import { buildRouteTools } from './tools/route-tools';
+import { buildNamedRouteTools, buildRouteTools } from './tools/route-tools';
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 { buildOnAgent } from '../agent-build';
import { toolArgsText, toolText } from '../../chat-parts';
import { recordContextUsage, type ContextUsage } from '../../chat-usage';
import { isChatThreadId, newChatThreadId } from './thread-ids';
@@ -112,7 +113,7 @@ export type AgentRunEvent =
async function buildAgent(
row: AiAgentRow,
projectId: number,
- contextPreamble: string,
+ opts: RunOpts,
sessionId: string,
): Promise<Agent> {
const project = await getProjectById(projectId);
@@ -123,10 +124,10 @@ async function buildAgent(
const apiKey = await getInternalAgentApiKey(row);
const instructions =
projectPreamble(project) +
- contextPreamble +
+ (opts.contextPreamble ?? '') +
(row.instructions ?? DEFAULT_INSTRUCTIONS) +
skillsPreamble(skills);
- const agent = new Agent({
+ const config: AgentConfig = {
id: `ai-agent-${row.id}`,
name: row.name,
instructions,
@@ -145,7 +146,18 @@ async function buildAgent(
...(row.memoryEnabled
? { memory: buildMemory(row.memoryLastMessages ?? DEFAULT_LAST_MESSAGES) }
: {}),
- });
+ };
+ const agent = new Agent(
+ await buildOnAgent(config, {
+ agentId: row.id,
+ teamId: row.teamId,
+ projectId,
+ runId: opts.runId,
+ trigger: opts.trigger,
+ issueId: opts.issueId,
+ routeTools: (names) => buildNamedRouteTools(project, apiKey, names),
+ }),
+ );
// An agent traces its run only through a container (see observability.ts).
agent.__registerMastra(getMastra());
return agent;
@@ -310,12 +322,7 @@ async function prepareRun(
const threadId = row.memoryEnabled
? (opts.threadId ?? newChatThreadId(row.id, opts.callerUserId))
: null;
- const agent = await buildAgent(
- row,
- projectId,
- opts.contextPreamble ?? '',
- threadId ?? randomUUID(),
- );
+ const agent = await buildAgent(row, projectId, opts, threadId ?? randomUUID());
// Mastra's generate/stream have overloaded options; type the shape we use. In
// Mastra v1 the temperature belongs to the call's model settings — a flat
diff --git a/apps/api/src/modules/agents/core/runtime/tools/route-tools.ts b/apps/api/src/modules/agents/core/runtime/tools/route-tools.ts
index b09d3d03..f3eacbcd 100644
--- a/apps/api/src/modules/agents/core/runtime/tools/route-tools.ts
+++ b/apps/api/src/modules/agents/core/runtime/tools/route-tools.ts
@@ -105,15 +105,23 @@ export function buildRouteTools(
apiKey: string,
enabledActions: string[] = [],
): Record<string, ReturnType<typeof createTool>> {
- const app = getMcpApp();
const granted = new Set([...ALWAYS_ON_KEYS, ...normalizeToolKeys(enabledActions)]);
// An update replaces the board's canvas as a whole, so without the read the agent
// would send a canvas built from nothing and delete every card already on the board.
if (granted.has('update_note_board')) granted.add('get_note_board');
+ return buildNamedRouteTools(project, apiKey, granted);
+}
+// The tools of the routes with these names, whatever the catalog grants.
+export function buildNamedRouteTools(
+ project: ProjectRow,
+ apiKey: string,
+ names: Iterable<string>,
+): Record<string, ReturnType<typeof createTool>> {
+ const wanted = new Set(names);
const tools: Record<string, ReturnType<typeof createTool>> = {};
- for (const route of routeTools(app)) {
- if (!granted.has(route.name)) continue;
+ for (const route of routeTools(getMcpApp())) {
+ if (!wanted.has(route.name)) continue;
tools[route.name] = buildOne(route, project, apiKey);
}
return tools;