summer-engine 2.8.1 → 3.0.0

package/dist/core/capabilities/project-context.js

@@ -0,0 +1,249 @@
+/**
+ * project-context — ONE builder for `summer_get_project_context`, called by
+ * both faces (src/mcp/tools/project-tools.ts and
+ * src/core/capabilities/tool-dispatch.ts) so the payload is identical
+ * (CONTRACT.md §3, "one behavior, two faces").
+ *
+ * E2E 2026-09-03 F-04: the CLI face returned an untrimmed 969-setting dump
+ * (144 KB) with no guidance/projectMemory while the MCP face returned the
+ * trimmed 88 KB shape — two implementations, two payloads. Both now call
+ * buildProjectContext(); the only face-specific input is the MCP boot drift
+ * notice, passed in as an extra.
+ *
+ * Payload budget: the engine's /api/state/project ignores ?prefix= (it is
+ * snapshot-served — see EngineApiClient.getProjectState), so every trim here
+ * is client-side and every trim is declared (settingsTruncated, totalSettings,
+ * settingsPrefixesIncluded, settingsPrefixesExcluded) — nothing is hidden,
+ * only deferred behind settingsPrefixes.
+ */
+import { z } from "zod";
+import { EngineRebindError } from "../api-client.js";
+import { buildCapabilitySkewWarning } from "../capability-skew.js";
+import { isTrajectoryEvalMode } from "../trajectory.js";
+import { getProjectMemorySummary, } from "../../project-memory/project-memory.js";
+import { asRecord, stringFrom } from "../util/json.js";
+/**
+ * Settings groups an agent acts on by default: project identity and main
+ * scene (application/), window size and stretch (display/window/), the
+ * project's own input actions (input/), gravity, the renderer method
+ * (forward_plus / mobile / gl_compatibility) and the 2D default texture
+ * filter (pixel art vs. smooth). Everything else — audio buses, layer names,
+ * editor prefs, per-feature rendering knobs — is one settingsPrefixes call
+ * away and is counted in totalSettings.
+ */
+export const DEFAULT_PROJECT_CONTEXT_SETTINGS_PREFIXES = [
+    "application/",
+    "display/window/",
+    "input/",
+    "physics/2d/default_gravity",
+    "physics/3d/default_gravity",
+    "rendering/renderer/",
+    "rendering/textures/canvas_textures/",
+];
+/**
+ * Dropped from the default set only: Godot's built-in `input/ui_*` actions
+ * (72 of them, identical in every project, each carrying InputEvent dumps).
+ * They are the single largest block of the default payload and never inform
+ * a game-building decision. Read them with settingsPrefixes: ["input/ui_"].
+ */
+export const DEFAULT_PROJECT_CONTEXT_SETTINGS_EXCLUDED = ["input/ui_"];
+export const MAX_SETTINGS_PREFIXES = 32;
+// Mirrors library/tools/get-project-context/resource.yaml input_schema (parity-tested).
+export const projectContextInputShape = {
+    settingsPrefix: z
+        .string()
+        .optional()
+        .describe("Only return project settings whose key starts with this prefix, e.g. 'audio/' or 'application/config/'. Omit for the curated default set."),
+    settingsPrefixes: z
+        .array(z.string())
+        .max(MAX_SETTINGS_PREFIXES)
+        .optional()
+        .describe("Several settings groups at once, e.g. ['audio/', 'layer_names/2d_physics/', 'input/ui_']. Merged with settingsPrefix. Omit for the curated default set."),
+};
+export const projectContextInputSchema = z.object(projectContextInputShape).strict();
+/** Which settings groups to keep: the caller's prefixes (settingsPrefix and
+ *  settingsPrefixes merged, blanks dropped, order kept, de-duplicated) or the
+ *  curated default with its exclusion. */
+export function resolveSettingsSelection(args) {
+    const requested = [];
+    const push = (value) => {
+        const prefix = stringFrom(value)?.trim();
+        if (prefix && !requested.includes(prefix))
+            requested.push(prefix);
+    };
+    push(args.settingsPrefix);
+    for (const prefix of args.settingsPrefixes ?? [])
+        push(prefix);
+    if (requested.length > 0) {
+        const single = stringFrom(args.settingsPrefix)?.trim();
+        return { prefixes: requested, excluded: [], explicit: true, ...(single ? { settingsPrefix: single } : {}) };
+    }
+    return {
+        prefixes: DEFAULT_PROJECT_CONTEXT_SETTINGS_PREFIXES,
+        excluded: DEFAULT_PROJECT_CONTEXT_SETTINGS_EXCLUDED,
+        explicit: false,
+    };
+}
+/**
+ * Bound the project-state payload to the selected settings groups. Everything
+ * outside data.entries is preserved; the trim is always declared so an agent
+ * can see what it did not get and how to ask for it.
+ */
+export function trimProjectSettings(projectState, selection) {
+    const root = asRecord(projectState);
+    const data = asRecord(root?.data);
+    const entries = data?.entries;
+    if (!root || !data || !Array.isArray(entries))
+        return projectState;
+    const keyOf = (entry) => stringFrom(asRecord(entry)?.key) ?? null;
+    const kept = entries.filter((entry) => {
+        const key = keyOf(entry);
+        if (key === null)
+            return false;
+        if (!selection.prefixes.some((prefix) => key.startsWith(prefix)))
+            return false;
+        return !selection.excluded.some((prefix) => key.startsWith(prefix));
+    });
+    return {
+        ...root,
+        data: {
+            ...data,
+            entries: kept,
+            settingsTruncated: kept.length < entries.length,
+            totalSettings: entries.length,
+            returnedSettings: kept.length,
+            settingsPrefixesIncluded: [...selection.prefixes],
+            ...(selection.settingsPrefix ? { settingsPrefix: selection.settingsPrefix } : {}),
+            ...(selection.excluded.length > 0 ? { settingsPrefixesExcluded: [...selection.excluded] } : {}),
+            settingsHint: selection.explicit
+                ? "Settings were filtered to settingsPrefixesIncluded; totalSettings counts everything the engine holds. Pass settingsPrefixes (several groups) or settingsPrefix (one) to read another group."
+                : `Settings were trimmed to the curated default groups in settingsPrefixesIncluded (minus settingsPrefixesExcluded) to bound payload size; the engine holds ${entries.length} in total. Pass settingsPrefixes — e.g. ["audio/"], ["layer_names/"], ["input/ui_"], ["rendering/"] — to read another group.`,
+        },
+    };
+}
+// ── Derived fields (shape-tolerant reads of the engine state) ──────────────
+function pickString(record, keys) {
+    if (!record)
+        return null;
+    for (const key of keys) {
+        const value = stringFrom(record[key]);
+        if (value)
+            return value;
+    }
+    return null;
+}
+function projectData(projectState) {
+    return asRecord(asRecord(projectState)?.data);
+}
+/** The value of the first matching ProjectSettings key, or null. */
+export function projectSettingValue(projectState, keys) {
+    const entries = projectData(projectState)?.entries;
+    if (!Array.isArray(entries))
+        return null;
+    for (const entry of entries) {
+        const item = asRecord(entry);
+        const key = stringFrom(item?.key);
+        if (key && keys.includes(key))
+            return stringFrom(item?.value) ?? null;
+    }
+    return null;
+}
+export function resolveProjectPath(projectState, health) {
+    const root = asRecord(projectState);
+    const data = projectData(projectState);
+    const healthRoot = asRecord(health);
+    return (pickString(data, ["projectPath", "project_path", "projectRoot", "project_root", "rootPath", "root_path"]) ??
+        pickString(root, ["projectPath", "project_path", "projectRoot", "project_root"]) ??
+        pickString(healthRoot, ["project_path", "projectPath", "projectRoot", "project_root"]) ??
+        null);
+}
+export function resolveProjectName(projectState, health) {
+    const root = asRecord(projectState);
+    const data = projectData(projectState);
+    const healthRoot = asRecord(health);
+    return (pickString(data, ["projectName", "project_name", "name"]) ??
+        pickString(root, ["projectName", "project_name", "name"]) ??
+        pickString(healthRoot, ["project_name", "projectName", "name"]) ??
+        projectSettingValue(projectState, ["application/config/name", "config/name"]));
+}
+export function resolveMainScene(projectState) {
+    const root = asRecord(projectState);
+    const data = projectData(projectState);
+    return (pickString(data, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        pickString(root, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        projectSettingValue(projectState, ["application/run/main_scene", "run/main_scene"]));
+}
+export function resolveCurrentScene(projectState, sceneState, health) {
+    const sceneRoot = asRecord(sceneState);
+    const projectRoot = asRecord(projectState);
+    return (pickString(asRecord(sceneRoot?.provenance), ["scenePath", "scene_path"]) ??
+        pickString(asRecord(sceneRoot?.data), ["scenePath", "scene_path", "currentScene", "current_scene"]) ??
+        pickString(projectData(projectState), ["currentScene", "current_scene", "scenePath", "scene_path"]) ??
+        pickString(asRecord(projectRoot?.provenance), ["scenePath", "scene_path"]) ??
+        pickString(asRecord(health), ["scene", "scenePath", "scene_path"]) ??
+        null);
+}
+// ── The builder ────────────────────────────────────────────────────────────
+export async function buildProjectContext(client, args = {}, extras = {}) {
+    const selection = resolveSettingsSelection(args);
+    const [health, fullProjectState, sceneState] = await Promise.all([
+        client.health(),
+        // ?prefix= rides along for forward-compatibility (a single prefix is all
+        // the engine query can carry); current engines ignore it, so the
+        // client-side trim below must hold on its own.
+        client.getProjectState(stringFrom(args.settingsPrefix)),
+        client.getSceneState().catch((err) => ({
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        })),
+    ]);
+    // Derived fields read the UNtrimmed state so a narrow prefix cannot hide
+    // mainScene/projectPath from the context summary.
+    const project = trimProjectSettings(fullProjectState, selection);
+    const projectPath = resolveProjectPath(fullProjectState, health);
+    const projectName = resolveProjectName(fullProjectState, health);
+    const mainScene = resolveMainScene(fullProjectState);
+    const currentScene = resolveCurrentScene(fullProjectState, sceneState, health);
+    // This tool is the deliberate (re)bind point: capture the currently-open
+    // project as the one this session's mutations are pinned to. A failed
+    // rebind keeps the previous identity; say so instead of echoing the stale
+    // hash as if the switch had been followed.
+    let boundProjectIdHash;
+    let rebindError;
+    try {
+        boundProjectIdHash = await client.rebind();
+    }
+    catch (error) {
+        if (!(error instanceof EngineRebindError))
+            throw error;
+        rebindError = error.message;
+    }
+    // Newer engines advertise capabilities (protocolVersion + opKinds) in
+    // /api/health; a one-line NON-FATAL warning explains upcoming unknown-op
+    // failures. Engines that predate the advert stay silent.
+    const capabilitySkewWarning = buildCapabilitySkewWarning(health);
+    if (capabilitySkewWarning)
+        extras.onCapabilitySkew?.(capabilitySkewWarning);
+    return {
+        health,
+        ...(capabilitySkewWarning ? { capabilitySkewWarning } : {}),
+        project,
+        scene: sceneState,
+        projectName,
+        projectPath,
+        currentScene,
+        mainScene,
+        boundProjectIdHash,
+        ...(rebindError ? { rebindError } : {}),
+        projectMemory: getProjectMemorySummary(projectPath),
+        summerUpdateNotice: extras.summerUpdateNotice ?? null,
+        // Eval-mode trajectory capture (unredacted trajectory.full.jsonl) is
+        // visible to the agent and to a human reading the transcript — on both
+        // faces, since both call this builder.
+        ...(isTrajectoryEvalMode() ? { trajectory_eval_mode: true } : {}),
+        guidance: mainScene
+            ? "Use `summer_open_scene` with `mainScene` if no scene is open."
+            : "Main scene not found in project state. Open a known scene path explicitly.",
+        fileEditingGuidance: "Use summer_read_file plus summer_replace_text or guarded summer_write_file for project files, including .gd/.cs/.tscn/.tres/.json/docs. New files require create_only:true; overwrites require the sha256 receipt from summer_read_file. Prefer scene tools for live hierarchy/inspector changes.",
+    };
+}