@wardby/cli 0.2.0 → 0.3.0

package/dist/core/provider-wording.js

@@ -0,0 +1,44 @@
+/**
+ * What a host (a PR comment, a check summary) is told when the model provider
+ * itself refused a run's requests: the class of problem and who has to act.
+ * Public repositories read these, so they never carry the provider's own
+ * error code or message; the code stays in the operator log.
+ */
+const CLASSES = ["quota", "rate_limited", "unavailable", "rejected"];
+const QUOTA_MARKERS = ["quota", "spend_limit", "billing", "insufficient_funds", "credit"];
+const UNAVAILABLE_CODES = new Set([
+    "server_error",
+    "overloaded",
+    "overloaded_error",
+    "service_unavailable",
+    // Anthropic's name for an internal server error.
+    "api_error",
+]);
+/** Files an upstream error code (or `http_<status>`) under the class of problem it names. */
+export function classifyProviderFailure(code) {
+    const lower = code.toLowerCase();
+    // Checked first: an exhausted account is the one case only an operator can fix.
+    if (QUOTA_MARKERS.some((marker) => lower.includes(marker)))
+        return "quota";
+    if (lower.includes("rate_limit"))
+        return "rate_limited";
+    if (UNAVAILABLE_CODES.has(lower) || /^http_5\d\d$/.test(lower))
+        return "unavailable";
+    return "rejected";
+}
+const SENTENCES = {
+    quota: "The model provider refused the request: its account has reached a spending or quota limit. An operator needs to raise the limit with the provider, then retry.",
+    rate_limited: "The model provider is rate-limiting requests. Try again later.",
+    unavailable: "The model provider reported an outage or overload. Try again later.",
+    rejected: "The model provider rejected the request.",
+};
+export function providerSentence(providerClass) {
+    return SENTENCES[providerClass];
+}
+/** The class a run's `provider_<class>` failure category names, or null for any other category. */
+export function providerClassOfCategory(category) {
+    if (!category?.startsWith("provider_"))
+        return null;
+    const value = category.slice("provider_".length);
+    return CLASSES.includes(value) ? value : null;
+}

package/dist/core/reconciler.d.ts

@@ -27,17 +27,53 @@
  * UPDATE commits first flips the row out of the matched status, so the
  * second one's WHERE simply matches zero rows — double-reconcile is a
  * no-op, not a race.
+ *
+ * Each pass also completes review-host checks left "in progress" by a run
+ * that ended without reaching `executeRun`'s own finalizer (reaped here as
+ * `lost`, failed to start, failed while loading, ...). One sweep covers all
+ * of those paths instead of patching each. Mention status comments get the
+ * same sweep: it also catches a run that ended before its comment was posted.
  */
-import type { PrismaClient } from "@prisma/client";
+import type { PrismaClient } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
-export type ReconcilerDb = Pick<PrismaClient, "run">;
+import type { ReviewHostRegistry } from "../providers/review-host/types.js";
+export type ReconcilerDb = Pick<PrismaClient, "run" | "runHostCheck" | "runHostStatus">;
+/**
+ * How long after a run finishes before its still-open check counts as
+ * orphaned: long enough that the sweep never races `executeRun`'s own
+ * `closeOpenHostCheck` for a run that just ended.
+ */
+export declare const ORPHANED_CHECK_GRACE_MS = 60000;
+/** Upper bound on checks completed per pass, so a backlog drains over several passes. */
+export declare const ORPHANED_CHECK_BATCH = 50;
+/** How long after a run finishes the sweep keeps trying to complete its check. */
+export declare const ORPHANED_CHECK_MAX_AGE_MS: number;
+/**
+ * Completes (as a failure) open host checks whose run reached a terminal status
+ * at least ORPHANED_CHECK_GRACE_MS and at most ORPHANED_CHECK_MAX_AGE_MS
+ * ago. Newest-finished first, so old checks the host keeps refusing cannot
+ * starve newer ones. A check the host still refuses after the max age (the
+ * check was deleted, the App was uninstalled, ...) is left as it is rather
+ * than retried forever; its Re-run button still works. Never queries when
+ * no host is configured. `closeOpenHostCheck` is best-effort and never throws.
+ */
+export declare function closeOrphanedHostChecks(db: Pick<PrismaClient, "runHostCheck" | "run">, hosts: ReviewHostRegistry | undefined, now?: Date): Promise<void>;
+/**
+ * Completes open mention status comments on the same terms as
+ * closeOrphanedHostChecks: the run ended between ORPHANED_CHECK_GRACE_MS and
+ * ORPHANED_CHECK_MAX_AGE_MS ago, newest first, at most ORPHANED_CHECK_BATCH per
+ * pass. `completeHostStatus` is best-effort and never throws.
+ */
+export declare function closeOrphanedHostStatuses(db: Pick<PrismaClient, "runHostStatus" | "run">, hosts: ReviewHostRegistry | undefined, now?: Date): Promise<void>;
 /** Runs one reconciliation pass. Returns the number of runs marked `lost`. */
