@agent-native/core 0.112.0 → 0.113.0

package/docs/content/integrations.mdx

@@ -409,8 +409,69 @@ these built-in providers:
 These entries are available to actions through the shared
 `provider-api-catalog`, `provider-api-docs`, and `provider-api-request` pattern.
 They do not imply that the provider also appears in the remote MCP picker.
-Custom provider registrations can extend this action catalog without changing
-the built-in list above.
+
+### Reuse the Core action factories {#provider-api-factories}
+
+Provider API actions are reusable Core primitives, not an implementation to
+copy between apps. App builders should keep a thin action file for each stable
+app-facing action id, then delegate its behavior to the shared factory. That
+keeps app-specific provider enums, descriptions, HTTP exposure, and
+`toolCallable` choices intact while Core owns request safety, auditing,
+credential injection, and staging.
+
+```ts
+import { createProviderApiRequestAction } from "@agent-native/core/provider-api/actions/provider-api";
+
+import { MY_APP_ID, getMyProviderApiRuntime } from "../server/provider-api";
+
+export default createProviderApiRequestAction(getMyProviderApiRuntime(), {
+  appId: MY_APP_ID,
+  schema: myProviderRequestSchema,
+  description: "Call a configured provider API for this app.",
+  http: { method: "POST" },
+  toolCallable: false,
+});
+```
+
+Use `createProviderApiCatalogAction` and `createProviderApiDocsAction` for the
+other two actions. Their runtime is the app's provider runtime; the wrapper is
+where an app deliberately narrows provider ids or preserves its own public
+action contract. Do not reimplement the request, catalog, or docs behavior in
+each template.
+
+For data too large to keep in a response, pass `stageAs` to the request action
+and expose thin wrappers around `createQueryStagedDatasetAction`,
+`createListStagedDatasetsAction`, and `createDeleteStagedDatasetAction` (or the
+combined `createStagedDatasetActions`). Set the same `appId` on request and
+staged-dataset factories. Core scopes staged data to that app and the current
+credential owner, so one user's scratch data cannot be queried or deleted by a
+different user or app.
+
+### Credentials and custom providers {#provider-api-authority}
+
+The provider runtime is the credential authority. It resolves a scoped
+workspace connection, OAuth account, or secret and injects authentication into
+an allowed provider request. Action arguments, provider registrations, and
+docs may name credential keys or connection ids, but must never accept, store,
+or log credential values. Use the app's secrets and onboarding surfaces to
+collect credentials; use workspace grants when an account should be shared
+across apps.
+
+Apps can add their own provider integrations. Start with a thin wrapper over a
+runtime that recognizes the provider, then use the catalog and docs actions to
+make its safe capabilities discoverable. Custom-provider registration is
+deliberately opt-in:
+
+```ts
+createProviderApiActions(runtime, { customProviderRegistration: true });
+```
+
+This exposes the registration action only when the app chooses to support it.
+Registration stores endpoint and credential-key
+metadata, never secret values, and organization-scoped mutations require the
+runtime's authorization checks. A custom provider registration is not a remote
+MCP preset or a webhook adapter; add those separate integrations only when the
+product needs them.
 
 ## Keep the directory honest {#keep-current}
 

package/docs/design/provider-integration-authority.md

