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): pass the project description to agents and cap it at 2000 characters (#244)

Croff7035ffca78d0
diff --git a/apps/api/src/modules/agents/chat/service.ts b/apps/api/src/modules/agents/chat/service.ts
index feeb44da..93604ce5 100644
--- a/apps/api/src/modules/agents/chat/service.ts
+++ b/apps/api/src/modules/agents/chat/service.ts
@@ -431,7 +431,11 @@ async function readHistory(
function buildSystemPrompt(agent: RunnerAgent, requester: Person): string {
const instructions = agent.instructions?.trim();
return (
- projectPreamble({ key: agent.projectKey, name: agent.projectName }) +
+ projectPreamble({
+ key: agent.projectKey,
+ name: agent.projectName,
+ description: agent.projectDescription,
+ }) +
chatModePreamble() +
chartPreamble() +
attachmentPreamble() +
diff --git a/apps/api/src/modules/agents/core/__tests__/unit/framing.test.ts b/apps/api/src/modules/agents/core/__tests__/unit/framing.test.ts
new file mode 100644
index 00000000..fb68bf15
--- /dev/null
+++ b/apps/api/src/modules/agents/core/__tests__/unit/framing.test.ts
@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'bun:test';
+import { projectPreamble } from '../../prompt/framing';
+import { PROJECT_DESCRIPTION_LIMIT } from '#modules/projects/model';
+
+describe('projectPreamble', () => {
+ it('adds the description as its own paragraph', () => {
+ const text = projectPreamble({ key: 'MKT', name: 'Marketing', description: 'Growth work' });
+ expect(text).toContain('\n\nGrowth work\n');
+ });
+
+ it('adds nothing when the description is empty', () => {
+ const text = projectPreamble({ key: 'MKT', name: 'Marketing', description: ' ' });
+ expect(text.endsWith('-123.\n\n')).toBe(true);
+ });
+
+ it('cuts a description longer than the limit', () => {
+ const description = 'x'.repeat(PROJECT_DESCRIPTION_LIMIT + 100);
+ const text = projectPreamble({ key: 'MKT', name: 'Marketing', description });
+ expect(text).toContain('x'.repeat(PROJECT_DESCRIPTION_LIMIT));
+ expect(text).not.toContain('x'.repeat(PROJECT_DESCRIPTION_LIMIT + 1));
+ });
+});
diff --git a/apps/api/src/modules/agents/core/prompt/framing.ts b/apps/api/src/modules/agents/core/prompt/framing.ts
index 6adb4326..b85bd487 100644
--- a/apps/api/src/modules/agents/core/prompt/framing.ts
+++ b/apps/api/src/modules/agents/core/prompt/framing.ts
@@ -1,5 +1,6 @@
import { peoplePreamble, type Person } from './run-context';
import { parseMentionHandles } from '#shared/mentions';
+import { PROJECT_DESCRIPTION_LIMIT } from '#modules/projects/model';
import type { AgentRunTrigger } from '../../model';
// Frames a triggered run into the text an agent receives: the framed user
@@ -129,12 +130,18 @@ function frameMention(run: RunForPrompt, titled: string): string {
// A leading system-instruction block naming the project the agent works in. Grounds
// every run — the test chat, the issue-triggered runs, and the ones a runner executes
// — so the agent knows which project its tools act on and how issue keys are formed.
-export function projectPreamble(project: { key: string; name: string }): string {
+export function projectPreamble(project: {
+ key: string;
+ name: string;
+ description: string;
+}): string {
+ const description = project.description.trim().slice(0, PROJECT_DESCRIPTION_LIMIT);
return [
'## Current project',
`You are working in the project "${project.name}" (key ${project.key}). All your`,
`work-item tools act on this project only, and its issues are addressed by keys`,
`like ${project.key}-123.`,
+ ...(description ? ['', description] : []),
'',
'',
].join('\n');
diff --git a/apps/api/src/modules/agents/runner/service.ts b/apps/api/src/modules/agents/runner/service.ts
index 100b98cf..bf61c1b0 100644
--- a/apps/api/src/modules/agents/runner/service.ts
+++ b/apps/api/src/modules/agents/runner/service.ts
@@ -34,6 +34,7 @@ export interface RunnerAgent {
// which go into the system prompt handed out with a run.
projectKey: string;
projectName: string;
+ projectDescription: string;
instructions: string | null;
}
@@ -50,6 +51,7 @@ export async function getRunnerAgent(userId: string): Promise<RunnerAgent | null
username: aiAgent.username,
projectKey: project.key,
projectName: project.name,
+ projectDescription: project.description,
instructions: aiAgent.instructions,
})
.from(aiAgent)
@@ -183,7 +185,11 @@ export async function claimRunnerRun(agent: RunnerAgent): Promise<RunnerRun | nu
function buildSystemPrompt(agent: RunnerAgent, run: RunForPrompt): string {
const instructions = agent.instructions?.trim();
return (
- projectPreamble({ key: agent.projectKey, name: agent.projectName }) +
+ projectPreamble({
+ key: agent.projectKey,
+ name: agent.projectName,
+ description: agent.projectDescription,
+ }) +
runModePreamble(run.trigger) +
peopleContext(run) +
(instructions ? `## Instructions\n${instructions}\n` : '')
diff --git a/apps/api/src/modules/projects/__tests__/integration/projects.test.ts b/apps/api/src/modules/projects/__tests__/integration/projects.test.ts
index 733963d6..914ba1ba 100644
--- a/apps/api/src/modules/projects/__tests__/integration/projects.test.ts
+++ b/apps/api/src/modules/projects/__tests__/integration/projects.test.ts
@@ -162,6 +162,16 @@ describe('projects', () => {
});
});
+ it('rejects a description over the limit', async () => {
+ const { api } = await signUpClient();
+ await api.projects.post({ key: 'MKT', name: 'Marketing' });
+
+ const res = await api
+ .projects({ projectKey: 'MKT' })
+ .patch({ description: 'x'.repeat(2001) });
+ expect(res.status).toBe(400);
+ });
+
it('denies a non-member (owner-only)', async () => {
const owner = await signUpClient();
await owner.api.projects.post({ key: 'MKT', name: 'Marketing' });
diff --git a/apps/api/src/modules/projects/index.ts b/apps/api/src/modules/projects/index.ts
index 253b1ebe..375e12cb 100644
--- a/apps/api/src/modules/projects/index.ts
+++ b/apps/api/src/modules/projects/index.ts
@@ -15,6 +15,7 @@ import { listCustomFields } from '#modules/custom-fields/service';
import {
AutoArchiveResponse,
EstimatesResponse,
+ PROJECT_DESCRIPTION_LIMIT,
ProjectBoardResponse,
ProjectListResponse,
ProjectResponse,
@@ -184,7 +185,10 @@ export const projectRoutes = new Elysia({ name: 'projects', detail: { tags: ['Pr
response: { 200: ProjectResponse, ...commonErrors },
detail: {
summary: 'Update a project',
- description: "Update a project's name and/or description. The key is immutable.",
+ description:
+ "Update a project's name and/or description. The description is given to the " +
+ `agents of the project in their system prompt; up to ${PROJECT_DESCRIPTION_LIMIT} ` +
+ 'characters. The key is immutable.',
...mcpTool('update_project'),
},
},
diff --git a/apps/api/src/modules/projects/model.ts b/apps/api/src/modules/projects/model.ts
index 875cbb56..d25cd561 100644
--- a/apps/api/src/modules/projects/model.ts
+++ b/apps/api/src/modules/projects/model.ts
@@ -7,10 +7,14 @@ import { PermissionMatrixSchema } from '#shared/permissions';
import { ISSUE_TYPE_PRESET_KEYS } from './service';
import { COPY_INCLUDE_KEYS } from './copy';
+// The description goes into the system prompt of every agent run, where it costs
+// input tokens each time, so it is capped on the way in and cut again in the prompt.
+export const PROJECT_DESCRIPTION_LIMIT = 2000;
+
const projectBody = t.Object({
key: t.String({ minLength: 1 }),
name: t.String({ minLength: 1 }),
- description: t.Optional(t.String()),
+ description: t.Optional(t.String({ maxLength: PROJECT_DESCRIPTION_LIMIT })),
});
// Create adds the issue-type preset: which set of types the new project starts with.
@@ -43,7 +47,7 @@ export const copyProjectBody = t.Composite([
export const updateProjectBody = t.Object({
name: t.Optional(t.String({ minLength: 1 })),
- description: t.Optional(t.String()),
+ description: t.Optional(t.String({ maxLength: PROJECT_DESCRIPTION_LIMIT })),
});
export const listProjectsQuery = t.Object({
diff --git a/apps/web/src/features/settings/components/general/SettingsGeneral.tsx b/apps/web/src/features/settings/components/general/SettingsGeneral.tsx
index ce783514..c52371db 100644
--- a/apps/web/src/features/settings/components/general/SettingsGeneral.tsx
+++ b/apps/web/src/features/settings/components/general/SettingsGeneral.tsx
@@ -34,6 +34,7 @@ export default function SettingsGeneral({ form }: { form: GeneralForm }) {
<Textarea
id="project-description"
rows={3}
+ maxLength={2000}
value={form.description}
onChange={(e) => form.setDescription(e.target.value)}
disabled={!form.editable}