notte-sdk 1.9.7 → 1.10.1

package/dist/index.js

@@ -31,11 +31,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ActionExecutionError: () => ActionExecutionError,
-  Agent: () => Agent,
   AuthenticationError: () => AuthenticationError,
   CAPTCHA_SOLVE_TIMEOUT_MS: () => CAPTCHA_SOLVE_TIMEOUT_MS,
   CLUSTER_OVERLOAD_RETRY_DELAY_MS: () => CLUSTER_OVERLOAD_RETRY_DELAY_MS,
   CREDENTIAL_FIELDS: () => CREDENTIAL_FIELDS,
+  DEFAULT_MAX_RETRIES: () => DEFAULT_MAX_RETRIES,
   DEFAULT_NOTTE_API_URL: () => DEFAULT_NOTTE_API_URL,
   DEFAULT_REQUEST_TIMEOUT_MS: () => DEFAULT_REQUEST_TIMEOUT_MS,
   Encryption: () => Encryption,
@@ -70,12 +70,17 @@ __export(index_exports, {
   Session: () => Session,
   SessionFiles: () => SessionFiles,
   TIMEOUT_HEADER: () => TIMEOUT_HEADER,
+  accountChanges: () => accountChanges,
+  accountRuns: () => accountRuns,
   actions: () => actions,
   agentStart: () => agentStart,
   agentStatus: () => agentStatus,
   agentStop: () => agentStop,
   anythingStart: () => anythingStart,
+  attempts: () => attempts,
+  brandRetrieve: () => brandRetrieve,
   buildFetchScript: () => buildFetchScript,
+  changes: () => changes,
   checkForLatestVersion: () => checkForLatestVersion,
   client: () => client,
   connectLinkContext: () => connectLinkContext,
@@ -85,15 +90,23 @@ __export(index_exports, {
   connectLinkStatus: () => connectLinkStatus,
   connectLinkSubmit: () => connectLinkSubmit,
   connectPaymentWallet: () => connectPaymentWallet,
+  create: () => create,
   createClient: () => createClient2,
   createOrAppendCookiesToFile: () => createOrAppendCookiesToFile,
   createPayment: () => createPayment,
+  creditUsage: () => creditUsage,
   default: () => NotteClient3,
   deleteSecret: () => deleteSecret,
   deleteSessionFile: () => deleteSessionFile,
+  delete_: () => delete_,
+  deliveries: () => deliveries,
+  detail: () => detail,
   disconnectPaymentWallet: () => disconnectPaymentWallet,
   downloadRunPayload: () => downloadRunPayload,
   downloadSessionFile: () => downloadSessionFile,
+  executeSessionFile: () => executeSessionFile,
+  extractProductEndpoint: () => extractProductEndpoint,
+  fetchSpecializedData: () => fetchSpecializedData,
   functionCreate: () => functionCreate,
   functionDelete: () => functionDelete,
   functionDownloadUrl: () => functionDownloadUrl,
@@ -109,6 +122,7 @@ __export(index_exports, {
   functionScheduleSet: () => functionScheduleSet,
   functionUpdate: () => functionUpdate,
   getPayment: () => getPayment,
+  getPolicy: () => getPolicy,
   getRootDomain: () => getRootDomain,
   getScript: () => getScript,
   getSecret: () => getSecret,
@@ -116,13 +130,18 @@ __export(index_exports, {
   getUsage: () => getUsage,
   getUsageLogs: () => getUsageLogs,
   healthCheck: () => healthCheck,
+  history_: () => history_,
   installServerOwnedDialogPolicy: () => installServerOwnedDialogPolicy,
+  invalidate: () => invalidate,
   isCaptchaSolveAction: () => isCaptchaSolveAction,
   isValidMfaSecret: () => isValidMfaSecret,
+  limits: () => limits,
   listAgents: () => listAgents,
   listAuditEvents: () => listAuditEvents,
+  listDataApis: () => listDataApis,
   listFunctionRunsByFunctionId: () => listFunctionRunsByFunctionId,
   listFunctions: () => listFunctions,
+  listMonitors: () => listMonitors,
   listPersonas: () => listPersonas,
   listSecrets: () => listSecrets,
   listSessionFiles: () => listSessionFiles,
@@ -135,19 +154,20 @@ __export(index_exports, {
   mailboxSync: () => mailboxSync,
   mailboxUpdate: () => mailboxUpdate,
   managedAuthConnectLinkCreate: () => managedAuthConnectLinkCreate,
+  mapsSearch: () => mapsSearch,
+  newsSearch: () => newsSearch,
   observeServerOwnedDialog: () => observeServerOwnedDialog,
   pageExecute: () => pageExecute,
   pageObserve: () => pageObserve,
   pageScrape: () => pageScrape,
   pageScreenshot: () => pageScreenshot,
-  parseAgentStatusMessage: () => parseAgentStatusMessage,
+  peopleEnrich: () => peopleEnrich,
   personaCreate: () => personaCreate,
   personaDelete: () => personaDelete,
   personaEmailsList: () => personaEmailsList,
   personaGet: () => personaGet,
   personaSmsList: () => personaSmsList,
   personaUpdate: () => personaUpdate,
-  prepareAgentRequest: () => prepareAgentRequest,
   prepareRunPayloadUpload: () => prepareRunPayloadUpload,
   processScrapeResponse: () => processScrapeResponse,
   profileCookiesGet: () => profileCookiesGet,
@@ -157,18 +177,29 @@ __export(index_exports, {
   profileDuplicate: () => profileDuplicate,
   profileGet: () => profileGet,
   profileList: () => profileList,
+  profileStateSet: () => profileStateSet,
   readCookiesFile: () => readCookiesFile,
   readyCheck: () => readyCheck,
   responseFromEvaluated: () => responseFromEvaluated,
-  retry: () => retry,
+  retrieve: () => retrieve,
+  retrieveChange: () => retrieveChange,
+  retrieveDelivery: () => retrieveDelivery,
+  retrieveRun: () => retrieveRun,
+  retry: () => retry2,
+  retryWebhookDelivery: () => retry,
+  rotateSecret: () => rotateSecret,
+  runNow: () => runNow,
+  runs: () => runs,
   sanitizeFilename: () => sanitizeFilename,
   scrapeFromHtml: () => scrapeFromHtml,
+  scrapeSpecializedData: () => fetchSpecializedData,
   scrapeWebpage: () => scrapeWebpage,
   searchWeb: () => searchWeb,
   sessionAuthReadiness: () => sessionAuthReadiness,
   sessionCookiesGet: () => sessionCookiesGet,
   sessionCookiesSet: () => sessionCookiesSet,
   sessionDebugInfo: () => sessionDebugInfo,
+  sessionMouseReplay: () => sessionMouseReplay,
   sessionNetworkLogs: () => sessionNetworkLogs,
   sessionOffset: () => sessionOffset,
   sessionProfilePreview: () => sessionProfilePreview,
@@ -179,6 +210,9 @@ __export(index_exports, {
   sessionStop: () => sessionStop,
   startVersionCheck: () => startVersionCheck,
   storeSecret: () => storeSecret,
+  styleguideEndpoint: () => styleguideEndpoint,
+  summary: () => summary,
+  update: () => update,
   uploadSessionFile: () => uploadSessionFile,
   validateCredentials: () => validateCredentials,
   validateMfaSecret: () => validateMfaSecret,
@@ -192,12 +226,13 @@ __export(index_exports, {
   vaultCreditCardGet: () => vaultCreditCardGet,
   vaultCreditCardSet: () => vaultCreditCardSet,
   vaultDelete: () => vaultDelete,
-  vaultUpdate: () => vaultUpdate
+  vaultUpdate: () => vaultUpdate,
+  youtubeEndpoint: () => youtubeEndpoint
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var SDK_VERSION = true ? "1.9.7" : "dev";
+var SDK_VERSION = true ? "1.10.1" : "dev";
 var SDK_PACKAGE_NAME = true ? "notte-sdk" : "notte-sdk";
 
 // src/version-check.ts
@@ -1081,6 +1116,11 @@ var createClient = (config = {}) => {
     const { opts, url } = await beforeRequest(options);
     return createSseClient({
       ...opts,
+      // Request interceptors can replace fetch when the stream starts.
+      fetch: (input, init) => {
+        const transport = opts.fetch;
+        return transport(input, init);
+      },
       body: opts.body,
       method,
       onRequest: async (url2, init) => {
@@ -1168,11 +1208,6 @@ var sessionProfileSave = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
-var getSessionScript = (options) => (options.client ?? client).get({
-  security: [{ scheme: "bearer", type: "http" }],
-  url: "/sessions/{session_id}/workflow/code",
-  ...options
-});
 var sessionStop = (options) => (options.client ?? client).delete({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/sessions/{session_id}/stop",
@@ -1239,11 +1274,25 @@ var sessionNetworkLogs = (options) => (options.client ?? client).get({
   url: "/sessions/{session_id}/network/logs",
   ...options
 });
+var sessionMouseReplay = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/sessions/{session_id}/replay/mouse",
+  ...options
+});
 var sessionReplay = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/sessions/{session_id}/replay",
   ...options
 });
+var executeSessionFile = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/sessions/{session_id}/page/execute/file",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
 var listSessionFiles = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/sessions/{session_id}/files",
@@ -1269,35 +1318,6 @@ var downloadSessionFile = (options) => (options.client ?? client).get({
   url: "/sessions/{session_id}/files/{file_id}",
   ...options
 });
-var agentStart = (options) => (options.client ?? client).post({
-  security: [{ scheme: "bearer", type: "http" }],
-  url: "/agents/start",
-  ...options,
-  headers: {
-    "Content-Type": "application/json",
-    ...options.headers
-  }
-});
-var agentStatus = (options) => (options.client ?? client).get({
-  security: [{ scheme: "bearer", type: "http" }],
-  url: "/agents/{agent_id}",
-  ...options
-});
-var getScript = (options) => (options.client ?? client).get({
-  security: [{ scheme: "bearer", type: "http" }],
-  url: "/agents/{agent_id}/workflow/code",
-  ...options
-});
-var agentStop = (options) => (options.client ?? client).delete({
-  security: [{ scheme: "bearer", type: "http" }],
-  url: "/agents/{agent_id}/stop",
-  ...options
-});
-var listAgents = (options) => (options?.client ?? client).get({
-  security: [{ scheme: "bearer", type: "http" }],
-  url: "/agents",
-  ...options
-});
 var functionRuntimeHealth = (options) => (options?.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/functions/health",
@@ -1567,6 +1587,15 @@ var profileCookiesSet = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
+var profileStateSet = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/profiles/{profile_id}/state",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
 var profileList = (options) => (options?.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/profiles",
@@ -1761,6 +1790,215 @@ var searchWeb = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
+var summary = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/analytics",
+  ...options
+});
+var history_ = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/analytics/requests",
+  ...options
+});
+var detail = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/analytics/requests/{request_id}",
+  ...options
+});
+var invalidate = (options) => (options?.client ?? client).delete({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/cache",
+  ...options
+});
+var getPolicy = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/cache",
+  ...options
+});
+var brandRetrieve = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/brand/retrieve",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var extractProductEndpoint = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/products/extract",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var styleguideEndpoint = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/web/styleguide",
+  ...options
+});
+var mapsSearch = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/maps/search",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var listMonitors = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors",
+  ...options
+});
+var create = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var limits = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/limits",
+  ...options
+});
+var creditUsage = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/credit-usage",
+  ...options
+});
+var accountRuns = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/runs",
+  ...options
+});
+var accountChanges = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/changes",
+  ...options
+});
+var delete_ = (options) => (options.client ?? client).delete({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}",
+  ...options
+});
+var retrieve = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}",
+  ...options
+});
+var update = (options) => (options.client ?? client).patch({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var runNow = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}/run",
+  ...options
+});
+var runs = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}/runs",
+  ...options
+});
+var changes = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}/changes",
+  ...options
+});
+var retrieveRun = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}/runs/{run_id}",
+  ...options
+});
+var retrieveChange = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}/changes/{change_id}",
+  ...options
+});
+var rotateSecret = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/monitors/{monitor_id}/webhook/rotate-secret",
+  ...options
+});
+var deliveries = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/webhooks/deliveries",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var retrieveDelivery = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/webhooks/deliveries/{delivery_id}",
+  ...options
+});
+var attempts = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/webhooks/deliveries/{delivery_id}/attempts",
+  ...options
+});
+var retry = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/webhooks/deliveries/{delivery_id}/retry",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var peopleEnrich = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/people/enrich",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var newsSearch = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/news/search",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var fetchSpecializedData = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/web/fetch",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var youtubeEndpoint = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data/youtube/extract",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var listDataApis = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/data",
+  ...options
+});
 var scrapeFromHtml = (options) => (options.client ?? client).post({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/scrape_from_html",
@@ -1770,6 +2008,40 @@ var scrapeFromHtml = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
+var agentStart = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/agents/start",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var agentStop = (options) => (options.client ?? client).delete({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/agents/{agent_id}/stop",
+  ...options
+});
+var agentStatus = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/agents/{agent_id}",
+  ...options
+});
+var getScript = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/agents/{agent_id}/workflow/code",
+  ...options
+});
+var listAgents = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/agents",
+  ...options
+});
+var getSessionScript = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/sessions/{session_id}/workflow/code",
+  ...options
+});
 
 // src/managed-auth.ts
 var import_promises = require("timers/promises");
