@agent-native/core 0.87.0 → 0.90.1

package/corpus/core/docs/content/locales/zh-TW/extensions.mdx

@@ -34,7 +34,7 @@ description: "使用者在範本內建置的迷你應用程式 - Analytics 中
     <div class="ext-helpers">
       <span class="diagram-pill">appAction</span
       ><span class="diagram-pill">appFetch</span
-      ><span class="diagram-pill">dbQuery / dbExec</span
+      ><span class="diagram-pill">dbQuery</span
       ><span class="diagram-pill">extensionData</span
       ><span class="diagram-pill">extensionFetch</span>
     </div>
@@ -220,17 +220,17 @@ description: "使用者在範本內建置的迷你應用程式 - Analytics 中
 
 在 iframe 沙箱內，每個擴充功能在 `window` 上都有這些幫助程式：
 
-| 幫手                                             | 目的                                      | 範例                                                      |
-| ------------------------------------------------ | ----------------------------------------- | --------------------------------------------------------- |
-| `appAction(name, params)`                        | 呼叫任意主機範本的actions                 | `appAction('list-emails', { view: 'inbox' })`             |
-| `appFetch(path, options)`                        | 呼叫`/_agent-native/*`下允許的框架端點    | `appFetch('/_agent-native/application-state/navigation')` |
-| `dbQuery(sql, args)`                             | 從 SQL 讀取（自動調整範圍給使用者）       | `dbQuery('SELECT id, name FROM tools')`                   |
-| `dbExec(sql, args)`                              | 寫入 SQL                                  | `dbExec('INSERT INTO ...')`                               |
-| `extensionFetch(url, options)`                   | 透過帶有秘密的安全代理攻擊外部 API        | `extensionFetch('https://api.github.com/user')`           |
-| `extensionData.set(collection, id, data, opts?)` | 保留每個擴充功能的資料（使用者/組織範圍） | `extensionData.set('notes', id, { text: '...' })`         |
-| `extensionData.list(collection, opts?)`          | 列出持久化專案                            | `extensionData.list('notes', { scope: 'all' })`           |
-| `extensionData.get(collection, id, opts?)`       | 取得單一專案                              | `extensionData.get('notes', 'note-1')`                    |
-| `extensionData.remove(collection, id, opts?)`    | 刪除持久化專案                            | `extensionData.remove('notes', 'note-1')`                 |
+| 幫手                                             | 目的                                                  | 範例                                                      |
+| ------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------- |
+| `appAction(name, params)`                        | 呼叫任意主機範本的actions                             | `appAction('list-emails', { view: 'inbox' })`             |
+| `appFetch(path, options)`                        | 呼叫`/_agent-native/*`下允許的框架端點                | `appFetch('/_agent-native/application-state/navigation')` |
+| `dbQuery(sql, args)`                             | 從 SQL 讀取（自動調整範圍給使用者）                   | `dbQuery('SELECT id, name FROM tools')`                   |
+| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions | Prefer `appAction` for app data writes                    |
+| `extensionFetch(url, options)`                   | 透過帶有秘密的安全代理攻擊外部 API                    | `extensionFetch('https://api.github.com/user')`           |
+| `extensionData.set(collection, id, data, opts?)` | 保留每個擴充功能的資料（使用者/組織範圍）             | `extensionData.set('notes', id, { text: '...' })`         |
+| `extensionData.list(collection, opts?)`          | 列出持久化專案                                        | `extensionData.list('notes', { scope: 'all' })`           |
+| `extensionData.get(collection, id, opts?)`       | 取得單一專案                                          | `extensionData.get('notes', 'note-1')`                    |
+| `extensionData.remove(collection, id, opts?)`    | 刪除持久化專案                                        | `extensionData.remove('notes', 'note-1')`                 |
 
 三個經驗法則：
 
