@webpresso/agent-kit 3.1.30 → 3.2.0

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;