summer-engine 4.3.0 → 4.5.0

package/dist/core/preview/preview-source.js

@@ -0,0 +1,350 @@
+import { missingEngineOpResult } from "../capability-skew.js";
+import { engineNotRunningFromConnectError } from "../error-codes.js";
+import { resolveCurrentScene, resolveProjectName } from "../capabilities/project-context.js";
+import { extractOpError } from "../capabilities/engine-receipt.js";
+import { buildGameInputOp } from "../capabilities/runtime-control.js";
+import { asRecord, numberFrom, stringFrom } from "../util/json.js";
+import { engineInputEvent } from "./input.js";
+/** Fastest pace: 5 frames a second. */
+export const MIN_FRAME_INTERVAL_MS = 200;
+/** Slowest pace while a frame still comes back. */
+export const MAX_FRAME_INTERVAL_MS = 30_000;
+/** Capture may take at most 1/share of the time: the editor's viewport
+ *  read is light; a game frame stalls the game while it is read. */
+export const LATENCY_SHARE = { editor: 2, game: 16 };
+/** Editor pace once the view has stopped changing (2 fps). */
+export const EDITOR_IDLE_INTERVAL_MS = 500;
+/** Identical frames in a row before the editor counts as idle. */
+export const IDLE_AFTER_SAME_FRAMES = 2;
+/** Fresh frames on demand: at most one capture start this often. */
+export const FRESH_MIN_GAP_MS = 2000;
+/** Pace of the page while no editor answers. */
+export const NO_EDITOR_INTERVAL_MS = 2000;
+export const PLAY_CHECK_MS = 1000;
+export const META_CHECK_MS = 5000;
+export const RECONNECT_MS = 2000;
+export const LINK_CHECK_MS = 2000;
+/** After a running game's frame failed for a reason other than "not running",
+ *  show the editor and try the game again after this long. */
+export const GAME_RETRY_MS = 10_000;
+/** A request that comes sooner than this share of the pace after the last
+ *  capture started gets that capture's frame again: two tabs, or the page and
+ *  an agent's own request, never double the engine's work. */
+export const SHARE_FRAME_FRACTION = 0.75;
+export const NO_EDITOR_MESSAGE = "Editor not running: run npx -y summer-engine@latest dev";
+export const GAME_NOT_RUNNING_MESSAGE = "Game not running: showing the editor";
+const EWMA_WEIGHT = 0.3;
+function errorMessage(err) {
+    return err instanceof Error ? err.message : "unknown error";
+}
+function firstResult(value) {
+    const results = asRecord(value)?.results;
+    return Array.isArray(results) ? asRecord(results[0]) : null;
+}
+/** The pace for a `source` capture that takes `latencyMs`; `idle` = the
+ *  editor view has stopped changing. */
+export function frameIntervalMs(latencyMs, source = "editor", idle = false) {
+    const floor = source === "editor" && idle ? EDITOR_IDLE_INTERVAL_MS : MIN_FRAME_INTERVAL_MS;
+    if (latencyMs === null)
+        return floor;
+    const paced = Math.round(latencyMs * LATENCY_SHARE[source]);
+    return Math.min(MAX_FRAME_INTERVAL_MS, Math.max(floor, paced));
+}
+/** Schedule a batch frame by frame: a key pressed and released (or released
+ *  and pressed again) in the same batch gets the second event one frame later,
+ *  so a fast tap still reads as a press in the game. */
+export function scheduleInputBatch(events) {
+    let frame = 0;
+    const lastFrame = new Map();
+    return events.map((event) => {
+        const key = event.type === "key" && typeof event.keycode === "number" ? event.keycode : null;
+        if (key !== null && lastFrame.get(key) === frame)
+            frame += 1;
+        if (key !== null)
+            lastFrame.set(key, frame);
+        return { ...event, at_frame: frame };
+    });
+}
+export class PreviewSource {
+    connectEngine;
+    now;
+    log;
+    client = null;
+    attempted = false;
+    lastConnectAt = -Infinity;
+    lastLinkCheckAt = -Infinity;
+    linkError = null;
+    playing = false;
+    playingScene = null;
+    lastPlayCheckAt = -Infinity;
+    project = null;
+    scene = null;
+    lastMetaAt = -Infinity;
+    gameBlockedUntil = -Infinity;
+    gameNote = null;
+    inputSupported = false;
+    latency = { game: null, editor: null };
+    current = null;
+    seq = 0;
+    inflight = null;
+    lastCaptureAt = -Infinity;
+    sameFrames = 0;
+    inputChain = Promise.resolve();
+    inputQueue = [];
+    constructor(options) {
+        this.connectEngine = options.connect;
+        this.now = options.now ?? (() => Date.now());
+        this.log = options.log ?? (() => undefined);
+    }
+    /** The current state, without asking the engine anything. */
+    status() {
+        const state = this.state();
+        const frame = state === "no_editor" ? null : this.current;
+        const latency = frame ? this.latency[frame.source] : null;
+        return {
+            service: "summer-preview",
+            state,
+            message: this.message(state),
+            project: this.project,
+            scene: state === "game" ? this.playingScene ?? this.scene : this.scene,
+            engineVersion: this.client?.getEngineVersion?.() ?? null,
+            frame: frame
+                ? {
+                    seq: frame.seq,
+                    source: frame.source,
+                    width: frame.width,
+                    height: frame.height,
+                    capturedAt: frame.capturedAt,
+                    latencyMs: frame.latencyMs,
+                }
+                : null,
+            latencyMs: latency === null ? null : Math.round(latency),
+            intervalMs: state === "no_editor" || state === "connecting" ? NO_EDITOR_INTERVAL_MS : this.pace(),
+            input: this.client !== null && this.playing && this.inputSupported,
+        };
+    }
+    /** The newest frame: captured now, or the last one when another viewer
+     *  asked moments ago. `fresh` captures now unless a capture started in the
+     *  last FRESH_MIN_GAP_MS. Null while no editor answers. One capture at a time. */
+    async frame(options = {}) {
+        if (this.inflight)
+            return this.inflight;
+        const reuseWithinMs = options.fresh ? FRESH_MIN_GAP_MS : this.pace() * SHARE_FRAME_FRACTION;
+        if (this.current && this.client && this.now() - this.lastCaptureAt < reuseWithinMs)
+            return this.current;
+        this.lastCaptureAt = this.now();
+        this.inflight = this.capture().finally(() => {
+            this.inflight = null;
+        });
+        return this.inflight;
+    }
+    /** Send clicks and keys to the running game, also while its frames cannot
+     *  be read (a key release must never be lost). Calls are sent one at a time,
+     *  in order; input that arrives meanwhile goes out as one script. */
+    async sendInput(inputs) {
+        if (!this.client || !this.playing) {
+            return { ok: false, error: "No game is running; clicks and keys go only to a running game." };
+        }
+        if (!this.inputSupported) {
+            return { ok: false, error: "This Summer Engine build cannot take input from the preview (it predates SimulateInputScript)." };
+        }
+        const geometry = this.current?.source === "game" ? this.current : null;
+        const events = inputs
+            .map((input) => engineInputEvent(input, geometry))
+            .filter((event) => event !== null);
+        if (events.length === 0)
+            return { ok: false, error: "Nothing to send: the key is not mapped, or the click is outside the frame." };
+        this.inputQueue.push(...events);
+        const client = this.client;
+        const run = this.inputChain.then(async () => {
+            const batch = this.inputQueue.splice(0);
+            if (batch.length === 0)
+                return { ok: true, sent: 0 };
+            const built = buildGameInputOp({ action: "script", events: scheduleInputBatch(batch), wait: false });
+            try {
+                const result = await client.executeOps([built.op], undefined, built.timeoutMs);
+                const failure = extractOpError(result);
+                return failure ? { ok: false, error: failure } : { ok: true, sent: batch.length };
+            }
+            catch (err) {
+                this.log(`summer preview: input not sent: ${errorMessage(err)}`);
+                return { ok: false, error: "The engine did not answer; check that the game still runs." };
+            }
+        });
+        this.inputChain = run.catch(() => undefined);
+        return run;
+    }
+    pace() {
+        const frame = this.current;
+        if (!frame)
+            return MIN_FRAME_INTERVAL_MS;
+        return frameIntervalMs(this.latency[frame.source], frame.source, this.sameFrames >= IDLE_AFTER_SAME_FRAMES);
+    }
+    state() {
+        if (!this.client)
+            return this.attempted ? "no_editor" : "connecting";
+        if (this.current)
+            return this.current.source === "game" ? "game" : "editor";
+        return this.playing ? "game" : "editor";
+    }
+    message(state) {
+        switch (state) {
+            case "connecting":
+                return "Looking for Summer Engine";
+            case "no_editor":
+                return this.linkError ?? NO_EDITOR_MESSAGE;
+            case "game":
+                return `Game running${this.playingScene ? `: ${this.playingScene}` : ""}`;
+            case "editor":
+                if (this.playing && this.gameNote)
+                    return `Game running, but its frame could not be read (${this.gameNote}): showing the editor`;
+                return GAME_NOT_RUNNING_MESSAGE;
+        }
+    }
+    drop() {
+        this.client = null;
+        this.current = null;
+        this.playing = false;
+        this.playingScene = null;
+        this.inputSupported = false;
+        this.lastConnectAt = -Infinity;
+    }
+    /** The connected client, connecting or following a restart as needed. */
+    async engine() {
+        const now = this.now();
+        if (this.client && now - this.lastLinkCheckAt >= LINK_CHECK_MS) {
+            this.lastLinkCheckAt = now;
+            if (await this.client.credentialsChanged().catch(() => false))
+                this.drop();
+        }
+        if (this.client)
+            return this.client;
+        if (now - this.lastConnectAt < RECONNECT_MS)
+            return null;
+        this.lastConnectAt = now;
+        this.attempted = true;
+        try {
+            const client = await this.connectEngine();
+            this.client = client;
+            this.linkError = null;
+            this.lastLinkCheckAt = now;
+            this.lastPlayCheckAt = -Infinity;
+            this.lastMetaAt = -Infinity;
+            this.gameBlockedUntil = -Infinity;
+            this.gameNote = null;
+            this.inputSupported = !missingEngineOpResult(client, "SimulateInputScript", "");
+            return client;
+        }
+        catch (err) {
+            const reason = errorMessage(err);
+            const notRunning = engineNotRunningFromConnectError(reason);
+            this.linkError = notRunning
+                ? /^No running Summer editor matches/.test(reason)
+                    ? `Editor not running for this project: run npx -y summer-engine@latest dev`
+                    : null
+                : `Summer Engine: ${reason.split("\n")[0]}`;
+            return null;
+        }
+    }
+    /** Whether a game runs (and which scene). False when the editor is gone. */
+    async refreshPlaying(client) {
+        const now = this.now();
+        if (now - this.lastPlayCheckAt < PLAY_CHECK_MS)
+            return true;
+        this.lastPlayCheckAt = now;
+        try {
+            const result = firstResult(await client.executeOps([{ op: "IsGameRunning" }]));
+            const playing = result?.playing === true || result?.running === true;
+            if (playing && !this.playing)
+                this.gameBlockedUntil = -Infinity;
+            this.playing = playing;
+            this.playingScene = playing ? stringFrom(result?.scene) || null : null;
+            if (!playing)
+                this.gameNote = null;
+            return true;
+        }
+        catch {
+            // The editor stopped answering: look for it again.
+            this.drop();
+            return false;
+        }
+    }
+    async refreshMeta(client) {
+        const now = this.now();
+        if (now - this.lastMetaAt < META_CHECK_MS)
+            return;
+        this.lastMetaAt = now;
+        const [projectState, sceneState] = await Promise.all([
+            client.getProjectState().catch(() => null),
+            client.getSceneState().catch(() => null),
+        ]);
+        if (projectState)
+            this.project = resolveProjectName(projectState, null);
+        if (sceneState || projectState)
+            this.scene = resolveCurrentScene(projectState, sceneState, null);
+    }
+    async capture() {
+        const client = await this.engine();
+        if (!client)
+            return null;
+        if (!(await this.refreshPlaying(client)))
+            return null;
+        await this.refreshMeta(client);
+        if (this.playing && this.now() >= this.gameBlockedUntil) {
+            const frame = await this.read(client, "game");
+            if (frame)
+                return frame;
+        }
+        const frame = await this.read(client, "editor");
+        if (frame)
+            return frame;
+        // Keep showing the last frame; the next status check finds a lost editor.
+        this.lastPlayCheckAt = -Infinity;
+        return this.current;
+    }
+    async read(client, source) {
+        const started = this.now();
+        let snap;
+        try {
+            snap = source === "game" ? await client.gameSnapshot({ saveFile: false }) : await client.viewportSnapshot({ saveFile: false });
+        }
+        catch (err) {
+            snap = { ok: false, error: errorMessage(err) };
+        }
+        const latencyMs = this.now() - started;
+        if (!snap.ok || !snap.base64) {
+            if (source === "game") {
+                if (snap.failureReason === "not_running") {
+                    this.playing = false;
+                    this.playingScene = null;
+                }
+                else {
+                    this.gameNote = snap.failureReason ?? snap.error ?? "no image";
+                    this.gameBlockedUntil = this.now() + GAME_RETRY_MS;
+                }
+            }
+            return null;
+        }
+        const previous = this.latency[source];
+        this.latency[source] = previous === null ? latencyMs : previous + EWMA_WEIGHT * (latencyMs - previous);
+        if (source === "game")
+            this.gameNote = null;
+        const bytes = Buffer.from(snap.base64, "base64");
+        const same = this.current?.source === source && this.current.bytes.equals(bytes);
+        this.sameFrames = same ? this.sameFrames + 1 : 0;
+        this.seq += 1;
+        this.current = {
+            seq: this.seq,
+            source,
+            bytes,
+            mime: snap.mime ?? "image/png",
+            width: snap.width ?? 0,
+            height: snap.height ?? 0,
+            sourceWidth: numberFrom(snap.metadata?.source_width),
+            sourceHeight: numberFrom(snap.metadata?.source_height),
+            capturedAt: this.now(),
+            latencyMs,
+        };
+        return this.current;
+    }
+}

