imprint-mcp 0.6.6 → 0.7.1

package/prompts/auth-compile-agent.md

@@ -1,32 +1,65 @@
 # Auth compile agent
 
-Compile the captured authentication recording into a deterministic
+Compile the captured authentication recording and observed live evidence 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.
+request repetition, error behavior, and completion criteria from the available evidence.
 The runtime only executes the program you write.
 
 ## Process
 
-1. Call `read_session_summary`.
+1. On the first task, call `read_session_summary`. On a recovery request in the
+   retained conversation, reuse the artifacts and decisive earlier observations;
+   read additional recording evidence only where the current question needs it.
 2. Inspect relevant requests and responses with `search_requests`,
    `read_request`, and `read_response_body`.
-3. Write `workflow.json`, an offline `request.test.ts`, and any
-   recording-grounded `request-transform.ts` needed by the requests. Call
+3. When the recording does not cover the currently offered flow, use
+   `interact_verification_browser` to inspect and operate the live UI. It can
+   open the recorded page before a workflow exists, or continue in the current
+   verification browser without resetting its state. Choose the available
+   authentication method from live evidence; a different MFA method is a reason
+   to investigate, not by itself a reason to require another human recording.
+   The tool captures network requests/responses, returns their sequence numbers,
+   and adds them to the ordinary recording readers and `IMPRINT_SESSION_PATH`.
+   First establish how to check or restore existing access without submitting
+   credentials or delivering a factor. Prefer that observed path as the entry
+   action. A recording with MFA demonstrates one branch, not a requirement to
+   replay MFA for an already usable session.
+4. Write `workflow.json`, an offline `request.test.ts`, and any
+   evidence-grounded `request-transform.ts` needed by the requests. Call
    `run_tests` and fix request construction before live verification.
-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
+5. Call `run_verification` with one declared action and its parameters. Await
+   the host result and use its observed status, execution facts, body preview,
+   and next action. The browser and declared continuation remain with the host.
+6. 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`
+7. Call `done` only after a live action whose selected 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.
+Use `interact_verification_browser` for live discovery and `run_verification`
+for compiled replay. Do not contact the site through shell commands or other
+tools. Discovery captures what the UI actually does; do not guess send/verify
+endpoints. Read the captured requests and responses to learn the new branch,
+then encode and test its reusable action program.
+
+Browser actions are `inspect`, `navigate` (url), `click` (selector), `fill` or
+`select` (selector and value), `press` (key), and `wait` (milliseconds). Returned
+controls include exact CSS selectors. Secret fill values use existing
+`${credential.NAME}` or the current `${prompt.ID}` reference. Ask the human for
+an actual OTP or external approval when required; do not ask them to invent
+endpoints or supply a new recording just because the factor differs. Capturing
+continues while the human answers. Inspect/wait again to collect later traffic;
+an observation interval does not prove the page has finished its work.
+
+Live discoveries remain separate observations from the original demonstrations.
+Their request sequences can ground `recordingRequestSeq`, captures, and offline
+tests, but their transient values must be obtained afresh during replay. Browser
+interaction or a manually established session does not by itself verify the
+compiled login/MFA program. After learning a branch, use `run_verification` to
+test it and report the actions actually executed.
 
 Verification reuses one browser and continuation state by default. If an
 observed result proves that state is no longer usable, you may set
@@ -36,11 +69,58 @@ 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.
 
+Later authentication requests retain this compiler conversation, workflow, browser
+and continuation within the same teach. A consumer failure is a new observation,
+not an instruction to restart credential login. Try the proven noninteractive
+session check or context-restoration action in that browser before starting
+another credential exchange. If it passes, return that result so the caller can
+retry its own protected operation. If access is still unusable, inspect the
+current response and context before deciding whether login is needed.
+Decide whether to inspect the
+current page, continue an action, restore its context, change the workflow, or
+start a new login. Keep useful recovery actions in the procedure once the
+observations establish why they work. You can revise every action boundary.
+When navigation changes the page or loses its query, compare the observed page
+and network response with the action's intended context. Choose a declared
+bootstrap or context-restoration action when useful; incidental origin-root
+navigation is not evidence that the requested page context was restored.
+Report which actions actually ran and which workspace/browser they verified.
+Earlier success does not prove that a different consumer has usable state.
+
+Separate response inspection from actions that deliver MFA. After checking the
+session or submitting credentials, branch on the observed current response:
+finish on established usable access, continue login on an observed login-required
+state, and deliver a factor only on an observed current challenge. Do not bundle
+an unconditional challenge/delivery sequence into every login action. Use the
+action `branches` below to encode the observed alternatives and keep delivery
+in its own action. Unknown responses should return repairable failure through
+missing declared evidence rather than silently choosing login or MFA. Do not
+invent an authenticated/trusted-browser branch from cookie names, HTTP 200, a
+user identifier, or a remember-me flag. Learn and test the offered path. Preserve
+observed device-registration inputs and their lifetime; do not regenerate
+long-lived device material merely because a new action is invoked.
+
+Human-response references remain available for repairs to the current challenge.
+Declared nonsecret option choices return a typed `kind: "choice"` value. Use that
+exact current choice to decide what to do next; a negative or unavailable answer
+is not approval. Secret and free-text answers remain host-held references.
+They expire when a fresh verification session is requested and between
+requests for authentication. Never reuse an earlier approval for a new challenge;
+ask about the currently delivered challenge when fresh approval is required.
+
+
+Existing `${credential.NAME}` strings in the recording name credentials held by
+the local backend; they are not literal login values. Keep those references in
+the workflow. The host resolves them for live verification. Request a missing
+value through `prompt_user` when verification reports it unavailable; a recording
+containing placeholders alone is not evidence that stored credentials are absent.
+
 ## Auth program
 
-Set `toolKind` to `"authenticate"`. Keep recorded network operations in the
+Set `toolKind` to `"authenticate"`. Keep observed network operations in the
 ordinary top-level `requests` array. `authConfig` references those requests:
 
+<!-- canonical-example:auth-session-branches -->
 ```json
 {
   "entry": "agent_chosen_entry",
@@ -53,6 +133,20 @@ ordinary top-level `requests` array. `authConfig` references those requests:
           "onError": "fail"
         }
       ],
