@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.6

package/gsd-core/bin/lib/host-integration-adapters/cline-sdk-binding.cjs

@@ -0,0 +1,234 @@
+/**
+ * Cline SDK binding — AgentPlugin + createAgentModel adapters
+ * (ADR-1239 Phase D / #2090).
+ *
+ * Two Context7-verified UPGRADES the file-convention projection ignored, now
+ * delivered through the negotiated `hookBus: host` + `modelMode: active`
+ * interface points:
+ *
+ *   UPGRADE 1 — `AgentPlugin.hooks.beforeTool` planning-artifact guard.
+ *     Re-implements the `.clinerules/hooks/PreToolUse` file-convention hook
+ *     (issue #787) as a real Cline SDK AgentPlugin. Guard semantics are
+ *     preserved EXACTLY: fail-open, cancel (skip) write-class calls targeting
+ *     `.planning/`, pass through everything else. The SDK maps the file hook's
+ *     `{cancel:true, errorMessage}` to `{skip:true, reason}` (beforeTool
+ *     contract).
+ *     Cite: https://github.com/cline/cline/blob/main/docs/sdk/plugins.mdx
+ *           https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md
+ *
+ *   UPGRADE 2 — `DefaultGateway.createAgentModel({providerId, modelId})`.
+ *     Resolves GSD's per-subagent `model_overrides` / `model_profile_overrides`
+ *     (already used for OpenCode/Codex passive hosts) into the createAgentModel
+ *     call params for cline's active model mode. The host gateway owns the
+ *     actual model instantiation; this binding resolves WHICH model an
+ *     overridden subagent should use.
+ *     Cite: https://github.com/cline/cline/blob/main/docs/sdk/reference/gateway.mdx
+ *           https://github.com/cline/cline/blob/main/sdk/packages/llms/README.md
+ *
+ * This module is PURE (no I/O, no SDK import): the real `@cline/sdk` is a
+ * fast-moving package set not linked at build/test time, so the binding exposes
+ * the decision functions a host plugin/gateway would call. Tests drive payloads
+ * through them directly (same mock-the-SDK pattern as the VS Code reference
+ * binding, tests/fixtures/vscode-host-binding.cjs).
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLINE_PROVIDER_ID = exports.clineGsdPlugin = exports.PLANNING_GUARD_REASON = exports.PLANNING_PATH_PATTERN = exports.WRITE_TOOL_PATTERN = void 0;
+exports.evaluateBeforeTool = evaluateBeforeTool;
+exports.inferProviderId = inferProviderId;
+exports.resolveClineAgentModelParams = resolveClineAgentModelParams;
+// ---------------------------------------------------------------------------
+// UPGRADE 1 — beforeTool planning-artifact guard
+// ---------------------------------------------------------------------------
+/**
+ * Write-class tool-verb detector. Matches the SAME regex as the #787
+ * PreToolUse file-convention hook so the guard behaves identically.
+ * Case-insensitive (the SDK delivers tool names in varying case).
+ */
+exports.WRITE_TOOL_PATTERN = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
+/**
+ * `.planning/` path detector. Matches `.planning` preceded by start-of-string
+ * or a path separator (posix `/` or windows `\`) and followed by a separator or
+ * end-of-string — so `.planning-readme.txt` is NOT falsely matched. Mirrors the
+ * PreToolUse hook's `(^|[\\/])\.planning([\\/]|$)` exactly.
+ */
+exports.PLANNING_PATH_PATTERN = /(^|[\\/])\.planning([\\/]|$)/;
+/**
+ * The user-visible reason returned when a `.planning/` write is blocked.
+ * Preserves the PreToolUse hook's errorMessage text so the guard behaves
+ * identically to the user (cancel→skip, errorMessage→reason).
+ */
+exports.PLANNING_GUARD_REASON = Object.freeze('GSD: .planning/ artifacts are managed by GSD workflows. Edit them only through a /gsd-* command, not directly.');
+/**
+ * Path-bearing field-name detector. Only PATH-keyed field values are inspected,
+ * so a document that merely mentions ".planning/" in its body content is never
+ * falsely blocked. Mirrors the PreToolUse hook's PATH_KEY regex exactly.
+ */
+const PATH_KEY_PATTERN = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
+/**
+ * Collect PATH-bearing string field values from an object tree, mirroring the
+ * PreToolUse hook's bounded walk. Pure; never throws.
+ */
+function collectPathValues(root) {
+    const paths = [];
+    const walk = (v, depth) => {
+        if (depth > 5 || paths.length > 64)
+            return;
+        if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x, depth + 1);
+            return;
+        }
+        if (v && typeof v === 'object') {
+            const obj = v;
+            for (const k of Object.keys(obj)) {
+                const val = obj[k];
+                if (typeof val === 'string' && PATH_KEY_PATTERN.test(k)) {
+                    paths.push(val);
+                }
+                else {
+                    walk(val, depth + 1);
+                }
+            }
+        }
+    };
+    walk(root, 0);
+    return paths;
+}
+/**
+ * Resolve a tool name from a beforeTool payload's `tool` field, which may be a
+ * string or an object with a `name` property. Returns '' when absent (treated
+ * as non-write-class → allow, fail-open).
+ */
+function resolveToolName(tool) {
+    if (!tool)
+        return '';
+    if (typeof tool === 'string')
+        return tool;
+    const name = tool.name;
+    return typeof name === 'string' ? name : '';
+}
+/**
+ * The pure guard decision: given a beforeTool payload, decide skip (cancel) or
+ * allow. Fail-OPEN — any malformed input, missing tool, or thrown error returns
+ * 'allow' (the guard never blocks on a defect, mirroring the PreToolUse hook).
+ *
+ * @returns `{decision:'skip', reason}` for a write-class call targeting
+ *          `.planning/`; `{decision:'allow'}` for everything else.
+ */
+function evaluateBeforeTool(payload) {
+    try {
+        if (!payload)
+            return { decision: 'allow' };
+        const toolName = resolveToolName(payload.tool);
+        if (!toolName)
+            return { decision: 'allow' };
+        const isWrite = exports.WRITE_TOOL_PATTERN.test(toolName);
+        if (!isWrite)
+            return { decision: 'allow' };
+        const paths = collectPathValues(payload.input);
+        const isPlanningPath = (s) => exports.PLANNING_PATH_PATTERN.test(s);
+        if (paths.some(isPlanningPath)) {
+            return { decision: 'skip', reason: exports.PLANNING_GUARD_REASON };
+        }
+        return { decision: 'allow' };
+    }
+    catch {
+        // Fail-open: a defect in the guard never blocks the user's operation.
+        return { decision: 'allow' };
+    }
+}
+/**
+ * The Cline `AgentPlugin` shape (Context7 /cline/cline). A plugin implements
+ * `setup({agentId})` returning `{hooks, tools}`. The `beforeTool` hook returns
+ * `{skip:true, reason}` to block or `undefined` to allow.
+ *
+ * This object is the portable plugin a host loads from `~/.cline/plugins/`
+ * (analogous to `.opencode/plugins/gsd-core.js`). Its `beforeTool` delegates to
+ * the pure `evaluateBeforeTool` so the decision logic is testable without the
+ * SDK linked.
+ */
+exports.clineGsdPlugin = Object.freeze({
+    name: 'gsd-planning-guard',
+    setup(_ctx) {
+        return {
+            hooks: {
+                beforeTool(payload) {
+                    const decision = evaluateBeforeTool(payload);
+                    return decision.decision === 'skip' ? { skip: true, reason: decision.reason } : undefined;
+                },
+            },
+        };
+    },
+});
+// ---------------------------------------------------------------------------
+// UPGRADE 2 — createAgentModel model-override resolution
+// ---------------------------------------------------------------------------
+/**
+ * The fallback provider id when a model id does not match a known provider
+ * family. Anthropic is cline's most common default; the host gateway retains
+ * the final say over provider resolution.
+ */
+exports.DEFAULT_CLINE_PROVIDER_ID = 'anthropic';
+/**
+ * Infer a `providerId` (the createAgentModel first arg) from a model id by
+ * matching known provider families. Returns DEFAULT_CLINE_PROVIDER_ID for an
+ * unrecognized or empty id (fail-safe — the gateway applies its own default).
+ *
+ * Pure string-prefix classification; does not validate the id is a real model.
+ */
+function inferProviderId(modelId) {
+    if (typeof modelId !== 'string' || modelId.length === 0)
+        return exports.DEFAULT_CLINE_PROVIDER_ID;
+    const lower = modelId.toLowerCase();
+    if (lower.startsWith('claude'))
+        return 'anthropic';
+    if (lower.startsWith('gpt') || lower.startsWith('o1') || lower.startsWith('o3') || lower.startsWith('o4'))
+        return 'openai';
+    if (lower.startsWith('gemini'))
+        return 'google';
+    if (lower.startsWith('deepseek'))
+        return 'deepseek';
+    return exports.DEFAULT_CLINE_PROVIDER_ID;
+}
+/**
+ * Resolve the createAgentModel call params for a cline subagent from GSD's model
+ * override config. Mirrors the precedence OpenCode/Codex use (passive hosts
+ * embed the resolved model into agent frontmatter); for cline's active model
+ * mode the same resolution flows to `gateway.createAgentModel(params)`.
+ *
+ * Precedence (matches GSD's model_overrides > model_profile_overrides contract):
+ *   1. `modelOverrides[agentType]` — direct per-agent override
+ *   2. `modelProfileOverrides[profile][agentType]` — profile-scoped override
+ *   3. null — no override; the host gateway applies its own default
+ *
+ * Pure; never throws. Non-string / empty override values are ignored (fail-safe).
+ *
+ * @returns the `{providerId, modelId}` for createAgentModel, or null when no
+ *          override is configured (the gateway default applies — GSD does NOT
+ *          call createAgentModel in that case).
+ */
+function resolveClineAgentModelParams(args) {
+    const { agentType, modelOverrides, modelProfileOverrides, profile } = args;
+    if (!agentType || typeof agentType !== 'string')
+        return null;
+    // 1. Direct per-agent override wins.
+    if (modelOverrides && typeof modelOverrides === 'object') {
+        const direct = modelOverrides[agentType];
+        if (typeof direct === 'string' && direct.length > 0) {
+            return { providerId: inferProviderId(direct), modelId: direct };
+        }
+    }
+    // 2. Profile-scoped override.
+    if (modelProfileOverrides && typeof modelProfileOverrides === 'object' && profile) {
+        const profileEntry = modelProfileOverrides[profile];
+        if (profileEntry && typeof profileEntry === 'object') {
+            const profileModel = profileEntry[agentType];
+            if (typeof profileModel === 'string' && profileModel.length > 0) {
+                return { providerId: inferProviderId(profileModel), modelId: profileModel };
+            }
+        }
+    }
+    // 3. No override — gateway default applies.
+    return null;
+}

