@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/mcp/tools/ci-preflight.js

@@ -0,0 +1,183 @@
+/**
+ * `wp_ci_preflight` MCP tool.
+ *
+ * Wraps `runCiPreflight` (the single owner of the pre-push gate — see
+ * `src/cli/commands/ci-preflight.ts`) so agents can run the exact fail-fast,
+ * branch-scoped sequence CI mirrors — `format → guardrails → typecheck →
+ * lint → test` — without shelling out to `wp ci-preflight` via Bash.
+ *
+ * `runCiPreflight`'s default `runCheck` re-invokes `wp <subcommand>` via
+ * `spawnSync(..., {stdio: "inherit"})`. That is correct for a real terminal
+ * but unsafe here: `wp mcp` speaks stdio-transport JSON-RPC over the process's
+ * real stdout, and an inherited child write would corrupt that stream. This
+ * tool substitutes a `runCheck` that spawns each stage asynchronously via the
+ * shared `runCommand` helper (captured stdout/stderr, a bounded per-stage
+ * timeout, and `extra.signal` cancellation) using the same `wp` launcher
+ * resolution (`resolveWpLauncher`) the CLI uses, so behavior stays identical
+ * — only the transport of the output changes. `runCiPreflight`'s own
+ * `stdout`/`stderr` deps are swallowed for the same reason (they default to
+ * `process.stdout`/`process.stderr`); the equivalent progress detail is
+ * reconstructed from the per-stage results this tool collects itself.
+ *
+ * `runCiPreflight` returns only an exit code — there is no structured
+ * per-stage payload to "pass through." The `{passed, summary, details:
+ * {stages, stoppedAt}}` shape below mirrors `wp_qa`'s aggregate-gate
+ * convention (structured pass/fail + per-stage breakdown) since ci-preflight
+ * is the same shape of thing: a staged composite gate, just sequential and
+ * fail-fast instead of `wp_qa`'s parallel `Promise.all`.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { resolveWpLauncher, runCiPreflight, } from "#cli/commands/ci-preflight.js";
+import { formatMcpToolOutput } from "./_shared/full-output.js";
+import { resolveProjectRoot } from "./_shared/project-root.js";
+import { createSummaryOutputSchema, createSummaryResult } from "./_shared/result.js";
+import { isRunFailure, runCommand } from "./_shared/run-command.js";
+const inputSchema = z.object({
+    cwd: z.string().optional(),
+    full: z.boolean().optional().default(false),
+});
+// Generous but bounded: mirrors `wp_typecheck`'s cap (the heaviest single
+// sibling stage). In normal operation every stage here is branch-scoped
+// (`--affected --branch`) so real runs finish in seconds to low minutes; this
+// cap only exists to convert a hang into a diagnosable `timedOut: true`
+// instead of blocking the MCP transport indefinitely. Applied per-stage (not
+// as one combined budget) so an early hang doesn't eat the time later stages
+// would have needed.
+const CI_PREFLIGHT_STAGE_TIMEOUT_MS = 10 * 60 * 1_000;
+const stageResultSchema = z.object({
+    label: z.string(),
+    args: z.array(z.string()),
+    passed: z.boolean(),
+    exitCode: z.number().optional(),
+    timedOut: z.boolean().optional(),
+    aborted: z.boolean().optional(),
+    spawnError: z.string().optional(),
+    rawOutput: z.string().optional(),
+    truncated: z.boolean().optional(),
+    logPath: z.string().optional(),
+});
+const outputSchema = createSummaryOutputSchema({
+    details: z.object({
+        stages: z.array(stageResultSchema),
+        stoppedAt: z.string().optional(),
+        bootstrapError: z.string().optional(),
+    }),
+});
+const noopWritable = { write: () => true };
+/**
+ * Build the `runCheck` substitution: same stages, same launcher, same
+ * fail-fast contract as the CLI's `defaultRunCheck` — just async and
+ * output-capturing instead of `spawnSync(..., {stdio: "inherit"})`.
+ */
+function buildCapturingRunCheck(stages, options) {
+    return async (check, repoRoot) => {
+        const launcher = resolveWpLauncher(repoRoot);
+        const outcome = await runCommand(launcher.command, [...launcher.prefixArgs, ...check.args], {
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            cwd: repoRoot,
+        });
+        if (isRunFailure(outcome)) {
+            const spawnError = `${outcome.error.code ?? "unknown"} ${outcome.error.message}`;
+            stages.push({ label: check.label, args: [...check.args], passed: false, spawnError });
+            return 1;
+        }
+        const combined = [outcome.stdout, outcome.stderr].filter(Boolean).join("\n");
+        const compact = formatMcpToolOutput(combined, {
+            toolName: `wp_ci_preflight-${check.label}`,
+            full: options.full,
+            cwd: repoRoot,
+        });
+        stages.push({
+            label: check.label,
+            args: [...check.args],
+            passed: outcome.exitCode === 0,
+            exitCode: outcome.exitCode,
+            ...(outcome.timedOut ? { timedOut: true } : {}),
+            ...(outcome.aborted ? { aborted: true } : {}),
+            ...compact,
+        });
+        return outcome.exitCode;
+    };
+}
+function summarizeCiPreflight(stages, bootstrapError) {
+    if (bootstrapError)
+        return bootstrapError;
+    if (stages.length === 0)
+        return "ci-preflight did not run any checks";
+    const failed = stages.find((stage) => !stage.passed);
+    if (!failed)
+        return `ci-preflight passed (${stages.map((stage) => stage.label).join(", ")})`;
+    if (failed.spawnError)
+        return `ci-preflight could not start ${failed.label}: ${failed.spawnError}`;
+    if (failed.timedOut)
+        return `ci-preflight: ${failed.label} timed out`;
+    if (failed.aborted)
+        return `ci-preflight: ${failed.label} aborted`;
+    return `ci-preflight failed at ${failed.label} (exit ${failed.exitCode ?? "unknown"})`;
+}
+const tool = {
+    name: "wp_ci_preflight",
+    description: "Run the locally-runnable required CI checks, fail-fast, branch-scoped: `format → audit guardrails → typecheck → lint → test` (mirrors `.husky/pre-push`). Returns `{passed, summary, details: {stages, stoppedAt}}`. Use before push / PR open-update; prefer over `wp_qa` when you need pre-push parity (branch-scoped `--affected --branch`, sequential fail-fast) rather than `wp_qa`'s parallel whole-scope lint+typecheck+test; run `wp ci-preflight` directly only if this tool is unavailable.",
+    inputSchema,
+    outputSchema,
+    annotations: {
+        title: "CI preflight (pre-push gate)",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw, extra) => {
+        const input = inputSchema.parse(raw ?? {});
+        const cwd = resolveProjectRoot(input.cwd ? { cwd: input.cwd } : {});
+        const stages = [];
+        let bootstrapError;
+        const runCheck = buildCapturingRunCheck(stages, {
+            timeoutMs: CI_PREFLIGHT_STAGE_TIMEOUT_MS,
+            signal: extra?.signal,
+            full: input.full,
+        });
+        const exitCode = await runCiPreflight({
+            cwd,
+            // Already resolved via the MCP-safe `resolveProjectRoot` walk above;
+            // re-resolving via git-topLevel here would risk landing on a different
+            // root than the one we're about to spawn stages in.
+            resolveRepoRoot: () => cwd,
+            hasNodeModules: (repoRoot) => {
+                const ok = existsSync(join(repoRoot, "node_modules"));
+                if (!ok) {
+                    bootstrapError = `wp_ci_preflight: ${repoRoot} is not bootstrapped — node_modules is missing. Run \`vp install\` in this worktree first, then retry.`;
+                }
+                return ok;
+            },
+            runCheck,
+            // Swallow progress writes — they default to process.stdout/stderr,
+            // which on a stdio-transport MCP server IS the JSON-RPC channel. The
+            // equivalent detail is already captured per-stage above.
+            stdout: noopWritable,
+            stderr: noopWritable,
+        });
+        const passed = exitCode === 0;
+        const stoppedAt = passed ? undefined : stages.at(-1)?.label;
+        const payload = {
+            passed,
+            summary: summarizeCiPreflight(stages, bootstrapError),
+            exitCode,
+            details: {
+                stages,
+                ...(stoppedAt ? { stoppedAt } : {}),
+                ...(bootstrapError ? { bootstrapError } : {}),
+            },
+        };
+        // `isError: true` is reserved for "we couldn't run the gate at all"
+        // (not bootstrapped, or a stage's spawn itself failed) — matching
+        // `wp_qa`'s convention that a check legitimately reporting `passed: false`
+        // is normal output the agent should act on, not a tool-execution error.
+        const executionFailed = bootstrapError !== undefined || stages.some((stage) => stage.spawnError !== undefined);
+        return createSummaryResult(payload, executionFailed ? { isError: true } : {});
+    },
+};
+export default tool;

