summer-engine 2.6.6 → 2.8.0

package/dist/commands/logs.js

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import { readCreatorLogs } from "../lib/creator.js";
+export const logsCommand = new Command("logs")
+    .description("Read creator runtime logs")
+    .option("--project-id <id>", "Creator project ID")
+    .option("--release <id>", "Restrict logs to one release")
+    .option("--limit <count>", "Maximum log entries to return", "100")
+    .action(async (opts) => {
+    const limit = Number.parseInt(opts.limit, 10);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+        throw new Error("--limit must be between 1 and 1000. Recovery: pass a whole number in that range.");
+    }
+    await readCreatorLogs({
+        projectId: opts.projectId,
+        releaseId: opts.release,
+        limit,
+        face: "cli",
+    });
+});

package/dist/commands/mcp.js

@@ -3,8 +3,13 @@ import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../
 import { startMcpServer } from "../mcp/server.js";
 export const mcpCommand = new Command("mcp")
     .description("Start the MCP server for AI tool integration (Cursor, Claude Code, etc.)")
-    .action(async () => {
-    await startMcpServer();
+    .option("--project <path>", "Bind local engine tools to the editor running this project")
+    .option("--instance <id>", "Bind local engine tools to one exact Summer editor instance")
+    .action(async (opts) => {
+    await startMcpServer({
+        projectPath: opts.project,
+        instanceId: opts.instance,
+    });
 });
 mcpCommand
     .command("setup <agent>")

package/dist/commands/open.js

@@ -13,7 +13,7 @@ export const openCommand = new Command("open")
     }
     if (!existsSync(`${fullPath}/project.godot`)) {
         console.error(`No project.godot found in ${fullPath}\n` +
-            "This doesn't look like a Godot/Summer Engine project.\n" +
+            "This doesn't look like a Summer Engine project.\n" +
             "Create one with: summer create 3d-basic my-game");
         process.exit(1);
     }

package/dist/commands/publish.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const publishCommand: Command;

package/dist/commands/publish.js

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { publishCreator } from "../lib/creator.js";
+export const publishCommand = new Command("publish")
+    .description("Publish a confirmed creator release")
+    .argument("[project]", "Project root. Defaults to the current directory.")
+    .requiredOption("--artifact <path>", "Exact exported Summer .pck artifact")
+    .requiredOption("--version <value>", "Immutable release version")
+    .option("--manifest <path>", "Optional JSON release manifest")
+    .option("--project-id <id>", "Creator project ID")
+    .option("--channel <name>", "Release channel")
+    .option("--notes <text>", "Release notes")
+    .option("--confirm", "Confirm the exact project and channel after reviewing them")
+    .action(async (project, opts) => {
+    const result = await publishCreator({
+        project,
+        ...opts,
+        face: "cli",
+    });
+    console.log(JSON.stringify(result, null, 2));
+});

package/dist/commands/releases.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const releasesCommand: Command;

package/dist/commands/releases.js

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { listCreatorReleases } from "../lib/creator.js";
+export const releasesCommand = new Command("releases")
+    .description("List creator releases for a project")
+    .option("--project-id <id>", "Creator project ID")
+    .option("--limit <count>", "Maximum releases to return", "20")
+    .option("--cursor <value>", "Opaque cursor returned by the previous page")
+    .action(async (opts) => {
+    const limit = Number.parseInt(opts.limit, 10);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        throw new Error("--limit must be between 1 and 100. Recovery: pass a whole number in that range.");
+    }
+    const result = await listCreatorReleases({
+        projectId: opts.projectId,
+        limit,
+        cursor: opts.cursor,
+        face: "cli",
+    });
+    console.log(JSON.stringify(result, null, 2));
+});

package/dist/commands/run.js

@@ -100,7 +100,7 @@ export const runCommand = new Command("run")
         }
         if (!existsSync(join(fullProjectPath, "project.godot"))) {
             console.error(`No project.godot found in ${fullProjectPath}\n` +
-                "This doesn't look like a Godot/Summer Engine project.");
+                "This doesn't look like a Summer Engine project.");
             process.exit(1);
         }
     }

package/dist/commands/skills.js

