@trusty-squire/mcp 1.1.13-rc.8 → 1.1.13

package/dist/tools/provision-drive.js

@@ -6,51 +6,44 @@
 // in place; the consent-at-install prompt is the remaining hardening.
 import { z } from "zod";
 import { constants, generateKeyPairSync, privateDecrypt } from "node:crypto";
-import { startProvisionSession, observe, captureScreenshot, act, cartAdd, formSelectMany, TargetStaleError, extractCredentials, captchaGate, awaitVerification, finishProvisionSession, finishProvisionSessionWithPreparation, observedHostsForSession, currentProvisionUrl, stashSecretSlot, readSecretSlotValue, getSessionUserEmail, generatePassword, rememberRecipe, verifyActiveRecipePostcondition, verifySavedRecipePostcondition, captureAndPromoteSession, replayOperatorRecipe, emitProvisionMeasurement, checkoutShapeSignatureForSession, manualCardEntryBlockReason, } from "../bot/provision-session.js";
+import { startProvisionSession, observe, captureScreenshot, observeQuery, act, cartAdd, cartClear, formSelectMany, TargetStaleError, extractCredentials, captchaGate, awaitVerification, finishProvisionSession, finishProvisionSessionWithPreparation, observedHostsForSession, currentProvisionUrl, stashSecretSlot, readSecretSlotValue, getSessionUserEmail, generatePassword, rememberRecipe, verifyActiveRecipePostcondition, verifySavedRecipePostcondition, captureAndPromoteSession, replayOperatorRecipe, emitProvisionMeasurement, checkoutShapeSignatureForSession, manualCardEntryBlockReason, } from "../bot/provision-session.js";
 import { signSkillForPublish } from "../skill-cli/signing.js";
 import { readRecipe, readRecipeForTask, readRecipeForCheckoutShape, readRecipeFromFile, renderOperatorRecipeHint, recipeEntryUrl, fillTemplate, operatorRecipeDomain, checkoutShapeKey, isCheckoutShapeKey, isSameRecipeDomain, OperatorVerbSchema, RecipeHoleSchema, PostconditionSchema, } from "../bot/operator-recipe.js";
 import { isMaskedDisplay } from "../bot/credential-shape.js";
 import { renderSkillHint, serviceSlugFromUrl } from "../bot/skill-hint.js";
 import { clientFromEnv, generateProvisionId } from "../skill-registry-client.js";
 import { openSessionStorage } from "../session.js";
-// PR2 — read the install-time inbox-read consent. Default-OFF: a missing flag
-// (older sessions, no session file) means "not consented", so awaitVerification
-// fails closed and hands the code request back to the user. Operator/housekeeper
-// deployments set consent_operator_inbox_otp=true.
+import { servingAccountId } from "../session-guard.js";
+// Read the install-time inbox-read preference. Inbox reads default on; an
+// explicit false in the saved advanced configuration remains an opt-out.
 async function readInboxConsent() {
     try {
-        const storage = await openSessionStorage();
-        const data = await storage.read();
-        return data?.consent_operator_inbox_otp === true;
+        const accountId = resolveAccountId();
+        if (accountId === undefined)
+            return true;
+        const data = await (await openSessionStorage()).read(accountId);
+        return data?.consent_operator_inbox_otp !== false;
     }
     catch {
-        return false;
+        return true;
     }
 }
