summer-engine 3.8.0 → 4.2.0

package/dist/core/capabilities/tool-dispatch.js

@@ -20,6 +20,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
 import { EngineApiClient } from "../api-client.js";
+import { CLI_RECOVERY, codedFailure, codeForStatus, describeNetworkError, engineNotRunningFromConnectError, networkDetails, NOT_SIGNED_IN, } from "../error-codes.js";
 import { missingEngineEventsResult, missingEngineOpResult, } from "../capability-skew.js";
 import { buildAgentPlaybook } from "./agent-playbook.js";
 import { recentEvents, recentEventsArgsSchema, waitForEvent, waitForEventArgsSchema, } from "./events.js";
@@ -35,7 +36,8 @@ import { ImportHdriError, importHdriArgsSchema, importPolyHavenHdri } from "./hd
 import { FABRICATE_FALLBACK, buildFabricateMeshOp, fabricateArgsSchema } from "./fabricate-mesh.js";
 import { buildUiActionsOp, buildUiActivateOp, buildUiScreenshotOp, buildUiTreeOp, executeUiOp, uiActionsArgsSchema, uiActivateArgsSchema, uiScreenshotArgsSchema, uiScreenshotCaption, uiScreenshotImage, uiTreeArgsSchema, withUiFailureDetails, } from "./ui-control.js";
 import { PLAY_INSTANCE_FALLBACK, RUNTIME_FALLBACKS, buildGameControlOp, buildGameInputOp, buildGameProbeOp, buildRuntimeAnimateOp, buildRuntimeCallOp, buildRuntimeSetOp, buildRuntimeSpawnOp, buildStopGameOp, findProbePayload, gameControlArgsSchema, gameInputArgsSchema, gameProbeArgsSchema, playGame, probeFrameStamp, runtimeAnimateArgsSchema, runtimeCallArgsSchema, runtimeSetArgsSchema, runtimeSpawnArgsSchema, stripProbeImage, withRuntimeFailureHints, } from "./runtime-control.js";
-import { RUN_EDITOR_SCRIPT_FALLBACK, RUN_SCRIPT_FALLBACK, buildRunEditorScriptOp, buildRunSceneScriptOp, } from "./scene-script.js";
+import { RUN_EDITOR_SCRIPT_FALLBACK, RUN_SCRIPT_FALLBACK, buildRunEditorScriptOp, } from "./scene-script.js";
+import { runSceneScriptOn } from "./scene-script-target.js";
 import { CAMERA_BOOKMARK_ACTIONS, CAMERA_BOOKMARK_FALLBACK, SCREENSHOT_FRAMINGS, buildCameraBookmarkOp, buildScenePreviewInput, } from "./camera-view.js";
 import { PLAY_DETERMINISM_NOT_SUPPORTED, pickPlayDeterminism, readPlayDeterminism } from "./play-determinism.js";
 import { debugViews, frameNodes, frameShot, rememberBookmarkRender, shotSheet, slotPolicy, zoom, } from "./seeing/seeing.js";
