firecrawl 4.41.0 → 4.42.0

package/dist/{chunk-I2DFXQYR.js → chunk-OCJTYRX5.js}

@@ -12,7 +12,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.41.0",
+      version: "4.42.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.41.0",
+      version: "4.42.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -317,6 +317,12 @@ var JobTimeoutError = class extends SdkError {
   }
 };
 
+// src/v2/utils/agentHints.ts
+function agentHintMetadata(body) {
+  const hints = body?.agent_hints;
+  return Array.isArray(hints) && hints.every((hint) => typeof hint === "string") ? { agent_hints: [...hints] } : {};
+}
+
 // src/utils/zodSchemaToJson.ts
 var import_zod_to_json_schema = require("zod-to-json-schema");
 function isZodSchema(value) {
@@ -550,7 +556,7 @@ function throwForBadResponse(resp, action) {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
-  throw new SdkError(
+  throw Object.assign(new SdkError(
     msg,
     status,
     body?.code,
@@ -558,14 +564,14 @@ function throwForBadResponse(resp, action) {
     void 0,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction)
-  );
+  ), agentHintMetadata(body));
 }
 function normalizeAxiosError(err, action) {
   const status = err.response?.status;
   const body = err.response?.data;
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = body?.code || err.code;
-  throw new SdkError(
+  throw Object.assign(new SdkError(
     message,
     status,
     code,
@@ -573,7 +579,7 @@ function normalizeAxiosError(err, action) {
     void 0,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction)
-  );
+  ), agentHintMetadata(body));
 }
 function isRetryableError(err) {
   if (err instanceof JobTimeoutError) {
@@ -641,7 +647,7 @@ async function scrape(http, url, options, deps = {}) {
       if (res.status !== 200 || !res.data?.success) {
         throwForBadResponse(res, "scrape");
       }
-      return res.data.data || {};
+      return { ...res.data.data, ...agentHintMetadata(res.data) };
     } catch (err) {
       const delayMs = autoResume !== false ? processingContinuesDelayMs(err) : void 0;
       if (delayMs !== void 0 && resumes < RESUME_MAX_ATTEMPTS && resumeWaitedMs + delayMs <= RESUME_MAX_TOTAL_WAIT_MS) {
@@ -758,7 +764,7 @@ async function parse(http, file, options) {
     if (res.status !== 200 || !res.data?.success) {
       throwForBadResponse(res, "parse");
     }
-    return res.data.data || {};
+    return { ...res.data.data, ...agentHintMetadata(res.data) };
   } catch (err) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "parse");
     throw err;
@@ -832,7 +838,7 @@ async function search(http, request) {
       throwForBadResponse(res, "search");
     }
     const data = res.data.data || {};
-    const out = {};
+    const out = { ...agentHintMetadata(res.data) };
     if (res.data.warning) out.warning = res.data.warning;
     if (data.web) out.web = transformArray(data.web);
     if (data.news) out.news = transformArray(data.news);
@@ -1037,7 +1043,7 @@ async function map(http, url, options) {
           description: item.description
         });
     }
-    return { id: res.data.id, links };
+    return { id: res.data.id, links, ...agentHintMetadata(res.data) };
   } catch (err) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "map");
     throw err;

package/dist/index.d.cts

