Files

Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)

Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.

2026-10-06 01:47:40 +02:00

3.4 KiB

Raw Blame History

How to author a host-plugin for MSD

This guide is for external tool authors who want to embed MSD's orchestration loop (dispatch + hooks + model + state) into a new host — a CLI, IDE, or agent runtime MSD does not special-case — by writing a host-plugin against the published Host-Integration SDK, without modifying msd-core source.

The contract is the SDK entry (src/host-integration-sdk.cts → msd-core/bin/lib/host-integration-sdk.cjs): import only from it. Everything it re-exports is public and versioned (PROTOCOL_VERSION); everything else in msd-core is internal and may change. A smoke test (tests/sdk-smoke.test.cjs) proves a third-party host can be built from this surface alone.

1. Decide your host's profile

Classify your host into one of three profiles (the SDK's profileOf does this from your axes):

Profile	Example hosts	Binding
`programmatic-cli`	OpenCode, pi	imperative adapter (`createImperativeAdapter`)
`declarative-cli`	Antigravity, Codex	declarative adapter (`createDeclarativeAdapter`)
`ide`	VS Code	imperative adapter + engine-owned hook bus + active model + sandboxed state

2. Declare your host's integration axes

Declare the nine negotiated axes (embeddingMode, commandSurface, dispatch, modelMode, hookBus, stateIO, transport, runtime, effortSurface) from your host's authoritative documentation — never infer. Where the docs are silent, use the undocumented sentinel (the SDK degrades it fail-closed). See docs/reference/host-integration-interface.md for the closed vocabulary.

3. Compose the engine adapters

const SDK = require('@golem15/msd-core/sdk'); // the published entry

// Engine-owned hook bus (for hosts with no event bus, e.g. VS Code):
const hookBus = SDK.createHookBus({ bus: 'engine' });

// Active model via a host provider (e.g. vscode.lm); or 'passive' for CLIs:
const model = SDK.createModelAdapter({ modelMode: 'active' }, { sendRequest: hostSendRequest });

// State IO — filesystem for CLIs, sandboxed-storage for IDEs/web:
const stateIO = SDK.createStateIO({ io: 'filesystem' });

// The engine-as-library adapter bound to your runtime id:
const adapter = SDK.createImperativeAdapter({ runtime: 'my-host' });

4. Negotiate capabilities (serialized, for out-of-process hosts)

If your host runs out-of-process (can't share object refs with the engine), use the serialized handshake instead of the in-process negotiateHostCapabilities:

const req = SDK.buildHandshakeRequest({ ...myAxes });
const { effective, points, warnings } = SDK.handleHandshakeRequest(req);

The result is identical to the in-process negotiation for the same axes — that consistency is the contract.

5. Bind your host primitives + ship

Map the six interface points (command, dispatch, model, hooks, state, artifact) to your host's primitives (palette/chat, plugin API, provider calls, etc.). The reference host-plugins (OpenCode, Antigravity, pi, VS Code — see Phase 5) are canonical examples to mirror. Your host-plugin is now a self-contained artifact; no msd-core source change is required.

3.4 KiB Raw Blame History