@@ -75,15 +77,12 @@ import { PLACEMENT_FIELDS, SCENE_MUTATION_OPS, SCENE_QUERY_OPS, instantiateScene
 import { attachToSurface, attachToSurfaceArgsSchema, connectPorts, connectPortsArgsSchema, inspectAsset, inspectAssetArgsSchema, measure, measureArgsSchema, placeAdjacent, placeAdjacentArgsSchema, raycast, raycastArgsSchema, repeatAlong, repeatAlongArgsSchema, } from "./placement.js";
 import { readLibraryEntry, readLibraryInputSchema } from "../library-read.js";
 import { runSearchLibrary, searchLibraryInputSchema } from "../library-search.js";
-import { TOOLKIT_VERSION as CLI_VERSION } from "../version.js";
+import { runWithToolContext, summerRequestHeaders } from "../agent-host.js";
 import { APP_DOCK_FALLBACK, appCall, appCallArgsSchema, appCreate, appCreateArgsSchema, appData, appDataArgsSchema, appDockArgsSchema, appDockOp, appEvents, appEventsArgsSchema, appGet, appGetArgsSchema, appGuide, appGuideArgsSchema, appList, appListArgsSchema, appPage, appPageArgsSchema, appScreenshot, appScreenshotArgsSchema, appUpdate, appUpdateArgsSchema, appPublish, appPublishArgsSchema, appReportGap, appReportGapArgsSchema, appsGateway, appTools, appToolsArgsSchema, } from "./apps.js";
 import { enablePluginArgsSchema, enablePluginOp, interpretEnablePluginResult } from "./enable-plugin.js";
 /** Dispatch-level failure with a user-facing message (no stack needed). */
 export class ToolDispatchError extends Error {
 }
-/** The local engine is not reachable — a clean state, not a crash. */
-export class EngineUnavailableError extends ToolDispatchError {
-}
 /** A tool failed with a structured receipt that `summer tool` prints whole
  *  (JSON on stdout, exit 1) instead of flattening to `message`: every engine
  *  envelope extractOpError reads as a failure (the same gate the MCP face
@@ -98,6 +97,23 @@ export class ToolResultError extends ToolDispatchError {
         this.result = result;
     }
 }
+/** A shared failure (core/error-codes.ts) — not signed in, no credits,
+ *  network — printed as `{ok:false, code, error, recovery}` with the shell
+ *  wording of the next step. */
+export class CodedToolError extends ToolResultError {
+    constructor(code, message, extra = {}, recovery = CLI_RECOVERY[code]) {
+        super(codedFailure(code, message, extra, recovery), message);
+    }
+}
+/** The local engine is not reachable — a clean state, not a crash. Prints
+ *  `{ok:false, code:"engine_not_running", error, recovery, hint}`. */
+export class EngineUnavailableError extends CodedToolError {
+    constructor(message) {
+        super("engine_not_running", message, {
+            hint: "Engine-free tools (generate-*, asset search/list/get, library search/read, plan) work without it.",
+        });
+    }
+}
 export function createDefaultDispatchContext() {
     let cached = null;
     return {
@@ -110,10 +126,12 @@ export function createDefaultDispatchContext() {
             }
             catch (error) {
                 const reason = error instanceof Error ? error.message : String(error);
-                throw new EngineUnavailableError("Summer Engine is not running (or no project is open).\n" +
-                    `${reason}\n` +
-                    "Start it with 'summer run' or open the project in the Summer desktop app, then retry.\n" +
-                    "Engine-free tools (generate-*, asset search/list/get, creator, plan) work without it.");
+                // Several editors open (or another selection problem) already says
+                // how to pick one; only "nothing reachable" is engine_not_running.
+                const notRunning = engineNotRunningFromConnectError(reason);
+                if (!notRunning)
+                    throw new ToolDispatchError(reason);
+                throw new EngineUnavailableError(notRunning.message);
             }
         },
     };
@@ -265,17 +283,24 @@ async function dispatchUiOp(ctx, built) {
 // ---------------------------------------------------------------------------
 async function requireToken() {
     const token = await getAuthToken();
-    if (!token) {
-        throw new ToolDispatchError("Not signed in. Run 'summer login' first — these tools require a Summer Engine account.");
-    }
+    if (!token)
+        throw new CodedToolError("not_signed_in", NOT_SIGNED_IN);
     return token;
 }
+/** A non-OK Summer web reply: 401 and 402 carry the shared codes. */
+function gatewayFailure(status, data) {
+    const message = String(data.message || data.error || `Request failed (${status})`);
+    const code = codeForStatus(status);
+    if (code === "not_signed_in")
+        return new CodedToolError(code, message, { status }, "Run: summer login --force");
+    if (code)
+        return new CodedToolError(code, message, { status });
+    return new ToolDispatchError(message);
+}
 function gatewayHeaders(token, endpoint) {
     return {
+        ...summerRequestHeaders({ surface: "cli" }),
         Authorization: `Bearer ${token}`,
-        "X-Summer-Client": "summer-cli",
-        "X-Summer-Client-Version": CLI_VERSION,
-        "X-Summer-Client-Surface": "cli",
         "X-Summer-MCP-Endpoint": endpoint,
     };
 }
@@ -305,12 +330,11 @@ async function gatewayGet(endpoint, params, timeoutMs = 30_000) {
         });
     }
     catch (err) {
-        throw new ToolDispatchError(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
+        throw new CodedToolError("unavailable", `Request failed: ${describeNetworkError(err)}`, networkDetails(err));
     }
     const data = await readJsonBody(res);
-    if (!res.ok) {
-        throw new ToolDispatchError(String(data.message || data.error || `Request failed (${res.status})`));
-    }
+    if (!res.ok)
+        throw gatewayFailure(res.status, data);
     return data;
 }
 async function gatewayPost(endpoint, body, timeoutMs = 120_000) {
@@ -329,19 +353,11 @@ async function gatewayPost(endpoint, body, timeoutMs = 120_000) {
         });
     }
     catch (err) {
-        throw new ToolDispatchError(`Generation request failed: ${err instanceof Error ? err.message : String(err)}`);
+        throw new CodedToolError("unavailable", `Generation request failed: ${describeNetworkError(err)}`, networkDetails(err));
     }
     const data = await readJsonBody(res);
