@scalebrowser/sdk 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -9,6 +9,41 @@ reconstructing it here would look like a record that had been kept all along.
 The daemon and the SDK version independently. An SDK release names the daemon
 version it was tested against wherever that matters.
 
+## 1.2.0 (2026-10-22)
+
+Two fixes in the CDP driver, both measured against a real browser, and three
+methods for routes the daemon serves since 0.24.0. Nothing is removed or renamed.
+
+- `navigate()` waited for the load by reading `document.readyState` in the
+  page's own world. A page that wraps that getter saw two reads with no script of
+  its own on the stack. The wait now reads from an isolated world.
+- `evaluate(expr, { isolated: true })` kept the id of its isolated world across a
+  navigation, so every isolated read after a page change failed with
+  `Cannot find context with specified id`. It now asks for the world of the
+  current document on every call.
+- `revealRequest(profileId, seq, { vault_password })`: what a recorded request
+  carried (the full address with its query, every header value and, on request,
+  the body), behind the vault password. `seq` is the number the agent's
+  `net_capture` tool lists.
+- `getAgentTools()` and `setAgentToolGroup(group, enabled)`: which optional MCP tool
+  groups agents on this machine see.
+- The README lists every method of the client.
+
+## 1.1.0 (2026-10-04)
+
+Three fields the daemon has sent since 0.20.0 now have types. All three are
+optional, so code written against 1.0.0 compiles unchanged.
+
+- `Profile.timezone_country`: the country the profile's clock places it in,
+  `null` for a zone the daemon has no country for. Read the country from here,
+  not from the language: Chrome sends the list of its interface language, so a
+  profile in Vienna sends `de-DE`.
+- `Account.plan_required`: the account has no active plan, and choosing one is
+  the only remedy. The daemon enrols the machine by itself on its next check
+  after that.
+- `Account.trial_available`: together with `plan_required`, the account still
+  has its free trial.
+
 ## 1.0.0 (2026-09-27)
 
 The library works as in 0.9.0. What changes is the promise: from this release

package/README.md

@@ -62,10 +62,13 @@ try {
 
 Every `/v1` endpoint is a typed method on `ScalebrowserClient`:
 
-- **Profiles**: `listProfiles`, `getProfile`, `createProfile`, `updateProfile`,
-  `deleteProfile`, `startProfile`, `stopProfile`
+- **Profiles**: `listProfiles`, `listProfileIds`, `countProfiles`, `getProfile`,
+  `createProfile`, `updateProfile`, `deleteProfile`, `startProfile`, `stopProfile`.
+  `releaseProfile` drops an agent's lease without its handle (the operator's way
+  out), and `takeoverProfile` asks for a profile that is open on another machine
+  of your account
 - **Bulk**: `bulkCreateProfiles`, `bulkStart`, `bulkStop`, `bulkDelete`,