+      "branches": [
+        {
+          "when": {
+            "source": "json",
+            "name": "recording_grounded_existing_session",
+            "path": "recorded.current_state",
+            "equals": "recorded_authenticated_value"
+          },
+          "outcome": {
+            "type": "success",
+            "evidence": ["recording_grounded_existing_session"]
+          }
+        }
+      ],
       "outcome": {
         "type": "pause",
         "next": "agent_chosen_next",
@@ -103,20 +197,32 @@ semantics.
   `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.
+- `branches` is optional and ordered. After all steps, each `when` is a normal
+  request capture evaluated against the final step's current response. The first
+  match supplies its named capture and selects that branch's `outcome`. A failed
+  or skipped final step cannot reuse an earlier response. Carried capture values
+  alone cannot match a branch. Use distinct capture names for the conditions.
+  Keep side-effecting delivery in a separate next action: branches do not skip
+  requests already listed in `steps`.
+- `outcome` is the fallback if no branch matches. Its evidence must still exist;
+  require evidence for the known fallback state so an unknown response fails.
 - `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
+  declares an exact `equals` value. Choose evidence from recorded or live observations 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.
+  Verify the session-reuse path and each login/MFA path actually offered by the
+  observed flow separately. Do not restart login just to repeat an already
+  passing reuse check, and do not claim an untested branch works.
 - `persist` names durable credential interfaces that data tools consume later as
   `${credential.NAME}`. Cookies persist automatically. These interface names do
   not constrain your internal capture names. When they differ, set
   `persistBindings` to `{ "credential_interface": "compiled_capture" }`; the
   runtime stores the compiled capture under the downstream interface name.
-- Set `crossOriginCookieReinjection` only when the recording proves a
+- Set `crossOriginCookieReinjection` only when observed evidence proves a
   cross-origin response cookie must be projected into the browser jar.
 
 ## Request construction
@@ -124,25 +230,33 @@ semantics.
 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`.
+Navigation can explicitly select a completed page-generated response with
+`networkResponse: { urlIncludes, recordingResponseRequestSeq, method?, resourceType?, occurrence? }`; use
+that only when the recording proves the browser must create the request and
+the selected body supplies this action's needed data.
 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.
+the outgoing request. It is required on requests whose captures appear in
+`authConfig.persist`. For an ordinary request, that request's response is the
+capture evidence. For `navigation.networkResponse`, the capture evidence is
+instead the response cited by `recordingResponseRequestSeq`.
 
 For a response field that contains another JSON document as a string, use a
 JSON capture with `path` for the outer field and `decodeJsonPath` for the value
 inside the decoded document. Do not capture structured nested JSON credentials
 with a regular expression; response escaping can change or truncate the value.
 
-For every durable interface in `authConfig.persist`, add a
-`request.test.ts` test whose title contains
-`persisted-capture:<credential-interface-name>`. Load the redacted recording
-through `process.env.IMPRINT_SESSION_PATH`, locate the declared
-`recordingRequestSeq`, independently decode the intended response field, and
-assert that evaluating the compiled capture produces that exact value. A
-nonempty assertion or comparison of the locator to itself is insufficient:
-the test must catch a broad regex or wrong nested path that resolves to a
-different field. Keep captured values in memory; never inline or print them.
+For every durable interface in `authConfig.persist`, exercise its capture in
+`request.test.ts`. Load the redacted recording through
+`process.env.IMPRINT_SESSION_PATH`, locate the declared `recordingRequestSeq`,
+or locate `navigation.networkResponse.recordingResponseRequestSeq` when the
+capture reads a selected page-generated response. Independently decode the
+intended response field, and assert that evaluating the compiled capture
+produces that exact value. A nonempty assertion or
+comparison of the locator to itself is insufficient: the test must catch a
+broad regex or wrong nested path that resolves to a different field. Keep
+captured values in memory; never inline or print them. The host checks that the
+test file exists and runs it; independent reviewers judge whether its evidence
+is convincing.
 
 `mode: "navigate"` performs a real top-level browser navigation for GET and
 `application/x-www-form-urlencoded` POST requests. Use it when the recording
@@ -152,6 +266,14 @@ preserved. Its response exposes the browser's final URL in the synthetic
 `source: "response_header"` when a redirect URL carries state needed by a later
 request.
 
+When `navigation.networkResponse` is present, the selected response body is
+returned instead of the rendered document. This is a precise agent-authored
+match, not automatic XHR selection and not a DOM playbook. Prefer a normal API
+request when it can express the same operation.
+The outer `recordingRequestSeq` must cite the document navigation, while
+`recordingResponseRequestSeq` must cite the background request whose response
+is returned. Do not use either sequence for both roles.
+
 Use runtime templates exactly as supported:
 `${credential.X}`, `${param.X}`, `${state.X}`,
 `${response[N].path}`, and `${generated.uuid|nonce|epoch_s|epoch_ms|iso8601}`.
@@ -179,20 +301,59 @@ and its exact `recordingRequestSeq`; do not request live verification for that
 workflow. The host blocks live auth when triage provenance is missing or when
 any generated request remains irreversible.
 
-Ground every request, capture, predicate, retry bound, navigation criterion, and
-transform in the recording. Preserve functional headers and request encoding.
+Ground requests, captures, predicates, navigation criteria, and transforms in
+the supplied recording or captured live browser/network evidence. Choose retry
+bounds from observed behavior. The original recording is a starting point, not
+a whitelist of allowed authentication methods. 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
+must mint coupled state, represent the observed 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.
 
+The module must export `transform(method, url, responses, params)`:
+
+```typescript
+export function transform(
+  method: string,
+  url: string,
+  responses: unknown[],
+  params?: Record<string, string | number | boolean>,
+) {
+  return { url };
+}
+```
+
+`method` and `url` are the substituted request strings, `responses` contains
+earlier raw response bodies from the current action only, and `params` contains
+resolved scalar parameters. Responses from an earlier action are not supplied.
+Cross-action values must come from declared carry or persisted inputs; you may
+carry a value, refetch it, combine actions, or redesign the procedure.
+The runtime does not pass a request object, current body, or current headers.
+Return a URL string or an object with optional `url`, `body`, `headers`,
+`navigation`, or `skip` fields. Build complete body/header replacements from
+the supported inputs. Both synchronous and asynchronous transforms are awaited.
+Thrown errors and rejected promises return `BAD_RESPONSE` verification feedback;
+use that feedback to repair the transform and retry the action. Exercise the
+same calling convention in your offline tests.
+
+For synthetic action tests, optionally import `createAuthActionTestHarness`
+from `imprint-mcp/runtime`. It accepts `{ workflow, credentials?, respond,
+browser? }`; `respond(request)` returns a synthetic `Response`, and
+`harness.run(action, parameters?)` executes the actual action program with only
+its declared continuation/session state. Supply constructed fixture values and
+responses. These offline tests do not contact the site or prove live success.
+
 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.
+Native and API host tools return their results directly. Await
+`interact_verification_browser`, `run_verification`, `inspect_verification_page`,
+`prompt_user`, or `wait_for_cooldown`, then continue in the same assignment.
+Do not submit the assignment merely because a host operation returned.
+
+CLI adapters that require checkpoint/resume instead return `CHECKPOINT_RECORDED`.
+Only for that response, stop and wait for the orchestrator to resume the same
+conversation with the result. Call `done` or `give_up` when the task is complete.

package/prompts/build-planning.md

@@ -87,7 +87,7 @@ 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?, headers?, skip? }`).
+3. **`request-transform`** — request preparation shared across tools. Wire-up: the consuming tool sets `requestTransformModule: "../_shared/<name>.ts"`. Ground it in exact recorded request/response evidence and `sourceSeqs`. The exported `transform(method, url, responses, params?)` returns either a body string or `{ url?, body?, headers?, navigation?, skip? }`, matching the runtime contract.
 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.** When `sharedContext.authRequestSeqs` or
