summer-engine 2.2.0 → 2.5.0

package/dist/lib/agent-config.js

@@ -2,13 +2,19 @@ import { existsSync } from "fs";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
-import { homedir } from "os";
+import { homedir, platform } from "os";
 export const SUMMER_MCP_SERVER_NAME = "summer-engine";
 export const supportedAgents = [
     "codex",
     "claude-code",
     "cursor",
     "windsurf",
+    "cline",
+    "roo-code",
+    "gemini",
+    "github-copilot",
+    "vscode-copilot",
+    "opencode",
 ];
 const agentAliases = {
     claude: "claude-code",
@@ -16,6 +22,23 @@ const agentAliases = {
     codex: "codex",
     cursor: "cursor",
     windsurf: "windsurf",
+    cline: "cline",
+    "roo-code": "roo-code",
+    roo: "roo-code",
+    roocode: "roo-code",
+    gemini: "gemini",
+    "gemini-cli": "gemini",
+    copilot: "github-copilot",
+    "copilot-cli": "github-copilot",
+    "github-copilot": "github-copilot",
+    "github-copilot-cli": "github-copilot",
+    vscode: "vscode-copilot",
+    "vs-code": "vscode-copilot",
+    "vscode-copilot": "vscode-copilot",
+    "vs-code-copilot": "vscode-copilot",
+    "github-copilot-vscode": "vscode-copilot",
+    opencode: "opencode",
+    "open-code": "opencode",
 };
 export function parseAgent(value) {
     if (!value)
@@ -43,7 +66,15 @@ export async function configureAgentMcp(options) {
         ? { changed: true }
         : target.format === "toml"
             ? await upsertCodexConfig(target.path, server, shouldWrite)
-            : await upsertJsonMcpConfig(target.path, server, shouldWrite);
+            : target.format === "json-opencode"
+                ? await upsertOpencodeConfig(target.path, server, shouldWrite)
+                : target.format === "json-copilot"
+                    ? await upsertCopilotConfig(target.path, server, shouldWrite)
+                    : target.format === "json-vscode"
+                        ? await upsertVsCodeMcpConfig(target.path, server, shouldWrite)
+                        : options.agent === "gemini"
+                            ? await upsertGeminiExtension(target.path, server, shouldWrite)
+                            : await upsertJsonMcpConfig(target.path, server, shouldWrite);
     return {
         agent: options.agent,
         scope: options.scope,
@@ -70,13 +101,38 @@ export function createSummerMcpServerConfig(localDev) {
     }
     return {
         command: "npx",
-        args: ["summer-engine", "mcp"],
+        args: ["-y", "summer-engine@latest", "mcp"],
     };
 }
 export function renderConfigSnippet(agent, server) {
     if (agent === "codex") {
         return renderCodexServerTable(server);
     }
+    if (agent === "opencode") {
+        return (JSON.stringify({
+            $schema: "https://opencode.ai/config.json",
+            mcp: {
+                [SUMMER_MCP_SERVER_NAME]: opencodeServerEntry(server),
+            },
+        }, null, 2) + "\n");
+    }
+    if (agent === "github-copilot") {
+        return (JSON.stringify({
+            mcpServers: {
+                [SUMMER_MCP_SERVER_NAME]: copilotServerEntry(server),
+            },
+        }, null, 2) + "\n");
+    }
+    if (agent === "vscode-copilot") {
+        return (JSON.stringify({
+            servers: {
+                [SUMMER_MCP_SERVER_NAME]: vsCodeServerEntry(server),
+            },
+        }, null, 2) + "\n");
+    }
+    if (agent === "gemini") {
+        return (JSON.stringify(geminiExtensionManifest(server), null, 2) + "\n");
+    }
     return (JSON.stringify({
         mcpServers: {
             [SUMMER_MCP_SERVER_NAME]: server,
@@ -91,9 +147,21 @@ function resolveConfigTarget(agent, scope, cwd, env) {
     const override = getConfigPathOverride(agent, env);
     const warnings = [];
     if (override) {
+        if (scope === "project" &&
+            (agent === "cline" || agent === "roo-code" || agent === "gemini")) {
+            warnings.push(`${agent} MCP config has no project scope today; treating as user scope.`);
+        }
         return {
             path: resolve(override),
-            format: agent === "codex" ? "toml" : "json",
+            format: agent === "codex"
+                ? "toml"
+                : agent === "opencode"
+                    ? "json-opencode"
+                    : agent === "github-copilot"
+                        ? "json-copilot"
+                        : agent === "vscode-copilot"
+                            ? "json-vscode"
+                            : "json",
             warnings,
         };
     }
@@ -124,6 +192,63 @@ function resolveConfigTarget(agent, scope, cwd, env) {
             warnings,
         };
     }
+    if (agent === "cline") {
+        if (scope === "project") {
+            warnings.push("Cline MCP config has no project scope today; writing to user-scope global VS Code storage instead.");
+        }
+        return {
+            path: vsCodeGlobalStoragePath(env, "saoudrizwan.claude-dev"),
+            format: "json",
+            warnings,
+        };
+    }
+    if (agent === "roo-code") {
+        if (scope === "project") {
+            warnings.push("Roo Code MCP config has no project scope today; writing to user-scope global VS Code storage instead.");
+        }
+        return {
+            path: vsCodeGlobalStoragePath(env, "rooveterinaryinc.roo-cline"),
+            format: "json",
+            warnings,
+        };
+    }
+    if (agent === "gemini") {
+        if (scope === "project") {
+            warnings.push("Gemini extensions are user-scoped today; writing to ~/.gemini/extensions/summer-engine/ instead of project.");
+        }
+        return {
+            path: join(homedir(), ".gemini", "extensions", "summer-engine", "gemini-extension.json"),
+            format: "json",
+            warnings,
+        };
+    }
+    if (agent === "github-copilot") {
+        return {
+            path: scope === "user"
+                ? join(homedir(), ".copilot", "mcp-config.json")
+                : join(cwd, ".mcp.json"),
+            format: "json-copilot",
+            warnings,
+        };
+    }
+    if (agent === "vscode-copilot") {
+        return {
+            path: scope === "user"
+                ? vsCodeUserMcpPath(env)
+                : join(cwd, ".vscode", "mcp.json"),
+            format: "json-vscode",
+            warnings,
+        };
+    }
+    if (agent === "opencode") {
+        return {
+            path: scope === "user"
+                ? opencodeUserConfigPath(env)
+                : join(cwd, "opencode.json"),
+            format: "json-opencode",
+            warnings,
+        };
+    }
     if (scope === "project") {
         warnings.push("Windsurf documents MCP configuration as user-scoped; project scope writes .windsurf/mcp_config.json for teams that load workspace config.");
     }
@@ -135,6 +260,40 @@ function resolveConfigTarget(agent, scope, cwd, env) {
         warnings,
     };
 }
+function vsCodeGlobalStoragePath(env, extensionId) {
+    const os = platform();
+    if (os === "win32") {
+        const appData = env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+        return join(appData, "Code", "User", "globalStorage", extensionId, "settings", "cline_mcp_settings.json");
+    }
+    if (os === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Code", "User", "globalStorage", extensionId, "settings", "cline_mcp_settings.json");
+    }
+    // Linux and other Unix
+    const xdg = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(xdg, "Code", "User", "globalStorage", extensionId, "settings", "cline_mcp_settings.json");
+}
+function opencodeUserConfigPath(env) {
+    const os = platform();
+    if (os === "win32") {
+        const appData = env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+        return join(appData, "opencode", "opencode.json");
+    }
+    const xdg = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(xdg, "opencode", "opencode.json");
+}
+function vsCodeUserMcpPath(env) {
+    const os = platform();
+    if (os === "win32") {
+        const appData = env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+        return join(appData, "Code", "User", "mcp.json");
+    }
+    if (os === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Code", "User", "mcp.json");
+    }
+    const xdg = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(xdg, "Code", "User", "mcp.json");
+}
 function getConfigPathOverride(agent, env) {
     if (agent === "codex")
         return env.SUMMER_CODEX_CONFIG_FILE;
@@ -142,6 +301,18 @@ function getConfigPathOverride(agent, env) {
         return env.SUMMER_CLAUDE_CONFIG_FILE;
     if (agent === "cursor")
         return env.SUMMER_CURSOR_MCP_CONFIG_FILE;
+    if (agent === "cline")
+        return env.SUMMER_CLINE_CONFIG_FILE;
+    if (agent === "roo-code")
+        return env.SUMMER_ROO_CODE_CONFIG_FILE;
+    if (agent === "gemini")
+        return env.SUMMER_GEMINI_CONFIG_FILE;
+    if (agent === "github-copilot")
+        return env.SUMMER_GITHUB_COPILOT_CONFIG_FILE;
+    if (agent === "vscode-copilot")
+        return env.SUMMER_VSCODE_COPILOT_CONFIG_FILE;
+    if (agent === "opencode")
+        return env.SUMMER_OPENCODE_CONFIG_FILE;
     return env.SUMMER_WINDSURF_MCP_CONFIG_FILE;
 }
 async function upsertJsonMcpConfig(path, server, write) {
@@ -198,6 +369,107 @@ async function upsertCodexConfig(path, server, write) {
     }
     return { changed };
 }
+async function upsertOpencodeConfig(path, server, write) {
+    const current = await readJsonConfig(path);
+    const next = copyJsonObject(current);
+    if (typeof next.$schema !== "string") {
+        next.$schema = "https://opencode.ai/config.json";
+    }
+    const existingMcp = isJsonObject(next.mcp) ? next.mcp : {};
+    next.mcp = {
+        ...existingMcp,
+        [SUMMER_MCP_SERVER_NAME]: opencodeServerEntry(server),
+    };
+    const currentRendered = renderJsonFile(current);
+    const nextRendered = renderJsonFile(next);
+    const changed = currentRendered !== nextRendered;
+    if (write && changed) {
+        await writeTextFile(path, nextRendered);
+    }
+    return { changed };
+}
+async function upsertCopilotConfig(path, server, write) {
+    const current = await readJsonConfig(path);
+    const next = copyJsonObject(current);
+    next.mcpServers = mergeNamedObject(next.mcpServers, SUMMER_MCP_SERVER_NAME, copilotServerEntry(server), "mcpServers");
+    const currentRendered = renderJsonFile(current);
+    const nextRendered = renderJsonFile(next);
+    const changed = currentRendered !== nextRendered;
+    if (write && changed) {
+        await writeTextFile(path, nextRendered);
+    }
+    return { changed };
+}
+async function upsertVsCodeMcpConfig(path, server, write) {
+    const current = await readJsonConfig(path);
+    const next = copyJsonObject(current);
+    next.servers = mergeNamedObject(next.servers, SUMMER_MCP_SERVER_NAME, vsCodeServerEntry(server), "servers");
+    const currentRendered = renderJsonFile(current);
+    const nextRendered = renderJsonFile(next);
+    const changed = currentRendered !== nextRendered;
+    if (write && changed) {
+        await writeTextFile(path, nextRendered);
+    }
+    return { changed };
+}
+async function upsertGeminiExtension(path, server, write) {
+    const current = await readJsonConfig(path);
+    const next = geminiExtensionManifest(server, current);
+    const currentRendered = renderJsonFile(current);
+    const nextRendered = renderJsonFile(next);
+    const changed = currentRendered !== nextRendered;
+    if (write && changed) {
+        await writeTextFile(path, nextRendered);
+    }
+    return { changed };
+}
+function opencodeServerEntry(server) {
+    const entry = {
+        type: "local",
+        command: [server.command, ...server.args],
+    };
+    if (server.env && Object.keys(server.env).length > 0) {
+        entry.environment = { ...server.env };
+    }
+    return entry;
+}
+function copilotServerEntry(server) {
+    const entry = {
+        type: "local",
+        command: server.command,
+        args: server.args,
+        tools: ["*"],
+    };
+    if (server.env && Object.keys(server.env).length > 0) {
+        entry.env = { ...server.env };
+    }
+    return entry;
+}
+function vsCodeServerEntry(server) {
+    const entry = {
+        type: "stdio",
+        command: server.command,
+        args: server.args,
+    };
+    if (server.env && Object.keys(server.env).length > 0) {
+        entry.env = { ...server.env };
+    }
+    return entry;
+}
+function geminiExtensionManifest(server, base = {}) {
+    const manifest = { ...base };
+    manifest.name = "summer";
+    manifest.description =
+        "Superpowers for AI game dev. MCP bridge to the local Summer Engine plus a context primer that teaches Gemini the Summer skills.";
+    manifest.contextFileName = "GEMINI.md";
+    manifest.mcpServers = {
+        [SUMMER_MCP_SERVER_NAME]: {
+            command: server.command,
+            args: server.args,
+        },
+    };
+    return manifest;
+}
 async function readTextFileIfExists(path) {
     if (!existsSync(path))
         return "";
@@ -256,6 +528,15 @@ function renderJsonFile(value) {
 function copyJsonObject(value) {
     return JSON.parse(JSON.stringify(value));
 }
+function mergeNamedObject(value, key, entry, label) {
+    if (value !== undefined && !isJsonObject(value)) {
+        throw new Error(`Existing ${label} value must be a JSON object.`);
+    }
+    return {
+        ...(isJsonObject(value) ? value : {}),
+        [key]: entry,
+    };
+}
 function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -273,7 +554,19 @@ function createNextSteps(agent, scope, path) {
             ? "Restart Codex or run /mcp in a new session."
             : agent === "cursor"
                 ? "Restart Cursor and enable the summer-engine MCP server if prompted."
-                : "Restart Windsurf and refresh MCP servers from Cascade settings.";
+                : agent === "cline"
+                    ? "Restart VS Code so Cline reloads its MCP config."
+                    : agent === "roo-code"
+                        ? "Restart VS Code so Roo Code reloads its MCP config."
+                        : agent === "gemini"
+                            ? "Run `gemini extensions enable summer-engine` (if not already enabled), then restart Gemini CLI."
+                            : agent === "github-copilot"
+                                ? "Restart Copilot CLI, or run /mcp reload and /skills reload in the active session."
+                                : agent === "vscode-copilot"
+                                    ? "Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode."
+                                    : agent === "opencode"
+                                        ? "Restart OpenCode so it reloads opencode.json."
+                                        : "Restart Windsurf and refresh MCP servers from Cascade settings.";
     const projectTrust = scope === "project" && agent === "codex"
         ? "Codex only loads project .codex/config.toml from trusted projects."
         : null;

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

@@ -19,6 +19,19 @@ export declare class EngineApiClient {
     constructor(port: number, token: string);
     static connect(): Promise<EngineApiClient>;
     private request;
+    /** Raw fetch with auth + timeout — returns the Response so callers can inspect
+     *  the status (202 queued vs 200 legacy). */
+    private _fetchRaw;
+    /** One long-poll of GET /api/ops/result (up to waitMs). */
+    private _pollResult;
+    /**
+     * Block E: send a mutating request, then resolve EITHER the legacy synchronous
+     * 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.
+     */
+    private _requestQueued;
     health(): Promise<unknown>;
     executeOps(ops: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
     getSceneState(): Promise<unknown>;

package/dist/lib/api-client.js

@@ -2,6 +2,7 @@ import { mkdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
 import { getApiToken, getApiPort, checkEngineHealth } from "./engine.js";
+import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -96,11 +97,60 @@ export class EngineApiClient {
         }
         return res.json();
     }
+    /** 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}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                "Content-Type": "application/json",
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    /** One long-poll of GET /api/ops/result (up to waitMs). */
+    async _pollResult(requestId, waitMs) {
+        const res = await this._fetchRaw("GET", `/api/ops/result?requestId=${encodeURIComponent(requestId)}&wait=${waitMs}`, undefined, waitMs + 5000);
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Engine API error ${res.status}: ${text.slice(0, 200)}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Block E: send a mutating request, then resolve EITHER the legacy synchronous
+     * 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.
+     */
+    async _requestQueued(method, path, body, timeoutMs) {
+        const res = await this._fetchRaw(method, path, body, timeoutMs);
+        // 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 respBody = await res.json().catch(() => ({}));
+        const classified = classifyOpsResponse(res.status, respBody);
+        if (classified.mode === "legacy") {
+            return respBody;
+        }
+        return pollOpToTerminal((waitMs) => this._pollResult(classified.requestId, waitMs), {
+            totalTimeoutMs: timeoutMs,
+        });
+    }
     async health() {
         return this.request("GET", "/api/health");
     }
     async executeOps(ops, options) {
-        return this.request("POST", "/api/ops", { ops, options });
+        // Ops may include long-running work (ImportFromUrlBatch, GitCommit); the
+        // engine keeps it "running" and we poll. 120s budget. Resolves legacy-200 or
+        // async-202 (Block E).
+        return this._requestQueued("POST", "/api/ops", { ops, options }, 120_000);
     }
     async getSceneState() {
         return this.request("GET", "/api/state/scene");
@@ -121,10 +171,11 @@ export class EngineApiClient {
         return this.request("GET", `/api/state/script-errors?path=${encodeURIComponent(path)}`);
     }
     async play(scene) {
-        return this.request("POST", "/api/play", scene ? { scene } : {});
+        // Cold-load on large projects can take 25-40s. 60s budget.
+        return this._requestQueued("POST", "/api/play", scene ? { scene } : {}, 60_000);
     }
     async stop() {
-        return this.request("POST", "/api/stop");
+        return this._requestQueued("POST", "/api/stop", undefined, 15_000);
     }
     async readFile(path, maxBytes) {
         const params = new URLSearchParams({ path });
@@ -153,31 +204,17 @@ export class EngineApiClient {
         return localPath;
     }
     async snapshot(kind) {
-        const url = `http://127.0.0.1:${this.port}/api/snapshot/${kind}`;
-        const res = await fetch(url, {
-            headers: { Authorization: `Bearer ${this.token}` },
-            signal: AbortSignal.timeout(30000),
-        });
-        if (!res.ok) {
-            const text = await res.text().catch(() => "");
-            throw new Error(`Snapshot failed ${res.status}: ${text.slice(0, 200)}`);
+        // Block E: /api/snapshot/* is queued (GET -> 202 -> poll /api/ops/result).
+        // The terminal result is the apply dict; the image rides as base64 inside it
+        // (no raw-binary channel). Legacy/dormant engines answer 200 synchronously
+        // with the same payload shape — _requestQueued resolves both.
+        let response;
+        try {
+            response = await this._requestQueued("GET", `/api/snapshot/${kind}`, undefined, 60_000);
         }
-        const contentType = res.headers.get("content-type") ?? "";
-        if (!contentType.toLowerCase().includes("application/json")) {
-            const { format, mime, ext } = snapshotFormat({ mime: contentType });
-            const buffer = Buffer.from(await res.arrayBuffer());
-            const localPath = await this.writeSnapshotFile(kind, buffer, ext);
-            return {
-                ok: true,
-                localPath,
-                path: localPath,
-                format,
-                mime,
-                context: kind === "viewport" ? "scene" : "game",
-                bytes: buffer.byteLength,
-            };
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
         }
-        const response = await res.json();
         const payload = findSnapshotPayload(response);
         if (!payload) {
             return {

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

@@ -0,0 +1,60 @@
+/**
+ * 0.5.34 Block E — async tool-lifecycle consumer for the CLI/MCP.
+ *
+ * Ported from the web orchestrator (publicsummerengine
+ * src/lib/bridge/async-op-lifecycle.ts) so the CLI speaks the SAME contract as
+ * the engine's responsive tool server (Block E):
+ *   - NEW path: `202 {requestId, status:"queued"}` -> long-poll
+ *     GET /api/ops/result?requestId=&wait=ms until terminal (done|failed|canceled).
+ *   - LEGACY path (dormant/older engine): a synchronous `200` with the full apply
+ *     result, exactly as before.
+ *
+ * It inspects the RESPONSE (status/body), not a flag, so it stays compatible with
+ * both an async and a synchronous engine. Pure + dependency-injected (now/sleep/
+ * pollOnce) so it is unit-tested without HTTP.
+ */
+export declare function isTerminalStatus(status: string | undefined): boolean;
+/** The envelope returned by GET /api/ops/result. */
+export interface OpResultEnvelope {
+    requestId?: string;
+    status: string;
+    terminalState?: string;
+    errorClass?: string;
+    result?: Record<string, unknown>;
+    progress?: unknown;
+    appliedSeq?: number;
+}
+export type OpsResponseClassification = {
+    mode: "queued";
+    requestId: string;
+} | {
+    mode: "legacy";
+    legacyResult: unknown;
+};
+/**
+ * Decide whether a POST /api/ops (or GET /api/snapshot/*) response is the new
+ * async ack (`202`) or the legacy synchronous result (`200`). Inspecting the HTTP
+ * status (not a flag) is what keeps this compatible with both engines.
+ */
+export declare function classifyOpsResponse(httpStatus: number, body: unknown): OpsResponseClassification;
+export interface PollOpts {
+    /** Hard wall-clock cap on the whole poll loop (ms). The per-tool budget. */
+    totalTimeoutMs: number;
+    /** 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
+     *  connection up to this long, which paces the loop in production. */
+    pollWaitMs?: number;
+    /** Pacing sleep between non-terminal polls (ms). Negligible in production
+     *  (the long-poll dominates); keeps the loop from hot-spinning. Default 250. */
+    pacingMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * 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.
+ */
+export declare function pollOpToTerminal(pollOnce: (waitMs: number) => Promise<OpResultEnvelope>, opts: PollOpts): Promise<Record<string, unknown>>;

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

@@ -0,0 +1,83 @@
+/**
+ * 0.5.34 Block E — async tool-lifecycle consumer for the CLI/MCP.
+ *
+ * Ported from the web orchestrator (publicsummerengine
+ * src/lib/bridge/async-op-lifecycle.ts) so the CLI speaks the SAME contract as
+ * the engine's responsive tool server (Block E):
+ *   - NEW path: `202 {requestId, status:"queued"}` -> long-poll
+ *     GET /api/ops/result?requestId=&wait=ms until terminal (done|failed|canceled).
+ *   - LEGACY path (dormant/older engine): a synchronous `200` with the full apply
+ *     result, exactly as before.
+ *
+ * It inspects the RESPONSE (status/body), not a flag, so it stays compatible with
+ * both an async and a synchronous engine. Pure + dependency-injected (now/sleep/
+ * pollOnce) so it is unit-tested without HTTP.
+ */
+const TERMINAL_STATUSES = new Set(["done", "failed", "canceled"]);
+export function isTerminalStatus(status) {
+    return status != null && TERMINAL_STATUSES.has(status);
+}
+/**
+ * Decide whether a POST /api/ops (or GET /api/snapshot/*) response is the new
+ * async ack (`202`) or the legacy synchronous result (`200`). Inspecting the HTTP
+ * status (not a flag) is what keeps this compatible with both engines.
+ */
+export function classifyOpsResponse(httpStatus, body) {
+    const b = (body ?? {});
+    const looksQueued = b.accepted === true && b.status === "queued" && typeof b.requestId === "string";
+    if (httpStatus === 202 || looksQueued) {
+        return { mode: "queued", requestId: String(b.requestId ?? "") };
+    }
+    return { mode: "legacy", legacyResult: body };
+}
+const TIMED_OUT_RESULT = {
+    status: "error",
+    error: "Tool timeout - Summer Engine may be unresponsive",
+    terminalState: "timed_out",
+    errorClass: "transient",
+};
+/**
+ * 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.
+ */
+export async function pollOpToTerminal(pollOnce, opts) {
+    const now = opts.now ?? (() => Date.now());
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const pollWaitMs = opts.pollWaitMs ?? 5000;
+    const pacingMs = opts.pacingMs ?? 250;
+    const noProgressMs = opts.noProgressTimeoutMs ?? opts.totalTimeoutMs;
+    const start = now();
+    let lastAdvanceAt = start;
+    let lastStatus;
+    let lastSeq = -1;
+    let lastProgress = "";
+    for (;;) {
+        const env = await pollOnce(pollWaitMs);
+        if (isTerminalStatus(env.status)) {
+            const out = { ...(env.result ?? {}) };
+            if (env.terminalState)
+                out.terminalState = env.terminalState;
+            if (env.errorClass)
+                out.errorClass = env.errorClass;
+            if (env.appliedSeq != null)
+                out.appliedSeq = env.appliedSeq;
+            return out;
+        }
+        const progressJson = env.progress != null ? JSON.stringify(env.progress) : "";
+        const seq = env.appliedSeq ?? -1;
+        const advanced = env.status !== lastStatus || seq !== lastSeq || progressJson !== lastProgress;
+        const t = now();
+        if (advanced) {
+            lastAdvanceAt = t;
+            lastStatus = env.status;
+            lastSeq = seq;
+            lastProgress = progressJson;
+        }
+        if (t - start >= opts.totalTimeoutMs || t - lastAdvanceAt >= noProgressMs) {
+            return { ...TIMED_OUT_RESULT };
+        }
+        await sleep(pacingMs);
+    }
+}