@@ -1854,14 +2126,14 @@ var ActionExecutionError = class _ActionExecutionError extends NotteError {
   agentMessage;
   shouldRetryLater;
   shouldNotifyTeam;
-  constructor(detail) {
-    super(detail.dev_message || detail.user_message || detail.error_type);
-    this.errorType = detail.error_type;
-    this.devMessage = detail.dev_message;
-    this.userMessage = detail.user_message;
-    this.agentMessage = detail.agent_message;
-    this.shouldRetryLater = detail.should_retry_later ?? false;
-    this.shouldNotifyTeam = detail.should_notify_team ?? false;
+  constructor(detail2) {
+    super(detail2.dev_message || detail2.user_message || detail2.error_type);
+    this.errorType = detail2.error_type;
+    this.devMessage = detail2.dev_message;
+    this.userMessage = detail2.user_message;
+    this.agentMessage = detail2.agent_message;
+    this.shouldRetryLater = detail2.should_retry_later ?? false;
+    this.shouldNotifyTeam = detail2.should_notify_team ?? false;
   }
   static fromMessage(message, errorType = "NotteBaseError") {
     return new _ActionExecutionError({
@@ -1892,7 +2164,7 @@ function normalizeErrorBody(body) {
   return { message: typeof body === "string" ? body : String(body) };
 }
 var DEFAULT_RETRY_MESSAGE = "An error occurred while executing the function. Try again later...";
-function retry(fn, options) {
+function retry2(fn, options) {
   const {
     maxTries,
     delayMs = 5e3,
@@ -1929,11 +2201,6 @@ function sleep(ms) {
 // src/managed-auth.ts
 var ManagedAuthError = class extends NotteError {
 };
-function validateAuthRetry(value) {
-  if (!Number.isInteger(value) || value < 0 || value > 2) {
-    throw new InvalidRequestError("auth_retry must be an integer between 0 and 2");
-  }
-}
 async function pollAuth(read, options) {
   const timeoutMs = options.timeoutMs ?? 615e3;
   const interval = options.pollIntervalMs ?? 1e3;
@@ -1974,6 +2241,7 @@ var NotteManagedAuth = class {
   constructor(client2) {
     this.client = client2;
   }
+  client;
   /** Run only the verifier; this does not submit login credentials. */
   async checkConnection(connectionId) {
     const response = await this.client.getClient().post({
@@ -2014,12 +2282,10 @@ var NotteManagedAuth = class {
     return this.run(connectionId, "reauthenticate", options);
   }
   async run(connectionId, action, options) {
-    const authRetry = options.auth_retry ?? 0;
-    validateAuthRetry(authRetry);
     options.signal?.throwIfAborted();
     const response = await this.client.getClient().post({
       url: `/managed-auth/connections/${encodeURIComponent(connectionId)}/${action}`,
-      body: { auth_retry: authRetry },
+      body: { auth_retry: options.auth_retry },
       headers: { "Content-Type": "application/json" },
       signal: options.signal,
       throwOnError: true
@@ -2054,7 +2320,7 @@ function createResources(client2, getApiKey) {
       },
       /** downloadSessionFile: /sessions/{session_id}/files/{file_id}. Returns the API response body. */
       downloadSessionFile: async (sessionId, fileId, requestOptions = {}) => {
-        const response = await downloadSessionFile({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId, "file_id": fileId } });
+        const response = await downloadSessionFile({ client: client2, throwOnError: true, signal: requestOptions.signal, parseAs: "blob", headers: { ...requestOptions.headers }, path: { "session_id": sessionId, "file_id": fileId } });
         return response.data;
       },
       /** pageExecute: /sessions/{session_id}/page/execute. Returns the API response body. */
@@ -2062,6 +2328,11 @@ function createResources(client2, getApiKey) {
         const response = await pageExecute({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, body, query });
         return response.data;
       },
+      /** executeSessionFile: /sessions/{session_id}/page/execute/file. Returns the API response body. */
+      executeSessionFile: async (sessionId, body, query = void 0, requestOptions = {}) => {
+        const response = await executeSessionFile({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, body, query });
+        return response.data;
+      },
       /** sessionCookiesGet: /sessions/{session_id}/cookies. Returns the API response body. */
       getCookies: async (sessionId, query = void 0, requestOptions = {}) => {
         const response = await sessionCookiesGet({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, query });
@@ -2082,6 +2353,11 @@ function createResources(client2, getApiKey) {
         const response = await listSessionFiles({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, query });
         return response.data;
       },
+      /** sessionMouseReplay: /sessions/{session_id}/replay/mouse. Returns the API response body. */
+      mouseReplay: async (sessionId, query = void 0, requestOptions = {}) => {
+        const response = await sessionMouseReplay({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, query });
+        return response.data;
+      },
       /** sessionNetworkLogs: /sessions/{session_id}/network/logs. Returns the API response body. */
       networkLogs: async (sessionId, query = void 0, requestOptions = {}) => {
         const response = await sessionNetworkLogs({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, query });
@@ -2107,16 +2383,16 @@ function createResources(client2, getApiKey) {
         const response = await sessionProfilePreview({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, query });
         return response.data;
       },
-      /** sessionProfileSave: /sessions/{session_id}/profile/save. Returns the API response body. */
-      profileSave: async (sessionId, body, requestOptions = {}) => {
-        const response = await sessionProfileSave({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, body });
-        return response.data;
-      },
       /** sessionReplay: /sessions/{session_id}/replay. Returns the API response body. */
       replay: async (sessionId, requestOptions = {}) => {
         const response = await sessionReplay({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId } });
         return response.data;
       },
+      /** sessionProfileSave: /sessions/{session_id}/profile/save. Returns the API response body. */
+      saveProfile: async (sessionId, body, requestOptions = {}) => {
+        const response = await sessionProfileSave({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, body });
+        return response.data;
+      },
       /** pageScrape: /sessions/{session_id}/page/scrape. Returns the API response body. */
       scrape: async (sessionId, body, query = void 0, requestOptions = {}) => {
         const response = await pageScrape({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, body, query });
@@ -2129,6 +2405,9 @@ function createResources(client2, getApiKey) {
       },
       /** sessionStart: /sessions/start. Returns the API response body. */
       start: async (body, requestOptions = {}) => {
+        body = { ...body };
+        if (body.record_session === true) delete body.record_session;
+        if (body.log_session === true) delete body.log_session;
         const response = await sessionStart({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, body });
         return response.data;
       },
@@ -2148,30 +2427,30 @@ function createResources(client2, getApiKey) {
         return response.data;
       }
     },
-    agents: {
-      /** getScript: /agents/{agent_id}/workflow/code. Returns the API response body. */
-      getScript: async (agentId, query, requestOptions = {}) => {
-        const response = await getScript({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "agent_id": agentId }, query });
+    files: {
+      /** deleteSessionFile: /sessions/{session_id}/files/{file_id}. Returns the API response body. */
+      delete: async (sessionId, fileId, requestOptions = {}) => {
+        const response = await deleteSessionFile({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId, "file_id": fileId } });
         return response.data;
       },
-      /** listAgents: /agents. Returns the API response body. */
-      list: async (query = void 0, requestOptions = {}) => {
-        const response = await listAgents({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, query });
+      /** downloadSessionFile: /sessions/{session_id}/files/{file_id}. Returns the API response body. */
+      download: async (sessionId, fileId, requestOptions = {}) => {
+        const response = await downloadSessionFile({ client: client2, throwOnError: true, signal: requestOptions.signal, parseAs: "blob", headers: { ...requestOptions.headers }, path: { "session_id": sessionId, "file_id": fileId } });
         return response.data;
       },
-      /** agentStart: /agents/start. Returns the API response body. */
-      start: async (body, requestOptions = {}) => {
-        const response = await agentStart({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, body });
+      /** executeSessionFile: /sessions/{session_id}/page/execute/file. Returns the API response body. */
+      execute: async (sessionId, body, query = void 0, requestOptions = {}) => {
+        const response = await executeSessionFile({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, body, query });
         return response.data;
       },
-      /** agentStatus: /agents/{agent_id}. Returns the API response body. */
-      status: async (agentId, requestOptions = {}) => {
-        const response = await agentStatus({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "agent_id": agentId } });
+      /** listSessionFiles: /sessions/{session_id}/files. Returns the API response body. */
+      list: async (sessionId, query = void 0, requestOptions = {}) => {
+        const response = await listSessionFiles({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, query });
         return response.data;
       },
-      /** agentStop: /agents/{agent_id}/stop. Returns the API response body. */
-      stop: async (agentId, query, requestOptions = {}) => {
-        const response = await agentStop({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "agent_id": agentId }, query });
+      /** uploadSessionFile: /sessions/{session_id}/files. Returns the API response body. */
+      upload: async (sessionId, body, requestOptions = {}) => {
+        const response = await uploadSessionFile({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "session_id": sessionId }, body });
         return response.data;
       }
     },
@@ -2252,8 +2531,8 @@ function createResources(client2, getApiKey) {
         return response.data;
       },
       /** functionRuntimeHealth: /functions/health. Returns the API response body. */
-      runtimeHealth: async (requestOptions = {}) => {
-        const response = await functionRuntimeHealth({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers } });
+      runtimeHealth: async (requestOptions = {}, query = void 0) => {
+        const response = await functionRuntimeHealth({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, query });
         return response.data;
       },
       /** functionScheduleSet: /functions/{function_id}/schedule. Returns the API response body. */
@@ -2267,6 +2546,43 @@ function createResources(client2, getApiKey) {
         return response.data;
       }
     },
+    personas: {
+      /** personaCreate: /personas/create. Returns the API response body. */
+      create: async (body, requestOptions = {}) => {
+        const response = await personaCreate({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, body });
+        return response.data;
+      },
+      /** personaDelete: /personas/{persona_id}. Returns the API response body. */
+      delete: async (personaId, requestOptions = {}) => {
+        const response = await personaDelete({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId } });
+        return response.data;
+      },
+      /** personaEmailsList: /personas/{persona_id}/emails. Returns the API response body. */
+      emailsList: async (personaId, query = void 0, requestOptions = {}) => {
+        const response = await personaEmailsList({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId }, query });
+        return response.data;
+      },
+      /** personaGet: /personas/{persona_id}. Returns the API response body. */
+      get: async (personaId, requestOptions = {}) => {
+        const response = await personaGet({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId } });
+        return response.data;
+      },
+      /** listPersonas: /personas. Returns the API response body. */
+      list: async (query = void 0, requestOptions = {}) => {
+        const response = await listPersonas({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, query });
+        return response.data;
+      },
+      /** personaSmsList: /personas/{persona_id}/sms. Returns the API response body. */
+      smsList: async (personaId, query = void 0, requestOptions = {}) => {
+        const response = await personaSmsList({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId }, query });
+        return response.data;
+      },
+      /** personaUpdate: /personas/{persona_id}. Returns the API response body. */
+      update: async (personaId, body, requestOptions = {}) => {
+        const response = await personaUpdate({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId }, body });
+        return response.data;
+      }
+    },
     vaults: {
       /** vaultCreate: /vaults/create. Returns the API response body. */
       create: async (body, requestOptions = {}) => {
@@ -2310,54 +2626,17 @@ function createResources(client2, getApiKey) {
       },
       /** vaultDelete: /vaults/{vault_id}. Returns the API response body. */
       delete: async (vaultId, requestOptions = {}) => {
-        const response = await vaultDelete({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "vault_id": vaultId } });
-        return response.data;
-      },
-      /** listVaults: /vaults. Returns the API response body. */
-      list: async (query = void 0, requestOptions = {}) => {
-        const response = await listVaults({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, query });
-        return response.data;
-      },
-      /** vaultUpdate: /vaults/{vault_id}. Returns the API response body. */
-      update: async (vaultId, body, requestOptions = {}) => {
-        const response = await vaultUpdate({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "vault_id": vaultId }, body });
-        return response.data;
-      }
-    },
-    personas: {
-      /** personaCreate: /personas/create. Returns the API response body. */
-      create: async (body, requestOptions = {}) => {
-        const response = await personaCreate({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, body });
-        return response.data;
-      },
-      /** personaDelete: /personas/{persona_id}. Returns the API response body. */
-      delete: async (personaId, requestOptions = {}) => {
-        const response = await personaDelete({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId } });
-        return response.data;
-      },
-      /** personaEmailsList: /personas/{persona_id}/emails. Returns the API response body. */
-      emailsList: async (personaId, query = void 0, requestOptions = {}) => {
-        const response = await personaEmailsList({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId }, query });
-        return response.data;
-      },
-      /** personaGet: /personas/{persona_id}. Returns the API response body. */
-      get: async (personaId, requestOptions = {}) => {
-        const response = await personaGet({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId } });
+        const response = await vaultDelete({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "vault_id": vaultId } });
         return response.data;
       },
-      /** listPersonas: /personas. Returns the API response body. */
+      /** listVaults: /vaults. Returns the API response body. */
       list: async (query = void 0, requestOptions = {}) => {
-        const response = await listPersonas({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, query });
-        return response.data;
-      },
-      /** personaSmsList: /personas/{persona_id}/sms. Returns the API response body. */
-      smsList: async (personaId, query = void 0, requestOptions = {}) => {
-        const response = await personaSmsList({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId }, query });
+        const response = await listVaults({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, query });
         return response.data;
       },
-      /** personaUpdate: /personas/{persona_id}. Returns the API response body. */
-      update: async (personaId, body, requestOptions = {}) => {
-        const response = await personaUpdate({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "persona_id": personaId }, body });
+      /** vaultUpdate: /vaults/{vault_id}. Returns the API response body. */
+      update: async (vaultId, body, requestOptions = {}) => {
+        const response = await vaultUpdate({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "vault_id": vaultId }, body });
         return response.data;
       }
     },
@@ -2396,6 +2675,11 @@ function createResources(client2, getApiKey) {
       list: async (query = void 0, requestOptions = {}) => {
         const response = await profileList({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, query });
         return response.data;
+      },
+      /** profileStateSet: /profiles/{profile_id}/state. Returns the API response body. */
+      stateSet: async (profileId, body, requestOptions = {}) => {
+        const response = await profileStateSet({ client: client2, throwOnError: true, signal: requestOptions.signal, headers: { ...requestOptions.headers }, path: { "profile_id": profileId }, body });
+        return response.data;
       }
     }
   };
@@ -2760,10 +3044,16 @@ async function createOrAppendCookiesToFile(cookieFile, cookies) {
         throw error;
       }
     }
-    existing.push(...cookies);
-    await (0, import_promises2.writeFile)(cookieFile, JSON.stringify(existing), "utf-8");
+    const merged = /* @__PURE__ */ new Map();
+    for (const cookie of [...existing, ...cookies]) {
+      merged.set(cookieIdentity(cookie), cookie);
+    }
+    await (0, import_promises2.writeFile)(cookieFile, JSON.stringify([...merged.values()]), "utf-8");
   });
 }
