summer-engine 2.8.2 → 3.1.0

package/dist/core/capabilities/engine-receipt.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Engine receipt failure semantics — ONE copy, imported by both faces
+ * (src/mcp/tools/with-engine.ts and src/core/capabilities/tool-dispatch.ts).
+ */
+export type OpResult = {
+    ok?: boolean;
+    status?: string;
+    error?: string;
+    terminalState?: string;
+    errorClass?: string;
+    failureReason?: string;
+    failure_reason?: string;
+    results?: Array<{
+        ok?: boolean;
+        op?: string;
+        error?: string;
+        failureReason?: string;
+        failure_reason?: string;
+    }>;
+};
+export declare function getFailureReason(value: {
+    failureReason?: string;
+    failure_reason?: string;
+}): string | undefined;
+/**
+ * Decide whether an engine result envelope represents a FAILURE, and if so
+ * return a model-visible message. Returns null only for genuine success.
+ *
+ * Guards the two web bug classes (publicsummerengine cf17134f + contract.ts
+ * `isFailureSignal`):
+ *   - a failure `terminalState` (anything other than applied/no_op) is a failure
+ *     even when results[] is absent — the cf17134f "no-results envelope looked
+ *     applied" masking. The poll loop surfaces timed_out/etc. here.
+ *   - an explicit ok:false / status:"error" / failed op inside results[].
+ *
+ * Exported for unit tests.
+ */
+export declare function extractOpError(result: unknown): string | null;
+/**
+ * An older engine answers an unknown op with a per-op "unknown op: <Kind>"
+ * (ops_executor.cpp fallthrough). Amend the envelope's error so the model gets
+ * the upgrade path instead of retrying, and stamp `failure_reason:
+ * "engine_lacks_op"` (+ `op`) so the result is detectable the same way as the
+ * capability pre-flight's MissingOpResult: programmatic callers read the
+ * field (the CLI prints the whole receipt), and extractOpError renders the
+ * classified failure as JSON. Engines WITH a capability advert never reach
+ * this — the pre-flight in missingEngineOpResult refuses before sending.
+ * A chunked mutation (executeSceneMutation) rewrites the envelope error into
+ * the "N earlier op(s) already applied" receipt, so the raw per-op text lives
+ * only inside results[] — both are read before deciding this is an old engine.
+ * Returns the input untouched when there is nothing to rewrite.
+ */
+export declare function withOldEngineHint(result: unknown, opName: string, fallback: string): unknown;

package/dist/core/capabilities/engine-receipt.js

