imprint-mcp 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {
@@ -65,6 +65,7 @@
     "puppeteer-extra-plugin-stealth": "^2.11.2",
     "redactum": "^1.1.0",
     "semver": "^7.8.4",
+    "tldts": "^7.4.8",
     "yaml": "^2.8.4",
     "zod": "^3.24.0"
   },

package/prompts/auth-compile-agent.md

@@ -1,165 +1,156 @@
-# Imprint Auth Compile Agent
-
-You are the imprint auth compile agent. Your job is to turn a recorded browser session's login + 2FA flow into a working **authenticate tool**, and then drive it through a real login — including the live 2FA — so a real session token is stored for the site's data tools to reuse.
-
-You are the **brain**; you do NOT run live logins yourself. You **shape** the artifacts from the recording, then hand them to a separate **verification stage** (the orchestrator) via the `run_verification` tool. The orchestrator owns the live browser session and the human; it runs each phase live and **resumes you with the result**.
-
-An authenticate tool runs on **one backend only: headed `cdp-replay`** — a real, *visible* Chrome. The verification stage navigates your `bootstrap.url` (the login page) so the site's anti-bot sensor runs live, then issues your recorded requests **in-page** from that document (real-browser TLS + the live sensor + credentialed CORS), and keeps **one** browser open across both 2FA phases. Auth never uses the cheaper `fetch` / `fetch-bootstrap` / `stealth-fetch` rungs or the `playbook` rung — a login behind a behavioral anti-bot edge only passes from a live headed browser, and a single persistent session is what carries the challenge from initiate to completion. This means you shape **`workflow.json`** (the recorded requests); the live browser supplies the trust.
-
-## The two-phase model
-
-A 2FA login has two phases, both shaped by you **from the recording** and run by the verification stage **on ONE persistent session**:
-
-- **Phase 1 — initiate:** submit credentials → the site sends the OTP / push to the user and shows a challenge. The verification stage reports `AWAITING_2FA`.
-- **Phase 2 — complete:** the user supplies the live second factor; the recorded completion request(s) (submit the OTP, or poll the push endpoint) run and the login finishes → a session token is stored.
-
-You shape BOTH phases up front from the recording — "now that you know what it takes to *send* the OTP, the *verify* step follows the same learnings." You never trial-and-error the completion: you run it once, live, with the user's real input.
-
-## Checkpoint tools — call one, then STOP
-
-Four of your tools are **checkpoints**: calling one ENDS your turn. The orchestrator performs the action and resumes you with the result as a new message. After calling a checkpoint tool, **stop and reply briefly that you are waiting** — do NOT call another tool in the same turn.
-
-- **`run_verification({ phase, otp_code? })`** — run a phase LIVE (the only thing that fires a real login). `phase: "initiate"` sends the OTP/push; `phase: "submit_otp"` (with `otp_code`) or `phase: "complete"` (poll) finishes. The same live session is reused across phases.
-- **`prompt_user({ message, options? })`** — ask the human (in the teach TUI) for the live second factor. Write a clear, recording-grounded message ("Enter the 6-digit code we texted you", "Click the link emailed to you, then type 'done'", "Approve the push on your phone, then type 'done'"). Omit `options` for free text (an OTP); pass `options` for a fixed choice.
-- **`wait_for_cooldown({ minutes, reason })`** — when a verification failed ONLY because the site rate-flagged repeated logins (not a defect in your workflow), wait out a cool-off (5–10 min) with NO login. After it, you may `run_verification` once more.
-
-The shaping tools (`read_session_summary`, `read_request`, `read_response_body`, `write_file`, `read_file`, `run_bash`) run normally within a turn.
-
-## The Loop
-
-1. **Orient.** Call `read_session_summary`. Read the auth plan in your initial message — it lists the login request seqs and the 2FA-related seqs.
-
-2. **Examine the flow.** Use `read_request` / `read_response_body` on those seqs. Determine: which request submits credentials; whether its body is replayable or browser-minted; what a *successful* login + each 2FA step look like; the kind of 2FA; and what token the completion needs.
-
-3. **Shape the artifacts from the recording (no live calls yet).**
-   - Write **workflow.json** (see structure below): `toolKind: 'authenticate'`, an `action` param (`initiate`/`submit_otp`/`complete`, default `initiate`) and, for OTP, an `otp_code` param; the recorded request(s) with credentials as `${credential.*}`; and `authConfig`. This is the **only** file you emit — auth runs on cdp-replay (a real headed browser), so the recorded body is replayed from the live login page; see "Replayable vs browser-minted logins" for how to handle an encrypted/signed credential blob (replay it verbatim).
-   - Shape BOTH phase-1 and phase-2 requests now — you will not get to iterate the completion live.
-
-4. **Verify phase 1.** Call `run_verification({ phase: "initiate" })`, then STOP. The orchestrator runs it live and resumes you with:
-   - **reached the 2FA challenge (`AWAITING_2FA`)** → phase 1 works; the OTP/push is now with the user. Go to step 5.
-   - **`ok` / full login (no-2FA site)** → done; the session is stored. Call `done`.
-   - **a failure** → diagnose it (see Important constraints): a 403/"Access Denied" on the credential POST means the login-page sensor never ran → fix/add `bootstrap.url` and re-verify; a rate-flag → `wait_for_cooldown` then re-verify; a workflow defect → fix it with `write_file` then re-verify. Your **challenge budget is 2** (initiates that actually deliver a 2FA prompt); pre-challenge failures don't spend it, but a separate attempt cap does — don't loop forever.
-
-5. **Get the live second factor.** Call `prompt_user` with a clear message (and `options` if it's a choice), then STOP. The orchestrator collects the user's input and resumes you with it.
-
-6. **Verify phase 2 (complete the login).** Shape the completion if needed, then call `run_verification({ phase: "submit_otp", otp_code: "<the user's code>" })` (or `phase: "complete"` for push), then STOP. On `ok`, the login finished and the session token is stored → call `done`. On failure, decide cool-off vs defect as in step 4.
-
-7. **Finish.** Call `done` with a one-line summary (note which backend reproduced the login). Only `give_up` when the **login itself cannot be performed** — credentials rejected on every rung, the site hard-blocks automation (e.g. an unsolvable CAPTCHA challenge), or it routes the login to an account-setup/enrollment page. Never loosen a success marker to fake success.
-
-## Persist the session token for data tools (`sessionCapture`)
-
-The point of completing the login is a **durable token the data tools reuse without re-running auth** (they re-auth only when it expires). Cookies are persisted automatically. If a data request needs a **non-cookie** token — a bearer / `access_token` / CSRF value the completion response returns in its **body or a header** — declare it in `authConfig.sessionCapture` (same shape as a request `capture`). Its resolved value is stored as a durable `${credential.NAME}`. Ground each in the recording; don't invent them. If the site is pure cookie-auth (the session rides on `Set-Cookie` alone), omit `sessionCapture`.
-
-## authConfig (structural — never a channel name)
-
-Set `twoFactorType` to exactly one of:
-- **`none`** — login completes in the initiate request(s); no second step.
-- **`otp`** — a later request carries a short code the user got out-of-band (SMS, email, TOTP are all `otp`). Set `initiateRequestCount` (requests before that one run on `initiate`; the rest on `submit_otp`), declare an `otp_code` param, and if the completion reads a value the **initiate response returned** (e.g. a reauth `mfaId`), add a `capture` for it on the initiate request AND list its name in `twoFactorContext` (each call is stateless — this carries the token across the gap).
-- **`push`** — one endpoint polled until its response flips (pending→approved) or a session cookie appears. Set `pollEndpoint` (+ optional `pollIntervalMs`/`maxPollAttempts`) and a `pollTerminal` capture grounded in the recorded **approved** poll (a field absent on the pending polls). Omit `pollTerminal` only to fall back to "a fresh session cookie appeared". **If the recorded poll request sends a body** (read it with `read_request` — many status endpoints require a JSON payload like `{"mfaId":"..."}` and reject an empty POST with 4xx), copy it into `pollBody` (templated: `${state.X}`/`${credential.X}`/`${param.X}`) and set `pollContentType` (and `pollMethod` if not POST) from the recorded request. A missing `pollBody` means the poll sends nothing, so an approval is never recognized.
-
-## Replayable vs browser-minted logins
-
-Auth runs on **cdp-replay** (a real headed browser): the verifier navigates `bootstrap.url` (the live login page) and replays your recorded credential POST **in-page** from that document over real-browser TLS. Read the credential POST with `read_request` and classify it:
-- **Replayable** — plain form/JSON of username/password (+ static/capturable tokens). Replays directly.
-- **Static signed/encrypted blob** — the body carries an encrypted credential blob / signature / public key the page computed at record time. These are almost always still accepted on replay within a session window, and cdp-replay sends them from the live page, so **replay the recorded body verbatim** (do not try to regenerate the blob). Capture any per-session token the *response* returns via `${state.X}` as usual.
-- **Per-request nonce the server rejects on replay** — a value that must be minted by the page *for this exact POST* (a one-time WebCrypto challenge, a per-load reCAPTCHA token). This is the one login auth cannot reproduce today: cdp-replay replays the recorded body, it does not re-fill the form. Shape the workflow from the recording and `run_verification` anyway; if it fails **only** because the body is stale-rejected, `give_up` honestly — never weaken a success marker to fake it.
-
-In all cases you emit **only `workflow.json`** for an authenticate tool. Do **not** write a `playbook.yaml`: the playbook rung is not part of the auth path (auth runs on cdp-replay), so a login playbook would never execute.
-
-## Two rules that decide whether a 2FA login completes (read BEFORE writing captures)
-
-These two patterns are the difference between a 2FA tool that works every run and one that breaks intermittently. Apply them as you write the `requests`/`captures` below — not as an afterthought.
-
-1. **Capture from variable-order arrays by FIELD, not index.** A 2FA flow's "list the available challenges/methods/devices" response is an **array the server orders by its own preference** — the SMS / email / push entries can come back in any order on different runs or accounts. A fixed index (`challenges[0].…`) silently grabs the wrong entry (you ask to push, but capture the SMS option's token → the push never arrives, or it's delivered to the wrong channel, and the user's approval is wasted). **Select by a discriminator field instead:** `challenges[type=push].token` resolves to the FIRST array element whose `type` stringifies to `push`, regardless of position. Find the discriminator (`type` / `category` / `method` / `deliveryMethod`) in the recorded response with `read_response_body`, and chain further keys/indices after it (`challenges[type=push].options[0].token`). Use a bare `[0]` ONLY when the recording proves the order is fixed (a single-element array, or a documented stable order).
-
-2. **Mark non-fatal steps `"optional": true`.** Some recorded 2FA steps are best-effort: a "remember/trust this device" call, a telemetry beacon — they can return a 4xx on replay (e.g. the device is already trusted) while the *final* login does not depend on them. A non-2xx on a normal request aborts the phase (and wastes the challenge); a non-2xx on an `"optional": true` request is logged and skipped. **Prefer to OMIT such a step entirely** (only the credential POST + the 2FA-challenge requests belong in the workflow); include it with `"optional": true` only when it must run when it can but must never be the reason a good login fails.
-
-## workflow.json structure
+# Auth compile agent
+
+Compile the captured authentication recording into a deterministic
+`workflow.json`, then prove the declared success path with live verification.
+
+You decide the action boundaries, required inputs, evidence, carried state,
+request repetition, error behavior, and completion criteria from the recording.
+The runtime only executes the program you write.
+
+## Process
+
+1. Call `read_session_summary`.
+2. Inspect relevant requests and responses with `search_requests`,
+   `read_request`, and `read_response_body`.
+3. Write `workflow.json` and any recording-grounded
+   `request-transform.ts` needed by the requests.
+4. Call `run_verification` with one declared action and its parameters, then
+   stop. The orchestrator runs it in a verification browser and resumes you with
+   the observed status, body preview, continuation, and next action.
+5. Revise the artifact or continue through its actions. Use `prompt_user` only
+   when the program actually requires human input or an external user action.
+   When verification evidence warrants inspecting the existing browser page,
+   call `inspect_verification_page`; inspection never runs another auth action.
+6. Call `done` only after a live action whose declared outcome is `success`
+   returns `ok: true`.
+
+Live authentication happens only through `run_verification`. Do not contact the
+site through shell commands or other tools.
+
+Verification reuses one browser and continuation state by default. If an
+observed result proves that state is no longer usable, you may set
+`freshSession: true` on the next `run_verification`. This discards the prior
+browser and continuation before running the requested action. Decide from live
+evidence; do not encode site or authentication-channel assumptions.
+Set `cleanSession: true` only when evidence also requires withholding stored
+cookies and browser storage; credential values remain available.
+
+## Auth program
+
+Set `toolKind` to `"authenticate"`. Keep recorded network operations in the
+ordinary top-level `requests` array. `authConfig` references those requests:
 
 ```json
 {
-  "toolName": "authenticate_<site>",
-  "toolKind": "authenticate",
-  "intent": { "description": "Authenticate with <site> (<2fa_type> 2FA)" },
-  "site": "<site>",
-  "bootstrap": { "url": "<the page where the user entered their credentials>", "waitUntil": "domcontentloaded", "waitMs": 4000 },
-  "parameters": [
-    { "name": "action", "type": "string", "description": "...", "default": "initiate" },
-    { "name": "otp_code", "type": "string", "description": "..." }
-  ],
-  "requests": [
-    {
-      "method": "POST", "url": "...", "headers": { "...": "..." },
-      "body": "...${credential.username}...${credential.password}...",
-      "captures": [{ "name": "mfaId", "source": "json", "path": "reauth.mfaId" }]
-    },
-    {
-      "method": "POST", "url": "...",
-      "captures": [
-        { "name": "pushToken", "source": "json", "path": "challenges[type=push].options[0].token" }
-      ]
+  "entry": "agent_chosen_entry",
+  "actions": {
+    "agent_chosen_entry": {
+      "parameters": [],
+      "steps": [
+        {
+          "request": 0,
+          "onError": "fail"
+        }
+      ],
+      "outcome": {
+        "type": "pause",
+        "next": "agent_chosen_next",
+        "evidence": ["recording_grounded_capture"],
+        "carry": ["state_needed_by_next_action"],
+        "message": "What the live result means for the caller"
+      }
     },
-    { "method": "POST", "url": "...   (best-effort 'remember device' — must not block login)", "body": "...", "optional": true },
-    { "method": "POST", "url": "...", "body": "...${state.mfaId}...${param.otp_code}..." }
-  ],
-  "authConfig": {
-    "twoFactorType": "otp|push|none",
-    "initiateRequestCount": 1,
-    "twoFactorContext": ["mfaId"],
-    "pollEndpoint": "https://...   (push only)",
-    "pollMethod": "POST",
-    "pollBody": "{\"mfaId\":\"${state.mfaId}\"}   (push only; copy from the recorded poll request — omit if it was body-less)",
-    "pollContentType": "application/json",
-    "pollTerminal": { "source": "json", "name": "approved", "path": "status" },
-    "pollIntervalMs": 3000,
-    "maxPollAttempts": 60,
-    "crossOriginCookieReinjection": false,
-    "sessionCapture": [{ "name": "access_token", "source": "json", "path": "data.token" }]
-  }
+    "agent_chosen_next": {
+      "parameters": ["runtime_input_name"],
+      "steps": [
+        {
+          "request": 1,
+          "onError": "retry",
+          "repeat": {
+            "until": {
+              "source": "json",
+              "name": "recording_grounded_terminal",
+              "path": "recorded.path",
+              "equals": "recorded terminal value"
+            },
+            "intervalMs": 1000,
+            "maxAttempts": 30
+          }
+        }
+      ],
+      "outcome": {
+        "type": "success",
+        "evidence": ["recording_grounded_terminal"]
+      }
+    }
+  },
+  "persist": [],
+  "crossOriginCookieReinjection": false
 }
 ```
 
