summer-engine 2.6.5 → 2.7.0

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

@@ -33,11 +33,16 @@ export type EngineSnapshot = {
      *  (item 4, client-side drift check). */
     projectMismatch?: boolean;
 };
+type EngineTargetIdentity = {
+    instanceId?: string;
+    projectId?: string;
+    projectIdHash?: string;
+};
 export declare class EngineApiClient {
     private port;
     private token;
-    private boundProjectIdHash?;
-    constructor(port: number, token: string, boundProjectIdHash?: string);
+    private targetIdentity;
+    constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string);
     static connect(): Promise<EngineApiClient>;
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
@@ -46,13 +51,15 @@ export declare class EngineApiClient {
      * Re-read health and rebind to the currently-open project. Called by
      * summer_get_project_context so the agent can INTENTIONALLY follow a project
      * switch (the deliberate escape hatch after an identity_mismatch). Returns the
-     * new bound hash. Reads carry no identity, so this always reaches the engine
-     * even when a mutation would be rejected.
+     * new bound hash. The direct health probe is intentionally unscoped, so it can
+     * reach the current engine even when bound requests would be rejected.
      */
     rebind(): Promise<string | undefined>;
     /** 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
      *  the status (202 queued vs 200 legacy). */
@@ -64,12 +71,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>;
@@ -125,3 +140,4 @@ export declare class EngineApiClient {
      */
     credentialsChanged(): Promise<boolean>;
 }
+export {};

package/dist/lib/api-client.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
+import { randomUUID } from "node:crypto";
 import { getApiToken, getApiPort, checkEngineHealth } from "./engine.js";
 import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 function asRecord(value) {
@@ -67,17 +68,19 @@ function withoutImageData(payload) {
 export class EngineApiClient {
     port;
     token;
-    // The project this session is BOUND to — the projectIdHash reported by the
-    // engine when this client first connected. Sent on every mutating op so the
-    // engine's identity guard (local_api_server.cpp ~271-302) atomically rejects a
-    // write aimed at a DIFFERENT project (e.g. after the user switched projects
-    // in-place). Health is the only identity signal the MCP has — /api/state/project
-    // carries no path and /api/health exposes only projectIdHash, not the raw id.
-    boundProjectIdHash;
-    constructor(port, token, boundProjectIdHash) {
+    // The engine and project this session is bound to. Every request carries the
+    // identity captured from health so the engine can reject requests after an
+    // in-place project switch or an unexpected instance change. The string form
+    // preserves the pre-2.6.6 constructor contract for existing callers that only
+    // supplied a projectIdHash.
+    targetIdentity;
+    constructor(port, token, targetIdentity = {}) {
         this.port = port;
         this.token = token;
-        this.boundProjectIdHash = boundProjectIdHash;
+        this.targetIdentity =
+            typeof targetIdentity === "string"
+                ? { projectIdHash: targetIdentity }
+                : { ...targetIdentity };
     }
     static async connect() {
         const port = await getApiPort();
@@ -94,34 +97,64 @@ export class EngineApiClient {
         // rebinds to the current project. An in-place project switch keeps the same
         // token, so the cached client retains its original binding and the engine
         // rejects mismatched mutations until the agent explicitly rebinds.
-        return new EngineApiClient(port, token, health.projectIdHash);
+        return new EngineApiClient(port, token, {
+            instanceId: health.instanceId,
+            projectId: health.projectId,
+            projectIdHash: health.projectIdHash,
+        });
     }
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
     getBoundProjectIdHash() {
-        return this.boundProjectIdHash;
+        return this.targetIdentity.projectIdHash;
     }
     /**
      * Re-read health and rebind to the currently-open project. Called by
      * summer_get_project_context so the agent can INTENTIONALLY follow a project
      * switch (the deliberate escape hatch after an identity_mismatch). Returns the
-     * new bound hash. Reads carry no identity, so this always reaches the engine
-     * even when a mutation would be rejected.
+     * new bound hash. The direct health probe is intentionally unscoped, so it can
+     * reach the current engine even when bound requests would be rejected.
      */
     async rebind() {
         const health = await checkEngineHealth(this.port);
         if (health) {
-            this.boundProjectIdHash = health.projectIdHash;
+            this.targetIdentity = {
+                instanceId: health.instanceId,
+                projectId: health.projectId,
+                projectIdHash: health.projectIdHash,
+            };
         }
-        return this.boundProjectIdHash;
+        return this.targetIdentity.projectIdHash;
     }
     /** 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). */
     identityOptions() {
-        return this.boundProjectIdHash ? { projectIdHash: this.boundProjectIdHash } : {};
+        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;
+        if (instanceId)
+            url.searchParams.set("instanceId", instanceId);
+        if (projectId)
+            url.searchParams.set("projectId", projectId);
+        if (projectIdHash)
+            url.searchParams.set("projectIdHash", projectIdHash);
+        if (instanceId && projectId && projectIdHash) {
+            url.searchParams.set("projectIdentityVersion", "1");
+        }
+        return url.toString();
     }
     async request(method, path, body) {
-        const url = `http://127.0.0.1:${this.port}${path}`;
+        const url = this.targetUrl(path);
         const headers = {
             Authorization: `Bearer ${this.token}`,
             "Content-Type": "application/json",
@@ -141,7 +174,7 @@ export class EngineApiClient {
     /** Raw fetch with auth + timeout — returns the Response so callers can inspect
      *  the status (202 queued vs 200 legacy). */
     async _fetchRaw(method, path, body, timeoutMs) {
-        return fetch(`http://127.0.0.1:${this.port}${path}`, {
+        return fetch(this.targetUrl(path), {
             method,
             headers: {
                 Authorization: `Bearer ${this.token}`,
@@ -165,24 +198,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");
@@ -193,12 +300,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");
@@ -305,18 +431,17 @@ export class EngineApiClient {
         const { format, mime, ext } = snapshotFormat(payload);
         const buffer = Buffer.from(base64, "base64");
         const localPath = await this.writeSnapshotFile(kind, buffer, ext);
-        // Client-side identity drift check (item 4). The engine's identity guard only
-        // acts on options.projectIdHash inside a queued command; a GET snapshot from
-        // `fetch` carries no reliable body, so we cannot count on the engine to reject
-        // a drifted read. Re-read health and compare to the bound hash — if the engine
-        // has switched projects since we bound, this frame may be from the WRONG
-        // project. Best-effort: a failed health read never blocks the (already
-        // captured) image.
+        // Client-side identity drift check (item 4). Current engines validate the
+        // identity query on snapshot reads, but older builds may ignore it. Re-read
+        // health and compare to the bound hash so a frame from a switched project is
+        // still marked as suspect. Best-effort: a failed health read never blocks the
+        // already captured image.
         let projectMismatch;
-        if (this.boundProjectIdHash) {
+        const boundProjectIdHash = this.targetIdentity.projectIdHash;
+        if (boundProjectIdHash) {
             try {
                 const health = await checkEngineHealth(this.port);
-                if (health?.projectIdHash && health.projectIdHash !== this.boundProjectIdHash) {
+                if (health?.projectIdHash && health.projectIdHash !== boundProjectIdHash) {
                     projectMismatch = true;
                 }
             }

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/cloud/engine-bridge.js

@@ -50,7 +50,15 @@ async function connectForProject(projectRoot) {
         // rescan; the executor rejects mismatches too, but skip the round trip.
         if (health.projectIdHash && health.projectIdHash !== projectIdHash)
             return null;
-        return { client: new EngineApiClient(port, token), projectIdHash, scene: health.scene };
+        return {
+            client: new EngineApiClient(port, token, {
+                instanceId: health.instanceId,
+                projectId: health.projectId,
+                projectIdHash,
+            }),
+            projectIdHash,
+            scene: health.scene,
+        };
     }
     catch {
         return null;

package/dist/lib/debug-report.d.ts

@@ -0,0 +1,50 @@
+import { type DoctorResult } from "../commands/doctor.js";
+export interface DebugReportOptions {
+    issue?: string;
+    outputPath?: string;
+    includePlaySession?: boolean;
+    playWaitMs?: number;
+    maxConsoleLines?: number;
+    maxDebuggerEntries?: number;
+    includeDoctor?: boolean;
+    baseDir?: string;
+}
+export interface DebugReportArtifact {
+    path: string;
+    markdown: string;
+    report: DebugReport;
+}
+export interface DebugReport {
+    generatedAt: string;
+    issue: string | null;
+    environment: {
+        cliVersion: string;
+        nodeVersion: string;
+        platform: string;
+        release: string;
+        cwd: string;
+        hostname: string;
+    };
+    doctor: DoctorResult | null;
+    mcp: {
+        logPath: string;
+        recentLog: string[];
+    };
+    engine: {
+        connected: boolean;
+        error?: string;
+        health?: unknown;
+        project?: unknown;
+        scene?: unknown;
+        diagnostics?: unknown;
+        console?: unknown;
+        debuggerErrors?: unknown;
+        debuggerWarnings?: unknown;
+        playSession?: unknown;
+    };
+}
+export declare function defaultDebugReportFilename(date?: Date): string;
+export declare function redactDebugReport(report: DebugReport): DebugReport;
+export declare function renderDebugReportMarkdown(report: DebugReport): string;
+export declare function collectDebugReport(options?: DebugReportOptions): Promise<DebugReport>;
+export declare function createDebugReportArtifact(options?: DebugReportOptions): Promise<DebugReportArtifact>;