@@ -0,0 +1,117 @@
+# ADR: Defer `defineIntegration` Until Authority Boundaries Converge
+
+Status: Accepted
+
+Date: 2026-07-19
+
+## Context
+
+Several framework surfaces describe a provider or integration: shared workspace
+connections, Dispatch Vault secrets, custom provider APIs, and managed messaging
+adapters. They are related, but they do not have one interchangeable authority
+model. A generic `defineIntegration(...)` API would imply a shared lifecycle for
+credentials, grants, OAuth installation, request dispatch, and user-visible
+setup before that lifecycle exists.
+
+The immediate cost would be an attractive abstraction that either bypasses an
+existing access check or becomes a thin facade over incompatible stores. The
+more serious cost is migration risk: live OAuth and Slack installations cannot
+be lost, silently disconnected, or made invisible while an API is normalized.
+
+## Decision
+
+Do not add `defineIntegration` yet. Keep each existing authority in its current
+owner and use narrow bridges only where the implementation is demonstrably
+shared. A future integration definition must compose existing authority
+contracts; it must not replace them with a new credential or access model.
+
+## Authority Boundary Map
+
+| Surface                          | Current authority          | What it owns                                                                                                                  | Boundary for a future abstraction                                                                                                                                       |
+| -------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Workspace connections and grants | Core workspace-connections | Shared provider connection metadata, app grants, scoped credential resolution, and readiness                                  | An integration may request a connection only through its app grant. It cannot treat a provider label as access to every workspace credential.                           |
+| Dispatch Vault                   | Dispatch                   | Workspace secret lifecycle, requests, approvals, grants, audit, and sync into app credential scopes                           | Vault is a credential-distribution authority, not a provider transport or OAuth-install store. A generic integration API must not bypass Vault approval or audit paths. |
+| Custom provider registry         | Core provider-api          | Scoped provider metadata, allowed hosts, auth descriptor, docs links, SSRF validation, and request-time credential resolution | Registry rows describe an allowed outbound API. They do not grant messaging installation, workspace connection, or Vault access by themselves.                          |
+| Messaging adapters               | Core integrations          | Signed inbound webhooks, platform identity, managed installations, token health, scopes, queues, and outbound delivery        | A messaging adapter is a runtime channel with its own installation and webhook contract, not just another HTTP provider.                                                |
+
+These boundaries deliberately permit one product to use more than one surface:
+for example, a workspace-granted connection can supply provider credentials,
+while Dispatch governs a separately shared secret, and a messaging adapter owns
+an inbound channel installation. No generic record may collapse those distinct
+authorities into one unscoped token reference.
+
+## Consequences
+
+- Core remains the authority for runtime request context, credential resolution,
+  SSRF protection, OAuth tokens, workspace-connection grants, and managed
+  messaging installations.
+- Dispatch remains the authority for Vault policy, approval, audit, and
+  distribution. Provider code must consume its scoped credential result rather
+  than read Vault records directly.
+- Toolkit remains presentation-only. It can render readiness and setup supplied
+  by Core adapters, but must not import Core runtime contracts or own provider
+  credentials.
+- Reusable low-level helpers are still encouraged when they preserve the owner
+  of the data and access decision. Examples include OAuth exchange helpers,
+  provider response normalization, and a hardened outbound-delivery primitive.
+
+## Deferred Work And Required Follow-ups
+
+### Provider API registration reads
+
+`provider-api-register` has mutation-side authorization for custom-provider
+scope. Before making registration a general integration primitive, add and test
+equivalent request-context scoping for its list and get operations. The
+operations must resolve the caller's user/org context and return only providers
+visible in that scope; callers must not be able to select an arbitrary
+`scopeId` to enumerate or read another tenant's registry entries.
+
+### Clips Slack migration
+
+Clips currently has a product-specific Slack unfurl installation: its own
+`slack_installations` metadata, app-secret token references, `link_shared`
+webhook routing, and unfurl-only scopes. Core managed messaging installs use a
+different table and encrypted token-bundle format. Do not replace the Clips
+path until all of the following are true:
+
+1. The target store preserves the Clips team/app lookup, owner/org access, and
+   unfurl-only scopes.
+2. Webhook handling can dual-read the new managed installation and the legacy
+   Clips row, with the existing row as a fallback until migration completion.
+3. Existing app-secret references are imported or safely resolved without
+   exposing tokens to route responses.
+4. List, status, disconnect, and signed `link_shared` delivery have migration
+   coverage using an existing installation.
+5. Production telemetry proves that the new read path handles live events
+   before legacy rows or secret references are removed.
+
+### Zoom
+
+Zoom is not currently a Core provider-api, workspace-connection, or managed
+messaging catalog entry. It is a real OAuth capability in the Calendar template
+backed by the Scheduling package's video-provider API and Core OAuth-token
+storage. Treat Zoom as a later provider-catalog candidate, not evidence that a
+generic integration API already has a common model. Revisit catalog inclusion
+only when there is a defined owner for connection grants, credential setup,
+token refresh, and the Calendar/Scheduling compatibility contract.
+
+## Revisit Criteria
+
+Reconsider `defineIntegration` only when all of these are satisfied:
+
+1. At least two production consumers share the same lifecycle, not merely a
+   provider name or an OAuth exchange endpoint.
+2. The API has explicit ports for request context, authorization, credential
+   resolution, token storage, outbound-host policy, and audit ownership.
+3. Workspace-connection grants, Dispatch Vault policy, custom-provider scope,
+   and messaging-install access are represented as distinct inputs or are
+   explicitly inapplicable; none is inferred from a provider id.
+4. Each migrated surface has a documented compatibility path, dual-read or
+   backfill plan where durable data exists, rollback behavior, and focused
+   tests for existing installations/connections.
+5. The public API can state what it does not own: domain-specific routes,
+   provider-specific payloads, app data models, and presentation UI remain with
+   the appropriate app or Toolkit adapter.
+
+Until then, prefer focused Core exports and app adapters over a universal
+registration API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.112.0",
+  "version": "0.113.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": {
@@ -245,6 +245,7 @@
     "./usage": "./dist/usage/store.js",
     "./connections": "./dist/connections/index.js",
     "./provider-api": "./dist/provider-api/index.js",
+    "./provider-api/gong": "./dist/provider-api/gong.js",
     "./provider-api/corpus-jobs": "./dist/provider-api/corpus-jobs.js",
     "./provider-api/corpus-jobs-store": "./dist/provider-api/corpus-jobs-store.js",
     "./provider-api/staging": "./dist/provider-api/staging.js",
@@ -253,7 +254,11 @@
     "./provider-api/actions/query-staged-dataset": "./dist/provider-api/actions/query-staged-dataset.js",
     "./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/staged-datasets": "./dist/provider-api/actions/staged-datasets.js",
     "./provider-api/actions/github-repo-files": "./dist/provider-api/actions/github-repo-files.js",
+    "./provider-api/actions/provider-api": "./dist/provider-api/actions/provider-api.js",
+    "./provider-api/actions/provider-api-audit": "./dist/provider-api/actions/provider-api-audit.js",
+    "./provider-api/actions/custom-provider-registration": "./dist/provider-api/actions/custom-provider-registration.js",
     "./data-programs": {
       "types": "./dist/data-programs/index.d.ts",
       "default": "./dist/data-programs/index.js"
@@ -363,7 +368,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.4.4",
-    "@agent-native/toolkit": "^0.6.0"
+    "@agent-native/toolkit": "^0.7.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.agents/skills/actions/SKILL.md

@@ -121,18 +121,38 @@ action trio instead:
   provider host, injects configured credentials, blocks private/internal URLs,
   and redacts secrets.
 
-Use `@agent-native/core/provider-api` as the shared substrate. A template should
-only add a thin credential adapter when it has app-specific credential lookup
-rules. If the app stores a built-in provider's OAuth grant under a narrower
-local provider id, use the runtime's `oauthProviderOverrides` instead of
-duplicating the provider config. If credentials are stored on shareable/resource
-rows rather than in the shared credential or OAuth-token stores, build a resolver
-that enforces those access checks before exposing raw provider requests. Keep
-`provider-api-request` `http: false` unless you have a separate UI permission
-model for arbitrary provider writes. Specific actions such as `search-records`,
-`search-emails`, or `sync-source` are convenience shortcuts, not capability
-limits; agents should fall back to the provider API trio when a question
-requires an endpoint or filter that the shortcut does not model.
+Use `@agent-native/core/provider-api` as the shared substrate, and build these
+actions as thin factory imports rather than copying `defineAction` schemas and
+handlers into each template:
+
+```ts
+import {
+  createProviderApiCatalogAction,
+  createProviderApiDocsAction,
+  createProviderApiRequestAction,
+} from "@agent-native/core/provider-api/actions/provider-api";
+import {
+  createDeleteStagedDatasetAction,
+  createListStagedDatasetsAction,
+  createQueryStagedDatasetAction,
+} from "@agent-native/core/provider-api/actions/staged-datasets";
+```
+
+Pass the app's existing provider runtime to the provider factories, and pass
+its app id to the staged-dataset factories. Keep app-specific descriptions,
+provider allow-lists, HTTP/tool-callability settings, and credential adapters
+as factory options. Only add a thin credential adapter when the app has
+app-specific credential lookup rules. If the app stores a built-in provider's
+OAuth grant under a narrower local provider id, use the runtime's
+`oauthProviderOverrides` instead of duplicating provider config. If credentials
+are stored on shareable/resource rows rather than in the shared credential or
+OAuth-token stores, build a resolver that enforces those access checks before
+exposing raw provider requests. Keep `provider-api-request` `http: false`
+unless a separate UI permission model authorizes arbitrary provider writes.
+Specific actions such as `search-records`, `search-emails`, or `sync-source`
+are convenience shortcuts, not capability limits; agents should fall back to
+the provider API trio when a question requires an endpoint or filter that the
+shortcut does not model.
 
 This is a framework tenet. The safety boundary should be provider host
 allow-listing, credential scoping, auth injection, private-network blocking,

package/src/templates/chat/.agents/skills/agent-native-docs/SKILL.md

@@ -37,6 +37,7 @@ pnpm action docs-search --slug <slug>
 pnpm action docs-search --list
 pnpm action source-search --query "<pattern>"
 pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
 pnpm action source-search --list
 ```
 
@@ -56,6 +57,13 @@ under `node_modules/@agent-native/core/docs/content/`. For source examples,
 read files under `node_modules/@agent-native/core/corpus/core/` or
 `node_modules/@agent-native/core/corpus/templates/`.
 
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
+`customizing-agent-native` before copying a shared component: inspect package
+source as a read-only reference, copy only the smallest UI piece into app-owned
+source, and preserve public actions, application state, auth, and agent-chat
+runtime contracts. Never edit `node_modules` or deep-import its private source.
+
 ## Useful Slugs
 
 | Need | Slugs |
@@ -74,3 +82,5 @@ read files under `node_modules/@agent-native/core/corpus/core/` or
 - Do not add custom REST wrappers for app data before reading `actions`.
 - Do not add inline LLM calls before reading `using-your-agent` and
   `agent-surfaces`.
+- Do not copy framework runtime internals when a public API or narrow UI copy
+  will do; read `customizing-agent-native` for the supported override ladder.

package/src/templates/chat/.agents/skills/customizing-agent-native/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: customizing-agent-native
+description: >-
+  How to adopt, compose, or selectively copy Agent Native UI into app-owned
+  code. Use when overriding shared components, customizing a template, adding
+  UI to chat or headless apps, or inspecting installed framework source.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Customizing Agent Native
+
+## Rule
+
+Start with the public component and its props, slots, callbacks, and stable
+class names. If those seams are not enough, copy the smallest useful reference
+implementation into the app and make that copy app-owned. Never edit
+`node_modules`, deep-import a private source file at runtime, or patch an
+`@agent-native/*` package.
+
+Use this order:
+
+1. Configure the public component.
+2. Compose public primitives behind a local app component.
+3. Copy one component or helper into app source and change the app import.
+4. Propose a new Toolkit seam when the same override is useful in two apps.
+
+Copying is for intentional product customization, not for hiding an upgrade
+failure or replacing Core runtime behavior.
+
+## Find The Installed Implementation
+
+Use the source that matches the installed package version:
+
+```bash
+pnpm action docs-search --query "<component or feature>"
+pnpm action source-search --query "<component or symbol>"
+rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
+rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
+```
+
+- Toolkit publishes readable TypeScript under
+  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
+- Core and first-party template source lives under
+  `node_modules/@agent-native/core/corpus/core/` and
+  `node_modules/@agent-native/core/corpus/templates/`.
+- Treat those trees as read-only references. Copy files into an app directory
+  such as `app/components/`, then import the local copy.
+
+When a copied component imports sibling helpers, copy only the required
+siblings or replace them with public package imports. Do not copy an entire
+package or template to change one surface.
+
+## Preserve The Agent-Native Contract
+
+UI ownership may change; product contracts should not:
+
+- Keep app operations in `defineAction` actions and call them through
+  `useActionQuery`, `useActionMutation`, or another named client helper.
+- Keep navigation, selection, and focused-object state visible through the
+  existing application-state keys.
+- Keep AI work in the shared agent chat instead of adding direct LLM calls.
+- Keep auth, access checks, persistence, chat transport, and agent execution in
+  Core. Do not copy those runtimes into the app.
+- Keep local adapters narrow so package upgrades still improve every surface
+  the app has not intentionally taken ownership of.
+
+## App Shapes
+
+- **Template app:** begin with its existing local adapters and domain UI. Use
+  Toolkit for repeated workspace UI; copy only the piece being customized.
+- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
+  Core. Compose or copy Toolkit presentation such as chat-history UI around it.
+- **Headless app:** stay action-first while no UI is needed. When adding a UI,
+  use the Chat template as the on-ramp or add Toolkit components without
+  replacing the existing actions.
+- **Workspace:** put one-app overrides in that app. Promote a local component
+  to `packages/shared` only when multiple workspace apps use it.
+
+## After Copying
+
+- Remove unused dependencies and imports from the copied file.
+- Keep visible text in the app's localization catalogs.
+- Run the app's formatter, typecheck, and focused tests.
+- Re-check the installed source during future package upgrades; the app-owned
+  copy does not receive upstream fixes automatically.
+
+## Don't
+
+- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
+- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
+- Don't copy Core auth, DB, action, agent-loop, or transport internals.
+- Don't fork a full template when a prop, slot, wrapper, or one-file copy works.
+
+## Related Skills
+
+- `agent-native-docs` — version-matched docs and source lookup
+- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
+- `self-modifying-code` — safe app source edits
+- `upgrade-agent-native` — supported package upgrade path
+- `adding-a-feature` — UI/action/instructions/application-state parity

package/src/templates/chat/.agents/skills/self-modifying-code/SKILL.md

@@ -35,8 +35,14 @@ Tier 4 includes **all** of the following — not only editing package source:
 - Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
 - `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
   target any `@agent-native/*` package
-- Local patches, vendored copies, or invented "dispatch/core behavior"
-  shims meant to paper over a version skew or failed upgrade
+- Local package patches or invented "dispatch/core behavior" shims meant to
+  paper over a version skew or failed upgrade
+
+This does not prohibit intentional app-owned UI customization. When public
+props and composition are insufficient, the `customizing-agent-native` skill
+allows copying the smallest reference UI component from the installed source
+into the app. The copy must use public runtime contracts and must not replace
+Core auth, DB, actions, agent execution, or transport behavior.
 
 When an older branch needs current packages, use **`agent-native upgrade`**
 (see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
@@ -88,6 +94,8 @@ inline strings in components.
 - Don't modify `.env` files or files containing secrets
 - Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
   `@agent-native/*` package internals (including under `node_modules`)
+- Don't confuse a read-only reference copy with editing package internals: use
+  `customizing-agent-native` for selective app-owned UI adoption
 - Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
   `@agent-native/*` to "make the app run" after a version bump
 - Don't invent local dispatch/core behavior overrides when upgrade fails —
@@ -99,6 +107,7 @@ inline strings in components.
 ## Related Skills
 
 - **upgrade-agent-native** — supported path to bring an older app/workspace current
+- **customizing-agent-native** — safe selective adoption of installed reference UI
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/src/templates/chat/.agents/skills/upgrade-agent-native/SKILL.md

@@ -63,6 +63,11 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Re-run `agent-native upgrade` or `pnpm typecheck`
    - Stop and ask the user if you cannot fix the app-level error
 
+   Intentional app-level UI customization is a separate workflow. Read
+   `customizing-agent-native` when the product needs to own a selectively
+   copied component; do not use that path to reproduce framework runtime
+   behavior or hide version skew.
+
 4. **Dry-run / partial runs**
 
    ```bash
@@ -91,4 +96,5 @@ install → refresh scaffold skills → verify, then fix **app** code only.
 
 - **self-modifying-code** — Tier 4: framework packages are off limits
 - **agent-native-docs** — version-matched docs after the bump
+- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
 - **portability** — keep app code provider-agnostic across upgrades

package/src/templates/chat/AGENTS.md

@@ -53,10 +53,13 @@ workflow needs durable UI around the conversation.
   first-party template implementation examples.
 - Prefer those installed docs over memory or public docs when package APIs,
   generated-app conventions, workspaces, actions, or agent surfaces are involved.
+- Read `customizing-agent-native` before overriding the chat shell or shared UI.
+  Keep Core thread/runtime behavior, try public props and composition first,
+  and copy only the smallest presentation component into app-owned source.
 
 ## Skills
 
 Read the relevant root skill before implementation: `adding-a-feature`,
-`actions`, `agent-native-docs`, `storing-data`, `real-time-sync`, `security`,
-`delegate-to-agent`, `frontend-design`, `shadcn-ui`, and
+`actions`, `agent-native-docs`, `customizing-agent-native`, `storing-data`,
+`real-time-sync`, `security`, `delegate-to-agent`, `frontend-design`, `shadcn-ui`, and
 `self-modifying-code`.