summer-engine 3.8.0 → 4.2.0

package/dist/core/agent-host.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Which agent app runs Summer (Claude Code, Codex, Cursor, ...) and which tool
+ * made a request, sent as headers on every request to Summer's servers
+ * (summerengine.com and the hosted Summer Engine MCP), so usage can be
+ * counted per agent app and per tool.
+ *
+ * The server reads X-Summer-Agent-Host / X-Summer-Agent-Host-Source
+ * (publicsummerengine src/lib/mcp/agent-host.ts) into the attribution of the
+ * usage rows a request causes, and X-Summer-MCP-Tool on generation errors.
+ * X-Summer-Agent-Host-Name / -Version carry the MCP handshake's clientInfo
+ * as the app sent it.
+ *
+ * Host resolution: SUMMER_AGENT_HOST (explicit override), then the MCP
+ * initialize handshake's clientInfo.name, then the environment an agent sets
+ * for the commands it runs (the CLI surface), else "unknown".
+ *
+ * SUMMER_NO_TELEMETRY=1 / DO_NOT_TRACK=1 drop the host and tool headers; the
+ * product headers (X-Summer-Client, -Version, -Surface) stay, like a
+ * user agent.
+ */
+export declare const AGENT_HOST_HEADER = "X-Summer-Agent-Host";
+export declare const AGENT_HOST_SOURCE_HEADER = "X-Summer-Agent-Host-Source";
+export declare const AGENT_HOST_NAME_HEADER = "X-Summer-Agent-Host-Name";
+export declare const AGENT_HOST_VERSION_HEADER = "X-Summer-Agent-Host-Version";
+export declare const MCP_TOOL_HEADER = "X-Summer-MCP-Tool";
+export declare const AGENT_HOST_OVERRIDE_ENV = "SUMMER_AGENT_HOST";
+export type AgentHostSource = "override" | "mcp-client" | "env" | "none";
+export type ClientSurface = "mcp" | "cli";
+export interface AgentHost {
+    id: string;
+    source: AgentHostSource;
+}
+export interface McpClientInfo {
+    name?: string;
+    version?: string;
+}
+type Env = Record<string, string | undefined>;
+/** The opt-out switches, the same two the library feedback mailbox honors. */
+export declare function isTelemetryDisabled(env?: Env): boolean;
+/** Lowercase `[a-z0-9-]`, at most 40 characters: the server's host id shape. */
+export declare function sanitizeHostId(raw: string): string;
+/** A known host id, or "other.<name>" for a client Summer does not know yet. */
+export declare function hostFromClientName(name: string | undefined | null): string | null;
+/** AI_AGENT ("<name>_<version>_<mode>") first, then the per-host variables. */
+export declare function hostFromEnv(env: Env): string | null;
+export declare function registerMcpClientSource(source: (() => McpClientInfo | undefined) | null): void;
+export declare function currentMcpClient(): McpClientInfo | undefined;
+export declare function resolveAgentHost(env?: Env, client?: McpClientInfo | undefined): AgentHost;
+interface ToolContext {
+    tool: string;
+    surface: ClientSurface;
+}
+/** Run one tool call so every Summer request it makes names the tool and surface. */
+export declare function runWithToolContext<T>(tool: string, surface: ClientSurface, fn: () => T): T;
+/** The tool call running now, if any (a tool that runs inside another one sees the outer call). */
+export declare function currentToolContext(): ToolContext | undefined;
+/**
+ * Headers for a request to Summer's servers. `tool` names the tool when no
+ * tool call is running (the endpoint's own tool); a running call's tool wins.
+ */
+export declare function summerRequestHeaders(options?: {
+    tool?: string;
+    surface?: ClientSurface;
+}, env?: Env): Record<string, string>;
+export {};

package/dist/core/agent-host.js