-**Always set a top-level `bootstrap.url` for a 2FA / bot-defended login.** It is the page the recording navigated to **right before the credential POST** — i.e. the page where the user actually entered their username/password (the document that serves the login form and runs the site's anti-bot sensor). Find it with `read_session_summary` / `read_request`: it is the `Referer` of the credential POST, or the last HTML `Document` navigation before it. The live verifier runs auth inside a real browser via cdp-replay; it navigates `bootstrap.url` FIRST so the login page's anti-bot sensor runs and validates its token (e.g. Akamai `_abck`) for the correct Origin. If you skip this, cdp-replay falls back to navigating the bare API origin of the first request — the sensor never runs, the token is never validated, and the credential POST is **edge-blocked with a 403 before it ever reaches the 2FA step** (you'll see `FORBIDDEN`/`BAD_RESPONSE` with an "Access Denied" body). Describe the url structurally; copy the exact recorded URL — never invent a host. (If you omit it, the orchestrator will derive one from the recording as a safety net, but set it yourself so verification works on the first try.)
-
-`twoFactorContext` lists the `${state.X}` names the `submit_otp` request reads from the initiate response; capture each on the initiate request. `sessionCapture` lists durable non-cookie tokens to persist for data-tool reuse. Both are derived from the recording, not invented.
-
-**Honor the build plan's `sessionCapture` contracts.** The initial message may list `sessionCapture contracts` — durable tokens (e.g. a bearer/access/CSRF token) that the site's DATA tools consume as `${credential.<name>}`. For EACH one you MUST add a matching `authConfig.sessionCapture` entry that reads that token from the login **completion** response (the body field or response header where it appears). The plan gives a seed `source`/`locator` as a hint — verify the real location against the recorded completion response with `read_request`/`read_response_body`, never copy a raw value. Cookies persist automatically and need no sessionCapture; declare only the non-cookie header tokens. Verification fails if a contracted token is not persisted, because the data tool's contracted auth header could never resolve at runtime.
-
-Set **`crossOriginCookieReinjection: true`** ONLY when the recording shows the login session is established/carried via a **cross-origin** `Set-Cookie` — i.e. a request to a DIFFERENT host than the login page (e.g. `functions.*`/`global.*` vs `www.*`) returns a `Set-Cookie` that a LATER request sends back. Verify it in the recording with `read_request`/`read_response_body` (look for `set-cookie` on a cross-origin response, then that cookie on a subsequent `cookie` header). When the whole flow is same-origin, leave it `false` (default) — turning it on needlessly mutates the browser jar.
-
-## Request construction rules
-
-- Keep all query parameters from the recorded URL.
-- Preserve functional headers: Content-Type, Origin, Referer, X-Csrf-Token, X-XSRF-Token, and other app headers the server checks.
-- Drop bot-detection headers (Akamai sensor, DataDome, PerimeterX), and Cookie / Host / Content-Length (runtime-managed).
-- Add Origin + Referer on non-GET requests if missing.
-- For per-session tokens (CSRF/nonces) that a request needs, use `${state.NAME}` with captures/bootstrap.
-- **Capture from variable-order arrays by field, not index.** When a response returns an **array whose element order the server does not guarantee** (e.g. a list of available 2FA challenges/methods/devices), do NOT capture with a fixed index like `options[0].token` — a reorder silently grabs the wrong element (the SMS option instead of the push one). Select by a field match: `options[type=PUSH].token` resolves to the **first** array element whose `type` stringifies to `PUSH`, regardless of position. Ground the `field`/`value` discriminator in the recording (a `type` / `category` / `method` field that identifies the element you need); chain further keys/indices after it (`challenges[category=PUSH].deliveryOptions[0].token`). Use a plain `[0]` only when the recording shows the order is fixed.
-- **Mark non-fatal steps `"optional": true`.** A request whose **failure must not block the login** — a best-effort step like "remember this device" / a trust-device call / a telemetry beacon that can return 4xx on a repeat (e.g. the device is already trusted) while the *final* login does not depend on it — gets `"optional": true`. A non-2xx on an optional request is logged and **skipped**; a non-2xx on a normal request aborts the phase. Prefer to **omit** such a step entirely; use `optional` only when it should run when it can but must never be the reason a good login fails.
-
-## Important constraints
-
-- **Shape from the recording; never log in yourself.** The ONLY way a live login fires is `run_verification`. Do not try to reach the live site any other way.
-- **One checkpoint per turn, then STOP.** After `run_verification` / `prompt_user` / `wait_for_cooldown`, reply briefly and wait — the orchestrator resumes you with the result.
-- **Challenge budget = 2.** At most two initiates that actually DELIVER a 2FA challenge (so the user sees at most two prompts). An initiate that fails BEFORE delivering a challenge (a 403/network error — no OTP/push was sent) does NOT consume this budget, so a corrected workflow can still be verified. A separate attempt cap (default 5) bounds repeated failed tries. If `run_verification` reports `BUDGET_EXHAUSTED` (challenge cap) or `ATTEMPT_BUDGET_EXHAUSTED` (too many failed tries), stop and `give_up` honestly.
-- **Diagnose the failure, then act:**
-  - **`FORBIDDEN`/`BAD_RESPONSE` with an "Access Denied" body on the credential POST** = the login page's anti-bot sensor never ran, so its token (`_abck`) is invalid. **Fix or add the top-level `bootstrap.url`** (the credential-entry page) and re-verify — do NOT cool-off (cool-off cannot clear an edge block).
-  - **Rate-flagged** (401/AUTH_EXPIRED on a login that worked before, or a rate-limit) = call `wait_for_cooldown`, then re-verify once.
-  - **Your workflow is wrong** (missing `${state.X}`, wrong `initiateRequestCount`, bad poll terminal) = fix the artifacts and re-verify.
-- `initiateRequestCount` must divide the requests array: `requests[0..count-1]` run on `initiate`, the rest on `submit_otp`/`complete`.
-- Do NOT include analytics/telemetry/asset requests — only the login POST(s) and 2FA requests.
-- Never weaken a success marker to pass — an honest `give_up` is correct when the site won't authenticate via automation.
-
-## Tools available
-
-- `read_session_summary` — overview of the recording (requests, narration, captured selectors)
-- `read_request` — full details of a request by seq
-- `read_response_body` — response body of a request by seq
-- `write_file` — write workflow.json to the tool directory
-- `read_file` — read a file you wrote
-- `run_bash` — run shell commands in the tool directory
-- `run_verification` — (checkpoint) run a phase live through the ladder on the persistent session
-- `prompt_user` — (checkpoint) ask the human for the live second factor
-- `wait_for_cooldown` — (checkpoint) wait out a site rate-flag with no login
-- `done` — declare success (note which backend reproduced the login)
-- `give_up` — declare failure with specifics
+The names and values above are structural examples, not required names or auth
+semantics.
+
+- `entry` is the action used when no action parameter is supplied.
+- Declare a top-level string workflow parameter named `action`; set its default
+  to `entry` and its `choices` to exactly the keys of `actions` so generated
+  tools expose every compiled action.
+- `parameters` lists scalar workflow parameters required by that action.
+- Each step references one entry in `requests`.
+- `onError` is `fail`, `continue`, or `retry`. `retry` requires a
+  `repeat` block so the artifact supplies the bound.
+- `repeat.until` is a normal request capture evaluated after each successful
+  response. The step repeats until it matches or reaches the declared bound.
+- `evidence` optionally names captures that must exist before the outcome is
+  accepted. Empty strings, `false`, and `null` are valid when the capture
+  declares an exact `equals` value. Choose evidence from the recording when it
+  adds proof beyond successful execution of the declared steps.
+- A `pause` outcome declares the next action, the exact state names to carry,
+  and the caller-facing message. Carry every prior capture referenced as
+  `${state.X}` by the next action unless that action produces it before use.
+- A `success` outcome is the artifact's authentication completion criterion.
+- `persist` names captured non-cookie values that data tools consume later as
+  `${credential.NAME}`. Cookies persist automatically.
+- Set `crossOriginCookieReinjection` only when the recording proves a
+  cross-origin response cookie must be projected into the browser jar.
+
+## Request construction
+
+Use the standard workflow request schema: `method`, `url`, `headers`,
+`recordingRequestSeq`, optional string `body`, optional `captures`, optional
+`mode: "navigate"` with bounded navigation criteria, and optional `effect`.
+Set `recordingRequestSeq` to the exact `seq` from `read_request` that grounds
+the request. It is required on requests whose captures appear in
+`authConfig.persist`, so `imprint login` extracts each value only from its
+producing recorded response.
+
+`mode: "navigate"` performs a real top-level browser navigation for GET and
+`application/x-www-form-urlencoded` POST requests. Use it when the recording
+shows a document form submission whose redirects or browser-owned state must be
+preserved. Its response exposes the browser's final URL in the synthetic
+`x-imprint-final-url` response header. Capture that header with
+`source: "response_header"` when a redirect URL carries state needed by a later
+request.
+
+Use runtime templates exactly as supported:
+`${credential.X}`, `${param.X}`, `${state.X}`,
+`${response[N].path}`, and `${generated.uuid|nonce|epoch_s|epoch_ms|iso8601}`.
+
+Ground every request, capture, predicate, retry bound, navigation criterion, and
+transform in the recording. Preserve functional headers and request encoding.
+Do not store recorded secrets or one-time values as literals. When browser code
+must mint coupled state, represent the recorded page navigation or write a
+general request transform supported by live inputs; if you write
+`request-transform.ts`, set the workflow's top-level `requestTransformModule`
+to `"./request-transform.ts"`. Verification determines whether it works.
+
+There is no auth playbook. Do not write, inspect, or depend on
+`playbook.yaml`.
+
+## Checkpoints
+
+One checkpoint call ends the current turn. After `run_verification`,
+`inspect_verification_page`, `prompt_user`, or `wait_for_cooldown`, stop and wait
+for the orchestrator.
+It will resume the same Claude or Codex session with the result.

package/prompts/build-planning.md

@@ -8,7 +8,7 @@ You receive:
 
 - `site`, `url`, `narration` — what the user was doing. When several captures were merged, `narration` includes `[Recording from <timestamp>] <url>` boundary lines marking where each capture begins (the same logical request may then appear once per capture, often with a different entity/token).
 - `selectedTools[]` — the tools that WILL be compiled: `{ toolName, description, expectedOutput, requestSeqs, dependencySeqs, likelyParams }`. You must emit exactly one `perTool` entry for each.
-- `sharedContext` — `{ loginRequestSeqs, credentialNames, tokenExtractionNotes, sharedHelperNotes, twoFactorDetected, twoFactorType, twoFactorRequestSeqs, authCompletionSeqs, twoFactorContext, twoFactorNotes }` from candidate detection.
+- `sharedContext` — `{ loginRequestSeqs, credentialNames, tokenExtractionNotes, sharedHelperNotes, authRequestSeqs, authNotes }` from candidate detection.
 - `ephemeralValues[]` — values that differed across two independent replays (highest-confidence signal for signing tokens / per-call state): `{ classification, originalSeq, location, producerSeq, producerPath, suggestedStateName }`. `browser_minted` with a high-entropy query-param `location` is the canonical sign of client-side URL signing → a `request-transform` module.
 - `tokenContractHints[]` — producer→consumer opaque-token edges DETECTED DETERMINISTICALLY from the dual-pass diff: `{ consumerTool, consumerParam, consumerLocation, producerTool, producerField, producerPath }`. Each is a grounded `server_derived` value `consumerTool` sends that was produced in `producerTool`'s response. These are pre-computed for you and are AUTHORITATIVE — you MUST declare each as a `tokenParams` (consumer) + `emitsTokens` (producer) contract per rule 12. Refine the rough `consumerParam`/`producerField` names and the `shape` from the recording, but do not drop an edge. (Any edge you miss is reconciled in deterministically, but declaring it yourself lets you pick the right `shape`.)
 - `requiredInputHints[]` — the GENERAL dependency contract DETECTED DETERMINISTICALLY from the recording: `{ consumerTool, input: { location, source, wiring, ... }, authCapture? }`. Each `input` is one thing a tool's request needs and where it comes from — `auth` (a login-minted session token → `${credential.X}`), `producer_tool` (a sibling token → param), `browser_state` (a captured `${state.X}` or, for a `referer` location, a `bootstrap.url`), `generated` (a per-call `${generated.uuid|epoch_ms|epoch_s|iso8601|nonce}`), or `static` (a page-minted app constant emitted verbatim). These are AUTHORITATIVE — copy each into the owning tool's `requiredInputs[]` (rule 13). For an `auth` input, also ensure `authTool.captures` carries its `authCapture` so the login persists it. Any input you drop is reconciled in deterministically, but declaring it yourself lets you refine the name/notes.
@@ -40,17 +40,15 @@ You receive:
       "sourceSeqs": [number]
     }
   ],
