summer-engine 2.8.2 → 3.1.0

package/dist/core/capabilities/variant-types.js

@@ -0,0 +1,101 @@
+/**
+ * Godot Variant.Type names for the raw integers the engine's inspector
+ * endpoint returns (E2E 2026-09-03 F-14: `summer_inspect_node` props carry
+ * `type: 2`, `type: 20`, ... — StateProvider writes `pd["type"] = pi.type`, the
+ * Variant::Type enum value, and nothing else).
+ *
+ * Order verified against summerengine core/variant/variant.h `enum Type`
+ * (Godot 4.x; VARIANT_MAX = 39). Names are the @GlobalScope `TYPE_*` constants
+ * agents see in GDScript (`typeof()`, `Variant.Type`), so a reader can match
+ * them against the class reference without a lookup table.
+ */
+export const VARIANT_TYPE_NAMES = [
+    "TYPE_NIL", // 0
+    // atomic types
+    "TYPE_BOOL", // 1
+    "TYPE_INT", // 2
+    "TYPE_FLOAT", // 3
+    "TYPE_STRING", // 4
+    // math types
+    "TYPE_VECTOR2", // 5
+    "TYPE_VECTOR2I", // 6
+    "TYPE_RECT2", // 7
+    "TYPE_RECT2I", // 8
+    "TYPE_VECTOR3", // 9
+    "TYPE_VECTOR3I", // 10
+    "TYPE_TRANSFORM2D", // 11
+    "TYPE_VECTOR4", // 12
+    "TYPE_VECTOR4I", // 13
+    "TYPE_PLANE", // 14
+    "TYPE_QUATERNION", // 15
+    "TYPE_AABB", // 16
+    "TYPE_BASIS", // 17
+    "TYPE_TRANSFORM3D", // 18
+    "TYPE_PROJECTION", // 19
+    // misc types
+    "TYPE_COLOR", // 20
+    "TYPE_STRING_NAME", // 21
+    "TYPE_NODE_PATH", // 22
+    "TYPE_RID", // 23
+    "TYPE_OBJECT", // 24
+    "TYPE_CALLABLE", // 25
+    "TYPE_SIGNAL", // 26
+    "TYPE_DICTIONARY", // 27
+    "TYPE_ARRAY", // 28
+    // typed arrays
+    "TYPE_PACKED_BYTE_ARRAY", // 29
+    "TYPE_PACKED_INT32_ARRAY", // 30
+    "TYPE_PACKED_INT64_ARRAY", // 31
+    "TYPE_PACKED_FLOAT32_ARRAY", // 32
+    "TYPE_PACKED_FLOAT64_ARRAY", // 33
+    "TYPE_PACKED_STRING_ARRAY", // 34
+    "TYPE_PACKED_VECTOR2_ARRAY", // 35
+    "TYPE_PACKED_VECTOR3_ARRAY", // 36
+    "TYPE_PACKED_COLOR_ARRAY", // 37
+    "TYPE_PACKED_VECTOR4_ARRAY", // 38
+];
+/** `TYPE_*` name for a Variant.Type integer; undefined for anything outside
+ *  the table (a future engine enum, or a value that was never a type). */
+export function variantTypeName(type) {
+    if (typeof type !== "number" || !Number.isInteger(type))
+        return undefined;
+    return VARIANT_TYPE_NAMES[type];
+}
+/**
+ * Add `type_name` next to every integer `type` in an inspector payload's
+ * `props` list (top level or under `data`), keeping the integer. Shape-
+ * tolerant: anything that is not the expected shape passes through untouched,
+ * and the input is never mutated.
+ */
+export function annotateVariantTypes(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return payload;
+    const root = payload;
+    const out = { ...root };
+    if (Array.isArray(root.props))
+        out.props = annotateProps(root.props);
+    if (root.data && typeof root.data === "object" && !Array.isArray(root.data)) {
+        const data = root.data;
+        if (Array.isArray(data.props))
+            out.data = { ...data, props: annotateProps(data.props) };
+    }
+    return out;
+}
+function annotateProps(props) {
+    return props.map((prop) => {
+        if (!prop || typeof prop !== "object" || Array.isArray(prop))
+            return prop;
+        const record = prop;
+        const name = variantTypeName(record.type);
+        if (!name || typeof record.type_name === "string")
+            return prop;
+        // Insert type_name right after type so the pair reads together.
+        const annotated = {};
+        for (const [key, value] of Object.entries(record)) {
+            annotated[key] = value;
+            if (key === "type")
+                annotated.type_name = name;
+        }
+        return annotated;
+    });
+}

