@webpresso/agent-kit 3.3.1 → 3.3.3

package/dist/esm/mcp/tools/release-progress.js

@@ -0,0 +1,110 @@
+/**
+ * `wp_release_progress` — read-only Release workflow phase reporter for agents.
+ *
+ * Shares {@link runReleaseProgress} with the CLI so MCP and `wp release-progress`
+ * never diverge. Does not mutate GitHub; only reads via `gh`.
+ */
+import { z } from "zod";
+import { runReleaseProgress, } from "#cli/commands/release-progress.js";
+import { createSummaryOutputSchema, createSummaryResult } from "./_shared/result.js";
+import { readonlyOpsBaseSchema } from "./_readonly-ops.js";
+const inputSchema = readonlyOpsBaseSchema
+    .extend({
+    runId: z.union([z.string().min(1), z.number().int().positive()]).optional(),
+    repo: z.string().min(1).optional(),
+})
+    .strict();
+const releaseProgressDetailsSchema = z
+    .object({
+    runId: z.string(),
+    repo: z.string(),
+    phase: z.enum(["detect", "native-matrix", "publish", "done", "failed"]),
+    detail: z.string(),
+    native: z.object({
+        done: z.number().int().nonnegative(),
+        total: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        inProgress: z.number().int().nonnegative(),
+    }),
+    publishRunning: z.boolean(),
+    publishDone: z.boolean(),
+    publishFailed: z.boolean(),
+    line: z.string(),
+})
+    .strict();
+const outputSchema = createSummaryOutputSchema({
+    details: releaseProgressDetailsSchema,
+});
+/**
+ * Build the tool descriptor. Tests inject gh seams; production uses defaults.
+ */
+export function createReleaseProgressTool(deps = {}) {
+    return {
+        name: "wp_release_progress",
+        description: "Read-only GitHub Actions Release workflow phase reporter (detect | native-matrix | publish | done | failed) with session-memory native matrix counts. Use instead of silent npm view polls after Version Packages merge. Does not mutate GitHub. Prefer this over shelling `wp release-progress` when available.",
+        inputSchema,
+        outputSchema,
+        annotations: {
+            title: "Release progress",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        handler: async (raw) => {
+            const input = inputSchema.parse(raw ?? {});
+            const repo = input.repo ?? "webpresso/agent-kit";
+            try {
+                const result = runReleaseProgress({
+                    runId: input.runId,
+                    repo,
+                    json: false,
+                    fetchJobs: deps.fetchJobs,
+                    resolveLatestRunId: deps.resolveLatestRunId,
+                    // Suppress CLI text I/O; structuredContent is the MCP contract.
+                    stdout: { write: () => undefined },
+                    stderr: { write: () => undefined },
+                });
+                const { progress, runId, line } = result;
+                const failed = progress.phase === "failed";
+                return createSummaryResult({
+                    passed: !failed,
+                    summary: line,
+                    details: {
+                        runId,
+                        repo,
+                        phase: progress.phase,
+                        detail: progress.detail,
+                        native: progress.native,
+                        publishRunning: progress.publishRunning,
+                        publishDone: progress.publishDone,
+                        publishFailed: progress.publishFailed,
+                        line,
+                    },
+                    warnings: failed ? [progress.detail] : [],
+                }, { isError: failed });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return createSummaryResult({
+                    passed: false,
+                    summary: `release-progress failed: ${message}`,
+                    details: {
+                        runId: input.runId === undefined ? "" : String(input.runId),
+                        repo,
+                        phase: "failed",
+                        detail: message,
+                        native: { done: 0, total: 0, failed: 0, inProgress: 0 },
+                        publishRunning: false,
+                        publishDone: false,
+                        publishFailed: false,
+                        line: `release-progress phase=failed native=0/0 ${message}`,
+                    },
+                    warnings: [message],
+                }, { isError: true });
+            }
+        },
+    };
+}
+const tool = createReleaseProgressTool();
+export default tool;

package/dist/esm/mcp/tools/wp-ui-blocks-list.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDescriptor } from "#mcp/auto-discover";
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/wp-ui-blocks-list.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { resolveBlockRegistry } from "#compose/registry-resolve.js";
+const inputSchema = z
+    .object({
+    cwd: z.string().optional(),
+    profile: z.enum(["admin-crud", "ops-report"]).optional(),
+})
+    .strict();
+const tool = {
+    name: "wp_ui_blocks_list",
+    description: "List the agent UI block catalog for composition. Resolves project `.webpresso/generated/frontend/blocks/registry.json` when present, otherwise the offline catalog snapshot. Always returns source (project|snapshot), registryVersion, and warnings (e.g. snapshot used inside a webpresso tree without a generated registry).",
+    inputSchema,
+    annotations: {
+        title: "UI blocks list",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw) => {
+        const input = inputSchema.parse(raw ?? {});
+        const resolved = resolveBlockRegistry({ cwd: input.cwd });
+        // admin-crud: full registry (list/detail/form). ops-report: no admin blocks.
+        const blocks = input.profile === "ops-report" ? [] : resolved.registry.blocks;
+        const summary = `UI blocks: ${blocks.length} (source=${resolved.source}, version=${resolved.registryVersion})`;
+        const payload = {
+            passed: true,
+            summary,
+            source: resolved.source,
+            registryVersion: resolved.registryVersion,
+            path: resolved.path,
+            warnings: [...resolved.warnings],
+            profiles: ["admin-crud", "ops-report"],
+            blocks,
+            webpressoPresentWithoutRegistry: resolved.webpressoPresentWithoutRegistry,
+        };
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: payload,
+        };
+    },
+};
+export default tool;

