feat(#2102): make pi a first-class installable runtime + fix its dispatch (ADR-1239)

Net-new EoS/pi installable runtime — purely additive (no prior runtime==='pi' branches). pi is a bun-runtime programmatic-CLI whose /gsd command is registered by a native ExtensionAPI extension and dispatches through the embedded engine. Stage 1 (install plumbing): - capabilities/pi/capability.json: full hostIntegration descriptor (imperative / slash-programmatic / active-model / native-extension / bun) + hostBehaviors {nativePlugin, pluginOnlyInstall}. - --pi flag + interactive-menu renumber (All 17->18); pi added to RUNTIME_FLAG_IDS, RUNTIME_LABELS, RUNTIME_META, allRuntimes/runtimeMap, model-catalog defaults. - Install mirrors OpenCode: pi installs the gsd.cjs extension + the shared engine payload (gsd-core + scripts + config markers) + the shared hooks bundle (spawned by the extension at lifecycle events, like OpenCode's plugin). pluginOnlyInstall EXCLUDES declarative command/agent/skill markdown, which pi has no host-read surface for (its /gsd is programmatic). _installNativePluginIfDeclared (extracted from the opencode-family path) copies pi/gsd.cjs -> ~/.pi/agent/extensions/gsd.cjs (global) / .pi/extensions/ (local). pi added to package.json files. - Golden: new pi.json (320 files: extension + engine + 27-file hooks bundle, no markdown); the 16 other fixtures + claude-local change only by the shared model-catalog hash line. Stage 2 (real dispatch + upgrades): - Shared dispatchGsdCommand() (shell-command-projection): bounded, no-throw subprocess-shim to gsd-tools.cjs (the only full-surface dispatch path; no in-process full-hub factory exists). Fixes pi/gsd.cjs's createHub()-no-args bug (every dispatch was UnknownCommand) AND the identical bug in mcp-server.cts's gsd_invoke_command, which a vacuous unknown-family-only test had masked (now has a real dispatch regression test). - pi/gsd.cjs: /gsd handler now (args, ctx) - tokenizes (quote-aware, via the shipped hooks/lib/git-cmd.js) + dispatches real family/subcommand (not hardcoded query/help); gsd_invoke gets a TypeBox (JSON-schema-fallback) parameters schema + consumes params; getArgumentCompletions; before_provider_request active-model steering (fail-open on null resolution); functional session_start / before_agent_start / session_before_compact hook bridges (spawn the shipped GSD hook scripts). - EXTENSION_EVENT_SURFACES.pi expanded from ['tool_call'] to the full 30-event vocabulary. Docs (host-integration matrix + how-to) + changeset (Added). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-11 19:34:23 -04:00
parent 246f566ee1
commit 79d7657eff
49 changed files with 1771 additions and 198 deletions
--- a/src/host-integration.cts
+++ b/src/host-integration.cts
@@ -584,7 +584,21 @@ const EXTENSION_EVENT_SURFACES: Readonly<Record<string, readonly string[]>> = Ob
    'pre_gateway_dispatch', 'pre_approval_request',
    'transform_tool_result',
  ]),
-  pi: Object.freeze(['tool_call']),
+  // #2102 Stage 2 — pi's real ExtensionAPI event vocabulary (~30 fine-grained
+  // extension events; documentation-sourced, ADR-1239 §research). Replaces the
+  // placeholder single-event ['tool_call'] surface — the Stage 1 value only
+  // covered the one event pi/gsd.cjs happened to bind at the time, not the
+  // full declared surface.
+  pi: Object.freeze([
+    'session_start', 'project_trust', 'resources_discover', 'input',
+    'before_agent_start', 'agent_start', 'message_start', 'message_update',
+    'message_end', 'turn_start', 'context', 'before_provider_request',
+    'after_provider_response', 'tool_execution_start', 'tool_execution_update',
+    'tool_execution_end', 'tool_call', 'tool_result', 'turn_end', 'agent_end',
+    'session_before_switch', 'session_shutdown', 'session_before_fork',
+    'session_info_changed', 'session_before_compact', 'session_compact',
+    'session_before_tree', 'session_tree', 'thinking_level_select', 'model_select',
+  ]),
  none: Object.freeze([]),
 });

--- a/src/install-engine.cts
+++ b/src/install-engine.cts
@@ -715,6 +715,19 @@ function installRuntimeArtifacts(
    const nestedGsdDirForCleanup = path.join(configDir, 'skills', 'gsd');
    _removeHermesBareStemDirs(nestedGsdDirForCleanup);
  }
