@wardby/cli 0.2.1 → 0.4.0

package/dist/core/issue-bridge.js

@@ -0,0 +1,189 @@
+/**
+ * Links a run's pull requests to the issue that started it: records each
+ * issue/PR pair, puts a web link on the issue, and applies the link's
+ * configured status move. Provider-neutral: a code host is only ever
+ * { provider, repository, number }. The issue key comes from the run tree
+ * (RunIssueStatus), never from model output. The status move is a control-plane
+ * action (not gated by allowedTransitions). Nothing here throws, except
+ * handlePullRequestClosed's lookup before it has claimed anything (so the
+ * webhook delivery is rolled back and redelivered).
+ */
+import { Prisma } from "#prisma";
+import { projectOf, } from "../providers/issue-tracker/types.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "issue-bridge" });
+export const pullRequestGlobalId = (pr) => `wardby:pr:${pr.codeProvider}:${pr.repository}#${pr.number}`;
+/**
+ * Makes sure the issue/PR pair has a row, without ever overwriting one: a new
+ * row is "created"; an existing open one gets its url refreshed ("open"); a
+ * merged or closed one is left alone ("settled"). A lost create race (P2002)
+ * reads back the winner's row. "unknown" when the store could not be read.
+ */
+async function ensurePair(db, input, pr) {
+    const where = {
+        codeProvider_repository_number_issueProvider_issueKey: {
+            codeProvider: pr.codeProvider,
+            repository: pr.repository,
+            number: pr.number,
+            issueProvider: input.issueProvider,
+            issueKey: input.issueKey,
+        },
+    };
+    try {
+        let existing = await db.issuePullRequest.findUnique({ where, select: { state: true } });
+        if (!existing) {
+            try {
+                await db.issuePullRequest.create({
+                    data: {
+                        issueProvider: input.issueProvider,
+                        issueKey: input.issueKey,
+                        codeProvider: pr.codeProvider,
+                        repository: pr.repository,
+                        number: pr.number,
+                        url: pr.url,
+                        agentId: input.agentId,
+                        openedByRunId: pr.openedByRunId,
+                    },
+                });
+                return "created";
+            }
+            catch (err) {
+                if (!(err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2002"))
+                    throw err;
+                existing = await db.issuePullRequest.findUnique({ where, select: { state: true } });
+                if (!existing)
+                    return "unknown";
+            }
+        }
+        if (existing.state !== "open")
+            return "settled";
+        await db.issuePullRequest.update({ where, data: { url: pr.url } });
+        return "open";
+    }
+    catch (err) {
+        log.warn({ err, issueKey: input.issueKey, repository: pr.repository, number: pr.number }, "could not record the issue/PR pair");
+        return "unknown";
+    }
+}
+/**
+ * Returns sentences for the outcome comment (a refused status move); empty
+ * when there is nothing to say. Safe to repeat (a retried completion): each
+ * pair's side effects happen once — the status move only when this call newly
+ * recorded an opened pull request, and a merged/closed pair is never re-linked
+ * (re-posting its web link would un-resolve it). An unreadable store skips
+ * both rather than risk repeating them.
+ */
+export async function recordPullRequests(db, tracker, input) {
+    const notes = [];
+    try {
+        let newlyOpened = false;
+        for (const pr of input.pullRequests) {
+            const state = await ensurePair(db, input, pr);
+            if (state === "created" && pr.outcome === "pull_request_opened")
+                newlyOpened = true;
+            if (state !== "created" && state !== "open")
+                continue;
+            try {
+                await tracker.addRemoteLink(input.issueKey, {
+                    globalId: pullRequestGlobalId(pr),
+                    url: pr.url,
+                    title: `${pr.repository}#${pr.number}`,
+                });
+            }
+            catch (err) {
+                log.warn({ err, issueKey: input.issueKey, repository: pr.repository, number: pr.number }, "could not link the pull request on the issue");
+            }
+        }
+        const target = input.onPullRequestOpened;
+        if (target && newlyOpened) {
+            try {
+                await tracker.transitionTo(input.issueKey, target);
+            }
+            catch (err) {
+                log.warn({ err, issueKey: input.issueKey, target }, "could not move the issue after a pull request opened");
+                notes.push(`Could not move ${input.issueKey} to "${target}"; it may need a manual move.`);
+            }
+        }
+    }
+    catch (err) {
+        log.warn({ err, issueKey: input.issueKey }, "could not bridge the pull requests to the issue");
+    }
+    return { notes };
+}
+/**
+ * A pull request wardby recorded against an issue was merged or closed: marks
+ * each still-open pair, and, where the agent's link to the issue's project is
+ * still write, comments on the issue (and on merge resolves the web link and
+ * applies the link's onPullRequestMerged move). Only rows wardby wrote are
+ * touched, matched by the host's own identity for the PR — nothing from the
+ * PR's text. The row is claimed first (open → merged/closed), so a duplicate
+ * or concurrent delivery finds nothing to do. Throws only when the lookup of
+ * linked rows fails — before anything is claimed — so the caller's webhook
+ * delivery is rolled back and redelivered; never throws after that.
+ */
+export async function handlePullRequestClosed(db, trackers, pr) {
+    if (!trackers)
+        return;
+    const where = { codeProvider: pr.codeProvider, repository: pr.repository, number: pr.number };
+    // Not caught: nothing is claimed yet, and a throw rolls back the delivery so it is redelivered.
+    const rows = await db.issuePullRequest.findMany({ where: { ...where, state: "open" } });
+    for (const row of rows) {
+        try {
+            const claimed = await db.issuePullRequest.updateMany({
+                where: { id: row.id, state: "open" },
+                data: { state: pr.merged ? "merged" : "closed" },
+            });
+            if (claimed.count === 0)
+                continue;
+            const tracker = trackers[row.issueProvider];
+            if (!tracker)
+                continue;
+            const link = await db.agentIssueProject.findUnique({
+                where: {
+                    agentId_provider_projectKey: {
+                        agentId: row.agentId,
+                        provider: row.issueProvider,
+                        projectKey: projectOf(row.issueKey),
+                    },
+                },
+                select: { access: true, commentVisibilityRole: true, onPullRequestMerged: true },
+            });
+            if (link?.access !== "write")
+                continue;
+            const ref = `[${row.repository}#${row.number}](${row.url})`;
+            let markdown;
+            if (pr.merged) {
+                await tracker
+                    .addRemoteLink(row.issueKey, {
+                    globalId: pullRequestGlobalId(row),
+                    url: row.url,
+                    title: `${row.repository}#${row.number}`,
+                    status: { resolved: true },
+                })
+                    .catch((err) => log.warn({ err, issueKey: row.issueKey, ...where }, "could not resolve the pull request's web link"));
+                markdown = `✅ Pull request ${ref} was merged.`;
+                const target = link.onPullRequestMerged;
+                if (target) {
+                    try {
+                        const moved = await tracker.transitionTo(row.issueKey, target);
+                        markdown += ` Moved to ${moved.toStatus}.`;
+                    }
+                    catch (err) {
+                        log.warn({ err, issueKey: row.issueKey, target }, "could not move the issue after its pull request merged");
+                        markdown += ` Could not move ${row.issueKey} to "${target}"; it may need a manual move.`;
+                    }
+                }
+            }
+            else {
+                markdown = `Pull request ${ref} was closed without merging.`;
+            }
+            await tracker.comment(row.issueKey, {
+                markdown,
+                ...(link.commentVisibilityRole ? { visibilityRole: link.commentVisibilityRole } : {}),
+            });
+        }
+        catch (err) {
+            log.warn({ err, issueKey: row.issueKey, ...where }, "could not bridge the closed pull request to the issue");
+        }
+    }
+}

package/dist/core/issue-dedupe.d.ts

@@ -0,0 +1,70 @@
+import type { PrismaClient } from "#prisma";
+import { type CreateIssueInput, type IssueTracker, type TrackerCallOptions } from "../providers/issue-tracker/types.js";
+export declare const FINGERPRINT_MAX_LENGTH = 200;
+/**
+ * Each tracker call inside the lock: a whole-call cap, and a 429 fails at once rather than sleeping. Jira
+ * Cloud calls through the api.atlassian.com gateway routinely take several seconds each, and one tracker
+ * call can be a few requests (a create resolves the issue type and its fields first), so the cap is generous.
+ */
+export declare const TRACKER_CALL_OPTIONS: Readonly<TrackerCallOptions>;
+/** How long a sighting waits for another sighting of the same fingerprint before answering "busy". */
+export declare const DEDUPE_LOCK_TIMEOUT_MS = 5000;
+/**
+ * The critical section is the lock wait (5 s) plus at most two bounded tracker calls (getIssue, then
+ * createIssue or comment: 2 x 30 s) plus a few row reads/writes; 90 s leaves ample margin so a create is
+ * never in flight when the transaction (and with it the advisory lock) is torn down. The cost: each
+ * sighting in progress holds one pool connection for up to this long, and waiters hold one for up to
+ * the lock timeout (callers waiting for a free connection give up after maxWait).
+ */
+export declare const DEDUPE_TRANSACTION_TIMEOUT_MS = 90000;
+export type IssueDedupeDb = Pick<PrismaClient, "$transaction">;
+export interface IssueDedupeLink {
+    provider: string;
+    projectKey: string;
+    access: string;
+    commentVisibilityRole?: string | null;
+}
+export interface FileIssueInput {
+    agentId: string;
+    runId?: string | null;
+    link: IssueDedupeLink;
+    tracker: IssueTracker;
+    fingerprint?: string | null;
+    /** Everything but the project, which comes from the link. */
+    create: Omit<CreateIssueInput, "projectKey">;
+    /** Appended after the description (and after any "Regression of" line), so it stays the last line. */
+    footerMarkdown?: string;
+    /** Posted on the existing issue when the fingerprint is seen again. */
+    seenAgainMarkdown: string;
+    /** false: only a seen-again update may happen; a create or regression returns issue_cap_reached. Default true. */
+    createAllowed?: boolean;
+}
+export type FileIssueOutcome = "created" | "seen_again" | "regression";
+export type FileIssueSuccess = {
+    outcome: FileIssueOutcome;
+    issueKey: string;
+    url: string;
+    seenCount: number;
+};
+export type FileIssueResult = FileIssueSuccess | {
+    error: string;
+    message: string;
+};
+export declare const BUSY_RESULT: {
+    readonly error: "busy";
+    readonly message: "another sighting of this fingerprint is being filed; try again";
+};
+/**
+ * The part of a fingerprint that identifies it: letters and digits only, lower-cased (Unicode-normalised),
+ * so a model's small slips in case, punctuation or spacing ("checkout-api" vs "checkoutapi") still match.
+ */
+export declare function normalizeFingerprint(fingerprint: string): string;
+export declare function fingerprintHash(fingerprint: string): string;
+/** A stable signed 64-bit advisory-lock key for one (provider, project, hash). */
+export declare function dedupeLockKey(provider: string, projectKey: string, hash: string): bigint;
+export declare function fileIssue(deps: {
+    db: IssueDedupeDb;
+    lockTimeoutMs?: number;
+}, input: FileIssueInput): Promise<FileIssueResult>;
+/** Postgres lock_not_available (55P03), as raised when lock_timeout expires, however the driver wraps it. */
+export declare function isLockTimeout(err: unknown): boolean;

package/dist/core/issue-dedupe.js

@@ -0,0 +1,255 @@
+/**
+ * Fingerprint dedupe for issue creation, shared by jira_create_issue and
+ * self-defects. A fingerprint (opaque, 1-200 chars) is stored only as its
+ * sha256 hex in IssueFingerprint; the raw value never reaches the tracker.
+ *
+ *   no fingerprint                      -> create
+ *   no earlier issue (or it is gone,
+ *     or it moved out of the project)   -> create            ("created")
+ *   earlier issue still open            -> comment on it      ("seen_again")
+ *   earlier issue Done                  -> create a new one, link it to the
+ *                                          old one ("Relates"), old untouched
+ *                                                            ("regression")
+ *
+ * With createAllowed: false (a caller at its creation cap) only the
+ * seen-again update happens; where it would create (or file a regression)
+ * it returns { error: "issue_cap_reached" } and makes no tracker write.
+ *
+ * Concurrency: a Postgres advisory transaction lock on (provider, project,
+ * hash) serialises find -> decide -> tracker call -> row write, so concurrent
+ * calls with one fingerprint create at most one issue. Every tracker call in
+ * that critical section is bounded (TRACKER_CALL_OPTIONS) and the transaction
+ * timeout sits well above their sum, so the lock is never released (by a
+ * timed-out transaction) while a create is still in flight. The regression
+ * link is made after commit, outside the lock. Control-plane actions
+ * here (the regression link, the seen-again comment) are not gated by the
+ * link's allowlists but only ever act in a project the agent has a write link
+ * to. Never throws: failures come back as { error, message }.
+ */
+import { createHash } from "node:crypto";
+import { logger } from "./logger.js";
+import { IssueTrackerError, } from "../providers/issue-tracker/types.js";
+const log = logger.child({ module: "issue-dedupe" });
+export const FINGERPRINT_MAX_LENGTH = 200;
+/**
+ * Each tracker call inside the lock: a whole-call cap, and a 429 fails at once rather than sleeping. Jira
+ * Cloud calls through the api.atlassian.com gateway routinely take several seconds each, and one tracker
+ * call can be a few requests (a create resolves the issue type and its fields first), so the cap is generous.
+ */
+export const TRACKER_CALL_OPTIONS = { timeoutMs: 30_000, retryOn429: false };
+/** How long a sighting waits for another sighting of the same fingerprint before answering "busy". */
+export const DEDUPE_LOCK_TIMEOUT_MS = 5_000;
+/**
+ * The critical section is the lock wait (5 s) plus at most two bounded tracker calls (getIssue, then
+ * createIssue or comment: 2 x 30 s) plus a few row reads/writes; 90 s leaves ample margin so a create is
+ * never in flight when the transaction (and with it the advisory lock) is torn down. The cost: each
+ * sighting in progress holds one pool connection for up to this long, and waiters hold one for up to
+ * the lock timeout (callers waiting for a free connection give up after maxWait).
+ */
+export const DEDUPE_TRANSACTION_TIMEOUT_MS = 90_000;
+const DEDUPE_TRANSACTION_MAX_WAIT_MS = 10_000;
+export const BUSY_RESULT = {
+    error: "busy",
+    message: "another sighting of this fingerprint is being filed; try again",
+};
+/** Thrown inside the transaction to abort a create the caller disallowed (nothing was written). */
+class CreateNotAllowed extends Error {
+}
+/**
+ * The part of a fingerprint that identifies it: letters and digits only, lower-cased (Unicode-normalised),
+ * so a model's small slips in case, punctuation or spacing ("checkout-api" vs "checkoutapi") still match.
+ */
+export function normalizeFingerprint(fingerprint) {
+    return fingerprint
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, "");
+}
+export function fingerprintHash(fingerprint) {
+    return createHash("sha256").update(normalizeFingerprint(fingerprint), "utf8").digest("hex");
+}
+/** A stable signed 64-bit advisory-lock key for one (provider, project, hash). */
+export function dedupeLockKey(provider, projectKey, hash) {
+    const digest = createHash("sha256").update(`wardby:issue-dedupe:${provider}:${projectKey}:${hash}`).digest();
+    return digest.readBigInt64BE(0);
+}
+const REGRESSION_LINK_TYPE = "relates";
+export async function fileIssue(deps, input) {
+    const { link, tracker } = input;
+    // Set once the tracker side is done (issue created / comment posted), so a later row failure still reports it:
+    // answering with an error would make the caller retry and file a duplicate.
+    let completed;
+    let regressionOf;
+    // The tracker's own URL for the Done issue (never model input): the tracker renders it as a smart link.
+    let regressionOfUrl;
+    let hash;
+    try {
+        if (link.access !== "write") {
+            return { error: "permission_denied", message: `Creating issues in ${link.projectKey} needs a write link.` };
+        }
+        if (link.provider !== tracker.provider) {
+            return { error: "invalid_arguments", message: "The link and tracker providers differ." };
+        }
+        const withFooter = (markdown) => input.footerMarkdown ? `${markdown}\n\n${input.footerMarkdown}` : markdown;
+        const createInput = {
+            ...input.create,
+            projectKey: link.projectKey,
+            descriptionMarkdown: withFooter(input.create.descriptionMarkdown),
+        };
+        const fingerprint = input.fingerprint ?? undefined;
+        const createAllowed = input.createAllowed ?? true;
+        if (fingerprint === undefined) {
+            if (!createAllowed)
+                return capReached(link.projectKey);
+            const created = await tracker.createIssue(createInput);
+            return { outcome: "created", issueKey: created.key, url: created.url, seenCount: 1 };
+        }
+        if (fingerprint.length < 1 || fingerprint.length > FINGERPRINT_MAX_LENGTH) {
+            return {
+                error: "invalid_arguments",
+                message: `fingerprint must be 1-${FINGERPRINT_MAX_LENGTH} characters.`,
+            };
+        }
+        if (normalizeFingerprint(fingerprint) === "") {
+            return { error: "invalid_arguments", message: "fingerprint must contain letters or digits." };
+        }
+        const fpHash = fingerprintHash(fingerprint);
+        hash = fpHash;
+        const lockKey = dedupeLockKey(link.provider, link.projectKey, fpHash);
+        const lockTimeoutMs = Math.max(1, Math.trunc(deps.lockTimeoutMs ?? DEDUPE_LOCK_TIMEOUT_MS));
+        const result = await deps.db.$transaction(async (tx) => {
+            // Transaction-local: bounds the wait for the advisory lock below.
+            await tx.$executeRaw `SELECT set_config('lock_timeout', ${`${lockTimeoutMs}ms`}, true)`;
+            await tx.$executeRaw `SELECT pg_advisory_xact_lock(${lockKey})`;
+            const previous = await tx.issueFingerprint.findFirst({
+                where: { issueProvider: link.provider, projectKey: link.projectKey, fingerprintHash: fpHash },
+                orderBy: [{ firstSeenAt: "desc" }, { id: "desc" }],
+            });
+            if (previous) {
+                const view = await currentIssue(tracker, previous.issueKey);
+                // A moved issue (now in another project) is not reused. Known limitation: renaming the project's key
+                // makes every earlier issue look moved too (Jira answers with the new key while the link keeps the old
+                // one), so each sighting files a new issue until the link is re-pointed at the new key.
+                if (view && view.projectKey === link.projectKey) {
+                    if (view.statusCategory !== "done") {
+                        const seenCount = previous.seenCount + 1;
+                        await tracker.comment(previous.issueKey, {
+                            markdown: `${input.seenAgainMarkdown}\n\nSeen again (×${seenCount})`,
+                            ...(link.commentVisibilityRole ? { visibilityRole: link.commentVisibilityRole } : {}),
+                        }, TRACKER_CALL_OPTIONS);
+                        completed = { outcome: "seen_again", issueKey: previous.issueKey, url: view.url, seenCount };
+                        await tx.issueFingerprint.update({
+                            where: { id: previous.id },
+                            data: { seenCount, lastSeenAt: new Date() },
+                        });
+                        return completed;
+                    }
+                    regressionOf = previous.issueKey;
+                    regressionOfUrl = view.url;
+                }
+            }
+            if (!createAllowed)
+                throw new CreateNotAllowed();
+            // Not idempotent: if the bounded POST is aborted after Jira already committed the issue, this transaction
+            // rolls back with no fingerprint row, and a retry files a second issue. Inherent to timing out a create
+            // (Jira has no idempotency key for it); the timeout keeps the advisory lock from being held indefinitely.
+            const created = await tracker.createIssue(regressionOf
+                ? {
+                    ...createInput,
+                    descriptionMarkdown: withFooter(`${input.create.descriptionMarkdown}\n\nRegression of ${regressionOfUrl?.startsWith("https://") ? regressionOfUrl : regressionOf}`),
+                }
+                : createInput, TRACKER_CALL_OPTIONS);
+            completed = {
+                outcome: regressionOf ? "regression" : "created",
+                issueKey: created.key,
+                url: created.url,
+                seenCount: 1,
+            };
+            await tx.issueFingerprint.create({
+                data: {
+                    issueProvider: link.provider,
+                    projectKey: link.projectKey,
+                    fingerprintHash: fpHash,
+                    issueKey: created.key,
+                    agentId: input.agentId,
+                    createdByRunId: input.runId ?? null,
+                },
+            });
+            return completed;
+        }, { timeout: DEDUPE_TRANSACTION_TIMEOUT_MS, maxWait: DEDUPE_TRANSACTION_MAX_WAIT_MS });
+        if (result.outcome === "regression" && regressionOf) {
+            await linkRegression(tracker, result.issueKey, regressionOf, input.agentId);
+        }
+        return result;
+    }
+    catch (err) {
+        if (completed) {
+            // The tracker side happened; only the bookkeeping did not. Report what was done (hash only, never the raw value).
+            log.warn({
+                err,
+                agentId: input.agentId,
+                issueKey: completed.issueKey,
+                fingerprintHash: hash,
+                outcome: completed.outcome,
+            }, "issue dedupe: tracker action done but its fingerprint row was not saved");
+            if (completed.outcome === "regression" && regressionOf) {
+                await linkRegression(tracker, completed.issueKey, regressionOf, input.agentId);
+            }
+            return completed;
+        }
+        if (err instanceof CreateNotAllowed)
+            return capReached(link.projectKey);
+        if (isLockTimeout(err))
+            return { ...BUSY_RESULT };
+        if (err instanceof IssueTrackerError) {
+            log.warn({ code: err.code, agentId: input.agentId, projectKey: link.projectKey }, "issue dedupe: tracker call failed");
+            return { error: err.code, message: err.message };
+        }
+        log.warn({ err, agentId: input.agentId, projectKey: link.projectKey }, "issue dedupe failed");
+        return { error: "internal_error", message: "Filing the issue failed." };
+    }
+}
+function capReached(projectKey) {
+    return {
+        error: "issue_cap_reached",
+        message: `This run has reached its limit of new issues in ${projectKey} (maxNewIssuesPerRun); nothing was created.`,
+    };
+}
+/** The issue as it is now, or null when it no longer exists. */
+async function currentIssue(tracker, key) {
+    try {
+        return await tracker.getIssue(key, { maxComments: 0, agentMarker: "", ...TRACKER_CALL_OPTIONS });
+    }
+    catch (err) {
+        if (err instanceof IssueTrackerError && err.code === "tracker_not_found")
+            return null;
+        throw err;
+    }
+}
+/** Postgres lock_not_available (55P03), as raised when lock_timeout expires, however the driver wraps it. */
+export function isLockTimeout(err) {
+    for (let e = err, depth = 0; e && typeof e === "object" && depth < 5; depth++) {
+        const o = e;
+        if (o.code === "55P03")
+            return true;
+        if (typeof o.message === "string" && /\b55P03\b|lock timeout/i.test(o.message))
+            return true;
+        const meta = o.meta;
+        if (meta?.code === "55P03" || meta?.driverAdapterError?.cause?.originalCode === "55P03")
+            return true;
+        e = o.cause;
+    }
+    return false;
+}
+/** New relates to old, after commit and outside the lock. Best effort: the description already names the old issue. */
+async function linkRegression(tracker, newKey, oldKey, agentId) {
+    try {
+        const type = (await tracker.linkTypes(TRACKER_CALL_OPTIONS)).find((t) => t.name.toLowerCase() === REGRESSION_LINK_TYPE);
+        if (!type)
+            return;
+        await tracker.linkIssues({ type: type.name, inwardKey: oldKey, outwardKey: newKey }, TRACKER_CALL_OPTIONS);
+    }
+    catch (err) {
+        log.warn({ err, agentId, newKey, oldKey }, "regression link failed");
+    }
+}

package/dist/core/issue-events.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Routes issue-tracker events (Jira webhooks) to the native agents linked to
+ * the issue's project. Adapters normalise payloads into IssueEvent
+ * (providers/issue-tracker/jira-events.ts); this module decides which agents
+ * run. The actor gate is accountType (in the adapter) plus, for mention and
+ * assignment, the link's trustedAccountIds — a live Jira permission check
+ * for another user needs Jira admin rights, which the bot must not hold.
+ * See docs/private/2026-09-30-jira-issue-tracker-design.md §5.
+ */
+import type { PrismaClient } from "#prisma";
+import type { Executor } from "../providers/executor/types.js";
+import type { IssueEvent, IssueEventKind, IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+import { type DispatchDb } from "./dispatch.js";
+export type IssueEventDb = DispatchDb & Pick<PrismaClient, "agentIssueProject" | "runIssueStatus" | "issuePullRequest" | "workItem">;
+export interface RouteIssueEventDeps {
+    db: IssueEventDb;
+    executor: Executor;
+    trackers: IssueTrackerRegistry;
+}
+export interface RouteResult {
+    runIds: string[];
+    followUps: Array<() => Promise<void>>;
+}
+export interface OpenIssuePr {
+    repository: string;
+    number: number;
+    url: string;
+    openedByRunId: string;
+}
+type TaskLink = {
+    triggerLabels: string[];
+    trustedAccountIds: string[];
+};
+/**
+ * The trusted task part carries only what the gate vouched for: key, kinds
+ * (with admin-configured labels), the actor's accountId, and, when the actor
+ * is in the link's trustedAccountIds, their display name. An unchecked actor's
+ * display name goes into the untrusted context with the summary/description.
+ */
+export declare function issueTaskText(event: IssueEvent, matched: IssueEventKind[], issueUrl: string, link: TaskLink, openPrs?: OpenIssuePr[]): string;
+export declare function routeIssueEvent(event: IssueEvent, deps: RouteIssueEventDeps): Promise<RouteResult>;
+export {};