package/dist/esm/mcp/tools/wp-ui-compose.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDescriptor } from "#mcp/auto-discover";
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/wp-ui-compose.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { composeValidate } from "#compose/compose.js";
+const inputSchema = z
+    .object({
+    cwd: z.string().optional(),
+    profile: z.enum(["admin-crud", "ops-report"]),
+    kind: z.enum(["list", "detail", "form"]).optional(),
+    spec: z.unknown(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.profile === "admin-crud" && value.kind === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "kind is required for admin-crud (list|detail|form)",
+            path: ["kind"],
+        });
+    }
+});
+const tool = {
+    name: "wp_ui_compose",
+    description: "Validate a profile-discriminated UI compose input. admin-crud: validate list/detail/form specs against the block registry (returns input spec unchanged when legal). ops-report: validate flat OpsReportSpec. Does not write files or open a browser.",
+    inputSchema,
+    annotations: {
+        title: "UI compose validate",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw) => {
+        const input = inputSchema.parse(raw ?? {});
+        const composeInput = input.profile === "admin-crud"
+            ? {
+                profile: "admin-crud",
+                kind: input.kind,
+                spec: input.spec && typeof input.spec === "object" && !Array.isArray(input.spec)
+                    ? input.spec
+                    : {},
+            }
+            : { profile: "ops-report", spec: input.spec };
+        const result = composeValidate(composeInput, { cwd: input.cwd });
+        const summary = result.ok
+            ? `compose ok (${result.profile})`
+            : `compose failed (${result.profile}): ${result.diagnostics.map((d) => d.message).join("; ")}`;
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: {
+                passed: result.ok,
+                summary,
+                profile: result.profile,
+                ok: result.ok,
+                spec: result.spec,
+                diagnostics: result.diagnostics,
+                registrySource: result.registrySource,
+                registryVersion: result.registryVersion,
+                warnings: result.warnings,
+            },
+        };
+    },
+};
+export default tool;

package/dist/esm/mcp/tools/wp-ui-preview.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDescriptor } from "#mcp/auto-discover";
+declare const tool: ToolDescriptor;
+export default tool;