+
+  // Generic-branch nativePlugin staging (ADR-1239 / #2102 Stage 1): runtimes
+  // outside the OpenCode/Kilo combined-family install (e.g. pi, whose
+  // artifactLayout is empty and which never sets combinedFamilyInstall) still
+  // need their declared hostBehaviors.nativePlugin file copied into configDir.
+  // findInstallSourceRoot resolves the repo/package root independent of
+  // configDir contents (marker check, then a walk-up from __dirname), so this
+  // is safe even when configDir has no .gsd-source marker (artifactLayout: []).
+  if (behaviors.nativePlugin) {
+    const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
+    const src = path.dirname(path.dirname(commandsGsdDir));
+    _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
+  }
 }

 // ---------------------------------------------------------------------------
@@ -879,6 +892,44 @@ function installOpencodeFamilyCommands(
  }
 }

+// ---------------------------------------------------------------------------
+// _installNativePluginIfDeclared
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy a runtime's declared native-extension/plugin file (hostBehaviors.nativePlugin)
+ * into its resolved config dir, when the runtime descriptor declares one.
+ *
+ * Extracted (ADR-1239 / #2102 Stage 1) from the body previously inlined in
+ * installOpencodeFamilyArtifacts so a runtime that is NOT part of the
+ * OpenCode/Kilo combined-family install (e.g. pi, whose artifactLayout is
+ * empty and which never sets combinedFamilyInstall) can still get its
+ * nativePlugin file staged via the generic installRuntimeArtifacts branch.
+ * Behavior for opencode/kilo is unchanged — same source resolution, same
+ * mkdir + copyFileSync call, same silent no-op when the source is missing.
+ *
+ * @param runtime  - canonical runtime id (only used for the assertDestWithinConfigHome guard)
+ * @param configDir - resolved runtime config directory
+ * @param behaviors - the runtime's hostBehaviors descriptor
+ * @param src       - repo/package root (two levels up from the commands/gsd source dir)
+ */
+function _installNativePluginIfDeclared(
+  runtime: string,
+  configDir: string,
+  behaviors: any,
+  src: string,
+): void {
+  const np = behaviors.nativePlugin;
+  if (np && np.source) {
+    const pluginSrc = path.join(src, np.source);
+    if (fs.existsSync(pluginSrc)) {
+      const destDir = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, np.dir);
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(pluginSrc, path.join(destDir, np.file));
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // installOpencodeFamilyArtifacts
 // ---------------------------------------------------------------------------
@@ -927,15 +978,7 @@ function installOpencodeFamilyArtifacts(
  installOpencodeFamilyCommands(runtime, commandDir, rawCommandsDir, pathPrefix, resolveAttribution);
  installOpencodeFamilySkills(runtime, configDir, rawCommandsDir, pathPrefix, resolveAttribution);

-  const np = behaviors.nativePlugin;
-  if (np && np.source) {
-    const pluginSrc = path.join(src, np.source);
-    if (fs.existsSync(pluginSrc)) {
-      const destDir = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, np.dir);
-      fs.mkdirSync(destDir, { recursive: true });
-      fs.copyFileSync(pluginSrc, path.join(destDir, np.file));
-    }
-  }
+  _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
 }

 // ---------------------------------------------------------------------------
@@ -1004,6 +1047,7 @@ export = {
  installOpencodeFamilySkills,
  installOpencodeFamilyCommands,
  installOpencodeFamilyArtifacts,
+  _installNativePluginIfDeclared,
  _hostBehaviors,
  _copyStaged,
  hasExistingSymlinkBetween,
--- a/src/mcp-server.cts
+++ b/src/mcp-server.cts
@@ -5,8 +5,16 @@
 * so any MCP-consuming host (Claude/Codex/OpenCode/VS Code/Gemini/Cursor/Cline/
 * Hermes) can drive GSD with NO bespoke plugin:
 *
- *   - point 1 (command): tool `gsd_invoke_command` → the command-routing hub
- *     (`createHub`/`dispatch`, src/command-routing-hub.cts).
+ *   - point 1 (command): tool `gsd_invoke_command` → `dispatchGsdCommand`
+ *     (src/shell-command-projection.cts), a bounded subprocess-shim to
+ *     gsd-tools.cjs. #2102 Stage 2: `commandRoutingHub.createHub()` called
+ *     with no args here always hit `if(!_cjsRegistry) return
+ *     makeUnknownCommand()` — every dispatch was UnknownCommand. No
+ *     fully-populated hub factory exists anywhere in gsd-core (every
+ *     createHub() caller builds a single-family hub for its own narrow
+ *     purpose), so the fix routes through the SAME shared dispatch helper
+ *     the pi extension uses (pi/gsd.cjs), mirroring the SUBPROCESS-REUSE
+ *     precedent already established for the OpenCode/Kilo hook bridge.
 *   - point 5 (state IO): tools `gsd_read_state` / `gsd_write_state` → the
 *     Phase 3 `stateIO` seam (src/state-io.cts, filesystem default).
 *
@@ -20,10 +28,11 @@
 */
 'use strict';

-// eslint-disable-next-line @typescript-eslint/no-require-imports
-import commandRoutingHub = require('./command-routing-hub.cjs');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import stateIo = require('./state-io.cjs');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import shellCommandProjection = require('./shell-command-projection.cjs');
+const { dispatchGsdCommand } = shellCommandProjection;

 export const PROTOCOL_VERSION = '2024-11-05';
 export const SERVER_NAME = 'gsd-core';
@@ -108,9 +117,11 @@ function callTool(name: string, args: unknown, ctx: McpContext): { content: Arra
      if (!family || !subcommand) {
        return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "family" and "subcommand".' }] };
      }
-      const hub = commandRoutingHub.createHub();
-      const res = hub.dispatch({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd, raw: undefined });
-      return { content: [{ type: 'text', text: JSON.stringify(res) }] };
+      const res = dispatchGsdCommand({ family, subcommand, args: Array.isArray(a.args) ? (a.args as string[]) : [], cwd });
+      if (!res.ok) {
+        return { isError: true, content: [{ type: 'text', text: res.stderr || res.stdout || `dispatch failed (exit ${res.code})` }] };
+      }
+      return { content: [{ type: 'text', text: res.stdout }] };
    }
    if (name === 'gsd_read_state') {
      const p = asString(a.path);
--- a/src/runtime-name-policy.cts
+++ b/src/runtime-name-policy.cts
@@ -210,6 +210,7 @@ const RUNTIME_LABELS: Readonly<Record<string, string>> = {
  codebuddy: 'CodeBuddy',
  cline: 'Cline',
  zcode: 'ZCode',
+  pi: 'pi',
 };

 /**
@@ -258,6 +259,12 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS: Readonly<Record<string, string>> = {
  cline:     "'.cline'",
  kimi:      "'.config', 'agents'",
  zcode:     "'.zcode'",
+  // pi's global config home is ~/.pi/agent (configHome: dot-home-nested,
+  // parent '.pi', name 'agent' — capabilities/pi/capability.json), matching
+  // resolveConfigHomeFromDescriptor's `path.join(home, parent, name)` for the
+  // no-probe dot-home-nested case (src/runtime-homes.cts). Two-segment
+  // path.join args, same shape as opencode/kilo/kimi above.
+  pi:        "'.pi', 'agent'",
 };

 /**
@@ -286,7 +293,7 @@ export function getGlobalConfigHomeFragment(runtime: string): string {
 // folds the shared-hooks-install skip).
 const RUNTIME_FLAG_IDS = Object.freeze([
  'opencode', 'kilo', 'codex', 'copilot', 'antigravity', 'cursor',
-  'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi', 'zcode',
+  'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi', 'zcode', 'pi',
 ] as const);

 /**
--- a/src/shell-command-projection.cts
+++ b/src/shell-command-projection.cts
@@ -518,6 +518,143 @@ export function execTool(program: string, args: string[], opts: { cwd?: string;
  return _spawnResult(result, program);
 }

+/**
+ * Result shape for {@link dispatchGsdCommand}. Modeled on the existing
+ * `{exitCode,stdout,stderr,signal,error}` seam above, but flattened to the
+ * fields callers actually need (never leaks a raw Error/signal — see
+ * `timedOut`), per the "Unbounded Subprocesses" contract (CLAUDE.md):
+ * degrade to a structured result on timeout/ENOENT, never throw.
+ */
+export interface DispatchGsdCommandResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  timedOut: boolean;
+}
+
+/**
+ * Resolve the absolute path to gsd-tools.cjs relative to THIS module.
+ *
+ * This file compiles to gsd-core/bin/lib/shell-command-projection.cjs — a
+ * sibling of gsd-core/bin/gsd-tools.cjs — so the relative walk-up is stable
+ * regardless of install location (global/local/dev-repo layouts all ship
+ * gsd-core/bin/ as a unit).
+ */
+export function resolveGsdToolsPath(): string {
+  return path.resolve(__dirname, '..', 'gsd-tools.cjs');
+}
+
+/**
+ * Subprocess-shim dispatch to gsd-tools.cjs (ADR-1239 #2102 Stage 2).
+ *
+ * No fully-populated in-process command-routing hub exists anywhere in the
+ * tree — every `createHub()` caller (cjs-command-router-adapter.cts,
+ * phase-command-router.cts, command-routing-hub.cts's own tests) builds a
+ * single-family hub for its own narrow purpose. The ONLY dispatch path that
+ * covers the FULL family/subcommand surface is the gsd-tools.cjs CLI itself.
+ * This mirrors the SUBPROCESS-REUSE precedent already established for the
+ * OpenCode/Kilo hook bridge (see .opencode/plugins/gsd-core.js header:
+ * "Architecture: SUBPROCESS REUSE ... spawns existing hook scripts as child
+ * processes") — the same pattern, applied to command dispatch instead of
+ * hook dispatch.
+ *
+ * Output-flag choice (verified by direct invocation — see #2102 dispatch
+ * notes for the sample invocations): always pass `--raw` (undecorated,
+ * programmatically-consumable stdout on success) and `--json-errors` (a
+ * structured `{ok:false,reason,message}` JSON object on stderr, with a
+ * non-zero exit, instead of a free-text "Error: ..." line). Both are global
+ * flags accepted by every gsd-tools.cjs family/subcommand, so passing them
+ * unconditionally is safe for the full command surface.
+ *
+ * `family` maps 1:1 onto gsd-tools.cjs's first positional argv token;
+ * `subcommand` (when present) onto the second — e.g.
+ * `{family:'phase', subcommand:'add'}` → `gsd-tools.cjs phase add`. An empty
+ * `subcommand` is omitted entirely (some families, e.g. `config-path`, take
+ * no subcommand).
+ *
+ * NEVER throws. Degrades to `{ ok:false, ... }` on:
+ *   - a missing/invalid "family" (validated locally, no subprocess spawned)
+ *   - ENOENT / a missing gsd-tools.cjs (via the injectable `gsdToolsPath`)
+ *   - a wall-clock timeout (`timedOut:true`, mirroring the
+ *     `signal === 'SIGTERM' && error.code === 'ETIMEDOUT'` idiom already used
+ *     by worktree-safety.cts)
+ *   - any other unanticipated throw from the underlying spawn (defensive
+ *     try/catch — execTool itself is spawnSync-based and does not throw).
+ */
+export function dispatchGsdCommand({
+  family,
+  subcommand,
+  args = [],
+  cwd,
+  timeout = 30_000,
+  gsdToolsPath,
+}: {
+  family?: string;
+  subcommand?: string;
+  args?: string[];
+  cwd?: string;
+  timeout?: number;
+  gsdToolsPath?: string;
+} = {}): DispatchGsdCommandResult {
+  if (typeof family !== 'string' || family.length === 0) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr: 'dispatchGsdCommand requires a non-empty string "family".',
+      code: null,
+      timedOut: false,
+    };
+  }
+
+  const resolvedCwd = cwd || process.cwd();
+  const toolsPath = gsdToolsPath || resolveGsdToolsPath();
+  const argv = [
+    toolsPath,
+    family,
+    ...(subcommand ? [subcommand] : []),
+    ...(Array.isArray(args) ? args : []),
+    '--cwd', resolvedCwd,
+    '--raw',
+    '--json-errors',
+  ];
+
+  let result: SpawnResultOutput;
+  try {
+    result = execTool(process.execPath, argv, { cwd: resolvedCwd, timeout });
+  } catch (e) {
+    // Defensive belt-and-suspenders: execTool is spawnSync-based and does not
+    // throw today, but a degraded result here keeps this seam's no-throw
+    // contract true even under an unanticipated future failure mode.
+    return {
+      ok: false,
+      stdout: '',
+      stderr: e instanceof Error ? e.message : String(e),
+      code: null,
+      timedOut: false,
+    };
+  }
+
+  // Mirrors the established `result.error && (result.error as
+  // NodeJS.ErrnoException).code === ...` idiom (graphify.cts, worktree-safety.cts):
+  // narrow away null via `!== null` FIRST, then cast — asserting `Error | null`
+  // to `NodeJS.ErrnoException | null` directly (paired with optional chaining)
+  // trips a typescript-eslint no-unnecessary-type-assertion false positive for
+  // this exact narrowing shape (all of ErrnoException's extra fields over Error
+  // are optional).
+  const timedOut = result.signal === 'SIGTERM'
+    && result.error !== null
+    && (result.error as NodeJS.ErrnoException).code === 'ETIMEDOUT';
+
+  return {
+    ok: result.exitCode === 0 && !timedOut,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    code: result.exitCode,
+    timedOut,
+  };
+}
+
 export function probeTty(opts: { platform?: string } = {}): string | null {
  const platform = opts.platform ?? process.platform;
  if (platform === 'win32') return null;