summer-engine 2.8.2 → 3.1.0

package/dist/core/capabilities/navigation/targets.d.ts

@@ -0,0 +1,87 @@
+export type NavSurface = "web" | "editor";
+export interface NavParam {
+    name: string;
+    description: string;
+    required?: boolean;
+    /** Closed vocabulary, when one exists (validated). */
+    values?: readonly string[];
+    /** Friendly names that resolve to a value in `values` (e.g. "cursor" -> a guide slug). */
+    valueAliases?: Readonly<Record<string, string>>;
+}
+export interface WebRoute {
+    id: string;
+    /** Path template. `{slot}` required; `[/{slot}]` optional segment. */
+    path: string;
+    title: string;
+    description: string;
+    intents: readonly string[];
+    auth: "public" | "signed-in";
+    aliases?: readonly string[];
+    params?: readonly NavParam[];
+    /** "docs" = docs.summerengine.com; default = the gateway origin. */
+    origin?: "web" | "docs";
+}
+export interface WebRoutesCatalog {
+    schemaVersion: string;
+    source?: string;
+    base: string;
+    docsBase: string;
+    login: {
+        path: string;
+        returnParam: string;
+    };
+    routes: WebRoute[];
+}
+export declare const WEB_ROUTES_SNAPSHOT_PATH: string;
+export declare function parseWebRoutesCatalog(raw: unknown, where?: string): WebRoutesCatalog;
+export declare function loadWebRoutesCatalog(path?: string): WebRoutesCatalog;
+export declare const WEB_CATALOG: WebRoutesCatalog;
+/** How to express a row as the engine's one-table op: Navigate { target, ...args }. */
+export interface NavigateSpec {
+    target: string;
+    fixed?: Readonly<Record<string, string>>;
+    /** param name -> Navigate arg name */
+    map?: Readonly<Record<string, string>>;
+}
+/** The pre-Navigate op an older engine can serve this row with. */
+export interface LegacyOpSpec {
+    op: string;
+    fixed?: Readonly<Record<string, string>>;
+    /** param name -> op field */
+    map?: Readonly<Record<string, string>>;
+}
+export interface EditorTargetMeta {
+    id: string;
+    title: string;
+    description: string;
+    intents: readonly string[];
+    aliases?: readonly string[];
+    navigate: NavigateSpec;
+    legacy?: LegacyOpSpec;
+    params?: readonly NavParam[];
+    /** When `path` is omitted, read application/run/main_scene first. */
+    mainSceneDefault?: boolean;
+}
+export declare const EDITOR_TARGETS: readonly EditorTargetMeta[];
+/** Legacy ops the toolkit may still send on engines that predate `Navigate`. */
+export declare const LEGACY_NAVIGATION_OPS: Set<string>;
+export interface NavTarget {
+    id: string;
+    surface: NavSurface;
+    title: string;
+    description: string;
+    intents: readonly string[];
+    aliases?: readonly string[];
+    params?: readonly NavParam[];
+    requires: {
+        login?: boolean;
+        engine?: boolean;
+    };
+    web?: {
+        origin: "gateway" | "docs";
+        path: string;
+    };
+    editor?: EditorTargetMeta;
+}
+export declare const NAV_TARGETS: readonly NavTarget[];
+export declare function getNavTarget(idOrAlias: string): NavTarget | undefined;

package/dist/core/capabilities/navigation/targets.js