@@ -0,0 +1,134 @@
+/**
+ * Engine receipt failure semantics — ONE copy, imported by both faces
+ * (src/mcp/tools/with-engine.ts and src/core/capabilities/tool-dispatch.ts).
+ */
+export function getFailureReason(value) {
+    return typeof value.failureReason === "string"
+        ? value.failureReason
+        : typeof value.failure_reason === "string"
+            ? value.failure_reason
+            : undefined;
+}
+// 0.5.34 Block E contract (publicsummerengine src/lib/tools/contract.ts §0.1).
+// The async lifecycle (async-op-lifecycle.ts pollOpToTerminal) merges
+// terminalState/errorClass onto the apply dict it returns. ONLY these two are
+// "applied something / applied nothing-on-purpose" — every other terminal state
+// means the op did NOT land and must be surfaced as a failure, not masked.
+const SUCCESS_TERMINAL_STATES = new Set(["applied", "no_op"]);
+// Human-readable fallback when the engine reports a failure terminalState but no
+// `error` string (queue-full / lease-reject / identity-mismatch / no-progress
+// timeout frequently arrive with terminalState set and results[] absent).
+const TERMINAL_STATE_MESSAGES = {
+    timed_out: "Engine operation timed out. Its final state is unknown; inspect the target before retrying (summer_get_scene_tree / summer_world_snapshot / summer_read_file). To recover: break the work into smaller pieces — several short scripts or batches instead of one long one — raise the tool's max_seconds if it has one, and confirm the engine is still responsive (summer_get_project_context, or `summer doctor` from a shell).",
+    still_queued: "Summer Engine accepted the operation, but it was still queued when the client stopped waiting. It may still run; do NOT retry blindly — inspect the target first (summer_get_scene_tree / summer_world_snapshot), and if the queue stays stuck check whether the editor is busy (modal dialog, long import) or run `summer doctor`.",
+    still_running: "Summer Engine accepted and started the operation, but no final receipt arrived. It may still be running or may already have applied; inspect the target before retrying (summer_get_scene_tree / summer_world_snapshot / summer_read_file). For long jobs, split the work into smaller scripts/batches so each finishes inside its budget.",
+    uncertain: "Summer Engine did not provide a final operation receipt. The current state is uncertain; inspect the target before retrying (summer_get_scene_tree / summer_world_snapshot / summer_read_file), and verify the engine is healthy with summer_get_project_context.",
+    not_connected: "Summer Engine is not connected (terminalState: not_connected). Nothing was applied.",
+    identity_mismatch: "Operation rejected — wrong project/instance (terminalState: identity_mismatch). Nothing was mutated.",
+    content_mismatch: "Operation rejected — content changed since last read (terminalState: content_mismatch). Nothing was applied.",
+    denied: "Operation denied (terminalState: denied). Nothing was applied.",
+    canceled: "Operation canceled (terminalState: canceled). Nothing was applied.",
+};
+/**
+ * Decide whether an engine result envelope represents a FAILURE, and if so
+ * return a model-visible message. Returns null only for genuine success.
+ *
+ * Guards the two web bug classes (publicsummerengine cf17134f + contract.ts
+ * `isFailureSignal`):
+ *   - a failure `terminalState` (anything other than applied/no_op) is a failure
+ *     even when results[] is absent — the cf17134f "no-results envelope looked
+ *     applied" masking. The poll loop surfaces timed_out/etc. here.
+ *   - an explicit ok:false / status:"error" / failed op inside results[].
+ *
+ * Exported for unit tests.
+ */
+export function extractOpError(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const op = result;
+    const firstFailed = op.results?.find((r) => r.ok === false);
+    // The engine stamps failure classifiers on the envelope OR per-op inside
+    // results[] (the batch gate does the latter) — read both.
+    const failureReason = getFailureReason(op) ?? (firstFailed ? getFailureReason(firstFailed) : undefined);
+    // Classified failures are rendered as JSON so callers can reliably read
+    // failure_reason instead of scraping a sentence. A plain-text "Hint:" line may
+    // follow the JSON in the final tool text. Unclassified failures stay plain.
+    const classify = (message) => {
+        if (!failureReason)
+            return message;
+        return JSON.stringify({
+            error: message,
+            failure_reason: failureReason,
+            ...(typeof firstFailed?.error === "string" && firstFailed.error.length > 0 && firstFailed.error !== message
+                ? { op_error: firstFailed.error }
+                : {}),
+            ...(typeof firstFailed?.op === "string" ? { op: firstFailed.op } : {}),
+            ...(typeof op.terminalState === "string" ? { terminalState: op.terminalState } : {}),
+            ...(typeof op.errorClass === "string" ? { errorClass: op.errorClass } : {}),
+        }, null, 2);
+    };
+    // Failure terminalState takes precedence — it is set by the async lifecycle
+    // exactly when the op did not land (timeout, backpressure, lease/identity
+    // rejection, cancellation), sometimes with NO results[] to inspect. Prefer the
+    // precise engine rejection (envelope error, then the failed op's error) over
+    // the generic terminal-state sentence.
+    const ts = op.terminalState;
+    if (typeof ts === "string" && ts.length > 0 && !SUCCESS_TERMINAL_STATES.has(ts)) {
+        const message = (typeof op.error === "string" && op.error.length > 0 && op.error) ||
+            (typeof firstFailed?.error === "string" && firstFailed.error.length > 0 && firstFailed.error) ||
+            TERMINAL_STATE_MESSAGES[ts] ||
+            `Engine operation failed (terminalState: ${ts}).`;
+        return classify(message);
+    }
+    // An explicit ok:false / status:"error" / failed op inside results[] is a
+    // failure even when the engine omitted an error string — surface it rather
+    // than mask it (matches the web contract `isFailureSignal`). The envelope
+    // error is kept when present; the failed op's own error backs it up.
+    if (op.ok === false || op.status === "error" || firstFailed) {
+        const message = (typeof op.error === "string" && op.error.length > 0 && op.error) ||
+            (typeof firstFailed?.error === "string" && firstFailed.error.length > 0 && firstFailed.error) ||
+            (firstFailed
+                ? `Engine op failed${firstFailed.op ? ` (${firstFailed.op})` : ""}.`
+                : op.ok === false
+                    ? "Engine operation failed (ok: false)."
+                    : "Engine operation failed (status: error).");
+        return classify(message);
+    }
+    return null;
+}
+/** The per-op text an older engine answers for a Kind its dispatch ladder does
+ *  not know (ops_executor.cpp fallthrough: `unknown op: <Kind>`). */
+const UNKNOWN_OP_PATTERN = /unknown op/i;
+/**
+ * An older engine answers an unknown op with a per-op "unknown op: <Kind>"
+ * (ops_executor.cpp fallthrough). Amend the envelope's error so the model gets
+ * the upgrade path instead of retrying, and stamp `failure_reason:
+ * "engine_lacks_op"` (+ `op`) so the result is detectable the same way as the
+ * capability pre-flight's MissingOpResult: programmatic callers read the
+ * field (the CLI prints the whole receipt), and extractOpError renders the
+ * classified failure as JSON. Engines WITH a capability advert never reach
+ * this — the pre-flight in missingEngineOpResult refuses before sending.
+ * A chunked mutation (executeSceneMutation) rewrites the envelope error into
+ * the "N earlier op(s) already applied" receipt, so the raw per-op text lives
+ * only inside results[] — both are read before deciding this is an old engine.
+ * Returns the input untouched when there is nothing to rewrite.
+ */
+export function withOldEngineHint(result, opName, fallback) {
+    const opError = extractOpError(result);
+    if (!opError)
+        return result;
+    const envelope = (result ?? {});
+    const failedOpError = envelope.results?.find((entry) => entry.ok === false && typeof entry.error === "string")
+        ?.error;
+    const engineSaid = (typeof envelope.error === "string" && envelope.error) || failedOpError || opError;
+    if (!UNKNOWN_OP_PATTERN.test(opError) && !UNKNOWN_OP_PATTERN.test(failedOpError ?? ""))
+        return result;
+    return {
+        ...envelope,
+        op: opName,
+        failure_reason: "engine_lacks_op",
+        error: `This Summer Engine build doesn't support ${opName} yet — ` +
+            `${fallback}, or update Summer Engine (restart it after updating). ` +
+            `Engine said: ${failedOpError ?? engineSaid}`,
+    };
+}