package/dist/core/preview/server.d.ts

@@ -0,0 +1,26 @@
+import { PreviewSource, type PreviewEngine } from "./preview-source.js";
+export declare const PREVIEW_HOST = "127.0.0.1";
+/** Ports tried after a taken default port. */
+export declare const PORT_SEARCH_SPAN = 20;
+export interface PreviewServerOptions {
+    /** First port to try. */
+    port: number;
+    /** true: that port or an error (a host that launched us expects it).
+     *  false: the next free port up to PORT_SEARCH_SPAN above it. 0 = any. */
+    strictPort: boolean;
+    connect: () => Promise<PreviewEngine>;
+    now?: () => number;
+    /** Where failure details go (default stderr); the page gets a short fixed text. */
+    log?: (line: string) => void;
+}
+export interface PreviewServer {
+    url: string;
+    port: number;
+    source: PreviewSource;
+    close(): Promise<void>;
+}
+export declare class PortInUseError extends Error {
+    readonly port: number;
+    constructor(port: number);
+}
+export declare function startPreviewServer(options: PreviewServerOptions): Promise<PreviewServer>;

package/dist/core/preview/server.js

@@ -0,0 +1,218 @@
+/**
+ * The `summer preview` HTTP server: loopback only, one page and three routes.
+ *
+ *   GET  /            the page (./page.ts)
+ *   GET  /api/frame   the newest frame (image bytes, status in x-summer-status),
+ *                     or 503 + the status as JSON while no editor answers;
+ *                     ?fresh=1 captures now (a check that needs the game as it is)
+ *   GET  /api/status  the status as JSON, without capturing
+ *   POST /api/input   {inputs:[{kind:"key",code,pressed} | {kind:"click",x,y,button}]}
+ *                     to the running game
+ *
+ * Listens on 127.0.0.1 and, where the machine has it, on ::1 at the same port,
+ * so http://localhost:<port> (what Claude Code Desktop's Browser pane opens)
+ * reaches it either way. Requests must name a loopback Host (stops a web page
+ * from reaching it through DNS rebinding); the API refuses requests a browser
+ * marks as coming from another site (Sec-Fetch-Site), so another page cannot
+ * make it capture with an <img>; input must be a same-origin JSON POST.
+ *
+ * No frame-ancestors in the CSP: Desktop's docs do not say how the Browser
+ * pane hosts a page, and a frame-ancestors rule would blank it if the pane
+ * frames it. Instead the page itself sends no input while it is framed.
+ */
+import { createServer } from "node:http";
+import { parsePreviewInputs } from "./input.js";
+import { PREVIEW_PAGE_HTML } from "./page.js";
+import { PreviewSource } from "./preview-source.js";
+export const PREVIEW_HOST = "127.0.0.1";
+/** Ports tried after a taken default port. */
+export const PORT_SEARCH_SPAN = 20;
+const CONTENT_SECURITY_POLICY = "default-src 'none'; img-src 'self' blob:; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'";
+const MAX_INPUT_BODY_BYTES = 16 * 1024;
+export class PortInUseError extends Error {
+    port;
+    constructor(port) {
+        super(`Port ${port} is in use.`);
+        this.port = port;
+    }
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+function allowedHosts(port) {
+    return new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+}
+async function readBody(req) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_INPUT_BODY_BYTES)
+            return null;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+function handler(source, getPort) {
+    return async (req, res) => {
+        const port = getPort();
+        const hosts = allowedHosts(port);
+        if (!hosts.has(req.headers.host ?? "")) {
+            sendJson(res, 403, { ok: false, error: "Open the preview at http://127.0.0.1:" + port });
+            return;
+        }
+        const [path, query = ""] = (req.url ?? "/").split("?");
+        const site = req.headers["sec-fetch-site"];
+        if (path.startsWith("/api/") && (site === "cross-site" || site === "same-site")) {
+            sendJson(res, 403, { ok: false, error: "The preview API answers only its own page." });
+            return;
+        }
+        if (req.method === "GET" && (path === "/" || path === "/index.html")) {
+            res.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store",
+                "content-security-policy": CONTENT_SECURITY_POLICY,
+                "x-content-type-options": "nosniff",
+                "referrer-policy": "no-referrer",
+            });
+            res.end(PREVIEW_PAGE_HTML);
+            return;
+        }
+        if (req.method === "GET" && path === "/api/status") {
+            sendJson(res, 200, source.status());
+            return;
+        }
+        if (req.method === "GET" && path === "/api/frame") {
+            const frame = await source.frame({ fresh: new URLSearchParams(query).get("fresh") === "1" });
+            const status = source.status();
+            if (!frame || status.state === "no_editor") {
+                sendJson(res, 503, status);
+                return;
+            }
+            res.writeHead(200, {
+                "content-type": frame.mime,
+                "content-length": frame.bytes.length,
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+                "x-summer-status": encodeURIComponent(JSON.stringify(status)),
+            });
+            res.end(frame.bytes);
+            return;
+        }
+        if (path === "/api/input") {
+            if (req.method !== "POST") {
+                sendJson(res, 405, { ok: false, error: "POST only" });
+                return;
+            }
+            const origin = req.headers.origin;
+            const sameOrigin = !origin || [...hosts].some((host) => origin === `http://${host}`);
+            const json = (req.headers["content-type"] ?? "").split(";")[0].trim() === "application/json";
+            if (!sameOrigin || !json) {
+                sendJson(res, 403, { ok: false, error: "Input is taken only from the preview page (same origin, JSON)." });
+                return;
+            }
+            const text = await readBody(req);
+            let body = null;
+            try {
+                body = text === null ? null : JSON.parse(text);
+            }
+            catch {
+                body = null;
+            }
+            const inputs = parsePreviewInputs(body);
+            if (!inputs) {
+                sendJson(res, 400, { ok: false, error: "Expected {inputs:[{kind:'key',code,pressed} | {kind:'click',x,y,button}]} (1 to 64)." });
+                return;
+            }
+            const result = await source.sendInput(inputs);
+            sendJson(res, result.ok ? 200 : 409, result);
+            return;
+        }
+        sendJson(res, 404, { ok: false, error: "Not found. The preview is at /" });
+    };
+}
+function listen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off("listening", onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, host);
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+        server.closeAllConnections?.();
+    });
+}
+function safe(handle, log) {
+    return (req, res) => {
+        handle(req, res).catch((err) => {
+            // Details stay in the local log; the page gets a fixed answer.
+            log(`summer preview: ${req.method} ${(req.url ?? "/").split("?")[0]} failed: ${err instanceof Error ? err.message : "unknown error"}`);
+            if (res.headersSent)
+                res.end();
+            else
+                sendJson(res, 500, { ok: false, error: "internal_error" });
+        });
+    };
+}
+/** Bind 127.0.0.1 (required) and ::1 (when the machine has IPv6) on one port. */
+async function bindPair(port, handle, log) {
+    const v4 = createServer(safe(handle, log));
+    await listen(v4, port, PREVIEW_HOST);
+    const bound = v4.address().port;
+    const v6 = createServer(safe(handle, log));
+    try {
+        await listen(v6, bound, "::1");
+        return [v4, v6];
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EADDRINUSE") {
+            // Something else answers localhost on this port over IPv6: the Browser
+            // pane could reach it instead of us. Treat the port as taken.
+            await closeServer(v4);
+            throw err;
+        }
+        return [v4];
+    }
+}
+export async function startPreviewServer(options) {
+    const log = options.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const source = new PreviewSource({ connect: options.connect, now: options.now, log });
+    let port = options.port;
+    const handle = handler(source, () => port);
+    const last = options.strictPort || options.port === 0 ? options.port : options.port + PORT_SEARCH_SPAN;
+    let servers = null;
+    for (let candidate = options.port; candidate <= last; candidate += 1) {
+        try {
+            servers = await bindPair(candidate, handle, log);
+            port = servers[0].address().port;
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EADDRINUSE")
+                throw err;
+            if (candidate === last)
+                throw new PortInUseError(options.strictPort ? options.port : candidate);
+        }
+    }
+    const bound = servers;
+    return {
+        url: `http://${PREVIEW_HOST}:${port}`,
+        port,
+        source,
+        close: async () => {
+            await Promise.all(bound.map(closeServer));
+        },
+    };
+}