-    if (!res.ok) {
-        let message = String(data.message || data.error || `Request failed (${res.status})`);
-        if (res.status === 402) {
-            message = `${message} — insufficient credits; top up or upgrade on the Summer dashboard.`;
-        }
-        if (res.status === 401) {
-            message = `${message} — auth token expired; run 'summer login' again.`;
-        }
-        throw new ToolDispatchError(message);
-    }
+    if (!res.ok)
+        throw gatewayFailure(res.status, data);
     return data;
 }
 async function pollGenerationJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000) {
@@ -350,14 +366,19 @@ async function pollGenerationJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000)
     const deadline = Date.now() + maxWaitMs;
     let interval = intervalMs;
     while (Date.now() < deadline) {
-        const res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
-            headers: gatewayHeaders(token, "/api/mcp/jobs"),
-            signal: AbortSignal.timeout(15_000),
-        });
-        const data = await readJsonBody(res);
-        if (!res.ok) {
-            throw new ToolDispatchError(String(data.message || "Job poll failed"));
+        let res;
+        try {
+            res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
+                headers: gatewayHeaders(token, "/api/mcp/jobs"),
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        catch (err) {
+            throw new CodedToolError("unavailable", `Job poll failed: ${describeNetworkError(err)}`, { jobId, ...networkDetails(err) });
         }
+        const data = await readJsonBody(res);
+        if (!res.ok)
+            throw gatewayFailure(res.status, { message: "Job poll failed", ...data });
         if (data.status === "completed")
             return data;
         if (data.status === "failed") {
@@ -366,7 +387,15 @@ async function pollGenerationJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000)
         await new Promise((resolve) => setTimeout(resolve, interval));
         interval = Math.min(interval * 1.2, 15_000);
     }
-    throw new ToolDispatchError(`Timed out after ${maxWaitMs / 1000}s. Re-check later with: summer tool check-job --json '{"jobId":"${jobId}"}'`);
+    throw new ToolDispatchError(`Timed out after ${maxWaitMs / 1000}s. Re-check later with: ${cliCheckJobCommand(jobId)}`);
+}
+function cliCheckJobCommand(jobId) {
+    return `summer tool check-job --args '{"jobId":"${jobId}"}'`;
+}
+/** generate-3d / generate-motion return the job at once, like the MCP face;
+ *  `--args '{"wait":true,…}'` blocks instead. */
+function cliCheckJobNext(jobId) {
+    return `The job runs on Summer's servers. Check it with: ${cliCheckJobCommand(jobId)}`;
 }
 async function searchAssetsGateway(params) {
     const search = new URLSearchParams();
@@ -403,6 +432,10 @@ async function gatewayReply(call) {
     catch (error) {
         if (!(error instanceof ToolDispatchError))
             throw error;
+        if (error instanceof CodedToolError) {
+            const { code, recovery } = error.result;
+            return { error: error.message, status: 0, code, recovery };
+        }
         return { error: error.message, status: 0 };
     }
 }
@@ -978,8 +1011,8 @@ export const TOOL_DISPATCH = [
             options,
         });
         const jobId = typeof result.jobId === "string" ? result.jobId : undefined;
-        if (args.wait === false || !jobId)
-            return result;
+        if (args.wait !== true || !jobId)
+            return jobId ? { ...result, next: cliCheckJobNext(jobId) } : result;
         const final = await pollGenerationJob(jobId);
         return { ...final, jobId };
     }),
