swallowkit 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/core/verify/index.ts

@@ -5,16 +5,17 @@
  * - structure:  プロジェクト構造規約 (validateProject)
  * - drift:      生成物と現在状態の乖離 (detectDrift)
  * - typecheck:  TypeScript 型チェック (tsc --noEmit / typecheck script)
+ * - backend-build: standalone Functions のコンパイル (C#/TypeScript) または構文検証 (Python)
  * - build/lint/test: package.json scripts に同名 script がある場合のみ実行 (なければ skip)
  * - custom:     swallowkit.config の verify.checks で定義されたプロジェクト固有チェック
  *
- * 既定実行セットは structure/drift/typecheck + custom。build/lint/test は --checks で明示指定。
+ * 既定実行セットは structure/drift/typecheck/backend-build + custom。build/lint/test は --checks で明示指定。
  */
 
 import * as fs from "fs";
 import * as path from "path";
 import { spawnSync } from "child_process";
-import { loadConfig } from "../config";
+import { loadConfig, loadConfigFromEnv } from "../config";
 import { detectDrift, DriftFinding } from "../project/drift";
 import { saveLastVerifyState } from "../project/state";
 import { ProjectViolation, validateProject } from "../project/validation";
@@ -60,11 +61,11 @@ export interface VerifyResult {
   verifiedAt: string;
 }
 
-export const AVAILABLE_VERIFY_CHECKS = ["structure", "drift", "typecheck", "build", "lint", "test"] as const;
+export const AVAILABLE_VERIFY_CHECKS = ["structure", "drift", "typecheck", "backend-build", "build", "lint", "test"] as const;
 export type VerifyCheckId = (typeof AVAILABLE_VERIFY_CHECKS)[number];
 
 /** 既定で実行される built-in チェック。build/lint/test は明示指定時のみ。 */
-export const DEFAULT_VERIFY_CHECKS = ["structure", "drift", "typecheck"] as const;
+export const DEFAULT_VERIFY_CHECKS = ["structure", "drift", "typecheck", "backend-build"] as const;
 
 async function runStructureCheck(projectRoot: string): Promise<VerifyCheckResult> {
   const startedAt = Date.now();
@@ -137,6 +138,7 @@ interface CommandCheckSpec {
   args: string[];
   timeoutMs?: number;
   failAction: string;
+  shell?: boolean;
 }
 
 function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyCheckResult {
@@ -145,9 +147,10 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
   try {
     const result = spawnSync(spec.command, spec.args, {
       cwd: projectRoot,
-      shell: true,
+      shell: spec.shell ?? true,
       encoding: "utf-8",
       timeout: spec.timeoutMs ?? 5 * 60 * 1000,
+      maxBuffer: 10 * 1024 * 1024,
     });
 
     const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
@@ -180,6 +183,11 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
         command: commandLabel,
         exitCode,
         logTail: tailLines(output, 50),
+        ...(spec.id === "backend-build" ? {
+          diagnostics: [...new Set(output.split(/\r?\n/).filter((line) =>
+            /\(\d+,\d+\):\s*error\s+\w+/.test(line) ||
+            /^\s*(File ".+", line \d+|(?:Sorry: )?(?:Syntax|Indentation|Tab)Error:|\*\*\* Error compiling)/.test(line)))],
+        } : {}),
       },
       suggestedActions: exitCode === 0 ? [] : [spec.failAction],
     };
@@ -201,6 +209,86 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
   }
 }
 
