summer-engine 4.0.0 → 4.3.0

package/dist/core/capabilities/runtime-control.d.ts

@@ -181,15 +181,15 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     path: string;
-    target: "tree" | "player" | "bones";
+    target: "player" | "tree" | "bones";
     name?: string | undefined;
     state?: string | undefined;
     value?: string | number | boolean | undefined;
     instance?: string | undefined;
     space?: "local" | "global" | "both" | undefined;
-    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
-    blend?: number | undefined;
+    cmd?: "state" | "pause" | "play" | "start" | "stop" | "seek" | "speed" | "travel" | "set_param" | "get_param" | undefined;
     position?: number | undefined;
+    blend?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;
     from_end?: boolean | undefined;
@@ -200,15 +200,15 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
     include_rest?: boolean | undefined;
 }, {
     path: string;
-    target: "tree" | "player" | "bones";
+    target: "player" | "tree" | "bones";
     name?: string | undefined;
     state?: string | undefined;
     value?: string | number | boolean | undefined;
     instance?: string | undefined;
     space?: "local" | "global" | "both" | undefined;
-    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
-    blend?: number | undefined;
+    cmd?: "state" | "pause" | "play" | "start" | "stop" | "seek" | "speed" | "travel" | "set_param" | "get_param" | undefined;
     position?: number | undefined;
+    blend?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;
     from_end?: boolean | undefined;
@@ -227,17 +227,17 @@ export declare const gameControlArgsSchema: z.ZodObject<{
     speed: z.ZodOptional<z.ZodNumber>;
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    action: "instances" | "pause" | "resume" | "speed" | "step";
+    action: "instances" | "pause" | "resume" | "step" | "speed";
     instance?: string | undefined;
     kind?: "physics" | "process" | undefined;
-    speed?: number | undefined;
     frames?: number | undefined;
+    speed?: number | undefined;
 }, {
-    action: "instances" | "pause" | "resume" | "speed" | "step";
+    action: "instances" | "pause" | "resume" | "step" | "speed";
     instance?: string | undefined;
     kind?: "physics" | "process" | undefined;
-    speed?: number | undefined;
     frames?: number | undefined;
+    speed?: number | undefined;
 }>;
 export type GameControlArgs = z.infer<typeof gameControlArgsSchema>;
 export declare function buildGameControlOp(args: GameControlArgs): BuiltRuntimeOp;
@@ -259,15 +259,15 @@ export declare const inputEventSchema: z.ZodObject<{
     class: z.ZodOptional<z.ZodString>;
     props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    type: "key" | "action" | "mouse_click" | "axis" | "raw";
+    type: "key" | "action" | "axis" | "mouse_click" | "raw";
     action?: string | undefined;
-    button?: number | undefined;
-    class?: string | undefined;
     position?: [number, number] | undefined;
+    pressed?: boolean | undefined;
     props?: Record<string, unknown> | undefined;
+    button?: number | undefined;
+    class?: string | undefined;
     at_frame?: number | undefined;
     at_ms?: number | undefined;
-    pressed?: boolean | undefined;
     strength?: number | undefined;
     hold_ms?: number | undefined;
     keycode?: number | undefined;
@@ -276,15 +276,15 @@ export declare const inputEventSchema: z.ZodObject<{
     action_positive?: string | undefined;
     duration_ms?: number | undefined;
 }, {
-    type: "key" | "action" | "mouse_click" | "axis" | "raw";
+    type: "key" | "action" | "axis" | "mouse_click" | "raw";
     action?: string | undefined;
-    button?: number | undefined;
-    class?: string | undefined;
     position?: [number, number] | undefined;
+    pressed?: boolean | undefined;
     props?: Record<string, unknown> | undefined;
+    button?: number | undefined;
+    class?: string | undefined;
     at_frame?: number | undefined;
     at_ms?: number | undefined;
-    pressed?: boolean | undefined;
     strength?: number | undefined;
     hold_ms?: number | undefined;
     keycode?: number | undefined;
@@ -314,15 +314,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
         class: z.ZodOptional<z.ZodString>;
         props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
-        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        type: "key" | "action" | "axis" | "mouse_click" | "raw";
         action?: string | undefined;
-        button?: number | undefined;
-        class?: string | undefined;
         position?: [number, number] | undefined;
+        pressed?: boolean | undefined;
         props?: Record<string, unknown> | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
         at_frame?: number | undefined;
         at_ms?: number | undefined;
-        pressed?: boolean | undefined;
         strength?: number | undefined;
         hold_ms?: number | undefined;
         keycode?: number | undefined;
@@ -331,15 +331,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
         action_positive?: string | undefined;
         duration_ms?: number | undefined;
     }, {
-        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        type: "key" | "action" | "axis" | "mouse_click" | "raw";
         action?: string | undefined;
-        button?: number | undefined;
-        class?: string | undefined;
         position?: [number, number] | undefined;
+        pressed?: boolean | undefined;
         props?: Record<string, unknown> | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
         at_frame?: number | undefined;
         at_ms?: number | undefined;
-        pressed?: boolean | undefined;
         strength?: number | undefined;
         hold_ms?: number | undefined;
         keycode?: number | undefined;
@@ -358,15 +358,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     action: "script" | "record_start" | "record_stop" | "replay";
     events?: {
-        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        type: "key" | "action" | "axis" | "mouse_click" | "raw";
         action?: string | undefined;
-        button?: number | undefined;
-        class?: string | undefined;
         position?: [number, number] | undefined;
+        pressed?: boolean | undefined;
         props?: Record<string, unknown> | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
         at_frame?: number | undefined;
         at_ms?: number | undefined;
-        pressed?: boolean | undefined;
         strength?: number | undefined;
         hold_ms?: number | undefined;
         keycode?: number | undefined;
@@ -385,15 +385,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
 }, {
     action: "script" | "record_start" | "record_stop" | "replay";
     events?: {
-        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        type: "key" | "action" | "axis" | "mouse_click" | "raw";
         action?: string | undefined;
-        button?: number | undefined;
-        class?: string | undefined;
         position?: [number, number] | undefined;
+        pressed?: boolean | undefined;
         props?: Record<string, unknown> | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
         at_frame?: number | undefined;
         at_ms?: number | undefined;
-        pressed?: boolean | undefined;
         strength?: number | undefined;
         hold_ms?: number | undefined;
         keycode?: number | undefined;
@@ -436,23 +436,23 @@ export declare const gameProbeArgsSchema: z.ZodObject<{
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     instance?: string | undefined;
+    props?: string[] | undefined;
+    screenshot?: boolean | undefined;
     tree?: {
         path?: string | undefined;
         limit?: number | undefined;
         depth?: number | undefined;
     } | undefined;
-    props?: string[] | undefined;
-    screenshot?: boolean | undefined;
     max_dim?: number | undefined;
 }, {
     instance?: string | undefined;
+    props?: string[] | undefined;
+    screenshot?: boolean | undefined;
     tree?: {
         path?: string | undefined;
         limit?: number | undefined;
         depth?: number | undefined;
     } | undefined;
-    props?: string[] | undefined;
-    screenshot?: boolean | undefined;
     max_dim?: number | undefined;
 }>;
 export type GameProbeArgs = z.infer<typeof gameProbeArgsSchema>;

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

@@ -124,10 +124,10 @@ export declare const frameNodesArgsSchema: z.ZodObject<{
     marks?: boolean | undefined;
     max_marks?: number | undefined;
     from?: string | undefined;
-    max_size?: number | undefined;
+    direction?: "top" | "front" | "iso" | "back" | "left" | "right" | undefined;
     bookmark_name?: string | undefined;
+    max_size?: number | undefined;
     aspect?: number | undefined;
-    direction?: "top" | "iso" | "front" | "back" | "left" | "right" | undefined;
 }, {
     nodes: string[];
     fill?: number | undefined;
@@ -136,10 +136,10 @@ export declare const frameNodesArgsSchema: z.ZodObject<{
     marks?: boolean | undefined;
     max_marks?: number | undefined;
     from?: string | undefined;
-    max_size?: number | undefined;
+    direction?: "top" | "front" | "iso" | "back" | "left" | "right" | undefined;
     bookmark_name?: string | undefined;
+    max_size?: number | undefined;
     aspect?: number | undefined;
-    direction?: "top" | "iso" | "front" | "back" | "left" | "right" | undefined;
 }>;
 export declare const shotSheetArgsSchema: z.ZodObject<{
     scenePath: z.ZodOptional<z.ZodString>;
@@ -177,12 +177,12 @@ export declare const shotSheetArgsSchema: z.ZodObject<{
         bookmark_name?: string | undefined;
     }[];
     scenePath?: string | undefined;
+    compare_previous?: boolean | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
     view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     update_previous?: boolean | undefined;
     aspect?: number | undefined;
-    compare_previous?: boolean | undefined;
 }, {
     shots: {
         camera_position?: string | undefined;
@@ -192,12 +192,12 @@ export declare const shotSheetArgsSchema: z.ZodObject<{
         bookmark_name?: string | undefined;
     }[];
     scenePath?: string | undefined;
+    compare_previous?: boolean | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
     view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     update_previous?: boolean | undefined;
     aspect?: number | undefined;
-    compare_previous?: boolean | undefined;
 }>;
 export declare const debugViewsArgsSchema: z.ZodObject<{
     scenePath: z.ZodOptional<z.ZodString>;
@@ -215,9 +215,9 @@ export declare const debugViewsArgsSchema: z.ZodObject<{
     camera_position?: string | undefined;
     camera_look_at?: string | undefined;
     fov?: number | undefined;
+    bookmark_name?: string | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    bookmark_name?: string | undefined;
     views?: ("lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe")[] | undefined;
     update_previous?: boolean | undefined;
     aspect?: number | undefined;
@@ -226,9 +226,9 @@ export declare const debugViewsArgsSchema: z.ZodObject<{
     camera_position?: string | undefined;
     camera_look_at?: string | undefined;
     fov?: number | undefined;
+    bookmark_name?: string | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    bookmark_name?: string | undefined;
     views?: ("lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe")[] | undefined;
     update_previous?: boolean | undefined;
     aspect?: number | undefined;
@@ -251,11 +251,11 @@ export declare const zoomArgsSchema: z.ZodObject<{
     camera_position?: string | undefined;
     camera_look_at?: string | undefined;
     fov?: number | undefined;
+    bookmark_name?: string | undefined;
+    region?: number[] | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    bookmark_name?: string | undefined;
     view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
-    region?: number[] | undefined;
     mark?: number | undefined;
     reference_size?: number[] | undefined;
     pad?: number | undefined;
@@ -264,11 +264,11 @@ export declare const zoomArgsSchema: z.ZodObject<{
     camera_position?: string | undefined;
     camera_look_at?: string | undefined;
     fov?: number | undefined;
+    bookmark_name?: string | undefined;
+    region?: number[] | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    bookmark_name?: string | undefined;
     view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
-    region?: number[] | undefined;
     mark?: number | undefined;
     reference_size?: number[] | undefined;
     pad?: number | undefined;
@@ -310,8 +310,9 @@ export declare const frameShotArgsSchema: z.ZodObject<{
     spawn?: string | undefined;
     scenePath?: string | undefined;
     fov?: number | undefined;
-    max_size?: number | undefined;
     bookmark_name?: string | undefined;
+    subject?: string[] | undefined;
+    max_size?: number | undefined;
     render?: "none" | "sheet" | "best" | undefined;
     aspect?: number | undefined;
     occluders?: {
@@ -321,7 +322,6 @@ export declare const frameShotArgsSchema: z.ZodObject<{
         hard_layers?: number | undefined;
         soft_layers?: number | undefined;
     } | undefined;
-    subject?: string[] | undefined;
     eye_height?: number | undefined;
     max_soft_fraction?: number | undefined;
     save_bookmark?: boolean | undefined;
@@ -330,8 +330,9 @@ export declare const frameShotArgsSchema: z.ZodObject<{
     spawn?: string | undefined;
     scenePath?: string | undefined;
     fov?: number | undefined;
-    max_size?: number | undefined;
     bookmark_name?: string | undefined;
+    subject?: string[] | undefined;
+    max_size?: number | undefined;
     render?: "none" | "sheet" | "best" | undefined;
     aspect?: number | undefined;
     occluders?: {
@@ -341,7 +342,6 @@ export declare const frameShotArgsSchema: z.ZodObject<{
         hard_layers?: number | undefined;
         soft_layers?: number | undefined;
     } | undefined;
-    subject?: string[] | undefined;
     eye_height?: number | undefined;
     max_soft_fraction?: number | undefined;
     save_bookmark?: boolean | undefined;

package/dist/core/capabilities/ui-control.d.ts

@@ -90,7 +90,7 @@ export declare const uiActivateArgsSchema: z.ZodObject<{
     value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
+    action?: "focus" | "press" | "select_tab" | "toggle" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;
     submit?: boolean | undefined;
@@ -98,7 +98,7 @@ export declare const uiActivateArgsSchema: z.ZodObject<{
     value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
+    action?: "focus" | "press" | "select_tab" | "toggle" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;
     submit?: boolean | undefined;

package/dist/core/capabilities/world-snapshot.d.ts

@@ -38,18 +38,18 @@ export declare const worldSnapshotInputSchema: z.ZodObject<{
     fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     scene_path?: string | undefined;
+    fields?: string[] | undefined;
+    path_prefix?: string | undefined;
     offset?: number | undefined;
     max_nodes?: number | undefined;
-    path_prefix?: string | undefined;
     classes?: string[] | undefined;
-    fields?: string[] | undefined;
 }, {
     scene_path?: string | undefined;
+    fields?: string[] | undefined;
+    path_prefix?: string | undefined;
     offset?: number | undefined;
     max_nodes?: number | undefined;
-    path_prefix?: string | undefined;
     classes?: string[] | undefined;
-    fields?: string[] | undefined;
 }>;
 export type WorldSnapshotArgs = z.infer<typeof worldSnapshotInputSchema>;
 export declare function buildWorldSnapshotOp(args: WorldSnapshotArgs): JsonRecord;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,18 @@
+/**
+ * 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 { postUsage } from "./telemetry.js";
+// 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);
+    }
+    catch {
+        // best-effort: a bad body or an unreachable server sends nothing
+    }
+})();

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

@@ -0,0 +1,49 @@
+/**
+ * The usage line for CLI commands that run on this computer (`summer create`,
+ * `summer skills install`, `summer engine play`, a local `summer tool`, ...),
+ * in the schema of the MCP tool-call line (telemetry.ts) with surface `cli`:
+ * 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
+ * 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`.
+ *
+ * It costs the command nothing: when the process exits, a detached child
+ * (cli-usage-beacon.ts) sends the line, so no command waits for Summer's
+ * server, prints anything, or loses the line to process.exit().
+ */
+import { spawn } from "node:child_process";
+interface Pending {
+    tool: string;
+    op?: string;
+    error?: string;
+    startedAt: number;
+    /** It ran on Summer's server, which records it. */
+    hosted?: boolean;
+}
+/** The command path as a tool name: `summer skills install` -> `skills_install`. */
+export declare function cliCommandName(path: readonly string[]): string;
+/**
+ * Start timing one command; the line goes out when the process exits. Once
+ * per process. An operation (`summer <area> <action>`, `whoami`) reports as
+ * `summer_call` with that operation; any other command as its own name.
+ */
+export declare function startCliCommand(command: string, op?: string, now?: number): void;
+/** `summer tool <name>` ran this local summer_* tool: report it under its own name. */
+export declare function noteCliTool(tool: string): void;
+/** The command ran on Summer's server, which records it: send no line. */
+export declare function noteCliHosted(): void;
+/** The command failed with this error code (an operation answer's `error.code`). */
+export declare function noteCliError(code: string): void;
+/** The line's body: no arguments, paths or project content can reach it. */
+export declare function cliUsageBody(started: Pending, exitCode: number, now?: number, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+export declare function sendCliUsage(exitCode: number, deps?: {
+    spawn?: typeof spawn;
+    signedIn?: () => boolean;
+}): void;
+/** Test-only: forget the command in progress. */
+export declare function _resetCliUsageForTests(): void;
+export {};

package/dist/core/cli-usage.js

@@ -0,0 +1,108 @@
+/**
+ * The usage line for CLI commands that run on this computer (`summer create`,
+ * `summer skills install`, `summer engine play`, a local `summer tool`, ...),
+ * in the schema of the MCP tool-call line (telemetry.ts) with surface `cli`:
+ * 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
+ * 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`.
+ *
+ * It costs the command nothing: when the process exits, a detached child
+ * (cli-usage-beacon.ts) sends the line, so no command waits for Summer's
+ * server, prints anything, or loses the line to process.exit().
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isTelemetryDisabled, resolveAgentHost } from "./agent-host.js";
+import { hasEnvAuthToken } from "./auth.js";
+import { OP_NAME } from "./ops/contract.js";
+import { getSummerDir } from "./store.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}$/;
+const BEACON = fileURLToPath(new URL("./cli-usage-beacon.js", import.meta.url));
+let pending = null;
+/** The command path as a tool name: `summer skills install` -> `skills_install`. */
+export function cliCommandName(path) {
+    return path.map((word) => word.toLowerCase().replace(/-/g, "_")).join("_");
+}
+/**
+ * Start timing one command; the line goes out when the process exits. Once
+ * per process. An operation (`summer <area> <action>`, `whoami`) reports as
+ * `summer_call` with that operation; any other command as its own name.
+ */
+export function startCliCommand(command, op, now = Date.now()) {
+    if (pending || isTelemetryDisabled())
+        return;
+    const isOp = op !== undefined && OP_NAME.test(op);
+    const tool = isOp ? "summer_call" : command;
+    if (!TOOL.test(tool))
+        return;
+    pending = { tool, ...(isOp ? { op } : {}), startedAt: now };
+    process.once("exit", (code) => sendCliUsage(code));
+}
+/** `summer tool <name>` ran this local summer_* tool: report it under its own name. */
+export function noteCliTool(tool) {
+    if (pending && /^summer_[a-z0-9_]{1,72}$/.test(tool)) {
+        pending.tool = tool;
+        delete pending.op;
+    }
+}
+/** The command ran on Summer's server, which records it: send no line. */
+export function noteCliHosted() {
+    if (pending)
+        pending.hosted = true;
+}
+/** The command failed with this error code (an operation answer's `error.code`). */
+export function noteCliError(code) {
+    if (pending && ERROR_CODE.test(code))
+        pending.error = code;
+}
+/** The line's body: no arguments, paths or project content can reach it. */
+export function cliUsageBody(started, exitCode, now = Date.now(), env = process.env) {
+    const ok = exitCode === 0 && !started.error;
+    return {
+        client: "summer-cli",
+        event: "mcp_tool_call",
+        surface: "cli",
+        tool: started.tool,
+        ...(started.op ? { op: started.op } : {}),
+        ok,
+        ...(ok ? {} : { error: started.error ?? `exit_${exitCode}` }),
+        durationMs: Math.max(0, Math.round(now - started.startedAt)),
+        mcpClient: resolveAgentHost(env, undefined).id,
+        surfaceVersion: "v4",
+    };
+}
+/** A token on disk or in the environment; the child reads it, the parent only checks it is there. */
+function signedIn() {
+    return hasEnvAuthToken() || existsSync(join(getSummerDir(), "auth-token"));
+}
+export function sendCliUsage(exitCode, deps = {}) {
+    const started = pending;
+    pending = null;
+    if (!started || started.hosted || isTelemetryDisabled() || !(deps.signedIn ?? signedIn)())
+        return;
+    try {
+        (deps.spawn ?? spawn)(process.execPath, [BEACON, JSON.stringify(cliUsageBody(started, exitCode))], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            // A debugger flag (--inspect-brk) would make the child wait forever.
+            env: { ...process.env, NODE_OPTIONS: (process.env.NODE_OPTIONS ?? "").replace(/--inspect\S*/g, "").trim() },
+        }).unref();
+    }
+    catch {
+        // never throws: usage is best-effort
+    }
+}
+/** Test-only: forget the command in progress. */
+export function _resetCliUsageForTests() {
+    pending = null;
+}

package/dist/core/feedback/client.d.ts

@@ -1,7 +1,7 @@
 export declare function getFeedbackSessionId(): string;
 /** Test-only seam. */
 export declare function _resetFeedbackSessionForTests(): void;
-/** Kill switches: send NOTHING when either is set to "1". */
+/** Kill switches: send NOTHING when either is set (1, true, yes or on; agent-host.ts). */
 export declare function isFeedbackDisabled(): boolean;
 /**
  * Anonymous install id: a random uuid persisted once in ~/.summer/.

package/dist/core/feedback/client.js

@@ -21,6 +21,7 @@
  * nothing is logged on failure — silence is the contract.
  */
 import { randomUUID } from "node:crypto";
+import { isTelemetryDisabled } from "../agent-host.js";
 import { getAuthToken } from "../auth.js";
 import { resolveGatewayUrl } from "../config.js";
 import { readStoreText, writeStoreText } from "../store.js";
@@ -43,9 +44,9 @@ export function _resetFeedbackSessionForTests() {
 async function feedbackUrl() {
     return `${await resolveGatewayUrl()}${FEEDBACK_PATH}`;
 }
-/** Kill switches: send NOTHING when either is set to "1". */
+/** Kill switches: send NOTHING when either is set (1, true, yes or on; agent-host.ts). */
 export function isFeedbackDisabled() {
-    return (process.env.SUMMER_NO_TELEMETRY === "1" || process.env.DO_NOT_TRACK === "1");
+    return isTelemetryDisabled();
 }
 /**
  * Anonymous install id: a random uuid persisted once in ~/.summer/.

package/dist/core/hosted-mcp.d.ts

@@ -1,5 +1,6 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { OAuthError } from "./oauth.js";
+import { type ClientSurface } from "./agent-host.js";
 /** The part of an MCP client the mount and the CLI use (a fake in tests). */
 export interface HostedClient {
     listTools(params?: {
@@ -54,7 +55,12 @@ export interface HostedConnectDependencies {
     token: () => Promise<string>;
     connect: (url: string, token: () => Promise<string>) => Promise<HostedClient>;
 }
-export declare function connectHostedMcp(url: string, token: () => Promise<string>): Promise<HostedClient>;
+/** The handshake name the hosted server sees: the MCP server's own, or the `summer` CLI's, so usage tells them apart. */
+export declare const HOSTED_CLIENT_NAMES: {
+    readonly mcp: "summer-engine-local";
+    readonly cli: "summer-cli";
+};
+export declare function connectHostedMcp(url: string, token: () => Promise<string>, surface?: ClientSurface): Promise<HostedClient>;
 /**
  * The hosted server's 3.x surface: the same address with `?surface=v3`. Once
  * the hosted server serves 4.0 to every request that does not ask, only 3.x

package/dist/core/hosted-mcp.js

@@ -2,7 +2,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { getStoreAccessToken, OAuthError, readStoredOAuthToken, resolveMcpResourceUrl } from "./oauth.js";
 import { TOOLKIT_VERSION } from "./version.js";
-import { summerRequestHeaders } from "./agent-host.js";
+import { processSurface, summerRequestHeaders } from "./agent-host.js";
 /**
  * A client for the hosted Summer Engine MCP (mcp.summerengine.com), signed in
  * with the store sign-in ("summer login --store"). The local MCP mounts its
@@ -11,18 +11,20 @@ import { summerRequestHeaders } from "./agent-host.js";
  * store and publishing tools.
  */
 const CALL_TIMEOUT_MS = 120_000;
-export async function connectHostedMcp(url, token) {
+/** The handshake name the hosted server sees: the MCP server's own, or the `summer` CLI's, so usage tells them apart. */
+export const HOSTED_CLIENT_NAMES = { mcp: "summer-engine-local", cli: "summer-cli" };
+export async function connectHostedMcp(url, token, surface = processSurface()) {
     const transport = new StreamableHTTPClientTransport(new URL(url), {
         // A fresh (refreshed when near expiry) token on every request.
         fetch: async (input, init) => {
             const headers = new Headers(init?.headers);
-            for (const [name, value] of Object.entries(summerRequestHeaders({ tool: calledTool(init?.body), surface: "mcp" })))
+            for (const [name, value] of Object.entries(summerRequestHeaders({ tool: calledTool(init?.body), surface })))
                 headers.set(name, value);
             headers.set("authorization", `Bearer ${await token()}`);
             return fetch(input, { ...init, headers });
         },
     });
-    const client = new Client({ name: "summer-engine-local", version: TOOLKIT_VERSION });
+    const client = new Client({ name: HOSTED_CLIENT_NAMES[surface], version: TOOLKIT_VERSION });
     await client.connect(transport);
     const timeout = { timeout: CALL_TIMEOUT_MS };
     return {