+function cookieIdentity(cookie) {
+  return JSON.stringify([cookie.name, cookie.domain ?? null, cookie.path ?? null, cookie.partitionKey ?? null]);
+}
 var fileLocks = /* @__PURE__ */ new Map();
 async function withFileLock(path, fn) {
   const key = (0, import_node_path.resolve)(path);
@@ -2922,8 +3212,8 @@ async function buildScrapeBody(options) {
     if (json_schema) {
       body.response_format = json_schema;
     } else {
-      const { z: z2 } = await import("zod");
-      body.response_format = normalizeJsonSchema(z2.toJSONSchema(response_format));
+      const { z } = await import("zod");
+      body.response_format = normalizeJsonSchema(z.toJSONSchema(response_format));
     }
   } else if (response_format) {
     body.response_format = response_format;
@@ -2935,9 +3225,6 @@ function processScrapeResponse(scrapeResponse, options) {
     throw new ScrapeFailedError("empty response");
   }
   const raiseOnFailure = options.raiseOnFailure ?? true;
-  if (options.only_images) {
-    return scrapeResponse.images ?? [];
-  }
   if (requiresSchema(options)) {
     const structured = scrapeResponse.structured;
     if (!structured) {
@@ -2960,10 +3247,126 @@ function processScrapeResponse(scrapeResponse, options) {
   return scrapeResponse.markdown;
 }
 
+// src/retry.ts
+var DEFAULT_MAX_RETRIES = 3;
+var RETRY_BASE_DELAY_MS = 1e3;
+var RETRY_MAX_DELAY_MS = 1e4;
+var RETRY_AFTER_MAX_MS = 2e4;
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);
+var REFUSED_STATUSES = /* @__PURE__ */ new Set([503, 529]);
+var GATEWAY_STATUSES = /* @__PURE__ */ new Set([502, 504]);
+var NOT_SENT_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "EAI_AGAIN",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+var BROKEN_CONNECTION_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "EPIPE",
+  "ETIMEDOUT",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CLOSED"
+]);
+function isIdempotentMethod(method) {
+  return IDEMPOTENT_METHODS.has(method.toUpperCase());
+}
+function isRetryableStatus(status, method) {
+  return REFUSED_STATUSES.has(status) || GATEWAY_STATUSES.has(status) && isIdempotentMethod(method);
+}
+function isRetryableNetworkError(error, method) {
+  const code = networkErrorCode(error);
+  if (code === void 0) return false;
+  return NOT_SENT_ERROR_CODES.has(code) || BROKEN_CONNECTION_ERROR_CODES.has(code) && isIdempotentMethod(method);
+}
+function networkErrorCode(error, depth = 0) {
+  if (typeof error !== "object" || error === null || depth > 4) return void 0;
+  const { code, cause, errors } = error;
+  if (typeof code === "string") return code;
+  if (Array.isArray(errors) && errors.length > 0) return networkErrorCode(errors[0], depth + 1);
+  return networkErrorCode(cause, depth + 1);
+}
+function parseRetryAfter(header, now = Date.now()) {
+  if (!header) return void 0;
+  const value = header.trim();
+  if (/^\d+(\.\d+)?$/.test(value)) return Number(value) * 1e3;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
+}
+function backoffDelayMs(attempt, random = Math.random) {
+  return random() * Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** attempt);
+}
+function retryDelayMs(attempt, retryAfter, random) {
+  const requested = parseRetryAfter(retryAfter);
+  if (requested === void 0) return backoffDelayMs(attempt, random);
+  return requested <= RETRY_AFTER_MAX_MS ? requested : void 0;
+}
+function createRetryingFetch(options) {
+  const wait2 = options.sleep ?? abortableSleep;
+  return async (input, init) => {
+    const baseFetch = options.fetch ?? globalThis.fetch;
+    const request = input instanceof Request ? input : void 0;
+    const method = (request?.method ?? init?.method ?? "GET").toUpperCase();
+    const signal = init?.signal ?? request?.signal;
+    const maxRetries = Math.max(0, Math.floor(options.maxRetries(signal) || 0));
+    const send = (last) => request && request.body !== null && !last ? baseFetch(request.clone(), init) : baseFetch(input, init);
+    for (let attempt = 0; ; attempt++) {
+      const last = attempt >= maxRetries;
+      let response;
+      try {
+        response = await send(last);
+      } catch (error) {
+        if (last || !isRetryableNetworkError(error, method)) throw error;
+        const delay4 = backoffDelayMs(attempt, options.random);
+        if (!fitsDeadline(delay4)) throw error;
+        warn(`${method} request failed (${networkErrorCode(error)})`, delay4, attempt, maxRetries);
+        await wait2(delay4, signal);
+        continue;
+      }
+      if (last || !isRetryableStatus(response.status, method)) return response;
+      const delay3 = retryDelayMs(attempt, response.headers.get("retry-after"), options.random);
+      if (delay3 === void 0 || !fitsDeadline(delay3)) return response;
+      await response.body?.cancel().catch(() => void 0);
+      warn(`${method} request returned ${response.status}`, delay3, attempt, maxRetries);
+      await wait2(delay3, signal);
+    }
+    function fitsDeadline(delay3) {
+      const deadline = options.deadline?.(signal);
+      return deadline === void 0 || Date.now() + delay3 < deadline;
+    }
+  };
+}
+function warn(reason, delay3, attempt, maxRetries) {
+  console.warn(`${reason}, retrying in ${(delay3 / 1e3).toFixed(1)}s (${attempt + 1}/${maxRetries})`);
+}
+function abortableSleep(ms, signal) {
+  return new Promise((resolve3, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve3();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/session.ts
 var SESSION_START_TRIES = 3;
 var CLUSTER_OVERLOAD_RETRY_DELAY_MS = 3e4;
 var CAPTCHA_SOLVE_TIMEOUT_MS = 1e5;
+var OBSERVE_MIGRATION_URL = "https://docs.notte.cc/features/sessions/observe-migration";
+var OBSERVE_DEPRECATIONS = {
+  instructions: `\`observe({ instructions })\` is deprecated and will be removed on December 1, 2026; <<ALTERNATIVE FOR instructions: session.act() \u2014 pending>>. See ${OBSERVE_MIGRATION_URL}`,
+  deep: `\`perception_type: 'deep'\` is deprecated and will be removed on December 1, 2026; use \`perception_type: 'fast'\` (the default). See ${OBSERVE_MIGRATION_URL}`
+};
 function observeServerOwnedDialog(_dialog) {
 }
 function installServerOwnedDialogPolicy(browser) {
@@ -2978,6 +3381,7 @@ var Session = class {
   legacyHeadless;
   defaultRaiseOnFailure;
   defaultPerceptionType;
+  warnedObserveDeprecations = /* @__PURE__ */ new Set();
   cookieFile;
   cookiesLoaded = false;
   cookieLoadPromise;
@@ -3013,9 +3417,11 @@ var Session = class {
   /**
    * Start the session: creates a new session on the server.
    *
-   * Retries up to `SESSION_START_TRIES` times on 5xx errors, waiting
-   * `CLUSTER_OVERLOAD_RETRY_DELAY_MS` on HTTP 529 (cluster overload). 4xx
-   * errors are never retried.
+   * 503, 529, and refused connections follow the client's retry policy
+   * (`NotteClientConfig.maxRetries`, honoring `Retry-After`). Other 5xx
+   * errors are retried up to `SESSION_START_TRIES` times. With client
+   * retries disabled, 529 waits `CLUSTER_OVERLOAD_RETRY_DELAY_MS` instead.
+   * 4xx errors are never retried.
    *
    * Managed-auth sessions wait for readiness by default. Pass
    * `{ wait_for_authentication: false }` for an explicit nonblocking start,
@@ -3028,11 +3434,6 @@ var Session = class {
    * await session.start();
    */
   async start(options = {}) {
-    if (this.legacyHeadless === false) {
-      throw new Error(
-        "Remote `headless: false` is no longer supported. `headless: true` sessions still include session replays and access to the live viewer."
-      );
-    }
     if (this.legacyHeadless === true) {
       console.warn("`headless: true` is deprecated and ignored; remote sessions always use the supported browser launch mode.");
       this.legacyHeadless = void 0;
@@ -3041,42 +3442,62 @@ var Session = class {
       throw new Error("Session is already active");
     }
     options.signal?.throwIfAborted();
-    validateAuthRetry(this.options.auth_retry ?? 0);
     const { auth_retry, wait_for_authentication, ...request } = this.options;
     const body = {
       ...request,
-      ...request.auth_ids?.length ? { auth_retry: auth_retry ?? 0, wait_for_authentication: false } : {}
+      ...this.legacyHeadless !== void 0 ? { headless: this.legacyHeadless } : {},
+      ...auth_retry !== void 0 ? { auth_retry } : {},
+      ...request.auth_ids?.length ? { wait_for_authentication: false } : {}
     };
+    if (body.record_session === true) delete body.record_session;
+    if (body.log_session === true) delete body.log_session;
     const shouldWait = options.wait_for_authentication ?? wait_for_authentication ?? true;
+    const maxRetries = this.client.getConfig().maxRetries ?? 0;
+    const timeoutMs = this.client.getConfig().timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : void 0;
+    const fitsDeadline = (wait2) => deadline === void 0 || Date.now() + wait2 < deadline;
+    let transientRetries = 0;
     let tries = SESSION_START_TRIES;
     const origTries = tries;
     let sessionData;
     while (tries > 0) {
       options.signal?.throwIfAborted();
-      tries -= 1;
+      if (!fitsDeadline(0)) throw new NotteTimeoutError(`Session start timed out after ${timeoutMs}ms`);
       try {
-        const response = await sessionStart({ client: this.client.getClient(), body, throwOnError: true });
+        const response = await sessionStart({
+          client: this.client.getClient(),
+          body,
+          throwOnError: true,
+          headers: {
+            [MAX_RETRIES_HEADER]: "0",
+            ...deadline === void 0 ? {} : { [TIMEOUT_HEADER]: String(Math.max(1, deadline - Date.now())) }
+          }
+        });
         sessionData = response.data;
         break;
       } catch (error) {
+        const transient = error instanceof NotteAPIError ? isRetryableStatus(error.statusCode, "POST") : isRetryableNetworkError(error, "POST");
+        if (maxRetries > 0 && transient) {
+          const wait2 = transientRetries >= maxRetries ? void 0 : error instanceof NotteAPIError ? retryDelayMs(transientRetries, error.response?.headers.get("retry-after")) : backoffDelayMs(transientRetries);
+          if (wait2 === void 0 || !fitsDeadline(wait2)) throw error;
+          transientRetries += 1;
+          console.warn(
+            `Failed to start session (${error instanceof NotteAPIError ? error.statusCode : "connection error"}), retrying in ${(wait2 / 1e3).toFixed(1)}s (${transientRetries}/${maxRetries})`
+          );
+          await pauseStart(wait2, options.signal);
+          continue;
+        }
+        tries -= 1;
         if (tries === 0 || !(error instanceof NotteAPIError) || error.statusCode < 500) {
           throw error;
         }
         const retryStr = `${origTries - tries}/${origTries - 1}`;
+        if (!fitsDeadline(error.statusCode === 529 ? CLUSTER_OVERLOAD_RETRY_DELAY_MS : 0)) throw error;
         if (error.statusCode === 529) {
           console.warn(
             `Failed to start session due to cluster overload, retrying in ${CLUSTER_OVERLOAD_RETRY_DELAY_MS / 1e3} seconds (${retryStr})...`
           );
-          if (options.signal) {
-            try {
-              await (0, import_promises4.setTimeout)(CLUSTER_OVERLOAD_RETRY_DELAY_MS, void 0, { signal: options.signal });
-            } catch (error2) {
-              options.signal.throwIfAborted();
-              throw error2;
-            }
-          } else {
-            await sleep(CLUSTER_OVERLOAD_RETRY_DELAY_MS);
-          }
+          await pauseStart(CLUSTER_OVERLOAD_RETRY_DELAY_MS, options.signal);
         } else {
           console.warn(`Failed to start session: retrying (${retryStr})`);
         }
@@ -3094,6 +3515,7 @@ var Session = class {
     this.fileStorage = this.fileStorage?.forSession(sessionData.session_id);
     try {
       options.signal?.throwIfAborted();
+      if (!fitsDeadline(0)) throw new NotteTimeoutError(`Session start timed out after ${timeoutMs}ms`);
       if (shouldWait) await this.waitForAuth(options);
       if (this.openViewer) {
         this.openViewerInBrowser();
@@ -3330,7 +3752,11 @@ var Session = class {
         if (!(error instanceof NotteAPIError) || error.statusCode !== 404) {
           throw error;
         }
-        if (this.isActive && (error.apiMessage ?? "").includes("still active")) {
+        const waitingForClose = error.error.replay_status === "waiting_for_session";
+        if (error.error.replay_status === "disabled" || error.error.retryable === false && !waitingForClose) {
+          throw error;
+        }
+        if (this.isActive && this.sessionId === sessionId && (waitingForClose || (error.apiMessage ?? "").includes("still active"))) {
           throw new Error(`Session ${sessionId} is still active \u2014 close the session first to generate the replay.`, {
             cause: error
           });
@@ -3418,9 +3844,7 @@ var Session = class {
    * start-time profile settings are not changed, so a session started with `persist: true`
    * still saves again when it stops.
    *
-   * @example
-   * const profile = await session.saveProfile({ name: 'github' });
-   * // later: client.Session({ profile: { id: profile.profile_id } })
+   * See [Browser Profiles](/features/sessions/browser-profiles) for the tested Python and TypeScript example.
    */
   async saveProfile(options = {}) {
     const { profile_id, name } = options;
@@ -3653,19 +4077,30 @@ var Session = class {
    * The `perception_type` defaults to the session option (`fast`). A bare
    * string argument is accepted as the perception type.
    *
+   * Deprecated: `perception_type: 'deep'` and `instructions` are removed on
+   * December 1, 2026, and each warns once per session. Use `perception_type:
+   * 'fast'` (the default) instead of `'deep'`. For `instructions`:
+   * `<<ALTERNATIVE FOR instructions: session.act() — pending>>`. See https://docs.notte.cc/features/sessions/observe-migration
+   *
    * @param options - Observation settings, including an optional URL, or a perception-mode string.
    * @returns Structured page analysis, available actions, and page metadata.
    * @throws NotteAPIError if observation fails.
    * @example
    * const obs = await session.observe();
    * console.log(obs.space.description);
-   * const deep = await session.observe({ perception_type: 'deep', max_nb_actions: 50 });
+   * const firstActions = await session.observe({ max_nb_actions: 50 });
    */
   async observe(options = {}) {
     const body = typeof options === "string" ? { perception_type: options } : { ...options };
     if (body.perception_type == null) {
       body.perception_type = this.defaultPerceptionType;
     }
+    if (body.instructions != null) {
+      this.warnObserveDeprecation("instructions");
+    }
+    if (body.perception_type !== "fast") {
+      this.warnObserveDeprecation("deep");
+    }
     const response = await pageObserve({
       client: this.client.getClient(),
       path: { session_id: this.requireSessionId() },
@@ -3674,6 +4109,12 @@ var Session = class {
     });
     return response.data;
   }
+  warnObserveDeprecation(option) {
+    if (!this.warnedObserveDeprecations.has(option)) {
+      this.warnedObserveDeprecations.add(option);
+      console.warn(OBSERVE_DEPRECATIONS[option]);
+    }
+  }
   async scrape(options = {}) {
     const sessionId = this.requireSessionId();
     const body = await buildScrapeBody(options);
@@ -3741,424 +4182,18 @@ var Session = class {
     }
   }
 };
-
-// src/agent.ts
-var import_ws = __toESM(require("ws"));
-var import_zod = require("zod");
-function prepareAgentRequest(data) {
-  const apiData = { ...data };
-  const rf = data.response_format;
-  if (rf && typeof rf.parse === "function" && typeof rf.safeParse === "function") {
-    apiData.response_format = normalizeJsonSchema(import_zod.z.toJSONSchema(rf));
-    return { apiData, zodSchema: rf };
-  }
-  return { apiData, zodSchema: null };
-}
-function parseAgentStatusMessage(parsed, agentId) {
-  if (parsed?.status === "agent_stop" && parsed.agent && parsed.agent.agent_id === agentId && parsed.agent.task !== void 0 && parsed.agent.status !== void 0) {
-    return parsed.agent;
-  }
-  if (parsed?.agent_id === agentId && parsed.task !== void 0 && parsed.status !== void 0) {
-    return parsed;
-  }
-  return null;
-}
-function validatePersonaOption(persona, persona_id) {
-  if (persona) {
-    try {
-      const personaId = persona.personaId;
-      if (!personaId || personaId.length === 0) {
-        throw new Error("Persona ID cannot be empty");
-      }
-      return personaId;
-    } catch (error) {
-      throw new Error(`Invalid persona object: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  } else if (persona_id) {
-    if (persona_id.length === 0) {
-      throw new Error("Persona ID cannot be empty");
-    }
-    return persona_id;
-  }
-  return void 0;
-}
-function validateVaultOption(vault, vault_id) {
-  if (vault) {
-    try {
-      const vaultId = vault.vaultId;
-      if (!vaultId || vaultId.length === 0) {
-        throw new Error("Vault ID cannot be empty");
-      }
-      return vaultId;
-    } catch (error) {
-      throw new Error(`Invalid vault object: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  } else if (vault_id) {
-    if (vault_id.length === 0) {
-      throw new Error("Vault ID cannot be empty");
-    }
-    return vault_id;
-  }
-  return void 0;
-}
-function validateSessionOption(session) {
-  const sessionId = session.getId();
-  if (!sessionId || sessionId.length === 0) {
-    throw new Error("Session ID cannot be empty");
+async function pauseStart(ms, signal) {
+  if (!signal) {
+    await sleep(ms);
+    return;
   }
-  return sessionId;
-}
-function validateAgentIdOption(agent_id) {
-  if (agent_id.length === 0) {
-    throw new Error("Agent ID cannot be empty");
+  try {
+    await (0, import_promises4.setTimeout)(ms, void 0, { signal });
+  } catch (error) {
+    signal.throwIfAborted();
+    throw error;
   }
 }
-var defaultStepLogger = (stepData, stepCounter, agentId) => {
-  console.log(`\u2728 Step ${stepCounter} (agent: ${agentId})`);
-  if (stepData && typeof stepData === "object") {
-    if (stepData.state) {
-      const state = stepData.state;
-      if (state.page_summary) {
-        console.log(`\u{1F4DD} Current page: ${state.page_summary}`);
-      }
-      if (state.previous_goal_eval) {
-        const statusEmoji = state.previous_goal_status === "success" ? "\u2705" : state.previous_goal_status === "failure" ? "\u274C" : "\u2753";
-        console.log(`\u{1F52C} Previous goal: ${statusEmoji} ${state.previous_goal_eval}`);
-      }
-      if (state.memory) {
-        console.log(`\u{1F9E0} Memory: ${state.memory}`);
-      }
-      if (state.next_goal) {
-        console.log(`\u{1F3AF} Next goal: ${state.next_goal}`);
-      }
-      if (state.relevant_interactions && state.relevant_interactions.length > 0) {
-        console.log(`\u{1F194} Relevant ids:`);
-        state.relevant_interactions.forEach((interaction) => {
-          console.log(`   \u25B6 ${interaction.id}: ${interaction.reason}`);
-        });
-      }
-    }
-    if (stepData.action) {
-      const action = stepData.action;
-      let actionStr = `\u26A1 Taking action:
-   \u25B6 ${action.name || action.type || "Unknown action"}`;
-      if (action.id) {
-        actionStr += ` with id ${action.id}`;
-      } else if (action.param && action.param.name && action[action.param.name]) {
-        actionStr += ` with ${action.param.name}=${action[action.param.name]}`;
-      }
-      console.log(actionStr);
-    }
-  } else {
-    console.log(stepData);
-  }
-  console.log("");
-};
-var Agent = class {
-  client;
-  request;
-  response = null;
-  websocket = null;
-  existingAgent;
-  constructor(client2, options) {
-    this.client = client2;
-    if ("agent_id" in options && options.agent_id) {
-      if (options.session) {
-        throw new Error("Either session (for running a new agent) or agent_id (for accessing an existing agent) have to be provided, not both");
-      }
-      validateAgentIdOption(options.agent_id);
-      this.existingAgent = true;
-      this.response = { agent_id: options.agent_id };
-    } else if ("session" in options && options.session) {
-      if (options.agent_id) {
-        throw new Error("Either session (for running a new agent) or agent_id (for accessing an existing agent) have to be provided, not both");
-      }
-      this.existingAgent = false;
-      const { session, vault, persona, ...requestData } = options;
-      const sessionId = validateSessionOption(session);
-      const vaultId = validateVaultOption(vault, options.vault_id);
-      const personaId = validatePersonaOption(persona, options.persona_id);
-      this.request = {
-        session_id: sessionId,
-        vault_id: vaultId,
-        persona_id: personaId,
-        ...requestData
-      };
-    } else {
-      throw new Error("Either session (for running a new agent) or agent_id (for accessing an existing agent) have to be provided");
-    }
-  }
-  async start(data) {
-    if (this.existingAgent) {
-      throw new Error("You cannot call start() on an agent instantiated from agent id");
-    }
-    if (!this.request) {
-      throw new Error("Agent not properly initialized with session");
-    }
-    try {
-      const { apiData } = prepareAgentRequest(data);
-      const requestBody = {
-        ...this.request,
-        ...apiData
-      };
-      const response = await agentStart({
-        client: this.client.getClient(),
-        body: requestBody
-      });
-      if (response?.error) {
-        throw new Error(`Failed to start agent: ${formatError(response.error)}`);
-      }
-      this.response = response.data;
-      return this.response;
-    } catch (error) {
-      throw new Error(`Failed to start agent: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-  async run(data) {
-    if (this.existingAgent) {
-      throw new Error("You cannot call run() on an agent instantiated from agent id");
-    }
-    const { apiData, zodSchema } = prepareAgentRequest(data);
-    this.response = await this.start(apiData);
-    console.log(`[Agent] ${this.agentId} started`);
-    const result = await this.watchLogsAndWait(true, data.updateHandler || null);
-    if (zodSchema && result && result.answer !== void 0 && result.answer !== null) {
-      let candidate;
-      try {
-        candidate = typeof result.answer === "string" ? JSON.parse(result.answer) : result.answer;
-      } catch {
-        throw new Error(`Agent answer is not valid JSON and cannot be validated against the schema`);
-      }
-      try {
-        result.answer = zodSchema.parse(candidate);
-      } catch (error) {
-        throw new Error(`Agent answer schema validation failed: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    }
-    return result;
-  }
-  /**
-   * Watch logs and wait for completion - mirrors Python watch_logs_and_wait
-   */
-  async watchLogsAndWait(log = true, updateHandler = null) {
-    if (this.existingAgent) {
-      throw new Error("You cannot call watchLogsAndWait() on an agent instantiated from agent id");
-    }
-    if (!this.response) {
-      throw new Error("Agent not started");
-    }
-    const deadline = Date.now() + 3e5;
-    try {
-      const result = await this.watchLogs(log, updateHandler, deadline);
-      if (result && result.status !== "active") {
-        return result;
-      }
-    } catch (error) {
-      console.warn(`[Agent] ${this.agentId} log stream unavailable; polling for completion.`);
-    }
-    while (Date.now() < deadline) {
-      const result = await this.status(AbortSignal.timeout(Math.max(1, deadline - Date.now())));
-      if (result.status !== "active") {
-        updateHandler?.({ type: "completion", data: result, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
-        return result;
-      }
-      await new Promise((resolve3) => setTimeout(resolve3, 1e3));
-    }
-    throw new Error(`Agent ${this.agentId} did not complete before the polling timeout; retrieve status() later.`);
-  }
-  /**
-   * Watch logs via WebSocket - mirrors Python watch_logs method
-   */
-  async watchLogs(log = true, updateHandler = null, deadline = Date.now() + 3e5) {
-    if (this.existingAgent) {
-      throw new Error("You cannot call watchLogs() on an agent instantiated from agent id");
-    }
-    if (!this.response) {
-      throw new Error("Agent not started");
-    }
-    const config = this.client.getConfig();
-    if (config.baseUrl?.startsWith("/")) return null;
-    const agentId = this.response.agent_id;
-    const sessionId = this.response.session_id;
-    const debug = await sessionDebugInfo({
-      client: this.client.getClient(),
-      path: { session_id: sessionId },
-      throwOnError: true,
-      signal: AbortSignal.timeout(Math.max(1, deadline - Date.now()))
-    });
-    const wsUrl = new URL(this.client.withDbPreview(debug.data.ws.logs));
-    const token = wsUrl.searchParams.get("token");
-    if (!token || token === config.apiKey || wsUrl.protocol !== "wss:") return null;
-    wsUrl.pathname = `/agents/${encodeURIComponent(agentId)}/debug/logs`;
-    wsUrl.searchParams.set("session_id", sessionId);
-    return new Promise((resolve3, reject) => {
-      this.websocket = new import_ws.default(wsUrl);
-      const socket = this.websocket;
-      const timeout = setTimeout(() => finish(null), Math.max(0, deadline - Date.now()));
-      let settled = false;
-      const finish = (result) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timeout);
-        if (this.websocket === socket) this.websocket = null;
-        if (socket.readyState !== import_ws.default.CLOSED) socket.terminate();
-        resolve3(result);
-      };
-      let counter = 0;
-      this.websocket.on("open", () => {
-      });
-      this.websocket.on("error", (error) => {
-        console.error(`Connection error: ${agentId} ${error.message}`);
-        finish(null);
-      });
-      this.websocket.on("message", (data) => {
-        try {
-          const message = data.toString();
-          let parsed;
-          try {
-            parsed = JSON.parse(message);
-          } catch {
-            return;
-          }
-          const finalStatus = parseAgentStatusMessage(parsed, agentId);
-          if (finalStatus) {
-            if (updateHandler) {
-              updateHandler({
-                type: "completion",
-                data: finalStatus,
-                timestamp: (/* @__PURE__ */ new Date()).toISOString()
-              });
-            } else if (!finalStatus.success) {
-              console.error(finalStatus.answer);
-            }
-            finish(finalStatus);
-            return;
-          }
-          if (log) {
-            counter++;
-            if (updateHandler) {
-              updateHandler({
-                type: "step",
-                data: parsed,
-                timestamp: (/* @__PURE__ */ new Date()).toISOString()
-              });
-            } else {
-              defaultStepLogger(parsed, counter, agentId);
-            }
-          }
-        } catch (error) {
-          console.error(`Error processing WebSocket message: ${error}`);
-        }
-      });
-      this.websocket.on("close", () => {
-        finish(null);
-      });
-    });
-  }
-  /**
-   * Get agent status - mirrors Python status method
-   */
-  async status(signal) {
-    if (!this.response) {
-      throw new Error("Agent not started or not accessible");
-    }
-    const response = await agentStatus({
-      client: this.client.getClient(),
-      signal,
-      path: {
-        agent_id: this.response.agent_id
-      }
-    });
-    if (response?.error) {
-      throw new Error(`Failed to get agent status: ${formatError(response.error)}`);
-    }
-    return response.data;
-  }
-  /**
-   * Stop the agent - mirrors Python stop method
-   */
-  async stop() {
-    if (this.existingAgent) {
-      throw new Error("You cannot call stop() on an agent instantiated from agent id");
-    }
-    if (!this.response) {
-      throw new Error("Agent not started");
-    }
-    try {
-      console.log(`[Agent] ${this.response.agent_id} is stopping`);
-      const response = await agentStop({
-        client: this.client.getClient(),
-        path: {
-          agent_id: this.response.agent_id
-        },
-        query: { session_id: this.response.session_id }
-      });
-      if (response?.error) {
-        throw new Error(`Failed to stop agent: ${formatError(response.error)}`);
-      }
-      console.log(`[Agent] ${this.response.agent_id} stopped`);
-      return response.data;
-    } catch (error) {
-      console.warn(`Failed to stop agent: ${error instanceof Error ? error.message : String(error)}`);
-      throw error;
-    } finally {
-      this.disconnectWebSocket();
-    }
-  }
-  /**
-   * Disconnect WebSocket
-   */
-  disconnectWebSocket() {
-    if (this.websocket) {
-      this.websocket.close();
-      this.websocket = null;
-    }
-  }
-  /**
-   * Get agent ID - mirrors Python agent_id property
-   */
-  get agentId() {
-    if (!this.response) {
-      throw new Error("You need to run the agent first to get the agent id");
-    }
-    return this.response.agent_id;
-  }
-  /**
-   * Get session ID - mirrors Python session_id property
-   */
-  get sessionId() {
-    if (!this.response) {
-      throw new Error("You need to run the agent first to get the session id");
-    }
-    return this.response.session_id;
-  }
-  /**
-   * Whether `start()`/`run()` was called on this instance (or it was built from an agent id).
-   * This is a local check and does not contact the API.
-   */
-  hasStarted() {
-    return this.response !== null;
-  }
-  /**
-   * Whether the agent is still active on the server. Fetches the current status,
-   * like calling `agent.status()` in Python; an agent that was never started is not active.
-   */
-  async isActive() {
-    if (!this.response) {
-      return false;
-    }
-    const status = await this.status();
-    return status.status === "active";
-  }
-  /**
-   * @deprecated Only reports whether this instance was started; it does not
-   * contact the API. Use `hasStarted()` for that check or `isActive()` for the
-   * live server status.
-   */
-  isRunning() {
-    return this.hasStarted();
-  }
-};
 
 // src/vaults.ts
 var import_tldts = require("tldts");
@@ -4318,9 +4353,9 @@ var NotteVault = class {
     await this.delete();
   }
   /**
-   * Add or update the credentials stored for a website. The URL is reduced to
-   * its root domain (`https://github.com/login` → `github.com`) before it is
-   * sent, like Python's `AddCredentialsRequest`.
+   * Add or update the credentials stored for a website. Values are sent as
+   * supplied; the API validates credentials and reduces the URL to its root
+   * domain (`https://github.com/login` → `github.com`).
    *
    * ```ts
    * await vault.addCredentials('https://github.com/', {
@@ -4331,13 +4366,11 @@ var NotteVault = class {
    * ```
    */
   async addCredentials(url, credentials) {
-    const domain = validateUrl(url);
-    validateCredentials(credentials);
     const vaultId = await this.ensureInitialized();
     await vaultCredentialsAdd({
       client: this.client.getClient(),
       path: { vault_id: vaultId },
-      body: { url: domain, credentials },
+      body: { url, credentials },
       throwOnError: true
     });
   }
@@ -4351,12 +4384,11 @@ var NotteVault = class {
    * ```
    */
   async getCredentials(url) {
-    const domain = validateUrl(url);
     const vaultId = await this.ensureInitialized();
     const response = await vaultCredentialsGet({
       client: this.client.getClient(),
       path: { vault_id: vaultId },
-      query: { url: domain },
+      query: { url },
       throwOnError: true
     });
     return response.data.credentials;
@@ -4384,12 +4416,11 @@ var NotteVault = class {
    * ```
    */
   async deleteCredentials(url) {
-    const domain = validateUrl(url);
     const vaultId = await this.ensureInitialized();
     await vaultCredentialsDelete({
       client: this.client.getClient(),
       path: { vault_id: vaultId },
-      query: { url: domain },
+      query: { url },
       throwOnError: true
     });
   }
@@ -4434,7 +4465,7 @@ var NotteVault = class {
    * ```
    */
   async addCredentialsFromEnv(url) {
-    const rootDomain = validateUrl(url);
+    const rootDomain = getRootDomain(url);
     const prefix = rootDomain.replace(/\./g, "_").toUpperCase();
     const credentials = {};
     const variableNames = [];
@@ -4510,6 +4541,10 @@ var NotteVault = class {
 };
 
 // src/personas.ts
+function withPersonaDefaults(persona) {
+  if (!persona || persona.email_provider) return persona;
+  return { ...persona, email_provider: "notte" };
+}
 var NottePersona = class {
   client;
   _initRequest;
@@ -4569,7 +4604,7 @@ var NottePersona = class {
     if (response?.error) {
       throw new Error(`Failed to get persona: ${formatError(response.error)}`);
     }
-    this.response = response.data;
+    this.response = withPersonaDefaults(response.data);
     return this.response;
   }
   async initNewPersona(createData) {
@@ -4580,7 +4615,7 @@ var NottePersona = class {
     if (response?.error) {
       throw new Error(`Failed to create persona: ${formatError(response.error)}`);
     }
-    this.response = response.data;
+    this.response = withPersonaDefaults(response.data);
     console.warn(
       `[Persona] ${this.response.persona_id} created since no persona id was provided. Please store this to retrieve it later.`
     );
@@ -4809,11 +4844,10 @@ async function offloadRunPayloads(client2, path, fields) {
     if (payload.length > MAX_PAYLOAD_BYTES) throw new Error(`Function run ${field} exceeds the payload limit`);
     if (payload.length <= INLINE_FIELD_BYTES) continue;
     const checksum = (0, import_node_crypto2.createHash)("sha256").update(payload).digest("base64");
-    const prepared = await client2.post({
-      url: "/functions/{function_id}/runs/{run_id}/payloads/{field}/upload",
+    const prepared = await prepareRunPayloadUpload({
+      client: client2,
       path: { ...path, field },
       body: { size_bytes: payload.length, sha256: checksum },
-      headers: { "Content-Type": "application/json" },
       throwOnError: true
     });
     const upload = prepared.data;
@@ -4889,7 +4923,6 @@ var FUNCTION_RUN_ENDPOINTS = {
   start: "/functions/{function_id}/runs/{run_id}"
 };
 var RUN_API_KEY_HEADER = "x-notte-api-key";
-var FUNCTION_RUNTIMES = ["standard", "extended"];
 var FUNCTION_RUN_STATUSES = ["closed", "active", "failed"];
 var NotteFunction = class {
   client;
@@ -4992,7 +5025,7 @@ var NotteFunction = class {
       throwOnError: true,
       path: { function_id: functionId },
       query: {
-        restricted: options.restricted ?? true,
+        restricted: options.restricted,
         ...options.version !== void 0 ? { version: options.version } : {}
       },
       body: { file }
@@ -5089,7 +5122,7 @@ var NotteFunction = class {
       client: this.client.getClient(),
       throwOnError: true,
       path: { function_id: functionId },
-      query: { restricted: options.restricted ?? true },
+      query: { restricted: options.restricted },
       body: { version: options.version }
     });
     return response.data;
@@ -5185,7 +5218,7 @@ var NotteFunction = class {
       client: this.client.getClient(),
       throwOnError: true,
       path: { function_id: functionId },
-      query: { ...options, only_active: options.only_active ?? false }
+      query: options
     });
     return response.data;
   }
@@ -5218,9 +5251,6 @@ var NotteFunction = class {
     if (!(timeoutMs > 0)) {
       throw new InvalidRequestError("timeoutMs must be a positive number");
     }
-    if (options.runtime !== void 0 && !FUNCTION_RUNTIMES.includes(options.runtime)) {
-      throw new InvalidRequestError(`runtime must be one of ${FUNCTION_RUNTIMES.join(", ")}, got '${String(options.runtime)}'`);
-    }
     const functionId = await this.ensureInitialized();
     const functionRunId = options.functionRunId ?? (await this.createRun()).function_run_id;
     const body = {
@@ -5535,6 +5565,8 @@ var SessionFiles = class {
     this.client = client2;
     this.sessionId = sessionId;
   }
+  client;
+  sessionId;
   /**
    * Upload bytes as a session file. `filename` is what the browser sees when
    * the file is later attached to a page.
@@ -5563,7 +5595,7 @@ var SessionFiles = class {
     const response = await listSessionFiles({
       client: this.client,
       path: { session_id: this.sessionId },
-      query: { limit: options.limit ?? 100, offset: options.offset ?? 0, source: options.source },
+      query: options,
       throwOnError: true
     });
     return response.data;
@@ -5639,6 +5671,7 @@ var RemoteFileStorage = class _RemoteFileStorage {
     this.client = client2;
     this._sessionId = sessionId ?? null;
   }
+  client;
   _sessionId;
   /** Bind the storage to a session. Called by `Session.start()` when the storage was passed to the session. */
   setSessionId(sessionId) {
@@ -5972,6 +6005,7 @@ var DEFAULT_NOTTE_API_URL = "https://api.notte.cc";
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
 var REQUEST_ORIGIN = "sdk-node";
 var TIMEOUT_HEADER = "x-notte-timeout-ms";
+var MAX_RETRIES_HEADER = "x-notte-max-retries";
 var DB_PREVIEW_ENV = "NOTTE_DB_PREVIEW_BRANCH";
 var DB_PREVIEW_HEADER = "x-db-preview";
 var EXECUTION_ERROR_CLASS = "NotteApiExecutionError";
@@ -5994,6 +6028,10 @@ var NotteClient3 = class {
     if (!(timeoutMs >= 0)) {
       throw new InvalidRequestError("timeoutMs must be a non-negative number");
     }
+    const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+      throw new InvalidRequestError("maxRetries must be a non-negative integer");
+    }
     const isProxyMode = isRelativeProxyUrl(baseUrl);
     if (!isProxyMode) {
       const url = new URL(baseUrl);
@@ -6009,7 +6047,15 @@ var NotteClient3 = class {
         "NOTTE_API_KEY needs to be provided. Pass config.apiKey or set the NOTTE_API_KEY environment variable."
       );
     }
-    this.config = { baseUrl, apiKey, timeoutMs, captchaTimeoutSeconds, dbPreview, verbose: config.verbose ?? false };
+    this.config = {
+      baseUrl,
+      apiKey,
+      timeoutMs,
+      captchaTimeoutSeconds,
+      dbPreview,
+      maxRetries,
+      verbose: config.verbose ?? false
+    };
     if (baseUrl !== DEFAULT_NOTTE_API_URL && !isProxyMode) {
       console.warn(`NOTTE_API_URL is set to: ${baseUrl}`);
     }
@@ -6018,7 +6064,7 @@ var NotteClient3 = class {
       redirect: "manual",
       throwOnError: true
     });
-    this.client.interceptors.request.use((request) => {
+    this.client.interceptors.request.use((request, opts) => {
       const headers = new Headers(request.headers);
       if (this.config.apiKey) headers.set("Authorization", `Bearer ${this.config.apiKey}`);
       headers.set("x-notte-request-origin", REQUEST_ORIGIN);
@@ -6026,16 +6072,25 @@ var NotteClient3 = class {
       if (this.config.dbPreview) headers.set(DB_PREVIEW_HEADER, this.config.dbPreview);
       const override = headers.get(TIMEOUT_HEADER);
       headers.delete(TIMEOUT_HEADER);
+      const retriesOverride = headers.get(MAX_RETRIES_HEADER);
+      headers.delete(MAX_RETRIES_HEADER);
       const timeoutMs2 = override !== null ? Number(override) : this.config.timeoutMs;
       if (this.config.verbose) {
         console.info(`Making \`${request.method}\` request to \`${request.url}\``);
       }
-      if (!(timeoutMs2 > 0)) {
-        return new Request(request, { headers });
-      }
-      const deadline = withTimeout(request.signal, timeoutMs2);
-      const timed = new Request(request, { headers, signal: deadline.signal });
-      pendingDeadlines.set(timed, deadline.release);
+      const callerSignal = opts.signal ?? request.signal;
+      const deadline = timeoutMs2 > 0 ? withTimeout(callerSignal, timeoutMs2) : void 0;
+      const signal = deadline?.signal ?? callerSignal;
+      const timed = new Request(request, { headers, signal });
+      pendingRequests.set(timed, { signal, release: deadline?.release ?? (() => void 0), expiresAt: deadline?.expiresAt ?? Infinity });
+      const transport = originalTransports.get(opts) ?? opts.fetch ?? globalThis.fetch;
+      originalTransports.set(opts, transport);
+      const retrying = createRetryingFetch({
+        fetch: transport,
+        maxRetries: () => retriesOverride !== null ? Number(retriesOverride) : this.config.maxRetries,
+        deadline: () => deadline?.expiresAt
+      });
+      opts.fetch = (input, init) => retrying(input, { ...init, signal });
       return timed;
     });
     this.client.interceptors.response.use(async (response, request, opts) => {
@@ -6073,7 +6128,7 @@ var NotteClient3 = class {
           method: request.method,
           headers: headerRecord,
           body: opts.serializedBody ?? void 0,
-          signal: request.signal,
+          signal: requestSignal(request),
           redirect: "manual"
         });
         currentUrl = location;
@@ -6121,14 +6176,15 @@ var NotteClient3 = class {
     if (error instanceof NotteAPIError) {
       return error;
     }
-    if (request?.signal.aborted) {
-      error = request.signal.reason ?? error;
+    const signal = request && requestSignal(request);
+    if (signal?.aborted) {
+      error = signal.reason ?? error;
     }
     if (isTimeoutAbort(error)) {
       const target = request ? ` to \`${requestPath(request)}\`` : "";
       return new NotteTimeoutError(`Request${target} ${error.message}`, { cause: error });
     }
-    if (request?.signal.aborted) return error;
+    if (signal?.aborted) return error;
     if (response) {
       const path = requestPath(request, response);
       const body = normalizeErrorBody(error);
@@ -6178,6 +6234,10 @@ var NotteClient3 = class {
   Session(options = {}) {
     return new Session(this, options);
   }
+  /** Generated file operations; use Files(sessionId) for local file IO helpers. */
+  get files() {
+    return this.resources.files;
+  }
   /** Access files owned by a specific session, including closed sessions. */
   Files(sessionId) {
     return new SessionFiles(this.getClient(), sessionId);
@@ -6196,12 +6256,6 @@ var NotteClient3 = class {
   FileStorage(sessionId) {
     return new RemoteFileStorage(this, sessionId);
   }
-  /**
-   * Create a new agent
-   */
-  Agent(options) {
-    return new Agent(this, options);
-  }
   /**
    * Create or access a vault
    */
@@ -6234,16 +6288,6 @@ var NotteClient3 = class {
       }
     };
   }
-  /** Client-bound agent API operations. `list()` retains its array return value. */
-  get agents() {
-    return {
-      ...this.resources.agents,
-      list: async (options = {}) => {
-        const response = await listAgents({ client: this.getClient(), query: options });
-        return response.data?.items ?? [];
-      }
-    };
-  }
   /** Client-bound vault API operations. `list()` retains its array return value. */
   get vaults() {
     return {
@@ -6292,14 +6336,18 @@ var NotteClient3 = class {
    * Personas client for listing and managing personas
    */
   get personas() {
+    const personas = this.resources.personas;
     return {
-      ...this.resources.personas,
+      ...personas,
+      create: async (...args) => withPersonaDefaults(await personas.create(...args)),
+      get: async (...args) => withPersonaDefaults(await personas.get(...args)),
+      update: async (...args) => withPersonaDefaults(await personas.update(...args)),
       list: async (options) => {
         const response = await listPersonas({
           client: this.getClient(),
           query: options || {}
         });
-        return response.data?.items || [];
+        return (response.data?.items || []).map(withPersonaDefaults);
       }
     };
   }
@@ -6345,18 +6393,18 @@ function isTimeoutAbort(error) {
 function timeoutReason(timeoutMs) {
   return new DOMException(`timed out after ${timeoutMs}ms`, "TimeoutError");
 }
-var pendingDeadlines = /* @__PURE__ */ new WeakMap();
+var pendingRequests = /* @__PURE__ */ new WeakMap();
+var originalTransports = /* @__PURE__ */ new WeakMap();
+function requestSignal(request) {
+  return pendingRequests.get(request)?.signal ?? request.signal;
+}
 function releaseDeadline(request) {
-  if (!request) return;
-  const release = pendingDeadlines.get(request);
-  if (release) {
-    pendingDeadlines.delete(request);
-    release();
-  }
+  if (request) pendingRequests.get(request)?.release();
 }
 function withTimeout(signal, timeoutMs) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(timeoutReason(timeoutMs)), timeoutMs);
+  const expiresAt = Date.now() + timeoutMs;
   timer.unref?.();
   let detach = () => void 0;
   let composite;
@@ -6383,7 +6431,7 @@ function withTimeout(signal, timeoutMs) {
     detach();
   };
   composite.addEventListener("abort", release, { once: true });
-  return { signal: composite, release };
+  return { signal: composite, release, expiresAt };
 }
 
 // src/actions.ts
@@ -6477,11 +6525,11 @@ var createClient2 = (config) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActionExecutionError,
-  Agent,
   AuthenticationError,
   CAPTCHA_SOLVE_TIMEOUT_MS,
   CLUSTER_OVERLOAD_RETRY_DELAY_MS,
   CREDENTIAL_FIELDS,
+  DEFAULT_MAX_RETRIES,
   DEFAULT_NOTTE_API_URL,
   DEFAULT_REQUEST_TIMEOUT_MS,
   Encryption,
@@ -6516,12 +6564,17 @@ var createClient2 = (config) => {
   Session,
   SessionFiles,
   TIMEOUT_HEADER,
+  accountChanges,
+  accountRuns,
   actions,
   agentStart,
   agentStatus,
   agentStop,
   anythingStart,
+  attempts,
+  brandRetrieve,
   buildFetchScript,
+  changes,
   checkForLatestVersion,
   client,
   connectLinkContext,
@@ -6531,14 +6584,22 @@ var createClient2 = (config) => {
   connectLinkStatus,
   connectLinkSubmit,
   connectPaymentWallet,
+  create,
   createClient,
   createOrAppendCookiesToFile,
   createPayment,
+  creditUsage,
   deleteSecret,
   deleteSessionFile,
+  delete_,
+  deliveries,
+  detail,
   disconnectPaymentWallet,
   downloadRunPayload,
   downloadSessionFile,
+  executeSessionFile,
+  extractProductEndpoint,
+  fetchSpecializedData,
   functionCreate,
   functionDelete,
   functionDownloadUrl,
@@ -6554,6 +6615,7 @@ var createClient2 = (config) => {
   functionScheduleSet,
   functionUpdate,
   getPayment,
+  getPolicy,
   getRootDomain,
   getScript,
   getSecret,
@@ -6561,13 +6623,18 @@ var createClient2 = (config) => {
   getUsage,
   getUsageLogs,
   healthCheck,
+  history_,
   installServerOwnedDialogPolicy,
+  invalidate,
   isCaptchaSolveAction,
   isValidMfaSecret,
+  limits,
   listAgents,
   listAuditEvents,
+  listDataApis,
   listFunctionRunsByFunctionId,
   listFunctions,
+  listMonitors,
   listPersonas,
   listSecrets,
   listSessionFiles,
@@ -6580,19 +6647,20 @@ var createClient2 = (config) => {
   mailboxSync,
   mailboxUpdate,
   managedAuthConnectLinkCreate,
+  mapsSearch,
+  newsSearch,
   observeServerOwnedDialog,
   pageExecute,
   pageObserve,
   pageScrape,
   pageScreenshot,
-  parseAgentStatusMessage,
+  peopleEnrich,
   personaCreate,
   personaDelete,
   personaEmailsList,
   personaGet,
   personaSmsList,
   personaUpdate,
-  prepareAgentRequest,
   prepareRunPayloadUpload,
   processScrapeResponse,
   profileCookiesGet,
@@ -6602,18 +6670,29 @@ var createClient2 = (config) => {
   profileDuplicate,
   profileGet,
   profileList,
+  profileStateSet,
   readCookiesFile,
   readyCheck,
   responseFromEvaluated,
+  retrieve,
+  retrieveChange,
+  retrieveDelivery,
+  retrieveRun,
   retry,
+  retryWebhookDelivery,
+  rotateSecret,
+  runNow,
+  runs,
   sanitizeFilename,
   scrapeFromHtml,
+  scrapeSpecializedData,
   scrapeWebpage,
   searchWeb,
   sessionAuthReadiness,
   sessionCookiesGet,
   sessionCookiesSet,
   sessionDebugInfo,
+  sessionMouseReplay,
   sessionNetworkLogs,
   sessionOffset,
   sessionProfilePreview,
@@ -6624,6 +6703,9 @@ var createClient2 = (config) => {
   sessionStop,
   startVersionCheck,
   storeSecret,
+  styleguideEndpoint,
+  summary,
+  update,
   uploadSessionFile,
   validateCredentials,
   validateMfaSecret,
@@ -6637,6 +6719,7 @@ var createClient2 = (config) => {
   vaultCreditCardGet,
   vaultCreditCardSet,
   vaultDelete,
-  vaultUpdate
+  vaultUpdate,
+  youtubeEndpoint
 });
 //# sourceMappingURL=index.js.map