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.

25.5 KB
Raw Blame
import {
  db,
  type DbExecutor,
  agentRun,
  aiAgent,
  documentComment,
  issue,
  project,
  projectDocument,
  team,
  user,
} from '@repo/db';
import {
  and,
  asc,
  desc,
  eq,
  exists,
  gt,
  inArray,
  isNotNull,
  isNull,
  lt,
  or,
  sql,
} from 'drizzle-orm';
import { getAgentSettings } from '#modules/settings/service';
import { intEnv, iso } from '#shared/lib';
import type { AgentRunTrigger } from '../model';
import { equalJitterBackoffMs } from './helpers/backoff';
import { emitRunsFinished } from './run-finished';

// The agent_run outbox: data access for triggered runs and run history. The api's
// run poller claims pending rows, runs them, and records the outcome.

// Tuning, env-overridable with defaults. A claim's lease must exceed a run's wall time
// so a row is not re-claimed while its run is still in flight: claimDueRuns raises it
// above the instance's maximum run time when that is longer.
export const agentRunConfig = {
  pollIntervalMs: () => intEnv('AGENT_RUN_POLL_INTERVAL_MS', 2000),
  maxAttempts: () => intEnv('AGENT_RUN_MAX_ATTEMPTS', 3),
  leaseSeconds: () => intEnv('AGENT_RUN_LEASE_SECONDS', 300),
};

// Time a claim's lease leaves after the run's time limit, for recording the outcome.
const LEASE_MARGIN_SECONDS = 60;

const RETRY_BASE_MS = 30_000;
const RETRY_CAP_MS = 30 * 60_000;

// How long a run waits before its next attempt after the given one failed.
export function runRetryDelayMs(attempts: number): number {
  return equalJitterBackoffMs(attempts, RETRY_BASE_MS, RETRY_CAP_MS);
}

// The condition a candidate run `q` of a claim meets when it is its turn. The runs of
// one agent on one issue, or on one document, share the agent's conversation thread and
// act on the same issue or document, so they go one at a time, oldest first: a run waits
// while another of them holds a slot (claimed and inside its lease, or waiting out a
// retry), and while an older one is due, which the same claim takes instead.
export const runTurn = sql`NOT EXISTS (
  SELECT 1 FROM agent_run o
  WHERE o.agent_id = q.agent_id AND o.id <> q.id
    AND (o.issue_id = q.issue_id OR o.document_id = q.document_id)
    AND o.status = 'pending'
    AND ((o.started_at IS NOT NULL AND o.next_attempt_at > now())
      OR (o.next_attempt_at <= now() AND o.id < q.id))
)`;

// A run started in a document reads as missing to a viewer the document is now private
// from, as the run of an issue that moved to another project does.
export function runDocumentVisibleTo(viewerId: string) {
  return or(
    isNull(agentRun.documentId),
    exists(
      db
        .select({ id: projectDocument.id })
        .from(projectDocument)
        .where(
          and(
            eq(projectDocument.id, agentRun.documentId),
            or(eq(projectDocument.isPrivate, false), eq(projectDocument.ownerUserId, viewerId)),
          ),
        ),
    ),
  );
}

// A run of an internal agent that holds a slot of its workspace's limit. A claim stamps
// started_at and pushes next_attempt_at forward, so a pending run that is stamped and
// still inside that window is one — as is a run waiting out its retry backoff, which
// holds a slot it is not using, so the older runs keep their turn. An external agent's
// runs are executed on the operator's machine and hold none.
export const holdsSlot = and(
  eq(agentRun.status, 'pending'),
  isNotNull(agentRun.startedAt),
  gt(agentRun.nextAttemptAt, sql`now()`),
  eq(aiAgent.kind, 'internal'),
);

// Active runs and retry backoff keep their slots regardless of queue order. Among
// claims awaiting admission, lower ids take precedence so a burst can make progress.
export async function countRunsAhead(
  workspaceId: number,
  runId: number,
  executor: DbExecutor = db,
): Promise<number> {
  const [row] = await executor
    .select({ count: sql<number>`count(*)::int` })
    .from(agentRun)
    .innerJoin(aiAgent, eq(aiAgent.id, agentRun.agentId))
    .innerJoin(project, eq(project.id, agentRun.projectId))
    .innerJoin(team, eq(team.id, project.teamId))
    .where(
      and(
        eq(team.workspaceId, workspaceId),
        holdsSlot,
        sql`${agentRun.id} <> ${runId}`,
        or(
          lt(agentRun.id, runId),
          isNotNull(agentRun.executionStartedAt),
          isNull(agentRun.claimedAt),
        ),
      ),
    );
  return row?.count ?? 0;
}

