summer-engine 2.8.2 → 3.0.0

package/dist/mcp/tools/debug-tools.js

@@ -1,7 +1,10 @@
 import { z } from "zod";
-import { withEngine } from "./with-engine.js";
-import { shapeEngineLogResponse } from "../../lib/log-filters.js";
-import { createDebugReportArtifact } from "../../lib/debug-report.js";
+import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
+import { shapeEngineLogResponse } from "../../core/log-filters.js";
+import { createDebugReportArtifact } from "../../core/capabilities/debug-report.js";
+import { withConsoleScope } from "../../core/capabilities/console-read.js";
+import { describePlayDeterminism, pickPlayDeterminism } from "../../core/capabilities/play-determinism.js";
+import { RUNTIME_FALLBACKS, buildStopGameOp, playGame, playGameExtensionSchema, withRuntimeFailureHints, } from "../../core/capabilities/runtime-control.js";
 // summer_get_diagnostics view shaping. The engine serves /api/state/diagnostics
 // from a pre-published snapshot (empty args — query params are NOT forwarded on
 // that route), so trimming has to happen here. The snapshot defaults bury
@@ -91,15 +94,15 @@ export function prioritizeDiagnostics(payload) {
     };
 }
 export function registerDebugTools(server) {
-    server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message.
+    server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from the editor console, the runtime debugger, and script errors together. Returns error counts and a guidance message.
 
-ALWAYS call this FIRST before diving into summer_get_console or summer_get_debugger_errors. It tells you where to look.
+ALWAYS call this FIRST before diving into summer_get_console or summer_get_debugger_errors. It tells you where to look. It is also THE post-play read: a played game's runtime errors land in the debugger section here (and in summer_get_debugger_errors), never in the editor console — summer_get_console alone can honestly report errors 0 right after a play session that produced several.
 
 By default the response is a prioritized view: errors first, then warnings, then a small capped tail of recent info/std noise. Counts (console totals, debugger totals) are always complete — only low-severity message bodies are trimmed, and a "_view" block reports exactly what was suppressed. Pass includeAll: true for the full untrimmed engine payload.
 
-Typical workflow after making changes:
-1. summer_get_diagnostics — are there issues?
-2. If errors: summer_get_console or summer_get_debugger_errors for details
+Typical workflow after making changes or playing:
+1. summer_get_diagnostics — are there issues? (after a play session: check debugger.errors)
+2. If errors: summer_get_debugger_errors (runtime, with stacks) or summer_get_console (editor output) for details
 3. Fix the issues
 4. summer_get_diagnostics again to verify`, {
         includeAll: z
@@ -111,11 +114,13 @@ Typical workflow after making changes:
         const raw = await client.getDiagnostics();
         return includeAll ? raw : prioritizeDiagnostics(raw);
     }));
-    server.tool("summer_get_console", `Read recent messages from the editor's Output panel.
+    server.tool("summer_get_console", `Read recent messages from the editor's Output panel (print() output, editor-side warnings and errors).
 
-Output is post-processed for token economy: consecutive identical messages collapse into one entry with a "(×N)" count suffix, and the response carries a "_filter" summary so you can see what was hidden. Use errors_only=true (default) to drop info/std noise; use raw=true to bypass all shaping.
+SCOPE: the editor console ONLY. Runtime errors from a played game are collected by the debugger, not the console — right after summer_play this tool can honestly report errors 0 while summer_get_debugger_errors holds several. Never treat this tool alone as the post-play verdict: read summer_get_diagnostics (console + debugger + script errors together) first, then come here for message bodies. Every result carries a "_scope" note restating this.
 
-Use after summer_get_diagnostics indicates console issues.`, {
+Output is post-processed for token economy: consecutive identical messages collapse into one entry with a "(×N)" count suffix, and the response carries a "_filter" summary so you can see what was hidden. Message types come straight from the editor log (error / warning / std / editor); errors_only=true (default) drops the std/editor lines — startup banners and print() output — and keeps errors and warnings. Use errors_only=false to read print() output, raw=true to bypass all shaping.
+
+Use after summer_get_diagnostics indicates console issues, or to check what your print() statements said.`, {
         max_lines: z.number().optional().default(100).describe("Max lines to return after dedupe (default 100)"),
         filter: z.string().optional().describe("Only return lines containing this string"),
         type: z.enum(["error", "warning", "std", "editor"]).optional().describe("Filter by message type at the engine level"),
@@ -136,7 +141,9 @@ Use after summer_get_diagnostics indicates console issues.`, {
             errorsOnlyStrict: strict_errors,
             maxEntries: max_lines,
         });
-        return result;
+        // E2E 2026-09-03 F-07: the console is not where a played game's runtime
+        // errors go. Say so on every shaped result, not only in the description.
+        return withConsoleScope(result);
     }));
     server.tool("summer_clear_console", "Clear the editor's Output panel. Useful before running the game to get a clean slate for error checking.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "ClearConsoleOutput" }])));
     server.tool("summer_get_debugger_errors", `Read runtime errors from the debugger. These occur while the game is running (null references, missing nodes, physics errors). Different from console output — these come from the debugger, not print statements.
@@ -185,14 +192,50 @@ Use this when summer_get_diagnostics shows a non-zero \`debugger.warnings\` coun
         const { result } = shapeEngineLogResponse(engineResult, { maxEntries: max_warnings });
         return result;
     }));
-    server.tool("summer_play", `Start running the game in the engine. The game runs inside Summer Engine's viewport.
+    server.tool("summer_play", `Start running the game in the engine. With no extra parameters the game runs inside Summer Engine's viewport (the 'main' instance) QUIETLY — see below.
+
+QUIET BY DEFAULT (focus:false, PlayGame agent:true): the user is usually working on the same machine while you build, so a play must not take over their screen. Quiet play makes the EDITOR stay put: it does not switch the main screen to the Game tab, does not grab keyboard focus for the embedded game, ignores the game's later focus report, and skips the render-health self-check that would otherwise misread the untouched Game view as a GPU failure and flip the user's embed setting. Quiet play does NOT hide the game: it still runs embedded in the Game view (visible if the user already has that tab open), it is the running game for summer_is_running / summer_screenshot target:'game' / summer_get_diagnostics, and on engines without the background launch posture it does not change a user who has "Embed Game on Play" turned off — their game opens in its own OS window as always. Engines with the background posture (--summer-background, 0.5.66+) also launch the play child with that flag, so a separate-window game appears without activating or taking focus either. The result echoes agent_quiet:true when honoured; a launch result WITHOUT agent_quiet means the engine predates quiet play and most likely took focus — the tool adds posture_note saying so. focus:true launches like the toolbar Play button (Game tab + focus): use it ONLY when the user is watching and asked to see the game come up.
 
-After starting, use summer_get_diagnostics to check for runtime errors.
+After starting, confirm boot with summer_is_running (boot time varies — never sleep a guessed delay), then summer_get_diagnostics for runtime errors. You can run a specific scene instead of the main scene — useful for testing individual levels or UI screens.
 
-You can run a specific scene instead of the main scene — useful for testing individual levels or UI screens.`, {
+DETERMINISTIC RUNS (newer engines): seed / fixed_fps / time_scale pin THIS launch only (nothing is persisted). seed pins the game's GLOBAL RNG (randi/randf/randi_range/randf_range/randfn, Array.shuffle/pick_random) — it does NOT pin RandomNumberGenerator instances, scripts that call randomize(), rand_from_seed, wall-clock reads, or thread/IO/audio timing. fixed_fps decouples scene time from the wall clock so frame-count-derived state lands on the same frame run to run. The result's \`determinism\` block says whether the pins were applied (applied:false carries a reason: already_running, editor_run_args_override, launch_not_started) and restates seed_scope. If the result has NO determinism block although you sent a pin, the engine predates the params and the run is NOT reproducible — the tool says so; do not claim otherwise. Omitting every pin and instance parameter is exactly the v1 launch.
+
+PLAYTEST LAUNCH (engine runtime-control build): instance + mode:'offscreen' spawn a disposable hidden instance (at most 3) that summer_game_probe / summer_game_input / summer_game_control / summer_runtime_* address by name — run two variants side by side for an A/B. deterministic:true (offscreen only) launches with --fixed-fps 60 --summer-seed --audio-driver Dummy and is what lets summer_game_input action:'replay' accept a seed; speed sets the user time scale on session start. The instance result reports session_attached; poll summer_game_control action:'instances' until attached:true before addressing it. Then: probe -> act -> step/probe -> assert (the agent-playtesting skill). Failure reasons: too_many_instances, instance_exists, session_timeout (child never attached — check summer_get_console), unsupported_mode, main_scene_not_configured. A game already running answers playing:true with determinism.applied:false — summer_stop first to apply seed/fixed_fps.`, {
         scene: z.string().optional().describe("Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'"),
-    }, async ({ scene }) => withEngine(async (client) => client.play(scene)));
-    server.tool("summer_stop", "Stop the running game. Use after runtime verification or when you intentionally need to restart the running instance; ordinary editor scene mutations do not require a blanket stop.", {}, async () => withEngine(async (client) => client.stop()));
+        ...playGameExtensionSchema,
+    }, async (args) => {
+        const requested = pickPlayDeterminism({ seed: args.seed, fixed_fps: args.fixed_fps, time_scale: args.time_scale });
+        return withEngine(
+        // ONE implementation with the CLI face (runtime-control.ts playGame):
+        // route choice, validation, runtime-control pre-flight, old-engine / instance /
+        // posture annotations. A ToolInputError propagates to withEngine.
+        async (client) => playGame(client, args), {
+            toContent: (result) => {
+                const json = JSON.stringify(result, null, 2);
+                // Surface applied / reason / seed_scope in prose so the model does not
+                // have to dig; and call out the old-engine case (pins sent, no
+                // determinism block back) as "not applied" instead of staying silent.
+                const summary = describePlayDeterminism(result, requested);
+                return [{ type: "text", text: summary ? `${json}\n\n${summary}` : json }];
+            },
+        });
+    });
+    server.tool("summer_stop", "Stop the running game. Use after runtime verification or when you intentionally need to restart the running instance; ordinary editor scene mutations do not require a blanket stop. Pass instance to stop ONE offscreen instance started with summer_play {instance, mode:'offscreen'} (the result reports was_playing and killed); omit it for the editor's main game.", {
+        instance: z
+            .string()
+            .optional()
+            .describe("Offscreen instance name to stop (from summer_play {instance}); omit for the main embedded game."),
+    }, async ({ instance }) => withEngine(async (client) => {
+        if (typeof instance !== "string" || instance.trim().length === 0 || instance.trim() === "main") {
+            return client.stop();
+        }
+        const missing = missingEngineOpResult(client, "ListGameInstances", RUNTIME_FALLBACKS.ListGameInstances);
+        if (missing)
+            return missing;
+        const { op, timeoutMs } = buildStopGameOp(instance);
+        const result = await client.executeOps([op], undefined, timeoutMs);
+        return withRuntimeFailureHints(withOldEngineHint(result, "StopGame", RUNTIME_FALLBACKS.ListGameInstances));
+    }));
     server.tool("summer_is_running", "Check if the game is currently running. Returns the active scene path if running.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "IsGameRunning" }])));
     server.tool("summer_get_script_errors", `Check a GDScript file for parse/compile errors without running the game.
 
@@ -202,7 +245,7 @@ Use after writing or editing a .gd file to verify it compiles. Returns line numb
     server.tool("summer_create_debug_report", `Create a support-ready Markdown report for /summer debug.
 
 Use this when the user says "/summer debug", asks to send Summer a bug report,
-or needs a portable artifact from a failing Codex/cloud/agent session. The
+or needs a portable artifact from a failing Codex, cloud or agent session. The
 report includes Summer doctor checks, engine health, diagnostics, console
 output, debugger errors/warnings, and an agent handoff prompt. It omits auth
 tokens and project file contents, but the user should still review it before

package/dist/mcp/tools/event-tools.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Events channel tools. The engine pushes moments (op terminal, save, play,
+ * script error) on GET /api/events; these tools consume the long-poll fallback
+ * so an agent can WAIT for a moment instead of sleeping and re-polling state.
+ * Implementation lives in core/capabilities/events.ts (shared with the CLI
+ * dispatcher and `summer events`); this file is the MCP face only.
+ *
+ * Whether the build has the channel is decided BEFORE anything is sent:
+ * missingEngineEventsResult returns a structured engine_lacks_events result
+ * when /api/health lacks capabilities.events (a capability, not an op — so it
+ * is not part of the op pre-flight or CLI_KNOWN_OP_NEEDS).
+ */
+export declare function registerEventTools(server: McpServer): void;

package/dist/mcp/tools/event-tools.js

@@ -0,0 +1,41 @@
+import { withEngine } from "./with-engine.js";
+import { missingEngineEventsResult } from "../../core/capability-skew.js";
+import { EVENT_KINDS_V1, recentEvents, recentEventsArgsSchema, waitForEvent, waitForEventArgsSchema, } from "../../core/capabilities/events.js";
+/**
+ * Events channel tools. The engine pushes moments (op terminal, save, play,
+ * script error) on GET /api/events; these tools consume the long-poll fallback
+ * so an agent can WAIT for a moment instead of sleeping and re-polling state.
+ * Implementation lives in core/capabilities/events.ts (shared with the CLI
+ * dispatcher and `summer events`); this file is the MCP face only.
+ *
+ * Whether the build has the channel is decided BEFORE anything is sent:
+ * missingEngineEventsResult returns a structured engine_lacks_events result
+ * when /api/health lacks capabilities.events (a capability, not an op — so it
+ * is not part of the op pre-flight or CLI_KNOWN_OP_NEEDS).
+ */
+export function registerEventTools(server) {
+    server.tool("summer_wait_for_event", `Block until the engine emits a matching EVENT, or a bounded timeout elapses — the replacement for sleeping and re-polling. Use it right after summer_play to wait for play.started (the game actually booting), after a long op (import, script, save) to wait for op.applied / op.failed by requestId instead of guessing a delay, and during a playtest to catch script.error the moment it fires.
+
+Event kinds (v1): ${EVENT_KINDS_V1.join(", ")}. Each event is {seq, kind, ts, data}; seq is a monotonic cursor.
+
+CURSOR DISCIPLINE: events are delivered live from \`since\` (omitted = from now). An event that fired BEFORE this call is NOT delivered, so when the moment may come fast, take a cursor first: summer_recent_events returns next_seq — pass it as since BEFORE triggering the action (summer_recent_events -> summer_play -> summer_wait_for_event since:<next_seq> kinds:['play.started']). Every result carries next_seq: pass it as since on the next call to keep waiting with no gap.
+
+match.requestId narrows op.applied / op.failed to one request (other kinds pass through). The call long-polls the engine in slices of at most 25 s until a match or timeout_seconds (default 30, max 120) elapses.
+
+Returns {ok, matched, events, next_seq, since, timed_out, waited_ms, polls}. timed_out:true means NO matching event arrived — it is not evidence the thing did not happen (verify with summer_is_running / summer_get_diagnostics) and you must never claim an event you did not receive. A \`gap\` field means events between since and the oldest retained were evicted — re-read state instead of trusting the stream. On an engine build without the events channel (no capabilities.events in /api/health) the result is a structured engine_lacks_events failure and nothing is sent: fall back to polling the state.`, waitForEventArgsSchema.shape, async (args) => withEngine(async (client) => {
+        const missing = missingEngineEventsResult(client);
+        if (missing)
+            return missing;
+        return waitForEvent(client, args);
+    }));
+    server.tool("summer_recent_events", `Read the newest engine events in ONE zero-wait poll — what just happened (saves, plays, op receipts, script errors, imports, selection) and, above all, the CURSOR: its next_seq is the \`since\` to hand summer_wait_for_event BEFORE you trigger the action you will wait on.
+
+since omitted = the newest \`limit\` sequence numbers (a kinds filter applies inside that window, so fewer may come back). since:0 = the whole retained ring from the oldest, paged — pass next_seq back as since while truncated is true. since:N = everything after N.
+
+Each event is {seq, kind, ts, data}; kinds (v1): ${EVENT_KINDS_V1.join(", ")}. The engine retains 512 events / 10 minutes — older history is gone, so an empty result is not proof nothing happened earlier. Payloads over 4 KB arrive clamped with truncated:true inside data. On an engine build without the events channel the result is a structured engine_lacks_events failure (nothing sent).`, recentEventsArgsSchema.shape, async (args) => withEngine(async (client) => {
+        const missing = missingEngineEventsResult(client);
+        if (missing)
+            return missing;
+        return recentEvents(client, args);
+    }));
+}

package/dist/mcp/tools/fabricate-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFabricateTools(server: McpServer): void;

package/dist/mcp/tools/fabricate-tools.js

@@ -0,0 +1,28 @@
+import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
+import { FABRICATE_FALLBACK, buildFabricateMeshOp, fabricateArgsSchema, } from "../../core/capabilities/fabricate-mesh.js";
+export function registerFabricateTools(server) {
+    server.tool("summer_fabricate_3d", `Fabricate a 3D mesh asset by running a Blender Python (bpy) script in the USER'S OWN installed Blender — headless, supervised by the engine — then import the exported .glb into the project and optionally instantiate it into the open scene. Blender is a dependency the user installs; Summer never bundles, downloads, or brands it.
+
+WHEN — the three asset classes neither generation nor the free library serve well:
+- modular kits with exact dimensions and snapping (walls, pipes, fences, rails: array + boolean + bevel, one shared material) — generation cannot hold size and style across 30 pieces;
+- VFX meshes (shatter pieces, curve sweeps, trails, LOD chains) — one-liners in bpy, absent in the engine;
+- post-processing a generated model (decimate -> UV unwrap -> bake) before it goes into the scene.
+WHEN NOT: a generic prop (barrel, crate, chair) -> summer_search_assets / summer_import_asset first, then summer_generate_3d; a character or any organic shape -> summer_generate_3d (scripted organic modelling is the documented failure mode); a blockout or placeholder -> summer_run_script primitives/CSG, instant and in-scene. Route with the asset-strategy skill; the fabricating-assets skill carries the bpy rules and recipes.
+
+SCRIPT CONTRACT: 'source' is plain bpy code. Pre-bound names: bpy, bmesh, mathutils, math, Vector, Matrix, Euler. The script must CREATE mesh objects and leave them linked in the scene — do NOT export and do NOT quit (the engine's bootstrap exports for you: modifiers applied at export, Geometry Nodes realized, +Y-up conversion, materials carried as Principled BSDF only, a procedural Base Color baked to a 2K texture; procedural Metallic/Roughness/Normal/Emission are NOT baked and come back in 'warnings'). Objects hidden or render-disabled are treated as helpers (boolean cutters, guides) and are not exported — they are listed in 'skipped'. Model in metres. MESH/CURVE/SURFACE/META/FONT export as meshes, EMPTY/ARMATURE keep hierarchy, cameras and lights are dropped. Name your objects — they become node names.
+
+REQUIRES BLENDER on the user's machine (4.2 LTS or newer). Resolution order: 'blender_path' -> SUMMER_BLENDER_BIN in the editor's environment -> Editor Settings filesystem/import/blender/blender_path (shared with .blend import) -> PATH, well-known install dirs, ~/.summer/tools/blender-*. Not found -> failure_reason blender_not_found with the exact fix and every path that was checked; relay it to the user as a one-line decision, never guess a path and never install anything on their behalf.
+
+ONE fabrication runs at a time per editor (failure_reason busy — wait for the result, never fire two in parallel). Budget max_seconds 15-600 (default 120) covers Blender boot + script + bakes + export; the client waits max_seconds + 60 s. Blind until import: there is no viewport feedback while the script runs, so keep scripts deterministic (fixed seeds) and verify afterwards.
+
+Returns {ok, ran, blender_version, blender_path, out_path, objects[{name,type,vertices,faces,triangles,materials,modifiers}], object_count, dimensions{x,y,z} (+Y up, source scale), warnings[], baked[], skipped[], output[], errors[], exit_code, duration_ms, checkpoint} plus imported_node_path / scale_applied / instance_dimensions with import_to_scene, and no_rewind_point:true when no checkpoint exists. Failures carry failure_reason: blender_not_found | blender_launch_failed | script_error (traceback_tail + script_line — fix the bpy against the reported blender_version and re-run; bpy APIs change across majors) | timeout (raise max_seconds or split the job) | export_empty (no exportable object — check hide/render flags and collection links) | export_failed | export_missing | import_failed / instantiate_failed (the .glb IS at out_path — summer_instantiate_scene it yourself; the importer's message is in summer_get_console) | busy | cancelled.
+
+THE LOOP: summer_world_snapshot BEFORE (keep snapshot_id) -> summer_fabricate_3d with import_to_scene (+ target_size for real-world scale) -> read dimensions/warnings/skipped -> summer_snapshot_diff + summer_screenshot -> iterate. Never claim a visual result without the screenshot. If this engine build predates FabricateMesh, the result is a structured engine_lacks_op failure (nothing is sent): use summer_generate_3d / summer_search_assets, or update Summer Engine.`, fabricateArgsSchema.shape, async (args) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "FabricateMesh", FABRICATE_FALLBACK);
+        if (missing)
+            return missing;
+        const { op, timeoutMs } = buildFabricateMeshOp(args);
+        const result = await client.executeIdentityBoundOps([op], undefined, timeoutMs);
+        return withOldEngineHint(result, "FabricateMesh", FABRICATE_FALLBACK);
+    }));
+}

