jevway 0.2.0 → 0.4.0

package/dist/task/person-wait.js

@@ -0,0 +1,104 @@
+// Identity providers' sign-in hosts. Their own pages (sign-up, settings) carry no request from another site.
+const SSO_HOSTS = {
+    'accounts.google.com': 'Google',
+    'appleid.apple.com': 'Apple',
+    'login.microsoftonline.com': 'Microsoft',
+    'login.live.com': 'Microsoft',
+};
+// A path segment that is a step of signing in: a page there is still the sign-in, whatever it shows.
+const SIGN_IN_STEP = /^(log-?in|sign-?in|sign_in|sessions?|auth|oauth2?|sso|saml2?|2fa|two-factor|mfa|otp|verify|challenge)$/i;
+// A query decoded up to twice: Google nests the OAuth request URL-encoded inside `continue`.
+const decodedQuery = (search) => {
+    let query = search;
+    for (let i = 0; i < 2; i++) {
+        try {
+            query = decodeURIComponent(query);
+        }
+        catch {
+            break;
+        }
+    }
+    return query;
+};
+/**
+ * The identity provider when `url` is its sign-in for another site: a provider host whose query carries an OAuth or
+ * OIDC request (`client_id` and `redirect_uri`, possibly nested in `continue`) or a SAML one (`SAMLRequest`).
+ *
+ * @example
+ * ssoProviderOf('https://accounts.google.com/o/oauth2/v2/auth?client_id=1&redirect_uri=https%3A%2F%2Fapp.example') // 'Google'
+ * ssoProviderOf('https://accounts.google.com/signup') // undefined
+ */
+export const ssoProviderOf = (url) => {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    const provider = SSO_HOSTS[parsed.hostname];
+    if (!provider)
+        return undefined;
+    const query = decodedQuery(parsed.search);
+    const oauth = /[?&]client_id=/.test(query) && /[?&]redirect_uri=/.test(query);
+    return oauth || /[?&]SAMLRequest=/.test(query) ? provider : undefined;
+};
+const pathOf = (url) => {
+    try {
+        const { origin, pathname } = new URL(url);
+        return { at: `${origin}${pathname}`, segments: pathname.split('/').filter(Boolean) };
+    }
+    catch {
+        return { at: url, segments: [] };
+    }
+};
+/**
+ * Whether `page` is still the sign-in `wall` was on: it shows a password field (typed or not), it is the wall's page
+ * still listing a field the wall had empty (filled or not), its path is a sign-in step (`/login`, `/sessions/two-factor`,
+ * `/auth/callback`), or it is an SSO page. Conservative: a person mid-way is never taken for done.
+ *
+ * @example
+ * stillSigningIn(dashboard, loginPage) // false
+ */
+export const stillSigningIn = (page, wall) => {
+    if (page.passwordFields?.length)
+        return true;
+    const here = pathOf(page.url);
+    if (here.at === pathOf(wall.url).at) {
+        const wallFields = new Set(wall.actions.filter((action) => action.kind === 'fill' && !action.value).map((action) => action.label));
+        if (page.actions.some((action) => action.kind === 'fill' && wallFields.has(action.label)))
+            return true;
+    }
+    return here.segments.some((segment) => SIGN_IN_STEP.test(segment)) || Boolean(ssoProviderOf(page.url));
+};
+/**
+ * Reads the page until the wall is gone for `clearReads` reads in a row, the wait runs out, or the call is stopped.
+ *
+ * @example
+ * const { outcome, page } = await waitForPersonLoop({ waitMs: 120_000, pollMs: 1000, tickMs: 10_000, clearReads: 1, read, isWall, pause, stopped, tell });
+ */
+export const waitForPersonLoop = async ({ waitMs, pollMs, tickMs, clearReads, read, isWall, pause, stopped, tell }) => {
+    const deadline = performance.now() + waitMs;
+    let nextTick = performance.now();
+    let clear = 0;
+    let page;
+    for (;;) {
+        const now = performance.now();
+        if (now >= deadline)
+            return { outcome: 'ran_out', page };
+        if (now >= nextTick) {
+            tell(Math.ceil((deadline - now) / 1000));
+            nextTick = now + tickMs;
+        }
+        await pause(Math.min(pollMs, deadline - now));
+        if (stopped())
+            return { outcome: 'stopped', page };
+        const next = await read();
+        if (!next)
+            return { outcome: 'gone', page };
+        page = next;
+        clear = (await isWall(page)) ? 0 : clear + 1;
+        if (clear >= clearReads)
+            return { outcome: 'passed', page };
+    }
+};

package/dist/task/present.js

@@ -1,6 +1,7 @@
 import { describeStep } from '../recording/describe-step.js';
+import { askUserFor } from './ask-user.js';
 // What the run appends to a step's element, in parentheses: a tab switch, a dialog, a scroll that moved nothing.