export async function countRunsInFlight(workspaceId: number): Promise<number> {
  const [row] = await db
    .select({ count: sql<number>`count(*)::int` })
    .from(agentRun)
    .innerJoin(aiAgent, eq(aiAgent.id, agentRun.agentId))
    .innerJoin(project, eq(project.id, agentRun.projectId))
    .innerJoin(team, eq(team.id, project.teamId))
    .where(and(eq(team.workspaceId, workspaceId), holdsSlot));
  return row?.count ?? 0;
}

// The runs of internal agents the api has claimed and works on, which the instance's
// limit counts. A deferred run and one in retry backoff are not claimed, so they leave
// their slot to the other workspaces; past the lease, the run of a crashed poller holds
// none either.
async function countClaimedRuns(executor: DbExecutor): Promise<number> {
  const [row] = await executor
    .select({ count: sql<number>`count(*)::int` })
    .from(agentRun)
    .innerJoin(aiAgent, eq(aiAgent.id, agentRun.agentId))
    .where(
      and(
        eq(agentRun.status, 'pending'),
        isNotNull(agentRun.claimedAt),
        gt(agentRun.nextAttemptAt, sql`now()`),
        eq(aiAgent.kind, 'internal'),
      ),
    );
  return row?.count ?? 0;
}

export async function enqueueAgentRun(input: {
  agentId: number;
  // The project the run works in, which is the issue's or the document's. An agent works
  // in several projects, so the run carries its own rather than reading the agent's.
  projectId: number;
  issueId: number | null;
  sourceActivityId: number | null;
  // A mention in a document comment: the document and the comment, with no issue.
  documentId?: number;
  sourceDocumentCommentId?: string;
  prompt: string;
  trigger?: 'mention' | 'delegation' | 'field';
  // Seconds the run stays unclaimable after it is queued, so the issue can still be
  // edited before the agent reads it.
  delaySeconds?: number;
}): Promise<void> {
  const delay = Math.max(0, Math.trunc(input.delaySeconds ?? 0));
  await db.insert(agentRun).values({
    agentId: input.agentId,
    projectId: input.projectId,
    issueId: input.issueId,
    sourceActivityId: input.sourceActivityId,
    documentId: input.documentId,
    sourceDocumentCommentId: input.sourceDocumentCommentId,
    prompt: input.prompt,
    trigger: input.trigger ?? (input.sourceActivityId == null ? 'delegation' : 'mention'),
    nextAttemptAt: delay > 0 ? sql`now() + make_interval(secs => ${delay})` : undefined,
  });
}

export interface ClaimedRun {
  id: number;
  agentId: number;
  // Null for a cron schedule's run or a manual one, which works on no single issue.
  issueId: number | null;
  scheduleId: number | null;
  trigger: AgentRunTrigger;
  prompt: string;
  attempts: number;
  // The source comment id when the run was triggered by a mention, null for a
  // delegation. The poller frames the task differently for each.
  sourceActivityId: number | null;
  // The run's project and the agent's bot user, read inline so the poller can run it
  // without a second query.
  projectId: number;
  agentUserId: string;
  // The agent's own run time limit, null when it uses the instance's maximum.
  agentRunTimeoutSec: number | null;
  // Monotonic deadline that leaves the claim's margin for recording the outcome.
  executionDeadline: number;
  // The agent's own handle, so the prompt can tell whether the text addressed it.
  agentUsername: string;
  // The issue's human-readable key ("MKT-42") and title, read inline so the poller can
  // frame the run with them. Null if the issue was deleted after enqueue.
  issueIdentifier: string | null;
  issueTitle: string | null;
  // The issue's assignee (the responsible human) and, for a mention run, the author of
  // the comment that mentioned the agent (from the source activity's name snapshot) with
  // their account. Each carries the handle the agent tags them by. Any may be null: no
  // assignee, a deleted user, or a run with no source comment.
  assigneeName: string | null;
  assigneeUsername: string | null;
  requesterName: string | null;
  requesterUsername: string | null;
  requesterUserId: string | null;
  // The comments the source comment replies to, oldest first, when it is a reply.
  // Null for a top-level mention or a delegation.
  threadContext: string | null;
  // A mention in a document comment: the document, the comment, and the thread it is in.
  // All null for any other run.
  documentId: number | null;
  sourceDocumentCommentId: string | null;
  documentTitle: string | null;
  // The text of the document the thread is about.
  documentQuote: string | null;
  // The first comment of the thread, which a reply is posted under.
  threadRootId: string | null;
}

