@agent-native/core 0.210.0-nightly-20261019183757 → 0.210.0

package/dist/agent/action-error-details.d.ts

@@ -0,0 +1,26 @@
+/** Longest serialized `details` an agent sees with a failed action. */
+export declare const MAX_AGENT_ERROR_DETAILS_CHARS = 2000;
+export interface AgentErrorDetails {
+    /** The `details` a `fail()` attached, as the browser receives them, redacted and bounded. */
+    details: Record<string, unknown>;
+    /**
+     * Top-level keys left out to stay within the bound, or because they don't
+     * serialize: up to ten names, each clipped, with the full count beside them.
+     */
+    omittedKeys?: string[];
+    omittedKeyCount?: number;
+    /** The line a text-only tool result carries, so text clients see the same data. */
+    line: string;
+}
+/**
+ * The structured `details` of a failed action, in the form an agent reads.
+ *
+ * Only a contract error (`fail()`) carries details meant for the caller; the
+ * HTTP action route already returns them to the browser, so an agent acting
+ * for the same user gets the same object. Values go through a JSON round trip
+ * first, so a `Date` reads as the browser would see it rather than as `{}`.
+ * When the whole object is too long, small top-level entries are kept in
+ * order and the rest are named in `omittedKeys`: a retry id must survive next
+ * to a large payload, and a cut must never read as a complete object.
+ */
+export declare function agentErrorDetails(error: unknown): AgentErrorDetails | undefined;

package/dist/agent/action-error-details.js

@@ -0,0 +1,99 @@
+import { isActionContractError } from "../action.js";
+import { redactSensitiveFields, sanitizeToolErrorText, } from "./tool-error-redaction.js";
+/** Longest serialized `details` an agent sees with a failed action. */
+export const MAX_AGENT_ERROR_DETAILS_CHARS = 2_000;
+/** A top-level entry longer than this is left out once the whole set is too long. */
+const MAX_KEPT_ENTRY_CHARS = 300;
+const MAX_LISTED_OMITTED_KEYS = 10;
+const MAX_OMITTED_KEY_CHARS = 60;
+/**
+ * The structured `details` of a failed action, in the form an agent reads.
+ *
+ * Only a contract error (`fail()`) carries details meant for the caller; the
+ * HTTP action route already returns them to the browser, so an agent acting
+ * for the same user gets the same object. Values go through a JSON round trip
+ * first, so a `Date` reads as the browser would see it rather than as `{}`.
+ * When the whole object is too long, small top-level entries are kept in
+ * order and the rest are named in `omittedKeys`: a retry id must survive next
+ * to a large payload, and a cut must never read as a complete object.
+ */
+export function agentErrorDetails(error) {
+    if (!isActionContractError(error))
+        return undefined;
+    const raw = error.details;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const entries = [];
+    const omittedKeys = [];
+    for (const key of Object.keys(raw)) {
+        const clean = jsonSafeEntry(raw, key);
+        if (clean === UNSERIALIZABLE)
+            omittedKeys.push(key);
+        else if (clean !== undefined)
+            entries.push([key, clean]);
+    }
+    const cleaned = Object.fromEntries(entries);
+    let details = cleaned;
+    if (JSON.stringify(cleaned).length > MAX_AGENT_ERROR_DETAILS_CHARS) {
+        details = {};
+        let budget = MAX_AGENT_ERROR_DETAILS_CHARS - 2;
+        for (const [key, value] of entries) {
+            const size = JSON.stringify({ [key]: value }).length - 1;
+            if (size <= MAX_KEPT_ENTRY_CHARS && size <= budget) {
+                details[key] = value;
+                budget -= size;
+            }
+            else {
+                omittedKeys.push(key);
+            }
+        }
+    }
+    if (Object.keys(details).length === 0 && omittedKeys.length === 0) {
+        return undefined;
+    }
+    const listed = omittedKeys
+        .slice(0, MAX_LISTED_OMITTED_KEYS)
+        .map((key) => key.length > MAX_OMITTED_KEY_CHARS
+        ? `${key.slice(0, MAX_OMITTED_KEY_CHARS)}…`
+        : key);
+    const more = omittedKeys.length > listed.length
+        ? `, and ${omittedKeys.length - listed.length} more`
+        : "";
+    return {
+        details,
+        ...(omittedKeys.length > 0
+            ? { omittedKeys: listed, omittedKeyCount: omittedKeys.length }
+            : {}),
+        line: `Error details${listed.length > 0 ? ` (omitted: ${listed.join(", ")}${more})` : ""}: ${JSON.stringify(details)}`,
+    };
+}
+const UNSERIALIZABLE = Symbol("unserializable");
+function jsonSafeEntry(raw, key) {
+    let parsed;
+    try {
+        // A getter can throw. Reading it here names the key; reading it outside
+        // would replace the action's own error.
+        const json = JSON.stringify(raw[key]);
+        if (json === undefined)
+            return undefined;
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return UNSERIALIZABLE;
+    }
+    const redacted = redactSensitiveFields({ [key]: parsed }, { compoundNames: true });
+    return sanitizeStrings(redacted[key]);
+}
+function sanitizeStrings(value) {
+    if (typeof value === "string")
+        return sanitizeToolErrorText(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeStrings);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            sanitizeStrings(entry),
+        ]));
+    }
+    return value;
+}