-  `bulkAssignProxy`
+  `bulkAssignProxy`, `bulkAssignExtensions`
 - **Groups / Presets**: `listGroups`/`createGroup`/`getGroup`/`updateGroup`/`deleteGroup`,
   `listPresets`/`createPreset`/`getPreset`/`updatePreset`/`deletePreset`,
   `getPersonaConstraints`. A preset is `config` (what the profiles do:
@@ -78,13 +81,20 @@ Every `/v1` endpoint is a typed method on `ScalebrowserClient`:
   it; pass `id` to reuse an existing proxy's stored credentials). Credentials
   are write-only, never returned
 - **Extensions**: `listExtensions`, `attachExtension`, `detachExtension`, plus
-  the daemon-wide library (`uploadExtension`, `getLibraryExtension`,
-  `deleteLibraryExtension`). An attached package IS loaded into the browser at
+  the daemon-wide library (`listLibraryExtensions`, `uploadExtension`,
+  `getLibraryExtension`, `deleteLibraryExtension`, `deleteLibraryExtensionVersion`). An attached package IS loaded into the browser at
   launch, under the canonical Web-Store id its own key derives
-- **Credentials**: `listCredentials`, `putCredential`, `revealCredential`
-  (needs the vault password), `exportCredentials`, `importCredentials`
+- **Credentials**: `listCredentials`, `putCredential`, `deleteCredential`,
+  `revealCredential` (needs the vault password), `exportCredentials`,
+  `importCredentials`. The vault password itself: `vaultStatus`, `setVaultPassword`
+- **Secret layer**: `getSecretLayer`, `setSecretLayer`, `listSecrets`,
+  `updateSecret`, `deleteSecret`. `scrubText` filters a text you hold against a
+  profile's values, and `runWithSecrets` runs a command with named values in its
+  environment, so no value crosses a socket
 - **Cookies**: `revealCookies`, the one route a cookie VALUE leaves through,
   behind the same vault password
+- **Recorded requests**: `revealRequest`, the one route what a request carried (query,
+  header values, body) leaves through, behind the same vault password
 - **Sessions**: `exportSession`, `importSession`
 - **Mailboxes**: `listInboxes`, `createInbox`, `updateInbox`, `deleteInbox`,
   `getInboxBindings`, `bindInbox`, `unbindInbox`, which is where a profile's
@@ -98,6 +108,30 @@ Every `/v1` endpoint is a typed method on `ScalebrowserClient`:
   may answer when the browser asks something
 - **Artifacts**: `putArtifact` (hand the daemon a file to upload later),
   `getArtifact` (fetch a screenshot, download or saved PDF as bytes)
+- **Tasks and memory**: `listTasks`, `createTasks`, `cancelTask`, `deleteTask`,
+  plus a profile's standing instructions for agents, its `PROFILE.md`:
+  `getProfileMemory`, `putProfileMemory`, `deleteProfileMemory`
+- **Videos**: `listVideos`, `getVideo`, `renameVideo`, `deleteVideo`,
+  `cancelVideo`, `rerenderVideo`, `videoAccess`, `downloadVideoFile`,
+  `videosStorage`; recordings with `listRecordings`, `getRecording`,
+  `deleteRecordingRaw`, `renderRecording`; public links with `share`,
+  `shareStatus`, `revokeShare`
+- **Video presets**: `listVideoPresets`, `getVideoPreset`, `createVideoPreset`,
+  `updateVideoPreset`, `duplicateVideoPreset`, `deleteVideoPreset`, and a look
+  at an unsaved config with `previewVideoPreset`, `previewVideoPresetClip`,
+  `downloadVideoPresetClip`. The files a preset points at: `listMedia`,
+  `uploadMedia`, `deleteMedia`, `mediaFile`. Narration keys: `listTtsProviders`,
+  `putTtsProvider`, `verifyTtsProvider`, `deleteTtsProvider`. Encoders:
+  `getCodecs`, `setCodecEnabled`
+- **Fingerprint audit**: `startAudit` drives the profile's running browser through
+  the external detector pages, `getAudit` reads the state and the last report
+- **Exit addresses**: `getExitStatus` (which addresses a profile owns), and the
+  machine's rule that one address belongs to one profile: `getExitRule`,
+  `setExitRule`
+- **Machine settings**: `getRemoteAccess`, `setRemoteAccess` (may a chat service
+  reach this machine's browsers), `getAgentTools`, `setAgentToolGroup` (which
+  optional MCP tool groups agents see), `getConnection` (which installation
+  answered: its data directory and its binary)
 - **Input**: `sendInput`
 - **Metrics / Account / Health**: `getMetrics`, `getAccount`, `health`, `ready`.
   The first two answer 404 on a daemon without them, which the SDK treats as
@@ -105,7 +139,9 @@ Every `/v1` endpoint is a typed method on `ScalebrowserClient`:
   state, and the account reads `licensed: false`, which is what "self-hosted, no
   control plane" means
 
-Errors map to typed exceptions carrying the daemon's numeric code (4001–4012):
+`setToken` swaps the bearer token on a live client.
+
+Errors map to typed exceptions carrying the daemon's numeric code (4001–4013):
 
 ```ts
 import { ApiError, ErrorCode } from '@scalebrowser/sdk';
@@ -140,7 +176,10 @@ for await (const e of sb.events()) {
 `CdpSession` (returned by `connectCdp` / `launch`) gives you:
 
 - `send<T>(method, params?)`: raw CDP command, awaited by id (concurrent-safe)
-- `navigate(url, { wait, timeout })`, `evaluate<T>(expr, { isolated })`
+- `navigate(url, { wait, timeout })`, `evaluate<T>(expr, { isolated })`. The
+  wait for the load reads from an isolated world, so a page that watches its own
+  `document.readyState` sees no foreign read; `isolated: true` asks for the world
+  of the document that is loaded now, on every call
 - `createIsolatedWorld(frameId?, worldName?)`
 - `attachToPage({ targetId?, create?, url? })`
 - `on(method, cb)` / `events()`: CDP event subscription scoped to the session

package/dist/index.cjs

@@ -588,6 +588,16 @@ var IdentityApi = class extends ClientCore {
   revealCookies(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/cookies/reveal`, body);
   }