package/dist/mcp/tools/feedback-tools.d.ts

@@ -0,0 +1,77 @@
+/**
+ * summer_library_feedback — the library outcome mailbox (CONTRACT.md §10).
+ *
+ * MCP adapter only: schema + disclosure description here, behavior in
+ * src/core/feedback/client.ts. Fire-and-forget, 1s cap, never throws.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export declare const ENTRY_ID_PATTERN: RegExp;
+export declare const OUTCOMES: readonly ["worked", "worked_with_fixes", "wrong", "outdated", "incomplete", "did_not_apply", "misrouted"];
+export declare const feedbackInputShape: {
+    reports: z.ZodArray<z.ZodObject<{
+        entry_id: z.ZodString;
+        outcome: z.ZodEnum<["worked", "worked_with_fixes", "wrong", "outdated", "incomplete", "did_not_apply", "misrouted"]>;
+        note: z.ZodOptional<z.ZodString>;
+        deviation: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entry_id: string;
+        outcome: "worked" | "worked_with_fixes" | "wrong" | "outdated" | "incomplete" | "did_not_apply" | "misrouted";
+        note?: string | undefined;
+        deviation?: string | undefined;
+    }, {
+        entry_id: string;
+        outcome: "worked" | "worked_with_fixes" | "wrong" | "outdated" | "incomplete" | "did_not_apply" | "misrouted";
+        note?: string | undefined;
+        deviation?: string | undefined;
+    }>, "many">;
+    engine_version: z.ZodString;
+    agent_model: z.ZodString;
+};
+export declare const feedbackInputSchema: z.ZodObject<{
+    reports: z.ZodArray<z.ZodObject<{
+        entry_id: z.ZodString;
+        outcome: z.ZodEnum<["worked", "worked_with_fixes", "wrong", "outdated", "incomplete", "did_not_apply", "misrouted"]>;
+        note: z.ZodOptional<z.ZodString>;
+        deviation: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entry_id: string;
+        outcome: "worked" | "worked_with_fixes" | "wrong" | "outdated" | "incomplete" | "did_not_apply" | "misrouted";
+        note?: string | undefined;
+        deviation?: string | undefined;
+    }, {
+        entry_id: string;
+        outcome: "worked" | "worked_with_fixes" | "wrong" | "outdated" | "incomplete" | "did_not_apply" | "misrouted";
+        note?: string | undefined;
+        deviation?: string | undefined;
+    }>, "many">;
+    engine_version: z.ZodString;
+    agent_model: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    engine_version: string;
+    reports: {
+        entry_id: string;
+        outcome: "worked" | "worked_with_fixes" | "wrong" | "outdated" | "incomplete" | "did_not_apply" | "misrouted";
+        note?: string | undefined;
+        deviation?: string | undefined;
+    }[];
+    agent_model: string;
+}, {
+    engine_version: string;
+    reports: {
+        entry_id: string;
+        outcome: "worked" | "worked_with_fixes" | "wrong" | "outdated" | "incomplete" | "did_not_apply" | "misrouted";
+        note?: string | undefined;
+        deviation?: string | undefined;
+    }[];
+    agent_model: string;
+}>;
+export declare const FEEDBACK_TOOL_DESCRIPTION: string;
+/**
+ * Host app identity from the MCP initialize handshake ("name version", e.g.
+ * "claude-code 2.1.0") — never self-reported by the agent. Returns undefined
+ * when the SDK has no clientInfo (not yet initialized, or an exotic client).
+ * Never throws: feedback must not fail because introspection did.
+ */
+export declare function captureClientInfo(server: McpServer): string | undefined;
+export declare function registerFeedbackTools(server: McpServer): void;

