@sakupa/mcp 0.7.44 → 0.7.46

package/dist/index.js

@@ -125,7 +125,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.44";
+var SAKUPA_MCP_VERSION = "0.7.46";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -736,8 +736,8 @@ var HttpApiClient = class {
       body: body?.slice(0, 200)
     });
   }
-  async registerDevice() {
-    return this.call("POST", "/v1/devices");
+  async registerDevice(req) {
+    return this.call("POST", "/v1/devices", { body: req });
   }
   async listDeviceFreeSites(deviceId, credential) {
     return this.call("GET", "/v1/devices/free-sites", {
@@ -1995,6 +1995,24 @@ function boundDiagnostics(processCwd, selected, snapshot = { supported: false, r
 
 // src/tools/result.ts
 import { z } from "zod";
+var TARGET_MCP_TOOL_NAMES = [
+  "init",
+  "help",
+  "analyze",
+  "deploy",
+  "refresh",
+  "status",
+  "rotate",
+  "plans",
+  "subscribe",
+  "bind",
+  "billing",
+  "portal",
+  "recover",
+  "change",
+  "support",
+  "report"
+];
 var STRUCTURED_TOOL_OUTPUT_SCHEMA = {
   schemaVersion: z.literal(1),
   outcome: z.enum([
@@ -2010,13 +2028,41 @@ var STRUCTURED_TOOL_OUTPUT_SCHEMA = {
   operationId: z.string().optional(),
   summary: z.string(),
   data: z.record(z.string(), z.unknown()),
+  decision: z.object({
+    decisionVersion: z.literal(1),
+    prompt: z.string(),
+    selectionMode: z.literal("single"),
+    selectionRequired: z.literal(true),
+    defaultOptionId: z.null(),
+    options: z.array(
+      z.object({
+        id: z.string(),
+        label: z.string(),
+        description: z.string(),
+        consequences: z.array(z.string()),
+        nextAction: z.discriminatedUnion("type", [
+          z.object({
+            type: z.literal("call_tool"),
+            tool: z.enum(TARGET_MCP_TOOL_NAMES),
+            arguments: z.record(z.string(), z.unknown()),
+            reasonCode: z.string().optional()
+          }),
+          z.object({ type: z.literal("open_url"), url: z.string() }),
+          z.object({ type: z.literal("none") })
+        ])
+      })
+    )
+  }).optional(),
   userAction: z.object({
     type: z.enum(["open_url", "confirm_in_mcp", "configure_dns", "select_site"]),
     provider: z.enum(["stripe", "sakupa"]).optional(),
     url: z.string().optional(),
     expiresAt: z.string().optional(),
     expectedOutcome: z.string(),
-    resumeWith: z.object({ tool: z.string(), arguments: z.record(z.string(), z.unknown()) }).optional(),
+    resumeWith: z.object({
+      tool: z.enum(TARGET_MCP_TOOL_NAMES),
+      arguments: z.record(z.string(), z.unknown())
+    }).optional(),
     options: z.array(
       z.object({
         label: z.string(),
@@ -2027,7 +2073,7 @@ var STRUCTURED_TOOL_OUTPUT_SCHEMA = {
   }).optional(),
   nextActions: z.array(
     z.object({
-      tool: z.string(),
+      tool: z.enum(TARGET_MCP_TOOL_NAMES),
       arguments: z.record(z.string(), z.unknown()).optional(),
       allowed: z.boolean(),
       reasonCode: z.string().optional()
@@ -2211,7 +2257,7 @@ function toolError(e) {
 }
 
 // src/tools/definitions.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
+import { randomUUID as randomUUID6 } from "node:crypto";
 import { promises as fs2 } from "node:fs";
 import { join as join9, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
 import { z as z2 } from "zod";
@@ -2939,6 +2985,7 @@ import {
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync4
 } from "node:fs";
+import { randomUUID as randomUUID4 } from "node:crypto";
 import { homedir as homedir3 } from "node:os";
 import { dirname as dirname4, join as join6 } from "node:path";
 var DEVICE_LOCK_STALE_MS = 3e4;
@@ -2948,10 +2995,22 @@ function deviceRegistryPath() {
   return join6(base, ".sakupa", "devices.json");
 }
 var deviceLockPath = () => join6(dirname4(deviceRegistryPath()), "devices.lock");
-function releaseDeviceLock(fd2) {
+function lockTokenAt(path) {
   try {
-    closeSync(fd2);
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    return typeof parsed.token === "string" ? parsed.token : null;
+  } catch {
+    return null;
+  }
+}
+function ownsDeviceLock(lock) {
+  return lockTokenAt(deviceLockPath()) === lock.token;
+}
+function releaseDeviceLock(lock) {
+  try {
+    closeSync(lock.fd);
   } finally {
+    if (!ownsDeviceLock(lock)) return;
     try {
       unlinkSync2(deviceLockPath());
     } catch {
@@ -2966,9 +3025,13 @@ async function acquireDeviceLock(apiBaseUrl) {
     const existing = loadDeviceBinding(apiBaseUrl);
     if (existing) return existing;
     try {
+      const token = randomUUID4();
       const fd2 = openSync(path, "wx", 384);
-      writeFileSync4(fd2, JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }));
-      return fd2;
+      writeFileSync4(
+        fd2,
+        JSON.stringify({ token, pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })
+      );
+      return { fd: fd2, token };
     } catch {
       try {
         if (Date.now() - statSync2(path).mtimeMs >= DEVICE_LOCK_STALE_MS) {
@@ -2989,13 +3052,16 @@ async function acquireDeviceLock(apiBaseUrl) {
 }
 function readRegistry() {
   const path = deviceRegistryPath();
-  if (!existsSync5(path)) return { schemaVersion: 1, environments: {} };
+  if (!existsSync5(path)) {
+    return { schemaVersion: 1, environments: {}, pendingRegistrations: {} };
+  }
   try {
     const parsed = JSON.parse(readFileSync4(path, "utf8"));
     if (parsed.schemaVersion !== 1 || !parsed.environments || typeof parsed.environments !== "object") {
       throw new Error("unsupported device registry schema");
     }
-    return { schemaVersion: 1, environments: parsed.environments };
+    const pendingRegistrations = "pendingRegistrations" in parsed && parsed.pendingRegistrations && typeof parsed.pendingRegistrations === "object" ? parsed.pendingRegistrations : {};
+    return { schemaVersion: 1, environments: parsed.environments, pendingRegistrations };
   } catch (error) {
     throw new Error(
       `Sakupa device registry is unreadable at ${path}: ${error instanceof Error ? error.message : String(error)}. Run help; do not search old project directories.`
@@ -3024,19 +3090,38 @@ async function ensureDeviceBinding(client, apiBaseUrl) {
   const existing = loadDeviceBinding(apiBaseUrl);
   if (existing) return existing;
   const lock = await acquireDeviceLock(apiBaseUrl);
-  if (typeof lock !== "number") return lock;
+  if (!("fd" in lock)) return lock;
   try {
     const afterLock = loadDeviceBinding(apiBaseUrl);
     if (afterLock) return afterLock;
-    const created = await client.registerDevice();
-    const registry = readRegistry();
+    let registry = readRegistry();
+    let pending = registry.pendingRegistrations[apiBaseUrl];
+    if (!pending) {
+      pending = {
+        operationId: randomUUID4(),
+        deviceId: randomUUID4(),
+        credential: generateCredential(),
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      registry.pendingRegistrations[apiBaseUrl] = pending;
+      writeRegistry(registry);
+    }
+    const created = await client.registerDevice({
+      operationId: pending.operationId,
+      deviceId: pending.deviceId,
+      credential: pending.credential
+    });
     const binding = {
       deviceId: created.deviceId,
       credential: created.credential,
       createdAt: created.createdAt
     };
-    registry.environments[apiBaseUrl] = binding;
-    writeRegistry(registry);
+    if (ownsDeviceLock(lock)) {
+      registry = readRegistry();
+      registry.environments[apiBaseUrl] = binding;
+      delete registry.pendingRegistrations[apiBaseUrl];
+      writeRegistry(registry);
+    }
     return binding;
   } finally {
     releaseDeviceLock(lock);
@@ -3321,7 +3406,7 @@ import {
   rmSync as rmSync2,
   writeFileSync as writeFileSync6
 } from "node:fs";
-import { randomUUID as randomUUID4 } from "node:crypto";
+import { randomUUID as randomUUID5 } from "node:crypto";
 import { join as join8 } from "node:path";
 var ROTATION_FILE = "rotation.json";
 function credentialRotationPath(projectDir) {
@@ -3382,7 +3467,7 @@ function writeCredentialRotation(projectDir, file) {
   const directory = join8(projectDir, ".sakupa");
   mkdirSync6(directory, { recursive: true, mode: 448 });
   const target = credentialRotationPath(projectDir);
-  const temporary = join8(directory, `.rotation-${randomUUID4()}.tmp`);
+  const temporary = join8(directory, `.rotation-${randomUUID5()}.tmp`);
   writeFileSync6(temporary, `${JSON.stringify(file, null, 2)}
 `, {
     encoding: "utf8",
@@ -3477,6 +3562,176 @@ async function resumeCredentialRotation(client, projectDir, site, apiBaseUrl) {
   };
 }
 
+// src/tools/decision.ts
+var FORBIDDEN_DECISION_ARGUMENT_KEYS = /* @__PURE__ */ new Set([
+  "credential",
+  "candidatecredential",
+  "devicecredential",
+  "password",
+  "secret",
+  "privatekey",
+  "accesstoken",
+  "refreshtoken"
+]);
+function assertDecisionArgumentsSafe(value, path = "arguments") {
+  if (typeof value === "string") {
+    if (/^sk_[A-Za-z0-9_-]{20,}$/.test(value)) {
+      throw new Error(`Decision ${path} contains a credential-like value.`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertDecisionArgumentsSafe(entry, `${path}[${index}]`));
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const [key, entry] of Object.entries(value)) {
+    const normalizedKey = key.replace(/[_-]/g, "").toLowerCase();
+    if (FORBIDDEN_DECISION_ARGUMENT_KEYS.has(normalizedKey)) {
+      throw new Error(`Decision ${path}.${key} contains a forbidden secret field.`);
+    }
+    assertDecisionArgumentsSafe(entry, `${path}.${key}`);
+  }
+}
+function buildDecisionContract(prompt, options) {
+  const normalizedPrompt = prompt.trim();
+  if (!normalizedPrompt) throw new Error("Decision prompt must not be empty.");
+  if (options.length < 2) throw new Error("A decision must contain at least two options.");
+  const ids = /* @__PURE__ */ new Set();
+  let actionableOptions = 0;
+  let noActionOptions = 0;
+  for (const option of options) {
+    if (!/^[a-z][a-z0-9_]*$/.test(option.id)) {
+      throw new Error(`Invalid decision option id: ${option.id}`);
+    }
+    if (ids.has(option.id)) throw new Error(`Duplicate decision option id: ${option.id}`);
+    ids.add(option.id);
+    if (!option.label.trim() || !option.description.trim()) {
+      throw new Error(`Decision option ${option.id} requires a label and description.`);
+    }
+    if (option.nextAction.type === "none") {
+      noActionOptions += 1;
+      continue;
+    }
+    actionableOptions += 1;
+    if (option.nextAction.type === "call_tool" && !TARGET_MCP_TOOL_NAMES.includes(option.nextAction.tool)) {
+      throw new Error(`Unknown MCP decision tool: ${String(option.nextAction.tool)}`);
+    }
+    if (option.nextAction.type === "call_tool") {
+      assertDecisionArgumentsSafe(option.nextAction.arguments);
+    }
+  }
+  if (actionableOptions === 0) throw new Error("A decision requires an actionable option.");
+  if (noActionOptions === 0) throw new Error("A decision requires a no-action exit option.");
+  return {
+    decisionVersion: 1,
+    prompt: normalizedPrompt,
+    selectionMode: "single",
+    selectionRequired: true,
+    defaultOptionId: null,
+    options
+  };
+}
+function formatDecisionFallback(decision) {
+  const options = decision.options.map((option, index) => {
+    const consequences = option.consequences.length === 0 ? "" : `
+   Consequences: ${option.consequences.join(" ")}`;
+    let exactAction;
+    switch (option.nextAction.type) {
+      case "call_tool":
+        exactAction = `If the user selects this option, call ${option.nextAction.tool} with these exact arguments: ${JSON.stringify(option.nextAction.arguments)}.`;
+        break;
+      case "open_url":
+        exactAction = `If the user selects this option, present this exact URL: ${option.nextAction.url}.`;
+        break;
+      case "none":
+        exactAction = "If the user selects this option, call no tool and make no change.";
+        break;
+    }
+    return `${index + 1}. [${option.id}] ${option.label}
+   ${option.description}${consequences}
+   ${exactAction}`;
+  });
+  return `USER DECISION REQUIRED: ${decision.prompt}
+No option is selected by default. Present every option to the user, do not choose on their behalf, and never reconstruct or guess tool arguments.
+
+` + options.join("\n\n");
+}
+function decisionToolResult(input) {
+  const decision = buildDecisionContract(input.prompt, input.options);
+  const actionable = decision.options.filter(
+    (option) => option.nextAction.type === "call_tool"
+  );
+  const nextActions = actionable.map((option) => ({
+    tool: option.nextAction.tool,
+    arguments: option.nextAction.arguments,
+    allowed: true,
+    ...option.nextAction.reasonCode === void 0 ? {} : { reasonCode: option.nextAction.reasonCode }
+  }));
+  let userAction;
+  if (input.legacyUserAction?.type === "confirm_in_mcp" && actionable.length === 1) {
+    const option = actionable[0];
+    if (option !== void 0) {
+      userAction = {
+        type: "confirm_in_mcp",
+        provider: input.legacyUserAction.provider,
+        expectedOutcome: option.description,
+        resumeWith: {
+          tool: option.nextAction.tool,
+          arguments: option.nextAction.arguments
+        }
+      };
+    }
+  } else if (input.legacyUserAction?.type === "select_site") {
+    userAction = {
+      type: "select_site",
+      provider: input.legacyUserAction.provider,
+      expectedOutcome: "Apply only the option explicitly selected by the user.",
+      options: actionable.map((option) => ({
+        label: option.label,
+        value: typeof option.nextAction.arguments["reuseSiteUrl"] === "string" ? option.nextAction.arguments["reuseSiteUrl"] : option.id,
+        expectedOutcome: option.description
+      }))
+    };
+  }
+  return structuredToolResult({
+    schemaVersion: 1,
+    outcome: input.outcome ?? "waiting_user",
+    resultCode: input.resultCode,
+    ...input.operationId === void 0 ? {} : { operationId: input.operationId },
+    summary: `${input.summary}
+
+${formatDecisionFallback(decision)}`,
+    data: input.data,
+    decision,
+    ...userAction === void 0 ? {} : { userAction },
+    nextActions
+  });
+}
+function callToolDecisionOption(input) {
+  return {
+    id: input.id,
+    label: input.label,
+    description: input.description,
+    consequences: input.consequences ?? [],
+    nextAction: {
+      type: "call_tool",
+      tool: input.tool,
+      arguments: input.arguments,
+      ...input.reasonCode === void 0 ? {} : { reasonCode: input.reasonCode }
+    }
+  };
+}
+function noActionDecisionOption(input) {
+  return {
+    id: input?.id ?? "cancel",
+    label: input?.label ?? "Do not continue",
+    description: input?.description ?? "Keep the current local and cloud state unchanged.",
+    consequences: [],
+    nextAction: { type: "none" }
+  };
+}
+
 // src/tools/definitions.ts
 function text(resultCode, t, data = {}, outcome = "completed", nextActions = []) {
   return structuredToolResult({
@@ -3616,17 +3871,10 @@ ${block}`, checklist: toDnsChecklist(diag.checks) };
   }
 }
 function freeSiteCreationBarrier(sites, deployArguments) {
-  const userSiteOptions = sites.map((site) => ({
-    label: `Replace content at ${site.url}`,
-    value: site.url,
-    expectedOutcome: "A site handoff keeps this existing free-site URL, replaces its online content, issues a fresh project credential, and revokes every previous credential."
-  }));
   const summary = `Sakupa cloud confirmed that this network already has ${FREE_ACTIVE_SITES_PER_IP} active free sites, so no new site was created. Authenticated device discovery found ${sites.length} free site(s) this device can hand off.
 
 ` + sites.map((site) => `- ${site.url} (expires ${site.expiresAt})`).join("\n") + "\n\nThe free-site allowance is full. Ask the user which existing free URL may have its content REPLACED by the current project. Selecting one authorizes a site handoff: deploy keeps that URL, overwrites its online content with the current files, issues a fresh project credential, and revokes every previous credential. The cloud site is NOT deleted. No prior project directory, browser history, workspace switch, or user-run command is required. YOU then call deploy with the exact nextAction arguments. Never ask the user to locate an old directory or run a CLI, and never recommend another hosting provider.";
-  return structuredToolResult({
-    schemaVersion: 1,
-    outcome: "waiting_user",
+  return decisionToolResult({
     resultCode: "free_site_slot_selection_required",
     summary,
     data: {
@@ -3638,29 +3886,44 @@ function freeSiteCreationBarrier(sites, deployArguments) {
       cloudSiteWillBeDeleted: false,
       previousProjectWillBeUnbound: true
     },
-    userAction: {
-      type: "select_site",
-      provider: "sakupa",
-      expectedOutcome: "The selected URL remains while its content is replaced and all previous credentials are revoked.",
-      options: userSiteOptions
-    },
-    nextActions: sites.map((site) => ({
-      tool: "deploy",
-      arguments: {
-        ...deployArguments,
-        publicConfirmed: true,
-        reuseSiteUrl: site.url,
-        reuseConfirmed: true
-      },
-      allowed: true,
-      reasonCode: "user_selected_reusable_free_site"
-    }))
+    prompt: "Choose exactly one existing free URL that the current project may take over.",
+    options: [
+      ...sites.map(
+        (site, index) => callToolDecisionOption({
+          id: `handoff_site_${index + 1}`,
+          label: `Replace content at ${site.url}`,
+          description: "Keep this existing free-site URL and replace its online content with the current project.",
+          consequences: [
+            "A fresh project credential is issued and every previous credential is revoked.",
+            "The cloud site is not deleted and no previous project directory is needed."
+          ],
+          tool: "deploy",
+          arguments: {
+            ...deployArguments,
+            publicConfirmed: true,
+            reuseSiteUrl: site.url,
+            reuseConfirmed: true
+          },
+          reasonCode: "user_selected_reusable_free_site"
+        })
+      ),
+      noActionDecisionOption({
+        description: "Do not take over any existing free site and create no new site."
+      })
+    ],
+    legacyUserAction: { type: "select_site", provider: "sakupa" }
   });
 }
 async function discoverDeviceFreeSites(client, apiBaseUrl, device) {
+  let cloudSites = (await client.listDeviceFreeSites(device.deviceId, device.credential)).sites;
+  const alreadyOwned = new Set(cloudSites.map((site) => site.siteId));
+  let claimedAny = false;
   for (const record of listRecentCreations(Date.now(), apiBaseUrl)) {
     const state = loadSiteFile(record.projectDir);
     if (state.kind !== "ok" || state.file.siteId !== record.siteId) continue;
+    if (state.file.apiBaseUrl !== "" && state.file.apiBaseUrl !== apiBaseUrl) continue;
+    if (alreadyOwned.has(record.siteId)) continue;
+    const environmentIsKnown = record.apiBaseUrl === apiBaseUrl || state.file.apiBaseUrl === apiBaseUrl;
     try {
       await client.claimDeviceFreeSite(
         record.siteId,
@@ -3668,9 +3931,11 @@ async function discoverDeviceFreeSites(client, apiBaseUrl, device) {
         device.deviceId,
         device.credential
       );
+      claimedAny = true;
+      alreadyOwned.add(record.siteId);
     } catch (error) {
       if (isSakupaError(error) && ["not_found", "state_conflict"].includes(error.code)) {
-        removeCreation(record.siteId);
+        if (environmentIsKnown) removeCreation(record.siteId);
         continue;
       }
       if (!isSakupaError(error) || error.code !== "unauthorized") {
@@ -3678,7 +3943,10 @@ async function discoverDeviceFreeSites(client, apiBaseUrl, device) {
       }
     }
   }
-  return (await client.listDeviceFreeSites(device.deviceId, device.credential)).sites;
+  if (claimedAny) {
+    cloudSites = (await client.listDeviceFreeSites(device.deviceId, device.credential)).sites;
+  }
+  return cloudSites;
 }
 function outputDirectoryChain(projectRoot, outputAbs) {
   const rel = relative3(projectRoot, outputAbs);
@@ -3775,18 +4043,39 @@ Next action: ${analysis.suggestedNextAction}`,
         const effectiveOutputDir = analysis.recommendedOutputDir ?? ".";
         const recordedOutputDir = ctx.projectMarker?.outputDir;
         if (recordedOutputDir !== void 0 && resolve5(ctx.projectDir, recordedOutputDir) !== resolve5(ctx.projectDir, effectiveOutputDir) && args.outputDirChangeConfirmed !== true) {
-          return structuredToolResult({
-            schemaVersion: 1,
-            outcome: "waiting_user",
+          const confirmation = { outputDirChangeConfirmed: true };
+          const confirmArguments = {
+            ...args,
+            outputDir: effectiveOutputDir,
+            ...confirmation
+          };
+          return decisionToolResult({
             resultCode: "publish_directory_change_confirmation_required",
             summary: `This initialized project last published from "${recordedOutputDir}", but this request selected "${effectiveOutputDir}". Nothing was uploaded and the site was not changed. Show both paths to the user; only after explicit confirmation call deploy again with outputDirChangeConfirmed: true.`,
             data: {
               projectDir: ctx.projectDir,
               previousOutputDir: recordedOutputDir,
               requestedOutputDir: effectiveOutputDir,
-              confirmationField: "outputDirChangeConfirmed"
+              confirmationField: "outputDirChangeConfirmed",
+              confirmation,
+              confirmArguments
             },
-            nextActions: [{ tool: "deploy", allowed: true, reasonCode: "explicit_confirmation" }]
+            prompt: `Use the newly selected publish directory "${effectiveOutputDir}"?`,
+            options: [
+              callToolDecisionOption({
+                id: "use_new_publish_directory",
+                label: `Use ${effectiveOutputDir}`,
+                description: "Publish this project from the newly selected directory.",
+                consequences: [`The recorded publish directory changes from ${recordedOutputDir}.`],
+                tool: "deploy",
+                arguments: confirmArguments,
+                reasonCode: "explicit_confirmation"
+              }),
+              noActionDecisionOption({
+                description: "Keep the recorded publish directory and upload nothing."
+              })
+            ],
+            legacyUserAction: { type: "confirm_in_mcp", provider: "sakupa" }
           });
         }
         const files = analysis.files;
@@ -3841,24 +4130,37 @@ Next action: ${analysis.suggestedNextAction}`,
           }
           if (nestedMarker.kind === "ok") {
             if (args.sakupaRelocationConfirmed !== true) {
-              return structuredToolResult({
-                schemaVersion: 1,
-                outcome: "waiting_user",
+              const confirmation = { sakupaRelocationConfirmed: true };
+              const confirmArguments = { ...args, ...confirmation };
+              return decisionToolResult({
                 resultCode: "sakupa_relocation_confirmation_required",
                 summary: `A nested Sakupa project marker exists at ${candidateDir}/.sakupa, but the active MCP Root is ${ctx.projectDir}. Nothing was moved or deployed. Show both paths to the user; after confirmation retry deploy with sakupaRelocationConfirmed:true. Sakupa will preserve credentials and refuse conflicts.`,
                 data: {
                   projectRoot: ctx.projectDir,
                   misplacedSakupaDirectory: join9(candidateDir, ".sakupa"),
                   targetSakupaDirectory: join9(ctx.projectDir, ".sakupa"),
-                  confirmationField: "sakupaRelocationConfirmed"
+                  confirmationField: "sakupaRelocationConfirmed",
+                  confirmation,
+                  confirmArguments
                 },
-                nextActions: [
-                  {
+                prompt: "Move the nested Sakupa project binding to the active workspace Root?",
+                options: [
+                  callToolDecisionOption({
+                    id: "relocate_sakupa_binding",
+                    label: "Move the Sakupa binding to the workspace Root",
+                    description: "Validate and relocate the nested Sakupa binding, then continue this deployment.",
+                    consequences: [
+                      "Sakupa preserves valid credentials and refuses conflicting bindings."
+                    ],
                     tool: "deploy",
-                    allowed: true,
+                    arguments: confirmArguments,
                     reasonCode: "explicit_sakupa_relocation_confirmation"
-                  }
-                ]
+                  }),
+                  noActionDecisionOption({
+                    description: "Leave both directories unchanged and upload nothing."
+                  })
+                ],
+                legacyUserAction: { type: "confirm_in_mcp", provider: "sakupa" }
               });
             }
             markerRelocatedFrom.push(candidateDir);
@@ -3981,19 +4283,41 @@ Next action: ${analysis.suggestedNextAction}`,
           deleteProjectMarker(dir);
         }
         if (!existing && args.reuseSiteUrl === void 0 && args.publicConfirmed !== true) {
-          return text(
-            "public_deployment_confirmation_required",
-            `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Explain this to the user and obtain explicit confirmation before retrying deploy with publicConfirmed: true.`,
-            { publicUrlLifetimeHours: FREE_SITE_TTL_HOURS, confirmationField: "publicConfirmed" },
-            "waiting_user"
-          );
+          const confirmation = { publicConfirmed: true };
+          const confirmArguments = { ...args, ...confirmation };
+          return decisionToolResult({
+            resultCode: "public_deployment_confirmation_required",
+            summary: `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Nothing has been uploaded or made public yet. The exact confirmation field is publicConfirmed: true.`,
+            data: {
+              publicUrlLifetimeHours: FREE_SITE_TTL_HOURS,
+              confirmationField: "publicConfirmed",
+              confirmation,
+              confirmArguments
+            },
+            prompt: "Create the first public free-site preview for this project?",
+            options: [
+              callToolDecisionOption({
+                id: "create_public_preview",
+                label: "Create the public preview",
+                description: `Publish the selected files at a public URL for ${FREE_SITE_TTL_HOURS} hours.`,
+                consequences: ["Anyone with the generated URL can open the site."],
+                tool: "deploy",
+                arguments: confirmArguments,
+                reasonCode: "explicit_public_deployment_confirmation"
+              }),
+              noActionDecisionOption({
+                description: "Keep the project private and upload nothing."
+              })
+            ],
+            legacyUserAction: { type: "confirm_in_mcp", provider: "sakupa" }
+          });
         }
         if (!existing) {
           if (args.reuseSiteUrl !== void 0) {
             if (args.reuseConfirmed !== true) {
-              return structuredToolResult({
-                schemaVersion: 1,
-                outcome: "waiting_user",
+              const confirmation = { reuseConfirmed: true };
+              const confirmArguments = { ...args, publicConfirmed: true, ...confirmation };
+              return decisionToolResult({
                 resultCode: "free_site_reuse_confirmation_required",
                 summary: `Nothing was changed. Reusing ${args.reuseSiteUrl} will replace all online content at that URL with the current project, issue a fresh credential here, and revoke every previous credential automatically. No old directory is needed. Show these consequences and call deploy with reuseConfirmed:true only after the user explicitly selects this URL.`,
                 data: {
@@ -4001,25 +4325,29 @@ Next action: ${analysis.suggestedNextAction}`,
                   cloudSiteWillBeDeleted: false,
                   onlineContentWillBeReplaced: true,
                   previousProjectWillBeUnbound: true,
-                  confirmationField: "reuseConfirmed"
+                  confirmationField: "reuseConfirmed",
+                  confirmation,
+                  confirmArguments
                 },
-                userAction: {
-                  type: "confirm_in_mcp",
-                  provider: "sakupa",
-                  expectedOutcome: "Replace the selected free URL content and move its local project binding.",
-                  resumeWith: {
+                prompt: `Take over ${args.reuseSiteUrl} with the current project?`,
+                options: [
+                  callToolDecisionOption({
+                    id: "confirm_site_handoff",
+                    label: `Take over ${args.reuseSiteUrl}`,
+                    description: "Keep the selected URL and replace all online content with the current project.",
+                    consequences: [
+                      "A fresh credential is issued here and every previous credential is revoked.",
+                      "The previous project becomes unbound; the cloud site is not deleted."
+                    ],
                     tool: "deploy",
-                    arguments: { ...args, publicConfirmed: true, reuseConfirmed: true }
-                  }
-                },
-                nextActions: [
-                  {
-                    tool: "deploy",
-                    arguments: { ...args, publicConfirmed: true, reuseConfirmed: true },
-                    allowed: true,
+                    arguments: confirmArguments,
                     reasonCode: "explicit_free_site_reuse_confirmation"
-                  }
-                ]
+                  }),
+                  noActionDecisionOption({
+                    description: "Keep the selected site and current project unchanged."
+                  })
+                ],
+                legacyUserAction: { type: "confirm_in_mcp", provider: "sakupa" }
               });
             }
           }
@@ -4395,7 +4723,7 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID5()
+            idempotencyKey: randomUUID6()
           },
           site.credential
         );
@@ -4846,10 +5174,59 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
         }
         if (args.action === "status") {
           const res2 = await ctx.client.getRecoveryStatus(verificationId);
+          if (res2.readyToComplete) {
+            const revokeArguments = {
+              action: "complete",
+              verificationId,
+              preserveExistingCredentials: false,
+              ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
+            };
+            const preserveArguments = {
+              ...revokeArguments,
+              preserveExistingCredentials: true
+            };
+            return decisionToolResult({
+              resultCode: "domain_recovery_ready",
+              summary: "DNS control is verified and recovery is ready to complete. Nothing was completed yet. The user must choose whether previous site credentials remain valid.",
+              data: {
+                recovery: res2,
+                credentialPolicyChoices: ["revoke_previous", "preserve_previous"]
+              },
+              prompt: "How should Sakupa handle the site credentials that existed before recovery?",
+              options: [
+                callToolDecisionOption({
+                  id: "revoke_previous_credentials",
+                  label: "Revoke all previous credentials",
+                  description: "Complete recovery with the new local credential and revoke every previous credential.",
+                  consequences: [
+                    "Old project folders and credential backups can no longer manage the site."
+                  ],
+                  tool: "recover",
+                  arguments: revokeArguments,
+                  reasonCode: "user_selected_secure_recovery"
+                }),
+                callToolDecisionOption({
+                  id: "preserve_previous_credentials",
+                  label: "Keep previous credentials valid",
+                  description: "Complete recovery with the new local credential without revoking existing credentials.",
+                  consequences: [
+                    "Any old project folder or leaked credential that still works retains site authority."
+                  ],
+                  tool: "recover",
+                  arguments: preserveArguments,
+                  reasonCode: "user_selected_credential_preservation"
+                }),
+                noActionDecisionOption({
+                  label: "Do not complete recovery yet",
+                  description: "Keep the verified recovery pending and change no credential."
+                })
+              ]
+            });
+          }
           return structuredToolResult({
             schemaVersion: 1,
-            outcome: res2.status === "expired" ? "expired" : res2.readyToComplete ? "completed" : "pending_provider",
-            resultCode: res2.status === "expired" ? "domain_recovery_expired" : res2.readyToComplete ? "domain_recovery_ready" : "domain_recovery_pending_dns",
+            outcome: res2.status === "expired" ? "expired" : "pending_provider",
+            resultCode: res2.status === "expired" ? "domain_recovery_expired" : "domain_recovery_pending_dns",
             summary: `DNS recovery verification status: ${res2.status}`,
             data: { recovery: res2 },
             nextActions: [
@@ -4860,8 +5237,8 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
                   verificationId,
                   ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
                 },
-                allowed: res2.readyToComplete,
-                ...res2.readyToComplete ? {} : { reasonCode: res2.status }
+                allowed: false,
+                reasonCode: res2.status
               }
             ]
           });
@@ -5031,12 +5408,39 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
         };
         if (args.confirmSubmit !== true) {
           const contactNote = args.contactEmail !== void 0 ? "note that their contact email is attached for follow-up. " : "ASK THEM ONCE whether they want to attach a contact email for follow-up (optional \u2014 omit if declined; include it as contactEmail when they do). ";
-          return textJson(
-            "bug_report_preview_ready",
-            `Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Show it to the user, and ${contactNote}Then re-run report with confirmSubmit: true to submit.`,
-            payload,
-            "preview"
-          );
+          const confirmation = { confirmSubmit: true };
+          const confirmArguments = { ...args, ...confirmation };
+          return decisionToolResult({
+            resultCode: "bug_report_preview_ready",
+            outcome: "preview",
+            summary: `Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Show it to the user, and ${contactNote}Exact payload:
+${JSON.stringify(payload, null, 2)}`,
+            data: {
+              result: payload,
+              confirmation,
+              confirmArguments,
+              submitted: false
+            },
+            prompt: "Submit this exact sanitized bug report?",
+            options: [
+              callToolDecisionOption({
+                id: "submit_bug_report",
+                label: "Submit the reviewed report",
+                description: "Submit exactly the sanitized payload shown above.",
+                consequences: [
+                  args.contactEmail === void 0 ? "No contact email is attached." : "The provided contact email is attached for follow-up."
+                ],
+                tool: "report",
+                arguments: confirmArguments,
+                reasonCode: "explicit_bug_report_submission_confirmation"
+              }),
+              noActionDecisionOption({
+                label: "Do not submit the report",
+                description: "Keep the report local and send nothing to Sakupa."
+              })
+            ],
+            legacyUserAction: { type: "confirm_in_mcp", provider: "sakupa" }
+          });
         }
         const res = await baseCtx.client.reportBug(payload, site?.credential);
         return text(
@@ -5436,8 +5840,18 @@ function registerHelpTools(server, baseCtx) {
             schemaVersion: 1,
             outcome: "completed",
             resultCode: "help_overview",
-            summary: 'Sakupa tool overview and parameter names returned. Site handoff moves an existing free URL to the current project and replaces its credential as a safety consequence; credential rotation changes the credential in place solely for security. Both revoke prior values. Use help topic:"terminology" for every site/credential distinction. On any failure call help with topic:"diagnose" before retrying, support or report.',
-            data: { tools: catalog, toolOrder: TOOL_TOPICS, terminology: HELP_TERMINOLOGY },
+            summary: `Sakupa tool overview and parameter names returned. Site handoff moves an existing free URL to the current project and replaces its credential as a safety consequence; credential rotation changes the credential in place solely for security. Both revoke prior values. When a result contains decision, present every option, select none by default, and copy only the user's selected option nextAction exactly. Use help topic:"terminology" for every site/credential distinction. On any failure call help with topic:"diagnose" before retrying, support or report.`,
+            data: {
+              tools: catalog,
+              toolOrder: TOOL_TOPICS,
+              terminology: HELP_TERMINOLOGY,
+              decisionOptions: {
+                selectionMode: "single",
+                defaultOptionId: null,
+                presentEveryOption: true,
+                exactNextActionRequired: true
+              }
+            },
             nextActions: []
           });
         }
@@ -5596,9 +6010,7 @@ function registerCredentialTools(server, baseCtx) {
         const status = await ctx.client.getCredentialStatus(site.siteId, site.credential);
         const confirmation = { confirmed: true };
         if (args.confirmed !== true) {
-          return structuredToolResult({
-            schemaVersion: 1,
-            outcome: "waiting_user",
+          return decisionToolResult({
             resultCode: "credential_rotation_confirmation_required",
             summary: `Nothing was changed. Rotating the management credential for ${site.url ?? site.siteId} will generate a new credential locally, save it as the current credential in this project .sakupa/site.json, and revoke EVERY previous credential for this site\u2014including copies in old folders and backups. Rotation is optional and deploy remains available. Current credential created at: ${status.credentialCreatedAt}. Exact confirm arguments: ${JSON.stringify(confirmation)}. Ask the user for explicit approval; never expose credential values.`,
             data: {
@@ -5611,20 +6023,26 @@ function registerCredentialTools(server, baseCtx) {
               previousCredentialsWillBeRevoked: true,
               optional: true
             },
-            userAction: {
-              type: "confirm_in_mcp",
-              provider: "sakupa",
-              expectedOutcome: "Generate one new local credential and revoke every previous credential for this site.",
-              resumeWith: { tool: "rotate", arguments: confirmation }
-            },
-            nextActions: [
-              {
+            prompt: `Rotate the management credential for ${site.url ?? site.siteId}?`,
+            options: [
+              callToolDecisionOption({
+                id: "rotate_credential",
+                label: "Rotate the management credential",
+                description: "Generate one new local credential and make it the only valid credential for this site.",
+                consequences: [
+                  "Every previous credential is revoked, including copies in old folders and backups.",
+                  "The site URL and online content do not change."
+                ],
                 tool: "rotate",
                 arguments: confirmation,
-                allowed: true,
                 reasonCode: "explicit_credential_rotation_confirmation"
-              }
-            ]
+              }),
+              noActionDecisionOption({
+                label: "Keep the current credential",
+                description: "Do not rotate; deployment remains available with the current credential."
+              })
+            ],
+            legacyUserAction: { type: "confirm_in_mcp", provider: "sakupa" }
           });
         }
         writeCredentialRotation(ctx.projectDir, {
@@ -5702,6 +6120,14 @@ Workflow:
    payment, refund and other customer-service requests. report is the LAST resort only when
    help explicitly recommends a product bug report, and submission still requires user review.
 
+Decision-options contract: when a result contains decision, present EVERY numbered option from the
+tool to the user and wait for their selection. No option is selected by default. Never choose from
+context, paraphrase a selection into different arguments, or invent another option. After the user
+selects, copy that option's exact nextAction. Legacy userAction and nextActions mirror the same
+choice for older clients; decision is the authoritative choice set. A type "none" option means call
+no tool and change nothing. Stripe-hosted links remain direct links because Stripe itself owns plan
+selection and confirmation.
+
 Project directory contract: before the first deploy or a new recovery, initialize the intended
 project by calling init with NO path argument. init uses the IDE's exact MCP Root and creates the
 non-secret .sakupa/project.json directly there. The CLI command