hips/HIPs/hip-0126-integrations-connectors-and-the-extension-runtime.md

hip, title, author, type, category, status, created, updated, requires

hip	title	author	type	category	status	created	updated	requires
0126	Integrations, Connectors & the Extension Runtime — One Registry, One Way	Hanzo AI Team	Standards Track	Interface	Final	2026-07-07	2026-07-08	HIP-0004, HIP-0010, HIP-0105, HIP-0106

HIP-0126: Integrations, Connectors & the Extension Runtime — One Registry, One Way

Abstract

Hanzo plugs external capability into the platform in three shapes — third-party services (Slack, GitHub, Stripe), AI providers (OpenAI, Anthropic, a BYO GPU fleet), and agent tools (MCP). Each grew its own vocabulary, its own config surface, and its own credential path, and the automation engine still carried the ActivePieces word "pieces" for what the rest of the codebase already calls connectors.

This HIP fixes the vocabulary and the shape. It defines one umbrella concept — the Integration — with exactly three kinds (Connector, Provider, Tool), surfaced through one Integrations registry per org/project, behind one IAM-scoped config/auth surface. It defines Flows (the IFTTT-style trigger→action builder on the @xyflow canvas) as the consumer that wires Connectors together, and it names the Extension Runtime (HIP-0105) as the ONE way custom logic runs — four engines (native Go, goja, wazero, v8go) behind a single Runtime interface — with a Plugin (HIP-0106) being a code extension that runs inside it.

It is deliberately orthogonal and reference-not-duplicate: it aligns the existing standards (HIP-0004 providers, HIP-0010 MCP tools, HIP-0105 extension runtime, HIP-0106 plugin model) into one taxonomy rather than restating them, and it normatively retires "pieces" in favour of "connectors."

Taxonomy

The single decision this HIP encodes:

Integration  (umbrella: an external capability plugged in; ONE registry per org/project)
├── Connector   external-service integration      Slack · GitHub · Stripe   (Flows building block)
├── Provider    AI model / compute provider       OpenAI · Anthropic · BYO  (HIP-0004, HIP-0113, HIP-0124)
└── Tool        MCP / agent tool                  MCP servers · agent tools (HIP-0010)

Flows  (IFTTT trigger→action on the @xyflow canvas)  — consumes Connectors as nodes

Extension Runtime  (HOW custom logic runs; ONE Runtime interface, 4 engines)  (HIP-0105)
├── native (Go)     default; zero-cost, no sandbox
├── goja  (JS/TS)   soft sandbox; multi-tenant SaaS default for user JS
├── wazero (WASM)   hard sandbox; the Rust/TinyGo/AssemblyScript/Python path
└── v8go  (V8)      hard sandbox; cgo; not recommended at high concurrency

Plugin  (a code extension that adds platform capability; runs IN the Extension Runtime)  (HIP-0106)

Definitions (normative):

• Integration — an external capability made available to an org/project. It is the umbrella; it is never a fourth kind alongside its own kinds.
• Connector — an Integration of kind external service, and the unit a Flow step invokes. This is the ONE Hanzo term; "piece" is retired.
• Provider — an Integration of kind AI model / compute provider, governed by HIP-0004.
• Tool — an Integration of kind MCP / agent tool, governed by HIP-0010.
• Flow — an IFTTT-style trigger→action automation authored on the @xyflow graph canvas; its nodes are Connectors.
• Extension — a unit of custom logic plus its extension.json manifest, run by the Extension Runtime (HIP-0105). Answers how code runs, never what is connected.
• Plugin — a code Extension that adds platform capability (the VM/subsystem model, HIP-0106). A Plugin runs in the Extension Runtime.

Specification

1. One Integrations registry per org/project

Every org/project has exactly one logical Integrations registry. It is IAM-scoped: identity and the tenant boundary come from the JWT owner claim (HIP-0026 / HIP-0111), and every registry entry is physically keyed by org, per the tenant-isolation model (HIP-0118). The registry is the ONE place that answers "what is connected here, of every kind, and with what credentials."

• One config/auth surface. Connecting a Connector, a Provider, or a Tool is the same act: authorize (OAuth2 / secret / BYO endpoint), store the credential KMS-sealed (never plaintext), and register the entry. Credentials are custodied by clients/integrations (KMS-sealed, per-org); a connector reaches a token ONLY through integrations.TokenFor, never KMS directly.
• One list, kind-badged. The registry lists all three kinds through one surface; a kind field (connector | provider | tool) is for display and filtering only — the connect / authorize / revoke lifecycle is identical across kinds.
• Not a service mesh. The Integrations registry is the external-capability registry. It is distinct from the internal service plane, which is a socket per plugin resolved per call by peer name and holds no registry at all (HIP-0134). Different axis, different concern; see "Relationship to existing HIPs."

2. Kind: Connector

