summer-engine 4.3.0 → 4.6.0

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

@@ -20,11 +20,13 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
 import { EngineApiClient } from "../api-client.js";
-import { CLI_RECOVERY, codedFailure, codeForStatus, describeNetworkError, engineNotRunningFromConnectError, networkDetails, NOT_SIGNED_IN, } from "../error-codes.js";
+import { CLI_RECOVERY, codedFailure, codeForStatus, describeNetworkError, EngineNotRunningError, engineNotRunningFromConnectError, networkDetails, NOT_SIGNED_IN, } from "../error-codes.js";
+import { engineSelectionFromEnv } from "../engine.js";
 import { missingEngineEventsResult, missingEngineOpResult, } from "../capability-skew.js";
 import { buildAgentPlaybook } from "./agent-playbook.js";
 import { recentEvents, recentEventsArgsSchema, waitForEvent, waitForEventArgsSchema, } from "./events.js";
 import { importResolvedAsset } from "./asset-import.js";
+import { importUrls } from "./video-ogv.js";
 import { executeSceneMutation, occurrenceCount, readTextPayload, safeProjectPath, validSha256, } from "./engine-ops.js";
 import { extractOpError, withOldEngineHint } from "./engine-receipt.js";
 import { lookupApiDocs } from "./api-docs.js";
@@ -52,7 +54,13 @@ import { shapeEngineLogResponse } from "../log-filters.js";
 import { exportGame } from "./export-game.js";
 import { exportTemplates } from "./export-templates.js";
 import { captureGameplay } from "./capture-gameplay.js";
+import { goLive } from "./go-live.js";
 import { publishBuild } from "./publish-build.js";
+import { DETAIL_SECTIONS, setStoreDetails } from "./store-details.js";
+import { syncItems } from "./sync-items.js";
+import { contentMake, contentMakeInput } from "./content-make/index.js";
+import { createLocalProject, LocalProjectError, localProjectFailure, openLocalProject } from "./projects-local.js";
+import { BuildToolError, buildToolFailure } from "./summer-bundle.js";
 import { resolveGatewayUrl } from "../config.js";
 import { createDebugReportArtifact } from "./debug-report.js";
 import { buildGameTaskPlan, gameTaskPlanInputSchema } from "./game-task-plan.js";
@@ -105,6 +113,32 @@ export class CodedToolError extends ToolResultError {
         super(codedFailure(code, message, extra, recovery), message);
     }
 }
+/** A creator tool's BuildToolError as a ToolResultError, so `summer tool` and
+ *  `summer <area> <action>` print its whole structured failure (code,
+ *  recovery and detail such as a manifest's problem list), as the MCP face does. */
+async function structuredBuildFailure(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof BuildToolError)
+            throw new ToolResultError(buildToolFailure(error), error.message);
+        throw error;
+    }
+}
+/** projects.create_local / open_local: their coded failures, printed whole. */
+async function localProjectStep(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof LocalProjectError)
+            throw new ToolResultError(localProjectFailure(error), error.message);
+        if (error instanceof EngineNotRunningError)
+            throw new CodedToolError("engine_not_running", error.message, {}, error.recovery);
+        throw error;
+    }
+}
 /** The local engine is not reachable — a clean state, not a crash. Prints
  *  `{ok:false, code:"engine_not_running", error, recovery, hint}`. */
 export class EngineUnavailableError extends CodedToolError {
@@ -715,6 +749,34 @@ export const TOOL_DISPATCH = [
         ...(typeof args.waitSeconds === "number" ? { waitSeconds: args.waitSeconds } : {}),
         face: "cli",
     })),