+  // ── Recorded requests ──────────────────────────────────────────────────────
+  /**
+   * The one door what a recorded request carried leaves through, and it needs the vault
+   * password: the full address with its query, every header value (`Cookie`,
+   * `Authorization`) and, on request, the body. The agent's `net_capture` answers by
+   * shape only. `seq` is the number it listed.
+   */
+  revealRequest(profileId, seq, body) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/network/${seq}/reveal`, body);
+  }
 };
 
 // src/client-tasks.ts
@@ -1142,7 +1152,6 @@ var CdpSession = class _CdpSession {
   sessionId;
   #client;
   #profileId;
-  #isolatedContextId;
   constructor(conn, sessionId, client, profileId) {
     this.#conn = conn;
     this.sessionId = sessionId;
@@ -1196,14 +1205,21 @@ var CdpSession = class _CdpSession {
       awaitPromise: opts.awaitPromise ?? true,
       returnByValue: opts.returnByValue ?? true
     };
-    if (opts.isolated) params["contextId"] = await this.#isolatedContext();
+    if (opts.isolated) params["contextId"] = await this.createIsolatedWorld();
     const res = await this.send("Runtime.evaluate", params);
     if (res.exceptionDetails) {
       throw new CdpError(-1, res.exceptionDetails.text || res.exceptionDetails.exception?.description || "evaluate exception");
     }
     return res.result.value;
   }
-  /** Create an isolated world for the (main) frame and return its execution context id. */
+  /**
+   * Create an isolated world for the (main) frame and return its execution context id.
+   *
+   * The id belongs to the document that is loaded right now. After a navigation it
+   * names a context that no longer exists, so ask again instead of keeping it:
+   * Chrome hands back the same world for the same name, so asking costs one round
+   * trip.
+   */
   async createIsolatedWorld(frameId, worldName = "__sb") {
     let frame = frameId;
     if (!frame) {
@@ -1261,14 +1277,18 @@ var CdpSession = class _CdpSession {
     }
     return this.#client.sendInput(this.#profileId, { ...body, humanize: true });
   }
-  async #isolatedContext() {
-    if (this.#isolatedContextId === void 0) this.#isolatedContextId = await this.createIsolatedWorld();
-    return this.#isolatedContextId;
-  }
+  // The poll reads in an isolated world: a page that wraps `document.readyState`
+  // sees a read from its own world, with a caller that is none of its scripts.
+  // While the new document commits, the world of the old one can vanish between
+  // asking for it and reading in it; the browser refuses that read with its own
+  // error code, and it is retried. A closed connection still fails at once.
   async #waitForLoad(timeout) {
     const deadline = Date.now() + timeout;
     for (; ; ) {
-      const ready = await this.evaluate("document.readyState");
+      const ready = await this.evaluate("document.readyState", { isolated: true }).catch((err) => {
+        if (err instanceof CdpError && err.code !== -1) return void 0;
+        throw err;
+      });
       if (ready === "complete") return;
       if (Date.now() > deadline) throw new CdpError(-1, "navigation wait timed out");
       await delay(50);
@@ -1665,6 +1685,24 @@ var ScalebrowserClient = class extends ClientCore {
   async setExitRule(enabled, signal) {
     return this.request("PUT", "/v1/exit-rule", { enabled }, { signal });
   }
+  /**
+   * Which optional MCP tool groups agents on this machine see.
+   *
+   * Agents see the basic tools by default; video, tasks, profile management,
+   * the captcha helpers, the extras and the developer tools are one switch each.
+   */
+  async getAgentTools(signal) {
+    return this.request("GET", "/v1/agent-tools", void 0, { signal });
+  }
+  /**
+   * Turn one tool group on or off for every agent on this machine.
+   *
+   * It applies to the next tool list an agent asks for. A session that listed
+   * its tools before keeps that list until it reconnects.
+   */
+  async setAgentToolGroup(group, enabled, signal) {
+    return this.request("PUT", "/v1/agent-tools", { group, enabled }, { signal });
+  }
   // ── Events (SSE) ───────────────────────────────────────────────────────────
   /** Subscribe to lifecycle events. Returns an unsubscribe function. */
   subscribeEvents(handlers) {
@@ -1738,7 +1776,7 @@ var PROXY_KINDS = ["http", "socks5", "gateway"];
 var ROTATIONS = ["sticky", "rotating"];
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.2.0";
 
 exports.ApiError = ApiError;
 exports.CdpError = CdpError;

package/dist/index.d.cts

@@ -486,6 +486,14 @@ interface Profile {
      * Additive; a daemon predating the credential vault simply omits it.
      */
     platforms?: string[];
+    /**
+     * The country the persona's clock places it in (`persona.timezone`), `null` for
+     * a zone outside the daemon's cohort table. Never read the country out of the
+     * language: Chrome sends the list of its UI language, so a profile in Vienna
+     * speaks `de-DE` and one in Stockholm `en-US`. Additive; present on list/get
+     * (`ProfileView`), absent where `protection` is.
+     */
+    timezone_country?: string | null;
 }
 interface Group {
     id: string;
@@ -1434,6 +1442,14 @@ interface Account {
     /** Unix seconds; when the cached entitlement stops being valid. */
     expires_at?: number;
     permits_launch: boolean;
+    /** The control plane refused this machine because the account has no active
+     *  plan. Choosing one on the pricing page is the only remedy; the daemon
+     *  enrols the machine by itself on its next check after that. Absent when
+     *  false. */
+    plan_required?: boolean;
+    /** With `plan_required`: the control plane said this account still has its
+     *  free trial. Absent when false. */
+    trial_available?: boolean;
 }
 interface HealthStatus {
     status: string;
@@ -1465,6 +1481,29 @@ interface RemoteStatus {
  * purpose, a residential line you pay for or a whitelisted office address, where
  * the rule would refuse every start after the first.
  */
+/** An optional tool group: `basic` is always served and has no switch. */
+type ToolGroupId = 'video' | 'tasks' | 'fleet' | 'captcha' | 'extras' | 'developer';
+/** One switchable group of MCP tools. */
+interface AgentToolGroup {
+    id: ToolGroupId;
+    /** Do agents on this machine see these tools? */
+    enabled: boolean;
+    /** Did a person decide this, or is the configured default still standing? */
+    explicit: boolean;
+    /** The tools the group adds, among the profiles this daemon serves. */
+    tools: string[];
+}
+/**
+ * What `GET /v1/agent-tools` answers: which optional tool groups agents see.
+ *
+ * Off by default. An agent sees the basic tools until a group is switched on,
+ * which keeps the tool list it pays for on every request short.
+ */
+interface AgentTools {
+    groups: AgentToolGroup[];
+    /** How many tools an agent sees right now. */
+    served: number;
+}
 interface ExitRuleStatus {
     /** Does the rule apply on this machine? */
     enabled: boolean;
@@ -1973,6 +2012,69 @@ interface RevealCookiesResult {
     domain: string;
     cookies: RevealedCookie[];
 }
+/** One header, name and value as the network stack saw them. */
+interface RequestHeader {
+    name: string;
+    value: string;
+}
+/**
+ * What a request looked like, with every value that could be a secret left out: the
+ * address stops at the path, headers are listed by name. This is the form the agent's
+ * `net_capture` tool answers with.
+ */
+interface RequestShape {
+    /** Increasing, never reused. The number the reveal route takes. */
+    seq: number;
+    method: string;
+    origin: string;
+    path: string;
+    /** The address had a query. The query itself is not here. */
+    has_query: boolean;
+    /** The fetch destination (`document`, `script`, `image`), empty for fetch/XHR. */
+    resource_type: string;
+    top_frame_origin: string;
+    /** `pending`, `loading`, `complete`, `failed` or `aborted`. */
+    state: string;
+    /** Status of the final response; 0 while there is none. */
+    status: number;
+    mime_type: string;
+    protocol: string;
+    from_cache: boolean;
+    net_error: number;
+    redirects: number;
+    encoded_bytes: number;
+    body_bytes: number;
+    /** Whether the body can still be revealed. */
+    has_body: boolean;
+    /** Why it cannot: `too_large`, `evicted` or `incomplete`. Empty otherwise. */
+    body_dropped: string;
+    request_header_names: string[];
+    response_header_names: string[];
+    age_ms: number;
+}
+interface RevealRequestBody {
+    /** The same gate a cookie value sits behind. */
+    vault_password: string;
+    /** Return the decoded body too. Left out by default. */
+    include_body?: boolean;
+    /** Longest body to return (default 1 MiB, at most 8 MiB). */
+    max_body_bytes?: number | null;
+}
+/** A recorded request in full: the query, every header value and, on request, the body. */
+interface RevealRequestResult {
+    seq: number;
+    /** The final address, query included. */
+    url: string;
+    shape: RequestShape;
+    request_headers: RequestHeader[];
+    response_headers: RequestHeader[];
+    /** The decoded body: text if it was valid UTF-8, base64 otherwise (`body_base64`). */
+    body: string | null;
+    body_base64: boolean;
+    body_truncated: boolean;
+    /** Why the body is missing although asked for: `decode_failed` or `decoded_too_large`. Empty otherwise. */
+    body_error: string;
+}
 /** What a stored value is. */
 type SecretKind = 'api_token' | 'password' | 'recovery_code' | 'totp_seed' | 'private_key' | 'unknown';
 /** How the layer came to know it. The first three are the honest origins. */
@@ -2207,6 +2309,13 @@ declare class IdentityApi extends ClientCore {
      * every other cookie surface answers with metadata only.
      */
     revealCookies(profileId: string, body: RevealCookiesBody): Promise<RevealCookiesResult>;
+    /**
+     * The one door what a recorded request carried leaves through, and it needs the vault
+     * password: the full address with its query, every header value (`Cookie`,
+     * `Authorization`) and, on request, the body. The agent's `net_capture` answers by
+     * shape only. `seq` is the number it listed.
+     */
+    revealRequest(profileId: string, seq: number, body: RevealRequestBody): Promise<RevealRequestResult>;
 }
 
 declare class TasksApi extends ClientCore {
@@ -2531,7 +2640,14 @@ declare class CdpSession {
     navigate(url: string, opts?: NavigateOptions): Promise<NavigateResult>;
     /** Evaluate a JS expression in the page (or an isolated world) and return its value. */
     evaluate<T = unknown>(expression: string, opts?: EvaluateOptions): Promise<T>;
-    /** Create an isolated world for the (main) frame and return its execution context id. */
+    /**
+     * Create an isolated world for the (main) frame and return its execution context id.
+     *
+     * The id belongs to the document that is loaded right now. After a navigation it
+     * names a context that no longer exists, so ask again instead of keeping it:
+     * Chrome hands back the same world for the same name, so asking costs one round
+     * trip.
+     */
     createIsolatedWorld(frameId?: string, worldName?: string): Promise<number>;
     humanizeMove(x: number, y: number, opts?: MoveOptions): Promise<unknown>;
     humanizeClick(x: number, y: number, opts?: ClickOptions): Promise<unknown>;
@@ -2793,6 +2909,20 @@ declare class ScalebrowserClient extends ClientCore {
      * exists for the narrower case (`updateProfile` with `exit_exclusive`).
      */
     setExitRule(enabled: boolean, signal?: AbortSignal): Promise<ExitRuleStatus>;
+    /**
+     * Which optional MCP tool groups agents on this machine see.
+     *
+     * Agents see the basic tools by default; video, tasks, profile management,
+     * the captcha helpers, the extras and the developer tools are one switch each.
+     */
+    getAgentTools(signal?: AbortSignal): Promise<AgentTools>;
+    /**
+     * Turn one tool group on or off for every agent on this machine.
+     *
+     * It applies to the next tool list an agent asks for. A session that listed
+     * its tools before keeps that list until it reconnects.
+     */
+    setAgentToolGroup(group: ToolGroupId, enabled: boolean, signal?: AbortSignal): Promise<AgentTools>;
     /** Subscribe to lifecycle events. Returns an unsubscribe function. */
     subscribeEvents(handlers: StreamHandlers): () => void;
     /** `for await (const event of client.events())` over lifecycle events. */
@@ -2905,6 +3035,6 @@ declare function errorMessage(err: unknown): string;
  * ```
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.2.0";
 