package/dist/mcp/tools/feedback-tools.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { FEEDBACK_FIELDS_SENT, sendLibraryFeedback, } from "../../core/feedback/client.js";
+import { textJson } from "./text-json.js";
+export const ENTRY_ID_PATTERN = /^(tool|skill|example|template|collection|reference)\/[a-z0-9-]+(@[a-f0-9]{8,64})?$/;
+export const OUTCOMES = [
+    "worked",
+    "worked_with_fixes",
+    "wrong",
+    "outdated",
+    "incomplete",
+    "did_not_apply",
+    "misrouted",
+];
+const reportSchema = z.object({
+    entry_id: z
+        .string()
+        .regex(ENTRY_ID_PATTERN, "entry_id must be <kind>/<slug> with optional @<content-hash>, e.g. skill/grappling-hook@1a2b3c4d")
+        .describe("The library entry ID exactly as the loader printed it (kind/slug, optionally @content-hash). Never guess or reconstruct it."),
+    outcome: z
+        .enum(OUTCOMES)
+        .describe("worked = verified in-engine (playtest/screenshot passed). worked_with_fixes = worked after your changes (say what in deviation). wrong = incorrect content. outdated = no longer matches this engine version. incomplete = missing a needed case. did_not_apply = loaded but irrelevant to the task. misrouted = the description/metadata led you here wrongly."),
+    note: z
+        .string()
+        .max(280)
+        .optional()
+        .describe("Optional, max 280 chars. About the ENTRY only — never the user's project, files, or code."),
+    deviation: z
+        .string()
+        .max(280)
+        .optional()
+        .describe("Optional, max 280 chars. What you did instead of / on top of the entry's instructions."),
+});
+export const feedbackInputShape = {
+    reports: z
+        .array(reportSchema)
+        .min(1)
+        .max(10)
+        .describe("1-10 outcome reports, batched at a natural checkpoint (one call, not one per entry)."),
+    engine_version: z
+        .string()
+        .min(1)
+        .max(32)
+        .describe('The Summer Engine version in use, e.g. "4.6.1".'),
+    agent_model: z
+        .string()
+        .min(1)
+        .max(64)
+        .describe('The model you are, e.g. claude-fable-5, gpt-5.5-codex; use "unknown" if unsure.'),
+};
+export const feedbackInputSchema = z.object(feedbackInputShape);
+export const FEEDBACK_TOOL_DESCRIPTION = "Report how library entries (skills, examples, templates, collections, references, tools) worked out, so " +
+    "Summer can fix and re-rank them — reports fix the entries this user's own future sessions load. " +
+    "Call once at a natural checkpoint with all entries used; fire-and-forget (1s cap, silent failure, never blocks). " +
+    "Only report outcome 'worked' after in-engine verification (playtest or screenshot passed). " +
+    `What is sent: ${FEEDBACK_FIELDS_SENT} The schema has no field for project files, chat content, or code. ` +
+    "The very first call on a machine sends nothing and returns {recorded:false, first_run:true, notice} — " +
+    "call again to send. Otherwise recorded:true means the gateway accepted the batch; {recorded:false, " +
+    "dropped:true, status, reason} means the 1s POST failed and the batch is gone (no retry) — reason is " +
+    "endpoint_missing (404), rejected (other 4xx), server_error (5xx) or network. The user can opt out entirely " +
+    "with SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1 — then nothing is sent and this tool returns " +
+    "{recorded:false, disabled:true}.";
+/**
+ * Host app identity from the MCP initialize handshake ("name version", e.g.
+ * "claude-code 2.1.0") — never self-reported by the agent. Returns undefined
+ * when the SDK has no clientInfo (not yet initialized, or an exotic client).
+ * Never throws: feedback must not fail because introspection did.
+ */
+export function captureClientInfo(server) {
+    try {
+        const info = server.server?.getClientVersion?.();
+        if (!info || typeof info.name !== "string" || !info.name)
+            return undefined;
+        const version = typeof info.version === "string" ? info.version : "";
+        const identity = version ? `${info.name} ${version}` : info.name;
+        return identity.slice(0, 128);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function registerFeedbackTools(server) {
+    server.tool("summer_library_feedback", FEEDBACK_TOOL_DESCRIPTION, feedbackInputShape, async (args) => textJson(await sendLibraryFeedback({
+        reports: args.reports,
+        engine_version: args.engine_version,
+        agent_model: args.agent_model,
+        client: captureClientInfo(server),
+    })));
+}

package/dist/mcp/tools/file-tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { withEngine } from "./with-engine.js";
+import { withEngine, ToolInputError } from "./with-engine.js";
+import { occurrenceCount, readTextPayload, safeProjectPath, validSha256, } from "../../core/capabilities/engine-ops.js";
 // MCP clients may issue tool calls concurrently. Keep the complete read->write
 // transaction ordered for one project file while allowing unrelated files to
 // proceed in parallel. The tail is always released in `finally`, so a rejected
@@ -28,54 +29,6 @@ async function withFileMutationTurn(projectIdHash, path, fn) {
         }
     }
 }
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : null;
-}
-function safeProjectPath(path) {
-    const normalized = path.trim().replace(/\\/g, "/");
-    if (!normalized.startsWith("res://") || normalized.includes("..")) {
-        throw new Error("File path must be a traversal-free res:// project path.");
-    }
-    return normalized;
-}
-function validSha256(value) {
-    return typeof value === "string" && /^[0-9a-f]{64}$/i.test(value);
-}
-function readTextPayload(result) {
-    const root = asRecord(result);
-    const data = asRecord(root?.data);
-    if (root?.ok === false) {
-        throw new Error(String(root.error ?? "Engine could not read the file."));
-    }
-    if (data?.encoding === "binary" || typeof data?.content !== "string") {
-        throw new Error("Safe text mutation refused: the engine did not return text content.");
-    }
-    if (data.truncated === true) {
-        throw new Error("Safe text mutation refused: the file exceeds the 1 MB read limit.");
-    }
-    const sha256 = typeof data.sha256 === "string" ? data.sha256 : undefined;
-    if (!validSha256(sha256)) {
-        throw new Error("Safe text mutation refused: the engine did not return a full-file sha256 receipt.");
-    }
-    return {
-        content: data.content,
-        sha256,
-        size: typeof data.size === "number" ? data.size : undefined,
-    };
-}
-function occurrenceCount(content, needle) {
-    let count = 0;
-    let offset = 0;
-    while (true) {
-        const index = content.indexOf(needle, offset);
-        if (index < 0)
-            return count;
-        count++;
-        offset = index + needle.length;
-    }
-}
 export function registerFileTools(server) {
     server.tool("summer_read_file", `Read a text file from the engine-bound project and return its full-file sha256 receipt.
 
@@ -95,10 +48,10 @@ For a new file, set create_only:true. For an existing file, first call summer_re
         const guardedCreate = create_only === true;
         const guardedOverwrite = validSha256(expected_sha256);
         if (expected_sha256 !== undefined && !guardedOverwrite) {
-            throw new Error("Safe write refused: expected_sha256 must be a 64-character hexadecimal sha256 from summer_read_file. Nothing was written.");
+            throw new ToolInputError("Safe write refused: expected_sha256 must be a 64-character hexadecimal sha256 from summer_read_file. Nothing was written.");
         }
         if (guardedCreate === guardedOverwrite) {
-            throw new Error("Safe write requires exactly one guard: create_only:true for a new file, or a 64-character expected_sha256 from summer_read_file for an existing file. Nothing was written.");
+            throw new ToolInputError("Safe write requires exactly one guard: create_only:true for a new file, or a 64-character expected_sha256 from summer_read_file for an existing file. Nothing was written.");
         }
         const op = {
             op: "WriteFile",
@@ -124,10 +77,10 @@ The MCP server reads the complete file, requires a unique match by default, comp
             const current = readTextPayload(await client.readProjectFile(safePath, 1_000_000));
             const matches = occurrenceCount(current.content, old_text);
             if (matches === 0) {
-                throw new Error("Safe replace refused: old_text was not found. Nothing was written.");
+                throw new ToolInputError("Safe replace refused: old_text was not found. Nothing was written.");
             }
             if (!replace_all && matches !== 1) {
-                throw new Error(`Safe replace refused: old_text matched ${matches} times. Provide a unique span or set replace_all:true. Nothing was written.`);
+                throw new ToolInputError(`Safe replace refused: old_text matched ${matches} times. Provide a unique span or set replace_all:true. Nothing was written.`);
             }
             const content = replace_all
                 ? current.content.split(old_text).join(new_text)