package/dist/agent/production-agent.js

@@ -56,6 +56,7 @@ import { DurableAttachmentReferenceRequiredError, stripInlineBytes, } from "../s
 import { isReasoningEffort, normalizeReasoningEffortForRequest, stepDownReasoningEffort, } from "../shared/reasoning-effort.js";
 import { SYNTHETIC_TRAFFIC_BETA_E2E, SYNTHETIC_TRAFFIC_HEADER, } from "../shared/test-traffic.js";
 import { actionPreparationContinuationNote } from "./action-continuation-guidance.js";
+import { agentErrorDetails } from "./action-error-details.js";
 import { drainAgentWarnings, formatAgentWarningsForToolResult, } from "./action-warnings.js";
 import { approvalKeyWithArguments } from "./approval-key.js";
 import { CONTINUE_UNAVAILABLE_CODE, } from "./auto-continue.js";
@@ -6617,6 +6618,7 @@ export async function runAgentLoop(opts) {
                 // handler returned does not.
                 let toolResultLost = false;
                 let toolErrorCode;
+                let toolErrorDetailsLine = "";
                 let mcpApp;
                 let toolResultImages;
                 let toolArtifacts = [];
@@ -6928,6 +6930,7 @@ export async function runAgentLoop(opts) {
                     toolErrorCode = isActionContractError(err)
                         ? err.errorCode
                         : undefined;
+                    toolErrorDetailsLine = agentErrorDetails(err)?.line ?? "";
                     result = signal.aborted
                         ? INTERRUPTED_TOOL_RESULT_MARKER
                         : thrownToolResult(err);
@@ -6940,7 +6943,13 @@ export async function runAgentLoop(opts) {
                 if (isError) {
                     receipt = undefined;
                     if (result !== INTERRUPTED_TOOL_RESULT_MARKER) {
+                        // Details go on after the loop breakers and the precondition
+                        // stop read the result: a retry id that changes on every attempt
+                        // must not make the same failure look like a new one.
                         result = finalizeToolErrorResult(result);
+                        if (toolErrorDetailsLine) {
+                            result = `${result}\n${toolErrorDetailsLine}`;
+                        }
                     }
                 }
                 else {

package/dist/agent/tool-error-redaction.d.ts

@@ -1,3 +1,10 @@
-export declare function redactSensitiveFields(value: unknown): unknown;
+/**
+ * `compoundNames` also redacts names such as `clientSecret`, `x-api-key`,
+ * `githubToken` or `embedTicket`.
+ * Tool-error text leaves it off and keeps names like `mySecret` readable.
+ */
+export declare function redactSensitiveFields(value: unknown, options?: {
+    compoundNames?: boolean;
+}): unknown;
 export declare function sanitizeToolErrorText(value: string): string;
 export declare function sanitizeToolErrorValue(value: unknown): string;

package/dist/agent/tool-error-redaction.js

@@ -1,22 +1,85 @@
+import { EMBED_RESULT_SENSITIVE_KEYS } from "../mcp/embed-redaction.js";
 const REDACTED = "[REDACTED]";
 const SENSITIVE_FIELD_PATTERN = /^(authorization|cookie|api[_-]?key|password|secret|token|access[_-]?token|refresh[_-]?token|bearer)$/i;
+// Only the trailing words of a compound name count. A `…Token` is a
+// credential unless it is a cursor such as `nextPageToken`, which an agent
+// needs for a retry. A `…Ticket` can redeem an embed session.
+const SENSITIVE_LAST_WORDS = new Set([
+    "authorization",
+    "cookie",
+    "credential",
+    "credentials",
+    "passphrase",
+    "password",
+    "secret",
+    "secrets",
+    "ticket",
+]);
+const SENSITIVE_LAST_WORD_PAIRS = new Set([
+    "access key",
+    "api key",
+    "private key",
+    "secret key",
+]);
+const CURSOR_TOKEN_QUALIFIERS = new Set([
+    "continuation",
+    "cursor",
+    "delta",
+    "idempotency",
+    "next",
+    "page",
+    "prev",
+    "previous",
+    "resume",
+    "skip",
+    "sync",
+]);
+function isSensitiveCompoundFieldName(key) {
+    if (SENSITIVE_FIELD_PATTERN.test(key) ||
+        EMBED_RESULT_SENSITIVE_KEYS.has(key)) {
+        return true;
+    }
+    const words = key
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+    const last = words.at(-1);
+    if (!last)
+        return false;
+    if (SENSITIVE_LAST_WORDS.has(last))
+        return true;
+    if (last === "token") {
+        return words.length > 1 && !CURSOR_TOKEN_QUALIFIERS.has(words.at(-2));
+    }
+    return (words.length > 1 && SENSITIVE_LAST_WORD_PAIRS.has(`${words.at(-2)} ${last}`));
+}
 const OPENAI_LIKE_SECRET_PATTERN = /(^|[^A-Za-z0-9_-])(sk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{24,})(?=$|[^A-Za-z0-9_-])/g;
-export function redactSensitiveFields(value) {
-    return redactWalk(value, new WeakSet());
+/**
+ * `compoundNames` also redacts names such as `clientSecret`, `x-api-key`,
+ * `githubToken` or `embedTicket`.
+ * Tool-error text leaves it off and keeps names like `mySecret` readable.
+ */
+export function redactSensitiveFields(value, options = {}) {
+    const isSensitive = options.compoundNames
+        ? isSensitiveCompoundFieldName
+        : (key) => SENSITIVE_FIELD_PATTERN.test(key);
+    return redactWalk(value, new WeakSet(), isSensitive);
 }
-function redactWalk(value, seen) {
+function redactWalk(value, seen, isSensitive) {
     if (value === null || typeof value !== "object")
         return value;
     if (seen.has(value))
         return "[Circular]";
     seen.add(value);
-    if (Array.isArray(value))
-        return value.map((v) => redactWalk(v, seen));
+    if (Array.isArray(value)) {
+        return value.map((v) => redactWalk(v, seen, isSensitive));
+    }
     const out = {};
     for (const [key, entry] of Object.entries(value)) {
-        out[key] = SENSITIVE_FIELD_PATTERN.test(key)
+        out[key] = isSensitive(key)
             ? REDACTED
-            : redactWalk(entry, seen);
+            : redactWalk(entry, seen, isSensitive);
     }
     return out;
 }

package/dist/automation/index.d.ts

@@ -139,8 +139,8 @@ export declare function createAutomationCallbackHandler(runtime: AutomationRunti
     duplicate?: undefined;
     eventId?: undefined;
 } | {
+    error?: undefined;
     accepted: boolean;
     duplicate: boolean;
     eventId: string;
-    error?: undefined;
 }>;

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

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

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

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

package/dist/jobs/actions/manage-recurring-job.d.ts

@@ -11,9 +11,9 @@ declare const _default: import("../../action.js").ActionDefinition<{
     enabled?: undefined;
     nextRun?: undefined;
 } | {
+    deleted?: undefined;
     name: string;
     enabled: boolean;
     nextRun: string;
-    deleted?: undefined;
 }>;
 export default _default;

package/dist/mcp/direct-action-call.js

@@ -1,5 +1,6 @@
 import { actionCallReadOnly, actionChangeResource, } from "../action-call-classification.js";
 import { ActionOutputContractError, failedCallEmitsChange, isActionOutputContractError, invocationEffect, ranCallEmitsChange, } from "../action.js";
+import { agentErrorDetails } from "../agent/action-error-details.js";
 import { extractAgentImagesFromActionResult } from "../agent/tool-result-images.js";
 import { writeActionChangeMarker } from "../server/action-change-marker-write.js";
 import { captureError } from "../server/capture-error.js";
@@ -35,6 +36,13 @@ export function createDirectActionCall(scope) {
     return async (call, fail) => {
         const { name, args, request, ctx } = call;
         const callableActions = fullCatalogRequested ? actions : advertisedActions;
+        // A directory profile may project results arbitrarily, so the derived
+        // contract is advertised and enforced on app catalogs only. It compiles
+        // before the action runs. A host may hold an error result to the same
+        // schema, so a contracted tool's errors carry no structuredContent.
+        const outputContract = directoryCatalog
+            ? undefined
+            : callableActions[name]?.mcpOutputContract;
         const errorText = (err) => {
             const projectedError = directoryCatalog && config.directoryProfile?.projectResult
                 ? config.directoryProfile.projectResult(name, err.message)
@@ -55,10 +63,37 @@ export function createDirectActionCall(scope) {
             try {
                 const errorCode = mcpActionErrorCode(err);
                 const { errorType, errorMessage } = describeMcpError(err);
-                return toolCallError({
-                    errorType: redactEmbedText(errorType),
-                    errorMessage: redactEmbedText(errorMessage),
-                }, `${redactEmbedText(errorText(err))}${errorCode !== undefined ? ` (errorCode: ${redactEmbedText(errorCode)})` : ""}`);
+                const message = redactEmbedText(errorText(err));
+                // A directory profile decides what its catalog shows, and it
+                // projects only the message.
+                const details = directoryCatalog ? undefined : agentErrorDetails(err);
+                const detailsLine = details && redactEmbedText(details.line);
+                return {
+                    ...toolCallError({
+                        errorType: redactEmbedText(errorType),
+                        errorMessage: redactEmbedText(errorMessage),
+                    }, `${message}${errorCode !== undefined ? ` (errorCode: ${redactEmbedText(errorCode)})` : ""}${detailsLine ? `\n${detailsLine}` : ""}`),
+                    // Some clients hand the model structuredContent in place of the
+                    // text, so it repeats the message rather than carrying details
+                    // alone. Details the embed check hid in the text stay out of it.
+                    ...(details && detailsLine === details.line && !outputContract
+                        ? {
+                            structuredContent: {
+                                error: {
+                                    message,
+                                    errorCode: err.errorCode,
+                                    details: details.details,
+                                    ...(details.omittedKeys
+                                        ? {
+                                            omittedKeys: details.omittedKeys,
+                                            omittedKeyCount: details.omittedKeyCount,
+                                        }
+                                        : {}),
+                                },
+                            },
+                        }
+                        : {}),
+                };
             }
             catch {
                 return toolCallError({
@@ -67,12 +102,6 @@ export function createDirectActionCall(scope) {
                 });
             }
         };
-        // A directory profile may project results arbitrarily, so the derived
-        // contract is advertised and enforced on app catalogs only. It compiles
-        // before the action runs.
-        const outputContract = directoryCatalog
-            ? undefined
-            : callableActions[name]?.mcpOutputContract;
         let checkOutput;
         try {
             checkOutput = outputContract

package/dist/notifications/routes.d.ts

@@ -1,12 +1,12 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -14,8 +14,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -27,43 +27,43 @@ 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[];
+} | {
     error?: undefined;
     ok?: undefined;
-} | {
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     traceMissing: true;
     id: string;
+} | {
     error?: undefined;
     ok?: undefined;
-} | {
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     traceMissing?: undefined;
     id: string;
-    error?: undefined;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     error: any;
-    ok?: undefined;
 } | {
+    error?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/progress/routes.d.ts

@@ -2,6 +2,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

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

@@ -75,6 +75,7 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
+    message?: undefined;
     deleted?: undefined;
     found?: undefined;
     id?: undefined;
@@ -91,8 +92,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     provider?: undefined;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     deleted?: undefined;
     id?: undefined;
     providers?: undefined;
@@ -101,8 +102,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     deleted?: undefined;
     providers?: undefined;
     count?: undefined;
@@ -111,8 +112,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     found?: undefined;
     providers?: undefined;
     count?: undefined;
@@ -121,7 +122,6 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
     deleted?: undefined;
     found?: undefined;

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;
 } | {
+    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;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -66,6 +66,7 @@ export declare function createAgentEngineApiKeyHandler(): import("h3").EventHand
     error: any;
     code: any;
 } | {
+    error?: undefined;
     errorCode?: undefined;
     code?: undefined;
     ok: boolean;
@@ -73,6 +74,5 @@ export declare function createAgentEngineApiKeyHandler(): import("h3").EventHand
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
     defaultModel?: import("./agent-engine-default-model-route.js").SavedKeyDefaultModelOutcome;
-    error?: undefined;
 }>>;
 export {};

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

@@ -8,8 +8,8 @@ export declare const AGENT_ENGINE_API_KEY_ACTION_NAME = "agent-engine-api-key";
  * resolveEngine's credential detection.
  */
 export declare function createAgentEngineDisconnectHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
     scope?: undefined;
 } | {
     ok: boolean;

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

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

package/dist/server/realtime-token.d.ts

@@ -54,8 +54,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/dist/templates/chat/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/dist/templates/default/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/dist/templates/factory/.agents/skills/review-prs/SKILL.md

@@ -3,8 +3,9 @@ name: review-prs
 description: >-
   Review recent BuilderIO/agent-native human pull requests, approve eligible
   internal PRs, and merge changes that are ready by Steve's bar. Use for
-  scheduled or manual PR sweeps; flag external non-bug work and unresolved major
-  product or UX decisions to Steve.
+  scheduled or manual PR sweeps; flag external work needing a major product
+  call or new framework API, and unresolved major product or UX decisions, to
+  Steve.
 user-invocable: true
 scope: dev
 metadata:
@@ -20,10 +21,12 @@ approve an external or unverified author.
 
 Approval and merge readiness are separate. A **Ready to merge by Steve's bar**
 result means merge the PR under the guarded merge procedure below. For a
-confirmed external author, only a clear bug fix enters evidence review and the
-possible merge flow; external authors are never eligible for an approval
-review. Surface other external work for Steve's explicit approval before a full
-review or merge; a scheduled or manual sweep is not that approval.
+confirmed external author, a clear bug fix or a bounded improvement that
+follows existing patterns enters evidence review and the possible merge flow;
+external authors are never eligible for an approval review. Surface external
+work that needs a major product call or a new framework API for Steve's explicit
+approval before a full review or merge; a scheduled or manual sweep is not that
+approval.
 
 ## Selection and evidence
 
@@ -53,6 +56,11 @@ author and draft state:
    summary to determine whether the PR already has a current, non-dismissed
    `APPROVED` review.
 
+ - Before the scope gate, check a confirmed nonmember's PR from a fork for
+   assignees. If any assignee is a verified current BuilderIO member, ignore
+   the PR completely, like a draft: that person owns it under `community-prs`.
+   Take no review, reply, or merge action, and leave it out of the recap.
+
  - Reuse that review as the code assessment only after verifying the reviewer
    is a different, current BuilderIO member and is eligible under the PR's
    author- and scope-specific rules, including any independent-review
@@ -99,17 +107,28 @@ the patch looks safe or the issue is obviously valid.
 
 ## External-contribution scope gate
 
+Builder devs decide bounded outside contributions; Steve keeps major product
+calls and new framework APIs.
+
 For an author the membership API confirms is not a current BuilderIO member,
-continue into the normal evidence sweep only for a clear bug fix: a change that
-corrects a specific reported or reproducible defect by restoring intended
-behavior. A feature, improvement, refactor, new or changed product behavior, or
-mixed bug-fix-and-enhancement scope is not a clear bug fix. If the title, issue,
-and initial diff do not establish a clear bug fix, treat it as non-bug work.
-
-For external non-bug work, stop before the full code review, approval or review
-action, merge-readiness disposition, author-facing draft, or merge. Report it to
-Steve as **Needs Steve's approval for scope**, with the PR link, author, stated
-scope, and why it is not a clear bug fix. Wait for Steve's explicit go-ahead on
+continue into the normal evidence sweep for a clear bug fix or a bounded
+improvement. A clear bug fix corrects a specific reported or reproducible
+defect by restoring intended behavior. A bounded improvement stays within one
+established workflow, app, or framework area and follows the patterns already
+there.
+
+External work needs Steve when it makes a major product call (as defined under
+Product and UX decisions) or adds a new framework API: a new public export,
+configuration option, action, plugin or hook contract, or CLI surface in a
+published package under `packages/`. A fix or bounded improvement to an existing
+API stays with devs when it keeps that API's contract. If the title, issue, and
+initial diff do not establish a clear bug fix or a bounded improvement, treat it
+as needing Steve.
+
+For external work that needs Steve, stop before the full code review, approval
+or review action, merge-readiness disposition, author-facing draft, or merge.
+Report it to Steve as **Needs Steve's approval for scope**, with the PR link,
+author, stated scope, and which call it needs. Wait for Steve's explicit go-ahead on
 that PR before continuing. Invoking or scheduling `review-prs`, approving a
 different PR, or prior approval of another external contribution does not
 authorize it. If membership is unknown, use the existing unknown-membership
@@ -118,6 +137,8 @@ solely because membership could not be verified. Keep the no-approval outcome,
 report the missing membership check, and assess merge readiness under the
 existing unknown-membership policy.
 
+Builder devs own outside PRs end to end with `community-prs`.
+
 ## Liamdebeasi approval policy
 
 For a PR authored by the exact GitHub login `liamdebeasi` and immutable user
@@ -296,9 +317,10 @@ merge scope and must remain completely untouched.
 For a PR that fails an approval gate, do not submit an approval. Flag the exact
 concern and the evidence needed to resolve it. External or unverified authors
 never receive an approval review, but their PRs can still be merged when they
-meet the readiness gate below. Confirmed external bug fixes must also pass the
-external-contribution scope gate; confirmed external non-bug work remains
-stopped at Steve's approval gate. For unknown membership, do not apply the
+meet the readiness gate below. Confirmed external PRs must also pass the
+external-contribution scope gate; external work that needs a major product call
+or a new framework API remains stopped at Steve's approval gate. For unknown
+membership, do not apply the
 external scope gate solely because verification failed; preserve the
 no-approval outcome, assess readiness under the existing unknown-membership
 policy, and name the missing check.
@@ -504,7 +526,8 @@ non-auto-approved external PR that needs an update or screenshot, include its
 draft reply in a separate section, or mark it waiting on the contributor with
 a link to Steve's outstanding request. For internal PRs, report the needed
 update or screenshot without drafting an author-facing reply. Do not add rows
-for bots, `steve8708`, or drafts; those are ignored completely.
+for bots, `steve8708`, drafts, or external PRs assigned to a BuilderIO member;
+those are ignored completely.
 
 Use this shape:
 
@@ -525,4 +548,4 @@ blocker when the PR is ready and the guarded admin merge is available.
 
 ## Related skills
 
-`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`
+`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`, `community-prs`

package/dist/templates/headless/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/dist/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

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

@@ -13,6 +13,8 @@ declare const _default: import("../../action.js").ActionDefinition<{
     executionEngine?: string;
     executionCwd?: string;
 }, {
+    deleted?: undefined;
+    enabled?: undefined;
     created: boolean;
     name: string;
     scope: "organization" | "personal";
@@ -23,33 +25,31 @@ declare const _default: import("../../action.js").ActionDefinition<{
     reasoningEffort: "auto" | "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh";
     webhookPath: string;
     nextRun: string;
-    deleted?: undefined;
-    enabled?: undefined;
     executionHostId?: undefined;
     executionEngine?: undefined;
     executionCwd?: undefined;
 } | {
+    enabled?: undefined;
+    nextRun?: undefined;
     created?: undefined;
     scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
     deleted: boolean;
     name: string;
-    enabled?: undefined;
     schedule?: undefined;
     timezone?: undefined;
     reasoningEffort?: undefined;
     executionHostId?: undefined;
     executionEngine?: undefined;
     executionCwd?: undefined;
-    nextRun?: undefined;
     webhookPath?: undefined;
 } | {
+    deleted?: undefined;
     created?: undefined;
     scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
-    deleted?: undefined;
     name: string;
     enabled: boolean;
     schedule: string;

package/docs/content/actions-defining.mdx

@@ -324,7 +324,7 @@ What you throw decides how much of the message survives. `fail()` raises an `Act
 - **message**: the text the caller reads. Write it for a person, not for a log.
 - **options.errorCode**: a stable machine-readable code. Defaults to `"action_failed"`.
 - **options.statusCode**: the HTTP status for the action route. Defaults to `400`.
-- **options.details**: safe structured context for the caller. Never put secrets or raw driver output here.
+- **options.details**: safe structured context for the caller, such as the id a retry needs. The browser and agents both receive it. Never put secrets or raw driver output here.
 
 The simplest call needs only a message:
 
@@ -402,7 +402,7 @@ A network drop, a proxy's HTML error page, and a bare status line author no mess
 
 So the status is not cosmetic. A refusal sent as `404` costs one round trip. The same refusal sent as a `500`, or thrown bare, costs four round trips and four duplicate error reports.
 
-Agent callers never see the status. The agent runs `run()` in process, so it receives the message directly whatever the type, as `Error running <action>: <message>`. An `errorCode` other than the default `action_failed` is appended as `(errorCode: not_found)` so the model can branch on it without parsing prose. External agents over MCP get the same text. Secrets in the message are redacted first, and the agent's own repeated-error breakers bound how many times it tries again.
+Agent callers never see the status. The agent runs `run()` in process, so it receives the message directly whatever the type, as `Error running <action>: <message>`. An `errorCode` other than the default `action_failed` is appended as `(errorCode: not_found)` so the model can branch on it without parsing prose. `details` follow on their own line as compact JSON, such as `Error details: {"importId":"imp_1"}`, so an id the model needs for its next call doesn't have to be written into the message. External agents over MCP get the same text, and the same details in `structuredContent.error`. A tool that advertises an output schema (`mcpOutputSchema: true`) returns the text only, since a client may check an error result against that schema too. Details are capped at 2,000 characters: past that, small top-level entries are kept and the rest are listed as omitted. Secrets in the message and details are redacted first, and the agent's own repeated-error breakers bound how many times it tries again.
 
 ## Keep the action surface small {#small-surface}
 

package/package.json

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

package/src/templates/chat/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/src/templates/default/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/src/templates/factory/.agents/skills/review-prs/SKILL.md

@@ -3,8 +3,9 @@ name: review-prs
 description: >-
   Review recent BuilderIO/agent-native human pull requests, approve eligible
   internal PRs, and merge changes that are ready by Steve's bar. Use for
-  scheduled or manual PR sweeps; flag external non-bug work and unresolved major
-  product or UX decisions to Steve.
+  scheduled or manual PR sweeps; flag external work needing a major product
+  call or new framework API, and unresolved major product or UX decisions, to
+  Steve.
 user-invocable: true
 scope: dev
 metadata:
@@ -20,10 +21,12 @@ approve an external or unverified author.
 
 Approval and merge readiness are separate. A **Ready to merge by Steve's bar**
 result means merge the PR under the guarded merge procedure below. For a
-confirmed external author, only a clear bug fix enters evidence review and the
-possible merge flow; external authors are never eligible for an approval
-review. Surface other external work for Steve's explicit approval before a full
-review or merge; a scheduled or manual sweep is not that approval.
+confirmed external author, a clear bug fix or a bounded improvement that
+follows existing patterns enters evidence review and the possible merge flow;
+external authors are never eligible for an approval review. Surface external
+work that needs a major product call or a new framework API for Steve's explicit
+approval before a full review or merge; a scheduled or manual sweep is not that
+approval.
 
 ## Selection and evidence
 
@@ -53,6 +56,11 @@ author and draft state:
    summary to determine whether the PR already has a current, non-dismissed
    `APPROVED` review.
 
+ - Before the scope gate, check a confirmed nonmember's PR from a fork for
+   assignees. If any assignee is a verified current BuilderIO member, ignore
+   the PR completely, like a draft: that person owns it under `community-prs`.
+   Take no review, reply, or merge action, and leave it out of the recap.
+
  - Reuse that review as the code assessment only after verifying the reviewer
    is a different, current BuilderIO member and is eligible under the PR's
    author- and scope-specific rules, including any independent-review
@@ -99,17 +107,28 @@ the patch looks safe or the issue is obviously valid.
 
 ## External-contribution scope gate
 
+Builder devs decide bounded outside contributions; Steve keeps major product
+calls and new framework APIs.
+
 For an author the membership API confirms is not a current BuilderIO member,
-continue into the normal evidence sweep only for a clear bug fix: a change that
-corrects a specific reported or reproducible defect by restoring intended
-behavior. A feature, improvement, refactor, new or changed product behavior, or
-mixed bug-fix-and-enhancement scope is not a clear bug fix. If the title, issue,
-and initial diff do not establish a clear bug fix, treat it as non-bug work.
-
-For external non-bug work, stop before the full code review, approval or review
-action, merge-readiness disposition, author-facing draft, or merge. Report it to
-Steve as **Needs Steve's approval for scope**, with the PR link, author, stated
-scope, and why it is not a clear bug fix. Wait for Steve's explicit go-ahead on
+continue into the normal evidence sweep for a clear bug fix or a bounded
+improvement. A clear bug fix corrects a specific reported or reproducible
+defect by restoring intended behavior. A bounded improvement stays within one
+established workflow, app, or framework area and follows the patterns already
+there.
+
+External work needs Steve when it makes a major product call (as defined under
+Product and UX decisions) or adds a new framework API: a new public export,
+configuration option, action, plugin or hook contract, or CLI surface in a
+published package under `packages/`. A fix or bounded improvement to an existing
+API stays with devs when it keeps that API's contract. If the title, issue, and
+initial diff do not establish a clear bug fix or a bounded improvement, treat it
+as needing Steve.
+
+For external work that needs Steve, stop before the full code review, approval
+or review action, merge-readiness disposition, author-facing draft, or merge.
+Report it to Steve as **Needs Steve's approval for scope**, with the PR link,
+author, stated scope, and which call it needs. Wait for Steve's explicit go-ahead on
 that PR before continuing. Invoking or scheduling `review-prs`, approving a
 different PR, or prior approval of another external contribution does not
 authorize it. If membership is unknown, use the existing unknown-membership
@@ -118,6 +137,8 @@ solely because membership could not be verified. Keep the no-approval outcome,
 report the missing membership check, and assess merge readiness under the
 existing unknown-membership policy.
 
+Builder devs own outside PRs end to end with `community-prs`.
+
 ## Liamdebeasi approval policy
 
 For a PR authored by the exact GitHub login `liamdebeasi` and immutable user
@@ -296,9 +317,10 @@ merge scope and must remain completely untouched.
 For a PR that fails an approval gate, do not submit an approval. Flag the exact
 concern and the evidence needed to resolve it. External or unverified authors
 never receive an approval review, but their PRs can still be merged when they
-meet the readiness gate below. Confirmed external bug fixes must also pass the
-external-contribution scope gate; confirmed external non-bug work remains
-stopped at Steve's approval gate. For unknown membership, do not apply the
+meet the readiness gate below. Confirmed external PRs must also pass the
+external-contribution scope gate; external work that needs a major product call
+or a new framework API remains stopped at Steve's approval gate. For unknown
+membership, do not apply the
 external scope gate solely because verification failed; preserve the
 no-approval outcome, assess readiness under the existing unknown-membership
 policy, and name the missing check.
@@ -504,7 +526,8 @@ non-auto-approved external PR that needs an update or screenshot, include its
 draft reply in a separate section, or mark it waiting on the contributor with
 a link to Steve's outstanding request. For internal PRs, report the needed
 update or screenshot without drafting an author-facing reply. Do not add rows
-for bots, `steve8708`, or drafts; those are ignored completely.
+for bots, `steve8708`, drafts, or external PRs assigned to a BuilderIO member;
+those are ignored completely.
 
 Use this shape:
 
@@ -525,4 +548,4 @@ blocker when the PR is ready and the guarded admin merge is available.
 
 ## Related skills
 
-`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`
+`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`, `community-prs`

package/src/templates/headless/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/src/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.