⭐️⭐️⭐️ 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 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 flatdiff --git a/apps/api/src/modules/agents/core/runtime/tools/route-tools.ts b/apps/api/src/modules/agents/core/runtime/tools/route-tools.tsindex 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;