@tangle-network/agent-integrations 0.25.0 → 0.25.1

package/README.md

@@ -1,21 +1,28 @@
 # @tangle-network/agent-integrations
 
-Vendor-neutral integration contracts for agent apps, sandboxes, and generated
-software that need user-authorized access to external systems.
+Integration infrastructure for agent products, sandbox apps, and generated
+software.
 
-The package standardizes connector catalogs, user connections, scoped sandbox
-capabilities, action invocation, trigger events, provider adapters, and
-first-party connector adapters. Product code can route through hosted gateways,
-custom runtimes, or first-party adapters without changing the agent-facing tool
-contract.
+Use this package when users connect external accounts and agents or apps need
+controlled read/write access to those accounts. It gives products one stable
+contract for connector discovery, OAuth/API-key connections, scoped sandbox
+capabilities, action invocation, workflow triggers, approval, audit,
+healthchecks, and provider/runtime adapters.
+
+The product keeps ownership of UI, tenant policy, persistence, and secret
+storage. `agent-integrations` keeps the runtime contract stable so generated
+apps and agents do not depend on a specific OAuth broker, workflow vendor, or
+provider SDK.
 
 ## Contents
 
 - [What It Provides](#what-it-provides)
 - [Architecture](#architecture)
 - [Install](#install)
+- [Quick Start](#quick-start)
 - [Core Primitives](#core-primitives)
 - [Catalog Registry](#catalog-registry)
+- [Product Adoption](#product-adoption)
 - [Provider Strategy](#provider-strategy)
 - [Executable Coverage](#executable-coverage)
 - [Examples](#examples)
@@ -25,7 +32,7 @@ contract.
 ## What It Provides
 
 - A normalized connector/action/trigger catalog.
-- First-class Tangle integration contracts for every catalog connector.
+- Tangle integration contracts for every catalog connector.
 - User-owned connection records that reference secrets without storing raw
   credentials in public shapes.
 - Short-lived capability tokens for sandbox-safe access to a subset of a user's
@@ -37,8 +44,8 @@ contract.
   runtimes, and internal connector registries.
 - A first-party `ConnectorAdapter` boundary for direct provider execution.
 - A declarative REST adapter factory for promoting REST APIs from reviewed specs.
-- A broad coverage catalog for planning hundreds of integrations without
-  pretending every catalog item is executable.
+- A broad catalog for discovering hundreds of integrations while keeping
+  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,
@@ -57,8 +64,10 @@ contract.
 ## Architecture
 
 ```txt
-connector catalog
+connector contract
   -> user connection
+  -> app/agent manifest
+  -> grant
   -> scoped capability
   -> policy decision
   -> provider/action invocation
@@ -80,6 +89,63 @@ Main boundaries:
 pnpm add @tangle-network/agent-integrations
 ```
 
+## Quick Start
+
+```ts
+import {
+  buildDefaultIntegrationRegistry,
+  buildIntegrationToolCatalog,
+  createIntegrationRuntime,
+  createPlatformIntegrationPolicyPreset,
+  InMemoryConnectionStore,
+  IntegrationHub,
+} from '@tangle-network/agent-integrations'
+
+const registry = buildDefaultIntegrationRegistry({
+  tangleCatalogRuntimeExecutable: false,
+})
+
+const hub = new IntegrationHub({
+  providers: [/* native, gateway, or catalog-runtime providers */],
+  store: productConnectionStore ?? new InMemoryConnectionStore(),
+  capabilitySecret: process.env.INTEGRATION_CAPABILITY_SECRET!,
+  policy: createPlatformIntegrationPolicyPreset(),
+})
+
+const runtime = createIntegrationRuntime({
+  hub,
+  grants: productGrantStore,
+})
+
+const tools = buildIntegrationToolCatalog(registry.connectors)
+```
+
+For a generated app or sandbox:
+
+```ts
+const resolution = await runtime.resolveManifest(manifest, user)
+
+if (resolution.missing.length > 0) {
+  // Show connect UI using IntegrationSpec renderers.
+}
+
+await runtime.createGrants({
+  manifest,
+  owner: user,
+  grantee: { type: 'app', id: manifest.id },
+})
+
+const bundle = await runtime.buildSandboxBundle({
+  manifestId: manifest.id,
+  subject: { type: 'sandbox', id: sandboxId },
+  ttlMs: 15 * 60_000,
+})
+```
+
+Generated code calls your product integration endpoint with the scoped
+capability bundle. It never receives provider refresh tokens, API keys, or raw
+OAuth credentials.
+
 ## Core Primitives
 
 | Primitive | Purpose |
@@ -129,9 +195,9 @@ pnpm add @tangle-network/agent-integrations
 
 ## Catalog Registry
 
-Every catalog connector has a first-class Tangle contract. Native adapters and
-package runtimes are implementation backends behind that contract; product code
-should route through `IntegrationHub` either way.
+Every catalog connector has a Tangle contract. Native adapters, hosted gateways,
+and package runtimes are implementation backends behind that contract; product
+code should route through `IntegrationHub` either way.
 
 Use `buildDefaultIntegrationRegistry()` before creating tool catalogs or
 connection pickers. It produces one canonical connector per integration,
@@ -144,16 +210,16 @@ catalogOnly < setupReady < gatewayExecutable < firstPartyExecutable < sandboxExe
 
 Use `buildDefaultIntegrationRegistry({ tangleCatalogRuntimeExecutable: true })`
 when the Tangle catalog runtime is deployed and should be exposed as executable
-tools. These states describe the backend currently wired into a product, not
-whether the connector has a first-class Tangle contract.
+tools. These states describe the backend currently wired into a product. They
+do not change the connector contract.
 
 See [Catalog Registry](./docs/catalog-registry.md).
 
-## App And Agent Grants
+## Product Adoption
 
 Use `IntegrationManifest` for any app or agent that needs integrations:
-Agent Builder-generated apps, tax/legal/GTM/creative agents, Blueprint Agent
-sandboxes, and executor-backed workflows all use the same shape.
+generated apps, domain agents, sandbox agents, workflow apps, and
+executor-backed runtimes all use the same shape.
 
 ```ts
 const runtime = createIntegrationRuntime({ hub, grants })
@@ -204,6 +270,9 @@ That installs provider trigger subscriptions against the user's connection and
 lets the product dispatch normalized events to UI workflows, sync jobs, or
 agent runs.
 
+For a full product checklist, see
+[External Product Integration](./docs/external-product-integration.md).
+
 ## Provider Strategy
 
 The package deliberately avoids vendor lock-in.

package/docs/external-product-integration.md

@@ -0,0 +1,203 @@
+# External Product Integration
+
+This guide is for product teams using `@tangle-network/agent-integrations`
+outside this repository. The package gives you stable contracts and runtime
+helpers; your product supplies persistence, secret storage, UI, and deployment
+policy.
+
+## Mental Model
+
+```txt
+user connects account
+  -> product stores IntegrationConnection + secret refs
+  -> app/agent declares IntegrationManifest
+  -> product creates IntegrationGrant
+  -> sandbox/app receives short-lived capability bundle
+  -> sandbox/app invokes product /integrations/invoke endpoint
+  -> IntegrationHub validates capability, policy, approval, idempotency
+  -> provider backend executes action
+  -> product stores audit event and returns normalized result
+```
+
+The invariant: generated apps and agents call the same Tangle integration tools
+no matter whether a connector is backed by a native adapter, hosted gateway, or
+catalog runtime.
+
+## Product-Owned Pieces
+
+You must provide:
+
+- `IntegrationConnection` storage in your database.
+- `IntegrationGrant` storage mapping user-owned connections to apps, agents, or
+  sandboxes.
+- Approval, audit, healthcheck, workflow, and event stores.
+- `IntegrationSecretStore` backed by your vault or KMS.
+- OAuth/API-key connect UI built from `IntegrationSpec` renderers.
+- Tenant policy for which connectors are enabled.
+- Human approval UX for write/destructive actions.
+- A deployed invocation endpoint such as `/v1/integrations/invoke`.
+
+The package provides interfaces and helpers for all of these. It does not store
+your secrets or run your product UI.
+
+## Setup Flow
+
+1. Build the registry.
+
+```ts
+import { buildDefaultIntegrationRegistry } from '@tangle-network/agent-integrations'
+
+const registry = buildDefaultIntegrationRegistry({
+  tangleCatalogRuntimeExecutable: process.env.TANGLE_CATALOG_RUNTIME === '1',
+})
+```
+
+2. Render setup UI from specs.
+
+```ts
+import {
+  listIntegrationSpecs,
+  renderConsoleSteps,
+  validateCredentialSet,
+} from '@tangle-network/agent-integrations'
+
+const spec = listIntegrationSpecs().find((candidate) => candidate.kind === 'google-calendar')
+const steps = renderConsoleSteps(spec!, { host: 'id.example.com' })
+const validation = validateCredentialSet(spec!, submittedCredentials)
+```
+
+3. Store provider credentials in your vault, then persist an
+   `IntegrationConnection` with secret refs, scopes, owner, connector id, and
+   status.
+
+4. Run `runIntegrationHealthchecks()` after setup and on a schedule.
+
+## Runtime Flow
+
+Create one hub per product runtime.
+
+```ts
+import {
+  createConnectorAdapterProvider,
+  createDefaultIntegrationActionGuard,
+  IntegrationHub,
+  createPlatformIntegrationPolicyPreset,
+} from '@tangle-network/agent-integrations'
+
+const hub = new IntegrationHub({
+  providers: [
+    createConnectorAdapterProvider({
+      adapters,
+      resolveDataSource: (connection) => credentialResolver.resolve(connection),
+    }),
+    // createHttpIntegrationProvider(...) or createTangleCatalogExecutorProvider(...)
+  ],
+  store: connections,
+  capabilitySecret: process.env.INTEGRATION_CAPABILITY_SECRET!,
+  policy: createPlatformIntegrationPolicyPreset(),
+  guard: createDefaultIntegrationActionGuard({
+    audit,
+    idempotency,
+  }),
+})
+```
+
+Your `/v1/integrations/invoke` route should:
+
+1. Parse the invocation envelope.
+2. Validate the capability token.
+3. Resolve the user's connection and credentials.
+4. Run policy and approval checks.
+5. Execute through the matching provider.
+6. Store an audit event.
+7. Return a normalized result or `approval_required`.
+
+## Generated Apps And Sandboxes
+
+Generated apps declare needs through `IntegrationManifest`.
+
+```ts
+const manifest = {
+  id: 'calendar-workout-planner',
+  requirements: [
+    {
+      connectorId: 'google-calendar',
+      mode: 'read',
+      reason: 'Find open workout windows from calendar events.',
+      requiredActions: ['events.list'],
+      scopes: ['calendar.read'],
+    },
+  ],
+}
+```
+
+When a user previews or installs the app:
+
+1. Resolve the manifest against the user's existing connections.
+2. Ask the user to connect missing accounts.
+3. Show consent using `renderConsentSummary()`.
+4. Create grants from the user's connections to the app.
+5. Build a sandbox bundle with short-lived capabilities.
+6. Inject the bridge environment into the sandbox.
+
+Generated app code should use `createTangleIntegrationsClient()` or the product
+equivalent. It should not call Google, Slack, GitHub, or any provider directly
+with user credentials.
+
+## Workflows And Triggers
+
+Use `createIntegrationWorkflowRuntime()` for non-agent automations:
+
+- GitHub issue or pull-request sync.
+- Slack message triggers.
+- Calendar event updates.
+- CRM record changes.
+- Webhook-to-sandbox workflows.
+
+Inbound provider webhooks should go through `receiveIntegrationWebhook()` for
+signature verification, provider-event dedupe, and normalized event dispatch.
+
+## Long-Tail Connectors
+
+The registry distinguishes connector contracts from executable backend state.
+Products can expose long-tail connectors only when they have configured a
+backend:
+
+- native adapter
+- hosted integration gateway
+- Tangle catalog runtime
+- product-specific provider
+
+Use `buildDefaultIntegrationRegistry({ tangleCatalogRuntimeExecutable: true })`
+only after the catalog runtime is deployed and audited with
+`auditTangleCatalogRuntimePackages()`.
+
+## Security Requirements
+
+- Never pass provider refresh tokens or API keys into a sandbox.
+- Use short-lived capability tokens scoped to connector, action, subject, and
+  connection.
+- Require approval for writes by default.
+- Deny destructive actions unless the product explicitly enables them.
+- Use idempotency keys for state-changing actions.
+- Store audit events for connect, grant, invoke, approve, revoke, rotate, and
+  webhook flows.
+- Redact provider credentials from logs, traces, errors, and generated app
+  payloads.
+
+## Launch Checklist
+
+- [ ] Connection, grant, approval, audit, healthcheck, workflow, and event stores
+      are backed by production persistence.
+- [ ] Secret refs resolve through vault/KMS and never serialize raw credentials.
+- [ ] OAuth/API-key setup UI renders from `IntegrationSpec`.
+- [ ] Connect, revoke, rotate, approve, and audit-log screens exist.
+- [ ] Generated app manifests feed into `resolveManifest()` and
+      `createGrants()`.
+- [ ] Sandbox launches receive `buildIntegrationBridgeEnvironment()` output.
+- [ ] Sandbox invocations route through your product integration endpoint.
+- [ ] Writes require approval and idempotency.
+- [ ] Webhooks verify signatures and dedupe provider event ids.
+- [ ] Healthchecks run after setup and on a schedule.
+- [ ] Browser E2E covers connect, consent, preview, invoke, approval, revoke,
+      and failure recovery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {