@scalebrowser/sdk 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -294,6 +294,17 @@ var ControlApi = class extends ClientCore {
       throw err;
     }
   }
+  /**
+   * Which installation answered: its data directory and its binary.
+   *
+   * `health()` tells you something is there. This tells you WHAT, and the two are
+   * different questions whenever a machine holds more than one installation. The
+   * data directory is the identity; the address is not, because a port is a
+   * preference and a stale `runtime.json` can name one that moved.
+   */
+  getConnection(signal) {
+    return this.request("GET", "/v1/connection", void 0, { signal });
+  }
   /** "Is the daemon alive?" Public, needs no token. */
   health(signal) {
     return this.request("GET", "/health", void 0, { signal });
@@ -1524,6 +1535,7 @@ var ScalebrowserClient = class extends ClientCore {
     );
   }
   // ── Proxies (credentials write-only) ────────────────────────────────────────
+  /** The list carries `used_by` per row; `getProxy` below does not. */
   listProxies(signal) {
     return this.request("GET", "/v1/proxies", void 0, { signal });
   }
@@ -1615,6 +1627,27 @@ var ScalebrowserClient = class extends ClientCore {
   async setRemoteAccess(enabled, signal) {
     return this.request("PUT", "/v1/remote", { enabled }, { signal });
   }
+  // ── Exit-address exclusivity (the machine's own switch) ─────────────────────
+  /**
+   * Does one exit address belong to one profile on this machine?
+   *
+   * Local like the remote-access switch above, and here for the same reason: on
+   * a headless install there is no UI to click, and setting up fifty machines by
+   * hand is not setting them up.
+   */
+  async getExitRule(signal) {
+    return this.request("GET", "/v1/exit-rule", void 0, { signal });
+  }
+  /**
+   * Turn the exit-address rule on or off for this machine.
+   *
+   * Off means two of your profiles can leave over the same address. Reach for it
+   * when the provider hands out ONE address on purpose; a per-profile switch
+   * exists for the narrower case (`updateProfile` with `exit_exclusive`).
+   */
+  async setExitRule(enabled, signal) {
+    return this.request("PUT", "/v1/exit-rule", { enabled }, { signal });
+  }
   // ── Events (SSE) ───────────────────────────────────────────────────────────
   /** Subscribe to lifecycle events. Returns an unsubscribe function. */
   subscribeEvents(handlers) {
@@ -1689,7 +1722,7 @@ var PROXY_KINDS = ["http", "socks5", "gateway"];
 var ROTATIONS = ["sticky", "rotating"];
 
 // src/index.ts
-var VERSION = "0.6.0";
+var VERSION = "0.7.0";
 
 exports.ApiError = ApiError;
 exports.CdpError = CdpError;

package/dist/index.d.cts

@@ -384,13 +384,20 @@ interface ShareLinkLocal {
 /**
  * Wire types: a 1:1 mirror of the daemon's serialized domain model
  * (`crates/core/src/model.rs`, `persona.rs`, `events.rs`) and the endpoint
- * contract in `docs/features/api.md`. Mirrored against `web-ui/src/api/types/`
- * (a directory of split files behind the `web-ui/src/api/types.ts` barrel), and
- * that mirror is ENFORCED: `web-ui/src/test/sdk-type-mirror.test.ts` compares
- * every shared exported declaration and goes red on drift. The Python SDK
- * (`sdks/python/src/scalebrowser/models*.py`) carries the same shapes by hand,
+ * contract in `docs/features/api.md`.
+ *
+ * THIS IS THE SOURCE, and since 2026-09-09 it is the only one on the TypeScript
+ * side: `web-ui/src/api/types.ts` re-exports these files through the
+ * `@scalebrowser/wire/*` alias instead of keeping a second copy (Decision 022).
+ * Before that the same 160 declarations stood twice, and each header named the
+ * other as the truth. The Python SDK
+ * (`sdks/python/src/scalebrowser/models*.py`) still carries the shapes by hand,
  * deliberately without a gate; a TS↔pydantic comparator is its own tool.
  *
+ * These files import nothing but each other, and that is load-bearing rather
+ * than tidy: the web-ui pulls them into a BROWSER bundle. A guard in
+ * `web-ui/src/test/sdk-type-mirror.test.ts` holds the property.
+ *
  * All Rust enums serialize `snake_case` (serde `rename_all`). Timestamps are
  * unix seconds (`number`, Rust `i64`). The truth for any disagreement is the
  * UNION of the Rust route shapes, never one serde struct (create/delete answer
@@ -442,6 +449,16 @@ interface Profile {
     proxy_id: string | null;
     geo_mode: GeoMode;
     expected_country: string | null;
+    /**
+     * Whether this profile claims its exit address for itself, so no other profile of
+     * the account starts on it (DEC-017). On for a new profile. Turn it off for a
+     * provider that hands out ONE address on purpose, a residential line you pay for
+     * or a whitelisted office address, where the rule would refuse every start after
+     * the first.
+     *
+     * Additive: a daemon predating it omits the field.
+     */
+    exit_exclusive?: boolean;
     data_dir: string;
     created_at: number;
     last_open_at: number | null;
@@ -718,12 +735,54 @@ interface Proxy {
     host: string;
     port: number;
     rotation: Rotation;
+    /**
+     * The operator's own name for this row, or `null` if they never gave one.
+     *
+     * The only field that tells two rows of one provider pool apart: kind, host,
+     * port and rotation are identical across a bought gateway, and the session tag
+     * that actually differs sits in the write-only username. Do not fall back to
+     * `last_exit_ip` for identity; the health check wrote it hours or days ago and
+     * a rotating exit no longer has that address.
+     */
+    label: string | null;
     last_exit_ip: string | null;
     last_country: string | null;
+    /**
+     * The operator string the geo probe answered with, for example
+     * `"AS21928 T-Mobile USA, Inc."`. Part of the same measurement as the fields
+     * around it: one check writes them, an endpoint change clears them together.
+     * The daemon derives the address kind from it, which decides how long an
+     * address stays reserved for a profile.
+     */
+    last_asn: string | null;
     last_check_at: number | null;
     healthy: boolean | null;
+    /** Round-trip latency of the last health check, in ms. */
+    last_latency_ms: number | null;
+    /**
+     * The row holds credentials that could not be decrypted (a database restored
+     * without its master key). Every launch through it fails closed, so a screen
+     * that shows only `healthy` paints such a row green while nothing can use it.
+     * Omitted by the daemon when false.
+     */
+    credentials_unreadable?: boolean;
     created_at: number;
 }
+/**
+ * Who depends on one proxy, as `GET /v1/proxies` reports it per row.
+ *
+ * `count` is exact, `names` holds at most three. A proxy shared by a fleet must
+ * not drag every profile name into the listing, so showing the names without the
+ * count would turn "three of forty" into "these three".
+ */
+interface ProxyUsage {
+    count: number;
+    names: string[];
+}
+/** A row of the proxy LIST: the proxy plus who uses it. The single GET has no `used_by`. */
+interface ProxyRow extends Proxy {
+    used_by: ProxyUsage;
+}
 /** Per-detector outcome; `skip` means the page could not be evaluated, NOT a pass. */
 type AuditVerdict = 'pass' | 'warn' | 'fail' | 'skip' | 'error';
 interface AuditDetectorReport {
@@ -889,7 +948,8 @@ interface ExitStatus {
 /**
  * The per-profile task list and the profile's own durable memory.
  *
- * Mirrors `web-ui/src/api/types/tasks.ts`, the shared source of contract truth.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022).
  */
 /**
  * Where a task stands.
@@ -1218,8 +1278,8 @@ declare function eventStream(params: StreamParams): AsyncIterableIterator<Lifecy
  * What the browser asks (interruptions), the bytes that go in and out
  * (artifacts), and what the licence says (account).
  *
- * Interruption shapes mirror `web-ui/src/api/types/credentials.ts`, the shared
- * source of contract truth.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022).
  */
 /** What an operator has taken out of an agent's hands. */
 type InterruptionLock = 'always_block' | 'always_allow' | 'agent_decides';
@@ -1291,6 +1351,32 @@ interface ArtifactBytes {
     /** Parsed out of `Content-Disposition`, when the daemon sent one. */
     filename: string | null;
 }
+/**
+ * Which installation this daemon is: the data directory it serves and the binary
+ * it runs from.
+ *
+ * One machine can hold several installations, and they are told apart by their
+ * data directory, never by their address. A port is a preference: the desktop app
+ * takes the first free one from 8787, and a `runtime.json` left behind by an
+ * earlier daemon can name a port that something else now holds. Ask this before
+ * assuming the daemon you reached is the one you meant.
+ */
+interface Connection {
+    /** The address the native API is bound to, as resolved. */
+    native_addr: string;
+    /** The data directory, in a form suitable for showing or for a command line. */
+    data_dir: string;
+    /**
+     * The same directory, in the form two daemons compare. Case is folded on
+     * Windows and links are resolved, so do not show this one to anybody; compare
+     * it with another daemon's value and nothing else.
+     */
+    data_dir_key: string;
+    /** Absolute path of the running binary, for a client that launches it over stdio. */
+    executable?: string;
+    /** The AdsPower-compatible adapter's address, when that adapter is enabled. */
+    adspower_addr?: string;
+}
 /**
  * Licence state, for display.
  *
@@ -1344,6 +1430,27 @@ interface RemoteStatus {
      *  whatever the switch says. */
     ready: boolean;
 }
+/**
+ * What `GET /v1/exit-rule` answers: the machine's own exit-address exclusivity
+ * switch.
+ *
+ * On by default. Turn it off for a provider that hands out ONE address on
+ * purpose, a residential line you pay for or a whitelisted office address, where
+ * the rule would refuse every start after the first.
+ */
+interface ExitRuleStatus {
+    /** Does the rule apply on this machine? */
+    enabled: boolean;
+    /** Did a person decide this, or is the configured default still standing? */
+    explicit: boolean;
+    /**
+     * How many profiles switched the rule off for themselves.
+     *
+     * A global "on" reads as "every profile is separated", and that stops being
+     * true the moment one profile has its own switch off.
+     */
+    profiles_opted_out: number;
+}
 
 interface ScalebrowserClientOptions {
     /** Daemon base URL. Default `http://127.0.0.1:8787`. */
@@ -1411,6 +1518,15 @@ declare class ControlApi extends ClientCore {
      * connected or permitted. Same shape of tolerance as {@link getMetrics}.
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
+    /**
+     * Which installation answered: its data directory and its binary.
+     *
+     * `health()` tells you something is there. This tells you WHAT, and the two are
+     * different questions whenever a machine holds more than one installation. The
+     * data directory is the identity; the address is not, because a port is a
+     * preference and a stale `runtime.json` can name one that moved.
+     */
+    getConnection(signal?: AbortSignal): Promise<Connection>;
     /** "Is the daemon alive?" Public, needs no token. */
     health(signal?: AbortSignal): Promise<HealthStatus>;
     /** "Can it serve?" Local facts only; the control plane is deliberately not consulted. */
@@ -1453,6 +1569,21 @@ interface CreateProfileBody {
     host_mode?: HostMode;
     geo_mode?: GeoMode;
     expected_country?: string | null;
+    /**
+     * Draw the identity for this region (ISO-3166 alpha-2, e.g. `"DE"`): language,
+     * timezone and speech voices come out of one row of the model together. Omit to
+     * draw unconstrained, weighted the way the population is.
+     *
+     * This is not `expected_country`, which only checks the exit and never touches
+     * the identity. And it is a starting value, not a promise: under the default
+     * `geo_mode` the launch rewrites the region to the country the profile really
+     * exits in, which is its proxy's, or with no proxy the machine's own. The
+     * daemon refuses the pairings where that collision is already known.
+     *
+     * Set only at create. A region the model cannot draw is a 400 listing the ones
+     * it can.
+     */
+    persona_country?: string;
     group_id?: string | null;
     proxy_id?: string | null;
 }
@@ -1461,7 +1592,14 @@ interface CreateProfileBody {
  * time (C4/C5): a DIFFERING `host_mode` is refused with 400, an unchanged echo is
  * accepted. Changing a tier requires delete + recreate.
  */
-type UpdateProfileBody = Omit<Partial<CreateProfileBody>, "host_mode" | "seed">;
+type UpdateProfileBody = Omit<Partial<CreateProfileBody>, "host_mode" | "seed" | "persona_country"> & {
+    /**
+     * Turn the exit-address rule off for this profile (DEC-017). Deliberately not
+     * part of `CreateProfileBody`: a new profile always claims its address, and
+     * switching that off is a later, deliberate act for a setup that needs it.
+     */
+    exit_exclusive?: boolean;
+};
 interface StartProfileBody {
     headless?: boolean;
 }
@@ -1510,6 +1648,12 @@ interface CreateProxyBody {
     username?: string | null;
     password?: string | null;
     rotation?: Rotation;
+    /**
+     * The operator's own name for the row. Trimmed by the daemon; a blank string is
+     * stored as null. On an update the field carries three states: omit the key to
+     * leave the name alone, send `null` to clear it, send a string to set it.
+     */
+    label?: string | null;
 }
 type UpdateProxyBody = Partial<CreateProxyBody>;
 /**
@@ -1646,9 +1790,10 @@ declare class ExtensionsApi extends ClientCore {
  * The account layer: mailboxes, passkeys and the one door a cookie value leaves
  * through.
  *
- * Mailbox and passkey shapes mirror `web-ui/src/api/types/{inboxes,credentials}.ts`,
- * the shared source of contract truth. The cookie reveal has no UI counterpart:
- * it is a REST-only route deliberately kept off every screen.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022). The cookie
+ * reveal has no UI counterpart: it is a REST-only route deliberately kept off
+ * every screen.
  */
 /** One configured mailbox. The password is never sent back. */
 interface Inbox {
@@ -2051,7 +2196,8 @@ declare class TasksApi extends ClientCore {
  * the live event stream carries them, and the run list describes the same rows.
  * A second copy would let the two drift apart while both looked right.
  *
- * Mirrors `web-ui/src/api/types/runs.ts`, the shared source of contract truth.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022).
  */
 
 /** Who made the outcome claim. `derived` means nobody did. */
@@ -2511,7 +2657,8 @@ declare class ScalebrowserClient extends ClientCore {
      * drifts the moment that model changes and every create 400s.
      */
     getPersonaConstraints(signal?: AbortSignal): Promise<PersonaConstraintOptions>;
-    listProxies(signal?: AbortSignal): Promise<Proxy[]>;
+    /** The list carries `used_by` per row; `getProxy` below does not. */
+    listProxies(signal?: AbortSignal): Promise<ProxyRow[]>;
     getProxy(id: string, signal?: AbortSignal): Promise<Proxy>;
     createProxy(body: CreateProxyBody): Promise<Proxy>;
     updateProxy(id: string, body: UpdateProxyBody): Promise<Proxy>;
@@ -2549,6 +2696,22 @@ declare class ScalebrowserClient extends ClientCore {
     getRemoteAccess(signal?: AbortSignal): Promise<RemoteStatus>;
     /** Turn remote access on or off for this machine. */
     setRemoteAccess(enabled: boolean, signal?: AbortSignal): Promise<RemoteStatus>;
+    /**
+     * Does one exit address belong to one profile on this machine?
+     *
+     * Local like the remote-access switch above, and here for the same reason: on
+     * a headless install there is no UI to click, and setting up fifty machines by
+     * hand is not setting them up.
+     */
+    getExitRule(signal?: AbortSignal): Promise<ExitRuleStatus>;
+    /**
+     * Turn the exit-address rule on or off for this machine.
+     *
+     * Off means two of your profiles can leave over the same address. Reach for it
+     * when the provider hands out ONE address on purpose; a per-profile switch
+     * exists for the narrower case (`updateProfile` with `exit_exclusive`).
+     */
+    setExitRule(enabled: boolean, signal?: AbortSignal): Promise<ExitRuleStatus>;
     /** Subscribe to lifecycle events. Returns an unsubscribe function. */
     subscribeEvents(handlers: StreamHandlers): () => void;
     /** `for await (const event of client.events())` over lifecycle events. */
@@ -2661,6 +2824,6 @@ declare function errorMessage(err: unknown): string;
  * ```
  */
 
-declare const VERSION = "0.6.0";
+declare const VERSION = "0.7.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 CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, HOST_MODES, type HealthStatus, type HostMode, 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, 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 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, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, 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, HOST_MODES, type HealthStatus, type HostMode, 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 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 };

package/dist/index.d.ts

@@ -384,13 +384,20 @@ interface ShareLinkLocal {
 /**
  * Wire types: a 1:1 mirror of the daemon's serialized domain model
  * (`crates/core/src/model.rs`, `persona.rs`, `events.rs`) and the endpoint
- * contract in `docs/features/api.md`. Mirrored against `web-ui/src/api/types/`
- * (a directory of split files behind the `web-ui/src/api/types.ts` barrel), and
- * that mirror is ENFORCED: `web-ui/src/test/sdk-type-mirror.test.ts` compares
- * every shared exported declaration and goes red on drift. The Python SDK
- * (`sdks/python/src/scalebrowser/models*.py`) carries the same shapes by hand,
+ * contract in `docs/features/api.md`.
+ *
+ * THIS IS THE SOURCE, and since 2026-09-09 it is the only one on the TypeScript
+ * side: `web-ui/src/api/types.ts` re-exports these files through the
+ * `@scalebrowser/wire/*` alias instead of keeping a second copy (Decision 022).
+ * Before that the same 160 declarations stood twice, and each header named the
+ * other as the truth. The Python SDK
+ * (`sdks/python/src/scalebrowser/models*.py`) still carries the shapes by hand,
  * deliberately without a gate; a TS↔pydantic comparator is its own tool.
  *
+ * These files import nothing but each other, and that is load-bearing rather
+ * than tidy: the web-ui pulls them into a BROWSER bundle. A guard in
+ * `web-ui/src/test/sdk-type-mirror.test.ts` holds the property.
+ *
  * All Rust enums serialize `snake_case` (serde `rename_all`). Timestamps are
  * unix seconds (`number`, Rust `i64`). The truth for any disagreement is the
  * UNION of the Rust route shapes, never one serde struct (create/delete answer
@@ -442,6 +449,16 @@ interface Profile {
     proxy_id: string | null;
     geo_mode: GeoMode;
     expected_country: string | null;
+    /**
+     * Whether this profile claims its exit address for itself, so no other profile of
+     * the account starts on it (DEC-017). On for a new profile. Turn it off for a
+     * provider that hands out ONE address on purpose, a residential line you pay for
+     * or a whitelisted office address, where the rule would refuse every start after
+     * the first.
+     *
+     * Additive: a daemon predating it omits the field.
+     */
+    exit_exclusive?: boolean;
     data_dir: string;
     created_at: number;
     last_open_at: number | null;
@@ -718,12 +735,54 @@ interface Proxy {
     host: string;
     port: number;
     rotation: Rotation;
+    /**
+     * The operator's own name for this row, or `null` if they never gave one.
+     *
+     * The only field that tells two rows of one provider pool apart: kind, host,
+     * port and rotation are identical across a bought gateway, and the session tag
+     * that actually differs sits in the write-only username. Do not fall back to
+     * `last_exit_ip` for identity; the health check wrote it hours or days ago and
+     * a rotating exit no longer has that address.
+     */
+    label: string | null;
     last_exit_ip: string | null;
     last_country: string | null;
+    /**
+     * The operator string the geo probe answered with, for example
+     * `"AS21928 T-Mobile USA, Inc."`. Part of the same measurement as the fields
+     * around it: one check writes them, an endpoint change clears them together.
+     * The daemon derives the address kind from it, which decides how long an
+     * address stays reserved for a profile.
+     */
+    last_asn: string | null;
     last_check_at: number | null;
     healthy: boolean | null;
+    /** Round-trip latency of the last health check, in ms. */
+    last_latency_ms: number | null;
+    /**
+     * The row holds credentials that could not be decrypted (a database restored
+     * without its master key). Every launch through it fails closed, so a screen
+     * that shows only `healthy` paints such a row green while nothing can use it.
+     * Omitted by the daemon when false.
+     */
+    credentials_unreadable?: boolean;
     created_at: number;
 }
+/**
+ * Who depends on one proxy, as `GET /v1/proxies` reports it per row.
+ *
+ * `count` is exact, `names` holds at most three. A proxy shared by a fleet must
+ * not drag every profile name into the listing, so showing the names without the
+ * count would turn "three of forty" into "these three".
+ */
+interface ProxyUsage {
+    count: number;
+    names: string[];
+}
+/** A row of the proxy LIST: the proxy plus who uses it. The single GET has no `used_by`. */
+interface ProxyRow extends Proxy {
+    used_by: ProxyUsage;
+}
 /** Per-detector outcome; `skip` means the page could not be evaluated, NOT a pass. */
 type AuditVerdict = 'pass' | 'warn' | 'fail' | 'skip' | 'error';
 interface AuditDetectorReport {
@@ -889,7 +948,8 @@ interface ExitStatus {
 /**
  * The per-profile task list and the profile's own durable memory.
  *
- * Mirrors `web-ui/src/api/types/tasks.ts`, the shared source of contract truth.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022).
  */
 /**
  * Where a task stands.
@@ -1218,8 +1278,8 @@ declare function eventStream(params: StreamParams): AsyncIterableIterator<Lifecy
  * What the browser asks (interruptions), the bytes that go in and out
  * (artifacts), and what the licence says (account).
  *
- * Interruption shapes mirror `web-ui/src/api/types/credentials.ts`, the shared
- * source of contract truth.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022).
  */
 /** What an operator has taken out of an agent's hands. */
 type InterruptionLock = 'always_block' | 'always_allow' | 'agent_decides';
@@ -1291,6 +1351,32 @@ interface ArtifactBytes {
     /** Parsed out of `Content-Disposition`, when the daemon sent one. */
     filename: string | null;
 }
+/**
+ * Which installation this daemon is: the data directory it serves and the binary
+ * it runs from.
+ *
+ * One machine can hold several installations, and they are told apart by their
+ * data directory, never by their address. A port is a preference: the desktop app
+ * takes the first free one from 8787, and a `runtime.json` left behind by an
+ * earlier daemon can name a port that something else now holds. Ask this before
+ * assuming the daemon you reached is the one you meant.
+ */
+interface Connection {
+    /** The address the native API is bound to, as resolved. */
+    native_addr: string;
+    /** The data directory, in a form suitable for showing or for a command line. */
+    data_dir: string;
+    /**
+     * The same directory, in the form two daemons compare. Case is folded on
+     * Windows and links are resolved, so do not show this one to anybody; compare
+     * it with another daemon's value and nothing else.
+     */
+    data_dir_key: string;
+    /** Absolute path of the running binary, for a client that launches it over stdio. */
+    executable?: string;
+    /** The AdsPower-compatible adapter's address, when that adapter is enabled. */
+    adspower_addr?: string;
+}
 /**
  * Licence state, for display.
  *
@@ -1344,6 +1430,27 @@ interface RemoteStatus {
      *  whatever the switch says. */
     ready: boolean;
 }
+/**
+ * What `GET /v1/exit-rule` answers: the machine's own exit-address exclusivity
+ * switch.
+ *
+ * On by default. Turn it off for a provider that hands out ONE address on
+ * purpose, a residential line you pay for or a whitelisted office address, where
+ * the rule would refuse every start after the first.
+ */
+interface ExitRuleStatus {
+    /** Does the rule apply on this machine? */
+    enabled: boolean;
+    /** Did a person decide this, or is the configured default still standing? */
+    explicit: boolean;
+    /**
+     * How many profiles switched the rule off for themselves.
+     *
+     * A global "on" reads as "every profile is separated", and that stops being
+     * true the moment one profile has its own switch off.
+     */
+    profiles_opted_out: number;
+}
 
 interface ScalebrowserClientOptions {
     /** Daemon base URL. Default `http://127.0.0.1:8787`. */
@@ -1411,6 +1518,15 @@ declare class ControlApi extends ClientCore {
      * connected or permitted. Same shape of tolerance as {@link getMetrics}.
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
+    /**
+     * Which installation answered: its data directory and its binary.
+     *
+     * `health()` tells you something is there. This tells you WHAT, and the two are
+     * different questions whenever a machine holds more than one installation. The
+     * data directory is the identity; the address is not, because a port is a
+     * preference and a stale `runtime.json` can name one that moved.
+     */
+    getConnection(signal?: AbortSignal): Promise<Connection>;
     /** "Is the daemon alive?" Public, needs no token. */
     health(signal?: AbortSignal): Promise<HealthStatus>;
     /** "Can it serve?" Local facts only; the control plane is deliberately not consulted. */
@@ -1453,6 +1569,21 @@ interface CreateProfileBody {
     host_mode?: HostMode;
     geo_mode?: GeoMode;
     expected_country?: string | null;
+    /**
+     * Draw the identity for this region (ISO-3166 alpha-2, e.g. `"DE"`): language,
+     * timezone and speech voices come out of one row of the model together. Omit to
+     * draw unconstrained, weighted the way the population is.
+     *
+     * This is not `expected_country`, which only checks the exit and never touches
+     * the identity. And it is a starting value, not a promise: under the default
+     * `geo_mode` the launch rewrites the region to the country the profile really
+     * exits in, which is its proxy's, or with no proxy the machine's own. The
+     * daemon refuses the pairings where that collision is already known.
+     *
+     * Set only at create. A region the model cannot draw is a 400 listing the ones
+     * it can.
+     */
+    persona_country?: string;
     group_id?: string | null;
     proxy_id?: string | null;
 }
@@ -1461,7 +1592,14 @@ interface CreateProfileBody {
  * time (C4/C5): a DIFFERING `host_mode` is refused with 400, an unchanged echo is
  * accepted. Changing a tier requires delete + recreate.
  */
-type UpdateProfileBody = Omit<Partial<CreateProfileBody>, "host_mode" | "seed">;
+type UpdateProfileBody = Omit<Partial<CreateProfileBody>, "host_mode" | "seed" | "persona_country"> & {
+    /**
+     * Turn the exit-address rule off for this profile (DEC-017). Deliberately not
+     * part of `CreateProfileBody`: a new profile always claims its address, and
+     * switching that off is a later, deliberate act for a setup that needs it.
+     */
+    exit_exclusive?: boolean;
+};
 interface StartProfileBody {
     headless?: boolean;
 }
@@ -1510,6 +1648,12 @@ interface CreateProxyBody {
     username?: string | null;
     password?: string | null;
     rotation?: Rotation;
+    /**
+     * The operator's own name for the row. Trimmed by the daemon; a blank string is
+     * stored as null. On an update the field carries three states: omit the key to
+     * leave the name alone, send `null` to clear it, send a string to set it.
+     */
+    label?: string | null;
 }
 type UpdateProxyBody = Partial<CreateProxyBody>;
 /**
@@ -1646,9 +1790,10 @@ declare class ExtensionsApi extends ClientCore {
  * The account layer: mailboxes, passkeys and the one door a cookie value leaves
  * through.
  *
- * Mailbox and passkey shapes mirror `web-ui/src/api/types/{inboxes,credentials}.ts`,
- * the shared source of contract truth. The cookie reveal has no UI counterpart:
- * it is a REST-only route deliberately kept off every screen.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022). The cookie
+ * reveal has no UI counterpart: it is a REST-only route deliberately kept off
+ * every screen.
  */
 /** One configured mailbox. The password is never sent back. */
 interface Inbox {
@@ -2051,7 +2196,8 @@ declare class TasksApi extends ClientCore {
  * the live event stream carries them, and the run list describes the same rows.
  * A second copy would let the two drift apart while both looked right.
  *
- * Mirrors `web-ui/src/api/types/runs.ts`, the shared source of contract truth.
+ * One of the files that ARE the contract; the web-ui reads them through
+ * `@scalebrowser/wire/*` rather than keeping a copy (Decision 022).
  */
 
 /** Who made the outcome claim. `derived` means nobody did. */
@@ -2511,7 +2657,8 @@ declare class ScalebrowserClient extends ClientCore {
      * drifts the moment that model changes and every create 400s.
      */
     getPersonaConstraints(signal?: AbortSignal): Promise<PersonaConstraintOptions>;
-    listProxies(signal?: AbortSignal): Promise<Proxy[]>;
+    /** The list carries `used_by` per row; `getProxy` below does not. */
+    listProxies(signal?: AbortSignal): Promise<ProxyRow[]>;
     getProxy(id: string, signal?: AbortSignal): Promise<Proxy>;
     createProxy(body: CreateProxyBody): Promise<Proxy>;
     updateProxy(id: string, body: UpdateProxyBody): Promise<Proxy>;
@@ -2549,6 +2696,22 @@ declare class ScalebrowserClient extends ClientCore {
     getRemoteAccess(signal?: AbortSignal): Promise<RemoteStatus>;
     /** Turn remote access on or off for this machine. */
     setRemoteAccess(enabled: boolean, signal?: AbortSignal): Promise<RemoteStatus>;
+    /**
+     * Does one exit address belong to one profile on this machine?
+     *
+     * Local like the remote-access switch above, and here for the same reason: on
+     * a headless install there is no UI to click, and setting up fifty machines by
+     * hand is not setting them up.
+     */
+    getExitRule(signal?: AbortSignal): Promise<ExitRuleStatus>;
+    /**
+     * Turn the exit-address rule on or off for this machine.
+     *
+     * Off means two of your profiles can leave over the same address. Reach for it
+     * when the provider hands out ONE address on purpose; a per-profile switch
+     * exists for the narrower case (`updateProfile` with `exit_exclusive`).
+     */
+    setExitRule(enabled: boolean, signal?: AbortSignal): Promise<ExitRuleStatus>;
     /** Subscribe to lifecycle events. Returns an unsubscribe function. */
     subscribeEvents(handlers: StreamHandlers): () => void;
     /** `for await (const event of client.events())` over lifecycle events. */
@@ -2661,6 +2824,6 @@ declare function errorMessage(err: unknown): string;
  * ```
  */
 
-declare const VERSION = "0.6.0";
+declare const VERSION = "0.7.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 CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, HOST_MODES, type HealthStatus, type HostMode, 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, 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 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, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, 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, HOST_MODES, type HealthStatus, type HostMode, 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 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 };

package/dist/index.js

@@ -288,6 +288,17 @@ var ControlApi = class extends ClientCore {
       throw err;
     }
   }
+  /**
+   * Which installation answered: its data directory and its binary.
+   *
+   * `health()` tells you something is there. This tells you WHAT, and the two are
+   * different questions whenever a machine holds more than one installation. The
+   * data directory is the identity; the address is not, because a port is a
+   * preference and a stale `runtime.json` can name one that moved.
+   */
+  getConnection(signal) {
+    return this.request("GET", "/v1/connection", void 0, { signal });
+  }
   /** "Is the daemon alive?" Public, needs no token. */
   health(signal) {
     return this.request("GET", "/health", void 0, { signal });
@@ -1518,6 +1529,7 @@ var ScalebrowserClient = class extends ClientCore {
     );
   }
   // ── Proxies (credentials write-only) ────────────────────────────────────────
+  /** The list carries `used_by` per row; `getProxy` below does not. */
   listProxies(signal) {
     return this.request("GET", "/v1/proxies", void 0, { signal });
   }
@@ -1609,6 +1621,27 @@ var ScalebrowserClient = class extends ClientCore {
   async setRemoteAccess(enabled, signal) {
     return this.request("PUT", "/v1/remote", { enabled }, { signal });
   }
+  // ── Exit-address exclusivity (the machine's own switch) ─────────────────────
+  /**
+   * Does one exit address belong to one profile on this machine?
+   *
+   * Local like the remote-access switch above, and here for the same reason: on
+   * a headless install there is no UI to click, and setting up fifty machines by
+   * hand is not setting them up.
+   */
+  async getExitRule(signal) {
+    return this.request("GET", "/v1/exit-rule", void 0, { signal });
+  }
+  /**
+   * Turn the exit-address rule on or off for this machine.
+   *
+   * Off means two of your profiles can leave over the same address. Reach for it
+   * when the provider hands out ONE address on purpose; a per-profile switch
+   * exists for the narrower case (`updateProfile` with `exit_exclusive`).
+   */
+  async setExitRule(enabled, signal) {
+    return this.request("PUT", "/v1/exit-rule", { enabled }, { signal });
+  }
   // ── Events (SSE) ───────────────────────────────────────────────────────────
   /** Subscribe to lifecycle events. Returns an unsubscribe function. */
   subscribeEvents(handlers) {
@@ -1683,6 +1716,6 @@ var PROXY_KINDS = ["http", "socks5", "gateway"];
 var ROTATIONS = ["sticky", "rotating"];
 
 // src/index.ts
-var VERSION = "0.6.0";
+var VERSION = "0.7.0";
 
 export { ApiError, CdpError, CdpSession, DEFAULT_CAPACITY, ErrorCode, GEO_MODES, HOST_MODES, NetworkError, PROXY_KINDS, ROTATIONS, RUNTIME_STATES, ScalebrowserClient, ScalebrowserError, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@scalebrowser/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Official Node/TypeScript SDK for the Scalebrowser daemon — typed REST client + direct-CDP driver plane (nodriver-style, not Playwright).",
   "type": "module",
   "license": "MIT",
   "homepage": "https://scalebrowser.net",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/blackdiamond6390/scalebrowser.git",
+    "url": "git+https://github.com/blackdiamond-labs/scalebrowser.git",
     "directory": "sdks/node"
   },
   "bugs": {