@qoniai/qoni 0.6.0 → 0.8.0

package/dist/index.js

@@ -490,6 +490,87 @@ var ActionKinds = {
 };
 var ACTION_KIND_VALUES = Object.values(ActionKinds);
 
+// src/scopes.ts
+var QoniScopes = {
+  GUMEM_SESSION_CREATE: "gumem.session:create",
+  GUMEM_MESSAGE_WRITE: "gumem.message:write",
+  GUMEM_MEMORY_READ: "gumem.memory:read",
+  GUMEM_MEMORY_WRITE: "gumem.memory:write",
+  GUMEM_MEMORY_DELETE: "gumem.memory:delete",
+  GUMEM_SEARCH_RUN: "gumem.search:run",
+  GUMEM_ADMIN_MANAGE: "gumem.admin:manage",
+  GUMEM_RESOURCE_WRITE: "gumem.resource:write",
+  GUMEM_ACTION_WRITE: "gumem.action:write",
+  GUMEM_ACTION_READ: "gumem.action:read",
+  GUMEM_PROFILE_READ: "gumem.profile:read",
+  // WebAgent products: exactly two verbs per product — `read` (observe) and
+  // `manage` (anything that changes execution state). See
+  // wa/docs/qoni-sdk-public-surface.md §3.
+  DO_ANYTHING_READ: "webagent.do_anything:read",
+  DO_ANYTHING_MANAGE: "webagent.do_anything:manage",
+  WEB_SEARCH_READ: "webagent.web_search:read",
+  WEB_SEARCH_MANAGE: "webagent.web_search:manage",
+  DEEP_RESEARCH_READ: "webagent.deep_research:read",
+  DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage",
+  TRACK_READ: "webagent.track:read",
+  TRACK_MANAGE: "webagent.track:manage",
+  // Interactive site login (`InteractionHandle.openLogin()` on a `site_login`
+  // 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"
+};
+var QoniProductScopes = {
+  doAnything: [
+    QoniScopes.DO_ANYTHING_READ,
+    QoniScopes.DO_ANYTHING_MANAGE
+  ],
+  webSearch: [
+    QoniScopes.WEB_SEARCH_READ,
+    QoniScopes.WEB_SEARCH_MANAGE
+  ],
+  deepResearch: [
+    QoniScopes.DEEP_RESEARCH_READ,
+    QoniScopes.DEEP_RESEARCH_MANAGE
+  ],
+  track: [
+    QoniScopes.TRACK_READ,
+    QoniScopes.TRACK_MANAGE
+  ]
+};
+var KNOWN_SCOPES = Object.values(QoniScopes);
+var QoniScopeBundles = {
+  GUMEM_READONLY: [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_PROFILE_READ],
+  GUMEM_SESSION_RECALL: [
+    QoniScopes.GUMEM_MEMORY_READ,
+    QoniScopes.GUMEM_MEMORY_WRITE,
+    QoniScopes.GUMEM_MESSAGE_WRITE
+  ],
+  GUMEM_WRITE: [
+    QoniScopes.GUMEM_SESSION_CREATE,
+    QoniScopes.GUMEM_MESSAGE_WRITE,
+    QoniScopes.GUMEM_ACTION_WRITE
+  ],
+  // One bundle per WebAgent product = [read, manage].
+  DO_ANYTHING: [
+    QoniScopes.DO_ANYTHING_READ,
+    QoniScopes.DO_ANYTHING_MANAGE
+  ],
+  WEB_SEARCH: [
+    QoniScopes.WEB_SEARCH_READ,
+    QoniScopes.WEB_SEARCH_MANAGE
+  ],
+  DEEP_RESEARCH: [
+    QoniScopes.DEEP_RESEARCH_READ,
+    QoniScopes.DEEP_RESEARCH_MANAGE
+  ],
+  TRACK: [
+    QoniScopes.TRACK_READ,
+    QoniScopes.TRACK_MANAGE
+  ]
+};
+
 // src/interactions.ts
 function asString2(value) {
   return typeof value === "string" && value ? value : void 0;
@@ -588,6 +669,9 @@ function normalizeInteraction(payload) {
   if (evidence) interaction.evidence = evidence;
   return interaction;
 }
+function interactionActionScopes(action, productManageScope) {
+  return action.kind === ActionKinds.openLogin ? [QoniScopes.SITE_LOGIN_REQUEST] : [productManageScope];
+}
 var InteractionHandle = class {
   constructor(interaction, post) {
     this.post = post;
@@ -612,48 +696,122 @@ var InteractionHandle = class {
     return this.interaction.actions.some((a) => a.kind === kind);
   }
   /** Answer a clarification ask. */
-  answer(text) {
-    return this.invoke(ActionKinds.answer, { response: text });
+  async answer(text) {
+    await this.invoke(ActionKinds.answer, { response: text });
   }
   /** Skip / dismiss the interaction (proceed without acting on it). */
-  skip() {
-    return this.invoke(ActionKinds.skip);
+  async skip() {
+    await this.invoke(ActionKinds.skip);
   }
   /** Confirm a pending confirmation (approve the plan / destructive op). */
-  confirm() {
-    return this.invoke(ActionKinds.confirm);
+  async confirm() {
+    await this.invoke(ActionKinds.confirm);
   }
   /** Reject a pending confirmation. */
-  reject() {
-    return this.invoke(ActionKinds.reject);
+  async reject() {
+    await this.invoke(ActionKinds.reject);
   }
-  /** Open the login surface for a site_login interaction. */
-  openLogin() {
-    return this.invoke(ActionKinds.openLogin);
+  /**
+   * 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}.
+   * The delegation must include `QoniScopes.SITE_LOGIN_REQUEST` and
+   * `QoniScopes.SITE_LOGIN_CONFIRM`; the AccessKey policy must allow both.
+   */
+  async openLogin(options = {}) {
+    this.#declaredAction(ActionKinds.openLogin);
+    const body = { site_id: this.#loginSiteId(options.siteId) };
+    if (options.profileId !== void 0) {
+      if (typeof options.profileId !== "string" || !options.profileId) {
+        throw new QoniValidationError("openLogin profileId must be a non-empty string");
+      }
+      body.profile_id = options.profileId;
+    }
+    const response = await this.invoke(ActionKinds.openLogin, body);
+    const raw = isJsonObject(response) ? response : {};
+    const fields = camelizeRecord(raw);
+    const profileId = asString2(fields.profileId) ?? "";
+    const siteId = asString2(fields.siteId) ?? String(body.site_id);
+    return {
+      profileId,
+      siteId,
+      sessionId: asString2(fields.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
+        };
+      }
+    };
   }
   /** Tell the agent the user has finished signing in. */
-  confirmSignedIn() {
-    return this.invoke(ActionKinds.confirmSignedIn);
+  async confirmSignedIn() {
+    await this.invoke(ActionKinds.confirmSignedIn);
   }
   /** Connect to the live browser for a take_control interaction. */
-  connectControl() {
-    return this.invoke(ActionKinds.connectControl);
+  async connectControl() {
+    await this.invoke(ActionKinds.connectControl);
   }
   /** Refresh the live control surface / live url. */
-  refreshControl() {
-    return this.invoke(ActionKinds.refreshControl);
+  async refreshControl() {
+    await this.invoke(ActionKinds.refreshControl);
   }
   /** Hand control back to the agent. */
-  releaseControl() {
-    return this.invoke(ActionKinds.releaseControl);
+  async releaseControl() {
+    await this.invoke(ActionKinds.releaseControl);
   }
   /** Retry a wait interaction now. */
-  retry() {
-    return this.invoke(ActionKinds.retry);
+  async retry() {
+    await this.invoke(ActionKinds.retry);
   }
   /** Switch the profile a wait/login interaction is bound to. */
-  switchProfile() {
-    return this.invoke(ActionKinds.switchProfile);
+  async switchProfile() {
+    await this.invoke(ActionKinds.switchProfile);
+  }
+  /** Resolve the site for `openLogin`: explicit, or the only listed site. */
+  #loginSiteId(requested) {
+    const payload = this.interaction.payload;
+    const listed = Array.isArray(payload?.sites) ? payload.sites.map((site) => site.siteId).filter((id) => typeof id === "string" && id.length > 0) : [];
+    if (requested !== void 0) {
+      if (typeof requested !== "string" || !requested) {
+        throw new QoniValidationError("openLogin siteId must be a non-empty string");
+      }
+      if (listed.length > 0 && !listed.includes(requested)) {
+        throw new QoniValidationError(
+          `openLogin siteId "${requested}" is not one of the sites this interaction asks for: ${listed.join(", ")}`
+        );
+      }
+      return requested;
+    }
+    if (listed.length === 1) return listed[0];
+    throw new QoniValidationError(
+      listed.length === 0 ? "openLogin needs a siteId: this interaction does not list the site to sign in to" : `openLogin needs a siteId: choose one of ${listed.join(", ")}`
+    );
   }
   /**
    * Invoke an action by kind with an optional body. `async` so a missing-action
@@ -661,6 +819,10 @@ var InteractionHandle = class {
    * method contract uniformly promise-based.
    */
   async invoke(kind, body) {
+    return this.post(this.#declaredAction(kind), body);
+  }
+  /** The declared action of `kind`; throws when the backend did not offer it. */
+  #declaredAction(kind) {
     const action = this.interaction.actions.find((a) => a.kind === kind);
     if (!action) {
       const offered = this.interaction.actions.map((a) => a.kind).join(", ") || "none";
@@ -668,7 +830,7 @@ var InteractionHandle = class {
         `interaction "${this.interaction.id}" (${this.interaction.type}) does not offer the "${kind}" action \u2014 the backend declared: ${offered}. Only call methods whose action the interaction currently offers.`
       );
     }
-    await this.post(action, body);
+    return action;
   }
 };
 
@@ -738,7 +900,7 @@ var RunHandle = class {
             break settled;
           }
         }
-        const detail2 = await waitWithSignal(() => this.ops.getDetail(signal), signal);
+        const detail2 = await settleRead(() => this.ops.getDetail(signal), signal);
         if (isTerminalRunStatus(normalizeRunStatus(this.id, detail2).status)) {
           terminalDetail = detail2;
           break;
@@ -752,10 +914,10 @@ var RunHandle = class {
         sawCleanClose = true;
         eventIdAtLastClose = lastEventId;
       }
-      const detail = terminalDetail ?? await waitWithSignal(() => this.ops.getDetail(signal), signal);
+      const detail = terminalDetail ?? await settleRead(() => this.ops.getDetail(signal), signal);
       this.#adoptSessionRef(detail);
       const result = settleRunResult(this.id, detail, [], terminalDoneReason);
-      result.artifacts = this.ops.listArtifacts ? await waitWithSignal(() => this.ops.listArtifacts(signal), signal) : [];
+      result.artifacts = this.ops.listArtifacts ? await settleRead(() => this.ops.listArtifacts(signal), signal) : [];
       return result;
     } catch (err) {
       if (timedOut() && !opts.signal?.aborted) {
@@ -778,7 +940,7 @@ var RunHandle = class {
   interactionHandle(interaction) {
     return new InteractionHandle(
       interaction,
-      (action, body) => this.ops.postAction(action, body)
+      (action, body, options) => this.ops.postAction(action, body, options)
     );
   }
   /**
@@ -872,6 +1034,35 @@ function withTimeout(signal, timeoutMs) {
   }
   return { signal: controller.signal, timedOut: () => fired, dispose };
 }
+var SETTLE_READ_BACKOFF_MS = [250, 1e3];
+async function settleRead(read, signal) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await waitWithSignal(read, signal);
+    } catch (err) {
+      const delay = SETTLE_READ_BACKOFF_MS[attempt];
+      if (delay === void 0 || signal?.aborted || !(err instanceof QoniError) || !err.retryable) throw err;
+      await sleepWithSignal(delay, signal);
+    }
+  }
+}
+function sleepWithSignal(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function waitWithSignal(operation, signal) {
   if (!signal) return Promise.resolve().then(operation);
   return new Promise((resolve, reject) => {
@@ -969,17 +1160,15 @@ function createDeepResearchNamespace(transport) {
         signal: opts.signal,
         onReconnect: opts.onReconnect
       }),
-      postAction: async (action, body) => {
-        await transport.webAgentJson(
-          action.method || "POST",
-          action.endpoint,
-          token,
-          {
-            ...body !== void 0 ? { body } : {},
-            requiredScopes: ["webagent.deep_research:manage"]
-          }
-        );
-      },
+      postAction: async (action, body, options) => (await transport.webAgentJson(
+        action.method || "POST",
+        action.endpoint,
+        token,
+        {
+          ...body !== void 0 ? { body } : {},
+          requiredScopes: options?.requiredScopes ?? interactionActionScopes(action, "webagent.deep_research:manage")
+        }
+      )).data,
       cancel: async () => asRecord((await api.cancel({ token, runId })).data),
       listArtifacts: async (signal) => {
         const res = await api.listArtifacts({ token, runId, signal });
@@ -1244,17 +1433,15 @@ function createDoAnythingNamespace(transport) {
         // Skip screenshot rows in backfill when the caller did not opt in.
         includeScreenshots: capture?.screenshots ? void 0 : false
       }),
-      postAction: async (action, body) => {
-        await transport.webAgentJson(
-          action.method || "POST",
-          action.endpoint,
-          token,
-          {
-            ...body !== void 0 ? { body } : {},
-            requiredScopes: ["webagent.do_anything:manage"]
-          }
-        );
-      },
+      postAction: async (action, body, options) => (await transport.webAgentJson(
+        action.method || "POST",
+        action.endpoint,
+        token,
+        {
+          ...body !== void 0 ? { body } : {},
+          requiredScopes: options?.requiredScopes ?? interactionActionScopes(action, "webagent.do_anything:manage")
+        }
+      )).data,
       cancel: async (reason) => asRecord2(
         (await api.cancel({
           token,
@@ -1375,84 +1562,16 @@ function createQoniNamespace(_transport, delegateToken, completeDelegateToken) {
   };
 }
 
-// src/scopes.ts
-var QoniScopes = {
-  GUMEM_SESSION_CREATE: "gumem.session:create",
-  GUMEM_MESSAGE_WRITE: "gumem.message:write",
-  GUMEM_MEMORY_READ: "gumem.memory:read",
-  GUMEM_MEMORY_WRITE: "gumem.memory:write",
-  GUMEM_MEMORY_DELETE: "gumem.memory:delete",
-  GUMEM_SEARCH_RUN: "gumem.search:run",
-  GUMEM_ADMIN_MANAGE: "gumem.admin:manage",
-  GUMEM_RESOURCE_WRITE: "gumem.resource:write",
-  GUMEM_ACTION_WRITE: "gumem.action:write",
-  GUMEM_ACTION_READ: "gumem.action:read",
-  GUMEM_PROFILE_READ: "gumem.profile:read",
-  // WebAgent products: exactly two verbs per product — `read` (observe) and
-  // `manage` (anything that changes execution state). See
-  // wa/docs/qoni-sdk-public-surface.md §3.
-  DO_ANYTHING_READ: "webagent.do_anything:read",
-  DO_ANYTHING_MANAGE: "webagent.do_anything:manage",
-  WEB_SEARCH_READ: "webagent.web_search:read",
-  WEB_SEARCH_MANAGE: "webagent.web_search:manage",
-  DEEP_RESEARCH_READ: "webagent.deep_research:read",
-  DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage",
-  TRACK_READ: "webagent.track:read",
-  TRACK_MANAGE: "webagent.track:manage"
-};
-var QoniProductScopes = {
-  doAnything: [
-    QoniScopes.DO_ANYTHING_READ,
-    QoniScopes.DO_ANYTHING_MANAGE
-  ],
-  webSearch: [
-    QoniScopes.WEB_SEARCH_READ,
-    QoniScopes.WEB_SEARCH_MANAGE
-  ],
-  deepResearch: [
-    QoniScopes.DEEP_RESEARCH_READ,
-    QoniScopes.DEEP_RESEARCH_MANAGE
-  ],
-  track: [
-    QoniScopes.TRACK_READ,
-    QoniScopes.TRACK_MANAGE
-  ]
-};
-var KNOWN_SCOPES = Object.values(QoniScopes);
-var QoniScopeBundles = {
-  GUMEM_READONLY: [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_PROFILE_READ],
-  GUMEM_SESSION_RECALL: [
-    QoniScopes.GUMEM_MEMORY_READ,
-    QoniScopes.GUMEM_MEMORY_WRITE,
-    QoniScopes.GUMEM_MESSAGE_WRITE
-  ],
-  GUMEM_WRITE: [
-    QoniScopes.GUMEM_SESSION_CREATE,
-    QoniScopes.GUMEM_MESSAGE_WRITE,
-    QoniScopes.GUMEM_ACTION_WRITE
-  ],
-  // One bundle per WebAgent product = [read, manage].
-  DO_ANYTHING: [
-    QoniScopes.DO_ANYTHING_READ,
-    QoniScopes.DO_ANYTHING_MANAGE
-  ],
-  WEB_SEARCH: [
-    QoniScopes.WEB_SEARCH_READ,
-    QoniScopes.WEB_SEARCH_MANAGE
-  ],
-  DEEP_RESEARCH: [
-    QoniScopes.DEEP_RESEARCH_READ,
-    QoniScopes.DEEP_RESEARCH_MANAGE
-  ],
-  TRACK: [
-    QoniScopes.TRACK_READ,
-    QoniScopes.TRACK_MANAGE
-  ]
-};
-
 // src/genauth.ts
 function createGenAuthNamespace(transport, options = {}) {
+  async function delegateAgent(input) {
+    if (!options.delegateTokenFor) {
+      throw new QoniValidationError("GenAuth delegateAgent requires a Qoni delegation provider");
+    }
+    return (await options.delegateTokenFor(input)).data;
+  }
   return {
+    delegateAgent,
     userInfo: (input) => transport.genauthJson("GET", "/oidc/me", input.accessToken),
     jwks: () => transport.genauthJson("GET", "/oidc/.well-known/jwks.json"),
     discovery: () => transport.genauthJson("GET", "/oidc/.well-known/openid-configuration"),
@@ -1648,7 +1767,7 @@ var MonitorHandle = class {
   id;
   /** Refresh and return the monitor (normalized camelCase fields). */
   async get() {
-    return camelizeRecord(await this.ops.get());
+    return normalizeMonitorRecord(await this.ops.get());
   }
   /**
    * Pause the monitor — stops scheduled ticks until {@link resume}. The
@@ -1656,11 +1775,11 @@ var MonitorHandle = class {
    * deleting.
    */
   async pause() {
-    return camelizeRecord(await this.ops.update({ action: "pause" }));
+    return normalizeMonitorRecord(await this.ops.update({ action: "pause" }));
   }
   /** Resume a paused monitor. */
   async resume() {
-    return camelizeRecord(await this.ops.update({ action: "resume" }));
+    return normalizeMonitorRecord(await this.ops.update({ action: "resume" }));
   }
   /**
    * Change the monitor definition. Pass any subset of fields (at least one);
@@ -1678,11 +1797,11 @@ var MonitorHandle = class {
         "track refine requires at least one field to change (schedule / targetUrls / extractionSchema / triggerDsl / stopConditionDsl / notifyChannel)"
       );
     }
-    return camelizeRecord(await this.ops.update({ action: "refine", patch: body }));
+    return normalizeMonitorRecord(await this.ops.update({ action: "refine", patch: body }));
   }
   /** Trigger an immediate tick outside the schedule. */
   async runNow() {
-    return camelizeRecord(await this.ops.runNow());
+    return normalizeMonitorRecord(await this.ops.runNow());
   }
   /**
    * Stream semantic monitor events. Monitors are resident, so the stream has
@@ -1703,7 +1822,7 @@ var MonitorHandle = class {
   interactionHandle(interaction) {
     return new InteractionHandle(
       interaction,
-      (action, body) => this.ops.postAction(action, body)
+      (action, body, options) => this.ops.postAction(action, body, options)
     );
   }
   /**
@@ -1808,17 +1927,15 @@ function createTrackNamespace(transport) {
       update: async (input) => asRecord3((await api.updateMonitor({ token, monitorId, ...input })).data),
       runNow: async () => asRecord3((await api.runNow({ token, monitorId })).data),
       streamEvents: (opts) => api.events({ token, monitorId, lastEventId: opts.lastEventId, signal: opts.signal }),
-      postAction: async (action, body) => {
-        await transport.webAgentJson(
-          action.method || "POST",
-          action.endpoint,
-          token,
-          {
-            ...body !== void 0 ? { body } : {},
-            requiredScopes: ["webagent.track:manage"]
-          }
-        );
-      },
+      postAction: async (action, body, options) => (await transport.webAgentJson(
+        action.method || "POST",
+        action.endpoint,
+        token,
+        {
+          ...body !== void 0 ? { body } : {},
+          requiredScopes: options?.requiredScopes ?? interactionActionScopes(action, "webagent.track:manage")
+        }
+      )).data,
       listRuns: async (opts) => asRecord3((await api.listRuns({ token, monitorId, ...opts })).data),
       getRun: async (runId) => asRecord3((await api.getRun({ token, monitorId, runId })).data),
       delete: async () => {
@@ -1833,10 +1950,12 @@ function createTrackNamespace(transport) {
       if (!prompt || typeof prompt !== "string") {
         throw new QoniValidationError("track.create requires a prompt string");
       }
+      const body = snakeifyKeys(rest);
+      if (body.schedule !== void 0) body.schedule = normalizeSchedule(body.schedule);
       const created = await api.createMonitor({
         token,
         intent: prompt,
-        ...snakeifyKeys(rest)
+        ...body
       });
       const monitorId = created.data.id || created.data.monitor_id;
       if (!monitorId) {
@@ -1854,7 +1973,7 @@ function createTrackNamespace(transport) {
   };
 }
 function normalizeMonitorRun(item) {
-  const normalized = camelizeRecord(item);
+  const normalized = normalizeMonitorRecord(item);
   if (typeof normalized.id !== "string" || !normalized.id) {
     const id = normalized.runId ?? normalized.snapshotId;
     if (typeof id === "string" && id) normalized.id = id;
@@ -1864,11 +1983,44 @@ function normalizeMonitorRun(item) {
 function normalizeTrackInterveneInput(input) {
   return renameKeys4(input, { requestId: "request_id" });
 }
+var USER_KEYED_FIELDS = /* @__PURE__ */ new Set(["extraction_schema", "baseline_extracted", "extracted"]);
+var USER_KEYED_DIFF_FIELDS = /* @__PURE__ */ new Set(["before", "after", "added", "removed", "sample_unchanged"]);
+function normalizeMonitorRecord(value) {
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (USER_KEYED_FIELDS.has(key)) out[camelKey2(key)] = item;
+    else if (key === "diffs" && Array.isArray(item)) out.diffs = item.map(normalizeDiff);
+    else out[camelKey2(key)] = camelizeKeys(item);
+  }
+  return out;
+}
+function normalizeDiff(entry) {
+  if (!isJsonObject(entry)) return camelizeKeys(entry);
+  const out = {};
+  for (const [key, item] of Object.entries(entry)) {
+    out[camelKey2(key)] = USER_KEYED_DIFF_FIELDS.has(key) ? item : camelizeKeys(item);
+  }
+  return out;
+}
+function camelKey2(key) {
+  return key.replace(/_([a-z0-9])/g, (_, ch) => ch.toUpperCase());
+}
 function normalizeSchedule(schedule) {
+  if (!isJsonObject(schedule)) return schedule;
   if (schedule.kind === "interval") {
-    return { kind: "interval", interval_seconds: schedule.intervalSeconds };
+    const { intervalSeconds, interval_seconds, ...rest } = schedule;
+    const seconds = intervalSeconds ?? interval_seconds;
+    if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0) {
+      throw new QoniValidationError(
+        'track interval schedule needs a positive number: { kind: "interval", intervalSeconds }'
+      );
+    }
+    return { ...rest, interval_seconds: seconds };
   }
-  return { kind: "cron", expr: schedule.expr };
+  if (schedule.kind === "cron" && (typeof schedule.expr !== "string" || !schedule.expr.trim())) {
+    throw new QoniValidationError('track cron schedule needs an expression: { kind: "cron", expr }');
+  }
+  return schedule;
 }
 function snakeifyKeys(value) {
   const out = {};
@@ -2055,7 +2207,8 @@ var Qoni = class {
       webAgentSSE: (...args) => this.webAgentSSE(...args)
     };
     this.genauth = createGenAuthNamespace(transport, {
-      adminTokenFor: () => this.genauthAdminTokenFor()
+      adminTokenFor: () => this.genauthAdminTokenFor(),
+      delegateTokenFor: (input) => this.delegateToken(input)
     });
     this.qoni = createQoniNamespace(
       transport,
@@ -2768,19 +2921,43 @@ function toRecord(value) {
 }
 function normalizeDelegateTokenInput(input) {
   const body = toRecord(input);
+  if (input.deniedScopes !== void 0) {
+    throw new QoniValidationError(
+      "delegateToken: deniedScopes is not supported by the delegation service. Do not rely on this field to prevent mailbox or browser actions."
+    );
+  }
+  if (input.agent !== void 0 && input.agentKey !== void 0 && input.agent !== input.agentKey) {
+    throw new QoniValidationError("delegateToken: agent and agentKey must identify the same Agent");
+  }
   if (!body.userId && isJsonObject(input.user) && typeof input.user.id === "string") {
     body.userId = input.user.id;
   }
   if (input.mode !== "interactive" && !body.userId) {
     throw new QoniValidationError(
-      'delegateToken: silent mode requires a user \u2014 pass `user: { id: <genauthUserId> }` (or the deprecated top-level `userId`). Interactive mode (`mode: "interactive"`) does not need one.'
+      'delegateToken: silent mode requires a user \u2014 pass `user: { id: <genauthUserId> }` (or the top-level `userId`). Interactive mode (`mode: "interactive"`) does not need one.'
     );
   }
-  body.agent = input.agent ?? "sdk";
+  body.agent = input.agent ?? input.agentKey ?? "sdk";
+  delete body.agentKey;
+  if (input.expiresIn !== void 0) body.expiresIn = delegationDurationSeconds(input.expiresIn);
   body.scopes = resolveDelegationScopes(input.scopes, input.products);
   delete body.products;
   return body;
 }
+function delegationDurationSeconds(value) {
+  let seconds = value;
+  if (typeof value === "string") {
+    const duration = /^(\d+)(s|m|h|d)?$/.exec(value);
+    const units = { s: 1, m: 60, h: 3600, d: 86400 };
+    seconds = duration ? Number(duration[1]) * units[duration[2] ?? "s"] : NaN;
+  }
+  if (typeof seconds !== "number" || !Number.isInteger(seconds) || seconds < 60 || seconds > 86400) {
+    throw new QoniValidationError(
+      'delegateToken: expiresIn must be 60\u201386400 integer seconds or a whole-number duration such as "15m"'
+    );
+  }
+  return seconds;
+}
 function resolveDelegationScopes(scopes, products) {
   const resolved = /* @__PURE__ */ new Set();
   for (const product of products ?? []) {
@@ -2804,6 +2981,11 @@ function resolveDelegationScopes(scopes, products) {
   return [...resolved];
 }
 function validateScopeFormat(scope) {
+  if (scope.startsWith("mailbox.") || scope === "web.search" || scope === "web.extract") {
+    throw new QoniValidationError(
+      `delegateToken: legacy action scope "${scope}" has no enforced mapping in this delegation service. It will not be expanded into broader product permissions.`
+    );
+  }
   if (KNOWN_SCOPES.includes(scope)) return;
   const prefixed = KNOWN_SCOPES.find((known) => known.endsWith(`.${scope}`) || known === `webagent.${scope}`);
   if (prefixed) {