@@ -1000,7 +1033,7 @@ export const TOOL_DISPATCH = [
         const result = await gatewayPost("/api/mcp/generate/motion", built.body);
         const jobId = typeof result.jobId === "string" ? result.jobId : undefined;
         if (!parsed.wait || !jobId)
-            return result;
+            return jobId ? { ...result, next: cliCheckJobNext(jobId) } : result;
         const final = await pollGenerationJob(jobId, 600_000);
         return { ...final, jobId };
     }),
@@ -1253,19 +1286,19 @@ export const TOOL_DISPATCH = [
         return runBatch(await ctx.engine(), { scenePath, ops, receipt });
     }),
     // --- scene scripting ---
-    entry("summer_run_script", "Run a GDScript func run(ctx) inside the live editor against the open scene", true, async (args, ctx) => {
+    entry("summer_run_script", "Run a GDScript func run(ctx) inside the live editor against scenePath (or the open scene)", true, async (args, ctx) => {
         const client = await ctx.engine();
         const missing = missingEngineOpResult(client, "RunSceneScript", RUN_SCRIPT_FALLBACK);
         if (missing)
             refuseMissingOp(missing);
         const undo = optStr(args, "undo");
-        const { op, timeoutMs } = buildRunSceneScriptOp({
+        return requireSupportedOp(await runSceneScriptOn(client, {
+            scenePath: optStr(args, "scenePath"),
             source: str(args, "source"),
             max_seconds: typeof args.max_seconds === "number" ? args.max_seconds : undefined,
             checkpoint: typeof args.checkpoint === "boolean" ? args.checkpoint : undefined,
             undo: undo === "action" || undo === "none" ? undo : undefined,
-        });
-        return requireSupportedOp(await client.executeIdentityBoundOps([op], undefined, timeoutMs), "RunSceneScript", RUN_SCRIPT_FALLBACK);
+        }), "RunSceneScript", RUN_SCRIPT_FALLBACK);
     }),
     entry("summer_run_editor_script", "Run an EditorScript in a fresh headless child editor against the on-disk project", true, async (args, ctx) => {
         const client = await ctx.engine();
@@ -1730,5 +1763,7 @@ export async function dispatchTool(nameOrSlug, args, ctx = createDefaultDispatch
     // The one gate every result passes, mirroring withEngine on the MCP face:
     // whatever the MCP face would mark isError is a ToolResultError here, so the
     // CLI exit code says what the receipt says — for every tool, not per handler.
-    return requireEngineSuccess(await dispatchEntry.handler(args, ctx));
+    // Summer requests made for this call name the tool (core/agent-host.ts); the
+    // MCP face sets the same context in its call wrapper.
+    return requireEngineSuccess(await runWithToolContext(dispatchEntry.name, "cli", () => dispatchEntry.handler(args, ctx)));
 }

package/dist/core/capabilities/ui-control.d.ts

@@ -90,7 +90,7 @@ export declare const uiActivateArgsSchema: z.ZodObject<{
     value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
+    action?: "focus" | "press" | "select_tab" | "toggle" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;
     submit?: boolean | undefined;
@@ -98,7 +98,7 @@ export declare const uiActivateArgsSchema: z.ZodObject<{
     value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
+    action?: "focus" | "press" | "select_tab" | "toggle" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;
     submit?: boolean | undefined;

package/dist/core/capabilities/world-snapshot.d.ts

@@ -38,18 +38,18 @@ export declare const worldSnapshotInputSchema: z.ZodObject<{
     fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     scene_path?: string | undefined;
+    fields?: string[] | undefined;
+    path_prefix?: string | undefined;
     offset?: number | undefined;
     max_nodes?: number | undefined;
-    path_prefix?: string | undefined;
     classes?: string[] | undefined;
-    fields?: string[] | undefined;
 }, {
     scene_path?: string | undefined;
+    fields?: string[] | undefined;
+    path_prefix?: string | undefined;
     offset?: number | undefined;
     max_nodes?: number | undefined;
-    path_prefix?: string | undefined;
     classes?: string[] | undefined;
-    fields?: string[] | undefined;
 }>;
 export type WorldSnapshotArgs = z.infer<typeof worldSnapshotInputSchema>;
 export declare function buildWorldSnapshotOp(args: WorldSnapshotArgs): JsonRecord;

package/dist/core/embeddings.d.ts

@@ -47,6 +47,8 @@ export interface EmbedProviderOptions {
     token?: string | null;
     timeoutMs: number;
     fetchImpl?: typeof fetch;
+    /** Extra request headers (the runtime's client and agent-host headers). */
+    headers?: Record<string, string>;
 }
 export declare function encodeVector(vector: readonly number[]): string;
 export declare function decodeVector(encoded: string): Float32Array;

package/dist/core/embeddings.js

@@ -140,7 +140,7 @@ export function createEmbedProvider(options) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), options.timeoutMs);
         try {
-            const headers = { "Content-Type": "application/json" };
+            const headers = { ...options.headers, "Content-Type": "application/json" };
             if (options.token)
                 headers.Authorization = `Bearer ${options.token}`;
             const response = await fetchImpl(options.url, {

package/dist/core/error-codes.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Stable codes for the failures any Summer tool can hit before it does its
+ * job: the engine is not running, the person is not signed in, the account
+ * has no credits left, or the network failed. Agents branch on `code` and
+ * follow `recovery` (one next step); the older fields each tool returned
+ * (`error`, `message`, `hint`) stay next to them so 3.x callers keep working.
+ *
+ * The store sign-in keeps its own code, `store_login_required`
+ * (core/oauth.ts): it is a second grant with its own recovery
+ * (`summer login --store`).
+ *
+ * The codes are the ones the 4.0 tools use (one closed list, shared with the
+ * hosted Summer MCP), so 4.0 changes where they sit, not their names.
+ */
+export type SummerErrorCode = "engine_not_running" | "not_signed_in" | "no_credits" | "unavailable";
+export declare const SIGN_IN_COMMAND = "npx -y summer-engine@latest login";
+export declare const CREDITS_URL = "https://summerengine.com/studio/credits";
+/** The one sentence every tool uses when there is no Summer account token. */
+export declare const NOT_SIGNED_IN = "Not signed in to Summer.";
+/** A token the server refused (expired, revoked): plain `login` would say
+ *  "Already logged in", so the step forces a new sign-in. */
+export declare const SIGN_IN_AGAIN_RECOVERY = "Ask the person to sign in again: npx -y summer-engine@latest login --force";
+/** The one next step per code, as the MCP face words it (the agent may not
+ *  have `summer` on PATH, so commands go through npx). */
+export declare const RECOVERY: Record<SummerErrorCode, string>;
+/** The same steps for `summer tool` in a shell, where `summer` is the CLI. */
+export declare const CLI_RECOVERY: Record<SummerErrorCode, string>;
+export interface CodedFailure {
+    ok: false;
+    code: SummerErrorCode;
+    error: string;
+    recovery: string;
+}
+/** `{ok:false, code, error, recovery}` first, then any other fields the
+ *  tool already returned (`message`, `hint`, `status`, …). The four named
+ *  fields win over `extra`; `recovery` defaults to the MCP wording. */
+export declare function codedFailure(code: SummerErrorCode, error: string, extra?: Record<string, unknown>, recovery?: string): CodedFailure & Record<string, unknown>;
+/** The code for a failed Summer web request by HTTP status, when it is one
+ *  of the shared ones. */
+export declare function codeForStatus(status: number): SummerErrorCode | null;
+/** The message for a failed request, with the real cause in it. */
+export declare function describeNetworkError(error: unknown): string;
+/** `details.cause` for an `unavailable` answer. */
+export declare function networkDetails(error: unknown): {
+    details: {
+        cause: string;
+    };
+};
+/** The engine connect failure that means "nothing is running for this
+ *  project", worded for the person; the raw reason (token files, instance
+ *  registry paths) stays in the logs, not in the line the agent repeats. */
+export declare class EngineNotRunningError extends Error {
+    readonly reason: string;
+    readonly code: "engine_not_running";
+    constructor(message: string, reason: string);
+}
+/** A connect error from core/engine.ts → EngineNotRunningError when it means
+ *  no editor is reachable; null for the others (several editors open, …),
+ *  which already say what to do. */
+export declare function engineNotRunningFromConnectError(reason: string): EngineNotRunningError | null;
+/** Engine-free tools keep working while the engine is down. */
+export declare const ENGINE_FREE_NOTE: string;

package/dist/core/error-codes.js

@@ -0,0 +1,97 @@
+/**
+ * Stable codes for the failures any Summer tool can hit before it does its
+ * job: the engine is not running, the person is not signed in, the account
+ * has no credits left, or the network failed. Agents branch on `code` and
+ * follow `recovery` (one next step); the older fields each tool returned
+ * (`error`, `message`, `hint`) stay next to them so 3.x callers keep working.
+ *
+ * The store sign-in keeps its own code, `store_login_required`
+ * (core/oauth.ts): it is a second grant with its own recovery
+ * (`summer login --store`).
+ *
+ * The codes are the ones the 4.0 tools use (one closed list, shared with the
+ * hosted Summer MCP), so 4.0 changes where they sit, not their names.
+ */
+export const SIGN_IN_COMMAND = "npx -y summer-engine@latest login";
+export const CREDITS_URL = "https://summerengine.com/studio/credits";
+/** The one sentence every tool uses when there is no Summer account token. */
+export const NOT_SIGNED_IN = "Not signed in to Summer.";
+/** A token the server refused (expired, revoked): plain `login` would say
+ *  "Already logged in", so the step forces a new sign-in. */
+export const SIGN_IN_AGAIN_RECOVERY = `Ask the person to sign in again: ${SIGN_IN_COMMAND} --force`;
+/** The one next step per code, as the MCP face words it (the agent may not
+ *  have `summer` on PATH, so commands go through npx). */
+export const RECOVERY = {
+    engine_not_running: "Open the project in Summer Engine, or run: npx -y summer-engine@latest run <project-path> (the folder that holds project.godot).",
+    not_signed_in: `Ask the person to sign in: ${SIGN_IN_COMMAND}`,
+    no_credits: `Ask the person to add credits: ${CREDITS_URL}`,
+    unavailable: "Check the network connection, then retry.",
+};
+/** The same steps for `summer tool` in a shell, where `summer` is the CLI. */
+export const CLI_RECOVERY = {
+    ...RECOVERY,
+    engine_not_running: "Open the project in Summer Engine, or run: summer run <project-path> (the folder that holds project.godot).",
+    not_signed_in: "Run: summer login",
+};
+/** `{ok:false, code, error, recovery}` first, then any other fields the
+ *  tool already returned (`message`, `hint`, `status`, …). The four named
+ *  fields win over `extra`; `recovery` defaults to the MCP wording. */
+export function codedFailure(code, error, extra = {}, recovery = RECOVERY[code]) {
+    const named = { ok: false, code, error, recovery };
+    return Object.assign({ ...named }, extra, named);
+}
+/** The code for a failed Summer web request by HTTP status, when it is one
+ *  of the shared ones. */
+export function codeForStatus(status) {
+    if (status === 401)
+        return "not_signed_in";
+    if (status === 402)
+        return "no_credits";
+    return null;
+}
+/** `fetch failed` says nothing; Node puts the real reason on `cause`
+ *  (`connect ECONNREFUSED 127.0.0.1:443`, `getaddrinfo ENOTFOUND …`). */
+function networkCause(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = error instanceof Error ? error.cause : undefined;
+    return cause instanceof Error ? cause.message : typeof cause === "string" ? cause : message;
+}
+/** The message for a failed request, with the real cause in it. */
+export function describeNetworkError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = networkCause(error);
+    return message.includes(cause) ? message : `${message} (${cause})`;
+}
+/** `details.cause` for an `unavailable` answer. */
+export function networkDetails(error) {
+    return { details: { cause: networkCause(error) } };
+}
+/** The engine connect failure that means "nothing is running for this
+ *  project", worded for the person; the raw reason (token files, instance
+ *  registry paths) stays in the logs, not in the line the agent repeats. */
+export class EngineNotRunningError extends Error {
+    reason;
+    code = "engine_not_running";
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "EngineNotRunningError";
+    }
+}
+/** A connect error from core/engine.ts → EngineNotRunningError when it means
+ *  no editor is reachable; null for the others (several editors open, …),
+ *  which already say what to do. */
+export function engineNotRunningFromConnectError(reason) {
+    const port = reason.match(/not responding on port (\d+)/)?.[1];
+    if (port)
+        return new EngineNotRunningError(`Summer Engine is not responding on port ${port}.`, reason);
+    if (/^No running Summer editor matches/.test(reason)) {
+        return new EngineNotRunningError(reason.split(/(?<=\.)\s/)[0], reason);
+    }
+    if (/not running/i.test(reason))
+        return new EngineNotRunningError("Summer Engine is not running.", reason);
+    return null;
+}
+/** Engine-free tools keep working while the engine is down. */
+export const ENGINE_FREE_NOTE = "Only tools that touch the local project need the engine. Library, generation and asset tools " +
+    "(summer_search_library, summer_generate_*, summer_search_assets, summer_list_my_assets, summer_get_asset, summer_check_job) work now.";

package/dist/core/format.d.ts

@@ -1,3 +1,5 @@
+/** ANSI colour only for a terminal: NO_COLOR turns it off, FORCE_COLOR on. */
+export declare function useColor(): boolean;
 export declare const c: {
     bold: (s: string) => string;
     dim: (s: string) => string;

package/dist/core/format.js

@@ -10,7 +10,8 @@ const ANSI = {
     // Summer brand orange (matches banner.ts mid gradient)
     brand: "\x1b[38;2;255;143;23m",
 };
-function useColor() {
+/** ANSI colour only for a terminal: NO_COLOR turns it off, FORCE_COLOR on. */
+export function useColor() {
     if (process.env.NO_COLOR)
         return false;
     if (process.env.FORCE_COLOR)

package/dist/core/hosted-mcp.d.ts

@@ -1,4 +1,5 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OAuthError } from "./oauth.js";
 /** The part of an MCP client the mount and the CLI use (a fake in tests). */
 export interface HostedClient {
     listTools(params?: {
@@ -54,7 +55,26 @@ export interface HostedConnectDependencies {
     connect: (url: string, token: () => Promise<string>) => Promise<HostedClient>;
 }
 export declare function connectHostedMcp(url: string, token: () => Promise<string>): Promise<HostedClient>;
+/**
+ * The hosted server's 3.x surface: the same address with `?surface=v3`. Once
+ * the hosted server serves 4.0 to every request that does not ask, only 3.x
+ * npm releases keep 3.x without asking, so the 3.x tool names here ask.
+ */
+export declare function withV3Surface(url: string): string;
 export declare const defaultHostedConnectDependencies: HostedConnectDependencies;
+/** The hosted server could not be reached, so no call was sent (a sign-in problem is an OAuthError instead). */
+export declare class HostedUnreachableError extends Error {
+    readonly recovery: string;
+    constructor(message: string, recovery: string);
+}
+/** The HTTP status an MCP transport error carries (the SDK's StreamableHTTPError puts it on `code`). */
+export declare function httpStatusOf(error: unknown): number | undefined;
+/**
+ * A failure to connect to the hosted server, before any call was sent: a
+ * sign-in problem (an OAuthError, or a 401), an account the server refuses
+ * (403, store_access_denied), or the server not answering.
+ */
+export declare function hostedConnectFailure(error: unknown, unreachableRecovery: string): OAuthError | HostedUnreachableError;
 /** True when this machine has a store sign-in on disk (no network). */
 export declare function hasStoreSignIn(): Promise<boolean>;
 export declare function listAllHostedTools(client: HostedClient): Promise<Tool[]>;
@@ -113,3 +133,5 @@ export type HostedCallOutcome = {
 };
 /** Call a hosted tool by its name or slug with the store sign-in (one connection). */
 export declare function callHostedToolForCli(name: string, args: Record<string, unknown>, deps?: HostedConnectDependencies, signedIn?: () => Promise<boolean>): Promise<HostedCallOutcome>;
+/** The tool a tools/call JSON-RPC body names, for the X-Summer-MCP-Tool header. */
+export declare function calledTool(body: unknown): string | undefined;

package/dist/core/hosted-mcp.js

@@ -2,6 +2,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { getStoreAccessToken, OAuthError, readStoredOAuthToken, resolveMcpResourceUrl } from "./oauth.js";
 import { TOOLKIT_VERSION } from "./version.js";
+import { summerRequestHeaders } from "./agent-host.js";
 /**
  * A client for the hosted Summer Engine MCP (mcp.summerengine.com), signed in
  * with the store sign-in ("summer login --store"). The local MCP mounts its
@@ -15,6 +16,8 @@ export async function connectHostedMcp(url, token) {
         // A fresh (refreshed when near expiry) token on every request.
         fetch: async (input, init) => {
             const headers = new Headers(init?.headers);
+            for (const [name, value] of Object.entries(summerRequestHeaders({ tool: calledTool(init?.body), surface: "mcp" })))
+                headers.set(name, value);
             headers.set("authorization", `Bearer ${await token()}`);
             return fetch(input, { ...init, headers });
         },
@@ -32,11 +35,51 @@ export async function connectHostedMcp(url, token) {
         close: () => client.close(),
     };
 }
+/**
+ * The hosted server's 3.x surface: the same address with `?surface=v3`. Once
+ * the hosted server serves 4.0 to every request that does not ask, only 3.x
+ * npm releases keep 3.x without asking, so the 3.x tool names here ask.
+ */
+export function withV3Surface(url) {
+    const parsed = new URL(url);
+    parsed.searchParams.set("surface", "v3");
+    return parsed.href;
+}
 export const defaultHostedConnectDependencies = {
-    url: () => resolveMcpResourceUrl(),
+    url: () => withV3Surface(resolveMcpResourceUrl()),
     token: () => getStoreAccessToken(),
     connect: connectHostedMcp,
 };
+/** The hosted server could not be reached, so no call was sent (a sign-in problem is an OAuthError instead). */
+export class HostedUnreachableError extends Error {
+    recovery;
+    constructor(message, recovery) {
+        super(`${message} ${recovery}`);
+        this.recovery = recovery;
+        this.name = "HostedUnreachableError";
+    }
+}
+/** The HTTP status an MCP transport error carries (the SDK's StreamableHTTPError puts it on `code`). */
+export function httpStatusOf(error) {
+    const code = error?.code;
+    return typeof code === "number" && code >= 100 && code <= 599 ? code : undefined;
+}
+/**
+ * A failure to connect to the hosted server, before any call was sent: a
+ * sign-in problem (an OAuthError, or a 401), an account the server refuses
+ * (403, store_access_denied), or the server not answering.
+ */
+export function hostedConnectFailure(error, unreachableRecovery) {
+    if (error instanceof OAuthError || error instanceof HostedUnreachableError)
+        return error;
+    const cause = error instanceof Error ? error.message : String(error);
+    const status = httpStatusOf(error);
+    if (status === 401)
+        return new OAuthError("oauth_token_invalid", `Summer's hosted server refused the sign-in: ${cause}.`, 'Recovery: run "summer login --store --force".');
+    if (status === 403)
+        return new OAuthError("store_access_denied", `Summer's hosted server refused this account: ${cause}.`, "Recovery: check the account in Summer Studio (for example confirm the email), then try again.");
+    return new HostedUnreachableError(`The hosted Summer Engine MCP did not answer: ${cause}.`, unreachableRecovery);
+}
 /** True when this machine has a store sign-in on disk (no network). */
 export async function hasStoreSignIn() {
     return (await readStoredOAuthToken()) !== null;
@@ -162,3 +205,15 @@ export async function callHostedToolForCli(name, args, deps = defaultHostedConne
         return { status: "unavailable", message: error instanceof Error ? error.message : String(error) };
     }
 }
+/** The tool a tools/call JSON-RPC body names, for the X-Summer-MCP-Tool header. */
+export function calledTool(body) {
+    if (typeof body !== "string" || !body.includes('"tools/call"'))
+        return undefined;
+    try {
+        const message = JSON.parse(body);
+        return message.method === "tools/call" && typeof message.params?.name === "string" ? message.params.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/library-read.js

@@ -480,6 +480,11 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     else if (kind === "tool") {
         bodyTitle = "how to call";
         body = toolBody(entry, slug);
+        // An engine tool's guide: its full how-to (the v4 surface lists only a short summary).
+        const guide = readText(join(dir, "GUIDE.md"));
+        if (guide !== null) {
+            body = `${body}\n\n${guide.replace(/\s+$/, "")}`;
+        }
     }
     else if (kind === "template") {
         bodyTitle = "pin";

package/dist/core/library-search.d.ts

@@ -98,12 +98,12 @@ export declare const searchLibraryInputSchema: z.ZodObject<{
     include_preview: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     query: string;
-    kinds?: ("template" | "tool" | "reference" | "skill" | "example" | "collection")[] | undefined;
+    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }, {
     query: string;
-    kinds?: ("template" | "tool" | "reference" | "skill" | "example" | "collection")[] | undefined;
+    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }>;