@agent-native/core 0.16.1 → 0.16.3

package/docs/content/workspace-connections.md

@@ -5,19 +5,26 @@ description: "Shared provider metadata, grants, and credential refs for connect-
 
 # Workspace Connections
 
-Workspace connections are the framework path toward "connect once, grant apps,
-use everywhere" integrations. The workspace/Dispatch layer records provider
-accounts once, grants apps such as Brain, Analytics, Mail, and Dispatch access,
-and lets each app's UI and agent inspect safe integration metadata before
-asking for another credential.
+Workspace connections are the framework primitive for reusable integration
+metadata. They make "connect once, grant apps, reuse credentials" possible
+without pretending every provider is fully generic. The workspace/Dispatch
+layer records provider accounts once, grants apps such as Brain, Analytics,
+Mail, and Dispatch access, and lets each app's UI and agent inspect safe
+integration metadata before asking for another credential.
 
-They have two shared pieces:
+They have three shared pieces:
 
 - A typed provider catalog that templates import to describe the external
   systems they understand.
 - A scoped SQL store for connected accounts plus per-app grants, so Dispatch or
   another workspace setup flow can connect Slack, GitHub, Google Drive, Granola,
   or another provider once and then grant individual apps access.
+- A conservative provider-reader registry/runtime that standardizes provider
+  `search`, `get`, and `listRecent` contracts and calls registered handlers
+  through granted workspace connections.
+- An app-local boundary: the shared connection owns provider identity,
+  credential refs, account metadata, and grants; each app owns the source
+  choices and interpretation that only make sense inside that app.
 
 The store records provider ids, account labels, non-secret config, credential
 reference names, health state, and grant rows. It does not run OAuth and never
@@ -25,6 +32,14 @@ returns secret values. Secret values stay in the credential vault and are
 resolved by actions at execution time from the request's user/org/workspace
 scope.
 
+That boundary is intentional. What is reusable today is provider identity,
+credential-reference resolution, per-app grants, provider readiness, safe
+account metadata, and the normalized provider-reader contract. What is not yet
+generic is most live provider API reading, OAuth flow ownership, ingestion
+cursors, source filters, sync cadence, and domain interpretation. Those stay in
+the app that owns the workflow unless a reader implementation is explicitly
+promoted to shared.
+
 Dispatch exposes the first control-plane implementation through the
 `list-workspace-connections`, `upsert-workspace-connection`, and
 `set-workspace-connection-grant` actions. App-specific actions then consume the
@@ -32,6 +47,22 @@ same records. Brain uses `list-connection-providers`; Analytics uses
 `data-source-status`; future apps should expose the same kind of readiness
 summary before asking users for duplicate provider keys.
 
+## Provider Reader Runtime
+
+The provider-reader layer is a contract first, not a promise that every
+provider has a shared live reader. Reader definitions describe supported
+operations, credential requirements, and implementation status:
+`metadata-only`, `template-owned`, or `shared`. The runtime resolves the granted
+workspace connection and credential refs for an app, calls a registered handler,
+and returns normalized items without exposing secret values.
+
+Initial providers such as Slack, GitHub, Notion, HubSpot, Gmail, Google Drive,
+and generic sources have conservative definitions. Most live handlers remain
+template-owned today, which means Brain still owns Slack/GitHub ingestion
+behavior and Analytics still owns analytics interpretation. Promote a reader to
+`shared` only when the provider-specific API calls, pagination, permissions,
+and result semantics are truly reusable across templates.
+
 ## Provider Catalog
 
 Import the catalog from `@agent-native/core/connections`:
@@ -169,15 +200,15 @@ it?"
 Use both together:
 
 1. Dispatch or another workspace setup flow creates/grants the underlying vault
-   secret.
+   secret or OAuth credential reference.
 2. The workspace connection store records the provider account, safe metadata,
    credential refs, and app grants.
 3. Each app reads provider metadata from the catalog and connection/grant
    summaries from the shared store.
 4. The app UI shows readiness: connected, granted but unhealthy, needs grant,
    missing credentials, or metadata-only.
-5. App-specific SQL stores only app-specific source ids, cursors, filters, and
-   user choices.
+5. App-specific SQL stores only app-specific source ids, cursors, filters,
+   sync windows, metric definitions, review rules, and user choices.
 6. App actions resolve credentials at execution time through granted connection
    refs and the vault, and never return secret values.
 
@@ -210,10 +241,10 @@ Use a connect-once flow before app-specific source setup:
    filters, cursors, or sync cadence.
 5. Agents inspect readiness and grants before asking for new credentials.
 