-const NOTE = / \((?=new tab opened: |the tab closed; |nothing moved: |the page then )/;
+const NOTE = / \((?=new tab opened: |the tab closed; |nothing moved: |the page then |downloaded |download of )/;
 const splitNotes = (element) => {
     const [label, ...notes] = element.split(NOTE);
     return { label, notes: notes.map((note) => note.replace(/\)$/, '')) };
@@ -10,6 +11,10 @@ const outcomeOf = (note) => {
         return `a ${note}`;
     if (note.startsWith('nothing moved: '))
         return 'nothing moved';
+    // 'downloaded invoice.pdf, 84 KB' → 'downloaded invoice.pdf (84 KB)'
+    const downloaded = /^(downloaded .+), (\d[\d.]* (?:bytes|KB|MB))$/.exec(note);
+    if (downloaded)
+        return `${downloaded[1]} (${downloaded[2]})`;
     return note;
 };
 const lowerFirst = (text) => text.charAt(0).toLowerCase() + text.slice(1);
@@ -38,40 +43,56 @@ export const storyLine = (step) => {
 };
 /** A call's steps as one sentence each. */
 export const storyOf = (steps) => steps.map(storyLine);
+const ASK = 'Ask the user the `ask_user` question with your ask tool';
 /**
- * The one thing the caller does next after this status, in the tools' parameter names.
+ * The one thing the caller does next after this status, in the tools' parameter names; with `asking`, it starts from
+ * the result's `ask_user` question.
  *
  * @example
  * nextFor({ status: 'needs_input', … }) // 'Add the missing values to `values` and call again with this session.'
  */
-export const nextFor = ({ status, wall }) => {
+export const nextFor = ({ status, wall }, { asking = false } = {}) => {
     switch (status) {
         case 'done':
             return 'Read the result in `page_text` (and `evidence`); end the session when you no longer need its tab.';
         case 'needs_input':
-            return 'Add the missing values to `values` and call again with this session.';
+            return asking
+                ? `${ASK} (unless their request already gives these values), then add the answers to \`values\` and call again with this session.`
+                : 'Add the missing values to `values` and call again with this session.';
         case 'needs_confirmation':
-            return "Ask the user, unless their own request names this action and its target; then call again with this session, `confirm_irreversible: true` and `confirm_target` (the user's words naming the target).";
+            return asking
+                ? `${ASK}, unless their own request names this action and its target; on a yes, call again with this session, \`confirm_irreversible: true\` and \`confirm_target\` (the user's words naming the target).`
+                : "Ask the user, unless their own request names this action and its target; then call again with this session, `confirm_irreversible: true` and `confirm_target` (the user's words naming the target).";
         case 'uncertain':
-            return 'Look at the screenshot and `page_text`, then call again with this session and a clearer `goal`, or finish the step yourself.';
+            return asking
+                ? `${ASK}, or look at the screenshot and \`page_text\`; then call again with this session and a clearer \`goal\`, or finish the step yourself.`
+                : 'Look at the screenshot and `page_text`, then call again with this session and a clearer `goal`, or finish the step yourself.';
         case 'step_budget':
             return 'Call again with this session and a narrower `goal`, or a larger `max_steps` / `max_seconds`.';
         case 'blocked':
-            if (wall?.kind === 'bot_check')
-                return 'Never try to get past it: ask the user to pass it in that tab, then call again with this session.';
-            if (wall?.kind === 'sign_in')
-                return `Sign in at ${wall.origin} (or pass the values the form wants), then call again with this session.`;
+            if (wall?.kind === 'bot_check') {
+                return asking
+                    ? `Never try to get past it: ${ASK.charAt(0).toLowerCase()}${ASK.slice(1)} (they pass it in that tab), then call again with this session.`
+                    : 'Never try to get past it: ask the user to pass it in that tab, then call again with this session.';
+            }
+            if (wall?.kind === 'sign_in') {
+                return asking
+                    ? `${ASK} (they sign in at ${wall.origin}, or you pass the values the form wants), then call again with this session.`
+                    : `Sign in at ${wall.origin} (or pass the values the form wants), then call again with this session.`;
+            }
             return 'Read the reason: tell the user, or change `goal` or `values` and call again with this session.';
     }
 };
 const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, inner]) => inner !== undefined));
 export function presentSummary({ session, summary, files }, { detail = 'concise' } = {}) {
+    const ask_user = askUserFor(summary);
     // The order both adapters print: how it ended and what to do first, then where, and the long page text last.
     const { page_text, ...head } = {
         status: summary.status,
         reason: summary.reason,
         story: storyOf(summary.steps),
-        next: nextFor(summary),
+        next: nextFor(summary, { asking: ask_user !== undefined }),
+        ask_user,
         session,
         url: summary.url,
         title: summary.title,