6cfa0c55d2
Removes kilo, kimi, kimi-code, copilot, windsurf, augment, trae, qwen, hermes, cline, codebuddy and pi end to end: capability descriptors, installer branches and converters (bin/install.js 14.9k -> 11.2k lines), TypeScript converters, hook surfaces and runtime homes, review lanes qwen/kimi-code, the two pi migrations, Kimi payload normalization in the hook guards, dead hostBehaviors vocabulary, launcher home probes, fixtures, runtime-specific tests and the prose that presented them as supported. Installer output for the six kept runtimes is byte-identical to before the prune. The Kimi tool-vocabulary tests in workflow-guard, read-guard and read-injection-scanner are left in place pending a decision.
80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# 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 | 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
|
|
|
|
```js
|
|
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`:
|
|
|
|
```js
|
|
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, 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.
|
|
|
|
## See also
|
|
|
|
- **Tutorial:** `docs/tutorials/embed-msd-in-a-new-host.md` — a complete end-to-end embedding.
|
|
- **Reference:** `docs/reference/host-integration-interface.md` — every axis, adapter, and the handshake.
|
|
- **Versioning:** `docs/explanation/interface-versioning-policy.md` — what evolves additively vs. breaking.
|