-This keeps the UX clean: users connect Slack, GitHub, HubSpot, Google Drive,
-Granola, and similar providers once, then choose which apps may use that
-connection without duplicating secrets or scattering account setup across every
-template.
+This keeps the UX clean without overclaiming the abstraction: users connect
+Slack, GitHub, HubSpot, Google Drive, Granola, and similar providers once, then
+choose which apps may use the credential/account metadata. Each app still
+decides what data to read, how to read it, and what the data means.
 
 ## Build A Reusable Connector Once
 
@@ -233,7 +264,9 @@ three layers:
 Do not duplicate OAuth/token storage in each app. The connection record should
 say "this is Acme Slack and its token lives at `SLACK_BOT_TOKEN`"; the app-local
 source should say "Brain may ingest `#product` and `#dev-fusion` from that
-Slack connection."
+Slack connection." The Slack API handler, cursor, retry policy, and
+distillation rules still belong to Brain unless and until those pieces are
+promoted to a shared provider-reader implementation.
 
 ### Dispatch control-plane setup
 
@@ -452,6 +485,19 @@ await upsertWorkspaceConnectionGrant({
 | **Mail**      | A Mail readiness action using the same catalog helper   | Mailboxes, labels, reply rules, CRM enrichment preferences        |
 | **Agents**    | App readiness actions before asking for secrets         | No secret values; only cite provider ids, grant state, next steps |
 
+Analytics data sources are app-owned even when their credentials come from a
+workspace connection. A HubSpot or GitHub grant tells Analytics which provider
+account it may use; the Analytics app still owns the source-of-truth decision,
+warehouse-vs-live-provider choice, metric definitions, dashboard semantics, and
+saved analyses.
+
+Brain's "ask across everything" direction should be federated rather than
+centralized. Brain can answer from reviewed Brain knowledge and raw captures it
+is allowed to search. When a question needs live app-owned data such as current
+analytics metrics, mail state, calendar availability, or Dispatch runtime
+policy, Brain should delegate to the specialized app agent or action and cite
+that result instead of trying to own every app's reader locally.
+
 Agents should follow a simple rule: if a user asks to connect Slack, GitHub,
 HubSpot, Gmail, Google Drive, Granola, or another shared provider, inspect the
 workspace connection catalog first. If the provider is `connected`, use it. If
@@ -504,6 +550,9 @@ layer:
 - Federated search can ask for providers with `search`, `docs`, `messages`,
   `meetings`, `crm`, or `code` capabilities instead of hardcoding every app's
   connector list.
+- Provider-specific readers, OAuth refresh flows, ingestion checkpoints, and
+  app-owned data models can become shared later, but they are not implied by a
+  workspace connection today.
 
 Keep the boundary strict: provider metadata is safe to show; credential values
 stay in the vault.

package/docs/content/workspace-management.md

@@ -187,7 +187,7 @@ The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It
 | Who can access secrets          | —                             | Vault policy, grants, request workflow                       |
 | What instructions agents follow | —                             | Global workspace resources (AGENTS.md, instructions, skills) |
 | Which agents are shared         | —                             | Workspace agent profiles                                     |
-| Integration inventory           | —                             | Integrations catalog                                         |
+| Integration inventory           | —                             | Workspace connections and integrations catalog               |
 | Runtime change approval         | —                             | Dispatch approval flow                                       |
 | Audit trail                     | `git log` / `git blame`       | Vault audit + dispatch audit logs                            |
 | Messaging & routing             | —                             | Slack / Telegram integration                                 |
@@ -197,7 +197,11 @@ The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It
 ### What Dispatch Manages
 
 - **Vault** — store credentials centrally and sync on demand. The default policy makes all vault keys available to all workspace apps; manual mode requires specific app grants. Non-admins can request access; admins approve.
-- **Integrations catalog** — see which credentials each app needs, what's configured, what's missing, what's granted from the vault.
+- **Reusable integrations** — connect provider accounts once, store safe
+  credential refs and account metadata, and grant apps access without copying
+  secrets. Dispatch is the control plane for provider inventory, repair,
+  grants, and audit; the vault/secrets layer owns values; each app keeps its
+  own source configuration and interpretation.
 - **Workspace resources** — manage global skills, always-on guardrail instructions, reusable agent profiles, and reference resources inherited by apps. Use `AGENTS.md` or `instructions/<slug>.md` for instructions loaded every turn, `skills/<slug>/SKILL.md` for on-demand skills, and `context/<slug>.md` for brand/company/product knowledge. Scope to All apps for workspace defaults; apps read those defaults at runtime with no copy or manual sync step, and app shared or personal resources can override locally. The Resources page highlights the starter global context files, can restore missing starter files, and each app card shows the exact inherited/granted resources that app receives.
 - **Approvals** — require review before runtime changes (destinations, settings) take effect.
 - **Audit** — full history of secret access, grants, syncs, and changes.
@@ -253,6 +257,9 @@ For a new workspace, after running `agent-native create`:
 - [ ] Add shared secrets to the vault (API keys, OAuth credentials, etc.)
 - [ ] Keep the default all-apps vault policy or switch to manual per-app grants
 - [ ] Sync vault secrets to push them to apps
+- [ ] Register reusable workspace connections for shared provider accounts, then
+      grant apps such as Brain, Analytics, Mail, or Dispatch only when they need
+      that account
 - [ ] Add workspace-wide skills, guardrail instructions, and brand/company reference resources via the Resources page: `context/company.md`, `context/brand.md`, `context/messaging.md`, `instructions/guardrails.md`, and `skills/company-voice/SKILL.md`
 - [ ] Configure the approval policy and approver emails
 - [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications

package/docs/content/workspace.md

@@ -283,11 +283,12 @@ Users can edit these memory files directly in the Workspace tab — they're regu
 
 ## Workspace Connections {#workspace-connections}
 
-Workspace Connections are the reusable integration metadata layer for apps that
-need the same third-party account. A connection records the provider, account
-label, status, scopes, allowed app slugs, and credential references in portable
-SQL. Secrets stay in the scoped credential store; connection records should only
-point at credential keys such as `SLACK_BOT_TOKEN` or `GITHUB_TOKEN`.
+Workspace Connections are the reusable integration framework primitive for apps
+that need the same third-party account. A connection records provider identity,
+account labels, status, scopes, app grants, and credential references in
+portable SQL. Secrets stay in the scoped credential store; connection records
+should only point at credential keys such as `SLACK_BOT_TOKEN` or
+`GITHUB_TOKEN`.
 
 This is the foundation for “connect once, use everywhere”: Brain can ingest
 approved repositories, Analytics can analyze the same provider later, and
@@ -295,6 +296,12 @@ Dispatch can remain the control plane for sharing credentials and policy. The
 initial API lives in `@agent-native/core/workspace-connections` and is scoped by
 the active request user/org.
 
+The boundary is deliberate: reusable connections own provider identity and
+grants; app-local source config still belongs to the app. Brain decides which
+channels, repositories, captures, review gates, and citations are allowed.
+Analytics decides which source is authoritative for a metric and stores the
+dashboard, dictionary, and analysis context.
+
 See [Workspace Connections](/docs/workspace-connections) for the reusable
 connector pattern, app grant/readiness APIs, and concrete Slack, HubSpot, and
 GitHub examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",

package/src/templates/workspace-root/AGENTS.md

@@ -60,15 +60,15 @@ coding agents can discover the same workspace-wide guidance from the root.
 - Do not satisfy a new-app request by adding a route, page, component, or file
   to `apps/starter` or another existing app unless the user explicitly asks to
   modify that existing app.
-- Treat first-party apps such as Mail, Calendar, Analytics, and Dispatch as
+- Treat first-party apps such as Mail, Calendar, Analytics, Brain, and Dispatch as
   existing hosted/connected neighbors available through links and A2A/default
-  connected agents. For example, Mail, Calendar, and Analytics already exist at
+  connected agents. For example, Mail, Calendar, Analytics, and Brain already exist at
   `https://mail.agent-native.com`, `https://calendar.agent-native.com`, and
-  `https://analytics.agent-native.com`.
-- If a new app needs to use Mail, Calendar, Analytics, or similar first-party
+  `https://analytics.agent-native.com`, and `https://brain.agent-native.com`.
+- If a new app needs to use Mail, Calendar, Analytics, Brain, or similar first-party
   data/agents, build only the genuinely new workflow and delegate/link to those
   existing apps. Do not create wrapper apps, child apps, nested template copies,
-  or cloned Mail/Calendar/Analytics implementations inside the new app just to
+  or cloned Mail/Calendar/Analytics/Brain implementations inside the new app just to
   provide access.
 - Only create a first-party app copy when the user explicitly asks for a
   customized fork/copy of that app. Otherwise prefer the hosted/shared app so

package/src/templates/workspace-root/README.md

@@ -116,7 +116,7 @@ separate workspace app registry to edit. React Router apps must preserve
 For requests phrased as creating an "agent", classify the scope first: simple
 recurring Dispatch behavior can stay in Dispatch, while a robust app-like
 teammate should become a real workspace app listed with the rest of the apps.
-First-party apps such as Mail, Calendar, Analytics, and Dispatch should be
+First-party apps such as Mail, Calendar, Analytics, Brain, and Dispatch should be
 treated as existing hosted or connected neighbors. If a new app needs access to
 their data or agents, link/delegate to those apps through the workspace/A2A
 path rather than creating wrapper apps, child apps, or cloned template copies