-export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type BlockedExport, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type Connection, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitRuleStatus, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, type HealthStatus, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type ListTasksParams, type ListVideosParams, type MediaAsset, type MediaKind, type MusicBed, type NarrationLine, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PatchTaskBody, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type PreviewHidden, type PreviewMoment, type Profile, type ProfileActivity, type ProfileMemory, type ProfileTask, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, type ProxyRow, type ProxyUsage, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type Recording, type RecordingKind, type RecordingState, type RemoteStatus, type RenderProgress, type RenderRequestBody, type RenderStage, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type ShareLinkLocal, type ShareStatus, type ShotFocus, type ShotIntent, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TaskState, type TimestampState, type TranscriptWord, type TrustedInputBody, type TtsProviderView, type TtsVerifyResult, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, type Video, type VideoAccessGrant, type VideoAssetName, type VideoAssets, type VideoBackground, type VideoCard, type VideoDestination, type VideoFlags, type VideoPreset, type VideoPresetClip, type VideoPresetClipBody, type VideoPresetClipProgress, type VideoPresetClipStarted, type VideoPresetConfig, type VideoPresetPreview, type VideoPresetPreviewBody, type VideoState, type VideosPage, type VideosStorage, type WriteMemoryBody, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };
+export { type Account, type ActivitySnapshot, type AgentRun, type AgentToolGroup, type AgentTools, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type BlockedExport, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type Connection, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitRuleStatus, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, type HealthStatus, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type ListTasksParams, type ListVideosParams, type MediaAsset, type MediaKind, type MusicBed, type NarrationLine, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PatchTaskBody, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type PreviewHidden, type PreviewMoment, type Profile, type ProfileActivity, type ProfileMemory, type ProfileTask, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, type ProxyRow, type ProxyUsage, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type Recording, type RecordingKind, type RecordingState, type RemoteStatus, type RenderProgress, type RenderRequestBody, type RenderStage, type RequestHeader, type RequestShape, type RevealCookiesBody, type RevealCookiesResult, type RevealRequestBody, type RevealRequestResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type ShareLinkLocal, type ShareStatus, type ShotFocus, type ShotIntent, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TaskState, type TimestampState, type ToolGroupId, type TranscriptWord, type TrustedInputBody, type TtsProviderView, type TtsVerifyResult, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, type Video, type VideoAccessGrant, type VideoAssetName, type VideoAssets, type VideoBackground, type VideoCard, type VideoDestination, type VideoFlags, type VideoPreset, type VideoPresetClip, type VideoPresetClipBody, type VideoPresetClipProgress, type VideoPresetClipStarted, type VideoPresetConfig, type VideoPresetPreview, type VideoPresetPreviewBody, type VideoState, type VideosPage, type VideosStorage, type WriteMemoryBody, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/dist/index.d.ts

@@ -486,6 +486,14 @@ interface Profile {
      * Additive; a daemon predating the credential vault simply omits it.
      */
     platforms?: string[];
+    /**
+     * The country the persona's clock places it in (`persona.timezone`), `null` for
+     * a zone outside the daemon's cohort table. Never read the country out of the
+     * language: Chrome sends the list of its UI language, so a profile in Vienna
+     * speaks `de-DE` and one in Stockholm `en-US`. Additive; present on list/get
+     * (`ProfileView`), absent where `protection` is.
+     */
+    timezone_country?: string | null;
 }
 interface Group {
     id: string;
@@ -1434,6 +1442,14 @@ interface Account {
     /** Unix seconds; when the cached entitlement stops being valid. */
     expires_at?: number;
     permits_launch: boolean;
+    /** The control plane refused this machine because the account has no active
+     *  plan. Choosing one on the pricing page is the only remedy; the daemon
+     *  enrols the machine by itself on its next check after that. Absent when
+     *  false. */
+    plan_required?: boolean;
+    /** With `plan_required`: the control plane said this account still has its
+     *  free trial. Absent when false. */
+    trial_available?: boolean;
 }
 interface HealthStatus {
     status: string;
@@ -1465,6 +1481,29 @@ interface RemoteStatus {
  * purpose, a residential line you pay for or a whitelisted office address, where
  * the rule would refuse every start after the first.
  */
+/** An optional tool group: `basic` is always served and has no switch. */
+type ToolGroupId = 'video' | 'tasks' | 'fleet' | 'captcha' | 'extras' | 'developer';
+/** One switchable group of MCP tools. */
+interface AgentToolGroup {
+    id: ToolGroupId;
+    /** Do agents on this machine see these tools? */
+    enabled: boolean;
+    /** Did a person decide this, or is the configured default still standing? */
+    explicit: boolean;
+    /** The tools the group adds, among the profiles this daemon serves. */
+    tools: string[];
+}
+/**
+ * What `GET /v1/agent-tools` answers: which optional tool groups agents see.
+ *
+ * Off by default. An agent sees the basic tools until a group is switched on,
+ * which keeps the tool list it pays for on every request short.
+ */
+interface AgentTools {
+    groups: AgentToolGroup[];
+    /** How many tools an agent sees right now. */
+    served: number;
+}
 interface ExitRuleStatus {
     /** Does the rule apply on this machine? */
     enabled: boolean;
@@ -1973,6 +2012,69 @@ interface RevealCookiesResult {
     domain: string;
     cookies: RevealedCookie[];
 }
+/** One header, name and value as the network stack saw them. */
+interface RequestHeader {
+    name: string;
+    value: string;
+}
+/**
+ * What a request looked like, with every value that could be a secret left out: the
+ * address stops at the path, headers are listed by name. This is the form the agent's
+ * `net_capture` tool answers with.
+ */
+interface RequestShape {
+    /** Increasing, never reused. The number the reveal route takes. */
+    seq: number;
+    method: string;
+    origin: string;
+    path: string;
+    /** The address had a query. The query itself is not here. */
+    has_query: boolean;
+    /** The fetch destination (`document`, `script`, `image`), empty for fetch/XHR. */
+    resource_type: string;
+    top_frame_origin: string;
+    /** `pending`, `loading`, `complete`, `failed` or `aborted`. */
+    state: string;
+    /** Status of the final response; 0 while there is none. */
+    status: number;
+    mime_type: string;
+    protocol: string;
+    from_cache: boolean;
+    net_error: number;
+    redirects: number;
+    encoded_bytes: number;
+    body_bytes: number;
+    /** Whether the body can still be revealed. */
+    has_body: boolean;
+    /** Why it cannot: `too_large`, `evicted` or `incomplete`. Empty otherwise. */
+    body_dropped: string;
+    request_header_names: string[];
+    response_header_names: string[];
+    age_ms: number;
+}
+interface RevealRequestBody {
+    /** The same gate a cookie value sits behind. */
+    vault_password: string;
+    /** Return the decoded body too. Left out by default. */
+    include_body?: boolean;
+    /** Longest body to return (default 1 MiB, at most 8 MiB). */
+    max_body_bytes?: number | null;
+}
+/** A recorded request in full: the query, every header value and, on request, the body. */
+interface RevealRequestResult {
+    seq: number;
+    /** The final address, query included. */
+    url: string;
+    shape: RequestShape;
+    request_headers: RequestHeader[];
+    response_headers: RequestHeader[];
+    /** The decoded body: text if it was valid UTF-8, base64 otherwise (`body_base64`). */
+    body: string | null;
+    body_base64: boolean;
+    body_truncated: boolean;
+    /** Why the body is missing although asked for: `decode_failed` or `decoded_too_large`. Empty otherwise. */
+    body_error: string;
+}
 /** What a stored value is. */
 type SecretKind = 'api_token' | 'password' | 'recovery_code' | 'totp_seed' | 'private_key' | 'unknown';
 /** How the layer came to know it. The first three are the honest origins. */
@@ -2207,6 +2309,13 @@ declare class IdentityApi extends ClientCore {
      * every other cookie surface answers with metadata only.
      */
     revealCookies(profileId: string, body: RevealCookiesBody): Promise<RevealCookiesResult>;
+    /**
+     * The one door what a recorded request carried leaves through, and it needs the vault
+     * password: the full address with its query, every header value (`Cookie`,
+     * `Authorization`) and, on request, the body. The agent's `net_capture` answers by
+     * shape only. `seq` is the number it listed.
+     */
+    revealRequest(profileId: string, seq: number, body: RevealRequestBody): Promise<RevealRequestResult>;
 }
 
 declare class TasksApi extends ClientCore {
@@ -2531,7 +2640,14 @@ declare class CdpSession {
     navigate(url: string, opts?: NavigateOptions): Promise<NavigateResult>;
     /** Evaluate a JS expression in the page (or an isolated world) and return its value. */
     evaluate<T = unknown>(expression: string, opts?: EvaluateOptions): Promise<T>;
-    /** Create an isolated world for the (main) frame and return its execution context id. */
+    /**
+     * Create an isolated world for the (main) frame and return its execution context id.
+     *
+     * The id belongs to the document that is loaded right now. After a navigation it
+     * names a context that no longer exists, so ask again instead of keeping it:
+     * Chrome hands back the same world for the same name, so asking costs one round
+     * trip.
+     */
     createIsolatedWorld(frameId?: string, worldName?: string): Promise<number>;
     humanizeMove(x: number, y: number, opts?: MoveOptions): Promise<unknown>;
     humanizeClick(x: number, y: number, opts?: ClickOptions): Promise<unknown>;
@@ -2793,6 +2909,20 @@ declare class ScalebrowserClient extends ClientCore {
      * exists for the narrower case (`updateProfile` with `exit_exclusive`).
      */
     setExitRule(enabled: boolean, signal?: AbortSignal): Promise<ExitRuleStatus>;
+    /**
+     * Which optional MCP tool groups agents on this machine see.
+     *
+     * Agents see the basic tools by default; video, tasks, profile management,
+     * the captcha helpers, the extras and the developer tools are one switch each.
+     */
+    getAgentTools(signal?: AbortSignal): Promise<AgentTools>;
+    /**
+     * Turn one tool group on or off for every agent on this machine.
+     *
+     * It applies to the next tool list an agent asks for. A session that listed
+     * its tools before keeps that list until it reconnects.
+     */
+    setAgentToolGroup(group: ToolGroupId, enabled: boolean, signal?: AbortSignal): Promise<AgentTools>;
     /** Subscribe to lifecycle events. Returns an unsubscribe function. */
     subscribeEvents(handlers: StreamHandlers): () => void;
     /** `for await (const event of client.events())` over lifecycle events. */
@@ -2905,6 +3035,6 @@ declare function errorMessage(err: unknown): string;
  * ```
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.2.0";
 
-export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type BlockedExport, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type Connection, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitRuleStatus, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, type HealthStatus, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type ListTasksParams, type ListVideosParams, type MediaAsset, type MediaKind, type MusicBed, type NarrationLine, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PatchTaskBody, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type PreviewHidden, type PreviewMoment, type Profile, type ProfileActivity, type ProfileMemory, type ProfileTask, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, type ProxyRow, type ProxyUsage, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type Recording, type RecordingKind, type RecordingState, type RemoteStatus, type RenderProgress, type RenderRequestBody, type RenderStage, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type ShareLinkLocal, type ShareStatus, type ShotFocus, type ShotIntent, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TaskState, type TimestampState, type TranscriptWord, type TrustedInputBody, type TtsProviderView, type TtsVerifyResult, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, type Video, type VideoAccessGrant, type VideoAssetName, type VideoAssets, type VideoBackground, type VideoCard, type VideoDestination, type VideoFlags, type VideoPreset, type VideoPresetClip, type VideoPresetClipBody, type VideoPresetClipProgress, type VideoPresetClipStarted, type VideoPresetConfig, type VideoPresetPreview, type VideoPresetPreviewBody, type VideoState, type VideosPage, type VideosStorage, type WriteMemoryBody, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };
+export { type Account, type ActivitySnapshot, type AgentRun, type AgentToolGroup, type AgentTools, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type BlockedExport, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type Connection, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitRuleStatus, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, type HealthStatus, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type ListTasksParams, type ListVideosParams, type MediaAsset, type MediaKind, type MusicBed, type NarrationLine, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PatchTaskBody, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type PreviewHidden, type PreviewMoment, type Profile, type ProfileActivity, type ProfileMemory, type ProfileTask, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, type ProxyRow, type ProxyUsage, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type Recording, type RecordingKind, type RecordingState, type RemoteStatus, type RenderProgress, type RenderRequestBody, type RenderStage, type RequestHeader, type RequestShape, type RevealCookiesBody, type RevealCookiesResult, type RevealRequestBody, type RevealRequestResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type ShareLinkLocal, type ShareStatus, type ShotFocus, type ShotIntent, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TaskState, type TimestampState, type ToolGroupId, type TranscriptWord, type TrustedInputBody, type TtsProviderView, type TtsVerifyResult, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, type Video, type VideoAccessGrant, type VideoAssetName, type VideoAssets, type VideoBackground, type VideoCard, type VideoDestination, type VideoFlags, type VideoPreset, type VideoPresetClip, type VideoPresetClipBody, type VideoPresetClipProgress, type VideoPresetClipStarted, type VideoPresetConfig, type VideoPresetPreview, type VideoPresetPreviewBody, type VideoState, type VideosPage, type VideosStorage, type WriteMemoryBody, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/dist/index.js

@@ -582,6 +582,16 @@ var IdentityApi = class extends ClientCore {
   revealCookies(profileId, body) {
     return this.request("POST", `/v1/profiles/${enc(profileId)}/cookies/reveal`, body);
   }
+  // ── Recorded requests ──────────────────────────────────────────────────────
+  /**
+   * The one door what a recorded request carried leaves through, and it needs the vault
+   * password: the full address with its query, every header value (`Cookie`,
+   * `Authorization`) and, on request, the body. The agent's `net_capture` answers by
+   * shape only. `seq` is the number it listed.
+   */
+  revealRequest(profileId, seq, body) {
+    return this.request("POST", `/v1/profiles/${enc(profileId)}/network/${seq}/reveal`, body);
+  }
 };
 
 // src/client-tasks.ts
@@ -1136,7 +1146,6 @@ var CdpSession = class _CdpSession {
   sessionId;
   #client;
   #profileId;
-  #isolatedContextId;
   constructor(conn, sessionId, client, profileId) {
     this.#conn = conn;
     this.sessionId = sessionId;
@@ -1190,14 +1199,21 @@ var CdpSession = class _CdpSession {
       awaitPromise: opts.awaitPromise ?? true,
       returnByValue: opts.returnByValue ?? true
     };
-    if (opts.isolated) params["contextId"] = await this.#isolatedContext();
+    if (opts.isolated) params["contextId"] = await this.createIsolatedWorld();
     const res = await this.send("Runtime.evaluate", params);
     if (res.exceptionDetails) {
       throw new CdpError(-1, res.exceptionDetails.text || res.exceptionDetails.exception?.description || "evaluate exception");
     }
     return res.result.value;
   }
-  /** Create an isolated world for the (main) frame and return its execution context id. */
+  /**
+   * Create an isolated world for the (main) frame and return its execution context id.
+   *
+   * The id belongs to the document that is loaded right now. After a navigation it
+   * names a context that no longer exists, so ask again instead of keeping it:
+   * Chrome hands back the same world for the same name, so asking costs one round
+   * trip.
+   */
   async createIsolatedWorld(frameId, worldName = "__sb") {
     let frame = frameId;
     if (!frame) {
@@ -1255,14 +1271,18 @@ var CdpSession = class _CdpSession {
     }
     return this.#client.sendInput(this.#profileId, { ...body, humanize: true });
   }
-  async #isolatedContext() {
-    if (this.#isolatedContextId === void 0) this.#isolatedContextId = await this.createIsolatedWorld();
-    return this.#isolatedContextId;
-  }
+  // The poll reads in an isolated world: a page that wraps `document.readyState`
+  // sees a read from its own world, with a caller that is none of its scripts.
+  // While the new document commits, the world of the old one can vanish between
+  // asking for it and reading in it; the browser refuses that read with its own
+  // error code, and it is retried. A closed connection still fails at once.
   async #waitForLoad(timeout) {
     const deadline = Date.now() + timeout;
     for (; ; ) {
-      const ready = await this.evaluate("document.readyState");
+      const ready = await this.evaluate("document.readyState", { isolated: true }).catch((err) => {
+        if (err instanceof CdpError && err.code !== -1) return void 0;
+        throw err;
+      });
       if (ready === "complete") return;
       if (Date.now() > deadline) throw new CdpError(-1, "navigation wait timed out");
       await delay(50);
@@ -1659,6 +1679,24 @@ var ScalebrowserClient = class extends ClientCore {
   async setExitRule(enabled, signal) {
     return this.request("PUT", "/v1/exit-rule", { enabled }, { signal });
   }
+  /**
+   * Which optional MCP tool groups agents on this machine see.
+   *
+   * Agents see the basic tools by default; video, tasks, profile management,
+   * the captcha helpers, the extras and the developer tools are one switch each.
+   */
+  async getAgentTools(signal) {
+    return this.request("GET", "/v1/agent-tools", void 0, { signal });
+  }
+  /**
+   * Turn one tool group on or off for every agent on this machine.
+   *
+   * It applies to the next tool list an agent asks for. A session that listed
+   * its tools before keeps that list until it reconnects.
+   */
+  async setAgentToolGroup(group, enabled, signal) {
+    return this.request("PUT", "/v1/agent-tools", { group, enabled }, { signal });
+  }
   // ── Events (SSE) ───────────────────────────────────────────────────────────
   /** Subscribe to lifecycle events. Returns an unsubscribe function. */
   subscribeEvents(handlers) {
@@ -1732,6 +1770,6 @@ var PROXY_KINDS = ["http", "socks5", "gateway"];
 var ROTATIONS = ["sticky", "rotating"];
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.2.0";
 
 export { ApiError, CdpError, CdpSession, DEFAULT_CAPACITY, ErrorCode, GEO_MODES, NetworkError, PROXY_KINDS, ROTATIONS, RUNTIME_STATES, ScalebrowserClient, ScalebrowserError, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebrowser/sdk",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Official Node/TypeScript SDK for the Scalebrowser daemon: typed REST client plus a direct-CDP driver plane (nodriver-style, not Playwright).",
   "type": "module",
   "license": "MIT",