-// The account the install is bound to. Operator/CI runs set it in the env;
-// end-user installs bind it in session.json (connect writes it there, NOT to the
-// MCP config env). Reading env-only silently disabled BOTH the hint read and the
-// auto-promote write for every end-user install — resolve from the session file
-// as the fallback so the registry loop works off a normal `connect`.
-async function resolveAccountId() {
-    const fromEnv = process.env.TRUSTY_SQUIRE_ACCOUNT_ID;
-    if (fromEnv !== undefined && fromEnv.length > 0)
-        return fromEnv;
-    try {
-        const data = await (await openSessionStorage()).read();
-        const id = data?.account_id;
-        return id !== undefined && id.length > 0 ? id : undefined;
-    }
-    catch {
-        return undefined;
-    }
+// The account THIS server adopted, as published by its SessionGuard. Never
+// re-resolve it here from TRUSTY_SQUIRE_ACCOUNT_ID or the store's
+// current-account pointer: a server launched from a pre-pin config binds by
+// fallback, and re-resolving after another account connects would hand this
+// tool the wrong account — applying that account's consent setting and
+// attributing registry reads/publishes to it. That is exactly the "acting as
+// an account it never bound to" defect this work exists to remove.
+function resolveAccountId() {
+    return servingAccountId();
 }
 // Best-effort: ask the registry for a known route for this service so the agent
 // drives on rails instead of ad-hoc. Returns undefined on any miss (no skill,
 // no registry configured, network error) — the agent just drives without it.
 async function resolveRouteHint(serviceUrl) {
     try {
-        const accountId = await resolveAccountId();
+        const accountId = resolveAccountId();
         if (accountId === undefined || accountId.length === 0)
             return undefined;
         const client = clientFromEnv(accountId);
@@ -90,7 +83,7 @@ async function autoPromoteProvision(sessionId) {
                 : "";
             return `rejected:${promoted.error_kind ?? "unknown"}${detail}`;
         }
-        const accountId = await resolveAccountId();
+        const accountId = resolveAccountId();
         if (accountId === undefined || accountId.length === 0)
             return "produced:no_account";
         const client = clientFromEnv(accountId);
@@ -126,7 +119,7 @@ async function autoPromoteProvision(sessionId) {
 export async function publishRecipeToRegistry(file) {
     try {
         const recipe = await readRecipeFromFile(file);
-        const accountId = await resolveAccountId();
+        const accountId = resolveAccountId();
         if (accountId === undefined || accountId.length === 0)
             return "skipped:no_account";
         const client = clientFromEnv(accountId);
@@ -159,7 +152,7 @@ export async function resolveRecipeForTask(verb, serviceUrl) {
         return await readRecipeForTask(verb, serviceUrl);
     }
     catch (localErr) {
-        const accountId = await resolveAccountId();
+        const accountId = resolveAccountId();
         if (accountId === undefined || accountId.length === 0)
             throw localErr;
         const client = clientFromEnv(accountId);
@@ -183,7 +176,7 @@ export async function resolveCheckoutLegRecipe(verb, signature) {
         return await readRecipeForCheckoutShape(verb, signature);
     }
     catch {
-        const accountId = await resolveAccountId();
+        const accountId = resolveAccountId();
         if (accountId === undefined || accountId.length === 0)
             return null;
         const client = clientFromEnv(accountId);
@@ -278,15 +271,15 @@ const startSchema = z.object({
     // Operate tasks that act AS the user (drive a gated app on an existing
     // account) set this so start fails closed to a connect hand-back if no live
     // Google session exists — rather than driving into a mid-task login wall.
-    require_live_identity: z.boolean().optional(),
 });
-const OBSERVE_DELTA_CONTRACT = "Compact observations carry their elements in `el_table`: a TAB-delimited table whose FIRST line is the " +
+const OBSERVE_DELTA_CONTRACT = "The following observation rules are V1-only (TRUSTY_SQUIRE_OBSERVE_V2=off or shadow). " +
+    "In V1 compact observations, elements are carried in `el_table`: a TAB-delimited table whose FIRST line is the " +
     "header (tab-joined column names, a subset of ref,label,tag,role,type,value_len,checked,href,testId," +
     "topmost,occluded_by, always starting ref,label,tag) and each following line is ONE element (tab-joined " +
     "cells in header order). An empty cell = that field is absent for that element; value_len is a number, " +
     "checked/topmost are true/false; a tab, newline, carriage-return or backslash inside a cell is " +
     "backslash-escaped (\\t \\n \\r \\\\). el_table is absent when the emit has no element rows. " +
-    "stable refs remain reusable across observes while their controls still exist. " +
+    "In V1, stable refs remain reusable across observes while their controls still exist. " +
     "The first observe, a URL change, or high churn returns delta:false as a full resync: discard the prior " +
     "element map and rebuild it from this el_table (or from snapshot_file — the table may omit collapsed " +
     "chrome links, which the file keeps); a delta:false with NO snapshot_file already has the complete, " +
@@ -295,17 +288,40 @@ const OBSERVE_DELTA_CONTRACT = "Compact observations carry their elements in `el
     "in removed, and retain the remaining elements counted by unchanged. text_unchanged:true means reuse the " +
     "prior text because text is empty. snapshot_file points to the complete current snapshot (all elements, " +
     "with path). An empty delta (no el_table) means nothing changed, not an empty page. " +
-    'detail:"full" instead returns the legacy `elements` JSON array (every field), never el_table. ' +
+    'In V1, detail:"full" instead returns the legacy `elements` JSON array (every field), never el_table. ' +
     "If a control you can see in `text`/the screenshot has NO row in el_table (a bare unlabeled clickable " +
     'div — e.g. some SPA "Add To Cart" buttons), it has no ref: click it with operate_act click/js_click ' +
     'target=`text="…"` or `css=…` (see operate_act). `click` respects actionability and throws if an overlay ' +
     "intercepts; dismiss the overlay or deliberately use `js_click`, which directly dispatches through a " +
-    "transparent overlay. ";
+    "transparent overlay. Under default compact-v2, only refs and @labels from the current action map are " +
+    "accepted. A ref is a durable element fingerprint: it stays valid across acts and benign re-renders on the same " +
+    "document, so one observation can drive several acts. On opaque `stale_ref`, call operate_observe and choose a " +
+    "new ref; do not retry the old one or use V1 replacement candidates or locator fallback. ";
+const COMPACT_V2_CONTRACT = "When format is `compact-v2`, use its action map: session_id is the continuation handle; `url` is the live page URL; `stage` is a finite enum; " +
+    "semantic carries the page title and primary visible heading; safe_table rows use [ref,role,facts?], where role is " +
+    "b=button,l=link,t=textbox,s=select,c=checkbox,r=radio,tb=tab,m=menuitem,f=file. ref is an opaque durable " +
+    "element handle. facts is a pipe-delimited string: an optional first unkeyed segment is the row's @label alias, " +
+    "a slug of its short label that operate_act also accepts as a target. " +
+    "The label is followed by any present s=<state bitset>, a=<action>, " +
+    "f=<field>, q=<choice position>/<choice total>, and x=<frame> segments. Fact-only rows begin with a keyed segment. " +
+    "State bitset codes are c=checked,u=unchecked,d=disabled,r=required; frame codes are x=s for a same-origin child " +
+    "and x=x for a cross-origin child, while an omitted x means the main frame. Actions are search,close,next,previous,submit," +
+    "continue,login,signup,add_to_cart,view_cart,checkout,payment,destructive; fields are email,password,username,name,phone,search,address," +
+    "city,region,postal,country,date,quantity,promo,payment. Short labels are included for viewport-prioritized controls; " +
+    "labels are exactly what the page renders. The row form omits field " +
+    "values purely as a size budget: read a value off the page with operate_screenshot, or with an explicitly " +
+    "selected V1 session. For a named product/control from the task, " +
+    "call operate_observe_query with those task words; it returns matching actionable refs with labels " +
+    "and code-owned facts. Use overflow.next_cursor to page. `detail:full` keeps the V2 format while V2 is enabled; " +
+    "set TRUSTY_SQUIRE_OBSERVE_V2=off for the legacy format. A delta:true delta retains the preceding V2 table, then upserts tuple rows in safe_table, " +
+    "removes refs in removed, and updates stage or semantic only when either changed. Omitted semantic title/heading remains from the preceding V2 page. " +
+    "A delta with none of those fields means the view is unchanged. ";
 export const provisionStartTool = {
     name: "operate_start",
     description: "Begin an interactive website task: opens a scoped browser on the " +
         "user's machine at service_url and returns the initial compact observation " +
-        "{session_id, url, text, el_table, delta, snapshot_file}. " +
+        "(legacy el_table/delta or compact-v2 safe_table). " +
+        COMPACT_V2_CONTRACT +
         OBSERVE_DELTA_CONTRACT +
         "YOU are the planner — read the observation, then drive the signup, setup, or " +
         "checkout with operate_act (and operate_pay for a purchase), re-read with " +
@@ -327,7 +343,6 @@ export const provisionStartTool = {
             },
             allowed_hosts: { type: "array", items: { type: "string" } },
             extra_allowed_hosts: { type: "array", items: { type: "string" } },
-            require_live_identity: { type: "boolean" },
         },
     },
     async handler(args, api) {
@@ -339,7 +354,6 @@ export const provisionStartTool = {
             consentInboxRead,
             ...(args.proxy !== undefined ? { proxyUrl: args.proxy } : {}),
             ...(extra.length > 0 ? { extraAllowedHosts: extra } : {}),
-            ...(args.require_live_identity === true ? { requireLiveIdentity: true } : {}),
             ...(hint !== undefined ? { hint } : {}),
             // Thread the api-client so the captcha gate can spend a vaulted 2Captcha key.
             ...(api !== null ? { api } : {}),
@@ -348,24 +362,19 @@ export const provisionStartTool = {
 };
 const observeSchema = z.object({
     session_id: z.string().min(1),
-    // Payload verbosity. Default "compact" (stable-ref element/text deltas plus a
-    // complete snapshot pointer). Pass "full" for the legacy
-    // screen+accessibility+full-field payload on a genuinely ambiguous step.
+    // Payload verbosity within the selected observation mode. In V2 both values
+    // return the compact action map; in V1, full requests the legacy expanded payload.
     detail: z.enum(["compact", "full"]).optional(),
 });
 export const provisionObserveTool = {
     name: "operate_observe",
-    description: "Re-read the current page of an operate session. DEFAULT is a COMPACT " +
-        "payload whose elements ride in `el_table` (a tab-delimited table; each row's " +
-        "stable `ref` is the operate_act.target) with compact label/role/href/value_len " +
-        "columns and `frame_origin` on child-frame controls; ordinary same- and " +
-        "cross-origin frames are included, while known captcha challenge frames stay " +
-        "behind the dedicated captcha flow. Path is retained only in snapshot_file, " +
-        "and redundant screen/accessibility trees are omitted. " +
+    description: "Re-read the current page of an operate session. The default compact-v2 mode returns the compact " +
+        'safe_table action map; `detail:"full"` stays in that format and does not restore legacy fields. ' +
+        COMPACT_V2_CONTRACT +
+        "Only explicitly selected V1 modes use el_table, reusable stable refs, locator fallbacks, snapshot_file, " +
+        "or the legacy expanded elements payload. " +
         OBSERVE_DELTA_CONTRACT +
-        "Pass " +
-        'detail:"full" for the legacy screen+accessibility+full-field payload on a ' +
-        "genuinely ambiguous step.",
+        'In V1 only, pass detail:"full" for the legacy screen+accessibility+full-field payload on a genuinely ambiguous step.',
     inputSchema: observeSchema,
     jsonInputSchema: {
         type: "object",
@@ -396,18 +405,19 @@ const screenshotSchema = z.object({
 });
 export const provisionScreenshotTool = {
     name: "operate_screenshot",
-    description: "Debugging tool: capture a screenshot of what the operate session's browser actually RENDERS — " +
+    description: "WARNING: EXPENSIVE — a screenshot is a full image and costs far more context than any " +
+        "observation. Reach for it ONLY when the DOM serialization (Compact V2 safe_table, " +
+        "operate_observe, operate_observe_query) is NOT sufficient to determine the page state; " +
+        "if the tables already tell you what the page is doing, do not take one. " +
+        "Debugging tool: capture a screenshot of what the operate session's browser actually RENDERS — " +
         "the whole page (default: viewport; full_page:true for the whole scrollable page) or ONE specific " +
         "frame in isolation via frame_index or frame_url_contains, so a cross-origin challenge iframe (a " +
         "3-D Secure ACS frame, a captcha) can be captured on its own even when it won't show clearly inside " +
-        "a full-page shot. Use this when text/el_table from operate_observe isn't enough to tell what state " +
+        "a full-page shot. Use this when safe_table from Compact V2, or text/el_table from an explicitly " +
+        "selected V1 session, isn't enough to tell what state " +
         "a stuck page is actually in — a challenge that never advances, an unexpected layout, a captcha you " +
         "need to SEE. Read-only: never navigates, clicks, types, submits, or steals focus; it only reads " +
-        "pixels. Money-fence: refuses (screenshot_unavailable_sealed_context) during an active card fill or " +
-        "when a frame included in this capture still holds a sealed secret or card-shaped value. It fails closed " +
-        "when that frame cannot be checked, while capture-time masking remains a second fence. A historical fill " +
-        "does not block an isolated 3-D Secure/challenge frame or a page navigated away from the sealed form. " +
-        "If you need to see a page WHILE a card fill is in progress, finish or cancel the payment step first.",
+        "pixels. The image is the page's real pixels, whatever the page is showing.",
     inputSchema: screenshotSchema,
     jsonInputSchema: {
         type: "object",
@@ -429,6 +439,50 @@ export const provisionScreenshotTool = {
         });
     },
 };
+const observeQuerySchema = z.object({
+    session_id: z.string().min(1),
+    // This string is matched only inside the live session; returned rows remain
+    // the compact-v2 enum-only action map.
+    query: z.string().max(160).default(""),
+    role: z
+        .enum(["button", "link", "textbox", "select", "checkbox", "radio", "tab", "menuitem", "file"])
+        .optional(),
+    cursor: z.string().max(1_024).optional(),
+});
+export const provisionObserveQueryTool = {
+    name: "operate_observe_query",
+    description: "Page compact-v2 overflow or named-control lookup. Supply the product/control words already in the task; " +
+        "matching happens only inside the live browser and returns actionable opaque refs plus finite role/state/action " +
+        "enums. Use overflow.next_cursor to page controls, or hint_overflow.next_cursor with an empty query to page " +
+        "trusted start routing metadata; never read a snapshot file.",
+    inputSchema: observeQuerySchema,
+    jsonInputSchema: {
+        type: "object",
+        required: ["session_id"],
+        properties: {
+            session_id: { type: "string" },
+            query: { type: "string" },
+            role: {
+                type: "string",
+                enum: [
+                    "button",
+                    "link",
+                    "textbox",
+                    "select",
+                    "checkbox",
+                    "radio",
+                    "tab",
+                    "menuitem",
+                    "file",
+                ],
+            },
+            cursor: { type: "string" },
+        },
+    },
+    async handler(args) {
+        return await observeQuery(args.session_id, args.query, args.role, args.cursor);
+    },
+};
 // Shared credential destination shape. Both operate_act(kind:"extract") and
 // the legacy operate_extract alias validate and execute this exact contract.
 // The credentials terminal also reuses it below.
@@ -459,7 +513,8 @@ const storeJsonProps = {
 const formSelectionsSchema = z
     .record(z.string().min(1).max(200), z.string().min(1).max(4096))
     .refine((value) => Object.keys(value).length > 0, "Provide at least one selection")
-    .refine((value) => Object.keys(value).length <= 12, "At most 12 selections per call");
+    .refine((value) => Object.keys(value).length <= 12, "At most 12 selections per call")
+    .describe("Map each current Compact V2 @e: ref or @label, or V1 observed label/ref, to its visible option text.");
 const actSchema = z
     .object({
     session_id: z.string().min(1),
@@ -479,6 +534,7 @@ const actSchema = z
         "scroll",
         "upload",
         "cart_add",
+        "cart_clear",
         "select_many",
         "extract",
         "solve_captcha",
@@ -496,6 +552,7 @@ const actSchema = z
     path: z.string().min(1).max(4096).optional(),
     url: z.string().url().optional(),
     key: z.string().min(1).max(40).optional(),
+    provider: z.enum(["google", "github"]).optional(),
     // allow_host: a bare hostname to cross into mid-session.
     host: z.string().min(1).max(253).optional(),
     // type_secret: the sealed slot whose value to type into `target`.
@@ -661,6 +718,7 @@ const ACTION_KINDS = [
     "scroll",
     "upload",
     "cart_add",
+    "cart_clear",
     "select_many",
     "extract",
     "solve_captcha",
@@ -682,13 +740,21 @@ const ACTION_REPAIR_BY_KIND = {
         safe_alternative: "Retry cart_add with the same stable idempotency_key for the same product_identity and options_hash. Do not replace it with click: cart_add reserves the mutation and exact-line post-verifies the cart." +
             manualCardRecovery,
     },
+    cart_clear: {
+        example: {
+            session_id: "<session_id>",
+            kind: "cart_clear",
+        },
+        safe_alternative: "Retry cart_clear with only session_id — it empties the cart so a following cart_add reaches a known quantity, regardless of what accumulated in the persistent browser profile's cart across earlier sessions." +
+            manualCardRecovery,
+    },
     select_many: {
         example: {
             session_id: "<session_id>",
             kind: "select_many",
-            selections: { "Observed field label": "Visible option label" },
+            selections: { "@e:<current-handle>": "Visible option label" },
         },
-        safe_alternative: "Retry select_many with selections in the intended order. It selects sequentially, re-observes after each success, and returns partial results; do not replace it with parallel select calls." +
+        safe_alternative: "Retry select_many with selections in the intended order. Compact V2 requires current @e: handles; V1 accepts observed labels or refs. It selects sequentially, re-observes after each success, and returns partial results; do not replace it with parallel select calls." +
             manualCardRecovery,
     },
     extract: {
@@ -698,7 +764,7 @@ const ACTION_REPAIR_BY_KIND = {
             into_slot: "sealed_secret",
             secret_label: "API key",
         },
-        safe_alternative: "Retry extract after navigating to the credential page. Use into_slot with optional secret_label to seal a value without exposing it, or store with a service to vault it; never put credential values in arguments or seal a still-masked value." +
+        safe_alternative: "Retry extract after navigating to the credential page. Use into_slot with optional secret_label to hold a value in a session slot for a later type_secret, or store with a service to vault it; never put credential values in arguments." +
             manualCardRecovery,
     },
     solve_captcha: {
@@ -715,9 +781,9 @@ const ACTION_REPAIR_BY_KIND = {
             kind: "await_verification",
             sender: "service.example",
             into_slot: "otp",
-            grant_inbox_consent: false,
+            grant_inbox_consent: true,
         },
-        safe_alternative: "Retry await_verification with sender scoped to the service and prefer into_slot so the OTP stays sealed. Leave grant_inbox_consent false unless the user explicitly agrees; only retry with grant_inbox_consent:true after that explicit yes." +
+        safe_alternative: "Retry await_verification with sender scoped to the service and prefer into_slot so the OTP stays sealed. Inbox reading is on by default; pass grant_inbox_consent:false to opt out for this session." +
             manualCardRecovery,
     },
     login_prepare_signup: {
@@ -818,9 +884,17 @@ function buildAction(args) {
         case "js_click":
             return { kind: "js_click", target: need(args.target, "target") };
         case "oauth_click":
-            return { kind: "oauth_click", target: need(args.target, "target") };
+            return {
+                kind: "oauth_click",
+                target: need(args.target, "target"),
+                ...(args.provider === undefined ? {} : { provider: args.provider }),
+            };
         case "oauth_login":
-            return { kind: "oauth_login", target: need(args.target, "target") };
+            return {
+                kind: "oauth_login",
+                target: need(args.target, "target"),
+                ...(args.provider === undefined ? {} : { provider: args.provider }),
+            };
         case "type":
             return {
                 kind: "type",
@@ -867,6 +941,7 @@ function buildAction(args) {
         case "upload":
             return { kind: "upload", target: need(args.target, "target"), path: need(args.path, "path") };
         case "cart_add":
+        case "cart_clear":
         case "select_many":
         case "extract":
         case "solve_captcha":
@@ -880,29 +955,34 @@ function buildAction(args) {
 async function handleCartAdd(args) {
     return await cartAdd(args.session_id, args.product_identity, args.options_hash, args.idempotency_key);
 }
+async function handleCartClear(args) {
+    return await cartClear(args.session_id);
+}
 async function handleFormSelectMany(args) {
     return await formSelectMany(args.session_id, args.selections);
 }
 async function handleExtract(args, api) {
     const extracted = await extractCredentials(args.session_id);
-    // Sealed transfer: capture the primary secret into a session-local slot and
-    // return ONLY a masked handle. The value never reaches the host. A later
-    // type_secret enters it into another site's form. Mutually exclusive with
-    // store (a slotted secret is being shuttled, not vaulted, in this call).
+    // Slot transfer: capture the primary secret into a session-local slot so a
+    // later type_secret can enter it into another site's form without the host
+    // having to relay it. Mutually exclusive with store (a slotted secret is
+    // being shuttled, not vaulted, in this call).
     if (args.into_slot !== undefined) {
         const values = extracted.credentials;
-        // A still-masked display (Google's OAuth secret shows "GOCSPX-••••" with a
-        // copy button) must NOT be sealed — the slot would hold junk. Reject any
-        // value with mask glyphs (canonical isMaskedDisplay) or the truncated-capture
-        // marker, and prefer a full value over the masked api_key when the page has both.
         const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
-        const candidates = Object.entries(values).filter(([k, v]) => !k.endsWith("_truncated") && typeof v === "string" && v.length >= 8 && !isMaskedDisplay(v));
+        const candidates = Object.entries(values).filter(([k, v]) => !k.endsWith("_truncated") && typeof v === "string" && v.length >= 8);
+        // A value that still LOOKS masked is never refused — it is simply ranked
+        // last, so a fully revealed sibling wins when the page shows both.
+        const ranked = [
+            ...candidates.filter(([, v]) => !isMaskedDisplay(v)),
+            ...candidates.filter(([, v]) => isMaskedDisplay(v)),
+        ];
         // When the page shows several credentials (Google's client ID + secret),
         // a secret_label picks the right one by field name; otherwise take the
         // first full value. Falling back avoids a hard fail when the label misses.
         const wantKey = args.secret_label !== undefined ? norm(args.secret_label) : null;
-        const matched = wantKey !== null ? candidates.find(([k]) => norm(k).includes(wantKey)) : undefined;
-        const full = (matched ?? candidates[0])?.[1];
+        const matched = wantKey !== null ? ranked.find(([k]) => norm(k).includes(wantKey)) : undefined;
+        const full = (matched ?? ranked[0])?.[1];
         if (typeof full !== "string" || full.length === 0) {
             return {
                 session_id: extracted.session_id,
@@ -910,21 +990,17 @@ async function handleExtract(args, api) {
                 candidate_count: extracted.candidate_count,
                 sealed: false,
                 slot: null,
-                blocked_reason: "the secret is still masked/hidden — reveal it first (click the " +
-                    'show/reveal/copy control near the key), then operate_act { kind: "extract" } again',
+                blocked_reason: "no credential value was found on this page — navigate to the keys/settings " +
+                    'page, then operate_act { kind: "extract" } again',
             };
         }
         const handle = stashSecretSlot(args.session_id, args.into_slot, full);
-        // Strip raw credential VALUES from the response — host gets the handle only.
         return {
             session_id: extracted.session_id,
             url: extracted.url,
             candidate_count: extracted.candidate_count,
             sealed: true,
             slot: handle,
-            ...(extracted.blocked_reason !== undefined
-                ? { blocked_reason: extracted.blocked_reason }
-                : {}),
         };
     }
     if (args.store === undefined || Object.keys(extracted.credentials).length === 0) {
@@ -943,18 +1019,19 @@ async function handleAwaitVerification(args) {
     return await awaitVerification(args.session_id, {
         ...(args.sender !== undefined ? { sender: args.sender } : {}),
         ...(args.into_slot !== undefined ? { intoSlot: args.into_slot } : {}),
-        ...(args.grant_inbox_consent === true ? { grantConsent: true } : {}),
+        ...(args.grant_inbox_consent !== undefined ? { grantConsent: args.grant_inbox_consent } : {}),
     });
 }
 export const provisionActTool = {
     name: "operate_act",
-    description: "Take one action in an operate session, then return the resulting " +
-        "observation. kinds: click (target=element ref, preferably an el_table row's ref), " +
+    description: "Take one action in an operate session. Under compact-v2 the default follow-up is a compact delta " +
+        "when its action map is unchanged; call operate_observe or operate_observe_query when you need a new map. " +
+        "kinds: click (target=element ref, preferably a safe_table row's ref), " +
         "type (target + text; model-supplied card-number-shaped text is refused — card payment " +
         "must use operate_pay, which fills a vaulted card without exposing it to the model), " +
         "" +
-        "TARGET FALLBACK (clicking or typing only) — when a control you can SEE (in the " +
-        "observation text or screenshot) has NO ref in el_table (a bare click-handler " +
+        "V1-ONLY TARGET FALLBACK (clicking or typing only) — when a control you can SEE (in the " +
+        "V1 observation text or screenshot) has NO ref in el_table (a bare click-handler " +
         '<div> with no role/label, e.g. a SPA "Add To Cart"), pass target as a locator ' +
         'instead of a ref: `text="Add To Cart"` (a matching clickable or typeable ' +
         "element, case-insensitive, hidden descendants ignored, open shadow roots " +
@@ -965,8 +1042,9 @@ export const provisionActTool = {
         "exact text= or a css= selector). `click` is actionability-checked and throws " +
         "if an overlay intercepts; dismiss the overlay or deliberately use `js_click`, " +
         "the explicit direct DOM dispatch that fires through a transparent overlay. " +
-        "Prefer a real ref when one exists; reach for " +
-        "text=/css= only when none does. " +
+        "Prefer a real ref when one exists; reach for text=/css= only when none does. Compact V2 never " +
+        "accepts locator fallback: it requires an opaque handle from the current snapshot/page/generation-" +
+        "scoped action map, with membership as the sole action boundary. " +
         "Observed child-frame refs and locator matches retain their frame origin. " +
         "Same-registrable-domain frames are reachable; other frame actions must pass " +
         "the goto/allow_host domain scope, opaque frames are refused, and type_secret " +
@@ -997,14 +1075,20 @@ export const provisionActTool = {
         "already signed into). " +
         "cart_add (product_identity + options_hash + idempotency_key — reserve an " +
         "idempotent cart mutation, exact-line post-verify it, and return its postcondition), " +
+        "cart_clear (no arguments beyond session_id — empty the cart so a following cart_add " +
+        "reaches a KNOWN quantity; the browser profile persists across sessions, so a cart " +
+        "can carry quantity over from an earlier run. Call cart_clear before the first cart_add " +
+        "whenever the cart's starting quantity is not already known to be zero), " +
         "select_many (ordered selections map — select sequentially, re-observe after " +
-        "each success, and retain partial results), extract (into_slot/secret_label/store — " +
+        "each success, and retain partial results; Compact V2 keys are current safe_table @e: refs or @labels, " +
+        "while V1 keys may be observed labels or refs), extract (into_slot/secret_label/store — " +
         "reveal masked keys and extract credentials from the current page, sealed slot or vaulted), " +
         "solve_captcha (detect and drive the in-session captcha gate; settled=false carries a " +
         "needs_user{gate,message,remedy} — FAIL FAST and relay it to the user), " +
         "await_verification (sender/into_slot/grant_inbox_consent — read the user's OWN inbox " +
-        "through their signed-in browser session for an email verification code/link, sealed " +
-        "into a slot with into_slot). Sealed username/password login lifecycle, never exposing raw " +
+        "through their signed-in browser session for an email verification code/link; pass into_slot " +
+        "to seal the code into a slot and fill it with type_secret instead of handling it yourself). " +
+        "Sealed username/password login lifecycle, never exposing raw " +
         "values: login_prepare_signup (login_slot/password_slot/password_length — seal the user's " +
         "captured email and a generated strong password into session slots; fill the signup form " +
         "with type_secret using the returned slots), login_store_signup (service + login_hosts, " +
@@ -1018,12 +1102,15 @@ export const provisionActTool = {
         "Squire-known address, contact, product_query, or quantity input; type_secret and " +
         "operate_pay record credential and card provenance from their sealed sources. " +
         "When repairing a replay fallback field, pass its replay_step_index and replay_hole. " +
-        "Stable target refs remain reusable while their element exists. If an @e: ref is stale, " +
-        "the response is {status:target_stale, replacement_candidates, retry_policy:do_not_retry_old_ref}; " +
-        "call operate_observe and choose a new ref instead of retrying the old one. " +
+        "Under default compact-v2, target is either an @e: ref from the current action map or the @label alias " +
+        "of exactly one of its rows; a @label matching several rows returns ambiguous_target listing their refs, never " +
+        "a guess. Refs survive acts and benign re-renders on the same document; a real navigation retires them. On " +
+        "opaque `stale_ref`, call operate_observe and choose a new ref; do not retry the old one. " +
+        "In V1, stable target refs remain reusable while their element exists; a stale @e: " +
+        "ref returns {status:target_stale, replacement_candidates, retry_policy:do_not_retry_old_ref}. " +
         'detail (default "compact") controls the returned payload: "none" skips it ' +
         "entirely for chained fills (then operate_observe before the next ref action), " +
-        '"full" returns the legacy screen+accessibility payload. ' +
+        'in V1, "full" returns the legacy screen+accessibility payload. ' +
         "For legible product/variant hints on a cart-affecting action, pass product_identity and options_hash together; returned checkout_state is best-effort informational state and never a payment charge input. " +
         OBSERVE_DELTA_CONTRACT,
     inputSchema: actSchema,
@@ -1050,6 +1137,7 @@ export const provisionActTool = {
                     "scroll",
                     "upload",
                     "cart_add",
+                    "cart_clear",
                     "select_many",
                     "extract",
                     "solve_captcha",
@@ -1065,6 +1153,11 @@ export const provisionActTool = {
             path: { type: "string" },
             url: { type: "string" },
             key: { type: "string" },
+            provider: {
+                type: "string",
+                enum: ["google", "github"],
+                description: "OAuth provider for oauth_login/oauth_click. Declare it for JavaScript-driven controls whose label or destination does not identify the provider.",
+            },
             host: { type: "string" },
             slot: { type: "string" },
             product_identity: { type: "string", minLength: 1 },
@@ -1075,7 +1168,7 @@ export const provisionActTool = {
                 minProperties: 1,
                 maxProperties: 12,
                 additionalProperties: { type: "string" },
-                description: "Map each observed field label or @e: ref to its visible option text.",
+                description: "Map each current Compact V2 @e: ref or @label, or V1 observed label/ref, to its visible option text.",
             },
             into_slot: { type: "string" },
             secret_label: { type: "string" },
@@ -1111,52 +1204,57 @@ export const provisionActTool = {
     },
     schemaRepair: actionSchemaRepair,
     async handler(args, api) {
-        switch (args.kind) {
-            case "cart_add":
-                return await handleCartAdd(args);
-            case "select_many":
-                return await handleFormSelectMany(args);
-            case "extract":
-                return await handleExtract(args, api);
-            case "solve_captcha":
-                return await handleCaptcha(args);
-            case "await_verification":
-                return await handleAwaitVerification(args);
-            case "login_prepare_signup":
-                return await handlePrepareLogin(args);
-            case "login_store_signup":
-                return await handleStoreLogin(args, api);
-            case "login_load_saved":
-                return await handleSealVaultCredential({
-                    ...args,
-                    fields: args.fields ?? ["login", "password"],
-                    slot_prefix: args.slot_prefix ?? "vault",
-                }, api);
-        }
-        // Keep the defense-in-depth guard in act() for internal/replay callers,
-        // while this public tool surface makes the safe recovery explicit at the
-        // exact point a small model tried a forbidden manual PAN entry.
-        if (args.kind === "type") {
-            const reason = manualCardEntryBlockReason(args.text ?? "");
-            if (reason !== null) {
-                return {
-                    status: "manual_card_entry_refused",
-                    reason,
-                    safe_alternative: "operate_pay",
-                    missing_prerequisite: "verified_cart_total",
-                };
+        const result = await (async () => {
+            switch (args.kind) {
+                case "cart_add":
+                    return await handleCartAdd(args);
+                case "cart_clear":
+                    return await handleCartClear(args);
+                case "select_many":
+                    return await handleFormSelectMany(args);
+                case "extract":
+                    return await handleExtract(args, api);
+                case "solve_captcha":
+                    return await handleCaptcha(args);
+                case "await_verification":
+                    return await handleAwaitVerification(args);
+                case "login_prepare_signup":
+                    return await handlePrepareLogin(args);
+                case "login_store_signup":
+                    return await handleStoreLogin(args, api);
+                case "login_load_saved":
+                    return await handleSealVaultCredential({
+                        ...args,
+                        fields: args.fields ?? ["login", "password"],
+                        slot_prefix: args.slot_prefix ?? "vault",
+                    }, api);
             }
-        }
-        try {
-            return await act(args.session_id, buildAction(args), args.detail ?? "compact", args.product_identity !== undefined && args.options_hash !== undefined
-                ? { productIdentity: args.product_identity, optionsHash: args.options_hash }
-                : undefined);
-        }
-        catch (err) {
-            if (err instanceof TargetStaleError)
-                return err.result;
-            throw err;
-        }
+            // Keep the defense-in-depth guard in act() for internal/replay callers,
+            // while this public tool surface makes the safe recovery explicit at the
+            // exact point a small model tried a forbidden manual PAN entry.
+            if (args.kind === "type") {
+                const reason = manualCardEntryBlockReason(args.text ?? "");
+                if (reason !== null) {
+                    return {
+                        status: "manual_card_entry_refused",
+                        reason,
+                        safe_alternative: "operate_pay",
+                        missing_prerequisite: "verified_cart_total",
+                    };
+                }
+            }
+            try {
+                return await act(args.session_id, buildAction(args), args.detail ?? "compact", args.product_identity !== undefined && args.options_hash !== undefined
+                    ? { productIdentity: args.product_identity, optionsHash: args.options_hash }
+                    : undefined);
+            }
+            catch (err) {
+                if (err instanceof TargetStaleError)
+                    return err.result;
+                throw err;
+            }
+        })();
+        return result;
     },
 };
 // The former standalone tool objects in the following sections are NOT part of
@@ -1194,13 +1292,12 @@ export const operateCartAddTool = {
 };
 const formSelectManySchema = z.object({
     session_id: z.string().min(1),
-    // A label/ref → visible option map. Labels deliberately match the existing
-    // select targeting grammar, while refs remain useful when labels collide.
     selections: formSelectionsSchema,
 });
 export const operateFormSelectManyTool = {
     name: "operate_form_select_many",
-    description: "Select several related form options sequentially from a label/ref-to-option map. " +
+    description: "Select several related form options sequentially from a target-to-option map. " +
+        "Compact V2 requires current @e: handles; V1 accepts observed labels or refs. " +
         "Selections run in order; after every successful selection the browser is re-observed " +
         "before the next one resolves, so variant changes cannot poison later refs. Each field " +
         "reports selected or failed independently; successful selections are not rolled back when " +
@@ -1217,7 +1314,7 @@ export const operateFormSelectManyTool = {
                 minProperties: 1,
                 maxProperties: 12,
                 additionalProperties: { type: "string" },
-                description: "Map each observed field label or @e: ref to its visible option text.",
+                description: "Map each current Compact V2 @e: ref or @label, or V1 observed label/ref, to its visible option text.",
             },
         },
     },
@@ -1241,7 +1338,8 @@ export const provisionExtractTool = {
         "the page is a login wall / anti-bot interstitial with NO credential present " +
         "(do not treat the empty result as a real key) — drive an interactive login " +
         "or hand back to the user. Call when you have navigated to the keys page. " +
-        "With `into_slot`, a still-masked value is refused (reveal it first); pass " +
+        "With `into_slot`, a value that still looks masked is ranked behind a fully " +
+        "revealed sibling but never refused; pass " +
         '`secret_label` (e.g. "client secret") to pick the right one when the page ' +
         "shows several credentials.",
     inputSchema: extractSchema,
@@ -1311,8 +1409,9 @@ export const provisionAwaitVerificationTool = {
         "operate_act and continue. The session stays live; this is a resumable " +
         "hand-back, not a failure. Scoped search-and-extract — reads only the matching " +
         "recent mail, never the whole inbox. If a needs_user(verification_code) says " +
-        "inbox reading isn't consented, ask the user; on an explicit yes retry with " +
-        "grant_inbox_consent:true.",
+        "inbox reading is disabled, ask the user; on an explicit yes retry with " +
+        "grant_inbox_consent:true. Pass grant_inbox_consent:false to disable inbox reading " +
+        "for the current session.",
     inputSchema: verifySchema,
     jsonInputSchema: {
         type: "object",
@@ -1394,6 +1493,7 @@ const finishOutcomeSchema = z.union([
     }),
 ]);
 async function handleFinishOutcome(sessionId, outcome, api) {
+    let successfulOutcome = false;
     const { finish, prepared } = await finishProvisionSessionWithPreparation(sessionId, async () => {
         if (outcome.kind === "credentials") {
             const extracted = await extractCredentials(sessionId);
@@ -1404,7 +1504,8 @@ async function handleFinishOutcome(sessionId, outcome, api) {
             const autoPromote = stored !== null && blocked === undefined
                 ? await autoPromoteProvision(sessionId)
                 : undefined;
-            emitProvisionMeasurement(sessionId, stored !== null && blocked === undefined ? "success" : "fail");
+            successfulOutcome = stored !== null && blocked === undefined;
+            emitProvisionMeasurement(sessionId, successfulOutcome ? "success" : "fail");
             return {
                 kind: "credentials",
                 candidate_count: extracted.candidate_count,
@@ -1417,14 +1518,18 @@ async function handleFinishOutcome(sessionId, outcome, api) {
             ? undefined
             : ((await verifyActiveRecipePostcondition(sessionId, outcome.verify_recipe)) ??
                 (await verifySavedRecipePostcondition(sessionId, await readRecipe(outcome.verify_recipe))));
-        emitProvisionMeasurement(sessionId, verified === undefined || verified.confirmed ? "success" : "fail");
+        successfulOutcome =
+            outcome.verify_recipe === undefined
+                ? outcome.data?.confirmed === "true"
+                : verified?.confirmed === true;
+        emitProvisionMeasurement(sessionId, successfulOutcome ? "success" : "fail");
         return {
             kind: "result",
             summary: (outcome.summary ?? "").slice(0, 4000),
             ...(verified !== undefined ? { verified } : {}),
             ...(outcome.data !== undefined ? { data: outcome.data } : {}),
         };
-    });
+    }, () => successfulOutcome);
     return { ...prepared, url: finish.url };
 }
 // Not part of the default MCP tool surface (dropped from OPERATE_TOOLS). Kept
@@ -1445,7 +1550,8 @@ export const provisionFinishTaskTool = {
         "operate_extract's store), for signups/key-provisioning. kind='result' " +
         "reports a `summary` (+ optional `data` map) for any other task — a design " +
         "review's findings, extracted data, or 'task done' (put confirmed:true in " +
-        "data). Use operate_finish instead to abort without an outcome. For a soft " +
+        "data only after a clean success; false or omitted preserves prior login state). " +
+        "Use operate_finish instead to abort without an outcome. For a soft " +
         "no-match with kind='result' (for example, no exact or authentic item in " +
         "stock), first relay the closest candidates and why they were rejected, then " +
         "let the user choose a substitute, broader search, or another site before " +
@@ -1491,9 +1597,11 @@ export const provisionFinishTool = {
     description: "Finish an operate task and close its session. outcome.kind='none' closes " +
         "without a reported outcome (and remains the default for compatibility); " +
         "'credentials' extracts and vault-stores a credential using required `store`; " +
-        "'result' reports required `summary` or `data` and can verify_recipe before closing. " +
-        "All credential values remain server-side; after Chrome closes, an eligible clean profile " +
-        "may return to the closed warm slot for the next task.",
+        "'result' reports required `summary` or `data`; it succeeds only when verify_recipe " +
+        "confirms or data.confirmed is true. " +
+        "All credential values remain server-side; after Chrome closes, its private per-session " +
+        "profile is destroyed. An explicit successful outcome atomically saves portable login state " +
+        "for a later task; no-outcome and failed closes preserve the prior snapshot.",
     inputSchema: finishSchema,
     jsonInputSchema: {
         type: "object",
@@ -1661,7 +1769,6 @@ const useSchema = z
     verb: OperatorVerbSchema.optional(),
     service_url: z.string().url().optional(),
     params: z.record(z.string().max(2000)).optional(),
-    require_live_identity: z.boolean().optional(),
     // After the host repairs one missed step, resume the same live session at
     // replay.next_index instead of starting over.
     session_id: z.string().min(1).optional(),
@@ -1721,7 +1828,6 @@ export const provisionUseTool = {
             verb: { type: "string", enum: OperatorVerbSchema.options },
             service_url: { type: "string" },
             params: { type: "object" },
-            require_live_identity: { type: "boolean" },
             session_id: { type: "string" },
             resume_from: { type: "integer" },
             leg: { type: "string", enum: ["checkout"] },
@@ -1748,7 +1854,6 @@ export const provisionUseTool = {
             const cold = await startProvisionSession({
                 serviceUrl: args.service_url,
                 consentInboxRead: await readInboxConsent(),
-                ...(args.require_live_identity === true ? { requireLiveIdentity: true } : {}),
                 ...(api !== null ? { api } : {}),
             });
             if (cold.needs_user !== undefined)
@@ -1789,7 +1894,6 @@ export const provisionUseTool = {
             const cold = await startProvisionSession({
                 serviceUrl: args.service_url,
                 consentInboxRead: await readInboxConsent(),
-                ...(args.require_live_identity === true ? { requireLiveIdentity: true } : {}),
                 ...(api !== null ? { api } : {}),
             });
             if (cold.needs_user !== undefined)
@@ -1814,7 +1918,6 @@ export const provisionUseTool = {
                 consentInboxRead,
                 ...(recipe.allowed_hosts.length > 0 ? { extraAllowedHosts: recipe.allowed_hosts } : {}),
                 hint: renderOperatorRecipeHint(recipe),
-                ...(args.require_live_identity === true ? { requireLiveIdentity: true } : {}),
                 ...(api !== null ? { api } : {}),
             });
             if (started.needs_user !== undefined)
@@ -2128,13 +2231,14 @@ export const operateLoginTool = {
 // operate_act's kinds and operate_recipe_save/run delegate to, and as direct handles
 // for tests that pin down that folded behavior.
 // operate_screenshot (2026-08-23) is a deliberate, narrow addition to this cut: a
-// read-only debugging instrument (page/frame pixels, money-fence redacted) with no
+// read-only debugging instrument (the page's or one frame's real pixels) with no
 // alias/kind it could fold into — operate_act's kinds all DO something; this only
 // looks.
 export const OPERATE_TOOLS = [
     provisionStartTool,
     provisionObserveTool,
     provisionScreenshotTool,
+    provisionObserveQueryTool,
     provisionActTool,
     operateRecipeSaveTool,
     operateRecipeRunTool,