@agent-native/core 0.121.2 → 0.122.0

package/corpus/core/docs/content/syncing-template-changes.mdx

@@ -0,0 +1,159 @@
+---
+title: "Syncing Template Changes"
+description: "agent-native template pulls later upstream first-party template changes into an app that was generated from a template, using a real per-file three-way merge against a pristine baseline."
+---
+
+# Syncing Template Changes
+
+`agent-native create` copies a first-party template into your app and then makes it yours — substituting the app name, renaming `_gitignore`, rewriting `package.json`, pinning `workspace:*` and `catalog:` dependencies to concrete versions, and (in a workspace) swapping in inherited auth and chat plugins. From that moment the app is a fork. Fixes and improvements that land in the template upstream do not reach it.
+
+`agent-native upgrade` does not close that gap. It moves package versions, runs import codemods, and refreshes skill directories — it never touches a file that was copied out of a template.
+
+`agent-native template` is the missing half. It re-fetches the template at a newer version, re-applies the exact transforms `create` applied, and merges the result into your app file by file.
+
+## Quick start {#quick-start}
+
+```bash
+agent-native upgrade
+agent-native template sync
+```
+
+`sync` defaults to the template version matching your installed `@agent-native/core`, so running it after `upgrade` keeps code and packages on the same version.
+
+Look before you merge:
+
+```bash
+agent-native template status
+agent-native template diff
+```
+
+## How the merge works {#how-the-merge-works}
+
+A useful merge needs three trees, not two:
+
+- **base** — the pristine template as it was when your app was generated.
+- **theirs** — the same template at the version you are syncing to, put through the same transform pipeline.
+- **ours** — your app as it stands now.
+
+With those, every file falls into a clear case. Upstream did not touch it, so it is left alone. You never touched it, so it fast-forwards. Both of you changed it, so it gets conflict markers. Nothing is overwritten just because it differs.
+
+Without a base, "sync" can only mean overwrite, which silently discards your work or reverts upstream's.
+
+## The baseline {#the-baseline}
+
+The base tree is stored as a git ref in your own repo:
+
+```txt
+refs/agent-native/template-baseline/apps/slides
+```
+
+It is written with git plumbing against a throwaway index file. Your `HEAD`, your branch, your index, and your working tree are never touched — running `template baseline` mid-edit is safe, and `git status` reads identically before and after.
+
+On first write, the fetch and push refspecs for `refs/agent-native/*` are added to your remote so the baseline survives a clone. If the app is not in a git repo, the baseline falls back to a tarball under `.agent-native/`.
+
+Apps generated before provenance existed have no baseline. Create one, then sync:
+
+```bash
+agent-native template baseline
+agent-native template sync
+```
+
+## Provenance {#provenance}
+
+`create` records what a later merge needs in the app's `package.json`:
+
+```json
+{
+  "agent-native": {
+    "scaffold": {
+      "template": "slides",
+      "frameworkSkills": "default",
+      "templateRef": "@agent-native/core@0.120.3",
+      "templateSource": "github",
+      "coreVersion": "0.120.3",
+      "shape": "workspace"
+    }
+  }
+}
+```
+
+`templateRef` is the immutable tag the template was actually fetched from, which is what makes the base reproducible. `shape` decides whether the workspace transforms are replayed during materialization.
+
+## Commands {#commands}
+
+### status {#status}
+
+```bash
+agent-native template status [app]
+```
+
+Reports the recorded ref, the latest available ref, whether a baseline exists, how many files upstream changed, and how many you have modified locally.
+
+### diff {#diff}
+
+```bash
+agent-native template diff [app] [--to <ref>]
+```
+
+A read-only unified diff of what changed upstream between your baseline and the target. Writes nothing.
+
+### sync {#sync}
+
+```bash
+agent-native template sync [app] [--to <ref>] [--dry-run] [--force]
+```
+
+Performs the merge. `--to` defaults to the ref matching the installed core. `--dry-run` prints the plan without writing.
+
+`sync` refuses to run when the app directory has uncommitted changes, so a bad merge is always recoverable with `git checkout`. `--force` overrides this; prefer committing first.
+
+When the merge is clean, the baseline advances automatically. When there are conflicts it deliberately does not — see `accept`.
+
+### accept {#accept}
+
+```bash
+agent-native template accept [app]
+```
+
+Advances the baseline after you resolve conflict markers. It refuses while any `<<<<<<<` remains, so the baseline can never move past an unresolved merge and quietly bake conflict markers into your next base.
+
+### baseline {#baseline}
+
+```bash
+agent-native template baseline [app] [--ref <ref>] [--template <name>]
+```
+
+Records a baseline for an app that predates scaffold provenance. Pass `--ref` when you know which version the app actually came from; the closer it is to the truth, the fewer phantom conflicts the first sync produces.
+
+## What is never merged {#what-is-never-merged}
+
+Some files are yours by definition, and some cannot be merged meaningfully:
+
+- Secrets and local config: `.env`, `.env.local`
+- Lockfiles: `pnpm-lock.yaml`
+- Generated output: `node_modules`, `.output`, `.react-router`, `dist`, `build`
+- App-owned content: `learnings.md`, pending entries under `changelog/`
+
+Binary files are never marker-merged. If both sides changed one, your copy is kept and the file is reported for manual handling. Symlinks are reported rather than clobbered.
+
+## Contributing changes back {#contributing-changes-back}
+
+Syncing is one-directional by design: upstream is the source of truth for template content, and the transforms `create` applies are not perfectly reversible. Recovering `{{APP_NAME}}` from a concrete app name is a guess, and files that `create` rewrote wholesale — `package.json`, `netlify.toml`, `app/root.tsx`, `server/plugins/auth.ts` — have no faithful inverse at all.
+
+If you are working inside the framework monorepo and want to push an app-side improvement back into a template, the `contribute:template` script does the reverse pass with those limits made explicit:
+
+```bash
+pnpm contribute:template --app <path-to-app> --dry-run
+```
+
+It diffs your app against its baseline so only your own changes are candidates, inverts the placeholder substitution on just those files, three-way merges them into `templates/<name>/` as unstaged edits on the current branch, and prints everything it refused to touch so you can port the intent by hand.
+
+## Relationship to other commands {#relationship-to-other-commands}
+
+| Command                      | Moves                                                          |
+| ---------------------------- | -------------------------------------------------------------- |
+| `agent-native upgrade`       | `@agent-native/*` package versions, imports, skill directories |
+| `agent-native template sync` | files copied out of a template at scaffold time                |
+| `agent-native eject`         | a framework component into app-owned source, with provenance   |
+
+`upgrade` and `template sync` are complementary and safe to run together. `eject` is the opposite move — it takes ownership of a file deliberately, and ejected files are tracked separately in `agent-native.ejections.json`.

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.121.2",
+  "version": "0.122.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -139,6 +139,7 @@
     "./client/AgentPanel": "./dist/client/AgentPanel.js",
     "./client/application-state": "./dist/client/application-state.js",
     "./client/api-path": "./dist/client/api-path.js",
