@agent-native/core 0.87.0 → 0.88.0

package/docs/content/locales/zh-TW/agent-native-toolkit.mdx

@@ -0,0 +1,61 @@
+---
+title: "Agent-Native 工具包"
+description: "用於協作、設定、分享、導覽、線上狀態、歷史、配置和 Agent UX 的可重用套件。"
+---
+
+# Agent-Native 工具包
+
+Agent-Native 應用程式不應重複建置 workspace 的通用能力。應用程式負責自己的領域模型、
+領域 actions 和產品視圖。Framework 與 `@agent-native/toolkit` 負責每個應用程式都應繼承的
+可重用產品表面：協作、分享、設定、導覽、組織、配置、Agent UX、歷史和營運可見性。
+
+使用者應該只學會一種分享方式、一種連接金鑰的方式、一種看到 Agent 一起編輯的方式、一個設定入口，
+以及一種理解變更的方式。
+
+## 工具包契約 {#toolkit-contract}
+
+當行為符合以下條件時，應移到 toolkit：
+
+- **Workspace 層級** - 使用者期待所有應用程式都一致。
+- **Agent 可見** - Agent 需要透過 actions、instructions 或 application state 使用同一能力。
+- **受治理** - 權限、audit、secrets、組織政策、billing 或分享規則會參與。
+- **重複出現** - 兩個應用程式已經建了相似 UI 或邏輯。
+- **非領域專屬** - 應用程式提供 resource 名稱與 actions，但互動模式是通用的。
+
+如果行為綁定領域模型、專屬 workflow 或應用程式自己的心智模型，就保持 app-local。
+
+## 可重用套件 {#reusable-kits}
+
+- **Settings kit** - account、workspace、AI models、LLM keys、connections、secrets、
+  usage、notifications、changelog 和 app preferences 的標準 tabs。持久設定放在 Settings；
+  Agent sidebar 只保留情境 quick controls 與 deep links。
+- **Collaboration kit** - real-time editing、Yjs docs、presence、agent presence、live
+  cursors、remote selections、recent edit highlights 和 shared undo/redo。請參閱
+  [Real-Time Collaboration](/docs/real-time-collaboration)。
+- **Sharing kit** - 用一個隱私與權限模型處理 private、workspace、org、public link、invites、
+  roles、expirations 和 agent-readable access。請參閱 [Sharing & Privacy](/docs/sharing)。
+- **Navigation and command kit** - app shell、nav、breadcrumbs、app switcher、command
+  palette、recents、pinned resources 和 search。
+- **Organization kit** - folders、tags、favorites、archive、trash、ownership、membership
+  和 common metadata。
+- **Setup and connections kit** - API keys、OAuth、connections、model readiness、
+  missing secrets 和 declarative onboarding。請參閱
+  [Workspace Connections](/docs/workspace-connections)。
+- **Agent UX kit** - sidebar、composer、staged context、mentions、voice、human approval、
+  generative UI、progress 和 Agent-visible state。
+- **History and recovery kit** - audit log、activity feed、version history、checkpoints、
+  undo、redo、restore 和 proof-of-done。請參閱 [Audit Log](/docs/audit-log)。
+- **Comments and review kit** - anchored comments、pins、mentions、review requests、
+  resolved threads 和 Agent follow-up tasks。
+- **Workflow and observability kit** - notifications、approvals、background runs、
+  recurring jobs、traces、evals、feedback 和 run timelines。請參閱
+  [Observability](/docs/observability)。
+
+## 實作順序 {#implementation-order}
+
+1. 將持久設定合併到標準 Settings tabs。
+2. 用共享 adapters 統一 collaboration、presence、agent presence、undo/redo 和 real-time editing。
+3. 將 navigation、commands、recents、favorites、folders、tags、archive 和 trash 移入共享 primitives。
+4. 讓所有可分享 resource 註冊到同一 permissions 和 agent-readable access 模型。
+5. 為每個 collaborative resource 提供一致的 activity、comments、review、restore 和 audit 體驗。
+6. 統一 notifications、approvals、run status、traces、evals 和 feedback。

package/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.87.0",
+  "version": "0.88.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": {
@@ -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",

package/src/templates/workspace-core/.agents/skills/agent-native-toolkit/SKILL.md

@@ -0,0 +1,92 @@
+# Agent-Native Toolkit
+
+Use this skill when deciding whether app chrome, settings, collaboration,
+sharing, navigation, organization, setup, history, comments, or agent UX should
+be built app-locally or moved into reusable framework/toolkit pieces.
+
+## Core Rule
+
+Apps own domain models, domain actions, and product-specific workflows. The
+framework and `@agent-native/toolkit` own repeated workspace behavior users
+expect to work the same everywhere.
+
+Move behavior into shared toolkit primitives when it is:
+
+- workspace-wide, such as settings, nav, search, org membership, or setup
+- agent-visible, such as context, actions, run progress, or proof-of-done
+- governed, such as secrets, permissions, sharing, audit, or billing
+- repeated by two or more apps
+- not tied to one domain model
+
+Keep behavior app-local when the abstraction would hide important domain
+language or make a simple app-specific workflow harder to understand.
+
+## Settings Direction
+
+Durable settings belong in the Settings app or a registered settings route. The
+agent sidebar should not become a second settings app. It can show contextual
+quick controls and deep links such as:
+
+- `/settings/ai`
+- `/settings/connections`
+- `/settings/secrets`
+- `/settings/usage`
+- `/settings/apps/:appId`
+
+When adding a new API key, OAuth grant, provider connection, model selector, app
+preference, notification preference, or usage/billing surface, register it as a
+settings tab or app settings panel first. Only add sidebar UI when it is needed
+in the moment of agent use.
+
+## Reusable Kits
+
+- **Settings kit**: account, workspace, AI models, LLM keys, connections,
+  secrets, usage, notifications, changelog, and app-specific panels.
+- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
+  remote selections, recent edit highlights, real-time sync indicators, and
+  undo/redo grouping.
+- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
+  expirations, agent-readable links, and resource registration.
+- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
+  command palette entries, recent resources, pinned resources, and global search.
+- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
+  membership, and common resource metadata.
+- **Setup and connections kit**: declarative setup requirements, model readiness,
+  missing-secret states, OAuth grants, and provider connection health.
+- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
+  approval, generative UI, progress, and screen-state exposure.
+- **History and recovery kit**: audit log, activity feed, version history,
+  checkpoints, undo, redo, restore, and proof-of-done.
+- **Comments and review kit**: anchored comments, pins, mentions, review
+  requests, resolved threads, agent follow-up tasks, and notifications.
+- **Workflow and observability kit**: notifications, approvals, scheduled work,
+  background runs, recurring jobs, traces, evals, feedback, and run timelines.
+
+## Implementation Checklist
+
+When adding or refactoring one of these areas:
+
+1. Search existing framework and template code for duplicated UI or actions.
+2. Decide the shared contract: data shape, action API, React component/hook, and
+   app adapter points.
+3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
+4. Expose the same capability to the UI and agent through actions or documented
+   client helpers.
+5. Register app-specific labels, routes, resource adapters, and settings panels
+   instead of hardcoding app names in core UI.
+6. Update docs and relevant skills so future apps discover the shared path.
+
+## Related Skills
+
+Read these alongside this skill when the work touches the specific area:
+
+- `sharing`
+- `real-time-collab`
+- `real-time-sync`
+- `client-side-routing`
+- `context-awareness`
+- `onboarding`
+- `secrets`
+- `audit-log`
+- `observability`
+- `frontend-design`