@agent-native/core 0.208.0 → 0.208.1-nightly-20261013212700

package/dist/agent/context-xray/tokenize.js

@@ -7,9 +7,18 @@ async function loadTokenizer() {
         // browser fallback, while the documented estimate below is sufficient
         // when an edge runtime cannot resolve the tokenizer.
         tokenizerPromise = import(/* @vite-ignore */ TOKENIZER_MODULE_ID)
-            .then((mod) => typeof mod.countTokens === "function"
-            ? mod.countTokens
-            : null)
+            .then((mod) => {
+            // The package's countTokens rebuilds the BPE encoder on every call
+            // (~20 ms); counting a whole context part by part before each model
+            // call turned that into seconds of dead time per turn.
+            if (typeof mod.getTokenizer === "function") {
+                const encoder = mod.getTokenizer();
+                return (text) => encoder.encode(text.normalize("NFKC"), "all").length;
+            }
+            return typeof mod.countTokens === "function"
+                ? mod.countTokens
+                : null;
+        })
             .catch(() => null);
     }
     return tokenizerPromise;

package/dist/agent/run-manager.js

@@ -10,7 +10,7 @@ import { classifyTerminalErrorCode, describeErrorWithCauses, isProviderConnectio
 import { runErrorTelemetryProperties } from "./engine/error-telemetry.js";
 import { getAgentEngineEntry } from "./engine/registry.js";
 import { EngineError } from "./engine/types.js";
-import { insertRun, insertRunEvent, updateRunStatusIfRunning, markRunAborted, getRunAbortState, getRunStatus, getRunEventsSince, getCurrentTurnRunEventsForThread, getRunById, getRunByThread, getRunTurnRef, markTurnAborted, cleanupOldRuns, updateRunHeartbeat, bumpRunProgress, setRunInFlightMarker, reapIfStale, reapUnclaimedBackgroundRun, shouldRedispatchUnclaimedBackgroundRun, reconcileTerminalRunFromEvents, ensureTerminalRunEvent, getLastTerminalRunEvent, resolveErroredRunTerminalEvent, setRunError, setRunTerminalReason, persistRunCheckpointEvent, recordRunDiagnostic, RUN_DIAG_STAGE, terminalEventForAbortReason, RUN_RECORD_MISSING_ERROR_EVENT, RUN_RECORD_MISSING_GRACE_MS, RUN_TERMINAL_LOOKUP_FAILED_ERROR_EVENT, UNKNOWN_RUN_STATUS_ERROR_EVENT, } from "./run-store.js";
+import { insertRun, insertRunEvent, insertRunEvents, updateRunStatusIfRunning, markRunAborted, getRunAbortState, getRunStatus, getRunEventsSince, getCurrentTurnRunEventsForThread, getRunById, getRunByThread, getRunTurnRef, markTurnAborted, cleanupOldRuns, updateRunHeartbeat, bumpRunProgress, setRunInFlightMarker, reapIfStale, reapUnclaimedBackgroundRun, shouldRedispatchUnclaimedBackgroundRun, reconcileTerminalRunFromEvents, ensureTerminalRunEvent, getLastTerminalRunEvent, resolveErroredRunTerminalEvent, setRunError, setRunTerminalReason, persistRunCheckpointEvent, recordRunDiagnostic, RUN_DIAG_STAGE, terminalEventForAbortReason, RUN_RECORD_MISSING_ERROR_EVENT, RUN_RECORD_MISSING_GRACE_MS, RUN_TERMINAL_LOOKUP_FAILED_ERROR_EVENT, UNKNOWN_RUN_STATUS_ERROR_EVENT, } from "./run-store.js";
 import { isContinuationTerminalReason } from "./types.js";
 const activeRuns = new Map();
 const threadToRun = new Map();
@@ -232,6 +232,11 @@ function isTerminalRunEvent(event) {
         event.type === "loop_limit" ||
         event.type === "auto_continue");
 }
