@agent-native/core 0.227.0 → 0.228.0-nightly-20261111004142

package/dist/shared/runtime-config.js

@@ -127,6 +127,10 @@ function addIssue(issues, issue, environment) {
     });
 }
 export function buildRuntimeConfigPrompt(report, appName) {
+    // A healthy report has nothing to fix. A "fix this" prompt here would send
+    // an agent that reads the probe looking for problems that are not there.
+    if (report.issues.length === 0)
+        return "";
     const appLine = appName ? `\nApp: ${appName}` : "";
     const issueLines = report.issues
         .map((issue) => `- ${issue.severity.toUpperCase()}: ${issue.title}. ${issue.message}`)
@@ -137,7 +141,7 @@ export function buildRuntimeConfigPrompt(report, appName) {
         `Phase: ${report.phase}${appLine}`,
         "",
         "Detected issues:",
-        issueLines || "- No issues were reported.",
+        issueLines,
         "",
         "Inspect the app's agent-native.json or agent-native.config.ts (including compatibility aliases), its deployment configuration, and the framework defaults. Make the smallest safe fix. Keep secrets out of source control. Do not print secret values in your response. Tell me exactly which deploy settings still need to be set, then verify the production build and runtime health check.",
     ].join("\n");

package/dist/templates/chat/.agents/skills/context-awareness/SKILL.md

@@ -246,6 +246,19 @@ of the local route unless a matching `view` route or explicit `publicPath`
 identifies the mounted URL. Carry the mounted form separately in `publicPath`;
 never infer that `path` is mounted from its prefix alone.
 
+**Calls from no tab.** An MCP tool call by a signed-in user carries no tab ID,
+so the tab-scoped helpers (`readAppState("navigation")`,
+`readAppStateForCurrentTab`, `writeAppStateForCurrentTab`) act on the tab of
+this app the user used last within 12 hours. `useAgentRouteState` records a
+tab's use when it gains focus or changes route; an app with its own navigation
+sync calls `useBrowserTabUse(route)` from
+`@agent-native/core/client/navigation`. The call doesn't become that tab:
+`getCurrentRequestBrowserTabId()` stays null, and checks that must come from
+the open editor keep requiring it. When no tab was used recently, `navigation`
+reads return null rather than the account-wide row, writes keep going to the
+account-wide row, and the MCP result says no tab was found. To pick a tab the
+same way in your own code, use `resolveCurrentRequestStateTab()`.
+
 ## Jitter Prevention
 
 Agent-side application-state writes are tagged with

package/dist/templates/default/.agents/skills/context-awareness/SKILL.md

@@ -246,6 +246,19 @@ of the local route unless a matching `view` route or explicit `publicPath`
 identifies the mounted URL. Carry the mounted form separately in `publicPath`;
 never infer that `path` is mounted from its prefix alone.
 
+**Calls from no tab.** An MCP tool call by a signed-in user carries no tab ID,
+so the tab-scoped helpers (`readAppState("navigation")`,
+`readAppStateForCurrentTab`, `writeAppStateForCurrentTab`) act on the tab of
+this app the user used last within 12 hours. `useAgentRouteState` records a
+tab's use when it gains focus or changes route; an app with its own navigation
+sync calls `useBrowserTabUse(route)` from
+`@agent-native/core/client/navigation`. The call doesn't become that tab:
+`getCurrentRequestBrowserTabId()` stays null, and checks that must come from
+the open editor keep requiring it. When no tab was used recently, `navigation`
+reads return null rather than the account-wide row, writes keep going to the
+account-wide row, and the MCP result says no tab was found. To pick a tab the
+same way in your own code, use `resolveCurrentRequestStateTab()`.
+
 ## Jitter Prevention
 
 Agent-side application-state writes are tagged with

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

@@ -246,6 +246,19 @@ of the local route unless a matching `view` route or explicit `publicPath`
 identifies the mounted URL. Carry the mounted form separately in `publicPath`;
 never infer that `path` is mounted from its prefix alone.
 
+**Calls from no tab.** An MCP tool call by a signed-in user carries no tab ID,
+so the tab-scoped helpers (`readAppState("navigation")`,
+`readAppStateForCurrentTab`, `writeAppStateForCurrentTab`) act on the tab of
+this app the user used last within 12 hours. `useAgentRouteState` records a
+tab's use when it gains focus or changes route; an app with its own navigation
+sync calls `useBrowserTabUse(route)` from
+`@agent-native/core/client/navigation`. The call doesn't become that tab:
+`getCurrentRequestBrowserTabId()` stays null, and checks that must come from
+the open editor keep requiring it. When no tab was used recently, `navigation`
+reads return null rather than the account-wide row, writes keep going to the
+account-wide row, and the MCP result says no tab was found. To pick a tab the
+same way in your own code, use `resolveCurrentRequestStateTab()`.
+
 ## Jitter Prevention
 
 Agent-side application-state writes are tagged with

package/dist/tracking/providers.d.ts

@@ -1,3 +1,10 @@
 export declare const AGENT_NATIVE_ANALYTICS_PROVIDER = "agent-native-analytics";
+/**
+ * The end-of-request flush. On serverless, the caller hands this to the
+ * host's waitUntil, so sends still under way outlive the reply. Long-running
+ * servers don't freeze, and a flush per request would end their 10-second
+ * batching, so there it resolves at once.
+ */
+export declare function flushTrackingSendsForResponse(): Promise<void>;
 export declare function sendPostHogEvent(name: string, properties: Record<string, unknown>, distinctId: string): boolean;
 export declare function registerBuiltinProviders(): void;

package/dist/tracking/providers.js

@@ -1,6 +1,7 @@
 import { withoutWriteObservation } from "../action-frame.js";
 import { getAppConfig } from "../app-config/index.js";
-import { getRequestContext } from "../server/request-context.js";
+import { platformWaitUntil } from "../server/background-work.js";
+import { getRequestContext, getRequestRunContext, } from "../server/request-context.js";
 import { isTestIdentity } from "../server/test-identity.js";
 import { resolveLaneEndpoint } from "../shared/environment-lanes.js";
 import { reshapeTrackedExceptionProperties } from "./posthog-exception.js";
@@ -32,12 +33,26 @@ function getTimer() {
 function setTimer(t) {
     globalThis[TIMER_KEY] = t;
 }
+/**
+ * A serverless host can freeze the function once the reply is out, cutting
+ * off a send still under way. Inside a request, the host's waitUntil keeps the
+ * function up until the send ends. Actions reach it without the request event:
+ * Cloudflare's through the request's run context, Netlify's through its store.
+ */
+function keepAlive(sending) {
+    try {
+        (getRequestRunContext()?.waitUntil ?? platformWaitUntil())?.(sending);
+    }
+    catch {
+        // coercion-ok: the send is already under way; a host refusing to wait for it only risks that event.
+    }
+}
 function enqueue(url, body, headers, options) {
     const queue = getQueue();
     queue.push({ url, body, headers });
     const flushImmediately = options?.flushImmediately ?? isServerlessRuntime();
     if (flushImmediately || queue.length >= MAX_BATCH_SIZE) {
-        void drainQueue();
+        keepAlive(drainQueue());
     }
     else if (!getTimer()) {
         const timer = setTimeout(() => {
@@ -72,6 +87,22 @@ function drainQueue() {
     // hold the request's background lifetime until those sends settle.
     return Promise.all([...inFlight]);
 }
+/**
+ * Sends what is queued, then waits for every send still under way, including
+ * the ones a serverless runtime started the moment their event was tracked.
+ */
+function flushSends() {
+    return drainQueue().then(() => undefined);
+}
+/**
+ * The end-of-request flush. On serverless, the caller hands this to the
+ * host's waitUntil, so sends still under way outlive the reply. Long-running
+ * servers don't freeze, and a flush per request would end their 10-second
+ * batching, so there it resolves at once.
+ */
+export function flushTrackingSendsForResponse() {
+    return isServerlessRuntime() ? flushSends() : Promise.resolve();
+}
 function isLocalhostUrl(value) {
     if (!value || !value.trim())
         return false;
@@ -122,6 +153,7 @@ function shouldSkipAgentNativeAnalyticsForLocalhost() {
 function isServerlessRuntime() {
     return Boolean(process.env.NETLIFY ||
         process.env.VERCEL ||
+        process.env.CF_PAGES ||
         process.env.AWS_LAMBDA_FUNCTION_NAME ||
         process.env.AWS_EXECUTION_ENV ||
         process.env.LAMBDA_TASK_ROOT ||
@@ -202,9 +234,7 @@ function createPostHogProvider(apiKey, host, errorTracking) {
                 properties: { $set: traits },
             }));
         },
-        flush: () => {
-            return drainQueue().then(() => undefined);
-        },
+        flush: flushSends,
     };
 }
 export function sendPostHogEvent(name, properties, distinctId) {
@@ -258,9 +288,7 @@ function createMixpanelProvider(token) {
             };
             enqueue("https://api.mixpanel.com/engage", JSON.stringify([data]));
         },
-        flush: () => {
-            return drainQueue().then(() => undefined);
-        },
+        flush: flushSends,
     };
 }
 function stripExceptionContextForAmplitude(properties) {
@@ -307,9 +335,7 @@ function createAmplitudeProvider(apiKey) {
             };
             enqueue("https://api2.amplitude.com/2/httpapi", JSON.stringify(data));
         },
-        flush: () => {
-            return drainQueue().then(() => undefined);
-        },
+        flush: flushSends,
     };
 }
 function createWebhookProvider(url, authHeader) {
@@ -334,9 +360,7 @@ function createWebhookProvider(url, authHeader) {
                 timestamp: new Date().toISOString(),
             }), extra);
         },