+    entry("summer_go_live", "Take your store game live: release its Build and publish its page, then watch until players get it (confirm-gated)", false, (args) => structuredBuildFailure(() => goLive({
+        gameId: optStr(args, "gameId"),
+        publicationId: optStr(args, "publicationId"),
+        confirm: args.confirm === true,
+        ...(typeof args.waitSeconds === "number" ? { waitSeconds: args.waitSeconds } : {}),
+        face: "cli",
+    }))),
+    entry("summer_store_set_details", "Fill store page sections: genres, features, credits, languages, requirements, content survey, AI disclosure", false, (args) => structuredBuildFailure(() => setStoreDetails({
+        gameId: optStr(args, "gameId"),
+        ...Object.fromEntries(DETAIL_SECTIONS.filter((section) => args[section] !== undefined).map((section) => [section, args[section]])),
+        face: "cli",
+    }))),
+    entry("summer_sync_items", "Sync summer.items.json to your store game by slug; the owner approves (confirm-gated)", false, (args) => 
+    // The same structured failure the MCP face gives (a manifest's whole problem list), printed whole.
+    structuredBuildFailure(() => syncItems({
+        gameId: optStr(args, "gameId"),
+        project: optStr(args, "project"),
+        file: optStr(args, "file"),
+        ...(Array.isArray(args.slugs) ? { slugs: args.slugs.filter((slug) => typeof slug === "string") } : {}),
+        confirm: args.confirm === true,
+        face: "cli",
+    }))),
+    entry("summer_projects_create_local", "Create a Summer project on this computer from a template (3d-basic by default)", false, (args) => localProjectStep(() => createLocalProject({ template: optStr(args, "template"), name: optStr(args, "name"), dir: optStr(args, "dir") }))),
+    entry("summer_projects_open_local", "Open a project in Summer Engine and wait until it connects; install:true installs a missing engine (only after the person's yes)", false, (args) => localProjectStep(() => openLocalProject({ path: optStr(args, "path"), install: args.install === true }, engineSelectionFromEnv() ?? { cwd: process.cwd() }, 
+    // A shell command waits for the whole install and first open, like `summer dev`
+    // (the MCP answers "call again" instead, to stay within a tool call).
+    { waitMs: args.install === true ? 60 * 60_000 : 180_000 }))),
+    entry("summer_content_make", "Make one finished piece of content for a game, beat for beat on a reference, from local footage, into the team's Review", false, (args) => structuredBuildFailure(() => contentMake({ ...contentMakeInput(args), face: "cli" }))),
     // --- debug ---
     entry("summer_get_diagnostics", "Overview of editor console and runtime debugger errors/warnings", true, async (args, ctx) => requireEngineSuccess(await (await ctx.engine()).getDiagnostics())),
     entry("summer_get_console", "Read recent editor Output panel messages (deduplicated)", true, async (args, ctx) => {
@@ -1130,16 +1192,14 @@ export const TOOL_DISPATCH = [
         return requireEngineSuccess(await client.getSceneState(target, { depth, limit }));
     }),
     entry("summer_import_from_url", "Download one file by URL through Godot's import pipeline", true, async (args, ctx) => {
-        const op = { op: "ImportFromUrl", url: str(args, "url") };
-        if (optStr(args, "path"))
-            op.path = args.path;
-        return requireEngineSuccess(await (await ctx.engine()).executeOps([op]));
+        const path = optStr(args, "path");
+        return requireEngineSuccess(await importUrls(await ctx.engine(), [{ url: str(args, "url"), ...(path ? { path } : {}) }], { batch: false }));
     }),
     entry("summer_import_from_url_batch", "Download multiple files by URL in one operation", true, async (args, ctx) => {
         if (!Array.isArray(args.imports)) {
             throw new ToolDispatchError("imports must be an array of {url, path} objects");
         }
-        return requireEngineSuccess(await (await ctx.engine()).executeOps([{ op: "ImportFromUrlBatch", imports: args.imports }]));
+        return requireEngineSuccess(await importUrls(await ctx.engine(), args.imports, { batch: true }));
     }),
     // --- scene ---
     entry("summer_create_scene", "Create a new minimal .tscn with a create-only guard", true, async (args, ctx) => {

package/dist/core/capabilities/video-ogv.d.ts

@@ -0,0 +1,49 @@
+/** Cloudinary's rendition: at most 1920x1080, Theora + Vorbis, same frame rate. */
+export declare const OGV_TRANSFORM = "c_limit,h_1080,w_1920";
+export type ImportEntry = {
+    url: string;
+    path?: string;
+};
+export type VideoConversion = {
+    from: string;
+    to: string;
+    via: "cloudinary" | "ffmpeg" | "summerengine.com";
+};
+/** The part of the engine client this needs. */
+export interface VideoImportClient {
+    executeOps(ops: Record<string, unknown>[]): Promise<unknown>;
+    getProjectRoot?(): string | undefined;
+}
+/** What the conversion runs; tests replace it. */
+export interface VideoOgvDeps {
+    /** The ffmpeg audio encoder for Vorbis when this ffmpeg has Theora, else null. */
+    ffmpegTheora(): Promise<{
+        audio: "libvorbis" | "vorbis" | null;
+    } | null>;
+    /** Run ffmpeg with these arguments. */
+    runFfmpeg(args: string[]): Promise<void>;
+    /** Download a public https file into a hidden file in `dir`; returns its path. */
+    download(url: string, dir: string): Promise<string>;
+    /** Ask summerengine.com for an .ogv of `url`; returns its URL. */
+    convertRemote(url: string): Promise<string>;
+}
+/** True when the entry is a video the engine cannot load (by the URL's file name or the requested path). */
+export declare function isConvertibleVideo(entry: ImportEntry): boolean;
+/** The res:// path the .ogv lands at: the requested path with .ogv, else res://assets/videos/<name>.ogv (the engine's own inference). */
+export declare function ogvResPath(entry: ImportEntry): string;
+/** The .ogv rendition of a Cloudinary video URL, or null when the URL is not one (or is signed). */
+export declare function cloudinaryOgvUrl(raw: string): string | null;
+/** ffmpeg arguments: Theora q8 video, Vorbis q5 audio when there is audio, same frame rate, at most 1920x1080. */
+export declare function ffmpegOgvArgs(input: string, output: string, audio: "libvorbis" | "vorbis" | null): string[];
+export declare class VideoConvertError extends Error {
+    readonly reason: "not_signed_in" | "remote_failed" | "local_failed";
+    constructor(reason: "not_signed_in" | "remote_failed" | "local_failed", detail?: string);
+}
+/**
+ * Import URLs into the project the way ImportFromUrl / ImportFromUrlBatch do,
+ * converting every video to .ogv first. Without a video the engine gets
+ * exactly the op it got before. `batch` picks ImportFromUrlBatch.
+ */
+export declare function importUrls(client: VideoImportClient, entries: ImportEntry[], options: {
+    batch: boolean;
+}, deps?: VideoOgvDeps): Promise<unknown>;

package/dist/core/capabilities/video-ogv.js

@@ -0,0 +1,260 @@
+/**
+ * Video imports for Summer Engine. The engine plays video only as Ogg Theora
+ * (.ogv): an .mp4, .mov or .webm import never becomes a loadable resource and
+ * the engine rolls it back. Every import path (summer_import_from_url, its
+ * batch, summer_import_asset_by_id, summer_import_asset) runs its entries
+ * through importUrls, which converts a video first, so a video just works:
+ *
+ * 1. A Cloudinary video URL (every video Summer generates or stores) becomes
+ *    its .ogv rendition URL: Cloudinary converts on delivery and the engine
+ *    downloads that. Nothing runs on this computer.
+ * 2. Else, when this computer has an ffmpeg with Theora and the project folder
+ *    is known: download, convert (Theora video q8, Vorbis audio q5, same frame
+ *    rate, at most 1920x1080), write the .ogv into the project and register it
+ *    with the editor.
+ * 3. Else summerengine.com converts it (needs the Summer sign-in) and the
+ *    engine downloads the .ogv it answers.
+ *
+ * The file lands at the requested path with its extension swapped to .ogv,
+ * and the answer says so (videoConversions, note).
+ */
+import { execFile } from "node:child_process";
+import { mkdir, rename, stat, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getAuthToken } from "../auth.js";
+import { resolveGatewayUrl } from "../config.js";
+import { summerRequestHeaders } from "../agent-host.js";
+/** Containers Summer Engine cannot load; .ogv is the one it can. */
+const VIDEO_EXTENSION = /\.(?:mp4|mov|webm|m4v|mkv|avi)$/i;
+/** Cloudinary's rendition: at most 1920x1080, Theora + Vorbis, same frame rate. */
+export const OGV_TRANSFORM = "c_limit,h_1080,w_1920";
+const VIDEO_UPLOAD = "/video/upload/";
+function pathOf(raw) {
+    try {
+        return new URL(raw).pathname;
+    }
+    catch {
+        return raw.split(/[?#]/)[0] ?? raw;
+    }
+}
+/** True when the entry is a video the engine cannot load (by the URL's file name or the requested path). */
+export function isConvertibleVideo(entry) {
+    return VIDEO_EXTENSION.test(pathOf(entry.url)) || (entry.path !== undefined && VIDEO_EXTENSION.test(entry.path));
+}
+/** The res:// path the .ogv lands at: the requested path with .ogv, else res://assets/videos/<name>.ogv (the engine's own inference). */
+export function ogvResPath(entry) {
+    if (entry.path) {
+        const swapped = entry.path.replace(/\.[A-Za-z0-9]+$/, ".ogv");
+        return swapped.toLowerCase().endsWith(".ogv") ? swapped : `${entry.path}.ogv`;
+    }
+    const file = decodeURIComponent(pathOf(entry.url).split("/").pop() || "video");
+    const stem = file.replace(/\.[A-Za-z0-9]+$/, "").replace(/[^\p{L}\p{N}_.-]+/gu, "_") || "video";
+    return `res://assets/videos/${stem}.ogv`;
+}
+/** The .ogv rendition of a Cloudinary video URL, or null when the URL is not one (or is signed). */
+export function cloudinaryOgvUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" || url.hostname !== "res.cloudinary.com" || url.username || url.password || url.port)
+        return null;
+    const at = url.pathname.indexOf(VIDEO_UPLOAD);
+    if (at < 0)
+        return null;
+    const rest = url.pathname.slice(at + VIDEO_UPLOAD.length);
+    // A signed delivery URL stops working when its transformation changes.
+    if (/^s--[^/]+--\//.test(rest))
+        return null;
+    if (!VIDEO_EXTENSION.test(rest) && !rest.toLowerCase().endsWith(".ogv"))
+        return null;
+    const stem = rest.replace(/\.[A-Za-z0-9]+$/, "");
+    if (!stem)
+        return null;
+    const transformed = stem.startsWith(`${OGV_TRANSFORM}/`) ? stem : `${OGV_TRANSFORM}/${stem}`;
+    return `${url.origin}${url.pathname.slice(0, at)}${VIDEO_UPLOAD}${transformed}.ogv`;
+}
+/** ffmpeg arguments: Theora q8 video, Vorbis q5 audio when there is audio, same frame rate, at most 1920x1080. */
+export function ffmpegOgvArgs(input, output, audio) {
+    const audioArgs = audio === "libvorbis"
+        ? ["-map", "0:a:0?", "-c:a", "libvorbis", "-q:a", "5"]
+        : audio === "vorbis"
+            ? ["-map", "0:a:0?", "-c:a", "vorbis", "-strict", "-2", "-ac", "2", "-q:a", "5"]
+            : ["-an"];
+    return [
+        "-v", "error", "-y", "-i", input,
+        "-map", "0:v:0",
+        "-vf", "scale='min(iw,1920)':'min(ih,1080)':force_original_aspect_ratio=decrease:force_divisible_by=2",
+        "-c:v", "libtheora", "-q:v", "8",
+        ...audioArgs,
+        "-f", "ogg", output,
+    ];
+}
+function exec(file, args, timeoutMs) {
+    return new Promise((resolvePromise, reject) => {
+        execFile(file, args, { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error)
+                reject(new Error(String(stderr || error.message).trim().split("\n").slice(-3).join(" ")));
+            else
+                resolvePromise(stdout);
+        });
+    });
+}
+let theoraProbe;
+const defaultDeps = {
+    ffmpegTheora() {
+        theoraProbe ??= exec("ffmpeg", ["-hide_banner", "-encoders"], 15_000).then((out) => (/\blibtheora\b/.test(out) ? { audio: /\blibvorbis\b/.test(out) ? "libvorbis" : /\svorbis\s/.test(out) ? "vorbis" : null } : null), () => null);
+        return theoraProbe;
+    },
+    async runFfmpeg(args) {
+        await exec("ffmpeg", args, 15 * 60_000);
+    },
+    async download(url, dir) {
+        // Loaded here: save-files.ts imports this module too.
+        const { fetchPublicToTemp } = await import("../ops/save-files.js");
+        return (await fetchPublicToTemp(url, dir)).temp;
+    },
+    async convertRemote(url) {
+        const token = await getAuthToken();
+        if (!token)
+            throw new VideoConvertError("not_signed_in");
+        const gateway = await resolveGatewayUrl();
+        const res = await fetch(`${gateway}/api/mcp/video/ogv`, {
+            method: "POST",
+            headers: { ...summerRequestHeaders({ surface: "mcp" }), Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ url }),
+            signal: AbortSignal.timeout(150_000),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok || typeof body.ogvUrl !== "string") {
+            throw new VideoConvertError(res.status === 401 ? "not_signed_in" : "remote_failed", body.message ?? body.error ?? `HTTP ${res.status}`);
+        }
+        return body.ogvUrl;
+    },
+};
+export class VideoConvertError extends Error {
+    reason;
+    constructor(reason, detail) {
+        super(reason === "not_signed_in"
+            ? "Summer Engine plays video only as Ogg Theora (.ogv), and this video needs converting. This computer has no ffmpeg with Theora, so summerengine.com converts it, which needs the Summer sign-in: run npx -y summer-engine@latest login, then import again."
+            : `Summer Engine plays video only as Ogg Theora (.ogv), and converting this video failed: ${detail ?? "unknown error"}.`);
+        this.reason = reason;
+        this.name = "VideoConvertError";
+    }
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Convert on this computer and put the .ogv at `resPath` in the project; returns the RenameFile receipt, or null when the file was moved into place directly. */
+async function convertLocally(client, root, url, resPath, audio, deps) {
+    const dest = join(root, resPath.slice("res://".length));
+    const inside = relative(root, dest);
+    if (inside === "" || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
+        throw new VideoConvertError("local_failed", `${resPath} is outside the project`);
+    }
+    const dir = dirname(dest);
+    await mkdir(dir, { recursive: true });
+    // Hidden names: the editor skips dot files, so it never sees a half-written video.
+    const staging = join(dir, `.summer-video-${randomBytes(6).toString("hex")}.ogv`);
+    const source = await deps.download(url, dir);
+    try {
+        await deps.runFfmpeg(ffmpegOgvArgs(source, staging, audio));
+    }
+    catch (error) {
+        await unlink(staging).catch(() => undefined);
+        throw new VideoConvertError("local_failed", error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await unlink(source).catch(() => undefined);
+    }
+    if (await exists(dest)) {
+        // Already known to the editor: replace its bytes in place.
+        await rename(staging, dest);
+        return { receipt: { ok: true, op: "ImportFromUrl", meta: { path: resPath, replaced: true } } };
+    }
+    // RenameFile registers the new file with the editor's file system (the one op that does so for a file on disk).
+    const stagingRes = `res://${relative(root, staging).split(sep).join("/")}`;
+    try {
+        const receipt = await client.executeOps([{ op: "RenameFile", from: stagingRes, to: resPath }]);
+        const failed = receipt?.status === "error" ||
+            (receipt?.results ?? []).some((result) => result?.ok === false);
+        if (!failed)
+            return { receipt: { ok: true, op: "ImportFromUrl", meta: { path: resPath } } };
+    }
+    catch {
+        // Fall through: the file still goes into place.
+    }
+    if (await exists(staging))
+        await rename(staging, dest);
+    return {
+        receipt: { ok: true, op: "ImportFromUrl", meta: { path: resPath } },
+        note: `${resPath} is on disk; the editor lists it after its next file scan.`,
+    };
+}
+function receiptsOf(result) {
+    const results = result?.results;
+    return Array.isArray(results) ? results : [];
+}
+/**
+ * Import URLs into the project the way ImportFromUrl / ImportFromUrlBatch do,
+ * converting every video to .ogv first. Without a video the engine gets
+ * exactly the op it got before. `batch` picks ImportFromUrlBatch.
+ */
+export async function importUrls(client, entries, options, deps = defaultDeps) {
+    const engineOp = (list) => options.batch
+        ? { op: "ImportFromUrlBatch", imports: list }
+        : { op: "ImportFromUrl", url: list[0].url, ...(list[0].path ? { path: list[0].path } : {}) };
+    if (!entries.some(isConvertibleVideo))
+        return client.executeOps([engineOp(entries)]);
+    const forEngine = [];
+    const localReceipts = [];
+    const conversions = [];
+    const notes = [];
+    for (const entry of entries) {
+        if (!isConvertibleVideo(entry)) {
+            forEngine.push(entry);
+            continue;
+        }
+        const to = ogvResPath(entry);
+        const rendition = cloudinaryOgvUrl(entry.url);
+        if (rendition) {
+            forEngine.push({ url: rendition, path: to });
+            conversions.push({ from: entry.url, to, via: "cloudinary" });
+            continue;
+        }
+        const root = client.getProjectRoot?.();
+        const theora = root ? await deps.ffmpegTheora() : null;
+        if (root && theora) {
+            const placed = await convertLocally(client, root, entry.url, to, theora.audio, deps);
+            localReceipts.push(placed.receipt);
+            if (placed.note)
+                notes.push(placed.note);
+            conversions.push({ from: entry.url, to, via: "ffmpeg" });
+            continue;
+        }
+        forEngine.push({ url: await deps.convertRemote(entry.url), path: to });
+        conversions.push({ from: entry.url, to, via: "summerengine.com" });
+    }
+    const engineResult = forEngine.length ? await client.executeOps([engineOp(forEngine)]) : { status: "ok", results: [] };
+    const base = engineResult && typeof engineResult === "object" && !Array.isArray(engineResult) ? engineResult : { result: engineResult };
+    const paths = conversions.map((conversion) => conversion.to).join(", ");
+    return {
+        ...base,
+        results: [...receiptsOf(engineResult), ...localReceipts],
+        videoConversions: conversions,
+        note: [
+            `Summer Engine plays video only as Ogg Theora (.ogv), so the video was converted and imported as ${paths}. Load it from that path.`,
+            ...notes,
+        ].join(" "),
+    };
+}

package/dist/core/capability-skew.js

@@ -57,8 +57,8 @@ export const CLI_KNOWN_OP_NEEDS = [
     "ProjectSetting", "InputMapAddAction", "InputMapBind",
     // Files (summer_write_file / summer_replace_text / summer_create_scene)
     "WriteFile",
-    // Import
-    "ImportFromUrl", "ImportFromUrlBatch",
+    // Import (RenameFile registers a video converted on this computer: core/capabilities/video-ogv.ts)
+    "ImportFromUrl", "ImportFromUrlBatch", "RenameFile",
     // Diagnostics + runtime control
     "GetConsoleOutput", "ClearConsoleOutput", "GetDebuggerErrors", "IsGameRunning",
     // summer_play / summer_stop send these as ops for the instance-aware and

package/dist/core/cli-usage-beacon.js

@@ -2,15 +2,39 @@
  * The detached child cli-usage.ts starts when a CLI command exits: it sends
  * that command's one usage line (argv[2], JSON) and exits. It prints nothing.
  */
+import { getInstallId } from "./feedback/client.js";
 import { postUsage } from "./telemetry.js";
+import { usageLineFields } from "./usage-fields.js";
+/** The fields the parent noted travel in the line; the child adds the template and engine state. */
+function processFieldsFrom(line) {
+    const fields = {};
+    for (const key of ["projectIdHash", "templateId", "templateTags", "instanceCount"]) {
+        if (line[key] !== undefined)
+            fields[key] = line[key];
+        delete line[key];
+    }
+    return fields;
+}
 // A hard cap: an abort does not cancel a TLS connect that hangs, so the
 // child never lives past 3 s, whatever the network does.
 setTimeout(() => process.exit(0), 3000).unref();
 void (async () => {
     try {
         const body = JSON.parse(process.argv[2] ?? "");
-        if (body && typeof body === "object" && !Array.isArray(body))
-            await postUsage(body, 1500);
+        if (body && typeof body === "object" && !Array.isArray(body)) {
+            const line = body;
+            // Only the first-run line goes without an account token.
+            if (process.argv[3] === "--anonymous") {
+                if (line.event === "cli_first_run")
+                    await postUsage(line, 1500, { anonymous: true });
+            }
+            else {
+                const extra = await usageLineFields(processFieldsFrom(line), typeof line.error === "string" ? line.error : null);
+                // A sign-in that worked joins this machine's anonymous first-run line to the account.
+                const join = line.tool === "login" && line.ok === true ? { installId: await getInstallId() } : {};
+                await postUsage({ ...line, ...extra, ...join }, 1500);
+            }
+        }
     }
     catch {
         // best-effort: a bad body or an unreachable server sends nothing

package/dist/core/cli-usage.d.ts

@@ -5,8 +5,11 @@
  * one per command run by a signed-in person, with the tool (`summer_call`
  * plus the operation for `summer <area> <action>`, the summer_* tool for
  * `summer tool`, else the command name), success or the error code, duration
- * and the agent app named in the environment. Never arguments, paths or
- * project content. Off with SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1; nothing
+ * and the agent app named in the environment, plus the closed-shape fields
+ * of usage-fields.ts (project id hash, template, game clients started,
+ * engine state) and, on a `summer login` that worked, this machine's install
+ * id so the anonymous first-run line joins the account. Never arguments,
+ * paths or project content. Off with SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1; nothing
  * at all when no account token is on disk or in SUMMER_TOKEN. A command that
  * ran on Summer's server (a cloud operation, a hosted `summer tool`) sends no
  * line: the server records it from the request's `X-Summer-Client-Surface: cli`.

package/dist/core/cli-usage.js

@@ -5,8 +5,11 @@
  * one per command run by a signed-in person, with the tool (`summer_call`
  * plus the operation for `summer <area> <action>`, the summer_* tool for
  * `summer tool`, else the command name), success or the error code, duration
- * and the agent app named in the environment. Never arguments, paths or
- * project content. Off with SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1; nothing
+ * and the agent app named in the environment, plus the closed-shape fields
+ * of usage-fields.ts (project id hash, template, game clients started,
+ * engine state) and, on a `summer login` that worked, this machine's install
+ * id so the anonymous first-run line joins the account. Never arguments,
+ * paths or project content. Off with SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1; nothing
  * at all when no account token is on disk or in SUMMER_TOKEN. A command that
  * ran on Summer's server (a cloud operation, a hosted `summer tool`) sends no
  * line: the server records it from the request's `X-Summer-Client-Surface: cli`.
@@ -23,6 +26,7 @@ import { isTelemetryDisabled, resolveAgentHost } from "./agent-host.js";
 import { hasEnvAuthToken } from "./auth.js";
 import { OP_NAME } from "./ops/contract.js";
 import { getSummerDir } from "./store.js";
+import { processUsageFields } from "./usage-fields.js";
 /** What the server accepts as a tool: `summer_call`, `summer_play`, `create`, `skills_install`. */
 const TOOL = /^[a-z][a-z0-9_]{0,79}$/;
 const ERROR_CODE = /^[a-z][a-z0-9_]{0,63}$/;
@@ -78,6 +82,8 @@ export function cliUsageBody(started, exitCode, now = Date.now(), env = process.
         durationMs: Math.max(0, Math.round(now - started.startedAt)),
         mcpClient: resolveAgentHost(env, undefined).id,
         surfaceVersion: "v4",
+        // The child (cli-usage-beacon.ts) checks these again and adds the template and engine state.
+        ...processUsageFields(),
     };
 }
 /** A token on disk or in the environment; the child reads it, the parent only checks it is there. */

package/dist/core/engine-install.d.ts

@@ -119,3 +119,56 @@ export declare function linuxArchiveKind(nameOrUrl: string): "tar.gz" | "zip" |
  *  name first, then the only file, then anything that looks like an engine
  *  build (covers artifacts packed straight from bin/). */
 export declare function findExtractedEngineBinary(files: string[]): string | null;
+/** Why `summer install` failed: the CLI usage line's error code, one per kind
+ *  of failure, so telemetry says more than `exit_1`. */
+export type InstallFailureReason = "release_info" | "download" | "checksum" | "disk_space" | "mount" | "copy" | "permission" | "app_running" | "needs_confirmation" | "installer" | "unsupported_platform";
+/** An install failure with its reason; the message ends in one next step. */
+export declare class EngineInstallError extends Error {
+    readonly reason: InstallFailureReason;
+    constructor(reason: InstallFailureReason, message: string);
+}
+/** The command every "try again" next step names. */
+export declare const INSTALL_RETRY = "npx -y summer-engine@latest install";
+/** The useful line of an error: for a failed shell command the last line of
+ *  its stderr ("cp: ...: Permission denied"), not "Command failed: ...". */
+export declare function errorDetail(err: unknown): string;
+/** A full disk and a refused write have their own reasons wherever they
+ *  happen; anything else is `fallback`. */
+export declare function installFailureReason(err: unknown, fallback: InstallFailureReason): InstallFailureReason;
+/** Turn an unexpected error into an EngineInstallError: disk_space and
+ *  permission get their own message, anything else `message(detail)`. */
+export declare function asInstallError(err: unknown, fallback: InstallFailureReason, message: (detail: string) => string): EngineInstallError;
+/** The engine download when the server sends no content-length (the macOS DMG is about 660 MB). */
+export declare const DEFAULT_DOWNLOAD_BYTES: number;
+/** The install folder needs about this many times the download: the unpacked
+ *  app plus the staged copy that replaces an existing one. */
+export declare const INSTALL_SPACE_FACTOR = 2.5;
+/** Free bytes on the volume holding `path`, and an id for that volume. */
+export type FreeSpace = (path: string) => {
+    bytes: number;
+    volume: string;
+};
+export declare function formatSize(bytes: number): string;
+/**
+ * Refuse before the download fills the disk. Each need is a folder and the
+ * bytes it takes; needs on one volume add up (the default macOS temp folder
+ * and /Applications share the system volume). A volume whose free space
+ * cannot be read is skipped: the install tries, and ENOSPC still maps to
+ * disk_space.
+ */
+export declare function checkDiskSpace(needs: Array<{
+    path: string;
+    bytes: number;
+}>, freeSpace: FreeSpace): void;
+/** Where the macOS engine goes: --path wins; otherwise /Applications/Summer.app,
+ *  or ~/Applications/Summer.app when this user cannot replace it there (a
+ *  standard, non-admin account). macEnginePaths looks there too, and the
+ *  install record puts it first. */
+export declare function chooseMacDestination(input: {
+    customPath?: string;
+    home: string;
+    canReplace: (app: string) => boolean;
+}): {
+    destApp: string;
+    fallback: boolean;
+};