summer-engine 2.8.1 → 3.0.0

package/dist/core/capabilities/events.js

@@ -0,0 +1,383 @@
+/**
+ * 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 { EVENTS_FALLBACK, buildMissingEventsResult, } from "../capability-skew.js";
+import { asRecord, numberFrom, stringFrom } from "../util/json.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 const EVENT_KINDS_V1 = [
+    "op.applied",
+    "op.failed",
+    "script.error",
+    "play.started",
+    "play.stopped",
+    "scene.saved",
+    "scene.opened",
+    "import.completed",
+    "selection.changed",
+    "snapshot.published",
+];
+export const WAIT_DEFAULT_SECONDS = 30;
+export const WAIT_MIN_SECONDS = 1;
+export 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 const POLL_SLICE_MS = 25_000;
+export const WAIT_MAX_EVENTS_DEFAULT = 20;
+/** Engine cap on `limit` per poll answer. */
+export const POLL_LIMIT_CAP = 500;
+export const RECENT_LIMIT_DEFAULT = 50;
+export 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 const PACING_MS = 250;
+// ---------------------------------------------------------------------------
+// Argument schemas — shared by the MCP registration (raw shape) and the CLI
+// dispatcher (same zod), so both faces reject the same inputs.
+// ---------------------------------------------------------------------------
+const kindsSchema = z
+    .array(z.string().min(1))
+    .describe(`Event kinds to deliver (default: all). v1 kinds: ${EVENT_KINDS_V1.join(", ")}. Unknown kinds are refused before waiting when the engine advertises its list.`);
+export const waitForEventArgsSchema = z.object({
+    kinds: kindsSchema.optional(),
+    since: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Deliver events with seq > since. Omit = live from now (an event that already fired is NOT delivered — take a cursor with summer_recent_events first and pass its next_seq here). 0 = replay the retained ring."),
+    timeout_seconds: z
+        .number()
+        .optional()
+        .describe("How long to wait for a match (default 30, clamped 1-120). The call long-polls in slices of at most 25 s."),
+    match: z
+        .object({
+        requestId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Only op.applied / op.failed events for this requestId match; every other kind passes through."),
+    })
+        .optional()
+        .describe("Extra client-side filters applied after the kinds filter."),
+    max_events: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Maximum matched events to return (default 20, cap 500)."),
+});
+export const recentEventsArgsSchema = z.object({
+    since: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Deliver events with seq > since. Omit = the newest `limit` sequence numbers. 0 = the whole retained ring from the oldest (paged: pass next_seq back while truncated is true)."),
+    kinds: kindsSchema.optional(),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Maximum events to return (default 50, cap 200)."),
+});
+// ---------------------------------------------------------------------------
+// Helpers (exported for the CLI command and tests)
+// ---------------------------------------------------------------------------
+function clampInt(value, min, max) {
+    return Math.min(max, Math.max(min, Math.round(value)));
+}
+/** Trim, drop empties, dedupe, keep order. */
+export function normalizeKinds(kinds) {
+    const out = [];
+    for (const raw of kinds ?? []) {
+        const kind = raw.trim();
+        if (kind && !out.includes(kind))
+            out.push(kind);
+    }
+    return out;
+}
+/**
+ * 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 function unknownKindsFailure(kinds, client) {
+    const advertised = typeof client.getEngineCapabilities === "function"
+        ? client.getEngineCapabilities()?.events?.kinds
+        : undefined;
+    if (!advertised || advertised.length === 0)
+        return null;
+    const known = new Set(advertised);
+    const unknown = kinds.filter((kind) => !known.has(kind));
+    if (unknown.length === 0)
+        return null;
+    return {
+        ok: false,
+        failure_reason: "unknown_event_kind",
+        unknown_kinds: unknown,
+        known_kinds: [...advertised],
+        error: `This Summer Engine build does not emit event kind(s) ${unknown.join(", ")} — nothing was sent (waiting would only time out). ` +
+            `Kinds it emits: ${advertised.join(", ")}.`,
+    };
+}
+/** 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 function parsePollPage(raw) {
+    const record = asRecord(raw) ?? {};
+    const events = [];
+    const frames = [];
+    if (Array.isArray(record.events)) {
+        for (const entry of record.events) {
+            const item = asRecord(entry);
+            const kind = item ? stringFrom(item.kind) : undefined;
+            if (!item || !kind)
+                continue;
+            if (kind.startsWith("sys.")) {
+                frames.push({ kind, data: item.data });
+                continue;
+            }
+            const seq = numberFrom(item.seq);
+            if (seq === undefined)
+                continue;
+            const event = { seq, kind };
+            const ts = numberFrom(item.ts);
+            if (ts !== undefined)
+                event.ts = ts;
+            if (item.data !== undefined)
+                event.data = item.data;
+            events.push(event);
+        }
+    }
+    return {
+        events,
+        frames,
+        next_seq: numberFrom(record.next_seq),
+        last_seq: numberFrom(record.last_seq),
+        since: numberFrom(record.since),
+        truncated: record.truncated === true,
+        timed_out: record.timed_out === true,
+    };
+}
+/**
+ * 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 function eventsFailure(page, client) {
+    const record = asRecord(page);
+    if (!record) {
+        return {
+            ok: false,
+            failure_reason: "malformed_events_envelope",
+            error: "Summer Engine answered the events poll with a non-object body; nothing can be read from it.",
+        };
+    }
+    if (record.ok !== false)
+        return null;
+    if (record.http_status === 404) {
+        const version = typeof client.getEngineVersion === "function" ? client.getEngineVersion() : undefined;
+        const missing = buildMissingEventsResult(version ?? null);
+        return {
+            ...record,
+            ok: false,
+            failure_reason: missing.failure_reason,
+            engine_version: missing.engine_version,
+            hint: missing.hint,
+            error: "This Summer Engine build doesn't expose the events channel yet (GET /api/events/poll answered HTTP 404) — " +
+                `${EVENTS_FALLBACK}, or update Summer Engine (restart it after updating).`,
+        };
+    }
+    return record;
+}
+/** op.* events match only when data.requestId equals the requested id; every
+ *  other kind passes. */
+export function selectMatches(events, requestId) {
+    if (!requestId)
+        return [...events];
+    return events.filter((event) => {
+        if (!event.kind.startsWith("op."))
+            return true;
+        return asRecord(event.data)?.requestId === requestId;
+    });
+}
+function gapOf(frames) {
+    return frames.find((frame) => frame.kind === "sys.gap")?.data;
+}
+function maxSeq(events) {
+    let max;
+    for (const event of events)
+        if (max === undefined || event.seq > max)
+            max = event.seq;
+    return max;
+}
+// ---------------------------------------------------------------------------
+// summer_wait_for_event
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function waitForEvent(client, args, deps = {}) {
+    const now = deps.now ?? (() => Date.now());
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const kinds = normalizeKinds(args.kinds);
+    const unknown = unknownKindsFailure(kinds, client);
+    if (unknown)
+        return unknown;
+    const timeoutSeconds = clampInt(args.timeout_seconds ?? WAIT_DEFAULT_SECONDS, WAIT_MIN_SECONDS, WAIT_MAX_SECONDS);
+    const maxEvents = clampInt(args.max_events ?? WAIT_MAX_EVENTS_DEFAULT, 1, POLL_LIMIT_CAP);
+    const requestId = args.match?.requestId?.trim() || undefined;
+    const kindsParam = kinds.length > 0 ? kinds : undefined;
+    const start = now();
+    const deadline = start + timeoutSeconds * 1000;
+    let since = args.since;
+    let resolvedSince = args.since ?? null;
+    let polls = 0;
+    let gap;
+    for (;;) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            break;
+        const wait = Math.min(POLL_SLICE_MS, remaining);
+        const pollStart = now();
+        const page = await client.pollEvents({ since, kinds: kindsParam, wait, limit: maxEvents });
+        const held = now() - pollStart;
+        polls += 1;
+        const failure = eventsFailure(page, client);
+        if (failure)
+            return failure;
+        const parsed = parsePollPage(page);
+        if (resolvedSince === null && parsed.since !== undefined)
+            resolvedSince = parsed.since;
+        const frameGap = gapOf(parsed.frames);
+        if (frameGap !== undefined)
+            gap = frameGap;
+        const advanced = parsed.next_seq ?? maxSeq(parsed.events);
+        if (advanced !== undefined)
+            since = advanced;
+        const matched = selectMatches(parsed.events, requestId).slice(0, maxEvents);
+        if (matched.length > 0) {
+            return {
+                ok: true,
+                matched: true,
+                events: matched,
+                next_seq: since ?? null,
+                since: resolvedSince,
+                timed_out: false,
+                waited_ms: now() - start,
+                polls,
+                kinds: kinds.length > 0 ? kinds : "all",
+                ...(requestId ? { match: { requestId } } : {}),
+                ...(gap !== undefined ? { gap } : {}),
+                ...(parsed.truncated ? { truncated: true } : {}),
+            };
+        }
+        // A zero-event answer that returned before its hold elapsed must not spin
+        // the loop (the flag is not trusted; the clock is).
+        if (parsed.events.length === 0 && held < wait)
+            await sleep(Math.min(PACING_MS, wait - held));
+    }
+    return {
+        ok: true,
+        matched: false,
+        events: [],
+        next_seq: since ?? null,
+        since: resolvedSince,
+        timed_out: true,
+        waited_ms: now() - start,
+        polls,
+        kinds: kinds.length > 0 ? kinds : "all",
+        ...(requestId ? { match: { requestId } } : {}),
+        ...(gap !== undefined ? { gap } : {}),
+        hint: `No matching event arrived within ${timeoutSeconds}s. This is not evidence that it did not happen: ` +
+            "an event that fired before `since` is never delivered (take a cursor with summer_recent_events BEFORE triggering the action next time). " +
+            "Verify the state directly (summer_is_running, summer_get_diagnostics, summer_get_scene_tree) and never claim an event you did not receive. " +
+            "To keep waiting without a gap, call again with since = next_seq.",
+    };
+}
+// ---------------------------------------------------------------------------
+// summer_recent_events
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function recentEvents(client, args) {
+    const kinds = normalizeKinds(args.kinds);
+    const unknown = unknownKindsFailure(kinds, client);
+    if (unknown)
+        return unknown;
+    const limit = clampInt(args.limit ?? RECENT_LIMIT_DEFAULT, 1, RECENT_LIMIT_CAP);
+    const kindsParam = kinds.length > 0 ? kinds : undefined;
+    let since = args.since;
+    let window = since === undefined ? "newest" : since === 0 ? "ring" : "since";
+    if (since === undefined) {
+        // Live-only head read: zero events, but the newest seq.
+        const head = await client.pollEvents({ wait: 0, limit: 1 });
+        const headFailure = eventsFailure(head, client);
+        if (headFailure)
+            return headFailure;
+        const parsedHead = parsePollPage(head);
+        const newest = parsedHead.last_seq ?? parsedHead.next_seq;
+        if (newest === undefined) {
+            since = 0;
+            window = "ring";
+        }
+        else {
+            since = Math.max(0, newest - limit);
+        }
+    }
+    const page = await client.pollEvents({ since, kinds: kindsParam, wait: 0, limit });
+    const failure = eventsFailure(page, client);
+    if (failure)
+        return failure;
+    const parsed = parsePollPage(page);
+    const nextSeq = parsed.next_seq ?? maxSeq(parsed.events) ?? since;
+    const gap = gapOf(parsed.frames);
+    return {
+        ok: true,
+        events: parsed.events,
+        count: parsed.events.length,
+        next_seq: nextSeq ?? null,
+        last_seq: parsed.last_seq ?? null,
+        since: parsed.since ?? since ?? null,
+        window,
+        truncated: parsed.truncated,
+        kinds: kinds.length > 0 ? kinds : "all",
+        ...(gap !== undefined ? { gap } : {}),
+        hint: "Pass next_seq as `since` to summer_wait_for_event BEFORE triggering the action you will wait on, or back to this tool to read what arrived since. " +
+            "The engine retains 512 events / 10 minutes — an empty result is not proof nothing happened earlier." +
+            (parsed.truncated ? " truncated:true — this page was full; pass next_seq back as since for the rest." : ""),
+    };
+}