@@ -367,7 +367,7 @@ function renderRuleBody(skill) {
 
 ${skill.description}
 
-Use Summer MCP tools for scene, editor, asset, play, and diagnostics operations. Use the host agent's normal file editing tools for scripts and other text files.
+Use Summer MCP tools for project files, scenes, editor state, assets, play, and diagnostics. Read project text with summer_read_file and mutate it with summer_replace_text or guarded summer_write_file.
 
 ## Skill
 

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

@@ -1,3 +1,4 @@
+import { type EngineSelection } from "./engine.js";
 export type EngineSnapshot = {
     ok: boolean;
     localPath?: string;
@@ -42,8 +43,9 @@ export declare class EngineApiClient {
     private port;
     private token;
     private targetIdentity;
-    constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string);
-    static connect(): Promise<EngineApiClient>;
+    private selection;
+    constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string, selection?: EngineSelection | null);
+    static connect(selection?: EngineSelection): Promise<EngineApiClient>;
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
     getBoundProjectIdHash(): string | undefined;
@@ -58,6 +60,7 @@ export declare class EngineApiClient {
     /** Identity to attach to a MUTATING command's options so the engine can reject
      *  a wrong-project write. Empty when unbound (engine then skips the check). */
     private identityOptions;
+    private requireBoundIdentity;
     private targetUrl;
     private request;
     /** Raw fetch with auth + timeout — returns the Response so callers can inspect
@@ -70,12 +73,20 @@ export declare class EngineApiClient {
      * result (HTTP 200 — dormant/older engine) OR the async lifecycle (202
      * {requestId} -> long-poll /api/ops/result until terminal). Compatible with
      * both — inspects the HTTP status, not a flag. `timeoutMs` is the poll loop's
-     * total budget; a long op that keeps advancing is not falsely timed out.
+     * client wait budget; expiry preserves the requestId and last known lifecycle
+     * state instead of pretending the accepted operation did not apply.
      */
     private _requestQueued;
     health(): Promise<unknown>;
     executeOps(ops: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
-    getSceneState(): Promise<unknown>;
+    /**
+     * Mutation path for MCP file tools. Unlike legacy executeOps callers, this
+     * fails closed when health did not provide a complete target identity. The
+     * bound hash is stamped last so a caller cannot override it in options.
+     */
+    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
+    readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
+    getSceneState(scenePath?: string): Promise<unknown>;
     getProjectState(): Promise<unknown>;
     getDiagnostics(): Promise<unknown>;
     inspectNode(path: string): Promise<unknown>;

package/dist/lib/api-client.js

@@ -1,7 +1,8 @@
 import { mkdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
-import { getApiToken, getApiPort, checkEngineHealth } from "./engine.js";
+import { randomUUID } from "node:crypto";
+import { getApiToken, getApiPort, checkEngineHealth, resolveEngineConnection, } from "./engine.js";
 import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -73,15 +74,25 @@ export class EngineApiClient {
     // preserves the pre-2.6.6 constructor contract for existing callers that only
     // supplied a projectIdHash.
     targetIdentity;
-    constructor(port, token, targetIdentity = {}) {
+    selection;
+    constructor(port, token, targetIdentity = {}, selection = null) {
         this.port = port;
         this.token = token;
         this.targetIdentity =
             typeof targetIdentity === "string"
                 ? { projectIdHash: targetIdentity }
                 : { ...targetIdentity };
-    }
-    static async connect() {
+        this.selection = selection ? { ...selection } : null;
+    }
+    static async connect(selection) {
+        if (selection) {
+            const connection = await resolveEngineConnection(selection);
+            return new EngineApiClient(connection.port, connection.token, {
+                instanceId: connection.health.instanceId,
+                projectId: connection.health.projectId,
+                projectIdHash: connection.health.projectIdHash,
+            }, { ...selection });
+        }
         const port = await getApiPort();
         const token = await getApiToken();
         if (!token) {
@@ -131,6 +142,13 @@ export class EngineApiClient {
         const projectIdHash = this.targetIdentity.projectIdHash;
         return projectIdHash ? { projectIdHash } : {};
     }
+    requireBoundIdentity() {
+        const { instanceId, projectId, projectIdHash } = this.targetIdentity;
+        if (!instanceId || !projectId || !projectIdHash) {
+            throw new Error("Safe project mutation requires a complete engine/project identity. Call summer_get_project_context to bind this MCP session, then retry. Nothing was written.");
+        }
+        return { projectIdHash };
+    }
     targetUrl(path) {
         const url = new URL(path, `http://127.0.0.1:${this.port}`);
         const { instanceId, projectId, projectIdHash } = this.targetIdentity;
@@ -190,24 +208,98 @@ export class EngineApiClient {
      * result (HTTP 200 — dormant/older engine) OR the async lifecycle (202
      * {requestId} -> long-poll /api/ops/result until terminal). Compatible with
      * both — inspects the HTTP status, not a flag. `timeoutMs` is the poll loop's
-     * total budget; a long op that keeps advancing is not falsely timed out.
+     * client wait budget; expiry preserves the requestId and last known lifecycle
+     * state instead of pretending the accepted operation did not apply.
      */
     async _requestQueued(method, path, body, timeoutMs) {
-        const res = await this._fetchRaw(method, path, body, timeoutMs);
+        // Mint the request ID before submission. If the acknowledgement or a later
+        // poll is lost, callers retain the exact identity needed to reconcile the
+        // accepted lifecycle instead of issuing an unsafe blind retry.
+        let clientRequestId;
+        let requestBody = body;
+        if (method === "POST") {
+            const bodyRecord = asRecord(body) ?? {};
+            const existingOptions = asRecord(bodyRecord.options) ?? {};
+            clientRequestId =
+                stringFrom(existingOptions.requestId) ?? `mcp-${randomUUID()}`;
+            requestBody = {
+                ...bodyRecord,
+                options: {
+                    ...existingOptions,
+                    requestId: clientRequestId,
+                },
+            };
+        }
+        let res;
+        try {
+            res = await this._fetchRaw(method, path, requestBody, timeoutMs);
+        }
+        catch (error) {
+            if (!clientRequestId)
+                throw error;
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`Summer Engine did not acknowledge request ${clientRequestId}; dispatch state is unknown. Do not retry blindly. ${detail}`);
+        }
         // 202 (queued) + 429 (backpressure, errorClass in body) are handled below;
         // any other non-2xx is a real transport error.
         if (!res.ok && res.status !== 202 && res.status !== 429) {
             const text = await res.text().catch(() => "");
-            throw new Error(`Engine API error ${res.status}: ${text.slice(0, 200)}`);
+            const suffix = clientRequestId ? ` (requestId ${clientRequestId})` : "";
+            throw new Error(`Engine API error ${res.status}${suffix}: ${text.slice(0, 200)}`);
         }
         const respBody = await res.json().catch(() => ({}));
         const classified = classifyOpsResponse(res.status, respBody);
         if (classified.mode === "legacy") {
+            if (res.status === 429) {
+                return {
+                    ...(asRecord(respBody) ?? {}),
+                    requestId: clientRequestId,
+                    terminalState: stringFrom(asRecord(respBody)?.terminalState) ?? "queue_full",
+                    dispatchState: "not_sent",
+                };
+            }
             return respBody;
         }
-        return pollOpToTerminal((waitMs) => this._pollResult(classified.requestId, waitMs), {
-            totalTimeoutMs: timeoutMs,
-        });
+        // The acknowledgement is authoritative for polling. Current engines echo
+        // the client-generated ID, while older engines may ignore options.requestId
+        // and mint their own; polling the submitted ID against those engines would
+        // wait forever on an unknown lifecycle.
+        const acceptedRequestId = classified.requestId || clientRequestId;
+        if (!acceptedRequestId) {
+            return {
+                status: "error",
+                error: "Summer Engine accepted an operation without returning a requestId; final state is uncertain.",
+                terminalState: "uncertain",
+                errorClass: "transient",
+                dispatchState: "uncertain",
+            };
+        }
+        try {
+            const terminal = await pollOpToTerminal((waitMs) => this._pollResult(acceptedRequestId, waitMs), {
+                totalTimeoutMs: timeoutMs,
+                requestId: acceptedRequestId,
+            });
+            if (clientRequestId && clientRequestId !== acceptedRequestId) {
+                terminal.submissionRequestId = clientRequestId;
+            }
+            return terminal;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return {
+                status: "error",
+                error: `Summer Engine accepted request ${acceptedRequestId}, but its final receipt could not be retrieved. ` +
+                    `The operation may still be running or may already have applied; inspect the target before retrying. ${detail}`,
+                terminalState: "uncertain",
+                errorClass: "transient",
+                dispatchState: "uncertain",
+                requestId: acceptedRequestId,
+                ...(clientRequestId && clientRequestId !== acceptedRequestId
+                    ? { submissionRequestId: clientRequestId }
+                    : {}),
+                lastKnownStatus: "unknown",
+            };
+        }
     }
     async health() {
         return this.request("GET", "/api/health");
@@ -218,12 +310,31 @@ export class EngineApiClient {
         // async-202 (Block E).
         // Attach the bound project identity so the engine rejects a write aimed at a
         // different project (identity_mismatch, atomic — before any op applies).
-        const merged = { ...this.identityOptions(), ...(options ?? {}) };
+        const merged = { ...(options ?? {}), ...this.identityOptions() };
         const body = Object.keys(merged).length ? { ops, options: merged } : { ops };
         return this._requestQueued("POST", "/api/ops", body, 120_000);
     }
-    async getSceneState() {
-        return this.request("GET", "/api/state/scene");
+    /**
+     * Mutation path for MCP file tools. Unlike legacy executeOps callers, this
+     * fails closed when health did not provide a complete target identity. The
+     * bound hash is stamped last so a caller cannot override it in options.
+     */
+    async executeIdentityBoundOps(ops, options) {
+        const identity = this.requireBoundIdentity();
+        return this.executeOps(ops, { ...(options ?? {}), ...identity });
+    }
+    async readProjectFile(path, maxBytes = 200_000) {
+        const query = new URLSearchParams({
+            path,
+            maxBytes: String(maxBytes),
+        });
+        return this.request("GET", `/api/state/read-file?${query.toString()}`);
+    }
+    async getSceneState(scenePath) {
+        const query = scenePath
+            ? `?scene=${encodeURIComponent(scenePath)}`
+            : "";
+        return this.request("GET", `/api/state/scene${query}`);
     }
     async getProjectState() {
         return this.request("GET", "/api/state/project");
@@ -457,6 +568,20 @@ export class EngineApiClient {
      * will fail and trigger a reconnect+retry if the client really is stale.
      */
     async credentialsChanged() {
+        if (this.selection) {
+            try {
+                const connection = await resolveEngineConnection(this.selection);
+                return (connection.port !== this.port ||
+                    connection.token !== this.token ||
+                    connection.health.instanceId !== this.targetIdentity.instanceId);
+            }
+            catch {
+                // A selected editor disappearing is real drift. Dropping the cached
+                // client makes the next connect report which project/instance is absent
+                // instead of silently following another editor's global pointer.
+                return true;
+            }
+        }
         try {
             const [port, token] = await Promise.all([getApiPort(), getApiToken()]);
             if (!token)

package/dist/lib/async-op-lifecycle.d.ts

@@ -40,6 +40,10 @@ export declare function classifyOpsResponse(httpStatus: number, body: unknown):
 export interface PollOpts {
     /** Hard wall-clock cap on the whole poll loop (ms). The per-tool budget. */
     totalTimeoutMs: number;
+    /** Stable client-generated correlation ID. Preserved in non-terminal timeout
+     *  receipts so callers can reconcile the accepted operation instead of
+     *  blindly retrying it. */
+    requestId?: string;
     /** Give up if the op hasn't advanced for this long (ms). Default = totalTimeoutMs. */
     noProgressTimeoutMs?: number;
     /** Server long-poll wait per GET (ms). Default 5000 — the engine holds the
@@ -54,7 +58,8 @@ export interface PollOpts {
 /**
  * Drive an async op to a terminal result by polling. `pollOnce(waitMs)` performs
  * one GET /api/ops/result (long-poll up to waitMs). Returns the engine's apply
- * dict with terminalState/errorClass/appliedSeq merged on top, or a synthetic
- * `timed_out` result if the budget is exhausted.
+ * dict with terminalState/errorClass/appliedSeq merged on top, or a truthful
+ * non-terminal `still_queued` / `still_running` / `uncertain` receipt when the
+ * client budget expires before the engine publishes a terminal.
  */
 export declare function pollOpToTerminal(pollOnce: (waitMs: number) => Promise<OpResultEnvelope>, opts: PollOpts): Promise<Record<string, unknown>>;

package/dist/lib/async-op-lifecycle.js

@@ -30,17 +30,37 @@ export function classifyOpsResponse(httpStatus, body) {
     }
     return { mode: "legacy", legacyResult: body };
 }
-const TIMED_OUT_RESULT = {
-    status: "error",
-    error: "Tool timeout - Summer Engine may be unresponsive",
-    terminalState: "timed_out",
-    errorClass: "transient",
-};
+function incompleteResult(requestId, lastStatus) {
+    if (lastStatus === "queued") {
+        return {
+            status: "error",
+            error: `Summer Engine accepted request ${requestId ?? "(unknown)"}, but it was still queued when this tool stopped waiting. ` +
+                "It may still run; do not retry blindly.",
+            terminalState: "still_queued",
+            errorClass: "transient",
+            dispatchState: "accepted",
+            requestId,
+            lastKnownStatus: "queued",
+        };
+    }
+    const wasRunning = lastStatus === "running";
+    return {
+        status: "error",
+        error: `Summer Engine did not provide a final receipt for request ${requestId ?? "(unknown)"}. ` +
+            `${wasRunning ? "The operation was still running" : "Its dispatch state is uncertain"}; inspect the target before retrying.`,
+        terminalState: wasRunning ? "still_running" : "uncertain",
+        errorClass: "transient",
+        dispatchState: wasRunning ? "sent" : "uncertain",
+        requestId,
+        lastKnownStatus: lastStatus ?? "unknown",
+    };
+}
 /**
  * Drive an async op to a terminal result by polling. `pollOnce(waitMs)` performs
  * one GET /api/ops/result (long-poll up to waitMs). Returns the engine's apply
- * dict with terminalState/errorClass/appliedSeq merged on top, or a synthetic
- * `timed_out` result if the budget is exhausted.
+ * dict with terminalState/errorClass/appliedSeq merged on top, or a truthful
+ * non-terminal `still_queued` / `still_running` / `uncertain` receipt when the
+ * client budget expires before the engine publishes a terminal.
  */
 export async function pollOpToTerminal(pollOnce, opts) {
     const now = opts.now ?? (() => Date.now());
@@ -57,6 +77,9 @@ export async function pollOpToTerminal(pollOnce, opts) {
         const env = await pollOnce(pollWaitMs);
         if (isTerminalStatus(env.status)) {
             const out = { ...(env.result ?? {}) };
+            const requestId = opts.requestId ?? env.requestId;
+            if (requestId)
+                out.requestId = requestId;
             if (env.terminalState)
                 out.terminalState = env.terminalState;
             if (env.errorClass)
@@ -76,7 +99,7 @@ export async function pollOpToTerminal(pollOnce, opts) {
             lastProgress = progressJson;
         }
         if (t - start >= opts.totalTimeoutMs || t - lastAdvanceAt >= noProgressMs) {
-            return { ...TIMED_OUT_RESULT };
+            return incompleteResult(opts.requestId ?? env.requestId, env.status);
         }
         await sleep(pacingMs);
     }

package/dist/lib/auth.d.ts

@@ -1,15 +1,43 @@
-export declare function getSummerDir(): string;
-export declare function getAuthToken(): Promise<string | null>;
-export declare function saveAuthToken(token: string): Promise<void>;
-export declare function getCloudToken(): Promise<string | null>;
-export declare function saveCloudToken(token: string): Promise<void>;
-export declare function getUserInfo(): Promise<{
+export { getSummerDir } from "./store.js";
+export interface SummerUserInfo {
     id: string;
     email: string;
     name?: string;
-} | null>;
-export declare function saveUserInfo(info: {
-    id: string;
-    email: string;
-    name?: string;
-}): Promise<void>;
+}
+export interface CredentialMetadata {
+    audience: string[];
+    scopes: string[];
+    tokenType?: string;
+    issuedAt?: string;
+    expiresAt?: string;
+}
+interface CredentialMetadataDocument {
+    schemaVersion: 1;
+    auth?: CredentialMetadata;
+    cloud?: CredentialMetadata;
+    creator?: CredentialMetadata;
+}
+export interface LoginSession {
+    token: string;
+    cloudToken?: string | null;
+    user?: SummerUserInfo;
+    scopes?: string[];
+    cloudScopes?: string[];
+}
+export declare function getAuthToken(): Promise<string | null>;
+export declare function saveAuthToken(token: string, scopes?: string[]): Promise<void>;
+export declare function getCloudToken(): Promise<string | null>;
+export declare function saveCloudToken(token: string, scopes?: string[]): Promise<void>;
+/**
+ * Summercraft creator tokens are a separate credential audience from the
+ * core-compatible Summer CLI JWT. Never store an sc_ token in auth-token:
+ * the engine reads that file and expects the summer-cli JWT contract.
+ */
+export declare function getCreatorToken(): Promise<string | null>;
+export declare function saveCreatorToken(token: string): Promise<void>;
+export declare function getUserInfo(): Promise<SummerUserInfo | null>;
+export declare function saveUserInfo(info: SummerUserInfo): Promise<void>;
+export declare function saveLoginSession(session: LoginSession): Promise<void>;
+export declare function getCredentialMetadata(): Promise<CredentialMetadataDocument>;
+export declare function clearAuthCredentials(): Promise<number>;
+export declare function assertCredentialScopes(metadata: CredentialMetadata | undefined, requiredScopes: string[]): void;