package/dist/esm/mcp/tools/wp-ui-preview.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { previewOpsReport } from "#compose/preview.js";
+const inputSchema = z
+    .object({
+    cwd: z.string().optional(),
+    profile: z.literal("ops-report"),
+    spec: z.unknown(),
+})
+    .strict();
+const tool = {
+    name: "wp_ui_preview",
+    description: "Validate an ops-report compose spec, write self-contained HTML under the worktree state surface (or .webpresso/compose fallback), and return { path } only. Does not open a browser. admin-crud is not supported for preview.",
+    inputSchema,
+    annotations: {
+        title: "UI ops-report preview",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw) => {
+        try {
+            const input = inputSchema.parse(raw ?? {});
+            const { path } = previewOpsReport({ cwd: input.cwd, spec: input.spec });
+            const summary = `ops-report preview written: ${path}`;
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: {
+                    passed: true,
+                    summary,
+                    path,
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof z.ZodError
+                ? `Invalid wp_ui_preview input: ${error.issues.map((i) => i.message).join("; ")} (ops-report profile only; admin-crud is not supported)`
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            return {
+                content: [{ type: "text", text: message }],
+                structuredContent: {
+                    passed: false,
+                    summary: message,
+                },
+                isError: true,
+            };
+        }
+    },
+};
+export default tool;

package/dist/esm/package.json

@@ -25,6 +25,8 @@
     "#worktrees/*": "./worktrees/*.js",
     "#fleet/*.js": "./fleet/*.js",
     "#fleet/*": "./fleet/*.js",
+    "#compose/*.js": "./compose/*.js",
+    "#compose/*": "./compose/*.js",
     "#cli/auto-update/*.js": "./cli/auto-update/*.js",
     "#cli/auto-update/*": "./cli/auto-update/*.js",
     "#cli/*.js": "./cli/*.js",

package/dist/esm/review/delivery-verifier.d.ts

@@ -1,5 +1,6 @@
-import { executeAllowedWpCommand } from "#trust/command-runner.js";
+import { executeAllowedWpCommand, type AllowedWpCommandResult } from "#trust/command-runner.js";
 import type { ReviewTargetCheckout } from "#review/execution/review-checkout.js";
+import type { SandboxAvailability } from "#review/execution/sandbox/types.js";
 export interface ReviewGateVerificationCommand {
     readonly command: string;
     readonly outcome: "passed" | "failed" | "timed-out" | "deferred";
@@ -7,12 +8,29 @@ export interface ReviewGateVerificationCommand {
     readonly exitCode: number | null;
     readonly signal?: string;
 }
+/**
+ * How the gate commands were isolated. `srt` = OS-sandboxed; `disabled-by-operator`
+ * = an explicit `WP_REVIEW_UNSANDBOXED_GATES=1` override ran them unsandboxed;
+ * `unavailable` = no backend and no override, so no gate ran (fail-closed).
+ */
+export type ReviewSandboxMode = "srt" | "disabled-by-operator" | "unavailable";
 export interface ReviewGateVerification {
     readonly status: "passed" | "failed";
     readonly commands: readonly ReviewGateVerificationCommand[];
     readonly failureCode?: string;
     readonly logPath?: string;
+    readonly sandbox?: ReviewSandboxMode;
+    readonly sandboxReason?: string;
 }
+/** Runs one gate command in the review checkout and returns its raw result. */
+export type RunSandboxedGate = (args: {
+    readonly command: string;
+    readonly executionRoot: string;
+    readonly logRoot: string;
+    readonly runTmpDir: string;
+    readonly projectRoot: string;
+    readonly signal?: AbortSignal;
+}) => Promise<AllowedWpCommandResult>;
 export interface VerifyDeliveryGatesInput {
     readonly purpose: "plan" | "delivery";
     readonly blueprintContent: string;
@@ -20,8 +38,21 @@ export interface VerifyDeliveryGatesInput {
     readonly gateId: string;
     readonly checkout: ReviewTargetCheckout;
     readonly signal?: AbortSignal;
+    /** Legacy/override execution path (unsandboxed). */
     readonly executeCommand?: typeof executeAllowedWpCommand;
+    /** Test seam: resolve the sandbox backend. */
+    readonly resolveAvailability?: () => Promise<SandboxAvailability>;
+    /** Test seam: run a single sandboxed gate. */
+    readonly runSandboxedGate?: RunSandboxedGate;
 }
-export declare function verifyDeliveryPromotionGates(input: VerifyDeliveryGatesInput): ReviewGateVerification | undefined;
+export declare function verifyDeliveryPromotionGates(input: VerifyDeliveryGatesInput): Promise<ReviewGateVerification | undefined>;
+/**
+ * Builds the real {@link RunSandboxedGate}. `cleanupSandbox` is a test-only
+ * seam (defaults to the real {@link cleanupSandboxCommand}) so unit tests can
+ * force the fail-closed "passing gate, leaky sandbox" path without a real srt
+ * backend; every non-test caller gets the real cleanup and byte-identical
+ * behavior to before this seam existed.
+ */
+export declare function createRunSandboxedGate(cleanupSandbox?: () => Promise<void>): RunSandboxedGate;
 export declare function verificationPromptSummary(verification: ReviewGateVerification | undefined): string | undefined;
 export declare function verificationArtifactSection(verification: ReviewGateVerification | undefined): string;

package/dist/esm/review/delivery-verifier.js

@@ -1,8 +1,14 @@
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
-import { executeAllowedWpCommand, relativeCommandLogPath, } from "#trust/command-runner.js";
+import { executeAllowedWpCommand, rejectedInvocationResult, relativeCommandLogPath, resolveInvocationFromCommand, runResolvedInvocationAsync, } from "#trust/command-runner.js";
 import { parseTrustDossier } from "#trust/dossier.js";
 import { parseAllowedWpCommand } from "#trust/gates.js";
-export function verifyDeliveryPromotionGates(input) {
+import { buildSandboxedGateEnv } from "#review/execution/sandbox/env.js";
+import { cleanupSandboxCommand, wrapGateForSandbox } from "#review/execution/sandbox/adapter.js";
+import { resolveSandboxAvailability } from "#review/execution/sandbox/probe.js";
+const UNSANDBOXED_OVERRIDE_ENV = "WP_REVIEW_UNSANDBOXED_GATES";
+export async function verifyDeliveryPromotionGates(input) {
     if (input.purpose !== "delivery")
         return undefined;
     const parsed = parseTrustDossier(input.blueprintContent);
@@ -12,48 +18,82 @@ export function verifyDeliveryPromotionGates(input) {
             parsed.violations[0]?.message === "missing Trust Dossier section") {
             return undefined;
         }
+        return { status: "failed", commands: [], failureCode: "malformed-trust-dossier" };
+    }
+    const gates = parsed.dossier?.gates ?? [];
+    if (gates.length === 0)
+        return undefined;
+    const overrideUnsandboxed = process.env[UNSANDBOXED_OVERRIDE_ENV] === "1";
+    const availability = await (input.resolveAvailability?.() ?? resolveSandboxAvailability());
+    if (availability.kind === "none" && !overrideUnsandboxed) {
         return {
             status: "failed",
             commands: [],
-            failureCode: "malformed-trust-dossier",
+            failureCode: "sandbox-unavailable",
+            sandbox: "unavailable",
+            sandboxReason: availability.reason,
         };
     }
-    const gates = parsed.dossier?.gates ?? [];
-    if (gates.length === 0)
-        return undefined;
-    const commands = [];
-    const executeCommand = input.executeCommand ?? executeAllowedWpCommand;
+    const sandbox = overrideUnsandboxed ? "disabled-by-operator" : "srt";
     const logRoot = path.join(input.projectRoot, ".webpresso", "logs", "delivery-verification", input.gateId);
-    for (const gate of gates) {
+    const runTmpDir = sandbox === "srt" ? mkdtempSync(path.join(tmpdir(), "wp-review-run-")) : undefined;
+    try {
+        return await runGateLoop(input, { gates, sandbox, logRoot, runTmpDir });
+    }
+    finally {
+        if (runTmpDir !== undefined)
+            rmSync(runTmpDir, { recursive: true, force: true });
+    }
+}
+async function runGateLoop(input, ctx) {
+    const commands = [];
+    const runSandboxedGate = input.runSandboxedGate ?? defaultRunSandboxedGate;
+    for (const gate of ctx.gates) {
         if (input.signal?.aborted) {
             return {
                 status: "failed",
                 commands,
                 failureCode: "verification-cancelled",
+                sandbox: ctx.sandbox,
             };
         }
         if (isApprovalDependentLifecycleGate(gate.command)) {
-            commands.push({
-                command: gate.command,
-                outcome: "deferred",
-                durationMs: 0,
-                exitCode: null,
-            });
+            commands.push({ command: gate.command, outcome: "deferred", durationMs: 0, exitCode: null });
             continue;
         }
-        const result = executeCommand({
-            command: gate.command,
-            executionRoot: input.checkout.cwd,
-            logRoot,
-            env: { CI: "1", NO_COLOR: "1", WP_FORCE_SOURCE: "1" },
-        });
+        const result = ctx.sandbox === "srt"
+            ? await runSandboxedGate({
+                command: gate.command,
+                executionRoot: input.checkout.cwd,
+                logRoot: ctx.logRoot,
+                runTmpDir: ctx.runTmpDir ?? "",
+                projectRoot: input.projectRoot,
+                ...(input.signal ? { signal: input.signal } : {}),
+            })
+            : (input.executeCommand ?? executeAllowedWpCommand)({
+                command: gate.command,
+                executionRoot: input.checkout.cwd,
+                logRoot: ctx.logRoot,
+                env: { CI: "1", NO_COLOR: "1", WP_FORCE_SOURCE: "1" },
+            });
         commands.push(publicCommandResult(result));
+        // A cancellation DURING a gate (abort mid-execution) must report as
+        // cancelled, not a generic command failure.
+        if (input.signal?.aborted || result.failureCode === "command-cancelled") {
+            return {
+                status: "failed",
+                commands,
+                failureCode: "verification-cancelled",
+                sandbox: ctx.sandbox,
+            };
+        }
         if (result.outcome !== "passed") {
             return {
                 status: "failed",
                 commands,
                 failureCode: result.failureCode ?? "verification-command-failed",
                 logPath: relativeCommandLogPath(input.projectRoot, result.logPath),
+                sandbox: ctx.sandbox,
             };
         }
         const changes = input.checkout.changes();
@@ -63,12 +103,76 @@ export function verifyDeliveryPromotionGates(input) {
                 commands,
                 failureCode: "verification-worktree-contaminated",
                 logPath: relativeCommandLogPath(input.projectRoot, result.logPath),
+                sandbox: ctx.sandbox,
             };
         }
     }
+    return { status: "passed", commands, sandbox: ctx.sandbox };
+}
+/**
+ * Builds the real {@link RunSandboxedGate}. `cleanupSandbox` is a test-only
+ * seam (defaults to the real {@link cleanupSandboxCommand}) so unit tests can
+ * force the fail-closed "passing gate, leaky sandbox" path without a real srt
+ * backend; every non-test caller gets the real cleanup and byte-identical
+ * behavior to before this seam existed.
+ */
+export function createRunSandboxedGate(cleanupSandbox = cleanupSandboxCommand) {
+    return async (args) => {
+        const startedAt = Date.now();
+        const env = buildSandboxedGateEnv(args.runTmpDir);
+        let invocation;
+        try {
+            invocation = resolveInvocationFromCommand(args.executionRoot, args.command, env, {
+                replaceProcessEnv: true,
+            });
+        }
+        catch (error) {
+            return rejectedInvocationResult(args.command, args.logRoot, startedAt, error);
+        }
+        let result;
+        try {
+            // The wrap is INSIDE the try so a wrap failure (unresolvable srt, empty
+            // argv) still produces a persisted failed verification instead of escaping.
+            const wrapped = await wrapGateForSandbox(invocation, {
+                checkoutRoot: realpathSync(args.executionRoot),
+                runTmpDir: realpathSync(args.runTmpDir),
+                projectRoot: args.projectRoot,
+            });
+            result = await runResolvedInvocationAsync({ command: wrapped.command, args: [...wrapped.args], env: wrapped.env }, {
+                command: args.command,
+                executionRoot: args.executionRoot,
+                logRoot: args.logRoot,
+                startedAt,
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+        }
+        catch (error) {
+            result = rejectedInvocationResult(args.command, args.logRoot, startedAt, error);
+        }
+        // Sandbox cleanup is part of the gate's integrity: an unbalanced srt counter
+        // or leftover mounts must NOT be reported as a clean pass. If cleanup fails
+        // after an otherwise-passing gate, convert the result to a failed
+        // verification and keep the gate output as secondary evidence. A gate that
+        // already failed keeps its more-informative primary failure.
+        try {
+            await cleanupSandbox();
+        }
+        catch (error) {
+            if (result.outcome === "passed")
+                return sandboxCleanupFailedResult(result, error);
+        }
+        return result;
+    };
+}
+const defaultRunSandboxedGate = createRunSandboxedGate();
+function sandboxCleanupFailedResult(gateResult, error) {
+    const message = error instanceof Error ? error.message : String(error);
     return {
-        status: "passed",
-        commands,
+        ...gateResult,
+        outcome: "failed",
+        failureCode: "sandbox-cleanup-failed",
+        errorMessage: `sandbox cleanup did not complete after a passing gate: ${message}`,
+        stderr: `${gateResult.stderr}\n[sandbox-cleanup-failed] ${message}`.trim(),
     };
 }
 export function verificationPromptSummary(verification) {
@@ -77,7 +181,7 @@ export function verificationPromptSummary(verification) {
     if (verification.status !== "passed")
         return undefined;
     return [
-        "Host verification before outside review: passed.",
+        `Host verification before outside review: passed (sandbox: ${verification.sandbox ?? "unknown"}).`,
         ...verification.commands.map((command, index) => `${index + 1}. ${command.command}: ${command.outcome === "deferred" ? "deferred until review publication" : "passed"}`),
     ].join("\n");
 }
@@ -97,6 +201,8 @@ export function verificationArtifactSection(verification) {
         "## Host Verification",
         "",
         `Status: ${verification.status}`,
+        `Sandbox: ${verification.sandbox ?? "unknown"}`,
+        ...(verification.sandboxReason ? [`Sandbox detail: ${verification.sandboxReason}`] : []),
         ...verification.commands.map((command, index) => `${index + 1}. ${command.command} -> ${command.outcome} (${command.durationMs}ms, exit ${command.exitCode ?? "null"})`),
         ...(verification.failureCode ? [`Failure code: ${verification.failureCode}`] : []),
         ...(verification.logPath ? [`Log: ${verification.logPath}`] : []),

package/dist/esm/review/execution/review-checkout.d.ts

@@ -6,6 +6,7 @@ export interface ReviewTargetCheckout {
 }
 declare function statusEntryPath(line: string): string;
 export declare function createReviewTargetCheckout(repositoryRoot: string, targetSha: string): ReviewTargetCheckout;
+export declare function assertDependencyContainment(checkoutRoot: string): void;
 /** Test-only surface for porcelain path parsing. */
 export declare const reviewCheckoutInternals: {
     statusEntryPath: typeof statusEntryPath;