@tangle-network/agent-integrations 0.25.1 → 0.25.3

package/dist/tangle-catalog-runtime.d.ts

@@ -0,0 +1,4 @@
+export { T as TangleCatalogAuthResolverOptions, w as TangleCatalogHttpAuthResolverOptions, x as TangleCatalogHttpAuthResolverRequest, y as TangleCatalogInstalledPackageExecutorOptions, z as TangleCatalogRuntimeHandlerOptions, A as TangleCatalogRuntimeHttpRequest, B as TangleCatalogRuntimeHttpResponse, C as TangleCatalogRuntimeInvocation, D as TangleCatalogRuntimeModuleAction, E as TangleCatalogRuntimePackageCoverageOptions, F as TangleCatalogRuntimePackageCoverageRow, G as auditTangleCatalogRuntimePackages, H as createTangleCatalogCredentialAuthResolver, J as createTangleCatalogHttpAuthResolver, K as createTangleCatalogInstalledPackageExecutor, L as createTangleCatalogRuntimeHandler, N as tangleCatalogAuthValue } from './registry.js';
+import './index-BNb1A0Id.js';
+import './connectors/index.js';
+import 'node:http';

package/dist/tangle-catalog-runtime.js

@@ -0,0 +1,22 @@
+import {
+  auditTangleCatalogRuntimePackages,
+  createTangleCatalogCredentialAuthResolver,
+  createTangleCatalogHttpAuthResolver,
+  createTangleCatalogInstalledPackageExecutor,
+  createTangleCatalogRuntimeHandler,
+  tangleCatalogAuthValue
+} from "./chunk-MU3UTIOX.js";
+import "./chunk-FQAT4IEE.js";
+import "./chunk-6KWCC42J.js";
+import "./chunk-4JQ754PA.js";
+import "./chunk-376UBTNB.js";
+import "./chunk-IDX3KIPA.js";
+export {
+  auditTangleCatalogRuntimePackages,
+  createTangleCatalogCredentialAuthResolver,
+  createTangleCatalogHttpAuthResolver,
+  createTangleCatalogInstalledPackageExecutor,
+  createTangleCatalogRuntimeHandler,
+  tangleCatalogAuthValue
+};
+//# sourceMappingURL=tangle-catalog-runtime.js.map

package/dist/tangle-catalog-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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/platform-control-plane.md

@@ -0,0 +1,54 @@
+# Platform Control Plane Adoption
+
+Use this package when one product owns user connections and many runtimes need
+safe access to those connections.
+
+```txt
+central platform
+  owns OAuth apps, connection storage, grants, approvals, audit, healthchecks
+
+sandbox / generated app / agent runtime
+  receives a short-lived capability bundle
+  calls /v1/integrations/invoke
+  never receives provider refresh tokens or API keys
+```
+
+## Required Flow
+
+1. Product code turns app requirements into an `IntegrationManifest`.
+2. Platform resolves the manifest against the user's active connections.
+3. Missing connections or scopes return a user-facing connect/consent action.
+4. Platform creates `IntegrationGrant` records for the approved grantee.
+5. Platform issues a short-lived bundle with `buildSandboxBundle()`.
+6. Runtime receives only `TANGLE_INTEGRATION_BUNDLE`.
+7. Generated app code calls `createTangleIntegrationsClient()`.
+8. Platform verifies capability, policy, approval, idempotency, and audit before
+   invoking the provider.
+
+## Durable Installs
+
+Preview runs can build bundles by `manifestId` and `grantee`. Installed apps and
+published templates often need a narrower path: bind one app instance to known
+pre-created grants. Use explicit grant ids:
+
+```ts
+const bundle = await runtime.buildSandboxBundle({
+  grantIds: ['grant_calendar_read'],
+  subject: { type: 'sandbox', id: 'sandbox_123' },
+  grantee: { type: 'app', id: 'installed_app_123' },
+  ttlMs: 15 * 60_000,
+})
+```
+
+The runtime fails closed if a grant id is unknown, belongs to another grantee, or
+belongs to a different manifest than the requested `manifestId`.
+
+## Production Gates
+
+- Catalog-only connectors are discoverable, not executable.
+- Runtime code receives capability tokens only.
+- Writes require approval unless product policy explicitly allows them.
+- Destructive actions are denied by default.
+- Every invoke has an audit event and an idempotency key.
+- Revoke deletes credentials and stops future bundles from including the grant.
+- Resume/long-running runtimes refresh bundles before expiry.

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/production-completion-checklist.md

@@ -20,6 +20,8 @@ provider credentials.
 - [x] Persistent grants from user-owned connections to apps, agents, sandboxes,
       and generated software.
 - [x] Sandbox bundles with short-lived capability tokens and tool definitions.
+- [x] Explicit grant-id bundle issuance for installed apps, published templates,
+      and durable app instances.
 - [x] Bridge payload/env helpers for sandbox processes and executor-style CLIs.
 - [x] Sandbox invocation host that validates envelopes before hub invocation and
       normalizes success, failure, and approval-required results.

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.3",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {
@@ -19,10 +19,40 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.js",
+      "default": "./dist/catalog.js"
+    },
+    "./connectors": {
+      "types": "./dist/connectors/index.d.ts",
+      "import": "./dist/connectors/index.js",
+      "default": "./dist/connectors/index.js"
+    },
+    "./connectors/adapters": {
+      "types": "./dist/connectors/adapters/index.d.ts",
+      "import": "./dist/connectors/adapters/index.js",
+      "default": "./dist/connectors/adapters/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js",
+      "default": "./dist/registry.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "default": "./dist/runtime.js"
+    },
     "./specs": {
       "types": "./dist/specs.d.ts",
       "import": "./dist/specs.js",
       "default": "./dist/specs.js"
+    },
+    "./tangle-catalog-runtime": {
+      "types": "./dist/tangle-catalog-runtime.d.ts",
+      "import": "./dist/tangle-catalog-runtime.js",
+      "default": "./dist/tangle-catalog-runtime.js"
     }
   },
   "bin": {
@@ -38,15 +68,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 +78,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"
+  }
+}