@agent-native/core 0.112.0 → 0.114.0

package/docs/AGENTS.md

@@ -25,6 +25,7 @@ pnpm action docs-search --slug actions
 pnpm action source-search --list
 pnpm action source-search --query "defineAction useActionQuery"
 pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
 ```
 
 The built-in app agent also has read-only `docs-search` and `source-search`
@@ -42,6 +43,12 @@ For source examples, read matching files under
 `node_modules/@agent-native/core/corpus/core/` or
 `node_modules/@agent-native/core/corpus/templates/`.
 
+Readable Toolkit TypeScript is available under
+`node_modules/@agent-native/toolkit/src/`. Before adapting it, read the
+generated app's `customizing-agent-native` skill. Treat installed source as a
+read-only reference, copy only the smallest UI piece into app-owned source, and
+preserve public action, state, auth, and agent-chat runtime contracts.
+
 ## What To Read First
 
 | Task                                  | Start with                                                                                               |

package/docs/content/agent-native-toolkit.mdx

@@ -122,6 +122,44 @@ Use the package path that owns the needed behavior, but design the user-facing
 settings, collaboration, sharing, team, review, and setup experiences as one
 coherent kit instead of exposing package boundaries in the app.
 
+## Customize or eject a kit {#customize-or-eject}
+
+Adopt shared behavior in this order: configure the public component or adapter,
+compose public primitives behind an app-owned wrapper, eject the smallest
+supported unit, then propose a new shared seam when the same override appears in
+multiple apps.
+
+Toolkit publishes readable, version-matched source and an ejection manifest that
+covers every public entry point. Inspect a unit before taking ownership:
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The dry run reports all files and consumer imports that will change. Applying
+the plan copies the complete source closure into the app, rewrites only the
+declared imports, and records package version, manifest digest, file hashes, and
+rewrites in the committed `agent-native.ejections.json`. Chat history is one
+such unit: an app can own its presentation while Core continues to own thread
+state, access, persistence, and chat transport.
+
+Use `agent-native eject diff <unit> --app <app>` to inspect drift. Use
+`agent-native eject restore <unit> --app <app>` to preview a return to the
+package implementation, then add `--apply`. Restore refuses when any ejected
+file or rewritten import has local edits, so app-owned changes are never
+silently discarded.
+
+The same unit contract covers first-party integration surfaces: remote MCP
+presets, workspace-connection providers, provider API definitions,
+messaging/channel adapters, setup and readiness UI, and domain packages. The
+catalog is complete by construction; a missing first-party unit fails the
+release guard. Unknown third-party packages receive an add-style blueprint.
+Protected runtime contracts are not ejectable and instead route to their public
+configuration, adapter, or extension seam.
+
 ## Foundation Pieces {#foundation-pieces}
 
 - [UI Primitives](/docs/toolkit-ui) covers the shared shadcn-style primitives

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/content/package-lifecycle.mdx

@@ -1,6 +1,6 @@
 ---
 title: Package Lifecycle
-description: Inspect, add, and eject manifest-driven Agent Native packages safely.
+description: Inspect, add, and take ownership of manifest-driven Agent Native packages and features safely.
 ---
 
 # Package lifecycle
@@ -22,6 +22,54 @@ agent-native package eject @agent-native/scheduling --apply
 writes files or runs the detected package manager. Use `--root` for a different
 project root; at a workspace root, pass `--app <name>` to select the target app.
 
+## Eject one feature
+
+Use the top-level `eject` command when the package should remain installed but
+one component, integration, or adapter needs app-specific source changes. Start
+with the customization ladder: configure a public API, compose public
+primitives, eject the smallest unit, then propose a shared seam when multiple
+apps need the same override.
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The dry run shows the complete source closure, target paths, consumer import
+rewrites, package imports that remain protected, and verification commands.
+`--apply` performs that exact plan. First-party packages publish static unit
+manifests, and release guards require every public Toolkit entry point and every
+first-party integration catalog entry to have a definition. A missing
+first-party recipe is therefore a framework coverage failure, not a reason to
+guess at files.
+
+For an unknown third-party package, the CLI emits an add-style blueprint that
+identifies the manifest information needed to make it ejectable. Protected Core
+runtime behavior is never copied: the result explains the public configuration,
+adapter, or extension seam to use instead.
+
+### Provenance, diff, and restore
+
+Every applied unit is recorded in the app root's committed
+`agent-native.ejections.json`. The record contains the source package and
+version, manifest digest, copied target hashes, and exact consumer import
+rewrites. Commit it with the app-owned source so CI, teammates, and fresh clones
+can review the same ownership boundary.
+
+```bash
+agent-native eject diff <unit> --app <app>
+agent-native eject restore <unit> --app <app>
+agent-native eject restore <unit> --app <app> --apply
+```
+
+`diff` compares the working tree with the recorded result. `restore` is also a
+dry run until `--apply`; it removes the copied files and reverses imports only
+when every file and rewrite still matches its recorded hash. If app-owned code
+has changed, restore refuses and prints the diff so no local customization is
+lost.
+
 ## Safety and idempotency
 
 Before writing, the CLI resolves every contribution and refuses missing or
@@ -66,7 +114,7 @@ Manifest entries can be `planned` before their destination ships. Doctor reports
 those as non-blocking warnings, and the codemod leaves them unchanged. An active
 move is rewritten only when the installed destination package exports its target.
 
-## Scheduling pilot
+## Whole-package ejection
 
 `@agent-native/scheduling` is the first package with the generic manifest. Add
 creates action re-export stubs, adds the schema export, copies its agent skills,
@@ -76,5 +124,7 @@ the dependency to `workspace:*`, and preserves canonical
 `@agent-native/scheduling` imports so workspace resolution selects the local
 copy.
 
-Ejecting other packages, including Pinpoint, is intentionally refused until the
-Scheduling pilot has proven the contract.
+Whole-package ejection and feature ejection solve different ownership needs.
+Use `agent-native package eject` when the complete domain package should become
+a workspace package. Use `agent-native eject <unit>` when the package should
+keep supplying upgrades for everything except one app-owned feature.

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.114.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": {
@@ -18,12 +18,18 @@
   "files": [
     "bin",
     "blueprints",
+    "agent-native.eject.json",
     "corpus",
     "dist",
     "docs",
     "!docs/content/locales/**",
     "migration-manifest.json",
     "tsconfig.base.json",
+    "src",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "src/templates/default",
     "src/templates/headless",
     "src/templates/chat",
@@ -63,6 +69,7 @@
     "./server/request-context": "./dist/server/request-context.js",
     "./server/design-token-utils": "./dist/server/design-token-utils.js",
     "./integrations": "./dist/integrations/index.js",
+    "./integrations/runtime": "./dist/integrations/runtime.js",
     "./ingestion": "./dist/ingestion/index.js",
     "./search-utils": "./dist/search-utils/index.js",
     "./search": "./dist/search/index.js",
@@ -106,6 +113,7 @@
     "./client/integrations": "./dist/client/integrations/index.js",
     "./client/navigation": "./dist/client/navigation/index.js",
     "./client/resources": "./dist/client/resources/index.js",
+    "./client/resources/runtime": "./dist/client/resources/runtime.js",
     "./client/route-chunk-recovery": "./dist/client/route-chunk-recovery/index.js",
     "./client/settings": "./dist/client/settings/index.js",
     "./client/ui": "./dist/client/ui/index.js",
@@ -132,6 +140,7 @@
     "./client/observability": "./dist/client/observability/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",
     "./client/setup-connections": "./dist/client/setup-connections/index.js",
+    "./client/setup-connections/runtime": "./dist/client/setup-connections/runtime.js",
     "./client/i18n": "./dist/client/i18n.js",
     "./client/settings/useBuilderStatus": "./dist/client/settings/useBuilderStatus.js",
     "./embedding": "./dist/embedding/index.js",
@@ -244,7 +253,10 @@
     "./tracking": "./dist/tracking/index.js",
     "./usage": "./dist/usage/store.js",
     "./connections": "./dist/connections/index.js",
+    "./connections/runtime": "./dist/connections/runtime.js",
     "./provider-api": "./dist/provider-api/index.js",
+    "./provider-api/runtime": "./dist/provider-api/runtime.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 +265,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"
@@ -267,6 +283,7 @@
       "types": "./dist/package-lifecycle/index.d.ts",
       "default": "./dist/package-lifecycle/index.js"
     },
+    "./agent-native.eject.json": "./agent-native.eject.json",
     "./migration-manifest.json": "./migration-manifest.json",
     "./code-agents": "./dist/code-agents/index.js",
     "./code-agents/transcript-normalizer": "./dist/code-agents/transcript-normalizer.js",
@@ -363,7 +380,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.8.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",
@@ -548,6 +565,7 @@
   "engines": {
     "node": ">=22.22.0"
   },
+  "agentNativeEjectManifest": "agent-native.eject.json",
   "scripts": {
     "build": "tsc && tsc -p tsconfig.cli.json && node scripts/finalize-build.mjs && node scripts/check-dist-imports.mjs",
     "dev": "tsc --watch",

package/src/a2a/agent-card.ts

@@ -0,0 +1,83 @@
+import { withConfiguredAppBasePath } from "../server/app-base-path.js";
+import { shouldAdvertiseJwtA2AAuth } from "./auth-policy.js";
+import type { A2AConfig, AgentCard } from "./types.js";
+
+export function generateAgentCard(
+  config: A2AConfig,
+  baseUrl: string,
+  endpointPath = "/_agent-native/a2a",
+): AgentCard {
+  const scopedUrl = withConfiguredAppBasePath(baseUrl);
+  const endpointUrl = withEndpointPath(scopedUrl, endpointPath);
+  const card: AgentCard = {
+    name: config.name,
+    description: config.description,
+    url: endpointUrl,
+    version: config.version ?? "1.0.0",
+    protocolVersion: "0.3",
+    capabilities: {
+      streaming: config.streaming ?? false,
+      pushNotifications: false,
+      stateTransitionHistory: true,
+    },
+    skills: config.skills,
+  };
+
+  const securitySchemes: NonNullable<AgentCard["securitySchemes"]> = {};
+  const security: NonNullable<AgentCard["security"]> = [];
+
+  // Hosted production deployments require JWT-capable A2A even before card
+  // generation can prove whether auth will use the shared A2A_SECRET or an
+  // org-scoped secret from SQL.
+  if (shouldAdvertiseJwtA2AAuth()) {
+    securitySchemes.jwtBearer = {
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+    };
+    security.push({ jwtBearer: [] });
+  }
+
+  if (config.apiKeyEnv) {
+    securitySchemes.apiKey = {
+      type: "http",
+      scheme: "bearer",
+    };
+    security.push({ apiKey: [] });
+  }
+
+  if (security.length > 0) {
+    card.securitySchemes = securitySchemes;
+    card.security = security;
+  }
+
+  return card;
+}
+
+function normalizeEndpointPath(value: string): string {
+  const normalized = value.trim().split("/").filter(Boolean).join("/");
+  return normalized ? `/${normalized}` : "";
+}
+
+function withEndpointPath(baseUrl: string, endpointPath: string): string {
+  const path = normalizeEndpointPath(endpointPath);
+  const trimmed = baseUrl.replace(/\/$/, "");
+  if (!path) return trimmed;
+
+  try {
+    const url = new URL(trimmed);
+    const pathname = url.pathname.replace(/\/$/, "");
+    if (pathname === path || pathname.endsWith(path)) {
+      return trimmed;
+    }
+    url.pathname = `${pathname === "/" ? "" : pathname}${path}`;
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    // Fall through for relative or otherwise non-URL strings.
+  }
+
+  if (trimmed.endsWith(path)) return trimmed;
+  return `${trimmed}${path}`;
+}