package/dist/core/capabilities/events.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Engine events channel — the ONE implementation behind summer_wait_for_event,
+ * summer_recent_events (MCP + `summer tool`) and `summer events` (CLI).
+ *
+ * Transport: GET /api/events/poll, the engine's long-poll route
+ * ({events:[{seq, kind, ts, data}], next_seq, last_seq, since, truncated,
+ * timed_out}). The SSE route (GET /api/events) is deliberately NOT consumed in
+ * v1 — the poll loop is the portable path through MCP hosts and proxies; an
+ * SSE client is a follow-up.
+ *
+ * Two rules every caller inherits:
+ *   - `seq` is a monotonic cursor. A result's next_seq is the `since` of the
+ *     next call; events are delivered live from `since`, so a caller who might
+ *     miss an event that fires immediately takes a cursor FIRST (recentEvents)
+ *     and passes it as `since`.
+ *   - timed_out:true is reported as exactly that — no match arrived — never
+ *     coerced into a failure or a success.
+ *
+ * Whether the engine HAS the channel is decided before anything is sent by
+ * missingEngineEventsResult (core/capability-skew.ts); this module carries the
+ * post-hoc twin for engines reached with the pre-flight off (HTTP 404).
+ */
+import { z } from "zod";
+import type { EventsPollParams } from "../api-client.js";
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+/** Event kinds v1 (SCENE_SCRIPTING_CONTRACTS.md, the engine scene-scripting contracts). sys.* transport
+ *  frames (sys.gap, sys.closed) are not kinds: never in the ring, never
+ *  filterable, surfaced separately below. */
+export declare const EVENT_KINDS_V1: readonly ["op.applied", "op.failed", "script.error", "play.started", "play.stopped", "scene.saved", "scene.opened", "import.completed", "selection.changed", "snapshot.published"];
+export declare const WAIT_DEFAULT_SECONDS = 30;
+export declare const WAIT_MIN_SECONDS = 1;
+export declare const WAIT_MAX_SECONDS = 120;
+/** Each held poll stays under this: below typical proxy/host idle limits and
+ *  under the engine's own 60 s cap. The wait loop chains slices. */
+export declare const POLL_SLICE_MS = 25000;
+export declare const WAIT_MAX_EVENTS_DEFAULT = 20;
+/** Engine cap on `limit` per poll answer. */
+export declare const POLL_LIMIT_CAP = 500;
+export declare const RECENT_LIMIT_DEFAULT = 50;
+export declare const RECENT_LIMIT_CAP = 200;
+/** Pacing sleep after a zero-event answer that came back before its `wait`
+ *  elapsed (an engine that answers held polls early would otherwise spin the
+ *  loop). Exported for the CLI follow loop. */
+export declare const PACING_MS = 250;
+export interface EngineEvent {
+    seq: number;
+    kind: string;
+    /** unix ms */
+    ts?: number;
+    data?: unknown;
+}
+/** A sys.* transport frame delivered inside a poll page. */
+export interface EventsFrame {
+    kind: string;
+    data?: unknown;
+}
+/** The client surface this module needs — EngineApiClient satisfies it. */
+export interface EventsClient extends CapabilityAdvertisingClient {
+    pollEvents(params?: EventsPollParams, timeoutMs?: number): Promise<unknown>;
+}
+export declare const waitForEventArgsSchema: z.ZodObject<{
+    kinds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    since: z.ZodOptional<z.ZodNumber>;
+    timeout_seconds: z.ZodOptional<z.ZodNumber>;
+    match: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId?: string | undefined;
+    }, {
+        requestId?: string | undefined;
+    }>>;
+    max_events: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    match?: {
+        requestId?: string | undefined;
+    } | undefined;
+    kinds?: string[] | undefined;
+    since?: number | undefined;
+    timeout_seconds?: number | undefined;
+    max_events?: number | undefined;
+}, {
+    match?: {
+        requestId?: string | undefined;
+    } | undefined;
+    kinds?: string[] | undefined;
+    since?: number | undefined;
+    timeout_seconds?: number | undefined;
+    max_events?: number | undefined;
+}>;
+export type WaitForEventArgs = z.infer<typeof waitForEventArgsSchema>;
+export declare const recentEventsArgsSchema: z.ZodObject<{
+    since: z.ZodOptional<z.ZodNumber>;
+    kinds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    kinds?: string[] | undefined;
+    since?: number | undefined;
+    limit?: number | undefined;
+}, {
+    kinds?: string[] | undefined;
+    since?: number | undefined;
+    limit?: number | undefined;
+}>;
+export type RecentEventsArgs = z.infer<typeof recentEventsArgsSchema>;
+export interface WaitForEventResult {
+    ok: true;
+    /** True when at least one event matched; events is then non-empty. */
+    matched: boolean;
+    events: EngineEvent[];
+    /** Cursor for the next call. null only when the engine never reported one. */
+    next_seq: number | null;
+    /** The cursor this wait started from (the engine's live head when omitted). */
+    since: number | null;
+    /** True when timeout_seconds elapsed with no match. Not a failure — and not
+     *  evidence the awaited thing did not happen. */
+    timed_out: boolean;
+    waited_ms: number;
+    polls: number;
+    kinds: string[] | "all";
+    match?: {
+        requestId: string;
+    };
+    /** sys.gap payload when events between since and the oldest retained were
+     *  evicted — the stream is not gapless; re-read state. */
+    gap?: unknown;
+    /** The page that produced the match was full; more matches may follow from next_seq. */
+    truncated?: boolean;
+    hint?: string;
+}
+export interface RecentEventsResult {
+    ok: true;
+    events: EngineEvent[];
+    count: number;
+    next_seq: number | null;
+    last_seq: number | null;
+    /** The cursor the read started from. */
+    since: number | null;
+    /** How `since` was chosen: the caller's value, or the newest-`limit` window. */
+    window: "since" | "newest" | "ring";
+    truncated: boolean;
+    kinds: string[] | "all";
+    gap?: unknown;
+    hint: string;
+}
+/** Any structured failure: engine_lacks_events, unknown_event_kind, an
+ *  identity_mismatch terminalState, a 503, ... Both faces classify it by its
+ *  fields (MCP isError, CLI ToolResultError). */
+export type EventsFailure = Record<string, unknown> & {
+    ok: false;
+};
+/** Trim, drop empties, dedupe, keep order. */
+export declare function normalizeKinds(kinds: readonly string[] | undefined): string[];
+/**
+ * Refuse kinds the engine cannot emit — waiting on one would only time out.
+ * Decidable only when the engine advertises `capabilities.events.kinds`; an
+ * engine without the list lets every kind through (forward-compatible with
+ * kinds newer than this CLI).
+ */
+export declare function unknownKindsFailure(kinds: readonly string[], client: CapabilityAdvertisingClient): EventsFailure | null;
+export interface ParsedPollPage {
+    events: EngineEvent[];
+    frames: EventsFrame[];
+    next_seq?: number;
+    last_seq?: number;
+    since?: number;
+    truncated: boolean;
+    timed_out: boolean;
+}
+/** Shape-tolerant read of a poll envelope: ring events need a numeric seq and
+ *  a string kind; sys.* frames are split out (they may carry no seq). */
+export declare function parsePollPage(raw: unknown): ParsedPollPage;
+/**
+ * A poll answer that is a structured failure, or null on a 2xx envelope. The
+ * post-hoc twin of the missingEngineEventsResult pre-flight: an engine that
+ * answers HTTP 404 for the poll route has no channel (reachable only with
+ * SUMMER_CAPABILITY_PREFLIGHT=off, or an advert that lies), so the answer is
+ * rewritten into the same engine_lacks_events shape the pre-flight returns.
+ */
+export declare function eventsFailure(page: unknown, client: CapabilityAdvertisingClient): EventsFailure | null;
+/** op.* events match only when data.requestId equals the requested id; every
+ *  other kind passes. */
+export declare function selectMatches(events: readonly EngineEvent[], requestId?: string): EngineEvent[];
+export interface EventsDeps {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Long-poll the engine in slices of at most POLL_SLICE_MS until an event
+ * passes the kinds + match filters, or timeout_seconds elapses. Every poll
+ * feeds the engine's next_seq back as `since`, so nothing between slices is
+ * skipped; sys.gap frames are surfaced (never counted as a match).
+ */
+export declare function waitForEvent(client: EventsClient, args: WaitForEventArgs, deps?: EventsDeps): Promise<WaitForEventResult | EventsFailure>;
+/**
+ * One zero-wait read. `since` given: everything after it (paged by limit).
+ * `since` omitted: the newest `limit` sequence numbers — the poll route has no
+ * "tail" mode, so this costs two zero-wait calls (learn last_seq, then read
+ * from last_seq - limit). `since: 0` pages the retained ring from the oldest.
+ */
+export declare function recentEvents(client: EventsClient, args: RecentEventsArgs): Promise<RecentEventsResult | EventsFailure>;