@tangle-network/agent-integrations 0.7.0 → 0.8.0

package/docs/integration-coverage-checklist.md

@@ -77,7 +77,7 @@ The exhaustive checklist is generated from `integrationCoverageChecklistMarkdown
 - HR/legal/signature: Workday, BambooHR, Greenhouse, Lever, Gusto, Rippling, DocuSign, Ironclad, Clio.
 - AI/vector/workflow: OpenAI, Anthropic, Gemini, Hugging Face, Pinecone, Weaviate, Qdrant, Zapier, Make, Nango, Pipedream, Activepieces.
 
-## Next Build Loop
+## Remaining Work
 
 - [ ] Wire Builder to show Tier 0 missing connections from the coverage catalog.
 - [ ] Add Gmail first-party adapter.
@@ -85,5 +85,6 @@ The exhaustive checklist is generated from `integrationCoverageChecklistMarkdown
 - [x] Add Salesforce or Zendesk first-party adapter.
 - [x] Add reusable declarative REST adapter factory.
 - [x] Add Airtable, GitLab, and Asana via declarative REST.
+- [x] Add generated integration setup specs, renderers, validation, and healthcheck plans.
 - [ ] Add live smoke-test harness that skips only when explicit credentials are absent.
 - [ ] Add gateway sync job for Nango/Pipedream/Activepieces metadata.

package/docs/provider-decision-matrix.md

@@ -159,6 +159,4 @@ This avoids two bad extremes:
 
 - locking the product into a vendor abstraction that becomes expensive and
   limiting;
-- spending months cloning hundreds of integrations before knowing which ones
-  matter.
-
+- cloning hundreds of integrations before knowing which ones matter.

package/examples/basic-hub.ts

@@ -0,0 +1,47 @@
+import {
+  InMemoryConnectionStore,
+  IntegrationHub,
+  buildIntegrationToolCatalog,
+  createMockIntegrationProvider,
+  searchIntegrationTools,
+} from '@tangle-network/agent-integrations'
+
+const provider = createMockIntegrationProvider()
+const store = new InMemoryConnectionStore()
+const hub = new IntegrationHub({
+  providers: [provider],
+  store,
+  capabilitySecret: 'replace-with-secret-manager-value',
+})
+
+const tools = searchIntegrationTools(
+  buildIntegrationToolCatalog(await hub.listConnectors()),
+  'email search',
+  { maxRisk: 'read' },
+)
+
+const connection = await hub.upsertConnection({
+  id: 'conn_1',
+  owner: { type: 'user', id: 'user_1' },
+  providerId: 'mock',
+  connectorId: 'gmail',
+  status: 'active',
+  grantedScopes: ['email.read'],
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+})
+
+const capability = await hub.issueCapability({
+  subject: { type: 'sandbox', id: 'sandbox_1' },
+  connectionId: connection.id,
+  scopes: ['email.read'],
+  allowedActions: [tools[0]!.tool.action.id],
+  ttlMs: 60_000,
+})
+
+const result = await hub.invokeWithCapability(capability.token, {
+  action: tools[0]!.tool.action.id,
+  input: { q: 'is:unread' },
+})
+
+console.log(result)

package/examples/declarative-rest.ts

@@ -0,0 +1,27 @@
+import { declarativeRestConnector } from '@tangle-network/agent-integrations'
+
+export const statusApiConnector = declarativeRestConnector({
+  kind: 'status-api',
+  displayName: 'Status API',
+  description: 'Read service health from an internal status endpoint.',
+  auth: { kind: 'api-key', hint: 'Status API token.' },
+  category: 'other',
+  defaultConsistencyModel: 'authoritative',
+  baseUrl: 'https://status.example.com/api',
+  capabilities: [
+    {
+      name: 'services.get',
+      class: 'read',
+      description: 'Read one service status.',
+      parameters: {
+        type: 'object',
+        properties: { serviceId: { type: 'string' } },
+        required: ['serviceId'],
+      },
+      request: {
+        method: 'GET',
+        path: '/services/{serviceId}',
+      },
+    },
+  ],
+})

package/examples/first-party-adapter.ts