package/dist/core/capability-skew.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Engine/CLI capability handshake.
+ *
+ * The MCP server and the engine build ship separately, so the tool surface can
+ * outrun the engine in the field. Newer engines advertise their dispatchable
+ * op kinds (and a protocol version) in /api/health `capabilities`. Two uses:
+ *
+ *   1. summer_get_project_context compares the advertised `opKinds` against
+ *      the ops this CLI's tools send and surfaces a ONE-LINE, NON-FATAL
+ *      warning (plus one mcp.log line per process).
+ *   2. Tools whose op the engine does not advertise return a STRUCTURED
+ *      "engine lacks op X (engine version Y); update the engine" result
+ *      BEFORE sending anything, instead of a raw "unknown op" error.
+ *
+ * Engines that predate `capabilities.opKinds` stay silent on both paths — an
+ * absent list proves nothing, and the per-tool "unknown op" hints still cover
+ * the failure at call time.
+ */
+/** Protocol generation this CLI speaks. Bump only alongside a real wire
+ *  change; used purely for the skew warning, never to refuse a connection. */
+export declare const CLI_PROTOCOL_VERSION = 1;
+/**
+ * Every engine op kind this package's tools CONSTRUCT themselves (every
+ * `op: "<Kind>"` literal under src/, MCP tools and the CLI dispatcher alike).
+ * capability-skew.test.ts scans the sources and fails when a literal is
+ * missing here; src/core/op-registry-drift.test.ts guards the other direction
+ * inside the engine monorepo (never send an op the engine has no branch for).
+ *
+ * Deliberately NOT listed: ops an agent may compose by hand through
+ * summer_batch / `summer tool batch` (MoveNode, ReparentNode, DisconnectSignal,
+ * Undo, Git*, RunCommand, ExtractZipFromUrl, CustomBake, ...). The CLI only
+ * classifies those for dispatch (single-only / scene-mutation sets) and never
+ * sends them on its own, so listing them would warn about skew the CLI cannot
+ * cause; the engine's per-op "unknown op" error still covers them at call time.
+ */
+export declare const CLI_KNOWN_OP_NEEDS: readonly string[];
+/** The `capabilities` block of /api/health, shape-checked. Every field is
+ *  optional: an older engine advertises none of them. */
+/**
+ * Escape hatch for the capability pre-flight. The op advert and the ops
+ * themselves ship on different engine branches, so an engine can IMPLEMENT an
+ * op it does not yet ADVERTISE; with the pre-flight on, such a tool would be
+ * refused before sending. `SUMMER_CAPABILITY_PREFLIGHT=off` sends every call
+ * and lets the engine's own "unknown op" error decide. The skew warning still
+ * prints (it is informational) but notes that the pre-flight is off.
+ */
+export declare const CAPABILITY_PREFLIGHT_ENV = "SUMMER_CAPABILITY_PREFLIGHT";
+export declare function isCapabilityPreflightDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The `events` block of /api/health `capabilities` — the engine's events
+ * channel advert (GET /api/events SSE + GET /api/events/poll long-poll).
+ * Present only on builds that ship the channel; every field is optional so a
+ * partial advert still counts as "the channel exists".
+ */
+export interface EngineEventsCapability {
+    /** Event kinds this build emits (op.applied, play.started, ...). */
+    kinds?: string[];
+    ring?: number;
+    retainMs?: number;
+    maxPayloadBytes?: number;
+    sse?: boolean;
+    poll?: boolean;
+    maxStreams?: number;
+    heartbeatMs?: number;
+}
+export interface EngineCapabilities {
+    protocolVersion?: number;
+    /** Full dispatch-ladder op set. Absent = engine predates the advert. */
+    opKinds?: string[];
+    /** Ops that must travel as their own single-op request. Absent = use the
+     *  CLI's hardcoded list. */
+    singleOnlyOps?: string[];
+    /** Events channel advert. Absent = the build has no events channel (the
+     *  channel and its advert ship together, so absence IS proof here). */
+    events?: EngineEventsCapability;
+    /** runtime control advert: the runtime op kinds, whether the game-side
+     *  `summer` capture ships, and the offscreen instance cap. Absent = engine
+     *  predates runtime control (or advertises the kinds only in opKinds). */
+    runtimeControl?: EngineRuntimeControlCapabilities;
+    /** Editor navigation advert (engine `Navigate` op, navigate_ops.cpp): the
+     *  destination ids this build can open. Absent = engine predates the op;
+     *  summer_open then falls back to the legacy per-surface ops it can map. */
+    navigation?: EngineNavigationCapabilities;
+    /** Launch postures this build ENFORCES: "focus" (always), "background"
+     *  (`--summer-background`), "offscreen" (`--summer-offscreen` /
+     *  `--summer-verify`). Non-macOS builds advertise ["focus"] only. Absent =
+     *  engine predates the advert, read as ["focus"]; `summer run` then relies on
+     *  the --help probe / version gate (core/launch-posture.ts). Accepts the
+     *  snake_case spelling too. */
+    launchPostures?: string[];
+}
+export interface EngineNavigationCapabilities {
+    version?: number;
+    targets: EngineNavigationTarget[];
+}
+export interface EngineNavigationTarget {
+    id: string;
+    title?: string;
+    args?: string[];
+}
+export interface EngineRuntimeControlCapabilities {
+    ops?: string[];
+    summerCapture?: boolean;
+    maxOffscreenInstances?: number;
+}
+/** Every op kind the engine advertises: `opKinds` plus the
+ *  `runtimeControl.ops` block (an engine may list the runtime kinds only
+ *  there). Undefined when the engine advertises no op list at all. */
+export declare function advertisedOpKinds(capabilities: EngineCapabilities | undefined | null): Set<string> | undefined;
+/** Parse a raw /api/health `capabilities` value. Tolerates any shape; returns
+ *  undefined when nothing usable is advertised. Never throws. */
+export declare function parseEngineCapabilities(raw: unknown): EngineCapabilities | undefined;
+/**
+ * True ONLY when the engine advertises an op list and `op` is not on it. An
+ * engine without an advert returns false — we cannot prove absence, so the
+ * call goes through and the per-tool "unknown op" hint handles the failure.
+ */
+export declare function engineLacksOp(capabilities: EngineCapabilities | undefined | null, op: string): boolean;
+export interface MissingOpResult {
+    ok: false;
+    op: string;
+    failure_reason: "engine_lacks_op";
+    engine_version: string | null;
+    error: string;
+    hint: string;
+}
+/**
+ * The structured result a tool returns when the engine provably lacks its op.
+ * Shaped like an engine op failure ({ok:false, op, error, failure_reason}) so
+ * withEngine/extractOpError classify it the same way, and the model reads the
+ * upgrade path instead of retrying.
+ */
+export declare function buildMissingOpResult(op: string, engineVersion: string | null | undefined, fallback: string): MissingOpResult;
+/**
+ * True when the engine does NOT advertise the events channel. Unlike ops,
+ * where an absent `opKinds` list proves nothing (ops predate the advert), the
+ * events channel and its `capabilities.events` advert ship together: a build
+ * with the channel always advertises it, so absence — including an engine that
+ * advertises no capabilities at all — is proof.
+ */
+export declare function engineLacksEvents(capabilities: EngineCapabilities | undefined | null): boolean;
+export interface MissingEventsResult {
+    ok: false;
+    failure_reason: "engine_lacks_events";
+    engine_version: string | null;
+    error: string;
+    hint: string;
+}
+/** What the events tools tell the model to do when the channel is missing. */
+export declare const EVENTS_FALLBACK = "poll the state you are waiting for instead (summer_is_running after summer_play; summer_get_debugger_errors / summer_get_console for script errors; summer_get_scene_tree after a long op)";
+/**
+ * The structured result an events tool returns when the engine provably lacks
+ * the channel. Shaped like buildMissingOpResult ({ok:false, failure_reason,
+ * engine_version, error, hint}) so withEngine/extractOpError classify it the
+ * same way and `summer tool` prints it whole — but under its own
+ * failure_reason, because no op was ever involved.
+ */
+export declare function buildMissingEventsResult(engineVersion: string | null | undefined, fallback?: string): MissingEventsResult;
+/**
+ * Capability pre-flight for the events tools (summer_wait_for_event,
+ * summer_recent_events, `summer events`). Returns a structured
+ * engine_lacks_events result (nothing is sent) when the engine's /api/health
+ * advert lacks `capabilities.events`; null when the channel is advertised or
+ * the SUMMER_CAPABILITY_PREFLIGHT=off escape hatch is set. Sibling of
+ * missingEngineOpResult — kept separate because events are a capability, not
+ * an op kind.
+ */
+export declare function missingEngineEventsResult(client: CapabilityAdvertisingClient, fallback?: string): MissingEventsResult | null;
+/**
+ * Build the one-line skew warning from a raw /api/health payload, or null when
+ * there is nothing trustworthy to say (no capabilities advertised, or no skew).
+ * Shape-tolerant: never throws on odd payloads.
+ */
+export declare function buildCapabilitySkewWarning(health: unknown): string | null;
+/**
+ * Engine ops that MUST be dispatched as their own single-op request. Mirrors
+ * _summer_requires_single_async_dispatch (local_api_server.cpp, engine
+ * 0.5.60+): the engine rejects any multi-op batch containing one of these
+ * WHOLESALE — nothing in the batch executes, and the batch fails with per-op
+ * failure_reason "unsupported_transport"/"skipped". Git ops are covered by a
+ * prefix check in the dispatchers.
+ *
+ * This hardcoded list is the FALLBACK for engines that predate the
+ * /api/health `capabilities.singleOnlyOps` advert; when the engine advertises
+ * its own list, that list is authoritative (resolveSingleOnlyOps).
+ */
+export declare const FALLBACK_SINGLE_ONLY_OPS: ReadonlySet<string>;
+/** The subset of EngineApiClient the capability readers use. Structural so
+ *  unit tests can pass bare mock clients (no getter = no advert). */
+export interface CapabilityAdvertisingClient {
+    getEngineCapabilities?: () => EngineCapabilities | undefined;
+    getEngineVersion?: () => string | undefined;
+}
+/** The single-only op set for THIS engine: its advertised
+ *  `capabilities.singleOnlyOps` when present, else the hardcoded fallback. An
+ *  empty advertised list counts as no advert — never as "everything batches". */
+export declare function resolveSingleOnlyOps(client: CapabilityAdvertisingClient): ReadonlySet<string>;
+/**
+ * Capability pre-flight for tools that depend on an op an older engine may
+ * lack. Returns a structured engine_lacks_op result (nothing is sent) when
+ * the engine's /api/health advert PROVES the op is missing; null otherwise —
+ * including for engines that advertise nothing, where the per-tool
+ * "unknown op" hint still covers the failure at call time.
+ */
+export declare function missingEngineOpResult(client: CapabilityAdvertisingClient, op: string, fallback: string): MissingOpResult | null;