@wardby/cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,347 @@
+/**
+ * Built-in code-review tools (`repo_*`) for native agents with at least one
+ * AgentRepository link. Like the memory built-ins they are synthesized by the
+ * runner, recognized by name, and never run in the sandbox. The security
+ * boundary is here: every call names a repository, which must resolve to one
+ * of this agent's links (with write access for write tools); the host then
+ * mints its own least-permission credential. The model never sees a token,
+ * a check id, or a marker. Never throws — failures are JSON tool results.
+ * See docs/private/2026-09-25-code-review-host-design.md §7.
+ */
+import { z } from "zod";
+import { REVIEW_HOST_PROVIDERS, ReviewHostError, } from "../providers/review-host/types.js";
+import { normalizeGitHubRepository } from "../coding/protocol.js";
+import { logger } from "./logger.js";
+import { describeDenial } from "./repo-access.js";
+const log = logger.child({ module: "review-host-tools" });
+const DEFAULT_PATCH_CHARS = 60_000;
+const SHA = z.string().regex(/^[0-9a-f]{40}$/);
+const Repository = z.string().min(1).max(300);
+const PrReadArgs = z
+    .object({
+    repository: Repository,
+    prNumber: z.number().int().positive(),
+    sinceSha: SHA.optional(),
+    maxPatchChars: z.number().int().positive().max(200_000).optional(),
+})
+    .strict();
+const ReadFileArgs = z
+    .object({
+    repository: Repository,
+    path: z.string().min(1).max(500),
+    ref: z.string().min(1).max(200).optional(),
+    startLine: z.number().int().positive().optional(),
+    maxLines: z.number().int().positive().max(2000).optional(),
+})
+    .strict();
+const ListFilesArgs = z
+    .object({
+    repository: Repository,
+    ref: z.string().min(1).max(200).optional(),
+    pathPrefix: z.string().max(500).optional(),
+})
+    .strict();
+const InlineCommentArgs = z
+    .object({
+    path: z.string().min(1).max(500),
+    line: z.number().int().positive(),
+    side: z.enum(["LEFT", "RIGHT"]).optional(),
+    severity: z.string().min(1).max(20),
+    body: z.string().min(1).max(4000),
+})
+    .strict();
+const PublishArgs = z
+    .object({
+    repository: Repository,
+    prNumber: z.number().int().positive(),
+    headSha: SHA,
+    verdict: z.enum(["APPROVE", "CHANGES_REQUESTED", "COMMENT"]),
+    summary: z.string().min(1).max(140),
+    body: z.string().min(1).max(60_000),
+    comments: z.array(InlineCommentArgs).max(50).optional(),
+    resolveThreadIds: z
+        .array(z.string().regex(/^[A-Za-z0-9_=-]{1,100}$/))
+        .max(100)
+        .optional(),
+})
+    .strict();
+const CommentArgs = z
+    .object({
+    repository: Repository,
+    number: z.number().int().positive(),
+    body: z.string().min(1).max(20_000),
+    replyToReviewCommentId: z
+        .string()
+        .regex(/^\d{1,20}$/)
+        .optional(),
+})
+    .strict();
+const REPOSITORY_PROP = {
+    type: "string",
+    description: 'The repository as "owner/name" (or "github.com/owner/name"); must be one this agent is linked to.',
+};
+export const REVIEW_HOST_TOOL_DEFS = [
+    {
+        name: "repo_pr_read",
+        description: "Reads a pull request: title, body, author, state, refs, headSha, isFork, each changed file's unified-diff patch (patches share a character budget; truncated ones are flagged), lastReviewedSha — the head you last reviewed on this PR, if any — and openThreads: your own unresolved inline review threads (id, path, line, outdated, body). Pass sinceSha (usually lastReviewedSha) to get only what changed since then; if baseMergedSince is true, the base branch was merged in meanwhile and each file shows the PR's full diff against the base, limited to files that changed since sinceSha.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                prNumber: { type: "integer", minimum: 1 },
+                sinceSha: { type: "string", pattern: "^[0-9a-f]{40}$" },
+                maxPatchChars: { type: "integer", minimum: 1, maximum: 200000 },
+            },
+            required: ["repository", "prNumber"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_read_file",
+        description: "Reads a file with line numbers (paged by startLine/maxLines, default 400 lines) or lists a directory, at a ref. Use the PR's headSha as the ref when reviewing.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                path: { type: "string" },
+                ref: { type: "string" },
+                startLine: { type: "integer", minimum: 1 },
+                maxLines: { type: "integer", minimum: 1, maximum: 2000 },
+            },
+            required: ["repository", "path"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_list_files",
+        description: 'Lists every file (path and size) at a ref (default: the default branch), optionally under a path prefix such as "tests/". Skips node_modules, dist, and lockfiles.',
+        jsonSchema: {
+            type: "object",
+            properties: { repository: REPOSITORY_PROP, ref: { type: "string" }, pathPrefix: { type: "string" } },
+            required: ["repository"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_publish_review",
+        description: "Publishes your review of one pull request head, in one call: inline comments on diff lines (a ```suggestion block in a comment body becomes a one-click fix; comments on lines outside the diff move to the summary automatically), one summary comment that is edited in place on later reviews, and — only on the pull request this run was started for, by an agent linked with a check name — the check conclusion (APPROVE = success, CHANGES_REQUESTED = failure, COMMENT = neutral). Pass resolveThreadIds with the ids of your openThreads that this head fixes; only your own open threads on this PR are resolved, and the result lists resolvedThreadIds and skippedThreadIds. Returns published:false with reason stale_head if the PR moved on; then stop.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                prNumber: { type: "integer", minimum: 1 },
+                headSha: { type: "string", pattern: "^[0-9a-f]{40}$" },
+                verdict: { type: "string", enum: ["APPROVE", "CHANGES_REQUESTED", "COMMENT"] },
+                summary: { type: "string", maxLength: 140, description: "One line, shown on the check." },
+                body: { type: "string", maxLength: 60000, description: "The full review in markdown." },
+                comments: {
+                    type: "array",
+                    maxItems: 50,
+                    items: {
+                        type: "object",
+                        properties: {
+                            path: { type: "string" },
+                            line: {
+                                type: "integer",
+                                minimum: 1,
+                                description: "Line number in the new file (side RIGHT) or the old file (side LEFT).",
+                            },
+                            side: { type: "string", enum: ["LEFT", "RIGHT"] },
+                            severity: { type: "string", description: "e.g. CRITICAL, MAJOR, MINOR, NIT" },
+                            body: { type: "string", maxLength: 4000 },
+                        },
+                        required: ["path", "line", "severity", "body"],
+                        additionalProperties: false,
+                    },
+                },
+                resolveThreadIds: {
+                    type: "array",
+                    maxItems: 100,
+                    items: { type: "string", pattern: "^[A-Za-z0-9_=-]{1,100}$" },
+                    description: "Ids from repo_pr_read's openThreads whose problem this head fixes. Leave a thread out when unsure.",
+                },
+            },
+            required: ["repository", "prNumber", "headSha", "verdict", "summary", "body"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_comment",
+        description: "Posts a comment on an issue or pull request conversation, or — with replyToReviewCommentId — replies inside an inline review thread.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                number: { type: "integer", minimum: 1, description: "The issue or pull request number." },
+                body: { type: "string", maxLength: 20000 },
+                replyToReviewCommentId: { type: "string", pattern: "^\\d{1,20}$" },
+            },
+            required: ["repository", "number", "body"],
+            additionalProperties: false,
+        },
+    },
+];
+export const REVIEW_HOST_TOOL_NAMES = new Set(REVIEW_HOST_TOOL_DEFS.map((t) => t.name));
+const WRITE_TOOLS = new Set(["repo_publish_review", "repo_comment"]);
+const HOST_PREFIXES = { github: "github.com/" };
+function normalizeFor(provider, value) {
+    try {
+        if (provider === "github")
+            return normalizeGitHubRepository(value);
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function resolveLink(links, repositoryArg) {
+    const raw = repositoryArg.trim();
+    for (const provider of REVIEW_HOST_PROVIDERS) {
+        const prefix = HOST_PREFIXES[provider];
+        if (raw.toLowerCase().startsWith(prefix)) {
+            const repository = normalizeFor(provider, raw.slice(prefix.length));
+            return links.find((l) => l.provider === provider && l.repository === repository) ?? null;
+        }
+    }
+    const matches = links.filter((l) => l.repository === normalizeFor(l.provider, raw));
+    if (matches.length > 1)
+        return "ambiguous";
+    return matches[0] ?? null;
+}
+function error(code, message = code) {
+    return JSON.stringify({ error: code, message });
+}
+/** Bookkeeping only: a failure to record the check completed is logged and never changes the tool result. */
+async function markCompleted(ctx) {
+    try {
+        await ctx.markRunCheckCompleted();
+    }
+    catch (err) {
+        log.warn({ err, agentId: ctx.agentId }, "could not record the run's check completed");
+    }
+}
+/**
+ * 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 async function handleReviewHostTool(name, argsJson, ctx) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argsJson || "{}");
+    }
+    catch (err) {
+        return error("invalid_arguments_json", err instanceof Error ? err.message : String(err));
+    }
+    const repositoryArg = parsed?.repository;
+    if (typeof repositoryArg !== "string")
+        return error("invalid_arguments", "repository is required");
+    const link = resolveLink(ctx.links, repositoryArg);
+    if (link === "ambiguous")
+        return error("repository_not_linked", "Ambiguous repository; qualify it as host/owner/name.");
+    if (!link)
+        return error("repository_not_linked", `This agent is not linked to "${repositoryArg}".`);
+    if (WRITE_TOOLS.has(name) && link.access !== "write") {
+        return error("write_access_required", `This agent's link to ${link.repository} is read-only.`);
+    }
+    const host = ctx.hosts[link.provider];
+    if (!host)
+        return error("host_not_configured", `No ${link.provider} host is configured on this deployment.`);
+    let decision;
+    try {
+        decision = await ctx.authorize(link);
+    }
+    catch (err) {
+        log.warn({ err, agentId: ctx.agentId }, "repository authorization failed; denying");
+        decision = { ok: false, reason: "check_failed" };
+    }
+    if (!decision.ok) {
+        log.info({ agentId: ctx.agentId, repository: link.repository, reason: decision.reason }, "repository use denied");
+        return error(decision.reason === "check_unavailable" ? "repository_access_unavailable" : "repository_access_denied", describeDenial(decision, link.repository));
+    }
+    try {
+        switch (name) {
+            case "repo_pr_read": {
+                const a = PrReadArgs.parse(parsed);
+                return JSON.stringify(await host.readPullRequest(link.repository, a.prNumber, {
+                    sinceSha: a.sinceSha,
+                    maxPatchChars: a.maxPatchChars ?? DEFAULT_PATCH_CHARS,
+                    agentMarker: ctx.agentId,
+                }));
+            }
+            case "repo_read_file": {
+                const a = ReadFileArgs.parse(parsed);
+                return JSON.stringify(await host.readFile(link.repository, a.path, a.ref, {
+                    startLine: a.startLine ?? 1,
+                    maxLines: a.maxLines ?? 400,
+                }));
+            }
+            case "repo_list_files": {
+                const a = ListFilesArgs.parse(parsed);
+                return JSON.stringify(await host.listFiles(link.repository, a.ref, a.pathPrefix));
+            }
+            case "repo_publish_review": {
+                const a = PublishArgs.parse(parsed);
+                const runCheck = ctx.runCheck;
+                // E-08/H5-4: a verdict check is only ever published on the PR this
+                // run was dispatched for (never a fork: those are never dispatched).
+                // Any other publish is comments only, with no check at all.
+                const samePullRequest = runCheck !== null &&
+                    runCheck.provider === link.provider &&
+                    runCheck.repository === link.repository &&
+                    runCheck.prNumber !== null &&
+                    runCheck.prNumber === a.prNumber;
+                const ownsCheck = samePullRequest && a.headSha === runCheck.headSha;
+                if (samePullRequest && !ownsCheck) {
+                    // The run's check sits on another head; close it rather than attach this review's verdict to it.
+                    try {
+                        await host.completeCheck(link.repository, {
+                            checkId: runCheck.checkId,
+                            conclusion: "neutral",
+                            title: "Superseded by a newer push",
+                            summary: "This run reviewed a newer commit; see that commit's check.",
+                        });
+                        await markCompleted(ctx);
+                    }
+                    catch (err) {
+                        log.warn({ err, agentId: ctx.agentId }, "could not supersede the run's check");
+                    }
+                }
+                const result = await host.publishReview(link.repository, {
+                    prNumber: a.prNumber,
+                    headSha: a.headSha,
+                    verdict: a.verdict,
+                    summary: a.summary,
+                    body: a.body,
+                    comments: (a.comments ?? []).map((c) => ({ ...c, side: c.side ?? "RIGHT" })),
+                    agentMarker: ctx.agentId,
+                    ...(samePullRequest && link.checkName ? { checkName: link.checkName } : {}),
+                    ...(ownsCheck ? { checkId: runCheck.checkId } : {}),
+                    ...(a.resolveThreadIds?.length ? { resolveThreadIds: a.resolveThreadIds } : {}),
+                });
+                if (ownsCheck)
+                    await markCompleted(ctx);
+                return JSON.stringify(result);
+            }
+            case "repo_comment": {
+                const a = CommentArgs.parse(parsed);
+                return JSON.stringify(await host.comment(link.repository, {
+                    number: a.number,
+                    body: a.body,
+                    replyToReviewCommentId: a.replyToReviewCommentId,
+                }));
+            }
+            default:
+                return error("unknown_tool", `No built-in tool named "${name}".`);
+        }
+    }
+    catch (err) {
+        if (err instanceof z.ZodError) {
+            return error("invalid_arguments", err.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; "));
+        }
+        if (err instanceof ReviewHostError)
+            return error(err.code, err.message);
+        return error("host_api_error", "The host request failed.");
+    }
+}

package/dist/core/run-heartbeat.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Liveness for native runs that no executor watches: an attended
+ * `wardby run` and a native sub-agent child, which runs inline inside its
+ * parent's tool call. Managed runs already beat through their executor
+ * (InProcessExecutor, DbosExecutor). A beat is what keeps a run's budget
+ * hold counted against its budget group (budget-groups.ts isHoldLive): once a
+ * process dies and the beats stop, the hold lapses on its own instead of
+ * pinning the group for the rest of the period.
+ */
+import type { PrismaClient } from "#prisma";
+type RunDb = Pick<PrismaClient, "run">;
+/** Beats `runId` once now and every `intervalMs` until `fn` settles. */
+export declare function withRunHeartbeat<T>(db: RunDb, runId: string, fn: () => Promise<T>, intervalMs?: number): Promise<T>;
+/** The part of `process` an interrupt handler needs (a fake in tests). */
+export interface SignalTarget {
+    once(signal: NodeJS.Signals, listener: () => void): unknown;
+    off(signal: NodeJS.Signals, listener: () => void): unknown;
+    exit(code: number): never | void;
+}
+/**
+ * For an attended run: on SIGINT/SIGTERM, record the run as `cancelled`
+ * (only if it is still pending/running) and exit with the conventional
+ * 128+signal code, instead of leaving a `running` row behind. Returns a
+ * function that removes the handlers once the run has finished.
+ */
+export declare function cancelRunOnSignal(db: RunDb, runId: string, target?: SignalTarget): () => void;
+export {};

package/dist/core/run-heartbeat.js

@@ -0,0 +1,54 @@
+import { HEARTBEAT_INTERVAL_MS } from "./timing.js";
+async function beat(db, runId) {
+    try {
+        await db.run.updateMany({
+            where: { id: runId, status: { in: ["pending", "running"] } },
+            data: { heartbeatAt: new Date() },
+        });
+    }
+    catch {
+        // A missed beat only lets the hold lapse a little sooner; never fatal to the run.
+    }
+}
+/** Beats `runId` once now and every `intervalMs` until `fn` settles. */
+export async function withRunHeartbeat(db, runId, fn, intervalMs = HEARTBEAT_INTERVAL_MS) {
+    await beat(db, runId);
+    const timer = setInterval(() => void beat(db, runId), intervalMs);
+    timer.unref?.();
+    try {
+        return await fn();
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+const EXIT_CODES = { SIGINT: 130, SIGTERM: 143 };
+/**
+ * For an attended run: on SIGINT/SIGTERM, record the run as `cancelled`
+ * (only if it is still pending/running) and exit with the conventional
+ * 128+signal code, instead of leaving a `running` row behind. Returns a
+ * function that removes the handlers once the run has finished.
+ */
+export function cancelRunOnSignal(db, runId, target = process) {
+    const handlers = new Map();
+    const remove = () => {
+        for (const [signal, handler] of handlers)
+            target.off(signal, handler);
+        handlers.clear();
+    };
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        const handler = () => {
+            remove();
+            void db.run
+                .updateMany({
+                where: { id: runId, status: { in: ["pending", "running"] } },
+                data: { status: "cancelled", error: `Interrupted by ${signal}.`, finishedAt: new Date() },
+            })
+                .catch(() => undefined)
+                .finally(() => target.exit(EXIT_CODES[signal] ?? 1));
+        };
+        handlers.set(signal, handler);
+        target.once(signal, handler);
+    }
+    return remove;
+}

package/dist/core/runner.d.ts

@@ -16,17 +16,26 @@
  * down) lives inside the engine now — there is exactly one place that
  * reasons about cost, not one here plus one in the engine.
  */
-import type { PrismaClient, Run, RunTrigger } from "@prisma/client";
+import type { PrismaClient, Run, RunTrigger } from "#prisma";
 import type { ProviderRegistry } from "../providers/index.js";
 import { type StepRunner } from "../providers/engine/types.js";
 import type { Executor } from "../providers/executor/types.js";
+import type { ReviewHostRegistry } from "../providers/review-host/types.js";
+import { type RepoAccessGate } from "./repo-access.js";
 /**
  * The subset of the Prisma client the runner touches — mockable in tests.
  * Includes `codingRun`/`task`/`webhook`/`$transaction`/`$queryRaw` so this
  * also satisfies `dispatch.ts`'s `DispatchDb`, needed for dispatching a
  * coding-kind sub-agent from inside a running native turn loop.
  */
-export type RunnerDb = Pick<PrismaClient, "agent" | "run" | "agentTool" | "agentSecret" | "agentDatastore" | "budgetGroup" | "agentSubAgent" | "codingRun" | "task" | "webhook" | "$transaction" | "$queryRaw">;
+export type RunnerDb = Pick<PrismaClient, "agent" | "run" | "agentTool" | "agentSecret" | "agentDatastore" | "budgetGroup" | "agentSubAgent" | "resourceGrant" | "codingRun" | "task" | "webhook" | "$transaction" | "$queryRaw" | "agentRepository" | "runHostCheck" | "runHostStatus" | "hostIdentity">;
+/** The providers a native run needs; `executor` and `reviewHosts` are optional capabilities. */
+export type NativeRunProviders = Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory"> & {
+    executor?: ProviderRegistry["executor"];
+    reviewHosts?: ReviewHostRegistry;
+    /** Repository authorization for repo_* calls; built from reviewHosts when absent. */
+    repoAccess?: RepoAccessGate;
+};
 /**
  * Raised when a run's step boundary observed a cancellation (DbosExecutor's
  * `stop`). `executeRun`'s backstop persists these as `cancelled` with the
@@ -61,6 +70,19 @@ export interface WaitForCodingChildOptions {
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;
 }
+/**
+ * What a coding sub-agent's run tells the parent run's model. A run refused
+ * over its services carries the host sentence (never the raw Run.error), so
+ * the parent can pass it on — for a mention, that is the requester.
+ */
+export declare function codingChildResult(run: {
+    status: string;
+    finalText: string | null;
+    costUsd: unknown;
+    tokensIn: number;
+    tokensOut: number;
+    error: string | null;
+}): string;
 /**
  * Polls a dispatched coding child until it reaches a terminal status. Needed
  * because a queued child (every concurrency slot taken) makes Executor.start
@@ -78,10 +100,10 @@ export declare function waitForCodingChild(options: WaitForCodingChildOptions):
 /** Persists a new pending Run for the named agent. Throws if the agent is unknown. */
 export declare function createRun(db: RunnerDb, agentName: string, trigger?: RunTrigger): Promise<Run>;
 /** Drives an existing Run (created by `createRun` or the scheduler) to a terminal state. */
-export declare function executeRun(runId: string, providers: Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory"> & {
-    executor?: ProviderRegistry["executor"];
-}, db?: RunnerDb, onText?: (delta: string) => void, step?: StepRunner): Promise<Run>;
-/** Convenience: create + execute a manual run in one call (what the CLI's `wardby run` uses). */
-export declare function runAgent(agentName: string, providers: Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory"> & {
-    executor?: ProviderRegistry["executor"];
-}, db?: RunnerDb, onText?: (delta: string) => void): Promise<Run>;
+export declare function executeRun(runId: string, providers: NativeRunProviders, db?: RunnerDb, onText?: (delta: string) => void, step?: StepRunner): Promise<Run>;
+/**
+ * Convenience: create + execute a manual run in one call (what the CLI's
+ * `wardby run` uses). No executor watches it, so it beats itself; `onCreated`
+ * lets the caller hook the new run (the CLI cancels it on SIGINT/SIGTERM).
+ */
+export declare function runAgent(agentName: string, providers: NativeRunProviders, db?: RunnerDb, onText?: (delta: string) => void, onCreated?: (run: Run) => void): Promise<Run>;