-export declare function reconcileOnce(db: ReconcilerDb, now?: Date, heartbeatTimeoutMs?: number, executor?: Executor): Promise<number>;
+export declare function reconcileOnce(db: ReconcilerDb, now?: Date, heartbeatTimeoutMs?: number, executor?: Executor, reviewHosts?: ReviewHostRegistry): Promise<number>;
 export interface ReconcilerOptions {
     db?: ReconcilerDb;
     intervalMs?: number;
     heartbeatTimeoutMs?: number;
     executor?: Executor;
+    /** Hosts used to complete checks orphaned by runs that ended abnormally; none configured = no sweep. */
+    reviewHosts?: ReviewHostRegistry;
 }
 export interface ReconcilerHandle {
     stop(): void;

package/dist/core/reconciler.js

@@ -27,13 +27,95 @@
  * UPDATE commits first flips the row out of the matched status, so the
  * second one's WHERE simply matches zero rows — double-reconcile is a
  * no-op, not a race.
+ *
+ * Each pass also completes review-host checks left "in progress" by a run
+ * that ended without reaching `executeRun`'s own finalizer (reaped here as
+ * `lost`, failed to start, failed while loading, ...). One sweep covers all
+ * of those paths instead of patching each. Mention status comments get the
+ * same sweep: it also catches a run that ended before its comment was posted.
  */
 import { HEARTBEAT_TIMEOUT_MS, RECONCILE_INTERVAL_MS } from "./timing.js";
 import { prisma as defaultDb } from "./db.js";
 import { logger } from "./logger.js";
+import { closeOpenHostCheck } from "./review-host-checks.js";
+import { completeHostStatus } from "./host-status.js";
 const reconcilerLog = logger.child({ module: "reconciler" });
+/**
+ * How long after a run finishes before its still-open check counts as
+ * orphaned: long enough that the sweep never races `executeRun`'s own
+ * `closeOpenHostCheck` for a run that just ended.
+ */
+export const ORPHANED_CHECK_GRACE_MS = 60_000;
+/** Upper bound on checks completed per pass, so a backlog drains over several passes. */
+export const ORPHANED_CHECK_BATCH = 50;
+/** How long after a run finishes the sweep keeps trying to complete its check. */
+export const ORPHANED_CHECK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Completes (as a failure) open host checks whose run reached a terminal status
+ * at least ORPHANED_CHECK_GRACE_MS and at most ORPHANED_CHECK_MAX_AGE_MS
+ * ago. Newest-finished first, so old checks the host keeps refusing cannot
+ * starve newer ones. A check the host still refuses after the max age (the
+ * check was deleted, the App was uninstalled, ...) is left as it is rather
+ * than retried forever; its Re-run button still works. Never queries when
+ * no host is configured. `closeOpenHostCheck` is best-effort and never throws.
+ */
+export async function closeOrphanedHostChecks(db, hosts, now = new Date()) {
+    const providers = Object.keys(hosts ?? {});
+    if (!hosts || providers.length === 0)
+        return;
+    const orphans = await db.runHostCheck.findMany({
+        where: {
+            completedAt: null,
+            // A check for a provider that isn't configured could never be completed; keep it out of the batch.
+            provider: { in: providers },
+            run: {
+                status: { notIn: ["pending", "running"] },
+                finishedAt: {
+                    lte: new Date(now.getTime() - ORPHANED_CHECK_GRACE_MS),
+                    gte: new Date(now.getTime() - ORPHANED_CHECK_MAX_AGE_MS),
+                },
+            },
+        },
+        select: { run: { select: { id: true, status: true } } },
+        orderBy: { run: { finishedAt: "desc" } },
+        take: ORPHANED_CHECK_BATCH,
+    });
+    for (const { run } of orphans)
+        await closeOpenHostCheck(db, run, hosts);
+}
+/**
+ * Completes open mention status comments on the same terms as
+ * closeOrphanedHostChecks: the run ended between ORPHANED_CHECK_GRACE_MS and
+ * ORPHANED_CHECK_MAX_AGE_MS ago, newest first, at most ORPHANED_CHECK_BATCH per
+ * pass. `completeHostStatus` is best-effort and never throws.
+ */
+export async function closeOrphanedHostStatuses(db, hosts, now = new Date()) {
+    const providers = Object.keys(hosts ?? {});
+    if (!hosts || providers.length === 0)
+        return;
+    const orphans = await db.runHostStatus.findMany({
+        where: {
+            completedAt: null,
+            provider: { in: providers },
+            run: {
+                status: { notIn: ["pending", "running"] },
+                finishedAt: {
+                    lte: new Date(now.getTime() - ORPHANED_CHECK_GRACE_MS),
+                    gte: new Date(now.getTime() - ORPHANED_CHECK_MAX_AGE_MS),
+                },
+            },
+        },
+        select: { run: { select: { id: true, status: true, finalText: true } } },
+        orderBy: { run: { finishedAt: "desc" } },
+        take: ORPHANED_CHECK_BATCH,
+    });
+    // postIfMissing: by now the dispatching instance's follow-up has had its
+    // chance; a run that ended with no comment (it died first) gets one here.
+    for (const { run } of orphans)
+        await completeHostStatus(db, run, hosts, { postIfMissing: true });
+}
 /** Runs one reconciliation pass. Returns the number of runs marked `lost`. */
