@qoniai/qoni 0.8.0 → 0.9.0

package/dist/index.cjs

@@ -23,7 +23,7 @@ __export(index_exports, {
   ActionKinds: () => ActionKinds,
   InteractionHandle: () => InteractionHandle,
   InteractionStatuses: () => InteractionStatuses,
-  InteractionTypes: () => InteractionTypes,
+  InteractionTypes: () => InteractionTypes2,
   MonitorHandle: () => MonitorHandle,
   Qoni: () => Qoni,
   QoniAuthError: () => QoniAuthError,
@@ -566,8 +566,22 @@ var QoniScopes = {
   // interaction). Not part of any product bundle: the AccessKey policy must
   // allow it, and the delegation must request it explicitly.
   SITE_LOGIN_REQUEST: "webagent.site_login:request",
-  // Persist that login into the browser profile (`OpenLoginResult.confirm()`).
-  SITE_LOGIN_CONFIRM: "webagent.site_login:confirm"
+  // Persist that login into the browser profile (`InteractionHandle.confirmSignedIn()`
+  // after `openLogin()`).
+  SITE_LOGIN_CONFIRM: "webagent.site_login:confirm",
+  // The delegating user's own data and the Agent's own mailbox (Personal
+  // Agent guide). Not part of any product bundle: request them explicitly;
+  // the AccessKey policy must allow them.
+  // Read the user's Profile (name, phone, shipping address, card brand + last 4).
+  USER_PROFILE_READ: "user.profile:read",
+  // Write answers back into the user's Profile.
+  USER_PROFILE_WRITE: "user.profile:write",
+  // Use the user's saved payment card once the user approves a payment.
+  USER_PAYMENT_USE: "user.payment:use",
+  // Read mail received by the Agent's own mailbox (for example verification codes).
+  AGENT_MAIL_READ: "agent.mail:read",
+  // Send mail from the Agent's own mailbox.
+  AGENT_MAIL_SEND: "agent.mail:send"
 };
 var QoniProductScopes = {
   doAnything: [
@@ -620,6 +634,15 @@ var QoniScopeBundles = {
 };
 
 // src/interactions.ts
+var InteractionTypes2 = {
+  SiteLogin: "site_login",
+  TakeControl: "take_control",
+  AskUser: "ask_user",
+  Confirmation: "confirmation",
+  Wait: "wait",
+  /** @deprecated `clarification` is presented as `ask_user`; use `InteractionTypes.AskUser`. */
+  Clarification: "ask_user"
+};
 function asString2(value) {
   return typeof value === "string" && value ? value : void 0;
 }
@@ -648,6 +671,49 @@ function normalizeEvidence(c) {
   const artifactId = asString2(c.evidenceArtifactId) ?? (isJsonObject(c.evidence) ? asString2(c.evidence.artifactId) : void 0);
   return artifactId ? { artifactId } : void 0;
 }
+var ANSWER_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "number",
+  "boolean",
+  "single_choice",
+  "multiple_choice"
+]);
+function normalizeOptions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((raw) => {
+    if (typeof raw === "string") return [{ value: raw, label: raw }];
+    if (!isJsonObject(raw) || typeof raw.value !== "string") return [];
+    return [{ value: raw.value, label: typeof raw.label === "string" ? raw.label : raw.value }];
+  });
+}
+function isAnswerType(value) {
+  return value !== void 0 && ANSWER_TYPES.has(value);
+}
+function askUserPayload(c) {
+  const options = normalizeOptions(c.options);
+  const native = asString2(c.answerType);
+  const hint = asString2(c.inputType);
+  let answerType;
+  if (isAnswerType(native)) answerType = native;
+  else if (isAnswerType(hint) && hint !== "single_choice" && hint !== "multiple_choice") answerType = hint;
+  else answerType = options.length > 0 ? hint === "multiple_choice" ? "multiple_choice" : "single_choice" : "text";
+  const payload = { question: asString2(c.question) ?? "", answerType };
+  if (options.length > 0) payload.options = options;
+  return payload;
+}
+var BASE_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "status",
+  "createdAt",
+  "resolvedAt",
+  "expiresAt",
+  "title",
+  "prompt",
+  "evidence",
+  "evidenceArtifactId",
+  "actions"
+]);
 function shapePayload(type, c) {
   switch (type) {
     case "site_login": {
@@ -664,14 +730,10 @@ function shapePayload(type, c) {
       const payload = { sites };
       const monitorId = asString2(c.monitorId);
       if (monitorId) payload.monitorId = monitorId;
-      return payload;
-    }
-    case "clarification": {
-      const payload = { question: asString2(c.question) ?? "" };
-      const inputType = asString2(c.inputType);
-      if (inputType) payload.inputType = inputType;
-      return payload;
+      return { ...payload };
     }
+    case "ask_user":
+      return { ...askUserPayload(c) };
     case "confirmation":
       return { summary: asString2(c.summary) ?? "" };
     case "take_control": {
@@ -680,7 +742,7 @@ function shapePayload(type, c) {
       const reason = asString2(c.reason);
       if (surface) payload.surface = surface;
       if (reason) payload.reason = reason;
-      return payload;
+      return { ...payload };
     }
     case "wait": {
       const payload = {
@@ -690,14 +752,20 @@ function shapePayload(type, c) {
       const retryable = asBool(c.retryable);
       if (until) payload.until = until;
       if (retryable !== void 0) payload.retryable = retryable;
+      return { ...payload };
+    }
+    default: {
+      const payload = {};
+      for (const [key, value] of Object.entries(c)) if (!BASE_FIELDS.has(key)) payload[key] = value;
       return payload;
     }
   }
 }
 function normalizeInteraction(payload) {
   const c = camelizeRecord(payload);
-  const type = asString2(c.type);
-  if (!type) return null;
+  const wireType = asString2(c.type);
+  if (!wireType) return null;
+  const type = wireType === "clarification" ? "ask_user" : wireType;
   const interaction = {
     id: asString2(c.id) ?? "",
     type,
@@ -717,15 +785,109 @@ function normalizeInteraction(payload) {
   if (evidence) interaction.evidence = evidence;
   return interaction;
 }
+var SETTLED_INTERACTION_STATUSES = /* @__PURE__ */ new Set(["resolved", "expired", "canceled"]);
+function isSettlingShell(next) {
+  if (!SETTLED_INTERACTION_STATUSES.has(next.status) || next.actions.length > 0) return false;
+  switch (next.type) {
+    case "ask_user":
+      return next.payload.question === "";
+    case "site_login":
+      return next.payload.sites.every((site) => !site.siteId);
+    case "confirmation":
+      return next.payload.summary === "";
+    default:
+      return false;
+  }
+}
+function foldInteraction(previous, next) {
+  if (!previous || previous.id !== next.id || !isSettlingShell(next)) return next;
+  const folded = { ...previous, status: next.status, actions: next.actions };
+  if (next.resolvedAt) folded.resolvedAt = next.resolvedAt;
+  return folded;
+}
 function interactionActionScopes(action, productManageScope) {
   return action.kind === ActionKinds.openLogin ? [QoniScopes.SITE_LOGIN_REQUEST] : [productManageScope];
 }
+function loginSlotIdle(slot) {
+  return slot.inflight === 0 && (!slot.session || slot.ended === true || slot.session.completed === true);
+}
+function markLoginEnded(store, interaction) {
+  if (!SETTLED_INTERACTION_STATUSES.has(interaction.status)) return;
+  const slot = store.get(interaction.id);
+  if (slot) slot.ended = true;
+}
+var SAVE_RETRY_PROBES = /* @__PURE__ */ new Set(["release_failed"]);
+function isNoPendingLogin(err) {
+  return err instanceof QoniError && err.status === 409 && err.code === "no_pending_login";
+}
+var INTERACTION_MEMORY_LIMIT = 256;
+function rememberBounded(map, key, value, limit = INTERACTION_MEMORY_LIMIT, evictable = () => true) {
+  map.delete(key);
+  map.set(key, value);
+  if (map.size <= limit) return;
+  for (const [candidate, entry] of map) {
+    if (map.size <= limit) break;
+    if (candidate !== key && evictable(entry)) map.delete(candidate);
+  }
+}
+function interactionSettled(interaction) {
+  return SETTLED_INTERACTION_STATUSES.has(interaction.status);
+}
+function controlSession(response) {
+  const raw = isJsonObject(response) ? response : {};
+  const fields = camelizeRecord(raw);
+  const session = { liveUrl: asString2(fields.standaloneControlUrl) ?? asString2(fields.liveUrl) ?? "", raw };
+  const expiresAt = asString2(fields.controlTokenExpiresAt) ?? asString2(fields.expiresAt);
+  const status = asString2(fields.status);
+  if (expiresAt) session.expiresAt = expiresAt;
+  if (status) session.status = status;
+  return session;
+}
+function describeOptions(payload) {
+  return (payload.options ?? []).map((option) => option.value).join(", ");
+}
+function checkAnswer(payload, value) {
+  const fail = (expected) => {
+    throw new QoniValidationError(`answer() for a ${payload.answerType} question expects ${expected}`);
+  };
+  const values = new Set((payload.options ?? []).map((option) => option.value));
+  switch (payload.answerType) {
+    case "text":
+      if (typeof value !== "string") fail("a string");
+      return;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) fail("a finite number");
+      return;
+    case "boolean":
+      if (typeof value !== "boolean") fail("a boolean");
+      return;
+    case "single_choice":
+      if (typeof value !== "string" || values.size > 0 && !values.has(value)) {
+        fail(`one option value: ${describeOptions(payload)}`);
+      }
+      return;
+    case "multiple_choice":
+      if (!Array.isArray(value)) fail(`an array of option values: ${describeOptions(payload)}`);
+      if (value.some((item) => typeof item !== "string" || values.size > 0 && !values.has(item))) {
+        fail(`option values only: ${describeOptions(payload)}`);
+      }
+      return;
+  }
+}
 var InteractionHandle = class {
-  constructor(interaction, post) {
+  /**
+   * @param loginSessions Login sessions opened on interactions, by interaction
+   *   id. A RunHandle / MonitorHandle shares one store across the handles it
+   *   hands out, so `confirmSignedIn()` finds the login `openLogin()` opened
+   *   even on the handle of a later event.
+   */
+  constructor(interaction, post, loginSessions = /* @__PURE__ */ new Map()) {
     this.post = post;
+    this.loginSessions = loginSessions;
     this.interaction = interaction;
   }
   post;
+  loginSessions;
   interaction;
   get id() {
     return this.interaction.id;
@@ -743,9 +905,18 @@ var InteractionHandle = class {
   can(kind) {
     return this.interaction.actions.some((a) => a.kind === kind);
   }
-  /** Answer a clarification ask. */
-  async answer(text) {
-    await this.invoke(ActionKinds.answer, { response: text });
+  /**
+   * Answer an `ask_user` question. The value follows `payload.answerType`:
+   * `text` → string, `number` → number, `boolean` → boolean, `single_choice` →
+   * one option `value`, `multiple_choice` → an array of option values. A value
+   * that does not fit throws `QoniValidationError` before anything is sent.
+   */
+  async answer(value) {
+    const action = this.#declaredAction(ActionKinds.answer);
+    if (this.interaction.type === "ask_user") {
+      checkAnswer(this.interaction.payload, value);
+    }
+    await this.post(action, { response: value });
   }
   /** Skip / dismiss the interaction (proceed without acting on it). */
   async skip() {
@@ -763,8 +934,8 @@ var InteractionHandle = class {
    * Start an interactive login session for a `site_login` interaction. The
    * backend needs the site to sign in to: pass `siteId`, or omit it when the
    * interaction lists exactly one site. Show `liveUrl` to the user; when they
-   * finish, call `confirm()` on the result to save the login, and act on its
-   * outcome (see {@link OpenLoginResult.confirm}) before {@link confirmSignedIn}.
+   * say they are signed in, call {@link confirmSignedIn}, which saves the login
+   * and lets the agent continue.
    * The delegation must include `QoniScopes.SITE_LOGIN_REQUEST` and
    * `QoniScopes.SITE_LOGIN_CONFIRM`; the AccessKey policy must allow both.
    */
@@ -777,57 +948,82 @@ var InteractionHandle = class {
       }
       body.profile_id = options.profileId;
     }
-    const response = await this.invoke(ActionKinds.openLogin, body);
+    const slot = this.#loginSlot();
+    const call = ++slot.calls;
+    slot.inflight += 1;
+    let response;
+    try {
+      response = await this.invoke(ActionKinds.openLogin, body);
+    } finally {
+      slot.inflight -= 1;
+    }
     const raw = isJsonObject(response) ? response : {};
     const fields = camelizeRecord(raw);
     const profileId = asString2(fields.profileId) ?? "";
     const siteId = asString2(fields.siteId) ?? String(body.site_id);
+    const sessionId = asString2(fields.sessionId) ?? "";
+    const current = slot.session;
+    const reused = current !== void 0 && sessionId !== "" && current.sessionId === sessionId && current.profileId === profileId && current.siteId === siteId;
+    const session = reused ? current : { profileId, siteId, sessionId, call };
+    if (reused) {
+      current.call = Math.max(current.call, call);
+    } else if (profileId && (current?.call ?? 0) < call) {
+      if (current) current.replaced = true;
+      slot.session = session;
+    } else {
+      session.replaced = true;
+    }
     return {
       profileId,
       siteId,
-      sessionId: asString2(fields.sessionId) ?? "",
+      sessionId,
       liveUrl: asString2(fields.liveUrl) ?? "",
       raw,
       confirm: async (confirmOptions = {}) => {
         if (!profileId) {
           throw new QoniValidationError("openLogin response did not include a profileId to confirm");
         }
-        const confirmBody = { site_id: siteId };
-        if (confirmOptions.displayLabel !== void 0) confirmBody.display_label = confirmOptions.displayLabel;
-        const response2 = await this.post(
-          {
-            kind: ActionKinds.openLogin,
-            label: "Confirm login",
-            method: "POST",
-            endpoint: `/profiles/${encodeURIComponent(profileId)}/confirm`
-          },
-          confirmBody,
-          { requiredScopes: [QoniScopes.SITE_LOGIN_CONFIRM] }
-        );
-        const raw2 = isJsonObject(response2) ? response2 : {};
-        const fields2 = camelizeRecord(raw2);
-        const state = asString2(fields2.state) ?? "";
-        return {
-          profileId: asString2(fields2.profileId) ?? profileId,
-          active: state === "active",
-          state,
-          probeResult: asString2(fields2.probeResult) ?? "",
-          raw: raw2
-        };
+        if (session.replaced) {
+          throw new QoniValidationError(
+            "this login session was replaced by a newer openLogin(); confirm the newer one (or call confirmSignedIn(), which saves the current session)"
+          );
+        }
+        return this.#saveOnce(session, confirmOptions);
       }
     };
   }
-  /** Tell the agent the user has finished signing in. */
+  /**
+   * The user finished signing in through the live browser `openLogin()`
+   * opened. Saves that login (so later tasks reuse it), then tells the agent
+   * to recheck the site and continue. If the user is not signed in after all,
+   * the agent raises a new `site_login` interaction.
+   *
+   * Saving needs `QoniScopes.SITE_LOGIN_CONFIRM` on the delegation; without
+   * `openLogin()` on this interaction, only the recheck is sent.
+   */
   async confirmSignedIn() {
-    await this.invoke(ActionKinds.confirmSignedIn);
+    const action = this.#declaredAction(ActionKinds.confirmSignedIn);
+    const session = this.loginSessions.get(this.id)?.session;
+    if (!session) {
+      await this.post(action, void 0);
+      return;
+    }
+    session.done ??= this.#saveThenRecheck(session, action).catch((err) => {
+      session.done = void 0;
+      throw err;
+    });
+    await session.done;
   }
-  /** Connect to the live browser for a take_control interaction. */
+  /**
+   * Take over the live browser for a take_control interaction. Resolves to the
+   * signed control URL to show the user (`liveUrl`) and when it expires.
+   */
   async connectControl() {
-    await this.invoke(ActionKinds.connectControl);
+    return controlSession(await this.invoke(ActionKinds.connectControl));
   }
-  /** Refresh the live control surface / live url. */
+  /** Get a fresh control URL when the current one expired. */
   async refreshControl() {
-    await this.invoke(ActionKinds.refreshControl);
+    return controlSession(await this.invoke(ActionKinds.refreshControl));
   }
   /** Hand control back to the agent. */
   async releaseControl() {
@@ -841,6 +1037,81 @@ var InteractionHandle = class {
   async switchProfile() {
     await this.invoke(ActionKinds.switchProfile);
   }
+  /** `POST /profiles/{profileId}/confirm` — persist the login of `session`. */
+  async #confirmLogin(session, options = {}) {
+    const confirmBody = { site_id: session.siteId };
+    if (options.displayLabel !== void 0) confirmBody.display_label = options.displayLabel;
+    const response = await this.post(
+      {
+        kind: ActionKinds.openLogin,
+        label: "Confirm login",
+        method: "POST",
+        endpoint: `/profiles/${encodeURIComponent(session.profileId)}/confirm`
+      },
+      confirmBody,
+      { requiredScopes: [QoniScopes.SITE_LOGIN_CONFIRM] }
+    );
+    const raw = isJsonObject(response) ? response : {};
+    const fields = camelizeRecord(raw);
+    const state = asString2(fields.state) ?? "";
+    return {
+      profileId: asString2(fields.profileId) ?? session.profileId,
+      active: state === "active",
+      state,
+      probeResult: asString2(fields.probeResult) ?? "",
+      raw
+    };
+  }
+  /** The save for `session`, started once; a failed attempt is forgotten so a retry saves again. */
+  #saveOnce(session, options) {
+    session.save ??= this.#confirmLogin(session, options).then(
+      (result) => {
+        if (SAVE_RETRY_PROBES.has(result.probeResult)) session.save = void 0;
+        return result;
+      },
+      (err) => {
+        if (!isNoPendingLogin(err)) session.save = void 0;
+        throw err;
+      }
+    );
+    return session.save;
+  }
+  /**
+   * Save the login, then let the agent recheck. A user who is not signed in
+   * yet still gets a recheck (the agent asks again), and so does 409
+   * `no_pending_login`. A save the backend could not complete (`release_failed`)
+   * throws a retryable error instead of telling the agent to go on.
+   */
+  async #saveThenRecheck(session, action) {
+    let result;
+    try {
+      result = await this.#saveOnce(session);
+    } catch (err) {
+      if (!isNoPendingLogin(err)) throw err;
+    }
+    if (result && SAVE_RETRY_PROBES.has(result.probeResult)) {
+      throw new QoniError(
+        `the login could not be saved yet (probeResult "${result.probeResult}"); the login browser is kept \u2014 call confirmSignedIn() again to retry`,
+        { code: "site_login.save_failed", retryable: true }
+      );
+    }
+    if (session.replaced) {
+      throw new QoniError(
+        "the login was reopened while it was being saved; call confirmSignedIn() again to save the newer login",
+        { code: "site_login.session_replaced", retryable: true }
+      );
+    }
+    await this.post(action, void 0);
+    session.completed = true;
+  }
+  #loginSlot() {
+    let slot = this.loginSessions.get(this.id);
+    if (!slot) {
+      slot = { calls: 0, inflight: 0 };
+      rememberBounded(this.loginSessions, this.id, slot, INTERACTION_MEMORY_LIMIT, loginSlotIdle);
+    }
+    return slot;
+  }
   /** Resolve the site for `openLogin`: explicit, or the only listed site. */
   #loginSiteId(requested) {
     const payload = this.interaction.payload;
@@ -896,6 +1167,10 @@ var RunHandle = class {
   /** Pass back to `run({ session })` to reuse the same backend session. */
   sessionRef;
   capture;
+  /** Login sessions opened on this run's interactions — see {@link interactionHandle}. */
+  #loginSessions = /* @__PURE__ */ new Map();
+  /** Latest card per interaction id, so lifecycle updates fold onto it. */
+  #interactions = /* @__PURE__ */ new Map();
   /** Refresh and return the run's current state. */
   async status() {
     const detail = await this.ops.getDetail();
@@ -909,8 +1184,14 @@ var RunHandle = class {
   async *events(opts = {}) {
     for await (const wire of this.ops.streamEvents(opts)) {
       await opts.onWireEvent?.(wire);
-      const event = normalizeRunEvent(wire, { topRunId: this.id });
+      let event = normalizeRunEvent(wire, { topRunId: this.id });
       if (!event) continue;
+      if (event.type === "interaction") {
+        const card = foldInteraction(this.#interactions.get(event.data.id), event.data);
+        rememberBounded(this.#interactions, card.id, card, INTERACTION_MEMORY_LIMIT, interactionSettled);
+        markLoginEnded(this.#loginSessions, card);
+        event = { ...event, data: card };
+      }
       if (event.type === "screenshot" && !this.capture.screenshots) continue;
       if (isVideoFrame(wire) && !this.capture.videoFrames) continue;
       yield event;
@@ -983,12 +1264,16 @@ var RunHandle = class {
    * Wrap an {@link Interaction} (from `event.data` of an `interaction` event)
    * in a typed {@link InteractionHandle} bound to this run. The handle's action
    * methods (`answer` / `confirmSignedIn` / `releaseControl` / …) post to the
-   * endpoint the backend declared for that action.
+   * endpoint the backend declared for that action. Handles this RunHandle
+   * hands out share the login sessions `openLogin()` opens, so
+   * `confirmSignedIn()` on the handle of a later event still saves that login.
+   * A RunHandle from another `attach()` (or process) does not see them.
    */
   interactionHandle(interaction) {
     return new InteractionHandle(
       interaction,
-      (action, body, options) => this.ops.postAction(action, body, options)
+      (action, body, options) => this.ops.postAction(action, body, options),
+      this.#loginSessions
     );
   }
   /**
@@ -1813,6 +2098,10 @@ var MonitorHandle = class {
   }
   ops;
   id;
+  /** Login sessions opened on this monitor's interactions — see {@link interactionHandle}. */
+  #loginSessions = /* @__PURE__ */ new Map();
+  /** Latest card per interaction id, so settling shells fold onto it. */
+  #interactions = /* @__PURE__ */ new Map();
   /** Refresh and return the monitor (normalized camelCase fields). */
   async get() {
     return normalizeMonitorRecord(await this.ops.get());
@@ -1857,7 +2146,13 @@ var MonitorHandle = class {
    */
   async *events(opts = {}) {
     for await (const wire of this.ops.streamEvents(opts)) {
-      const event = normalizeRunEvent(wire);
+      let event = normalizeRunEvent(wire);
+      if (event?.type === "interaction") {
+        const card = foldInteraction(this.#interactions.get(event.data.id), event.data);
+        rememberBounded(this.#interactions, card.id, card, INTERACTION_MEMORY_LIMIT, interactionSettled);
+        markLoginEnded(this.#loginSessions, card);
+        event = { ...event, data: card };
+      }
       if (event) yield event;
     }
   }
@@ -1865,12 +2160,14 @@ var MonitorHandle = class {
    * Wrap an {@link Interaction} (from `event.data` of an `interaction` event on
    * the monitor stream — e.g. a `site_login` to unlock a `needs_reauth` park)
    * in a typed {@link InteractionHandle}. The handle's action methods post to
-   * the endpoint the backend declared for that action.
+   * the endpoint the backend declared for that action. Handles of one
+   * MonitorHandle share the login sessions `openLogin()` opens.
    */
   interactionHandle(interaction) {
     return new InteractionHandle(
       interaction,
-      (action, body, options) => this.ops.postAction(action, body, options)
+      (action, body, options) => this.ops.postAction(action, body, options),
+      this.#loginSessions
     );
   }
   /**
@@ -3035,10 +3332,10 @@ function validateScopeFormat(scope) {
     );
   }
   if (KNOWN_SCOPES.includes(scope)) return;
-  const prefixed = KNOWN_SCOPES.find((known) => known.endsWith(`.${scope}`) || known === `webagent.${scope}`);
-  if (prefixed) {
+  const prefixed = KNOWN_SCOPES.filter((known) => known.endsWith(`.${scope}`));
+  if (prefixed.length > 0) {
     throw new QoniValidationError(
-      `delegateToken: scope "${scope}" is missing its service prefix \u2014 write "${prefixed}"`
+      `delegateToken: scope "${scope}" is missing its service prefix \u2014 write ` + prefixed.map((known) => `"${known}"`).join(" or ")
     );
   }
   if (!/^[a-z0-9_]+(\.[a-z0-9_]+)+:[a-z0-9_]+$/.test(scope)) {