@@ -0,0 +1,250 @@
+/**
+ * The product map as the toolkit sees it (docs/design/NAVIGATION-PLAN.md).
+ *
+ * The toolkit does NOT own where things are. Each product does:
+ *
+ * - summerengine.com publishes /agent-routes.json (web repo
+ *   src/lib/navigation/routes.ts). A vendored snapshot lives at
+ *   assets/navigation/web-routes.json (refresh: `npm run sync:web-routes`) and
+ *   every web row below is built from it — nothing hand-written.
+ * - Summer Engine owns one table of editor destinations (navigate_ops.cpp) and
+ *   advertises the ids it can open in /api/health capabilities.navigation.
+ *   The rows below are METADATA for those ids (titles, intents, argument
+ *   names) plus, for the few ids an older engine can serve through its
+ *   original ops, a `legacy` mapping. Availability is decided at connect time
+ *   from the advert, never hardcoded here.
+ *
+ * `summer_open` / `summer open` forward ids; they never know the layout.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { PACKAGE_ROOT } from "../../package-root.js";
+export const WEB_ROUTES_SNAPSHOT_PATH = resolve(PACKAGE_ROOT, "assets/navigation/web-routes.json");
+export function parseWebRoutesCatalog(raw, where = "web-routes") {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`${where}: not an object`);
+    const doc = raw;
+    if (!Array.isArray(doc.routes))
+        throw new Error(`${where}: missing routes[]`);
+    const login = (doc.login ?? {});
+    const routes = [];
+    const seen = new Set();
+    for (const entry of doc.routes) {
+        const r = (entry ?? {});
+        for (const key of ["id", "path", "title", "description"]) {
+            if (typeof r[key] !== "string" || r[key].length === 0) {
+                throw new Error(`${where}: route ${JSON.stringify(r.id ?? "?")} missing string ${key}`);
+            }
+        }
+        if (seen.has(r.id))
+            throw new Error(`${where}: duplicate route id ${r.id}`);
+        seen.add(r.id);
+        routes.push({
+            id: r.id,
+            path: r.path,
+            title: r.title,
+            description: r.description,
+            intents: Array.isArray(r.intents) ? r.intents.filter((x) => typeof x === "string") : [],
+            auth: r.auth === "signed-in" ? "signed-in" : "public",
+            ...(Array.isArray(r.aliases) ? { aliases: r.aliases.filter((x) => typeof x === "string") } : {}),
+            ...(Array.isArray(r.params) ? { params: r.params } : {}),
+            ...(r.origin === "docs" ? { origin: "docs" } : {}),
+        });
+    }
+    return {
+        schemaVersion: typeof doc.schemaVersion === "string" ? doc.schemaVersion : "1.0",
+        ...(typeof doc.source === "string" ? { source: doc.source } : {}),
+        base: typeof doc.base === "string" ? doc.base : "https://www.summerengine.com",
+        docsBase: typeof doc.docsBase === "string" ? doc.docsBase : "https://docs.summerengine.com",
+        login: {
+            path: typeof login.path === "string" ? login.path : "/login",
+            returnParam: typeof login.returnParam === "string" ? login.returnParam : "returnUrl",
+        },
+        routes,
+    };
+}
+export function loadWebRoutesCatalog(path = WEB_ROUTES_SNAPSHOT_PATH) {
+    return parseWebRoutesCatalog(JSON.parse(readFileSync(path, "utf8")), path);
+}
+export const WEB_CATALOG = loadWebRoutesCatalog();
+const PATH_PARAM = { name: "path", description: "Project resource path, e.g. res://levels/level_1.tscn", required: true };
+function dock(id, name, title, intents, legacyDock, aliases) {
+    return {
+        id,
+        title,
+        description: `The ${title} comes to the front.`,
+        intents,
+        ...(aliases ? { aliases } : {}),
+        navigate: { target: "dock", fixed: { name } },
+        ...(legacyDock ? { legacy: { op: "FocusDock", fixed: { dock: legacyDock } } } : {}),
+    };
+}
+function screen(id, name, intents) {
+    return {
+        id,
+        title: `${name} main screen`,
+        description: `The main editor switches to the ${name} view.`,
+        intents,
+        navigate: { target: id },
+    };
+}
+function panel(id, title, intents) {
+    return {
+        id,
+        title,
+        description: `The ${title} opens at the bottom of the editor.`,
+        intents,
+        navigate: { target: "panel", fixed: { name: id } },
+    };
+}
+export const EDITOR_TARGETS = [
+    {
+        id: "scene",
+        title: "Open a scene",
+        description: "The scene becomes the current tab in Summer Engine.",
+        intents: ["open the scene", "open this scene", "show the scene", "switch to the scene", "the scene i'm editing", "open my level"],
+        navigate: { target: "scene", map: { path: "path" } },
+        legacy: { op: "OpenScene", map: { path: "path" } },
+        params: [{ name: "path", description: "Scene path, e.g. res://main.tscn. Omit for the project's main scene." }],
+        mainSceneDefault: true,
+    },
+    {
+        id: "main-scene",
+        title: "Open the main scene",
+        description: "The project's configured main scene becomes the current tab.",
+        intents: ["open the main scene", "main scene", "go to the main scene", "the starting scene"],
+        navigate: { target: "scene" },
+        legacy: { op: "OpenScene" },
+        mainSceneDefault: true,
+    },
+    {
+        id: "node",
+        title: "Select a node",
+        description: "The node is highlighted in the Scene tree and its properties show in the Inspector.",
+        intents: ["select the node", "show me the node", "focus the player node", "highlight the node", "go to the node", "inspect the node in the editor"],
+        navigate: { target: "node", map: { node: "path", scene: "scene" } },
+        legacy: { op: "SelectNode", map: { node: "nodePath", scene: "scenePath" } },
+        params: [
+            { name: "node", description: "Node path relative to the scene root, e.g. Player/Camera3D.", required: true },
+            { name: "scene", description: "Scene to open first, e.g. res://main.tscn (optional)." },
+        ],
+    },
+    {
+        id: "script",
+        title: "Open a script",
+        description: "The script opens in the Script editor and takes focus (at a line, when given). On engines without the Navigate op it opens without taking focus.",
+        intents: ["open the script", "show me the script", "open the gdscript file", "go to the script", "open player.gd", "jump to line"],
+        navigate: { target: "script", map: { path: "path", line: "line", col: "col" } },
+        legacy: { op: "OpenResource", map: { path: "path" } },
+        params: [PATH_PARAM, { name: "line", description: "1-based line to jump to (Navigate engines only)." }, { name: "col", description: "Column (Navigate engines only)." }],
+    },
+    {
+        id: "file",
+        title: "Reveal a file",
+        description: "The FileSystem dock comes to the front, scrolled to the file.",
+        intents: ["show the file in the filesystem", "reveal the file", "find the file in the editor", "where is this asset", "show me the texture in the file dock"],
+        navigate: { target: "file", map: { path: "path" } },
+        legacy: { op: "RevealInFileSystem", map: { path: "path" } },
+        params: [PATH_PARAM],
+    },
+    dock("files", "file_system", "FileSystem dock", ["filesystem dock", "file dock", "show the files", "project files panel"], "file_system", ["filesystem", "file-system"]),
+    dock("scene-tree", "scene_tree", "Scene tree dock", ["scene tree", "scene dock", "show the scene tree", "node tree panel"], "scene_tree"),
+    dock("inspector", "inspector", "Inspector dock", ["inspector", "show the inspector", "properties panel", "inspector dock"], "inspector"),
+    dock("import-dock", "import", "Import dock", ["import dock", "import settings panel", "show import options"]),
+    dock("signals-dock", "node", "Node dock (signals and groups)", ["signals dock", "node dock", "show the signals", "connect signals panel"]),
+    dock("changes-dock", "changes", "Changes dock", ["changes dock", "show the changes", "what did the agent change", "diff panel"]),
+    screen("screen-2d", "2D", ["switch to 2d", "2d view", "show the 2d editor"]),
+    screen("screen-3d", "3D", ["switch to 3d", "3d view", "show the 3d editor", "show me the viewport"]),
+    screen("screen-script", "Script", ["switch to the script editor", "script view", "show the code editor"]),
+    screen("screen-game", "Game", ["switch to the game view", "game tab", "show the running game view"]),
+    screen("screen-assetlib", "AssetLib", ["asset library tab", "open the asset lib", "godot asset library"]),
+    {
+        id: "viewport-show",
+        title: "Show the viewport column",
+        description: "The agent layout's viewport column becomes visible.",
+        intents: ["show the viewport column", "bring back the viewport", "unhide the editor viewport"],
+        navigate: { target: "viewport-show" },
+    },
+    {
+        id: "viewport-hide",
+        title: "Hide the viewport column",
+        description: "The agent layout's viewport column is hidden.",
+        intents: ["hide the viewport column", "hide the editor viewport", "chat only layout"],
+        navigate: { target: "viewport-hide" },
+    },
+    {
+        id: "assistant",
+        title: "Summer assistant",
+        description: "The Summer assistant (chat) dock opens.",
+        intents: ["open the assistant", "show the chat dock", "summer assistant", "ai chat in the editor", "open the agent panel"],
+        navigate: { target: "assistant", map: { path: "path" } },
+        params: [{ name: "path", description: "Chat path to open (optional)." }],
+    },
+    {
+        id: "project-settings",
+        title: "Project Settings",
+        description: "The Project Settings dialog opens.",
+        intents: ["project settings", "settings", "open project settings", "input map settings", "autoload settings", "rendering settings"],
+        navigate: { target: "project-settings", map: { tab: "tab" } },
+        params: [{ name: "tab", description: "Settings tab to show (best effort)." }],
+    },
+    {
+        id: "editor-settings",
+        title: "Editor Settings",
+        description: "The Editor Settings dialog opens.",
+        intents: ["editor settings", "settings", "open editor settings", "editor preferences", "change the editor theme"],
+        navigate: { target: "editor-settings" },
+    },
+    panel("output", "Output panel", ["output panel", "show the output", "editor console", "show the log"]),
+    panel("debugger", "Debugger panel", ["debugger panel", "show the debugger", "open the debugger", "errors panel"]),
+    {
+        id: "editor-window",
+        title: "Summer Engine window",
+        description: "The Summer Engine window comes to the front.",
+        intents: ["bring the editor to the front", "focus summer engine", "show the editor window", "switch to the editor"],
+        navigate: { target: "editor-window" },
+    },
+];
+/** Legacy ops the toolkit may still send on engines that predate `Navigate`. */
+export const LEGACY_NAVIGATION_OPS = new Set(["OpenScene", "SelectNode", "OpenResource", "FocusDock", "RevealInFileSystem"]);
+function fromWeb(route) {
+    return {
+        id: route.id,
+        surface: "web",
+        title: route.title,
+        description: route.description,
+        intents: route.intents,
+        ...(route.aliases ? { aliases: route.aliases } : {}),
+        ...(route.params ? { params: route.params } : {}),
+        requires: route.auth === "signed-in" ? { login: true } : {},
+        web: { origin: route.origin === "docs" ? "docs" : "gateway", path: route.path },
+    };
+}
+function fromEditor(meta) {
+    return {
+        id: meta.id,
+        surface: "editor",
+        title: meta.title,
+        description: meta.description,
+        intents: meta.intents,
+        ...(meta.aliases ? { aliases: meta.aliases } : {}),
+        ...(meta.params ? { params: meta.params } : {}),
+        requires: { engine: true },
+        editor: meta,
+    };
+}
+export const NAV_TARGETS = [...WEB_CATALOG.routes.map(fromWeb), ...EDITOR_TARGETS.map(fromEditor)];
+const BY_ID = new Map();
+for (const target of NAV_TARGETS) {
+    if (BY_ID.has(target.id))
+        throw new Error(`navigation: duplicate target id ${target.id}`);
+    BY_ID.set(target.id, target);
+    for (const alias of target.aliases ?? []) {
+        if (BY_ID.has(alias))
+            throw new Error(`navigation: alias ${alias} collides on ${target.id}`);
+        BY_ID.set(alias, target);
+    }
+}
+export function getNavTarget(idOrAlias) {
+    return BY_ID.get(idOrAlias.trim().toLowerCase());
+}