package/dist/core/capabilities/fabricate-mesh.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Mesh-fabrication op builder (tool/fabricate-3d -> engine op FabricateMesh).
+ * Shared by the MCP tool (summer_fabricate_3d) and the CLI dispatcher
+ * (`summer tool fabricate-3d`) so both faces validate the same arguments, send
+ * the same op with the same clamps, and wait the same client poll budget.
+ *
+ * What the op does on the engine side (fabricate_ops.cpp, mesh fabrication): run one
+ * agent-authored bpy script in a supervised headless child of the USER'S OWN
+ * Blender install, validate the .glb the child exported, move it under res://,
+ * wait for the editor import to settle, and optionally instantiate it into the
+ * edited scene. This package never spawns Blender, never imports bpy, and
+ * never downloads or bundles Blender — it only sends the op. "Blender" appears
+ * in user-facing text only as the name of the dependency.
+ *
+ * Server-side clamps mirrored here: 15..600 s, default 120 — the budget covers
+ * Blender boot + the script + procedural-colour bakes + export, so the floor is
+ * the same as RunEditorScript's child-editor floor.
+ */
+import { z } from "zod";
+export declare const FABRICATE_MIN_SECONDS = 15;
+export declare const FABRICATE_MAX_SECONDS = 600;
+export declare const FABRICATE_DEFAULT_SECONDS = 120;
+/** Client poll headroom beyond the engine's own budget: the res:// move, the
+ *  import settle-wait and InstantiateScene all run AFTER the child exits. */
+export declare const FABRICATE_CLIENT_HEADROOM_MS = 60000;
+/** Where the engine writes the .glb when out_path is omitted. */
+export declare const FABRICATE_DEFAULT_OUT_DIR = "res://assets/fabricated/";
+/** What the tool tells the model to do when the engine lacks FabricateMesh. */
+export declare const FABRICATE_FALLBACK = "generate the asset with summer_generate_3d, import one from the free library with summer_search_assets / summer_import_asset, use summer_import_hdri for environment lighting, or build blockout geometry in-scene with summer_add_node / summer_set_prop or a summer_run_editor_script";
+/**
+ * Mirror of the engine's out_path pre-validation (fabricate_ops.cpp
+ * _resolve_out_path) so a bad destination is refused on this side with the
+ * same words, and nothing is sent. Returns null when the path is acceptable.
+ */
+export declare function fabricateOutPathProblem(rawPath: string): string | null;
+/**
+ * The one input contract for summer_fabricate_3d, shared by the MCP tool
+ * (pass `.shape` to server.tool) and the CLI dispatcher (`summer tool
+ * fabricate-3d`) so both faces reject the same inputs with the same message.
+ */
+export declare const fabricateArgsSchema: z.ZodObject<{
+    source: z.ZodString;
+    name: z.ZodString;
+    out_path: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    target_size: z.ZodOptional<z.ZodNumber>;
+    import_to_scene: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        position: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        parent: string;
+        position?: string | undefined;
+    }, {
+        parent: string;
+        position?: string | undefined;
+    }>>;
+    max_seconds: z.ZodOptional<z.ZodNumber>;
+    checkpoint: z.ZodOptional<z.ZodBoolean>;
+    blender_path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    name: string;
+    out_path?: string | undefined;
+    target_size?: number | undefined;
+    import_to_scene?: {
+        parent: string;
+        position?: string | undefined;
+    } | undefined;
+    max_seconds?: number | undefined;
+    checkpoint?: boolean | undefined;
+    blender_path?: string | undefined;
+}, {
+    source: string;
+    name: string;
+    out_path?: string | undefined;
+    target_size?: number | undefined;
+    import_to_scene?: {
+        parent: string;
+        position?: string | undefined;
+    } | undefined;
+    max_seconds?: number | undefined;
+    checkpoint?: boolean | undefined;
+    blender_path?: string | undefined;
+}>;
+export interface FabricateImportToScene {
+    parent: string;
+    position?: string;
+}
+export interface FabricateMeshArgs {
+    source: string;
+    name: string;
+    out_path?: string;
+    target_size?: number;
+    import_to_scene?: FabricateImportToScene;
+    max_seconds?: number;
+    checkpoint?: boolean;
+    blender_path?: string;
+}
+export interface BuiltFabricateOp {
+    op: Record<string, unknown>;
+    /** Client poll budget — MUST outlive the engine's own max_seconds plus the
+     *  main-thread finalizer (move, import settle, instantiate), or a long but
+     *  successful fabrication is reported as timed_out client-side. */
+    timeoutMs: number;
+}
+/**
+ * Build the single FabricateMesh op (+ client budget) from validated args.
+ * Re-checks the pre-apply invariants so a caller that bypasses the zod schema
+ * still cannot send a bad destination or an unusable script: every throw here
+ * is a ToolInputError, classified as "nothing was sent" by both faces.
+ */
+export declare function buildFabricateMeshOp(args: FabricateMeshArgs): BuiltFabricateOp;

