@opengsd/gsd-core 1.6.0 → 1.7.0-rc.1

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

@@ -0,0 +1,408 @@
+'use strict';
+/**
+ * Host Integration module — ADR-1239 Phase A.
+ *
+ * Pure, additive, no-I/O module providing a closed vocabulary for host
+ * integration axes, degradation ladder, profile classification, and
+ * capability negotiation.
+ *
+ * The SINGLE source of truth for integration axes and degradation levels.
+ * All functions are pure (no side effects, no I/O).
+ *
+ * Per-CLI sourced axis VALUES (with citations) live in docs/reference/host-integration-capability-matrix.md — every value is documented or explicitly 'undocumented'.
+ */
+// ---------------------------------------------------------------------------
+// Protocol version
+// ---------------------------------------------------------------------------
+const PROTOCOL_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Undocumented sentinel — fail-closed when a host omits CLI docs for an axis
+// ---------------------------------------------------------------------------
+/**
+ * Sentinel value used when a host descriptor's CLI docs do not state a value
+ * for an axis. It VALIDATES (accepted by the validator) but NEVER propagates
+ * into effective axes — it fails closed exactly like an unknown/missing value.
+ *
+ * Do NOT add to HOST_INTEGRATION_AXES (which is the documented vocabulary).
+ */
+const UNDOCUMENTED = 'undocumented';
+// ---------------------------------------------------------------------------
+// Closed vocabulary — axes and interface points
+// ---------------------------------------------------------------------------
+const HOST_INTEGRATION_AXES = Object.freeze({
+    embeddingMode: Object.freeze(['imperative', 'declarative']),
+    commandSurface: Object.freeze(['slash-file', 'slash-programmatic', 'slash-toml', 'palette', 'prose-only']),
+    modelMode: Object.freeze(['active', 'passive']),
+    hookBus: Object.freeze(['host', 'engine', 'none']),
+    stateIO: Object.freeze(['filesystem', 'sandboxed-storage', 'session-log-append']),
+    transport: Object.freeze(['mcp', 'native-extension']),
+    runtime: Object.freeze(['node', 'bun', 'sandboxed-web', 'python', 'go', 'rust', 'electron', 'other']),
+    subagentToolkit: Object.freeze(['full', 'read-only']),
+});
+const INTERFACE_POINTS = Object.freeze(['command', 'dispatch', 'model', 'hooks', 'state', 'artifact']);
+// ---------------------------------------------------------------------------
+// Profile baselines
+// ---------------------------------------------------------------------------
+// Fail-closed floor: the most restrictive known value per axis, injected when a host omits an axis (degrade-closed, never assume capability).
+const SAFE_DEFAULTS = {
+    embeddingMode: 'declarative',
+    commandSurface: 'prose-only',
+    dispatch: { namedDispatch: false, nested: false, maxDepth: 0, background: false, subagentToolkit: 'read-only', backgroundDispatch: false },
+    modelMode: 'passive',
+    hookBus: 'none',
+    stateIO: 'session-log-append',
+    transport: 'mcp',
+    runtime: 'node',
+};
+const PROFILE_BASELINES = Object.freeze({
+    'programmatic-cli': Object.freeze({
+        embeddingMode: 'imperative',
+        commandSurface: 'slash-file',
+        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true }),
+        modelMode: 'passive',
+        hookBus: 'host',
+        stateIO: 'filesystem',
+        transport: 'mcp',
+        runtime: 'node',
+    }),
+    'declarative-cli': Object.freeze({
+        embeddingMode: 'declarative',
+        commandSurface: 'slash-file',
+        dispatch: Object.freeze({ namedDispatch: true, nested: false, maxDepth: 1, background: false, subagentToolkit: 'full', backgroundDispatch: false }),
+        modelMode: 'passive',
+        hookBus: 'host',
+        stateIO: 'filesystem',
+        transport: 'mcp',
+        runtime: 'node',
+    }),
+    'ide': Object.freeze({
+        embeddingMode: 'imperative',
+        commandSurface: 'palette',
+        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: 5, background: true, subagentToolkit: 'full', backgroundDispatch: true }),
+        modelMode: 'active',
+        hookBus: 'engine',
+        stateIO: 'sandboxed-storage',
+        transport: 'mcp',
+        runtime: 'sandboxed-web',
+    }),
+});
+// ---------------------------------------------------------------------------
+// degradationFor — plain data-table lookup (NOT clever code)
+// ---------------------------------------------------------------------------
+/**
+ * Look up the degradation level for a given interface point and partial axes.
+ *
+ * NEVER throws. Returns { level:'absent', fallback:'...', unknown:true } for
+ * any missing or unrecognised axis value.
+ */
+function degradationFor(point, axes) {
+    const UNKNOWN = {
+        level: 'absent',
+        fallback: 'unknown capability — degraded closed',
+        unknown: true,
+    };
+    switch (point) {
+        case 'command': {
+            const cs = axes.commandSurface;
+            if (cs === 'slash-file' || cs === 'slash-programmatic')
+                return { level: 'full', fallback: '' };
+            if (cs === 'slash-toml' || cs === 'palette')
+                return { level: 'degraded', fallback: 'toml/palette surface — limited command routing' };
+            if (cs === 'prose-only')
+                return { level: 'absent', fallback: 'AGENTS.md prose + skills menu' };
+            return UNKNOWN;
+        }
+        case 'dispatch': {
+            const d = axes.dispatch;
+            if (!d || typeof d !== 'object')
+                return UNKNOWN;
+            const disp = d;
+            if (disp.namedDispatch !== true || disp.maxDepth === 0) {
+                return { level: 'absent', fallback: 'single-agent inline / SDK sub-session' };
+            }
+            // maxDepth < 0 means unbounded
+            const isUnbounded = typeof disp.maxDepth === 'number' && Number.isFinite(disp.maxDepth) && disp.maxDepth < 0;
+            const depth = (typeof disp.maxDepth === 'number' && Number.isFinite(disp.maxDepth)) ? disp.maxDepth : 0;
+            const isFullDepth = isUnbounded || (disp.nested === true && depth >= 2);
+            if (isFullDepth) {
+                // Fail-closed: return 'full' ONLY when subagentToolkit is explicitly 'full';
+                // any other value (read-only, undocumented, unknown, missing) → degraded.
+                if (disp.subagentToolkit === 'full') {
+                    return { level: 'full', fallback: '' };
+                }
+                return { level: 'degraded', fallback: 'restricted/undocumented subagent toolkit — limited dispatch surface' };
+            }
+            // flat (maxDepth===1)
+            return { level: 'degraded', fallback: 'flat dispatch — waves run inline' };
+        }
+        case 'model': {
+            const mm = axes.modelMode;
+            if (mm === 'active')
+                return { level: 'full', fallback: '' };
+            if (mm === 'passive')
+                return { level: 'degraded', fallback: 'instruction-injection / per-agent model field' };
+            return UNKNOWN;
+        }
+        case 'hooks': {
+            const hb = axes.hookBus;
+            if (hb === 'host')
+                return { level: 'full', fallback: '' };
+            if (hb === 'engine')
+                return { level: 'degraded', fallback: 'engine-owned bus' };
+            if (hb === 'none')
+                return { level: 'absent', fallback: 'rule-text instructions' };
+            return UNKNOWN;
+        }
+        case 'state': {
+            const si = axes.stateIO;
+            if (si === 'filesystem')
+                return { level: 'full', fallback: '' };
+            if (si === 'sandboxed-storage')
+                return { level: 'degraded', fallback: 'sandboxed storage' };
+            if (si === 'session-log-append')
+                return { level: 'degraded', fallback: 'append-only session log' };
+            return UNKNOWN;
+        }
+        case 'artifact': {
+            const cs = axes.commandSurface;
+            if (cs === 'slash-file' || cs === 'slash-programmatic')
+                return { level: 'full', fallback: '' };
+            if (cs === 'slash-toml' || cs === 'prose-only')
+                return { level: 'degraded', fallback: 'menu / @-only' };
+            if (cs === 'palette')
+                return { level: 'absent', fallback: 'palette + chat participant; skills become LM tools' };
+            return UNKNOWN;
+        }
+        default:
+            return UNKNOWN;
+    }
+}
+// ---------------------------------------------------------------------------
+// profileOf
+// ---------------------------------------------------------------------------
+/**
+ * Classify a partial set of integration axes into a named profile.
+ * Returns null when no profile can be determined.
+ */
+function profileOf(axes) {
+    const a = axes;
+    if (a.embeddingMode === 'imperative' && a.runtime === 'sandboxed-web')
+        return 'ide';
+    if (a.embeddingMode === 'imperative')
+        return 'programmatic-cli';
+    if (a.embeddingMode === 'declarative')
+        return 'declarative-cli';
+    return null;
+}
+const DEFAULT_ENGINE = {
+    protocolVersion: PROTOCOL_VERSION,
+    axes: {
+        embeddingMode: 'imperative',
+        commandSurface: 'slash-file',
+        dispatch: { namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true },
+        modelMode: 'active',
+        hookBus: 'host',
+        stateIO: 'filesystem',
+        transport: 'mcp',
+        runtime: 'node',
+    },
+    known: HOST_INTEGRATION_AXES,
+};
+// ---------------------------------------------------------------------------
+// negotiateHostCapabilities
+// ---------------------------------------------------------------------------
+/**
+ * Negotiate host integration capabilities against an engine.
+ *
+ * POST-CONDITION: every effective scalar axis value is in engine.known[axis].
+ * effective never contains a value the host didn't declare AND the engine
+ * cannot drive.
+ *
+ * NEVER throws. Returns a fresh object each call (mutation-safe).
+ */
+function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
+    const warnings = [];
+    const h = host;
+    // Warn if protocolVersion is present but not a finite number
+    if (h.protocolVersion !== undefined && (typeof h.protocolVersion !== 'number' || !Number.isFinite(h.protocolVersion))) {
+        warnings.push(`host protocolVersion is not a finite number — using engine version ${engine.protocolVersion}`);
+    }
+    const hostPV = (typeof h.protocolVersion === 'number' && Number.isFinite(h.protocolVersion)) ? h.protocolVersion : engine.protocolVersion;
+    const enginePV = engine.protocolVersion;
+    // Warn if host declares a newer protocol version
+    if (hostPV > enginePV) {
+        warnings.push(`host protocolVersion ${hostPV} newer than engine ${enginePV} — capabilities beyond version ${enginePV} not trusted`);
+    }
+    // ---------------------------------------------------------------------------
+    // Helper: negotiate a single scalar axis
+    // ---------------------------------------------------------------------------
+    function negotiateScalar(axis) {
+        const knownValues = engine.known[axis];
+        const hostVal = h[axis];
+        const engineVal = engine.axes[axis];
+        const safeDefault = SAFE_DEFAULTS[axis];
+        if (hostVal === undefined || hostVal === null) {
+            // Host did not declare this axis
+            warnings.push(`host did not declare '${axis}'`);
+            return safeDefault;
+        }
+        if (hostVal === UNDOCUMENTED) {
+            // Host declared the undocumented sentinel — treat as fail-closed (degrade to safe default)
+            warnings.push(`host axis '${axis}' is undocumented — degraded closed`);
+            return safeDefault;
+        }
+        if (!knownValues.includes(hostVal)) {
+            // Host declared an unknown/future value — NEVER copy into effective
+            warnings.push(`host declared unknown '${axis}' value '${String(hostVal)}' — not trusted (host protocolVersion ${hostPV} vs engine ${enginePV})`);
+            return safeDefault;
+        }
+        // Engine capability cap: if the engine can't drive the host's value,
+        // use the engine's lesser capability.
+        // For modelMode: 'active' > 'passive' — if host wants active but engine
+        // is passive, cap to passive.
+        if (axis === 'modelMode') {
+            if (hostVal === 'active' && engineVal === 'passive')
+                return 'passive';
+        }
+        return hostVal;
+    }
+    // Negotiate all scalar axes
+    const effectiveEmbeddingMode = negotiateScalar('embeddingMode');
+    const effectiveCommandSurface = negotiateScalar('commandSurface');
+    const effectiveModelMode = negotiateScalar('modelMode');
+    const effectiveHookBus = negotiateScalar('hookBus');
+    const effectiveStateIO = negotiateScalar('stateIO');
+    const effectiveTransport = negotiateScalar('transport');
+    const effectiveRuntime = negotiateScalar('runtime');
+    // ---------------------------------------------------------------------------
+    // Dispatch struct negotiation
+    // ---------------------------------------------------------------------------
+    const hostDispatch = (typeof h.dispatch === 'object' && h.dispatch !== null)
+        ? h.dispatch
+        : null;
+    const engineDispatch = engine.axes.dispatch;
+    let effectiveNamedDispatch;
+    let effectiveNested;
+    let effectiveBackground;
+    let effectiveBackgroundDispatch;
+    let effectiveSubagentToolkit;
+    let effectiveMaxDepth;
+    if (hostDispatch === null) {
+        // Host didn't declare dispatch at all — fail-closed to most-restrictive values
+        warnings.push(`host did not declare 'dispatch'`);
+        effectiveNamedDispatch = false;
+        effectiveNested = false;
+        effectiveBackground = false;
+        effectiveBackgroundDispatch = false;
+        effectiveSubagentToolkit = 'read-only';
+        effectiveMaxDepth = 0;
+    }
+    else {
+        // N1: observability warnings for 'undocumented' sentinel on dispatch fields
+        if (hostDispatch.namedDispatch === 'undocumented') {
+            warnings.push(`dispatch.namedDispatch is undocumented — degraded closed`);
+        }
+        if (hostDispatch.nested === 'undocumented') {
+            warnings.push(`dispatch.nested is undocumented — degraded closed`);
+        }
+        if (hostDispatch.background === 'undocumented') {
+            warnings.push(`dispatch.background is undocumented — degraded closed`);
+        }
+        if (hostDispatch.subagentToolkit === 'undocumented') {
+            warnings.push(`dispatch.subagentToolkit is undocumented — degraded closed (read-only)`);
+        }
+        if (hostDispatch.backgroundDispatch === 'undocumented') {
+            warnings.push(`dispatch.backgroundDispatch is undocumented — degraded closed`);
+        }
+        effectiveNamedDispatch = (hostDispatch.namedDispatch === true) && engineDispatch.namedDispatch;
+        effectiveNested = (hostDispatch.nested === true) && engineDispatch.nested;
+        effectiveBackground = (hostDispatch.background === true) && engineDispatch.background;
+        effectiveBackgroundDispatch = (hostDispatch.backgroundDispatch === true) && engineDispatch.backgroundDispatch;
+        // subagentToolkit: fail closed to read-only unless explicitly 'full'
+        // (an 'undocumented' or 'read-only' value → read-only)
+        const hostToolkit = hostDispatch.subagentToolkit === 'full' ? 'full' : 'read-only';
+        const engineToolkit = engineDispatch.subagentToolkit === 'read-only' ? 'read-only' : 'full';
+        effectiveSubagentToolkit = (hostToolkit === 'read-only' || engineToolkit === 'read-only') ? 'read-only' : 'full';
+        // maxDepth: missing/non-number/non-finite → 0 + warning
+        let hostMaxDepth;
+        if (typeof hostDispatch.maxDepth !== 'number' || !Number.isFinite(hostDispatch.maxDepth)) {
+            warnings.push(`host dispatch.maxDepth is missing or not a number — treating as 0`);
+            hostMaxDepth = 0;
+        }
+        else {
+            hostMaxDepth = hostDispatch.maxDepth;
+        }
+        // Treat negative as +Infinity for the min, then if result is +Infinity emit -1
+        const hDepthNum = hostMaxDepth < 0 ? Infinity : hostMaxDepth;
+        const eDepthNum = engineDispatch.maxDepth < 0 ? Infinity : engineDispatch.maxDepth;
+        const minDepth = Math.min(hDepthNum, eDepthNum);
+        effectiveMaxDepth = minDepth === Infinity ? -1 : minDepth;
+        // If namedDispatch is false, cap maxDepth/nested/background/backgroundDispatch to 0/false/false/false (struct consistency)
+        if (!effectiveNamedDispatch) {
+            effectiveMaxDepth = 0;
+            effectiveNested = false;
+            effectiveBackground = false;
+            effectiveBackgroundDispatch = false;
+        }
+    }
+    const effectiveDispatch = {
+        namedDispatch: effectiveNamedDispatch,
+        nested: effectiveNested,
+        maxDepth: effectiveMaxDepth,
+        background: effectiveBackground,
+        subagentToolkit: effectiveSubagentToolkit,
+        backgroundDispatch: effectiveBackgroundDispatch,
+    };
+    // ---------------------------------------------------------------------------
+    // Assemble effective axes
+    // ---------------------------------------------------------------------------
+    const effective = {
+        embeddingMode: effectiveEmbeddingMode,
+        commandSurface: effectiveCommandSurface,
+        dispatch: effectiveDispatch,
+        modelMode: effectiveModelMode,
+        hookBus: effectiveHookBus,
+        stateIO: effectiveStateIO,
+        transport: effectiveTransport,
+        runtime: effectiveRuntime,
+    };
+    // ---------------------------------------------------------------------------
+    // Compute points (fresh objects — mutation-safe)
+    // ---------------------------------------------------------------------------
+    const points = {};
+    for (const point of INTERFACE_POINTS) {
+        const hostDeg = degradationFor(point, host);
+        const effectiveDeg = degradationFor(point, effective);
+        points[point] = {
+            hostLevel: hostDeg.level,
+            effectiveLevel: effectiveDeg.level,
+            fallback: effectiveDeg.fallback,
+        };
+    }
+    // protocolVersion: min of host and engine
+    const resultProtocolVersion = Math.min(hostPV, enginePV);
+    return {
+        protocolVersion: resultProtocolVersion,
+        effective,
+        points,
+        warnings: [...warnings], // fresh copy
+    };
+}
+function shouldFlattenDispatch(dispatch) {
+    if (!dispatch || typeof dispatch !== 'object')
+        return true;
+    const canBackground = dispatch.background === true && dispatch.backgroundDispatch === true;
+    return !canBackground;
+}
+module.exports = {
+    PROTOCOL_VERSION,
+    UNDOCUMENTED,
+    HOST_INTEGRATION_AXES,
+    INTERFACE_POINTS,
+    PROFILE_BASELINES,
+    DEFAULT_ENGINE,
+    degradationFor,
+    profileOf,
+    negotiateHostCapabilities,
+    shouldFlattenDispatch,
+};

package/gsd-core/bin/lib/init.cjs

@@ -1756,7 +1756,7 @@ function buildAgentSkillsBlock(config, agentType, projectRoot, diagnostics) {
         if (entry.kind === 'directive') {
             return `- Load the \`${entry.name}\` skill via the Skill tool before proceeding (plugin-provided).`;
         }
-        return `- @${entry.ref}`;
+        return `- @${String(entry.ref).replace(/\\/g, '/')}`;
     }).join('\n');
     return `<agent_skills>\nRead these user-configured skills:\n${lines}\n</agent_skills>`;
 }