// Every api replica claims under this lock, so two claims never count the same free slot.
const RUN_CLAIM_LOCK_NS = 8243;

// Atomically claims the due runs of internal agents, as many as the instance has free
// slots for, or every due one when it sets no limit. FOR UPDATE SKIP LOCKED lets more
// than one API replica run without ever claiming the same row.
// Claiming bumps attempts and pushes next_attempt_at forward by the lease while
// keeping status 'pending', so a run whose poller crashes mid-flight becomes
// claimable again after the lease — no separate recovery pass. The run's project and
// the agent's user_id are read inline. An external agent's runs are left alone:
// they are claimed over HTTP by the operator's runner (modules/agents/runner).
export async function claimDueRuns(): Promise<ClaimedRun[]> {
  const { maxRunSeconds, maxConcurrentRuns } = await getAgentSettings();
  const leaseSeconds = Math.max(
    agentRunConfig.leaseSeconds(),
    maxRunSeconds + LEASE_MARGIN_SECONDS,
  );
  const executionDeadline = performance.now() + (leaseSeconds - LEASE_MARGIN_SECONDS) * 1000;
  const rows = await db.transaction(async (tx) => {
    await tx.execute(sql`select pg_advisory_xact_lock(${RUN_CLAIM_LOCK_NS}, 0)`);
    // LIMIT NULL claims every due run.
    const free = maxConcurrentRuns > 0 ? maxConcurrentRuns - (await countClaimedRuns(tx)) : null;
    if (free !== null && free <= 0) return [];
    // MATERIALIZED picks the runs once. As `r.id IN (...)` the planner may rescan the
    // pick for every row it updates, and each rescan skips the rows already claimed and
    // hands out the next ones, past the free slots.
    return tx.execute(sql`
      WITH due AS MATERIALIZED (
        SELECT id FROM agent_run q
        WHERE q.status = 'pending' AND q.next_attempt_at <= now()
          AND (SELECT kind FROM ai_agent a WHERE a.id = q.agent_id) = 'internal'
          AND ${runTurn}
        ORDER BY q.next_attempt_at, q.id
        FOR UPDATE SKIP LOCKED
        LIMIT ${free}
      )
      UPDATE agent_run r
      SET attempts = r.attempts + 1,
          started_at = coalesce(r.started_at, now()),
          execution_started_at = NULL,
          claimed_at = now(),
          next_attempt_at = now() + make_interval(secs => ${leaseSeconds})
      FROM due
      WHERE r.id = due.id
      RETURNING
        r.id,
        r.agent_id AS "agentId",
        r.issue_id AS "issueId",
        r.schedule_id AS "scheduleId",
        r.trigger,
        r.prompt,
        r.attempts,
        r.source_activity_id AS "sourceActivityId",
        r.document_id AS "documentId",
        r.source_document_comment_id AS "sourceDocumentCommentId",
        r.project_id AS "projectId",
        (SELECT user_id FROM ai_agent a WHERE a.id = r.agent_id) AS "agentUserId",
        (SELECT username FROM ai_agent a WHERE a.id = r.agent_id) AS "agentUsername",
        (SELECT run_timeout_sec FROM ai_agent a WHERE a.id = r.agent_id) AS "agentRunTimeoutSec",
        (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",
        (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",
        (SELECT actor_user_id FROM issue_activity a WHERE a.id = r.source_activity_id) AS "requesterUserId"
    `);
  });
  const runs = rows as unknown as Omit<ClaimedRun, ThreadField | 'executionDeadline'>[];
  return Promise.all(
    runs.map(async (run) => ({ ...run, executionDeadline, ...(await loadRunThread(run)) })),
  );
}

// How far up a thread the agent is given. Further up, the exchange is too far from
// the question to pay for the tokens it costs.
const THREAD_CONTEXT_DEPTH = 5;

type ThreadField = 'threadContext' | 'documentTitle' | 'documentQuote' | 'threadRootId';

