@jgengine/editor 0.10.0

package/dist/agent/AgentPanel.js

@@ -0,0 +1,156 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { BTN, INPUT, MICRO } from "../chromeStyles.js";
+import { createDefaultAgentEndpoint, createHttpAgentEndpoint, createLocalAgentEndpoint, EDITOR_AGENT_KEY_ENV, EDITOR_AGENT_URL_ENV, resolveAgentEndpointConfig, } from "./endpoint.js";
+import { packAgentContext } from "./context.js";
+import { runAgentTurn, undoAgentPatch, } from "./turn.js";
+const STORAGE_URL = "jgengine.editorAgentUrl";
+const STORAGE_KEY = "jgengine.editorAgentKey";
+function readStoredConfig() {
+    if (typeof localStorage === "undefined")
+        return { url: "", apiKey: "" };
+    return {
+        url: localStorage.getItem(STORAGE_URL) ?? "",
+        apiKey: localStorage.getItem(STORAGE_KEY) ?? "",
+    };
+}
+function buildEndpoint(url, apiKey) {
+    const env = resolveAgentEndpointConfig();
+    const resolvedUrl = url.trim() || env.url || "";
+    const resolvedKey = apiKey.trim() || env.apiKey || "";
+    if (resolvedUrl.length > 0) {
+        return createHttpAgentEndpoint({ url: resolvedUrl, apiKey: resolvedKey || undefined });
+    }
+    return createLocalAgentEndpoint();
+}
+/**
+ * Dockable in-editor agent chat: humans and agents share the same RPC/undo surface.
+ * Tool calls route through `EditorHostApi.handle`; patches appear in the transcript and can be undone.
+ * @internal — mounted by `EditorChrome`.
+ */
+export function AgentPanel({ api, onClose, }) {
+    const stored = useMemo(() => readStoredConfig(), []);
+    const [url, setUrl] = useState(stored.url);
+    const [apiKey, setApiKey] = useState(stored.apiKey);
+    const [showConfig, setShowConfig] = useState(false);
+    const [input, setInput] = useState("");
+    const [busy, setBusy] = useState(false);
+    const [history, setHistory] = useState([]);
+    const [transcript, setTranscript] = useState([]);
+    const [patches, setPatches] = useState([]);
+    const [contextTick, setContextTick] = useState(0);
+    const listRef = useRef(null);
+    const endpoint = useMemo(() => buildEndpoint(url, apiKey), [url, apiKey]);
+    const context = useMemo(() => packAgentContext(api), [api, contextTick]);
+    useEffect(() => {
+        const unsubSession = api.getSession().subscribe(() => setContextTick((v) => v + 1));
+        const unsubMode = api.subscribeMode(() => setContextTick((v) => v + 1));
+        const unsubFocus = api.subscribeFocus(() => setContextTick((v) => v + 1));
+        return () => {
+            unsubSession();
+            unsubMode();
+            unsubFocus();
+        };
+    }, [api]);
+    useEffect(() => {
+        const el = listRef.current;
+        if (el !== null)
+            el.scrollTop = el.scrollHeight;
+    }, [transcript, busy]);
+    const persistConfig = useCallback(() => {
+        if (typeof localStorage === "undefined")
+            return;
+        if (url.trim().length > 0)
+            localStorage.setItem(STORAGE_URL, url.trim());
+        else
+            localStorage.removeItem(STORAGE_URL);
+        if (apiKey.trim().length > 0)
+            localStorage.setItem(STORAGE_KEY, apiKey.trim());
+        else
+            localStorage.removeItem(STORAGE_KEY);
+    }, [url, apiKey]);
+    const send = useCallback(async () => {
+        const text = input.trim();
+        if (text.length === 0 || busy)
+            return;
+        setInput("");
+        setBusy(true);
+        try {
+            const turn = await runAgentTurn({
+                api,
+                endpoint,
+                history,
+                userMessage: text,
+            });
+            setHistory(turn.messages);
+            setTranscript((prev) => [...prev, ...turn.transcript]);
+            setPatches((prev) => [...prev, ...turn.patches]);
+            setContextTick((v) => v + 1);
+        }
+        catch (error) {
+            const content = error instanceof Error ? error.message : String(error);
+            setTranscript((prev) => [
+                ...prev,
+                { kind: "user", id: `user_${Date.now()}`, content: text, at: Date.now() },
+                { kind: "error", id: `err_${Date.now()}`, content, at: Date.now() },
+            ]);
+        }
+        finally {
+            setBusy(false);
+        }
+    }, [api, busy, endpoint, history, input]);
+    const onUndoPatch = useCallback((patchId) => {
+        const result = undoAgentPatch(api, patches, patchId);
+        if (!result.ok)
+            return;
+        setPatches(result.patches);
+        setTranscript((prev) => prev.map((entry) => entry.kind === "patch" && entry.patch.id === patchId
+            ? { ...entry, patch: { ...entry.patch, undone: true } }
+            : entry));
+        setContextTick((v) => v + 1);
+    }, [api, patches]);
+    const envHint = resolveAgentEndpointConfig();
+    return (_jsxs("aside", { className: "pointer-events-auto flex w-80 min-w-64 max-w-[48vw] resize-x flex-col overflow-hidden border-l border-white/[0.08] bg-[#0d0f13]/95 backdrop-blur-md", children: [_jsxs("div", { className: "flex items-center gap-2 border-b border-white/[0.08] px-2 py-2", children: [_jsx("div", { className: MICRO, children: "Agent" }), _jsx("span", { className: `rounded-full px-1.5 py-0.5 text-[9px] font-semibold uppercase tracking-wider ${endpoint.id === "http"
+                            ? "bg-violet-500/20 text-violet-200 ring-1 ring-inset ring-violet-400/30"
+                            : "bg-white/[0.06] text-neutral-400 ring-1 ring-inset ring-white/10"}`, title: endpoint.id === "http" ? "Remote endpoint" : "Local offline agent", children: endpoint.id }), _jsx("button", { type: "button", className: `${BTN} ml-auto text-[10px]`, onClick: () => setShowConfig((v) => !v), children: "Config" }), _jsx("button", { type: "button", className: "rounded-md px-2 py-1 text-neutral-500 transition-colors hover:bg-white/10 hover:text-neutral-200", onClick: onClose, "aria-label": "Close agent panel", children: "\u00D7" })] }), showConfig ? (_jsxs("div", { className: "space-y-2 border-b border-white/[0.08] p-2", children: [_jsx("div", { className: `${MICRO} text-neutral-500`, children: "Endpoint" }), _jsx("input", { className: `w-full text-[11px] ${INPUT}`, placeholder: `${EDITOR_AGENT_URL_ENV} or https://…`, value: url, onChange: (event) => setUrl(event.target.value), onBlur: persistConfig }), _jsx("input", { className: `w-full text-[11px] ${INPUT}`, type: "password", placeholder: `${EDITOR_AGENT_KEY_ENV} / ANTHROPIC_API_KEY`, value: apiKey, onChange: (event) => setApiKey(event.target.value), onBlur: persistConfig }), _jsxs("p", { className: "text-[10px] leading-snug text-neutral-500", children: ["Env: ", EDITOR_AGENT_URL_ENV, envHint.url !== undefined ? " ✓" : " (unset)", " \u00B7 ", EDITOR_AGENT_KEY_ENV, envHint.apiKey !== undefined ? " ✓" : " (unset)", ". Empty URL uses the local command agent (/help). Remote: POST JSON ", "{messages,context,tools}", " \u2192 ", "{message?,toolCalls?}", "."] }), _jsx("button", { type: "button", className: BTN, onClick: () => {
+                            setUrl("");
+                            setApiKey("");
+                            if (typeof localStorage !== "undefined") {
+                                localStorage.removeItem(STORAGE_URL);
+                                localStorage.removeItem(STORAGE_KEY);
+                            }
+                        }, children: "Use local agent" })] })) : null, _jsxs("div", { className: "border-b border-white/[0.08] px-2 py-1.5 text-[10px] text-neutral-500", children: [_jsx("span", { className: "text-neutral-400", children: context.mode }), _jsx("span", { className: "mx-1.5 text-neutral-700", children: "\u00B7" }), _jsxs("span", { children: ["sel ", context.selection.length === 0 ? "—" : context.selection.slice(0, 3).join(", "), context.selection.length > 3 ? ` +${context.selection.length - 3}` : ""] }), _jsx("span", { className: "mx-1.5 text-neutral-700", children: "\u00B7" }), _jsxs("span", { children: [context.summary.markers, "m ", context.summary.volumes, "v ", context.summary.paths, "p"] })] }), _jsxs("div", { ref: listRef, className: "min-h-0 flex-1 space-y-2 overflow-auto p-2", children: [transcript.length === 0 ? (_jsxs("div", { className: "rounded-lg border border-dashed border-white/10 bg-black/20 p-3 text-[11px] leading-relaxed text-neutral-500", children: ["Chat drives the live scene through the same RPC verbs as the MCP bridge. Edits share undo with the toolbar. Local: try ", _jsx("code", { className: "text-cyan-300", children: "/status" }), ",", " ", _jsx("code", { className: "text-cyan-300", children: "/help" }), ", or", " ", _jsx("code", { className: "text-cyan-300", children: "move id x y z" }), "."] })) : null, transcript.map((entry) => (_jsx(TranscriptRow, { entry: entry, patches: patches, onUndo: onUndoPatch }, entry.id))), busy ? _jsx("div", { className: "text-[10px] text-violet-300", children: "Thinking\u2026" }) : null] }), patches.some((p) => !p.undone) ? (_jsxs("div", { className: "max-h-28 overflow-auto border-t border-white/[0.08] p-2", children: [_jsx("div", { className: `${MICRO} mb-1`, children: "Agent patches" }), _jsx("ul", { className: "space-y-1", children: patches
+                            .filter((p) => !p.undone)
+                            .map((patch, index, live) => {
+                            const isTop = index === live.length - 1;
+                            return (_jsxs("li", { className: "flex items-center gap-1 text-[10px] text-neutral-300", children: [_jsx("span", { className: "min-w-0 flex-1 truncate font-mono text-cyan-200/90", children: patch.summary }), _jsx("button", { type: "button", className: `${BTN} shrink-0 px-1.5 py-0.5 text-[10px] disabled:opacity-40`, disabled: !isTop, title: isTop ? "Undo this edit" : "Undo newer patches first", onClick: () => onUndoPatch(patch.id), children: "Undo" })] }, patch.id));
+                        }) })] })) : null, _jsxs("div", { className: "flex gap-1 border-t border-white/[0.08] p-2", children: [_jsx("input", { className: `min-w-0 flex-1 text-[12px] ${INPUT}`, placeholder: endpoint.id === "local" ? "/help · /status · move id x y z" : "Ask the agent to edit the scene…", value: input, disabled: busy, onChange: (event) => setInput(event.target.value), onKeyDown: (event) => {
+                            if (event.key === "Enter" && !event.shiftKey) {
+                                event.preventDefault();
+                                void send();
+                            }
+                        } }), _jsx("button", { type: "button", className: `${BTN} shrink-0 disabled:opacity-40`, disabled: busy || input.trim().length === 0, onClick: () => void send(), children: "Send" })] })] }));
+}
+function TranscriptRow({ entry, patches, onUndo, }) {
+    if (entry.kind === "user") {
+        return (_jsx("div", { className: "rounded-lg bg-cyan-500/10 px-2.5 py-1.5 text-[11px] text-cyan-50 ring-1 ring-inset ring-cyan-400/20", children: entry.content }));
+    }
+    if (entry.kind === "assistant") {
+        return (_jsx("div", { className: "rounded-lg bg-white/[0.04] px-2.5 py-1.5 text-[11px] whitespace-pre-wrap text-neutral-200 ring-1 ring-inset ring-white/[0.06]", children: entry.content }));
+    }
+    if (entry.kind === "error") {
+        return (_jsx("div", { className: "rounded-lg bg-rose-500/10 px-2.5 py-1.5 text-[11px] text-rose-100 ring-1 ring-inset ring-rose-400/25", children: entry.content }));
+    }
+    if (entry.kind === "tool") {
+        const tone = entry.result.ok
+            ? entry.result.mutated
+                ? "text-emerald-200"
+                : "text-neutral-400"
+            : "text-rose-200";
+        return (_jsxs("div", { className: `font-mono text-[10px] ${tone}`, children: ["\u21B3 ", entry.result.patchSummary, !entry.result.ok && entry.result.error !== undefined ? ` — ${entry.result.error}` : ""] }));
+    }
+    const patch = patches.find((p) => p.id === entry.patch.id) ?? entry.patch;
+    return (_jsxs("div", { className: "flex items-center gap-1 rounded-md border border-violet-400/20 bg-violet-500/[0.08] px-2 py-1 text-[10px]", children: [_jsxs("span", { className: `min-w-0 flex-1 truncate font-mono ${patch.undone ? "text-neutral-600 line-through" : "text-violet-100"}`, children: ["patch \u00B7 ", patch.summary] }), !patch.undone ? (_jsx("button", { type: "button", className: `${BTN} px-1.5 py-0.5 text-[10px]`, onClick: () => onUndo(patch.id), children: "Undo" })) : (_jsx("span", { className: "text-neutral-600", children: "undone" }))] }));
+}
+/** Re-export for hosts that want a default endpoint without the panel. */
+export { createDefaultAgentEndpoint };

