Files
skills/public/hip-0126.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

328 lines
31 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-0126</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hip-0126.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-0126">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-0126.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hip-0126</h1><p class="lede">HIP-126: Integrations, Connectors &amp; the Extension Runtime — One Registry, One Way. Status Final. Hanzo architectural specification.</p><h1>HIP-0126: Integrations, Connectors &amp; the Extension Runtime — One Registry, One Way</h1>
<h2>Abstract</h2>
<p>Hanzo plugs external capability into the platform in three shapes — third-party <strong>services</strong> (Slack, GitHub, Stripe), AI <strong>providers</strong> (OpenAI, Anthropic, a BYO GPU fleet), and agent <strong>tools</strong> (MCP). Each grew its own vocabulary, its own config surface, and its own credential path, and the automation engine still carried the ActivePieces word <strong>&quot;pieces&quot;</strong> for what the rest of the codebase already calls <strong>connectors</strong>.</p>
<p>This HIP fixes the vocabulary and the shape. It defines <strong>one umbrella concept — the Integration</strong> — with exactly three kinds (<strong>Connector</strong>, <strong>Provider</strong>, <strong>Tool</strong>), surfaced through <strong>one Integrations registry</strong> per org/project, behind <strong>one IAM-scoped config/auth surface</strong>. It defines <strong>Flows</strong> (the IFTTT-style trigger→action builder on the <code>@xyflow</code> canvas) as the consumer that wires Connectors together, and it names the <strong>Extension Runtime</strong> (HIP-0105) as the ONE way custom logic <em>runs</em> — four engines (native Go, goja, wazero, v8go) behind a single <code>Runtime</code> interface — with a <strong>Plugin</strong> (HIP-0106) being a code extension that runs inside it.</p>
<p>It is deliberately <strong>orthogonal and reference-not-duplicate</strong>: 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 <strong>retires &quot;pieces&quot; in favour of &quot;connectors.&quot;</strong></p>
<h2>Taxonomy</h2>
<p>The single decision this HIP encodes:</p>
<pre><code>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)</code></pre>
<p><strong>Definitions (normative):</strong></p>
<ul><li><strong>Integration</strong> — an external capability made available to an org/project. It is</li></ul>
<p> the umbrella; it is never a fourth kind alongside its own kinds.</p>
<ul><li><strong>Connector</strong> — an Integration of kind <em>external service</em>, and the unit a Flow</li></ul>
<p> step invokes. <strong>This is the ONE Hanzo term; &quot;piece&quot; is retired.</strong></p>
<ul><li><strong>Provider</strong> — an Integration of kind <em>AI model / compute provider</em>, governed by</li></ul>
<p> HIP-0004.</p>
<ul><li><strong>Tool</strong> — an Integration of kind <em>MCP / agent tool</em>, governed by HIP-0010.</li><li><strong>Flow</strong> — an IFTTT-style trigger→action automation authored on the <code>@xyflow</code></li></ul>
<p> graph canvas; its nodes are Connectors.</p>
<ul><li><strong>Extension</strong> — a unit of custom logic plus its <code>extension.json</code> manifest, run by</li></ul>
<p> the Extension Runtime (HIP-0105). Answers <em>how code runs</em>, never <em>what is connected</em>.</p>
<ul><li><strong>Plugin</strong> — a code Extension that adds platform capability (the VM/subsystem</li></ul>
<p> model, HIP-0106). A Plugin runs in the Extension Runtime.</p>
<h2>Specification</h2>
<h3>1. One Integrations registry per org/project</h3>
<p>Every org/project has <strong>exactly one</strong> logical Integrations registry. It is <strong>IAM-scoped</strong>: identity and the tenant boundary come from the JWT <code>owner</code> 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 &quot;what is connected here, of every kind, and with what credentials.&quot;</p>
<ul><li><strong>One config/auth surface.</strong> Connecting a Connector, a Provider, or a Tool is</li></ul>
<p> the same <em>act</em>: authorize (OAuth2 / secret / BYO endpoint), store the credential <strong>KMS-sealed</strong> (never plaintext), and register the entry. Credentials are custodied by <code>clients/integrations</code> (KMS-sealed, per-org); a connector reaches a token ONLY through <code>integrations.TokenFor</code>, never KMS directly.</p>
<ul><li><strong>One list, kind-badged.</strong> The registry lists all three kinds through one</li></ul>
<p> surface; a <code>kind</code> field (<code>connector</code> | <code>provider</code> | <code>tool</code>) is for display and filtering only — the connect / authorize / revoke lifecycle is identical across kinds.</p>
<ul><li><strong>Not a service mesh.</strong> The Integrations registry is the <em>external-capability</em></li></ul>
<p> registry. It is distinct from the <em>internal service</em> 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 &quot;Relationship to existing HIPs.&quot;</p>
<h3>2. Kind: Connector</h3>
<p>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 <strong><code>GET /v1/automations/connectors</code></strong>.</p>
<p>Normative rules for the connector surface:</p>
<ul><li>The catalogue is <code>Catalog{ connectorCount, connectors[] }</code> of</li></ul>
<p> <code>ConnectorMetadata</code>. The pre-rename schema (<code>pieceCount</code>, <code>pieces</code>, <code>PieceMetadata</code>, <code>PieceAuth</code>, <code>PieceAction</code>, <code>PieceTrigger</code>) is <strong>retired</strong>.</p>
<ul><li><strong><code>GET /v1/automations/pieces</code> is kept as a byte-identical back-compat alias</strong></li></ul>
<p> of <code>/connectors</code> so live clients do not break. It is <code>deprecated</code>; new clients MUST use <code>/connectors</code>.</p>
<ul><li>A Connector&#x27;s registry name <strong>equals</strong> its <code>clients/integrations</code> provider id</li></ul>
<p> wherever it needs credentials — one identity for the connector and its credential.</p>
<h3>3. Kind: Provider</h3>
<p>A Provider is an AI model / compute provider. Its interface, config, and routing are defined by <strong>HIP-0004</strong> (unified provider interface), its in-process runtime by <strong>HIP-0113</strong>, and bring-your-own providers by <strong>HIP-0124</strong>. 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.</p>
<h3>4. Kind: Tool</h3>
<p>A Tool is an MCP / agent tool. Its manifest, discovery, and invocation contract are defined by <strong>HIP-0010</strong>. Hanzo Cloud already exposes an org&#x27;s flows as MCP tools at <code>POST /v1/automations/mcp</code>. This HIP places Tools as the third kind in the one registry; it does not redefine MCP.</p>
<h3>5. Flows consume Connectors</h3>
<p><strong>Flows</strong> are the IFTTT-style automation builder (trigger → action) on the <code>@xyflow</code> graph canvas, executed by the durable engine in <code>clients/automations</code> (running on the ONE shared in-process <code>hanzoai/tasks</code> engine). A Flow&#x27;s nodes are <strong>Connectors</strong>: a trigger node starts the flow, action nodes invoke connector actions. Flows are the primary consumer of the Connector kind.</p>
<p>The persisted flow-graph wire schema (the node discriminants <code>PIECE</code> / <code>PIECE_TRIGGER</code> and the step fields <code>pieceName</code> / <code>pieceVersion</code>) 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 <strong>retained as-is</strong> at this stage; aligning the flow-step schema to the connector vocabulary is a <strong>staged</strong> migration coordinated with the builder (see Backwards Compatibility).</p>
<h3>6. The Extension Runtime — HOW custom logic runs</h3>
<p>When an Integration needs <em>custom logic</em> — a connector transform, a validator, a provider adapter, a per-record hook — that logic runs in the <strong>In-Process Extension Runtime (HIP-0105)</strong>. There is ONE execution model:</p>
<ul><li><strong>One <code>Runtime</code> interface</strong>, four backing engines:</li></ul>
<p> | Engine | Language | Sandbox | Use | |---|---|---|---| | <code>native</code> | Go | none | <strong>default</strong> — Hanzo-authored, zero abstraction cost | | <code>goja</code> | JS/TS | soft | multi-tenant SaaS default for user JS (~9 KB/module) | | <code>wazero</code> | WASM | <strong>hard</strong> | user code needing a hard sandbox; the Rust/TinyGo/AssemblyScript/<strong>Python</strong> path | | <code>v8go</code> | V8 | hard (cgo) | JS needing hard isolation; not recommended at high concurrency |</p>
<ul><li><strong>One manifest.</strong> Every extension carries a sibling <code>extension.json</code></li></ul>
<p> (<code>name</code>, <code>version</code>, <code>runtime</code> ∈ {native, goja, wazero, v8go}, <code>module</code>, <code>exports</code>). JSON is the wire format across all engines.</p>
<ul><li><strong>One contract, two mount points</strong> (HIP-0105 / HIP-0106): in-process hooks and</li></ul>
<p> <code>hanzoai/zip</code> web routes mount the same runtime the same way.</p>
<ul><li><strong>Multi-tenant gate.</strong> Operators MUST restrict <code>AllowedRuntimes</code> to</li></ul>
<p> hard-sandbox engines (wazero) for untrusted tenant code; soft-sandbox engines (goja, v8go-experimental) are for the &quot;ordinary customers, not adversaries&quot; threat model only.</p>
<h3>7. Plugin — a code extension in the runtime</h3>
<p>A <strong>Plugin</strong> is a code Extension that adds platform capability (a subsystem / VM), specified by <strong>HIP-0106</strong>. A Plugin <em>runs in</em> the Extension Runtime; &quot;plugin&quot; is therefore a specialization of &quot;extension,&quot; never a synonym for &quot;integration&quot; or &quot;connector.&quot; The reference impl lives at <code>~/work/hanzo/base/plugins/{extruntime,gojavm,wasmvm,v8vm}</code> (base#3).</p>
<h3>8. Normative rules (the &quot;one way&quot;)</h3>
<ol><li><strong>&quot;Pieces&quot; is banned.</strong> The external-service kind is a <strong>Connector</strong></li></ol>
<p> everywhere: identifiers, routes, JSON fields, comments, docs, UI. The only surviving <code>/pieces</code> token is the explicit deprecated back-compat alias.</p>
<ol><li><strong>One registry, not per-product scatter.</strong> An org/project has exactly one</li></ol>
<p> Integrations registry spanning all three kinds. New integration kinds are new entries in it, never new parallel registries.</p>
<ol><li><strong>One config/auth surface.</strong> Connect / authorize / store (KMS-sealed) / revoke</li></ol>
<p> is one lifecycle for every kind; <code>kind</code> is display metadata only.</p>
<ol><li><strong>Two axes stay separate.</strong> <em>Integration</em> (what is plugged in) and *Extension</li></ol>
<p> Runtime* (how custom logic runs) are orthogonal. Never name one with the other&#x27;s word.</p>
<ol><li><strong>Four engines, one interface.</strong> The Extension Runtime is the ONE execution</li></ol>
<p> model; no service invents a fifth in-process code host.</p>
<ol><li><strong>Reference, don&#x27;t duplicate.</strong> Provider (HIP-0004), Tool (HIP-0010),</li></ol>
<p> Runtime (HIP-0105), Plugin (HIP-0106) remain the authoritative specs; this HIP aligns them into the taxonomy and does not restate their internals.</p>
<h2>Relationship to existing HIPs</h2>
<p>Reference-don&#x27;t-duplicate. This HIP is the umbrella; each row below stays the authority for its slice.</p>
<p>| HIP | Owns | This HIP&#x27;s relationship | |---|---|---| | HIP-0004 | Unified AI provider interface | Places <strong>Provider</strong> as a registry kind; does not redefine | | HIP-0010 | MCP integration standards | Places <strong>Tool</strong> as a registry kind; does not redefine | | HIP-0134 | One process, one socket, one identity | <strong>Disambiguation:</strong> owns the INTERNAL <em>service</em> 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 <strong>4-engine Runtime</strong>; 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 &amp; VM model | Owns <strong>Plugin</strong>; this HIP positions Plugin as an Extension in the runtime | | HIP-0124 | BYO provider &amp; AI | BYO Providers; a registry Provider-kind onboarding path |</p>
<p><strong>Note on the internal plane.</strong> Service-to-service inside a deployment is a socket per plugin, resolved per call by peer name (HIP-0134); what it resolves are <em>Hanzo plugins</em>. The Integrations registry here registers <em>external capabilities</em> (connectors/providers/tools) for a tenant. The two never collide; this HIP does not modify HIP-0134.</p>
<h2>Status: shipped vs staged</h2>
<p>| Piece of the taxonomy | Status | Evidence | |---|---|---| | Connector framework (native-Go, self-registering) | <strong>Shipped</strong> | <code>clients/automations/connector.go</code>, <code>connector_core.go</code> | | Connector catalogue renamed pieces→connectors + <code>/pieces</code> alias | <strong>Shipped</strong> | <code>GET /v1/automations/connectors</code> (this HIP&#x27;s companion cloud PR) | | Per-org connector credentials, KMS-sealed | <strong>Shipped</strong> | <code>clients/integrations</code> (<code>integrations.TokenFor</code>) | | Flows (durable trigger→action, <code>@xyflow</code>) | <strong>Shipped</strong> | <code>clients/automations</code> engine on <code>hanzoai/tasks</code> | | Providers (unified interface, gateway, BYO) | <strong>Shipped</strong> | HIP-0004 gateway, HIP-0113, HIP-0124 | | Tools (MCP) | <strong>Shipped</strong> | HIP-0010; <code>POST /v1/automations/mcp</code> | | Extension Runtime (4 engines, manifest) | <strong>Shipped</strong> | base#3 <code>plugins/{extruntime,gojavm,wasmvm,v8vm}</code>; cloud <code>clients/gojahost</code>, <code>clients/plugin</code>, <code>clients/framework/hook.go</code> (HIP-0105) | | Plugin / VM model | <strong>Shipped (spec)</strong> | HIP-0106 | | <strong>Unified cross-kind registry surface</strong> (one API listing Connector+Provider+Tool under one config/auth surface) | <strong>Staged</strong> | today: connectors in automations, providers at gateway, tools in MCP — same lifecycle, not yet one endpoint | | Flow-step schema aligned to connector vocabulary (<code>PIECE</code>→…, <code>pieceName</code>→…) | <strong>Staged</strong> | retained for builder + stored-flow back-compat; needs builder-coordinated migration |</p>
<h2>Reference implementation</h2>
<ul><li><strong>Connectors:</strong> <code>github.com/hanzoai/cloud</code> <code>clients/automations</code></li></ul>
<p> (<code>connector.go</code>, <code>connector_core.go</code>, catalogue at <code>/v1/automations/connectors</code>).</p>
<ul><li><strong>Integration credentials:</strong> <code>clients/integrations</code> (KMS-sealed, per-org).</li><li><strong>Extension Runtime:</strong> <code>github.com/hanzoai/base</code> <code>plugins/{extruntime,gojavm,wasmvm,v8vm}</code>;</li></ul>
<p> cloud seams <code>clients/gojahost</code>, <code>clients/plugin</code> (the <code>CLOUD_PLUGINS</code> manifest), <code>clients/framework/hook.go</code>.</p>
<h2>Security considerations</h2>
<ul><li><strong>Tenant isolation is physical.</strong> Every registry entry and every stored</li></ul>
<p> credential is keyed by the validated org (<code>principal.Tenant</code> from the JWT <code>owner</code> claim); a caller can never read or author another tenant&#x27;s integrations (HIP-0118).</p>
<ul><li><strong>Credentials are KMS-sealed, never plaintext.</strong> All three kinds store secrets</li></ul>
<p> through KMS via <code>clients/integrations</code>; code reaches tokens only through the custody API.</p>
<ul><li><strong>Sandbox gate.</strong> Untrusted tenant Extension code MUST run in a hard-sandbox</li></ul>
<p> engine (wazero); soft-sandbox engines (goja, v8go-experimental) are limited to the non-adversarial threat model. The <code>AllowedRuntimes</code> gate is enforced at the host boundary (HIP-0105).</p>
<ul><li><strong>One auth surface, one audit trail.</strong> Because connect/authorize/revoke is one</li></ul>
<p> lifecycle, every kind&#x27;s privileged action is audited uniformly (AU-2/AU-12).</p>
<h2>Backwards compatibility</h2>
<p>None. <code>/v1/automations/connectors</code> is the address; there is no <code>/pieces</code> to keep alive beside it, and the flow-graph schema says <code>connector</code> because that is what the thing is called.</p>
<h2>References</h2>
<ul><li>HIP-0004 — LLM Gateway: Unified AI Provider Interface</li><li>HIP-0010 — Model Context Protocol (MCP) Integration Standards</li><li>HIP-0026 — Identity &amp; Access Management Standard</li><li>HIP-0105 — In-Process Extension Runtime Standard</li><li>HIP-0106 — Unified Hanzo Cloud Binary</li><li>HIP-0111 — Hanzo IAM Authentication Standard</li><li>HIP-0113 — Cognitive Sidecar &amp; Hanzo Engine Provider Runtime</li><li>HIP-0106 — Hanzo Plugin &amp; VM Model</li><li>HIP-0118 — SuperAdmin &amp; Tenant Isolation Model</li><li>HIP-0124 — Bring-Your-Own Provider &amp; AI</li><li>HIP-0134 — One Process, One Socket, One Identity (internal service plane — disambiguation)</li></ul>
<h2>Copyright</h2>
<p>This document is placed in the public domain.</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hip-0126.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>