@wardby/cli 0.4.1 → 0.5.1

package/dist/providers/vcs/remote.d.ts

@@ -0,0 +1,58 @@
+import type { FinalizeChangesDetails, PreparedWorkspace, VcsProvider } from "./types.js";
+/** What a remote needs to publish a pushed commit (GitHub: open or find the draft PR). */
+export interface PublishInput {
+    /** The validated workspace whose headRef was just pushed. */
+    workspace: PreparedWorkspace;
+    details?: FinalizeChangesDetails;
+    /** Every path the commit changes relative to baseCommit (already validated). */
+    changedPaths: readonly string[];
+}
+export type PublishResult = {
+    kind: "pull_request";
+    number: number;
+    url: string;
+} | {
+    kind: "branch";
+    branch: string;
+};
+/**
+ * The remote-specific half of GitVcsProvider: where a repository is cloned
+ * from and pushed to, how git authenticates, and what happens after a push.
+ * Everything else (workspace layout, hardened git config, finalize checks,
+ * fetch-compare-push) stays in GitVcsProvider and applies to every remote.
+ */
+export interface GitRemote {
+    /** Extra `-c` pairs appended after HARDENED_GIT_CONFIG for clone/push/ls-remote (GitHub: none). */
+    readonly gitConfig: readonly string[];
+    /** Syntactic normalization of a repository id for this remote (GitHub: owner/name; local: local:/abs/path). */
+    normalizeRepository(repository: string): string;
+    cloneUrl(repository: string): string;
+    /** Runs fn with an auth token for git (GitHub: installation token; local: undefined). */
+    withAccess<T>(repository: string, fn: (token: string | undefined) => Promise<T>): Promise<T>;
+    /** Continuation precondition (GitHub: the PR is still open). */
+    assertContinuationOpen(input: {
+        repository: string;
+        baseRef: string;
+        headRef: string;
+        continuation?: {
+            rootRunId: string;
+        };
+    }): Promise<void>;
+    /** After a successful push: GitHub opens or finds the draft PR; local returns the branch. */
+    publish(input: PublishInput): Promise<PublishResult>;
+    /** The error pushOnce throws when the remote branch moved since the clone. */
+    conflictError(): Error;
+    /**
+     * When set, prepareWorkspace runs `ls-remote --heads` for the branch it is
+     * about to clone and throws this error if the branch is absent, instead of
+     * leaving a missing ref to surface as an opaque clone failure (GitHub: unset).
+     */
+    refNotFoundError?(ref: string): Error;
+    /** When set, called with headRef before any push; throws to refuse writing that ref (GitHub: unset). */
+    assertPushRef?(headRef: string): void;
+    /** When set, called inside withAccess right before the push; throws to refuse it (GitHub: unset). */
+    beforePush?(repository: string, headRef: string): Promise<void>;
+    notifyContinuationStarted?: VcsProvider["notifyContinuationStarted"];
+    notifyContinuationFinished?: VcsProvider["notifyContinuationFinished"];
+    readRepositoryFile?: VcsProvider["readRepositoryFile"];
+}

package/dist/providers/vcs/remote.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/vcs/routing.d.ts

