@agent-native/core 0.72.4 → 0.74.0

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 1160
-- template files: 4012
+- template files: 4025

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @agent-native/core
 
+## 0.74.0
+
+### Minor Changes
+
+- 4a0d3c4: Durable background agent runs are robust again, and **on by default** for hosted apps.
+  - **Graceful inline fallback (the safety fix).** When the foreground turn can't
+    hand off to a background worker — the HMAC self-dispatch self-POST fails fast,
+    e.g. a connection error or a non-2xx returned within the settle window — the
+    agent-chat handler no longer breaks the chat with
+    `Failed to dispatch background run`. It now degrades to a normal synchronous
+    (inline) run, reusing the already-inserted run row. The run is claimed
+    atomically (`claimBackgroundRun`, a conditional `dispatch_mode: background →
+background-processing` UPDATE) before running inline, so the SQL atomic claim
+    is the single owner — a delayed background delivery that arrives afterward
+    loses the claim and no-ops, and the run can never double-execute. A dispatch
+    that _did_ land (so a worker already owns the run) still streams the worker's
+    events instead of running a second copy.
+  - **Default-on, safely.** `AGENT_CHAT_DURABLE_BACKGROUND` is now opt-out for
+    hosted apps: unset/empty/unknown counts as enabled; opt a specific app back
+    out with an explicit falsy value (`false`/`0`/`no`/`off`). The gate still
+    composes with the existing guards, so a run only goes durable when the runtime
+    is hosted/serverless **and** `A2A_SECRET` is configured — local dev and
+    unconfigured apps stay on the synchronous inline path unchanged. Default-on is
+    safe precisely because a failed dispatch degrades to a working inline run. The
+    Netlify 15-min `-background` function emit (`isDurableBackgroundDeployEnabled`)
+    remains opt-in until its path is separately verified; with it off, the
+    default-on baseline runs the worker through the standard function and
+    server-chains continuations.
+  - **More diagnosable dispatch errors.** Self-dispatch failures now log the
+    resolved base URL so a failure tied to which host the self-POST targets
+    (custom domain vs deploy URL) is visible in logs. The URL resolution order is
+    unchanged (it matches the working A2A/agent-teams self-dispatch paths).
+
+### Patch Changes
+
+- 4a0d3c4: Show numbered annotation markers in the annotated-code gutter, matching the diff
+  annotation affordance while preserving the hover popover behavior.
+- 4a0d3c4: Clarify Builder code-change handoff fallbacks when cloud agents are unavailable.
+
+## 0.73.0
+
+### Minor Changes
+
+- d684bbf: Durable background agent runs are now **on by default** for hosted apps. Previously the `AGENT_CHAT_DURABLE_BACKGROUND` flag was opt-in (off unless set truthy); it is now opt-out — unset means enabled, and an app disables it with an explicit falsy value (`AGENT_CHAT_DURABLE_BACKGROUND=false`).
+
+  The gate still composes with the existing guards, so a run only goes durable when the runtime is hosted/serverless **and** `A2A_SECRET` is configured — local dev and unconfigured apps stay on the synchronous inline path unchanged. Default-on uses the server-driven agnostic continuation path (verified in prod: long multi-step runs complete past the 40s soft-timeout with no thrash and no int4 overflow). The Netlify 15-min `-background` function emit (`isDurableBackgroundDeployEnabled`) remains opt-in until its path is separately verified.
+
+### Patch Changes
+
+- d684bbf: Clarify the Clips "agent-readable clips" docs so the "see and hear" promise is
+  accurate: frame-viewing works in any image-capable agent (ChatGPT, Claude Code,
+  Cursor, Codex, MCP-connected agents), while text-only web chats fall back to the
+  transcript and can take an uploaded frame. Verified empirically — ChatGPT fetches
+  the JPEG frame URLs and describes the screen; claude.ai's web chat reads the
+  transcript only. Docs-only copy change; the agent-context/frame APIs are
+  unchanged.
+- d684bbf: Add scaffold skill refresh commands for generated Agent Native apps and workspaces, plus public `@agent-native/skills` status/update forwarding.
+- d684bbf: Redesign the Google sign-in preflight notice on the onboarding/sign-in screen
+  to match the in-app connect popover: an amber warning-icon chip beside a bold
+  heading and muted body copy, with the close affordance moved to the top-right.
+  The `googleSignInNotice.body` already accepts a string array, so reassurance
+  like "It's safe to continue." now renders on its own line. The Continue /
+  Run-locally action buttons no longer wrap their labels (`white-space: nowrap`).
+  Purely presentational — the host-gating, Continue, and Run-locally behaviors are
+  unchanged.
+- d684bbf: Add a secondary hosted-app signup notice linking to the Agent-Native Terms and Privacy Policy.
+
 ## 0.72.4
 
 ### Patch Changes