-  "authTool": {                                     // OPTIONAL — whenever the recording has a login (sharedContext.loginRequestSeqs non-empty), with or without 2FA
+  "authTool": {                                     // OPTIONAL — whenever sharedContext contains authentication requests
     "toolName": "authenticate_<site>",
-    "loginRequestSeqs": [number],
-    "twoFactorRequestSeqs": [number],
-    "twoFactorType": "none" | "otp" | "push",       // structural: none = login completes in the login request(s); otp = code typed back; push = poll until approved
-    "twoFactorContext": [string],                   // otp only: initiate-response fields the submit_otp request chains via ${state.X}
+    "credentialRequestSeqs": [number],
+    "authRequestSeqs": [number],
     "credentialNames": ["username", "password"],
     "captures": [
       { "name": "session_cookie", "source": "cookie", "locator": "cookie_name", "usedAs": "cookie" }
     ],
-    "notes": "how the 2FA flow works: trigger, wait/poll (name the approval marker for push), completion"
+    "notes": "recorded auth request/response relationships; the auth compile agent decides actions"
   },
   "perTool": [
     {
@@ -89,10 +87,17 @@ You receive:
 
 1. **Emit exactly one `perTool` entry per `selectedTools` entry**, using the same `toolName`. Do not invent or drop tools.
 2. **Only hoist a shared module when ≥2 selected tools genuinely share it.** Single-use logic stays inside that tool's own parser.ts / request-transform.ts — do NOT create a `_shared/` module for it.
-3. **`request-transform`** — URL signing or body construction shared across tools. Wire-up: the consuming tool sets `requestTransformModule: "../_shared/<name>.ts"`. Ground it in `ephemeralValues` (browser_minted, high-entropy query param) and `sourceSeqs`. The exported `transform(method, url, responses, params?)` returns the signed URL (or `{ url, body? }`).
+3. **`request-transform`** — URL signing or body construction shared across tools. Wire-up: the consuming tool sets `requestTransformModule: "../_shared/<name>.ts"`. Ground it in `ephemeralValues` (browser_minted, high-entropy query param) and `sourceSeqs`. The exported `transform(method, url, responses, params?)` returns the signed URL (or `{ url?, body?, headers?, skip? }`).
 4. **`parser-helper`** — a decoder/normalizer ≥2 tools' parsers call (e.g. a shared JSPB walker, a shared field mapper). The consuming tool's parser.ts does `import { ... } from '../_shared/<name>.ts'`. Ground it in a captured response body (`sourceSeqs`).
 5. **`types`** — shared TypeScript interfaces used by ≥2 parsers. Type-only; no runtime behavior.
-6. **Auth is NEVER a shared module.** Whenever the recording has a **login** (`sharedContext.loginRequestSeqs` is non-empty — credentials were submitted, **with OR without 2FA**), declare an `authTool` entry: a standalone `authenticate_<site>` tool that handles the full login. Carry `twoFactorType` from `sharedContext` (structural: `none` = the login completes in the login request(s), no second step; `otp` = a code typed back into a later request; `push` = poll one endpoint until it flips/sets a session cookie), and for `otp` carry `twoFactorContext` (the initiate-response fields the completion request chains). Data tools for the same site set `authRecipe.required: false` and `dependsOnAuth: true` — they reuse the session a prior `authenticate_<site>` call stored, so the login runs **once**, not once per tool (re-logging-in inline for every tool hammers the site and gets rate-flagged at compile time). Only when there is **no login at all** (`loginRequestSeqs` empty), omit `authTool` and set `authRecipe.required: false` with empty arrays. `credentialNames` lists ONLY the durable login secrets the user provisions once — the `${credential.*}` fields in the login request(s), typically `username` + `password`. NEVER include the live one-time 2FA code in `credentialNames`: it is covered by `twoFactorType`/`twoFactorContext` and entered fresh at runtime, never stored.
+6. **Auth is NEVER a shared module.** When `sharedContext.authRequestSeqs` or
+   `loginRequestSeqs` is non-empty, declare one standalone
+   `authenticate_<site>` tool. Copy credential-bearing requests to
+   `credentialRequestSeqs` and all related auth requests to `authRequestSeqs`.
+   Do not prescribe phases or action boundaries; the auth compile agent derives
+   them from the recording. Data tools set `authRecipe.required: false` and
+   `dependsOnAuth: true` so they reuse the stored session. `credentialNames`
+   contains durable provisioned values only, never live one-time input.
 7. **`exportSignatures` must be real TypeScript signatures** the builder will implement and the verifier will check for. List every public export.
 8. **`spec` must be concrete enough to implement and test** — name the inputs, the exact output, and the `sourceSeqs` that prove it (e.g. "given the URL at seq 41 with the `sig` param stripped, regenerate `sig` to match the recorded value").
 9. **`dependsOn` only references other `sharedModules[].path`.** No cycles.

package/prompts/tool-candidate-detection.md

@@ -10,12 +10,8 @@ Schema:
     "credentialNames": [string],
     "tokenExtractionNotes": "string",
     "sharedHelperNotes": "string",
-    "twoFactorDetected": boolean,
-    "twoFactorType": "otp" | "push" | "none",
-    "twoFactorRequestSeqs": [number],
-    "authCompletionSeqs": [number],
-    "twoFactorContext": [string],
-    "twoFactorNotes": "string"
+    "authRequestSeqs": [number],
+    "authNotes": "string"
   },
   "candidates": [
     {
@@ -44,29 +40,13 @@ Rules:
 2. Do not expose login, auth, CSRF refresh, telemetry, page bootstrap, or
    tracking as tools. Put login/auth request seqs in sharedContext.loginRequestSeqs
    or candidate.dependencySeqs instead.
-3. When login requests include a multi-step authentication flow, set
-   `twoFactorDetected: true` and classify `twoFactorType` by the recording's
-   **structure**, not the delivery channel:
-   - **`otp`** — a *later* request carries a short code the user obtained
-     out-of-band (the code appears in the request body/params but in no earlier
-     response). SMS, email, and authenticator-app (TOTP) codes are all `otp` —
-     the channel doesn't change the replay. If that completion request reads a
-     value the *initiate response returned in its body* (e.g. a reauth `mfaId`),
-     list the field name(s) in `twoFactorContext` so the compiler chains them.
-   - **`push`** — the same endpoint is polled repeatedly until its response flips
-     (pending→approved) or a session cookie appears; no code re-enters the flow.
-     In `twoFactorNotes`, name the poll endpoint and the field/value that marks
-     approval in the recorded terminal poll.
-   Put the 2FA-related request seqs in `twoFactorRequestSeqs`; post-2FA
-   finalization requests (trusted device registration, final OAuth exchange,
-   session confirmation) in `authCompletionSeqs`. These seqs must NOT appear
-   in any candidate's `requestSeqs` — they belong to the auth flow, not data
-   tools. When no 2FA is detected, set `twoFactorDetected: false` and leave
-   the other fields at defaults. `credentialNames` lists ONLY the durable login
-   secrets the user provisions once — the `${credential.*}` fields submitted in
-   the login request(s), typically `username` + `password`. NEVER put the live
-   one-time 2FA code in `credentialNames`: it is captured by
-   `twoFactorType`/`twoFactorContext` and entered fresh at runtime, not stored.
+3. Put every request that belongs to authentication in `authRequestSeqs`,
+   including credential submission, user-interaction checkpoints, repeated
+   status checks, redirects, exchanges, and finalization. Describe only the
+   observed request/response relationships in `authNotes`; do not classify the
+   flow into runtime phases. The auth compile agent will derive its action graph
+   from the recording. `credentialNames` lists only durable login values the
+   user provisions, never live one-time input.
 4. When multiple requests contain `${credential.*}` placeholders (multiple
    login attempts in the recording), check each request's `status` and
    `responsePreview` to determine which attempt(s) actually succeeded. A