summer-engine 3.7.0 → 4.0.0

package/dist/core/capabilities/apps.js

@@ -0,0 +1,353 @@
+import { readdir, readFile, lstat } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { getAuthToken } from "../auth.js";
+import { resolveGatewayUrl } from "../config.js";
+import { summerRequestHeaders } from "../agent-host.js";
+import { codedFailure, describeNetworkError, networkDetails, NOT_SIGNED_IN, SIGN_IN_AGAIN_RECOVERY } from "../error-codes.js";
+/**
+ * Summer Apps (summer_app_*): tools a game team uses inside Summer Studio,
+ * built by agents. Every cloud tool here calls the Summer web API under
+ * /api/mcp/apps with the signed-in Summer account; summer_app_dock asks the
+ * running editor to dock an app (engine ops OpenAppDock / CloseAppDock /
+ * ListAppDocks).
+ *
+ * One implementation for both faces: the MCP tools (src/mcp/tools/app-tools.ts)
+ * and `summer tool app-*` (tool-dispatch.ts) share the schemas and functions
+ * here and pass their own client surface.
+ */
+export const APPS_ENDPOINT = "/api/mcp/apps";
+/** The server's long-poll ceiling for summer_app_events. */
+export const MAX_APP_EVENTS_WAIT_SECONDS = 50;
+export const APP_GUIDE_SECTIONS = ["all", "overview", "manifest", "sdk", "kit", "layout", "design", "examples", "types"];
+export const APP_DOCK_SLOTS = ["left", "right", "bottom"];
+/** Bundle limits the server enforces (checked here first for a clear local error). */
+const MAX_FILES = 300;
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
+const TEXT_EXTENSIONS = new Set([".html", ".js", ".mjs", ".css", ".json", ".txt", ".md", ".svg", ".gltf"]);
+const appId = z.string().uuid().describe("The app id from summer_app_create or summer_app_list");
+const jsonObject = z.record(z.unknown());
+export const appGuideArgsSchema = z.object({
+    section: z
+        .enum(APP_GUIDE_SECTIONS)
+        .default("overview")
+        .describe("Start with overview (the default), then read what the app needs: examples (a working app to copy), sdk, manifest, kit, design, layout, types (exact SDK TypeScript types). all returns every section but types (about 100 KB)"),
+});
+export const appListArgsSchema = z.object({
+    workspaceId: z.string().uuid().optional().describe("Only this workspace (team). Default: every workspace the person is in"),
+    q: z.string().max(200).optional().describe("Search app names and purposes"),
+});
+export const appCreateArgsSchema = z.object({
+    name: z.string().min(1).max(80),
+    purpose: z.string().max(280).optional().describe("One line: what the tool does and where its data goes"),
+    format: z.enum(["code", "layout"]).default("code").describe("code: index.html + JS/CSS (default). layout: a JSON layout of kit nodes, for quick decision UIs"),
+    workspaceId: z.string().uuid().optional().describe("A workspace id. Default: the person's team (the one their Studio tab is on, else their latest team, else personal); the result's workspace says which"),
+    folder: z.string().min(1).max(80).optional(),
+});
+export const appPublishArgsSchema = z.object({
+    appId,
+    dir: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A local folder holding the app (index.html at its root). Every file under it is published; dotfiles, node_modules and .d.ts files are skipped"),
+    files: z
+        .array(z.object({
+        path: z.string().min(1).max(200),
+        content: z.string(),
+        encoding: z.enum(["utf8", "base64"]).default("utf8"),
+    }))
+        .max(MAX_FILES)
+        .optional()
+        .describe("The files instead of dir: [{path, content, encoding}]"),
+    layout: jsonObject.optional().describe("Layout apps: { version: 1, title, root }"),
+    manifest: jsonObject.describe("The manifest {name, purpose, permissions, engineFiles, agentEvents, agentTools} (summer_app_guide section manifest)"),
+    note: z.string().max(500).optional().describe("What changed, shown in the version list"),
+    idempotencyKey: z.string().min(8).max(128).optional(),
+});
+export const appGetArgsSchema = z.object({ appId });
+export const appEventsArgsSchema = z.object({
+    appId,
+    after: z.number().int().min(0).default(0).describe("Return events after this cursor (0: from the start). Pass the returned cursor next time"),
+    timeoutSeconds: z.number().int().min(0).max(MAX_APP_EVENTS_WAIT_SECONDS).default(25).describe("Wait up to this long (max 50) for the first new event"),
+    kinds: z.array(z.enum(["agent", "error", "feedback", "tool"])).max(4).optional().describe("Default: agent, error, feedback"),
+});
+export const appPageArgsSchema = z.object({
+    appId,
+    fill: z
+        .array(z.object({ field: z.string().min(1).max(200), value: z.union([z.string().max(10_000), z.number(), z.boolean()]) }))
+        .max(50)
+        .optional()
+        .describe("Values to set: [{field, value}] with field ids from a read"),
+    press: z.string().min(1).max(200).optional().describe("An action id to press after filling"),
+});
+export const appUpdateArgsSchema = z.object({
+    appId,
+    name: z.string().min(1).max(80).optional(),
+    purpose: z.string().max(280).optional(),
+    status: z.enum(["scratch", "kept", "archived"]).optional().describe("kept: the team keeps it. archived: hidden from the app list (restore with scratch or kept)"),
+    folder: z.string().min(1).max(80).nullable().optional().describe("null takes it out of its folder"),
+});
+export const appScreenshotArgsSchema = z.object({
+    appId,
+    version: z.number().int().positive().optional().describe("A published version. Default: the current one"),
+    width: z.number().int().min(320).max(1920).default(1280).describe("Viewport width in px: 390 for a phone"),
+    height: z.number().int().min(320).max(1600).default(800),
+    theme: z.enum(["light", "dark"]).default("light"),
+    fullPage: z.boolean().default(false).describe("Capture the whole scroll height (up to 4000 px)"),
+    params: z.record(z.string().max(500)).optional().describe("Launch params, as in /studio/apps/<id>?key=value"),
+    steps: z
+        .array(z.object({ click: z.string().max(300).optional(), press: z.string().max(40).optional(), wait: z.number().int().min(0).max(3000).optional() }))
+        .max(5)
+        .optional()
+        .describe('Before the capture, in order: click a CSS selector in the app (">>>" reaches inside kit components), press a declared action id, or wait ms. Use it to see a dialog or a second state'),
+    out: z.string().min(1).optional().describe("Also save the PNG to this local path"),
+});
+export const appDataArgsSchema = z.object({
+    appId,
+    collection: z.string().max(48).optional().describe("Read: one collection. Default: all"),
+    after: z.string().max(200).optional().describe("Read: the next cursor from the previous page"),
+    limit: z.number().int().min(1).max(500).default(200),
+    ops: z
+        .array(jsonObject)
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Write: [{op: put, collection, recordId, data}, {op: patch, collection, recordId, patch}, {op: remove, collection, recordId}]; ifRevision on an op applies it only at that record revision (0: must not exist)"),
+    as: z.enum(["agent", "seed"]).optional().describe("Write: seed for starter data that belongs to the team (no author). Default: agent"),
+});
+export const appToolsArgsSchema = z.object({ appId });
+export const appCallArgsSchema = z.object({
+    appId,
+    tool: z.string().min(1).max(64).describe("The agent tool name from summer_app_tools"),
+    input: jsonObject.default({}).describe("Input matching the tool's input schema"),
+});
+export const appReportGapArgsSchema = z.object({
+    capability: z.string().min(1).max(200).describe('What the app needed, e.g. "read Steam reviews"'),
+    detail: z.string().max(2000).optional(),
+    method: z.string().max(100).optional().describe("The SDK method name you wished existed"),
+    appId: appId.optional(),
+});
+export const appDockArgsSchema = z.object({
+    action: z.enum(["open", "close", "list"]).default("open"),
+    appId: appId.optional().describe("open, close: the app"),
+    slot: z.enum(APP_DOCK_SLOTS).default("right").describe("open: left, right or bottom"),
+});
+/** Fetch with the Summer account token; errors come back as replies, never throws. */
+export function appsGateway(surface, tool) {
+    return async (method, endpoint, { query, body, timeoutMs }) => {
+        const token = await getAuthToken();
+        if (!token)
+            return {
+                ok: false,
+                status: 401,
+                data: { error: { code: "not_signed_in", message: NOT_SIGNED_IN } },
+            };
+        const gateway = await resolveGatewayUrl();
+        const suffix = query?.toString() ? `?${query.toString()}` : "";
+        let response;
+        try {
+            response = await fetch(`${gateway}${endpoint}${suffix}`, {
+                method,
+                headers: {
+                    ...summerRequestHeaders({ tool, surface }),
+                    Authorization: `Bearer ${token}`,
+                    "X-Summer-MCP-Endpoint": endpoint,
+                    ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            return { ok: false, status: 0, data: { error: { code: "unavailable", message: `Request failed: ${describeNetworkError(error)}`, ...networkDetails(error) } } };
+        }
+        const text = await response.text().catch(() => "");
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = { message: text.slice(0, 1000) };
+        }
+        return { ok: response.ok, status: response.status, data };
+    };
+}
+/** The server's `{error: {code, message}}` as one flat result an agent can act on.
+ *  Not signed in, no credits and network failures carry the shared codes
+ *  (core/error-codes.ts); the server's own codes pass through. */
+function failure(reply) {
+    const error = reply.data.error;
+    const record = error && typeof error === "object" ? error : {};
+    const code = typeof record.code === "string" ? record.code : reply.status === 404 ? "not_found" : "unavailable";
+    const message = typeof record.message === "string" ? record.message : typeof reply.data.message === "string" ? reply.data.message : `Request failed (${reply.status})`;
+    const { error: _error, message: _message, ...rest } = reply.data;
+    const extra = { status: reply.status, ...rest, ...(record.details ? { details: record.details } : {}) };
+    if (code === "not_signed_in")
+        return codedFailure("not_signed_in", message, extra);
+    if (code === "unauthorized" || reply.status === 401)
+        return codedFailure("not_signed_in", message, extra, SIGN_IN_AGAIN_RECOVERY);
+    if (reply.status === 402)
+        return codedFailure("no_credits", message, extra);
+    if (reply.status === 0)
+        return codedFailure("unavailable", message, extra);
+    const hints = {
+        not_found: "Summer Apps is not available for this account yet, or the app id is wrong: summer_app_list shows the person's apps.",
+        app_not_open: "Use summer_app_data, or ask the person to open the app in Summer Studio.",
+        invalid: "Fix what the message names and try again (summer_app_guide has the rules).",
+        too_large: "Limits: 10 MB per app, 300 files, 5 MB per file.",
+        rate_limited: "Wait a minute and try again.",
+    };
+    return { ok: false, code, error: message, status: reply.status, ...(hints[code] ? { hint: hints[code] } : {}), ...rest, ...(record.details ? { details: record.details } : {}) };
+}
+const done = (reply) => (reply.ok ? { ok: true, ...reply.data } : failure(reply));
+const params = (values) => {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(values))
+        if (value !== undefined && value !== "")
+            query.set(key, value);
+    return query;
+};
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+export async function appGuide(args, deps) {
+    return done(await deps.request("GET", `${APPS_ENDPOINT}/guide`, { query: params({ section: args.section }), timeoutMs: 30_000 }));
+}
+export async function appList(args, deps) {
+    return done(await deps.request("GET", APPS_ENDPOINT, { query: params({ workspaceId: args.workspaceId, q: args.q }), timeoutMs: 30_000 }));
+}
+export async function appCreate(args, deps) {
+    const reply = await deps.request("POST", APPS_ENDPOINT, { body: args, timeoutMs: 30_000 });
+    if (!reply.ok)
+        return failure(reply);
+    const studio = reply.data.studio;
+    const workspace = reply.data.workspace;
+    const where = workspace?.name ? `It is in ${workspace.kind === "personal" ? "the person's personal workspace" : `the team ${workspace.name}`}: tell them. ` : "";
+    return {
+        ok: true,
+        ...reply.data,
+        next: `${where}${studio?.queued ? "The person's Summer Studio tab is opening the app. " : ""}Write the app (summer_app_guide first), then summer_app_publish with appId and the files or dir.`,
+    };
+}
+/** Every file under dir (dotfiles, node_modules and .d.ts type files skipped), as publish files. */
+export async function readAppDir(dir) {
+    const root = path.resolve(dir);
+    const files = [];
+    let total = 0;
+    const walk = async (current) => {
+        for (const entry of (await readdir(current, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name.endsWith(".d.ts"))
+                continue;
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            if (!entry.isFile() || (await lstat(full)).isSymbolicLink())
+                continue;
+            const bytes = await readFile(full);
+            if (bytes.length > MAX_FILE_BYTES)
+                throw new Error(`${path.relative(root, full)} is over 5 MB`);
+            total += bytes.length;
+            if (total > MAX_BUNDLE_BYTES)
+                throw new Error(`${dir} is over the 10 MB app limit`);
+            const relative = path.relative(root, full).split(path.sep).join("/");
+            const text = TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase());
+            files.push({ path: relative, content: bytes.toString(text ? "utf8" : "base64"), encoding: text ? "utf8" : "base64" });
+            if (files.length > MAX_FILES)
+                throw new Error(`${dir} has more than ${MAX_FILES} files`);
+        }
+    };
+    await walk(root);
+    return files;
+}
+export async function appPublish(args, deps) {
+    const sources = [args.dir, args.files, args.layout].filter((value) => value !== undefined).length;
+    if (sources !== 1)
+        return { ok: false, code: "invalid", error: "Send exactly one of dir, files or layout." };
+    let files = args.files;
+    if (args.dir) {
+        try {
+            files = await (deps.readDir ?? readAppDir)(args.dir);
+        }
+        catch (error) {
+            return { ok: false, code: "invalid", error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    const body = { ...(files ? { files } : { layout: args.layout }), manifest: args.manifest, ...(args.note ? { note: args.note } : {}), ...(args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {}) };
+    const reply = await deps.request("POST", `${APPS_ENDPOINT}/${args.appId}/publish`, { body, timeoutMs: 120_000 });
+    if (!reply.ok)
+        return failure(reply);
+    const version = reply.data.version;
+    return {
+        ok: true,
+        ...reply.data,
+        next: `Version ${version?.version ?? "?"} is live in the person's Studio. Wait for what the app sends with summer_app_events, or publish again to change it.`,
+    };
+}
+export async function appGet(args, deps) {
+    return done(await deps.request("GET", `${APPS_ENDPOINT}/${args.appId}`, { timeoutMs: 60_000 }));
+}
+export async function appEvents(args, deps) {
+    return done(await deps.request("GET", `${APPS_ENDPOINT}/${args.appId}/events`, {
+        query: params({ after: String(args.after), timeoutMs: String(args.timeoutSeconds * 1000), kinds: args.kinds?.join(",") }),
+        timeoutMs: (args.timeoutSeconds + 20) * 1000,
+    }));
+}
+export async function appPage(args, deps) {
+    const { appId: id, ...body } = args;
+    return done(await deps.request("POST", `${APPS_ENDPOINT}/${id}/page`, { body, timeoutMs: 60_000 }));
+}
+export async function appUpdate(args, deps) {
+    const { appId: id, ...body } = args;
+    return done(await deps.request("POST", `${APPS_ENDPOINT}/${id}/update`, { body, timeoutMs: 30_000 }));
+}
+/**
+ * summer_app_screenshot: the server renders the app headless and read-only as the
+ * person and answers the PNG (base64) with its console, errors and declared page.
+ * The image moves to `image`; `out` also writes it to disk.
+ */
+export async function appScreenshot(args, deps) {
+    const { appId: id, out, ...body } = args;
+    const result = done(await deps.request("POST", `${APPS_ENDPOINT}/${id}/screenshot`, { body, timeoutMs: 90_000 }));
+    if (result.ok !== true)
+        return result;
+    const { image, ...report } = result;
+    if (!image)
+        return { ...report, ok: false, code: "invalid", error: "The server answered without an image" };
+    if (out)
+        await (deps.writeFile ?? ((file, data) => import("node:fs/promises").then((fs) => fs.writeFile(file, data))))(path.resolve(out), Buffer.from(image.base64, "base64"));
+    return { ...report, image, ...(out ? { savedTo: path.resolve(out) } : {}) };
+}
+export async function appData(args, deps) {
+    if (args.ops)
+        return done(await deps.request("POST", `${APPS_ENDPOINT}/${args.appId}/data`, { body: { ops: args.ops, ...(args.as ? { as: args.as } : {}) }, timeoutMs: 30_000 }));
+    return done(await deps.request("GET", `${APPS_ENDPOINT}/${args.appId}/data`, {
+        query: params({ collection: args.collection, after: args.after, limit: String(args.limit) }),
+        timeoutMs: 30_000,
+    }));
+}
+export async function appTools(args, deps) {
+    return done(await deps.request("GET", `${APPS_ENDPOINT}/${args.appId}/tools`, { timeoutMs: 30_000 }));
+}
+export async function appCall(args, deps) {
+    const { appId: id, ...body } = args;
+    return done(await deps.request("POST", `${APPS_ENDPOINT}/${id}/call`, { body, timeoutMs: 90_000 }));
+}
+export async function appReportGap(args, deps) {
+    return done(await deps.request("POST", `${APPS_ENDPOINT}/report-gap`, { body: args, timeoutMs: 30_000 }));
+}
+// ---------------------------------------------------------------------------
+// summer_app_dock (engine)
+// ---------------------------------------------------------------------------
+export const APP_DOCK_FALLBACK = "This engine build cannot dock apps yet. Open the app in the Summer Studio tab instead (summer_studio_open with /studio/apps/<appId>), or update Summer Engine.";
+/** The engine op for one dock action. */
+export function appDockOp(args) {
+    if (args.action === "list")
+        return { op: "ListAppDocks" };
+    if (!args.appId)
+        throw new Error(`${args.action} needs appId`);
+    return args.action === "open" ? { op: "OpenAppDock", appId: args.appId, slot: args.slot } : { op: "CloseAppDock", appId: args.appId };
+}

package/dist/core/capabilities/doctor.d.ts

@@ -22,6 +22,9 @@ interface DoctorOptions {
     quiet?: boolean;
 }
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorResult>;
+/** The oldest Node major the package supports: `engines.node` in package.json. */
+export declare const MIN_NODE_MAJOR = 20;
+export declare function checkNodeVersion(nodeVersion?: string): DoctorCheck;
 export declare function checkLogin(): Promise<DoctorCheck>;
 /**
  * Store access: with a store sign-in ("summer login --store"), ask the store

package/dist/core/capabilities/doctor.js

@@ -10,14 +10,15 @@ import { c, pad, sym, tildeify } from "../format.js";
 import { getMcpLogPath } from "../mcp-log.js";
 import { checkStoreAccess, hasStoreSignIn } from "../hosted-mcp.js";
 import { formatProjectPin, getProjectMemorySummary, } from "../../project-memory/project-memory.js";
-import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, detectRecordedInstall, fetchLatestRegistryVersion, } from "../../installer/version-check.js";
+import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, detectRecordedInstall, fetchLatestRegistryVersion, fetchRegistryDistTags, } from "../../installer/version-check.js";
 import { TOOLKIT_VERSION as version } from "../version.js";
+import { resolveSurface } from "../tool-profiles.js";
 const MIN_EXPECTED_MCP_TOOLS = 50;
-const REQUIRED_MCP_TOOLS = [
-    "summer_get_project_context",
-    "summer_generate_image",
-    "summer_create_debug_report",
-];
+/** Per surface: the spawned `summer mcp` reads SUMMER_SURFACE from this process's env. */
+const REQUIRED_MCP_TOOLS = {
+    v3: ["summer_get_project_context", "summer_generate_image", "summer_create_debug_report"],
+    v4: ["summer_get_project_context", "summer_search", "summer_call", "summer_create_debug_report"],
+};
 export async function runDoctor(options = {}) {
     const checks = [];
     checks.push(checkNodeVersion());
@@ -47,21 +48,24 @@ export async function runDoctor(options = {}) {
     }
     return result;
 }
-function checkNodeVersion() {
-    const major = Number(process.versions.node.split(".")[0]);
-    if (Number.isFinite(major) && major >= 18) {
+/** The oldest Node major the package supports: `engines.node` in package.json. */
+export const MIN_NODE_MAJOR = 20;
+export function checkNodeVersion(nodeVersion = process.versions.node) {
+    const major = Number(nodeVersion.split(".")[0]);
+    const shown = `v${nodeVersion.replace(/^v/, "")}`;
+    if (Number.isFinite(major) && major >= MIN_NODE_MAJOR) {
         return {
             id: "node-version",
             label: "Node.js",
             status: "ok",
-            message: process.version,
+            message: shown,
         };
     }
     return {
         id: "node-version",
         label: "Node.js",
         status: "fail",
-        message: `${process.version} (need 18+)`,
+        message: `${shown} (need ${MIN_NODE_MAJOR}+)`,
     };
 }
 async function checkCliVersionCurrent() {
@@ -83,12 +87,12 @@ async function checkCliVersionCurrent() {
  *  recorded by `summer setup`: a `--local-dev` link gets the local-dev form
  *  so the fix does not replace the checkout with the published package. */
 async function checkSkillsVersion() {
-    const registry = await fetchLatestRegistryVersion();
+    const registry = await fetchRegistryDistTags();
     const result = await buildSkillsVersionCheck({
         installedCliVersion: version,
         candidates: defaultSkillMarkerCandidates(),
         recordedInstall: detectRecordedInstall,
-        ...(registry.ok ? { latestRegistryVersion: registry.version } : {}),
+        ...(registry.ok ? { latestRegistryVersion: registry.tags.latest, nextRegistryVersion: registry.tags.next } : {}),
     });
     return {
         id: "skills-version-stale",
@@ -384,11 +388,12 @@ async function checkMcpToolsList() {
         await client.connect(transport, { timeout: 5000 });
         const listed = await client.listTools(undefined, { timeout: 5000 });
         const toolNames = listed.tools.map((tool) => tool.name).sort();
-        const missing = REQUIRED_MCP_TOOLS.filter((tool) => !toolNames.includes(tool));
+        const requiredTools = REQUIRED_MCP_TOOLS[resolveSurface(undefined)];
+        const missing = requiredTools.filter((tool) => !toolNames.includes(tool));
         const details = {
             ...resolved,
             toolCount: toolNames.length,
-            requiredTools: REQUIRED_MCP_TOOLS,
+            requiredTools,
             missing,
             server: client.getServerVersion(),
             stderr: stderr.trim().slice(-1000),

package/dist/core/capabilities/enable-plugin.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * summer_enable_plugin: enable an editor plugin (`res://addons/<name>/`) and
+ * report what really happened. Engines with Summer Apps support run the
+ * EnableEditorPlugin op until the plugin's `_enter_tree` has run and answer
+ * `enabled` (or a failure `code`); older engines only queue the enable and
+ * answer `deferred: true`, so this tool says the result is unknown instead of
+ * claiming success. One implementation for the MCP tool and `summer tool
+ * enable-plugin`.
+ */
+export declare const enablePluginArgsSchema: z.ZodObject<{
+    plugin: z.ZodString;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    plugin: string;
+    timeoutMs?: number | undefined;
+}, {
+    plugin: string;
+    timeoutMs?: number | undefined;
+}>;
+export declare function enablePluginOp(args: z.output<typeof enablePluginArgsSchema>): {
+    op: string;
+    [key: string]: unknown;
+};
+export declare const QUEUED_ONLY_NOTE: string;
+/** The engine's answer for EnableEditorPlugin, as one result an agent can trust. */
+export declare function interpretEnablePluginResult(raw: unknown): Record<string, unknown>;

package/dist/core/capabilities/enable-plugin.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { asRecord } from "../util/json.js";
+import { extractOpError } from "./engine-receipt.js";
+/**
+ * summer_enable_plugin: enable an editor plugin (`res://addons/<name>/`) and
+ * report what really happened. Engines with Summer Apps support run the
+ * EnableEditorPlugin op until the plugin's `_enter_tree` has run and answer
+ * `enabled` (or a failure `code`); older engines only queue the enable and
+ * answer `deferred: true`, so this tool says the result is unknown instead of
+ * claiming success. One implementation for the MCP tool and `summer tool
+ * enable-plugin`.
+ */
+export const enablePluginArgsSchema = z.object({
+    plugin: z
+        .string()
+        .min(1)
+        .max(200)
+        .describe("The plugin folder under res://addons/ (e.g. 'quest_tools') or its 'res://addons/<name>/plugin.cfg'"),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(120_000)
+        .optional()
+        .describe("How long the engine waits for the plugin to load (default 30000)"),
+});
+export function enablePluginOp(args) {
+    return { op: "EnableEditorPlugin", pluginPath: args.plugin.trim(), ...(args.timeoutMs ? { timeoutMs: args.timeoutMs } : {}) };
+}
+const FAILURE_HINTS = {
+    CFG_MISSING: "No plugin.cfg there. Check the folder name under res://addons/.",
+    CFG_PARSE_FAILED: "plugin.cfg does not parse. Fix it and enable again.",
+    NO_SCRIPT_KEY: "plugin.cfg needs a script= entry under [plugin].",
+    EMPTY_SCRIPT_PATH: "plugin.cfg needs a script= entry under [plugin].",
+    SCRIPT_MISSING: "The script plugin.cfg names does not exist.",
+    SCRIPT_LOAD_FAILED: "The plugin script did not load. Read summer_get_script_errors for it.",
+    SCRIPT_ERROR: "The plugin script has errors. Read summer_get_script_errors, fix them, and enable again.",
+    NOT_EDITOR_PLUGIN: "The plugin script must extend EditorPlugin.",
+    NOT_TOOL: "The plugin script must start with @tool.",
+    TIMEOUT: "The plugin did not finish loading in time (often a filesystem scan). Try again, or raise timeoutMs.",
+};
+export const QUEUED_ONLY_NOTE = "This Summer Engine build only queues the enable and does not report whether the plugin loaded. " +
+    "Check summer_get_debugger_errors and summer_get_script_errors for the plugin script before relying on it, or update Summer Engine for the real result.";
+/** The engine's answer for EnableEditorPlugin, as one result an agent can trust. */
+export function interpretEnablePluginResult(raw) {
+    const root = asRecord(raw) ?? {};
+    const results = Array.isArray(root.results) ? root.results : [];
+    const entry = asRecord(results.find((item) => asRecord(item)?.op === "EnableEditorPlugin") ?? results[0]) ?? root;
+    const addonPath = typeof entry.addonPath === "string" ? entry.addonPath : undefined;
+    const error = extractOpError(raw) ?? (entry.ok === false ? String(entry.error ?? "The plugin was not enabled.") : null);
+    if (error) {
+        const code = typeof entry.code === "string" ? entry.code : undefined;
+        return {
+            ok: false,
+            enabled: false,
+            ...(addonPath ? { addonPath } : {}),
+            ...(code ? { code } : {}),
+            error,
+            ...(code && FAILURE_HINTS[code] ? { hint: FAILURE_HINTS[code] } : {}),
+        };
+    }
+    if (entry.alreadyEnabled === true)
+        return { ok: true, enabled: true, alreadyEnabled: true, ...(addonPath ? { addonPath } : {}) };
+    if (entry.enabled === true) {
+        return {
+            ok: true,
+            enabled: true,
+            ...(addonPath ? { addonPath } : {}),
+            autoloadsRegistered: Array.isArray(entry.autoloadsRegistered) ? entry.autoloadsRegistered : [],
+            ...(typeof entry.elapsedMs === "number" ? { elapsedMs: entry.elapsedMs } : {}),
+        };
+    }
+    // Older engines: { ok: true, deferred: true } means "scheduled", not "loaded".
+    return { ok: true, enabled: null, queued: true, ...(addonPath ? { addonPath } : {}), note: QUEUED_ONLY_NOTE };
+}

package/dist/core/capabilities/fabricate-mesh.d.ts

@@ -56,8 +56,8 @@ export declare const fabricateArgsSchema: z.ZodObject<{
     checkpoint: z.ZodOptional<z.ZodBoolean>;
     blender_path: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    source: string;
     name: string;
+    source: string;
     out_path?: string | undefined;
     target_size?: number | undefined;
     import_to_scene?: {
@@ -68,8 +68,8 @@ export declare const fabricateArgsSchema: z.ZodObject<{
     checkpoint?: boolean | undefined;
     blender_path?: string | undefined;
 }, {
-    source: string;
     name: string;
+    source: string;
     out_path?: string | undefined;
     target_size?: number | undefined;
     import_to_scene?: {

package/dist/core/capabilities/game-task-plan.d.ts

@@ -15,17 +15,17 @@ export declare const gameTaskPlanInputSchema: z.ZodObject<{
     assetPolicy: z.ZodDefault<z.ZodEnum<["reuse-first", "ask-before-paid-generation", "no-paid-generation", "generate-when-clearly-needed"]>>;
     verification: z.ZodDefault<z.ZodEnum<["none", "fast", "full"]>>;
 }, "strip", z.ZodTypeAny, {
-    mode: "auto" | "debug" | "new-game" | "feature" | "asset" | "playtest" | "polish" | "ship";
-    target: "auto" | "audio" | "level" | "npc" | "2d" | "3d" | "ui" | "animation" | "multiplayer";
+    mode: "auto" | "ship" | "debug" | "new-game" | "feature" | "asset" | "playtest" | "polish";
+    target: "auto" | "audio" | "level" | "npc" | "ui" | "2d" | "3d" | "animation" | "multiplayer";
     goal: string;
     assetPolicy: "reuse-first" | "ask-before-paid-generation" | "no-paid-generation" | "generate-when-clearly-needed";
-    verification: "none" | "fast" | "full";
+    verification: "none" | "full" | "fast";
 }, {
     goal: string;
-    mode?: "auto" | "debug" | "new-game" | "feature" | "asset" | "playtest" | "polish" | "ship" | undefined;
-    target?: "auto" | "audio" | "level" | "npc" | "2d" | "3d" | "ui" | "animation" | "multiplayer" | undefined;
+    mode?: "auto" | "ship" | "debug" | "new-game" | "feature" | "asset" | "playtest" | "polish" | undefined;
+    target?: "auto" | "audio" | "level" | "npc" | "ui" | "2d" | "3d" | "animation" | "multiplayer" | undefined;
     assetPolicy?: "reuse-first" | "ask-before-paid-generation" | "no-paid-generation" | "generate-when-clearly-needed" | undefined;
-    verification?: "none" | "fast" | "full" | undefined;
+    verification?: "none" | "full" | "fast" | undefined;
 }>;
 export type GameTaskMode = (typeof GAME_TASK_MODES)[number];
 export type GameTaskTarget = (typeof GAME_TASK_TARGETS)[number];
@@ -37,6 +37,10 @@ export interface GameTaskPlanOptions {
     target?: GameTaskTarget;
     assetPolicy?: AssetPolicy;
     verification?: VerificationLevel;
+    /** False when the session has no engine tools (the assets profile): the plan
+     *  then ends at a delivered file and names only tools the session has. Not
+     *  part of the input schema; the MCP server sets it from its profile. */
+    engine?: boolean;
 }
 export interface SkillRoute {
     /** Library resource id, e.g. "skill/make-game". */
@@ -62,5 +66,7 @@ export interface GameTaskPlan {
     userGates: string[];
     nextAgentSteps: string[];
     antiPatterns: string[];
+    /** Present only without engine tools: what this session can and cannot do. */
+    profileNote?: string;
 }
 export declare function buildGameTaskPlan(options: GameTaskPlanOptions): GameTaskPlan;