A Connector is an external-service integration and the Flow building block. It carries a name, a display name, a logo, an auth descriptor, and its actions and triggers — the catalogue schema served at GET /v1/automations/connectors.

Normative rules for the connector surface:

• The catalogue is Catalog{ connectorCount, connectors[] } of ConnectorMetadata. The pre-rename schema (pieceCount, pieces, PieceMetadata, PieceAuth, PieceAction, PieceTrigger) is retired.
• GET /v1/automations/pieces is kept as a byte-identical back-compat alias of /connectors so live clients do not break. It is deprecated; new clients MUST use /connectors.
• A Connector's registry name equals its clients/integrations provider id wherever it needs credentials — one identity for the connector and its credential.

3. Kind: Provider

A Provider is an AI model / compute provider. Its interface, config, and routing are defined by HIP-0004 (unified provider interface), its in-process runtime by HIP-0113, and bring-your-own providers by HIP-0124. This HIP does not redefine providers; it places them as the second kind in the one registry so a Provider is connected, authorized, and revoked through the same surface as a Connector.

4. Kind: Tool

A Tool is an MCP / agent tool. Its manifest, discovery, and invocation contract are defined by HIP-0010. Hanzo Cloud already exposes an org's flows as MCP tools at POST /v1/automations/mcp. This HIP places Tools as the third kind in the one registry; it does not redefine MCP.

5. Flows consume Connectors

Flows are the IFTTT-style automation builder (trigger → action) on the @xyflow graph canvas, executed by the durable engine in clients/automations (running on the ONE shared in-process hanzoai/tasks engine). A Flow's nodes are Connectors: a trigger node starts the flow, action nodes invoke connector actions. Flows are the primary consumer of the Connector kind.

The persisted flow-graph wire schema (the node discriminants PIECE / PIECE_TRIGGER and the step fields pieceName / pieceVersion) is the contract authored by the reused builder canvas and stored in flow-version JSON. Because renaming it would break live builder clients and every stored flow, it is retained as-is at this stage; aligning the flow-step schema to the connector vocabulary is a staged migration coordinated with the builder (see Backwards Compatibility).

6. The Extension Runtime — HOW custom logic runs

When an Integration needs custom logic — a connector transform, a validator, a provider adapter, a per-record hook — that logic runs in the In-Process Extension Runtime (HIP-0105). There is ONE execution model:

• One Runtime interface, four backing engines:

  Engine	Language	Sandbox	Use
  native	Go	none	default — Hanzo-authored, zero abstraction cost
  goja	JS/TS	soft	multi-tenant SaaS default for user JS (~9 KB/module)
  wazero	WASM	hard	user code needing a hard sandbox; the Rust/TinyGo/AssemblyScript/Python path
  v8go	V8	hard (cgo)	JS needing hard isolation; not recommended at high concurrency

• One manifest. Every extension carries a sibling extension.json (name, version, runtime ∈ {native, goja, wazero, v8go}, module, exports). JSON is the wire format across all engines.

• One contract, two mount points (HIP-0105 / HIP-0106): in-process hooks and hanzoai/zip web routes mount the same runtime the same way.

• Multi-tenant gate. Operators MUST restrict AllowedRuntimes to hard-sandbox engines (wazero) for untrusted tenant code; soft-sandbox engines (goja, v8go-experimental) are for the "ordinary customers, not adversaries" threat model only.

7. Plugin — a code extension in the runtime