package/dist/core/telemetry.d.ts

@@ -1,19 +1,5 @@
-/**
- * Usage beacons for the local MCP server. Fire-and-forget, never blocks, never throws.
- *
- * - One session ping per MCP server lifetime (mcp_session_start), on the
- *   first tool call, with the host app's name from the MCP handshake.
- * - One line per local tool call (mcp_tool_call): the tool name, the
- *   Summer operation it ran, success, duration, the host app's name from the
- *   MCP handshake, and the tool surface and profile. Nothing else: no
- *   arguments, no results, no project or file names.
- *
- * Both go to /api/mcp/log-local-call, only when signed in (the account token
- * attributes them), and never when SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1.
- * The endpoint always returns allowed:true and never gates; the response is
- * ignored.
- */
 import { isTelemetryDisabled } from "./agent-host.js";
+import { type UsageFields } from "./usage-fields.js";
 export { isTelemetryDisabled };
 /**
  * Ping the telemetry endpoint once per MCP server lifetime.
@@ -38,6 +24,8 @@ export interface LocalToolCall {
     profile?: string;
     /** A failed call's error code (toolErrorCode); never sent for a call that worked. */
     error?: string | null;
+    /** What the call noted (usage-fields.ts noteToolUsage) and the bound project. */
+    usage?: UsageFields;
 }
 /**
  * The code a failed tool result names, read from its first text block: the
@@ -48,7 +36,23 @@ export declare function toolErrorCode(result: unknown, fallback?: string): strin
 /** Report one local tool call: tool name, success, duration, host app name. */
 export declare function recordLocalToolCall(call: LocalToolCall): void;
 /** POST one usage line with the account token; resolves when sent or given up. Never throws. */
-export declare function postUsage(body: Record<string, unknown>, timeoutMs?: number): Promise<void>;
+export declare function postUsage(body: Record<string, unknown>, timeoutMs?: number, options?: {
+    anonymous?: boolean;
+}): Promise<void>;
+/** The one-time notice, printed to stderr (never stdout: `summer mcp` speaks MCP there). */
+export declare const TELEMETRY_NOTICE: string;
+export interface FirstRunDeps {
+    env?: NodeJS.ProcessEnv;
+    write?: (text: string) => void;
+    send?: (body: Record<string, unknown>) => void;
+}
+/**
+ * The first `summer` command on this machine: print the notice once, then
+ * send one anonymous cli_first_run line (install id, command name, agent
+ * app, operating system). Nothing when opted out, in CI, or when the marker
+ * cannot be written (no line without the notice). Returns whether it ran.
+ */
+export declare function noteFirstRun(command: string, deps?: FirstRunDeps): Promise<boolean>;
 /**
  * Reset the once-per-session guard. Test-only.
  */