-export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, executor) {
+export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, executor, reviewHosts) {
     const cutoff = new Date(now.getTime() - heartbeatTimeoutMs);
     const stale = {
         executionManaged: true,
@@ -133,6 +215,8 @@ export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = H
         });
         lost += result.count;
     }
+    await closeOrphanedHostChecks(db, reviewHosts, now);
+    await closeOrphanedHostStatuses(db, reviewHosts, now);
     return lost;
 }
 export function startReconciler(options = {}) {
@@ -140,7 +224,7 @@ export function startReconciler(options = {}) {
     const intervalMs = options.intervalMs ?? RECONCILE_INTERVAL_MS;
     const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? HEARTBEAT_TIMEOUT_MS;
     const timer = setInterval(() => {
-        reconcileOnce(db, new Date(), heartbeatTimeoutMs, options.executor).catch((err) => {
+        reconcileOnce(db, new Date(), heartbeatTimeoutMs, options.executor, options.reviewHosts).catch((err) => {
             reconcilerLog.error({ err }, "reconcile pass failed");
         });
     }, intervalMs);

package/dist/core/repo-access.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Repository access authorization, host-neutral (security findings
+ * H5-1/A3/C3-2 and H5-3). An agent may use a repository only when its current
+ * owner's verified host identity has enough permission on it, or when the
+ * authorization was an explicit, recorded admin approval (or predates
+ * enforcement: "grandfathered"). Owner-less (public) agents never hold
+ * repository authority: anyone can edit them.
+ *
+ * One gate serves every point of use (a coding run before its workspace is
+ * prepared, each repo_* tool call, each host-event dispatch and mention
+ * author) and every set-time check (link_repository, create/update_agent).
+ * Host answers are cached per (provider, repository, host user id) for a
+ * short TTL, positive and negative alike; set-time checks bypass the cache
+ * and refresh it. A host error always denies: fail closed.
+ * See docs/private/2026-09-26-repo-access-authorization-spec-and-plan.md.
+ */
+import type { PrismaClient } from "#prisma";
+import { type HostPermission, type HostUser, type ReviewHostRegistry } from "../providers/review-host/types.js";
+export type { HostPermission };
+/** How an authorization was granted; stored on the row that grants the authority. */
+export type AuthorizedVia = "host_permission" | "admin" | "grandfathered";
+export declare const AUTHORIZED_VIA: readonly AuthorizedVia[];
+export type RepoAccessDenial = "owner_required" | "not_authorized" | "identity_not_linked" | "insufficient_permission" | "check_failed"
+/** In-flight use only: the host was unreachable or rate-limited, even after one retry. */
+ | "check_unavailable";
+export type RepoAccessDecision = {
+    ok: true;
+    level?: HostPermission;
+} | {
+    ok: false;
+    reason: RepoAccessDenial;
+    level?: HostPermission;
+};
+/** What a use of the repository needs. */
+export type RepoAccessKind = "coding" | "write" | "read" | "mention";
+/**
+ * Coding runs and write links push, comment, and publish checks; a mention
+ * drives a write-capable agent holding its owner's tools and secrets, so
+ * triage is not enough for it either.
+ */
+export declare function requiredLevel(kind: RepoAccessKind): HostPermission;
+export declare function atLeast(level: HostPermission, required: HostPermission): boolean;
+export interface AuthorizeUseInput {
+    /** The agent's CURRENT owner — never whoever authorized the link. */
+    ownerId: string | null;
+    provider: string;
+    repository: string;
+    required: HostPermission;
+    /** The stamp on the row granting the authority (null = never authorized). */
+    authorizedVia: string | null;
+    /**
+     * A use by a run already under way (a launched coding run, its final push,
+     * a repo_* call): a transient host error (5xx, timeout, rate limit) is
+     * retried once, then denied as `check_unavailable`. Starting something new
+     * and set-time checks stay strict: any error is `check_failed`, no retry.
+     */
+    retryTransient?: boolean;
+}
+export interface RepoAccessGate {
+    /** Point of use: may this agent (by its owner and stamp) use the repository now? */
+    authorizeUse(input: AuthorizeUseInput): Promise<RepoAccessDecision>;
+    /** Does this principal's linked identity have `required` on the repository? */
+    authorizePrincipal(input: {
+        principalId: string;
+        provider: string;
+        repository: string;
+        required: HostPermission;
+        /** Bypass (and refresh) the cache: set-time checks. */
+        fresh?: boolean;
+    }): Promise<RepoAccessDecision>;
+    /** Does this host user (e.g. a mention's author) have `required` on the repository? */
+    authorizeHostUser(input: {
+        provider: string;
+        repository: string;
+        user: HostUser;
+        required: HostPermission;
+        fresh?: boolean;
+    }): Promise<RepoAccessDecision>;
+}
+export interface RepoAccessGateOptions {
+    db: Pick<PrismaClient, "hostIdentity">;
+    hosts: ReviewHostRegistry;
+    /** Default 5 minutes. */
+    ttlMs?: number;
+    /** Default 1000; the oldest entry is evicted first. */
+    maxEntries?: number;
+    now?: () => number;
+    /** Delay before the one retry of a transient error (default 1s). */
+    retryDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** 5xx, rate limits (403/429), and transport failures: worth one retry for a run already under way. */
+export declare function isTransientHostError(err: unknown): boolean;
+export declare const DEFAULT_REPO_ACCESS_TTL_MS: number;
+export declare function createRepoAccessGate(options: RepoAccessGateOptions): RepoAccessGate;
+/** Actionable, non-leaking text for a denial, for tool results and run errors. */
+export declare function describeDenial(decision: Extract<RepoAccessDecision, {
+    ok: false;
+}>, repository: string): string;

package/dist/core/repo-access.js

@@ -0,0 +1,136 @@
+import { HOST_PERMISSION_RANK, ReviewHostError, } from "../providers/review-host/types.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "repo-access" });
+export const AUTHORIZED_VIA = ["host_permission", "admin", "grandfathered"];
+/**
+ * Coding runs and write links push, comment, and publish checks; a mention
+ * drives a write-capable agent holding its owner's tools and secrets, so
+ * triage is not enough for it either.
+ */
+export function requiredLevel(kind) {
+    return kind === "read" ? "read" : "write";
+}
+export function atLeast(level, required) {
+    return HOST_PERMISSION_RANK[level] >= HOST_PERMISSION_RANK[required];
+}
+/** 5xx, rate limits (403/429), and transport failures: worth one retry for a run already under way. */
+export function isTransientHostError(err) {
+    if (!(err instanceof ReviewHostError) || err.code !== "host_api_error")
+        return false;
+    return err.message === "github_api_unavailable" || /^github_api_error:(5\d\d|429|403)(:|$)/.test(err.message);
+}
+export const DEFAULT_REPO_ACCESS_TTL_MS = 5 * 60_000;
+export function createRepoAccessGate(options) {
+    const ttlMs = options.ttlMs ?? DEFAULT_REPO_ACCESS_TTL_MS;
+    const maxEntries = options.maxEntries ?? 1000;
+    const now = options.now ?? (() => Date.now());
+    const retryDelayMs = options.retryDelayMs ?? 1000;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const cache = new Map();
+    /** The user's level, or why it could not be determined (host missing or failing). */
+    async function levelOf(provider, repository, user, fresh, retryTransient) {
+        const key = `${provider}\u0000${repository}\u0000${user.id}`;
+        const hit = cache.get(key);
+        if (!fresh && hit && hit.expiresAt > now())
+            return { ok: true, level: hit.level, login: user.login };
+        const host = options.hosts[provider];
+        if (!host) {
+            log.warn({ provider, repository }, "no review host configured for a repository access check");
+            return { ok: false, transient: false };
+        }
+        let answer;
+        for (let attempt = 0; !answer; attempt++) {
+            if (attempt > 0)
+                await sleep(retryDelayMs);
+            try {
+                answer = await host.repositoryPermission(repository, user);
+            }
+            catch (err) {
+                const transient = isTransientHostError(err);
+                log.warn({ err, provider, repository, hostUserId: user.id, transient, attempt }, "repository access check failed");
+                // Strict: no retry. In flight: one retry of a transient error, then check_unavailable.
+                if (!transient || !retryTransient || attempt > 0)
+                    return { ok: false, transient: transient && retryTransient };
+            }
+        }
+        cache.delete(key);
+        cache.set(key, { level: answer.level, expiresAt: now() + ttlMs });
+        while (cache.size > maxEntries)
+            cache.delete(cache.keys().next().value);
+        return { ok: true, ...answer };
+    }
+    const unavailable = (answer) => ({
+        ok: false,
+        reason: answer.transient ? "check_unavailable" : "check_failed",
+    });
+    function decide(level, required) {
+        return atLeast(level, required) ? { ok: true, level } : { ok: false, reason: "insufficient_permission", level };
+    }
+    async function authorizePrincipal(input) {
+        let identity;
+        try {
+            identity = await options.db.hostIdentity.findUnique({
+                where: { principalId_provider: { principalId: input.principalId, provider: input.provider } },
+            });
+        }
+        catch (err) {
+            log.warn({ err, provider: input.provider }, "could not read a host identity; denying");
+            return { ok: false, reason: "check_failed" };
+        }
+        if (!identity)
+            return { ok: false, reason: "identity_not_linked" };
+        const answer = await levelOf(input.provider, input.repository, { id: identity.hostUserId, login: identity.login }, input.fresh === true, input.retryTransient === true);
+        if (!answer.ok)
+            return unavailable(answer);
+        if (answer.login !== identity.login) {
+            await options.db.hostIdentity
+                .updateMany({
+                where: { principalId: input.principalId, provider: input.provider, hostUserId: identity.hostUserId },
+                data: { login: answer.login },
+            })
+                .catch((err) => log.warn({ err }, "could not record a renamed host login"));
+        }
+        return decide(answer.level, input.required);
+    }
+    return {
+        async authorizeUse(input) {
+            if (!input.ownerId)
+                return { ok: false, reason: "owner_required" };
+            if (input.authorizedVia === "admin" || input.authorizedVia === "grandfathered")
+                return { ok: true };
+            if (input.authorizedVia !== "host_permission")
+                return { ok: false, reason: "not_authorized" };
+            return authorizePrincipal({
+                principalId: input.ownerId,
+                provider: input.provider,
+                repository: input.repository,
+                required: input.required,
+                retryTransient: input.retryTransient,
+            });
+        },
+        authorizePrincipal,
+        async authorizeHostUser(input) {
+            const answer = await levelOf(input.provider, input.repository, input.user, input.fresh === true, false);
+            if (!answer.ok)
+                return unavailable(answer);
+            return decide(answer.level, input.required);
+        },
+    };
+}
+/** Actionable, non-leaking text for a denial, for tool results and run errors. */
+export function describeDenial(decision, repository) {
+    switch (decision.reason) {
+        case "owner_required":
+            return `Agents without an owner cannot use repositories; an admin can assign one with make_owner.`;
+        case "not_authorized":
+            return `This agent's access to ${repository} was never authorized; re-link it (link_repository) or update the coding profile.`;
+        case "identity_not_linked":
+            return `The agent owner has not linked a GitHub account; run link_host_account first.`;
+        case "insufficient_permission":
+            return `The agent owner's GitHub account has ${decision.level ?? "no"} access to ${repository}, which is not enough.`;
+        case "check_failed":
+            return `Could not verify access to ${repository} right now; try again later.`;
+        case "check_unavailable":
+            return `GitHub could not be reached (or rate-limited wardby) while re-checking access to ${repository}, so the use was refused for safety. Try again later.`;
+    }
+}

package/dist/core/review-host-checks.d.ts

@@ -0,0 +1,11 @@
+import type { PrismaClient, Run } from "#prisma";
+import type { ReviewHostRegistry } from "../providers/review-host/types.js";
+/**
+ * A check the control plane started for a run must never stay "in progress":
+ * when the run reaches any terminal state without the review tool having
+ * completed it, complete it as a failure. Not neutral: branch protection
+ * counts a neutral required check as passing, which would let a pull request
+ * merge with no review. Best effort — a failure is logged, not retried; the
+ * check's Re-run button still works. Never throws.
+ */
+export declare function closeOpenHostCheck(db: Pick<PrismaClient, "runHostCheck" | "run">, run: Pick<Run, "id" | "status">, hosts: ReviewHostRegistry | undefined): Promise<void>;

package/dist/core/review-host-checks.js

@@ -0,0 +1,41 @@
+import { loadBudgetSentence } from "./budget-wording.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "review-host-checks" });
+/**
+ * A check the control plane started for a run must never stay "in progress":
+ * when the run reaches any terminal state without the review tool having
+ * completed it, complete it as a failure. Not neutral: branch protection
+ * counts a neutral required check as passing, which would let a pull request
+ * merge with no review. Best effort — a failure is logged, not retried; the
+ * check's Re-run button still works. Never throws.
+ */
+export async function closeOpenHostCheck(db, run, hosts) {
+    if (!hosts)
+        return;
+    try {
+        const check = await db.runHostCheck.findUnique({ where: { runId: run.id } });
+        if (!check || check.completedAt)
+            return;
+        const host = hosts[check.provider];
+        if (!host)
+            return;
+        const outOfBudget = run.status === "refused" || run.status === "budget_exhausted";
+        await host.completeCheck(check.repository, {
+            checkId: check.checkId,
+            conclusion: "failure",
+            ...(outOfBudget
+                ? {
+                    title: "Review could not run: out of budget",
+                    summary: `${await loadBudgetSentence(db, run.id, run.status)} Use Re-run after raising the budget or when it resets.`,
+                }
+                : {
+                    title: "Review did not complete",
+                    summary: `wardby run ${run.id} ended with status "${run.status}" before publishing a review. Use Re-run to try again.`,
+                }),
+        });
+        await db.runHostCheck.update({ where: { runId: run.id }, data: { completedAt: new Date() } });
+    }
+    catch (err) {
+        log.warn({ err, runId: run.id }, "could not complete the run's host check");
+    }
+}

package/dist/core/review-host-tools.d.ts

@@ -0,0 +1,47 @@
+import type { LoadedTool } from "../providers/engine/types.js";
+import { type ReviewHostProvider, type ReviewHostRegistry } from "../providers/review-host/types.js";
+import { type RepoAccessDecision } from "./repo-access.js";
+export interface RepositoryLink {
+    provider: ReviewHostProvider;
+    repository: string;
+    access: "read" | "write";
+    checkName: string | null;
+}
+export interface RunHostCheckRef {
+    provider: string;
+    repository: string;
+    checkId: string;
+    /** The head the check was started on; the check is only the review's if the heads match. */
+    headSha: string;
+    /**
+     * The pull request the run was dispatched for. A check (the run's own, or a
+     * new one under the link's checkName) is only ever published for this PR;
+     * null (a row from before it was recorded) binds to no PR.
+     */
+    prNumber: number | null;
+}
+export interface ReviewToolContext {
+    agentId: string;
+    links: readonly RepositoryLink[];
+    hosts: ReviewHostRegistry;
+    /** The run's open check, if the control plane started one. */
+    runCheck: RunHostCheckRef | null;
+    /** Records that the run's check is now completed (RunHostCheck.completedAt). */
+    markRunCheckCompleted: () => Promise<void>;
+    /**
+     * Re-authorizes the link against its current stamp and the agent's current
+     * owner (core/repo-access.ts). Called before every host call; a denial or a
+     * throw refuses the call.
+     */
+    authorize: (link: RepositoryLink) => Promise<RepoAccessDecision>;
+}
+export declare const REVIEW_HOST_TOOL_DEFS: LoadedTool[];
+export declare const REVIEW_HOST_TOOL_NAMES: ReadonlySet<string>;
+export declare function resolveLink(links: readonly RepositoryLink[], repositoryArg: string): RepositoryLink | "ambiguous" | null;
+/**
+ * Dispatches one built-in repo tool call. Never throws — mirrors
+ * runner.ts's `runSandboxTool` contract: a failure becomes a JSON error
+ * result fed back to the model as the tool's result, not an engine-halting
+ * exception.
+ */
+export declare function handleReviewHostTool(name: string, argsJson: string, ctx: ReviewToolContext): Promise<string>;