+    "./client/clipboard": "./dist/client/clipboard.js",
     "./client/route-state": "./dist/client/route-state.js",
     "./client/observability": "./dist/client/observability/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",

package/corpus/core/src/a2a/activity.ts

@@ -37,6 +37,9 @@ export interface A2AAgentActivitySnapshot extends Record<string, unknown> {
   activePhase: A2AAgentActivityPhase;
   reasoning: string[];
   toolCalls: A2AAgentActivityToolCall[];
+  /** Response text segments, indexed by how many tool calls preceded them. */
+  response?: string[];
+  /** Tail segment only. Kept so peers predating `response` still render. */
   responseText?: string;
 }
 
@@ -47,7 +50,7 @@ export interface A2AAgentActivityState {
   activePhase: A2AAgentActivityPhase;
   reasoning: string[];
   toolCalls: A2AAgentActivityToolCall[];
-  responseText: string;
+  response: string[];
 }
 
 export function createA2AAgentActivityState(
@@ -60,7 +63,7 @@ export function createA2AAgentActivityState(
     activePhase: "reasoning",
     reasoning: [],
     toolCalls: [],
-    responseText: "",
+    response: [],
   };
 }
 
@@ -90,7 +93,6 @@ export function applyA2AAgentActivityEvent(
       break;
     case "tool_start":
       next.activePhase = "tool";
-      next.responseText = "";
       next.toolCalls = appendToolCall(next.toolCalls, toolFromEvent(event));
       changed = true;
       break;
@@ -101,10 +103,11 @@ export function applyA2AAgentActivityEvent(
       break;
     case "text":
       next.activePhase = "responding";
-      next.responseText = appendBoundedText(
-        next.responseText,
+      next.response = appendBoundedSegment(
+        next.response,
         event.text,
         MAX_A2A_ACTIVITY_RESPONSE_CHARS,
+        next.toolCalls.length,
       );
       changed = true;
       break;
@@ -117,7 +120,7 @@ export function applyA2AAgentActivityEvent(
       changed = true;
       break;
     case "clear":
-      next.responseText = "";
+      next.response = [];
       changed = true;
       break;
   }
@@ -138,10 +141,15 @@ export function buildA2AAgentActivitySnapshot(
     activePhase: state.activePhase,
     reasoning: state.reasoning,
     toolCalls: state.toolCalls,
-    ...(state.responseText ? { responseText: state.responseText } : {}),
+    ...(state.response.length ? { response: state.response } : {}),
+    ...(tailSegment(state) ? { responseText: tailSegment(state) } : {}),
   };
 }
 
+function tailSegment(state: A2AAgentActivityState): string {
+  return state.response[state.toolCalls.length] ?? "";
+}
+
 export function buildA2AAgentActivityPart(
   state: A2AAgentActivityState,
 ): DataPart {
@@ -165,8 +173,10 @@ export function parseA2AAgentActivityPart(
     !isPhase(data.activePhase) ||
     data.updatedAt < data.startedAt ||
     data.durationMs !== data.updatedAt - data.startedAt ||
-    !isSafeReasoning(data.reasoning) ||
+    !isSafeSegments(data.reasoning, MAX_A2A_ACTIVITY_REASONING_CHARS) ||
     !isSafeToolCalls(data.toolCalls) ||
+    (data.response !== undefined &&
+      !isSafeSegments(data.response, MAX_A2A_ACTIVITY_RESPONSE_CHARS)) ||
     (data.responseText !== undefined &&
       !isSafeText(data.responseText, MAX_A2A_ACTIVITY_RESPONSE_CHARS)) ||
     activityCharacterCount(data) > MAX_A2A_ACTIVITY_TOTAL_CHARS
@@ -193,14 +203,6 @@ function toolFromEvent(
   };
 }
 
-function appendBoundedText(
-  current: string,
-  addition: string,
-  maxChars: number,
-) {
-  return sanitizeText(`${current}${addition}`, maxChars);
-}
-
 function appendBoundedSegment(
   current: string[],
   addition: string,
@@ -293,7 +295,7 @@ function isPhase(value: unknown): value is A2AAgentActivityPhase {
   );
 }
 
-function isSafeReasoning(value: unknown): value is string[] {
+function isSafeSegments(value: unknown, maxChars: number): value is string[] {
   return (
     Array.isArray(value) &&
     value.length <= MAX_A2A_ACTIVITY_REASONING_SEGMENTS &&
@@ -301,8 +303,8 @@ function isSafeReasoning(value: unknown): value is string[] {
       (total, text) =>
         total + (typeof text === "string" ? text.length : Infinity),
       0,
-    ) <= MAX_A2A_ACTIVITY_REASONING_CHARS &&
-    value.every((text) => isSafeText(text, MAX_A2A_ACTIVITY_REASONING_CHARS))
+    ) <= maxChars &&
+    value.every((text) => isSafeText(text, maxChars))
   );
 }
 
@@ -349,14 +351,14 @@ function isSafeToolId(value: unknown): value is string {
 }
 
 function activityCharacterCount(data: Record<string, unknown>): number {
-  const reasoning = Array.isArray(data.reasoning)
-    ? data.reasoning.reduce(
-        (total, text) => total + (typeof text === "string" ? text.length : 0),
-        0,
-      )
-    : 0;
-  const response =
-    typeof data.responseText === "string" ? data.responseText.length : 0;
+  const reasoning = segmentCharacterCount(data.reasoning);
+  // `responseText` duplicates the tail of `response`; counting both would
+  // reject a snapshot that is within budget.
+  const response = Array.isArray(data.response)
+    ? segmentCharacterCount(data.response)
+    : typeof data.responseText === "string"
+      ? data.responseText.length
+      : 0;
   const tools = Array.isArray(data.toolCalls)
     ? data.toolCalls.reduce((total, tool) => {
         if (!isRecord(tool)) return total;
@@ -369,3 +371,12 @@ function activityCharacterCount(data: Record<string, unknown>): number {
     : 0;
   return reasoning + response + tools;
 }
+
+function segmentCharacterCount(value: unknown): number {
+  return Array.isArray(value)
+    ? value.reduce(
+        (total, text) => total + (typeof text === "string" ? text.length : 0),
+        0,
+      )
+    : 0;
+}

package/corpus/core/src/agent/engine/builder-engine.ts

@@ -71,6 +71,8 @@ const MAX_BACKGROUND_BUILDER_GATEWAY_TIMEOUT_MS = 14 * 60_000;
 const MAX_LOCAL_BUILDER_GATEWAY_TIMEOUT_MS =
   MAX_BACKGROUND_BUILDER_GATEWAY_TIMEOUT_MS;
 const BUILDER_GATEWAY_NETWORK_ERROR_CODE = "builder_gateway_network_error";
+export const BUILDER_MODEL_UNAUTHORIZED_ERROR_CODE =
+  "builder_model_unauthorized";
 
 export const BUILDER_DEFAULT_MODEL = BUILDER_MODEL_CONFIG.defaultModel;
 
@@ -669,8 +671,16 @@ async function* parseJsonlStream(
               explicitErrMsg ??
               `Gateway error (no detail; raw event: ${JSON.stringify(event)})`;
             const gatewayErrCode = event.errorCode ?? event.code;
+            // The gateway already authenticated this request before streaming,
+            // so a bare "Unauthorized" here means the account cannot use this
+            // model — not that the connection is broken. Only a message that
+            // names the credential may tear down the Builder connection.
             const isCredentialAuthError =
               Boolean(explicitErrMsg) &&
+              isBuilderCredentialAuthErrorInStream(String(errMsg));
+            const isModelAuthError =
+              Boolean(explicitErrMsg) &&
+              !isCredentialAuthError &&
               isBuilderCredentialAuthError(String(errMsg));
             // Anthropic's bare "Connection error." often arrives here with no
             // gateway code. Tag it as a network error so in-run retries and
@@ -680,10 +690,12 @@ async function* parseJsonlStream(
               isProviderConnectionErrorMessage(String(explicitErrMsg));
             const errCode = isCredentialAuthError
               ? "builder_auth_error"
-              : isProviderConnectionError
-                ? BUILDER_GATEWAY_NETWORK_ERROR_CODE
-                : (gatewayErrCode ??
-                  (!explicitErrMsg ? "builder_gateway_error" : undefined));
+              : isModelAuthError
+                ? BUILDER_MODEL_UNAUTHORIZED_ERROR_CODE
+                : isProviderConnectionError
+                  ? BUILDER_GATEWAY_NETWORK_ERROR_CODE
+                  : (gatewayErrCode ??
+                    (!explicitErrMsg ? "builder_gateway_error" : undefined));
             console.error(
               `[builder-engine] stop reason=error model=${model} code=${errCode ?? "(none)"} error=${errMsg}`,
             );
@@ -988,6 +1000,25 @@ function isBuilderCredentialAuthError(message: string): boolean {
   );
 }
 
+/**
+ * Stricter than {@link isBuilderCredentialAuthError} for errors that arrive
+ * inside an already-authenticated stream, where a bare "unauthorized" is far
+ * more likely to be a per-model entitlement rejection than a bad credential.
+ * Misreading one there disconnects Builder for every model, including the ones
+ * that still work.
+ */
+function isBuilderCredentialAuthErrorInStream(message: string): boolean {
+  if (!isBuilderCredentialAuthError(message)) return false;
+  const lowerMessage = message.toLowerCase();
+  return (
+    lowerMessage.includes("private key") ||
+    lowerMessage.includes("access token") ||
+    lowerMessage.includes("invalid token") ||
+    lowerMessage.includes("invalid_token") ||
+    lowerMessage.includes("token invalid")
+  );
+}
+
 function normalizeBuilderGatewayFetchError(
   err: unknown,
   timedOut: boolean,

package/corpus/core/src/agent/run-manager.ts

@@ -29,6 +29,7 @@ import {
   setRunError,
   setRunTerminalReason,
 } from "./run-store.js";
+import { isContinuationTerminalReason } from "./types.js";
 import type { AgentChatEvent, RunEvent, RunStatus } from "./types.js";
 
 export interface ActiveRun {
@@ -1429,10 +1430,28 @@ function subscribeFromSQL(
                   return;
                 }
               } else if (run?.status === "completed") {
+                // A chunk boundary is also status "completed" (with a
+                // continuation terminal_reason, and a chained successor run
+                // already carrying the turn). Synthesizing `done` here told the
+                // client the agent stopped while it was still working, which
+                // surfaced as a premature "stopped without sending a final
+                // message". Prefer the run's REAL terminal event, then the
+                // terminal_reason, before falling back to `done`.
+                const existing = await getLastTerminalRunEvent(runId).catch(
+                  () => null,
+                );
+                const terminalEvent = existing
+                  ? existing.event
+                  : isContinuationTerminalReason(run.terminalReason)
+                    ? { type: "auto_continue", reason: run.terminalReason }
+                    : { type: "done" };
                 try {
                   controller.enqueue(
                     encoder.encode(
-                      `data: ${JSON.stringify({ type: "done", seq: lastSeq })}\n\n`,
+                      `data: ${JSON.stringify({
+                        ...terminalEvent,
+                        seq: existing?.seq ?? lastSeq,
+                      })}\n\n`,
                     ),
                   );
                 } catch {

package/corpus/core/src/agent/run-store.ts

@@ -1929,11 +1929,12 @@ export async function getRunById(runId: string): Promise<{
   startedAt: number;
   errorCode: string | null;
   errorDetail: string | null;
+  terminalReason: string | null;
 } | null> {
   await ensureRunTables();
   const client = getDbExec();
   const { rows } = await client.execute({
-    sql: `SELECT id, thread_id, status, started_at, error_code, error_detail FROM agent_runs WHERE id = ?`,
+    sql: `SELECT id, thread_id, status, started_at, error_code, error_detail, terminal_reason FROM agent_runs WHERE id = ?`,
     args: [runId],
   });
   if (rows.length === 0) return null;
@@ -1944,6 +1945,7 @@ export async function getRunById(runId: string): Promise<{
     started_at: number | string;
     error_code?: string | null;
     error_detail?: string | null;
+    terminal_reason?: string | null;
   };
   return {
     id: r.id,
@@ -1952,6 +1954,7 @@ export async function getRunById(runId: string): Promise<{
     startedAt: Number(r.started_at),
     errorCode: r.error_code ?? null,
     errorDetail: r.error_detail ?? null,
+    terminalReason: r.terminal_reason ?? null,
   };
 }
 

package/corpus/core/src/agent/types.ts

@@ -369,18 +369,38 @@ export type AgentChatEvent =
     }
   | {
       type: "auto_continue";
-      reason:
-        | "run_timeout"
-        | "loop_limit"
-        | "max_tokens"
-        | "no_progress"
-        | "stream_ended"
-        | "gateway_timeout"
-        | "network_interrupted";
+      reason: ContinuationReason;
       maxIterations?: number;
     }
   | { type: "clear" };
 
+export const CONTINUATION_REASONS = [
+  "run_timeout",
+  "loop_limit",
+  "max_tokens",
+  "no_progress",
+  "stream_ended",
+  "gateway_timeout",
+  "network_interrupted",
+] as const;
+
+export type ContinuationReason = (typeof CONTINUATION_REASONS)[number];
+
+/**
+ * True when an `agent_runs.terminal_reason` marks a CHUNK boundary rather than
+ * the end of the turn. Both writers (`terminalReasonForRun` in run-manager and
+ * `markBackgroundContinuationChunkTerminal` in production-agent) record
+ * status='completed' with one of these while a chained successor run carries the
+ * turn on, so such a row must never be reported to a client as a plain `done`.
+ * Mirrored client-side by `BACKGROUND_CONTINUATION_TERMINAL_REASONS`.
+ */
+export function isContinuationTerminalReason(reason: unknown): boolean {
+  return (
+    reason === "auto_continue" ||
+    CONTINUATION_REASONS.includes(reason as ContinuationReason)
+  );
+}
+
 export interface RunEvent {
   seq: number;
   event: AgentChatEvent;

package/corpus/core/src/chat-threads/store.ts

@@ -1290,6 +1290,51 @@ export async function getThreadByShareToken(
   return null;
 }
 
+/**
+ * Grant a user an explicit share on a thread they don't own. Used by the
+ * messaging-integration path, where a channel conversation runs as the
+ * integration service principal and so creates a thread owned by
+ * `integration@<platform>` rather than the human who asked — without this the
+ * "Open thread" deep link resolves to a 404 for them.
+ *
+ * Idempotent, and never downgrades an existing stronger role.
+ */
+export async function grantThreadUserShare(
+  threadId: string,
+  userEmail: string,
+  role: ShareRole,
+  grantedBy: string,
+): Promise<void> {
+  const normalizedEmail = userEmail.trim().toLowerCase();
+  if (!threadId || !normalizedEmail.includes("@")) return;
+  await ensureTable();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT id, role FROM chat_thread_shares WHERE resource_id = ? AND principal_type = 'user' AND LOWER(principal_id) = ?`,
+    args: [threadId, normalizedEmail],
+  });
+  const existing = rows[0];
+  if (existing) {
+    if (roleSatisfies(existing.role as ShareRole, role)) return;
+    await client.execute({
+      sql: `UPDATE chat_thread_shares SET role = ? WHERE id = ?`,
+      args: [role, existing.id as string],
+    });
+    return;
+  }
+  await client.execute({
+    sql: `INSERT INTO chat_thread_shares (id, resource_id, principal_type, principal_id, role, created_by, created_at) VALUES (?, ?, 'user', ?, ?, ?, ?)`,
+    args: [
+      crypto.randomUUID(),
+      threadId,
+      normalizedEmail,
+      role,
+      grantedBy,
+      new Date().toISOString(),
+    ],
+  });
+}
+
 export async function deleteThread(id: string): Promise<boolean> {
   await ensureTable();
   const client = getDbExec();

package/corpus/core/src/checkpoints/index.ts

@@ -6,6 +6,8 @@ export {
   cleanupOldCheckpoints,
 } from "./store.js";
 
+export { isCheckpointRestorePath } from "./route-match.js";
+
 export {
   isGitRepo,
   hasUncommittedChanges,

package/corpus/core/src/checkpoints/route-match.ts

@@ -0,0 +1,13 @@
+/**
+ * The framework mount shim normally rewrites `event.path` to the mount-relative
+ * remainder ("/restore"), but it falls back to the unstripped request path when
+ * `event.url` is read-only on the host runtime. Accept both so a restore POST
+ * never silently 405s.
+ */
+export function isCheckpointRestorePath(path: string | undefined): boolean {
+  if (!path) return false;
+  return (
+    /(^|\/)checkpoints\/restore(?:[/?]|$)/.test(path) ||
+    /^\/?restore(?:[/?]|$)/.test(path)
+  );
+}