shopstack 0.3.2 → 0.3.4

package/README.md

@@ -6,9 +6,9 @@ guest restaurant reservations.
 ## Install
 
 ```bash
-npm install shopstack@0.3.2
+npm install shopstack@0.3.4
 # or
-npm install -g shopstack@0.3.2
+npm install -g shopstack@0.3.4
 ```
 
 Node.js 18 or newer is required.
@@ -18,7 +18,7 @@ WebSocket (Node.js 22 or newer). It reads the authenticated checkout resource
 after each notification. Older runtimes, or a failed socket connection, use the
 bounded HTTP update wait. The one-time socket token is never placed in a URL.
 
-This preview release pairs `shopstack@0.3.2` with `shopstack-mcp@0.2.2`.
+This preview release pairs `shopstack@0.3.4` with `shopstack-mcp@0.2.4`.
 Both packages use the `preview` distribution tag. The `latest` versions are
 unchanged. Use the exact versions above to install this release.
 
@@ -79,7 +79,7 @@ Configure any stdio MCP client to run:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp@0.2.2"],
+      "args": ["-y", "shopstack-mcp@0.2.4"],
       "env": {
         "SHOPSTACK_API_URL": "https://shopstack-release-preview.shopstack.workers.dev/v1",
         "SHOPSTACK_CONFIG_FILE": "/absolute/private/path/shopstack-config.json"
@@ -110,7 +110,7 @@ one MCP server and three focused skills:
 - `shopstack-checkout` for checkout creation and monitoring;
 - `shopstack-onboarding` for verified signup and private local profiles.
 
-The plugin pins `shopstack-mcp@0.2.1`, which installs the matching
+The plugin pins `shopstack-mcp@0.2.4`, which installs the matching
 reservation-capable `shopstack` client. Configure the API address
 before starting the plugin or use a profile already bound to that API. The existing top-level
 `SKILL.md` remains in the npm client package for compatibility.
@@ -129,6 +129,11 @@ responds, checkout resumes automatically. No “done” message is needed. The C
 keeps watching; MCP agents use `wait_checkout_update` with the latest
 `presentation_revision`. Final order approval is still a separate step.
 
+For ordinary missing information, MCP returns `question.content` with the
+current unanswered question. Show it and reply with `send_message`. Interactive
+CLI checkout prompts use the same message. This reads the existing message API;
+it does not add another model call or include the full conversation history.
+
 ## Run a guest reservation
 
 Create `reservation.json` with the diner details, location name, and a detailed
@@ -156,14 +161,27 @@ shopstack reservation run --file reservation.json
 ```
 
 The CLI asks natural follow-up questions and displays current location,
-restaurant, and time IDs. It shows the exact locked booking summary before it
-asks for confirmation. A clear confirmation is sent through the same
-reservation message route; there is no separate reservation approval command.
+restaurant, and time IDs. The two-letter diner country is for the E.164 phone
+number, not for the restaurant location. Select a restaurant by number, name,
+or a natural description. The CLI then shows its full description, rating and
+review count, cuisine, price, address, photos, fit notes, caveats, and current
+times. Use `back`, `more`, `search TEXT`, or `refine TEXT` before booking. It
+shows the exact locked booking summary before it asks for confirmation. Any
+clear affirmative answer can confirm it; the exact word `book` is not required.
+After success, the CLI prints a short confirmation and offers immediate
+cancellation. Add `--json` to retain the full machine-readable response.
+
+If the input email belongs to a registered OpenTable account, Shopstack uses
+one temporary guest address and forwards provider email to the supplied address.
+Every booking requests reservation SMS, but this does not prove SMS delivery.
+A clear confirmation is sent through the same reservation message route; there
+is no separate reservation approval command.
 Use `shopstack reservation get`, `message`, or `cancel` for individual API
 operations. Use `shopstack reservation options RESERVATION_ID` for another
 stored page and `shopstack reservation option RESERVATION_ID OPTION_ID` for
 full provider details. These reads do not repeat model inference or restaurant
-search.
+search. Use `shopstack reservation email RESERVATION_ID` to inspect owned test
+email evidence without exposing private inbox or forwarding identifiers.
 
 ## Run a checkout
 

package/SKILL.md

@@ -19,8 +19,8 @@ chat to fix an environment mismatch.
 For the JavaScript client and CLI:
 
 ```bash
-npm install shopstack@0.3.1
-npm install -g shopstack@0.3.1
+npm install shopstack@0.3.4
+npm install -g shopstack@0.3.4
 ```
 
 For MCP clients, configure the local stdio server:
@@ -30,7 +30,7 @@ For MCP clients, configure the local stdio server:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp@0.2.1"]
+      "args": ["-y", "shopstack-mcp@0.2.4"]
     }
   }
 }
@@ -43,7 +43,7 @@ not equivalent to the current source.
 
 ## Run a guest restaurant reservation
 
-Give Shopstack the diner name, phone number, two-letter country, a location
+Give Shopstack the diner name, E.164 phone number, its two-letter country, a location
 name, and one detailed natural-language request. Do not supply coordinates or a
 time zone. Shopstack resolves the valid OpenTable location and its time zone.
 Include as much useful detail as possible: date, local time or range, party
@@ -62,15 +62,23 @@ stored provider description, photos, facts, and time IDs. These reads do not
 run another model inference or OpenTable search. Preserve every current
 `option_id` and `time_id`. A new search makes older IDs stale.
 
+Evaluate restaurants against the complete request. Compare the rating with its
+review count, cuisine, full description, price, current times, photos, fit
+facts, and caveats. Call `get_reservation_option` for every restaurant used in
+the final comparison. State the observed facts that support the recommendation.
+
 Selection rechecks availability, locks the slot, and returns one exact booking
 summary. Send a clear confirmation only when the user confirms that exact
 summary. This confirmation is an ordinary reservation message and can create
 the booking. There is no separate reservation approval endpoint or MCP tool.
 An ambiguous reply must not be treated as confirmation. The anonymous guest
 profile is created only when booking. Pass optional `diner.email` when the user
-supplies it; that is the guest contact address. Otherwise omit it and Shopstack
-creates a temporary inbox when booking. Never require the user to give a
-restaurant email. Cancel a confirmed
+supplies it. If OpenTable reports that this address belongs to a registered
+account, Shopstack retries once with a reservation inbox and forwards provider
+email to the supplied address. Otherwise omit it and Shopstack creates a
+managed inbox when booking. Every booking asks OpenTable for reservation SMS.
+`sms_requested` confirms the request, not SMS delivery. Never require the user
+to give a restaurant email. Cancel a confirmed
 reservation with the typed reservation cancellation operation.
 
 ## Choose the account shape
@@ -113,7 +121,18 @@ shopstack connect list
 shopstack connect link
 ```
 
-Include `payment_provider: "link"` only when the active user's Link connection reports checkout-ready. Otherwise omit `payment_provider`. Shopstack will run until card entry and request one protected checkout-scoped card through the SDK or no-echo CLI prompt.
+When the user chooses Link, include `payment_provider: "link"` even if Link is
+not connected. Shopstack prepares the merchant checkout first. At card
+issuance, `required_input.type: "link"` supplies the exact sign-in or approval
+URL, amount, currency, and an optional verification phrase. Show those values
+and keep monitoring. Shopstack polls Link and resumes automatically; never ask
+the user to send a completion message. Link credential approval does not grant
+Shopstack final order approval.
+
+Omit `payment_provider` when the user wants to supply a card directly.
+Shopstack then requests protected checkout-scoped card input at the payment
+form through the SDK, CLI prompt, or live viewer. Connecting Link in advance
+with the commands above is optional.
 
 Never put card data in MCP arguments, natural-language messages, model output, logs, or ordinary CLI flags.
 
@@ -150,20 +169,26 @@ Run it with:
 shopstack checkout run --file checkout.json
 ```
 
-Or create with MCP, then call `poll_checkout`. Display these authoritative fields to the user when they change:
+Or create with MCP, read with `poll_checkout`, and monitor changes with
+`wait_checkout_update` using the latest `presentation_revision`. Display these
+authoritative fields to the user when they change:
 
 - `status`: one of exactly `queued`, `started`, `help_required`, `approval_required`, `submitting`, `complete`, `failed`, `cancelled`;
 - `activity`: bounded present-tense display text;
 - `intent.name`, `intent.phase`, and `intent.updated_at`: bounded mechanical action progress with no arguments or reasoning;
-- `required_input`: a typed handoff such as protected payment-card input;
+- `required_input`: a typed handoff for Link or protected payment-card input;
+- `question.content`: the current ordinary question, when MCP returns it; show it and send the user's answer with `send_message`;
 - `approval`: the exact amount-bound approval request when present.
 
-Poll every two seconds for `queued`, `started`, and `submitting`; every five seconds for `help_required` and `approval_required`; stop at `complete`, `failed`, or `cancelled`.
+Keep calling `wait_checkout_update` while Link sign-in or approval is pending;
+an unchanged response is not a failure. Stop at `complete`, `failed`, or
+`cancelled`. The CLI monitor follows changes automatically.
 
 ## Respond at typed boundaries
 
 - Use `GET/POST /v1/checkout/{id}/messages` only for ordinary missing information.
 - Use protected SDK/CLI payment input when `required_input.type` is `payment_card`.
+- Show the exact URL and keep monitoring when `required_input.type` is `link`.
 - Use only the dedicated payment-approval endpoint from a separately scoped trusted backend.
 - MCP and messages cannot approve payment and expose no approval tool.
 - Never infer approval from a user's conversational message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shopstack",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Shopstack API client and command-line checkout and reservation tools.",
   "type": "module",
   "exports": {

package/specs/openapi.json

@@ -548,6 +548,39 @@
         }
       }
     },
+    "/reservations/{reservation_id}/email": {
+      "get": {
+        "operationId": "getReservationEmailEvidence",
+        "summary": "Read the owned reservation inbox for testing",
+        "description": "Returns messages from the reservation-scoped OpenInbox inbox and their forwarding state. It never returns the temporary address, inbox ID, destination address, guest profile ID, or provider message ID.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ReservationId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Current reservation email evidence",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ReservationEmailEvidence"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "503": {
+            "$ref": "#/components/responses/Unavailable"
+          }
+        }
+      }
+    },
     "/reservations/{reservation_id}/options": {
       "get": {
         "operationId": "listReservationOptions",
@@ -1868,11 +1901,12 @@
                 "type": "string",
                 "format": "email",
                 "maxLength": 254,
-                "description": "Optional booking contact email. When supplied, this exact trimmed address is used for the guest profile. Otherwise Shopstack creates a temporary inbox when booking. Do not ask for an email if it was omitted."
+                "description": "Optional booking contact email. Shopstack first uses this trimmed address for the guest profile. If OpenTable reports that it belongs to a registered account, Shopstack creates one reservation inbox, retries guest creation once, and forwards provider messages to this address. If omitted, Shopstack uses a managed reservation inbox. Guest creation starts only after exact booking confirmation."
               },
               "country": {
                 "type": "string",
-                "pattern": "^[A-Z]{2}$"
+                "pattern": "^[A-Z]{2}$",
+                "description": "ISO 3166-1 alpha-2 country for phone_number, not the restaurant location."
               },
               "first_name": {
                 "type": "string",
@@ -1886,8 +1920,8 @@
               },
               "phone_number": {
                 "type": "string",
-                "minLength": 7,
-                "maxLength": 40
+                "pattern": "^\\+[1-9][0-9]{6,14}$",
+                "description": "E.164 phone number compatible with diner.country."
               }
             }
           },
@@ -2013,7 +2047,6 @@
           },
           "times": {
             "type": "array",
-            "minItems": 1,
             "maxItems": 30,
             "items": {
               "$ref": "#/components/schemas/ReservationTime"
@@ -2094,7 +2127,6 @@
           },
           "available_times": {
             "type": "array",
-            "minItems": 1,
             "maxItems": 30,
             "items": {
               "$ref": "#/components/schemas/ReservationTime"
@@ -2187,6 +2219,17 @@
               },
               "message": {
                 "type": "string"
+              },
+              "error_code": {
+                "type": "string",
+                "enum": [
+                  "BOOKING_REJECTED",
+                  "BOOKING_UNKNOWN",
+                  "DINER_ALREADY_REGISTERED",
+                  "DINER_PHONE_INVALID",
+                  "DINER_PROFILE_INVALID",
+                  "UPSTREAM_UNAVAILABLE"
+                ]
               }
             }
           },
@@ -2367,7 +2410,9 @@
               "restaurant",
               "date_time",
               "party_size",
-              "status"
+              "status",
+              "sms_requested",
+              "email_delivery_mode"
             ],
             "properties": {
               "confirmation_number": {
@@ -2387,6 +2432,19 @@
               "status": {
                 "type": "string",
                 "description": "Shopstack booking outcome, confirmed. Provider lifecycle labels are not returned as this status."
+              },
+              "sms_requested": {
+                "type": "boolean",
+                "const": true,
+                "description": "OpenTable received the reservation SMS request. This does not prove delivery."
+              },
+              "email_delivery_mode": {
+                "type": "string",
+                "enum": [
+                  "direct",
+                  "shopstack_forwarded",
+                  "shopstack_managed"
+                ]
               }
             }
           }
@@ -2476,6 +2534,112 @@
             "type": "string",
             "format": "date-time",
             "description": "Search conversation deadline; not the confirmed booking lifetime."
+          },
+          "email_delivery": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "mode",
+              "status"
+            ],
+            "properties": {
+              "mode": {
+                "type": "string",
+                "const": "shopstack_forwarded"
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "pending",
+                  "sent",
+                  "failed"
+                ]
+              }
+            }
+          }
+        }
+      },
+      "ReservationEmailEvidence": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "reservation_id",
+          "email_delivery_mode",
+          "messages"
+        ],
+        "properties": {
+          "reservation_id": {
+            "$ref": "#/components/schemas/ReservationId"
+          },
+          "email_delivery_mode": {
+            "type": "string",
+            "enum": [
+              "direct",
+              "shopstack_forwarded",
+              "shopstack_managed"
+            ]
+          },
+          "messages": {
+            "type": "array",
+            "maxItems": 100,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "from",
+                "subject",
+                "received_at",
+                "forwarding"
+              ],
+              "properties": {
+                "from": {
+                  "type": "string"
+                },
+                "subject": {
+                  "type": "string"
+                },
+                "received_at": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "text_body": {
+                  "type": "string"
+                },
+                "html_body": {
+                  "type": "string"
+                },
+                "forwarding": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "status",
+                    "attempt_count"
+                  ],
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "pending",
+                        "sent",
+                        "failed",
+                        "not_applicable"
+                      ]
+                    },
+                    "attempt_count": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "last_error_category": {
+                      "type": "string"
+                    },
+                    "sent_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              }
+            }
           }
         }
       },
@@ -2681,7 +2845,7 @@
             "enum": [
               "qwen"
             ],
-            "description": "Optional idempotent selector for the fixed product Qwen route. Omit it to use the same default route."
+            "description": "Optional experimental selector for direct Cerebras qwen-3.8-27b using the managed runner credential. Omit it to use the trusted deployment default. No arbitrary model, endpoint, or credential is accepted."
           },
           "proxy": {
             "$ref": "#/components/schemas/ProxyRequest"

package/src/cli.js

@@ -24,8 +24,9 @@ Payment connection:
 
 Reservation:
   shopstack reservation create --file reservation.json
-  shopstack reservation run --file reservation.json
+  shopstack reservation run --file reservation.json [--json]
   shopstack reservation get RESERVATION_ID
+  shopstack reservation email RESERVATION_ID [--json]
   shopstack reservation options RESERVATION_ID [--offset N] [--limit N]
   shopstack reservation option RESERVATION_ID OPTION_ID
   shopstack reservation message RESERVATION_ID --revision N --content TEXT
@@ -40,7 +41,7 @@ Checkout:
   shopstack checkout cancel CHECKOUT_ID
 `;
 
-function parseOptions(args, allowed) {
+function parseOptions(args, allowed, flags = new Set()) {
   const positional = [];
   const options = {};
   for (let index = 0; index < args.length; index += 1) {
@@ -51,6 +52,10 @@ function parseOptions(args, allowed) {
     }
     const name = value.slice(2);
     if (!allowed.has(name)) throw new Error(`Unknown option: --${name}`);
+    if (flags.has(name)) {
+      options[name] = true;
+      continue;
+    }
     const optionValue = args[index + 1];
     if (optionValue === undefined || optionValue.startsWith("--")) {
       throw new Error(`Option --${name} requires a value.`);
@@ -91,7 +96,10 @@ function boundedIntegerOption(options, name, fallback, minimum, maximum) {
 
 function isAffirmative(value) {
   const answer = String(value).trim().toLowerCase();
-  return answer === "y" || answer === "yes";
+  if (/\b(?:no|not|don't|do not|cancel|stop)\b/u.test(answer)) return false;
+  return /^(?:y|yes|yeah|yep|sure|confirm|confirmed|proceed|go ahead|please do|looks good|that works|book it)(?:\b|[.!])/u.test(
+    answer,
+  );
 }
 
 function writeJson(stream, value) {
@@ -253,18 +261,261 @@ async function reportSignupProgress(progress, stream) {
   }
 }
 
+function reportReservationOptions(options, stream, offset = 0) {
+  options.forEach((option, index) => {
+    const rating =
+      option.rating === undefined
+        ? "rating not supplied"
+        : `${option.rating}${option.review_count === undefined ? "" : ` (${option.review_count} reviews)`}`;
+    stream.write(
+      `${offset + index + 1}. ${option.name} — ${rating}${option.price_label === undefined ? "" : ` — ${option.price_label}`}\n`,
+    );
+    stream.write(`   Option ID: ${option.option_id}\n`);
+    stream.write(`   ${option.address}\n`);
+    if (option.cuisines?.length > 0) {
+      stream.write(`   Cuisine: ${option.cuisines.join(", ")}\n`);
+    }
+    option.available_times?.forEach((time, timeIndex) => {
+      stream.write(
+        `   Time ${timeIndex + 1}: ${time.date_time} [${time.time_id}]\n`,
+      );
+    });
+  });
+}
+
+function reportReservationOption(option, stream) {
+  stream.write(`\n${option.name}\n`);
+  stream.write(`Option ID: ${option.option_id}\n`);
+  stream.write(`Address: ${option.address}\n`);
+  if (option.description) stream.write(`Description: ${option.description}\n`);
+  if (option.rating !== undefined) {
+    stream.write(
+      `Rating: ${option.rating}${option.review_count === undefined ? "" : ` from ${option.review_count} reviews`}\n`,
+    );
+  }
+  if (option.cuisines?.length > 0) {
+    stream.write(`Cuisines: ${option.cuisines.join(", ")}\n`);
+  }
+  if (option.price_label) stream.write(`Price: ${option.price_label}\n`);
+  if (option.photo_urls?.length > 0) {
+    stream.write(`Photos:\n${option.photo_urls.map((url) => `  ${url}`).join("\n")}\n`);
+  }
+  if (option.match_reasons?.length > 0) {
+    stream.write(`Fit: ${option.match_reasons.join("; ")}\n`);
+  }
+  if (option.unverified?.length > 0) {
+    stream.write(`Caveats: ${option.unverified.join("; ")}\n`);
+  }
+  option.times?.forEach((time, index) => {
+    stream.write(`Time ${index + 1}: ${time.date_time} [${time.time_id}]\n`);
+  });
+}
+
+function normalizedWords(value) {
+  return new Set(
+    String(value)
+      .toLowerCase()
+      .match(/[\p{L}\p{N}]+/gu)
+      ?.filter((word) => word.length > 2) ?? [],
+  );
+}
+
+function selectReservationOption(input, options, offset) {
+  const trimmed = input.trim();
+  if (/^[1-9][0-9]*$/u.test(trimmed)) {
+    const index = Number(trimmed) - offset - 1;
+    return options[index];
+  }
+  const normalized = trimmed.toLowerCase();
+  const exact = options.find(
+    (option) => option.name.toLowerCase() === normalized,
+  );
+  if (exact !== undefined) return exact;
+  const contained = options.filter((option) =>
+    option.name.toLowerCase().includes(normalized),
+  );
+  if (contained.length === 1) return contained[0];
+  const requested = normalizedWords(trimmed);
+  const scored = options
+    .map((option) => {
+      const observed = normalizedWords(
+        [
+          option.name,
+          option.address,
+          ...(option.cuisines ?? []),
+          option.price_label,
+          option.description_excerpt,
+          ...(option.fit ?? []),
+          ...(option.caveats ?? []),
+        ].join(" "),
+      );
+      return {
+        option,
+        score: [...requested].filter((word) => observed.has(word)).length,
+      };
+    })
+    .sort((left, right) => right.score - left.score);
+  return scored[0]?.score > (scored[1]?.score ?? 0)
+    ? scored[0].option
+    : undefined;
+}
+
+function searchMessage(input) {
+  const match = /^(search|refine)\s+(.+)$/iu.exec(input.trim());
+  if (match === null) return undefined;
+  return `${match[1].toLowerCase() === "search" ? "Search for" : "Refine the search with"} ${match[2].trim()}.`;
+}
+
+async function browseReservationOptions(reservation, client, dependencies) {
+  let page = {
+    more_available: reservation.turn.more_available,
+    offset: 0,
+    options: reservation.turn.options,
+  };
+  for (;;) {
+    const input = String(
+      await visiblePrompt(
+        "Choose a restaurant number or name, or type more, search <text>, or refine <text>: ",
+        dependencies,
+      ),
+    ).trim();
+    const changedSearch = searchMessage(input);
+    if (changedSearch !== undefined) return changedSearch;
+    if (input.toLowerCase() === "more") {
+      if (page.more_available <= 0) {
+        dependencies.stderr.write("There are no more current options.\n");
+        continue;
+      }
+      const offset = page.offset + page.options.length;
+      page = await client.listReservationOptions(reservation.id, {
+        limit: 6,
+        offset,
+      });
+      reportReservationOptions(page.options, dependencies.stderr, page.offset);
+      continue;
+    }
+    const selected = selectReservationOption(input, page.options, page.offset);
+    if (selected === undefined) {
+      dependencies.stderr.write(
+        "I could not identify one restaurant. Use its number or name, or refine the search.\n",
+      );
+      continue;
+    }
+    const detail = await client.getReservationOption(
+      reservation.id,
+      selected.option_id,
+    );
+    reportReservationOption(detail, dependencies.stderr);
+    for (;;) {
+      const action = String(
+        await visiblePrompt(
+          "Choose a time number, or type back, more, search <text>, or refine <text>: ",
+          dependencies,
+        ),
+      ).trim();
+      const refinement = searchMessage(action);
+      if (refinement !== undefined) return refinement;
+      if (action.toLowerCase() === "back") {
+        reportReservationOptions(page.options, dependencies.stderr, page.offset);
+        break;
+      }
+      if (action.toLowerCase() === "more") {
+        if (page.more_available <= 0) {
+          dependencies.stderr.write("There are no more current options.\n");
+        } else {
+          const offset = page.offset + page.options.length;
+          page = await client.listReservationOptions(reservation.id, {
+            limit: 6,
+            offset,
+          });
+          reportReservationOptions(
+            page.options,
+            dependencies.stderr,
+            page.offset,
+          );
+        }
+        break;
+      }
+      const time = /^[1-9][0-9]*$/u.test(action)
+        ? detail.times?.[Number(action) - 1]
+        : detail.times?.find(
+            (candidate) =>
+              candidate.time_id === action ||
+              candidate.date_time.toLowerCase().includes(action.toLowerCase()),
+          );
+      if (time === undefined) {
+        dependencies.stderr.write("Choose one of the current time numbers.\n");
+        continue;
+      }
+      return `Use ${detail.name} with option ID ${detail.option_id} at ${time.date_time} with time ID ${time.time_id}.`;
+    }
+  }
+}
+
 function reportReservationTurn(reservation, stream) {
   const turn = reservation.turn;
   if (typeof turn?.message === "string") {
     stream.write(`${turn.message}\n`);
   }
-  const details =
-    turn?.locations ??
-    turn?.options ??
-    turn?.confirmation_prompt ??
-    turn?.confirmation ??
-    turn?.cancellation;
-  if (details !== undefined) writeJson(stream, details);
+  if (turn?.type === "location_options") {
+    turn.locations.forEach((location, index) =>
+      stream.write(`${index + 1}. ${location.label} [${location.location_id}]\n`),
+    );
+  }
+  if (turn?.type === "options") {
+    reportReservationOptions(turn.options, stream);
+  }
+  if (turn?.type === "confirmation_required") {
+    const summary = turn.confirmation_prompt;
+    stream.write(
+      `${summary.restaurant}\n${summary.address ?? ""}\n${summary.date_time} for ${summary.party_size ?? "the requested party"}\nOption: ${summary.option_id}\nTime: ${summary.time_id}\n`,
+    );
+  }
+}
+
+function reservationEmailMode(reservation) {
+  const mode =
+    reservation.turn?.confirmation?.email_delivery_mode ??
+    reservation.email_delivery?.mode;
+  if (mode === "shopstack_forwarded") return "Shopstack forwarded";
+  if (mode === "shopstack_managed") return "Shopstack managed";
+  if (mode === "direct") return "Direct";
+  return "Not reported";
+}
+
+function reportReservationResult(reservation, fallback, stream) {
+  const confirmation = reservation.turn?.confirmation;
+  stream.write("Reservation confirmed\n");
+  stream.write(
+    `Restaurant: ${confirmation?.restaurant ?? fallback?.restaurant ?? "Not reported"}\n`,
+  );
+  stream.write(
+    `Date and time: ${confirmation?.date_time ?? fallback?.date_time ?? "Not reported"}\n`,
+  );
+  stream.write(
+    `Party size: ${confirmation?.party_size ?? fallback?.party_size ?? "Not reported"}\n`,
+  );
+  stream.write(
+    `Confirmation: ${confirmation?.confirmation_number ?? "Not reported"}\n`,
+  );
+  stream.write(`SMS requested: ${confirmation?.sms_requested === true ? "Yes" : "No"}\n`);
+  stream.write(`Email delivery: ${reservationEmailMode(reservation)}\n`);
+}
+
+function reportReservationEmail(evidence, stream) {
+  stream.write(`Email delivery: ${evidence.email_delivery_mode}\n`);
+  if (evidence.messages.length === 0) {
+    stream.write("No reservation email has arrived.\n");
+    return;
+  }
+  evidence.messages.forEach((message, index) => {
+    stream.write(`\n${index + 1}. ${message.subject}\n`);
+    stream.write(`Received: ${message.received_at}\n`);
+    stream.write(`From: ${message.from}\n`);
+    stream.write(`Forwarding: ${message.forwarding.status}\n`);
+    if (message.text_body) stream.write(`${message.text_body}\n`);
+    else if (message.html_body) stream.write(`${message.html_body}\n`);
+  });
 }
 
 async function activeClient(dependencies, requiredKind = "user") {
@@ -520,15 +771,24 @@ export async function runCli(args, supplied = {}) {
   }
 
   if (group === "reservation" && action === "run") {
-    const { options, positional } = parseOptions(rest, new Set(["file"]));
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["file", "json"]),
+      new Set(["json"]),
+    );
     if (positional.length > 0) {
       throw new Error("Unexpected reservation argument.");
     }
     const { client } = await activeClient(dependencies, "user");
     const request = await dependencies.readJsonFile(required(options, "file"));
-    const result = await client.runReservation(request, {
-      onTurn: (reservation) =>
-        reportReservationTurn(reservation, dependencies.stderr),
+    let lastConfirmationPrompt;
+    let result = await client.runReservation(request, {
+      onTurn: (reservation) => {
+        if (reservation.turn?.type === "confirmation_required") {
+          lastConfirmationPrompt = reservation.turn.confirmation_prompt;
+        }
+        reportReservationTurn(reservation, dependencies.stderr);
+      },
       respond: async (reservation) => {
         if (reservation.status === "confirmation_required") {
           const accepted = dependencies.confirm
@@ -546,10 +806,47 @@ export async function runCli(args, supplied = {}) {
             ? "Yes, confirm this exact booking."
             : "No, do not book this reservation.";
         }
+        if (reservation.turn?.type === "options") {
+          return browseReservationOptions(reservation, client, dependencies);
+        }
         return String(await visiblePrompt("Your reply: ", dependencies)).trim();
       },
     });
-    writeJson(dependencies.stdout, result);
+    const completedBooking = result.status === "confirmed";
+    if (completedBooking) {
+      if (options.json !== true) {
+        reportReservationResult(
+          result,
+          lastConfirmationPrompt,
+          dependencies.stdout,
+        );
+      }
+      if (
+        isAffirmative(
+          await visiblePrompt(
+            "Cancel this reservation now? [y/N] ",
+            dependencies,
+          ),
+        )
+      ) {
+        result = await client.cancelReservation(result.id, result.revision);
+        if (options.json !== true) {
+          if (result.status === "cancelled") {
+            dependencies.stdout.write("Reservation cancelled\n");
+            dependencies.stdout.write(
+              `Confirmation: ${result.turn?.cancellation?.confirmation_number ?? result.turn?.confirmation?.confirmation_number ?? "Not reported"}\n`,
+            );
+          } else {
+            dependencies.stdout.write(
+              `Cancellation status: ${result.status}\n`,
+            );
+          }
+        }
+      }
+    }
+    if (options.json === true || !completedBooking) {
+      writeJson(dependencies.stdout, result);
+    }
     return;
   }
 
@@ -560,6 +857,22 @@ export async function runCli(args, supplied = {}) {
     return;
   }
 
+  if (group === "reservation" && action === "email") {
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["json"]),
+      new Set(["json"]),
+    );
+    if (positional.length !== 1) {
+      throw new Error("A reservation ID is required.");
+    }
+    const { client } = await activeClient(dependencies, "user");
+    const evidence = await client.getReservationEmail(positional[0]);
+    if (options.json === true) writeJson(dependencies.stdout, evidence);
+    else reportReservationEmail(evidence, dependencies.stdout);
+    return;
+  }
+
   if (group === "reservation" && action === "options") {
     const { options, positional } = parseOptions(
       rest,
@@ -676,9 +989,9 @@ export async function runCli(args, supplied = {}) {
         );
         return /^y(?:es)?$/iu.test(answer.trim());
       },
-      message: (checkout) =>
+      message: (checkout, question) =>
         visiblePrompt(
-          `${checkout.activity || "Shopstack needs more information"}: `,
+          `${question?.content || checkout.activity || "Shopstack needs more information"}: `,
           dependencies,
         ),
       paymentDetails: async () => ({

package/src/client.d.ts

@@ -39,6 +39,7 @@ export interface CreateCheckoutRequest {
 }
 
 export interface ReservationDiner {
+  /** ISO 3166-1 alpha-2 country for phone_number, not the restaurant location. */
   country: string;
   /** Optional booking contact address. If omitted, Shopstack creates a temporary inbox. */
   email?: string;
@@ -115,6 +116,18 @@ export interface PaymentApproval {
   expires_at: string;
 }
 
+export interface CheckoutQuestion {
+  id: string;
+  content: string;
+  sequence: number;
+}
+
+export interface CheckoutMessage extends CheckoutQuestion {
+  checkout_id: string;
+  role: "user" | "assistant";
+  created_at: string;
+}
+
 export interface Checkout {
   id: string;
   status:
@@ -172,11 +185,26 @@ export interface Reservation {
   updated_at: string;
   /** Search-session expiry; it does not end the life of a confirmed booking. */
   expires_at: string;
+  /** Present only when Shopstack forwards provider email from its reservation inbox. */
+  email_delivery?: {
+    mode: "shopstack_forwarded";
+    status: "pending" | "sent" | "failed";
+  };
   /** Last retained time for reading and managing the confirmed booking. */
 }
 
 export type ReservationTurn =
-  | { type: "question" | "message"; message: string }
+  | {
+      type: "question" | "message";
+      message: string;
+      error_code?:
+        | "BOOKING_REJECTED"
+        | "BOOKING_UNKNOWN"
+        | "DINER_ALREADY_REGISTERED"
+        | "DINER_PHONE_INVALID"
+        | "DINER_PROFILE_INVALID"
+        | "UPSTREAM_UNAVAILABLE";
+    }
   | {
       type: "location_options";
       message: string;
@@ -208,8 +236,13 @@ export type ReservationTurn =
         confirmation_number: string;
         restaurant: string;
         date_time: string;
+        email_delivery_mode:
+          | "direct"
+          | "shopstack_forwarded"
+          | "shopstack_managed";
         party_size: number;
         status: string;
+        sms_requested: true;
       };
     }
   | {
@@ -264,6 +297,24 @@ export interface ReservationOptionPage {
   total_available: number;
 }
 
+export interface ReservationEmailEvidence {
+  email_delivery_mode: "direct" | "shopstack_forwarded" | "shopstack_managed";
+  messages: {
+    forwarding: {
+      attempt_count: number;
+      last_error_category?: string;
+      sent_at?: string;
+      status: "failed" | "not_applicable" | "pending" | "sent";
+    };
+    from: string;
+    html_body?: string;
+    received_at: string;
+    subject: string;
+    text_body?: string;
+  }[];
+  reservation_id: string;
+}
+
 export interface RunReservationOptions {
   idempotencyKey?: string;
   onTurn?(reservation: Reservation): void | Promise<void>;
@@ -287,6 +338,7 @@ export interface RunCheckoutOptions {
   ): boolean | Promise<boolean | undefined> | undefined;
   message?(
     checkout: Checkout,
+    question: CheckoutQuestion,
   ): string | Promise<string | undefined> | undefined;
 }
 
@@ -415,6 +467,7 @@ export class ShopstackClient {
     options?: ReservationMutationOptions,
   ): Promise<Reservation>;
   getReservation(reservationId: string): Promise<Reservation>;
+  getReservationEmail(reservationId: string): Promise<ReservationEmailEvidence>;
   listReservationOptions(
     reservationId: string,
     options?: { limit?: number; offset?: number },
@@ -470,7 +523,17 @@ export class ShopstackClient {
     content: string,
     options?: { idempotencyKey?: string },
   ): Promise<Record<string, unknown>>;
-  listMessages(checkoutId: string): Promise<Record<string, unknown>>;
+  listMessages(
+    checkoutId: string,
+    options?: { after?: string; limit?: number },
+  ): Promise<{
+    data: CheckoutMessage[];
+    has_more: boolean;
+    next_cursor: string | null;
+  }>;
+  getCheckoutQuestion(
+    checkout: Checkout,
+  ): Promise<CheckoutQuestion | undefined>;
   listEvents(checkoutId: string): Promise<Record<string, unknown>>;
   providePaymentDetails(
     checkoutId: string,

package/src/client.js

@@ -384,6 +384,12 @@ export class ShopstackClient {
     return this.request(`/reservations/${encodeURIComponent(reservationId)}`);
   }
 
+  getReservationEmail(reservationId) {
+    return this.request(
+      `/reservations/${encodeURIComponent(reservationId)}/email`,
+    );
+  }
+
   listReservationOptions(reservationId, { limit = 6, offset = 0 } = {}) {
     const query = new URLSearchParams({
       offset: String(offset),
@@ -525,8 +531,47 @@ export class ShopstackClient {
     );
   }
 
-  listMessages(checkoutId) {
-    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/messages`);
+  listMessages(checkoutId, { after, limit } = {}) {
+    const query = new URLSearchParams();
+    if (after !== undefined) query.set("after", after);
+    if (limit !== undefined) query.set("limit", String(limit));
+    const suffix = query.size ? `?${query}` : "";
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/messages${suffix}`,
+    );
+  }
+
+  async getCheckoutQuestion(checkout) {
+    if (
+      checkout.status !== "help_required" ||
+      checkout.required_input !== undefined
+    )
+      return undefined;
+    let latest;
+    let after;
+    const cursors = new Set();
+    do {
+      const page = await this.listMessages(checkout.id, { after, limit: 100 });
+      latest = page.data.at(-1) ?? latest;
+      if (!page.has_more) break;
+      if (
+        typeof page.next_cursor !== "string" ||
+        !page.next_cursor ||
+        cursors.has(page.next_cursor)
+      )
+        throw new Error("Checkout message pagination did not advance.");
+      after = page.next_cursor;
+      cursors.add(after);
+    } while (true);
+    // A posted answer can arrive before the runner changes help_required.
+    // Never ask an already answered question again during that interval.
+    if (latest?.role !== "assistant" || latest.checkout_id !== checkout.id)
+      return undefined;
+    return {
+      id: latest.id,
+      content: latest.content,
+      sequence: latest.sequence,
+    };
   }
 
   listEvents(checkoutId) {
@@ -640,8 +685,16 @@ export class ShopstackClient {
           handledMessageRevision !== checkout.revision
         ) {
           if (typeof options.message !== "function") return checkout;
+          const question = await this.getCheckoutQuestion(checkout);
+          if (question === undefined) {
+            await monitor.wait(
+              checkout.presentation_revision ?? 0,
+              timeoutMs - (Date.now() - startedAt),
+            );
+            continue;
+          }
           handledMessageRevision = checkout.revision;
-          const content = await options.message(checkout);
+          const content = await options.message(checkout, question);
           if (typeof content !== "string" || content.length === 0)
             return checkout;
           await this.sendMessage(checkout.id, content, {