feat(#2093): migrate Kilo onto EoS imperative adapter + hook-bus/model/MCP/dispatch upgrades (ADR-1239)
Fold remaining isKilo logic branches into descriptor-driven reads: finishPermissionWriter (uninstall cleanup), skipSharedHooksInstall (hooks copy), and a skills converter-name registry (the artifactLayout.converter field is now load-bearing, not decorative). frontmatterDialect stays the documented dispatch key for frontmatter (no descriptor field for it). Dead isKilo destructure bindings removed. Byte-identical golden parity for all 16 runtimes (opencode, which shares kilo's combined-family path, verified clean). UPGRADE 1 (hook bus): install .kilo/plugins/gsd-core.js native plugin + extensionEvents:"kilo" + EXTENSION_EVENT_SURFACES.kilo (OpenCode-fork bus). UPGRADE 2 (active model): populate runtimeTierDefaults.kilo + thread modelOverride through convertClaudeToKiloFrontmatter — model no longer stripped from agents. UPGRADE 3 (MCP): document the gsd-core MCP companion under kilo's mcp config key. UPGRADE 4 (named dispatch): agents/*.md mode:subagent roster is the Task-tool dispatch surface (tested); subagentToolkit stays 'undocumented' per AC so dispatch degrades to 'degraded' by design. Model-catalog single-source edit ripples the shared model-catalog.json hash into all 16 golden fixtures (expected). Inline defect fixes (no-defer): stale- bake-guard resolveAgentDir 'agent'->'agents' (was a silent no-op for opencode/ codex), hardcoded 'Removed OpenCode plugin' uninstall log -> generic, and the connect-gsd-mcp-server.md OpenCode mcpServers->mcp doc error. Tests: kilo-imperative-reference (adapter/axes/fail-closed/degradation/ hostBehaviors + widened isKilo source-grep across 4 modules) + kilo-upgrades (plugin parity+load, model-override converter, agents dispatch surface, MCP doc). Matrix + how-to + config docs updated; changeset added. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -551,14 +551,26 @@ function hookEventSurfaceFor(hookEvents: unknown): readonly string[] | null {
|
||||
// events (session/tool/file/permission); pi ~30 fine-grained extension events;
|
||||
// 'none' = the host exposes no extension surface and the engine owns the bus
|
||||
// (VS Code). Declarative hosts (no plugin API) do not set `extensionEvents`.
|
||||
// OpenCode's plugin event surface (ADR-1239 §research; ~25 documented events,
|
||||
// GSD binds this subset). Hoisted to a named const — rather than duplicated
|
||||
// object literals — so the `kilo` dialect below (#2093) can reuse the IDENTICAL
|
||||
// array instead of a copy-pasted one that could silently drift out of sync.
|
||||
const OPENCODE_EXTENSION_EVENTS = Object.freeze([
|
||||
'session.created', 'session.idle', 'experimental.session.compacting',
|
||||
'tool.execute.before', 'tool.execute.after', 'file.edited',
|
||||
// #2087 — additional documented plugin events GSD binds (opencode.ai/docs/plugins):
|
||||
// permission decisions + session error surface.
|
||||
'permission.asked', 'permission.replied', 'session.error',
|
||||
]);
|
||||
|
||||
const EXTENSION_EVENT_SURFACES: Readonly<Record<string, readonly string[]>> = Object.freeze({
|
||||
opencode: Object.freeze([
|
||||
'session.created', 'session.idle', 'experimental.session.compacting',
|
||||
'tool.execute.before', 'tool.execute.after', 'file.edited',
|
||||
// #2087 — additional documented plugin events GSD binds (opencode.ai/docs/plugins):
|
||||
// permission decisions + session error surface.
|
||||
'permission.asked', 'permission.replied', 'session.error',
|
||||
]),
|
||||
opencode: OPENCODE_EXTENSION_EVENTS,
|
||||
// #2093 — Kilo Code is an OpenCode fork sharing the same plugin/extension
|
||||
// event bus (host hook bus, UPGRADE 1): reuses OPENCODE_EXTENSION_EVENTS
|
||||
// verbatim (not a re-derivation), so the two dialects stay pinned together
|
||||
// by construction. See .kilo/plugins/gsd-core.js (copied verbatim from
|
||||
// .opencode/plugins/gsd-core.js).
|
||||
kilo: OPENCODE_EXTENSION_EVENTS,
|
||||
// #2091 — Hermes Agent real plugin hook vocabulary (13 events).
|
||||
// Cite: https://github.com/nousresearch/hermes-agent/blob/main/website/docs/user-guide/features/hooks.md
|
||||
// Replaces the borrowed `hookEvents: "claude"` 6-event surface that silently
|
||||
|
||||
@@ -122,6 +122,18 @@ function convertClaudeCommandToKiloSkill(content: string, skillName: string): st
|
||||
return (runtimeArtifactConversion as any).convertClaudeCommandToKiloSkill(content, skillName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converter-name registry for the OpenCode-family combined skills installer
|
||||
* (ADR-1239 / #2093). Maps the `converter` string declared on each runtime's
|
||||
* artifactLayout skills-kind descriptor (capabilities/<runtime>/capability.json)
|
||||
* to the actual conversion function, so `installOpencodeFamilySkills` dispatches
|
||||
* off the descriptor instead of a `frontmatterDialect === 'kilo'` runtime check.
|
||||
*/
|
||||
const SKILLS_CONVERTER_REGISTRY: Record<string, (content: string, skillName: string) => string> = {
|
||||
convertClaudeCommandToOpencodeSkill,
|
||||
convertClaudeCommandToKiloSkill,
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// User-artifact preservation helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -734,9 +746,18 @@ function installOpencodeFamilySkills(
|
||||
const rawDir = rawCommandsDir;
|
||||
if (!rawDir || !fs.existsSync(rawDir)) return 0;
|
||||
|
||||
const converter = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
|
||||
? convertClaudeCommandToKiloSkill
|
||||
: convertClaudeCommandToOpencodeSkill;
|
||||
// #2093: descriptor-driven — dispatch off the skills-kind entry's `converter`
|
||||
// string (capabilities/<runtime>/capability.json artifactLayout) via the
|
||||
// SKILLS_CONVERTER_REGISTRY, instead of a `frontmatterDialect === 'kilo'`
|
||||
// runtime check. Fail loud if the descriptor names an unregistered converter
|
||||
// (mirrors the converter=null throw in runtime-artifact-layout.cts).
|
||||
const converterName: string | undefined = skillsKindEntry.converter;
|
||||
const converter = converterName ? SKILLS_CONVERTER_REGISTRY[converterName] : undefined;
|
||||
if (!converter) {
|
||||
throw new TypeError(
|
||||
`installOpencodeFamilySkills: unknown skills converter '${String(converterName)}' for runtime '${runtime}'`,
|
||||
);
|
||||
}
|
||||
|
||||
const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath);
|
||||
// Symlink-escape guard: reject if any path component between targetDir and
|
||||
@@ -836,6 +857,16 @@ function installOpencodeFamilyCommands(
|
||||
let content = fs.readFileSync(srcPath, 'utf8');
|
||||
content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
|
||||
content = processAttribution(content, resolveAttribution(runtime));
|
||||
// #2093: this commands-kind entry's descriptor `converter` field is
|
||||
// intentionally `null` (see capabilities/{kilo,opencode}/capability.json —
|
||||
// the flattened-command writer above applies its own path/attribution
|
||||
// rewrites and has no per-file converter slot to key on), so there is no
|
||||
// descriptor string to dispatch through here. `frontmatterDialect` is the
|
||||
// documented, intentional dispatch key for frontmatter-shape selection —
|
||||
// it is itself descriptor-driven (not a `runtime === 'kilo'` check), so it
|
||||
// already satisfies the fold-to-descriptor requirement. Only the SKILLS
|
||||
// converter site above (installOpencodeFamilySkills) has a real
|
||||
// `converter` string to key on via SKILLS_CONVERTER_REGISTRY.
|
||||
content = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
|
||||
? (runtimeArtifactConversion as any).convertClaudeToKiloFrontmatter(content)
|
||||
: (runtimeArtifactConversion as any).convertClaudeToOpencodeFrontmatter(content);
|
||||
@@ -849,9 +880,10 @@ function installOpencodeFamilyCommands(
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Combined-family install orchestrator for OpenCode/Kilo (ADR-1239 / #2087).
|
||||
* Stages the flattened commands surface + skills surface + (OpenCode only)
|
||||
* native plugin adapter, mirroring the bespoke `else if (isOpencode ||
|
||||
* Combined-family install orchestrator for OpenCode/Kilo (ADR-1239 / #2087,
|
||||
* #2093). Stages the flattened commands surface + skills surface + (any
|
||||
* runtime whose hostBehaviors declares `nativePlugin` — OpenCode and, since
|
||||
* #2093, Kilo) native plugin adapter, mirroring the bespoke `else if (isOpencode ||
|
||||
* isKilo)` block previously inlined in bin/install.js.
|
||||
*
|
||||
* @param runtime - 'opencode' or 'kilo'
|
||||
|
||||
@@ -1676,7 +1676,12 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
|
||||
}
|
||||
|
||||
// Kilo CLI — same conversion logic as OpenCode, different config paths.
|
||||
function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
|
||||
// DEFECT.GENERATIVE-FIX: this body is mirrored in bin/install.js's
|
||||
// convertClaudeToKiloFrontmatter (used by bin/install.js's own legacy install
|
||||
// path). Neither copy re-exports the other — mirror any behavior change into
|
||||
// both. Guarded by the output-parity test in tests/runtime-converters.test.cjs
|
||||
// (#2093).
|
||||
function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
|
||||
// Replace tool name references in content (applies to all files)
|
||||
let convertedContent = content;
|
||||
convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
|
||||
@@ -1835,6 +1840,14 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
|
||||
// For agents: add required Kilo agent fields
|
||||
if (isAgent) {
|
||||
newLines.push('mode: subagent');
|
||||
// Embed model override from ~/.gsd/defaults.json so model_overrides is
|
||||
// respected on Kilo (which uses static agent frontmatter, not inline
|
||||
// Task() model parameters) — mirrors convertClaudeToOpencodeFrontmatter's
|
||||
// model emission exactly (#2093 UPGRADE 2 / ADR-1239; Kilo is an OpenCode
|
||||
// fork with the same static-frontmatter model constraint). See #2256.
|
||||
if (modelOverride) {
|
||||
newLines.push(['model:', modelOverride].join(' '));
|
||||
}
|
||||
newLines.push(...buildKiloAgentPermissionBlock(agentTools));
|
||||
}
|
||||
|
||||
|
||||
@@ -77,6 +77,12 @@ interface ArtifactKind {
|
||||
* specifies one (e.g. codex skills → $HOME/.agents). Undefined means the
|
||||
* kind installs under the runtime's normal configDir. */
|
||||
home?: string;
|
||||
/** Name of the converter function in Runtime Artifact Conversion exports, as
|
||||
* declared on the descriptor's `converter` field. Only populated for the
|
||||
* `skills` kind today — lets bespoke callers (e.g. the OpenCode-family
|
||||
* combined installer, ADR-1239 / #2093) look up the descriptor-declared
|
||||
* converter by name instead of re-deriving it from a runtime === check. */
|
||||
converter?: string;
|
||||
}
|
||||
|
||||
interface Layout {
|
||||
@@ -323,6 +329,7 @@ function skillsKind(
|
||||
kind: 'skills',
|
||||
destSubpath,
|
||||
prefix,
|
||||
converter: converterName,
|
||||
stage: (resolved) => {
|
||||
const realConverter = conversionExports[converterName] as (content: string, skillName: string, runtime: string, cmdNames: string[], isGlobal: boolean) => string;
|
||||
// Compute cmdNames once per stage call for performance (#3583).
|
||||
|
||||
Reference in New Issue
Block a user