summer-engine 4.5.0 → 4.8.0

package/dist/cli/commands/login.js

@@ -1,21 +1,13 @@
 import { Command } from "commander";
 import { randomUUID } from "crypto";
 import open from "open";
-import { getAuthToken, saveLoginSession, } from "../../core/auth.js";
-import { summerRequestHeaders } from "../../core/agent-host.js";
+import { getAuthToken } from "../../core/auth.js";
+import { cliSessionLoginUrl, pollCliSession } from "../../core/cli-session.js";
 import { resolveGatewayUrl } from "../../core/config.js";
-import { readStoredOAuthToken, runStoreLogin } from "../../core/oauth.js";
-const POLL_INTERVAL_MS = 2000;
-// One generous window on ONE session id. First-time users may need to create an
-// account and confirm an email before they can approve the CLI. The gateway
-// never expires a pending session (the completed payload waits under this id
-// for pickup), so the worst mistake would be rotating ids mid-wait — the user
-// would approve the original browser tab while we poll a different session.
-const POLL_TIMEOUT_MS = 900000;
-const HEARTBEAT_MS = 30000;
+import { runStoreLogin, storeSignInWorks } from "../../core/oauth.js";
 export const loginCommand = new Command("login")
-    .description("Sign in to Summer in your browser: your Summer account, then the store, publishing and Grow tools in the same browser")
-    .option("--store", "Only the store sign-in (uploads with store.upload_file, item sync with economy.sync_items, the store, publishing, board and Grow tools); plain summer login does it too")
+    .description("Sign in to Summer in your browser: your Summer account, then the Summer sign-in (OAuth) the Summer API, store, publishing and Grow tools use, in the same browser")
+    .option("--store", "Only the Summer sign-in (OAuth): the Summer API (summer api, summer token), uploads with store.upload_file, item sync, the store, publishing, board and Grow tools; plain summer login does it too")
     .option("--no-store", "Only the Summer account sign-in; skip the store sign-in")
     .option("--force", "Force re-authentication even if already logged in")
     .action(async (opts) => {
@@ -25,7 +17,8 @@ export const loginCommand = new Command("login")
 export const STORE_STEP_TIMEOUT_MS = 3 * 60_000;
 const defaultCommandDependencies = {
     hasAuthToken: async () => Boolean(await getAuthToken()),
-    hasStoreSignIn: async () => Boolean(await readStoredOAuthToken()),
+    // Checked with the sign-in server: a stored token for a revoked app is not a sign-in.
+    hasStoreSignIn: () => storeSignInWorks(),
     login: () => runLogin(),
     storeLogin: ({ newClient, timeoutMs }) => runStoreLogin({ fetch, now: Date.now, openUrl: open, log: console.log, newClient, ...(timeoutMs ? { timeoutMs } : {}) }),
     log: console.log,
@@ -79,9 +72,6 @@ export async function runLoginCommand(opts, overrides = {}) {
         deps.log('Your Summer login is saved. To add the store, publishing and Grow tools later, run "summer login --store".');
     }
 }
-/** The gateway answered with a terminal 4xx — retrying the same URL cannot help. */
-class LoginRejectedError extends Error {
-}
 const defaultDependencies = {
     fetch,
     openUrl: open,
@@ -94,7 +84,7 @@ export async function runLogin(overrides = {}) {
     const deps = { ...defaultDependencies, ...overrides };
     const gatewayUrl = await resolveGatewayUrl();
     const sessionId = deps.randomId();
-    const loginUrl = `${gatewayUrl}/login?cli_session=${encodeURIComponent(sessionId)}`;
+    const loginUrl = cliSessionLoginUrl(gatewayUrl, sessionId);
     deps.log("Sign in at: " + loginUrl);
     deps.log("");
     try {
@@ -105,67 +95,6 @@ export async function runLogin(overrides = {}) {
         deps.log("");
     }
     deps.log("Waiting for authentication...");
-    const pollUrl = `${gatewayUrl}/api/auth/cli-login?session=${encodeURIComponent(sessionId)}`;
-    const startTime = deps.now();
-    let lastHeartbeat = startTime;
-    let lastError = null;
-    while (deps.now() - startTime < POLL_TIMEOUT_MS) {
-        await deps.sleep(POLL_INTERVAL_MS);
-        if (deps.now() - lastHeartbeat >= HEARTBEAT_MS) {
-            lastHeartbeat = deps.now();
-            deps.log('Still waiting — finish signing in (or creating your account) in the browser, then click "Yes, Sign In". Same link: ' +
-                loginUrl +
-                (lastError ? ` (last error: ${lastError})` : ""));
-        }
-        // Only the network round-trip is retried. A completed session is handled
-        // OUTSIDE this try: saveLoginSession rejecting the token (mismatched sub,
-        // non-CLI token type, already expired) is terminal — the gateway will
-        // return the same payload forever, so polling on would only bury the
-        // recovery message under a 15-minute timeout.
-        let completed = null;
-        try {
-            const res = await deps.fetch(pollUrl, {
-                headers: summerRequestHeaders({ surface: "cli" }),
-                signal: AbortSignal.timeout(5000),
-            });
-            if (!res.ok) {
-                if (res.status === 503) {
-                    lastError =
-                        "The login service is unavailable (Redis/auth is not configured).";
-                }
-                else if (res.status >= 500) {
-                    lastError = `The login service failed (${res.status}).`;
-                }
-                else if (res.status === 429 || res.status === 408) {
-                    lastError = `The login service asked us to slow down (${res.status}).`;
-                }
-                else {
-                    // 401/403/404 and the other 4xx are terminal: this URL will not
-                    // start succeeding on its own.
-                    throw new LoginRejectedError(`The login request was rejected (${res.status}). Recovery: check that gateway.url (${gatewayUrl}) is the Summer gateway you meant, then run "summer login" again.`);
-                }
-                continue;
-            }
-            const data = (await res.json());
-            if (data.status === "pending")
-                continue;
-            if (data.status === "complete" && data.token) {
-                completed = { token: data.token, user: data.user, scopes: data.scopes };
-            }
-            else {
-                lastError = "The login service returned an incomplete authentication result.";
-            }
-        }
-        catch (err) {
-            if (err instanceof LoginRejectedError)
-                throw err;
-            lastError = err instanceof Error ? err.message : "Network error";
-        }
-        if (completed) {
-            await saveLoginSession(completed);
-            deps.log(`\nLogged in as ${completed.user?.email || "unknown"}`);
-            return;
-        }
-    }
-    throw new Error(`Login timed out after ${Math.round(POLL_TIMEOUT_MS / 60000)} minutes.${lastError ? ` Last error: ${lastError}` : ""} Recovery: run "summer login" again and complete "Yes, Sign In" in the browser tab it opens.`);
+    const completed = await pollCliSession(gatewayUrl, sessionId, deps);
+    deps.log(`\nLogged in as ${completed.user?.email || "unknown"}`);
 }

package/dist/cli/commands/setup.js

@@ -2,8 +2,10 @@ import { spawnSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { relative } from "path";
 import { Command, Option } from "commander";
-import { configureAgentMcp, configureSummerGamesMcp, resolveAgentSelection, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
+import { configureAgentMcp, configureSummerGamesMcp, resolveAgentSelection, resolveBundledRuntime, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
 import { previewNote, setupSkills } from "../../installer/setup.js";
+import { detectAgents } from "../../installer/agent-detect.js";
+import { SetupError, toStepError } from "../../installer/setup-error.js";
 import { printDoctorResult, runDoctor } from "../../core/capabilities/doctor.js";
 import { brandLine, c, sym, tildeify } from "../../core/format.js";
 import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
@@ -23,6 +25,8 @@ const MCP_ENTRY_FLAGS = [
     ["localDev", "--local-dev"],
     ["channel", "--channel"],
     ["profile", "--profile"],
+    ["runtime", "--runtime"],
+    ["packageDir", "--package-dir"],
 ];
 export const setupCommand = new Command("setup")
     .description("Configure Summer Engine for an AI agent and run diagnostics. For agents that can sign in to it, it also adds Summer Games (summer-games). --cli installs the skills only: the agent runs summer commands in its shell, with no MCP server.")
@@ -32,6 +36,9 @@ export const setupCommand = new Command("setup")
     .option("--dry-run", "Show planned changes without writing files")
     .option("--print", "Print the MCP config snippet instead of writing files")
     .option("--local-dev", "Point the agent at this checkout's built CLI (node <repo>/dist/bin/summer.js mcp) instead of npx summer-engine@latest — for testing unpublished builds. SUMMER_DEV=1 does the same.")
+    .option("--runtime <node>", "Run the MCP server with this node executable instead of npx: <node> <package-dir>/dist/bin/summer.js mcp. Needs --package-dir. For installers that ship their own Node.js")
+    .option("--package-dir <dir>", "The summer-engine package folder (package.json and dist/bin/summer.js) that --runtime runs")
+    .option("--detect", "List every supported agent: installed or not, its MCP config file, and whether it already lists summer-engine. Writes nothing; takes no agent. Use with --json")
     .option("--channel <dist-tag>", "npm dist-tag or exact version the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; a CLI newer than npm latest pins next when next is this version, else this version). SUMMER_CHANNEL does the same.")
     .option("--yes", "Apply practical setup steps without prompting")
     .option("--no-games", "Do not add the Summer Games MCP (summer-games: friends, parties and messages as you, signed in through summer.games)")
@@ -49,8 +56,52 @@ export const setupCommand = new Command("setup")
     // Pre-reversal opt-in, kept one release as a hidden no-op so old scripts still parse.
     .addOption(new Option("--include-preview", "No-op: preview skills install by default").hideHelp())
     .action(async (agentArg, opts) => {
-    const agent = resolveAgentSelection(agentArg, opts.agent);
-    const scope = resolveConfigScope(opts.scope);
+    if (opts.detect) {
+        runDetect(agentArg, opts);
+        return;
+    }
+    if (!opts.json) {
+        await setupAgent(agentArg, opts);
+        return;
+    }
+    // --json: one JSON document on stdout, also when setup cannot start.
+    try {
+        await setupAgent(agentArg, opts);
+    }
+    catch (error) {
+        console.log(JSON.stringify({ ok: false, error: toStepError(error, "setup_failed"), steps: [] }, null, 2));
+        process.exit(1);
+    }
+});
+/**
+ * Runs one step. With --json a throw becomes the step's coded error and the
+ * other steps still run; without it the throw ends setup as it always did.
+ */
+async function runStep(json, fallbackCode, run) {
+    if (!json)
+        return { value: await run() };
+    try {
+        return { value: await run() };
+    }
+    catch (error) {
+        return { value: null, error: toStepError(error, fallbackCode) };
+    }
+}
+async function setupAgent(agentArg, opts) {
+    let agent;
+    try {
+        agent = resolveAgentSelection(agentArg, opts.agent);
+    }
+    catch (error) {
+        throw new SetupError("unknown_agent", error instanceof Error ? error.message : String(error));
+    }
+    let scope;
+    try {
+        scope = resolveConfigScope(opts.scope);
+    }
+    catch (error) {
+        throw new SetupError("invalid_scope", error instanceof Error ? error.message : String(error));
+    }
     if (opts.removeAllowRules) {
         await removeCliAllowRules(agent, scope, opts);
         return;
@@ -63,8 +114,14 @@ export const setupCommand = new Command("setup")
     if (opts.allowRules)
         console.error(`  ${sym.warn()}  ${c.yellow("--allow-rules works with --cli only (the MCP server asks through the agent's own tool approvals); no rules were added.")}`);
     const profile = resolveSetupProfile(opts);
-    const defaultChannel = await resolveDefaultChannel(cliVersion);
-    const config = await configureAgentMcp({
+    const runtime = resolveBundledRuntime(opts.runtime, opts.packageDir);
+    if (runtime && (opts.localDev || opts.channel)) {
+        throw new SetupError("invalid_option", `--runtime runs a bundled summer-engine; leave out ${opts.localDev ? "--local-dev" : "--channel"}.`);
+    }
+    const json = Boolean(opts.json);
+    // A bundled runtime runs the package beside it, so npm's tags do not matter (and no network call is made).
+    const defaultChannel = runtime ? { channel: "latest" } : await resolveDefaultChannel(cliVersion);
+    const mcp = await runStep(json, "mcp_entry_failed", () => configureAgentMcp({
         agent,
         scope,
         dryRun: opts.dryRun,
@@ -72,14 +129,19 @@ export const setupCommand = new Command("setup")
         localDev: Boolean(opts.localDev) || process.env.SUMMER_DEV === "1",
         channel: opts.channel ?? process.env.SUMMER_CHANNEL ?? defaultChannel.channel,
         profile,
-    });
-    const games = opts.games === false || opts.assetsOnly || opts.print
-        ? null
-        : await configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun });
-    if (!opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
-        console.log(`  ${c.dim(defaultChannel.note)}`);
-    }
-    const skills = setupSkills(agent, {
+        runtime: runtime ?? undefined,
+    }));
+    const config = mcp.value;
+    const gamesSkipped = opts.games === false || opts.assetsOnly || opts.print;
+    const gamesStep = gamesSkipped
+        ? { value: null }
+        : await runStep(json, "summer_games_failed", () => configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun }));
+    const games = gamesStep.value;
+    if (!runtime && !opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
+        // On stderr with --json, so stdout stays one JSON document.
+        (json ? console.error : console.log)(`  ${c.dim(defaultChannel.note)}`);
+    }
+    const skillsStep = await runStep(json, "skills_install_failed", () => setupSkills(agent, {
         dryRun: Boolean(opts.dryRun || opts.print),
         yes: Boolean(opts.yes),
         force: Boolean(opts.force),
@@ -87,26 +149,104 @@ export const setupCommand = new Command("setup")
         recommended: Boolean(opts.recommended),
         stableOnly: Boolean(opts.stableOnly),
         assetsOnly: Boolean(opts.assetsOnly),
-    });
-    const projectFiles = setupProjectInstructions(opts);
+    }));
+    const skills = skillsStep.value ?? { status: "failed", message: skillsStep.error?.message ?? "Skill install failed." };
+    const projectStep = await runStep(json, "project_files_failed", () => setupProjectInstructions(opts));
+    const projectFiles = projectStep.value;
     const doctor = await runDoctor({ quiet: true });
-    if (opts.json) {
-        console.log(JSON.stringify({
-            ok: doctor.ok && skills.status !== "failed",
-            config,
-            games,
-            skills,
-            projectFiles,
-            doctor,
-        }, null, 2));
-    }
-    else {
-        printSetupResult(config, games, skills, doctor, projectFiles);
+    if (json) {
+        const steps = [
+            mcpEntryStep(config, mcp.error),
+            summerGamesStep(agent, games, gamesSkipped ? "skipped" : null, gamesStep.error, Boolean(opts.dryRun)),
+            skillsStepResult(skills, skillsStep.error),
+            projectFilesStep(projectFiles, projectStep.error, opts),
+            doctorStep(doctor),
+        ];
+        const ok = steps.every((step) => step.ok);
+        console.log(JSON.stringify({ ok, agent, scope, steps, config, games, skills, projectFiles, doctor }, null, 2));
+        if (!ok)
+            process.exit(1);
+        return;
     }
+    printSetupResult(config, games, skills, doctor, projectFiles);
     if (!doctor.ok || skills.status === "failed") {
         process.exit(1);
     }
-});
+}
+function mcpEntryStep(config, error) {
+    if (!config)
+        return { step: "mcp_entry", ok: false, status: "failed", error: error ?? { code: "mcp_entry_failed", message: "The MCP entry was not written." } };
+    const status = config.print ? "printed" : config.dryRun ? (config.changed ? "planned" : "unchanged") : config.wrote ? "written" : "unchanged";
+    return { step: "mcp_entry", ok: true, status, path: config.path, ...(config.warnings.length ? { warnings: config.warnings } : {}) };
+}
+function summerGamesStep(agent, games, skipped, error, dryRun) {
+    if (error)
+        return { step: "summer_games", ok: false, status: "failed", error };
+    if (skipped)
+        return { step: "summer_games", ok: true, status: "skipped" };
+    // configureSummerGamesMcp returns null only for agents without a Summer Games entry shape.
+    if (!games)
+        return { step: "summer_games", ok: true, status: "not_supported", warnings: [`${agentLabel(agent)} gets no Summer Games entry from setup.`] };
+    const status = games.existingName ? "exists" : dryRun ? (games.changed ? "planned" : "unchanged") : games.wrote ? "written" : "unchanged";
+    return { step: "summer_games", ok: true, status, path: games.path };
+}
+function skillsStepResult(skills, error) {
+    if (skills.status === "failed") {
+        return {
+            step: "skills",
+            ok: false,
+            status: "failed",
+            error: error ?? { code: "skills_install_failed", message: [skills.message, skills.stderr].filter(Boolean).join(" ") },
+        };
+    }
+    return { step: "skills", ok: true, status: skills.status, ...(skills.destination ? { path: skills.destination } : {}) };
+}
+function projectFilesStep(project, error, opts) {
+    if (error)
+        return { step: "project_files", ok: false, status: "failed", error };
+    if (!project) {
+        const skipped = opts.projectFiles === false || opts.print || opts.assetsOnly;
+        return { step: "project_files", ok: true, status: skipped ? "skipped" : "not_in_project" };
+    }
+    // A file setup leaves alone (a link out of the project, a broken Summer block) is a warning, as in the human output.
+    const warnings = project.files.filter((file) => file.reason).map((file) => `${file.path}: ${file.reason}`);
+    return { step: "project_files", ok: true, status: project.written ? "written" : "planned", path: project.root, ...(warnings.length ? { warnings } : {}) };
+}
+function doctorStep(doctor) {
+    if (doctor.ok)
+        return { step: "doctor", ok: true, status: "passed" };
+    const failed = doctor.checks.filter((check) => check.status === "fail");
+    return {
+        step: "doctor",
+        ok: false,
+        status: "failed",
+        error: { code: "doctor_failed", message: failed.map((check) => `${check.label}: ${check.message}`).join("; ") || "Doctor found a problem." },
+    };
+}
+/** `summer setup --detect`: every agent, installed or not, and whether it is linked. Writes nothing. */
+function runDetect(agentArg, opts) {
+    if (agentArg || opts.agent) {
+        const message = "--detect lists every agent; leave out the agent name.";
+        if (!opts.json)
+            throw new Error(message);
+        console.log(JSON.stringify({ ok: false, error: { code: "invalid_option", message }, agents: [] }, null, 2));
+        process.exit(1);
+        return;
+    }
+    const agents = detectAgents();
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, os: process.platform, agents }, null, 2));
+        return;
+    }
+    console.log("");
+    for (const agent of agents) {
+        if (agent.status === "legacy" && !agent.installed)
+            continue;
+        const mark = agent.installed ? sym.ok() : c.dim("-");
+        const linked = agent.mcpEntry ? c.dim(`linked  ${tildeify(agent.configPath)}`) : agent.installed ? c.dim(`not linked: summer setup ${agent.id}`) : c.dim("not found");
+        console.log(`  ${mark}  ${agent.label}  ${linked}`);
+    }
+}
 /**
  * `summer setup <agent> --cli`: the skills (the asset skills with --assets-only)
  * and no MCP server, so the agent runs Summer as `summer <area> <action>` in its
@@ -117,7 +257,7 @@ async function setupCliOnly(agent, scope, opts) {
     const spec = agentSpec(agent);
     const mcpFlags = MCP_ENTRY_FLAGS.filter(([key]) => opts[key] !== undefined && opts[key] !== false).map(([, flag]) => flag);
     if (mcpFlags.length > 0) {
-        throw new Error(`${mcpFlags.join(", ")} sets up the MCP entry, and --cli writes none. Leave ${mcpFlags.length === 1 ? "it" : "them"} out, or leave out --cli.`);
+        throw new SetupError("invalid_option", `${mcpFlags.join(", ")} sets up the MCP entry, and --cli writes none. Leave ${mcpFlags.length === 1 ? "it" : "them"} out, or leave out --cli.`);
     }
     const refusal = cliSetupRefusal(spec);
     if (refusal)
@@ -278,11 +418,11 @@ async function recordedMcpEntry(agent, scope) {
 function resolveSetupProfile(opts) {
     const profile = opts.profile === undefined ? undefined : parseProfile(opts.profile);
     if (profile === null) {
-        throw new Error(`Unknown --profile "${opts.profile}". Use one of: ${Object.keys(PROFILES).join(", ")}.`);
+        throw new SetupError("invalid_option", `Unknown --profile "${opts.profile}". Use one of: ${Object.keys(PROFILES).join(", ")}.`);
     }
     if (opts.assetsOnly) {
         if (profile && profile !== "assets")
-            throw new Error("--assets-only uses the assets profile; leave out --profile.");
+            throw new SetupError("invalid_option", "--assets-only uses the assets profile; leave out --profile.");
         return "assets";
     }
     return profile;
@@ -305,7 +445,10 @@ function printSetupResult(config, games, skills, doctor, projectFiles) {
     else {
         console.log(`  ${sym.ok()}  Already linked to ${c.bold(label)}  ${c.dim(tildeify(config.path))}`);
     }
-    if (config.localDev) {
+    if (config.runtime) {
+        console.log(`  ${c.dim("(bundled runtime)")}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
+    }
+    else if (config.localDev) {
         console.log(`  ${c.dim("(local dev)")}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
     }
     else if (config.channel !== "latest") {

package/dist/cli/commands/token.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+/**
+ * `summer token`: print the Summer sign-in's current access token (Supabase
+ * OAuth, about one hour; refreshed first when it is about to expire), for
+ * curl against the Summer API:
+ *
+ *   curl -H "Authorization: Bearer $(summer token)" https://www.summerengine.com/v1/models
+ *
+ * Only the token goes to stdout; a missing sign-in says so on stderr and exits 1.
+ */
+export interface TokenCommandDependencies {
+    token: () => Promise<string>;
+    print: (line: string) => void;
+    printError: (line: string) => void;
+}
+export declare function runTokenCommand(overrides?: Partial<TokenCommandDependencies>): Promise<number>;
+export declare const tokenCommand: Command;