-        flush: () => {
-            return drainQueue().then(() => undefined);
-        },
+        flush: flushSends,
     };
 }
 function createAgentNativeAnalyticsProvider(publicKey, endpoint) {
@@ -364,9 +388,7 @@ function createAgentNativeAnalyticsProvider(publicKey, endpoint) {
                 timestamp: new Date().toISOString(),
             }), undefined, { flushImmediately });
         },
-        flush: () => {
-            return drainQueue().then(() => undefined);
-        },
+        flush: flushSends,
     };
 }
 let _registered = false;

package/dist/triggers/condition-evaluator.d.ts

@@ -32,5 +32,7 @@ export declare function evaluateCondition(condition: string | undefined, payload
     signal?: AbortSignal;
     engine?: AgentEngine;
     resolvedModel?: string;
+    /** Usage label for the check's model call, such as the automation's own. */
+    usageLabel?: string;
 }): Promise<boolean>;
 export declare function __clearConditionCache(): void;

package/dist/triggers/condition-evaluator.js

@@ -27,6 +27,12 @@ import { getStoredModelForEngine, normalizeModelForEngine, resolveEngine, } from
 import { createTtlCache } from "../shared/ttl-cache.js";
 const CONDITION_EVAL_VERSION = "v4";
 const CONDITION_EVALUATION_TIMEOUT_MS = 15_000;
