@tangle-network/agent-integrations 0.14.0 → 0.16.0

package/README.md

@@ -45,6 +45,11 @@ agent-facing tool contract.
   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.
 
@@ -86,6 +91,18 @@ pnpm add @tangle-network/agent-integrations
 | `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. |
@@ -142,6 +159,22 @@ const bundle = await runtime.buildSandboxBundle({
 
 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:
+
+```ts
+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:
 
@@ -205,6 +238,8 @@ Runnable examples live in [`examples/`](./examples):
   first-party adapter provider wiring.
 - [`examples/declarative-rest.ts`](./examples/declarative-rest.ts) - compact
   REST connector spec.
+- [`examples/calendar-exercise-app.ts`](./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.
@@ -214,9 +249,16 @@ without obscuring the package contract.
 - 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,