⭐️⭐️⭐️ 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
import { db, aiAgent, agentRun, project, projectMember } from '@repo/db';
import { and, eq, isNotNull, isNull, or, sql } from 'drizzle-orm';
import { HttpError } from '#shared/lib';
import { type ContextUsage } from '../chat-usage';
import {
agentRunConfig,
deferRun,
runTurn,
loadRunThread,
markRunExecuting,
runRetryDelayMs,
scheduleRunRetry,
} from '../core/run-queue';
import { agentRunStarted, recordAgentRunFinished } from '../core/run-activity';
import { emitRunsFinished } from '../core/run-finished';
import { runAdmissionDelay } from '../core/run-admission';
import type { AgentKind } from '../core/service';
import type { AgentRunTrigger } from '../model';
import {
framePrompt,
peopleContext,
projectPreamble,
runModePreamble,
type RunForPrompt,
} from '../core/prompt/framing';
// The queue an external agent's runner drains. The runner is a process the operator
// starts on their own machine; it authenticates with the agent's API key, claims one
// run at a time, executes whatever command it is configured with, and reports the
// result back. The task is framed here, the same way it is for an internal agent, so
// every runner gets a task that says what started the run and what to do about it
// without having to build that itself. Claiming works exactly like the worker's: the
// row stays 'pending' and its next_attempt_at is pushed forward by a lease, so a run
// whose runner dies mid-flight becomes claimable again once the lease expires.
// The project facts a system prompt names.
export interface RunnerProject {
key: string;
name: string;
description: string;
}
export interface RunnerAgent {
id: number;
teamId: number;
kind: AgentKind;
// The agent's bot user, so a run's prompts do not name the agent to itself, and
// the handle it is addressed by.
userId: string;
username: string;
// The projects of the team the agent works in, and the operator's own instructions.
// A chat names all of them in the system prompt; a run names the one it works in.
projects: RunnerProject[];
instructions: string | null;
// Set when the agent is sent its work rather than drained by a runner.
invocationUrl: string | null;
}
// The agent whose bot user is the caller, or null when the caller is not an agent.
// The API key identifies the agent, so holding it is the authorization to drain its
// queue — no permission check applies.
export async function getRunnerAgent(userId: string): Promise<RunnerAgent | null> {
const rows = await db
.select({
id: aiAgent.id,
teamId: aiAgent.teamId,
kind: aiAgent.kind,
userId: aiAgent.userId,
username: aiAgent.username,
instructions: aiAgent.instructions,
invocationUrl: aiAgent.invocationUrl,
})
.from(aiAgent)
.where(eq(aiAgent.userId, userId))
.limit(1);
const row = rows[0];
if (!row) return null;
const projects = await db
.select({ key: project.key, name: project.name, description: project.description })
.from(projectMember)
.innerJoin(project, eq(project.id, projectMember.projectId))
.where(and(eq(projectMember.userId, userId), eq(project.teamId, row.teamId)))
.orderBy(project.key);
return { ...row, kind: row.kind as AgentKind, projects };
}
export interface RunnerRun {
traceEvents: boolean;
id: number;
trigger: AgentRunTrigger;
// The task as the agent should read it: the trigger text framed with what started
// the run and what to do about it, the same framing an internal agent gets.
prompt: string;
// Instructions about the run itself — that it is autonomous, and who the people
// behind it are — for the agent's system prompt rather than its task.
systemPrompt: string;
attempts: number;
issueId: number | null;
// The issue's human-readable key ("MKT-42"), so the runner can name the work in its
// log. Null for a run with no issue, or a deleted one.
issueIdentifier: string | null;
}
// The claim's raw row, before framing. The extra people columns exist only to build
// the prompts and are not handed to the runner.
type ClaimedRow = Omit<RunnerRun, 'systemPrompt' | 'traceEvents'> & {
// The project the run works in, which is what its system prompt names.
projectId: number;
projectKey: string;
projectName: string;
projectDescription: string;
issueTitle: string | null;
assigneeName: string | null;
assigneeUsername: string | null;
requesterName: string | null;
requesterUsername: string | null;
sourceActivityId: number | null;
documentId: number | null;
sourceDocumentCommentId: string | null;
scheduleId: number | null;
};
// Records that a runner polled, which is what the UI shows as the agent's presence.
// The chat feed calls it too: both queues are drained by the same runner.
export async function touchRunner(agentId: number): Promise<void> {
await db.update(aiAgent).set({ lastSeenAt: new Date() }).where(eq(aiAgent.id, agentId));
}
// Fails runs that were handed out too many times without a result, so a run whose
// runner keeps dying ends in a visible state instead of being served forever. That is
// the end of the run, so the issue's timeline gets the same entry a reported failure
// writes.
async function expireExhaustedRuns(agent: RunnerAgent): Promise<void> {
const rows = await db
.update(agentRun)
.set({
status: 'failed',
executionStartedAt: null,
lastError: 'Runner did not report a result',
finishedAt: new Date(),
})
.where(
and(
eq(agentRun.agentId, agent.id),
eq(agentRun.status, 'pending'),
sql`${agentRun.attempts} >= ${agentRunConfig.maxAttempts()}`,
sql`${agentRun.nextAttemptAt} <= now()`,
),
)
.returning({ id: agentRun.id, issueId: agentRun.issueId });
for (const row of rows)
await recordAgentRunFinished({ ...row, agentUserId: agent.userId }, 'failed');
await emitRunsFinished(rows.map((row) => row.id));
}
// An agent with an invocation URL is sent its work, so a runner that claims as well
// would take tasks the endpoint is meant to get. The endpoint reports through the runner
// routes too; only the claims are refused.
export function assertRunnerDrained(agent: RunnerAgent): void {
if (agent.invocationUrl) {
throw new HttpError(409, 'This agent receives its work at its invocation URL');
}
}
export async function claimRunnerRun(agent: RunnerAgent): Promise<RunnerRun | null> {
assertRunnerDrained(agent);
await touchRunner(agent.id);
return takeNextRun(agent);
}
// Claims the agent's next due run, or null when it has none. FOR UPDATE SKIP LOCKED
// keeps two claims on the same agent from taking the same run.
export async function takeNextRun(agent: RunnerAgent): Promise<RunnerRun | null> {
const agentId = agent.id;
await expireExhaustedRuns(agent);
const rows = await db.execute(sql`
UPDATE agent_run r
SET attempts = r.attempts + 1,
started_at = coalesce(r.started_at, now()),
execution_started_at = NULL,
next_attempt_at = now() + make_interval(secs => ${agentRunConfig.leaseSeconds()})
WHERE r.id = (
SELECT id FROM agent_run q
WHERE q.agent_id = ${agentId} AND q.status = 'pending' AND q.next_attempt_at <= now()
AND ${runTurn}
ORDER BY q.next_attempt_at, q.id
FOR UPDATE SKIP LOCKED
LIMIT 1
)
RETURNING
r.id,
r.trigger,
r.prompt,
r.attempts,
r.issue_id AS "issueId",
r.schedule_id AS "scheduleId",
r.project_id AS "projectId",
(SELECT p.key FROM project p WHERE p.id = r.project_id) AS "projectKey",
(SELECT p.name FROM project p WHERE p.id = r.project_id) AS "projectName",
(SELECT p.description FROM project p WHERE p.id = r.project_id) AS "projectDescription",
(SELECT p.key || '-' || i.sequence_number
FROM issue i JOIN project p ON p.id = i.project_id
WHERE i.id = r.issue_id) AS "issueIdentifier",
(SELECT title FROM issue i WHERE i.id = r.issue_id) AS "issueTitle",
(SELECT u.name FROM issue i JOIN "user" u ON u.id = i.assignee_user_id
WHERE i.id = r.issue_id) AS "assigneeName",
(SELECT COALESCE(u.username, ag.username)
FROM issue i JOIN "user" u ON u.id = i.assignee_user_id
LEFT JOIN ai_agent ag ON ag.user_id = u.id
WHERE i.id = r.issue_id) AS "assigneeUsername",
r.source_activity_id AS "sourceActivityId",
r.document_id AS "documentId",
r.source_document_comment_id AS "sourceDocumentCommentId",
(SELECT actor_name FROM issue_activity a WHERE a.id = r.source_activity_id) AS "requesterName",
(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"
`);
const row = (rows as unknown as ClaimedRow[])[0];
if (!row) return null;
const wait = await runAdmissionDelay({ ...row, agentId });
if (wait > 0) {
await deferRun(row.id, wait);
return null;
}
const forPrompt = {
...row,
agentUserId: agent.userId,
agentUsername: agent.username,
...(await loadRunThread(row)),
};
// A start that fails is a failed attempt: the run comes back after the retry delay,
// with the error on it, rather than being handed out half started.
try {
await agentRunStarted(forPrompt);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
await scheduleRunRetry(row.id, runRetryDelayMs(row.attempts), message);
return null;
}
const result = {
traceEvents: true,
id: row.id,
trigger: row.trigger,
prompt: framePrompt(forPrompt),
systemPrompt: buildSystemPrompt(
agent,
{ key: row.projectKey, name: row.projectName, description: row.projectDescription },
forPrompt,
),
attempts: row.attempts,
issueId: row.issueId,
issueIdentifier: row.issueIdentifier,
};
if (!(await markRunExecuting(row.id, row.attempts))) return null;
return result;
}
// What the agent is told about the run before the task itself: the project the run
// works in, that the run is autonomous, who the people behind it are, and last the
// operator's own instructions from the agent's settings, which therefore win over the
// generic parts.
function buildSystemPrompt(agent: RunnerAgent, project: RunnerProject, run: RunForPrompt): string {
const instructions = agent.instructions?.trim();
return (
projectPreamble(project) +
runModePreamble(run) +
peopleContext(run) +
(instructions ? `## Instructions\n${instructions}\n` : '')
);
}
// Extends a claimed run's lease while the runner is still working on it. A command
// can outlive the lease by far, so the runner sends this periodically; without it the
// run would be handed to another runner mid-flight. False when the run is not this
// agent's, or is already finished.
export async function heartbeatRun(
agentId: number,
runId: number,
attempt?: number,
): Promise<boolean> {
await touchRunner(agentId);
const rows = await db
.update(agentRun)
.set({
executionStartedAt: sql`coalesce(${agentRun.executionStartedAt}, now())`,
nextAttemptAt: sql`now() + make_interval(secs => ${agentRunConfig.leaseSeconds()})`,
})
.where(
and(
eq(agentRun.id, runId),
eq(agentRun.agentId, agentId),
eq(agentRun.status, 'pending'),
attempt == null ? undefined : eq(agentRun.attempts, attempt),
isNotNull(agentRun.startedAt),
or(isNotNull(agentRun.executionStartedAt), isNull(agentRun.lastError)),
),
)
.returning({ id: agentRun.id });
return rows.length > 0;
}
// Records the outcome the runner reports. A failure is terminal: the runner ran the
// command and it failed, so re-serving the same run would just repeat it. False when
// the run is not this agent's, or was already finished.
export async function finishRun(
agent: RunnerAgent,
runId: number,
result: {
status: 'success' | 'failed';
attempt?: number;
output?: string | null;
error?: string | null;
usage?: ContextUsage | null;
},
): Promise<boolean> {
await touchRunner(agent.id);
const rows = await db
.update(agentRun)
.set({
status: result.status,
executionStartedAt: null,
output: result.output?.slice(0, 10_000) ?? null,
lastError: result.status === 'failed' ? (result.error?.slice(0, 500) ?? 'Run failed') : null,
inputTokens: result.usage?.inputTokens ?? null,
outputTokens: result.usage?.outputTokens ?? null,
finishedAt: new Date(),
})
.where(
and(
eq(agentRun.id, runId),
eq(agentRun.agentId, agent.id),
eq(agentRun.status, 'pending'),
result.attempt == null ? undefined : eq(agentRun.attempts, result.attempt),
),
)
.returning({ id: agentRun.id, issueId: agentRun.issueId });
const row = rows[0];
if (!row) return false;
await recordAgentRunFinished({ ...row, agentUserId: agent.userId }, result.status);
await emitRunsFinished([row.id]);
return true;
}