summer-engine 3.7.0 → 4.0.0

package/dist/core/ops/contract.js

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../package-root.js";
+/**
+ * The Summer operation catalog, the part this package needs (contract 1).
+ * Every Summer operation has one name (`area.action`), one effect, one
+ * approval rule and one answer shape; the MCP surface, the CLI and the
+ * store profiles are views of it. The machine contract is
+ * registry/schemas/operation.schema.json; old 3.x tool names map to
+ * operations in registry/operations/legacy-names.json.
+ *
+ * Engine and local operations run in this package. Cloud operations run on
+ * the hosted Summer server; this package reaches them through its v4
+ * surface (summer_search, summer_call) with the person's sign-in.
+ */
+export const CONTRACT_VERSION = 1;
+export const EFFECTS = ["read", "write", "spend", "publish", "player_facing", "destructive"];
+export const MIN_APPROVAL = {
+    read: "none",
+    write: "none",
+    spend: "none",
+    publish: "owner",
+    player_facing: "owner",
+    destructive: "confirm",
+};
+export function errorAnswer(code, message, options = {}) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message,
+            ...(options.next ? { next: options.next } : {}),
+            retry: options.retry ?? (code === "rate_limited" || code === "unavailable" || code === "in_progress" ? "after" : code === "engine_not_running" ? "safe" : code === "outcome_unknown" ? "same_key" : "no"),
+            ...(options.details ? { details: options.details } : {}),
+        },
+    };
+}
+// ── Names ────────────────────────────────────────────────────────────────────
+export const OP_NAME = /^(whoami|[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*)$/;
+/** `games.list` -> `summer_games_list`. */
+export function mcpNameOf(op) {
+    return `summer_${op.replace(/\./g, "_")}`;
+}
+/** `assets generate-image` -> `assets.generate_image`; `whoami` stays. */
+export function opFromCli(area, action) {
+    const clean = (part) => part.trim().toLowerCase().replace(/-/g, "_");
+    return action ? `${clean(area)}.${clean(action)}` : clean(area);
+}
+let legacyCache = null;
+/** registry/operations/legacy-names.json: every 3.x tool name (and `#action`) to its operation. */
+export function legacyNames() {
+    if (legacyCache)
+        return legacyCache;
+    try {
+        const parsed = JSON.parse(readFileSync(join(PACKAGE_ROOT, "registry", "operations", "legacy-names.json"), "utf8"));
+        legacyCache = parsed.names ?? {};
+    }
+    catch {
+        legacyCache = {};
+    }
+    return legacyCache;
+}
+/** A 3.x name as its operation name; an operation name unchanged. */
+export function resolveOpName(name) {
+    const trimmed = name.trim();
+    return legacyNames()[trimmed]?.op ?? trimmed;
+}
+/**
+ * Operations that run in this package: everything in `engine`, the library
+ * (`docs`, apart from the Studio workflows, which are cloud), opening a
+ * page or an editor surface, docking an App in the editor, and uploading a
+ * local export. Everything else runs on the hosted server.
+ */
+const LOCAL_OPS = new Set(["docs.search", "docs.read", "docs.feedback", "docs.plan", "docs.engine_api", "studio.open", "apps.dock", "apps.publish_folder", "store.upload_file"]);
+/**
+ * Local operations a 3.x tool runs although legacy-names.json maps that
+ * tool to a cloud operation: the local-only input is its own operation
+ * (apps.publish_folder reads a folder on disk; apps.publish takes files).
+ */
+export const LOCAL_RUNNERS = { "apps.publish_folder": "summer_app_publish" };
+export function isLocalOp(op) {
+    return op.startsWith("engine.") || LOCAL_OPS.has(op);
+}
+/**
+ * The local 3.x tools that run an operation here, first choice first: the
+ * tool the op was renamed from before the tools merged into it.
+ */
+export function localToolsFor(op) {
+    if (LOCAL_RUNNERS[op])
+        return [LOCAL_RUNNERS[op]];
+    const rank = (row) => (row.kind === "merge" ? 1 : 0);
+    return Object.entries(legacyNames())
+        .filter(([name, row]) => row.op === op && !name.includes("#"))
+        .sort(([, a], [, b]) => rank(a) - rank(b))
+        .map(([name]) => name);
+}
+// ── Job ids ──────────────────────────────────────────────────────────────────
+const JOB_KINDS = new Set(["gen", "op", "apr", "plan", "build", "upload", "engine"]);
+/** `<kind>:<backend id>`; an id without a known kind is a 3.x generation job. */
+export function parseJobId(id) {
+    const trimmed = id.trim();
+    if (!/^[A-Za-z0-9._~:-]{1,260}$/.test(trimmed))
+        return null;
+    const [head, ...rest] = trimmed.split(":");
+    return JOB_KINDS.has(head) && rest.length > 0 && rest.every(Boolean) ? { kind: head, parts: rest } : { kind: "gen", parts: [trimmed] };
+}
+// ── Telemetry ────────────────────────────────────────────────────────────────
+const AREA_TOOL = /^summer_([a-z]+)_([a-z][a-z0-9_]*)$/;
+/**
+ * The operation a tool call ran, for usage telemetry: summer_call's `op`,
+ * summer_search's own op, a 3.x name's op, or a v4 tool's op from its name
+ * (areas are single words, so the first underscore after `summer_` is the dot).
+ */
+export function opForToolCall(tool, args) {
+    if (tool === "summer_call") {
+        const call = args && typeof args === "object" ? args : {};
+        if (typeof call.op !== "string")
+            return null;
+        const name = call.op.trim();
+        // A mixed 3.x tool: the action in its input picks the operation; an engine operation's own tool name is the operation.
+        const input = call.input && typeof call.input === "object" ? call.input : {};
+        const action = typeof input.action === "string" ? input.action : typeof input.mode === "string" ? input.mode : null;
+        const resolved = (action ? legacyNames()[`${name}#${action}`]?.op : undefined) ??
+            (name.startsWith("summer_engine_") ? `engine.${name.slice("summer_engine_".length)}` : resolveOpName(name));
+        return OP_NAME.test(resolved) ? resolved : null;
+    }
+    if (tool === "summer_search")
+        return "ops.search";
+    if (tool === "summer_whoami")
+        return "whoami";
+    // A split 3.x tool: its action (or mode) argument picks the operation.
+    const record = args && typeof args === "object" ? args : {};
+    const action = typeof record.action === "string" ? record.action : typeof record.mode === "string" ? record.mode : null;
+    const split = action ? legacyNames()[`${tool}#${action}`]?.op : undefined;
+    if (split)
+        return split;
+    const legacy = legacyNames()[tool]?.op;
+    if (legacy)
+        return legacy;
+    const match = tool.match(AREA_TOOL);
+    return match ? `${match[1]}.${match[2]}` : null;
+}

package/dist/core/ops/engine-answer.d.ts

@@ -0,0 +1,25 @@
+import { type Answer, type NextStep } from "./contract.js";
+/**
+ * A 3.x engine tool's result as the one answer shape (SPEC §5.2, §5.5).
+ * Success: `{ok, status: "done", result}` with the tool's own payload as
+ * the result. Failure: one stable code with one next step; the engine's
+ * structured failure (failure_reason, receipts) travels whole in
+ * `details.tool`, so nothing the 3.x result said is lost.
+ */
+export declare const ENGINE_NOT_RUNNING_STEP: NextStep;
+export declare function engineNotRunning(): Answer;
+/** The text blocks of a tool result: the first is its payload, the rest are notes (a tip, a caption). */
+export declare function textsOf(result: unknown): string[];
+/**
+ * Map a failed engine tool call. `guide` is the docs.read id with the tool's
+ * full guide and schema (tool/<slug>), the one next step for a bad input.
+ */
+export declare function engineFailure(text: string, op: string, options: {
+    effect: "read" | "write";
+    guide?: string;
+}): Answer;
+/** A 3.x engine tool's whole result as the answer: its payload on success, the mapped failure otherwise. */
+export declare function answerOfEngineResult(result: unknown, op: string, options: {
+    effect: "read" | "write";
+    guide?: string;
+}): Answer;

package/dist/core/ops/engine-answer.js

@@ -0,0 +1,117 @@
+import { errorAnswer } from "./contract.js";
+/**
+ * A 3.x engine tool's result as the one answer shape (SPEC §5.2, §5.5).
+ * Success: `{ok, status: "done", result}` with the tool's own payload as
+ * the result. Failure: one stable code with one next step; the engine's
+ * structured failure (failure_reason, receipts) travels whole in
+ * `details.tool`, so nothing the 3.x result said is lost.
+ */
+export const ENGINE_NOT_RUNNING_STEP = {
+    say: "Open the project in Summer Engine, or run: npx -y summer-engine@latest run <project-path>",
+};
+export function engineNotRunning() {
+    return errorAnswer("engine_not_running", "Summer Engine is not running, or no project is open.", { next: ENGINE_NOT_RUNNING_STEP });
+}
+/** The text blocks of a tool result: the first is its payload, the rest are notes (a tip, a caption). */
+export function textsOf(result) {
+    const content = result && typeof result === "object" ? result.content : undefined;
+    return Array.isArray(content)
+        ? content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text)
+        : [];
+}
+function parsePayload(text) {
+    // A classified engine failure is JSON, sometimes followed by a plain "Hint:" paragraph.
+    const json = text.split(/\n\nHint: /)[0];
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/** The 4.0 codes a 3.x result may already carry (`{ok:false, code}`, summer PR #139). */
+const PASSED_CODES = new Set(["engine_not_running", "engine_lacks_op", "not_signed_in", "no_credits", "unavailable", "invalid_input", "not_found"]);
+const NOT_RUNNING = /Summer Engine is not running|Summer Engine( instance \S+)? is not responding on port|No running Summer editor matches/;
+/** Several editors run and none was picked for this session. */
+const SEVERAL_EDITORS = /Multiple Summer editors are running/;
+const SEVERAL_EDITORS_STEP = { say: "Several Summer editors are open: start the agent in the project folder, or run the MCP with --project <path>." };
+const NO_PROJECT = /No project\.godot found/;
+/** withEngine's transport recipe: the call failed between this package and the engine, mid-request. */
+const TRANSPORT = /Recovery: \(1\) check the engine is running/;
+function str(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+/** Where to read after a failure that may have changed something. */
+function readAfter(op) {
+    if (op === "engine.write_file" || op === "engine.replace_text")
+        return { op: "engine.read_file" };
+    if (op.startsWith("engine.runtime_") || op.startsWith("engine.game_"))
+        return { op: "engine.game_probe" };
+    return { op: "engine.get_scene_tree" };
+}
+/**
+ * Map a failed engine tool call. `guide` is the docs.read id with the tool's
+ * full guide and schema (tool/<slug>), the one next step for a bad input.
+ */
+export function engineFailure(text, op, options) {
+    const payload = parsePayload(text);
+    const body = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : null;
+    // `error` is sometimes a code ("import_failed") and `message` the sentence.
+    const sentence = /^[a-z0-9_]+$/.test(str(body?.error) ?? "") ? (str(body?.message) ?? str(body?.error)) : (str(body?.error) ?? str(body?.message));
+    const message = (sentence ?? text.split("\n")[0] ?? "").slice(0, 500) || "The engine tool failed.";
+    const details = { tool: body ?? text };
+    const describe = options.guide ? { op: "docs.read", input: { id: options.guide } } : { op: "ops.describe", input: { name: op } };
+    const code = str(body?.code);
+    const reason = str(body?.failure_reason);
+    if (code === "engine_not_running" || NOT_RUNNING.test(text))
+        return engineNotRunning();
+    if (SEVERAL_EDITORS.test(text))
+        return errorAnswer("conflict", message, { next: SEVERAL_EDITORS_STEP, details });
+    if (NO_PROJECT.test(text))
+        return errorAnswer("not_found", message, { next: { say: "Name the folder that holds project.godot, or open the project in Summer Engine." }, details });
+    if (code === "engine_lacks_op" || reason === "engine_lacks_op" || reason === "engine_lacks_events" || /engine_lacks_op/.test(text)) {
+        return errorAnswer("engine_lacks_op", message, { next: { say: "Update Summer Engine." }, details });
+    }
+    if (code && PASSED_CODES.has(code))
+        return errorAnswer(code, message, { details, ...(code === "invalid_input" ? { next: describe } : {}) });
+    if (!body && TRANSPORT.test(text)) {
+        return options.effect === "read"
+            ? errorAnswer("unavailable", message, { retry: "safe", next: { op: "engine.get_project_context" }, details })
+            : errorAnswer("outcome_unknown", `${message} It may have partly applied: read before you retry.`, { retry: "no", next: readAfter(op), details });
+    }
+    switch (reason) {
+        case "invalid_input":
+        case "bad_args":
+            return errorAnswer("invalid_input", message, { next: describe, details });
+        case "unsupported_operation":
+            return errorAnswer("unsupported", message, { details });
+        case "identity_mismatch":
+            return errorAnswer("conflict", message, { next: { op: "engine.get_project_context" }, details });
+        case "busy":
+            return errorAnswer("in_progress", message, { retry: "after", details: { ...details, retryAfterSeconds: 5 } });
+        case "game_not_running":
+            return errorAnswer("not_found", message, { next: { op: "engine.play" }, details });
+        case "unknown_snapshot":
+            return errorAnswer("not_found", message, { next: { op: "engine.world_snapshot" }, details });
+        case "not_found":
+            return errorAnswer("not_found", message, { details });
+    }
+    if (/identity_mismatch|registry identity changed/i.test(text))
+        return errorAnswer("conflict", message, { next: { op: "engine.get_project_context" }, details });
+    if (/^[a-z_]*not_found$/.test(str(body?.error) ?? ""))
+        return errorAnswer("not_found", message, { details });
+    if (/no scene (is currently )?open|no edited scene/i.test(text))
+        return errorAnswer("not_found", message, { next: { op: "engine.open_main_scene" }, details });
+    if (/not found|does not exist|no such/i.test(message))
+        return errorAnswer("not_found", message, { details });
+    return errorAnswer("invalid_input", message, { next: describe, details });
+}
+/** A 3.x engine tool's whole result as the answer: its payload on success, the mapped failure otherwise. */
+export function answerOfEngineResult(result, op, options) {
+    const [first = "", ...notes] = textsOf(result);
+    if (result && typeof result === "object" && result.isError === true) {
+        return engineFailure([first, ...notes].join("\n\n"), op, options);
+    }
+    const payload = parsePayload(first) ?? (first ? { text: first } : {});
+    return { ok: true, status: "done", result: payload, ...(notes.length ? { warnings: notes } : {}) };
+}

package/dist/core/ops/engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The `engine` area of the operation catalog: every operation that runs in
+ * Summer Engine on the person's computer. The 3.x tools stay the
+ * implementation and keep their MCP names (summer_set_prop is
+ * engine.set_prop); their input schemas stay in
+ * library/tools/<slug>/resource.yaml. This file adds what the catalog needs
+ * on top: a title, a short summary (what it does, what it returns, the next
+ * operation), the effect, and one real example.
+ *
+ * The long how-to text of each 3.x description lives in
+ * library/tools/<slug>/GUIDE.md (docs.read tool/<slug>), so a summary stays
+ * at or under 300 characters.
+ *
+ * Effects follow the 3.x annotations: a tool that only reads or renders
+ * evidence is `read` (render baselines and audit notes under res://.summer/
+ * do not change the game); everything else is `write`. Scene edits are
+ * undoable and checkpointed, so no engine operation is `destructive`, and
+ * none needs an approval.
+ *
+ * Two 3.x tools mixed a read with a change; their operations are split here
+ * (SPEC §3.1 rule 5) and run the same tool with its action fixed:
+ * summer_camera_bookmark (list, save, delete) and summer_ui_actions (list,
+ * invoke).
+ */
+export interface EngineOpDef {
+    title: string;
+    summary: string;
+    effect: "read" | "write";
+    example: {
+        input: Record<string, unknown>;
+        note: string;
+    };
+    /** Needs the Summer sign-in (imports from the Summer library). */
+    auth?: "account";
+}
+/** An operation cut out of a mixed 3.x tool: that tool, with its action fixed and only these fields. */
+export interface EngineSplitDef extends EngineOpDef {
+    tool: string;
+    fixed: Record<string, string>;
+    fields: readonly string[];
+    required?: readonly string[];
+}
+export declare const ENGINE_OPS: Readonly<Record<string, EngineOpDef>>;
+export declare const ENGINE_SPLIT_OPS: Readonly<Record<string, EngineSplitDef>>;
+/** The catalog fields of an engine operation, split or not; null for anything else. */
+export declare function engineOpDef(op: string): EngineOpDef | EngineSplitDef | null;
+export declare function isSplitOp(op: string): boolean;
+/** A split operation's input as its 3.x tool takes it: only its fields, plus its fixed action. */
+export declare function splitToolArgs(def: EngineSplitDef, input: Record<string, unknown>): Record<string, unknown>;
+/** A split operation's input JSON Schema, cut from its 3.x tool's schema. */
+export declare function splitInputSchema(def: EngineSplitDef, toolSchema: Record<string, unknown> | null): Record<string, unknown>;
+/** Every operation a summary names (`engine.snapshot_diff`, `docs.read`). */
+export declare function opsNamedIn(text: string): string[];
+/** A summary with each operation it names written as the tool that runs it in this view. */
+export declare function renderOpRefs(text: string, toolOf: (op: string) => string | undefined): string;