package/dist/core/capabilities/fabricate-mesh.js

@@ -0,0 +1,165 @@
+/**
+ * Mesh-fabrication op builder (tool/fabricate-3d -> engine op FabricateMesh).
+ * Shared by the MCP tool (summer_fabricate_3d) and the CLI dispatcher
+ * (`summer tool fabricate-3d`) so both faces validate the same arguments, send
+ * the same op with the same clamps, and wait the same client poll budget.
+ *
+ * What the op does on the engine side (fabricate_ops.cpp, mesh fabrication): run one
+ * agent-authored bpy script in a supervised headless child of the USER'S OWN
+ * Blender install, validate the .glb the child exported, move it under res://,
+ * wait for the editor import to settle, and optionally instantiate it into the
+ * edited scene. This package never spawns Blender, never imports bpy, and
+ * never downloads or bundles Blender — it only sends the op. "Blender" appears
+ * in user-facing text only as the name of the dependency.
+ *
+ * Server-side clamps mirrored here: 15..600 s, default 120 — the budget covers
+ * Blender boot + the script + procedural-colour bakes + export, so the floor is
+ * the same as RunEditorScript's child-editor floor.
+ */
+import { z } from "zod";
+import { ToolInputError } from "../tool-errors.js";
+export const FABRICATE_MIN_SECONDS = 15;
+export const FABRICATE_MAX_SECONDS = 600;
+export const FABRICATE_DEFAULT_SECONDS = 120;
+/** Client poll headroom beyond the engine's own budget: the res:// move, the
+ *  import settle-wait and InstantiateScene all run AFTER the child exits. */
+export const FABRICATE_CLIENT_HEADROOM_MS = 60_000;
+/** Where the engine writes the .glb when out_path is omitted. */
+export const FABRICATE_DEFAULT_OUT_DIR = "res://assets/fabricated/";
+/** What the tool tells the model to do when the engine lacks FabricateMesh. */
+export const FABRICATE_FALLBACK = "generate the asset with summer_generate_3d, import one from the free library with summer_search_assets / summer_import_asset, use summer_import_hdri for environment lighting, or build blockout geometry in-scene with summer_add_node / summer_set_prop or a summer_run_editor_script";
+const VECTOR3_VARIANT_RE = /^Vector3\(\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*,\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*,\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*\)$/;
+/**
+ * Mirror of the engine's out_path pre-validation (fabricate_ops.cpp
+ * _resolve_out_path) so a bad destination is refused on this side with the
+ * same words, and nothing is sent. Returns null when the path is acceptable.
+ */
+export function fabricateOutPathProblem(rawPath) {
+    const path = rawPath.trim().replace(/\\/g, "/");
+    if (!path.startsWith("res://"))
+        return `out_path must start with res:// (got '${path}').`;
+    if (!/\.glb$/i.test(path)) {
+        return "out_path must end in .glb; the fabricator exports binary glTF which the engine imports as a scene.";
+    }
+    const parts = path.slice("res://".length).split("/").filter((part) => part.length > 0);
+    if (parts.length < 1)
+        return "out_path must name a file under res://.";
+    for (const part of parts) {
+        if (part === "..")
+            return "out_path may not contain '..'.";
+        if (part.startsWith(".")) {
+            return `out_path may not point into a hidden directory or file (the editor never imports those): ${path}`;
+        }
+    }
+    return null;
+}
+/**
+ * The one input contract for summer_fabricate_3d, shared by the MCP tool
+ * (pass `.shape` to server.tool) and the CLI dispatcher (`summer tool
+ * fabricate-3d`) so both faces reject the same inputs with the same message.
+ */
+export const fabricateArgsSchema = z.object({
+    source: z
+        .string()
+        .min(1)
+        .describe("Blender Python (bpy) code that CREATES mesh objects and leaves them linked in the scene. Do not export — the engine exports the .glb for you. Pre-bound names: bpy, bmesh, mathutils, math, Vector, Matrix, Euler."),
+    name: z
+        .string()
+        .min(1)
+        .describe("Asset name — used for the default out_path (res://assets/fabricated/<name>.glb) and for the instantiated node. Sanitized by the engine to [A-Za-z0-9_-]."),
+    out_path: z
+        .string()
+        .superRefine((value, ctx) => {
+        const problem = fabricateOutPathProblem(value);
+        if (problem)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem });
+    })
+        .optional()
+        .describe("Destination res:// path ending in .glb (default res://assets/fabricated/<name>.glb). An existing file is overwritten; '..' and hidden directories are refused."),
+    target_size: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Largest world-AABB dimension in units after instantiation — uniform scale, same rule as summer_instantiate_scene target_size (chair 1.0, car 4.5). Only used together with import_to_scene."),
+    import_to_scene: z
+        .object({
+        parent: z
+            .string()
+            .describe("Parent node path in the CURRENTLY OPEN scene, e.g. '/' (scene root) or './World'."),
+        position: z
+            .string()
+            .regex(VECTOR3_VARIANT_RE, "position must be a 'Vector3(x, y, z)' variant string")
+            .optional()
+            .describe("Optional local position as the engine variant string 'Vector3(x, y, z)'."),
+    })
+        .optional()
+        .describe("Instantiate the imported .glb into the currently open scene after import (one undo action). Omit to only write and import the file."),
+    max_seconds: z
+        .number()
+        .optional()
+        .describe("Child budget in seconds (default 120, clamped 15-600): Blender boot + script + procedural-colour bakes + export. Raise it for heavy booleans or bakes; the client waits max_seconds + 60 s."),
+    checkpoint: z
+        .boolean()
+        .optional()
+        .describe("Take a SummerGit checkpoint before the child runs (default false). The result confesses (no_rewind_point) when none could be taken."),
+    blender_path: z
+        .string()
+        .optional()
+        .describe("Explicit Blender executable. Pass only when the user named one; otherwise the engine resolves SUMMER_BLENDER_BIN, the editor setting filesystem/import/blender/blender_path, then PATH and well-known install locations."),
+});
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, Math.round(value)));
+}
+/**
+ * Build the single FabricateMesh op (+ client budget) from validated args.
+ * Re-checks the pre-apply invariants so a caller that bypasses the zod schema
+ * still cannot send a bad destination or an unusable script: every throw here
+ * is a ToolInputError, classified as "nothing was sent" by both faces.
+ */
+export function buildFabricateMeshOp(args) {
+    if (typeof args.source !== "string" || args.source.trim().length === 0) {
+        throw new ToolInputError("source is required: bpy code that creates mesh objects and leaves them linked in the scene (the engine exports them).");
+    }
+    if (typeof args.name !== "string" || args.name.trim().length === 0) {
+        throw new ToolInputError("name is required: it names the .glb (res://assets/fabricated/<name>.glb) and the instantiated node.");
+    }
+    const budgetSeconds = clamp(typeof args.max_seconds === "number" && Number.isFinite(args.max_seconds)
+        ? args.max_seconds
+        : FABRICATE_DEFAULT_SECONDS, FABRICATE_MIN_SECONDS, FABRICATE_MAX_SECONDS);
+    const op = {
+        op: "FabricateMesh",
+        script_source: args.source,
+        name: args.name.trim(),
+        max_seconds: budgetSeconds,
+    };
+    if (typeof args.out_path === "string" && args.out_path.trim().length > 0) {
+        const problem = fabricateOutPathProblem(args.out_path);
+        if (problem)
+            throw new ToolInputError(problem);
+        op.out_path = args.out_path.trim().replace(/\\/g, "/");
+    }
+    if (args.target_size !== undefined) {
+        if (typeof args.target_size !== "number" || !Number.isFinite(args.target_size) || args.target_size <= 0) {
+            throw new ToolInputError("target_size must be a positive number (largest AABB dimension after instantiation).");
+        }
+        op.target_size = args.target_size;
+    }
+    if (args.import_to_scene !== undefined) {
+        const spec = args.import_to_scene;
+        const parent = typeof spec.parent === "string" && spec.parent.trim().length > 0 ? spec.parent.trim() : "/";
+        const importSpec = { parent };
+        if (spec.position !== undefined) {
+            if (typeof spec.position !== "string" || !VECTOR3_VARIANT_RE.test(spec.position.trim())) {
+                throw new ToolInputError(`import_to_scene.position must be a 'Vector3(x, y, z)' variant string (got ${JSON.stringify(spec.position)}).`);
+            }
+            importSpec.position = spec.position.trim();
+        }
+        op.import_to_scene = importSpec;
+    }
+    if (args.checkpoint !== undefined)
+        op.checkpoint = args.checkpoint;
+    if (typeof args.blender_path === "string" && args.blender_path.trim().length > 0) {
+        op.blender_path = args.blender_path.trim();
+    }
+    return { op, timeoutMs: budgetSeconds * 1000 + FABRICATE_CLIENT_HEADROOM_MS };
+}