package/dist/cli/commands/token.js

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { getStoreAccessToken, OAuthError } from "../../core/oauth.js";
+const defaults = () => ({
+    token: () => getStoreAccessToken(),
+    print: (line) => process.stdout.write(`${line}\n`),
+    printError: (line) => console.error(line),
+});
+export async function runTokenCommand(overrides = {}) {
+    const deps = { ...defaults(), ...overrides };
+    try {
+        deps.print(await deps.token());
+        return 0;
+    }
+    catch (error) {
+        deps.printError(error instanceof OAuthError ? 'This computer is not signed in to Summer. Run "summer login", then retry.' : error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+export const tokenCommand = new Command("token")
+    .description("Print a one-hour Summer API access token from this computer's Summer sign-in (summer login), for curl: Authorization: Bearer $(summer token)")
+    .action(async () => {
+    const code = await runTokenCommand();
+    if (code)
+        process.exitCode = code;
+});

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { loginCommand } from "./commands/login.js";
 import { logoutCommand } from "./commands/logout.js";
+import { tokenCommand } from "./commands/token.js";
 import { statusCommand } from "./commands/status.js";
 import { runCommand } from "./commands/run.js";
 import { openCommand } from "./commands/open.js";
@@ -18,6 +19,7 @@ import { configCommand } from "./commands/config.js";
 import { eventsCommand } from "./commands/events.js";
 import { previewCommand } from "./commands/preview.js";
 import { toolCommand } from "./commands/tool.js";
+import { apiCommand } from "./commands/api.js";
 import { opsCliCommands } from "./commands/ops.js";
 import { getBanner } from "./banner.js";
 import { runRootAction } from "./root-action.js";
@@ -42,6 +44,7 @@ export function runCli(mcpCommand) {
     program.addCommand(installCommand);
     program.addCommand(loginCommand);
     program.addCommand(logoutCommand);
+    program.addCommand(tokenCommand);
     program.addCommand(statusCommand);
     program.addCommand(runCommand);
     program.addCommand(openCommand);
@@ -58,6 +61,7 @@ export function runCli(mcpCommand) {
     program.addCommand(eventsCommand);
     program.addCommand(previewCommand);
     program.addCommand(toolCommand);
+    program.addCommand(apiCommand);
     // The 4.0 operation catalog (`summer <area> <action>`); SUMMER_SURFACE=v3 leaves it out.
     if (resolveSurface(undefined) === "v4") {
         for (const command of opsCliCommands())

package/dist/core/api-client.d.ts

@@ -74,7 +74,6 @@ export type EventsPollParams = {
      *  truncated:true when the page was full. */
     limit?: number;
 };
-/** rebind() could not re-read engine health; the session identity is unchanged. */
 export declare class EngineRebindError extends Error {
     constructor(message: string);
 }
@@ -152,6 +151,11 @@ export declare class EngineApiClient {
      * feed its ONE response in here instead of issuing a second request.
      */
     private _resolveQueuedResponse;
+    /**
+     * One Studio page op in the app's own Studio tab (capabilities.studioPage):
+     * POST /api/studio {op, input} -> 202, then its one terminal envelope.
+     */
+    studioPage(op: string, input: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     health(): Promise<unknown>;
     /**
      * One long-poll of GET /api/events/poll (the engine's events channel). The

package/dist/core/api-client.js

@@ -3,6 +3,7 @@ import { tmpdir } from "os";
 import { join } from "path";
 import { randomUUID } from "node:crypto";
 import { checkEngineHealth, discoverRegistryConnection, engineNotRunningError, engineSelectionFromEnv, getApiPort, getApiToken, resolveEngineConnection, } from "./engine.js";
+import { AGENT_HOST_HEADER, resolveAgentHost } from "./agent-host.js";
 import { asRecord, boolFrom, numberFrom, stringFrom } from "./util/json.js";
 import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 import { pickPlayDeterminism } from "./capabilities/play-determinism.js";
@@ -56,6 +57,16 @@ function withoutImageData(payload) {
     return metadata;
 }
 /** rebind() could not re-read engine health; the session identity is unchanged. */
+/**
+ * The agent app driving the engine (Claude Code, Codex, ...), so the person's
+ * editor can say who is working ("Claude Code · Placing 12 trees"). Local
+ * only: the engine on this computer reads it for its activity line; it never
+ * leaves the machine from here, so the telemetry opt-out does not apply.
+ */
+function engineAgentHeader() {
+    const host = resolveAgentHost().id;
+    return host && host !== "unknown" ? { [AGENT_HOST_HEADER]: host } : {};
+}
 export class EngineRebindError extends Error {
     constructor(message) {
         super(message);
@@ -254,6 +265,7 @@ export class EngineApiClient {
         const headers = {
             Authorization: `Bearer ${this.token}`,
             "Content-Type": "application/json",
+            ...engineAgentHeader(),
         };
         const res = await fetch(url, {
             method,
@@ -282,6 +294,7 @@ export class EngineApiClient {
             headers: {
                 Authorization: `Bearer ${this.token}`,
                 "Content-Type": "application/json",
+                ...engineAgentHeader(),
             },
             body: body !== undefined ? JSON.stringify(body) : undefined,
             signal: AbortSignal.timeout(timeoutMs),
@@ -404,6 +417,14 @@ export class EngineApiClient {
             };
         }
     }
+    /**
+     * One Studio page op in the app's own Studio tab (capabilities.studioPage):
+     * POST /api/studio {op, input} -> 202, then its one terminal envelope.
+     */
+    async studioPage(op, input, timeoutMs = 90_000) {
+        const path = this.getEngineCapabilities()?.studioPage?.path ?? "/api/studio";
+        return this._requestQueued("POST", path, { op, input }, timeoutMs);
+    }
     async health() {
         return this.request("GET", "/api/health");
     }

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

@@ -23,7 +23,7 @@ interface DoctorOptions {
 }
 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 const MIN_NODE_MAJOR = 22;
 export declare function checkNodeVersion(nodeVersion?: string): DoctorCheck;
 export declare function checkLogin(): Promise<DoctorCheck>;
 /**

package/dist/core/capabilities/doctor.js

@@ -49,7 +49,7 @@ export async function runDoctor(options = {}) {
     return result;
 }
 /** The oldest Node major the package supports: `engines.node` in package.json. */
-export const MIN_NODE_MAJOR = 20;
+export const MIN_NODE_MAJOR = 22;
 export function checkNodeVersion(nodeVersion = process.versions.node) {
     const major = Number(nodeVersion.split(".")[0]);
     const shown = `v${nodeVersion.replace(/^v/, "")}`;

package/dist/core/capabilities/game-task-plan.d.ts

@@ -16,14 +16,14 @@ export declare const gameTaskPlanInputSchema: z.ZodObject<{
     verification: z.ZodDefault<z.ZodEnum<["none", "fast", "full"]>>;
 }, "strip", z.ZodTypeAny, {
     mode: "auto" | "ship" | "debug" | "asset" | "new-game" | "feature" | "playtest" | "polish";
-    target: "auto" | "audio" | "level" | "npc" | "ui" | "2d" | "3d" | "animation" | "multiplayer";
+    target: "auto" | "audio" | "level" | "npc" | "ui" | "3d" | "2d" | "animation" | "multiplayer";
     goal: string;
     assetPolicy: "reuse-first" | "ask-before-paid-generation" | "no-paid-generation" | "generate-when-clearly-needed";
     verification: "none" | "full" | "fast";
 }, {
     goal: string;
     mode?: "auto" | "ship" | "debug" | "asset" | "new-game" | "feature" | "playtest" | "polish" | undefined;
-    target?: "auto" | "audio" | "level" | "npc" | "ui" | "2d" | "3d" | "animation" | "multiplayer" | undefined;
+    target?: "auto" | "audio" | "level" | "npc" | "ui" | "3d" | "2d" | "animation" | "multiplayer" | undefined;
     assetPolicy?: "reuse-first" | "ask-before-paid-generation" | "no-paid-generation" | "generate-when-clearly-needed" | undefined;
     verification?: "none" | "full" | "fast" | undefined;
 }>;

package/dist/core/capabilities/navigation/open.d.ts

@@ -126,6 +126,9 @@ export declare function isAllowedNavigationOrigin(origin: string): boolean;
  *  escapes, nothing that could name a file outside the project. Returns the
  *  problem, or null when the path is acceptable. */
 export declare function resPathProblem(value: string): string | null;
+/** A summerengine.com Studio path (`/studio`, `/studio/games`, `/studio?tab=assets`), the
+ *  only paths the engine's `studio` Navigate row opens. */
+export declare function isStudioPath(path: string): boolean;
 export declare function tokenize(text: string): string[];
 /** Rank every target for a free-text query. Exported for tests. */
 export declare function rankTargets(query: string, surface?: OpenSurface): OpenMatch[];