@agent-native/core 0.76.6 → 0.76.8

package/corpus/core/docs/content/locales/zh-CN/workspace-connections.md

@@ -16,7 +16,7 @@ description: "用于 connect-once-use-everywhere 集成的共享提供商元数
 - **credentialRef** — 指向保管库机密 (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`) 的指针。连接表明令牌所在的位置；金库保存着价值。
 - **就绪** - 应用程序看到的组合状态：`connected`（已授予 + 存在凭据）、`needs_grant`、`needs_credentials`、`needs_attention` 或 `not_configured`。
 
-```an-diagram title="Connect once, grant apps, reuse credentials" summary="A Connection holds provider metadata (never secrets) and credentialRefs that point at the vault. Per-app Grants unlock it. Apps read a single Readiness status."
+```an-diagram title="连接一次、授予应用程序、重复使用凭据" summary="连接保存提供者元数据（绝不是秘密）和指向保管库的 credentialRefs。每个应用程序授予解锁它。应用程序读取单个就绪状态。"
 {
   "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, status, scopes, config &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
   "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
@@ -206,7 +206,7 @@ const brainCatalog = await listWorkspaceConnectionProviderCatalogForApp({
 
 工作区连接提供程序元数据回答：“这是哪个提供程序，它能做什么，可能需要什么凭据密钥，以及哪些模板应提供它？”
 
-```an-diagram title="Connection store vs. vault" summary="The vault owns the secret value. The connection owns provider metadata plus credentialRefs (pointers). At execution time the app resolves the ref through a granted connection and reads the value from the vault."
+```an-diagram title="连接存储与保管库" summary="金库拥有秘密价值。连接拥有提供者元数据和 credentialRefs（指针）。在执行时，应用程序通过授予的连接解析引用并从保管库读取值。"
 {
   "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection store</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, scopes, config</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">App action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">never returned to the agent or UI</small></div></div></div>",
   "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"

package/corpus/core/docs/content/locales/zh-CN/workspace-management.md

@@ -9,7 +9,7 @@ description: "分支、CODEOWNERS、PR 审查以及 Dispatch 如何与 git 级
 
 本指南涵盖了运行代理本机工作区的操作方面 - 如何分支、谁审查什么、如何设置代码所有权以及 Dispatch 控制平面如何适应您的治理模型。
 
-```an-diagram title="Two governance planes" summary="Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."
+```an-diagram title="两个治理平面" summary="Git 管理代码； Dispatch 控制运行时。它们是互补的——不要将一个复制到另一个中。"
 {
   "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git / GitHub</span><strong>Code governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR review</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
   "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
@@ -47,13 +47,13 @@ main                         ← production
 
 代码治理由存储库根目录中的几个文件配置：
 
-```an-file-tree title="Governance config in the repo"
+```an-file-tree title="repo 中的治理配置"
 {
   "entries": [
-    { "path": ".github/CODEOWNERS", "note": "Auto-assigns reviewers per changed path" },
-    { "path": ".github/labeler.yml", "note": "Auto-labels PRs by app" },
-    { "path": "pnpm-workspace.yaml", "note": "Workspace-level — broad review" },
-    { "path": "package.json", "note": "Workspace-level — platform team owns" }
+    { "path": ".github/CODEOWNERS", "note": "按变更路径自动分配 reviewers" },
+    { "path": ".github/labeler.yml", "note": "按 app 自动给 PR 加标签" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace 级别：宽范围 review" },
+    { "path": "package.json", "note": "Workspace 级别：平台团队负责" }
   ]
 }
 ```

package/corpus/core/docs/content/locales/zh-CN/workspace.md

@@ -11,9 +11,9 @@ description: "Claude - 每个用户的代码级自定义 - skills、内存、指
 
 变化：**它是 SQL 行，而不是文件系统文件。**每个用户都将自己的工作区存储在数据库中。没有要启动的开发盒，没有每个用户的容器，没有要安装的文件。多租户 SaaS 可以为每个用户提供基本上免费的完全可定制的代理，因为所有这些都是行——个人内存、个人 MCP 服务器、个人 skills、个人子代理——并且共享代码库同时托管所有这些。
 
-```an-diagram title="A Claude-Code workspace, but stored in SQL" summary="The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."
+```an-diagram title="Claude-Code 工作区，但存储在 SQL 中" summary="相同的定制层——指令、技能、内存、代理、作业、MCP——除了每个文件都是共享多租户数据库中的一行。"
 {
-  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native workspace</span><small class=\"diagram-muted\">rows in one SQL database</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">one codebase, many users, scoped <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
+  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native workspace</span><small class=\"diagram-muted\">rows in one SQL 数据库</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">one codebase, many users, scoped <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
   "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
 }
 ```
@@ -51,7 +51,7 @@ description: "Claude - 每个用户的代码级自定义 - skills、内存、指
 
 这些路径适用于所有三个范围 - 工作空间、组织/应用程序和个人。当同一路径存在于多个级别时，后面的范围获胜。
 
-```an-diagram title="Three scopes, one effective file" summary="The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."
+```an-diagram title="三个范围，一个有效文件" summary="运行时在读取时解析跨工作区、应用程序和个人范围的相同路径 - 最具体的范围获胜。"
 {
   "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">company-wide defaults from Dispatch</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Organization / app</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
   "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
@@ -217,7 +217,7 @@ Skills 是 `skills/` 路径（最好是 `skills/<name>/SKILL.md`）下的 Markdo
 
 自定义代理使用 YAML frontmatter 加上 Markdown 指令：
 
-```an-annotated-code title="A custom agent profile"
+```an-annotated-code title="自定义代理配置文件"
 {
   "filename": "agents/design.md",
   "language": "markdown",

package/corpus/core/docs/content/locales/zh-CN/writing-agent-instructions.md

@@ -7,7 +7,7 @@ description: "如何为代理原生应用或模板编写出色的代理指令：
 
 代理在代理本机应用程序中的行为仅与您给出的说明一样好。三个表面承载该指导：`AGENTS.md`（地图）、skills（深入研究）和操作/工具描述（代理如何选择正确的工具）。写下每一篇都是为了快速检索，而不是为了散文。
 
-```an-diagram title="Three authored surfaces + one runtime surface" summary="AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."
+```an-diagram title="三个创作表面 + 一个运行时表面" summary="AGENTS.md 和工具描述每回合都会加载；按需加载技能； application_state 由您的 UI 实时编写。"
 {
   "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">the map: purpose, core rules, state keys, action + skills index</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>Tool descriptions</strong><small class=\"diagram-muted\">drive tool selection — one precise sentence each</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">On demand</span><strong>Skills</strong><small class=\"diagram-muted\">deep how-to, loaded when the description fires</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">written by your UI: navigation, selection, focus</small></div></div>",
   "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"

package/corpus/core/docs/content/real-time-collaboration.md

@@ -121,8 +121,12 @@ Prevents Vite from re-bundling TipTap in incompatible ways during dev:
 
 ```ts
 // vite.config.ts
+import { reactRouter } from "@react-router/dev/vite";
+import { agentNative } from "@agent-native/core/vite";
+import { defineConfig } from "vite";
+
 export default defineConfig({
-  plugins: [reactRouter()],
+  plugins: [reactRouter(), agentNative()],
   optimizeDeps: {
     include: [
       "yjs",

package/corpus/core/package.json

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

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

@@ -4569,18 +4569,24 @@ export function createProductionAgentHandler(
       // again, but its duplicate-PK collision is swallowed, so an existing
       // `background-processing` row is reused — no double row.
       if (backgroundOutcome.reason === "worker-never-claimed") {
-        // The async 202 landed but no worker claimed within grace — the generated
-        // wrapper never reached the route. Record it so the failure is visible on
-        // the run even though the user still gets a working (inline) turn.
+        // The async 202 landed but no worker claimed within grace. PRESERVE the
+        // bg-fn's last-recorded diag_stage (route_entered / auth_failed / ... or
+        // "none" if it never reached the route) in the recovery detail BEFORE we
+        // overwrite diag_stage — otherwise foreground_inline_recovery clobbers
+        // the only clue to WHY the worker died (its own logs are unreadable).
+        const priorClaim = await readBackgroundRunClaim(runId).catch(
+          () => null,
+        );
+        const priorDiag = priorClaim?.diagStage ?? "none";
         console.error(
           "[agent-chat] background worker did not claim the 202-dispatched run " +
-            "within grace; recovering inline:",
+            `within grace; recovering inline. bgFnPriorDiag=${priorDiag}`,
           runId,
         );
         await recordRunDiagnostic(
           runId,
           RUN_DIAG_STAGE.foregroundInlineRecovery,
-          "202 dispatched but no worker claimed within the foreground grace window",
+          `202 dispatched but no worker claimed within grace; bgFnPriorDiag=${priorDiag}`,
         ).catch(() => {});
       }
       // Fall through to the inline `startRun` path below.

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

@@ -388,22 +388,29 @@ export async function claimBackgroundRun(runId: string): Promise<boolean> {
  * the claim; a terminal `status` means the run already resolved. Returns null if
  * the row is missing.
  */
-export async function readBackgroundRunClaim(
-  runId: string,
-): Promise<{ dispatchMode: string | null; status: string | null } | null> {
+export async function readBackgroundRunClaim(runId: string): Promise<{
+  dispatchMode: string | null;
+  status: string | null;
+  diagStage: string | null;
+} | null> {
   await ensureRunTables();
   const client = getDbExec();
   const { rows } = await client.execute({
-    sql: `SELECT dispatch_mode, status FROM agent_runs WHERE id = ? LIMIT 1`,
+    sql: `SELECT dispatch_mode, status, diag_stage FROM agent_runs WHERE id = ? LIMIT 1`,
     args: [runId],
   });
   const row = rows?.[0] as
-    | { dispatch_mode?: string | null; status?: string | null }
+    | {
+        dispatch_mode?: string | null;
+        status?: string | null;
+        diag_stage?: string | null;
+      }
     | undefined;
   if (!row) return null;
   return {
     dispatchMode: row.dispatch_mode ?? null,
     status: row.status ?? null,
+    diagStage: row.diag_stage ?? null,
   };
 }
 
@@ -517,19 +524,6 @@ export const RUN_DIAG_STAGE = {
    * recovered by running the turn inline. The run still completes for the user.
    */
   foregroundInlineRecovery: "foreground_inline_recovery",
-  /**
-   * bg-fn wrapper self-diagnostics (the generated `server-agent-background`
-   * wrapper reports these via the `_bg-diag` route, since its own logs are
-   * unreadable). `bgfnWrapperEntered`: the wrapper actually ran in the bg-fn
-   * isolate. `bgfnHandoffReturned`: the in-isolate handoff to the Nitro handler
-   * RETURNED — detail carries the HTTP status (404=route mismatch, 401=auth,
-   * 2xx/5xx=route ran). `bgfnWrapperThrew`: the import/handoff THREW before
-   * returning — detail carries the error. Read in the pre-grace window before
-   * the circuit-breaker overwrites diag_stage.
-   */
-  bgfnWrapperEntered: "bgfn_wrapper_entered",
-  bgfnHandoffReturned: "bgfn_handoff_returned",
-  bgfnWrapperThrew: "bgfn_wrapper_threw",
 } as const;
 
 export type RunDiagStage = (typeof RUN_DIAG_STAGE)[keyof typeof RUN_DIAG_STAGE];