@@ -540,6 +540,8 @@ interface DocumentMetadata {
     [key: string]: unknown;
 }
 interface Document {
+    /** API guidance, separate from extracted page content. */
+    agent_hints?: string[];
     markdown?: string;
     html?: string;
     rawHtml?: string;
@@ -671,6 +673,7 @@ interface SearchResultImages {
     position?: number;
 }
 interface SearchData {
+    agent_hints?: string[];
     warning?: string;
     web?: Array<SearchResultWeb | Document>;
     news?: Array<SearchResultNews | Document>;
@@ -917,6 +920,7 @@ interface BatchScrapeJob {
     data: Document[];
 }
 interface MapData {
+    agent_hints?: string[];
     id?: string;
     links: SearchResultWeb[];
 }
@@ -1236,7 +1240,11 @@ interface AgentExchangeOptions {
     toolkits?: string[];
     maxCalls?: number;
     requireApproval?: boolean;
-    /** Answers a pendingApproval from the previous turn of the thread. */
+    /**
+     * Answers a pendingApproval from the previous turn of the thread. A `terms`
+     * approval is accepted or declined as a whole: `callIds` and `always` are
+     * ignored on it.
+     */
     approve?: {
         approvalId: string;
         callIds?: string[];
@@ -1245,6 +1253,75 @@ interface AgentExchangeOptions {
     decline?: {
         approvalId: string;
     };
+    /**
+     * What to do when a provider the agent would use needs data terms the team
+     * has not accepted. Gated providers are never called in any mode:
+     * - "skip" (server default): answer with accepted providers only and list
+     *   the gated ones in `exchange.skippedProviders`.
+     * - "ask": the same, plus `exchange.requiresAction` and a `terms`
+     *   pendingApproval. Get your user's explicit consent, call terms/accept,
+     *   then continue the thread with `approve: { approvalId }`.
+     * Terms gating is rolling out: until it is on for a thread, none of the
+     * terms fields appear. There is no auto-accept mode. Omitted on a follow-up turn inherits the
+     * previous turn's value.
+     */
+    onTermsRequired?: AgentOnTermsRequired;
+}
+type AgentOnTermsRequired = "skip" | "ask";
+/** A gated provider the run would have used but did not. */
+interface AgentSkippedProvider {
+    provider: string;
+    name: string;
+    capability?: string;
+    /** What it would have added, in the agent's words. */
+    adds?: string;
+    reason: "terms_required";
+    /** The gating terms version. */
+    version: string;
+    /** Where a person accepts the terms in the dashboard. */
+    termsUrl: string;
+}
+/**
+ * The exact Exchange calls to view and accept a provider's terms. Nothing here
+ * is executed for you, and terms/accept must only be called after the user
+ * has explicitly agreed to that provider's terms.
+ */
+interface AgentTermsRequiredAction {
+    type: "accept_terms";
+    /**
+     * The `terms` pendingApproval that answers this. After the user agrees and
+     * terms/accept succeeds, continue the thread with
+     * `exchange.approve: { approvalId }`, or refuse with `decline`.
+     */
+    approvalId: string;
+    providers: {
+        provider: string;
+        name: string;
+        capability?: string;
+        adds?: string;
+        version: string;
+        /** null when the catalog published no digest; terms/show returns it. */
+        digest: string | null;
+        url: string;
+        show: {
+            provider: "firecrawl";
+            capability: "terms/show";
+            options: {
+                provider: string;
+            };
+        };
+        accept: {
+            provider: "firecrawl";
+            capability: "terms/accept";
+            options: {
+                provider: string;
+                version: string;
+                /** null when the catalog published no digest; terms/show returns it. */
+                digest: string | null;
+                confirmed: true;
+            };
+        };
+    }[];
 }
 /** Per-run summary reported on a status response. */
 interface AgentExchangeSummary {
@@ -1252,33 +1329,72 @@ interface AgentExchangeSummary {
     /** What the run resolved to after thread inheritance, not what it requested. */
     toolkits?: string[];
     requireApproval?: boolean;
+    onTermsRequired?: AgentOnTermsRequired;
     paidCalls: number;
     creditsUsed: number | null;
+    /** Gated providers that would have helped and were not used. Any mode. */
+    skippedProviders?: AgentSkippedProvider[];
+    /** "ask" mode, when a terms offer ended the turn. */
+    requiresAction?: AgentTermsRequiredAction;
+}
+/** A provider in a `terms` pendingApproval. */
+interface AgentTermsGate {
+    provider: string;
+    name: string;
+    logo?: string;
+    capability?: string;
+    adds?: string;
+    version: string;
+    /** null when the catalog published no digest; terms/show returns it. */
+    digest: string | null;
+    url: string;
 }
 /** A follow-up the agent offers for the next turn of the thread. */
 interface AgentSuggestion {
     label: string;
     prompt: string;
 }
-/** A turn that ended waiting for the caller to allow or refuse paid calls. */
-interface PendingApproval {
+/** A paid call a `calls` pendingApproval is holding back. */
+interface PendingApprovalCall {
+    id: string;
+    provider: string;
+    capability: string;
+    input: Record<string, unknown>;
+    more?: Record<string, unknown>[];
+    creditsEstimate: number | null;
+}
+interface PendingApprovalBase {
     id: string;
     reason: string;
-    calls: {
-        id: string;
-        provider: string;
-        capability: string;
-        input: Record<string, unknown>;
-        more?: Record<string, unknown>[];
-        creditsEstimate: number | null;
-    }[];
     resolution: null | {
         approved: boolean;
+        /** Calls approved. Ignored on terms offers. */
         callIds: string[];
         always: boolean;
         byRunId: string;
     };
 }
+/**
+ * A turn that ended waiting for the caller to allow or refuse paid calls.
+ * `kind` is absent on items written before terms offers existed.
+ */
+interface PendingCallsApproval extends PendingApprovalBase {
+    kind?: "calls";
+    calls: PendingApprovalCall[];
+    terms?: never;
+}
+/**
+ * A turn that ended waiting for the caller to accept providers' data terms
+ * ("ask" mode). `calls` is always empty (typed `never[]` rather
+ * than `[]` so existing `pendingApproval.calls[0]` code still compiles).
+ */
+interface PendingTermsApproval extends PendingApprovalBase {
+    kind: "terms";
+    calls: never[];
+    terms: AgentTermsGate[];
+}
+/** Narrow on `kind === "terms"`. */
+type PendingApproval = PendingCallsApproval | PendingTermsApproval;
 interface AgentResponse {
     success: boolean;
     id: string;
@@ -1588,6 +1704,7 @@ interface RequiresAction {
 }
 declare function parseRequiresAction(value: unknown): RequiresAction | undefined;
 declare class SdkError extends Error {
+    agent_hints?: string[];
     requestId?: string;
     status?: number;
     code?: string;
@@ -1631,10 +1748,12 @@ interface BrowserExecuteResponse {
     stderr?: string;
     exitCode?: number;
     killed?: boolean;
+    truncated?: boolean;
     error?: string;
 }
 interface BrowserDeleteResponse {
     success: boolean;
+    status?: string;
     sessionDurationMs?: number;
     creditsBilled?: number;
     error?: string;
@@ -3409,4 +3528,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentThread, type AgentThreadResponse, type AgentThreadRun, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AlexandriaCall, type AlexandriaOptions, type AlexandriaScrapeData, type AlexandriaScrapeError, type AlexandriaScrapeRequest, type AlexandriaScrapeResult, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type DiscoveredTool, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, type FindToolsData, type FindToolsOptions, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, type ImageParser, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, type RequiresAction, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default, parseRequiresAction };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOnTermsRequired, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSkippedProvider, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentTermsGate, type AgentTermsRequiredAction, type AgentThread, type AgentThreadResponse, type AgentThreadRun, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AlexandriaCall, type AlexandriaOptions, type AlexandriaScrapeData, type AlexandriaScrapeError, type AlexandriaScrapeRequest, type AlexandriaScrapeResult, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type DiscoveredTool, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, type FindToolsData, type FindToolsOptions, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, type ImageParser, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PendingApprovalCall, type PendingCallsApproval, type PendingTermsApproval, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, type RequiresAction, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default, parseRequiresAction };

package/dist/index.d.ts

@@ -540,6 +540,8 @@ interface DocumentMetadata {
     [key: string]: unknown;
 }
 interface Document {
+    /** API guidance, separate from extracted page content. */
+    agent_hints?: string[];
     markdown?: string;
     html?: string;
     rawHtml?: string;
@@ -671,6 +673,7 @@ interface SearchResultImages {
     position?: number;
 }
 interface SearchData {
+    agent_hints?: string[];
     warning?: string;
     web?: Array<SearchResultWeb | Document>;
     news?: Array<SearchResultNews | Document>;
@@ -917,6 +920,7 @@ interface BatchScrapeJob {
     data: Document[];
 }
 interface MapData {
+    agent_hints?: string[];
     id?: string;
     links: SearchResultWeb[];
 }
@@ -1236,7 +1240,11 @@ interface AgentExchangeOptions {
     toolkits?: string[];
     maxCalls?: number;
     requireApproval?: boolean;
-    /** Answers a pendingApproval from the previous turn of the thread. */
+    /**
+     * Answers a pendingApproval from the previous turn of the thread. A `terms`
+     * approval is accepted or declined as a whole: `callIds` and `always` are
+     * ignored on it.
+     */
     approve?: {
         approvalId: string;
         callIds?: string[];
@@ -1245,6 +1253,75 @@ interface AgentExchangeOptions {
     decline?: {
         approvalId: string;
     };
+    /**
+     * What to do when a provider the agent would use needs data terms the team
+     * has not accepted. Gated providers are never called in any mode:
+     * - "skip" (server default): answer with accepted providers only and list
+     *   the gated ones in `exchange.skippedProviders`.
+     * - "ask": the same, plus `exchange.requiresAction` and a `terms`
+     *   pendingApproval. Get your user's explicit consent, call terms/accept,
+     *   then continue the thread with `approve: { approvalId }`.
+     * Terms gating is rolling out: until it is on for a thread, none of the
+     * terms fields appear. There is no auto-accept mode. Omitted on a follow-up turn inherits the
+     * previous turn's value.
+     */
+    onTermsRequired?: AgentOnTermsRequired;
+}
+type AgentOnTermsRequired = "skip" | "ask";
+/** A gated provider the run would have used but did not. */
+interface AgentSkippedProvider {
+    provider: string;
+    name: string;
+    capability?: string;
+    /** What it would have added, in the agent's words. */
+    adds?: string;
+    reason: "terms_required";
+    /** The gating terms version. */
+    version: string;
+    /** Where a person accepts the terms in the dashboard. */
+    termsUrl: string;
+}
+/**
+ * The exact Exchange calls to view and accept a provider's terms. Nothing here
+ * is executed for you, and terms/accept must only be called after the user
+ * has explicitly agreed to that provider's terms.
+ */
+interface AgentTermsRequiredAction {
+    type: "accept_terms";
+    /**
+     * The `terms` pendingApproval that answers this. After the user agrees and
+     * terms/accept succeeds, continue the thread with
+     * `exchange.approve: { approvalId }`, or refuse with `decline`.
+     */
+    approvalId: string;
+    providers: {
+        provider: string;
+        name: string;
+        capability?: string;
+        adds?: string;
+        version: string;
+        /** null when the catalog published no digest; terms/show returns it. */
+        digest: string | null;
+        url: string;
+        show: {
+            provider: "firecrawl";
+            capability: "terms/show";
+            options: {
+                provider: string;
+            };
+        };
+        accept: {
+            provider: "firecrawl";
+            capability: "terms/accept";
+            options: {
+                provider: string;
+                version: string;
+                /** null when the catalog published no digest; terms/show returns it. */
+                digest: string | null;
+                confirmed: true;
+            };
+        };
+    }[];
 }
 /** Per-run summary reported on a status response. */
 interface AgentExchangeSummary {
@@ -1252,33 +1329,72 @@ interface AgentExchangeSummary {
     /** What the run resolved to after thread inheritance, not what it requested. */
     toolkits?: string[];
     requireApproval?: boolean;
+    onTermsRequired?: AgentOnTermsRequired;
     paidCalls: number;
     creditsUsed: number | null;
+    /** Gated providers that would have helped and were not used. Any mode. */
+    skippedProviders?: AgentSkippedProvider[];
+    /** "ask" mode, when a terms offer ended the turn. */
+    requiresAction?: AgentTermsRequiredAction;
+}
+/** A provider in a `terms` pendingApproval. */
+interface AgentTermsGate {
+    provider: string;
+    name: string;
+    logo?: string;
+    capability?: string;
+    adds?: string;
+    version: string;
+    /** null when the catalog published no digest; terms/show returns it. */
+    digest: string | null;
+    url: string;
 }
 /** A follow-up the agent offers for the next turn of the thread. */
 interface AgentSuggestion {
     label: string;
     prompt: string;
 }
-/** A turn that ended waiting for the caller to allow or refuse paid calls. */
-interface PendingApproval {
+/** A paid call a `calls` pendingApproval is holding back. */
+interface PendingApprovalCall {
+    id: string;
+    provider: string;
+    capability: string;
+    input: Record<string, unknown>;
+    more?: Record<string, unknown>[];
+    creditsEstimate: number | null;
+}
+interface PendingApprovalBase {
     id: string;
     reason: string;
-    calls: {
-        id: string;
-        provider: string;
-        capability: string;
-        input: Record<string, unknown>;
-        more?: Record<string, unknown>[];
-        creditsEstimate: number | null;
-    }[];
     resolution: null | {
         approved: boolean;
+        /** Calls approved. Ignored on terms offers. */
         callIds: string[];
         always: boolean;
         byRunId: string;
     };
 }
+/**
+ * A turn that ended waiting for the caller to allow or refuse paid calls.
+ * `kind` is absent on items written before terms offers existed.
+ */
+interface PendingCallsApproval extends PendingApprovalBase {
+    kind?: "calls";
+    calls: PendingApprovalCall[];
+    terms?: never;
+}
+/**
+ * A turn that ended waiting for the caller to accept providers' data terms
+ * ("ask" mode). `calls` is always empty (typed `never[]` rather
+ * than `[]` so existing `pendingApproval.calls[0]` code still compiles).
+ */
+interface PendingTermsApproval extends PendingApprovalBase {
+    kind: "terms";
+    calls: never[];
+    terms: AgentTermsGate[];
+}
+/** Narrow on `kind === "terms"`. */
+type PendingApproval = PendingCallsApproval | PendingTermsApproval;
 interface AgentResponse {
     success: boolean;
     id: string;
@@ -1588,6 +1704,7 @@ interface RequiresAction {
 }
 declare function parseRequiresAction(value: unknown): RequiresAction | undefined;
 declare class SdkError extends Error {
+    agent_hints?: string[];
     requestId?: string;
     status?: number;
     code?: string;
@@ -1631,10 +1748,12 @@ interface BrowserExecuteResponse {
     stderr?: string;
     exitCode?: number;
     killed?: boolean;
+    truncated?: boolean;
     error?: string;
 }
 interface BrowserDeleteResponse {
     success: boolean;
+    status?: string;
     sessionDurationMs?: number;
     creditsBilled?: number;
     error?: string;
@@ -3409,4 +3528,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentThread, type AgentThreadResponse, type AgentThreadRun, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AlexandriaCall, type AlexandriaOptions, type AlexandriaScrapeData, type AlexandriaScrapeError, type AlexandriaScrapeRequest, type AlexandriaScrapeResult, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type DiscoveredTool, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, type FindToolsData, type FindToolsOptions, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, type ImageParser, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, type RequiresAction, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default, parseRequiresAction };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOnTermsRequired, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSkippedProvider, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentTermsGate, type AgentTermsRequiredAction, type AgentThread, type AgentThreadResponse, type AgentThreadRun, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AlexandriaCall, type AlexandriaOptions, type AlexandriaScrapeData, type AlexandriaScrapeError, type AlexandriaScrapeRequest, type AlexandriaScrapeResult, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type DiscoveredTool, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, type FindToolsData, type FindToolsOptions, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, type ImageParser, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PendingApprovalCall, type PendingCallsApproval, type PendingTermsApproval, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, type RequiresAction, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default, parseRequiresAction };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-I2DFXQYR.js";
+} from "./chunk-OCJTYRX5.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -185,6 +185,12 @@ var JobTimeoutError = class extends SdkError {
   }
 };
 
+// src/v2/utils/agentHints.ts
+function agentHintMetadata(body) {
+  const hints = body?.agent_hints;
+  return Array.isArray(hints) && hints.every((hint) => typeof hint === "string") ? { agent_hints: [...hints] } : {};
+}
+
 // src/utils/zodSchemaToJson.ts
 import { zodToJsonSchema as zodToJsonSchemaLib } from "zod-to-json-schema";
 function isZodSchema(value) {
@@ -418,7 +424,7 @@ function throwForBadResponse(resp, action) {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
-  throw new SdkError(
+  throw Object.assign(new SdkError(
     msg,
     status,
     body?.code,
@@ -426,14 +432,14 @@ function throwForBadResponse(resp, action) {
     void 0,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction)
-  );
+  ), agentHintMetadata(body));
 }
 function normalizeAxiosError(err, action) {
   const status = err.response?.status;
   const body = err.response?.data;
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = body?.code || err.code;
-  throw new SdkError(
+  throw Object.assign(new SdkError(
     message,
     status,
     code,
@@ -441,7 +447,7 @@ function normalizeAxiosError(err, action) {
     void 0,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction)
-  );
+  ), agentHintMetadata(body));
 }
 function isRetryableError(err) {
   if (err instanceof JobTimeoutError) {
@@ -509,7 +515,7 @@ async function scrape(http, url, options, deps = {}) {
       if (res.status !== 200 || !res.data?.success) {
         throwForBadResponse(res, "scrape");
       }
-      return res.data.data || {};
+      return { ...res.data.data, ...agentHintMetadata(res.data) };
     } catch (err) {
       const delayMs = autoResume !== false ? processingContinuesDelayMs(err) : void 0;
       if (delayMs !== void 0 && resumes < RESUME_MAX_ATTEMPTS && resumeWaitedMs + delayMs <= RESUME_MAX_TOTAL_WAIT_MS) {
@@ -626,7 +632,7 @@ async function parse(http, file, options) {
     if (res.status !== 200 || !res.data?.success) {
       throwForBadResponse(res, "parse");
     }
-    return res.data.data || {};
+    return { ...res.data.data, ...agentHintMetadata(res.data) };
   } catch (err) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "parse");
     throw err;
@@ -700,7 +706,7 @@ async function search(http, request) {
       throwForBadResponse(res, "search");
     }
     const data = res.data.data || {};
-    const out = {};
+    const out = { ...agentHintMetadata(res.data) };
     if (res.data.warning) out.warning = res.data.warning;
     if (data.web) out.web = transformArray(data.web);
     if (data.news) out.news = transformArray(data.news);
@@ -905,7 +911,7 @@ async function map(http, url, options) {
           description: item.description
         });
     }
-    return { id: res.data.id, links };
+    return { id: res.data.id, links, ...agentHintMetadata(res.data) };
   } catch (err) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "map");
     throw err;
@@ -2667,7 +2673,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-V72LKFNW.js");
+      const packageJson = await import("./package-ECWDBUY3.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-V72LKFNW.js → package-ECWDBUY3.js}

@@ -1,4 +1,4 @@
 import {
   require_package
-} from "./chunk-I2DFXQYR.js";
+} from "./chunk-OCJTYRX5.js";
 export default require_package();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.41.0",
+  "version": "4.42.0",
   "description": "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/__tests__/unit/v2/agent-hints.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import { search } from "../../../v2/methods/search";
+import { scrape } from "../../../v2/methods/scrape";
+import { parse } from "../../../v2/methods/parse";
+import { map } from "../../../v2/methods/map";
+import {
+  normalizeAxiosError,
+  throwForBadResponse,
+} from "../../../v2/utils/errorHandler";
+
+const hints = [
+  "Scrape a selected search result if you need full page content.",
+  "Evaluate this result before submitting feedback.",
+];
+function httpFor(body: object) {
+  return {
+    post: jest.fn<any>().mockResolvedValue({ status: 200, data: body }),
+    postMultipart: jest
+      .fn<any>()
+      .mockResolvedValue({ status: 200, data: body }),
+  } as any;
+}
+
+describe("agent hints survive SDK response unwrapping", () => {
+  it("preserves search hints without adding them to records", async () => {
+    const web = [{ url: "https://example.com" }];
+    const result = await search(
+      httpFor({ success: true, data: { web }, agent_hints: hints }),
+      { query: "test" },
+    );
+    expect(result.web).toEqual(web);
+    expect(result.web[0]).not.toHaveProperty("agent_hints");
+    expect(result.agent_hints).toEqual(hints);
+    expect(JSON.parse(JSON.stringify(result)).agent_hints).toEqual(hints);
+  });
+
+  it("keeps existing search output unchanged when hints are absent", async () => {
+    const result = await search(httpFor({ success: true, data: { web: [] } }), {
+      query: "test",
+    });
+    expect(Object.keys(result)).toEqual(["web"]);
+  });
+
+  it.each(["scrape", "parse"])(
+    "keeps %s hints separate from document content",
+    async (method) => {
+      const http = httpFor({
+        success: true,
+        data: { markdown: "# Page" },
+        agent_hints: hints,
+      });
+      const result =
+        method === "scrape"
+          ? await scrape(http, "https://example.com")
+          : await parse(http, { filename: "page.txt", data: "Page" });
+      expect(result.markdown).toBe("# Page");
+      expect(result.agent_hints).toEqual(hints);
+    },
+  );
+
+  it("preserves map metadata alongside normalized links", async () => {
+    const result = await map(
+      httpFor({
+        success: true,
+        id: "map-id",
+        links: ["https://example.com"],
+        agent_hints: hints,
+      }),
+      "https://example.com",
+    );
+    expect(result).toEqual({
+      id: "map-id",
+      links: [{ url: "https://example.com" }],
+      agent_hints: hints,
+    });
+  });
+
+  it.each([null, "unexpected", [123]])(
+    "ignores malformed optional hints: %j",
+    async (value) => {
+      const result = await search(
+        httpFor({ success: true, data: {}, agent_hints: value }),
+        { query: "test" },
+      );
+      expect(result).not.toHaveProperty("agent_hints");
+    },
+  );
+
+  it("preserves hints on HTTP and Axios errors without changing their status", () => {
+    const response = {
+      status: 400,
+      data: {
+        success: false,
+        code: "INVALID",
+        error: "Invalid request",
+        agent_hints: hints,
+      },
+    } as any;
+    for (const raise of [
+      () => throwForBadResponse(response, "search"),
+      () =>
+        normalizeAxiosError({ response, isAxiosError: true } as any, "search"),
+    ]) {
+      try {
+        raise();
+        throw new Error("Expected SDK error");
+      } catch (error) {
+        expect(error).toMatchObject({
+          status: 400,
+          code: "INVALID",
+          agent_hints: hints,
+        });
+      }
+    }
+  });
+});

package/src/__tests__/unit/v2/agent-thread.unit.test.ts

@@ -161,4 +161,126 @@ describe("v2.agent threads unit", () => {
       "/v2/agent/threads/thread-1?includeData=true",
     );
   });
+  test("startAgent forwards exchange.onTermsRequired and a terms approve", async () => {
+    const post = okPost();
+    const exchange = {
+      onTermsRequired: "ask" as const,
+      approve: { approvalId: "0199aaaa-0000-7000-8000-000000000000" },
+    };
+
+    await startAgent({ post } as any, {
+      prompt: "Continue",
+      threadId: "thread-1",
+      exchange,
+    });
+
+    expect(post).toHaveBeenCalledWith("/v2/agent", {
+      prompt: "Continue",
+      threadId: "thread-1",
+      exchange,
+    });
+  });
+
+  test("startAgent forwards exchange.onTermsRequired skip", async () => {
+    const post = okPost();
+
+    await startAgent({ post } as any, {
+      prompt: "Find the key business contact at exa.ai",
+      exchange: { onTermsRequired: "skip" },
+    });
+
+    expect(post).toHaveBeenCalledWith("/v2/agent", {
+      prompt: "Find the key business contact at exa.ai",
+      exchange: { onTermsRequired: "skip" },
+    });
+  });
+
+  test("getAgentStatus parses skippedProviders, requiresAction and a terms approval", async () => {
+    const approvalId = "0199aaaa-0000-7000-8000-000000000000";
+    const get = jest.fn().mockResolvedValue({
+      status: 200,
+      data: {
+        success: true,
+        status: "completed",
+        data: null,
+        model: "spark-2",
+        expiresAt: "2026-09-02T00:00:00.000Z",
+        exchange: {
+          enabled: true,
+          onTermsRequired: "ask",
+          paidCalls: 0,
+          creditsUsed: null,
+          skippedProviders: [
+            {
+              provider: "apollo",
+              name: "Apollo",
+              capability: "people/search",
+              adds: "verified work emails",
+              reason: "terms_required",
+              version: "F-1.0.0",
+              termsUrl: "https://www.firecrawl.dev/app/alexandria/apollo",
+            },
+          ],
+          requiresAction: {
+            type: "accept_terms",
+            approvalId,
+            providers: [
+              {
+                provider: "apollo",
+                name: "Apollo",
+                version: "F-1.0.0",
+                digest: null,
+                url: "https://www.firecrawl.dev/app/alexandria/apollo",
+                show: {
+                  provider: "firecrawl",
+                  capability: "terms/show",
+                  options: { provider: "apollo" },
+                },
+                accept: {
+                  provider: "firecrawl",
+                  capability: "terms/accept",
+                  options: {
+                    provider: "apollo",
+                    version: "F-1.0.0",
+                    digest: null,
+                    confirmed: true,
+                  },
+                },
+              },
+            ],
+          },
+        },
+        pendingApproval: {
+          id: approvalId,
+          kind: "terms",
+          reason: "Apollo could add verified work emails.",
+          calls: [],
+          terms: [
+            {
+              provider: "apollo",
+              name: "Apollo",
+              version: "F-1.0.0",
+              digest: null,
+              url: "https://www.firecrawl.dev/app/alexandria/apollo",
+            },
+          ],
+          resolution: null,
+        },
+      },
+    });
+
+    const status = await getAgentStatus({ get } as any, "agent-job");
+
+    expect(status.exchange!.onTermsRequired).toBe("ask");
+    expect(status.exchange!.skippedProviders![0].reason).toBe("terms_required");
+    const action = status.exchange!.requiresAction!;
+    expect(action.approvalId).toBe(approvalId);
+    expect(action.providers[0].accept.capability).toBe("terms/accept");
+    expect(action.providers[0].accept.options.digest).toBeNull();
+    const pending = status.pendingApproval!;
+    expect(pending.kind).toBe("terms");
+    if (pending.kind !== "terms") throw new Error("expected a terms approval");
+    expect(pending.calls).toEqual([]);
+    expect(pending.terms[0].provider).toBe("apollo");
+  });
 });

package/src/v2/methods/map.ts

@@ -1,5 +1,6 @@
 import { type MapData, type MapOptions, type SearchResultWeb } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import {
   throwForBadResponse,
   normalizeAxiosError,
@@ -65,7 +66,7 @@ export async function map(
           description: (item as any).description,
         });
     }
-    return { id: res.data.id, links };
+    return { id: res.data.id, links, ...agentHintMetadata(res.data) };
   } catch (err: any) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "map");
     throw err;

package/src/v2/methods/parse.ts

@@ -1,5 +1,6 @@
 import { type Document, type ParseFile, type ParseOptions } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import { ensureValidParseOptions } from "../utils/validation";
 import {
   throwForBadResponse,
@@ -88,7 +89,7 @@ export async function parse(
     if (res.status !== 200 || !res.data?.success) {
       throwForBadResponse(res, "parse");
     }
-    return (res.data.data || {}) as Document;
+    return { ...res.data.data, ...agentHintMetadata(res.data) };
   } catch (err: any) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "parse");
     throw err;

package/src/v2/methods/scrape.ts

@@ -6,6 +6,7 @@ import {
   type ScrapeOptions,
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import { ensureValidScrapeOptions } from "../utils/validation";
 import {
   throwForBadResponse,
@@ -131,7 +132,7 @@ export async function scrape(
       if (res.status !== 200 || !res.data?.success) {
         throwForBadResponse(res, "scrape");
       }
-      return (res.data.data || {}) as Document;
+      return { ...res.data.data, ...agentHintMetadata(res.data) };
     } catch (err: any) {
       const delayMs = autoResume !== false ? processingContinuesDelayMs(err) : undefined;
       if (

package/src/v2/methods/search.ts

@@ -8,6 +8,7 @@ import {
   type SearchResultImages,
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import { ensureValidScrapeOptions } from "../utils/validation";
 import {
   throwForBadResponse,
@@ -101,7 +102,7 @@ export async function search(
       throwForBadResponse(res, "search");
     }
     const data = (res.data.data || {}) as Record<string, any>;
-    const out: SearchData = {};
+    const out: SearchData = { ...agentHintMetadata(res.data) };
     if (res.data.warning) out.warning = res.data.warning;
     if (data.web) out.web = transformArray<SearchResultWeb>(data.web);
     if (data.news) out.news = transformArray<SearchResultNews>(data.news);

package/src/v2/types.ts

@@ -678,6 +678,8 @@ export interface DocumentMetadata {
 }
 
 export interface Document {
+  /** API guidance, separate from extracted page content. */
+  agent_hints?: string[];
   markdown?: string;
   html?: string;
   rawHtml?: string;
@@ -820,6 +822,7 @@ export interface SearchResultImages {
 }
 
 export interface SearchData {
+  agent_hints?: string[];
   warning?: string;
   web?: Array<SearchResultWeb | Document>;
   news?: Array<SearchResultNews | Document>;
@@ -1086,6 +1089,7 @@ export interface BatchScrapeJob {
 }
 
 export interface MapData {
+  agent_hints?: string[];
   id?: string;
   links: SearchResultWeb[];
 }
@@ -1449,9 +1453,83 @@ export interface AgentExchangeOptions {
   toolkits?: string[];
   maxCalls?: number;
   requireApproval?: boolean;
-  /** Answers a pendingApproval from the previous turn of the thread. */
+  /**
+   * Answers a pendingApproval from the previous turn of the thread. A `terms`
+   * approval is accepted or declined as a whole: `callIds` and `always` are
+   * ignored on it.
+   */
   approve?: { approvalId: string; callIds?: string[]; always?: boolean };
   decline?: { approvalId: string };
+  /**
+   * What to do when a provider the agent would use needs data terms the team
+   * has not accepted. Gated providers are never called in any mode:
+   * - "skip" (server default): answer with accepted providers only and list
+   *   the gated ones in `exchange.skippedProviders`.
+   * - "ask": the same, plus `exchange.requiresAction` and a `terms`
+   *   pendingApproval. Get your user's explicit consent, call terms/accept,
+   *   then continue the thread with `approve: { approvalId }`.
+   * Terms gating is rolling out: until it is on for a thread, none of the
+   * terms fields appear. There is no auto-accept mode. Omitted on a follow-up turn inherits the
+   * previous turn's value.
+   */
+  onTermsRequired?: AgentOnTermsRequired;
+}
+
+export type AgentOnTermsRequired = "skip" | "ask";
+
+/** A gated provider the run would have used but did not. */
+export interface AgentSkippedProvider {
+  provider: string;
+  name: string;
+  capability?: string;
+  /** What it would have added, in the agent's words. */
+  adds?: string;
+  reason: "terms_required";
+  /** The gating terms version. */
+  version: string;
+  /** Where a person accepts the terms in the dashboard. */
+  termsUrl: string;
+}
+
+/**
+ * The exact Exchange calls to view and accept a provider's terms. Nothing here
+ * is executed for you, and terms/accept must only be called after the user
+ * has explicitly agreed to that provider's terms.
+ */
+export interface AgentTermsRequiredAction {
+  type: "accept_terms";
+  /**
+   * The `terms` pendingApproval that answers this. After the user agrees and
+   * terms/accept succeeds, continue the thread with
+   * `exchange.approve: { approvalId }`, or refuse with `decline`.
+   */
+  approvalId: string;
+  providers: {
+    provider: string;
+    name: string;
+    capability?: string;
+    adds?: string;
+    version: string;
+    /** null when the catalog published no digest; terms/show returns it. */
+    digest: string | null;
+    url: string;
+    show: {
+      provider: "firecrawl";
+      capability: "terms/show";
+      options: { provider: string };
+    };
+    accept: {
+      provider: "firecrawl";
+      capability: "terms/accept";
+      options: {
+        provider: string;
+        version: string;
+        /** null when the catalog published no digest; terms/show returns it. */
+        digest: string | null;
+        confirmed: true;
+      };
+    };
+  }[];
 }
 
 /** Per-run summary reported on a status response. */
@@ -1460,8 +1538,26 @@ export interface AgentExchangeSummary {
   /** What the run resolved to after thread inheritance, not what it requested. */
   toolkits?: string[];
   requireApproval?: boolean;
+  onTermsRequired?: AgentOnTermsRequired;
   paidCalls: number;
   creditsUsed: number | null;
+  /** Gated providers that would have helped and were not used. Any mode. */
+  skippedProviders?: AgentSkippedProvider[];
+  /** "ask" mode, when a terms offer ended the turn. */
+  requiresAction?: AgentTermsRequiredAction;
+}
+
+/** A provider in a `terms` pendingApproval. */
+export interface AgentTermsGate {
+  provider: string;
+  name: string;
+  logo?: string;
+  capability?: string;
+  adds?: string;
+  version: string;
+  /** null when the catalog published no digest; terms/show returns it. */
+  digest: string | null;
+  url: string;
 }
 
 /** A follow-up the agent offers for the next turn of the thread. */
@@ -1470,26 +1566,52 @@ export interface AgentSuggestion {
   prompt: string;
 }
 
-/** A turn that ended waiting for the caller to allow or refuse paid calls. */
-export interface PendingApproval {
+/** A paid call a `calls` pendingApproval is holding back. */
+export interface PendingApprovalCall {
+  id: string;
+  provider: string;
+  capability: string;
+  input: Record<string, unknown>;
+  more?: Record<string, unknown>[];
+  creditsEstimate: number | null;
+}
+
+interface PendingApprovalBase {
   id: string;
   reason: string;
-  calls: {
-    id: string;
-    provider: string;
-    capability: string;
-    input: Record<string, unknown>;
-    more?: Record<string, unknown>[];
-    creditsEstimate: number | null;
-  }[];
   resolution: null | {
     approved: boolean;
+    /** Calls approved. Ignored on terms offers. */
     callIds: string[];
     always: boolean;
     byRunId: string;
   };
 }
 
+/**
+ * A turn that ended waiting for the caller to allow or refuse paid calls.
+ * `kind` is absent on items written before terms offers existed.
+ */
+export interface PendingCallsApproval extends PendingApprovalBase {
+  kind?: "calls";
+  calls: PendingApprovalCall[];
+  terms?: never;
+}
+
+/**
+ * A turn that ended waiting for the caller to accept providers' data terms
+ * ("ask" mode). `calls` is always empty (typed `never[]` rather
+ * than `[]` so existing `pendingApproval.calls[0]` code still compiles).
+ */
+export interface PendingTermsApproval extends PendingApprovalBase {
+  kind: "terms";
+  calls: never[];
+  terms: AgentTermsGate[];
+}
+
+/** Narrow on `kind === "terms"`. */
+export type PendingApproval = PendingCallsApproval | PendingTermsApproval;
+
 export interface AgentResponse {
   success: boolean;
   id: string;
@@ -1876,6 +1998,7 @@ export function parseRequiresAction(value: unknown): RequiresAction | undefined
 }
 
 export class SdkError extends Error {
+  declare agent_hints?: string[];
   requestId?: string;
   status?: number;
   code?: string;
@@ -1956,11 +2079,13 @@ export interface BrowserExecuteResponse {
   stderr?: string;
   exitCode?: number;
   killed?: boolean;
+  truncated?: boolean;
   error?: string;
 }
 
 export interface BrowserDeleteResponse {
   success: boolean;
+  status?: string;
   sessionDurationMs?: number;
   creditsBilled?: number;
   error?: string;

package/src/v2/utils/agentHints.ts

@@ -0,0 +1,7 @@
+/** Keep response guidance as metadata when convenience methods unwrap data. */
+export function agentHintMetadata(body: unknown): { agent_hints?: string[] } {
+  const hints = (body as { agent_hints?: unknown } | null)?.agent_hints;
+  return Array.isArray(hints) && hints.every((hint) => typeof hint === "string")
+    ? { agent_hints: [...hints] }
+    : {};
+}

package/src/v2/utils/errorHandler.ts

@@ -1,11 +1,12 @@
 import { type AxiosError, type AxiosResponse } from "axios";
 import { SdkError, JobTimeoutError, parseRequiresAction } from "../types";
+import { agentHintMetadata } from "./agentHints";
 
 export function throwForBadResponse(resp: AxiosResponse, action: string): never {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
-  throw new SdkError(
+  throw Object.assign(new SdkError(
     msg,
     status,
     body?.code,
@@ -13,7 +14,7 @@ export function throwForBadResponse(resp: AxiosResponse, action: string): never
     undefined,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction),
-  );
+  ), agentHintMetadata(body));
 }
 
 export function normalizeAxiosError(err: AxiosError, action: string): never {
@@ -21,7 +22,7 @@ export function normalizeAxiosError(err: AxiosError, action: string): never {
   const body: any = err.response?.data;
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = (body?.code as string) || err.code;
-  throw new SdkError(
+  throw Object.assign(new SdkError(
     message,
     status,
     code,
@@ -29,7 +30,7 @@ export function normalizeAxiosError(err: AxiosError, action: string): never {
     undefined,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction),
-  );
+  ), agentHintMetadata(body));
 }
 
 export function isRetryableError(err: any): boolean {
@@ -64,4 +65,3 @@ export function isRetryableError(err: any): boolean {
   // Default: retry on unknown errors (safer than not retrying)
   return true;
 }
-