package/dist/core/capabilities/play-determinism.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PlayGame determinism params (engine contract "PlayGame determinism params
+ * (additive)"): seed / fixed_fps / time_scale ride onto ONE launch's child
+ * command line (--summer-seed, --fixed-fps, --time-scale). Shared by the MCP
+ * summer_play tool and the CLI dispatcher.
+ *
+ * Transport note: the engine's /api/play rung copies only `scene` into the
+ * PlayGame op (local_api_server.cpp play branch), so a launch that carries a
+ * pin is sent as an explicit PlayGame op through /api/ops instead. A launch
+ * without any pin stays on /api/play, byte-for-byte the v1 call.
+ *
+ * Result: the engine adds `determinism {seed?, fixed_fps?, time_scale?, args,
+ * applied, reason?, conflicting_flag?, conflicting_source?, hint?, note?,
+ * seed_scope?}` ONLY when a pin was requested. An engine that predates the
+ * params ignores them and answers the v1 result — no `determinism` key — which
+ * is the one case the toolkit must call out itself: the run is NOT pinned.
+ */
+export interface PlayDeterminism {
+    seed?: number;
+    fixed_fps?: number;
+    time_scale?: number;
+}
+/** Keep only the pins that were actually given (undefined never travels). */
+export declare function pickPlayDeterminism(input: PlayDeterminism | undefined): PlayDeterminism | undefined;
+/** Pull the `determinism` object off a play result — the envelope's first
+ *  PlayGame result, or the top level (legacy /api/play shapes). */
+export declare function readPlayDeterminism(result: unknown): Record<string, unknown> | null;
+export declare const PLAY_DETERMINISM_NOT_SUPPORTED = "not applied (engine predates determinism params): seed/fixed_fps/time_scale were sent but this Summer Engine build ignored them, so this run is NOT pinned \u2014 do not treat it as reproducible. Update Summer Engine (restart it after updating).";
+/**
+ * Human/model-facing summary of what the pin did. Null when no pin was
+ * requested (nothing to say). Reads applied / reason / hint / conflicting_flag
+ * / note / seed_scope off the engine's determinism object; when the engine
+ * returned none, says so honestly.
+ */
+export declare function describePlayDeterminism(result: unknown, requested: PlayDeterminism | undefined): string | null;

package/dist/core/capabilities/play-determinism.js

@@ -0,0 +1,86 @@
+/**
+ * PlayGame determinism params (engine contract "PlayGame determinism params
+ * (additive)"): seed / fixed_fps / time_scale ride onto ONE launch's child
+ * command line (--summer-seed, --fixed-fps, --time-scale). Shared by the MCP
+ * summer_play tool and the CLI dispatcher.
+ *
+ * Transport note: the engine's /api/play rung copies only `scene` into the
+ * PlayGame op (local_api_server.cpp play branch), so a launch that carries a
+ * pin is sent as an explicit PlayGame op through /api/ops instead. A launch
+ * without any pin stays on /api/play, byte-for-byte the v1 call.
+ *
+ * Result: the engine adds `determinism {seed?, fixed_fps?, time_scale?, args,
+ * applied, reason?, conflicting_flag?, conflicting_source?, hint?, note?,
+ * seed_scope?}` ONLY when a pin was requested. An engine that predates the
+ * params ignores them and answers the v1 result — no `determinism` key — which
+ * is the one case the toolkit must call out itself: the run is NOT pinned.
+ */
+/** Keep only the pins that were actually given (undefined never travels). */
+export function pickPlayDeterminism(input) {
+    if (!input)
+        return undefined;
+    const out = {};
+    if (input.seed !== undefined)
+        out.seed = input.seed;
+    if (input.fixed_fps !== undefined)
+        out.fixed_fps = input.fixed_fps;
+    if (input.time_scale !== undefined)
+        out.time_scale = input.time_scale;
+    return Object.keys(out).length ? out : undefined;
+}
+/** Pull the `determinism` object off a play result — the envelope's first
+ *  PlayGame result, or the top level (legacy /api/play shapes). */
+export function readPlayDeterminism(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const envelope = result;
+    const candidates = [envelope];
+    if (Array.isArray(envelope.results))
+        candidates.push(...envelope.results);
+    for (const candidate of candidates) {
+        if (!candidate || typeof candidate !== "object")
+            continue;
+        const det = candidate.determinism;
+        if (det && typeof det === "object" && !Array.isArray(det))
+            return det;
+    }
+    return null;
+}
+export const PLAY_DETERMINISM_NOT_SUPPORTED = "not applied (engine predates determinism params): seed/fixed_fps/time_scale were sent but this Summer Engine build ignored them, so this run is NOT pinned — do not treat it as reproducible. Update Summer Engine (restart it after updating).";
+/**
+ * Human/model-facing summary of what the pin did. Null when no pin was
+ * requested (nothing to say). Reads applied / reason / hint / conflicting_flag
+ * / note / seed_scope off the engine's determinism object; when the engine
+ * returned none, says so honestly.
+ */
+export function describePlayDeterminism(result, requested) {
+    const pins = pickPlayDeterminism(requested);
+    if (!pins)
+        return null;
+    const asked = Object.entries(pins)
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(", ");
+    const det = readPlayDeterminism(result);
+    if (!det)
+        return `Determinism (${asked}): ${PLAY_DETERMINISM_NOT_SUPPORTED}`;
+    const lines = [];
+    const args = Array.isArray(det.args) ? det.args.filter((a) => typeof a === "string") : [];
+    if (det.applied === true) {
+        lines.push(`Determinism (${asked}): applied — flags on the child command line${args.length ? `: ${args.join(" ")}` : ""}.`);
+    }
+    else {
+        const reason = typeof det.reason === "string" ? det.reason : "unknown";
+        let why = `Determinism (${asked}): NOT applied — reason: ${reason}.`;
+        if (typeof det.conflicting_flag === "string") {
+            why += ` A user-configured run argument (${det.conflicting_flag}${typeof det.conflicting_source === "string" ? ` in ${det.conflicting_source}` : ""}) is appended after the op's flags and wins.`;
+        }
+        if (typeof det.hint === "string" && det.hint)
+            why += ` ${det.hint}`;
+        lines.push(why);
+    }
+    if (typeof det.note === "string" && det.note)
+        lines.push(`Note: ${det.note}`);
+    if (typeof det.seed_scope === "string" && det.seed_scope)
+        lines.push(`seed_scope: ${det.seed_scope}`);
+    return lines.join("\n");
+}

package/dist/core/capabilities/project-context.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 { type ProjectMemorySummary } from "../../project-memory/project-memory.js";
+import { type JsonRecord } 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 declare const DEFAULT_PROJECT_CONTEXT_SETTINGS_PREFIXES: readonly string[];
+/**
+ * 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 declare const DEFAULT_PROJECT_CONTEXT_SETTINGS_EXCLUDED: readonly string[];
+export declare const MAX_SETTINGS_PREFIXES = 32;
+export declare const projectContextInputShape: {
+    settingsPrefix: z.ZodOptional<z.ZodString>;
+    settingsPrefixes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+};
+export declare const projectContextInputSchema: z.ZodObject<{
+    settingsPrefix: z.ZodOptional<z.ZodString>;
+    settingsPrefixes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    settingsPrefix?: string | undefined;
+    settingsPrefixes?: string[] | undefined;
+}, {
+    settingsPrefix?: string | undefined;
+    settingsPrefixes?: string[] | undefined;
+}>;
+export type ProjectContextArgs = z.infer<typeof projectContextInputSchema>;
+/** The engine reads the builder needs — a structural subset of EngineApiClient
+ *  so tests and the headless router can hand in a stand-in. */
+export interface ProjectContextClient {
+    health(): Promise<unknown>;
+    getProjectState(prefix?: string): Promise<unknown>;
+    getSceneState(): Promise<unknown>;
+    rebind(): Promise<string | undefined>;
+}
+export interface ProjectContextExtras {
+    /** MCP-only: the boot drift notice the server probes at startup. The CLI
+     *  face has no such probe and passes nothing; the key is still emitted (null). */
+    summerUpdateNotice?: string | null;
+    /** Called with the skew warning when the engine advert and this toolkit
+     *  disagree — the MCP face logs it once per process. */
+    onCapabilitySkew?: (warning: string) => void;
+}
+export interface ProjectContextPayload extends JsonRecord {
+    health: unknown;
+    capabilitySkewWarning?: string;
+    project: unknown;
+    scene: unknown;
+    projectName: string | null;
+    projectPath: string | null;
+    currentScene: string | null;
+    mainScene: string | null;
+    boundProjectIdHash: string | undefined;
+    rebindError?: string;
+    projectMemory: ProjectMemorySummary;
+    summerUpdateNotice: string | null;
+    /** Present (true) only while SUMMER_TRAJECTORY_DIR + SUMMER_TRAJECTORY_EVAL=1
+     *  make every tool call also land unredacted in trajectory.full.jsonl. */
+    trajectory_eval_mode?: true;
+    guidance: string;
+    fileEditingGuidance: string;
+}
+export interface SettingsSelection {
+    prefixes: readonly string[];
+    excluded: readonly string[];
+    /** True when the caller named the prefixes (no default trim applies). */
+    explicit: boolean;
+    /** The single settingsPrefix argument as given (echoed in the payload). */
+    settingsPrefix?: string;
+}
+/** 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 declare function resolveSettingsSelection(args: ProjectContextArgs): SettingsSelection;
+/**
+ * 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 declare function trimProjectSettings(projectState: unknown, selection: SettingsSelection): unknown;
+/** The value of the first matching ProjectSettings key, or null. */
+export declare function projectSettingValue(projectState: unknown, keys: string[]): string | null;
+export declare function resolveProjectPath(projectState: unknown, health: unknown): string | null;
+export declare function resolveProjectName(projectState: unknown, health: unknown): string | null;
+export declare function resolveMainScene(projectState: unknown): string | null;
+export declare function resolveCurrentScene(projectState: unknown, sceneState: unknown, health: unknown): string | null;
+export declare function buildProjectContext(client: ProjectContextClient, args?: ProjectContextArgs, extras?: ProjectContextExtras): Promise<ProjectContextPayload>;