@@ -0,0 +1,32 @@
+import {
+  createConnectorAdapterProvider,
+  githubConnector,
+  type IntegrationConnection,
+  type ResolvedDataSource,
+} from '@tangle-network/agent-integrations'
+
+const provider = createConnectorAdapterProvider({
+  adapters: [githubConnector],
+  resolveDataSource,
+})
+
+const connectors = await provider.listConnectors()
+console.log(connectors.map((connector) => connector.id))
+
+async function resolveDataSource(connection: IntegrationConnection): Promise<ResolvedDataSource> {
+  return {
+    id: `source_${connection.id}`,
+    projectId: 'project_1',
+    publishedAgentId: null,
+    kind: connection.connectorId,
+    label: connection.connectorId,
+    consistencyModel: 'authoritative',
+    scopes: connection.grantedScopes,
+    metadata: {},
+    credentials: {
+      kind: 'api-key',
+      apiKey: process.env.GITHUB_TOKEN ?? '',
+    },
+    status: 'active',
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "README.md"
   ],
   "publishConfig": {

package/docs/execution-layer-launch-plan.md

@@ -1,222 +0,0 @@
-# Agent Integrations Execution Layer Launch Plan
-
-## Goal
-
-Make `agent-integrations` the shared execution layer for Tangle products, generated sandbox apps, and agents that need external systems.
-
-The package should own the stable product contract for:
-
-- connector catalog and tool discovery
-- user/team-owned connections
-- OAuth/API-key/HMAC connection flows
-- short-lived sandbox-safe capabilities
-- policy checks and approval gates
-- action execution
-- trigger/webhook normalization
-- MCP/tool export surfaces
-- first-party and vendor-backed provider adapters
-
-The product value is direct: a user can ask Agent Builder to create an app that uses Gmail, Slack, Calendar, HubSpot, Stripe, Notion, or a webhook; the app can request the right connections; the sandbox receives only scoped capabilities; and every read, write, trigger, and approval is auditable.
-
-## Current Status
-
-Shipped:
-
-- vendor-neutral `IntegrationHub`
-- connection store contract
-- short-lived signed capabilities
-- action invocation with scope/action checks
-- `IntegrationActionGuard` hook for idempotency, audit, rate limits, and approvals
-- generic HTTP provider adapter for hosted gateways
-- OAuth helper
-- webhook signature helpers
-- first-party adapter contracts
-- first-party adapters for Google Calendar, Google Sheets, Microsoft Calendar, HubSpot, Slack, Notion, Twilio SMS, Stripe, generic webhooks, Slack events, and Stripe webhooks
-- adapter manifest contract tests
-
-Missing for full launch:
-
-- typed, searchable tool catalog that agents can query by intent
-- canonical policy engine with approval decisions, not only a hook
-- approval request/result types and helpers
-- MCP/tool-call export helpers
-- runtime invocation envelope for sandboxes, with central validation for
-  tool/action consistency, idempotency keys, metadata shape, known-tool checks,
-  and input-size limits
-- connection requirement planning for generated apps
-- provider import pipeline for OpenAPI/GraphQL/MCP catalogs
-- first-party provider registry that wraps `ConnectorAdapter[]` into `IntegrationProvider`
-- live provider smoke tests for top connectors
-- security hardening gates for secret redaction, scope minimization, replay, and writes
-
-## Architecture Target
-
-```txt
-Generated app / agent / sandbox
-  -> Integration tool catalog search
-  -> connection requirements
-  -> user connects provider account
-  -> capability issued for sandbox/session
-  -> policy engine decides allow / approve / deny
-  -> action executor calls first-party or vendor-backed provider
-  -> audit event emitted
-  -> trigger receiver wakes sandbox workflows
-```
-
-`agent-integrations` owns contracts and reusable enforcement. Product repos own UI, tenant policy, persistence, and provider credentials.
-
-## Tactical PR Sequence
-
-### PR 1: Execution Plan
-
-- Add this tracking doc.
-
-Exit criteria:
-
-- The repo has a durable, concrete launch map.
-
-### PR 2: Catalog Search and Tool Export
-
-- [x] Add `IntegrationToolDefinition`.
-- [x] Add `buildIntegrationToolCatalog(connectors)`.
-- [x] Add `searchIntegrationTools(catalog, query, filters)`.
-- [x] Add `integrationToolName(providerId, connectorId, actionId)`.
-- [x] Add `parseIntegrationToolName(name)`.
-- [x] Add MCP-compatible tool export shape.
-
-Exit criteria:
-
-- Agents can discover tools by intent instead of stuffing every schema into context.
-- Tool names round-trip deterministically to provider/connector/action.
-
-### PR 3: Policy Engine and Approvals
-
-- [x] Add `IntegrationPolicyRule`.
-- [x] Add `IntegrationPolicyEngine`.
-- [x] Add decision states: `allow`, `require_approval`, `deny`.
-- [x] Add approval artifact types: `IntegrationApprovalRequest`, `IntegrationApprovalResolution`.
-- [x] Add default policy: reads allowed, writes require approval by default, destructive denied unless explicitly allowed.
-
-Exit criteria:
-
-- Product apps can enforce a consistent approval boundary before any external write.
-- Policy decisions include reasons and audit-safe metadata.
-
-### PR 4: Sandbox Invocation Envelope
-
-- [x] Add `IntegrationInvocationEnvelope`.
-- [x] Add helper to build a sandbox-safe invocation request from a capability and tool call.
-- [x] Add redaction helpers for logs/events.
-- [x] Add action result normalization for conflict/rate-limit/approval states.
-
-Exit criteria:
-
-- Sandboxes can invoke integrations without ever receiving reusable provider credentials.
-
-### PR 5: First-Party Provider Registry
-
-- [x] Add `createConnectorAdapterProvider`.
-- [x] Convert `ConnectorAdapter` manifests into `IntegrationConnector` catalog entries.
-- [x] Route read/mutation calls to adapter methods.
-- [x] Enforce capability class alignment and idempotency key defaults.
-
-Exit criteria:
-
-- The shipped first-party adapters become directly usable through `IntegrationHub`.
-
-### PR 6: Catalog Importers
-
-- [x] Add source importer contracts for OpenAPI, GraphQL, and MCP catalogs.
-- [x] Add manifest normalization helpers.
-- Add license-safe notes for importing MIT/open catalogs and deriving patterns from restricted-license systems.
-
-Exit criteria:
-
-- We can mine open-source catalogs and API specs without making product code vendor-shaped.
-
-### PR 7: Launch Smoke Tests
-
-- Add live-test harness contracts with environment-gated tests.
-- Cover OAuth start/complete where practical.
-- Cover reads, writes, approval-required writes, webhook verification, replay rejection, and scope denial.
-
-Exit criteria:
-
-- Top connectors have real non-mocked verification paths before public launch.
-
-## First Provider Priorities
-
-Tier 1 first-party:
-
-- Gmail
-- Google Calendar
-- Slack
-- GitHub
-- Notion
-- Stripe
-- HubSpot
-- Airtable
-- Microsoft Calendar / Outlook
-- Linear
-
-Tier 2 first-party or vendor-backed:
-
-- Google Sheets
-- Google Drive
-- Salesforce
-- Zendesk
-- Intercom
-- Jira
-- Asana
-- Trello
-- Resend
-- Twilio
-- Supabase
-- Postgres
-
-Long tail:
-
-- Import from OpenAPI/GraphQL/MCP catalogs.
-- Use vendor-backed providers only as coverage accelerators.
-- Promote high-volume or high-trust integrations to first-party.
-
-## OSS Mining Policy
-
-Use permissively licensed projects aggressively, especially MIT and Apache-2.0.
-
-Allowed:
-
-- copy, fork, or port license-compatible code with attribution
-- import connector definitions and catalog structure
-- reuse MCP bridge and policy patterns where license permits
-- derive architecture lessons from any public repo
-
-Not allowed without explicit legal/product decision:
-
-- copying restricted-license source into this package
-- inheriting a vendor's auth, storage, tenancy, or billing model as our product contract
-- exposing provider secrets to generated apps or sandboxes
-
-Executor-style systems are priority inspiration for catalog, policy, MCP, and local/dev ergonomics. Nango-style systems are useful for OAuth, sync, and provider quirks, but restricted-license source should be treated as reference material rather than vendored code.
-
-## Launch Gate Checklist
-
-- [x] Tool catalog search works over first-party tools.
-- [x] MCP-compatible tool export is stable.
-- [x] Default policy engine gates writes and destructive actions.
-- [x] Approval artifacts are typed and audit-safe.
-- [x] Sandbox invocation envelope never contains provider credentials.
-- [x] First-party adapters are callable through `IntegrationHub`.
-- [x] Webhook receivers verify signatures and reject replay where provider supports timestamps.
-- [x] Redaction helper covers connections, capabilities, approvals, and invocation logs.
-- [ ] Agent Builder can declare required connectors from generated app specs.
-- [ ] Agent Builder can ask users to connect missing accounts.
-- [ ] Agent Builder can pass scoped capabilities to generated sandbox apps.
-- [ ] Generated sandbox apps can call integrations through the runtime envelope.
-- [ ] Human approval flow exists for writes.
-- [ ] Top provider live smoke tests are documented and environment-gated.
-- [ ] Package README explains the concrete product UX, not only abstractions.
-
-## Definition Of Done
-
-The package is launch-ready when Agent Builder can generate an app that needs at least Gmail, Slack, Calendar, or Stripe; the user can connect the account; the app runs in a sandbox with a scoped capability; reads execute without extra user friction; writes pause for approval; triggers can wake workflows; and every step is observable without leaking secrets.