@tangle-network/agent-integrations

Vendor-neutral integration contracts for agent apps, sandboxes, and generated software that need user-authorized access to external systems.

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 Nango, Pipedream, Activepieces, a custom gateway, or first-party adapters without changing the agent-facing tool contract.

Contents

• What It Provides
• Architecture
• Install
• Core Primitives
• Catalog Registry
• Provider Strategy
• Executable Coverage
• Examples
• Security Model
• Development

What It Provides

• A normalized connector/action/trigger catalog.
• 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 connection.
• 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.
• Approval persistence, audit events, healthchecks, credential resolution, webhook ingestion, idempotency guards, and sandbox/CLI bridge payloads.
• Generated-app client helpers, manifest inference/validation, consent copy, platform policy presets, canonical launch action schemas, and controlled provider-native passthrough validation.
• A generated IntegrationSpec registry used for setup docs, admin UI steps, normalized permissions, healthcheck plans, and tool descriptions.

Architecture

connector catalog
  -> user connection
  -> scoped capability
  -> policy decision
  -> provider/action invocation
  -> audit-safe result or normalized trigger event

Main boundaries:

• IntegrationHub: product-facing facade for catalogs, connections, capabilities, and action invocation.
• IntegrationProvider: vendor or gateway implementation boundary.
• ConnectorAdapter: first-party connector boundary for direct API execution.
• IntegrationActionGuard: optional cross-cutting hook for idempotency, approval, audit logging, rate limits, and conflict handling.

Install

pnpm add @tangle-network/agent-integrations

Core Primitives

Primitive	Purpose
IntegrationConnector	Normalized catalog entry for a provider connection.
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.
createApprovalBackedPolicyEngine	Persists approval requests and allows approved invocations to resume.
createDefaultIntegrationActionGuard	Adds idempotency replay, dry-run mutation handling, rate-limit hooks, and audit events.
createConnectionCredentialResolver	Resolves secret refs into in-memory connector credentials and refreshes expired OAuth credentials.
runIntegrationHealthchecks	Checks connection status, registry executability, scope shape, and optional live provider tests.
receiveIntegrationWebhook	Verifies inbound webhooks, dedupes provider events, and dispatches normalized trigger events.
buildIntegrationBridgeEnvironment	Encodes scoped sandbox capabilities for sandbox processes or executor-style CLIs.
createTangleIntegrationsClient	Tiny generated-app/sandbox client for platform /v1/integrations/invoke.
inferIntegrationManifestFromTools / validateIntegrationManifest	Deterministic manifest helpers for Builder and platform APIs.
renderConsentSummary / renderApprovalCopy	User-facing consent and approval copy from manifests/actions.
createPlatformIntegrationPolicyPreset	Secure defaults: reads allowed after grant, writes need approval, destructive denied, passthrough disabled.
buildCanonicalLaunchConnectors	Product-ready launch action schemas for Calendar, Gmail, Drive, GitHub, and Slack.
validateProviderPassthroughRequest	Policy-gated provider-native HTTP escape hatch validation.
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.
createConnectorAdapterProvider	Runs first-party ConnectorAdapters through the same provider contract.
declarativeRestConnector	Builds REST-backed first-party adapters from compact specs.
listIntegrationSpecs	Generates setup/execution specs from the coverage catalog and family defaults.
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:

catalogOnly < setupReady < gatewayExecutable < firstPartyExecutable < sandboxExecutable

See Catalog Registry.

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.

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. For sandbox processes, pass the bundle through buildIntegrationBridgeEnvironment(); the payload contains short-lived capability tokens and tool names only.

Generated app code should use the tiny client instead of raw provider tokens:

const integrations = createTangleIntegrationsClient({
  endpoint: 'https://id.tangle.tools',
  env: process.env,
})

await integrations.invoke({
  tool: 'google-calendar.events.list',
  input: { calendarId: 'primary', timeMin, timeMax },
})

The same manifest/grant model works for non-agent workflows:

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.

• Use a hosted gateway when it compresses long-tail OAuth/API coverage.
• Promote high-volume, sensitive, or strategically important integrations to first-party adapters.
• Keep product and sandbox code on IntegrationHub contracts so provider changes do not alter generated apps or agent tool calls.
• Treat catalog coverage and executable coverage as different states.

See Provider Decision Matrix.

Executable Coverage

Current first-party adapters:

• Google Calendar
• Microsoft Calendar
• Google Sheets
• Slack
• Slack Events
• HubSpot
• Notion database
• Stripe payments pack
• Stripe webhook receiver
• Twilio SMS
• Generic webhook
• GitHub
• GitLab
• Airtable
• Asana
• Salesforce

Broad planning coverage is generated from buildIntegrationCoverageConnectors() and tracked in Integration Coverage Checklist.

Examples

Runnable examples live in examples/:

• examples/basic-hub.ts - catalog search, connection storage, capability issue, and action invocation.
• examples/first-party-adapter.ts - first-party adapter provider wiring.
• examples/declarative-rest.ts - compact REST connector spec.
• examples/calendar-exercise-app.ts - generated-app golden path: manifest, consent copy, bridge env, and invoke.

The README stays short; examples are separate so they can be copied and expanded without obscuring the package contract.

Security Model

• Capability tokens expire.
• Capability tokens do not contain provider credentials.
• Connection records carry secret references, not raw secrets.
• Secret stores are consumer-pluggable; the package only resolves secret refs at call time and keeps raw credentials in memory.
• Write and destructive actions can require approval.
• Approval records are bound to the subject, connection, connector, and action.
• Default guards provide idempotency replay and same-key drift detection.
• Invocation envelopes validate action/tool consistency, idempotency keys, metadata shape, known tools, and input size.
• Webhook ingestion supports signature verification and provider-event dedupe.
• Provider-native passthrough is disabled by default and must be explicitly policy-enabled with method/path/body limits.
• Action invocation checks ownership, connection status, scopes, allowed actions, and expiration.
• IntegrationActionGuard can enforce idempotency, approval, audit logging, conflict handling, and rate limits across all providers.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

License

MIT