package/corpus/core/docs/content/skills-guide.md

@@ -264,3 +264,17 @@ npx @agent-native/core@latest skills update visual-plan
 the copied folder hash to the latest bundled skill, and rewrites stale folders in
 place. Newly copied Agent Native skills include an `agent-native-skill.json`
 marker so future status output can identify the source and hash.
+
+Generated Agent Native apps and workspaces also include framework-provided
+skills under `.agents/skills` (or `packages/shared/.agents/skills` in a
+workspace). Refresh those scaffolded skills from the current/latest CLI with:
+
+```bash
+npm run skills:update
+# or, without relying on the local package script:
+npx @agent-native/core@latest skills update scaffold --project
+```
+
+`AGENTS.md` and `.agents/skills` stay canonical. The update command also repairs
+Claude compatibility links (`CLAUDE.md` and `.claude/skills`) so Claude Code sees
+the same instructions without maintaining a second copy.

package/corpus/core/docs/content/template-clips.md

@@ -15,7 +15,7 @@ A capture-everything app: screen recordings, meeting notes from your calendar, a
 }
 ```
 
-Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's. Clips also makes shared recordings agent-readable: paste a normal Clips share link into an agent, and it can "hear" the transcript and "see" timestamped frames even when the underlying model cannot ingest raw video or audio.
+Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's. Clips also makes shared recordings agent-readable: paste a normal Clips share link into an agent and it can "hear" the transcript as text and "see" timestamped screen frames as images — no raw video needed. Frame-viewing works in any image-capable agent (ChatGPT, Claude Code, Cursor, Codex); text-only web chats still get the full transcript and can take a frame you upload.
 
 ```an-diagram title="Capture, transcribe, reuse" summary="Three capture types land in one library; the agent transcribes, titles, and summarizes, then every transcript is searchable and shareable."
 {
@@ -69,6 +69,12 @@ a compact agent context URL, and that context points to the transcript and frame
 APIs, so models that only accept text or still images can still understand what
 happened in the recording.
 
+Any agent that can fetch an image URL into its vision — ChatGPT, Claude Code,
+Cursor, Codex, and MCP-connected agents — reads the transcript and sees the
+frames. A few text-only web chats read the transcript but won't pull frame images
+in on their own; there, upload a key frame or open the clip in an image-capable
+agent.
+
 | Endpoint                                          | What agents get                                                                                                |
 | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `/api/agent-context.json?id=<recordingId>`        | Clip metadata, transcript status, chapters, CTAs, recommended frames, and links to the transcript/frame APIs   |

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.72.4",
+  "version": "0.74.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/corpus/core/src/agent/durable-background.ts

@@ -17,12 +17,22 @@
  *
  * GUARDRAIL: when `isAgentChatDurableBackgroundEnabled()` returns false, the
  * agent-chat handler must behave byte-for-byte like the current synchronous
- * path. The flag is only ever true when ALL of these hold:
- *   1. `AGENT_CHAT_DURABLE_BACKGROUND` env is a truthy value.
+ * path. The gate is true only when ALL of these hold:
+ *   1. `AGENT_CHAT_DURABLE_BACKGROUND` env is not explicitly disabled. It is
+ *      DEFAULT-ON: unset/empty/unknown counts as enabled; set it to a falsy
+ *      value (`false`/`0`/`no`/`off`) to opt a specific app back out.
  *   2. The runtime is hosted/serverless (local dev keeps the inline path so SSE
  *      stays a single live stream and no second function is needed).
  *   3. `A2A_SECRET` is configured (the HMAC handoff is required to authenticate
  *      the background dispatch; without it the dispatch can't be trusted).
+ *
+ * Default-on is safe because a *dispatch failure degrades to an inline run*: if
+ * the self-dispatch self-POST can't be delivered (fast connection error or
+ * fast non-2xx), the foreground handler runs the turn synchronously instead of
+ * erroring (see `production-agent.ts` — the inline fallback claims the run row
+ * atomically so a delayed delivery can never double-execute). So an app where
+ * durable dispatch happens to fail still gets a working chat, just without the
+ * 15-min budget.
  */
 import {
   hasConfiguredA2ASecret,
@@ -41,7 +51,10 @@ import {
 export const AGENT_CHAT_PROCESS_RUN_PATH =
   "/_agent-native/agent-chat/_process-run";
 
-/** Env flag (off by default) that opts an app into durable background runs. */
+/**
+ * Env flag for durable background runs. DEFAULT-ON: unset means enabled; an app
+ * opts OUT with an explicit falsy value (`false`/`0`/`no`/`off`).
+ */
 export const AGENT_CHAT_DURABLE_BACKGROUND_ENV =
   "AGENT_CHAT_DURABLE_BACKGROUND";
 
@@ -87,21 +100,31 @@ function isFlagEnabled(): boolean {
   // Read the literal key (not `process.env[CONST]`) so guard:no-env-credentials
   // can statically verify it against the allowlisted `AGENT_*` prefix. Keep this
   // in sync with AGENT_CHAT_DURABLE_BACKGROUND_ENV.
+  //
+  // DEFAULT-ON: durable background runs are the desired behavior for every
+  // hosted app. So an unset/empty/unknown flag means ON; an app opts OUT only
+  // with an explicit falsy value. This still composes with the hosted +
+  // A2A_SECRET gates below, so non-hosted / unconfigured apps stay synchronous.
+  // Safety net: a failed dispatch degrades to a synchronous inline run (see
+  // production-agent.ts), so default-on cannot break chat even if the
+  // self-dispatch can't be delivered on a given app.
   const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
-  if (raw == null) return false;
+  if (raw == null) return true;
   const normalized = raw.trim().toLowerCase();
-  return (
-    normalized === "1" ||
-    normalized === "true" ||
-    normalized === "yes" ||
-    normalized === "on"
+  return !(
+    normalized === "0" ||
+    normalized === "false" ||
+    normalized === "no" ||
+    normalized === "off"
   );
 }
 
 /**
- * The single gate. True only when the flag is on AND the runtime is hosted AND
- * A2A_SECRET is configured. False otherwise — and false means the current
- * synchronous behavior is used, unchanged.
+ * The single gate. True when the flag is not explicitly disabled (default-on)
+ * AND the runtime is hosted AND A2A_SECRET is configured. False otherwise — and
+ * false means the current synchronous behavior is used, unchanged. So a local /
+ * non-hosted / unconfigured app stays synchronous even with the flag defaulting
+ * on; durable only engages where the runtime actually supports it.
  */
 export function isAgentChatDurableBackgroundEnabled(): boolean {
   return (

package/corpus/core/src/agent/production-agent.ts

@@ -4363,6 +4363,7 @@ export function createProductionAgentHandler(
     // change. With the flag OFF this whole branch is skipped and the inline
     // `startRun` path below runs exactly as before (byte-for-byte).
     if (dispatchToBackground) {
+      let backgroundRowInserted = false;
       try {
         // Insert the run row up front so /runs/active sees it immediately and
         // the slot stays held while the background function cold-starts. Mark
@@ -4370,6 +4371,7 @@ export function createProductionAgentHandler(
         await insertRun(runId, effectiveThreadId, effectiveTurnId, {
           dispatchMode: "background",
         });
+        backgroundRowInserted = true;
       } catch (err) {
         // A duplicate-PK collision means the row already exists (ret­ried POST);
         // any other failure means we can't safely hand off — fall back to the
@@ -4418,14 +4420,59 @@ export function createProductionAgentHandler(
         setResponseStatus(event, 500);
         return { error: "Failed to subscribe to background run" };
       }
-      // Dispatch failed before any worker could claim the run. Fail loud: flip
-      // the row terminal so the held slot is released (and any reconnect sees a
-      // terminal status instead of spinning), then 500 so the client can retry.
-      // We do NOT silently fall through to inline here — that risks a later,
-      // delayed background delivery double-executing the same runId.
-      await updateRunStatusIfRunning(runId, "errored").catch(() => {});
-      setResponseStatus(event, 500);
-      return { error: "Failed to dispatch background run" };
+
+      // ─── Dispatch failed → degrade to a normal synchronous (inline) run ────
+      // `fireInternalDispatch` throws ONLY when the self-POST failed *fast*
+      // (rejected the connection, or returned a non-2xx within the ~250ms settle
+      // race). The `_process-run` route verifies the HMAC token and validates
+      // the body BEFORE it ever reaches the SQL atomic claim, so a fast throw
+      // means NO background worker claimed this run — there is nothing to
+      // double-execute. Rather than break the chat with "Failed to dispatch
+      // background run", we run the turn inline (the same synchronous path the
+      // flag-off branch below takes), reusing the already-inserted run row.
+      //
+      // Safety against a (very improbable) delayed background delivery: claim the
+      // run atomically here via `claimBackgroundRun`, which flips the row's
+      // dispatch_mode `background → background-processing` in one conditional
+      // UPDATE. If a delayed dispatch DID land and a worker already won the
+      // claim, our claim returns false and we must NOT run inline (that would
+      // double-execute) — fall back to subscribing to the worker's run instead.
+      // The SQL atomic claim is the single source of truth for ownership, so at
+      // most one of {inline fallback, background worker} ever executes this run.
+      if (backgroundRowInserted) {
+        let claimedInline = false;
+        try {
+          claimedInline = await claimBackgroundRun(runId);
+        } catch (err) {
+          console.error(
+            "[agent-chat] inline-fallback claim failed:",
+            err instanceof Error ? err.message : err,
+          );
+        }
+        if (!claimedInline) {
+          // A background worker already owns this run (a delayed delivery landed
+          // after our fast throw). Stream its events instead of running a second
+          // copy. If we somehow can't subscribe, surface an error rather than
+          // risk a double-run.
+          const stream = subscribeToRun(runId, 0);
+          if (stream) {
+            setResponseHeader(event, "Content-Type", "text/event-stream");
+            setResponseHeader(event, "Cache-Control", "no-cache");
+            setResponseHeader(event, "Connection", "keep-alive");
+            setResponseHeader(event, "X-Run-Id", runId);
+            return stream;
+          }
+          await updateRunStatusIfRunning(runId, "errored").catch(() => {});
+          setResponseStatus(event, 500);
+          return { error: "Failed to dispatch background run" };
+        }
+        // We own the run. `startRun` (below) calls `insertRun` again, but its
+        // duplicate-PK collision is swallowed (`insertRun(...).catch(() => {})`),
+        // so the existing `background-processing` row is reused — no double row.
+      }
+      // Fall through to the inline `startRun` path below (the same one the
+      // flag-off branch uses). If the row was never inserted, `startRun` inserts
+      // it fresh; if it was, the claim above made us the sole owner.
     }
 
     const trackedProgressOwner =

package/corpus/core/src/cli/create.ts

@@ -1893,7 +1893,7 @@ function copyDir(src: string, dest: string, root?: string): void {
 
 function shouldSkipScaffoldEntry(name: string, srcPath?: string): boolean {
   if (
-    name === "settings.json" &&
+    /^settings(?:\..*)?\.json$/.test(name) &&
     srcPath?.split(path.sep).includes(".claude")
   ) {
     return true;