+function isBatchableRunEvent(event) {
+    return (event.type !== "tool_start" &&
+        event.type !== "tool_done" &&
+        !isTerminalRunEvent(event));
+}
 /**
  * A tool result with no later assistant text is an unfinished turn, not a
  * successful terminal response. Keep this predicate beside the run-manager's
@@ -570,6 +575,10 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
             throw error;
     });
     let persistenceChain = Promise.resolve();
+    // Streamed deltas arrive hundreds per tool call, and a write tool waits for
+    // every queued event to persist first; one round trip per event put tens of
+    // seconds between the model finishing and the tool starting.
+    let openEventBatch = null;
     const PROGRESS_BUMP_INTERVAL_MS = 1_000;
     let lastProgressBumpAt = 0;
     let progressWriteInFlight = null;
@@ -1029,18 +1038,20 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
             },
         });
     };
-    const persistRunEvent = async (runEvent, eventData) => {
+    const persistEventHook = options?.persistEvent;
+    const persistRunEvent = async (runEvent, eventData, eventAt) => {
         if (runEvent.event.type === "tool_start")
             await insertRunPromise;
         const write = () => runEvent.event.type === "tool_start" ||
             runEvent.event.type === "tool_done"
             ? insertRunEvent(runId, runEvent.seq, eventData, {
+                eventAt,
                 toolInputSource: "execution",
                 ...(runEvent.event.type === "tool_start"
                     ? { requireInserted: true }
                     : {}),
             })
-            : insertRunEvent(runId, runEvent.seq, eventData);
+            : insertRunEvent(runId, runEvent.seq, eventData, { eventAt });
         return options?.persistEvent
             ? options.persistEvent(write, {
                 terminal: isTerminalRunEvent(runEvent.event),
@@ -1052,6 +1063,7 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
     };
     const emitRunEvent = (runEvent, options) => {
         const eventData = JSON.stringify(runEvent.event);
+        const eventAt = Date.now();
         run.events.push(runEvent);
         for (const subscriber of run.subscribers) {
             try {
@@ -1066,9 +1078,9 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
             lastRealProgressAt = Date.now();
             bumpProgressIfDue();
         }
-        const thisInsert = persistenceChain.then(async () => {
+        const retryOnce = async (write) => {
             try {
-                await persistRunEvent(runEvent, eventData);
+                await write();
             }
             catch (error) {
                 if (!eventPersistenceErrorCaptured) {
@@ -1078,11 +1090,36 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                         eventType: runEvent.event.type,
                     });
                 }
-                await persistRunEvent(runEvent, eventData);
+                await write();
             }
-        });
-        persistenceChain = thisInsert;
-        const persistence = thisInsert;
+        };
+        let persistence;
+        if (isBatchableRunEvent(runEvent.event) && !persistEventHook) {
+            if (!openEventBatch) {
+                const batch = {
+                    events: [],
+                    write: persistenceChain.then(() => {
+                        if (openEventBatch === batch)
+                            openEventBatch = null;
+                        return retryOnce(() => insertRunEvents(runId, batch.events));
+                    }),
+                };
+                openEventBatch = batch;
+                persistenceChain = batch.write;
+            }
+            openEventBatch.events.push({
+                seq: runEvent.seq,
+                eventAt,
+                eventData,
+            });
+            persistence = openEventBatch.write;
+        }
+        else {
+            // Anything emitted after this event must not persist before it.
+            openEventBatch = null;
+            persistence = persistenceChain.then(() => retryOnce(() => persistRunEvent(runEvent, eventData, eventAt)));
+            persistenceChain = persistence;
+        }
         if (!options?.surfacePersistenceError) {
             persistence.catch(() => { });
         }
@@ -1275,7 +1312,7 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                     console.error("[run-manager] terminal event persistence error:", err instanceof Error ? err.message : err);
                     if (!eventPersistenceError) {
                         try {
-                            await persistRunEvent(terminal, JSON.stringify(terminal.event));
+                            await persistRunEvent(terminal, JSON.stringify(terminal.event), Date.now());
                             terminalPersistenceError = null;
                         }
                         catch (retryError) {

package/dist/agent/run-store.d.ts

@@ -285,7 +285,17 @@ export declare class AgentRunEventNotPersistedError extends Error {
 export declare function insertRunEvent(runId: string, seq: number, eventData: string, options?: {
     toolInputSource?: "execution";
     requireInserted?: boolean;
+    eventAt?: number;
 }): Promise<void>;
+/**
+ * Same guarantees as `insertRunEvent` without execution-input fingerprints,
+ * so tool_start/tool_done must keep going through `insertRunEvent`.
+ */
+export declare function insertRunEvents(runId: string, events: ReadonlyArray<{
+    seq: number;
+    eventAt: number;
+    eventData: string;
+}>): Promise<void>;
 export declare const CHECKPOINT_TERMINAL_EVENT_SEQ = 1000000000;
 export declare function persistRunCheckpointEvent(runId: string, event: AgentChatEvent, terminalReason: string): Promise<void>;
 export declare function getRunEventsSince(runId: string, fromSeq: number, opts?: {

package/dist/agent/run-store.js

@@ -1910,7 +1910,7 @@ export async function insertRunEvent(runId, seq, eventData, options) {
         args: [
             runId,
             seq,
-            Date.now(),
+            options?.eventAt ?? Date.now(),
             storedEventData,
             ...(options?.requireInserted ? [] : [runId]),
         ],
@@ -1918,6 +1918,42 @@ export async function insertRunEvent(runId, seq, eventData, options) {
     if (options?.requireInserted && rowsAffected !== 1)
         throw new AgentRunEventNotPersistedError(runId, seq);
 }
+// Stays well under PostgreSQL's 65,535 bind-parameter limit at 4 per row.
+const RUN_EVENT_BATCH_ROWS = 500;
+/**
+ * Same guarantees as `insertRunEvent` without execution-input fingerprints,
+ * so tool_start/tool_done must keep going through `insertRunEvent`.
+ */
+export async function insertRunEvents(runId, events) {
+    if (events.length === 0)
+        return;
+    await ensureRunTables();
+    const client = getDbExec();
+    for (let start = 0; start < events.length; start += RUN_EVENT_BATCH_ROWS) {
+        const chunk = events.slice(start, start + RUN_EVENT_BATCH_ROWS);
+        await client.execute({
+            sql: `INSERT INTO agent_run_events (run_id, seq, event_at, event_data)
+        SELECT v.run_id, v.seq, v.event_at, v.event_data
+        FROM (VALUES ${chunk
+                .map(() => "(CAST(? AS TEXT), CAST(? AS BIGINT), CAST(? AS BIGINT), CAST(? AS TEXT))")
+                .join(", ")}) AS v(run_id, seq, event_at, event_data)
+        WHERE NOT EXISTS (
+          SELECT 1 FROM agent_runs
+          WHERE id = ? AND status <> 'running'
+        )
+        ON CONFLICT (run_id, seq) DO NOTHING`,
+            args: [
+                ...chunk.flatMap(({ seq, eventAt, eventData }) => [
+                    runId,
+                    seq,
+                    eventAt,
+                    persistedRunEventData(eventData),
+                ]),
+                runId,
+            ],
+        });
+    }
+}
 export const CHECKPOINT_TERMINAL_EVENT_SEQ = 1_000_000_000;
 export async function persistRunCheckpointEvent(runId, event, terminalReason) {
     await insertRunEvent(runId, CHECKPOINT_TERMINAL_EVENT_SEQ, JSON.stringify(event));

package/dist/collab/awareness.d.ts

@@ -38,19 +38,19 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -13,8 +13,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
     };
 }>>;
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -1,6 +1,6 @@
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/extensions/fetch-tool.js

@@ -10,10 +10,12 @@
  * the raw secret never enters the model's context.
  */
 import { fail, isActionContractError } from "../action.js";
+import { SAVE_TO_FILE_MAX_BYTES } from "../workspace-files/constants.js";
 import { collectSecretValues, MAX_EXTENSION_PROXY_RESPONSE_SIZE, normalizeExtensionProxyMethod, readResponseBytesWithLimit, readResponseTextWithLimit, redactSecrets, redactString, sanitizeOutboundHeaders, } from "./proxy-security.js";
 import { createSsrfSafeDispatcher, isBlockedExtensionUrlWithDns, } from "./url-safety.js";
-import { formatWebContentResult, parseWebContentSearchOptions, processWebContent, } from "./web-content.js";
+import { formatWebContentResult, hasWebContentSearch, parseWebContentSearchOptions, processWebContent, } from "./web-content.js";
 const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_WEB_REQUEST_HTML_BYTES = SAVE_TO_FILE_MAX_BYTES;
 const VISION_IMAGE_CONTENT_TYPES = new Set([
     "image/jpeg",
     "image/png",
@@ -21,6 +23,20 @@ const VISION_IMAGE_CONTENT_TYPES = new Set([
     "image/webp",
 ]);
 const CREDENTIAL_NAME_RE = /(?:^|[-_])(access[-_]?token|api[-_]?key|auth(?:orization)?|credential|expires?|key[-_]?pair[-_]?id|key|password|passwd|policy|secret|session|signature|sig|token|jwt|assertion)(?:$|[-_])/i;
+function isHtmlResponseContentType(contentType) {
+    const mediaType = contentType.toLowerCase();
+    return (mediaType === "text/html" ||
+        mediaType === "application/xhtml+xml" ||
+        mediaType.endsWith("+html"));
+}
+function truncateToolText(value, maxChars) {
+    if (value.length <= maxChars)
+        return value;
+    const marker = "\n...[truncated]";
+    if (maxChars <= marker.length)
+        return marker.slice(0, maxChars);
+    return `${value.slice(0, maxChars - marker.length)}${marker}`;
+}
 function uint8ArrayToBase64(bytes) {
     if (typeof Buffer !== "undefined")
         return Buffer.from(bytes).toString("base64");
@@ -85,7 +101,7 @@ export function createFetchToolEntry(opts = {}) {
     return {
         "web-request": {
             tool: {
-                description: `Make an outbound HTTP request to any EXTERNAL URL — APIs, webhooks, and arbitrary web pages (HTML, RSS, JSON, etc.). Use this to fetch the contents of a URL the user pastes in chat. Sends realistic Chrome-on-macOS headers by default (User-Agent, Accept, Sec-Fetch-*) so most sites that block obvious bots will respond normally; pass an explicit header to override any default. Supports \${keys.NAME} placeholders in url, headers, and body — these are resolved server-side from the user's saved keys (the raw value never enters your context). Example: \${keys.SLACK_WEBHOOK} in the url field. IMPORTANT: Never use this to call internal /_agent-native/ endpoints or localhost action URLs — use the registered actions directly (e.g. \`search-records\`, \`provider-api-request\`, \`update-resource\`). Actions are already available as native tools; calling them via HTTP is slower and bypasses validation.`,
+                description: `Make an outbound HTTP request to an external URL: APIs, webhooks, or web pages. HTML/XHTML responses up to 20 MB are extracted before maxChars limits the response body; optional metadata and links can add characters. Raw and other inline responses remain capped at 1 MB. saveToFile can stage responses up to 20 MB. For HTML, it saves extracted Markdown or text unless responseMode is raw; with search, it returns bounded matches instead of a preview. Sends realistic Chrome-on-macOS headers by default; explicit headers override them. Supports \${keys.NAME} placeholders in url, headers, and body, resolved server-side so raw secrets never enter context. Never use this for internal /_agent-native/ endpoints or localhost action URLs; call registered actions directly.`,
                 parameters: {
                     type: "object",
                     properties: {
@@ -112,7 +128,7 @@ export function createFetchToolEntry(opts = {}) {
                         },
                         maxChars: {
                             type: "number",
-                            description: "Maximum response body characters to return. Default: 32000. Max: 200000. Increase when you need to read a large document, API response, or dataset.",
+                            description: "Maximum response-body characters returned to context. Default: 32000; max: 200000. Metadata and optional links are additional. This limits extracted content, not the HTML download. Use saveToFile for a longer extracted document.",
                         },
                         responseMode: {
                             type: "string",
@@ -134,11 +150,11 @@ export function createFetchToolEntry(opts = {}) {
                         },
                         includeLinks: {
                             type: "boolean",
-                            description: "Whether extracted HTML responses should include a compact links list. Default: true for extracted pages.",
+                            description: "Whether extracted HTML responses should include a compact links list. Default: true for inline responses and false when saveToFile is set.",
                         },
                         search: {
                             type: "object",
-                            description: "Optional post-fetch search over extracted content by default. Supports {query, queries, terms, regex, regexFlags, source:'extracted'|'raw', maxMatches, contextChars, caseSensitive}. Regex is safety-checked and bounded; prefer query/terms for simple grep-like searches.",
+                            description: "Optional post-fetch search over extracted content by default. Searches at most the first 500,000 characters of the selected source; saved results report searchSourceTruncated when this limit is reached. Supports {query, queries, terms, regex, regexFlags, source:'extracted'|'raw', maxMatches, contextChars, caseSensitive}. Regex is safety-checked and bounded; prefer query/terms for simple grep-like searches.",
                             properties: {
                                 query: { type: "string" },
                                 queries: { type: "array", items: { type: "string" } },
@@ -153,7 +169,7 @@ export function createFetchToolEntry(opts = {}) {
                         },
                         saveToFile: {
                             type: "string",
-                            description: "Workspace file path to save the full response body to instead of returning it in context (e.g. 'analysis/page.html'). When set, returns only a compact summary {savedTo, status, bytes, preview}. Useful for large web pages or API responses that would overflow context.",
+                            description: "Workspace path to stage a response up to 20 MB (e.g. 'scratch/research/page.md'). HTML saves full extracted Markdown/text unless responseMode is raw; non-HTML and raw mode save the response body. With search, returns matches bounded by maxChars and reports when source scanning was capped; without search, returns a preview.",
                         },
                     },
                     required: ["url"],
@@ -295,6 +311,9 @@ export function createFetchToolEntry(opts = {}) {
                     }
                     const contentType = response.headers.get("content-type")?.split(";")[0].trim() ??
                         "text/plain";
+                    const requestedResponseMode = String(args.responseMode ?? "auto");
+                    const normalizedResponseMode = requestedResponseMode.toLowerCase();
+                    const isHtmlContentType = isHtmlResponseContentType(contentType);
                     const httpErrorCode = response.ok
                         ? undefined
                         : `http_${response.status}`;
@@ -335,10 +354,11 @@ export function createFetchToolEntry(opts = {}) {
                     }
                     let body;
                     let bodyResult;
+                    const readLimit = saveToFilePath ||
+                        (isHtmlContentType && normalizedResponseMode !== "raw")
+                        ? MAX_WEB_REQUEST_HTML_BYTES
+                        : MAX_EXTENSION_PROXY_RESPONSE_SIZE;
                     try {
-                        const readLimit = saveToFilePath
-                            ? 20 * 1024 * 1024
-                            : MAX_EXTENSION_PROXY_RESPONSE_SIZE;
                         bodyResult = await readResponseTextWithLimit(response, readLimit);
                     }
                     catch {
@@ -347,8 +367,15 @@ export function createFetchToolEntry(opts = {}) {
                         });
                     }
                     if (bodyResult.truncated) {
-                        fail(`HTTP ${response.status} ${response.statusText}\n\n${bodyResult.text}`, {
-                            errorCode: httpErrorCode ?? "web_request_response_too_large",
+                        const declaredBytes = Number(response.headers.get("content-length"));
+                        const exceedsSaveLimit = readLimit === MAX_WEB_REQUEST_HTML_BYTES ||
+                            (Number.isFinite(declaredBytes) &&
+                                declaredBytes > MAX_WEB_REQUEST_HTML_BYTES);
+                        const recovery = exceedsSaveLimit
+                            ? `The response exceeds web-request's ${MAX_WEB_REQUEST_HTML_BYTES}-byte limit.`
+                            : `Retry with saveToFile to stage responses up to ${MAX_WEB_REQUEST_HTML_BYTES} bytes.`;
+                        fail(`HTTP ${response.status} ${response.statusText}\n\nResponse too large: at least ${bodyResult.size} bytes observed; maximum ${readLimit} bytes. ${recovery}`, {
+                            errorCode: "web_request_response_too_large",
                         });
                     }
                     body = bodyResult.text;
@@ -361,21 +388,69 @@ export function createFetchToolEntry(opts = {}) {
                     }
                     let displayBody;
                     let processedMode = "raw";
+                    let searchResultsTruncated = false;
+                    let searchSourceTruncated = false;
+                    let fileContent = body;
+                    let fileContentType = contentType;
+                    const search = parseWebContentSearchOptions(args.search);
+                    const hasSearch = hasWebContentSearch(search);
+                    const includeLinks = args.includeLinks === undefined
+                        ? !saveToFilePath
+                        : parseBooleanArg(args.includeLinks);
+                    const saveContentFormat = saveToFilePath &&
+                        isHtmlContentType &&
+                        normalizedResponseMode !== "raw"
+                        ? normalizedResponseMode === "text"
+                            ? "text"
+                            : "markdown"
+                        : undefined;
                     try {
                         const processed = await processWebContent({
                             url: resolvedUrl,
                             body,
                             contentType,
-                            responseMode: String(args.responseMode ?? "auto"),
+                            responseMode: saveToFilePath && hasSearch ? "matches" : requestedResponseMode,
                             extract: String(args.extract ?? "readability"),
-                            includeLinks: args.includeLinks === undefined
-                                ? true
-                                : parseBooleanArg(args.includeLinks),
-                            search: parseWebContentSearchOptions(args.search),
-                            maxChars,
+                            includeLinks,
+                            search,
+                            maxChars: saveContentFormat ? null : maxChars,
+                            saveContentFormat,
                         });
                         processedMode = processed.mode;
+                        searchSourceTruncated = processed.searchTruncated ?? false;
                         displayBody = formatWebContentResult(processed);
+                        if (saveToFilePath && hasSearch && displayBody.length > maxChars) {
+                            searchResultsTruncated = true;
+                            displayBody = truncateToolText(displayBody, maxChars);
+                        }
+                        if (saveContentFormat) {
+                            if (processed.fullContent === undefined) {
+                                throw new Error("HTML extraction did not produce saved content");
+                            }
+                            fileContent = formatWebContentResult({
+                                ...processed,
+                                mode: saveContentFormat,
+                                content: processed.fullContent,
+                                fullContent: undefined,
+                                matches: undefined,
+                                totalMatches: undefined,
+                                omittedMatches: undefined,
+                                searchSource: undefined,
+                                searchTruncated: undefined,
+                                truncated: false,
+                            });
+                            fileContentType =
+                                saveContentFormat === "markdown"
+                                    ? "text/markdown"
+                                    : "text/plain";
+                        }
+                        if (!saveToFilePath &&
+                            isHtmlContentType &&
+                            normalizedResponseMode !== "raw" &&
+                            processed.truncated &&
+                            processed.contentLength !== undefined) {
+                            displayBody += `\n\nFull extracted content: ${processed.contentLength} characters. Retry with saveToFile (up to ${MAX_WEB_REQUEST_HTML_BYTES} bytes), then use workspace-files grep or read with offsets.`;
+                        }
                     }
                     catch (err) {
                         fail(`web-request post-processing error: ${err?.message ?? String(err)}`, { errorCode: httpErrorCode ?? "web_request_processing_failed" });
@@ -383,7 +458,7 @@ export function createFetchToolEntry(opts = {}) {
                     console.log(`[fetch-tool] ${method} ${rawUrl} → ${response.status} (${elapsed}ms, keys: ${allUsedKeys.join(",") || "none"})`);
                     if (saveToFilePath) {
                         try {
-                            const { writeWorkspaceFile, SAVE_TO_FILE_MAX_BYTES, isScratchWorkspacePath, toWorkspaceFileCard, } = await import("../workspace-files/store.js");
+                            const { writeWorkspaceFile, isScratchWorkspacePath, toWorkspaceFileCard, } = await import("../workspace-files/store.js");
                             const { getRequestOrgId, getRequestUserEmail } = await import("../server/request-context.js");
                             const orgId = getRequestOrgId();
                             const email = getRequestUserEmail();
@@ -398,21 +473,37 @@ export function createFetchToolEntry(opts = {}) {
                             if (!response.ok && !scratchPath) {
                                 throw new Error(`Refusing to save a failed response to durable workspace file "${saveToFilePath}" (status ${response.status}). Use a scratch/... path for diagnostics.`);
                             }
-                            const meta = await writeWorkspaceFile(scope, saveToFilePath, body, contentType, {
+                            const savedFormat = saveContentFormat ?? "raw";
+                            const meta = await writeWorkspaceFile(scope, saveToFilePath, fileContent, fileContentType, {
                                 maxFileBytes: SAVE_TO_FILE_MAX_BYTES,
                             });
-                            const bytes = Buffer.byteLength(body, "utf8");
-                            const preview = displayBody.slice(0, 2000);
+                            const bytes = Buffer.byteLength(fileContent, "utf8");
+                            const previewSource = saveContentFormat
+                                ? fileContent
+                                : displayBody;
+                            const preview = previewSource.slice(0, 2000);
                             if (!response.ok)
-                                fail(`HTTP ${response.status} ${response.statusText}\n\n${displayBody}`, { errorCode: `http_${response.status}` });
+                                fail(`HTTP ${response.status} ${response.statusText}\n\n${truncateToolText(displayBody, maxChars)}`, { errorCode: `http_${response.status}` });
                             return JSON.stringify({
                                 savedToFile: true,
                                 savedTo: saveToFilePath,
                                 status: response.status,
                                 bytes,
+                                chars: fileContent.length,
                                 contentType,
+                                savedFormat,
                                 responseMode: processedMode,
-                                preview: preview.length < displayBody.length ? `${preview}…` : preview,
+                                ...(hasSearch
+                                    ? {
+                                        searchResults: displayBody,
+                                        searchResultsTruncated,
+                                        searchSourceTruncated,
+                                    }
+                                    : {
+                                        preview: preview.length < previewSource.length
+                                            ? `${preview}…`
+                                            : preview,
+                                    }),
                                 ...(scratchPath ? {} : { file: toWorkspaceFileCard(meta) }),
                             });
                         }

package/dist/extensions/web-content.d.ts

@@ -20,7 +20,9 @@ export interface WebContentProcessOptions {
     extract?: string;
     includeLinks?: boolean;
     search?: WebContentSearchOptions | null;
-    maxChars?: number;
+    /** `null` keeps the complete content available for a saved workspace file. */
+    maxChars?: number | null;
+    saveContentFormat?: "markdown" | "text";
 }
 export interface WebContentLink {
     text: string;
@@ -45,6 +47,8 @@ export interface WebContentResult {
     publishedTime?: string;
     agentMetadata?: unknown[];
     content?: string;
+    fullContent?: string;
+    contentLength?: number;
     links?: WebContentLink[];
     matches?: WebContentMatch[];
     totalMatches?: number;

package/dist/extensions/web-content.js

@@ -68,16 +68,33 @@ export async function processWebContent(options) {
     const html = isHtmlResponse(contentType, options.body);
     const mode = resolveMode(requestedMode, html, search);
     const emptyHtmlBody = html && !options.body.trim();
-    const maxChars = normalizeBoundedNumber(options.maxChars, DEFAULT_MAX_CONTENT_CHARS, 1, 200_000);
-    const extracted = html && !emptyHtmlBody && (mode !== "raw" || hasWebContentSearch(search))
-        ? await extractHtml(options.body, options.url, extract, mode === "markdown" || mode === "matches")
+    const maxChars = options.maxChars === null
+        ? Number.POSITIVE_INFINITY
+        : normalizeBoundedNumber(options.maxChars, DEFAULT_MAX_CONTENT_CHARS, 1, 200_000);
+    const extracted = html &&
+        !emptyHtmlBody &&
+        (mode !== "raw" || hasWebContentSearch(search) || options.saveContentFormat)
+        ? await extractHtml(options.body, options.url, extract, mode === "markdown" ||
+            mode === "matches" ||
+            options.saveContentFormat === "markdown")
         : null;
     const baseContent = contentForMode(mode, options.body, extracted);
+    const fullContent = options.saveContentFormat
+        ? options.saveContentFormat === "text"
+            ? (extracted?.text ?? (extracted ? "" : options.body))
+            : extracted?.markdown ||
+                extracted?.text ||
+                (extracted ? "" : options.body)
+        : undefined;
     const result = {
         mode,
         extract,
         contentType,
         ...metadataFromExtraction(extracted),
+        ...(fullContent !== undefined ? { fullContent } : {}),
+        ...(mode !== "links" && mode !== "metadata"
+            ? { contentLength: baseContent.length }
+            : {}),
     };
     if (emptyHtmlBody &&
         mode !== "raw" &&
@@ -183,9 +200,10 @@ function resolveMode(requestedMode, html, search) {
 }
 function isHtmlResponse(contentType, body) {
     if (contentType) {
-        return (contentType === "text/html" ||
-            contentType === "application/xhtml+xml" ||
-            contentType.endsWith("+html"));
+        const mediaType = contentType.toLowerCase();
+        return (mediaType === "text/html" ||
+            mediaType === "application/xhtml+xml" ||
+            mediaType.endsWith("+html"));
     }
     return /<!doctype html|<html[\s>]|<body[\s>]|<article[\s>]/i.test(body.slice(0, 2_000));
 }

package/dist/observability/routes.d.ts

@@ -27,39 +27,39 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    ok?: undefined;
     error: string;
     message: string;
     summary?: undefined;
     spans?: undefined;
-    ok?: undefined;
 } | {
     error?: undefined;
+    ok?: undefined;
     message?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
-    ok?: undefined;
 } | {
     error?: undefined;
+    ok?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     traceMissing: true;
     id: string;
-    ok?: undefined;
 } | {
     error?: undefined;
+    ok?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     traceMissing?: undefined;
     id: string;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     error: any;
-    ok?: undefined;
 } | {
     error?: undefined;
     message?: undefined;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,10 +75,10 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    message?: undefined;
     id?: undefined;
     provider?: undefined;
     deleted?: undefined;
+    message?: undefined;
     providers: {
         id: string;
         label: string;
@@ -93,9 +93,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     registered?: undefined;
     label?: undefined;
 } | {
-    message?: undefined;
     id?: undefined;
     deleted?: undefined;
+    message?: undefined;
     providers?: undefined;
     count?: undefined;
     found: boolean;
@@ -103,9 +103,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     registered?: undefined;
     label?: undefined;
 } | {
-    message?: undefined;
     provider?: undefined;
     deleted?: undefined;
+    message?: undefined;
     providers?: undefined;
     count?: undefined;
     found: boolean;
@@ -113,8 +113,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     registered?: undefined;
     label?: undefined;
 } | {
-    message?: undefined;
     provider?: undefined;
+    message?: undefined;
     providers?: undefined;
     count?: undefined;
     found?: undefined;

package/dist/resources/handlers.d.ts

@@ -39,8 +39,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
     error: string;
 }>;
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -57,39 +57,39 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
 } | {
     error: string;
     errorCode?: undefined;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
     error: string;
     errorCode: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
-    error?: undefined;
     errorCode?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -117,11 +117,11 @@ export declare function createAdHocSecretHandler(): import("h3").EventHandlerWit
 } | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-engine-default-model-route.d.ts

@@ -9,16 +9,16 @@ export declare const AGENT_ENGINE_API_KEY_ACTION_NAME = "agent-engine-api-key";
  */
 export declare function createAgentEngineDisconnectHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    scope?: undefined;
     ok?: undefined;
+    scope?: undefined;
 } | {
     ok: boolean;
     error: any;
     scope?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     scope: "org" | "user";
-    error?: undefined;
 }>>;
 export interface DefaultModelSelectionRequest {
     engine: string;

package/dist/server/agent-engine-ollama-models-route.d.ts

@@ -1,7 +1,7 @@
 export declare function createAgentEngineOllamaModelsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    models?: undefined;
     ok?: undefined;
+    models?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/index.d.ts

@@ -1,6 +1,7 @@
 export { readComposerWebsiteSource, type ComposerWebsiteExtraction, } from "./composer-website-source.js";
 export { isAgentKitFigmaSourceAvailable, listAgentKitCapabilities, readAgentKitIntegrationIntent, type AgentKitCapabilityAppId, type AgentKitCapabilityCatalog, type AgentKitIntegrationCapability, } from "../agentkit/capabilities.js";
 export { defineAppConfig, getAppConfig, resolveAppHomePath, resetAppConfigForTests, appConfigSchema, type AppConfig, type AppConfigInput, } from "../app-config/index.js";
+export { platformWaitUntil } from "./background-work.js";
 export { resolveDeployEnvironment } from "./deploy-environment.js";
 export { isTestIdentity, testIdentitySql } from "./test-identity.js";
 export { inferWorkspaceAppRootHomePath, readConfiguredWorkspaceAppHomePath, } from "../workspace-app-config.js";
@@ -16,7 +17,7 @@ export { createSSEHandler, type SSEHandlerOptions } from "./sse.js";
 export { isCredentialMembershipUnavailable } from "./credential-membership-unavailable.js";
 export { mountAuthMiddleware, autoMountAuth, registerAuthPublicPaths, getSession, isSessionResolutionUnavailable, getMcpOAuthBearerSession, logout, COOKIE_NAME, addSession, removeSession, getSessionEmail, getFrameworkSessionCookieValues, setFrameworkSessionCookie, setFirstRunOnboardingCookie, clearFrameworkSessionCookies, runAuthGuard, registerDesktopExchange, prepareDesktopOAuthBrowserBinding, matchesDesktopOAuthBrowserBinding, DESKTOP_OAUTH_BROWSER_BINDING_COOKIE, setDesktopExchange, setDesktopExchangeError, safeReturnPath, type DesktopExchangeErrorPayload, type AuthSession, type AuthOptions, } from "./auth.js";
 export { handleIdentitySso, ensureIdentityUser, getIdentityHubUrl, isIdentitySsoEnabled, isIdentitySsoBypassPath, identitySsoLoginButtonHtml, IDENTITY_SSO_BOOTSTRAP_ACTIVATE_PATH, IDENTITY_SSO_BOOTSTRAP_BINDING_COOKIE, clearIdentitySsoBootstrapBindingCookie, getIdentitySsoBootstrapBindingCookie, setIdentitySsoBootstrapBindingCookie, IDENTITY_SSO_PROVIDER_ID, IDENTITY_SSO_SCOPE, IDENTITY_SSO_DESKTOP_COMPLETE_PATH, } from "./identity-sso.js";
-export { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, hasGoogleAuthIdentity, setBetterAuthSessionCookie, } from "./better-auth-instance.js";
+export { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getBetterAuthUserIdForEmail, hasGoogleAuthIdentity, setBetterAuthSessionCookie, } from "./better-auth-instance.js";
 export { setIdentityGoogleAuthCookie } from "./identity-auth-provider.js";
 export { requireEnvKey, type MissingKeyResponse } from "./missing-key.js";
 export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } from "./org-admin.js";

package/dist/server/index.js

@@ -1,6 +1,7 @@
 export { readComposerWebsiteSource, } from "./composer-website-source.js";
 export { isAgentKitFigmaSourceAvailable, listAgentKitCapabilities, readAgentKitIntegrationIntent, } from "../agentkit/capabilities.js";
 export { defineAppConfig, getAppConfig, resolveAppHomePath, resetAppConfigForTests, appConfigSchema, } from "../app-config/index.js";
+export { platformWaitUntil } from "./background-work.js";
 export { resolveDeployEnvironment } from "./deploy-environment.js";
 export { isTestIdentity, testIdentitySql } from "./test-identity.js";
 export { inferWorkspaceAppRootHomePath, readConfiguredWorkspaceAppHomePath, } from "../workspace-app-config.js";
@@ -16,7 +17,7 @@ export { createSSEHandler } from "./sse.js";
 export { isCredentialMembershipUnavailable } from "./credential-membership-unavailable.js";
 export { mountAuthMiddleware, autoMountAuth, registerAuthPublicPaths, getSession, isSessionResolutionUnavailable, getMcpOAuthBearerSession, logout, COOKIE_NAME, addSession, removeSession, getSessionEmail, getFrameworkSessionCookieValues, setFrameworkSessionCookie, setFirstRunOnboardingCookie, clearFrameworkSessionCookies, runAuthGuard, registerDesktopExchange, prepareDesktopOAuthBrowserBinding, matchesDesktopOAuthBrowserBinding, DESKTOP_OAUTH_BROWSER_BINDING_COOKIE, setDesktopExchange, setDesktopExchangeError, safeReturnPath, } from "./auth.js";
 export { handleIdentitySso, ensureIdentityUser, getIdentityHubUrl, isIdentitySsoEnabled, isIdentitySsoBypassPath, identitySsoLoginButtonHtml, IDENTITY_SSO_BOOTSTRAP_ACTIVATE_PATH, IDENTITY_SSO_BOOTSTRAP_BINDING_COOKIE, clearIdentitySsoBootstrapBindingCookie, getIdentitySsoBootstrapBindingCookie, setIdentitySsoBootstrapBindingCookie, IDENTITY_SSO_PROVIDER_ID, IDENTITY_SSO_SCOPE, IDENTITY_SSO_DESKTOP_COMPLETE_PATH, } from "./identity-sso.js";
-export { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, hasGoogleAuthIdentity, setBetterAuthSessionCookie, } from "./better-auth-instance.js";
+export { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getBetterAuthUserIdForEmail, hasGoogleAuthIdentity, setBetterAuthSessionCookie, } from "./better-auth-instance.js";
 export { setIdentityGoogleAuthCookie } from "./identity-auth-provider.js";
 export { requireEnvKey } from "./missing-key.js";
 export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } from "./org-admin.js";

package/dist/shared/context-status.js

@@ -50,5 +50,5 @@ export const SELECTION_CONTEXT_UNAVAILABLE_NOTE = wrapNote("Selected text unavai
 /** `partial` when another source did deliver context this turn. */
 export function preloadedContextUnavailableNote(status, options = {}) {
     const reason = status === "timed_out" ? "timed out" : "failed";
-    return wrapNote(`${options.partial ? "Some preloaded context" : "Preloaded context"} was unavailable this turn (${reason}); search for anything relevant with the available tools before answering.`);
+    return wrapNote(`${options.partial ? "Some preloaded context" : "Preloaded context"} was unavailable this turn (${reason}); if the request depends on workspace knowledge, such as prior work, team docs, brand defaults, or people, search for it with the available tools before answering; otherwise continue without it.`);
 }

package/dist/sharing/actions/list-resource-shares.d.ts

@@ -2,7 +2,6 @@ declare const _default: import("../../action.js").ActionDefinition<{
     resourceType: string;
     resourceId: string;
 }, {
-    role?: undefined;
     ownerEmail: any;
     visibility: any;
     shares: any[];
@@ -12,6 +11,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
         supportsGroupShares?: boolean;
     };
     orgId?: undefined;
+    role?: undefined;
     agentReadable?: undefined;
 } | {
     ownerEmail: string;

package/dist/tracking/index.d.ts

@@ -1,5 +1,6 @@
 export { track, identify, flushTracking, registerTrackingProvider, unregisterTrackingProvider, listTrackingProviders, type TrackingMeta, type TrackingSource, } from "./registry.js";
 export { registerBuiltinProviders } from "./providers.js";
+export { readAnalyticsAnonymousId } from "../server/attribution.js";
 export { AGENT_NATIVE_ACTION_EVENTS, AGENT_NATIVE_LIFECYCLE_EVENTS, trackActionEvent, trackLifecycleEvent, type AgentNativeActionEventName, type AgentNativeLifecycleEventName, } from "./lifecycle.js";
 export { captureException, type TrackingExceptionContext, type TrackingExceptionLevel, } from "./error-capture.js";
 export { classifyTrackingFailure, type TrackingFailureCategory, } from "./failure-category.js";

package/dist/tracking/index.js

@@ -1,5 +1,6 @@
 export { track, identify, flushTracking, registerTrackingProvider, unregisterTrackingProvider, listTrackingProviders, } from "./registry.js";
 export { registerBuiltinProviders } from "./providers.js";
+export { readAnalyticsAnonymousId } from "../server/attribution.js";
 export { AGENT_NATIVE_ACTION_EVENTS, AGENT_NATIVE_LIFECYCLE_EVENTS, trackActionEvent, trackLifecycleEvent, } from "./lifecycle.js";
 export { captureException, } from "./error-capture.js";
 export { classifyTrackingFailure, } from "./failure-category.js";

package/dist/triggers/actions/manage-automation.d.ts

@@ -29,8 +29,8 @@ declare const _default: import("../../action.js").ActionDefinition<{
     executionEngine?: undefined;
     executionCwd?: undefined;
 } | {
-    created?: undefined;
     scope?: undefined;
+    created?: undefined;
     triggerType?: undefined;
     event?: undefined;
     deleted: boolean;
@@ -45,8 +45,8 @@ declare const _default: import("../../action.js").ActionDefinition<{
     nextRun?: undefined;
     webhookPath?: undefined;
 } | {
-    created?: undefined;
     scope?: undefined;
+    created?: undefined;
     triggerType?: undefined;
     event?: undefined;
     deleted?: undefined;

package/dist/workspace-files/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_FILE_BYTES: number;
+export declare const MAX_SCOPE_BYTES: number;
+export declare const SAVE_TO_FILE_MAX_BYTES: number;

package/dist/workspace-files/constants.js

@@ -0,0 +1,3 @@
+export const MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const MAX_SCOPE_BYTES = 200 * 1024 * 1024;
+export const SAVE_TO_FILE_MAX_BYTES = 20 * 1024 * 1024;

package/dist/workspace-files/store.d.ts

@@ -1,6 +1,5 @@
-export declare const MAX_FILE_BYTES: number;
-export declare const MAX_SCOPE_BYTES: number;
-export declare const SAVE_TO_FILE_MAX_BYTES: number;
+import { MAX_FILE_BYTES, MAX_SCOPE_BYTES, SAVE_TO_FILE_MAX_BYTES } from "./constants.js";
+export { MAX_FILE_BYTES, MAX_SCOPE_BYTES, SAVE_TO_FILE_MAX_BYTES };
 export interface WorkspaceFilesScope {
     scope: "user" | "org";
     scopeId: string;

package/dist/workspace-files/store.js

@@ -2,9 +2,8 @@ import { getOrgRoleForEmail } from "../mcp/actions/service-token-access.js";
 import { canManageOrg } from "../org/permissions.js";
 import { SHARED_OWNER, isLegacyOrganizationWorkspaceFile, sharedResourceOwner, resourceDeleteIfCurrent, resourceGetByPath, resourceList, resourcePut, } from "../resources/store.js";
 import { getRequestUserEmail } from "../server/request-context.js";
-export const MAX_FILE_BYTES = 2 * 1024 * 1024;
-export const MAX_SCOPE_BYTES = 200 * 1024 * 1024;
-export const SAVE_TO_FILE_MAX_BYTES = 20 * 1024 * 1024;
+import { MAX_FILE_BYTES, MAX_SCOPE_BYTES, SAVE_TO_FILE_MAX_BYTES, } from "./constants.js";
+export { MAX_FILE_BYTES, MAX_SCOPE_BYTES, SAVE_TO_FILE_MAX_BYTES };
 function ownerForScope(scope) {
     return scope.scope === "org"
         ? sharedResourceOwner(scope.scopeId)

package/docs/content/automations.mdx

@@ -290,19 +290,25 @@ Placeholders are resolved **server-side** after the agent emits the tool call
 
 ### Parameters {#web-request-params}
 
-| Parameter      | Type    | Default       | Description                                                                                                                                                    |
-| -------------- | ------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url`          | string  | —             | Full URL. May contain `${keys.NAME}` references.                                                                                                               |
-| `method`       | string  | `GET`         | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD).                                                                                                             |
-| `headers`      | string  | `{}`          | JSON object of headers. May contain `${keys.NAME}`.                                                                                                            |
-| `body`         | string  | —             | Request body. May contain `${keys.NAME}`.                                                                                                                      |
-| `timeout_ms`   | number  | 15000         | Timeout in milliseconds (max 30000).                                                                                                                           |
-| `maxChars`     | number  | 32000         | Maximum response characters to return (max 200000). Raise it to read a large page or dataset in full.                                                          |
-| `responseMode` | string  | `auto`        | How to return the response: `auto` (HTML becomes markdown, JSON/text stays raw), `raw`, `text`, `markdown`, `links`, `metadata`, or `matches` (with `search`). |
-| `extract`      | string  | `readability` | HTML extraction strategy: `readability`, `all-visible` (full visible body text), or `none` (full document).                                                    |
-| `includeLinks` | boolean | `true`        | Whether extracted HTML responses include a compact links list.                                                                                                 |
-| `search`       | object  | —             | Optional post-fetch search over the extracted content: `{ query, queries, terms, regex, regexFlags, source, maxMatches, contextChars, caseSensitive }`.        |
-| `saveToFile`   | string  | —             | Workspace file path to save the full response to instead of returning it inline — useful for large pages or API responses.                                     |
+| Parameter      | Type    | Default       | Description                                                                                                                                                                                                                         |
+| -------------- | ------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`          | string  | —             | Full URL. May contain `${keys.NAME}` references.                                                                                                                                                                                    |
+| `method`       | string  | `GET`         | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD).                                                                                                                                                                                  |
+| `headers`      | string  | `{}`          | JSON object of headers. May contain `${keys.NAME}`.                                                                                                                                                                                 |
+| `body`         | string  | —             | Request body. May contain `${keys.NAME}`.                                                                                                                                                                                           |
+| `timeout_ms`   | number  | 15000         | Timeout in milliseconds (max 30000).                                                                                                                                                                                                |
+| `maxChars`     | number  | 32000         | Maximum response-body characters returned in the agent's context (max 200000). It caps body characters, not the whole formatted tool response, so optional metadata and links can add characters. This does not limit a saved file. |
+| `responseMode` | string  | `auto`        | How to return the response: `auto` (HTML becomes markdown, JSON/text stays raw), `raw`, `text`, `markdown`, `links`, `metadata`, or `matches` with `search`.                                                                        |
+| `extract`      | string  | `readability` | HTML extraction strategy: `readability`, `all-visible` (full visible body text), or `none` (full document).                                                                                                                         |
+| `includeLinks` | boolean | varies        | Whether extracted HTML responses include a compact links list. Defaults to `true` for inline responses and `false` when `saveToFile` is set.                                                                                        |
+| `search`       | object  | —             | Optional post-fetch search over the extracted content: `{ query, queries, terms, regex, regexFlags, source, maxMatches, contextChars, caseSensitive }`.                                                                             |
+| `saveToFile`   | string  | —             | Workspace file path for saving the full response, up to 20 MiB. With `search`, returns full matches up to `maxChars`; otherwise returns a 2,000-character preview.                                                                  |
+
+By default, `maxChars` caps only response-body characters returned in the agent's context. It does not cap the whole formatted tool response, so optional metadata and links can add characters. Inline responses are limited to 1 MiB, except extracted HTML or XHTML, which can be up to 20 MiB. Raw HTML and other inline responses remain limited to 1 MiB.
+
+`saveToFile` supports responses up to 20 MiB. HTML or XHTML saved with a non-raw `responseMode` is written as extracted Markdown or text. Raw mode and non-HTML responses are saved as decoded response body text without HTML extraction. When `saveToFile` is used with `search`, the tool returns full search matches bounded by `maxChars`. Without `search`, it returns a 2,000-character preview. `searchResultsTruncated` means `maxChars` cut the formatted result. `searchSourceTruncated` means the tool scanned only the first 500,000 characters of the selected search source.
+
+An over-limit error reports the observed size and applicable cap, and explains how to recover. Use `saveToFile` for responses up to 20 MiB, or request a smaller response if it exceeds that limit.
 
 ## Keys {#keys}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.208.0",
+  "version": "0.208.1-nightly-20261013212700",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -703,7 +703,7 @@
     "yaml": "^2.9.0",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/agentkit": "^0.208.0",
+    "@agent-native/agentkit": "^0.208.1-nightly-20261013212700",
     "@agent-native/recap-cli": "^0.5.71"
   },
   "devDependencies": {
@@ -774,7 +774,7 @@
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@agent-native/core-corpus": ">=0.196.0",
+    "@agent-native/core-corpus": "0.208.1-nightly-20261013212700",
     "@ai-sdk/anthropic": ">=3",
     "@ai-sdk/cohere": ">=3",
     "@ai-sdk/google": ">=3",