+function backendUnavailable(reason: string): VerifyCheckResult {
+  return {
+    id: "backend-build",
+    title: "Standalone Functions compilation",
+    status: "skip",
+    durationMs: 0,
+    fixable: false,
+    evidence: { logTail: [reason], diagnostics: [reason] },
+    suggestedActions: ["Install or restore the backend toolchain, then re-run verify with --checks \"backend-build\". A skipped check is not backend validation."],
+  };
+}
+
+function runBackendBuildCheck(projectRoot: string): VerifyCheckResult {
+  const functionsRoot = path.join(projectRoot, "functions");
+  if (!fs.existsSync(functionsRoot)) return backendUnavailable("functions/ not found; no standalone backend was checked.");
+  const configPath = ["swallowkit.config.json", "swallowkit.config.js", ".swallowkitrc.json"]
+    .map((name) => path.join(projectRoot, name)).find((file) => fs.existsSync(file));
+  if (!configPath) return backendUnavailable("SwallowKit configuration not found; backend language is unknown.");
+  // Same effective language as generation (getBackendLanguage): env override, then file, invalid -> typescript.
+  const configured = loadConfigFromEnv().backend?.language ?? loadConfig(configPath, true, true).backend?.language;
+  const language = configured && ["typescript", "csharp", "python"].includes(configured) ? configured : "typescript";
+  let command: string;
+  let args: string[];
+  if (language === "csharp") {
+    command = "dotnet";
+    args = ["build", "--nologo"];
+    const probe = spawnSync(command, ["--version"], { cwd: functionsRoot, encoding: "utf-8", timeout: 30_000 });
+    if (probe.error && "code" in probe.error && probe.error.code === "ENOENT") return backendUnavailable("dotnet SDK is not installed or is not on PATH; C# compilation was skipped.");
+  } else if (language === "python") {
+    const venvPython = process.platform === "win32"
+      ? path.join(functionsRoot, ".venv", "Scripts", "python.exe")
+      : path.join(functionsRoot, ".venv", "bin", "python");
+    const candidates = fs.existsSync(venvPython)
+      ? [{ command: venvPython, args: [] as string[] }]
+      : process.platform === "win32"
+        ? [{ command: "python", args: [] }, { command: "python3", args: [] }, { command: "py", args: ["-3"] }]
+        : [{ command: "python3", args: [] }, { command: "python", args: [] }];
+    const python = candidates.find((candidate) => {
+      const probe = spawnSync(candidate.command, [...candidate.args, "-c", "import sys; sys.exit(0 if sys.version_info.major == 3 else 1)"], {
+        cwd: functionsRoot, encoding: "utf-8", timeout: 30_000,
+      });
+      // Preserve execution errors for an installed interpreter instead of silently falling back.
+      return probe.status === 0 || (probe.error && (!("code" in probe.error) || probe.error.code !== "ENOENT"));
+    });
+    if (!python) return backendUnavailable("Python 3 is not available in functions/.venv or on PATH; Python syntax compilation was skipped.");
+    command = python.command;
+    // -f: never trust cached bytecode, which can survive same-size edits within one mtime second.
+    args = [...python.args, "-m", "compileall", "-q", "-f", "-x", "[/\\\\](?:\\.venv|\\.codegen-venv|node_modules|__pycache__)(?:[/\\\\]|$)", "."];
+  } else {
+    let tscPath: string;
+    try {
+      tscPath = require.resolve("typescript/bin/tsc", { paths: [functionsRoot] });
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND") {
+        return backendUnavailable("The project's TypeScript compiler is not installed; restore dependencies before verifying functions/.");
+      }
+      throw error;
+    }
+    const sharedBuild = runSharedBuildIfPresent(projectRoot);
+    if (sharedBuild.ran && !sharedBuild.ok) {
+      return {
+        id: "backend-build", title: "Standalone Functions compilation", status: sharedBuild.unavailable ? "error" : "fail",
+        durationMs: 0, fixable: !sharedBuild.unavailable,
+        evidence: { command: sharedBuild.command, logTail: sharedBuild.logTail,
+          ...(sharedBuild.unavailable ? { errorCode: "verification-command-unavailable" as const } : {}) },
+        suggestedActions: ["Fix the shared package build before compiling the TypeScript backend."],
+      };
+    }
+    command = process.execPath;
+    args = [tscPath, "--project", "tsconfig.json", "--noEmit"];
+  }
+  const result = runCommandCheck(functionsRoot, {
+    id: "backend-build", title: "Standalone Functions compilation", command, args, shell: false,
+    timeoutMs: 10 * 60 * 1000,
+    failAction: "Fix the backend compilation errors in evidence.diagnostics / evidence.logTail, then re-run verify.",
+  });
+  result.evidence.command = `${result.evidence.command} (in functions/)`;
+  return result;
+}
+
 function readPackageScripts(projectRoot: string): Record<string, string> {
   const packageJsonPath = path.join(projectRoot, "package.json");
   if (!fs.existsSync(packageJsonPath)) return {};
@@ -430,6 +518,8 @@ export async function runVerify(
       checks.push(await runDriftCheck(projectRoot));
     } else if (id === "typecheck") {
       checks.push(runTypecheckCheck(projectRoot));
+    } else if (id === "backend-build") {
+      checks.push(runBackendBuildCheck(projectRoot));
     } else if (id === "build" || id === "lint" || id === "test") {
       checks.push(runScriptCheck(projectRoot, id));
     } else {

package/src/machine/contracts.ts

@@ -23,6 +23,7 @@ export interface MachineErrorResponse {
   ok: false;
   command: string;
   status?: MachineOperationStatus;
+  nextActions?: MachineNextAction[];
   error: {
     code: string;
     message: string;

package/src/machine/errors.ts

@@ -1,16 +1,18 @@
-import type { MachineOperationStatus } from "./contracts";
+import type { MachineNextAction, MachineOperationStatus } from "./contracts";
 
 export class MachineCommandError extends Error {
   readonly code: string;
   readonly details?: unknown;
   readonly status?: MachineOperationStatus;
+  readonly nextActions?: MachineNextAction[];
 
-  constructor(code: string, message: string, details?: unknown, status?: MachineOperationStatus) {
+  constructor(code: string, message: string, details?: unknown, status?: MachineOperationStatus, nextActions?: MachineNextAction[]) {
     super(message);
     this.name = "MachineCommandError";
     this.code = code;
     this.details = details;
     this.status = status;
+    this.nextActions = nextActions;
   }
 }
 

package/src/machine/index.ts

@@ -3,7 +3,7 @@ import { isSwallowKitProject } from "../core/config";
 import { createModelOperation } from "../core/operations/create-model";
 import { applyScaffoldOperation } from "../core/operations/scaffold-apply";
 import { applyAuthOperation, planAuthOperation } from "../core/operations/auth-operations";
-import { applyProvisionOperation, planProvisionOperation } from "../core/operations/provision-operations";
+import { applyProvisionOperation, inspectProvisionOperation, planProvisionOperation } from "../core/operations/provision-operations";
 import { ProcessExitInterceptError } from "../core/operations/runtime";
 import { inspectInfra } from "../core/project/infra";
 import { runMachineScaffoldOperation } from "../core/operations/scaffold-machine";
@@ -58,6 +58,7 @@ function writeMachineError(command: string, error: unknown): void {
     ok: false,
     command,
     status: resolveMachineErrorStatus(error),
+    ...(error instanceof MachineCommandError && error.nextActions?.length ? { nextActions: error.nextActions } : {}),
     error: toMachineError(error),
   };
   writeMachineResponse(response);
@@ -140,6 +141,17 @@ function createMachineProgram(): Command {
     .showHelpAfterError(false);
 
   const inspect = new Command("inspect");
+  inspect
+    .command("provision")
+    .description("Read/wait for an original provision deployment without writes or replay")
+    .requiredOption("--plan <runId>", "Original provision plan/execution checkpoint ID")
+    .option("--wait-seconds <seconds>", "Bounded read-only wait, 0-3600 seconds (default: 0)", Number)
+    .action(async (options: { plan: string; waitSeconds?: number }) => {
+      await handleMachineAction("inspect-provision", async () => {
+        ensureProjectForMachine();
+        return inspectProvisionOperation({ planId: options.plan, waitSeconds: options.waitSeconds });
+      }, (result) => ({ status: result.status, nextActions: result.nextActions }));
+    });
   inspect
     .command("project")
     .description("Inspect SwallowKit project metadata")
@@ -372,7 +384,7 @@ function createMachineProgram(): Command {
 
   plan
     .command("provision")
-    .description("Preflight Azure provisioning locally; use --what-if for an az what-if analysis (requires az login)")
+    .description("Review local infrastructure and current Azure state without writes (requires az login)")
     .requiredOption("-g, --resource-group <name>", "Resource group name")
     .requiredOption("--location <region>", "Primary location for Functions and Cosmos DB")
     .requiredOption("--swa-location <region>", "Static Web App location")
@@ -381,7 +393,8 @@ function createMachineProgram(): Command {
     .option("--adopt-existing", "Adopt an existing untagged resource group without deploying main.bicep", false)
     .option("--baseline <version>", "Baseline version for adoption", (value) => Number(value))
     .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
-    .action(async (options: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean }) => {
+    .option("--resume-deployment <name>", "Recover a matching older baseline deployment without re-submitting Bicep")
+    .action(async (options: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean; resumeDeployment?: string }) => {
       await handleMachineAction(
         "plan-provision",
         async () => {
@@ -395,6 +408,7 @@ function createMachineProgram(): Command {
             adoptExisting: options.adoptExisting,
             baseline: options.baseline,
             reconcile: options.reconcile,
+            resumeDeployment: options.resumeDeployment,
           });
         },
         (planData) => ({
@@ -545,32 +559,25 @@ function createMachineProgram(): Command {
     .description("Apply an approved provisioning plan (always requires --approve; creates billable Azure resources)")
     .requiredOption("--plan <planId>", "Provision plan to apply")
     .option("--approve", "Confirm human approval of the provisioning plan", false)
-    .action(async (options: { plan: string; approve?: boolean }) => {
+    .option("--wait-seconds <seconds>", "Bounded state wait, 0-3600 seconds (default: 300)", Number)
+    .action(async (options: { plan: string; approve?: boolean; waitSeconds?: number }) => {
       await handleMachineAction(
         "apply-provision",
         async () => {
           ensureProjectForMachine();
-          return applyProvisionOperation({ planId: options.plan, approve: options.approve });
+          return applyProvisionOperation({ planId: options.plan, approve: options.approve, waitSeconds: options.waitSeconds });
         },
-        () => ({
-          status: "complete",
-          nextActions: [
-            {
-              command: "swallowkit machine inspect infra",
-              description: "Re-inspect infra assets after provisioning.",
-            },
-          ],
-        })
+        (result) => ({ status: result.status, nextActions: result.nextActions })
       );
     });
 
   const verify = new Command("verify");
   verify
     .command("project")
-    .description("Run verification checks (structure, drift, typecheck) with machine-readable evidence")
+    .description("Run verification checks (structure, drift, typecheck, backend-build) with machine-readable evidence")
     .option(
       "--checks <ids>",
-      "Comma-separated check ids to run (structure,drift,typecheck,build,lint,test, plus custom ids from swallowkit.config verify.checks)"
+      "Comma-separated check ids to run (structure,drift,typecheck,backend-build,build,lint,test, plus custom ids from swallowkit.config verify.checks); quote CSV values in PowerShell"
     )
     .option("--compact", "Suppress info-severity findings/violations from evidence to keep agent-facing output small", false)
     .action(async (options: { checks?: string; compact?: boolean }) => {

package/src/mcp/index.ts

@@ -5,9 +5,10 @@ import * as path from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
-import type { MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
+import type { MachineErrorResponse, MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
 import { getSwallowKitVersion } from "../version";
 import { detectFromProject, getCommands } from "../utils/package-manager";
+import { provisionNextActions } from "../core/operations/provision-operations";
 import {
   MCP_DELEGATED_FROM_ENV,
   McpVersionContext,
@@ -24,13 +25,18 @@ interface MachineSuccessPayload<TData> {
   data: TData;
 }
 
-type MachineCliRunner = (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
-type ToolContentResult = { content: Array<{ type: "text"; text: string }> };
+type MachineCliRunner = (args: string[], signal?: AbortSignal) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+type ToolContentResult = { content: Array<{ type: "text"; text: string }>; isError?: boolean };
+class MachineCliError extends Error {
+  constructor(message: string, readonly response: MachineErrorResponse) {
+    super(message);
+  }
+}
 type ToolDefinition = {
   name: string;
   description: string;
   inputSchema: z.ZodTypeAny;
-  handler: (input: any) => Promise<ToolContentResult>;
+  handler: (input: any, signal?: AbortSignal) => Promise<ToolContentResult>;
 };
 type ExecaModule = typeof import("execa");
 
@@ -43,29 +49,45 @@ function resolveMachineCliEntrypoint(): string {
   return path.resolve(__dirname, "..", "cli", "index.js");
 }
 
-async function defaultMachineCliRunner(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+async function defaultMachineCliRunner(args: string[], signal?: AbortSignal): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   const { execa } = await importModule("execa");
-  const result = await execa(process.execPath, [resolveMachineCliEntrypoint(), "machine", ...args], {
+  const child = execa(process.execPath, [resolveMachineCliEntrypoint(), "machine", ...args], {
     reject: false,
   });
-
+  const abort = () => child.kill("SIGTERM", { forceKillAfterTimeout: 6_000 });
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted) abort();
+  let result: Awaited<typeof child>;
+  try { result = await child; } finally { signal?.removeEventListener("abort", abort); }
   return {
     stdout: result.stdout,
     stderr: result.stderr,
-    exitCode: result.exitCode ?? 0,
+    exitCode: result.exitCode ?? 1,
   };
 }
 
 async function executeMachineCommand<TData>(
   args: string[],
-  runMachineCli: MachineCliRunner
+  runMachineCli: MachineCliRunner,
+  signal?: AbortSignal
 ): Promise<MachineSuccessPayload<TData>> {
-  const result = await runMachineCli(args);
+  const interrupted = () => {
+    const runId = args[args.indexOf("--plan") + 1];
+    const response: MachineErrorResponse = {
+      ok: false, command: args.slice(0, 2).join("-"), status: "blocked",
+      error: { code: "provision-interrupted", message: "The local MCP wait was interrupted. Azure may continue; inspect the original checkpoint. No Azure cancellation or successful result is implied.", details: { runId, outcome: "unknown", localFailure: "cancelled" } },
+      nextActions: /^[a-f0-9]{12}$/.test(runId) ? provisionNextActions(runId) : [],
+    };
+    return new MachineCliError(response.error.message, response);
+  };
+  if (signal?.aborted) throw interrupted();
+  const result = await (signal ? runMachineCli(args, signal) : runMachineCli(args));
 
   let parsed: MachineResponse<TData>;
   try {
     parsed = JSON.parse(result.stdout) as MachineResponse<TData>;
   } catch {
+    if (signal?.aborted) throw interrupted();
     throw new Error(result.stderr || result.stdout || "Machine CLI returned invalid JSON.");
   }
 
@@ -73,7 +95,7 @@ async function executeMachineCommand<TData>(
     const detailsSuffix =
       parsed.error.details !== undefined ? `\ndetails: ${JSON.stringify(parsed.error.details)}` : "";
     const statusSuffix = parsed.status ? ` (status: ${parsed.status})` : "";
-    throw new Error(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`);
+    throw new MachineCliError(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`, parsed);
   }
 
   return parsed;
@@ -308,7 +330,7 @@ export function buildSwallowKitToolDefinitions(
     },
     {
       name: "swallowkit_verify_project",
-      description: "Run verification checks (structure, drift, typecheck by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. summary.done=true means the project passed all checks. Set compact=true to suppress info-severity findings and keep the output small.",
+      description: "Run verification checks (structure, drift, typecheck, backend-build by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. backend-build compiles standalone C#/TypeScript Functions or checks Python syntax; unavailable toolchains are skipped with a reason. summary.done=true means no checks failed, not that skipped checks were validated or runtime/auth flows work. Set compact=true to suppress info-severity findings and keep the output small.",
       inputSchema: z.object({
         checks: z.array(z.string()).optional(),
         compact: z.boolean().optional(),
@@ -418,14 +440,16 @@ export function buildSwallowKitToolDefinitions(
         adoptExisting: z.boolean().optional(),
         baseline: z.number().int().nonnegative().optional(),
         reconcile: z.boolean().optional(),
+        resumeDeployment: z.string().optional(),
       }),
-      handler: async ({ resourceGroup, location, swaLocation, subscription, whatIf, adoptExisting, baseline, reconcile }: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean }) => {
+      handler: async ({ resourceGroup, location, swaLocation, subscription, whatIf, adoptExisting, baseline, reconcile, resumeDeployment }: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean; resumeDeployment?: string }) => {
         const args = ["plan", "provision", "--resource-group", resourceGroup, "--location", location, "--swa-location", swaLocation];
         if (subscription) args.push("--subscription", subscription);
         if (whatIf) args.push("--what-if");
         if (adoptExisting) args.push("--adopt-existing");
         if (baseline !== undefined) args.push("--baseline", String(baseline));
         if (reconcile) args.push("--reconcile");
+        if (resumeDeployment) args.push("--resume-deployment", resumeDeployment);
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -433,16 +457,32 @@ export function buildSwallowKitToolDefinitions(
     },
     {
       name: "swallowkit_apply_provision",
-      description: "Apply an approved provisioning plan. Creates billable Azure resources; approve=true is always required and must reflect explicit human consent.",
+      description: "Apply or resume an approved provision checkpoint with bounded state polling. Never resubmit an attempted deployment; finish tags/ledger only after Azure Succeeded. Check status/nextActions, not just ok. approve=true always requires explicit human consent.",
       inputSchema: z.object({
         planId: z.string(),
         approve: z.boolean().optional(),
+        waitSeconds: z.number().int().min(0).max(3600).optional(),
       }),
-      handler: async ({ planId, approve }: { planId: string; approve?: boolean }) => {
+      handler: async ({ planId, approve, waitSeconds }: { planId: string; approve?: boolean; waitSeconds?: number }, signal?: AbortSignal) => {
         const args = ["apply", "provision", "--plan", planId];
         if (approve) args.push("--approve");
+        if (waitSeconds !== undefined) args.push("--wait-seconds", String(waitSeconds));
 
-        const response = await executeMachineCommand(args, runMachineCli);
+        const response = await executeMachineCommand(args, runMachineCli, signal);
+        return jsonTextContent(withOperationStatus(response));
+      },
+    },
+    {
+      name: "swallowkit_inspect_provision",
+      description: "Read or bounded-wait for the original provision deployment. No create, cancel, delete, tag, or ledger writes. Azure Succeeded alone is partial until the original approved checkpoint finishes bookkeeping.",
+      inputSchema: z.object({
+        planId: z.string(),
+        waitSeconds: z.number().int().min(0).max(3600).optional(),
+      }),
+      handler: async ({ planId, waitSeconds }: { planId: string; waitSeconds?: number }, signal?: AbortSignal) => {
+        const args = ["inspect", "provision", "--plan", planId];
+        if (waitSeconds !== undefined) args.push("--wait-seconds", String(waitSeconds));
+        const response = await executeMachineCommand(args, runMachineCli, signal);
         return jsonTextContent(withOperationStatus(response));
       },
     },
@@ -451,9 +491,17 @@ export function buildSwallowKitToolDefinitions(
   // Every response reports which SwallowKit version answered and why it was selected.
   return definitions.map((definition) => ({
     ...definition,
-    handler: async (input: unknown) => {
-      const result = await definition.handler(input);
-      return jsonTextContent(withSwallowKitMetadata(JSON.parse(result.content[0].text)));
+    handler: async (input: unknown, signal?: AbortSignal) => {
+      try {
+        const result = await definition.handler(input, signal);
+        return jsonTextContent(withSwallowKitMetadata(JSON.parse(result.content[0].text)));
+      } catch (error) {
+        // Prerequisite failures carry nextActions; keep them structured so agents can follow them.
+        if (error instanceof MachineCliError && error.response.nextActions?.length) {
+          return { ...jsonTextContent(withSwallowKitMetadata(error.response)), isError: true };
+        }
+        throw error;
+      }
     },
   }));
 }
@@ -475,7 +523,7 @@ export function createSwallowKitMcpServer(
         description: tool.description,
         inputSchema: tool.inputSchema,
       },
-      tool.handler
+      (input, extra) => tool.handler(input, extra.signal)
     );
   }