@@ -0,0 +1,193 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { TOOLKIT_VERSION } from "./version.js";
+/**
+ * Which agent app runs Summer (Claude Code, Codex, Cursor, ...) and which tool
+ * made a request, sent as headers on every request to Summer's servers
+ * (summerengine.com and the hosted Summer Engine MCP), so usage can be
+ * counted per agent app and per tool.
+ *
+ * The server reads X-Summer-Agent-Host / X-Summer-Agent-Host-Source
+ * (publicsummerengine src/lib/mcp/agent-host.ts) into the attribution of the
+ * usage rows a request causes, and X-Summer-MCP-Tool on generation errors.
+ * X-Summer-Agent-Host-Name / -Version carry the MCP handshake's clientInfo
+ * as the app sent it.
+ *
+ * Host resolution: SUMMER_AGENT_HOST (explicit override), then the MCP
+ * initialize handshake's clientInfo.name, then the environment an agent sets
+ * for the commands it runs (the CLI surface), else "unknown".
+ *
+ * SUMMER_NO_TELEMETRY=1 / DO_NOT_TRACK=1 drop the host and tool headers; the
+ * product headers (X-Summer-Client, -Version, -Surface) stay, like a
+ * user agent.
+ */
+export const AGENT_HOST_HEADER = "X-Summer-Agent-Host";
+export const AGENT_HOST_SOURCE_HEADER = "X-Summer-Agent-Host-Source";
+export const AGENT_HOST_NAME_HEADER = "X-Summer-Agent-Host-Name";
+export const AGENT_HOST_VERSION_HEADER = "X-Summer-Agent-Host-Version";
+export const MCP_TOOL_HEADER = "X-Summer-MCP-Tool";
+export const AGENT_HOST_OVERRIDE_ENV = "SUMMER_AGENT_HOST";
+/** The opt-out switches, the same two the library feedback mailbox honors. */
+export function isTelemetryDisabled(env = process.env) {
+    return env.SUMMER_NO_TELEMETRY === "1" || env.DO_NOT_TRACK === "1";
+}
+const set = (env, key) => {
+    const value = env[key];
+    return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+};
+/**
+ * Variables hosts set for the commands they run, most specific first (the
+ * convention @vercel/detect-agent reads). CURSOR_TRACE_ID is last: Cursor sets
+ * it in every integrated terminal, so Claude Code or Codex inside Cursor wins.
+ */
+const ENV_SIGNALS = [
+    { id: "claude-code", test: (e) => set(e, "CLAUDECODE") || set(e, "CLAUDE_CODE") || set(e, "CLAUDE_CODE_ENTRYPOINT") },
+    { id: "codex", test: (e) => set(e, "CODEX_SANDBOX") || set(e, "CODEX_CI") || set(e, "CODEX_THREAD_ID") },
+    { id: "gemini-cli", test: (e) => set(e, "GEMINI_CLI") },
+    { id: "antigravity", test: (e) => set(e, "ANTIGRAVITY_AGENT") },
+    { id: "augment", test: (e) => set(e, "AUGMENT_AGENT") },
+    { id: "opencode", test: (e) => set(e, "OPENCODE_CLIENT") },
+    { id: "github-copilot", test: (e) => set(e, "COPILOT_MODEL") || set(e, "COPILOT_ALLOW_ALL") || set(e, "COPILOT_GITHUB_TOKEN") },
+    { id: "cursor", test: (e) => set(e, "CURSOR_AGENT") || e.CURSOR_EXTENSION_HOST_ROLE === "agent-exec" },
+    { id: "replit", test: (e) => set(e, "REPL_ID") },
+    { id: "cursor", test: (e) => set(e, "CURSOR_TRACE_ID") },
+];
+/**
+ * clientInfo.name patterns (lowercased), most specific first. Names are what
+ * each app sends in `initialize`, matched loosely so a renamed build lands.
+ */
+const MCP_CLIENT_PATTERNS = [
+    { id: "claude-code", pattern: /claude[-_ ]?code/ },
+    { id: "claude-desktop", pattern: /^claude(-ai)?$|claude[-_ ]desktop/ },
+    { id: "codex", pattern: /codex/ },
+    { id: "cursor", pattern: /cursor/ },
+    { id: "windsurf", pattern: /windsurf|codeium|cascade|devin/ },
+    { id: "gemini-cli", pattern: /gemini/ },
+    { id: "antigravity", pattern: /antigravity/ },
+    { id: "openclaw", pattern: /openclaw|clawdbot|moltbot/ },
+    { id: "hermes", pattern: /hermes/ },
+    { id: "grok", pattern: /grok/ },
+    { id: "chatgpt", pattern: /chatgpt|openai/ },
+    { id: "roo-code", pattern: /roo[-_ ]?(code|cline)/ },
+    { id: "kilo-code", pattern: /kilo/ },
+    { id: "cline", pattern: /cline/ },
+    { id: "github-copilot", pattern: /copilot/ },
+    { id: "vscode", pattern: /visual studio code|vscode/ },
+    { id: "visual-studio", pattern: /visual studio/ },
+    { id: "zed", pattern: /\bzed\b/ },
+    { id: "opencode", pattern: /opencode/ },
+    { id: "goose", pattern: /goose/ },
+    { id: "amp", pattern: /\bamp\b/ },
+    { id: "kiro", pattern: /kiro/ },
+    { id: "trae", pattern: /trae/ },
+    { id: "qwen-code", pattern: /qwen/ },
+    { id: "kimi-code", pattern: /kimi/ },
+    { id: "crush", pattern: /crush/ },
+    { id: "factory", pattern: /factory|droid/ },
+    { id: "junie", pattern: /junie|jetbrains/ },
+    { id: "warp", pattern: /warp/ },
+    { id: "rovo-dev", pattern: /rovo/ },
+    { id: "qoder", pattern: /qoder/ },
+    { id: "mistral-vibe", pattern: /mistral|vibe/ },
+    { id: "lm-studio", pattern: /lm[-_ ]?studio/ },
+    { id: "continue", pattern: /continue/ },
+    { id: "augment", pattern: /augment/ },
+    { id: "replit", pattern: /replit/ },
+];
+/** Lowercase `[a-z0-9-]`, at most 40 characters: the server's host id shape. */
+export function sanitizeHostId(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+}
+function matchClientPattern(name) {
+    const lower = name.toLowerCase();
+    return MCP_CLIENT_PATTERNS.find(({ pattern }) => pattern.test(lower))?.id ?? null;
+}
+/** A known host id, or "other.<name>" for a client Summer does not know yet. */
+export function hostFromClientName(name) {
+    if (!name)
+        return null;
+    const known = matchClientPattern(name);
+    if (known)
+        return known;
+    const fallback = sanitizeHostId(name);
+    return fallback ? `other.${fallback}` : null;
+}
+/** AI_AGENT ("<name>_<version>_<mode>") first, then the per-host variables. */
+export function hostFromEnv(env) {
+    if (env.AI_AGENT) {
+        const declared = hostFromClientName(env.AI_AGENT.split("_")[0]);
+        if (declared)
+            return declared;
+    }
+    return ENV_SIGNALS.find(({ test }) => test(env))?.id ?? null;
+}
+// The MCP server registers a getter; it is read at request time, after the
+// initialize handshake has given the client's name and version.
+let mcpClientSource = null;
+export function registerMcpClientSource(source) {
+    mcpClientSource = source;
+}
+export function currentMcpClient() {
+    try {
+        return mcpClientSource?.() ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveAgentHost(env = process.env, client = currentMcpClient()) {
+    const override = env[AGENT_HOST_OVERRIDE_ENV] ? sanitizeHostId(env[AGENT_HOST_OVERRIDE_ENV]) : "";
+    if (override)
+        return { id: override, source: "override" };
+    const fromClient = hostFromClientName(client?.name);
+    if (fromClient)
+        return { id: fromClient, source: "mcp-client" };
+    const fromEnv = hostFromEnv(env);
+    if (fromEnv)
+        return { id: fromEnv, source: "env" };
+    return { id: "unknown", source: "none" };
+}
+const toolContext = new AsyncLocalStorage();
+/** Run one tool call so every Summer request it makes names the tool and surface. */
+export function runWithToolContext(tool, surface, fn) {
+    return toolContext.run({ tool, surface }, fn);
+}
+/** The tool call running now, if any (a tool that runs inside another one sees the outer call). */
+export function currentToolContext() {
+    return toolContext.getStore();
+}
+/** Printable ASCII only, so a header value never breaks a request. */
+const headerValue = (value, max) => value.replace(/[^\x20-\x7e]/g, "").trim().slice(0, max);
+/**
+ * Headers for a request to Summer's servers. `tool` names the tool when no
+ * tool call is running (the endpoint's own tool); a running call's tool wins.
+ */
+export function summerRequestHeaders(options = {}, env = process.env) {
+    const context = toolContext.getStore();
+    const surface = context?.surface ?? options.surface ?? (mcpClientSource ? "mcp" : "cli");
+    const headers = {
+        "X-Summer-Client": "summer-cli",
+        "X-Summer-Client-Version": TOOLKIT_VERSION,
+        "X-Summer-Client-Surface": surface,
+    };
+    if (isTelemetryDisabled(env))
+        return headers;
+    const client = surface === "mcp" ? currentMcpClient() : undefined;
+    const host = resolveAgentHost(env, client);
+    headers[AGENT_HOST_HEADER] = host.id;
+    headers[AGENT_HOST_SOURCE_HEADER] = host.source;
+    const name = client?.name ? headerValue(client.name, 64) : "";
+    const version = client?.version ? headerValue(client.version, 32) : "";
+    if (name)
+        headers[AGENT_HOST_NAME_HEADER] = name;
+    if (version)
+        headers[AGENT_HOST_VERSION_HEADER] = version;
+    const tool = context?.tool ?? options.tool;
+    if (tool)
+        headers[MCP_TOOL_HEADER] = tool;
+    return headers;
+}

package/dist/core/capabilities/agent-playbook.d.ts

@@ -15,6 +15,9 @@
 export interface AgentPlaybookOptions {
     /** The MCP layer's cached "Summer update available" notice, if any. */
     summerUpdateNotice?: string | null;
+    /** False for a session without engine tools (the assets profile): the
+     *  playbook then covers finding, generating and handing over files. */
+    engine?: boolean;
 }
 export declare function buildAgentPlaybook(options?: AgentPlaybookOptions): Record<string, unknown>;
 export declare function renderAgentPlaybook(options?: AgentPlaybookOptions): string;

package/dist/core/capabilities/agent-playbook.js

@@ -1,4 +1,6 @@
 export function buildAgentPlaybook(options = {}) {
+    if (options.engine === false)
+        return buildAssetsPlaybook(options);
     return {
         summerUpdateNotice: options.summerUpdateNotice ?? null,
         // ------------------------------------------------------------------
@@ -204,7 +206,7 @@ export function buildAgentPlaybook(options = {}) {
             "summer_get_project_context",
             "Choose the exact res:// scenePath. OpenScene is a user-visible tab action, not a mutation prerequisite.",
             "summer_world_snapshot (keep the snapshot_id) — or summer_get_scene_tree with scenePath for the hierarchy view.",
-            "summer_add_node / summer_set_prop / summer_set_resource_property with scenePath — or one summer_run_script for anything computed.",
+            "3 or more scene edits: one summer_run_script with scenePath (snapshot, script, diff, screenshot). A single tweak: summer_set_prop / summer_set_resource_property with scenePath.",
             "Mutation tools append one final SaveScene; use summer_save_scene only for a standalone save/save-as.",
             "summer_snapshot_diff from_id:<the id> + summer_screenshot — then summer_get_diagnostics.",
         ],
@@ -226,7 +228,7 @@ export function buildAgentPlaybook(options = {}) {
         ],
         // Scene scripting: when one GDScript beats a chain of CRUD ops.
         scripting: [
-            "Single property tweak -> summer_set_prop. Composition or ANY computed placement (3+ related ops, scatter/grids/rings, procedural meshes, bulk edits) -> summer_run_script: one GDScript `func run(ctx):` executed in the LIVE editor against the OPEN scene, with ctx.get_scene_root() / ctx.report(key, value) / print capture.",
+            "Single property tweak -> summer_set_prop. Composition or ANY computed placement (3+ related ops, scatter/grids/rings, procedural meshes, bulk edits) -> summer_run_script: one GDScript `func run(ctx):` executed in the LIVE editor against its scenePath (opened first when needed), with ctx.get_scene_root() / ctx.report(key, value) / print capture.",
             "OWNERSHIP in scripts: call ctx.set_owner_recursive(node) AFTER add_child on every created subtree (manual form: node.owner = root on the node AND each descendant), or the nodes silently vanish on save. The ctx creation helpers (ctx.add_node, ctx.add_mesh, ctx.instance_scene, ...) set the owner for you — prefer them.",
             "Cold batch/project-wide jobs (re-save every scene, resource sweeps, long bakes) -> summer_run_editor_script: a fresh HEADLESS child editor against the ON-DISK project. Unsaved live edits are invisible to it; it has no renderer, so it can never screenshot.",
             "Property/method/signal lookup -> summer_api_docs (offline class reference, stamped with the engine technical base it was generated from). Verify names before scripting instead of guessing; entries list declared members only, so walk `inherits` for inherited ones.",
@@ -259,6 +261,56 @@ export function buildAgentPlaybook(options = {}) {
         ],
     };
 }
+/**
+ * The playbook for the assets profile: the same habits (search the library
+ * first, reuse before generating, confirm spend, never describe an image you
+ * did not receive) without any engine tool, ending at a file the person can
+ * use in any engine or web app.
+ */
+function buildAssetsPlaybook(options) {
+    return {
+        summerUpdateNotice: options.summerUpdateNotice ?? null,
+        profile: "assets",
+        scope: [
+            "This session has generation, the Summer asset library, account and library search, and no Summer Engine tools: no project context, scenes, play, screenshots or imports. You deliver files, not scenes.",
+            "Load the summer-assets skill (summer_read_library skill/summer-assets) for the whole loop.",
+            "If the person wants a game built in Summer Engine, say that needs the full setup: npx -y summer-engine@latest setup <agent> --yes, then open the project in Summer Engine.",
+        ],
+        step0_askFirst: [
+            "Ask once, in one message, what the asset is for: the engine or app, the file format, the size or scale, the style, how many.",
+            "Then summer_search_library for the asset's skill and summer_read_library it before you generate.",
+            "Asset skills are written for Summer Engine too. Follow each one until the asset exists, then read its 'Without Summer Engine' section: skip every step that imports into a project (summer_import_asset_by_id, summer_import_from_url) or adds nodes to a scene (summer_add_node, summer_set_prop). Those tools are not in this session.",
+        ],
+        contentRouting: {
+            priorityOrder: ["1_reuseMyAssets", "2_assetLibrary", "3_generation"],
+            "1_reuseMyAssets": "summer_list_my_assets: the person's own uploads and earlier generations. Never generate an asset they already have.",
+            "2_assetLibrary": "summer_search_assets (source: library | my_assets | all), then summer_get_asset for the hit.",
+            "3_generation": "summer_generate_image / summer_generate_3d / summer_generate_audio / summer_generate_sfx_choices / summer_generate_video / summer_generate_motion, then summer_check_job until the state is terminal (never continue on a pending job), then summer_get_asset with the asset id the job returned (never search by name right after a generation). The summer_tool_* generators load after summer login; when they are missing, summer_store_tools says why.",
+        },
+        handOff: [
+            "summer_generate_image saves the file itself when you pass out (a folder or a file path in the person's project).",
+            "For every other asset, summer_get_asset_download_url (role primary, or thumbnail for a preview) returns a link: download it with your own shell into the folder the person named, and keep a clear file name.",
+            "Formats: GLB for 3D models, PNG, JPG or WebP for images, MP3 or WAV for audio, MP4 for video. Generated models are not at real-world size: give the person the target size.",
+            "Tell the person the path, the format and anything their engine must set (looping, texture filtering, scale).",
+        ],
+        costRules: [
+            "Generation uses the person's Summer credits: say what you will make and how many versions, and wait for a yes. Search and download are free.",
+            "Never run a paid generation again for the same item: download the asset you already have.",
+        ],
+        honestyRules: [
+            "Never describe an image you did not receive. Look at the preview (the localPath of a generated image, or the thumbnail) before you say it looks right; for audio, the person listens.",
+            "A failed or pending job is a result: report its state and error as returned, do not claim the asset exists.",
+        ],
+        doneMeans: [
+            "The job finished without an error.",
+            "You saw the preview, or the person heard the sound.",
+            "The file is where the person asked, and you told them the path and format.",
+        ],
+        libraryFeedback: [
+            "At a natural checkpoint, call summer_library_feedback once with every skill you loaded: 'worked' only after the asset was checked as above, 'worked_with_fixes' with the deviation, 'wrong'/'outdated'/'incomplete' when the entry misled you.",
+        ],
+    };
+}
 export function renderAgentPlaybook(options = {}) {
     return JSON.stringify(buildAgentPlaybook(options), null, 2);
 }

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

@@ -18,9 +18,9 @@ export declare const APP_DOCK_SLOTS: readonly ["left", "right", "bottom"];
 export declare const appGuideArgsSchema: z.ZodObject<{
     section: z.ZodDefault<z.ZodEnum<["all", "overview", "manifest", "sdk", "kit", "layout", "design", "examples", "types"]>>;
 }, "strip", z.ZodTypeAny, {
-    section: "all" | "kit" | "layout" | "examples" | "manifest" | "overview" | "sdk" | "design" | "types";
+    section: "all" | "examples" | "kit" | "layout" | "manifest" | "overview" | "sdk" | "design" | "types";
 }, {
-    section?: "all" | "kit" | "layout" | "examples" | "manifest" | "overview" | "sdk" | "design" | "types" | undefined;
+    section?: "all" | "examples" | "kit" | "layout" | "manifest" | "overview" | "sdk" | "design" | "types" | undefined;
 }>;
 export declare const appListArgsSchema: z.ZodObject<{
     workspaceId: z.ZodOptional<z.ZodString>;
@@ -80,8 +80,8 @@ export declare const appPublishArgsSchema: z.ZodObject<{
         path: string;
         content: string;
     }[] | undefined;
-    idempotencyKey?: string | undefined;
     dir?: string | undefined;
+    idempotencyKey?: string | undefined;
     layout?: Record<string, unknown> | undefined;
 }, {
     manifest: Record<string, unknown>;
@@ -92,8 +92,8 @@ export declare const appPublishArgsSchema: z.ZodObject<{
         content: string;
         encoding?: "utf8" | "base64" | undefined;
     }[] | undefined;
-    idempotencyKey?: string | undefined;
     dir?: string | undefined;
+    idempotencyKey?: string | undefined;
     layout?: Record<string, unknown> | undefined;
 }>;
 export declare const appGetArgsSchema: z.ZodObject<{
@@ -109,15 +109,15 @@ export declare const appEventsArgsSchema: z.ZodObject<{
     timeoutSeconds: z.ZodDefault<z.ZodNumber>;
     kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["agent", "error", "feedback", "tool"]>, "many">>;
 }, "strip", z.ZodTypeAny, {
-    timeoutSeconds: number;
     after: number;
+    timeoutSeconds: number;
     appId: string;
     kinds?: ("error" | "agent" | "tool" | "feedback")[] | undefined;
 }, {
     appId: string;
     kinds?: ("error" | "agent" | "tool" | "feedback")[] | undefined;
-    timeoutSeconds?: number | undefined;
     after?: number | undefined;
+    timeoutSeconds?: number | undefined;
 }>;
 export declare const appPageArgsSchema: z.ZodObject<{
     appId: z.ZodString;
@@ -155,14 +155,14 @@ export declare const appUpdateArgsSchema: z.ZodObject<{
     folder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     appId: string;
-    status?: "scratch" | "kept" | "archived" | undefined;
     name?: string | undefined;
+    status?: "kept" | "scratch" | "archived" | undefined;
     folder?: string | null | undefined;
     purpose?: string | undefined;
 }, {
     appId: string;
-    status?: "scratch" | "kept" | "archived" | undefined;
     name?: string | undefined;
+    status?: "kept" | "scratch" | "archived" | undefined;
     folder?: string | null | undefined;
     purpose?: string | undefined;
 }>;
@@ -174,6 +174,19 @@ export declare const appScreenshotArgsSchema: z.ZodObject<{
     theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
     fullPage: z.ZodDefault<z.ZodBoolean>;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        click: z.ZodOptional<z.ZodString>;
+        press: z.ZodOptional<z.ZodString>;
+        wait: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }, {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }>, "many">>;
     out: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     width: number;
@@ -184,6 +197,11 @@ export declare const appScreenshotArgsSchema: z.ZodObject<{
     version?: number | undefined;
     params?: Record<string, string> | undefined;
     out?: string | undefined;
+    steps?: {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }[] | undefined;
 }, {
     appId: string;
     version?: number | undefined;
@@ -192,6 +210,11 @@ export declare const appScreenshotArgsSchema: z.ZodObject<{
     params?: Record<string, string> | undefined;
     out?: string | undefined;
     theme?: "light" | "dark" | undefined;
+    steps?: {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }[] | undefined;
     fullPage?: boolean | undefined;
 }>;
 export declare const appDataArgsSchema: z.ZodObject<{
@@ -205,16 +228,16 @@ export declare const appDataArgsSchema: z.ZodObject<{
     limit: number;
     appId: string;
     ops?: Record<string, unknown>[] | undefined;
-    after?: string | undefined;
     as?: "seed" | "agent" | undefined;
     collection?: string | undefined;
+    after?: string | undefined;
 }, {
     appId: string;
     ops?: Record<string, unknown>[] | undefined;
     limit?: number | undefined;
-    after?: string | undefined;
     as?: "seed" | "agent" | undefined;
     collection?: string | undefined;
+    after?: string | undefined;
 }>;
 export declare const appToolsArgsSchema: z.ZodObject<{
     appId: z.ZodString;

package/dist/core/capabilities/apps.js

@@ -3,7 +3,8 @@ 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";
+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
@@ -30,8 +31,8 @@ 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"),
+        .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"),
@@ -96,6 +97,11 @@ export const appScreenshotArgsSchema = z.object({
     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({
@@ -136,7 +142,7 @@ export function appsGateway(surface, tool) {
             return {
                 ok: false,
                 status: 401,
-                data: { error: { code: "unauthorized", message: "Not signed in. Run: npx -y summer-engine@latest login" } },
+                data: { error: { code: "not_signed_in", message: NOT_SIGNED_IN } },
             };
         const gateway = await resolveGatewayUrl();
         const suffix = query?.toString() ? `?${query.toString()}` : "";
@@ -145,12 +151,9 @@ export function appsGateway(surface, tool) {
             response = await fetch(`${gateway}${endpoint}${suffix}`, {
                 method,
                 headers: {
+                    ...summerRequestHeaders({ tool, surface }),
                     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) } : {}),
@@ -158,7 +161,7 @@ export function appsGateway(surface, tool) {
             });
         }
         catch (error) {
-            return { ok: false, status: 0, data: { error: { code: "unavailable", message: `Request failed: ${error instanceof Error ? error.message : String(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 = {};
@@ -171,21 +174,31 @@ export function appsGateway(surface, tool) {
         return { ok: response.ok, status: response.status, data };
     };
 }
-/** The server's `{error: {code, message}}` as one flat result an agent can act on. */
+/** 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 = {
-        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));

package/dist/core/capabilities/audit/args.d.ts

@@ -71,10 +71,10 @@ export declare const sceneAuditArgsSchema: z.ZodObject<{
     limit?: number | undefined;
     root?: string | undefined;
     scenePath?: string | undefined;
-    render?: "none" | "sheet" | undefined;
-    checks?: ("resource" | "through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights" | "transform")[] | undefined;
-    min_severity?: "error" | "warn" | "look" | undefined;
     offset?: number | undefined;
+    min_severity?: "error" | "warn" | "look" | undefined;
+    render?: "none" | "sheet" | undefined;
+    checks?: ("resource" | "transform" | "through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights")[] | undefined;
     budget_ms?: number | undefined;
     show_accepted?: boolean | undefined;
 }, {
@@ -85,10 +85,10 @@ export declare const sceneAuditArgsSchema: z.ZodObject<{
     limit?: number | undefined;
     root?: string | undefined;
     scenePath?: string | undefined;
-    render?: "none" | "sheet" | undefined;
-    checks?: ("resource" | "through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights" | "transform")[] | undefined;
-    min_severity?: "error" | "warn" | "look" | undefined;
     offset?: number | undefined;
+    min_severity?: "error" | "warn" | "look" | undefined;
+    render?: "none" | "sheet" | undefined;
+    checks?: ("resource" | "transform" | "through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights")[] | undefined;
     budget_ms?: number | undefined;
     show_accepted?: boolean | undefined;
 }>;

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