@qoniai/qoni 0.5.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -363,7 +363,70 @@ interface Interaction<T extends InteractionType = InteractionType> {
363
363
  * supplies this (token + run addressing already bound); the handle below uses
364
364
  * it to invoke `action.endpoint` without the consumer touching HTTP.
365
365
  */
366
- type InteractionActionPoster = (action: Action, body: JsonObject | undefined) => Promise<void>;
366
+ type InteractionActionPoster = (action: Action, body: JsonObject | undefined, options?: {
367
+ requiredScopes?: readonly string[];
368
+ }) => Promise<unknown>;
369
+ /** Options for {@link InteractionHandle.openLogin}. */
370
+ interface OpenLoginOptions {
371
+ /**
372
+ * Site to sign in to — one of `interaction.payload.sites[].siteId`. May be
373
+ * omitted when the interaction lists exactly one site.
374
+ */
375
+ siteId?: string;
376
+ /** Re-login an existing browser profile in place instead of creating one. */
377
+ profileId?: string;
378
+ }
379
+ /** Interactive login session started by {@link InteractionHandle.openLogin}. */
380
+ interface OpenLoginResult {
381
+ profileId: string;
382
+ siteId: string;
383
+ /** Login browser session the user signs in through. */
384
+ sessionId: string;
385
+ /** Live view URL of the login browser to show to the user. */
386
+ liveUrl: string;
387
+ /** Unmodified response body (escape hatch — shape may evolve with the API). */
388
+ raw: JsonObject;
389
+ /**
390
+ * Persist the login into the profile after the user signs in
391
+ * (`POST /profiles/{profileId}/confirm`). Confirming ends this login
392
+ * session and closes its browser, whatever the outcome:
393
+ *
394
+ * - `active: true` — the login is saved; call
395
+ * {@link InteractionHandle.confirmSignedIn}.
396
+ * - `active: false` with `probeResult: "no_session"` — the backend no longer
397
+ * holds the session (it may already have saved the login automatically, or
398
+ * restarted). Call `confirmSignedIn()`: the agent rechecks the site and
399
+ * raises a new `site_login` interaction if it is still signed out.
400
+ * - Rejects with a `QoniError` whose `code` is `no_pending_login` (HTTP 409)
401
+ * when the backend has no pending login for this profile: the session
402
+ * already ended on providers that report it this way, or the profile no
403
+ * longer exists for this user. Handle it like `no_session`: call
404
+ * `confirmSignedIn()`, and the agent asks again if it is still signed out.
405
+ * - `active: false` with any other `probeResult` — the user was not signed
406
+ * in. Start a new session with `openLogin({ siteId, profileId })` and show
407
+ * its new `liveUrl`; the old one no longer works.
408
+ *
409
+ * Requires `QoniScopes.SITE_LOGIN_CONFIRM`.
410
+ */
411
+ confirm(options?: ConfirmLoginOptions): Promise<ConfirmLoginResult>;
412
+ }
413
+ /** Options for {@link OpenLoginResult.confirm}. */
414
+ interface ConfirmLoginOptions {
415
+ /** Optional human-readable label stored on the profile. */
416
+ displayLabel?: string;
417
+ }
418
+ /** Result of {@link OpenLoginResult.confirm}. */
419
+ interface ConfirmLoginResult {
420
+ profileId: string;
421
+ /** True only when the profile is now `active` (the login was captured). */
422
+ active: boolean;
423
+ /** Profile state after confirmation: `active`, or `pending_login` when no signed-in session was detected. */
424
+ state: string;
425
+ /** Outcome of the backend's signed-in probe, for example `no_session`. */
426
+ probeResult: string;
427
+ /** Unmodified response body (escape hatch — shape may evolve with the API). */
428
+ raw: JsonObject;
429
+ }
367
430
  /**
368
431
  * Typed wrapper over an {@link Interaction} that exposes one method per
369
432
  * action kind. Each method finds the matching declared action and posts to its
@@ -372,6 +435,7 @@ type InteractionActionPoster = (action: Action, body: JsonObject | undefined) =>
372
435
  * backend offered it).
373
436
  */
374
437
  declare class InteractionHandle<T extends InteractionType = InteractionType> {
438
+ #private;
375
439
  private readonly post;
376
440
  readonly interaction: Interaction<T>;
377
441
  constructor(interaction: Interaction<T>, post: InteractionActionPoster);
@@ -389,8 +453,16 @@ declare class InteractionHandle<T extends InteractionType = InteractionType> {
389
453
  confirm(): Promise<void>;
390
454
  /** Reject a pending confirmation. */
391
455
  reject(): Promise<void>;
392
- /** Open the login surface for a site_login interaction. */
393
- openLogin(): Promise<void>;
456
+ /**
457
+ * Start an interactive login session for a `site_login` interaction. The
458
+ * backend needs the site to sign in to: pass `siteId`, or omit it when the
459
+ * interaction lists exactly one site. Show `liveUrl` to the user; when they
460
+ * finish, call `confirm()` on the result to save the login, and act on its
461
+ * outcome (see {@link OpenLoginResult.confirm}) before {@link confirmSignedIn}.
462
+ * The delegation must include `QoniScopes.SITE_LOGIN_REQUEST` and
463
+ * `QoniScopes.SITE_LOGIN_CONFIRM`; the AccessKey policy must allow both.
464
+ */
465
+ openLogin(options?: OpenLoginOptions): Promise<OpenLoginResult>;
394
466
  /** Tell the agent the user has finished signing in. */
395
467
  confirmSignedIn(): Promise<void>;
396
468
  /** Connect to the live browser for a take_control interaction. */
@@ -445,6 +517,8 @@ declare const QoniEventTypes: {
445
517
  readonly Interaction: "interaction";
446
518
  /** A live screenshot frame (opt in with `capture: { screenshots: true }`); image on `event.image`. */
447
519
  readonly Screenshot: "screenshot";
520
+ /** The browser viewer moved to a new page or needs a fresh attachment. Use `event.data.liveUrl` for the live preview. */
521
+ readonly BrowserLiveUrlChanged: "browserLiveUrlChanged";
448
522
  /** Terminal — the run finished; outcome + output in `event.data` (cost is on the `RunResult`). */
449
523
  readonly Done: "done";
450
524
  /** Web Search results are ready; `event.data` is the count (the list is in `done.output`). */
@@ -487,6 +561,13 @@ interface RunScreenshotData {
487
561
  pageUrl?: string;
488
562
  step?: number;
489
563
  }
564
+ /** `browserLiveUrlChanged` — the provider's live viewer URL can rotate as tabs change. */
565
+ interface RunBrowserLiveUrlChangedData {
566
+ liveUrl: string;
567
+ supportsLivePump: boolean;
568
+ forceViewerReload: boolean;
569
+ providerSessionId?: string;
570
+ }
490
571
  /** `done` — terminal outcome + final output. (Total cost is on the `RunResult`.) */
491
572
  interface RunDoneData {
492
573
  output?: unknown;
@@ -510,6 +591,10 @@ type RunEvent = (RunEventBase & {
510
591
  data: RunScreenshotData;
511
592
  image: RunImage;
512
593
  isTerminal: false;
594
+ }) | (RunEventBase & {
595
+ type: "browserLiveUrlChanged";
596
+ data: RunBrowserLiveUrlChangedData;
597
+ isTerminal: false;
513
598
  }) | (RunEventBase & {
514
599
  type: "done";
515
600
  data: RunDoneData;
@@ -541,7 +626,7 @@ type RunEvent = (RunEventBase & {
541
626
  });
542
627
  /** Events any product run can emit. */
543
628
  type CoreRunEvent = Extract<RunEvent, {
544
- type: "progress" | "message" | "interaction" | "screenshot" | "done";
629
+ type: "progress" | "message" | "interaction" | "screenshot" | "browserLiveUrlChanged" | "done";
545
630
  }>;
546
631
  /** Do Anything — core events only. */
547
632
  type DoAnythingEvent = CoreRunEvent;
@@ -650,7 +735,9 @@ interface RunWireOps {
650
735
  * Interaction model's `actions[]` carry the endpoint + method, so the SDK
651
736
  * never hard-codes a HITL route — it forwards what the backend declared.
652
737
  */
653
- postAction(action: Action, body: JsonObject | undefined): Promise<void>;
738
+ postAction(action: Action, body: JsonObject | undefined, options?: {
739
+ requiredScopes?: readonly string[];
740
+ }): Promise<unknown>;
654
741
  cancel(reason?: string): Promise<JsonObject>;
655
742
  /** Products without artifacts leave this undefined → `result.artifacts` is []. */
656
743
  listArtifacts?(signal?: AbortSignal): Promise<Artifact[]>;
@@ -1077,10 +1164,12 @@ interface MonitorRunsOptions {
1077
1164
  /** A monitor's check cadence. */
1078
1165
  type MonitorSchedule = {
1079
1166
  kind: "cron";
1080
- expr: string;
1167
+ expr: string; /** IANA time zone for the cron expression. */
1168
+ tz?: string;
1081
1169
  } | {
1082
1170
  kind: "interval";
1083
1171
  intervalSeconds: number;
1172
+ tz?: string;
1084
1173
  };
1085
1174
  /**
1086
1175
  * Fields to change on a monitor via {@link MonitorHandle.refine}. Pass any
@@ -1102,7 +1191,9 @@ interface MonitorWireOps {
1102
1191
  update(input: JsonObject): Promise<JsonObject>;
1103
1192
  runNow(): Promise<JsonObject>;
1104
1193
  streamEvents(opts: MonitorEventsOptions): AsyncIterable<QoniEvent<unknown>>;
1105
- postAction(action: Action, body: JsonObject | undefined): Promise<void>;
1194
+ postAction(action: Action, body: JsonObject | undefined, options?: {
1195
+ requiredScopes?: readonly string[];
1196
+ }): Promise<unknown>;
1106
1197
  listRuns(opts: MonitorRunsOptions): Promise<JsonObject>;
1107
1198
  getRun(runId: string): Promise<JsonObject>;
1108
1199
  delete(): Promise<void>;
@@ -1375,6 +1466,8 @@ declare const QoniScopes: {
1375
1466
  readonly DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage";
1376
1467
  readonly TRACK_READ: "webagent.track:read";
1377
1468
  readonly TRACK_MANAGE: "webagent.track:manage";
1469
+ readonly SITE_LOGIN_REQUEST: "webagent.site_login:request";
1470
+ readonly SITE_LOGIN_CONFIRM: "webagent.site_login:confirm";
1378
1471
  };
1379
1472
  type QoniScope = (typeof QoniScopes)[keyof typeof QoniScopes];
1380
1473
  /** Product names accepted by `delegateToken({ products })`. */
@@ -1394,4 +1487,4 @@ declare const QoniScopeBundles: {
1394
1487
  readonly TRACK: readonly ["webagent.track:read", "webagent.track:manage"];
1395
1488
  };
1396
1489
 
1397
- export { type Action, type ActionKind, ActionKinds, type Artifact, type BrowserProxyOptions, type BrowserbaseRegion, type CaptureOptions, type ClarificationPayload, type CompleteDelegateAgentInput, type CompleteDelegateTokenInput, type ConfirmationPayload, type CoreRunEvent, type DeepResearchAttachOptions, type DeepResearchEvent, type DeepResearchRunOptions, type DelegateAgentInput, type DelegateAgentResponse, type DelegateAgentTokenResponse, type DelegateTokenInput, type DelegateTokenInteractiveInput, type DelegateTokenResponse, type DelegateTokenResult, type DelegateTokenSilentInput, type DelegateTokenSilentResponse, type DelegationMode, type DelegationTokenResponse, type DoAnythingAttachOptions, type DoAnythingEvent, type DoAnythingRunOptions, type DoAnythingSnapshot, type GenAuthAccessTokenInput, type GenAuthAdminToken, type GenAuthAdminTokenOverrideInput, type GenAuthDelegationIntrospectionInput, type GenAuthUserCreateBatchInput, type GenAuthUserCreateInput, type GenAuthUserDeleteBatchInput, type GenAuthUserGetBatchInput, type GenAuthUserGetInput, type GenAuthUserListInput, type GenAuthUserUpdateInput, type Interaction, type InteractionEvidence, InteractionHandle, type InteractionPayloadByType, type InteractionSite, type InteractionStatus, InteractionStatuses, type InteractionType, InteractionTypes, type InteractiveDelegationResponse, type JsonObject, type MonitorEvent, type MonitorEventsOptions, MonitorHandle, type MonitorRunsOptions, Qoni, QoniAuthError, QoniDelegationRequiredError, QoniError, type QoniErrorCode, type QoniErrorOptions, type QoniEvent, type QoniEventType, QoniEventTypes, type QoniMeta, type QoniOptions, QoniPermissionDeniedError, type QoniProduct, type QoniProductName, QoniProductScopes, QoniRateLimitError, type QoniResponse, type QoniRuntimeConfig, type QoniSSEEvent, QoniScopeBundles, QoniScopes, QoniTimeoutError, QoniTokenExpiredError, QoniUpstreamError, QoniValidationError, type RawRequestInput, type RunDoneData, type RunEvent, type RunEventsOptions, RunHandle, type RunImage, type RunLimits, type RunMessageData, type RunReconnectInfo, type RunResult, type RunScreenshotData, type RunStatus, type RunWaitOptions, type RuntimeTokenInput, type SessionRef, type SiteLoginPayload, type SnapshotAction, type SnapshotImage, type TakeControlPayload, type TokenInput, type TrackAttachOptions, type TrackCreateOptions, type WaitKind, type WaitPayload, type WebSearchAttachOptions, type WebSearchEvent, type WebSearchRunOptions, buildAuthorization, buildSignature, buildStringToSign };
1490
+ export { type Action, type ActionKind, ActionKinds, type Artifact, type BrowserProxyOptions, type BrowserbaseRegion, type CaptureOptions, type ClarificationPayload, type CompleteDelegateAgentInput, type CompleteDelegateTokenInput, type ConfirmLoginOptions, type ConfirmLoginResult, type ConfirmationPayload, type CoreRunEvent, type DeepResearchAttachOptions, type DeepResearchEvent, type DeepResearchRunOptions, type DelegateAgentInput, type DelegateAgentResponse, type DelegateAgentTokenResponse, type DelegateTokenInput, type DelegateTokenInteractiveInput, type DelegateTokenResponse, type DelegateTokenResult, type DelegateTokenSilentInput, type DelegateTokenSilentResponse, type DelegationMode, type DelegationTokenResponse, type DoAnythingAttachOptions, type DoAnythingEvent, type DoAnythingRunOptions, type DoAnythingSnapshot, type GenAuthAccessTokenInput, type GenAuthAdminToken, type GenAuthAdminTokenOverrideInput, type GenAuthDelegationIntrospectionInput, type GenAuthUserCreateBatchInput, type GenAuthUserCreateInput, type GenAuthUserDeleteBatchInput, type GenAuthUserGetBatchInput, type GenAuthUserGetInput, type GenAuthUserListInput, type GenAuthUserUpdateInput, type Interaction, type InteractionEvidence, InteractionHandle, type InteractionPayloadByType, type InteractionSite, type InteractionStatus, InteractionStatuses, type InteractionType, InteractionTypes, type InteractiveDelegationResponse, type JsonObject, type MonitorEvent, type MonitorEventsOptions, MonitorHandle, type MonitorRunsOptions, type OpenLoginOptions, type OpenLoginResult, Qoni, QoniAuthError, QoniDelegationRequiredError, QoniError, type QoniErrorCode, type QoniErrorOptions, type QoniEvent, type QoniEventType, QoniEventTypes, type QoniMeta, type QoniOptions, QoniPermissionDeniedError, type QoniProduct, type QoniProductName, QoniProductScopes, QoniRateLimitError, type QoniResponse, type QoniRuntimeConfig, type QoniSSEEvent, QoniScopeBundles, QoniScopes, QoniTimeoutError, QoniTokenExpiredError, QoniUpstreamError, QoniValidationError, type RawRequestInput, type RunBrowserLiveUrlChangedData, type RunDoneData, type RunEvent, type RunEventsOptions, RunHandle, type RunImage, type RunLimits, type RunMessageData, type RunReconnectInfo, type RunResult, type RunScreenshotData, type RunStatus, type RunWaitOptions, type RuntimeTokenInput, type SessionRef, type SiteLoginPayload, type SnapshotAction, type SnapshotImage, type TakeControlPayload, type TokenInput, type TrackAttachOptions, type TrackCreateOptions, type WaitKind, type WaitPayload, type WebSearchAttachOptions, type WebSearchEvent, type WebSearchRunOptions, buildAuthorization, buildSignature, buildStringToSign };
package/dist/index.d.ts CHANGED
@@ -363,7 +363,70 @@ interface Interaction<T extends InteractionType = InteractionType> {
363
363
  * supplies this (token + run addressing already bound); the handle below uses
364
364
  * it to invoke `action.endpoint` without the consumer touching HTTP.
365
365
  */
366
- type InteractionActionPoster = (action: Action, body: JsonObject | undefined) => Promise<void>;
366
+ type InteractionActionPoster = (action: Action, body: JsonObject | undefined, options?: {
367
+ requiredScopes?: readonly string[];
368
+ }) => Promise<unknown>;
369
+ /** Options for {@link InteractionHandle.openLogin}. */
370
+ interface OpenLoginOptions {
371
+ /**
372
+ * Site to sign in to — one of `interaction.payload.sites[].siteId`. May be
373
+ * omitted when the interaction lists exactly one site.
374
+ */
375
+ siteId?: string;
376
+ /** Re-login an existing browser profile in place instead of creating one. */
377
+ profileId?: string;
378
+ }
379
+ /** Interactive login session started by {@link InteractionHandle.openLogin}. */
380
+ interface OpenLoginResult {
381
+ profileId: string;
382
+ siteId: string;
383
+ /** Login browser session the user signs in through. */
384
+ sessionId: string;
385
+ /** Live view URL of the login browser to show to the user. */
386
+ liveUrl: string;
387
+ /** Unmodified response body (escape hatch — shape may evolve with the API). */
388
+ raw: JsonObject;
389
+ /**
390
+ * Persist the login into the profile after the user signs in
391
+ * (`POST /profiles/{profileId}/confirm`). Confirming ends this login
392
+ * session and closes its browser, whatever the outcome:
393
+ *
394
+ * - `active: true` — the login is saved; call
395
+ * {@link InteractionHandle.confirmSignedIn}.
396
+ * - `active: false` with `probeResult: "no_session"` — the backend no longer
397
+ * holds the session (it may already have saved the login automatically, or
398
+ * restarted). Call `confirmSignedIn()`: the agent rechecks the site and
399
+ * raises a new `site_login` interaction if it is still signed out.
400
+ * - Rejects with a `QoniError` whose `code` is `no_pending_login` (HTTP 409)
401
+ * when the backend has no pending login for this profile: the session
402
+ * already ended on providers that report it this way, or the profile no
403
+ * longer exists for this user. Handle it like `no_session`: call
404
+ * `confirmSignedIn()`, and the agent asks again if it is still signed out.
405
+ * - `active: false` with any other `probeResult` — the user was not signed
406
+ * in. Start a new session with `openLogin({ siteId, profileId })` and show
407
+ * its new `liveUrl`; the old one no longer works.
408
+ *
409
+ * Requires `QoniScopes.SITE_LOGIN_CONFIRM`.
410
+ */
411
+ confirm(options?: ConfirmLoginOptions): Promise<ConfirmLoginResult>;
412
+ }
413
+ /** Options for {@link OpenLoginResult.confirm}. */
414
+ interface ConfirmLoginOptions {
415
+ /** Optional human-readable label stored on the profile. */
416
+ displayLabel?: string;
417
+ }
418
+ /** Result of {@link OpenLoginResult.confirm}. */
419
+ interface ConfirmLoginResult {
420
+ profileId: string;
421
+ /** True only when the profile is now `active` (the login was captured). */
422
+ active: boolean;
423
+ /** Profile state after confirmation: `active`, or `pending_login` when no signed-in session was detected. */
424
+ state: string;
425
+ /** Outcome of the backend's signed-in probe, for example `no_session`. */
426
+ probeResult: string;
427
+ /** Unmodified response body (escape hatch — shape may evolve with the API). */
428
+ raw: JsonObject;
429
+ }
367
430
  /**
368
431
  * Typed wrapper over an {@link Interaction} that exposes one method per
369
432
  * action kind. Each method finds the matching declared action and posts to its
@@ -372,6 +435,7 @@ type InteractionActionPoster = (action: Action, body: JsonObject | undefined) =>
372
435
  * backend offered it).
373
436
  */
374
437
  declare class InteractionHandle<T extends InteractionType = InteractionType> {
438
+ #private;
375
439
  private readonly post;
376
440
  readonly interaction: Interaction<T>;
377
441
  constructor(interaction: Interaction<T>, post: InteractionActionPoster);
@@ -389,8 +453,16 @@ declare class InteractionHandle<T extends InteractionType = InteractionType> {
389
453
  confirm(): Promise<void>;
390
454
  /** Reject a pending confirmation. */
391
455
  reject(): Promise<void>;
392
- /** Open the login surface for a site_login interaction. */
393
- openLogin(): Promise<void>;
456
+ /**
457
+ * Start an interactive login session for a `site_login` interaction. The
458
+ * backend needs the site to sign in to: pass `siteId`, or omit it when the
459
+ * interaction lists exactly one site. Show `liveUrl` to the user; when they
460
+ * finish, call `confirm()` on the result to save the login, and act on its
461
+ * outcome (see {@link OpenLoginResult.confirm}) before {@link confirmSignedIn}.
462
+ * The delegation must include `QoniScopes.SITE_LOGIN_REQUEST` and
463
+ * `QoniScopes.SITE_LOGIN_CONFIRM`; the AccessKey policy must allow both.
464
+ */
465
+ openLogin(options?: OpenLoginOptions): Promise<OpenLoginResult>;
394
466
  /** Tell the agent the user has finished signing in. */
395
467
  confirmSignedIn(): Promise<void>;
396
468
  /** Connect to the live browser for a take_control interaction. */
@@ -445,6 +517,8 @@ declare const QoniEventTypes: {
445
517
  readonly Interaction: "interaction";
446
518
  /** A live screenshot frame (opt in with `capture: { screenshots: true }`); image on `event.image`. */
447
519
  readonly Screenshot: "screenshot";
520
+ /** The browser viewer moved to a new page or needs a fresh attachment. Use `event.data.liveUrl` for the live preview. */
521
+ readonly BrowserLiveUrlChanged: "browserLiveUrlChanged";
448
522
  /** Terminal — the run finished; outcome + output in `event.data` (cost is on the `RunResult`). */
449
523
  readonly Done: "done";
450
524
  /** Web Search results are ready; `event.data` is the count (the list is in `done.output`). */
@@ -487,6 +561,13 @@ interface RunScreenshotData {
487
561
  pageUrl?: string;
488
562
  step?: number;
489
563
  }
564
+ /** `browserLiveUrlChanged` — the provider's live viewer URL can rotate as tabs change. */
565
+ interface RunBrowserLiveUrlChangedData {
566
+ liveUrl: string;
567
+ supportsLivePump: boolean;
568
+ forceViewerReload: boolean;
569
+ providerSessionId?: string;
570
+ }
490
571
  /** `done` — terminal outcome + final output. (Total cost is on the `RunResult`.) */
491
572
  interface RunDoneData {
492
573
  output?: unknown;
@@ -510,6 +591,10 @@ type RunEvent = (RunEventBase & {
510
591
  data: RunScreenshotData;
511
592
  image: RunImage;
512
593
  isTerminal: false;
594
+ }) | (RunEventBase & {
595
+ type: "browserLiveUrlChanged";
596
+ data: RunBrowserLiveUrlChangedData;
597
+ isTerminal: false;
513
598
  }) | (RunEventBase & {
514
599
  type: "done";
515
600
  data: RunDoneData;
@@ -541,7 +626,7 @@ type RunEvent = (RunEventBase & {
541
626
  });
542
627
  /** Events any product run can emit. */
543
628
  type CoreRunEvent = Extract<RunEvent, {
544
- type: "progress" | "message" | "interaction" | "screenshot" | "done";
629
+ type: "progress" | "message" | "interaction" | "screenshot" | "browserLiveUrlChanged" | "done";
545
630
  }>;
546
631
  /** Do Anything — core events only. */
547
632
  type DoAnythingEvent = CoreRunEvent;
@@ -650,7 +735,9 @@ interface RunWireOps {
650
735
  * Interaction model's `actions[]` carry the endpoint + method, so the SDK
651
736
  * never hard-codes a HITL route — it forwards what the backend declared.
652
737
  */
653
- postAction(action: Action, body: JsonObject | undefined): Promise<void>;
738
+ postAction(action: Action, body: JsonObject | undefined, options?: {
739
+ requiredScopes?: readonly string[];
740
+ }): Promise<unknown>;
654
741
  cancel(reason?: string): Promise<JsonObject>;
655
742
  /** Products without artifacts leave this undefined → `result.artifacts` is []. */
656
743
  listArtifacts?(signal?: AbortSignal): Promise<Artifact[]>;
@@ -1077,10 +1164,12 @@ interface MonitorRunsOptions {
1077
1164
  /** A monitor's check cadence. */
1078
1165
  type MonitorSchedule = {
1079
1166
  kind: "cron";
1080
- expr: string;
1167
+ expr: string; /** IANA time zone for the cron expression. */
1168
+ tz?: string;
1081
1169
  } | {
1082
1170
  kind: "interval";
1083
1171
  intervalSeconds: number;
1172
+ tz?: string;
1084
1173
  };
1085
1174
  /**
1086
1175
  * Fields to change on a monitor via {@link MonitorHandle.refine}. Pass any
@@ -1102,7 +1191,9 @@ interface MonitorWireOps {
1102
1191
  update(input: JsonObject): Promise<JsonObject>;
1103
1192
  runNow(): Promise<JsonObject>;
1104
1193
  streamEvents(opts: MonitorEventsOptions): AsyncIterable<QoniEvent<unknown>>;
1105
- postAction(action: Action, body: JsonObject | undefined): Promise<void>;
1194
+ postAction(action: Action, body: JsonObject | undefined, options?: {
1195
+ requiredScopes?: readonly string[];
1196
+ }): Promise<unknown>;
1106
1197
  listRuns(opts: MonitorRunsOptions): Promise<JsonObject>;
1107
1198
  getRun(runId: string): Promise<JsonObject>;
1108
1199
  delete(): Promise<void>;
@@ -1375,6 +1466,8 @@ declare const QoniScopes: {
1375
1466
  readonly DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage";
1376
1467
  readonly TRACK_READ: "webagent.track:read";
1377
1468
  readonly TRACK_MANAGE: "webagent.track:manage";
1469
+ readonly SITE_LOGIN_REQUEST: "webagent.site_login:request";
1470
+ readonly SITE_LOGIN_CONFIRM: "webagent.site_login:confirm";
1378
1471
  };
1379
1472
  type QoniScope = (typeof QoniScopes)[keyof typeof QoniScopes];
1380
1473
  /** Product names accepted by `delegateToken({ products })`. */
@@ -1394,4 +1487,4 @@ declare const QoniScopeBundles: {
1394
1487
  readonly TRACK: readonly ["webagent.track:read", "webagent.track:manage"];
1395
1488
  };
1396
1489
 
1397
- export { type Action, type ActionKind, ActionKinds, type Artifact, type BrowserProxyOptions, type BrowserbaseRegion, type CaptureOptions, type ClarificationPayload, type CompleteDelegateAgentInput, type CompleteDelegateTokenInput, type ConfirmationPayload, type CoreRunEvent, type DeepResearchAttachOptions, type DeepResearchEvent, type DeepResearchRunOptions, type DelegateAgentInput, type DelegateAgentResponse, type DelegateAgentTokenResponse, type DelegateTokenInput, type DelegateTokenInteractiveInput, type DelegateTokenResponse, type DelegateTokenResult, type DelegateTokenSilentInput, type DelegateTokenSilentResponse, type DelegationMode, type DelegationTokenResponse, type DoAnythingAttachOptions, type DoAnythingEvent, type DoAnythingRunOptions, type DoAnythingSnapshot, type GenAuthAccessTokenInput, type GenAuthAdminToken, type GenAuthAdminTokenOverrideInput, type GenAuthDelegationIntrospectionInput, type GenAuthUserCreateBatchInput, type GenAuthUserCreateInput, type GenAuthUserDeleteBatchInput, type GenAuthUserGetBatchInput, type GenAuthUserGetInput, type GenAuthUserListInput, type GenAuthUserUpdateInput, type Interaction, type InteractionEvidence, InteractionHandle, type InteractionPayloadByType, type InteractionSite, type InteractionStatus, InteractionStatuses, type InteractionType, InteractionTypes, type InteractiveDelegationResponse, type JsonObject, type MonitorEvent, type MonitorEventsOptions, MonitorHandle, type MonitorRunsOptions, Qoni, QoniAuthError, QoniDelegationRequiredError, QoniError, type QoniErrorCode, type QoniErrorOptions, type QoniEvent, type QoniEventType, QoniEventTypes, type QoniMeta, type QoniOptions, QoniPermissionDeniedError, type QoniProduct, type QoniProductName, QoniProductScopes, QoniRateLimitError, type QoniResponse, type QoniRuntimeConfig, type QoniSSEEvent, QoniScopeBundles, QoniScopes, QoniTimeoutError, QoniTokenExpiredError, QoniUpstreamError, QoniValidationError, type RawRequestInput, type RunDoneData, type RunEvent, type RunEventsOptions, RunHandle, type RunImage, type RunLimits, type RunMessageData, type RunReconnectInfo, type RunResult, type RunScreenshotData, type RunStatus, type RunWaitOptions, type RuntimeTokenInput, type SessionRef, type SiteLoginPayload, type SnapshotAction, type SnapshotImage, type TakeControlPayload, type TokenInput, type TrackAttachOptions, type TrackCreateOptions, type WaitKind, type WaitPayload, type WebSearchAttachOptions, type WebSearchEvent, type WebSearchRunOptions, buildAuthorization, buildSignature, buildStringToSign };
1490
+ export { type Action, type ActionKind, ActionKinds, type Artifact, type BrowserProxyOptions, type BrowserbaseRegion, type CaptureOptions, type ClarificationPayload, type CompleteDelegateAgentInput, type CompleteDelegateTokenInput, type ConfirmLoginOptions, type ConfirmLoginResult, type ConfirmationPayload, type CoreRunEvent, type DeepResearchAttachOptions, type DeepResearchEvent, type DeepResearchRunOptions, type DelegateAgentInput, type DelegateAgentResponse, type DelegateAgentTokenResponse, type DelegateTokenInput, type DelegateTokenInteractiveInput, type DelegateTokenResponse, type DelegateTokenResult, type DelegateTokenSilentInput, type DelegateTokenSilentResponse, type DelegationMode, type DelegationTokenResponse, type DoAnythingAttachOptions, type DoAnythingEvent, type DoAnythingRunOptions, type DoAnythingSnapshot, type GenAuthAccessTokenInput, type GenAuthAdminToken, type GenAuthAdminTokenOverrideInput, type GenAuthDelegationIntrospectionInput, type GenAuthUserCreateBatchInput, type GenAuthUserCreateInput, type GenAuthUserDeleteBatchInput, type GenAuthUserGetBatchInput, type GenAuthUserGetInput, type GenAuthUserListInput, type GenAuthUserUpdateInput, type Interaction, type InteractionEvidence, InteractionHandle, type InteractionPayloadByType, type InteractionSite, type InteractionStatus, InteractionStatuses, type InteractionType, InteractionTypes, type InteractiveDelegationResponse, type JsonObject, type MonitorEvent, type MonitorEventsOptions, MonitorHandle, type MonitorRunsOptions, type OpenLoginOptions, type OpenLoginResult, Qoni, QoniAuthError, QoniDelegationRequiredError, QoniError, type QoniErrorCode, type QoniErrorOptions, type QoniEvent, type QoniEventType, QoniEventTypes, type QoniMeta, type QoniOptions, QoniPermissionDeniedError, type QoniProduct, type QoniProductName, QoniProductScopes, QoniRateLimitError, type QoniResponse, type QoniRuntimeConfig, type QoniSSEEvent, QoniScopeBundles, QoniScopes, QoniTimeoutError, QoniTokenExpiredError, QoniUpstreamError, QoniValidationError, type RawRequestInput, type RunBrowserLiveUrlChangedData, type RunDoneData, type RunEvent, type RunEventsOptions, RunHandle, type RunImage, type RunLimits, type RunMessageData, type RunReconnectInfo, type RunResult, type RunScreenshotData, type RunStatus, type RunWaitOptions, type RuntimeTokenInput, type SessionRef, type SiteLoginPayload, type SnapshotAction, type SnapshotImage, type TakeControlPayload, type TokenInput, type TrackAttachOptions, type TrackCreateOptions, type WaitKind, type WaitPayload, type WebSearchAttachOptions, type WebSearchEvent, type WebSearchRunOptions, buildAuthorization, buildSignature, buildStringToSign };