Files

Tom Boucher 69fef7c00e docs(#1683 ): Diátaxis host-integration docs + versioning policy + ADR-1239 Accepted — Slice 3 (#1940 )

- how-to: author a host-plugin (external-author guide against the SDK surface)
- tutorial: embed GSD in a new host (end-to-end programmatic-cli example)
- reference: the Host-Integration Interface (axes, adapters, handshake, profiles)
- explanation: interface versioning + deprecation policy (additive vs breaking,
  PROTOCOL_VERSION bumps, deprecation window)
- ADR-1239 Status: Proposed → Accepted (Phases B–E shipped)

2026-07-02 18:38:11 -04:00

4.3 KiB

Raw Blame History

Reference: the Host-Integration Interface

This is the normative reference for the GSD Host-Integration Interface (ADR-1239) — the versioned, negotiated contract over which any host embeds GSD's orchestration loop. The published surface is the SDK entry (src/host-integration-sdk.cts); this document specifies every symbol on it.

The governing principle: every axis value a host declares must come from that host's authoritative documentation. Where docs are silent, the host declares the undocumented sentinel and the engine degrades fail-closed — it never assumes a capability.

Protocol version

PROTOCOL_VERSION (a positive integer) is the interface version. It governs the negotiated capability set; see the versioning policy for what a bump means.

The eight negotiated axes

HOST_INTEGRATION_AXES is the closed vocabulary. Each axis takes a documented value (or the undocumented sentinel):

Axis	Values
`embeddingMode`	`imperative` \| `declarative`
`commandSurface`	`slash-file` \| `slash-programmatic` \| `slash-toml` \| `palette` \| `prose-only`
`dispatch`	struct: `{ namedDispatch, nested, maxDepth, background, subagentToolkit, backgroundDispatch }`
`modelMode`	`active` \| `passive`
`hookBus`	`host` \| `engine` \| `none`
`stateIO`	`filesystem` \| `sandboxed-storage` \| `session-log-append`
`transport`	`mcp` \| `native-extension`
`runtime`	`node` \| `bun` \| `sandboxed-web` \| `python` \| `go` \| `rust` \| `electron` \| `other`

Classification + negotiation

profileOf(axes) → 'programmatic-cli' | 'declarative-cli' | 'ide' | null.
negotiateHostCapabilities(host, engine) → { protocolVersion, effective, points, warnings } — the in-process negotiation. Pure; never throws.
handleHandshakeRequest(request) / buildHandshakeRequest(descriptor) — the serialized (out-of-process) form of the same negotiation, JSON-safe across a wire boundary. The two are consistent: a serialized request yields the same effective axes as the in-process call.
degradationFor(point, axes) → { level, fallback, unknown? } for one of the six interface points (command | dispatch | model | hooks | state | artifact).
hookEventSurfaceFor(hookEvents) → the host-fireable hook events for a dialect ('claude' | 'gemini' | 'opencode-subset'), or null if unknown.
shouldFlattenDispatch(dispatch) → true when the orchestrator must run inline (fail-closed).

The engine adapters

All five satisfy a common { kind, runtime, install, uninstall } shape and are constructed fail-closed (they throw if a required host primitive is absent):

Adapter	Factory	Selected by
Embedding (declarative)	`createDeclarativeAdapter({runtime})`	`embeddingMode: 'declarative'`
Embedding (imperative)	`createImperativeAdapter({runtime})`	`embeddingMode: 'imperative'` (also exposes the composed `registry`)
Model	`createModelAdapter({modelMode}, {sendRequest?})`	`modelMode` (`'active'` needs a host `sendRequest`)
Hook bus	`createHookBus({bus}, {hostEmit?})`	`hookBus` (`'host'` needs a host `hostEmit`)
State IO	`createStateIO({io}, {backend?})`	`stateIO` (`'sandboxed-storage'`/`'session-log-append'` need a host `backend`)

The declarative + imperative adapters delegate install/uninstall in-process to the same installRuntimeArtifacts engine function bin/install.js uses, so adapter output is byte-identical to a first-party install (gated by tests/golden-install-parity.test.cjs).

Profiles

PROFILE_BASELINES fixes the three reference profiles:

Profile	Baseline
`programmatic-cli`	imperative, slash-file, host bus, filesystem, mcp, node
`declarative-cli`	declarative, slash-file, host bus, filesystem, mcp, node
`ide`	imperative, palette, active model, engine bus, sandboxed-storage, sandboxed-web

4.3 KiB Raw Blame History