@valescoagency/runway 0.14.3 → 0.15.0

package/dist/github.js

@@ -18,6 +18,12 @@ export class PrCreateFailed extends Data.TaggedError("PrCreateFailed") {
 // be running. We accept that limitation for Step 2.
 export class GithubTimeout extends Data.TaggedError("GithubTimeout") {
 }
+// VA-461: read failures (gh pr view / git merge-tree). Kept distinct
+// from PushFailed / PrCreateFailed because the recovery is different
+// — a read failure on the shepherd's poll is recoverable (try again
+// next tick); a push or pr-create failure interrupts the workflow.
+export class GithubReadFailed extends Data.TaggedError("GithubReadFailed") {
+}
 // VA-357: same jittered exponential shape as the Linear policy.
 export const githubRetrySchedule = Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(5)), Schedule.jittered);
 /**
@@ -145,5 +151,349 @@ export function createGithubGateway() {
                 // and a retry would create a duplicate.
             });
         },
+        getPullRequest({ repoPath, prNumber }) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    const { stdout } = await execa("gh", [
+                        "pr",
+                        "view",
+                        String(prNumber),
+                        "--json",
+                        "number,mergeable,mergeStateStatus,merged,headRefOid,headRefName,baseRefName",
+                    ], { cwd: repoPath });
+                    const parsed = JSON.parse(stdout);
+                    // `mergeStateStatus` is the v4 enum runway maps to its
+                    // own `MergeableState`. gh returns it ALL_CAPS; runway
+                    // canonicalises to lowercase. Anything we don't
+                    // recognise becomes `unknown` rather than throwing — the
+                    // shepherd loop treats unknown as quiet, which is the
+                    // safe fallback.
+                    const mergeableState = canonicaliseMergeableState(parsed.mergeStateStatus);
+                    return {
+                        number: parsed.number,
+                        mergeableState,
+                        merged: parsed.merged,
+                        headSha: parsed.headRefOid,
+                        headRefName: parsed.headRefName,
+                        baseRefName: parsed.baseRefName,
+                    };
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `gh CLI not found on PATH (${err instanceof Error ? err.message : String(err)})`,
+                        });
+                    }
+                    return new GithubReadFailed({
+                        call: `getPullRequest(${prNumber})`,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `gh pr view failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `getPullRequest(${prNumber})`,
+                timeoutMs: 15_000,
+                retryOn: (err) => err._tag === "GithubTimeout",
+            });
+        },
+        getCheckRuns({ repoPath, sha }) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    const { stdout } = await execa("gh", [
+                        "api",
+                        `repos/{owner}/{repo}/commits/${sha}/check-runs`,
+                        "--paginate",
+                        "--jq",
+                        ".check_runs[] | {id, name, status, conclusion, run_id: (.details_url | capture(\"/runs/(?<id>[0-9]+)\") | .id | tonumber? // null)}",
+                    ], { cwd: repoPath });
+                    // `--jq` with the streaming form returns one JSON object
+                    // per line. Empty stdout → no check runs yet.
+                    const lines = stdout.split("\n").filter((s) => s.trim().length > 0);
+                    return lines.map((line) => {
+                        const o = JSON.parse(line);
+                        return {
+                            id: o.id,
+                            name: o.name,
+                            status: canonicaliseCheckStatus(o.status),
+                            conclusion: canonicaliseCheckConclusion(o.conclusion),
+                            runId: typeof o.run_id === "number" ? o.run_id : null,
+                        };
+                    });
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `gh CLI not found on PATH (${err instanceof Error ? err.message : String(err)})`,
+                        });
+                    }
+                    return new GithubReadFailed({
+                        call: `getCheckRuns(${sha})`,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `gh api check-runs failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `getCheckRuns(${sha})`,
+                timeoutMs: 15_000,
+                retryOn: (err) => err._tag === "GithubTimeout",
+            });
+        },
+        getRequiredChecks({ repoPath, baseBranch }) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    try {
+                        const { stdout } = await execa("gh", [
+                            "api",
+                            `repos/{owner}/{repo}/branches/${baseBranch}/protection/required_status_checks`,
+                            "--jq",
+                            ".contexts // []",
+                        ], { cwd: repoPath });
+                        const trimmed = stdout.trim();
+                        if (!trimmed)
+                            return null;
+                        const parsed = JSON.parse(trimmed);
+                        return parsed;
+                    }
+                    catch (err) {
+                        // 404 (branch not protected) and 403 (no admin) are
+                        // both expected — fall back to "filter unknown" by
+                        // returning null. The watcher treats null as
+                        // "conservatively require all checks" so a missing
+                        // protection rule can't silently hide failures.
+                        const stderr = execaStderr(err);
+                        if (stderr.includes("404") ||
+                            stderr.includes("403") ||
+                            stderr.includes("Branch not protected")) {
+                            return null;
+                        }
+                        throw err;
+                    }
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `gh CLI not found on PATH (${err instanceof Error ? err.message : String(err)})`,
+                        });
+                    }
+                    return new GithubReadFailed({
+                        call: `getRequiredChecks(${baseBranch})`,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `gh api branch-protection failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `getRequiredChecks(${baseBranch})`,
+                timeoutMs: 15_000,
+                retryOn: (err) => err._tag === "GithubTimeout",
+            });
+        },
+        getCheckRunLogTail({ repoPath, runId, lines }) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    try {
+                        // `gh run view <id> --log-failed` is the supported way
+                        // to fetch only the failed-step logs of an Actions run.
+                        // Non-Actions checks have no runId and don't reach this
+                        // path; the gateway caller maps `runId === null` to an
+                        // empty tail upstream.
+                        const { stdout } = await execa("gh", ["run", "view", String(runId), "--log-failed"], { cwd: repoPath });
+                        const all = stdout.split("\n");
+                        if (all.length <= lines)
+                            return stdout;
+                        return all.slice(-lines).join("\n");
+                    }
+                    catch (err) {
+                        const stderr = execaStderr(err);
+                        // 404 (run gone) or "no logs" → empty tail rather than
+                        // throwing; the agent gets the check name only.
+                        if (stderr.includes("404") ||
+                            stderr.includes("no logs") ||
+                            stderr.includes("expired")) {
+                            return "";
+                        }
+                        throw err;
+                    }
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `gh CLI not found on PATH (${err instanceof Error ? err.message : String(err)})`,
+                        });
+                    }
+                    return new GithubReadFailed({
+                        call: `getCheckRunLogTail(${runId})`,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `gh run view failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `getCheckRunLogTail(${runId})`,
+                timeoutMs: 30_000,
+                retryOn: (err) => err._tag === "GithubTimeout",
+            });
+        },
+        getPullRequestComments({ repoPath, prNumber }) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    // Three endpoints, three flavors of comment. We fetch
+                    // them in parallel and merge by createdAt — keeping
+                    // source labels so the watcher knows where each one
+                    // came from if it ever needs to round-trip a reply.
+                    const fetchJson = async (path, jq) => {
+                        const { stdout } = await execa("gh", ["api", path, "--paginate", "--jq", jq], { cwd: repoPath });
+                        const lines = stdout
+                            .split("\n")
+                            .filter((s) => s.trim().length > 0);
+                        return lines.map((line) => JSON.parse(line));
+                    };
+                    const projection = ".[] | {id, body, login: (.user.login // \"\"), created_at}";
+                    const [issueComments, reviewComments, reviewSummaries] = await Promise.all([
+                        fetchJson(`repos/{owner}/{repo}/issues/${prNumber}/comments`, projection),
+                        fetchJson(`repos/{owner}/{repo}/pulls/${prNumber}/comments`, projection),
+                        // Review summaries omit empty bodies (a review can be
+                        // submitted with no top-level body — only inline
+                        // comments). The `select(.body != "")` filter drops
+                        // those so they don't show up as ghost entries.
+                        fetchJson(`repos/{owner}/{repo}/pulls/${prNumber}/reviews`, ".[] | select(.body != \"\" and .body != null) | {id, body, login: (.user.login // \"\"), submitted_at}"),
+                    ]);
+                    const norm = (o, source, tsField) => ({
+                        id: Number(o.id ?? 0),
+                        authorLogin: String(o.login ?? ""),
+                        body: String(o.body ?? ""),
+                        createdAtUnixSeconds: Math.floor(new Date(String(o[tsField] ?? 0)).getTime() / 1000),
+                        source,
+                    });
+                    const merged = [
+                        ...issueComments.map((c) => norm(c, "issue", "created_at")),
+                        ...reviewComments.map((c) => norm(c, "review", "created_at")),
+                        ...reviewSummaries.map((c) => norm(c, "review-summary", "submitted_at")),
+                    ];
+                    merged.sort((a, b) => a.createdAtUnixSeconds - b.createdAtUnixSeconds);
+                    return merged;
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `gh CLI not found on PATH (${err instanceof Error ? err.message : String(err)})`,
+                        });
+                    }
+                    return new GithubReadFailed({
+                        call: `getPullRequestComments(${prNumber})`,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `gh api comments failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `getPullRequestComments(${prNumber})`,
+                timeoutMs: 30_000,
+                retryOn: (err) => err._tag === "GithubTimeout",
+            });
+        },
+        getConflictFiles({ repoPath, baseBranch, branch }) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    // Step 1: refresh origin/<base> so the merge-tree below
+                    // reasons about the latest remote state, not whatever
+                    // the cwd happened to have fetched last.
+                    await execa("git", ["fetch", "origin", baseBranch], {
+                        cwd: repoPath,
+                    });
+                    // Step 2: simulate the merge. `git merge-tree --name-only`
+                    // (git >= 2.38) prints only the conflicted paths, one per
+                    // line, on stdout. Exit code is non-zero when there ARE
+                    // conflicts, so we read stdout regardless of status.
+                    const result = await execa("git", [
+                        "merge-tree",
+                        "--name-only",
+                        "--no-messages",
+                        `origin/${baseBranch}`,
+                        branch,
+                    ], { cwd: repoPath, reject: false });
+                    const files = result.stdout
+                        .split("\n")
+                        .map((s) => s.trim())
+                        .filter(Boolean);
+                    return files;
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `git not found on PATH (${err instanceof Error ? err.message : String(err)})`,
+                        });
+                    }
+                    return new GithubReadFailed({
+                        call: `getConflictFiles(${branch}→${baseBranch})`,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `git merge-tree failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `getConflictFiles(${branch})`,
+                timeoutMs: 30_000,
+                retryOn: (err) => err._tag === "GithubTimeout",
+            });
+        },
     };
 }
+function canonicaliseCheckStatus(raw) {
+    switch (raw.toLowerCase()) {
+        case "queued":
+            return "queued";
+        case "in_progress":
+            return "in_progress";
+        case "completed":
+            return "completed";
+        default:
+            // Unknown status — treat as queued so the watcher waits for a
+            // final conclusion rather than acting on intermediate state.
+            return "queued";
+    }
+}
+function canonicaliseCheckConclusion(raw) {
+    if (raw === null)
+        return null;
+    switch (raw.toLowerCase()) {
+        case "success":
+        case "failure":
+        case "cancelled":
+        case "timed_out":
+        case "neutral":
+        case "skipped":
+        case "action_required":
+        case "stale":
+        case "startup_failure":
+            return raw.toLowerCase();
+        default:
+            return null;
+    }
+}
+function canonicaliseMergeableState(raw) {
+    switch (raw.toLowerCase()) {
+        case "clean":
+            return "clean";
+        case "dirty":
+            return "dirty";
+        case "behind":
+            return "behind";
+        case "blocked":
+            return "blocked";
+        case "unstable":
+            return "unstable";
+        case "draft":
+            return "draft";
+        default:
+            return "unknown";
+    }
+}

package/dist/orchestrator.js

@@ -7,6 +7,7 @@ import { flagHitl, handleProcessFailure } from "./hitl.js";
 import { runImplementLoop } from "./implement.js";
 import { formatInRunReviewerFeedback, formatPriorFeedback, } from "./prompts.js";
 import { runReviewPass } from "./review.js";
+import { makeCiWatcher, makeIsMerged, makeMergeabilityWatcher, makeReviewerWatcher, runShepherdPass, } from "./shepherd.js";
 import { finalize, formatRebaseConflictReason, formatRebaseFailureReason, } from "./finalize.js";
 // Re-exports so existing callers (commands/run.ts) and tests
 // (orchestrator.test.ts) keep working without import churn. The
@@ -302,6 +303,49 @@ const processIssue = (issue, deps) => Effect.gen(function* () {
                 yield* flagHitl(issue, deps, reason);
                 return { kind: "hitl", detail: reason };
             }
+            // VA-460: post-finalize shepherd loop. Gated off by default —
+            // first ship lands the scaffolding only; VA-461..463 wire the
+            // mergeability / CI / reviewer subscriptions, VA-464 the
+            // budget knobs. When gated off the composer returns the
+            // `opened` outcome verbatim, preserving the historical
+            // behavior.
+            if (deps.config.shepherdEnabled) {
+                const shepherd = yield* runShepherdPass(issue, {
+                    config: deps.config,
+                    cwd: deps.cwd,
+                    baseBranch: deps.baseBranch,
+                    github: deps.github,
+                    // VA-461 / VA-462 / VA-463: three real subscriptions
+                    // wired in precedence order. Mergeability runs first
+                    // (a dirty base would prevent CI from even running);
+                    // CI second; reviewer feedback last (CI fixes that
+                    // address reviewer concerns push commits which will
+                    // be seen on the next tick).
+                    isMerged: makeIsMerged(deps.github),
+                    subscriptions: [
+                        makeMergeabilityWatcher({
+                            github: deps.github,
+                            config: deps.config,
+                        }),
+                        makeCiWatcher({
+                            github: deps.github,
+                            config: deps.config,
+                        }),
+                        makeReviewerWatcher({
+                            github: deps.github,
+                            config: deps.config,
+                        }),
+                    ],
+                }, branch, finalized.detail);
+                if (shepherd.kind === "hitl") {
+                    const reason = `Shepherd routed PR to HITL: ${shepherd.reason}`;
+                    yield* flagHitl(issue, deps, reason);
+                    return { kind: "hitl", detail: reason };
+                }
+                // `merged` and `ready` both preserve the `opened` outcome —
+                // the PR exists; whether it's merged yet doesn't change the
+                // per-issue verdict the operator sees in the exit summary.
+            }
             return finalized;
         }
         if (review.kind === "hitl") {

package/dist/prompts.js

@@ -31,6 +31,43 @@ export async function renderReviewPrompt(args) {
     const template = await loadReviewPrompt();
     return renderPrompt(template, reviewVars(args));
 }
+/**
+ * VA-461: render the shepherd-rebase prompt. The agent receives the
+ * branch / base / mergeable_state and an optional list of files
+ * `getConflictFiles` pre-detected — it executes the rebase inside
+ * sandcastle and signals IMPL: DONE or IMPL: BLOCKED.
+ */
+export async function renderShepherdRebasePrompt(args) {
+    const template = await loadShepherdRebasePrompt();
+    return renderPrompt(template, shepherdRebaseVars(args));
+}
+/**
+ * VA-462: render the shepherd-ci-fix prompt. The agent receives the
+ * failing check name and the trailing log lines and executes a
+ * targeted fix on the impl branch (commit + push, not force-push).
+ */
+export async function renderShepherdCiFixPrompt(args) {
+    const template = await loadShepherdCiFixPrompt();
+    return renderPrompt(template, shepherdCiFixVars(args));
+}
+/**
+ * VA-463: render the prompt for a `REVIEW: CHANGES-REQUESTED — <fix>`
+ * verdict from the adversarial PR-reviewer agent. The fix line is
+ * inserted verbatim; the agent applies the change and pushes.
+ */
+export async function renderShepherdReviewFixPrompt(args) {
+    const template = await loadShepherdReviewFixPrompt();
+    return renderPrompt(template, shepherdReviewFixVars(args));
+}
+/**
+ * VA-463: render the prompt for a verbatim human comment on the PR.
+ * The agent decides whether the comment is actionable; non-actionable
+ * comments resolve to IMPL: DONE with no commit.
+ */
+export async function renderShepherdReviewRespondPrompt(args) {
+    const template = await loadShepherdReviewRespondPrompt();
+    return renderPrompt(template, shepherdReviewRespondVars(args));
+}
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -40,6 +77,18 @@ async function loadImplementPrompt() {
 async function loadReviewPrompt() {
     return readFile(join(PROMPT_DIR, "review.md"), "utf8");
 }
+async function loadShepherdRebasePrompt() {
+    return readFile(join(PROMPT_DIR, "shepherd-rebase.md"), "utf8");
+}
+async function loadShepherdCiFixPrompt() {
+    return readFile(join(PROMPT_DIR, "shepherd-ci-fix.md"), "utf8");
+}
+async function loadShepherdReviewFixPrompt() {
+    return readFile(join(PROMPT_DIR, "shepherd-review-fix.md"), "utf8");
+}
+async function loadShepherdReviewRespondPrompt() {
+    return readFile(join(PROMPT_DIR, "shepherd-review-respond.md"), "utf8");
+}
 /**
  * Replace all `{{KEY}}` placeholders with values from `vars`. Done
  * here (not in sandcastle's promptArgs) so the prompt can be passed
@@ -77,6 +126,56 @@ function reviewVars(args) {
         COMMITS: args.commits || "(no commits)",
     };
 }
+function shepherdCiFixVars(args) {
+    return {
+        ISSUE_IDENTIFIER: args.issue.identifier,
+        ISSUE_TITLE: args.issue.title,
+        ISSUE_DESCRIPTION: args.issue.description || "(no description)",
+        BRANCH: args.branch,
+        CHECK_NAME: args.checkName,
+        LOG_TAIL: args.logTail.trim() || "(log unavailable)",
+    };
+}
+function shepherdReviewFixVars(args) {
+    return {
+        ISSUE_IDENTIFIER: args.issue.identifier,
+        ISSUE_TITLE: args.issue.title,
+        ISSUE_DESCRIPTION: args.issue.description || "(no description)",
+        BRANCH: args.branch,
+        FIX_REQUEST: args.fixRequest.trim() || "(empty fix request)",
+    };
+}
+function shepherdReviewRespondVars(args) {
+    return {
+        ISSUE_IDENTIFIER: args.issue.identifier,
+        ISSUE_TITLE: args.issue.title,
+        ISSUE_DESCRIPTION: args.issue.description || "(no description)",
+        BRANCH: args.branch,
+        COMMENT_AUTHOR: args.commentAuthor || "(unknown author)",
+        COMMENT_SOURCE: args.commentSource,
+        COMMENT_BODY: args.commentBody.trim() || "(empty body)",
+    };
+}
+function shepherdRebaseVars(args) {
+    // The conflict-files block is one of two shapes: a bulleted list
+    // (when `getConflictFiles` returned hits) or a single line saying
+    // the branch is "behind" with no expected conflicts. The template
+    // substitutes the whole block via `{{CONFLICT_FILES_BLOCK}}` so
+    // either shape renders cleanly without dangling headers.
+    const filesBlock = args.conflictFiles.length > 0
+        ? `Pre-detected conflicting files:\n${args.conflictFiles
+            .map((f) => `  - ${f}`)
+            .join("\n")}`
+        : `No conflicts pre-detected — the branch is behind base, expect a clean fast-forward rebase`;
+    return {
+        ISSUE_IDENTIFIER: args.issue.identifier,
+        ISSUE_TITLE: args.issue.title,
+        BRANCH: args.branch,
+        BASE_BRANCH: args.baseBranch,
+        MERGEABLE_STATE: args.mergeableState,
+        CONFLICT_FILES_BLOCK: filesBlock,
+    };
+}
 /**
  * VA-383: known orchestrator-emitted comment prefixes that are
  * bookkeeping noise, not feedback the impl agent should learn from.