@@ -395,7 +395,7 @@ SQL 本機擴充功能安裝行。
 
 - 除非停用，否則 `extensionData` 可用於小型執行時狀態。
 - `appAction` 呼叫必須在 `permissions.appActions` 中顯式列出。
-- `dbQuery`、`dbExec` 和 `extensionFetch` 暫時被屏蔽。
+- `dbQuery` 和 `extensionFetch` 暫時被屏蔽。
 - SQL 支援的更新、刪除、共用和歷史紀錄 actions 返回一條訊息
   指向本機入口檔案。
 
@@ -428,6 +428,8 @@ SQL 本機擴充功能安裝行。
 
 經驗法則：**如果它適用於一個使用者或一個團隊，那麼它就是一個擴充功能。**如果範本的每個使用者都應該獲得它，請將其作為一項真正的功能提供。
 
+對於應該為原生圖表與表格提供資料、而非客製化小工具 UI 的自訂資料擷取需求，請參見[資料程式](/docs/data-programs)——一個已儲存、可更新的 `run-code` 腳本，dashboard 面板可直接綁定到它，完全不涉及擴充功能 iframe。
+
 ## 安全 {#security}
 
 <Callout id="doc-block-frp4nq" tone="success">
@@ -442,7 +444,7 @@ SQL 本機擴充功能安裝行。
 - **伺服器端秘密注入**透過 `${keys.NAME}` 範本 - 實際的金鑰值永遠不會到達瀏覽器。
 - **域鎖定的秘密** — 每個金鑰都綁定到 URL 允許清單；代理拒絕對其他主機的請求。
 - **專用網路保護** - 擴充功能無法到達內部地址。
-- **需要驗證** - 擴充功能僅針對登入使用者執行，並且 `dbQuery` / `dbExec` 呼叫是自動範圍的。
+- **需要驗證** - 擴充功能僅針對登入使用者執行，並且 `dbQuery` 呼叫是自動範圍的。
 
 ## 有關命名的一些知識 {#naming-back-compat}
 

package/corpus/core/docs/content/locales/zh-TW/key-concepts.mdx