A Plugin is a code Extension that adds platform capability (a subsystem / VM), specified by HIP-0106. A Plugin runs in the Extension Runtime; "plugin" is therefore a specialization of "extension," never a synonym for "integration" or "connector." The reference impl lives at ~/work/hanzo/base/plugins/{extruntime,gojavm,wasmvm,v8vm} (base#3).

8. Normative rules (the "one way")

1. "Pieces" is banned. The external-service kind is a Connector everywhere: identifiers, routes, JSON fields, comments, docs, UI. The only surviving /pieces token is the explicit deprecated back-compat alias.
2. One registry, not per-product scatter. An org/project has exactly one Integrations registry spanning all three kinds. New integration kinds are new entries in it, never new parallel registries.
3. One config/auth surface. Connect / authorize / store (KMS-sealed) / revoke is one lifecycle for every kind; kind is display metadata only.
4. Two axes stay separate. Integration (what is plugged in) and Extension Runtime (how custom logic runs) are orthogonal. Never name one with the other's word.
5. Four engines, one interface. The Extension Runtime is the ONE execution model; no service invents a fifth in-process code host.
6. Reference, don't duplicate. Provider (HIP-0004), Tool (HIP-0010), Runtime (HIP-0105), Plugin (HIP-0106) remain the authoritative specs; this HIP aligns them into the taxonomy and does not restate their internals.

Relationship to existing HIPs

Reference-don't-duplicate. This HIP is the umbrella; each row below stays the authority for its slice.

HIP	Owns	This HIP's relationship
HIP-0004	Unified AI provider interface	Places Provider as a registry kind; does not redefine
HIP-0010	MCP integration standards	Places Tool as a registry kind; does not redefine
HIP-0134	One process, one socket, one identity	Disambiguation: owns the INTERNAL service plane (a socket per plugin, resolved by peer name). That is not the external Integrations registry. Orthogonal — different axis, no overlap
HIP-0105	In-process extension runtime	Owns the 4-engine Runtime; this HIP names it the ONE execution model for integration/plugin logic
HIP-0113	Provider runtime	Provider-kind execution; referenced by the Provider kind
HIP-0106	Plugin & VM model	Owns Plugin; this HIP positions Plugin as an Extension in the runtime
HIP-0124	BYO provider & AI	BYO Providers; a registry Provider-kind onboarding path

Note on the internal plane. Service-to-service inside a deployment is a socket per plugin, resolved per call by peer name (HIP-0134); what it resolves are Hanzo plugins. The Integrations registry here registers external capabilities (connectors/providers/tools) for a tenant. The two never collide; this HIP does not modify HIP-0134.

Status: shipped vs staged

Piece of the taxonomy	Status	Evidence
Connector framework (native-Go, self-registering)	Shipped	clients/automations/connector.go, connector_core.go
Connector catalogue renamed pieces→connectors + /pieces alias	Shipped	GET /v1/automations/connectors (this HIP's companion cloud PR)
Per-org connector credentials, KMS-sealed	Shipped	clients/integrations (integrations.TokenFor)
Flows (durable trigger→action, @xyflow)	Shipped	clients/automations engine on hanzoai/tasks
Providers (unified interface, gateway, BYO)	Shipped	HIP-0004 gateway, HIP-0113, HIP-0124
Tools (MCP)	Shipped	HIP-0010; POST /v1/automations/mcp
Extension Runtime (4 engines, manifest)	Shipped	base#3 plugins/{extruntime,gojavm,wasmvm,v8vm}; cloud clients/gojahost, clients/plugin, clients/framework/hook.go (HIP-0105)
Plugin / VM model	Shipped (spec)	HIP-0106
Unified cross-kind registry surface (one API listing Connector+Provider+Tool under one config/auth surface)	Staged	today: connectors in automations, providers at gateway, tools in MCP — same lifecycle, not yet one endpoint
Flow-step schema aligned to connector vocabulary (PIECE→…, pieceName→…)	Staged	retained for builder + stored-flow back-compat; needs builder-coordinated migration

Reference implementation

• Connectors: github.com/hanzoai/cloud clients/automations (connector.go, connector_core.go, catalogue at /v1/automations/connectors).
• Integration credentials: clients/integrations (KMS-sealed, per-org).
• Extension Runtime: github.com/hanzoai/base plugins/{extruntime,gojavm,wasmvm,v8vm}; cloud seams clients/gojahost, clients/plugin (the CLOUD_PLUGINS manifest), clients/framework/hook.go.

Security considerations

• Tenant isolation is physical. Every registry entry and every stored credential is keyed by the validated org (principal.Tenant from the JWT owner claim); a caller can never read or author another tenant's integrations (HIP-0118).
• Credentials are KMS-sealed, never plaintext. All three kinds store secrets through KMS via clients/integrations; code reaches tokens only through the custody API.
• Sandbox gate. Untrusted tenant Extension code MUST run in a hard-sandbox engine (wazero); soft-sandbox engines (goja, v8go-experimental) are limited to the non-adversarial threat model. The AllowedRuntimes gate is enforced at the host boundary (HIP-0105).
• One auth surface, one audit trail. Because connect/authorize/revoke is one lifecycle, every kind's privileged action is audited uniformly (AU-2/AU-12).

Backwards compatibility

None. /v1/automations/connectors is the address; there is no /pieces to keep alive beside it, and the flow-graph schema says connector because that is what the thing is called.

References

• HIP-0004 — LLM Gateway: Unified AI Provider Interface
• HIP-0010 — Model Context Protocol (MCP) Integration Standards
• HIP-0026 — Identity & Access Management Standard
• HIP-0105 — In-Process Extension Runtime Standard
• HIP-0106 — Unified Hanzo Cloud Binary
• HIP-0111 — Hanzo IAM Authentication Standard
• HIP-0113 — Cognitive Sidecar & Hanzo Engine Provider Runtime
• HIP-0106 — Hanzo Plugin & VM Model
• HIP-0118 — SuperAdmin & Tenant Isolation Model
• HIP-0124 — Bring-Your-Own Provider & AI
• HIP-0134 — One Process, One Socket, One Identity (internal service plane — disambiguation)

Copyright

This document is placed in the public domain.