// What a run is told about the conversation it answers, read once it is claimed. A
// document run also names its requester here.
type RunThread = Pick<ClaimedRun, ThreadField> &
  Partial<Pick<ClaimedRun, 'requesterName' | 'requesterUsername' | 'requesterUserId'>>;

export async function loadRunThread(run: {
  sourceActivityId: number | null;
  documentId: number | null;
  sourceDocumentCommentId: string | null;
}): Promise<RunThread> {
  if (run.documentId != null)
    return loadDocumentThread(run.documentId, run.sourceDocumentCommentId);
  return {
    threadContext: await loadThreadContext(run.sourceActivityId),
    documentTitle: null,
    documentQuote: null,
    threadRootId: null,
  };
}

// A document comment's thread: the document's title, the text the thread is about, its
// first comment, and the comments before the given one, oldest first and at most
// THREAD_CONTEXT_DEPTH of them. The comment's author is the requester, read here because
// a document comment keeps no name of its own.
async function loadDocumentThread(
  documentId: number,
  commentId: string | null,
): Promise<RunThread> {
  const [document] = await db
    .select({ title: projectDocument.title })
    .from(projectDocument)
    .where(eq(projectDocument.id, documentId));
  const thread: RunThread = {
    threadContext: null,
    documentTitle: document?.title ?? null,
    documentQuote: null,
    threadRootId: null,
  };
  if (commentId == null) return thread;
  const [source] = await db
    .select({
      parentId: documentComment.parentId,
      authorId: documentComment.authorId,
      authorName: user.name,
      authorUsername: sql<string | null>`coalesce(${user.username}, ${aiAgent.username})`,
    })
    .from(documentComment)
    .leftJoin(user, eq(user.id, documentComment.authorId))
    .leftJoin(aiAgent, eq(aiAgent.userId, documentComment.authorId))
    .where(eq(documentComment.id, commentId));
  if (!source) return thread;
  const rootId = source.parentId ?? commentId;
  const comments = await db
    .select({
      id: documentComment.id,
      quote: documentComment.quote,
      body: documentComment.body,
      authorName: user.name,
    })
    .from(documentComment)
    .leftJoin(user, eq(user.id, documentComment.authorId))
    .where(or(eq(documentComment.id, rootId), eq(documentComment.parentId, rootId)))
    .orderBy(asc(documentComment.createdAt), asc(documentComment.id));
  const at = comments.findIndex((comment) => comment.id === commentId);
  const before = comments.slice(Math.max(0, at - THREAD_CONTEXT_DEPTH), Math.max(0, at));
  return {
    ...thread,
    threadContext: before.length
      ? before.map((c) => `${c.authorName ?? 'Unknown'}: ${c.body}`).join('\n\n')
      : null,
    documentQuote: comments.find((comment) => comment.id === rootId)?.quote || null,
    threadRootId: rootId,
    requesterName: source.authorName,
    requesterUsername: source.authorUsername,
    requesterUserId: source.authorId,
  };
}

// The comments the given one replies to, oldest first and at most
// THREAD_CONTEXT_DEPTH of them, as the text a prompt carries. Null when the comment
// is not a reply.
async function loadThreadContext(sourceActivityId: number | null): Promise<string | null> {
  if (sourceActivityId == null) return null;
  const rows = await db.execute(sql`
    WITH RECURSIVE chain AS (
      SELECT a.id, a.reply_to_id, a.actor_name, a.body, 0 AS depth
        FROM issue_activity a
       WHERE a.id = ${sourceActivityId}
      UNION ALL
      SELECT p.id, p.reply_to_id, p.actor_name, p.body, c.depth + 1
        FROM issue_activity p
        JOIN chain c ON p.id = c.reply_to_id
       WHERE c.depth < ${THREAD_CONTEXT_DEPTH}
    )
    SELECT actor_name AS "actorName", body FROM chain WHERE depth > 0 ORDER BY depth DESC
  `);
  const ancestors = rows as unknown as { actorName: string | null; body: string | null }[];
  if (ancestors.length === 0) return null;
  return ancestors.map((a) => `${a.actorName ?? 'Unknown'}: ${a.body ?? ''}`).join('\n\n');
}

// A run canceled while it was in flight keeps that outcome: each of these writes only
// where the row is still 'pending'.