package/gsd-core/bin/lib/host-integration-adapters/imperative-hook-bus.cjs

@@ -0,0 +1,145 @@
+/**
+ * Imperative hook-bus adapter — descriptor-driven hooks.json binding
+ * (ADR-1239 Phase D / #2089).
+ *
+ * Generalizes the Cursor-specific `writeCursorHooksJson`/`removeCursorHooksJson`
+ * into a descriptor-driven hook-bus binding that reads the negotiated `hookBus`
+ * axis + the host's documented hook-event list (from
+ * `runtime.hostBehaviors.managedHookEvents`), NOT a hardcoded
+ * `sessionStart`/`postToolUse` pair.
+ *
+ * This module is PURE (no I/O): it resolves the event→script mapping and builds
+ * the hooks.json entry manifest. The actual file I/O (copying scripts, writing
+ * hooks.json) stays in `runtime-hooks-surface.cts`, which calls into the pure
+ * functions exported here. This separation makes the binding testable without a
+ * filesystem.
+ *
+ * Cursor hook-event universe (closed vocabulary per ADR-1239,
+ * https://cursor.com/docs/hooks):
+ *   sessionStart, sessionEnd, preToolUse, postToolUse, subagentStart,
+ *   subagentStop, beforeShellExecution, afterShellExecution,
+ *   afterMCPExecution, afterFileEdit, preCompact, stop,
+ *   beforeTabFileRead, afterTabFileEdit, workspaceOpen
+ *
+ * GSD registers for the 6 events in the portable floor + subagent lifecycle
+ * (AC4a upgrade, #2089):
+ *   sessionStart, postToolUse, preToolUse, stop, subagentStart, subagentStop
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GSD_HOOK_MARKER = exports.CURSOR_EVENT_SCRIPT_MAP = exports.CURSOR_HOOK_EVENTS = void 0;
+exports.resolveManagedHookEvents = resolveManagedHookEvents;
+exports.resolveHookScripts = resolveHookScripts;
+exports.buildHookBusEntries = buildHookBusEntries;
+/**
+ * The full set of Cursor hook events GSD can register for.
+ * Frozen closed vocabulary — adding an event requires updating both this set
+ * and the event→script mapping below.
+ */
+exports.CURSOR_HOOK_EVENTS = Object.freeze([
+    'sessionStart',
+    'postToolUse',
+    'preToolUse',
+    'stop',
+    'subagentStart',
+    'subagentStop',
+]);
+/**
+ * Event → hook-script mapping. Each event maps to a standalone `.js` script
+ * under `hooks/` that Cursor invokes via `hooks.json`.
+ *
+ * Convention: `gsd-cursor-<kebab-event>.js`. The script files are authored in
+ * `hooks/` and copied to `<configDir>/hooks/` during install by
+ * `runtime-hooks-surface.cts`.
+ */
+exports.CURSOR_EVENT_SCRIPT_MAP = Object.freeze({
+    sessionStart: 'gsd-cursor-session-start.js',
+    postToolUse: 'gsd-cursor-post-tool.js',
+    preToolUse: 'gsd-cursor-pre-tool.js',
+    stop: 'gsd-cursor-stop.js',
+    subagentStart: 'gsd-cursor-subagent-start.js',
+    subagentStop: 'gsd-cursor-subagent-stop.js',
+});
+/**
+ * The GSD-managed marker written into each hooks.json entry so the
+ * reconcile pass can distinguish GSD-owned entries from user-owned ones.
+ */
+exports.GSD_HOOK_MARKER = 'gsd-managed';
+/**
+ * Resolve the managed hook events from a runtime descriptor's
+ * `hostBehaviors.managedHookEvents` list. Falls back to the full
+ * `CURSOR_HOOK_EVENTS` set when the descriptor does not declare the list
+ * (backward-compat for descriptors predating #2089).
+ *
+ * Pure: no I/O, never throws. Unknown event names are silently filtered
+ * (fail-closed — an unrecognized event is never registered). Falls back to
+ * the full CURSOR_HOOK_EVENTS set when the descriptor is absent or all entries
+ * are unrecognized (ensures the portable-event floor is always covered).
+ *
+ * @param managedHookEvents - the descriptor's `hostBehaviors.managedHookEvents` array
+ * @returns a deduplicated, validated array of event names
+ */
+function resolveManagedHookEvents(managedHookEvents) {
+    if (!Array.isArray(managedHookEvents) || managedHookEvents.length === 0) {
+        return exports.CURSOR_HOOK_EVENTS;
+    }
+    const valid = new Set(exports.CURSOR_HOOK_EVENTS);
+    const seen = new Set();
+    const result = [];
+    for (const ev of managedHookEvents) {
+        if (typeof ev === 'string' && valid.has(ev) && !seen.has(ev)) {
+            seen.add(ev);
+            result.push(ev);
+        }
+    }
+    return result.length > 0 ? result : exports.CURSOR_HOOK_EVENTS;
+}
+/**
+ * Build the list of hook script files that need to be copied for the given
+ * managed events. Each event maps to a script via `CURSOR_EVENT_SCRIPT_MAP`.
+ *
+ * Pure: returns a deduplicated array of script filenames.
+ *
+ * @param events - the managed event names (validated by `resolveManagedHookEvents`)
+ * @returns array of script filenames (e.g. `['gsd-cursor-session-start.js', ...]`)
+ */
+function resolveHookScripts(events) {
+    const scripts = [];
+    const seen = new Set();
+    for (const ev of events) {
+        const script = exports.CURSOR_EVENT_SCRIPT_MAP[ev];
+        if (script && !seen.has(script)) {
+            seen.add(script);
+            scripts.push(script);
+        }
+    }
+    return scripts;
+}
+/**
+ * Build the hooks.json managed-entry manifest for the given events.
+ * Each entry is `{ type: 'command', command: <cmd>, [GSD_HOOK_MARKER]: true }`.
+ *
+ * The `command` string is built by the caller (it requires platform-specific
+ * node-runner resolution from `runtime-hooks-surface.cts`). This function
+ * receives a pre-built `event → command` map and attaches the marker.
+ *
+ * Pure: no I/O.
+ *
+ * @param events - the managed event names
+ * @param commands - a map of event → command string (built by the caller)
+ * @returns a map of event → managed entry, ready for hooks.json reconciliation
+ */
+function buildHookBusEntries(events, commands) {
+    const entries = {};
+    for (const ev of events) {
+        const cmd = commands[ev];
+        if (cmd) {
+            entries[ev] = {
+                type: 'command',
+                command: cmd,
+                [exports.GSD_HOOK_MARKER]: true,
+            };
+        }
+    }
+    return entries;
+}

package/gsd-core/bin/lib/host-integration.cjs

@@ -430,12 +430,53 @@ function hookEventSurfaceFor(hookEvents) {
 // 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 = Object.freeze({
-    opencode: Object.freeze([
-        'session.created', 'session.idle', 'experimental.session.compacting',
-        'tool.execute.before', 'tool.execute.after', 'file.edited',
+    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
+    // never fired on Hermes.
+    hermes: Object.freeze([
+        'pre_tool_call', 'post_tool_call',
+        'pre_llm_call', 'post_llm_call',
+        'on_session_start', 'on_session_end',
+        'on_session_finalize', 'on_session_reset',
+        'subagent_start', 'subagent_stop',
+        'pre_gateway_dispatch', 'pre_approval_request',
+        'transform_tool_result',
+    ]),
+    // #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',
     ]),
-    pi: Object.freeze(['tool_call']),
     none: Object.freeze([]),
 });
 /**