summer-engine 2.3.0 → 2.5.0

package/dist/commands/skills.js

@@ -1,13 +1,21 @@
 import { Command } from "commander";
-import { existsSync, mkdirSync, readFileSync, cpSync, writeFileSync, } from "fs";
+import { existsSync, mkdirSync, readFileSync, cpSync, rmSync, writeFileSync, readdirSync, copyFileSync, } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { homedir, platform } from "os";
+import { createRequire } from "node:module";
 import { AGENT_CLIENTS, SKILL_REGISTRY, } from "../lib/skills-registry.js";
 import { tildeify } from "../lib/format.js";
+import { writeSkillMarker } from "../lib/version-check.js";
+const requireFromHere = createRequire(import.meta.url);
+const { version: cliVersion } = requireFromHere("../../package.json");
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Resolve skills dir: from dist/commands/skills.js -> ../../skills
 const skillsDir = join(__dirname, "..", "..", "skills");
+// Resolve commands dir: same parent. Used by Claude Code installs to also copy
+// slash commands (e.g. /gameskill) to ~/.claude/commands/. Other agents don't
+// have an equivalent today, so the copy is gated to claude-code.
+const commandsDir = join(__dirname, "..", "..", "commands");
 const SKILL_SCOPES = ["user", "project"];
 function getBuiltinSkills() {
     const skills = [];
@@ -126,6 +134,10 @@ function agentLabel(agent) {
             return "Roo Code";
         case "gemini":
             return "Gemini CLI";
+        case "github-copilot":
+            return "GitHub Copilot CLI";
+        case "vscode-copilot":
+            return "GitHub Copilot in VS Code";
         case "opencode":
             return "OpenCode";
         case "summer":
@@ -180,6 +192,14 @@ function resolveInstallLocation(agent, scope) {
                 kind: "gemini-skill-dir",
                 path: join(homedir(), ".gemini", "extensions", "summer-engine", "skills"),
             };
+        case "github-copilot":
+        case "vscode-copilot":
+            return {
+                kind: "skill-dir",
+                path: scope === "user"
+                    ? join(homedir(), ".copilot", "skills")
+                    : join(process.cwd(), ".github", "skills"),
+            };
         case "opencode":
             return {
                 kind: "opencode-skill-dir",
@@ -244,13 +264,13 @@ function printAvailableSkillNames() {
         console.log(`  ${skill.name}`);
     }
 }
-function installSkill(skill, agent, location) {
+function installSkill(skill, agent, location, options) {
     if (!skill.clients.includes(agent)) {
         die(`${skill.name} does not support ${agentLabel(agent)}.`);
     }
     switch (location.kind) {
         case "skill-dir":
-            return copySkillDirectory(skill, location.path);
+            return copySkillDirectory(skill, location.path, options);
         case "cursor-rule-dir":
             return writeCursorRule(skill, location.path);
         case "windsurf-rule-file":
@@ -263,13 +283,18 @@ function installSkill(skill, agent, location) {
             return writeOpencodeSkill(skill, location.path);
     }
 }
-function copySkillDirectory(skill, targetDir) {
+function copySkillDirectory(skill, targetDir, options) {
     const src = getSkillPath(skill.name);
     if (!src)
         die(`Skill files missing: ${skill.name}`);
     mkdirSync(targetDir, { recursive: true });
     const dest = join(targetDir, skill.name);
-    cpSync(src, dest, { recursive: true });
+    if (options.force && existsSync(dest)) {
+        // Wipe stale skill content so re-installs overwrite cleanly even if files
+        // were renamed or removed upstream.
+        rmSync(dest, { recursive: true, force: true });
+    }
+    cpSync(src, dest, { recursive: true, force: true });
     return { action: "Installed", path: dest };
 }
 function writeCursorRule(skill, rulesDir) {
@@ -400,6 +425,7 @@ skillsCommand
     .option("--scope <scope>", "Install scope: user or project")
     .option("--as-claude-skill", "Legacy alias for --agent claude-code")
     .option("--as-cursor-skill", "Legacy alias for --agent cursor")
+    .option("--force", "Overwrite existing skill files (wipe stale skill dirs before copying)")
     .action((name, opts) => {
     const agent = resolveAgent(opts);
     const scope = resolveScope(agent, opts);
@@ -410,11 +436,69 @@ skillsCommand
         return;
     }
     for (const skill of skills) {
-        const result = installSkill(skill, agent, location);
+        const result = installSkill(skill, agent, location, {
+            force: Boolean(opts.force),
+        });
         console.log(`  ${result.action} ${skill.name} -> ${result.path}`);
     }
+    // Claude Code: also install slash commands (`tools/summer-cli/commands/*.md`)
+    // into `~/.claude/commands/`. Other agents don't have an equivalent today.
+    if (agent === "claude-code") {
+        const commandResults = installClaudeCommands(scope, Boolean(opts.force));
+        for (const r of commandResults) {
+            console.log(`  ${r.action} command ${r.name} -> ${r.path}`);
+        }
+    }
+    writeMarkerForLocation(location);
     printInstallSummary(skills.length, agent, scope, location);
 });
+/**
+ * Copy every `.md` file in `tools/summer-cli/commands/` to the user's
+ * `~/.claude/commands/` directory so the slash commands (e.g. `/gameskill`)
+ * are available on every machine that runs `summer skills install`.
+ *
+ * Project-scope installs go to `<cwd>/.claude/commands/`. Returns one result
+ * per command file copied. Silent no-op if no commands directory exists in
+ * the package (older summer-cli releases didn't ship one).
+ */
+function installClaudeCommands(scope, force) {
+    if (!existsSync(commandsDir))
+        return [];
+    const root = scope === "user" ? homedir() : process.cwd();
+    const targetDir = join(root, ".claude", "commands");
+    mkdirSync(targetDir, { recursive: true });
+    const results = [];
+    for (const entry of readdirSync(commandsDir)) {
+        if (!entry.endsWith(".md"))
+            continue;
+        const src = join(commandsDir, entry);
+        const dest = join(targetDir, entry);
+        if (existsSync(dest) && !force) {
+            results.push({ action: "Kept", name: entry, path: dest });
+            continue;
+        }
+        copyFileSync(src, dest);
+        results.push({ action: "Installed", name: entry, path: dest });
+    }
+    return results;
+}
+/**
+ * Drop a `.summer-version` marker into the install dir so doctor's
+ * `skills-version-stale` check can detect drift later. Windsurf writes a
+ * single rules file with no surrounding dir, so we skip it there.
+ */
+function writeMarkerForLocation(location) {
+    if (location.kind === "windsurf-rule-file")
+        return;
+    try {
+        mkdirSync(location.path, { recursive: true });
+        writeSkillMarker(location.path, cliVersion);
+    }
+    catch {
+        // Marker is purely informational. If the FS rejects it (e.g. permission
+        // surprises on locked-down corp machines) we don't want to fail the install.
+    }
+}
 skillsCommand
     .command("info <name>")
     .description("Show skill description and preview")

package/dist/commands/status.js

@@ -1,6 +1,8 @@
 import { Command } from "commander";
 import { getAuthToken, getUserInfo } from "../lib/auth.js";
 import { getApiToken, getApiPort, checkEngineHealth } from "../lib/engine.js";
+import { getProjectMemorySummary } from "../lib/project-memory.js";
+import { formatStatusMemoryLine } from "./memory.js";
 export const statusCommand = new Command("status")
     .description("Check Summer Engine status, connection, and auth state")
     .action(async () => {
@@ -36,6 +38,7 @@ export const statusCommand = new Command("status")
     }
     if (health.project_path) {
         console.log(`  Path: ${health.project_path}`);
+        console.log(`  ${formatStatusMemoryLine(getProjectMemorySummary(health.project_path))}`);
     }
     if (health.scene) {
         console.log(`  Scene: ${health.scene}`);

package/dist/lib/agent-config.d.ts

@@ -1,5 +1,5 @@
 export declare const SUMMER_MCP_SERVER_NAME = "summer-engine";
-export declare const supportedAgents: readonly ["codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "gemini", "opencode"];
+export declare const supportedAgents: readonly ["codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
 export type SupportedAgent = (typeof supportedAgents)[number];
 export type ConfigScope = "user" | "project";
 export interface StdioMcpServerConfig {
@@ -22,7 +22,7 @@ export interface AgentConfigResult {
     path: string;
     serverName: string;
     server: StdioMcpServerConfig;
-    format: "json" | "toml" | "json-opencode";
+    format: "json" | "toml" | "json-opencode" | "json-copilot" | "json-vscode";
     snippet: string;
     changed: boolean;
     wrote: boolean;

package/dist/lib/agent-config.js

@@ -12,6 +12,8 @@ export const supportedAgents = [
     "cline",
     "roo-code",
     "gemini",
+    "github-copilot",
+    "vscode-copilot",
     "opencode",
 ];
 const agentAliases = {
@@ -26,6 +28,15 @@ const agentAliases = {
     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",
 };
@@ -57,9 +68,13 @@ export async function configureAgentMcp(options) {
             ? await upsertCodexConfig(target.path, server, shouldWrite)
             : target.format === "json-opencode"
                 ? await upsertOpencodeConfig(target.path, server, shouldWrite)
-                : options.agent === "gemini"
-                    ? await upsertGeminiExtension(target.path, server, shouldWrite)
-                    : await upsertJsonMcpConfig(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,
@@ -101,6 +116,20 @@ export function renderConfigSnippet(agent, 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");
     }
@@ -128,7 +157,11 @@ function resolveConfigTarget(agent, scope, cwd, env) {
                 ? "toml"
                 : agent === "opencode"
                     ? "json-opencode"
-                    : "json",
+                    : agent === "github-copilot"
+                        ? "json-copilot"
+                        : agent === "vscode-copilot"
+                            ? "json-vscode"
+                            : "json",
             warnings,
         };
     }
@@ -189,6 +222,24 @@ function resolveConfigTarget(agent, scope, cwd, env) {
             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"
@@ -231,6 +282,18 @@ function opencodeUserConfigPath(env) {
     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;
@@ -244,6 +307,10 @@ function getConfigPathOverride(agent, env) {
         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;
@@ -321,6 +388,30 @@ async function upsertOpencodeConfig(path, server, write) {
     }
     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);
@@ -342,6 +433,29 @@ function opencodeServerEntry(server) {
     }
     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";
@@ -414,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);
 }
@@ -437,9 +560,13 @@ function createNextSteps(agent, scope, path) {
                         ? "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 === "opencode"
-                                ? "Restart OpenCode so it reloads opencode.json."
-                                : "Restart Windsurf and refresh MCP servers from Cascade settings.";
+                            : 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>>;