@@ -101,8 +101,8 @@ You receive:
 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.
-10. **Be conservative.** Never invent a module without grounding `sourceSeqs`. If unsure whether two tools truly share logic, leave it per-tool (empty `sharedModules`, empty `usesSharedModules`). A wrong shared module forces every assigned tool to import code that doesn't fit. Fewer, well-grounded modules beat many speculative ones.
-11. `paramChecklist` mirrors the candidate's `likelyParams` names — the inputs each tool must template as `${param.NAME}`.
+10. **Be conservative.** Never invent a module without grounding `sourceSeqs`. If unsure whether two tools truly share logic, leave it per-tool (empty `sharedModules`, empty `usesSharedModules`). These are advisory module proposals for the master to consider, not host-enforced import assignments. Fewer, well-grounded modules beat many speculative ones.
+11. `paramChecklist` is your evidence-backed proposal for the public inputs worth investigating during focused compilation. It may add, rename, or drop candidate `likelyParams`; the detector list is not authoritative.
 12. **Producer-derived chains (`emitsTokens` / `tokenParams`).** When one tool's param is an opaque id/token OR another context value a caller cannot type reliably — because its value is minted/derived by ANOTHER selected tool's response (a `search_*` → `get_*_details` chain) — model it as a cross-tool compatibility target instead of asking the caller/auditor to fabricate it. An `emitsTokens` entry does not redefine the producer's core success: useful producer records and input classes remain valid when an optional downstream token is unavailable, provided compilation records the missing output and affected consumers as a limitation. Start from `tokenContractHints[]` (each entry is a pre-detected edge you MUST declare), and also catch any the diff missed (`ephemeralValues` with a `server_derived` `producerSeq` belonging to a different tool's `requestSeqs`, or a `dependencySeqs` link):
     - On the CONSUMER, add `tokenParams: [{ param, sourceTool, sourceField }]` — the param's value comes from `sourceTool`'s `sourceField` output, used as-is.
     - On the PRODUCER (`sourceTool`), add `emitsTokens: [{ field, shape }]` so its parser uses that exact `field` and emits the full shape when the response supplies it (e.g. a composite of id + area context), never a bare or fabricated fragment. If some useful result class lacks the field, preserve that class and require an explicit producer limitation; leave affected consumers limited/unverified rather than narrowing the producer merely to make the chain total.