@@ -0,0 +1,33 @@
+import type { RepositoryFileInput } from "./github.js";
+import type { ContinuationFinishedDetails, ContinuationOutcome, FinalizeChangesDetails, FinalizeChangesResult, PreparedWorkspace, VcsPrepareInput, VcsProvider } from "./types.js";
+/** Keeps the `vcs_github_not_configured` code prefix that error matching and categorization key on. */
+export declare const VCS_GITHUB_NOT_CONFIGURED_ERROR = "vcs_github_not_configured: set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY to run coding agents on GitHub repositories";
+export interface RoutingVcsOptions {
+    /** Null when no GitHub App is configured. */
+    github: VcsProvider | null;
+    /** Null when no local repository roots are configured. */
+    local: VcsProvider | null;
+}
+/**
+ * One VcsProvider over both repository kinds: `local:/abs/path` goes to the
+ * local provider, everything else to GitHub. A kind that is not configured
+ * fails only when a repository of that kind is actually used, so a server with
+ * only one of the two still starts. The repository name is not re-resolved
+ * here: the local provider verifies it against the trusted roots.
+ */
+export declare class RoutingVcsProvider implements VcsProvider {
+    private readonly options;
+    constructor(options: RoutingVcsOptions);
+    private target;
+    /** The target when configured, else null (best-effort calls that must never throw). */
+    private optionalTarget;
+    prepareWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace>;
+    recoverWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace | null>;
+    finalizeChanges(workspace: PreparedWorkspace, details?: FinalizeChangesDetails): Promise<FinalizeChangesResult>;
+    cleanup(workspace: PreparedWorkspace): Promise<void>;
+    notifyContinuationStarted(workspace: PreparedWorkspace, details?: {
+        agentName?: string;
+    }): Promise<void>;
+    notifyContinuationFinished(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
+}

package/dist/providers/vcs/routing.js

@@ -0,0 +1,52 @@
+import { LocalRepoError, isLocalRepository } from "../../coding/local-repo.js";
+/** Keeps the `vcs_github_not_configured` code prefix that error matching and categorization key on. */
+export const VCS_GITHUB_NOT_CONFIGURED_ERROR = "vcs_github_not_configured: set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY to run coding agents on GitHub repositories";
+/**
+ * One VcsProvider over both repository kinds: `local:/abs/path` goes to the
+ * local provider, everything else to GitHub. A kind that is not configured
+ * fails only when a repository of that kind is actually used, so a server with
+ * only one of the two still starts. The repository name is not re-resolved
+ * here: the local provider verifies it against the trusted roots.
+ */
+export class RoutingVcsProvider {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    target(repository) {
+        if (isLocalRepository(repository)) {
+            if (!this.options.local) {
+                throw new LocalRepoError("local_repo_not_allowed", "no local repository roots are configured (LOCAL_REPO_ROOTS)");
+            }
+            return this.options.local;
+        }
+        if (!this.options.github)
+            throw new Error(VCS_GITHUB_NOT_CONFIGURED_ERROR);
+        return this.options.github;
+    }
+    /** The target when configured, else null (best-effort calls that must never throw). */
+    optionalTarget(repository) {
+        return (isLocalRepository(repository) ? this.options.local : this.options.github) ?? null;
+    }
+    async prepareWorkspace(input) {
+        return this.target(input.repository).prepareWorkspace(input);
+    }
+    async recoverWorkspace(input) {
+        return this.target(input.repository).recoverWorkspace(input);
+    }
+    async finalizeChanges(workspace, details) {
+        return this.target(workspace.repository).finalizeChanges(workspace, details);
+    }
+    async cleanup(workspace) {
+        return this.target(workspace.repository).cleanup(workspace);
+    }
+    async notifyContinuationStarted(workspace, details) {
+        await this.optionalTarget(workspace.repository)?.notifyContinuationStarted?.(workspace, details);
+    }
+    async notifyContinuationFinished(workspace, outcome, details) {
+        await this.optionalTarget(workspace.repository)?.notifyContinuationFinished?.(workspace, outcome, details);
+    }
+    async readRepositoryFile(input) {
+        return (await this.optionalTarget(input.repository)?.readRepositoryFile?.(input)) ?? null;
+    }
+}

package/dist/providers/vcs/types.d.ts

@@ -1,4 +1,4 @@
-import type { RepositoryFileInput } from "./github.js";
+import type { RelatedPullRequestsInput, RepositoryFileInput } from "./github.js";
 export interface VcsPrepareInput {
     runId: string;
     repository: string;
@@ -71,6 +71,8 @@ export interface FinalizeChangesDetails {
         url?: string;
         trackerName?: string;
     };
+    /** The request's other pull requests (control-plane rows): the PR body's Related pull requests section. */
+    related?: RelatedPullRequestsInput;
 }
 export type FinalizeChangesResult = {
     outcome: "no_changes";
@@ -97,6 +99,15 @@ export type FinalizeChangesResult = {
     commitSha: string;
     pullRequestNumber: number;
     pullRequestUrl: string;
+} | {
+    /** Pushed the run's branch to a remote with no pull requests (a local
+     * repository): headRef now points at commitSha there. */
+    outcome: "branch_pushed";
+    repository: string;
+    baseRef: string;
+    baseCommit: string;
+    headRef: string;
+    commitSha: string;
 };
 export interface VcsProvider {
     prepareWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace>;

package/dist/quickstart/coding-db.d.ts

@@ -0,0 +1,11 @@
+import type { DeclaredService } from "../coding/services/declaration.js";
+import type { LocalAgent } from "./coding-doctor.js";
+import { type CodingSeedInput, type CodingSeedResult } from "./coding-seed.js";
+import { type QuickstartPaths } from "./config.js";
+export declare function prismaSeedCodingAgents(paths: QuickstartPaths, input: Omit<CodingSeedInput, "ownerId">): Promise<CodingSeedResult>;
+export declare function prismaCatalogImages(paths: QuickstartPaths, services: DeclaredService[]): Promise<Array<{
+    service: DeclaredService;
+    image?: string;
+}>>;
+/** Coding agents with a local repository, and native agents with a local link. */
+export declare function prismaLocalAgents(paths: QuickstartPaths): Promise<LocalAgent[]>;

package/dist/quickstart/coding-db.js

@@ -0,0 +1,75 @@
+import { LOCAL_REPO_PREFIX } from "../coding/local-repo.js";
+import { seedCodingAgents } from "./coding-seed.js";
+import { readQuickstartEnv } from "./config.js";
+async function withDb(paths, use) {
+    const { createPrismaClient } = await import("../core/db.js");
+    const env = readQuickstartEnv(paths);
+    const db = createPrismaClient(env.DATABASE_URL);
+    try {
+        return await use(db, env);
+    }
+    finally {
+        await db.$disconnect();
+    }
+}
+function seedDb(db) {
+    return {
+        findAgent: (name) => db.agent.findUnique({ where: { name }, select: { id: true, kind: true, systemPrompt: true } }),
+        createAgent: (data) => db.agent.create({ data, select: { id: true } }),
+        updateAgent: async (id, data) => {
+            await db.agent.update({ where: { id }, data });
+        },
+        upsertCodingProfile: async (agentId, profile) => {
+            const fields = profile;
+            await db.codingAgentProfile.upsert({ where: { agentId }, create: { agentId, ...fields }, update: fields });
+        },
+        upsertLocalLink: async (agentId, link) => {
+            const fields = { access: link.access, triggers: [], checkName: null, ...link.stamp };
+            await db.agentRepository.upsert({
+                where: { agentId_provider_repository: { agentId, provider: "local", repository: link.repository } },
+                create: { agentId, provider: "local", repository: link.repository, ...fields },
+                update: fields,
+            });
+        },
+    };
+}
+export async function prismaSeedCodingAgents(paths, input) {
+    const { resolvePrincipal } = await import("../mcp/auth/principal.js");
+    return await withDb(paths, async (db, env) => {
+        const owner = await resolvePrincipal(env.LOCAL_PRINCIPAL || "local", db);
+        return await seedCodingAgents(seedDb(db), { ...input, ownerId: owner.id });
+    });
+}
+export async function prismaCatalogImages(paths, services) {
+    if (services.length === 0)
+        return [];
+    return await withDb(paths, async (db) => {
+        const rows = await db.codingService.findMany({
+            where: { OR: services.map(({ name, version }) => ({ name, version })) },
+            select: { name: true, version: true, image: true },
+        });
+        return services.map((service) => ({
+            service,
+            image: rows.find((row) => row.name === service.name && row.version === service.version)?.image,
+        }));
+    });
+}
+/** Coding agents with a local repository, and native agents with a local link. */
+export async function prismaLocalAgents(paths) {
+    return await withDb(paths, async (db) => {
+        const [coding, links] = await Promise.all([
+            db.codingAgentProfile.findMany({
+                where: { repository: { startsWith: LOCAL_REPO_PREFIX } },
+                select: { repository: true, baseRef: true, agent: { select: { name: true } } },
+            }),
+            db.agentRepository.findMany({
+                where: { provider: "local" },
+                select: { repository: true, agent: { select: { name: true } } },
+            }),
+        ]);
+        return [
+            ...coding.map((row) => ({ name: row.agent.name, repository: row.repository, ref: row.baseRef })),
+            ...links.map((row) => ({ name: row.agent.name, repository: row.repository })),
+        ].sort((a, b) => a.name.localeCompare(b.name));
+    });
+}

package/dist/quickstart/coding-doctor.d.ts

@@ -0,0 +1,13 @@
+import { type RunCommand } from "./coding.js";
+export interface LocalAgent {
+    name: string;
+    /** `local:/abs/path`. */
+    repository: string;
+    /** The branch whose services.yaml applies (a coding agent's baseRef); default: the checked-out branch. */
+    ref?: string;
+}
+export interface CodingDoctorDeps {
+    run: RunCommand;
+    listLocalAgents: () => Promise<LocalAgent[]>;
+}
+export declare function codingDoctorLines(env: Record<string, string | undefined>, deps: CodingDoctorDeps): Promise<string[]>;

package/dist/quickstart/coding-doctor.js

@@ -0,0 +1,88 @@
+/**
+ * The coding section of `wardby doctor` / `wardby status` for a quickstart
+ * project: trusted folders, the worker image, the coding proxy, and for each
+ * agent with a local repository whether it is inside the trusted folders and
+ * what its committed `.wardby/services.yaml` declares. Lines start with ✓ or ✗
+ * like the rest of doctor's output; an empty list means the coding step was
+ * never configured.
+ */
+import { LOCAL_REPO_PREFIX, LocalRepoError, loadLocalRepoRoots, resolveLocalRepository } from "../coding/local-repo.js";
+import { imageVariable } from "../config/providers.js";
+import { isImmutableDockerImage } from "../providers/jobs/docker-isolation.js";
+import { CODING_PROXY_CONTAINER } from "./coding.js";
+import { inspectDeclaredServices, repoDefaultBranch } from "./starter-services.js";
+const ok = (name, detail) => `✓ ${name}${detail ? ` (${detail})` : ""}`;
+const bad = (name, detail) => `✗ ${name}${detail ? ` (${detail})` : ""}`;
+async function agentLines(agent, roots) {
+    let path;
+    try {
+        path = (await resolveLocalRepository(agent.repository, roots)).path;
+    }
+    catch (error) {
+        const message = error instanceof LocalRepoError ? error.message : String(error);
+        return [`✗ ${agent.name}: ${message}`];
+    }
+    const lines = [`✓ ${agent.name}: ${path} is inside the trusted folders`];
+    const ref = agent.ref ?? (await repoDefaultBranch(path))?.branch;
+    if (!ref)
+        return [...lines, `✗ ${agent.name}: ${path} has no checked-out branch with commits`];
+    const declared = await inspectDeclaredServices(path, roots, ref);
+    if (declared.kind === "absent")
+        lines.push(`✓ ${agent.name}: no .wardby/services.yaml on ${ref} (no services)`);
+    else if (declared.kind === "invalid") {
+        lines.push(`✗ ${agent.name}: .wardby/services.yaml on ${ref} is invalid: ${declared.reason}`);
+    }
+    else {
+        const list = declared.services.map((service) => `${service.name} ${service.version}`).join(", ");
+        lines.push(`✓ ${agent.name}: .wardby/services.yaml on ${ref} declares ${list || "no services"}`);
+    }
+    return lines;
+}
+export async function codingDoctorLines(env, deps) {
+    if (!env.LOCAL_REPO_ROOTS && env.JOB_LAUNCHER !== "docker")
+        return [];
+    const lines = [];
+    const { roots, missing } = loadLocalRepoRoots({ LOCAL_REPO_ROOTS: env.LOCAL_REPO_ROOTS });
+    for (const root of roots)
+        lines.push(ok(`Trusted folder ${root}`));
+    for (const root of missing)
+        lines.push(bad(`Trusted folder ${root}`, "does not exist"));
+    if (roots.length === 0 && missing.length === 0)
+        lines.push(bad("Trusted folders", "LOCAL_REPO_ROOTS is empty"));
+    // Each provider's images are optional (Codex: CODING_WORKER_IMAGE; Claude Code: its pair); check what is set.
+    // Blank is unset, as the server reads it (imageVariable).
+    const codexSet = Boolean(imageVariable(env.CODING_WORKER_IMAGE));
+    const claudeSet = Boolean(imageVariable(env.CODING_CLAUDE_WORKER_IMAGE) || imageVariable(env.CODING_CLAUDE_TOOL_RUNNER_IMAGE));
+    const checkImage = (label, name) => {
+        const image = imageVariable(env[name]);
+        if (!image)
+            lines.push(bad(label, `${name} is not set`));
+        else if (!isImmutableDockerImage(image))
+            lines.push(bad(label, `${name} must be an immutable digest or image id`));
+        else if (deps.run("docker", ["image", "inspect", image]).status !== 0) {
+            lines.push(bad(label, "Docker cannot inspect it; re-run quickstart"));
+        }
+        else
+            lines.push(ok(label));
+    };
+    if (codexSet)
+        checkImage("Coding worker image", "CODING_WORKER_IMAGE");
+    if (claudeSet) {
+        checkImage("Claude Code worker image", "CODING_CLAUDE_WORKER_IMAGE");
+        checkImage("Claude Code tool runner image", "CODING_CLAUDE_TOOL_RUNNER_IMAGE");
+    }
+    if (!codexSet && !claudeSet) {
+        lines.push(bad("Coding worker image", "set CODING_WORKER_IMAGE for Codex, or CODING_CLAUDE_WORKER_IMAGE and CODING_CLAUDE_TOOL_RUNNER_IMAGE for Claude Code"));
+    }
+    const proxy = deps.run("docker", ["inspect", "--format", "{{.State.Running}}", CODING_PROXY_CONTAINER]);
+    const running = proxy.status === 0 && proxy.stdout.trim() === "true";
+    lines.push(running
+        ? ok(`Coding proxy container (${CODING_PROXY_CONTAINER})`)
+        : bad(`Coding proxy container (${CODING_PROXY_CONTAINER})`, "not running"));
+    for (const agent of await deps.listLocalAgents()) {
+        if (!agent.repository.startsWith(LOCAL_REPO_PREFIX))
+            continue;
+        lines.push(...(await agentLines(agent, roots)));
+    }
+    return lines;
+}

package/dist/quickstart/coding-images.d.ts

@@ -0,0 +1,15 @@
+import type { CodingProvider } from "../coding/provider.js";
+import type { CodingDeps } from "./coding.js";
+/** Stops the optional coding step with a message; the rest of quickstart carries on. */
+export declare class CodingSkip extends Error {
+}
+export interface PreparedImages {
+    runtime: string;
+    /** The Codex worker; only for codex. */
+    worker?: string;
+    /** Claude Code's worker and tool runner; only for claude-code. */
+    claudeWorker?: string;
+    claudeToolRunner?: string;
+}
+/** Only the chosen provider's images: a Claude-only setup never builds or pulls the Codex worker. */
+export declare function prepareImages(provider: CodingProvider, config: Record<string, string>, deps: CodingDeps): PreparedImages;

package/dist/quickstart/coding-images.js

@@ -0,0 +1,79 @@
+/**
+ * The coding step's images: the wardby runtime (coding proxy) plus the chosen
+ * provider's own images -- the Codex worker, or Claude Code's worker and tool
+ * runner. Pulled by digest from a release, or built from a source checkout
+ * and pinned by local image id (the Docker launcher refuses mutable tags).
+ */
+import { join } from "node:path";
+import { isImmutableDockerImage } from "../providers/jobs/docker-isolation.js";
+import { resolveQuickstartImages } from "./images.js";
+/** Stops the optional coding step with a message; the rest of quickstart carries on. */
+export class CodingSkip extends Error {
+}
+function imageId(deps, tag) {
+    const inspected = deps.run("docker", ["image", "inspect", "--format", "{{.Id}}", tag]);
+    const id = inspected.stdout.trim();
+    if (inspected.status !== 0 || !isImmutableDockerImage(id))
+        throw new CodingSkip(`could not read the image id of ${tag}`);
+    return id;
+}
+function build(deps, dockerfile, tag, target) {
+    deps.log(`Building ${tag} (this can take a few minutes the first time)...`);
+    const args = ["build", "--file", join(deps.packageRoot, dockerfile), ...(target ? ["--target", target] : [])];
+    const result = deps.run("docker", [...args, "--tag", tag, deps.packageRoot], { inherit: true });
+    if (result.status !== 0)
+        throw new CodingSkip(`docker build of ${tag} failed`);
+}
+/** Pulls `image`; an image that cannot be pulled is fine if Docker already has it (e.g. a local image id). */
+function pullOrPresent(deps, image) {
+    if (deps.run("docker", ["pull", image], { inherit: true }).status === 0)
+        return;
+    if (deps.run("docker", ["image", "inspect", image]).status === 0)
+        return;
+    throw new CodingSkip(`could not pull ${image}`);
+}
+/** Only the chosen provider's images: a Claude-only setup never builds or pulls the Codex worker. */
+export function prepareImages(provider, config, deps) {
+    const resolved = resolveQuickstartImages({ env: deps.env, packageRoot: deps.packageRoot });
+    if ("unavailable" in resolved)
+        throw new CodingSkip(resolved.unavailable);
+    if (resolved.source === "build") {
+        build(deps, "deploy/Dockerfile", resolved.runtime, "runtime");
+        if (provider !== "claude-code") {
+            build(deps, "src/coding-worker/Dockerfile", resolved.worker);
+            return { runtime: resolved.runtime, worker: imageId(deps, resolved.worker) };
+        }
+        const claudeWorker = resolved.claudeWorker ?? "wardby-claude-coding-worker:local";
+        const claudeToolRunner = resolved.claudeToolRunner ?? "wardby-claude-tool-runner:local";
+        build(deps, "src/claude-coding-worker/Dockerfile", claudeWorker);
+        build(deps, "src/claude-tool-runner/Dockerfile", claudeToolRunner);
+        return {
+            runtime: resolved.runtime,
+            claudeWorker: imageId(deps, claudeWorker),
+            claudeToolRunner: imageId(deps, claudeToolRunner),
+        };
+    }
+    let images;
+    if (provider !== "claude-code") {
+        if (!isImmutableDockerImage(resolved.worker)) {
+            throw new CodingSkip("CODING_WORKER_IMAGE must be an immutable digest (repo@sha256:...) or local image id");
+        }
+        images = { runtime: resolved.runtime, worker: resolved.worker };
+    }
+    else {
+        const claudeWorker = resolved.claudeWorker || config.CODING_CLAUDE_WORKER_IMAGE;
+        const claudeToolRunner = resolved.claudeToolRunner || config.CODING_CLAUDE_TOOL_RUNNER_IMAGE;
+        if (!claudeWorker || !claudeToolRunner) {
+            throw new CodingSkip("Claude Code images aren't available: set both CODING_CLAUDE_WORKER_IMAGE and CODING_CLAUDE_TOOL_RUNNER_IMAGE, upgrade to a release that publishes them, or run from a wardby source checkout");
+        }
+        if (!isImmutableDockerImage(claudeWorker) || !isImmutableDockerImage(claudeToolRunner)) {
+            throw new CodingSkip("CODING_CLAUDE_WORKER_IMAGE and CODING_CLAUDE_TOOL_RUNNER_IMAGE must be immutable digests (repo@sha256:...) or local image ids");
+        }
+        images = { runtime: resolved.runtime, claudeWorker, claudeToolRunner };
+    }
+    for (const image of [images.runtime, images.worker, images.claudeWorker, images.claudeToolRunner]) {
+        if (image)
+            pullOrPresent(deps, image);
+    }
+    return images;
+}

package/dist/quickstart/coding-seed.d.ts

@@ -0,0 +1,63 @@
+import { type CodingProvider } from "../coding/provider.js";
+export declare const BUILDER_AGENT = "local-builder";
+export declare const REVIEWER_AGENT = "local-reviewer";
+export declare const BUILDER_PROMPT = "You are the Wardby quickstart coding agent, working in a local git repository. Make the smallest change that completes the task, follow the repository's existing style, add or update tests when behavior changes, and run the tests before you finish. End with a short summary of what you changed and how you verified it.";
+export declare const REVIEWER_PROMPT: string;
+/** The database operations seeding needs; the default implementation is Prisma (quickstart/coding.ts). */
+export interface SeedDb {
+    findAgent(name: string): Promise<{
+        id: string;
+        kind: string;
+        systemPrompt: string;
+    } | null>;
+    createAgent(data: AgentData): Promise<{
+        id: string;
+    }>;
+    updateAgent(id: string, data: Partial<AgentData>): Promise<void>;
+    upsertCodingProfile(agentId: string, profile: Record<string, unknown>): Promise<void>;
+    upsertLocalLink(agentId: string, link: {
+        repository: string;
+        access: "write";
+        stamp: Stamp;
+    }): Promise<void>;
+}
+export interface AgentData {
+    name: string;
+    kind: "native" | "coding";
+    model: string;
+    budgetUsd: number;
+    systemPrompt: string;
+    maxTurns: number;
+    ownerId: string;
+}
+interface Stamp {
+    authorizedVia: "local_root";
+    authorizedById: string;
+    authorizedAt: Date;
+}
+export interface CodingSeedInput {
+    ownerId: string;
+    provider: CodingProvider;
+    /** The coding agent's model; must be one the coding provider supports. */
+    builderModel: string;
+    /** The native reviewer's model (the quickstart's own provider). */
+    reviewerModel: string;
+    /** Canonical `local:/realpath`, already checked against the trusted roots. */
+    repository: string;
+    baseRef: string;
+    /** Catalog service names the builder's runs may start. */
+    services: string[];
+}
+export type SeedOutcome = {
+    id: string;
+    status: "created" | "updated";
+} | {
+    status: "skipped";
+    reason: string;
+};
+export interface CodingSeedResult {
+    builder: SeedOutcome;
+    reviewer: SeedOutcome;
+}
+export declare function seedCodingAgents(db: SeedDb, input: CodingSeedInput, now?: Date): Promise<CodingSeedResult>;
+export {};

package/dist/quickstart/coding-seed.js

@@ -0,0 +1,85 @@
+/**
+ * Seeds the quickstart's two local-repository agents, idempotently:
+ * `local-builder` (a coding agent whose repository is a trusted local folder)
+ * and `local-reviewer` (a native agent with a write `local` link, so it can
+ * publish reviews of the builder's branches). Re-running updates them in
+ * place; an agent of the same name that quickstart did not create is left
+ * alone. Writes go straight to the database, like seedDemo, with the same
+ * authorization stamp the MCP tools give a local repository ("local_root").
+ */
+import { CodingProfileSchema } from "../coding/profile.js";
+import { codingProviderSupportsModel } from "../coding/provider.js";
+export const BUILDER_AGENT = "local-builder";
+export const REVIEWER_AGENT = "local-reviewer";
+const BUILDER_BUDGET_USD = 2;
+const REVIEWER_BUDGET_USD = 1;
+const REVIEWER_MAX_TURNS = 12;
+export const BUILDER_PROMPT = "You are the Wardby quickstart coding agent, working in a local git repository. Make the smallest change that completes the task, follow the repository's existing style, add or update tests when behavior changes, and run the tests before you finish. End with a short summary of what you changed and how you verified it.";
+export const REVIEWER_PROMPT = [
+    "You are the Wardby quickstart review agent. Your task names one pull request: its number, its repository (local:/path), and its head commit.",
+    "1. Call repo_pr_read with that repository and prNumber to get the description and the diff.",
+    "2. When a change needs more context, read the surrounding code with repo_read_file at the head commit (repo_list_files lists what exists).",
+    "3. Look for correctness bugs, missing or weak tests, security problems, and confusing code. Skip style a formatter would fix.",
+    "4. Call repo_publish_review exactly once with the head commit, a verdict (APPROVE when nothing needs to change, CHANGES_REQUESTED for real defects, COMMENT otherwise), a one-line summary, a markdown body, and inline comments on changed lines, each with a severity (CRITICAL, MAJOR, MINOR, NIT).",
+    "If repo_publish_review returns stale_head, stop: the branch moved on.",
+].join("\n");
+async function upsertAgent(db, data) {
+    const existing = await db.findAgent(data.name);
+    if (existing && (existing.systemPrompt !== data.systemPrompt || existing.kind !== data.kind)) {
+        return {
+            status: "skipped",
+            reason: `an agent named "${data.name}" already exists and was not created by quickstart; it was left unchanged`,
+        };
+    }
+    if (existing) {
+        const { name: _name, systemPrompt: _prompt, kind: _kind, ownerId: _owner, ...changes } = data;
+        await db.updateAgent(existing.id, changes);
+        return { id: existing.id, status: "updated" };
+    }
+    const created = await db.createAgent(data);
+    return { id: created.id, status: "created" };
+}
+export async function seedCodingAgents(db, input, now = new Date()) {
+    if (!codingProviderSupportsModel(input.provider, input.builderModel)) {
+        throw new Error(`Model "${input.builderModel}" is not supported by coding provider "${input.provider}".`);
+    }
+    const stamp = { authorizedVia: "local_root", authorizedById: input.ownerId, authorizedAt: now };
+    // Parsed for its defaults and validation, exactly as create_agent would store it.
+    const profile = CodingProfileSchema.parse({
+        provider: input.provider,
+        repository: input.repository,
+        baseRef: input.baseRef,
+        services: input.services,
+    });
+    const builder = await upsertAgent(db, {
+        name: BUILDER_AGENT,
+        kind: "coding",
+        model: input.builderModel,
+        budgetUsd: BUILDER_BUDGET_USD,
+        systemPrompt: BUILDER_PROMPT,
+        maxTurns: 10,
+        ownerId: input.ownerId,
+    });
+    if (builder.status !== "skipped") {
+        await db.upsertCodingProfile(builder.id, {
+            ...profile,
+            repositoryAuthorizedVia: stamp.authorizedVia,
+            repositoryAuthorizedById: stamp.authorizedById,
+            repositoryAuthorizedAt: stamp.authorizedAt,
+        });
+    }
+    const reviewer = await upsertAgent(db, {
+        name: REVIEWER_AGENT,
+        kind: "native",
+        model: input.reviewerModel,
+        budgetUsd: REVIEWER_BUDGET_USD,
+        systemPrompt: REVIEWER_PROMPT,
+        maxTurns: REVIEWER_MAX_TURNS,
+        ownerId: input.ownerId,
+    });
+    if (reviewer.status !== "skipped") {
+        // Write access: repo_publish_review is a write tool on the link.
+        await db.upsertLocalLink(reviewer.id, { repository: profile.repository, access: "write", stamp });
+    }
+    return { builder, reviewer };
+}