⭐️⭐️⭐️ 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,
user,
apikey,
project,
projectColumn,
projectMember,
team,
teamMember,
agentSkillLink,
agentToolLink,
agentFieldTrigger,
customField,
integrationCredential,
} from '@repo/db';
import { and, asc, eq, inArray, ne, notInArray, sql } from 'drizzle-orm';
import { auth } from '@repo/auth';
import { iso, HttpError, rethrowDuplicate } from '#shared/lib';
import { getCredentialById } from '../integrations/service';
import { integrationKind } from '../integrations/catalog';
import { encryptSecret, decryptSecret } from '@repo/crypto';
import { normalizeToolKeys, ALWAYS_ON_ACTIONS } from './runtime/tools/catalog';
import { deleteThreadsWhere } from './runtime/memory';
import { listAgentMemberFieldIds } from '#modules/custom-fields/service';
import { runsTeam, type TeamStanding } from '#modules/teams/service';
import type { TeamMembership } from '#shared/access';
import { projectRefSql } from '#modules/teams/ref';
import { getDefaultRoleId } from '#modules/roles/service';
import { deleteAccount } from '#shared/account-deletion';
import { assertPublicHttpUrl } from '#shared/net';
import { ensureInvocationSecret } from '../invocation/secret';
// Data access for AI agents. Each agent is backed by a hidden bot user
// (ai_agent.user_id -> user.id): that user is what a work item is assigned to,
// what authors comments/activity, and what owns the agent's better-auth API key
// (apikey.reference_id).
//
// An agent belongs to a team and works in the projects of that team it is attached
// to; a project_member row is what says so, and one key therefore reaches every one
// of them. Both kinds of agent act through the same API under the same authorization:
// each owns an API key and project_member rows carrying its team role, so its requests
// are checked by the normal permission matrix. The kinds differ in who drives them:
// an external agent is driven over HTTP by its operator, who holds the key; an
// internal agent is driven by the built-in runtime, carries a model configuration,
// and replays its own key against the routes in process. That is why an internal
// agent's key is also kept here, encrypted — better-auth only stores a hash, and the
// runtime needs the secret on every tool call. An internal agent's effective rights
// are the intersection of its granted actions (ai_agent.tools) and its role.
export type AgentKind = 'external' | 'internal';
// Which runs an external agent's runner is served. 'project', the default: any
// member's runs, so an agent added to a project works for the whole team. 'owner':
// only runs triggered by the member who created it, for a runner whose machine and
// credentials should serve nobody else.
export type RunnerScope = 'owner' | 'team';
// The reasoning effort levels the provider SDKs share (see runtime/index.ts).
export type ReasoningEffort = 'low' | 'medium' | 'high';
// One member custom field an agent reacts to, with the seconds its run waits before
// the agent may pick it up.
export interface FieldTrigger {
fieldId: number;
delaySec: number;
}
// The same trigger as a read of an agent returns it: the field's name comes along, so
// a reader can name the field without loading the project it belongs to.
export interface FieldTriggerRead extends FieldTrigger {
name: string;
}
// A project the agent is a member of, as the settings screen lists them.
export interface AgentProject {
id: number;
key: string;
ref: string;
name: string;
}
export interface AiAgentRow {
id: number;
teamId: number;
userId: string;
// The projects of the team the agent works in, by key. Membership is what grants
// its key access to a project, so this is the list an operator edits.
projects: AgentProject[];
// name lives on the bot user; username is the team-scoped handle.
name: string;
username: string;
kind: AgentKind;
modelCredentialId: number | null;
model: string | null;
instructions: string | null;
tools: string[];
temperature: number | null;
reasoningEffort: ReasoningEffort | null;
maxSteps: number | null;
runTimeoutSec: number | null;
// Conversation memory: recall the last memoryLastMessages messages of a thread.
memoryEnabled: boolean;
memoryLastMessages: number | null;
// Run triggers.
triggerOnMention: boolean;
triggerOnAssign: boolean;
// Whether the agent may be chatted with; a mention, a delegation and a schedule ignore it.
chatEnabled: boolean;
// The member custom fields the agent also reacts to: being set into one of them
// starts a run the way being made an issue's delegate does. Each field carries its
// own delay, so a field can start at once while another leaves time to edit.
fieldTriggers: FieldTriggerRead[];
// How long a delegation run waits before it can be claimed.
delegationDelaySec: number;
// The member who created the agent, and whose runs an 'owner'-scoped runner is
// limited to. 'team' scope lets the runner take any member's runs.
ownerUserId: string | null;
runnerScope: RunnerScope;
// When a runner last polled for this agent, which is what presence is derived
// from. Null until a runner connects.
lastSeenAt: string | null;
// Where an external agent's work is sent instead of being claimed by a runner, or
// null when a runner drains it.
invocationUrl: string | null;
createdAt: string;
// The agent's current API key, for display only — the secret is never returned
// after creation. start is the key's leading characters kept for identification.
apiKeyStart: string | null;
// The integration key of the model credential (the provider, e.g. "openai"), or
// null when no credential is set. For the list's meta display.
modelProvider: string | null;
// How many actions the agent can take, how many skills and configured tools are
// enabled. actionCount is the always-on read-only actions plus the granted mutating
// ones (`tools`), matching the Actions section of the editor. For the meta display.
actionCount: number;
skillCount: number;
toolCount: number;
}
function mapAgent(row: {
id: number;
teamId: number;
projects: AgentProject[];
userId: string;
name: string;
username: string;
kind: string;
modelCredentialId: number | null;
model: string | null;
instructions: string | null;
tools: unknown;
temperature: number | null;
reasoningEffort: string | null;
maxSteps: number | null;
runTimeoutSec: number | null;
memoryEnabled: boolean;
memoryLastMessages: number | null;
triggerOnMention: boolean;
triggerOnAssign: boolean;
chatEnabled: boolean;
fieldTriggers: FieldTriggerRead[];
delegationDelaySec: number;
ownerUserId: string | null;
runnerScope: string;
lastSeenAt: Date | null;
invocationUrl: string | null;
createdAt: Date;
apiKeyStart: string | null;
modelProvider: string | null;
skillCount: number;
toolCount: number;
}): AiAgentRow {
const tools = Array.isArray(row.tools) ? (row.tools as string[]) : [];
return {
id: row.id,
teamId: row.teamId,
projects: row.projects,
userId: row.userId,
name: row.name,
username: row.username,
kind: row.kind as AgentKind,
modelCredentialId: row.modelCredentialId,
model: row.model,
instructions: row.instructions,
tools,
temperature: row.temperature,
reasoningEffort: row.reasoningEffort as ReasoningEffort | null,
maxSteps: row.maxSteps,
runTimeoutSec: row.runTimeoutSec,
memoryEnabled: row.memoryEnabled,
memoryLastMessages: row.memoryLastMessages,
triggerOnMention: row.triggerOnMention,
triggerOnAssign: row.triggerOnAssign,
chatEnabled: row.chatEnabled,
fieldTriggers: row.fieldTriggers,
delegationDelaySec: row.delegationDelaySec,
ownerUserId: row.ownerUserId,
runnerScope: row.runnerScope as RunnerScope,
lastSeenAt: row.lastSeenAt ? iso(row.lastSeenAt) : null,
invocationUrl: row.invocationUrl,
createdAt: iso(row.createdAt),
apiKeyStart: row.apiKeyStart,
modelProvider: row.modelProvider,
actionCount: tools.length + ALWAYS_ON_ACTIONS.length,
skillCount: row.skillCount,
toolCount: row.toolCount,
};
}
const agentColumns = {
id: aiAgent.id,
teamId: aiAgent.teamId,
// The projects of the agent's own team it is a member of. A membership in a project
// of another team cannot happen (the attach route refuses it) and is not listed.
projects: sql<
AgentProject[]
>`(select coalesce(json_agg(json_build_object('id', ${project.id}, 'key', ${project.key}, 'ref', ${projectRefSql}, 'name', ${project.name}) order by ${project.key}), '[]'::json) from ${projectMember} join ${project} on ${project.id} = ${projectMember.projectId} join ${team} on ${team.id} = ${project.teamId} where ${projectMember.userId} = ${aiAgent.userId} and ${project.teamId} = ${aiAgent.teamId})`,
userId: aiAgent.userId,
name: user.name,
username: aiAgent.username,
kind: aiAgent.kind,
modelCredentialId: aiAgent.modelCredentialId,
model: aiAgent.model,
instructions: aiAgent.instructions,
tools: aiAgent.tools,
temperature: aiAgent.temperature,
reasoningEffort: aiAgent.reasoningEffort,
maxSteps: aiAgent.maxSteps,
runTimeoutSec: aiAgent.runTimeoutSec,
memoryEnabled: aiAgent.memoryEnabled,
memoryLastMessages: aiAgent.memoryLastMessages,
triggerOnMention: aiAgent.triggerOnMention,
triggerOnAssign: aiAgent.triggerOnAssign,
chatEnabled: aiAgent.chatEnabled,
fieldTriggers: sql<
FieldTriggerRead[]
>`(select coalesce(json_agg(json_build_object('fieldId', ${agentFieldTrigger.fieldId}, 'name', ${customField.name}, 'delaySec', ${agentFieldTrigger.delaySec}) order by ${customField.name}), '[]'::json) from ${agentFieldTrigger} join ${customField} on ${customField.id} = ${agentFieldTrigger.fieldId} where ${agentFieldTrigger.agentId} = ${aiAgent.id})`,
delegationDelaySec: aiAgent.delegationDelaySec,
ownerUserId: aiAgent.ownerUserId,
runnerScope: aiAgent.runnerScope,
lastSeenAt: aiAgent.lastSeenAt,
invocationUrl: aiAgent.invocationUrl,
createdAt: aiAgent.createdAt,
apiKeyStart: apikey.start,
modelProvider: integrationCredential.integrationKey,
skillCount:
sql<number>`(select count(*) from ${agentSkillLink} where ${agentSkillLink.agentId} = ${aiAgent.id})`.mapWith(
Number,
),
toolCount:
sql<number>`(select count(*) from ${agentToolLink} where ${agentToolLink.agentId} = ${aiAgent.id})`.mapWith(
Number,
),
};
// The bot user carries the name, the key row the prefix, and the credential the
// provider, so every read of an agent joins the three.
function agentQuery() {
return db
.select(agentColumns)
.from(aiAgent)
.innerJoin(user, eq(user.id, aiAgent.userId))
.leftJoin(apikey, eq(apikey.referenceId, aiAgent.userId))
.leftJoin(integrationCredential, eq(integrationCredential.id, aiAgent.modelCredentialId));
}
// Whether the agent is a member of the project, as a condition on a query over
// ai_agent. Membership is held by the bot user, so it is a project_member row of it.
function inProject(projectId: number) {
return sql`exists (select 1 from ${projectMember} pm where pm.user_id = ${aiAgent.userId} and pm.project_id = ${projectId})`;
}
// The agents a caller may reach: an owner or a manager of the team reaches every agent
// it has, anyone else only the ones working in a project they are a member of. The
// reads below take the id it returns, or nothing when the whole team is theirs.
export function agentScopeOf(membership: {
role: TeamStanding;
userId: string;
}): string | undefined {
return runsTeam(membership.role) ? undefined : membership.userId;
}
// The projects of the team the user is a member of. Attaching an agent to a project
// makes its bot user a member of that one, so the set bounds where someone who does
// not run the team may put an agent.
export async function memberProjectIds(teamId: number, userId: string): Promise<number[]> {
const rows = await db
.select({ id: project.id })
.from(projectMember)
.innerJoin(project, eq(project.id, projectMember.projectId))
.where(and(eq(project.teamId, teamId), eq(projectMember.userId, userId)));
return rows.map((row) => row.id);
}
// The agents, each with whether the caller may act on it as a whole, by the rule
// assertFullAgentAccess applies, so a screen can hide what the caller would be refused.
export async function withCanManage<T extends { projects: { id: number }[] }>(
membership: TeamMembership,
agents: T[],
): Promise<(T & { canManage: boolean })[]> {
const runs = runsTeam(membership.role);
const mine = new Set(runs ? [] : await memberProjectIds(membership.teamId, membership.userId));
return agents.map((agent) => ({
...agent,
canManage: runs || agent.projects.every((p) => mine.has(p.id)),
}));
}
// Regenerating the key, editing the agent, changing its tools or skills, deleting it, or
// reading its invocation secret acts on the agent in every project it works in — the key
// authenticates as the bot in all of them, and the secret signs the work it runs there.
// The visibility check only needs one shared project, so a caller who shares just one
// must not reach the others: these require running the team or being a member of every
// project the agent is in.
export async function assertFullAgentAccess(
membership: TeamMembership,
agentId: number,
): Promise<void> {
if (runsTeam(membership.role)) return;
const agent = await getAgentById(agentId, membership.teamId);
if (!agent) throw new HttpError(404, 'Agent not found');
const [{ canManage }] = await withCanManage(membership, [agent]);
if (!canManage) {
throw new HttpError(
403,
'Only a team owner or manager, or a member of every project the agent works in, can do this',
);
}
}
// Whether the agent works in a project the user is a member of, as a condition on a
// query over ai_agent. Both sides are project_member rows: the agent's bot user and
// the user themselves.
function sharesProjectWith(userId: string) {
return sql`exists (select 1 from ${projectMember} pm join ${projectMember} mine on mine.project_id = pm.project_id and mine.user_id = ${userId} where pm.user_id = ${aiAgent.userId})`;
}
export async function listProjectAgents(projectId: number) {
const rows = await db
.select({ id: aiAgent.id, name: user.name, kind: aiAgent.kind, model: aiAgent.model })
.from(aiAgent)
.innerJoin(user, eq(user.id, aiAgent.userId))
.where(inProject(projectId))
.orderBy(asc(user.name));
return rows.map((row) => ({ ...row, kind: row.kind as AgentKind }));
}
// The agents of the team, or only the ones working in one of its projects when
// projectId is given. visibleTo narrows the list to the agents working in a project
// that user belongs to; the callers who run the team pass nothing and see them all.
export async function listAgents(
teamId: number,
projectId?: number,
visibleTo?: string,
): Promise<AiAgentRow[]> {
const rows = await agentQuery()
.where(
and(
eq(aiAgent.teamId, teamId),
projectId == null ? undefined : inProject(projectId),
visibleTo == null ? undefined : sharesProjectWith(visibleTo),
),
)
.orderBy(user.name);
return rows.map(mapAgent);
}
// Scoped to teamId so an id from another team resolves to null, and to visibleTo the
// same way the list is: an agent of a project that user is not in reads as missing.
export async function getAgentById(
id: number,
teamId: number,
visibleTo?: string,
): Promise<AiAgentRow | null> {
const rows = await agentQuery().where(
and(
eq(aiAgent.id, id),
eq(aiAgent.teamId, teamId),
visibleTo == null ? undefined : sharesProjectWith(visibleTo),
),
);
return rows[0] ? mapAgent(rows[0]) : null;
}
// The agent of that id that works in the project, or null. A run addresses an agent
// together with the project it is to work in, and membership is what allows it: an
// agent detached from a project stops running there, whatever was queued for it.
export async function getAgentInProject(id: number, projectId: number): Promise<AiAgentRow | null> {
const rows = await agentQuery().where(and(eq(aiAgent.id, id), inProject(projectId)));
return rows[0] ? mapAgent(rows[0]) : null;
}
// An agent may run for whoever triggered it: always an internal agent, which runs on
// our side, and an external one only when its runner is team-scoped or the trigger
// came from the agent's owner, whose machine that runner is. An 'owner'-scoped agent
// without an owner names nobody to restrict it to — the account was deleted — so it
// takes any member's runs rather than silently stopping.
export function isTriggerableBy(
agent: { kind: string; runnerScope: string; ownerUserId: string | null },
actorUserId: string | null,
): boolean {
if (agent.kind === 'internal' || agent.runnerScope !== 'owner' || !agent.ownerUserId) return true;
return agent.ownerUserId === actorUserId;
}
// Asked for a chat message only: a queued run (a mention, a delegation, a schedule)
// ignores chatEnabled.
export function assertChatEnabled(agent: { chatEnabled: boolean }): void {
if (!agent.chatEnabled) {
throw new HttpError(403, 'This agent is not available in chat', 'AGENT_CHAT_DISABLED');
}
}
const triggerScopeColumns = {
kind: aiAgent.kind,
runnerScope: aiAgent.runnerScope,
ownerUserId: aiAgent.ownerUserId,
};
// Whether the member may send the agent a task, for the paths that queue a run
// outside the mention and delegation triggers (a schedule). An agent that no longer
// exists reads as triggerable — the caller's own lookup reports it missing.
export async function canTriggerAgent(agentId: number, actorUserId: string): Promise<boolean> {
const rows = await db
.select(triggerScopeColumns)
.from(aiAgent)
.where(eq(aiAgent.id, agentId))
.limit(1);
return !rows[0] || isTriggerableBy(rows[0], actorUserId);
}
// Agents working in the project whose bot user is among the given ids and that react
// to mentions. Turns the user ids parsed from a comment's mentions into the agents that
// should run for the comment's author. An agent of the team that is not a member of
// this project is left out: a mention must not pull a key into a project the team
// never opened it to.
export async function listMentionTriggerAgents(
projectId: number,
userIds: string[],
actorUserId: string | null,
): Promise<{ id: number; userId: string }[]> {
if (userIds.length === 0) return [];
const rows = await db
.select({ id: aiAgent.id, userId: aiAgent.userId, ...triggerScopeColumns })
.from(aiAgent)
.where(
and(
inProject(projectId),
eq(aiAgent.triggerOnMention, true),
inArray(aiAgent.userId, userIds),
),
);
return rows
.filter((row) => isTriggerableBy(row, actorUserId))
.map((row) => ({ id: row.id, userId: row.userId }));
}
// The agent working in the project whose bot user is userId and that reacts to being
// delegated to, or null. Turns a new delegate into the agent that should run on
// delegation.
export async function getAssignTriggerAgent(
projectId: number,
userId: string,
actorUserId: string | null,
): Promise<{ id: number; delegationDelaySec: number } | null> {
const rows = await db
.select({
id: aiAgent.id,
delegationDelaySec: aiAgent.delegationDelaySec,
...triggerScopeColumns,
})
.from(aiAgent)
.where(and(eq(aiAgent.userId, userId), eq(aiAgent.triggerOnAssign, true), inProject(projectId)))
.limit(1);
const row = rows[0];
if (!row || !isTriggerableBy(row, actorUserId)) return null;
return { id: row.id, delegationDelaySec: row.delegationDelaySec };
}
// The agent working in the project whose bot user is userId and that reacts to being
// set into that member field, or null. The counterpart of getAssignTriggerAgent for a
// custom field.
export async function getFieldTriggerAgent(
projectId: number,
userId: string,
fieldId: number,
actorUserId: string | null,
): Promise<{ id: number; delaySec: number } | null> {
const rows = await db
.select({
id: aiAgent.id,
delaySec: agentFieldTrigger.delaySec,
...triggerScopeColumns,
})
.from(aiAgent)
.innerJoin(agentFieldTrigger, eq(agentFieldTrigger.agentId, aiAgent.id))
.where(
and(eq(aiAgent.userId, userId), eq(agentFieldTrigger.fieldId, fieldId), inProject(projectId)),
)
.limit(1);
const row = rows[0];
if (!row || !isTriggerableBy(row, actorUserId)) return null;
return { id: row.id, delaySec: row.delaySec };
}
// Replaces the member fields an agent reacts to. A field that is not a member field
// holding agents in one of the agent's projects is dropped, so a stale id from a
// client never links.
async function setFieldTriggers(
agentId: number,
projectIds: number[],
triggers: FieldTrigger[],
): Promise<void> {
const allowed = new Set(await listAgentMemberFieldIds(projectIds));
const byField = new Map(
triggers.filter((t) => allowed.has(t.fieldId)).map((t) => [t.fieldId, t.delaySec]),
);
await db.transaction(async (tx) => {
await tx.delete(agentFieldTrigger).where(eq(agentFieldTrigger.agentId, agentId));
if (byField.size > 0) {
await tx
.insert(agentFieldTrigger)
.values([...byField].map(([fieldId, delaySec]) => ({ agentId, fieldId, delaySec })));
}
});
}
// True if the user id is the bot user of an agent working in this project. Validates
// that a delegate is an agent of the project before it is written to an issue, and is
// what keeps the delegation and field triggers off an agent that is not a member.
export async function isProjectAgent(projectId: number, userId: string): Promise<boolean> {
const rows = await db
.select({ id: aiAgent.id })
.from(aiAgent)
.where(and(eq(aiAgent.userId, userId), inProject(projectId)))
.limit(1);
return rows.length > 0;
}
// The team of the agent a bot user belongs to, or null when the user is a person.
// An agent belongs to exactly one team, so this is the team its API key acts in.
export async function agentTeam(userId: string): Promise<number | null> {
const rows = await db
.select({ teamId: aiAgent.teamId })
.from(aiAgent)
.where(eq(aiAgent.userId, userId))
.limit(1);
return rows[0]?.teamId ?? null;
}
// True if the user id is an agent's bot user rather than a person's.
export async function isAgentUser(userId: string): Promise<boolean> {
return (await agentTeam(userId)) !== null;
}
// An unknown, foreign, or non-LLM credential id would otherwise be stored and only
// surface later, as a run that fails to start. Credentials belong to the team, so an
// id from another team is what counts as foreign.
async function assertModelCredential(
teamId: number,
credentialId: number | null | undefined,
): Promise<void> {
if (credentialId == null) return;
const credential = await getCredentialById(credentialId, teamId);
if (!credential) throw new HttpError(400, 'Credential not found');
if (integrationKind(credential.integrationKey) !== 'llm') {
throw new HttpError(
400,
`A model needs an LLM provider credential, not ${credential.integrationKey}.`,
);
}
}
// The projects of the team the agent is to work in. An id that is not a project of the
// team is refused rather than dropped: attaching an agent to a project its team does
// not own would put its key somewhere the team never opened.
async function resolveTeamProjectIds(teamId: number, projectIds: number[]): Promise<number[]> {
const wanted = [...new Set(projectIds)];
if (wanted.length === 0) return [];
const rows = await db
.select({ id: project.id })
.from(project)
.where(and(eq(project.teamId, teamId), inArray(project.id, wanted)));
if (rows.length !== wanted.length) throw new HttpError(400, 'Project not found in this team');
return rows.map((row) => row.id);
}
export interface NewAgentInput {
name: string;
username: string;
kind: AgentKind;
modelCredentialId?: number | null;
model?: string | null;
instructions?: string | null;
tools?: string[];
temperature?: number | null;
reasoningEffort?: ReasoningEffort | null;
maxSteps?: number | null;
runTimeoutSec?: number | null;
memoryEnabled?: boolean;
memoryLastMessages?: number | null;
// Run triggers. Assign is off by default, and so is mention for an external agent:
// nothing answers its runs until its operator starts a runner, so an agent added
// for its API key alone must not collect runs no one drains.
triggerOnMention?: boolean;
triggerOnAssign?: boolean;
// Whether the agent may be chatted with. Defaults on.
chatEnabled?: boolean;
// The member custom fields that start a run when the agent is set into one.
fieldTriggers?: FieldTrigger[];
delegationDelaySec?: number;
// The projects of the team the agent works in. Empty means it works in none yet:
// it authenticates and reaches nothing until it is attached to one.
projectIds?: number[];
// External-agent runner scope (default: any member's runs).
runnerScope?: RunnerScope;
// Where an external agent's work is sent; omitted or null for one a runner drains.
invocationUrl?: string | null;
// The member creating the agent, who owns its runner.
ownerUserId?: string | null;
}
// A handle addresses one person or one agent, never several: a mention is resolved
// against the members and the agents of the project at once, and by the lowercased
// handle, so a name a member already answers to cannot be issued to an agent and two
// agents of a team cannot differ by case alone. The agents of a team are held to that
// by the unique index on (team_id, lower(username)); the check here turns a conflict
// into a message that names which side took the handle. The reverse check sits in
// @repo/auth, where a member's username is set.
async function assertUsernameFree(
teamId: number,
username: string,
exceptAgentId?: number,
): Promise<void> {
const handle = username.toLowerCase();
if ((await db.$count(user, eq(user.username, handle))) > 0)
throw new HttpError(409, 'A member already uses this username');
const conflicts = and(
eq(aiAgent.teamId, teamId),
eq(sql`lower(${aiAgent.username})`, handle),
exceptAgentId == null ? undefined : ne(aiAgent.id, exceptAgentId),
);
if ((await db.$count(aiAgent, conflicts)) > 0)
throw new HttpError(409, 'An agent with this username already exists');
}
// Issues a fresh API key owned by the agent's bot user and returns its plaintext
// value (only available at creation). The server-side call sets the owner via
// userId — better-auth allows this only for a direct (non-request) server call.
//
// The key carries no expiry, unlike a personal one: an internal agent replays its
// stored secret with nothing that would renew it, and an external agent's key is
// rotated by its operator through regenerate-key. The plugin puts its default on
// every key it creates, so the expiry is cleared on the row afterwards.
async function issueKey(userId: string, name: string): Promise<string> {
const created = await auth.api.createApiKey({ body: { userId, name: `agent:${name}` } });
await db.update(apikey).set({ expiresAt: null }).where(eq(apikey.id, created.id));
return created.key;
}
// Creates an agent: a bot user, the ai_agent config row, its team and project
// memberships, and its first API key. Internal-agent config fields are stored only for
// kind "internal"; an external agent keeps them null.
//
// Returns the agent plus the one-time key secret. That secret is returned only for
// an external agent, whose operator must copy it — an internal agent's key is kept
// encrypted on the row for its own runtime and is never surfaced to a caller.
export async function createAgent(
teamId: number,
input: NewAgentInput,
): Promise<{ agent: AiAgentRow; apiKey: string | null }> {
const userId = crypto.randomUUID();
const email = `${userId}@agents.local`;
const isInternal = input.kind === 'internal';
const invocationUrl = isInternal ? null : (input.invocationUrl ?? null);
await assertUsernameFree(teamId, input.username);
if (isInternal) await assertModelCredential(teamId, input.modelCredentialId);
if (invocationUrl) await assertPublicHttpUrl(invocationUrl);
const projectIds = await resolveTeamProjectIds(teamId, input.projectIds ?? []);
// An agent joins a project the way a person accepting an invite does: on the default
// role, changed per project from the project's member list afterwards.
const roleId = await getDefaultRoleId();
const agentId = await db.transaction(async (tx) => {
await tx
.insert(user)
.values({ id: userId, name: input.name, email, emailVerified: false, role: 'user' });
try {
const [row] = await tx
.insert(aiAgent)
.values({
teamId,
userId,
username: input.username,
kind: input.kind,
modelCredentialId: isInternal ? (input.modelCredentialId ?? null) : null,
model: isInternal ? (input.model ?? null) : null,
instructions: input.instructions ?? null,
tools: isInternal ? normalizeToolKeys(input.tools) : [],
temperature: isInternal ? (input.temperature ?? null) : null,
reasoningEffort: isInternal ? (input.reasoningEffort ?? null) : null,
maxSteps: isInternal ? (input.maxSteps ?? null) : null,
runTimeoutSec: isInternal ? (input.runTimeoutSec ?? null) : null,
memoryEnabled: isInternal ? (input.memoryEnabled ?? false) : false,
memoryLastMessages: isInternal ? (input.memoryLastMessages ?? null) : null,
triggerOnMention: input.triggerOnMention ?? isInternal,
triggerOnAssign: input.triggerOnAssign ?? false,
chatEnabled: input.chatEnabled ?? true,
delegationDelaySec: input.delegationDelaySec,
ownerUserId: input.ownerUserId ?? null,
runnerScope: input.runnerScope ?? 'team',
invocationUrl,
})
.returning({ id: aiAgent.id });
// The agent belongs to the team's member list like a person does, on a standing
// of its own that closes the owner and manager guards to it.
await tx.insert(teamMember).values({ teamId, userId, role: 'agent' });
if (projectIds.length > 0) {
await tx
.insert(projectMember)
.values(projectIds.map((projectId) => ({ projectId, userId, role: 'member', roleId })));
}
return row.id;
} catch (err) {
rethrowDuplicate(err, 'An agent with this username');
throw err;
}
});
if (input.fieldTriggers?.length) {
await setFieldTriggers(agentId, projectIds, input.fieldTriggers);
}
if (invocationUrl) await ensureInvocationSecret(agentId);
// Issued outside the transaction: better-auth writes the key through its own
// connection, so it cannot join this one.
const apiKey = await issueKey(userId, input.name);
if (isInternal) await storeAgentKey(agentId, apiKey);
const agent = (await getAgentById(agentId, teamId))!;
return { agent, apiKey: isInternal ? null : apiKey };
}
// Replaces the projects the agent works in. Membership is what gives its key access,
// so this is the whole of attaching and detaching: a project left out is detached, and
// the runs, threads and issues it produced there are untouched. A project it already
// works in keeps the role that membership carries.
async function setAgentProjects(agent: AiAgentRow, projectIds: number[]): Promise<number[]> {
const wanted = await resolveTeamProjectIds(agent.teamId, projectIds);
const roleId = await getDefaultRoleId();
await db.transaction(async (tx) => {
await tx
.delete(projectMember)
.where(
and(
eq(projectMember.userId, agent.userId),
wanted.length > 0 ? notInArray(projectMember.projectId, wanted) : undefined,
),
);
// A column cannot keep assigning issues to an agent that no longer works in the
// project, the same rule remove_member follows.
await tx
.update(projectColumn)
.set({ autoAssignUserId: null })
.where(
and(
eq(projectColumn.autoAssignUserId, agent.userId),
wanted.length > 0 ? notInArray(projectColumn.projectId, wanted) : undefined,
),
);
if (wanted.length > 0) {
await tx
.insert(projectMember)
.values(
wanted.map((projectId) => ({
projectId,
userId: agent.userId,
role: 'member',
roleId,
})),
)
.onConflictDoNothing();
}
});
return wanted;
}
// Saves an internal agent's key secret, encrypted at rest, so its runtime can replay
// it on every tool call.
async function storeAgentKey(agentId: number, apiKey: string): Promise<void> {
const enc = encryptSecret(apiKey);
await db
.update(aiAgent)
.set({ apiKeyCiphertext: enc.ciphertext, apiKeyIv: enc.iv, apiKeyAuthTag: enc.authTag })
.where(eq(aiAgent.id, agentId));
}
// Namespace for the provisioning advisory lock, so its keys cannot collide with an
// advisory lock taken anywhere else. The second key is the agent id.
const KEY_PROVISION_LOCK_NS = 8241;
// Reads and decrypts an agent's stored key, or null when it has none yet.
async function readAgentKey(agentId: number): Promise<string | null> {
const rows = await db
.select({
ciphertext: aiAgent.apiKeyCiphertext,
iv: aiAgent.apiKeyIv,
authTag: aiAgent.apiKeyAuthTag,
})
.from(aiAgent)
.where(eq(aiAgent.id, agentId));
const row = rows[0];
if (!row?.ciphertext || !row.iv || !row.authTag) return null;
return decryptSecret({ ciphertext: row.ciphertext, iv: row.iv, authTag: row.authTag });
}
// The API key an internal agent authenticates its own tool calls with, provisioning
// one if it has none. Agents created before the key was introduced have no stored
// secret (and may predate the team membership too), so both are filled in on first use
// rather than in a data migration — better-auth issues a key through its API, which
// a SQL migration cannot call.
//
// Provisioning is serialized per agent with an advisory lock. Runs are claimed in
// batches and across replicas (see run-queue), so two runs of the same unprovisioned
// agent can start together; without the lock each would issue a key, and the second
// would revoke the first out from under a run already using it. A second surviving
// key would be just as wrong: the agent reads join apikey on the bot user, so two
// rows would list the agent twice.
export async function getInternalAgentApiKey(agent: AiAgentRow): Promise<string> {
const existing = await readAgentKey(agent.id);
if (existing) return existing;
return db.transaction(async (tx) => {
// Held until this transaction ends. A concurrent run blocks here and then finds
// the key the winner stored, instead of issuing a second one.
await tx.execute(sql`select pg_advisory_xact_lock(${KEY_PROVISION_LOCK_NS}, ${agent.id})`);
const won = await readAgentKey(agent.id);
if (won) return won;
await tx
.insert(teamMember)
.values({ teamId: agent.teamId, userId: agent.userId, role: 'agent' })
.onConflictDoNothing();
// Clears any key row left without a stored secret, so the bot user ends with
// exactly the one issued here.
await db.delete(apikey).where(eq(apikey.referenceId, agent.userId));
const apiKey = await issueKey(agent.userId, agent.name);
await storeAgentKey(agent.id, apiKey);
return apiKey;
});
}
export interface AgentPatch {
name?: string;
username?: string;
// The projects the agent works in. Replaces the set, so a project left out is
// detached.
projectIds?: number[];
modelCredentialId?: number | null;
model?: string | null;
instructions?: string | null;
tools?: string[];
temperature?: number | null;
reasoningEffort?: ReasoningEffort | null;
maxSteps?: number | null;
runTimeoutSec?: number | null;
memoryEnabled?: boolean;
memoryLastMessages?: number | null;
triggerOnMention?: boolean;
triggerOnAssign?: boolean;
chatEnabled?: boolean;
fieldTriggers?: FieldTrigger[];
delegationDelaySec?: number;
runnerScope?: RunnerScope;
invocationUrl?: string | null;
}
export async function updateAgent(
id: number,
teamId: number,
patch: AgentPatch,
// The member making the change: choosing the 'owner' scope means their own runs.
actorUserId: string,
): Promise<AiAgentRow | null> {
const agent = await getAgentById(id, teamId);
if (!agent) return null;
await assertModelCredential(teamId, patch.modelCredentialId);
// Only an external agent is sent its work; an internal one runs here.
const invocationUrl = agent.kind === 'external' ? patch.invocationUrl : undefined;
if (invocationUrl) await assertPublicHttpUrl(invocationUrl);
// The display name lives on the bot user.
if (patch.name !== undefined) {
await db.update(user).set({ name: patch.name }).where(eq(user.id, agent.userId));
}
const set: Partial<typeof aiAgent.$inferInsert> = {};
if (patch.username !== undefined) {
await assertUsernameFree(teamId, patch.username, id);
set.username = patch.username;
}
if (patch.modelCredentialId !== undefined) set.modelCredentialId = patch.modelCredentialId;
if (patch.model !== undefined) set.model = patch.model;
if (patch.instructions !== undefined) set.instructions = patch.instructions;
if (patch.tools !== undefined) set.tools = normalizeToolKeys(patch.tools);
if (patch.temperature !== undefined) set.temperature = patch.temperature;
if (patch.reasoningEffort !== undefined) set.reasoningEffort = patch.reasoningEffort;
if (patch.maxSteps !== undefined) set.maxSteps = patch.maxSteps;
if (patch.runTimeoutSec !== undefined) set.runTimeoutSec = patch.runTimeoutSec;
if (patch.memoryEnabled !== undefined) set.memoryEnabled = patch.memoryEnabled;
if (patch.memoryLastMessages !== undefined) set.memoryLastMessages = patch.memoryLastMessages;
if (patch.triggerOnMention !== undefined) set.triggerOnMention = patch.triggerOnMention;
if (patch.triggerOnAssign !== undefined) set.triggerOnAssign = patch.triggerOnAssign;
if (patch.chatEnabled !== undefined) set.chatEnabled = patch.chatEnabled;
if (patch.delegationDelaySec !== undefined) set.delegationDelaySec = patch.delegationDelaySec;
// The scope and its owner are one setting: 'owner' means the runs of the member who
// chose it, so switching to it hands the agent to them.
if (patch.runnerScope !== undefined) {
set.runnerScope = patch.runnerScope;
if (patch.runnerScope === 'owner') set.ownerUserId = actorUserId;
}
if (invocationUrl !== undefined) set.invocationUrl = invocationUrl;
if (Object.keys(set).length > 0) {
try {
await db
.update(aiAgent)
.set(set)
.where(and(eq(aiAgent.id, id), eq(aiAgent.teamId, teamId)));
} catch (err) {
rethrowDuplicate(err, 'An agent with this username');
throw err;
}
}
// The projects go first, so a field trigger of a project the same call attaches is
// kept rather than dropped as unknown.
const projectIds =
patch.projectIds !== undefined
? await setAgentProjects(agent, patch.projectIds)
: agent.projects.map((p) => p.id);
if (patch.fieldTriggers !== undefined) {
await setFieldTriggers(id, projectIds, patch.fieldTriggers);
}
if (invocationUrl) await ensureInvocationSecret(id);
return getAgentById(id, teamId);
}
// Replaces the agent's API key: deletes the current key row(s) for the bot user
// and issues a new one. Returns the new plaintext secret, or null if the agent
// does not exist. There is no atomic rotate in the plugin, so this is delete+create.
// An internal agent's new secret is re-encrypted onto its row for its runtime.
export async function regenerateKey(id: number, teamId: number): Promise<string | null> {
const agent = await getAgentById(id, teamId);
if (!agent) return null;
await db.delete(apikey).where(eq(apikey.referenceId, agent.userId));
const apiKey = await issueKey(agent.userId, agent.name);
if (agent.kind === 'internal') await storeAgentKey(agent.id, apiKey);
return apiKey;
}
// Deletes an agent: its conversation threads, its API key row(s), then the bot user.
// Deleting the user cascades to the ai_agent row (ON DELETE CASCADE on user_id), sets
// assignee_user_id to NULL on every issue the agent was on, and nulls the actor on its
// activity.
export async function deleteAgent(id: number, teamId: number): Promise<boolean> {
const agent = await getAgentById(id, teamId);
if (!agent) return false;
await deleteThreadsWhere({ agentId: id });
await db.delete(apikey).where(eq(apikey.referenceId, agent.userId));
await deleteAccount(agent.userId);
return true;
}
// True if the agent belongs to the team (guards addressing an agent by id).
export async function agentInTeam(
agentId: number,
teamId: number,
visibleTo?: string,
): Promise<boolean> {
const rows = await db
.select({ id: aiAgent.id })
.from(aiAgent)
.where(
and(
eq(aiAgent.id, agentId),
eq(aiAgent.teamId, teamId),
visibleTo == null ? undefined : sharesProjectWith(visibleTo),
),
)
.limit(1);
return rows.length > 0;
}
// True if the agent works in the project (guards naming an agent for work there).
export async function agentWorksInProject(agentId: number, projectId: number): Promise<boolean> {
const rows = await db
.select({ id: aiAgent.id })
.from(aiAgent)
.where(and(eq(aiAgent.id, agentId), inProject(projectId)))
.limit(1);
return rows.length > 0;
}