package/dist/esm/mcp/tools/pr-upsert.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { prDescriptionInputSchema, renderAndValidatePrDescription, } from "#pr-description/contract.js";
+import { readCurrentSessionId } from "#session-memory/current-session.js";
 import { createSummaryOutputSchema, createSummaryResult } from "./_shared/result.js";
 import { resolveProjectRoot } from "./_shared/project-root.js";
 import { redactText } from "./_shared/redact.js";
@@ -58,6 +59,42 @@ function resolveCwd(input) {
 function branchFor(input) {
     return input.branch ?? "HEAD";
 }
+/**
+ * Best-effort fill for an omitted `description.sessionId`, using the same
+ * lookup `wp_session_id` wraps. Never overrides an explicit value and never
+ * fights an explicit `Session-skip` (a caller who set a skip reason has
+ * already made a deliberate choice not to disclose a session id).
+ *
+ * This DOES change one previously-fail-closed case: an omitted `sessionId`
+ * with no `Session-skip` used to fail validation outright; it now silently
+ * passes when the current worktree has a resolvable id (which may be a prior,
+ * still-accurate-for-this-worktree id when no capture has happened yet in the
+ * live session) — this is the intended best-effort automation of the paste a
+ * caller would otherwise do by hand. When NO id resolves, the outcome is
+ * unchanged: the description is returned as-is and the pre-existing
+ * "missing sessionId" validation error still blocks the mutation. So the only
+ * new behavior is "fills a real gap"; it never manufactures a fake id and
+ * never converts a genuine miss into a silent success.
+ */
+function withAutoResolvedSessionId(input) {
+    const description = input.description;
+    if (description.sessionId?.trim())
+        return description;
+    if (description.sessionSkipReason?.trim())
+        return description;
+    try {
+        const sessionId = readCurrentSessionId(resolveCwd(input), process.env);
+        return sessionId ? { ...description, sessionId } : description;
+    }
+    catch (error) {
+        // Match this module's stderr-breadcrumb philosophy (see current-session.ts):
+        // a lookup throw degrades to "leave as-is" (fail-closed — validation then
+        // reports the missing sessionId), but is surfaced so a genuine store bug
+        // is not silently swallowed.
+        process.stderr.write(`[wp_pr_upsert] sessionId auto-resolve failed; leaving description unchanged: ${error instanceof Error ? error.message : String(error)}\n`);
+        return description;
+    }
+}
 function clipOutput(value, maxOutputBytes) {
     const redacted = redactText(value.trim());
     if (!redacted)
@@ -152,7 +189,8 @@ const tool = {
     },
     handler: async (raw, extra) => {
         const input = inputSchema.parse(raw ?? {});
-        const { body, validation } = renderAndValidatePrDescription(input.description);
+        const description = withAutoResolvedSessionId(input);
+        const { body, validation } = renderAndValidatePrDescription(description);
         const branch = branchFor(input);
         const bodySha256 = bodyHash(body);
         const commands = [];

package/dist/esm/mcp/tools/review-run.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `wp_review_run` MCP tool.
+ *
+ * Wraps `runReviewRunCommand` — the exact runtime `wp review run` and
+ * `wp review gate` use — so MCP callers get a first-class outside-voice
+ * review primitive instead of shelling into a provider CLI directly. Two
+ * ergonomic improvements over the raw `wp review run` CLI:
+ *
+ *   1. Accepts `prompt` directly instead of requiring a `--prompt-file` on
+ *      disk. The tool writes the prompt to a private temp file under the
+ *      resolved `artifactRoot` itself (cleaned up after each stage), since
+ *      `runReviewRunCommand` requires a real file to read over stdin.
+ *   2. By default runs a synthesized `probe` stage (cheap liveness check)
+ *      followed by the `review` stage in ONE call — removing the two-step
+ *      probe-then-review dance every consumer previously had to hand-roll in
+ *      bash (see the `codex` skill's pre-fix version). If the probe fails,
+ *      the review stage is never attempted. Pass `skipProbe: true` to go
+ *      straight to `review` once a provider is known-warm, or pass an
+ *      explicit `stage` for CLI-parity manual control.
+ *
+ * Provider fallback (e.g. Codex out of API credits) is a `provider`
+ * parameter change on this SAME tool call — never a raw shell-out to a
+ * different provider's CLI. `forbidden-commands.ts`'s
+ * `findReviewCliRedirect` enforces that on the Bash-tool side.
+ */
+import type { ToolDescriptor } from "#mcp/auto-discover";
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/review-run.js

@@ -0,0 +1,216 @@
+/**
+ * `wp_review_run` MCP tool.
+ *
+ * Wraps `runReviewRunCommand` — the exact runtime `wp review run` and
+ * `wp review gate` use — so MCP callers get a first-class outside-voice
+ * review primitive instead of shelling into a provider CLI directly. Two
+ * ergonomic improvements over the raw `wp review run` CLI:
+ *
+ *   1. Accepts `prompt` directly instead of requiring a `--prompt-file` on
+ *      disk. The tool writes the prompt to a private temp file under the
+ *      resolved `artifactRoot` itself (cleaned up after each stage), since
+ *      `runReviewRunCommand` requires a real file to read over stdin.
+ *   2. By default runs a synthesized `probe` stage (cheap liveness check)
+ *      followed by the `review` stage in ONE call — removing the two-step
+ *      probe-then-review dance every consumer previously had to hand-roll in
+ *      bash (see the `codex` skill's pre-fix version). If the probe fails,
+ *      the review stage is never attempted. Pass `skipProbe: true` to go
+ *      straight to `review` once a provider is known-warm, or pass an
+ *      explicit `stage` for CLI-parity manual control.
+ *
+ * Provider fallback (e.g. Codex out of API credits) is a `provider`
+ * parameter change on this SAME tool call — never a raw shell-out to a
+ * different provider's CLI. `forbidden-commands.ts`'s
+ * `findReviewCliRedirect` enforces that on the Bash-tool side.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { runReviewRunCommand } from "#cli/commands/review.js";
+import { createSummaryOutputSchema, createSummaryResult } from "./_shared/result.js";
+import { resolveProjectRoot } from "./_shared/project-root.js";
+const PROBE_PROMPT = "Reply exactly WP_REVIEW_PROBE_OK.";
+const PROBE_EXPECTED_MARKER = "WP_REVIEW_PROBE_OK";
+const inputSchema = z
+    .object({
+    prompt: z.string().min(1),
+    provider: z.enum(["claude", "codex", "opencode", "grok"]),
+    model: z.string().min(1).optional(),
+    effort: z.enum(["medium", "high"]).optional().default("medium"),
+    stage: z.enum(["probe", "review"]).optional(),
+    skipProbe: z.boolean().optional().default(false),
+    expectedMarker: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Required substring of the provider's output. Applies to BOTH stages. On a review, ask the prompt for a verdict token (e.g. 'VERDICT:') and pass it here — a provider that announces intent and ends the turn without doing the work then fails loudly as expected-marker-missing instead of reporting a content-free success. On an explicit probe it is the liveness marker; in auto mode the probe uses its own synthesized marker and this value applies to the review stage."),
+    artifactRoot: z.string().optional(),
+    idleSeconds: z.number().int().positive().optional().default(180),
+    cwd: z.string().optional(),
+})
+    .strict();
+const reviewRunSummarySchema = z.object({
+    schemaVersion: z.literal(1),
+    runId: z.string(),
+    provider: z.enum(["claude", "codex", "opencode", "grok"]),
+    adapterVersion: z.string(),
+    model: z.string(),
+    effort: z.enum(["medium", "high"]),
+    stage: z.enum(["probe", "review"]),
+    status: z.string(),
+    startedAt: z.string(),
+    finishedAt: z.string(),
+    lastProgressAt: z.string(),
+    semanticProgressCount: z.number(),
+    exitCode: z.number().nullable(),
+    markerMatched: z.boolean().nullable(),
+    result: z.string().optional(),
+    failureCode: z.string().optional(),
+    limitWindow: z.enum(["five-hour", "weekly", "monthly", "unknown"]).optional(),
+    retryAfterMs: z.number().optional(),
+    summaryPath: z.string(),
+});
+const outputSchema = createSummaryOutputSchema({
+    counts: z.object({ stagesRun: z.number() }),
+    details: z.object({
+        stages: z.array(reviewRunSummarySchema),
+        probeSkipped: z.boolean(),
+    }),
+});
+function resolveCwd(input) {
+    return resolveProjectRoot(input.cwd ? { cwd: input.cwd } : {});
+}
+function resolveArtifactRoot(projectRoot, input) {
+    if (!input.artifactRoot)
+        return path.join(projectRoot, ".webpresso", "reviews");
+    return path.isAbsolute(input.artifactRoot)
+        ? input.artifactRoot
+        : path.join(projectRoot, input.artifactRoot);
+}
+function writePromptFile(artifactRoot, prompt) {
+    mkdirSync(artifactRoot, { recursive: true });
+    const promptFile = path.join(artifactRoot, `mcp-review-prompt-${randomUUID()}.txt`);
+    // 0600 matches the CLI fallback's `mktemp` posture: the prompt can carry a
+    // diff/context the caller would not want other local users reading, and the
+    // file lives under a shared artifactRoot. Owner-only, not just an
+    // unpredictable name.
+    writeFileSync(promptFile, prompt, { encoding: "utf8", mode: 0o600 });
+    return promptFile;
+}
+function cleanupPromptFile(promptFile) {
+    try {
+        unlinkSync(promptFile);
+    }
+    catch {
+        // Best-effort cleanup: a leftover temp file under the private
+        // artifactRoot is harmless and is never treated as review evidence.
+    }
+}
+async function runStage(projectRoot, artifactRoot, input, stage, prompt, expectedMarker, signal) {
+    const promptFile = writePromptFile(artifactRoot, prompt);
+    try {
+        const options = {
+            provider: input.provider,
+            promptFile,
+            effort: input.effort,
+            stage,
+            artifactRoot,
+            idleSeconds: String(input.idleSeconds),
+            ...(input.model ? { model: input.model } : {}),
+            ...(expectedMarker ? { expectedMarker } : {}),
+        };
+        return await runReviewRunCommand(projectRoot, options, signal ? { signal } : {});
+    }
+    finally {
+        cleanupPromptFile(promptFile);
+    }
+}
+/**
+ * Execution success, not verdict positivity: a `review` stage that completes
+ * with a REJECT verdict is still `status: "complete"` and counts as `passed`
+ * here. Only a `probe` stage additionally requires its expected marker to
+ * have matched (when one was actually requested — an explicit probe without
+ * an `expectedMarker` only needs to complete).
+ *
+ * Note this check does NOT need a review-stage marker branch: when the caller
+ * supplies an `expectedMarker`, the supervisor itself downgrades a run whose
+ * output lacks it to `status: "provider-failure"` /
+ * `failureCode: "expected-marker-missing"`, so the `status !== "complete"`
+ * guard above already rejects it. That is the load-bearing defense against a
+ * provider that announces intent and ends the turn without doing the work —
+ * observed 2026-07-24, when reviews returned only "I'll compare X against
+ * Y..." yet reported `complete`.
+ */
+function stageOk(summary, markerRequired) {
+    if (summary.status !== "complete")
+        return false;
+    if (summary.stage !== "probe")
+        return true;
+    return markerRequired ? summary.markerMatched === true : summary.markerMatched !== false;
+}
+function describeStage(summary) {
+    if (summary.stage === "probe") {
+        const ok = summary.status === "complete" && summary.markerMatched !== false;
+        return ok ? "probe ok" : `probe failed (${summary.failureCode ?? summary.status})`;
+    }
+    return summary.status === "complete"
+        ? "review complete"
+        : `review failed (${summary.failureCode ?? summary.status})`;
+}
+function summarize(stages, passed, probeSkipped) {
+    const parts = stages.map(describeStage);
+    if (probeSkipped)
+        parts.unshift("probe skipped");
+    return `${passed ? "passed" : "failed"}: ${parts.join("; ")}`;
+}
+function toResult(stages, passed, probeSkipped) {
+    return createSummaryResult({
+        passed,
+        summary: summarize(stages, passed, probeSkipped),
+        counts: { stagesRun: stages.length },
+        details: { stages, probeSkipped },
+    }, { isError: !passed });
+}
+const tool = {
+    name: "wp_review_run",
+    description: 'Run an outside-voice provider review (claude|codex|opencode|grok) from a `prompt` string — no `--prompt-file` needed. By default runs a synthesized probe stage first, then the review stage, in one call; the review stage is skipped if the probe fails. Pass `stage: "probe"` or `stage: "review"` for single-stage CLI-parity control, or `skipProbe: true` to skip straight to review once a provider is known-warm. To fall back from an unavailable provider (e.g. Codex out of credits), change the `provider` parameter on this SAME tool — never shell into a different provider CLI. IMPORTANT: `passed` means the review EXECUTED to completion, NOT that the reviewer approved — a review that runs and returns REJECT is still `passed: true`. The reviewer\'s actual verdict/findings are in `details.stages[].result`; read that text before reporting approval. To guarantee the reviewer actually did the work, ask the prompt for a verdict token and pass it as `expectedMarker`: a provider that only announces intent then stops will fail as expected-marker-missing rather than returning a content-free success.',
+    inputSchema,
+    outputSchema,
+    annotations: {
+        title: "Run outside-voice provider review",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (raw, extra) => {
+        const input = inputSchema.parse(raw ?? {});
+        const projectRoot = resolveCwd(input);
+        const artifactRoot = resolveArtifactRoot(projectRoot, input);
+        const signal = extra?.signal;
+        if (input.stage === "probe") {
+            const result = await runStage(projectRoot, artifactRoot, input, "probe", input.prompt, input.expectedMarker, signal);
+            return toResult([result], stageOk(result, input.expectedMarker !== undefined), false);
+        }
+        if (input.stage === "review") {
+            const result = await runStage(projectRoot, artifactRoot, input, "review", input.prompt, input.expectedMarker, signal);
+            return toResult([result], stageOk(result, false), false);
+        }
+        // No explicit stage requested: auto probe-then-review.
+        const stages = [];
+        if (!input.skipProbe) {
+            const probeResult = await runStage(projectRoot, artifactRoot, input, "probe", PROBE_PROMPT, PROBE_EXPECTED_MARKER, signal);
+            stages.push(probeResult);
+            if (!stageOk(probeResult, true)) {
+                // Probe failed: do not waste a full review-stage call.
+                return toResult(stages, false, false);
+            }
+        }
+        const reviewResult = await runStage(projectRoot, artifactRoot, input, "review", input.prompt, input.expectedMarker, signal);
+        stages.push(reviewResult);
+        const passed = stages.every((stage) => stageOk(stage, stage.stage === "probe"));
+        return toResult(stages, passed, input.skipProbe);
+    },
+};
+export default tool;

package/dist/esm/mcp/tools/run-wait.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import type { ToolDescriptor, ToolHandlerExtra } from "#mcp/auto-discover";
+export declare const RUN_WAIT_UNTIL_VALUES: readonly ["run_terminal", "all_jobs_terminal"];
+export type RunWaitUntil = (typeof RUN_WAIT_UNTIL_VALUES)[number];
+export type RunWaitStatus = "success" | "failed" | "timed_out" | "no_run";
+export type RunWaitVerdict = "passed" | "failed" | "pending";
+export type RunWaitTerminalReason = "run_terminal" | "all_jobs_terminal" | "run_failed" | "timeout" | "no_run" | "command_failed";
+export type WorkflowRunStatus = "queued" | "in_progress" | "completed" | "waiting" | "requested" | "pending" | (string & {});
+export type WorkflowRunConclusion = "success" | "failure" | "cancelled" | "skipped" | "neutral" | "timed_out" | "action_required" | "stale" | "startup_failure" | null;
+export type JobStatus = "queued" | "in_progress" | "completed" | "waiting" | "requested" | "pending" | (string & {});
+export type JobConclusion = "success" | "failure" | "neutral" | "cancelled" | "skipped" | "timed_out" | "action_required" | null;
+export type JobClassification = "blocked_upstream";
+export interface RunWaitJob {
+    readonly name: string;
+    readonly status: JobStatus;
+    readonly conclusion: JobConclusion;
+    readonly failedStep?: string;
+    readonly errorTail?: string;
+    readonly upstreamCulprits?: readonly string[];
+    readonly classification?: JobClassification;
+    readonly transient?: string;
+}
+/**
+ * Slim per-command record: keeps spawn diagnostics (exit code, timedOut,
+ * aborted, missingBinary, deadline-skips) without carrying raw output — job
+ * logs and JSON payloads never enter the result's command trail.
+ */
+interface SlimCommand {
+    readonly id: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly passed: boolean;
+    readonly exitCode?: number;
+    readonly timedOut?: true;
+    readonly aborted?: true;
+    readonly missingBinary?: true;
+    readonly skipped?: true;
+}
+export interface RunWaitResult {
+    readonly [key: string]: unknown;
+    readonly status: RunWaitStatus;
+    readonly passed: boolean;
+    readonly summary: string;
+    readonly verdict: RunWaitVerdict;
+    readonly terminalReason: RunWaitTerminalReason;
+    readonly conclusion: WorkflowRunConclusion;
+    readonly runId: number | null;
+    readonly runUrl?: string;
+    readonly workflowName?: string;
+    readonly headSha?: string;
+    readonly until: RunWaitUntil;
+    readonly jobs: readonly RunWaitJob[];
+    readonly counts: Record<string, number>;
+    readonly details: {
+        readonly cwd: string;
+        readonly sha?: string;
+        readonly runId?: number;
+        readonly workflow?: string;
+        readonly until: RunWaitUntil;
+        readonly timeoutMs: number;
+        readonly pollIntervalMs: number;
+        readonly pollCount: number;
+        readonly elapsedMs: number;
+        readonly commands: readonly SlimCommand[];
+    };
+    readonly warnings?: readonly string[];
+}
+declare const inputSchema: z.ZodObject<{
+    cwd: z.ZodOptional<z.ZodString>;
+    directory: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxOutputBytes: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    sha: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    workflow: z.ZodOptional<z.ZodString>;
+    until: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        all_jobs_terminal: "all_jobs_terminal";
+        run_terminal: "run_terminal";
+    }>>>;
+    pollIntervalMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strict>;
+export type RunWaitInput = z.input<typeof inputSchema>;
+export declare function classifyTransient(text: string): string | undefined;
+export declare function runRunWait(raw: RunWaitInput, extra?: ToolHandlerExtra): Promise<RunWaitResult>;
+declare const tool: ToolDescriptor;
+export default tool;