@tangle-network/agent-integrations 0.25.1 → 0.25.2

package/README.md

@@ -25,6 +25,7 @@ provider SDK.
 - [Product Adoption](#product-adoption)
 - [Provider Strategy](#provider-strategy)
 - [Executable Coverage](#executable-coverage)
+- [Product Hub Ownership](#product-hub-ownership)
 - [Examples](#examples)
 - [Security Model](#security-model)
 - [Development](#development)
@@ -48,9 +49,9 @@ provider SDK.
   executable backend state explicit.
 - A canonical registry that deduplicates overlapping catalogs, keeps support
   tiers explicit, and reports auth/category conflicts.
-- App/agent manifests, grants, and sandbox bundles so Builder, generated apps,
-  domain agents, Blueprint Agent, and executor-backed runtimes can reuse the
-  same user-owned connections safely.
+- App/agent manifests, grants, and sandbox bundles so generated apps, domain
+  agents, and executor-backed runtimes can reuse the same user-owned
+  connections safely.
 - Workflow trigger installation and normalized event dispatch for non-agent UI
   automation, sync jobs, webhooks, and product workflows.
 - Approval persistence, audit events, healthchecks, credential resolution,
@@ -246,7 +247,7 @@ Generated app code should use the tiny client instead of raw provider tokens:
 
 ```ts
 const integrations = createTangleIntegrationsClient({
-  endpoint: 'https://id.tangle.tools',
+  endpoint: 'https://integrations.example.com',
   env: process.env,
 })
 
@@ -273,6 +274,16 @@ agent runs.
 For a full product checklist, see
 [External Product Integration](./docs/external-product-integration.md).
 
+## Product Hub Ownership
+
+Use a hosted hub when multiple apps intentionally share identity, billing,
+consent, and connection custody. Use a product-owned hub when a standalone
+deployment needs its own customer boundary, OAuth branding, vault, policy, or
+data residency. Both modes use the same package contracts.
+
+See [Product Hub Ownership](./docs/product-hub-ownership.md) for the
+deployment model and launch gates.
+
 ## Provider Strategy
 
 The package deliberately avoids vendor lock-in.

package/docs/adapter-triage.md

@@ -63,7 +63,7 @@ import {
 
 const provider = createTangleCatalogExecutorProvider({
   executeAction: createTangleCatalogHttpExecutor({
-    endpoint: 'https://id.tangle.tools/integration-runtime',
+    endpoint: 'https://integrations.example.com/integration-runtime',
     secret: process.env.TANGLE_CATALOG_RUNTIME_SECRET,
   }),
 })

package/docs/product-hub-ownership.md

@@ -0,0 +1,126 @@
+# Integration Hub Ownership
+
+Status: deployment guidance
+
+This document describes where integration custody should live when a product
+uses `@tangle-network/agent-integrations`.
+
+## Decision
+
+Use one contract everywhere, not one deployment everywhere.
+
+- Products that share identity, billing, and consent can use a hosted platform
+  hub.
+- Standalone products can run a product-owned hub.
+- Both modes must use `@tangle-network/agent-integrations` contracts:
+  `IntegrationSpec`, `IntegrationManifest`, `IntegrationGrant`, capability
+  bundles, `/v1/integrations/invoke`, approvals, healthchecks, audit, webhooks,
+  and provider/runtime adapters.
+- Product-owned hubs may federate to a hosted platform hub when the deployment
+  wants a shared connection wallet.
+
+The package defines the shared protocol. Each deployment decides where to store
+connections, secrets, grants, approvals, audit records, and workflow state.
+
+## Ownership Modes
+
+| Mode | Use When | Owns OAuth, Vault, Audit | Invocation Path |
+|---|---|---:|---|
+| Hosted platform hub | Multiple apps share account, consent, billing, and connection custody | Platform service | App/sandbox calls platform hub or product proxy with scoped capability |
+| Product-owned hub | Standalone SaaS, private deployment, or customer-owned data boundary | Product app | App/sandbox calls product `/v1/integrations/invoke` |
+| Federated product hub | Product wants local policy with remote connection custody | Product policy + hosted custody | Product issues local grants over remote platform connections |
+
+The important invariant: sandboxes and generated apps never receive provider
+refresh tokens, API keys, or raw OAuth credentials in any mode.
+
+## Where Duplication Is Bad
+
+Fully duplicating hubs is bad when apps are intentionally part of the same
+account system:
+
+- Users reconnect Gmail, Slack, GitHub, and Drive in every app.
+- OAuth app verification, scopes, redirect configuration, and consent review
+  are repeated.
+- Revocation, audit, healthchecks, and billing attribution fragment.
+- Generated apps cannot inherit a user's already-approved connection.
+
+For those deployments, use a hosted hub as the connection source of truth and
+pass scoped grants down to apps, sandboxes, and agents.
+
+## Where Centralization Is Bad
+
+Forcing every deployment through a hosted platform hub is bad when the product
+needs a separate customer, compliance, or operational boundary:
+
+- The buyer may not want shared identity or billing in their end-user flow.
+- Enterprise deployments may require product-branded OAuth apps, product-owned
+  vaults, customer-managed keys, private networking, or data residency.
+- Product-specific subscriptions and compliance boundaries may not match the
+  platform account model.
+- A central platform outage should not necessarily take down a standalone app.
+
+For those products, run a product-owned hub using the same package contracts.
+Optionally add federation to a hosted platform hub as a deployment choice.
+
+## Execution Checklist
+
+- [x] One stable contract for specs, manifests, grants, capabilities, invocation,
+      approvals, healthchecks, webhooks, audit, and bridge payloads.
+- [x] Long-tail connector contracts and runtime-backed execution path are
+      represented without leaking external catalog names into product UX.
+- [x] External product adoption guide documents product-owned deployment.
+- [x] This ownership decision documents platform versus product-owned custody.
+
+### Hosted Hub Bar
+
+- [ ] The hosted hub has production stores for connections, grants, approvals,
+      audit, healthchecks, workflows, webhook events, and idempotency.
+- [ ] The hosted hub vault/KMS stores raw OAuth/API-key credentials behind
+      secret refs.
+- [ ] The hosted hub exposes connect, callback, revoke, rotate, approve, audit,
+      healthcheck, and `/v1/integrations/invoke`.
+- [ ] Sandbox and generated-app launches receive
+      `buildIntegrationBridgeEnvironment()` output.
+- [ ] Browser E2E covers connect, consent, preview, invoke read, approval write,
+      revoke, expired token recovery, and missing-connection recovery.
+
+### Product-Owned Hub Bar
+
+- [ ] The product chooses local hub or federated platform hub per deployment.
+- [ ] Local hubs use `IntegrationHub`; custom provider switch statements are
+      removed or wrapped as `IntegrationProvider` implementations.
+- [ ] The product stores connections, grants, approvals, audit, healthchecks,
+      workflows, events, and idempotency in its own database.
+- [ ] The product uses its own vault/KMS or explicitly delegates secret custody
+      to a hosted hub.
+- [ ] The product has live OAuth/API-key setup UI generated from
+      `IntegrationSpec`.
+- [ ] The product has browser E2E personas using real product UX and live
+      integration secrets where available.
+
+## Product E2E Gates
+
+Run these before launch for every product adopting integrations:
+
+1. Existing connection: user asks for a task requiring Gmail, Calendar, Slack,
+   GitHub, Drive, Sheets, or CRM data; agent detects the existing connection and
+   uses it without asking for manual copy/paste.
+2. Missing connection: user asks for the same task without a connection; product
+   renders connect/consent in flow, resumes the task after OAuth, and does not
+   lose conversation state.
+3. Generated app preview: generated software declares an
+   `IntegrationManifest`; preview requests user consent, receives scoped
+   capabilities, and reads provider data through the invoke endpoint.
+4. Write approval: generated app or agent proposes a write/send/update action;
+   product requires approval, records audit, and executes once with idempotency.
+5. Revocation: user revokes a connection; existing grants fail closed and the UI
+   explains how to reconnect.
+6. Healthcheck failure: expired or revoked upstream credentials surface in admin
+   UI and task UX without exposing secrets in logs or traces.
+
+## Recommendation
+
+Do not fork integration semantics by product. Make hub custody a deployment
+choice while keeping the protocol stable. Hosted hubs, product-owned hubs, and
+federated hubs should all expose the same manifest, grant, capability, approval,
+audit, webhook, and invocation shapes.

package/docs/provider-decision-matrix.md

@@ -74,9 +74,9 @@ Use gateway-backed coverage for the next large tranche:
 - long-tail CRM/support/helpdesk systems
 - vendor-specific workflow triggers
 
-This gives Agent Builder useful breadth immediately without forcing us to own
-hundreds of OAuth apps, refresh-token edge cases, webhook subscription models,
-rate-limit policies, and provider-specific APIs on day one.
+This gives products useful breadth immediately without forcing every team to
+own hundreds of OAuth apps, refresh-token edge cases, webhook subscription
+models, rate-limit policies, and provider-specific APIs on day one.
 
 ## When To Roll Our Own
 

package/examples/calendar-exercise-app.ts

@@ -12,8 +12,8 @@ const consent = renderConsentSummary(manifest, { appName: 'Exercise Planner' })
 
 console.log(consent.body)
 
-// In production this bundle comes from id.tangle.tools after the user grants
-// the generated app access to their Google Calendar connection.
+// In production this bundle comes from the product integration hub after the
+// user grants the generated app access to their Google Calendar connection.
 const bundle: IntegrationSandboxBundle = {
   manifestId: manifest.id,
   subject: { type: 'sandbox', id: 'sandbox_preview_1' },
@@ -64,7 +64,7 @@ const bundle: IntegrationSandboxBundle = {
 
 const env = buildIntegrationBridgeEnvironment(bundle)
 const client = createTangleIntegrationsClient({
-  endpoint: 'https://id.tangle.tools',
+  endpoint: 'https://integrations.example.com',
   env,
 })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {
@@ -38,15 +38,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "audit:execution": "pnpm build >/dev/null && node scripts/audit-integration-execution.mjs",
-    "prepare": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
-  },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
@@ -57,5 +48,12 @@
     "node": ">=20"
   },
   "license": "MIT",
-  "packageManager": "pnpm@10.28.0"
-}
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "audit:execution": "pnpm build >/dev/null && node scripts/audit-integration-execution.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}