@@ -237,21 +237,16 @@ export const forms = table("forms", {
 ```
 
 ```bash
-# 資料庫快速檢查和一次性維護的核心動作
+# 資料庫快速檢查的核心動作
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
-pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
-# 大型文字列上的 Surgical find/replace — 傳送差異，而不是整個值
-pnpm action db-patch --table documents --column content \
-  --where "id='doc-1'" --find "old heading" --replace "new heading"
 ```
 
-正式環境代理聊天外掛預設啟用原始資料庫寫入
-(`databaseTools: "write"`)，以便代理可以修復應用程式擁有的資料，而無需等待
-新型別的動作。這些寫入的範圍僅限於經過驗證的使用者/組織。設定
-`databaseTools: "read"` 僅保留 `db-schema` / `db-query` 檢查，或
-`databaseTools: "off"` / `false` 要求型別化應用程式 actions 取得所有資料
-存取。
+正式環境代理聊天外掛預設將原始 SQL 工具設為唯讀
+(`databaseTools: "read"`)，因此代理使用 `db-schema` / `db-query` 檢查應用程式擁有的資料，
+並透過型別化應用程式 actions 執行寫入。只有在刻意的維護介面也需要公開具範圍限制的
+`db-exec` / `db-patch` 時，才設定 `databaseTools: "write"`（或 `true`）；
+設定 `databaseTools: "off"` / `false` 可要求所有資料存取都透過型別化應用程式 actions。
 
 ## 代理聊天橋 {#agent-chat-bridge}
 
@@ -431,6 +426,7 @@ UI 在路由變更時寫入此資訊；代理在採取任何操作之前都會
 
 - **[Dispatch](/docs/dispatch)** — 工作區控制平面：共用收件箱、機密庫、計畫作業以及透過 A2A 委托給專業應用程式的編排器。
 - **[Extensions](/docs/extensions)** — 代理在執行時建立的沙盒 Alpine.js 迷你應用，無需更改來源或遷移。
+- **[資料程式](/docs/data-programs)** — 由 agent 撰寫並儲存的 `run-code` 腳本，為 dashboard 面板提供快取的、可更新的結果，而非硬編碼的 provider action。
 - **[A2A Protocol](/docs/a2a-protocol)** — 同一工作區中的應用如何透過 JSON-RPC 發現並相互呼叫。
 
 ## 您免費獲得的東西 {#what-you-get-for-free}

package/corpus/core/docs/content/locales/zh-TW/real-time-collaboration.mdx

@@ -252,11 +252,8 @@ export default createCollabPlugin({
 ### 4.使用用戶端鉤子
 
 ```ts
-import {
-  useCollaborativeDoc,
-  emailToColor,
-  emailToName,
-} from "@agent-native/core/client";
+import { useCollaborativeDoc } from "@agent-native/core/client";
+import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
 
@@ -358,12 +355,14 @@ pnpm action edit-document --id doc123 --find "delete me" --replace ""
 
 ```ts
 import {
-  PresenceBar,
-  LiveCursorOverlay,
-  RemoteSelectionRings,
   useCollaborativeDoc,
   usePresence,
 } from "@agent-native/core/client/collab";
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
 ```
 
 伺服器端代理存在幫助程式保留在較低階別的協作包中：
@@ -449,7 +448,7 @@ setPresence({ cursor: { x: 0.4, y: 0.7 }, selection: "#hero" });
 將遠端游標呈現為容器元素上的絕對定位標籤：
 
 ```tsx
-import { LiveCursorOverlay } from "@agent-native/core/client";
+import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 
 // cursor positions stored as { x, y } normalized 0–1 under presence.cursor
 <div ref={containerRef} style={{ position: "relative" }}>
@@ -469,7 +468,7 @@ import { LiveCursorOverlay } from "@agent-native/core/client";
 在遠端選取的元素上渲染彩色輪廓環+名稱標籤：
 
 ```tsx
-import { RemoteSelectionRings } from "@agent-native/core/client";
+import { RemoteSelectionRings } from "@agent-native/toolkit/collab-ui";
 
 <div ref={containerRef} style={{ position: "relative" }}>
   {content}
@@ -745,7 +744,7 @@ undoManager.redo(); // Shift+Cmd+Z
   （持久存在心跳）。
 
 Use `emailToColor(email)` and `emailToName(email)` from
-`@agent-native/core/client` 產生一致的游標顏色和顯示
+`@agent-native/toolkit/collab-ui` 產生一致的游標顏色和顯示
 電子郵件地址中的姓名。
 
 使用 `activeUsers` 渲染的 `PresenceBar` 顯示活人和代理

package/corpus/core/docs/content/locales/zh-TW/sharing.mdx

@@ -93,9 +93,10 @@ description: "Google Docs 風格的共用，內建於框架中。每個使用者
 - **幻燈片** — 幻燈片
 - **設計** — 設計和資產
 - **剪輯** — 螢幕錄製（Loom 風格）
+- **Plan** — visual plans and PR recaps
 - **表單** — 表單定義
 - **行事曆** — 活動和預訂連結
-- **分析** - 儀表板（推出 - 請參閱分析範本的 `AGENTS.md`）
+- **分析** - dashboards, saved analyses, and tokenized session replays
 - **擴充功能** - 沙盒迷你應用程式（參見 [Extensions](/docs/extensions#sharing)）
 
 其中每一個都使用相同的 `ownableColumns()` 模式助手、相同的 `share-resource` 操作和相同的 `<ShareButton>` UI。從一個範本行動到另一個範本，共用對話框看起來相同。
@@ -136,15 +137,22 @@ import { ShareButton } from "@agent-native/core/client";
 
 框架在每個範本中自動安裝這些 actions - 代理將它們稱為工具，UI 透過 `useActionQuery` / `useActionMutation` 呼叫它們：
 
-| 行動                      | 它的作用                                                               |
-| ------------------------- | ---------------------------------------------------------------------- |
-| `share-resource`          | 授予使用者或組織特定角色的存取權限。可選的 `notify` 控制電子郵件通知。 |
-| `unshare-resource`        | 撤銷使用者或組織的存取權限。                                           |
-| `list-resource-shares`    | 顯示目前可見性以及所有顯式授權。                                       |
-| `set-resource-visibility` | 更改為 `private`、`org` 或 `public`。                                  |
+| 行動                         | 它的作用                                                                                |
+| ---------------------------- | --------------------------------------------------------------------------------------- |
+| `share-resource`             | 授予使用者或組織特定角色的存取權限。可選的 `notify` 控制電子郵件通知。                  |
+| `unshare-resource`           | 撤銷使用者或組織的存取權限。                                                            |
+| `list-resource-shares`       | 顯示目前可見性以及所有顯式授權。                                                        |
+| `set-resource-visibility`    | 更改為 `private`、`org` 或 `public`。                                                   |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource. |
 
 告訴代理“與作為編輯的行銷團隊共用此設計”，它會針對 UI 使用的同一端點呼叫 `share-resource`。結果將顯示在下一次渲染的共用對話框中。
 
+## Agent-readable share links {#agent-readable-links}
+
+Human share links should also work for agents when the resource is a document-like artifact: plans, documents, decks, designs, analytics dashboards, saved analyses, clips, and similar "things you would send to a person." Public links expose a small SSR discovery script that points at structured JSON. Private resources use a short-lived `agent_access` token scoped to exactly one resource.
+
+Register the resource with `agentReadable`, add a read-only JSON context endpoint, inject the SSR discovery script with `renderAgentReadableResourceDiscoveryScript()`, and let agents call `create-agent-resource-link` when they need a temporary private URL. The endpoint must return data only when the row is `public` or `verifyScopedAgentAccessToken()` accepts the token for that exact `resourceKind` and `resourceId`.
+
 ## 將其建置到新範本中 {#building}
 
 如果您正在建立範本（請參閱 [Creating Templates](/docs/creating-templates)），則共用接線會很短。您的架構中新增了兩項內容：

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

@@ -258,11 +258,8 @@ export default createCollabPlugin({
 ### 4. Use the client hook
 
 ```ts
-import {
-  useCollaborativeDoc,
-  emailToColor,
-  emailToName,
-} from "@agent-native/core/client";
+import { useCollaborativeDoc } from "@agent-native/core/client";
+import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
 
@@ -364,12 +361,14 @@ Import client-side presence and editor UI from the focused browser subpath:
 
 ```ts
 import {
-  PresenceBar,
-  LiveCursorOverlay,
-  RemoteSelectionRings,
   useCollaborativeDoc,
   usePresence,
 } from "@agent-native/core/client/collab";
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
 ```
 
 Server-side agent presence helpers stay in the lower-level collab package:
@@ -455,7 +454,7 @@ The agent (AGENT_CLIENT_ID) appears as a first-class participant with `isAgent:
 Renders remote cursors as absolutely-positioned labels over a container element:
 
 ```tsx
-import { LiveCursorOverlay } from "@agent-native/core/client";
+import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 
 // cursor positions stored as { x, y } normalized 0–1 under presence.cursor
 <div ref={containerRef} style={{ position: "relative" }}>
@@ -475,7 +474,7 @@ The agent's cursor renders distinctly with a sparkle icon. Cursors fade out afte
 Renders colored outline rings + name tags over remotely-selected elements:
 
 ```tsx
-import { RemoteSelectionRings } from "@agent-native/core/client";
+import { RemoteSelectionRings } from "@agent-native/toolkit/collab-ui";
 
 <div ref={containerRef} style={{ position: "relative" }}>
   {content}
@@ -751,7 +750,7 @@ The `useCollaborativeDoc` hook returns:
   (durable presence heartbeat).
 
 Use `emailToColor(email)` and `emailToName(email)` from
-`@agent-native/core/client` to generate consistent cursor colors and display
+`@agent-native/toolkit/collab-ui` to generate consistent cursor colors and display
 names from email addresses.
 
 A `PresenceBar` rendered with `activeUsers` shows live human and agent

package/corpus/core/docs/content/sharing.mdx

@@ -93,9 +93,10 @@ Every template that stores user-authored work uses this model. Concretely:
 - **Slides** — decks
 - **Design** — designs and assets
 - **Clips** — screen recordings (Loom-style)
+- **Plan** — visual plans and PR recaps
 - **Forms** — form definitions
 - **Calendar** — events and booking links
-- **Analytics** — dashboards (rolling out — see the analytics template's `AGENTS.md`)
+- **Analytics** — dashboards, saved analyses, and tokenized session replays
 - **Extensions** — sandboxed mini-apps (see [Extensions](/docs/extensions#sharing))
 
 Every one of these uses the same `ownableColumns()` schema helper, the same `share-resource` action, and the same `<ShareButton>` UI. Move from one template to another and the share dialog looks identical.
@@ -136,15 +137,46 @@ For lists, drop a `<VisibilityBadge visibility={row.visibility} />` next to each
 
 The framework auto-mounts these actions in every template — the agent calls them as tools, and the UI calls them through `useActionQuery` / `useActionMutation`:
 
-| Action                    | What it does                                                                                   |
-| ------------------------- | ---------------------------------------------------------------------------------------------- |
-| `share-resource`          | Grant a user or org access at a specific role. Optional `notify` controls email notifications. |
-| `unshare-resource`        | Revoke access for a user or org.                                                               |
-| `list-resource-shares`    | Show current visibility plus all explicit grants.                                              |
-| `set-resource-visibility` | Change to `private`, `org`, or `public`.                                                       |
+| Action                       | What it does                                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| `share-resource`             | Grant a user or org access at a specific role. Optional `notify` controls email notifications. |
+| `unshare-resource`           | Revoke access for a user or org.                                                               |
+| `list-resource-shares`       | Show current visibility plus all explicit grants.                                              |
+| `set-resource-visibility`    | Change to `private`, `org`, or `public`.                                                       |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource.        |
 
 Tell the agent "share this design with the marketing team as editors" and it calls `share-resource` against the same endpoint the UI uses. The result shows up in the share dialog the next render.
 
+## Agent-readable share links {#agent-readable-links}
+
+Human share links should also work for agents when the resource is a document-like artifact: plans, documents, decks, designs, analytics dashboards, saved analyses, clips, and similar "things you would send to a person." Public links expose a small SSR discovery script that points at structured JSON. Private resources use a short-lived `agent_access` token scoped to exactly one resource.
+
+The default flow is:
+
+1. Register the resource with `agentReadable`.
+2. Add a read-only JSON endpoint that returns the same content a viewer can see.
+3. Add an SSR discovery script on the human page with `renderAgentReadableResourceDiscoveryScript()`.
+4. Let agents call `create-agent-resource-link` when they need a temporary private URL.
+
+```ts
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/p/${deck.id}`,
+  agentReadable: {
+    resourceKind: "slides:deck",
+    getContextPath: () => "/api/deck-agent-context.json",
+    getPagePath: (deck) => `/p/${deck.id}`,
+  },
+  getDb,
+});
+```
+
+The context endpoint must be read-only. It should return data only when the row is `public` or `verifyScopedAgentAccessToken()` accepts the token for that exact `resourceKind` and `resourceId`. Set `Cache-Control: no-store`, `Referrer-Policy: no-referrer`, and avoid including write credentials, provider blob URLs, or secrets. Token links should not change the resource visibility.
+
 ## Building it into a new template {#building}
 
 If you're creating a template (see [Creating Templates](/docs/creating-templates)), wiring sharing in is short. Two additions to your schema:

package/corpus/core/docs/content/toolkit-app-adapters.mdx

@@ -0,0 +1,46 @@
+---
+title: "Toolkit App Adapters"
+description: "Use app-local wrappers so Toolkit components are reusable without forcing one visual system."
+---
+
+# Toolkit App Adapters
+
+Every template can expose local UI adapters under `@/components/ui/*` and local
+hook adapters under `@/hooks/*`. Most adapters are intentionally tiny:
+
+```tsx
+export * from "@agent-native/toolkit/ui/button";
+```
+
+This pattern gives apps a stable customization point. Reusable Toolkit code can
+ship once, while app owners can replace `Button`, `Input`, or `Dialog` locally
+without rewriting every callsite.
+
+## Import Rule {#import-rule}
+
+Inside an app, prefer:
+
+```tsx
+import { Button } from "@/components/ui/button";
+```
+
+Inside Toolkit or other reusable packages, use:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+```
+
+For reusable kit components that render app chrome, prefer `ToolkitProvider`
+over direct imports for primitives that apps commonly customize.
+
+Provider wiring can import from the focused provider subpath:
+
+```tsx
+import { ToolkitProvider } from "@agent-native/toolkit/provider";
+```
+
+## Compatibility {#compatibility}
+
+Existing template code that used direct Toolkit imports has been migrated to
+local adapters. Existing external apps can keep their old imports while they
+migrate, because the Toolkit package still exports every primitive directly.

package/corpus/core/docs/content/toolkit-collaboration-ui.mdx

@@ -0,0 +1,48 @@
+---
+title: "Toolkit Collaboration UI"
+description: "Reusable presence, cursor, selection, and recent-edit UI for collaborative Agent-Native apps."
+---
+
+# Toolkit Collaboration UI
+
+`@agent-native/toolkit/collab-ui` contains the presentational collaboration
+pieces that do not own transport or storage:
+
+```tsx
+import {
+  AgentPresenceChip,
+  LiveCursorOverlay,
+  PresenceBar,
+  RecentEditHighlights,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
+```
+
+Core still owns the live collaboration runtime: Yjs documents, awareness sync,
+presence hooks, recent edit publication, undo grouping, and server plugins. Use
+core for data and Toolkit for rendering.
+
+```tsx
+import { useCollaborativeDoc, usePresence } from "@agent-native/core/client";
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+```
+
+Existing imports from `@agent-native/core/client` still work because core
+re-exports these Toolkit components as compatibility shims.
+
+## Responsibilities {#responsibilities}
+
+Toolkit owns:
+
+- Presence avatars and agent editing chips.
+- Live cursor overlays.
+- Remote selection rings.
+- Recent edit highlight overlays.
+- Display helpers such as collaborator color and display-name derivation.
+
+Core owns:
+
+- Yjs document creation and sync.
+- Awareness polling and SSE fast-path transport.
+- Collaboration server plugins and actions.
+- Recent edit publication and collection from awareness.

package/corpus/core/docs/content/toolkit-sharing-ui.mdx

@@ -0,0 +1,33 @@
+---
+title: "Toolkit Sharing UI"
+description: "Reusable sharing display components with core-owned sharing runtime compatibility."
+---
+
+# Toolkit Sharing UI
+
+`@agent-native/toolkit/sharing` contains sharing UI that does not perform access
+checks or mutations. Today it exports `VisibilityBadge`:
+
+```tsx
+import { VisibilityBadge } from "@agent-native/toolkit/sharing";
+```
+
+Core still owns the sharing runtime: share tables, resource registration, access
+filters, visibility changes, invites, roles, and private access tokens for
+agent-readable public surfaces.
+
+Use core wrappers when a component needs to call sharing actions:
+
+```tsx
+import { ShareButton, ShareDialog } from "@agent-native/core/client";
+```
+
+Those imports remain compatible. As more sharing UI is split into presentational
+base components, core wrappers should keep doing the runtime work and pass data
+and callbacks into Toolkit-owned UI.
+
+## Boundary {#boundary}
+
+Toolkit sharing UI can render badges, rows, base dialogs, and role pickers when
+data and callbacks are injected. Core sharing code should own SQL, permissions,
+request context, org membership lookups, and share-token minting.

package/corpus/core/docs/content/toolkit-shell-hooks.mdx

@@ -0,0 +1,27 @@
+---
+title: "Toolkit Shell & Hooks"
+description: "Shared shell helpers and hooks that templates can compose through local adapters."
+---
+
+# Toolkit Shell & Hooks
+
+Toolkit includes small shell helpers and hooks that are useful across apps:
+
+```tsx
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+import { useIsMobile } from "@agent-native/toolkit/hooks/use-mobile";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+```
+
+Apps can wrap these through local adapters when they want the same customization
+point as UI primitives:
+
+```tsx
+export * from "@agent-native/toolkit/hooks/use-mobile";
+```
+
+Keep shell helpers in Toolkit when they are reusable and do not own app data.
+Keep app-specific navigation, command entries, and domain state in the template.
+
+Core remains responsible for framework-wide shell behavior such as app providers,
+agent chat, app state, auth, and runtime sync.

package/corpus/core/docs/content/toolkit-ui.mdx

@@ -0,0 +1,69 @@
+---
+title: "Toolkit UI Primitives"
+description: "How to use @agent-native/toolkit UI primitives without locking apps out of customization."
+---
+
+# Toolkit UI Primitives
+
+Toolkit UI primitives live under `@agent-native/toolkit/ui/*`. They are the
+shared shadcn-style building blocks used by templates and reusable kits.
+
+Reusable package code can import them directly:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Dialog, DialogContent } from "@agent-native/toolkit/ui/dialog";
+```
+
+Apps that render Toolkit UI must also import the Toolkit stylesheet from
+`app/global.css` so Tailwind generates classes used only inside package
+components, such as dropdown and popover z-index and animation utilities:
+
+```css
+@import "tailwindcss";
+@import "@agent-native/core/styles/agent-native.css";
+@import "@agent-native/toolkit/styles.css";
+```
+
+Template app code should usually import the app-local adapter instead:
+
+```tsx
+import { Button } from "@/components/ui/button";
+```
+
+The adapter starts as a one-line re-export:
+
+```tsx
+export * from "@agent-native/toolkit/ui/button";
+```
+
+When an app wants its own button, it replaces that one adapter file. The rest of
+the app keeps importing `@/components/ui/button`.
+
+## Provider Overrides {#provider-overrides}
+
+Reusable Toolkit UI should read overridable primitives from `ToolkitProvider`
+instead of hard-coding a visual system. Templates wire their local `Button` into
+that provider so future kits automatically pick up app customization.
+
+```tsx
+import { ToolkitProvider } from "@agent-native/toolkit/provider";
+
+import { Button } from "@/components/ui/button";
+
+export function AppToolkitProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <ToolkitProvider components={{ Button }}>{children}</ToolkitProvider>;
+}
+```
+
+If an app override wants to keep Toolkit's default button styling as its base,
+render `ButtonBase` from `@agent-native/toolkit/ui/button`. Do not render
+Toolkit's `Button` from inside the override; `ButtonBase` is the explicit escape
+hatch, while Toolkit's recursion guard is only a fallback.
+
+Core keeps old imports working with re-export shims, but new app UI should flow
+through local adapters.

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.87.0",
+  "version": "0.90.1",
   "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": {
@@ -132,6 +132,7 @@
     "./sharing/actions/unshare-resource": "./dist/sharing/actions/unshare-resource.js",
     "./sharing/actions/list-resource-shares": "./dist/sharing/actions/list-resource-shares.js",
     "./sharing/actions/set-resource-visibility": "./dist/sharing/actions/set-resource-visibility.js",
+    "./sharing/actions/create-agent-resource-link": "./dist/sharing/actions/create-agent-resource-link.js",
     "./client/sharing": "./dist/client/sharing/index.js",
     "./client/extensions": "./dist/client/extensions/index.js",
     "./client/tools": "./dist/client/extensions/index.js",
@@ -161,6 +162,10 @@
     "./provider-api/actions/list-staged-datasets": "./dist/provider-api/actions/list-staged-datasets.js",
     "./provider-api/actions/delete-staged-dataset": "./dist/provider-api/actions/delete-staged-dataset.js",
     "./provider-api/actions/github-repo-files": "./dist/provider-api/actions/github-repo-files.js",
+    "./data-programs": {
+      "types": "./dist/data-programs/index.d.ts",
+      "default": "./dist/data-programs/index.js"
+    },
     "./local-artifacts": {
       "types": "./dist/local-artifacts/index.d.ts",
       "default": "./dist/local-artifacts/index.js"

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

@@ -339,6 +339,59 @@ export function isAgentChatDurableBackgroundEnabled(options?: {
   );
 }
 
+/**
+ * Env flag for the FOREGROUND server-driven self-chain. DEFAULT-OFF (opt-in):
+ * unset means disabled; an app opts IN with an explicit truthy value
+ * (`true`/`1`/`yes`/`on`) — same parsing convention as
+ * `AGENT_CHAT_DURABLE_BACKGROUND`, deliberately kept as a separate flag so
+ * this narrower capability can be enabled/disabled independently of the full
+ * durable-background worker path.
+ */
+export const AGENT_CHAT_FOREGROUND_SELF_CHAIN_ENV =
+  "AGENT_CHAT_FOREGROUND_SELF_CHAIN";
+
+function isForegroundSelfChainFlagEnabled(): 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_FOREGROUND_SELF_CHAIN_ENV.
+  const raw = process.env.AGENT_CHAT_FOREGROUND_SELF_CHAIN;
+  if (raw == null) return false;
+  const normalized = raw.trim().toLowerCase();
+  return (
+    normalized === "1" ||
+    normalized === "true" ||
+    normalized === "yes" ||
+    normalized === "on"
+  );
+}
+
+/**
+ * Gate for the OPT-IN foreground self-chain: a normal (non-durable-background)
+ * agent-chat turn that hits its soft-timeout chunk boundary continues via a
+ * server-side self-dispatch on the REGULAR function (not a Netlify
+ * `-background` function) instead of depending on the client to re-POST
+ * `auto_continue`. Composes exactly like `isAgentChatDurableBackgroundEnabled`:
+ * true only when the env flag is explicitly truthy AND the runtime is hosted
+ * AND `A2A_SECRET` is configured (the HMAC handoff authenticates the
+ * self-dispatch). False otherwise — and false means the existing
+ * client-driven `auto_continue` re-POST path is used unchanged, byte-for-byte.
+ *
+ * Deliberately independent of `isAgentChatDurableBackgroundEnabled`: an app can
+ * enable this narrower capability without opting into the full 15-min
+ * background-function worker path, and the two gates never need to agree.
+ * When BOTH would be true for a given run, the durable-background dispatch
+ * decision in `production-agent.ts` is evaluated first and takes precedence —
+ * a run already dispatched to the durable background worker chains via the
+ * existing `isBackgroundWorker` path, not this one.
+ */
+export function isAgentChatForegroundSelfChainEnabled(): boolean {
+  return (
+    isForegroundSelfChainFlagEnabled() &&
+    isHostedRuntimeForDurableBackground() &&
+    hasConfiguredA2ASecret()
+  );
+}
+
 /** Decision returned by `prepareProcessRunRequest`. */
 export type ProcessRunPreparation =
   | {