// `usage` is what the last model call of the run read and wrote. Null where the model
// reports none, which the run history shows as a dash.
export async function markRunSuccess(
  id: number,
  output: string,
  usage: { inputTokens: number; outputTokens: number } | null,
): Promise<void> {
  const rows = await db
    .update(agentRun)
    .set({
      status: 'success',
      executionStartedAt: null,
      output,
      lastError: null,
      inputTokens: usage?.inputTokens ?? null,
      outputTokens: usage?.outputTokens ?? null,
      finishedAt: new Date(),
    })
    .where(and(eq(agentRun.id, id), eq(agentRun.status, 'pending')))
    .returning({ id: agentRun.id });
  await emitRunsFinished(rows.map((row) => row.id));
}

export async function scheduleRunRetry(id: number, delayMs: number, error: string): Promise<void> {
  const delaySeconds = Math.max(1, Math.ceil(delayMs / 1000));
  await db
    .update(agentRun)
    .set({
      status: 'pending',
      executionStartedAt: null,
      claimedAt: null,
      nextAttemptAt: sql`now() + make_interval(secs => ${delaySeconds})`,
      lastError: error.slice(0, 500),
    })
    .where(and(eq(agentRun.id, id), eq(agentRun.status, 'pending')));
}

export async function markRunFailed(id: number, error: string, output?: string): Promise<void> {
  const rows = await db
    .update(agentRun)
    .set({
      status: 'failed',
      executionStartedAt: null,
      lastError: error.slice(0, 500),
      ...(output ? { output } : {}),
      finishedAt: new Date(),
    })
    .where(and(eq(agentRun.id, id), eq(agentRun.status, 'pending')))
    .returning({ id: agentRun.id });
  await emitRunsFinished(rows.map((row) => row.id));
}

// Puts a claimed run back in the queue without spending the attempt, for a run the
// team has no free slot for or one held back by setRunAdmission. Waiting is not a failed
// attempt, and nothing has been recorded on the issue yet, so the run leaves no trace of
// having been picked up at all: a first claim's started_at goes too, so the waiting run
// holds no slot in countRunsAhead and can be canceled as not started.
export async function deferRun(
  id: number,
  delaySeconds: number,
  executor: DbExecutor = db,
  attempts?: number,
): Promise<void> {
  await executor
    .update(agentRun)
    .set({
      executionStartedAt: null,
      claimedAt: null,
      attempts: sql`${agentRun.attempts} - 1`,
      startedAt: sql`CASE WHEN ${agentRun.attempts} = 1 THEN NULL ELSE ${agentRun.startedAt} END`,
      nextAttemptAt: sql`now() + make_interval(secs => ${delaySeconds})`,
    })
    .where(
      and(
        eq(agentRun.id, id),
        eq(agentRun.status, 'pending'),
        attempts === undefined
          ? undefined
          : and(
              eq(agentRun.attempts, attempts),
              isNotNull(agentRun.claimedAt),
              gt(agentRun.nextAttemptAt, sql`now()`),
            ),
      ),
    );
}

export const executionState = sql<'queued' | 'running' | 'success' | 'failed' | 'canceled'>`
  CASE WHEN ${agentRun.status} <> 'pending' THEN ${agentRun.status}
    WHEN ${agentRun.executionStartedAt} IS NOT NULL AND ${agentRun.nextAttemptAt} > now()
      THEN 'running'
    ELSE 'queued' END`;

export async function markRunExecuting(
  id: number,
  attempts: number,
  executor: DbExecutor = db,
): Promise<boolean> {
  const rows = await executor
    .update(agentRun)
    .set({ executionStartedAt: new Date() })
    .where(
      and(
        eq(agentRun.id, id),
        eq(agentRun.status, 'pending'),
        eq(agentRun.attempts, attempts),
        gt(agentRun.nextAttemptAt, sql`now()`),
      ),
    )
    .returning({ id: agentRun.id });
  return rows.length > 0;
}

// Share the claim lock: another replica cannot admit a later claim between the
// workspace count and this run reserving its execution slot.
export async function admitWorkspaceRun(
  run: ClaimedRun,
  workspaceId: number,
  limit: number,
): Promise<boolean> {
  return db.transaction(async (tx) => {
    await tx.execute(sql`select pg_advisory_xact_lock(${RUN_CLAIM_LOCK_NS}, 0)`);
    if (limit > 0 && (await countRunsAhead(workspaceId, run.id, tx)) >= limit) {
      await deferRun(run.id, 30, tx, run.attempts);
      return false;
    }
    return markRunExecuting(run.id, run.attempts, tx);
  });
}