package/dist/agent/context.d.ts

@@ -0,0 +1,27 @@
+import type { EditorHostApi, EditorRunMode } from "../session.js";
+/** Compact editor state injected into every agent turn so the model sees selection/mode/camera. */
+export interface AgentEditorContext {
+    gameId: string;
+    mode: EditorRunMode;
+    selection: string[];
+    focus: {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    summary: {
+        markers: number;
+        volumes: number;
+        paths: number;
+        annotations: number;
+    };
+}
+/**
+ * Packs the live host's selection, mode, focus, and document counts for agent prompts.
+ * Injected into every embedded-panel turn so the agent shares the human's current view.
+ */
+export declare function packAgentContext(api: EditorHostApi): AgentEditorContext;
+/** @internal Stable, prompt-friendly serialization of {@link AgentEditorContext}. */
+export declare function formatAgentContext(context: AgentEditorContext): string;

package/dist/agent/context.js

@@ -0,0 +1,39 @@
+import { summarizeEditorSession } from "@jgengine/core/editor/index";
+/**
+ * Packs the live host's selection, mode, focus, and document counts for agent prompts.
+ * Injected into every embedded-panel turn so the agent shares the human's current view.
+ */
+export function packAgentContext(api) {
+    const session = api.getSession();
+    const state = session.getState();
+    const summary = summarizeEditorSession(state);
+    return {
+        gameId: api.gameId,
+        mode: api.getMode(),
+        selection: [...state.selection],
+        focus: api.getFocusTarget(),
+        canUndo: session.canUndo(),
+        canRedo: session.canRedo(),
+        summary: {
+            markers: summary.markers,
+            volumes: summary.volumes,
+            paths: summary.paths,
+            annotations: summary.annotations,
+        },
+    };
+}
+/** @internal Stable, prompt-friendly serialization of {@link AgentEditorContext}. */
+export function formatAgentContext(context) {
+    const focus = context.focus === null
+        ? "none"
+        : `(${context.focus.x.toFixed(1)}, ${context.focus.y.toFixed(1)}, ${context.focus.z.toFixed(1)})`;
+    const selection = context.selection.length === 0 ? "(none)" : context.selection.join(", ");
+    return [
+        `gameId=${context.gameId}`,
+        `mode=${context.mode}`,
+        `selection=[${selection}]`,
+        `focus=${focus}`,
+        `counts=markers:${context.summary.markers} volumes:${context.summary.volumes} paths:${context.summary.paths} notes:${context.summary.annotations}`,
+        `history=undo:${context.canUndo ? "yes" : "no"} redo:${context.canRedo ? "yes" : "no"}`,
+    ].join("\n");
+}

package/dist/agent/endpoint.d.ts

@@ -0,0 +1,68 @@
+import type { EditorMcpTool } from "../mcp/tools.js";
+import type { AgentEditorContext } from "./context.js";
+import type { AgentToolCall } from "./toolBridge.js";
+/** One message in an agent chat transcript (user, assistant, or tool result). */
+export type AgentChatRole = "user" | "assistant" | "tool" | "system";
+/** One turn message exchanged with a pluggable agent endpoint (user, assistant, tool, or system). */
+export interface AgentChatMessage {
+    role: AgentChatRole;
+    content: string;
+    /** Present on tool-result messages. */
+    toolCallId?: string;
+    name?: string;
+}
+/** Payload sent to a pluggable agent backend for one model turn. */
+export interface AgentChatRequest {
+    messages: readonly AgentChatMessage[];
+    context: AgentEditorContext;
+    tools: readonly EditorMcpTool[];
+}
+/** Model reply: optional prose plus zero or more tool calls to run via editor RPC. */
+export interface AgentChatResponse {
+    message?: string;
+    toolCalls?: AgentToolCall[];
+}
+/** Pluggable agent backend — HTTP, Claude SDK adapter, or a local rule engine. */
+export interface AgentEndpoint {
+    /** Stable id for UI status (e.g. "http", "local"). */
+    id: string;
+    chat(request: AgentChatRequest): Promise<AgentChatResponse>;
+}
+/** Env var name for the remote agent HTTP URL (`JGENGINE_EDITOR_AGENT_URL`). */
+export declare const EDITOR_AGENT_URL_ENV = "JGENGINE_EDITOR_AGENT_URL";
+/** Env var name for the optional Bearer token (`JGENGINE_EDITOR_AGENT_KEY`). */
+export declare const EDITOR_AGENT_KEY_ENV = "JGENGINE_EDITOR_AGENT_KEY";
+/** Fallback API-key env when `JGENGINE_EDITOR_AGENT_KEY` is unset (`ANTHROPIC_API_KEY`). */
+export declare const EDITOR_AGENT_KEY_FALLBACK_ENV = "ANTHROPIC_API_KEY";
+/** Resolved remote agent settings: optional URL and optional Bearer API key. */
+export interface AgentEndpointConfig {
+    url?: string;
+    apiKey?: string;
+}
+/**
+ * Reads agent endpoint config from an env map.
+ * Prefer `JGENGINE_EDITOR_AGENT_URL` + `JGENGINE_EDITOR_AGENT_KEY` (falls back to `ANTHROPIC_API_KEY`).
+ * Empty URL → local offline agent; set the URL for a remote model/tool-call backend.
+ */
+export declare function resolveAgentEndpointConfig(env?: Record<string, string | undefined>): AgentEndpointConfig;
+/**
+ * HTTP POST agent endpoint: `{ messages, context, tools }` → `{ message?, toolCalls? }`.
+ * Bearer auth from `apiKey` when provided (`JGENGINE_EDITOR_AGENT_KEY` / `ANTHROPIC_API_KEY`).
+ */
+export declare function createHttpAgentEndpoint(config: {
+    url: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}): AgentEndpoint;
+/**
+ * Offline rule-based agent for demos and tests when no remote URL is configured.
+ * Understands slash-style commands that map onto editor RPC verbs.
+ * @internal
+ */
+export declare function createLocalAgentEndpoint(): AgentEndpoint;
+/** @internal Parses a local agent command into message + optional tool calls. */
+export declare function interpretLocalCommand(text: string, context: AgentEditorContext): AgentChatResponse;
+/**
+ * Picks HTTP endpoint when `JGENGINE_EDITOR_AGENT_URL` (or config.url) is set, otherwise the offline local agent.
+ */
+export declare function createDefaultAgentEndpoint(config?: AgentEndpointConfig): AgentEndpoint;

package/dist/agent/endpoint.js

@@ -0,0 +1,186 @@
+/** Env var name for the remote agent HTTP URL (`JGENGINE_EDITOR_AGENT_URL`). */
+export const EDITOR_AGENT_URL_ENV = "JGENGINE_EDITOR_AGENT_URL";
+/** Env var name for the optional Bearer token (`JGENGINE_EDITOR_AGENT_KEY`). */
+export const EDITOR_AGENT_KEY_ENV = "JGENGINE_EDITOR_AGENT_KEY";
+/** Fallback API-key env when `JGENGINE_EDITOR_AGENT_KEY` is unset (`ANTHROPIC_API_KEY`). */
+export const EDITOR_AGENT_KEY_FALLBACK_ENV = "ANTHROPIC_API_KEY";
+function readProcessEnv() {
+    const root = globalThis;
+    return root.process?.env ?? {};
+}
+/**
+ * Reads agent endpoint config from an env map.
+ * Prefer `JGENGINE_EDITOR_AGENT_URL` + `JGENGINE_EDITOR_AGENT_KEY` (falls back to `ANTHROPIC_API_KEY`).
+ * Empty URL → local offline agent; set the URL for a remote model/tool-call backend.
+ */
+export function resolveAgentEndpointConfig(env = readProcessEnv()) {
+    const url = env[EDITOR_AGENT_URL_ENV]?.trim() || undefined;
+    const apiKey = env[EDITOR_AGENT_KEY_ENV]?.trim() || env[EDITOR_AGENT_KEY_FALLBACK_ENV]?.trim() || undefined;
+    return { url, apiKey };
+}
+/**
+ * HTTP POST agent endpoint: `{ messages, context, tools }` → `{ message?, toolCalls? }`.
+ * Bearer auth from `apiKey` when provided (`JGENGINE_EDITOR_AGENT_KEY` / `ANTHROPIC_API_KEY`).
+ */
+export function createHttpAgentEndpoint(config) {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    return {
+        id: "http",
+        async chat(request) {
+            const headers = { "content-type": "application/json" };
+            if (config.apiKey !== undefined && config.apiKey.length > 0) {
+                headers.authorization = `Bearer ${config.apiKey}`;
+            }
+            const response = await fetchImpl(config.url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => "");
+                throw new Error(`agent endpoint HTTP ${response.status}${body ? `: ${body.slice(0, 200)}` : ""}`);
+            }
+            const raw = (await response.json());
+            return normalizeChatResponse(raw);
+        },
+    };
+}
+function normalizeChatResponse(raw) {
+    const toolCalls = Array.isArray(raw.toolCalls)
+        ? raw.toolCalls
+            .filter((call) => call !== null && typeof call === "object")
+            .map((call, index) => {
+            const record = call;
+            const name = typeof record.name === "string" ? record.name : "";
+            const id = typeof record.id === "string" && record.id.length > 0 ? record.id : `call_${index}`;
+            const args = record.arguments !== null && typeof record.arguments === "object" && !Array.isArray(record.arguments)
+                ? record.arguments
+                : {};
+            return { id, name, arguments: args };
+        })
+            .filter((call) => call.name.length > 0)
+        : undefined;
+    return {
+        ...(typeof raw.message === "string" ? { message: raw.message } : {}),
+        ...(toolCalls !== undefined && toolCalls.length > 0 ? { toolCalls } : {}),
+    };
+}
+/**
+ * Offline rule-based agent for demos and tests when no remote URL is configured.
+ * Understands slash-style commands that map onto editor RPC verbs.
+ * @internal
+ */
+export function createLocalAgentEndpoint() {
+    return {
+        id: "local",
+        async chat(request) {
+            const lastUser = [...request.messages].reverse().find((m) => m.role === "user");
+            const text = lastUser?.content.trim() ?? "";
+            if (text.length === 0) {
+                return { message: "Send a command (e.g. /status, /select id, /undo, or free text)." };
+            }
+            return interpretLocalCommand(text, request.context);
+        },
+    };
+}
+/** @internal Parses a local agent command into message + optional tool calls. */
+export function interpretLocalCommand(text, context) {
+    const trimmed = text.trim();
+    const lower = trimmed.toLowerCase();
+    if (lower === "/help" || lower === "help") {
+        return {
+            message: [
+                "Local agent commands (tool calls → editor RPC, same undo as the GUI):",
+                "/status  /summary  /selection  /frame  /undo  /redo",
+                "/select <id…>  /clear",
+                "/goto <id>  /move <id> <x> <y> <z>",
+                "Or configure JGENGINE_EDITOR_AGENT_URL for a remote model endpoint.",
+            ].join("\n"),
+        };
+    }
+    if (lower === "/status" || lower === "status") {
+        return {
+            message: `mode=${context.mode} selection=${context.selection.join(",") || "(none)"}`,
+            toolCalls: [{ id: "local_status", name: "editor_status", arguments: {} }],
+        };
+    }
+    if (lower === "/summary" || lower === "summary") {
+        return {
+            message: "Pulling scene summary…",
+            toolCalls: [{ id: "local_summary", name: "scene_summary", arguments: {} }],
+        };
+    }
+    if (lower === "/selection" || lower === "selection") {
+        return {
+            message: context.selection.length === 0 ? "Nothing selected." : `Selected: ${context.selection.join(", ")}`,
+            toolCalls: [{ id: "local_sel", name: "list_selection", arguments: {} }],
+        };
+    }
+    if (lower === "/frame" || lower === "frame") {
+        return {
+            message: "Framing scene…",
+            toolCalls: [{ id: "local_frame", name: "camera_frame", arguments: {} }],
+        };
+    }
+    if (lower === "/undo" || lower === "undo") {
+        return {
+            message: context.canUndo ? "Undoing last edit…" : "Nothing to undo.",
+            toolCalls: context.canUndo ? [{ id: "local_undo", name: "undo", arguments: {} }] : undefined,
+        };
+    }
+    if (lower === "/redo" || lower === "redo") {
+        return {
+            message: context.canRedo ? "Redoing…" : "Nothing to redo.",
+            toolCalls: context.canRedo ? [{ id: "local_redo", name: "redo", arguments: {} }] : undefined,
+        };
+    }
+    if (lower === "/clear" || lower === "clear selection") {
+        return {
+            message: "Clearing selection…",
+            toolCalls: [{ id: "local_clear", name: "clear_selection", arguments: {} }],
+        };
+    }
+    const selectMatch = trimmed.match(/^\/?select\s+(.+)$/i);
+    if (selectMatch !== null) {
+        const ids = selectMatch[1].trim().split(/[\s,]+/).filter((id) => id.length > 0);
+        return {
+            message: `Selecting ${ids.join(", ")}…`,
+            toolCalls: [{ id: "local_select", name: "select", arguments: { ids } }],
+        };
+    }
+    const gotoMatch = trimmed.match(/^\/?goto\s+(\S+)$/i);
+    if (gotoMatch !== null) {
+        const id = gotoMatch[1];
+        return {
+            message: `Focusing ${id}…`,
+            toolCalls: [{ id: "local_goto", name: "camera_goto", arguments: { id } }],
+        };
+    }
+    const moveMatch = trimmed.match(/^\/?move\s+(\S+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s*$/i);
+    if (moveMatch !== null) {
+        const id = moveMatch[1];
+        const x = Number(moveMatch[2]);
+        const y = Number(moveMatch[3]);
+        const z = Number(moveMatch[4]);
+        return {
+            message: `Moving ${id} → (${x}, ${y}, ${z})…`,
+            toolCalls: [{ id: "local_move", name: "set_transform", arguments: { id, x, y, z } }],
+        };
+    }
+    return {
+        message: [
+            `No local handler for “${trimmed.slice(0, 80)}”.`,
+            "Try /help, or set JGENGINE_EDITOR_AGENT_URL (+ optional JGENGINE_EDITOR_AGENT_KEY) for a remote agent.",
+            `Context: mode=${context.mode}, selection=${context.selection.join(",") || "(none)"}.`,
+        ].join("\n"),
+    };
+}
+/**
+ * Picks HTTP endpoint when `JGENGINE_EDITOR_AGENT_URL` (or config.url) is set, otherwise the offline local agent.
+ */
+export function createDefaultAgentEndpoint(config = resolveAgentEndpointConfig()) {
+    if (config.url !== undefined && config.url.length > 0) {
+        return createHttpAgentEndpoint({ url: config.url, apiKey: config.apiKey });
+    }
+    return createLocalAgentEndpoint();
+}

package/dist/agent/toolBridge.d.ts

@@ -0,0 +1,35 @@
+import type { EditorBridgeRequest, EditorHostApi } from "../session.js";
+/** One tool call from an agent turn — name maps 1:1 onto an editor RPC method. */
+export interface AgentToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** Result of routing one tool call through the editor host. */
+export interface AgentToolResult {
+    id: string;
+    name: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+    /** True when the document JSON changed — lands as one undo step the human can reverse. */
+    mutated: boolean;
+    /** Short human-readable summary for the patch transcript. */
+    patchSummary: string;
+}
+/** @internal Builds an editor RPC request from a tool name + args (tool name ≡ method). */
+export declare function toolCallToRequest(call: AgentToolCall): {
+    ok: true;
+    request: EditorBridgeRequest;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Routes one agent tool call through the same editor RPC surface humans use.
+ * Mutating calls share the session undo stack — no parallel history.
+ * Tool name maps 1:1 onto `EditorBridgeRequest.method` (same verbs as MCP/CLI).
+ */
+export declare function routeToolCall(api: EditorHostApi, call: AgentToolCall): AgentToolResult;
+/** @internal Routes every tool call in order; returns one result per call. */
+export declare function routeToolCalls(api: EditorHostApi, calls: readonly AgentToolCall[]): AgentToolResult[];

package/dist/agent/toolBridge.js

@@ -0,0 +1,93 @@
+import { decodeEditorBridgeRequest } from "../mcp/rpcRequest.js";
+/** Methods that never write the document (no undo step). */
+const READ_ONLY_METHODS = new Set([
+    "editor_status",
+    "list_layers",
+    "list_selection",
+    "get_marker",
+    "get_volume",
+    "camera_goto",
+    "camera_frame",
+    "scene_summary",
+    "export_document",
+    "list_assets",
+    "perf_report",
+    "terrain_summary",
+    "terrain_materials",
+    "terrain_layers",
+    "scatter_summary",
+    "hierarchy",
+    "list_prefabs",
+    "list_collections",
+]);
+/** @internal Builds an editor RPC request from a tool name + args (tool name ≡ method). */
+export function toolCallToRequest(call) {
+    const payload = { method: call.name, ...call.arguments };
+    const decoded = decodeEditorBridgeRequest(payload);
+    if (!decoded.ok) {
+        const detail = decoded.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
+        return { ok: false, error: detail };
+    }
+    return { ok: true, request: decoded.request };
+}
+function summarizeCall(name, args, response, mutated) {
+    if (!response.ok)
+        return `${name} failed: ${response.error ?? "unknown error"}`;
+    if (mutated) {
+        const id = typeof args.id === "string" ? args.id : undefined;
+        const ids = Array.isArray(args.ids) ? args.ids.join(",") : undefined;
+        const target = id ?? ids;
+        return target !== undefined && target.length > 0 ? `${name} · ${target}` : name;
+    }
+    return `${name} (read)`;
+}
+/**
+ * Routes one agent tool call through the same editor RPC surface humans use.
+ * Mutating calls share the session undo stack — no parallel history.
+ * Tool name maps 1:1 onto `EditorBridgeRequest.method` (same verbs as MCP/CLI).
+ */
+export function routeToolCall(api, call) {
+    const built = toolCallToRequest(call);
+    if (!built.ok) {
+        return {
+            id: call.id,
+            name: call.name,
+            ok: false,
+            error: built.error,
+            mutated: false,
+            patchSummary: `${call.name} rejected: ${built.error}`,
+        };
+    }
+    const session = api.getSession();
+    const before = session.exportJson(false);
+    let response;
+    try {
+        response = api.handle(built.request);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            id: call.id,
+            name: call.name,
+            ok: false,
+            error: message,
+            mutated: false,
+            patchSummary: `${call.name} threw: ${message}`,
+        };
+    }
+    const after = session.exportJson(false);
+    const mutated = !READ_ONLY_METHODS.has(call.name) && before !== after && response.ok === true;
+    return {
+        id: call.id,
+        name: call.name,
+        ok: response.ok,
+        result: response.result,
+        error: response.error,
+        mutated,
+        patchSummary: summarizeCall(call.name, call.arguments, response, mutated),
+    };
+}
+/** @internal Routes every tool call in order; returns one result per call. */
+export function routeToolCalls(api, calls) {
+    return calls.map((call) => routeToolCall(api, call));
+}