@tangle-network/agent-integrations 0.9.0 → 0.14.0

package/README.md

@@ -15,6 +15,7 @@ agent-facing tool contract.
 - [Architecture](#architecture)
 - [Install](#install)
 - [Core Primitives](#core-primitives)
+- [Catalog Registry](#catalog-registry)
 - [Provider Strategy](#provider-strategy)
 - [Executable Coverage](#executable-coverage)
 - [Examples](#examples)
@@ -31,10 +32,19 @@ agent-facing tool contract.
 - Policy checks for read/write/destructive actions.
 - Invocation-envelope validation before sandbox tool calls reach the hub.
 - A generic HTTP provider boundary for hosted integration gateways.
+- A gateway catalog provider for Nango, Pipedream, Activepieces, Zapier,
+  executor-style gateways, 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 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,
+  vertical agents, Blueprint Agent, 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.
 - A generated `IntegrationSpec` registry used for setup docs, admin UI steps,
   normalized permissions, healthcheck plans, and tool descriptions.
 
@@ -72,9 +82,16 @@ pnpm add @tangle-network/agent-integrations
 | `IntegrationConnection` | User/team/agent-owned grant with scopes and secret references. |
 | `IntegrationHub` | Facade for provider catalogs, connection storage, capabilities, and invocation. |
 | `IntegrationCapability` | Short-lived authorization for a specific subject, connection, scope set, and action set. |
+| `IntegrationManifest` | Generated app or agent requirements: connectors, actions, scopes, and reasons. |
+| `IntegrationGrant` | Persistent grant from a user-owned connection to an app, agent, or sandbox consumer. |
+| `createIntegrationRuntime` | Facade for manifest resolution, grant creation, and sandbox capability bundles. |
+| `createIntegrationWorkflowRuntime` | Installs trigger workflows and dispatches normalized provider events. |
 | `buildIntegrationToolCatalog` | Converts connector actions into agent/tool definitions. |
 | `searchIntegrationTools` | Intent search over normalized integration tools. |
+| `buildDefaultIntegrationRegistry` | Composes setup specs and vendored catalog metadata into one deduplicated connector registry. |
+| `composeIntegrationRegistry` | Merges arbitrary catalog sources with explicit aliases, precedence, support tiers, and conflict diagnostics. |
 | `buildIntegrationCoverageConnectors` | Planning catalog for 100+ high-value integrations. |
+| `createGatewayCatalogProvider` | Normalizes 500+ gateway-backed connectors into the same provider contract. |
 | `buildIntegrationInvocationEnvelope` | Sandbox-safe action envelope. |
 | `validateIntegrationInvocationEnvelope` | Runtime validation for tool/action consistency and input limits. |
 | `createHttpIntegrationProvider` | Adapter for hosted integration gateways. |
@@ -84,6 +101,62 @@ pnpm add @tangle-network/agent-integrations
 | `renderRunbookMarkdown` / `renderConsoleSteps` | Render operator docs or admin UI steps from the same spec source. |
 | `validateCredentialSet` / `buildHealthcheckPlan` | Validate setup input and describe the correct healthcheck path. |
 
+## Catalog Registry
+
+Catalog breadth and runtime execution are separate. Activepieces metadata gives
+the package broad connector inventory; first-party adapters and gateways decide
+which connectors can actually run.
+
+Use `buildDefaultIntegrationRegistry()` before creating tool catalogs or
+connection pickers. It produces one canonical connector per integration,
+dedupes aliases such as `notion -> notion-database`, keeps source provenance in
+metadata, and marks each connector with a support tier:
+
+```txt
+catalogOnly < setupReady < gatewayExecutable < firstPartyExecutable < sandboxExecutable
+```
+
+See [Catalog Registry](./docs/catalog-registry.md).
+
+## App And Agent Grants
+
+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.
+
+```ts
+const runtime = createIntegrationRuntime({ hub, grants })
+
+const resolution = await runtime.resolveManifest(manifest, user)
+const grants = 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 apps and sandboxes receive scoped capability tokens and tool
+definitions. They never receive OAuth refresh tokens, API keys, or raw secrets.
+
+The same manifest/grant model works for non-agent workflows:
+
+```ts
+await workflows.install({
+  workflow,
+  owner: user,
+  grantee: { type: 'app', id: 'github-pr-sync' },
+})
+```
+
+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.
+
 ## Provider Strategy
 
 The package deliberately avoids vendor lock-in.