@ai-digital-factory/lmt-web-cli 0.1.4 → 0.1.5

package/README.md

@@ -43,7 +43,8 @@ npx --yes @ai-digital-factory/lmt-web-cli@latest zerodha-login --session SESSION
 npx --yes @ai-digital-factory/lmt-web-cli@latest zerodha-otp --session SESSION_ID --attempt ATTEMPT_ID --stdin
 ```
 
-The user supplies the OTP for the active attempt. Never put it in a command-line
+`zerodha-cancel --session SESSION_ID` cancels a waiting attempt through the page's
+**Cancel login** control. The user supplies the OTP for the active attempt. Never put it in a command-line
 argument or ask the CLI to retrieve it. Inspect the latest JSON result after each
 command. Control references are short-lived: every new observation or action returns
 fresh references, so use only references from the most recent result.
@@ -67,6 +68,31 @@ Broker activity. The CLI also supports `inspect`, `click`, `fill`, `select`, and
 `navigate`; run `npx --yes @ai-digital-factory/lmt-web-cli@latest --help` for the
 complete command list.
 
+## Interactive Zerodha login (human)
+
+Agents cannot receive the Zerodha OTP, so a human logs the saved Web CLI session
+into Zerodha once and agents then restore it with `start`. Run `lmt-web` with no
+arguments (or `lmt-web interactive`) in a terminal:
+
+```sh
+npx --yes @ai-digital-factory/lmt-web-cli@latest
+```
+
+Use ↑/↓ and Enter to choose **Login to Zerodha** or **Logout from Zerodha**; press
+`q` to quit. Logout asks for `y` to confirm, then uses Web's Logout Zerodha control;
+the Operator stays logged in, so the next login needs only the OTP. Interactive
+mode targets `--env dev --device desktop` by default; pass `--env local` or
+`--device mobile` to log in to another saved session. It restores or reuses that
+saved headless browser, logs in to the Operator with the provisioned SMS credential
+when required, starts the Zerodha Login Attempt, and asks for the OTP as a masked
+six-digit field. An attempt left waiting from earlier (for example by an agent) is
+cancelled first, so every run issues a fresh challenge. A rejected OTP can be
+retried on the same attempt; Esc cancels without submitting. An uncertain submission is never replayed—check the page with
+`inspect` first. On exit, a browser started by interactive mode is stopped (its
+login stays saved); a browser that was already running stays open.
+
+Interactive mode requires a terminal; without one it exits with status 2.
+
 ## Install
 
 Requires Node.js 22.13 or later, Chromium, and a macOS or Linux session owner.
@@ -274,8 +300,9 @@ also accept `--timeout` and `--full-page`.
 Credential fields are detected from their type, labels, and attributes. Use
 `fill --secret` for sensitive values in other fields. Entered secrets remain in the
 live session's redaction registry, including when echoed into text or revealed in
-an input. JSON observations omit field values and redact secret text. Screenshots
-show the rendered page without additional masking.
+an input. General JSON observations omit field values and redact secret text; explicit
+reads follow the ordinary-value/secret-metadata contract below. Screenshots mask secret
+values and their learned echoes.
 A click whose completion cannot be confirmed returns `outcome: "uncertain"` and a
 nonzero exit status. Pending browser loading is stopped to retain evidence, but the
 submitted server operation may still complete. Inspect before deciding what to do
@@ -393,6 +420,7 @@ this check performs no npm publication or live dev login.
 ```sh
 lmt-web read --session ID --ref FIELD
 lmt-web clipboard --session ID
+lmt-web paste --session ID --ref FIELD
 lmt-web check --session ID --ref FIELD --stdin < /path/to/protected-expectation
 lmt-web clipboard-check --session ID --ref FIELD
 lmt-web scroll --session ID --ref FIELD
@@ -400,19 +428,49 @@ lmt-web scroll --session ID --y 600
 lmt-web inspect --session ID --full-page
 ```
 
-read returns an ordinary field value. clipboard returns content only when it matches
-a verified ordinary field on the current page; unknown or secret content is refused.
+`read` returns `value` for an ordinary field, including Settings User ID. A protected
+field returns only `secret: {present, length, fingerprint}`. `fingerprint` is the
+12-hex SHA-256 prefix used in Broker token logs, or null for an empty value.
+`clipboard` returns an ordinary value only when it matches a verified ordinary field;
+otherwise it returns the same safe secret metadata. Reveal the saved token before
+reading it: hidden/capture-safe placeholders report `value_unreadable`, never metadata
+for the placeholder. Copy still permits safe clipboard metadata in capture-safe mode.
 check compares the field with one stdin-supplied expectation (an optional final newline
 is removed). clipboard-check compares clipboard and field inside the browser session.
 Comparisons return only matches: true or matches: false. An unreadable field/clipboard
 or an expired reference is an error without a matches result. Inspect/action observations
 continue to redact secrets, including revealed fields.
 
+`paste` reads the clipboard and updates a protected input or textarea entirely inside
+the browser. It returns secret metadata and `matches: true` only after the field retains
+the value. It does not submit the form. Read-only, ordinary, missing or rejecting fields
+and unreadable clipboards fail explicitly. A failed paste has no equality result.
+
+For current-token verification, use the existing saved browser session: navigate to
+Settings, click Copy access token, inspect clipboard metadata, click Replace access token,
+then `paste --ref` the Replacement access token input. Use fresh references from each
+result. `clipboard-check` can prove the pasted field matches. Explicitly click Validate
+and replace and inspect the resulting verification or refusal message. All actions use
+the rendered controls; no HTTP Runner profile or direct API probing is required.
+
+Screenshots mask protected field values and learned secret echoes while keeping ordinary
+fields and labels readable. Every result still includes its independent screenshot outcome.
+Same-origin browser requests carry `x-lmt-client-kind: cli` and
+`x-lmt-client-profile: web-cli-desktop|web-cli-mobile`. Control actions also send a
+`journey_step` audit through the browser to Gate's existing `/api/journey-records` ingest:
+step `Web CLI <action>`, browser session correlation, CLI attribution, action outcome and
+screenshot outcome only. No field/clipboard value, reference label or payload is logged.
+`audit.outcome` reports `recorded` only for HTTP 202; `failed`/`unavailable` means logging
+has not been established and does not reverse an already completed browser action.
+In OpenObserve, discover the current `journey_step` fields and filter by step, browser
+session and the bounded run window; join API traces using the attributed request rows.
+
 Referenced scrolling brings the control into view through its ancestors. Pixel scrolling
 targets the largest scrolling content area. Results include before/after positions and
 moved, already_visible, or at_boundary. Each observation expires older references.
+A referenced control still outside the clipped visible area reports `target_unreachable`.
 
 Full-page capture temporarily expands inner scrolling content and restores its styles
 and positions afterward. A screenshot with unexpanded clipped content reports failed;
-browser-action and screenshot outcomes remain separate. Screenshots retain the existing
-rendered-page confidentiality behavior: protect their files as you would the visible UI.
+browser-action and screenshot outcomes remain separate. Protect screenshot files as
+evidence even though their secret values are masked.