@agent-native/core 0.228.2-nightly-20261113032548 → 0.228.2

package/dist/application-state/handlers.d.ts

@@ -36,18 +36,18 @@ export declare const listComposeDrafts: import("h3").EventHandlerWithFetch<impor
 export declare const getComposeDraft: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<Record<string, unknown> | null>>;
 export declare const putComposeDraft: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<any>>;
 export declare const saveComposeDraft: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    errorCode?: undefined;
     value?: undefined;
     error: string;
     revision?: undefined;
-    errorCode?: undefined;
     details?: undefined;
 } | {
+    errorCode?: undefined;
     error?: undefined;
     value: {
         id: string;
     };
     revision: string;
-    errorCode?: undefined;
     details?: undefined;
 } | {
     value?: undefined;

package/dist/cli/skills-content/an-skill.d.ts

@@ -1,2 +1,2 @@
-export declare const AN_SKILL_MD = "---\nname: an\ndescription: >-\n  Open and operate Agent-Native workspace apps through Dispatch MCP, with\n  inline app surfaces, browser-session authentication, and current screen state.\nmetadata:\n  visibility: exported\n---\n\n# Agent-Native Apps\n\nUse `/an <app>` to open an Agent-Native app beside the conversation and keep\nthe app's live UI and the agent's actions in the same workflow. The first\nargument is the Dispatch app id. For example, `/an slides` opens the Slides\neditor. After it opens, the user can sign in in that browser surface and ask\nfor new decks or focused edits in ordinary language.\n\n## Open the app\n\nFor a known app, call Dispatch's `open_app` with an inline surface:\n\n```json\n{\n  \"app\": \"slides\",\n  \"path\": \"/\",\n  \"embed\": true,\n  \"chrome\": \"full\"\n}\n```\n\nThe MCP App response is the preferred handoff for Claude, Claude Desktop,\nClaude Cowork, ChatGPT, ChatGPT desktop, Codex, and other compatible hosts. Keep\nthe returned open link as the fallback for a host that cannot render MCP Apps\ninline. Do not claim that a browser opened unless the host rendered the inline\nsurface or its browser tool confirmed the returned URL.\n\nIf the app name is missing or uncertain, call `list_apps` first and use the\nexact granted app id. If the requested app is not listed, explain that it must\nbe granted in Dispatch's Agents access settings. Do not invent a URL, use a\nlocalhost URL, or route around the Dispatch grant.\n\n## Work in the opened app\n\nPrefer direct app tools when the host exposes them. After opening an app, call\n`list-host-webmcp-tools` when available, then use `run-host-webmcp-tool`\nwith the exact listed name and origin. Page-local tools reflect current app\nstate and selection, so use `view-screen` before selection-dependent edits\nand read back writes.\n\nYou are the model doing the work: when the user asks for new content \u2014 a\ndesign, a deck, a form, a document \u2014 author it yourself and save it with the\napp's create/update tools. Never hand off authoring to the app's own agent\nwhen those tools exist, and never wait on an in-app question form; it answers\nback through that app's own chat, not to you.\n\nUse `ask_app` only when the host has no direct page tools, the requested\ncapability is not exposed, the task needs the app agent's interpretation or\nmulti-step specialist reasoning, or a direct call fails and needs recovery.\nDispatch's unified `/mcp` endpoint still exposes generic cross-app verbs; a\ndirect app MCP connection or page WebMCP surface is where named app actions\nappear.\n\nThe app's MCP `instructions` name its key tools (generated from the app's own\nlist); follow those names verbatim and use `tool-search` for anything else \u2014\nnever guess a tool name.\n\n1. Call `view-screen` before any selection-dependent edit and use the ids it\n   returns; never guess an id from a title, index, or stale context.\n2. If `view-screen` returns a `selection` and `nextRequiredAction`, make\n   that call directly with the smallest atomic change; do not regenerate a\n   whole artifact for a focused edit.\n3. Read the result back with the app's matching read action and report what\n   changed. A queued `ask_app_status` task is not proof an edit completed.\n\n## Authentication and host behavior\n\nThe Dispatch MCP connector identifies the calling agent, while the embedded app\nuses the user's browser session. Let the user complete sign-in in the rendered\nAgent-Native browser surface. Never request, copy, or store passwords, OAuth\ncodes, cookies, or access tokens.\n\nThe generic Agent-Native plugin registers Dispatch at\n`https://dispatch.agent-native.com/mcp` for hosts that support plugin MCP\nconfiguration. ChatGPT custom connectors use the same URL with OAuth. After\ninstalling or changing a connector, reload Claude/Cowork/ChatGPT or reconnect\nand rescan the MCP server if the new tools or inline surface are not visible.\n\n## Failure handling\n\n- If `open_app` succeeds but no inline surface appears, show its returned\n  link and say that this host does not expose an embedded browser here.\n- After an app loads, check for `list-host-webmcp-tools` before delegating. If\n  it is available, use the exact returned tool name and origin for direct work.\n- If `ask_app` cannot reach Slides, check that Slides is granted in\n  Dispatch and that the connector is authenticated, then retry once with the\n  exact app id `slides`.\n- If screen state has no deck or selection, describe that state instead of\n  fabricating context. Ask the user to open a deck or select an element when\n  the requested edit depends on it.\n- Treat a successful open link, a queued task, or a tool acknowledgment as\n  navigation/task setup only. Confirm a write with the app's readback action.\n";
+export declare const AN_SKILL_MD = "---\nname: an\ndescription: >-\n  Open and operate Agent-Native workspace apps through Dispatch MCP, with\n  inline app surfaces, browser-session authentication, and current screen state.\nmetadata:\n  visibility: exported\n---\n\n# Agent-Native Apps\n\nUse `/an <app>` to open an Agent-Native app beside the conversation and keep\nthe app's live UI and the agent's actions in the same workflow. The first\nargument is the Dispatch app id. For example, `/an slides` opens the Slides\neditor. After it opens, the user can sign in in that browser surface and ask\nfor new decks or focused edits in ordinary language.\n\n## Open the app\n\nFor a known app, call Dispatch's `open_app` with an inline surface:\n\n```json\n{\n  \"app\": \"slides\",\n  \"path\": \"/\",\n  \"embed\": true,\n  \"chrome\": \"full\"\n}\n```\n\nThe MCP App response is the preferred handoff for Claude, Claude Desktop,\nClaude Cowork, ChatGPT, ChatGPT desktop, Codex, and other compatible hosts. Keep\nthe returned open link as the fallback for a host that cannot render MCP Apps\ninline. Do not claim that a browser opened unless the host rendered the inline\nsurface or its browser tool confirmed the returned URL.\n\nIf the app name is missing or uncertain, call `list_apps` first and use the\nexact granted app id. If the requested app is not listed, explain that it must\nbe granted in Dispatch's Agents access settings. Do not invent a URL, use a\nlocalhost URL, or route around the Dispatch grant.\n\n## Work in the opened app\n\nPrefer direct app tools when the host exposes them. After opening an app, call\n`list-host-webmcp-tools` when available, then use `run-host-webmcp-tool`\nwith the exact listed name and origin. Page-local tools reflect current app\nstate and selection, so use `view-screen` before selection-dependent edits\nand read back writes.\n\nYou are the model doing the work: when the user asks for new content \u2014 a\ndesign, a deck, a form, a document \u2014 author it yourself and save it with the\napp's create/update tools. Never hand off authoring to the app's own agent\nwhen those tools exist, and never wait on an in-app question form; it answers\nback through that app's own chat, not to you.\n\nUse `ask_app` only when the host has no direct page tools, the requested\ncapability is not exposed, the task needs the app agent's interpretation or\nmulti-step specialist reasoning, or a direct call fails and needs recovery.\nDispatch's unified `/mcp` endpoint still exposes generic cross-app verbs; a\ndirect app MCP connection or page WebMCP surface is where named app actions\nappear.\n\nThe app's MCP `instructions` name its key tools (generated from the app's own\nlist); follow those names verbatim and use `tool-search` for anything else \u2014\nnever guess a tool name.\n\n1. Call `view-screen` before any selection-dependent edit and use the ids it\n   returns; never guess an id from a title, index, or stale context.\n2. If `view-screen` returns a `selection` and `nextRequiredAction`, make\n   that call directly with the smallest atomic change; do not regenerate a\n   whole artifact for a focused edit.\n3. Read the result back with the app's matching read action and report what\n   changed. A queued `ask_app_status` task is not proof an edit completed.\n\n## Keep the open app in step with the chat\n\nClaude opens an embedded app in its side panel. The panel is one live app: an\nedit made through a tool shows there, and an edit the user makes by hand is in\nthe app's data the next time you read it.\n\n- To change what the open panel shows (filter a list, open a record, switch a\n  week), call the view tools `read_view` and `navigate_view` on the open app\n  instead of calling `open_app` again. Each new `open_app` call opens a new\n  view and replaces the panel.\n- Before acting on \"this\", \"it\" or \"the one I opened\", call `read_view`;\n  the user may have clicked or typed in the panel since your last turn.\n- Draft and edit with the app's own actions (create or update a draft, an\n  event, a task), then read it back. Send, delete or move only when the user\n  asks.\n\n## Authentication and host behavior\n\nThe Dispatch MCP connector identifies the calling agent, while the embedded app\nuses the user's browser session. Let the user complete sign-in in the rendered\nAgent-Native browser surface. Never request, copy, or store passwords, OAuth\ncodes, cookies, or access tokens.\n\nThe generic Agent-Native plugin registers Dispatch at\n`https://dispatch.agent-native.com/mcp` for hosts that support plugin MCP\nconfiguration. ChatGPT custom connectors use the same URL with OAuth. After\ninstalling or changing a connector, reload Claude/Cowork/ChatGPT or reconnect\nand rescan the MCP server if the new tools or inline surface are not visible.\n\n## Failure handling\n\n- If `open_app` succeeds but no inline surface appears, show its returned\n  link and say that this host does not expose an embedded browser here.\n- After an app loads, check for `list-host-webmcp-tools` before delegating. If\n  it is available, use the exact returned tool name and origin for direct work.\n- If `ask_app` cannot reach Slides, check that Slides is granted in\n  Dispatch and that the connector is authenticated, then retry once with the\n  exact app id `slides`.\n- If screen state has no deck or selection, describe that state instead of\n  fabricating context. Ask the user to open a deck or select an element when\n  the requested edit depends on it.\n- Treat a successful open link, a queued task, or a tool acknowledgment as\n  navigation/task setup only. Confirm a write with the app's readback action.\n";
 export declare const AN_COMMAND_MD = "---\ndescription: Open and operate a granted Agent-Native app through Dispatch MCP.\nargument-hint: <app> [request]\n---\n\nUse the an skill. Treat the first argument as the Agent-Native Dispatch app id.\nFor `/an slides`, call `open_app` with app `slides`, path \"/\", embed\ntrue, and chrome `full`. Keep the returned link if the host cannot render\nthe inline MCP App. Any remaining arguments are the user's request after the\napp opens:\n\n$ARGUMENTS\n";

package/dist/cli/skills-content/an-skill.js

@@ -73,6 +73,22 @@ never guess a tool name.
 3. Read the result back with the app's matching read action and report what
    changed. A queued \`ask_app_status\` task is not proof an edit completed.
 
+## Keep the open app in step with the chat
+
+Claude opens an embedded app in its side panel. The panel is one live app: an
+edit made through a tool shows there, and an edit the user makes by hand is in
+the app's data the next time you read it.
+
+- To change what the open panel shows (filter a list, open a record, switch a
+  week), call the view tools \`read_view\` and \`navigate_view\` on the open app
+  instead of calling \`open_app\` again. Each new \`open_app\` call opens a new
+  view and replaces the panel.
+- Before acting on "this", "it" or "the one I opened", call \`read_view\`;
+  the user may have clicked or typed in the panel since your last turn.
+- Draft and edit with the app's own actions (create or update a draft, an
+  event, a task), then read it back. Send, delete or move only when the user
+  asks.
+
 ## Authentication and host behavior
 
 The Dispatch MCP connector identifies the calling agent, while the embedded app

package/dist/collab/routes.d.ts

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

package/dist/db/schema-snapshot.generated.js

@@ -68,7 +68,7 @@ export const SCHEMA_SNAPSHOT = {
         'CREATE TABLE "app_permission_overrides" (\n  "org_id" text NOT NULL,\n  "app_id" text NOT NULL,\n  "permission" text NOT NULL,\n  "roles_json" text NOT NULL,\n  "updated_by" text NOT NULL,\n  "updated_at" bigint NOT NULL\n);',
         'CREATE TABLE "app_resource_change_consumers" (\n  "app" text NOT NULL,\n  "resource_type" text NOT NULL,\n  "consumer" text NOT NULL,\n  "registered_at" timestamp with time zone DEFAULT now() NOT NULL\n);',
         'CREATE TABLE "app_resource_changes" (\n  "consumer" text NOT NULL,\n  "app" text NOT NULL,\n  "resource_type" text NOT NULL,\n  "resource_id" text NOT NULL,\n  "reason" text NOT NULL,\n  "seq" bigint NOT NULL,\n  "changed_at" timestamp with time zone DEFAULT clock_timestamp() NOT NULL,\n  "available_at" timestamp with time zone DEFAULT clock_timestamp() NOT NULL,\n  "attempts" integer DEFAULT 0 NOT NULL,\n  "failed_at" timestamp with time zone\n);',
-        'CREATE TABLE "app_secrets" (\n  "id" text NOT NULL,\n  "scope" text NOT NULL,\n  "scope_id" text NOT NULL,\n  "key" text NOT NULL,\n  "encrypted_value" text NOT NULL,\n  "shared_encrypted_value" text,\n  "description" text,\n  "url_allowlist" text,\n  "created_at" bigint NOT NULL,\n  "updated_at" bigint NOT NULL\n);',
+        'CREATE TABLE "app_secrets" (\n  "id" text NOT NULL,\n  "scope" text NOT NULL,\n  "scope_id" text NOT NULL,\n  "key" text NOT NULL,\n  "encrypted_value" text NOT NULL,\n  "shared_encrypted_value" text,\n  "description" text,\n  "url_allowlist" text,\n  "created_at" bigint NOT NULL,\n  "updated_at" bigint NOT NULL,\n  "label" text,\n  "provider" text,\n  "created_by" text\n);',
         'CREATE TABLE "application_state" (\n  "session_id" text NOT NULL,\n  "key" text NOT NULL,\n  "value" text NOT NULL,\n  "updated_at" bigint NOT NULL,\n  "writer" text,\n  "writer_seq" bigint\n);',
         'CREATE TABLE "automation_runs" (\n  "id" text NOT NULL,\n  "owner" text NOT NULL,\n  "automation" text NOT NULL,\n  "path" text NOT NULL,\n  "scope" text,\n  "org_id" text,\n  "app_id" text,\n  "run_id" text,\n  "thread_id" text,\n  "status" text DEFAULT \'running\'::text NOT NULL,\n  "started_at" bigint NOT NULL,\n  "finished_at" bigint,\n  "error" text,\n  "error_code" text,\n  "notification_email" text,\n  "failure_alerted" bigint DEFAULT 0 NOT NULL,\n  "failure_alert_state" text,\n  "failure_alert_attempts" bigint DEFAULT 0 NOT NULL,\n  "failure_alert_next_attempt_at" bigint,\n  "failure_alert_claimed_at" bigint,\n  "failure_alert_provider" text,\n  "failure_alert_first_attempt_at" bigint,\n  "failure_alert_unsubscribe_token" text,\n  "claimed_at" bigint,\n  "dispatch_pending" bigint DEFAULT 0 NOT NULL\n);',
         'CREATE TABLE "automation_scheduler_health" (\n  "id" text NOT NULL,\n  "app_id" text DEFAULT \'default\'::text NOT NULL,\n  "org_id" text,\n  "last_checked_at" bigint,\n  "last_dispatched_at" bigint,\n  "last_error" text,\n  "runtime" text,\n  "updated_at" bigint NOT NULL,\n  "lease_owner" text,\n  "lease_expires_at" bigint\n);',
@@ -953,6 +953,7 @@ export const SCHEMA_SNAPSHOT = {
         ["agent_tool_approvals", "tool-revision", null],
         ["app_resource_changes", "baseline", null],
         ["app_secrets", "baseline", null],
+        ["app_secrets", "vault-metadata-columns", null],
         ["application_state", "baseline", null],
         ["application_state", "indexes", null],
         ["application_state", "widen-bigint", null],

package/dist/file-upload/actions/upload-image.d.ts

@@ -33,9 +33,9 @@ declare const _default: import("../../action.js").ActionDefinition<{
     idempotencyKey: string;
     deleted: boolean;
 } | {
-    id?: undefined;
     error: string;
     url?: undefined;
+    id?: undefined;
     provider?: undefined;
     configured?: undefined;
 } | {
@@ -45,8 +45,8 @@ declare const _default: import("../../action.js").ActionDefinition<{
     provider: string;
     configured?: undefined;
 } | {
-    id?: undefined;
     url?: undefined;
+    id?: undefined;
     provider?: undefined;
     error: string;
     configured: boolean;

package/dist/file-upload/builder-gateway.d.ts

@@ -0,0 +1,42 @@
+export type BuilderGatewayStep = "signed_url" | "session_start" | "complete";
+export interface BuilderGatewayErrorDetails {
+    step: BuilderGatewayStep;
+    /** HTTP status of the last attempt; 0 when no response arrived. */
+    status: number;
+    attempts: number;
+    /** The last response was an HTML error page, not the gateway's JSON. */
+    isHtml: boolean;
+    /** One id per attempt sent to Builder; search the upload function's logs by it. */
+    traceIds: string[];
+    /** Allow-listed response headers of the last failed attempt. */
+    headers: Record<string, string>;
+    cause?: unknown;
+}
+export declare class BuilderGatewayError extends Error {
+    readonly provider = "builder";
+    readonly step: BuilderGatewayStep;
+    readonly status: number;
+    readonly attempts: number;
+    readonly isHtml: boolean;
+    readonly traceIds: string[];
+    readonly headers: Record<string, string>;
+    constructor(message: string, details: BuilderGatewayErrorDetails);
+}
+/** Summarize a failed response without keeping a whole HTML error page. */
+export declare function describeErrorBody(res: Response): Promise<{
+    detail: string;
+    isHtml: boolean;
+}>;
+export interface GatewayRequestInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: BodyInit;
+}
+/**
+ * One bounded, observable call to the Builder upload gateway or the storage
+ * session it hands out. Retries only failures that say "try again": no
+ * response, a gateway 5xx, and the step's own extra statuses. Resolves with
+ * the OK response; rejects with `BuilderGatewayError` once the attempts run
+ * out or the failure is not retryable.
+ */
+export declare function builderGatewayRequest(step: BuilderGatewayStep, url: string, init: GatewayRequestInit): Promise<Response>;

package/dist/file-upload/builder-gateway.js

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+export class BuilderGatewayError extends Error {
+    provider = "builder";
+    step;
+    status;
+    attempts;
+    isHtml;
+    traceIds;
+    headers;
+    constructor(message, details) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = "BuilderGatewayError";
+        this.step = details.step;
+        this.status = details.status;
+        this.attempts = details.attempts;
+        this.isHtml = details.isHtml;
+        this.traceIds = details.traceIds;
+        this.headers = details.headers;
+    }
+}
+const BACKOFF_FACTOR = 3;
+// The signed-URL and session-start requests are tiny and answer in well under
+// a second, so their 15 s cap lets every attempt fit inside one serverless
+// request; a slow answer is retried instead of waited on.
+const GATEWAY_POLICIES = {
+    signed_url: {
+        label: "Builder.io signed-URL request failed",
+        attempts: 3,
+        baseDelayMs: 500,
+        timeoutMs: 15_000,
+        retryStatuses: new Set([502, 503, 504]),
+        retryOnTimeout: true,
+        traced: true,
+    },
+    session_start: {
+        label: "GCS resumable session initiation failed",
+        attempts: 3,
+        baseDelayMs: 500,
+        timeoutMs: 15_000,
+        retryStatuses: new Set([408, 429, 500, 502, 503, 504]),
+        retryOnTimeout: true,
+        traced: false,
+    },
+    // Completing a stable video can include server-side compression, so this
+    // keeps the long timeout and never retries after our own timeout: that retry
+    // would race the first attempt. A 409 is that race from elsewhere (a
+    // duplicate in flight); the next call returns the registered asset.
+    complete: {
+        label: "Builder.io upload complete failed",
+        attempts: 4,
+        baseDelayMs: 500,
+        timeoutMs: 120_000,
+        retryStatuses: new Set([409, 502, 503, 504]),
+        retryOnTimeout: false,
+        traced: true,
+    },
+};
+// Response headers that say which layer answered; never request headers,
+// which carry the Authorization token.
+const DIAGNOSTIC_RESPONSE_HEADERS = [
+    "server",
+    "via",
+    "x-served-by",
+    "x-cache",
+    "x-cloud-trace-context",
+    "x-amz-cf-id",
+    "x-amz-cf-pop",
+    "cf-ray",
+    "retry-after",
+    "content-type",
+    "date",
+];
+function snapshotResponseHeaders(headers) {
+    const snapshot = {};
+    for (const name of DIAGNOSTIC_RESPONSE_HEADERS) {
+        const value = headers.get(name);
+        if (value)
+            snapshot[name] = value;
+    }
+    return snapshot;
+}
+/** Summarize a failed response without keeping a whole HTML error page. */
+export async function describeErrorBody(res) {
+    let raw;
+    try {
+        raw = await res.text();
+    }
+    catch {
+        return {
+            detail: `${res.statusText || "no status text"} (response body unreadable)`,
+            isHtml: false,
+        };
+    }
+    const isHtml = /text\/html/i.test(res.headers.get("content-type") ?? "") ||
+        /^\s*<(?:!doctype\s+html|html)\b/i.test(raw);
+    if (isHtml) {
+        return { detail: "HTML error page returned instead of JSON", isHtml: true };
+    }
+    const text = raw.trim();
+    return { detail: text ? text.slice(0, 500) : res.statusText, isHtml: false };
+}
+async function sendOnce(url, init, policy, traceId) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, policy.timeoutMs);
+    try {
+        const response = await fetch(url, {
+            ...init,
+            headers: traceId
+                ? { ...init.headers, "X-Cloud-Trace-Context": `${traceId}/1;o=1` }
+                : init.headers,
+            signal: controller.signal,
+        });
+        return { kind: "response", response };
+    }
+    catch (error) {
+        return { kind: "network", error, timedOut };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * One bounded, observable call to the Builder upload gateway or the storage
+ * session it hands out. Retries only failures that say "try again": no
+ * response, a gateway 5xx, and the step's own extra statuses. Resolves with
+ * the OK response; rejects with `BuilderGatewayError` once the attempts run
+ * out or the failure is not retryable.
+ */
+export async function builderGatewayRequest(step, url, init) {
+    const policy = GATEWAY_POLICIES[step];
+    const traceIds = [];
+    for (let attempt = 1;; attempt++) {
+        const startedAt = Date.now();
+        const traceId = policy.traced ? randomUUID().replaceAll("-", "") : null;
+        if (traceId)
+            traceIds.push(traceId);
+        const result = await sendOnce(url, init, policy, traceId);
+        const elapsedMs = Date.now() - startedAt;
+        if (result.kind === "response" && result.response.ok) {
+            if (attempt > 1) {
+                console.log(`[builder-upload] ${step} recovered on attempt ${attempt}/${policy.attempts}`, { elapsedMs, traceId });
+            }
+            return result.response;
+        }
+        let status = 0;
+        let isHtml = false;
+        let detail;
+        let headers = {};
+        let retryable;
+        if (result.kind === "response") {
+            status = result.response.status;
+            headers = snapshotResponseHeaders(result.response.headers);
+            ({ detail, isHtml } = await describeErrorBody(result.response));
+            retryable = policy.retryStatuses.has(status);
+        }
+        else {
+            detail = result.timedOut
+                ? `timed out after ${policy.timeoutMs} ms`
+                : result.error instanceof Error
+                    ? result.error.message
+                    : String(result.error);
+            retryable = result.timedOut ? policy.retryOnTimeout : true;
+        }
+        const willRetry = retryable && attempt < policy.attempts;
+        console.warn(`[builder-upload] ${step} attempt ${attempt}/${policy.attempts} failed${willRetry ? ", retrying" : ""}`, { status: status || "no response", elapsedMs, traceId, headers });
+        if (!willRetry) {
+            throw new BuilderGatewayError(`${policy.label} (${status || "no response"}): ${detail}`, {
+                step,
+                status,
+                attempts: attempt,
+                isHtml,
+                traceIds,
+                headers,
+                cause: result.kind === "network" ? result.error : undefined,
+            });
+        }
+        // Jitter keeps a burst of retrying recordings from landing together.
+        const delayMs = policy.baseDelayMs * BACKOFF_FACTOR ** (attempt - 1);
+        await new Promise((resolve) => setTimeout(resolve, Math.round(delayMs * (0.75 + Math.random() * 0.5))));
+    }
+}

package/dist/file-upload/builder.js

@@ -1,3 +1,4 @@
+import { builderGatewayRequest, describeErrorBody } from "./builder-gateway.js";
 const DEFAULT_BUILDER_APP_HOST = "https://builder.io";
 const LARGE_FILE_THRESHOLD_BYTES = 30 * 1024 * 1024;
 const UPLOAD_TIMEOUT_MS = 120_000;
@@ -44,8 +45,10 @@ function setRecordAssetQueryParam(url, recordAsset) {
 }
 async function assertOk(res, label) {
     if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw Object.assign(new Error(`${label} (${res.status}): ${body || res.statusText}`), { status: res.status });
+        const { detail } = await describeErrorBody(res);
+        throw Object.assign(new Error(`${label} (${res.status}): ${detail}`), {
+            status: res.status,
+        });
     }
 }
 function confirmedBuilderAuthorizationFailure(error) {
@@ -116,7 +119,7 @@ async function requestBuilderSignedUrl(authorization, apiKey, filename, mimeType
     const url = new URL("/api/v1/upload/signed-url", host);
     if (apiKey)
         url.searchParams.set("apiKey", apiKey);
-    const res = await fetchWithTimeout(url.toString(), {
+    const res = await builderGatewayRequest("signed_url", url.toString(), {
         method: "POST",
         headers: {
             Authorization: authorization,
@@ -129,7 +132,6 @@ async function requestBuilderSignedUrl(authorization, apiKey, filename, mimeType
             resumable,
         }),
     });
-    await assertOk(res, "Builder.io signed-URL request failed");
     const json = (await res.json());
     if (!json.uploadUrl || !json.assetId || !json.requiredHeaders) {
         throw new Error(`Builder.io signed-URL response missing required fields: ${JSON.stringify(Object.keys(json))}`);
@@ -149,7 +151,7 @@ async function completeBuilderUpload(authorization, apiKey, assetId, filename, o
         setStableUrlQueryParam(url);
     }
     setRecordAssetQueryParam(url, options?.recordAsset);
-    const res = await fetchWithTimeout(url.toString(), {
+    const res = await builderGatewayRequest("complete", url.toString(), {
         method: "POST",
         headers: {
             Authorization: authorization,
@@ -161,7 +163,6 @@ async function completeBuilderUpload(authorization, apiKey, assetId, filename, o
             ...(options?.recordAsset === false ? { record: false } : {}),
         }),
     });
-    await assertOk(res, "Builder.io upload complete failed");
     const json = (await res.json());
     if (!json.url)
         throw new Error("Builder.io upload/complete returned no URL");
@@ -315,15 +316,11 @@ export const builderFileUploadProvider = {
             if (contentLengthRange)
                 initHeaders["x-goog-content-length-range"] = contentLengthRange;
             console.log(`[builder-resumable] session step 2: initiating GCS session`);
-            const initRes = await fetchWithTimeout(uploadUrl, {
+            const initRes = await builderGatewayRequest("session_start", uploadUrl, {
                 method: "POST",
                 headers: initHeaders,
                 body: new Uint8Array(0),
             });
-            if (!initRes.ok) {
-                const body = await initRes.text().catch(() => "");
-                throw new Error(`GCS resumable session initiation failed (${initRes.status}): ${body}`);
-            }
             const sessionUri = initRes.headers.get("location");
             if (!sessionUri)
                 throw new Error("GCS did not return a Location header for the resumable session");

package/dist/file-upload/index.d.ts

@@ -1,6 +1,7 @@
 export type { FileUploadDeleteInput, FileUploadInput, FileUploadProvider, FileUploadResult, ResumableUploadSession, ResumableChunkResult, } from "./types.js";
 export { registerFileUploadProvider, unregisterFileUploadProvider, listFileUploadProviders, getActiveFileUploadProvider, getActiveFileUploadProviderForRequest, deleteUploadedFile, uploadFile, } from "./registry.js";
 export { builderFileUploadProvider } from "./builder.js";
+export { BuilderGatewayError, type BuilderGatewayErrorDetails, type BuilderGatewayStep, } from "./builder-gateway.js";
 export { getBuilderUploadCredentialStatus } from "./status.js";
 export { ensureS3FileUploadProvider, S3RequestError, s3FileUploadProvider, } from "./s3.js";
 export { cancelS3ResponseBody, fetchS3WithTimeout, presignS3GetUrl, readS3ErrorText, rfc3986, s3ObjectUri, sha256Hex, signS3Request, signedS3Request, trustedDeploymentS3Origin, type PresignS3GetOptions, type S3ClientConfig, type S3Method, type SignedS3RequestOptions, } from "./s3-client.js";

package/dist/file-upload/index.js

@@ -1,5 +1,6 @@
 export { registerFileUploadProvider, unregisterFileUploadProvider, listFileUploadProviders, getActiveFileUploadProvider, getActiveFileUploadProviderForRequest, deleteUploadedFile, uploadFile, } from "./registry.js";
 export { builderFileUploadProvider } from "./builder.js";
+export { BuilderGatewayError, } from "./builder-gateway.js";
 export { getBuilderUploadCredentialStatus } from "./status.js";
 export { ensureS3FileUploadProvider, S3RequestError, s3FileUploadProvider, } from "./s3.js";
 export { cancelS3ResponseBody, fetchS3WithTimeout, presignS3GetUrl, readS3ErrorText, rfc3986, s3ObjectUri, sha256Hex, signS3Request, signedS3Request, trustedDeploymentS3Origin, } from "./s3-client.js";

package/dist/framework-package-versions.json

@@ -1,17 +1,17 @@
 {
-  "@agent-native/agentkit": "0.228.2-nightly-20261113032548",
+  "@agent-native/agentkit": "0.228.2",
   "@agent-native/code-agents-ui": "0.1.75",
-  "@agent-native/core": "0.228.2-nightly-20261113032548",
-  "@agent-native/core-corpus": "0.228.2-nightly-20261113032548",
-  "@agent-native/creative-context": "0.8.71",
-  "@agent-native/dispatch": "0.42.7-nightly-20261113032548",
+  "@agent-native/core": "0.228.2",
+  "@agent-native/core-corpus": "0.228.2",
+  "@agent-native/creative-context": "0.8.72",
+  "@agent-native/dispatch": "0.42.7",
   "@agent-native/embedding": "0.2.0",
   "@agent-native/migrate": "0.0.7",
-  "@agent-native/otel": "0.1.38",
-  "@agent-native/pinpoint": "0.1.114",
-  "@agent-native/recap-cli": "0.5.102",
-  "@agent-native/scheduling": "0.2.58",
+  "@agent-native/otel": "0.1.39",
+  "@agent-native/pinpoint": "0.1.115",
+  "@agent-native/recap-cli": "0.5.103",
+  "@agent-native/scheduling": "0.2.59",
   "@agent-native/shared-app-config": "0.1.2",
-  "@agent-native/skills": "0.4.7-nightly-20261113032548",
-  "@agent-native/toolkit": "0.228.2-nightly-20261113032548"
+  "@agent-native/skills": "0.4.7",
+  "@agent-native/toolkit": "0.228.2"
 }

package/dist/identity/rekey.js

@@ -239,6 +239,8 @@ export const IDENTITY_REKEY_IGNORED_COLUMNS = new Set([
     "tool_history.actor_email",
     "tool_history.owner_email",
     "agent_resource_versions.created_by",
+    // Creator attribution on a Vault key, kept as written; the key is owned by its scope.
+    "app_secrets.created_by",
     "agent_review_comments.created_by",
     "agent_human_review_summaries.created_by",
     "organizations.created_by",