+// How long a check cut off by its deadline may take to unwind its aborted
+// stream, so the usage it reported is saved before the caller moves on.
+const ABORTED_CHECK_UNWIND_MS = 1_000;
+// How long the caller waits for the check's usage write. A write still
+// running after this finishes on its own; it never rejects.
+const USAGE_WRITE_WAIT_MS = 5_000;
 const CACHE_TTL_MS = 5 * 60 * 1000;
 const MAX_CACHE_SIZE = 500;
 const _cache = createTtlCache({
@@ -73,6 +79,9 @@ export async function evaluateCondition(condition, payload, identity, options =
     const controller = new AbortController();
     let timeoutId;
     let removeAbortListener;
+    // Saving what the check spent stays outside the deadline, so a slow write
+    // never turns an answer the model already gave into a timeout.
+    const usageWrites = [];
     const evaluate = async () => {
         let engine;
         let model;
@@ -115,7 +124,12 @@ export async function evaluateCondition(condition, payload, identity, options =
                 return cached;
         }
         // A classification is an answer, not a write of the call that emitted the event.
-        const result = await withoutWriteObservation(() => callClassifier(condition, payload, engine, model, controller.signal));
+        const result = await withoutWriteObservation(() => callClassifier(condition, payload, engine, model, controller.signal, {
+            ownerEmail: identity.userEmail,
+            ...(identity.orgId === undefined ? {} : { orgId: identity.orgId }),
+            ...(identity.appId === undefined ? {} : { app: identity.appId }),
+            label: options.usageLabel ?? "automation-condition",
+        }, usageWrites));
         if (controller.signal.aborted) {
             throw new Error(options.signal?.aborted
                 ? "Condition evaluation aborted."
@@ -141,10 +155,11 @@ export async function evaluateCondition(condition, payload, identity, options =
             removeAbortListener = () => options.signal.removeEventListener("abort", onAbort);
         })
         : null;
+    const evaluation = evaluate();
     let result;
     try {
         result = await Promise.race([
-            evaluate(),
+            evaluation,
             timeout,
             ...(aborted ? [aborted] : []),
         ]);
@@ -153,10 +168,54 @@ export async function evaluateCondition(condition, payload, identity, options =
         if (timeoutId)
             clearTimeout(timeoutId);
         removeAbortListener?.();
+        // A check cut off by the deadline queues its usage write only once its
+        // aborted stream unwinds, so give it a moment before collecting writes.
+        await settledWithin(evaluation, ABORTED_CHECK_UNWIND_MS);
+        await settledWithin(Promise.all(usageWrites), USAGE_WRITE_WAIT_MS);
     }
     return result;
 }
-async function callClassifier(condition, payload, engine, model, signal) {
+/**
+ * Resolves when `promise` settles or `ms` passes, whichever is first. The
+ * timer is always cleared, so it needs no Node-only `unref` (Workers timers
+ * are plain numbers).
+ */
+async function settledWithin(promise, ms) {
+    let timer;
+    try {
+        await Promise.race([
+            promise.then(() => undefined, () => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Save what the check spent, as every other model call does, so usage
+ * dashboards and spend totals include it on whichever key paid for it.
+ * Never rejects, so callers can leave it running.
+ */
+async function recordClassifierUsage(scope, usage) {
+    if (usage.inputTokens <= 0 &&
+        usage.outputTokens <= 0 &&
+        !usage.cacheReadTokens &&
+        !usage.cacheWriteTokens &&
+        usage.builderCreditsUsed == null) {
+        return;
+    }
+    try {
+        const { recordUsage } = await import("../usage/store.js");
+        await recordUsage({ ...scope, ...usage });
+    }
+    catch (error) {
+        console.error("[triggers] Failed to persist condition check usage:", error);
+    }
+}
+async function callClassifier(condition, payload, engine, model, signal, usageScope, usageWrites) {
     let payloadStr;
     try {
         payloadStr = JSON.stringify(payload, null, 2);
@@ -181,6 +240,13 @@ Condition: "${condition}"
 Does the event payload satisfy the condition above? Respond with ONLY "yes" or "no".`;
     let text = "";
     let streamErrorMessage;
+    const usage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        builderCreditsUsed: undefined,
+    };
     try {
         const stream = engine.stream({
             model,
@@ -196,6 +262,16 @@ Does the event payload satisfy the condition above? Respond with ONLY "yes" or "
             if (event.type === "text-delta") {
                 text += event.text;
             }
+            else if (event.type === "usage") {
+                usage.inputTokens += event.inputTokens;
+                usage.outputTokens += event.outputTokens;
+                usage.cacheReadTokens += event.cacheReadTokens ?? 0;
+                usage.cacheWriteTokens += event.cacheWriteTokens ?? 0;
+                if (event.builderCreditsUsed !== undefined) {
+                    usage.builderCreditsUsed =
+                        (usage.builderCreditsUsed ?? 0) + event.builderCreditsUsed;
+                }
+            }
             else if (event.type === "stop" && event.reason === "error") {
                 streamErrorMessage = event.error ?? "model error";
             }
@@ -209,6 +285,20 @@ Does the event payload satisfy the condition above? Respond with ONLY "yes" or "
             ? `Condition evaluation failed: ${err.message}`
             : "Condition evaluation failed: unknown error");
     }
+    finally {
+        // A check that failed or timed out after the model answered still spent.
+        usageWrites.push(recordClassifierUsage(usageScope, {
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            cacheReadTokens: usage.cacheReadTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            ...(usage.builderCreditsUsed === undefined
+                ? {}
+                : { builderCreditsUsed: usage.builderCreditsUsed }),
+            engineName: engine.name,
+            model,
+        }));
+    }
     if (streamErrorMessage) {
         throw new Error(`Condition evaluation failed: ${streamErrorMessage}`);
     }

package/dist/triggers/dispatcher.js

@@ -2,7 +2,7 @@ import { automationMatchesEventOwner, resolveAutomationExecutionIdentity, } from
 import { isProductionServerlessFunctionRuntime } from "../db/client.js";
 import { subscribeAll, unsubscribe } from "../event-bus/index.js";
 import { countAutomationCredentialState, trackAutomationPaused, } from "../jobs/automation-events.js";
-import { applyAutomationFailure, classifyAutomationFailure, CLEAR_FAILURE_STATE, CONFIG_INVALID_ERROR_CODE, OWNER_MISSING_ERROR_CODE, pauseNow, } from "../jobs/automation-outcome.js";
+import { applyAutomationFailure, classifyAutomationFailure, CLEAR_FAILURE_STATE, CONFIG_INVALID_ERROR_CODE, isTransientAutomationFailureCode, OWNER_MISSING_ERROR_CODE, pauseNow, } from "../jobs/automation-outcome.js";
 import { BackgroundAutomationRunError, checkBackgroundAutomationCredentials, isBackgroundAutomationRunActive, runBackgroundAutomation, validateAutomationRunIdentity, } from "../jobs/background-automation-runner.js";
 import { buildJobResourceContent, jobBelongsToApp, parseJobResource, patchJobFrontmatterFields, } from "../jobs/frontmatter.js";
 import { registerRecurringSweepHandler, } from "../jobs/sweep-hooks.js";
@@ -121,6 +121,13 @@ Execute the following automation instructions, and only these:
 
 ${input.body}`;
 }
+function automationNameOf(resource) {
+    return resource.path.replace(/^jobs\//, "").replace(/\.md$/, "");
+}
+/** One label for a run and its condition check, so both count as its spend. */
+function automationUsageLabel(resource) {
+    return `automation:${automationNameOf(resource)}`;
+}
 async function recordTriggerSkip(resource, status, reason, errorCode) {
     await recordTriggerExecutionOutcome(resource, {
         lastCheck: new Date().toISOString(),
@@ -193,7 +200,7 @@ failed) {
         countAutomationCredentialState(failed.failure.code);
     if (failed && pausedAfter !== undefined) {
         trackAutomationPaused({
-            name: resource.path.replace(/^jobs\//, "").replace(/\.md$/, ""),
+            name: automationNameOf(resource),
             failure: failed.failure,
             consecutiveFailures: pausedAfter,
             surface: failed.pauseImmediately ? "preflight" : "trigger",
@@ -979,7 +986,13 @@ async function dispatchQueuedAutomationEvent(queued, deps, hardDeadlineAt) {
                 : {}),
         }, deps, meta.model);
         if (!credentialCheck.ok) {
-            await recordTriggerExecutionOutcome(resource, { lastCheck: new Date().toISOString() }, { failure: credentialCheck.failure });
+            await recordTriggerExecutionOutcome(resource, { lastCheck: new Date().toISOString() }, { failure: credentialCheck.failure, eventId: queued.eventId });
+            // An unreadable credential store or a provider outage clears by itself,
+            // so the event stays queued, as it does when an unconditional run fails.
+            // A missing or rejected key does not, so the event ends here.
+            if (isTransientAutomationFailureCode(credentialCheck.failure.code)) {
+                throw new BackgroundAutomationRunError(credentialCheck.failure.message, credentialCheck.failure.code);
+            }
             return "completed";
         }
         classifierEngine = credentialCheck.engine;
@@ -1004,6 +1017,7 @@ async function dispatchQueuedAutomationEvent(queued, deps, hardDeadlineAt) {
             deadlineAt: hardDeadlineAt,
             engine: classifierEngine,
             resolvedModel: classifierModel,
+            usageLabel: automationUsageLabel(resource),
         }));
     }
     catch (error) {
@@ -1099,7 +1113,11 @@ export async function dispatchAutomationWebhookTask(task) {
             userEmail: identity.userEmail,
             orgId: identity.orgId,
             appId: deps.appId,
-        }, { engine: classifierEngine, resolvedModel: classifierModel }));
+        }, {
+            engine: classifierEngine,
+            resolvedModel: classifierModel,
+            usageLabel: automationUsageLabel(resource),
+        }));
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : "Condition evaluation failed";
@@ -1136,7 +1154,7 @@ export async function dispatchAutomationWebhookTask(task) {
 async function dispatchAgentic(resource, payload, eventMeta, identity, hardDeadlineAt) {
     if (!_deps)
         return false;
-    const triggerName = resource.path.replace(/^jobs\//, "").replace(/\.md$/, "");
+    const triggerName = automationNameOf(resource);
     const now = new Date();
     const jobUserEmail = identity.userEmail;
     const jobOrgId = identity.orgId;
@@ -1249,7 +1267,7 @@ async function dispatchAgentic(resource, payload, eventMeta, identity, hardDeadl
             }),
             threadTitle: `Trigger: ${triggerName} — ${now.toLocaleDateString()}`,
             runIdPrefix: `automation-${triggerName}`,
-            usageLabel: `automation:${triggerName}`,
+            usageLabel: automationUsageLabel(resource),
             usageRefId: eventMeta.eventId,
             eventId: eventMeta.eventId,
             requestContext,

package/docs/AGENTS.md

@@ -66,22 +66,22 @@ preserve public action, state, auth, and agent-chat runtime contracts.
 
 ## What To Read First
 
-| Task                                  | Start with                                                                                               |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Define or call app operations         | `content/actions.md`, `content/client.md`                                                                |
-| Add PostgreSQL data, schema, or access rules | `content/server-database.mdx`, `content/security.md`, `content/sharing.md`                         |
-| Keep the UI and agent in sync         | `content/context-awareness.md`, `content/client.md`                                                      |
-| Localize UI copy and language choices | `content/internationalization.md`, `content/client.md`                                                   |
-| Build headless or chat-first apps     | `content/pure-agent-apps.md`, `content/agent-surfaces.md`, `content/using-your-agent.md`                 |
-| Add automations or scheduled work     | `content/automations.md`, `content/recurring-jobs.md`                                                    |
-| Compose apps or call sibling agents   | `content/a2a-protocol.md`, `content/multi-app-workspace.md`, `content/agent-resources.mdx`               |
-| Expose tools to external agents       | `content/external-agents.md`, `content/mcp-protocol.md`, `content/mcp-apps.md`, `content/mcp-clients.md` |
-| Add integrations, setup, or secrets   | `content/onboarding.md`, `content/workspace-connections.md`, `content/security.md`                       |
-| Build extensions or custom widgets    | `content/extensions.md`, `content/agent-web-surfaces.md`                                                 |
-| Deploy or configure hosting           | `content/deployment.md`, `content/server-overview.md`                                                    |
-| Write agent instructions or skills    | `content/skills-guide.md`, `content/writing-agent-instructions.md`                                       |
-| Plan a breaking package API change    | `migrations/README.md`                                                                                  |
-| Migrate the Core chat API to AgentKit | `migrations/agentkit-chat.md`, `content/native-chat-ui.mdx`                                               |
+| Task                                         | Start with                                                                                                   |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Define or call app operations                | `content/actions-overview.mdx`, `content/client-overview.mdx`                                                |
+| Add PostgreSQL data, schema, or access rules | `content/server-database.mdx`, `content/security.mdx`, `content/sharing.mdx`                                 |
+| Keep the UI and agent in sync                | `content/context-awareness.mdx`, `content/client-overview.mdx`                                               |
+| Localize UI copy and language choices        | `content/internationalization.mdx`, `content/client-overview.mdx`                                            |
+| Build headless or chat-first apps            | `content/pure-agent-apps.mdx`, `content/agent-surfaces.mdx`, `content/using-your-agent.mdx`                  |
+| Add automations or scheduled work            | `content/automations.mdx`, `content/recurring-jobs.mdx`                                                      |
+| Compose apps or call sibling agents          | `content/a2a-protocol.mdx`, `content/multi-app-workspace.mdx`, `content/agent-resources.mdx`                 |
+| Expose tools to external agents              | `content/external-agents.mdx`, `content/mcp-protocol.mdx`, `content/mcp-apps.mdx`, `content/mcp-clients.mdx` |
+| Add integrations, setup, or secrets          | `content/onboarding.mdx`, `content/workspace-connections.mdx`, `content/security.mdx`                        |
+| Build extensions or custom widgets           | `content/extensions.mdx`, `content/agent-web-surfaces.mdx`                                                   |
+| Deploy or configure hosting                  | `content/deployment.mdx`, `content/server-overview.mdx`                                                      |
+| Write agent instructions or skills           | `content/skills-guide.mdx`, `content/writing-agent-instructions.mdx`                                         |
+| Plan a breaking package API change           | `migrations/README.md`                                                                                       |
+| Migrate the Core chat API to AgentKit        | `migrations/agentkit-chat.md`, `content/native-chat-ui.mdx`                                                  |
 
 ## Rules
 

package/docs/content/create-with-an-agent.mdx

@@ -36,10 +36,14 @@ it. Use that name wherever a step below says APP_NAME.
 4. Read APP_NAME/AGENTS.md so you know how the app is laid out.
 5. Start the app with `pnpm dev --no-open` and keep it running in the background.
 6. Read the local URL that `pnpm dev` prints. Check that it responds,
-   for example with `curl -I <url>`. Do not open a browser and do not
-   use headless browser tools. I will open the app myself.
-7. Show me the result. Give me the local URL and the response you got
-   from it. Do not just say that setup is complete.
+   with `curl "<url>/_agent-native/ping?configuration=1"`. The reply
+   should include `"message":"pong"` and a configuration status of
+   `"ok"`. Do not open a browser and do not use headless browser
+   tools. I will open the app myself.
+7. In the APP_NAME folder, run `pnpm action hello`. It runs the
+   app's sample action and should print "Hello, world!".
+8. Show me the result. Give me the local URL and what both checks
+   printed. Do not just say that setup is complete.
 
 Rules:
 
@@ -57,6 +61,8 @@ A good run ends with these results, and you can check each one yourself:
 - A new app folder, named `my-app` unless you changed it, that contains `actions/`, `app/`, and an `AGENTS.md` file.
 - `pnpm dev` running without errors.
 - A local URL, usually `http://localhost:8080`, that the agent has checked responds.
+- A reply from `<url>/_agent-native/ping?configuration=1` with a configuration status of `ok`.
+- `pnpm action hello` printing "Hello, world!".
 
 Then open the local URL in your own browser. On the Welcome screen, choose **Continue as local dev**. The Get started page appears.
 

package/docs/content/durable-resume.mdx

@@ -83,7 +83,7 @@ When a run resumes (soft timeout, gateway timeout, or any resumable transport er
 - which tool calls **already completed** (with short results) so it reuses them and does **not** re-run them, and
 - which tool calls were **interrupted with unknown outcome** so it verifies state before assuming success or failure.
 
-When the journal is empty (a turn with no tool activity, or a clean continuation), nothing extra is appended and resume behavior is byte-for-byte what it was before. The note is best-effort: a failed ledger read never blocks a recovery that would otherwise succeed.
+When the journal is empty (a turn with no tool activity, or a clean continuation), nothing extra is appended and resume behavior is byte-for-byte what it was before. The journal itself is required, though: if the ledger can't be read, even after one retry, the resumed run stops before the model runs, with `tool_call_journal_unreadable`, and asks you to send the request again. Without the ledger it can't tell which steps already finished.
 
 ## Layer 2: tool-layer hard-block {#hard-block}
 
@@ -103,13 +103,22 @@ Key properties:
 The hard-block stops only an **exact repeat**: the same write tool with the same input, after an earlier attempt in the same turn finished and recorded its result. It does not rule out every duplicate email, charge, or ticket:
 
 - **A reworded retry isn't matched.** If the model changes any argument, such as the email body, the call no longer matches a completed call, so the hard-block doesn't stop it.
-- **A crash mid-send can repeat.** If the process dies after the side effect lands but before its result is recorded, the call counts as interrupted, and the hard-block covers only completed calls. A separate guard refuses an identical retry of an interrupted write, but only when the resumed run's history shows the interruption.
+- **After a crash mid-send, a repeat is held back only for the rest of the turn.** If the process dies after the side effect lands but before its result is recorded, the call counts as interrupted, and the hard-block covers only completed calls. The resumed run holds back that write tool instead, as [Writes with an unknown outcome](#unknown-outcome) describes. A new message starts a new turn, where nothing holds it back.
 - **A crashed run can resume in the same turn through either of two separate paths.** One is a [durable background run](/docs/durable-background-runs). The other is a later chunk of a normal foreground turn using the [foreground self-chain](/docs/durable-background-runs#foreground-self-chain). Any other crashed run ends with an error. Choosing **Continue** on it resumes the same turn, so both layers apply.
 
 An action whose side effect must never repeat needs its own idempotency check. The hard-block never applies to read-only actions.
 
 </Callout>
 
+## Writes with an unknown outcome {#unknown-outcome}
+
+A write's outcome is unknown when it started but no result was recorded, when it timed out, or when it failed after it began writing without saying whether anything was saved. Running it again could apply the change twice, so for the rest of the turn the loop holds back that tool:
+
+- **The same call again.** If the model repeats the call with the same arguments, the loop first checks whether that call's own result was recorded after all, and returns it if so. Otherwise the call doesn't run: the run stops with `write_tool_outcome_unknown` and asks you to check what was saved, then reply "continue".
+- **Any other call to that tool.** A call with different arguments, such as a reworded email, doesn't run either. The model is told that the earlier call may already have applied, and to check the current state with a read and tell you what it found. The turn goes on, unless the earlier call can't be identified because it recorded no arguments to compare or was left out of the replayed history. Then any call to that tool could be a repeat, so it stops the run the way the same call does.
+
+An action marked `retrySafe` is exempt, because running it again can't duplicate or corrupt data: it validates before it writes, or it sets an end state, such as replacing a record by ID. The model can correct its arguments and try again. Read-only actions aren't held back unless a write ran inside one.
+
 ## Automatic continuation after a time limit {#auto-continue}
 
 When the server stops a turn at its run time limit and nothing server-side picks it up, the chat continues it on its own, in the **same turn**. The resumed run gets the thread's tool calls and results plus the journal note above, so finished steps are reused, and an identical repeat of a write — including a cross-app `call-agent` delegation, whose idempotency key is derived from the turn — returns the recorded result instead of being sent again. The chat shows a _Resuming_ status, and Stop keeps working.

package/docs/content/toolkit-comments-review.mdx

@@ -75,6 +75,58 @@ If the resource is already registered with the Sharing Kit, the review actions
 reuse that access model. Add a review registration when the app needs a custom
 access resolver or wants to make the resource type explicit in setup code.
 
+## App Rules {#app-rules}
+
+A registration can also set how comments behave on its resource:
+
+```ts
+registerReviewableResource({
+  type: "deck",
+  comments: { minimumRole: "viewer", unmentionedRoute: "human" },
+  anchorKinds: {
+    "slide-point": { version: 2, parse: parseSlidePoint },
+  },
+  async onCommentWrite(event, tx) {
+    await tx.execute(/* keep the deck's comment count in step */);
+  },
+});
+```
+
+- `comments.minimumRole` is the lowest role that may comment, reply, react and
+  edit or delete their own comments (default `commenter`). Suggesting needs it
+  too, and never less than `commenter`.
+  `comments.unmentionedRoute` sends a new thread with no mention to the agent
+  (the default) or to people.
+- `anchorKinds` types the anchor. Once a resource declares any, every anchored
+  comment names its `anchorKind`, and `parse(anchor, version)` checks it and
+  returns what's stored, so an older version can be read forward. A comment is
+  written at the kind's current `version` unless it gives an older one. A
+  suggestion's thread uses the kit's own `review-suggestion` kind, which
+  every resource accepts and only the kit writes: the comment actions refuse
+  it.
+- `onCommentWrite` runs inside the comment's own database transaction for
+  `created`, `edited`, `anchor-moved`, `resolved`, `reopened` and `deleted`.
+  Resolving a thread that is already resolved, or reopening an open one,
+  fires no event, though a new resolution note is still saved. Throwing
+  refuses the write. Use the `tx` handle for database work there. A database
+  client without transactions refuses a hooked write.
+
+Every comment also carries a `surfaceId` (the slide, page or screen a thread
+sits on; `list-review-comments` filters by it) and a `revision` that goes up
+when it changes, including a thread's routing on its first comment. Pass the
+revision you read as `expectedRevision` to
+`update-review-comment` or `update-review-comment-anchor`, and a newer one
+refuses the write with `revision_conflict`. `list-review-comments` pages oldest
+first: pass back its `nextCursor` as `cursor` to read past the `limit` of 500.
+A cursor resumes only the list it came from, at any `limit`; with another
+resource or filter it's refused with `invalid_cursor`. A newest-first list isn't
+paged and returns no `nextCursor`.
+
+`linkReviewComment()` ties a comment to an ID in another system, such as a
+Notion discussion, so an import skips what it already copied.
+`findReviewCommentLink()` and `listReviewCommentLinks()` read those links back.
+An ID links to one comment, and a link outlives the comment's deletion.
+
 ## UI Usage {#ui-usage}
 
 ```tsx
@@ -96,7 +148,8 @@ export function DocumentReview({ documentId }: { documentId: string }) {
 
 The `anchor` field is intentionally `unknown`: editors, canvases, diagrams, and
 documents can store the shape they need while still using the shared review
-actions and thread UI.
+actions and thread UI. Declare [anchor kinds](#app-rules) to have the kit check
+that shape for you.
 
 ## UX Standard {#ux-standard}