summer-engine 3.7.0 → 3.8.0

package/dist/core/capabilities/apps.js

@@ -0,0 +1,340 @@
+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 { TOOLKIT_VERSION } from "../version.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("all")
+        .describe("One part of the guide: overview, manifest, sdk, kit, layout, design, examples, or types (the SDK's exact TypeScript types, not in all). Default all"),
+});
+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"),
+    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: "unauthorized", message: "Not signed in. Run: npx -y summer-engine@latest login" } },
+            };
+        const gateway = await resolveGatewayUrl();
+        const suffix = query?.toString() ? `?${query.toString()}` : "";
+        let response;
+        try {
+            response = await fetch(`${gateway}${endpoint}${suffix}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "X-Summer-Client": "summer-cli",
+                    "X-Summer-Client-Version": TOOLKIT_VERSION,
+                    "X-Summer-Client-Surface": surface,
+                    "X-Summer-MCP-Endpoint": endpoint,
+                    "X-Summer-MCP-Tool": tool,
+                    ...(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: ${error instanceof Error ? error.message : String(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. */
+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 hints = {
+        unauthorized: "Run: npx -y summer-engine@latest login",
+        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.",
+    };
+    const { error: _error, message: _message, ...rest } = reply.data;
+    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/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/tool-dispatch.js

@@ -76,6 +76,8 @@ import { attachToSurface, attachToSurfaceArgsSchema, connectPorts, connectPortsA
 import { readLibraryEntry, readLibraryInputSchema } from "../library-read.js";
 import { runSearchLibrary, searchLibraryInputSchema } from "../library-search.js";
 import { TOOLKIT_VERSION as CLI_VERSION } from "../version.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 {
 }
@@ -404,6 +406,14 @@ async function gatewayReply(call) {
         return { error: error.message, status: 0 };
     }
 }
+/** summer tool app-screenshot: the PNG goes to `out` (default ./summer-app-screenshot.png), not into the printed JSON. */
+async function cliScreenshot(args, deps) {
+    const shot = await appScreenshot({ ...args, out: args.out ?? "summer-app-screenshot.png" }, deps);
+    if (shot.ok !== true || !("image" in shot))
+        return shot;
+    const { image: _image, ...report } = shot;
+    return report;
+}
 function sfxChoicesDeps() {
     return {
         post: (endpoint, body, timeoutMs) => gatewayReply(() => gatewayPost(endpoint, body, timeoutMs)),
@@ -906,6 +916,45 @@ export const TOOL_DISPATCH = [
             throw new ToolResultError(result, String(result.error));
         return result;
     }),
+    // Summer Apps (core/capabilities/apps.ts): the same functions as the MCP face.
+    ...[
+        ["summer_app_guide", "Read the Summer Apps build guide (SDK, manifest, kit, layout, design, examples)", appGuideArgsSchema, appGuide],
+        ["summer_app_list", "List the Summer Apps in the person's workspaces", appListArgsSchema, appList],
+        ["summer_app_create", "Create a scratch Summer App and open it in Summer Studio", appCreateArgsSchema, appCreate],
+        ["summer_app_publish", "Publish a new version of a Summer App from a folder or files", appPublishArgsSchema, appPublish],
+        ["summer_app_get", "Read a Summer App's manifest, files and data summary", appGetArgsSchema, appGet],
+        ["summer_app_update", "Rename a Summer App or keep, archive or restore it", appUpdateArgsSchema, appUpdate],
+        ["summer_app_events", "Wait for events a Summer App sends to agents", appEventsArgsSchema, appEvents],
+        ["summer_app_page", "Read or use the open app's declared fields and buttons", appPageArgsSchema, appPage],
+        ["summer_app_data", "Read or write a Summer App's shared data", appDataArgsSchema, appData],
+        ["summer_app_screenshot", "See a Summer App rendered (read-only) with its console and errors; out saves the PNG", appScreenshotArgsSchema, cliScreenshot],
+        ["summer_app_tools", "List a Summer App's agent tools", appToolsArgsSchema, appTools],
+        ["summer_app_call", "Run a Summer App's agent tool in the person's open app", appCallArgsSchema, appCall],
+        ["summer_app_report_gap", "Report an SDK capability a Summer App needed", appReportGapArgsSchema, appReportGap],
+    ].map(([name, summary, schema, run]) => entry(name, summary, false, async (args) => {
+        const result = await run(parseToolArgs(schema, args, name.replace(/^summer_/, "").replace(/_/g, "-")), { request: appsGateway("cli", name) });
+        if (result.ok !== true)
+            throw new ToolResultError(result, String(result.error));
+        return result;
+    })),
+    entry("summer_enable_plugin", "Enable an editor plugin and report whether it really loaded", true, async (args, ctx) => {
+        const parsed = parseToolArgs(enablePluginArgsSchema, args, "enable-plugin");
+        const result = interpretEnablePluginResult(await (await ctx.engine()).executeOps([enablePluginOp(parsed)]));
+        if (result.ok !== true)
+            throw new ToolResultError(result, String(result.error));
+        return result;
+    }),
+    entry("summer_app_dock", "Dock a Summer App in the editor, close its dock, or list docks", true, async (args, ctx) => {
+        const parsed = parseToolArgs(appDockArgsSchema, args, "app-dock");
+        if (parsed.action !== "list" && !parsed.appId)
+            throw new ToolDispatchError(`${parsed.action} needs appId`);
+        const op = appDockOp(parsed);
+        const client = await ctx.engine();
+        const missing = missingEngineOpResult(client, op.op, APP_DOCK_FALLBACK);
+        if (missing)
+            throw new ToolResultError({ ...missing }, missing.error);
+        return requireEngineSuccess(await client.executeOps([op]));
+    }),
     entry("summer_generate_3d", "Generate a 3D model (optional auto-rig + animations)", false, async (args) => {
         const options = {
             ...(args.options ?? {}),

package/dist/core/capability-skew.js

@@ -49,6 +49,10 @@ export const CLI_KNOWN_OP_NEEDS = [
     // engine's one-table op; the other three are the legacy
     // fallbacks on engines that predate it.
     "Navigate", "OpenResource", "FocusDock", "RevealInFileSystem",
+    // Summer Apps editor docks (summer_app_dock: core/capabilities/apps.ts)
+    "OpenAppDock", "CloseAppDock", "ListAppDocks",
+    // summer_enable_plugin (core/capabilities/enable-plugin.ts)
+    "EnableEditorPlugin",
     // Project + input
     "ProjectSetting", "InputMapAddAction", "InputMapBind",
     // Files (summer_write_file / summer_replace_text / summer_create_scene)

package/dist/mcp/hosted-mount.js

@@ -1,4 +1,4 @@
-import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { connectHostedMcp } from "../core/hosted-mcp.js";
 import { getStoreAccessToken, OAuthError, resolveMcpResourceUrl } from "../core/oauth.js";
@@ -79,6 +79,18 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
             };
         });
     }
+    // tools/call for a name the server does not know yet: a hosted tool whose mount
+    // is still running (an agent that calls before it lists). Wait for that mount,
+    // at most the first-list cap, then dispatch; an unknown name still errors.
+    const callTool = handlers.get("tools/call");
+    if (callTool) {
+        server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            const name = request.params?.name;
+            if (typeof name === "string" && !(name in registries._registeredTools))
+                await waitForMount(firstListWaitMs);
+            return (await callTool(request, extra));
+        });
+    }
     let statusTool = null;
     let running = null;
     /** Wait for a mount in progress, at most ms; returns at once when none runs. */

package/dist/mcp/server.js

@@ -16,6 +16,7 @@ import { registerEventTools } from "./tools/event-tools.js";
 import { registerFabricateTools } from "./tools/fabricate-tools.js";
 import { registerUiTools } from "./tools/ui-tools.js";
 import { registerRuntimeTools } from "./tools/runtime-tools.js";
+import { registerAppTools } from "./tools/app-tools.js";
 import { recordToolCall, registrationHasInputSchema, trajectoryArgsFor, } from "../core/trajectory.js";
 import { registerFileTools } from "./tools/file-tools.js";
 import { registerAssetTools } from "./tools/asset-tools.js";
@@ -328,6 +329,7 @@ export function createMcpServer() {
     registerFabricateTools(server);
     registerUiTools(server);
     registerRuntimeTools(server);
+    registerAppTools(server);
     // The playbook is also an MCP prompt so prompt-surfacing hosts get it
     // natively (same content as the summer_get_agent_playbook tool).
     registerPlaybookPrompt(server);

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

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

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

@@ -0,0 +1,64 @@
+import { MAX_APP_EVENTS_WAIT_SECONDS, APP_DOCK_FALLBACK, appCall, appCallArgsSchema, appCreate, appCreateArgsSchema, appData, appDataArgsSchema, appDockArgsSchema, appDockOp, appEvents, appEventsArgsSchema, appGet, appGetArgsSchema, appGuide, appGuideArgsSchema, appList, appListArgsSchema, appPage, appPageArgsSchema, appPublish, appPublishArgsSchema, appReportGap, appReportGapArgsSchema, appScreenshot, appScreenshotArgsSchema, appUpdate, appUpdateArgsSchema, appsGateway, appTools, appToolsArgsSchema, } from "../../core/capabilities/apps.js";
+import { enablePluginArgsSchema, enablePluginOp, interpretEnablePluginResult } from "../../core/capabilities/enable-plugin.js";
+import { missingEngineOpResult, withEngine } from "./with-engine.js";
+/**
+ * Summer Apps over MCP: tools a game team uses inside Summer Studio, built by
+ * the agent. Shared implementation: core/capabilities/apps.ts.
+ */
+const CLOUD = "Cloud tool: runs on Summer's servers and works without the Summer Engine app open. Requires sign-in: npx -y summer-engine@latest login.";
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], ...(value.ok === false ? { isError: true } : {}) };
+}
+/** The MCP handler of one cloud tool: validate with the shared schema, call the web API. */
+function cloud(name, schema, run) {
+    return async (args) => {
+        const parsed = schema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        return result(await run(parsed.data, { request: appsGateway("mcp", name) }));
+    };
+}
+export function registerAppTools(server) {
+    server.tool("summer_app_guide", `Read this before building or changing a Summer App (a tool for the person's team inside Summer Studio, live on their assets, game data and engine): when to build one, Layout vs code, the build loop, manifest schema, SDK reference, UI kit, layout format, design rules and four worked examples. section returns one part.\n\n${CLOUD}`, appGuideArgsSchema.shape, cloud("summer_app_guide", appGuideArgsSchema, appGuide));
+    server.tool("summer_app_list", `The Summer Apps in the person's workspaces: id, name, purpose, folder, status (scratch, kept, archived), version, format.\n\n${CLOUD}`, appListArgsSchema.shape, cloud("summer_app_list", appListArgsSchema, appList));
+    server.tool("summer_app_create", `Create a new scratch Summer App; their open Summer Studio tab opens it. Without workspaceId it goes to the person's team (the one their Studio tab is on, else their latest team, else personal); the result's workspace says which: tell the person. Read summer_app_guide first. format code (index.html + JS/CSS) or layout (a JSON layout of kit nodes for a quick decision UI). Then summer_app_publish.\n\n${CLOUD}`, appCreateArgsSchema.shape, cloud("summer_app_create", appCreateArgsSchema, appCreate));
+    server.tool("summer_app_publish", `Publish a new immutable version of a Summer App: dir (a local folder with index.html at its root) or files [{path, content, encoding}] for code apps, layout for layout apps, plus the manifest. Limits: 10 MB, 300 files, 5 MB per file. The person's Studio tab boots it. An error names the file or rule to fix: fix it and publish again.\n\n${CLOUD}`, appPublishArgsSchema.shape, cloud("summer_app_publish", appPublishArgsSchema, appPublish));
+    server.tool("summer_app_get", `A Summer App's manifest, its current version's files (or layout) and a summary of its shared data. Use it before changing an app.\n\n${CLOUD}`, appGetArgsSchema.shape, cloud("summer_app_get", appGetArgsSchema, appGet));
+    server.tool("summer_app_update", `Rename a Summer App, change its purpose or folder, or set its status: kept (the team keeps it), archived (hidden from the app list; restore with scratch or kept), scratch. Archive the scratch apps you made that the person did not keep.\n\n${CLOUD}`, appUpdateArgsSchema.shape, cloud("summer_app_update", appUpdateArgsSchema, appUpdate));
+    server.tool("summer_app_events", `Wait for what a Summer App sends you: summer.agent.send events (kind agent), errors in the app (kind error), feedback (kind feedback), agent tool calls (kind tool). Waits up to timeoutSeconds (max ${MAX_APP_EVENTS_WAIT_SECONDS}) for the first event after the cursor; pass the returned cursor as after next time.\n\n${CLOUD}`, appEventsArgsSchema.shape, cloud("summer_app_events", appEventsArgsSchema, appEvents));
+    server.tool("summer_app_page", `Read or use the fields and buttons a Summer App declared while it is open in the person's Studio tab or editor dock: no fill and no press reads the page; fill [{field, value}] and press an action id use it. Critical actions (delete, publish, pay, send) are pressed only by the person. app_not_open when the app is not open.\n\n${CLOUD}`, appPageArgsSchema.shape, cloud("summer_app_page", appPageArgsSchema, appPage));
+    server.tool("summer_app_screenshot", `See a Summer App without the person: Summer renders its current version (or version) headless with the person's data and returns the picture plus what to fix: console lines, uncaught errors, refused calls, whether the SDK connected and rendered, and the fields, buttons and agent tools it declared. Read-only: writes, sends and paid calls are refused, nothing changes. width 390 for a phone, theme dark, fullPage for the whole scroll; out also saves the PNG. Use it after every publish.\n\n${CLOUD}`, appScreenshotArgsSchema.shape, async (args) => {
+        const parsed = appScreenshotArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        const shot = await appScreenshot(parsed.data, { request: appsGateway("mcp", "summer_app_screenshot") });
+        if (shot.ok !== true || !("image" in shot))
+            return result(shot);
+        const { image, ...report } = shot;
+        return { content: [{ type: "image", data: image.base64, mimeType: image.mimeType }, { type: "text", text: JSON.stringify(report, null, 2) }] };
+    });
+    server.tool("summer_app_data", `Read or write a Summer App's shared data, its API: works with no app open, and everyone in the app sees writes live. Without ops it reads records (paged with after) plus declaredCollections, the record shape the app declares; with ops it writes them in one revision: {op: put|patch|remove, collection, recordId, data|patch, ifRevision?}. Writes show as yours (actor kind agent); as: seed writes starter data for the team (kind seed, no author).\n\n${CLOUD}`, appDataArgsSchema.shape, cloud("summer_app_data", appDataArgsSchema, appData));
+    server.tool("summer_app_tools", `The agent tools (name, description, input JSON Schema) and the data collections (record fields and types) a Summer App declares. Run a tool with summer_app_call; read or write the collections with summer_app_data.\n\n${CLOUD}`, appToolsArgsSchema.shape, cloud("summer_app_tools", appToolsArgsSchema, appTools));
+    server.tool("summer_app_call", `Run one of a Summer App's agent tools inside the person's open app (Studio tab or editor dock) with their rights; waits up to 60 s. app_not_open when the app is not open: use summer_app_data or ask the person to open it. May spend the person's credits when the tool generates.\n\n${CLOUD}`, appCallArgsSchema.shape, cloud("summer_app_call", appCallArgsSchema, appCall));
+    server.tool("summer_app_report_gap", `Tell Summer about an SDK capability a Summer App needed and did not have, so it can be built for everyone.\n\n${CLOUD}`, appReportGapArgsSchema.shape, cloud("summer_app_report_gap", appReportGapArgsSchema, appReportGap));
+    server.tool("summer_app_dock", `Dock a Summer App as a panel in the running Summer Engine editor (left, right or bottom), close its dock, or list docked apps. Docks persist per project. Engine builds without app docks return engine_lacks_op: open the app in the Summer Studio tab instead.`, appDockArgsSchema.shape, async (args) => {
+        const parsed = appDockArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        if (parsed.data.action !== "list" && !parsed.data.appId)
+            return result({ ok: false, code: "invalid", error: `${parsed.data.action} needs appId` });
+        const op = appDockOp(parsed.data);
+        return withEngine(async (client) => {
+            const missing = missingEngineOpResult(client, op.op, APP_DOCK_FALLBACK);
+            if (missing)
+                return missing;
+            return client.executeOps([op]);
+        });
+    });
+    server.tool("summer_enable_plugin", `Enable an editor plugin in the open project (res://addons/<name>/, for example one paired with a Summer App) and report the real result: enabled with the autoloads it registered, or why it failed (code SCRIPT_ERROR, NOT_TOOL, NOT_EDITOR_PLUGIN, CFG_MISSING, TIMEOUT, ...). Older Summer Engine builds only queue the enable; then the result says queued: true and enabled: null, and you check summer_get_debugger_errors before relying on the plugin.`, enablePluginArgsSchema.shape, async (args) => {
+        const parsed = enablePluginArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        return withEngine(async (client) => interpretEnablePluginResult(await client.executeOps([enablePluginOp(parsed.data)])));
+    });
+}