export interface AgentRunRow {
  id: number;
  status: string;
  executionState: 'queued' | 'running' | 'success' | 'failed' | 'canceled';
  trigger: AgentRunTrigger;
  issueId: number | null;
  issueIdentifier: string | null;
  issueTitle: string | null;
  documentId: number | null;
  // Null for a document that is private now, whose title is its owner's alone.
  documentTitle: string | null;
  prompt: string;
  attempts: number;
  lastError: string | null;
  // What the run produced: the runtime's reply, or whatever the runner's command
  // printed. Null until the run finishes.
  output: string | null;
  contextTokens?: number;
  nextAttemptAt: string;
  createdAt: string;
}

// The size of a run's context as its DTO carries it. The field is left out where there
// is nothing to report: a run stored before the counts were recorded, and one whose
// agent reports none.
export function contextTokensOf(row: { inputTokens: number | null; outputTokens: number | null }): {
  contextTokens?: number;
} {
  if (row.inputTokens == null && row.outputTokens == null) return {};
  return { contextTokens: (row.inputTokens ?? 0) + (row.outputTokens ?? 0) };
}

export interface AgentRunPage {
  items: AgentRunRow[];
  // The id to pass as `before` to load the next page, or null when at the end.
  nextCursor: number | null;
}

// One page of an agent's runs, newest first. Keyset pagination by id (runs are
// id-monotonic): pass the previous page's nextCursor as `before`. limit is clamped to
// 1..50.
//
// An agent works in several projects of its team and a run carries the one it ran in,
// so `projectIds` bounds the page to the projects the reader may see. Omitted, it
// reads every project — only a caller who runs the team passes nothing.
export async function listAgentRuns(
  agentId: number,
  opts: { before?: number; limit?: number; projectIds?: number[] } = {},
): Promise<AgentRunPage> {
  if (opts.projectIds?.length === 0) return { items: [], nextCursor: null };
  const limit = Math.min(Math.max(opts.limit ?? 25, 1), 50);
  const rows = await db
    .select({
      id: agentRun.id,
      status: agentRun.status,
      executionState,
      trigger: agentRun.trigger,
      issueId: agentRun.issueId,
      documentId: agentRun.documentId,
      documentTitle: projectDocument.title,
      prompt: agentRun.prompt,
      attempts: agentRun.attempts,
      lastError: agentRun.lastError,
      output: agentRun.output,
      inputTokens: agentRun.inputTokens,
      outputTokens: agentRun.outputTokens,
      nextAttemptAt: agentRun.nextAttemptAt,
      createdAt: agentRun.createdAt,
      issueSeq: issue.sequenceNumber,
      issueTitle: issue.title,
      projectKey: project.key,
    })
    .from(agentRun)
    .leftJoin(issue, eq(issue.id, agentRun.issueId))
    .leftJoin(project, eq(project.id, issue.projectId))
    .leftJoin(
      projectDocument,
      and(eq(projectDocument.id, agentRun.documentId), eq(projectDocument.isPrivate, false)),
    )
    .where(
      and(
        eq(agentRun.agentId, agentId),
        opts.projectIds ? inArray(agentRun.projectId, opts.projectIds) : undefined,
        opts.before ? lt(agentRun.id, opts.before) : undefined,
      ),
    )
    .orderBy(desc(agentRun.id))
    .limit(limit + 1);
  const hasMore = rows.length > limit;
  const page = hasMore ? rows.slice(0, limit) : rows;
  return {
    items: page.map((r) => ({
      id: r.id,
      status: r.status,
      executionState: r.executionState,
      trigger: r.trigger as AgentRunTrigger,
      issueId: r.issueId,
      issueIdentifier: r.projectKey && r.issueSeq != null ? `${r.projectKey}-${r.issueSeq}` : null,
      issueTitle: r.issueTitle ?? null,
      documentId: r.documentId,
      documentTitle: r.documentTitle,
      prompt: r.prompt,
      attempts: r.attempts,
      lastError: r.lastError,
      output: r.output,
      ...contextTokensOf(r),
      nextAttemptAt: iso(r.nextAttemptAt),
      createdAt: iso(r.createdAt),
    })),
    nextCursor: hasMore ? page[page.length - 1].id : null,
  };
}