Skip to content

Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.

Live mode: an AI tool drives the open window (sculptforge-cli --mcp --attach)

islandmed01f65309c7b0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bfcf47c5..a3c527ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,15 @@ All notable changes to SculptForge are listed here. The format follows
## [Unreleased]
+### Added
+- **Live mode: an AI tool sculpts in the open window while you watch.** Turn on **Edit > Preferences > AI > Let AI
+ tools control this window** (off by default) and connect Claude Code or any MCP client with
+ `sculptforge-cli --mcp --attach`. You approve each connection (a 6-digit code), an **AI connected** badge has
+ Disconnect, every step lands in Undo labelled **AI:**, and files outside the project, overwrites, scripts and the
+ network ask you first. The AI can see its work (`viewport_image`, `view_turntable`, `view_set`), draw strokes in
+ screen space (`stroke_screen`), block out forms from Forge Spheres in one call (`blockout`) and check proportions
+ (`measure`, `scene_overview`). Local only: a socket / pipe just your user can open, no network port.
+
## [0.11.2] - 2026-11-05
### Fixed
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0608ce66..83b08de2 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -138,7 +138,7 @@ add_library(sculptforge_core STATIC
src/core/QRemesh2Field.cpp
src/core/QRemesh2Param.cpp
src/core/QuadQuality.cpp
- src/core/ForgeSpheres.cpp
+ src/core/ForgeSpheres.cpp src/core/AgentTools.cpp
src/core/Projection.cpp
src/core/RetopoCommands.cpp
third_party/xatlas/xatlas.cpp
@@ -312,9 +312,12 @@ set_source_files_properties(third_party/qrcodegen/qrcodegen.cpp ${CMAKE_CURRENT_
# --- Headless command-line tool (pipelines, build farms, AI agents) ---
# The MCP server (src/cli/McpServer.cpp) is a library of its own: the tool and the tests link it, nobody compiles it twice.
-add_library(sculptforge_mcp STATIC src/cli/McpServer.cpp)
+add_library(sculptforge_mcp STATIC src/cli/McpServer.cpp src/cli/McpTools.cpp src/cli/McpAttach.cpp src/link/AiLink.cpp src/link/AiLinkSession.cpp)
target_compile_definitions(sculptforge_mcp PRIVATE SCULPTFORGE_VERSION="${PROJECT_VERSION}")
target_link_libraries(sculptforge_mcp PUBLIC sculptforge_core sculptforge_ai)
+if(WIN32)
+ target_link_libraries(sculptforge_mcp PRIVATE advapi32) # live mode's pipe ACL (src/link/AiLink.cpp)
+endif()
add_executable(sculptforge-cli src/cli/main.cpp)
target_compile_definitions(sculptforge-cli PRIVATE SCULPTFORGE_VERSION="${PROJECT_VERSION}")
target_link_libraries(sculptforge-cli PRIVATE sculptforge_core sculptforge_ai sculptforge_mcp)
@@ -427,6 +430,7 @@ if(SCULPTFORGE_BUILD_APP)
src/app/PanelSupport.cpp
src/app/QuickTour.cpp
src/app/PanelAi.cpp
+ src/app/PanelAiLink.cpp
src/app/PanelSupportCard.cpp
src/app/PanelIntegrations.cpp
src/app/WhatsNewPopup.cpp
@@ -447,7 +451,7 @@ if(SCULPTFORGE_BUILD_APP)
src/render/MicroRenderer.cpp
)
target_link_libraries(sculptforge PRIVATE sculptforge_core sculptforge_ai sculptforge_phone sculptforge_appshared
- sculptforge_actions imgui SDL3::SDL3)
+ sculptforge_mcp sculptforge_actions imgui SDL3::SDL3)
target_include_directories(sculptforge PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/third_party/lucide)
target_compile_definitions(sculptforge PRIVATE SCULPTFORGE_VERSION="${PROJECT_VERSION}"
SCULPTFORGE_PRERELEASE="${SCULPTFORGE_PRERELEASE}"
diff --git a/docs/guide/scripting.md b/docs/guide/scripting.md
index 8d94d33d..f2e07694 100644
--- a/docs/guide/scripting.md
+++ b/docs/guide/scripting.md
@@ -271,6 +271,38 @@ are on your machine. The agent works headless; to see the result, open the expor
`sculptforge-cli --schema` prints the same tool definitions as JSON, for wiring SculptForge into your own
agent.
+### Live mode: an AI tool sculpts in the open window
+
+Turn on **Edit > Preferences > AI > Let AI tools control this window** (off by default, and gone while AI features
+are off), then add the attach server to your AI tool:
+
+```sh
+claude mcp add sculptforge-live -- /path/to/sculptforge-cli --mcp --attach
+```
+
+Ask it to connect ("connect to SculptForge and block out a dragon head"). SculptForge shows **Let an AI tool control
+this window?** with a 6-digit code: click **Approve**, or read the code to the AI tool. The approval lasts until it
+disconnects. While it works:
+
+- an **AI connected** badge sits at the bottom right of the canvas, with **Disconnect** (also in the command palette:
+ *Disconnect AI tool*). Turning the switch or AI features off disconnects it too;
+- every step it takes is in the undo history, labelled **AI:**, so you can step back through its work;
+- it asks first (**Allow this AI step?**) before reading or writing files outside the project folder and the files
+ you picked, overwriting a file, saving over the project, deleting library files, running a macro or script, or
+ anything that uses the network (Generate 3D, AI Brush, the brush gallery). Deny and it is told not to retry.
+ Installing or switching packs and the AI switch itself are never offered;
+- it can see: `viewport_image` returns the viewport as you see it, `view_turntable` the model from 4 to 8 sides in one
+ picture, `view_set` turns and frames your camera, and `stroke_screen` draws a brush stroke in screen space. With
+ `blockout` (a Forge Sphere armature in one call), `measure` and `scene_overview` it can look, think and correct.
+ What it sees goes to that tool's AI service, as anything you show it does.
+
+The recipes your AI tool lists as prompts (creature head, stylised bust, game-ready, rock variations, teach me) work
+in live mode too.
+
+How it is kept safe: the connection is a Unix socket (owner-only, in your runtime folder) or, on Windows, a named
+pipe only your user account can open; there is no network port. Only one AI tool can be connected at a time,
+requests are rate limited, and what the tool sends is data: tool names and values, never code to run.
+
## See also
- [The interface](interface.md): the command palette and Ctrl-hover help
diff --git a/src/ai/BrushAssistant.cpp b/src/ai/BrushAssistant.cpp
index a4a9d911..b088460b 100644
--- a/src/ai/BrushAssistant.cpp
+++ b/src/ai/BrushAssistant.cpp
@@ -146,6 +146,7 @@ Json AiSettings::toJson() const {
j.set("comfyImageWorkflow", comfyImageWorkflow);
j.set("comfyTextWorkflow", comfyTextWorkflow);
j.set("enabled", enabled);
+ j.set("liveControl", liveControl);
return j;
}
@@ -185,6 +186,7 @@ AiSettings AiSettings::fromJson(const Json& j) {
s.comfyImageWorkflow = j["comfyImageWorkflow"].asString();
s.comfyTextWorkflow = j["comfyTextWorkflow"].asString();
s.enabled = j["enabled"].asBool(true);
+ s.liveControl = j["liveControl"].asBool(false);
return s;
}
diff --git a/src/ai/BrushAssistant.h b/src/ai/BrushAssistant.h
index 67e4999d..b501cdb2 100644
--- a/src/ai/BrushAssistant.h
+++ b/src/ai/BrushAssistant.h
@@ -18,6 +18,8 @@ namespace sf::ai {
struct AiSettings {
// Preferences > AI > Enable AI features (ai/AiPolicy.h: SF_AI=off wins over it).
bool enabled = true;
+ // Preferences > AI > Let AI tools control this window (live mode, link/AiLink.h): off unless the user turns it on.
+ bool liveControl = false;
// Free: Pollinations' anonymous OpenAI-compatible endpoint (open models, no
// key), falling back to a local Ollama if it is running.
enum class Provider { Free, Anthropic, OpenAICompatible };
diff --git a/src/app/App.cpp b/src/app/App.cpp
index f6b8af96..c1df70ab 100644
--- a/src/app/App.cpp
+++ b/src/app/App.cpp
@@ -461,6 +461,7 @@ int App::runUiTest(int w, int h, int fps) {
pollBlender(); // (demo recordings leave the user's Blender bridge alone)
pollMaya(); // (tests and recordings never read the user's Maya folder: maya.json isn't loaded)
pollPhone();
+ pollAiLink(); // live mode (PanelAiLink.cpp)
pollAutoUv();
pollUvEditor();
pollBake();
@@ -1090,6 +1091,7 @@ int App::run() {
pollBlender();
pollMaya();
pollPhone();
+ pollAiLink(); // live mode (PanelAiLink.cpp): an AI tool's next step
pollAutoUv();
pollUvEditor();
pollBake();
@@ -2590,6 +2592,7 @@ void SDLCALL onFileChosen(void* userdata, const char* const* files, int) {
} // namespace
void App::queueFile(FileAction action, std::string path) {
+ aiLinkPicked(path); // the user chose it: a connected AI tool may use it without asking (PanelAiLink.cpp)
if (action != FileAction::OpenObj && action != FileAction::LoadBrush && action != FileAction::OpenImage &&
action != FileAction::AppendPart && action != FileAction::ComfyWorkflow && action != FileAction::InsertMesh &&
!path.empty() &&
@@ -2934,6 +2937,7 @@ void App::drawUi() {
guide_.draw(*this); // Help > User Guide
drawPacksUi(); // pack review, New Pack, macro confirmation and editor (PanelPacks.cpp)
drawMemoryConfirm(); // "Not enough free memory" before a big mesh (MemoryConfirm.cpp)
+ drawAiLink(); // live mode: Approve / Allow dialogs, the "AI connected" badge (PanelAiLink.cpp)
drawHelpConsoleUi(); // console, command palette, Controls (F1), Ctrl-hover help: last, on top
drawWhatsNew(); // What's New after an update or from the Help menu (WhatsNewPopup.cpp)
drawSupportCard(); // the support card at launch, over everything (PanelSupportCard.cpp)
diff --git a/src/app/App.h b/src/app/App.h
index 68a2010b..0fa55ed6 100644
--- a/src/app/App.h
+++ b/src/app/App.h
@@ -23,6 +23,7 @@
#include "core/BrushSettings.h"
#include "core/Commands.h"
#include "core/Image.h"
+#include "link/AiLinkSession.h"
#include "core/Macro.h"
#include "core/Pack.h"
#include "core/Document.h"
@@ -540,6 +541,30 @@ private:
void setAiFeatures(bool on);
void registerAiActions(); // ui.brush_lab, ui.generate3d: only while AI is on
void drawAiPrefs(); // the Preferences > AI section and the first-run question
+ // Live mode (PanelAiLink.cpp, link/AiLink.h): Preferences > AI > Let AI tools control this window. An AI tool
+ // (sculptforge-cli --mcp --attach) connects over a local socket / pipe only this user can open, is approved in
+ // a dialog (a one-time code), shows an "AI connected" badge with Disconnect while it works, and asks first
+ // before files outside the project, overwrites, scripts or the network. Off by default; gone while AI is off.
+ struct AiLinkState;
+ struct AiLinkStateDeleter {
+ void operator()(AiLinkState* s) const;
+ };
+ std::unique_ptr<AiLinkState, AiLinkStateDeleter> aiLink_;
+ void setAiLiveControl(bool on);
+ void syncAiLink(); // starts or stops the listener to match the switch (and the AI switch)
+ void pollAiLink(); // every frame: the connection's messages, one at a time
+ void drawAiLink(); // the Approve and Allow dialogs, the "AI connected" badge
+ void drawAiLinkPrefs(); // its switch in Preferences > AI
+ void aiLinkDisconnect(const std::string& why); // the kill switch: closes the connection now
+ void aiLinkPicked(const std::string& path); // a file the user chose: an AI tool may use it without asking
+ int aiLinkStateValue() const; // UI tests: 0 off, 1 listening, 2 waiting for approval, 3 connected, 4 asking
+ std::vector<std::string> aiLinkPickedPaths_; // files the user chose this run (each connection starts with them)
+ void aiLinkExecute(const link::AiLinkCall& call);
+ uint32_t activePartInfoId() const;
+ void labelAiUndo(uint32_t part, size_t undoCountBefore, uint64_t revisionBefore); // "AI: " on the new undo steps
+ bool aiApplyView(const Args& args, std::string& error); // view_set's preset / yaw / elevation / frame / zoom / ortho
+ bool aiRenderView(const Camera& cam, int width, int height, Image& img, std::string& error);
+ Json aiLiveTool(const std::string& name, const Args& args, bool& ok); // viewport_image, view_set, ...
// Brush Lab (AI brush designer)
bool showBrushLab_ = false; // floating; opened from the top shelf's AI Brush or the Brush palette
bool hideUi_ = false;
diff --git a/src/app/I18nSpanish.cpp b/src/app/I18nSpanish.cpp
index b0b7913f..09ff09c7 100644
--- a/src/app/I18nSpanish.cpp
+++ b/src/app/I18nSpanish.cpp
@@ -3518,6 +3518,35 @@ constexpr Entry kSpanish[] = {
{"Stamp rotation", "Rotación del sello"},
{"Vector displacement", "Desplazamiento vectorial"},
{"World Size", "Tamaño en el mundo"},
+ // Live mode (PanelAiLink.cpp)
+ {"\"%s\" on this computer asks to sculpt in this window.", "«%s», en este equipo, pide esculpir en esta ventana."},
+ {"%d steps", "%d pasos"},
+ {"%s wants to run:", "%s quiere ejecutar:"},
+ {"AI connected: ", "IA conectada: "},
+ {"AI connected: %s", "IA conectada: %s"},
+ {"AI connection declined", "Conexión de IA rechazada"},
+ {"AI connection request timed out", "La solicitud de conexión de IA ha caducado"},
+ {"AI step declined", "Paso de IA rechazado"},
+ {"AI tool disconnected", "Herramienta de IA desconectada"},
+ {"AI tools can ask to control this window (Preferences > AI)", "Las herramientas de IA pueden pedir controlar esta ventana (Preferencias > IA)"},
+ {"AI tools can't control this window", "Las herramientas de IA no pueden controlar esta ventana"},
+ {"Allow once", "Permitir una vez"},
+ {"Allow this AI step?", "¿Permitir este paso de IA?"},
+ {"An AI tool on this computer (sculptforge-cli --mcp --attach) can ask to sculpt here while you watch. You approve each connection; it can see the viewport, and what it sees goes to that tool's AI service. Files outside the project, scripts and the network ask you first. Nothing listens on the network.", "Una herramienta de IA de este equipo (sculptforge-cli --mcp --attach) puede pedir esculpir aquí mientras miras. Apruebas cada conexión; puede ver el visor, y lo que ve va al servicio de IA de esa herramienta. Los archivos fuera del proyecto, los scripts y la red te preguntan antes. Nada escucha en la red."},
+ {"Approve", "Aprobar"},
+ {"Click Approve, or tell your AI tool this code. Approval lasts until it disconnects.", "Pulsa Aprobar o dile este código a tu herramienta de IA. La aprobación dura hasta que se desconecte."},
+ {"Code", "Código"},
+ {"Deny", "Denegar"},
+ {"Disconnect AI tool", "Desconectar herramienta de IA"},
+ {"Disconnect", "Desconectar"},
+ {"It can run SculptForge's commands and see the viewport; what it sees goes to that tool's AI service. Every step is in Undo. Files outside the project, scripts and the network ask you first.", "Puede ejecutar los comandos de SculptForge y ver el visor; lo que ve va al servicio de IA de esa herramienta. Cada paso queda en Deshacer. Los archivos fuera del proyecto, los scripts y la red te preguntan antes."},
+ {"Let AI tools control this window", "Permitir que herramientas de IA controlen esta ventana"},
+ {"Let an AI tool control this window?", "¿Permitir que una herramienta de IA controle esta ventana?"},
+ {"Live mode can't start: ", "El modo en vivo no puede iniciarse: "},
+ {"Live mode: an AI tool on this computer (sculptforge-cli --mcp --attach) can ask to sculpt in this window while you watch. You approve each connection; files outside the project, scripts and the network ask first. Nothing listens on the network.", "Modo en vivo: una herramienta de IA de este equipo (sculptforge-cli --mcp --attach) puede pedir esculpir en esta ventana mientras miras. Apruebas cada conexión; los archivos fuera del proyecto, los scripts y la red preguntan antes. Nada escucha en la red."},
+ {"Stop the AI tool controlling this window now (its steps stay in Undo).", "Detener ahora la herramienta de IA que controla esta ventana (sus pasos quedan en Deshacer)."},
+ {"Stop the AI tool now. Its steps stay in Undo.", "Detener ahora la herramienta de IA. Sus pasos quedan en Deshacer."},
+ {"Your AI tool asks: ", "Tu herramienta de IA pide: "},
};
} // namespace
diff --git a/src/app/I18nTraditionalChinese.cpp b/src/app/I18nTraditionalChinese.cpp
index d84fcc38..770171d5 100644
--- a/src/app/I18nTraditionalChinese.cpp
+++ b/src/app/I18nTraditionalChinese.cpp
@@ -3050,6 +3050,35 @@ constexpr Entry kTraditionalChinese[] = {
{"Stamp rotation", "印章旋轉"},
{"Vector displacement", "向量位移"},
{"World Size", "世界尺寸"},
+ // Live mode (PanelAiLink.cpp)
+ {"\"%s\" on this computer asks to sculpt in this window.", "這台電腦上的「%s」要求在此視窗中雕刻。"},
+ {"%d steps", "%d 個步驟"},
+ {"%s wants to run:", "%s 想要執行:"},
+ {"AI connected: ", "AI 已連線:"},
+ {"AI connected: %s", "AI 已連線:%s"},
+ {"AI connection declined", "已拒絕 AI 連線"},
+ {"AI connection request timed out", "AI 連線要求已逾時"},
+ {"AI step declined", "已拒絕 AI 步驟"},
+ {"AI tool disconnected", "AI 工具已中斷連線"},
+ {"AI tools can ask to control this window (Preferences > AI)", "AI 工具可要求控制此視窗(偏好設定 > AI)"},
+ {"AI tools can't control this window", "AI 工具無法控制此視窗"},
+ {"Allow once", "允許一次"},
+ {"Allow this AI step?", "允許此 AI 步驟?"},
+ {"An AI tool on this computer (sculptforge-cli --mcp --attach) can ask to sculpt here while you watch. You approve each connection; it can see the viewport, and what it sees goes to that tool's AI service. Files outside the project, scripts and the network ask you first. Nothing listens on the network.", "這台電腦上的 AI 工具(sculptforge-cli --mcp --attach)可要求在你觀看時於此雕刻。每次連線都需你核准;它能看到視埠,看到的內容會傳送到該工具的 AI 服務。專案外的檔案、指令碼和網路都會先詢問你。不會在網路上監聽。"},
+ {"Approve", "核准"},
+ {"Click Approve, or tell your AI tool this code. Approval lasts until it disconnects.", "按「核准」,或把這組代碼告訴你的 AI 工具。核准在其中斷連線前有效。"},
+ {"Code", "代碼"},
+ {"Deny", "拒絕"},
+ {"Disconnect AI tool", "中斷 AI 工具連線"},
+ {"Disconnect", "中斷連線"},
+ {"It can run SculptForge's commands and see the viewport; what it sees goes to that tool's AI service. Every step is in Undo. Files outside the project, scripts and the network ask you first.", "它可以執行 SculptForge 的指令並看到視埠;看到的內容會傳送到該工具的 AI 服務。每個步驟都在「復原」中。專案外的檔案、指令碼和網路都會先詢問你。"},
+ {"Let AI tools control this window", "允許 AI 工具控制此視窗"},
+ {"Let an AI tool control this window?", "允許 AI 工具控制此視窗?"},
+ {"Live mode can't start: ", "即時模式無法啟動:"},
+ {"Live mode: an AI tool on this computer (sculptforge-cli --mcp --attach) can ask to sculpt in this window while you watch. You approve each connection; files outside the project, scripts and the network ask first. Nothing listens on the network.", "即時模式:這台電腦上的 AI 工具(sculptforge-cli --mcp --attach)可要求在你觀看時於此視窗雕刻。每次連線都需你核准;專案外的檔案、指令碼和網路會先詢問。不會在網路上監聽。"},
+ {"Stop the AI tool controlling this window now (its steps stay in Undo).", "立即停止控制此視窗的 AI 工具(其步驟保留在「復原」中)。"},
+ {"Stop the AI tool now. Its steps stay in Undo.", "立即停止 AI 工具。其步驟保留在「復原」中。"},
+ {"Your AI tool asks: ", "你的 AI 工具要求:"},
};
} // namespace
diff --git a/src/app/PanelAi.cpp b/src/app/PanelAi.cpp
index 38ac5487..6b46c653 100644
--- a/src/app/PanelAi.cpp
+++ b/src/app/PanelAi.cpp
@@ -28,6 +28,27 @@ void App::registerAiActions() {
sw.checked = [] { return ai::aiEnabled(); };
sw.enabled = [] { return !ai::aiPolicyLocked(); };
actions_.add(std::move(sw));
+ if (!actions_.find("prefs.ai_live")) { // live mode (PanelAiLink.cpp): its switch and the kill switch
+ Action live;
+ live.id = "prefs.ai_live";
+ live.label = "Let AI tools control this window";
+ live.palette = "Preferences > AI";
+ live.description = "Live mode: an AI tool on this computer (sculptforge-cli --mcp --attach) can ask to sculpt in this "
+ "window while you watch. You approve each connection; files outside the project, scripts and "
+ "the network ask first. Nothing listens on the network.";
+ live.run = [this] { setAiLiveControl(!aiSettings_.liveControl); };
+ live.checked = [this] { return aiSettings_.liveControl; };
+ live.enabled = [] { return ai::aiEnabled(); };
+ actions_.add(std::move(live));
+ Action cut;
+ cut.id = "ai.live_disconnect";
+ cut.label = "Disconnect AI tool";
+ cut.palette = "Preferences > AI";
+ cut.description = "Stop the AI tool controlling this window now (its steps stay in Undo).";
+ cut.run = [this] { aiLinkDisconnect("AI tool disconnected"); };
+ cut.enabled = [this] { return aiLinkStateValue() >= 2; };
+ actions_.add(std::move(cut));
+ }
commands_.remove("ai_features"); // (called again when AI is turned back on)
commands_.add({"ai_features", "Turn the AI features on or off (Preferences > AI > Enable AI features).",
{{"on", ParamSpec::Type::Bool, "true: on, false: off.", true}},
@@ -79,6 +100,7 @@ void App::setAiFeatures(bool on) {
showBrushLab_ = false;
showImageTo3D_ = false;
}
+ syncAiLink(); // AI off: live mode stops and any AI tool is disconnected
std::string err;
if (!uiConfigDeterministic_ && !aiSettingsPath_.empty() && !aiSettings_.save(aiSettingsPath_, err))
status_ = "AI features " + std::string(on ? "on" : "off") + ", but " + err;
@@ -98,6 +120,9 @@ void App::drawAiPrefs() {
ImGui::TextWrapped("AI Brush and Generate 3D. Off: they are hidden and SculptForge makes no AI network calls.");
ImGui::TextWrapped("%s", ai::kPrivacyLine);
ImGui::PopStyleColor();
+ ImGui::Spacing();
+ drawAiLinkPrefs(); // live mode (PanelAiLink.cpp)
+ ImGui::Spacing();
if (ImGui::SmallButton("AI services & privacy##prefs.ai"))
SDL_OpenURL("https://github.com/islandmed/SculptForge/blob/main/docs/ai-services.md");
}
diff --git a/src/app/PanelAiLink.cpp b/src/app/PanelAiLink.cpp
new file mode 100644
index 00000000..f930d36d
--- /dev/null
+++ b/src/app/PanelAiLink.cpp
@@ -0,0 +1,721 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Live mode: Preferences > AI > Let AI tools control this window (off by default; hidden while AI is off).
+// `sculptforge-cli --mcp --attach` connects through link/AiLink.h (a Unix socket / named pipe only this user can
+// open; no network port). The rules are link/AiLinkSession.h's; here they meet the window:
+// - the Approve dialog, with the one-time code the user can read to the AI tool instead of clicking;
+// - the "AI connected" badge with Disconnect (the kill switch; turning the switch or AI off also cuts it);
+// - the Allow dialog before files outside the project, overwrites, scripts and the network;
+// - every command runs as if typed in the console (App::runCommand), its undo steps labelled "AI: ...";
+// - the live-window tools: viewport_image (what the user sees, as an image), view_set (camera), view_turntable
+// (the model from every side in one image) and stroke_screen (a brush stroke drawn in screen space).
+// A background thread accepts and reads; everything else happens here on the main thread, one message at a time.
+#include "app/App.h"
+
+#include "app/I18n.h"
+#include "app/Theme.h"
+#include "app/Ui.h"
+#include "cli/McpServer.h"
+#include "cli/McpTools.h"
+#include "link/AiLink.h"
+#include "link/AiLinkSession.h"
+
+#include <IconsLucide.h>
+#include <imgui.h>
+
+#include <atomic>
+#include <cmath>
+#include <cstring>
+#include <deque>
+#include <optional>
+#include <sstream>
+#include <mutex>
+#include <thread>
+#include <utility>
+
+namespace sf {
+
+namespace {
+
+constexpr double kApprovalSeconds = 120.0; // an unanswered Approve dialog says no
+
+double seconds() { return double(SDL_GetTicksNS()) * 1e-9; }
+
+Json schemaProp(const char* type, const char* description) {
+ Json p = Json::object();
+ p.set("type", type);
+ p.set("description", description);
+ return p;
+}
+
+Json liveTool(const char* name, const char* description, std::vector<std::pair<const char*, Json>> props) {
+ Json properties = Json::object();
+ for (auto& [k, v] : props) properties.set(k, std::move(v));
+ Json schema = Json::object();
+ schema.set("type", "object");
+ schema.set("properties", std::move(properties));
+ schema.set("required", Json::array());
+ Json t = Json::object();
+ t.set("name", name);
+ t.set("description", description);
+ t.set("inputSchema", std::move(schema));
+ return t;
+}
+
+Json liveTools() {
+ Json tools = Json::array();
+ const auto view = [] {
+ return std::vector<std::pair<const char*, Json>>{
+ {"preset", schemaProp("string", "front, back, left, right, top, bottom or three_quarter (front-right, a little from above).")},
+ {"yaw", schemaProp("number", "Degrees around the vertical axis: 0 = front, 90 = the model's right side, 180 = back.")},
+ {"elevation", schemaProp("number", "Degrees above the model (-89..89): 0 = level, 30 = looking down a little.")},
+ {"frame", schemaProp("string", "Frame the view on: all (every visible Part), active (the active Part) or a Part's name.")},
+ {"zoom", schemaProp("number", "Closer (2 = twice as close) or further (0.5) after framing.")},
+ {"ortho", schemaProp("boolean", "Orthographic (true) or perspective (false).")}};
+ };
+ Json image = viewportImageTool(); // (one schema with the headless server: cli/McpTools.h)
+ image.set("description", "See the model: the viewport exactly as the user sees it (without the interface), as a PNG. "
+ "The view options turn the user's camera too (they stay; with none, the view as it is). "
+ "Look after every step and correct what you see.");
+ tools.push(std::move(image));
+ tools.push(liveTool("view_set", "Turn and frame the camera the user sees (and viewport_image renders).", view()));
+ tools.push(liveTool("view_turntable",
+ "The model from several sides in one image (a grid, labelled by yaw), to check form and "
+ "proportions all around. The user's camera is put back afterwards.",
+ {{"views", schemaProp("number", "4, 6 or 8 views around (default 4: front, right, back, left).")},
+ {"elevation", schemaProp("number", "Degrees above the model (default 10).")},
+ {"size", schemaProp("number", "Each view's side in pixels (192-512, default 320).")}}));
+ tools.push(liveTool(
+ "stroke_screen",
+ "Brush stroke drawn on the screen, as a user drags across the viewport: points in viewport coordinates "
+ "(0,0 = top left, 1,1 = bottom right), projected onto the model (points off the model are skipped). Use "
+ "viewport_image to see where things are. One undo step.",
+ {{"points", schemaProp("string", "\"u,v u,v ...\" in 0..1 viewport coordinates (at least one on the model).")},
+ {"brush", schemaProp("string", "Brush name (Standard, Clay, Clay Buildup, Crease, Inflate, Smooth, Pinch...). Default: the active brush.")},
+ {"radius", schemaProp("number", "Brush radius as a fraction of the viewport's height (default 0.04).")},
+ {"strength", schemaProp("number", "0-1 (default 0.5).")},
+ {"invert", schemaProp("boolean", "Carve instead of build (like holding Alt).")},
+ {"symmetry", schemaProp("string", "Mirror across these world planes, e.g. \"x\" (default none).")}}));
+ return tools;
+}
+
+bool isLiveTool(const std::string& name) {
+ return name == "viewport_image" || name == "view_set" || name == "view_turntable" || name == "stroke_screen";
+}
+
+std::string degrees(float radians) {
+ char buf[16];
+ std::snprintf(buf, sizeof buf, "%.0f", double(glm::degrees(radians)));
+ return buf;
+}
+
+} // namespace
+
+// ---------------------------------------------------------------------------
+// State: the listener thread and what the main thread is doing with the connection
+// ---------------------------------------------------------------------------
+
+struct App::AiLinkState {
+ link::AiLinkListener listener;
+ link::AiLinkConn conn;
+ std::mutex connMutex; // conn: reads (thread) and writes (main thread)
+ std::thread thread;
+ std::atomic<bool> stop{false};
+ std::atomic<bool> connected{false};
+ std::atomic<bool> drop{false}; // the main thread asks the thread to close the connection
+
+ struct Event {
+ enum class Kind { Connected, Line, Closed } kind;
+ std::string line;
+ };
+ std::mutex eventMutex;
+ std::deque<Event> events;
+
+ std::unique_ptr<link::AiLinkSession> session;
+ std::deque<std::string> waiting; // lines that came while a dialog was open
+ double approvalSince = 0.0;
+ bool approving = false;
+ bool focusDialog = false; // a dialog just opened: bring it to the front once
+ struct Pending {
+ link::AiLinkCall call;
+ std::string reason;
+ };
+ std::optional<Pending> confirm;
+ std::string error; // why the listener isn't running
+ int commands = 0; // tool calls run this connection
+
+ void push(Event e) {
+ {
+ std::lock_guard lock(eventMutex);
+ events.push_back(std::move(e));
+ }
+ wakeMainLoop();
+ }
+
+ void send(const std::string& line) {
+ std::lock_guard lock(connMutex);
+ conn.writeLine(line);
+ }
+
+ void run() {
+ while (!stop) {
+ if (!connected) {
+ link::AiLinkConn client;
+ bool refused = false;
+ if (!listener.accept(client, 200, &refused)) continue;
+ std::lock_guard lock(connMutex);
+ conn = std::move(client);
+ connected = true;
+ drop = false;
+ push({Event::Kind::Connected, {}});
+ continue;
+ }
+ // A second client while one is connected: told so and closed.
+ {
+ link::AiLinkConn other;
+ if (listener.accept(other, 0)) other.writeLine(R"({"error":"SculptForge is already connected to an AI tool"})");
+ }
+ std::string line;
+ int got;
+ {
+ std::lock_guard lock(connMutex);
+ got = drop ? -1 : conn.readLine(line, 50);
+ if (got < 0) conn.close();
+ }
+ if (got > 0) push({Event::Kind::Line, std::move(line)});
+ else if (got < 0) {
+ connected = false;
+ push({Event::Kind::Closed, {}});
+ } else {
+ std::this_thread::sleep_for(std::chrono::milliseconds(5)); // (lets the main thread write)
+ }
+ }
+ }
+};
+
+void App::AiLinkStateDeleter::operator()(AiLinkState* s) const {
+ if (!s) return;
+ s->stop = true;
+ if (s->thread.joinable()) s->thread.join();
+ delete s;
+}
+
+// ---------------------------------------------------------------------------
+// The switch
+// ---------------------------------------------------------------------------
+
+void App::setAiLiveControl(bool on) {
+ aiSettings_.liveControl = on;
+ std::string err;
+ if (!uiConfigDeterministic_ && !aiSettingsPath_.empty() && !aiSettings_.save(aiSettingsPath_, err)) status_ = err;
+ syncAiLink();
+ if (!aiLink_ && on && ai::aiEnabled()) return; // (status_ says why)
+ status_ = on && aiLink_ ? tr("AI tools can ask to control this window (Preferences > AI)")
+ : tr("AI tools can't control this window");
+}
+
+void App::syncAiLink() {
+ const bool want = ai::aiEnabled() && aiSettings_.liveControl;
+ if (want == bool(aiLink_)) return;
+ if (!want) {
+ if (aiLink_ && aiLink_->session) consoleEcho("ai_live", {}, {true, "AI tool disconnected"});
+ aiLink_.reset();
+ return;
+ }
+ std::unique_ptr<AiLinkState, AiLinkStateDeleter> s(new AiLinkState);
+ std::string err;
+ const std::string endpoint = link::aiLinkEndpoint(err);
+ if (endpoint.empty() || !s->listener.open(endpoint, err)) {
+ status_ = std::string(tr("Live mode can't start: ")) + err;
+ SDL_Log("Live mode: %s", err.c_str());
+ aiSettings_.liveControl = false;
+ return;
+ }
+ SDL_Log("Live mode: listening on %s", endpoint.c_str());
+ AiLinkState* raw = s.get();
+ s->thread = std::thread([raw] { raw->run(); });
+ aiLink_ = std::move(s);
+}
+
+void App::aiLinkDisconnect(const std::string& why) {
+ if (!aiLink_ || !aiLink_->connected) return;
+ aiLink_->drop = true;
+ {
+ std::lock_guard lock(aiLink_->connMutex);
+ aiLink_->conn.shutdown();
+ }
+ status_ = why;
+}
+
+void App::aiLinkPicked(const std::string& path) {
+ if (aiLink_ && aiLink_->session) aiLink_->session->policy.addPicked(path);
+ aiLinkPickedPaths_.push_back(path);
+}
+
+int App::aiLinkStateValue() const {
+ if (!aiLink_) return 0;
+ if (!aiLink_->session) return 1;
+ if (aiLink_->session->state() == link::AiLinkSession::State::Pairing) return 2;
+ return aiLink_->confirm ? 4 : 3;
+}
+
+void App::drawAiLinkPrefs() {
+ if (!ai::aiEnabled()) return;
+ bool on = aiSettings_.liveControl;
+ if (ImGui::Checkbox(tr("Let AI tools control this window##prefs.ai_live"), &on)) setAiLiveControl(on);
+ ui::HelpAction(*this, "prefs.ai_live");
+ ImGui::PushStyleColor(ImGuiCol_Text, ImGui::GetStyleColorVec4(ImGuiCol_TextDisabled));
+ ImGui::TextWrapped("%s", tr("An AI tool on this computer (sculptforge-cli --mcp --attach) can ask to sculpt here while "
+ "you watch. You approve each connection; it can see the viewport, and what it sees goes "
+ "to that tool's AI service. Files outside the project, scripts and the network ask "
+ "you first. Nothing listens on the network."));
+ ImGui::PopStyleColor();
+ if (aiLink_ && !aiLink_->error.empty()) ImGui::TextColored(theme::danger, "%s", aiLink_->error.c_str());
+}
+
+// ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+
+void App::pollAiLink() {
+ syncAiLink();
+ if (!aiLink_) return;
+ AiLinkState& s = *aiLink_;
+ std::deque<AiLinkState::Event> events;
+ {
+ std::lock_guard lock(s.eventMutex);
+ events.swap(s.events);
+ }
+ for (auto& e : events) {
+ if (e.kind == AiLinkState::Event::Kind::Connected) {
+ s.session = std::make_unique<link::AiLinkSession>(link::makePairingCode());
+ s.session->policy.projectDir = macroProjectDir();
+ for (const std::string& p : aiLinkPickedPaths_) s.session->policy.addPicked(p);
+ s.waiting.clear();
+ s.confirm.reset();
+ s.approving = false;
+ s.commands = 0;
+ } else if (e.kind == AiLinkState::Event::Kind::Closed) {
+ if (s.session && s.session->state() == link::AiLinkSession::State::Paired) {
+ status_ = tr("AI tool disconnected");
+ consoleEcho("ai_live", {}, {true, "AI tool disconnected"});
+ }
+ s.session.reset();
+ s.waiting.clear();
+ s.confirm.reset();
+ s.approving = false;
+ } else if (s.session) {
+ s.waiting.push_back(std::move(e.line));
+ }
+ }
+ if (!s.session) return;
+ if (s.approving && seconds() - s.approvalSince > kApprovalSeconds) {
+ s.send(s.session->deny());
+ s.approving = false;
+ aiLinkDisconnect(tr("AI connection request timed out"));
+ return;
+ }
+ // One message at a time; none while a dialog waits for the user.
+ while (!s.waiting.empty() && !s.confirm && s.session && s.session->state() != link::AiLinkSession::State::Closed) {
+ const bool wasPairing = s.session->state() == link::AiLinkSession::State::Pairing;
+ const std::string line = std::move(s.waiting.front());
+ s.waiting.pop_front();
+ link::AiLinkSession::Step step = s.session->handle(line, seconds());
+ using K = link::AiLinkSession::Step::Kind;
+ if (!step.reply.empty() && step.kind != K::Execute && step.kind != K::ListTools) s.send(step.reply);
+ if (wasPairing && s.session->state() == link::AiLinkSession::State::Paired) { // the right code
+ s.approving = false;
+ status_ = std::string(tr("AI connected: ")) + s.session->client();
+ consoleEcho("ai_live", {}, {true, "AI connected: " + s.session->client()});
+ }
+ switch (step.kind) {
+ case K::None:
+ case K::Reply: break;
+ case K::Close:
+ aiLinkDisconnect(tr("AI tool disconnected"));
+ return;
+ case K::ShowApproval:
+ s.approving = true;
+ s.focusDialog = true;
+ s.approvalSince = seconds();
+ break;
+ case K::ListTools: {
+ Json tools = Json::array();
+ const Json commands = mcpToolList(commands_), live = liveTools();
+ for (const Json& t : commands.items())
+ if (!link::AiLinkPolicy::hidden(t["name"].asString())) tools.push(t);
+ for (const Json& t : live.items()) tools.push(t);
+ s.send(link::AiLinkSession::listReply(step.call.id, std::move(tools)));
+ break;
+ }
+ case K::Execute:
+ case K::Confirm: {
+ const std::string& name = step.call.name;
+ const Command* cmd = commands_.find(name);
+ if (!cmd && !isLiveTool(name)) {
+ s.send(link::AiLinkSession::resultReply(step.call.id, false, "Unknown tool: " + name));
+ break;
+ }
+ s.session->policy.projectDir = macroProjectDir();
+ const link::AiDecision d = s.session->policy.classify(isLiveTool(name) ? nullptr : cmd, name, step.call.args);
+ if (d.verdict == link::AiVerdict::Deny) {
+ s.send(link::AiLinkSession::resultReply(step.call.id, false, d.reason));
+ } else if (d.verdict == link::AiVerdict::Confirm) {
+ s.confirm = AiLinkState::Pending{std::move(step.call), d.reason};
+ s.focusDialog = true;
+ status_ = std::string(tr("Your AI tool asks: ")) + d.reason;
+ } else {
+ aiLinkExecute(step.call);
+ }
+ break;
+ }
+ }
+ }
+}
+
+void App::aiLinkExecute(const link::AiLinkCall& call) {
+ AiLinkState& s = *aiLink_;
+ ++s.commands;
+ if (isLiveTool(call.name)) {
+ bool ok = true;
+ Json content = aiLiveTool(call.name, call.args, ok);
+ s.send(link::AiLinkSession::contentReply(call.id, std::move(content), !ok));
+ return;
+ }
+ // As if typed in the console; the steps it adds to the history say who made them.
+ const uint32_t part = activePartInfoId();
+ const size_t before = doc_.undo.undoCount();
+ const uint64_t revision = doc_.undo.revision();
+ runCommand(call.name, call.args);
+ labelAiUndo(part, before, revision);
+ s.send(link::AiLinkSession::resultReply(call.id, lastCommandOk_, status_));
+}
+
+uint32_t App::activePartInfoId() const { return doc_.activePartInfo().id; }
+
+void App::labelAiUndo(uint32_t part, size_t before, uint64_t revision) {
+ if (doc_.undo.revision() == revision || !doc_.undo.canUndo()) return;
+ // New steps on the same Part: every one of them; on another Part (a new Part made active): its last one.
+ const size_t added = doc_.activePartInfo().id == part && doc_.undo.undoCount() > before ? doc_.undo.undoCount() - before : 1;
+ for (size_t k = 0; k < added; ++k) {
+ UndoRecord* r = k == 0 ? doc_.undo.lastUndo() : nullptr;
+ if (k > 0) r = const_cast<UndoRecord*>(doc_.undo.undoStep(k));
+ if (r && r->label.rfind("AI: ", 0) != 0) r->label = "AI: " + r->label;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// The live-window tools
+// ---------------------------------------------------------------------------
+
+bool App::aiApplyView(const Args& args, std::string& error) {
+ const std::string preset = argString(args, "preset");
+ if (!preset.empty()) {
+ static const struct { const char* name; float yaw, pitch; } kPresets[] = {
+ {"front", 0, 0}, {"back", 180, 0}, {"right", 90, 0}, {"left", -90, 0},
+ {"top", 0, -89}, {"bottom", 0, 89}, {"three_quarter", 35, -15}};
+ bool found = false;
+ for (const auto& p : kPresets)
+ if (preset == p.name) {
+ camera_.yaw = glm::radians(p.yaw);
+ camera_.pitch = glm::radians(p.pitch);
+ camera_.roll = 0.0f;
+ found = true;
+ }
+ if (!found) {
+ error = "preset must be front, back, left, right, top, bottom or three_quarter";
+ return false;
+ }
+ }
+ if (args.contains("yaw")) camera_.yaw = glm::radians(float(argNumber(args, "yaw", 0.0))), camera_.roll = 0.0f;
+ if (args.contains("elevation"))
+ camera_.pitch = -glm::radians(std::clamp(float(argNumber(args, "elevation", 0.0)), -89.0f, 89.0f)), camera_.roll = 0.0f;
+ if (args.contains("ortho")) camera_.ortho = argBool(args, "ortho", false), autoOrtho_ = false;
+ const std::string frame = argString(args, "frame");
+ if (frame == "all") camera_.frame(sceneBounds());
+ else if (frame == "active") camera_.frame(doc_.mesh.bounds());
+ else if (!frame.empty()) {
+ const int i = doc_.findPart(frame);
+ if (i < 0) {
+ error = "No Part \"" + frame + "\" (see scene_overview)";
+ return false;
+ }
+ camera_.frame(doc_.partMesh(i).bounds());
+ }
+ if (args.contains("zoom")) {
+ const float z = float(argNumber(args, "zoom", 1.0));
+ if (!(z > 0.05f && z < 20.0f)) {
+ error = "zoom must be between 0.05 and 20";
+ return false;
+ }
+ camera_.distance /= z;
+ }
+ return true;
+}
+
+bool App::aiRenderView(const Camera& cam, int width, int height, Image& img, std::string& error) {
+ img.width = width;
+ img.height = height;
+ RenderSettings settings = renderSettings_;
+ settings.dimInactive = false;
+ settings.showMask = true; // (the agent sees the mask it painted)
+ settings.resolutionScale = 1.0f;
+ constexpr GLenum kFramebufferBinding = 0x8CA6, kViewport = 0x0BA2;
+ GLint fbo = 0, viewport[4] = {};
+ gl::GetIntegerv(kFramebufferBinding, &fbo);
+ gl::GetIntegerv(kViewport, viewport);
+ const bool ok = renderer_.renderToImage(cam, width, height, settings, img.rgba, error);
+ gl::BindFramebuffer(GL_FRAMEBUFFER, GLuint(fbo));
+ gl::Viewport(viewport[0], viewport[1], viewport[2], viewport[3]);
+ return ok;
+}
+
+Json App::aiLiveTool(const std::string& name, const Args& args, bool& ok) {
+ Json content = Json::array();
+ auto text = [&](const std::string& t) {
+ Json j = Json::object();
+ j.set("type", "text");
+ j.set("text", t);
+ content.push(std::move(j));
+ };
+ auto image = [&](const Image& img) {
+ std::vector<uint8_t> png;
+ if (!img.encodePng(png)) return false;
+ Json j = Json::object();
+ j.set("type", "image");
+ j.set("data", link::base64Encode(png.data(), png.size()));
+ j.set("mimeType", "image/png");
+ content.push(std::move(j));
+ return true;
+ };
+ auto fail = [&](const std::string& e) {
+ ok = false;
+ text(e);
+ return content;
+ };
+ ok = true;
+ std::string err;
+ const auto viewText = [this] {
+ return "Camera: yaw " + degrees(camera_.yaw) + ", elevation " + degrees(-camera_.pitch) +
+ (camera_.ortho ? ", orthographic" : ", perspective") + "; active Part: " + doc_.activePartInfo().name;
+ };
+
+ if (name == "view_set" || name == "viewport_image") {
+ if (!aiApplyView(args, err)) return fail(err);
+ if (name == "view_set") {
+ text(viewText());
+ return content;
+ }
+ const CanvasRect c = canvasRect();
+ const float aspect = c.h > 1.0f ? c.w / c.h : 1.0f;
+ const int longSide = std::clamp(int(argNumber(args, "size", 768)), 256, 1536);
+ const int w = aspect >= 1.0f ? longSide : std::max(1, int(std::lround(longSide * aspect)));
+ const int h = aspect >= 1.0f ? std::max(1, int(std::lround(longSide / aspect))) : longSide;
+ Camera cam = camera_;
+ cam.aspect = float(w) / float(h);
+ Image img;
+ if (!aiRenderView(cam, w, h, img, err) || !image(img)) return fail("Can't render the view: " + err);
+ text(viewText() + " (" + std::to_string(w) + "x" + std::to_string(h) + ")");
+ return content;
+ }
+
+ if (name == "view_turntable") {
+ const int views = int(argNumber(args, "views", 4));
+ if (views != 4 && views != 6 && views != 8) return fail("views must be 4, 6 or 8");
+ const int tile = std::clamp(int(argNumber(args, "size", 320)), 192, 512);
+ const int cols = views / 2, rows = 2;
+ Camera cam = camera_;
+ cam.frame(sceneBounds());
+ cam.aspect = 1.0f;
+ cam.roll = 0.0f;
+ cam.pitch = -glm::radians(std::clamp(float(argNumber(args, "elevation", 10.0)), -89.0f, 89.0f));
+ Image sheet;
+ sheet.width = cols * tile;
+ sheet.height = rows * tile;
+ sheet.rgba.assign(size_t(sheet.width) * sheet.height * 4, 0);
+ std::string yaws;
+ for (int v = 0; v < views; ++v) {
+ cam.yaw = glm::radians(360.0f * float(v) / float(views));
+ Image img;
+ if (!aiRenderView(cam, tile, tile, img, err)) return fail("Can't render the view: " + err);
+ const int ox = (v % cols) * tile, oy = (v / cols) * tile;
+ for (int y = 0; y < tile; ++y)
+ std::memcpy(&sheet.rgba[(size_t(oy + y) * sheet.width + ox) * 4], &img.rgba[size_t(y) * tile * 4], size_t(tile) * 4);
+ yaws += (v ? ", " : "") + degrees(cam.yaw);
+ }
+ if (!image(sheet)) return fail("Can't encode the image");
+ text(std::to_string(views) + " views, left to right then top to bottom, yaw " + yaws + " degrees (0 = front, 90 = "
+ "the model's right side); elevation " + degrees(-cam.pitch) + ". The user's camera didn't move.");
+ return content;
+ }
+
+ if (name == "stroke_screen") {
+ const CanvasRect c = canvasRect();
+ if (c.w < 2.0f || c.h < 2.0f) return fail("The viewport is too small");
+ std::string worldPoints;
+ int hits = 0, misses = 0;
+ float radius = 0.0f;
+ const float radiusFrac = std::clamp(float(argNumber(args, "radius", 0.04)), 0.002f, 0.5f);
+ std::stringstream in(argString(args, "points"));
+ std::string token;
+ while (in >> token) {
+ float u = 0, v = 0;
+ if (std::sscanf(token.c_str(), "%f,%f", &u, &v) != 2 || !std::isfinite(u) || !std::isfinite(v))
+ return fail("points must be \"u,v u,v ...\" in 0..1 (bad: " + token + ")");
+ glm::vec3 origin, dir;
+ camera_.screenRay(u * c.w, v * c.h, c.w, c.h, origin, dir);
+ RayHit hit;
+ if (!doc_.bvh.raycast(doc_.mesh, origin, dir, hit)) {
+ ++misses;
+ continue;
+ }
+ if (radius == 0.0f) radius = camera_.worldPerPixel(hit.position, c.h) * radiusFrac * c.h;
+ char buf[96];
+ std::snprintf(buf, sizeof buf, "%s%g,%g,%g", worldPoints.empty() ? "" : " ", double(hit.position.x),
+ double(hit.position.y), double(hit.position.z));
+ worldPoints += buf;
+ ++hits;
+ if (hits > 2000) return fail("at most 2000 points");
+ }
+ if (hits == 0) return fail("No point is on the active Part (see viewport_image; 0,0 is the top left)");
+ const glm::vec3 f = camera_.forward();
+ char view[96];
+ std::snprintf(view, sizeof view, "%g,%g,%g", double(f.x), double(f.y), double(f.z));
+ Args a{{"points", worldPoints}, {"view", std::string(view)}, {"radius", double(radius)},
+ {"strength", argNumber(args, "strength", 0.5)}, {"invert", argBool(args, "invert", false)}};
+ if (args.contains("brush")) a["brush"] = argString(args, "brush");
+ if (args.contains("symmetry")) a["symmetry"] = argString(args, "symmetry");
+ const uint32_t part = activePartInfoId();
+ const size_t before = doc_.undo.undoCount();
+ const uint64_t revision = doc_.undo.revision();
+ runCommand("stroke", a);
+ labelAiUndo(part, before, revision);
+ ok = lastCommandOk_;
+ text(status_ + (misses ? " (" + std::to_string(misses) + " points were off the model)" : ""));
+ return content;
+ }
+ return fail("Unknown tool: " + name);
+}
+
+// ---------------------------------------------------------------------------
+// Dialogs and the badge
+// ---------------------------------------------------------------------------
+
+void App::drawAiLink() {
+ if (!aiLink_ || !aiLink_->session) return;
+ AiLinkState& s = *aiLink_;
+ const float sc = uiScale_;
+ const ImGuiViewport* vp = ImGui::GetMainViewport();
+ const ImVec2 centre(vp->WorkPos.x + vp->WorkSize.x * 0.5f, vp->WorkPos.y + vp->WorkSize.y * 0.5f);
+ const ImGuiWindowFlags dialog = ImGuiWindowFlags_NoCollapse | ImGuiWindowFlags_NoSavedSettings |
+ ImGuiWindowFlags_AlwaysAutoResize;
+
+ if (s.approving && s.session->state() == link::AiLinkSession::State::Pairing) {
+ ImGui::SetNextWindowPos(centre, ImGuiCond_Appearing, ImVec2(0.5f, 0.5f));
+ if (std::exchange(s.focusDialog, false)) ImGui::SetNextWindowFocus();
+ bool open = true;
+ if (ImGui::Begin(tr("Let an AI tool control this window?###ailinkapprove"), &open, dialog)) {
+ ImGui::PushTextWrapPos(460 * sc);
+ ImGui::TextWrapped(tr("\"%s\" on this computer asks to sculpt in this window."), s.session->client().c_str());
+ ImGui::Spacing();
+ ImGui::TextUnformatted(tr("Code"));
+ const std::string& code = s.session->code();
+ ImGui::PushFont(nullptr);
+ ImGui::SetWindowFontScale(2.2f);
+ ImGui::TextColored(theme::accent, "%s %s", code.substr(0, 3).c_str(), code.substr(3).c_str());
+ ImGui::SetWindowFontScale(1.0f);
+ ImGui::PopFont();
+ ImGui::TextWrapped("%s", tr("Click Approve, or tell your AI tool this code. Approval lasts until it disconnects."));
+ ImGui::Spacing();
+ ImGui::PushStyleColor(ImGuiCol_Text, ImGui::GetStyleColorVec4(ImGuiCol_TextDisabled));
+ ImGui::TextWrapped("%s", tr("It can run SculptForge's commands and see the viewport; what it sees goes to that "
+ "tool's AI service. Every step is in Undo. Files outside the project, scripts "
+ "and the network ask you first."));
+ ImGui::PopStyleColor();
+ ImGui::PopTextWrapPos();
+ ImGui::Spacing();
+ ImGui::PushStyleColor(ImGuiCol_Button, theme::accent);
+ ImGui::PushStyleColor(ImGuiCol_ButtonHovered, theme::accentHover);
+ ImGui::PushStyleColor(ImGuiCol_Text, theme::textOnAccent);
+ const bool approve = ImGui::Button(tr("Approve##ailink"), ImVec2(140 * sc, 0));
+ ImGui::PopStyleColor(3);
+ ImGui::SameLine();
+ if (ImGui::Button(tr("Deny##ailink"), ImVec2(120 * sc, 0)) || ImGui::IsKeyPressed(ImGuiKey_Escape)) open = false;
+ if (approve) {
+ s.send(s.session->approve());
+ s.approving = false;
+ status_ = std::string(tr("AI connected: ")) + s.session->client();
+ consoleEcho("ai_live", {}, {true, "AI connected: " + s.session->client()});
+ }
+ }
+ ImGui::End();
+ if (!open) {
+ s.send(s.session->deny());
+ s.approving = false;
+ aiLinkDisconnect(tr("AI connection declined"));
+ }
+ return;
+ }
+ if (s.session->state() != link::AiLinkSession::State::Paired) return;
+
+ // The badge: bottom right of the canvas (clear of the history strip on top), while connected.
+ const CanvasRect c = canvasRect();
+ ImGui::SetNextWindowPos(ImVec2(c.x + c.w - 12 * sc, c.y + c.h - 12 * sc), ImGuiCond_Always, ImVec2(1.0f, 1.0f));
+ ImGui::SetNextWindowBgAlpha(0.92f);
+ ImGui::PushStyleVar(ImGuiStyleVar_WindowRounding, 8 * sc);
+ ImGui::PushStyleColor(ImGuiCol_Border, theme::accent);
+ if (ImGui::Begin("##ailinkbadge", nullptr,
+ ImGuiWindowFlags_NoDecoration | ImGuiWindowFlags_AlwaysAutoResize | ImGuiWindowFlags_NoSavedSettings |
+ ImGuiWindowFlags_NoFocusOnAppearing | ImGuiWindowFlags_NoNav)) {
+ const float pulse = 0.55f + 0.45f * std::sin(float(seconds()) * 3.0f);
+ ImVec4 dot = theme::accent;
+ dot.w = pulse;
+ ImGui::TextColored(dot, ICON_LC_SPARKLES);
+ ImGui::SameLine();
+ ImGui::Text(tr("AI connected: %s"), s.session->client().c_str());
+ ImGui::SameLine();
+ ImGui::TextDisabled(tr("%d steps"), s.commands);
+ ImGui::SameLine();
+ if (ImGui::SmallButton(tr("Disconnect##ailink"))) aiLinkDisconnect(tr("AI tool disconnected"));
+ if (ImGui::IsItemHovered()) ImGui::SetTooltip("%s", tr("Stop the AI tool now. Its steps stay in Undo."));
+ }
+ ImGui::End();
+ ImGui::PopStyleColor();
+ ImGui::PopStyleVar();
+
+ if (!s.confirm) return;
+ ImGui::SetNextWindowPos(centre, ImGuiCond_Appearing, ImVec2(0.5f, 0.5f));
+ if (std::exchange(s.focusDialog, false)) ImGui::SetNextWindowFocus();
+ bool open = true;
+ bool allow = false;
+ if (ImGui::Begin(tr("Allow this AI step?###ailinkconfirm"), &open, dialog)) {
+ ImGui::PushTextWrapPos(480 * sc);
+ ImGui::TextWrapped(tr("%s wants to run:"), s.session->client().c_str());
+ ImGui::TextColored(theme::accent, "%s", s.confirm->call.name.c_str());
+ const std::string args = link::describeArgs(s.confirm->call.args);
+ if (!args.empty()) ImGui::TextWrapped("%s", args.c_str());
+ ImGui::Spacing();
+ ImGui::TextColored(theme::danger, "%s", s.confirm->reason.c_str());
+ ImGui::PopTextWrapPos();
+ ImGui::Spacing();
+ allow = ImGui::Button(tr("Allow once##ailink"), ImVec2(140 * sc, 0));
+ ImGui::SameLine();
+ if (ImGui::Button(tr("Deny##ailinkconfirm"), ImVec2(120 * sc, 0)) || ImGui::IsKeyPressed(ImGuiKey_Escape)) open = false;
+ }
+ ImGui::End();
+ if (allow) {
+ AiLinkState::Pending p = std::move(*s.confirm);
+ s.confirm.reset();
+ // The user said yes to this file: later steps may use it without asking again (as if picked).
+ for (const char* key : {"path", "file", "folder", "out"})
+ if (const std::string f = argString(p.call.args, key); !f.empty()) aiLinkPicked(f);
+ aiLinkExecute(p.call);
+ } else if (!open) {
+ s.send(link::AiLinkSession::declinedReply(s.confirm->call.id, s.confirm->call.name));
+ s.confirm.reset();
+ status_ = tr("AI step declined");
+ }
+}
+
+} // namespace sf
diff --git a/src/app/UiTest.cpp b/src/app/UiTest.cpp
index 747a2ab3..77339926 100644
--- a/src/app/UiTest.cpp
+++ b/src/app/UiTest.cpp
@@ -200,6 +200,13 @@
// phone_face NAME=W ... [frames=N] N face messages (default 5) with these ARKit weights
// phone_request METHOD PATH STATUS [BODY] any request with the session token; fails unless the answer has
// STATUS (e.g. phone_request POST /api/ar 200 {"scope":"part","size":20})
+// A scripted AI tool for live mode (PanelAiLink.cpp), over the real local socket / pipe (link/AiLink.h):
+// ai_client connect connect to this window's live-mode endpoint (Preferences > AI > Let AI tools ...)
+// ai_client send JSON send one message as is (a hello, a code, a tools/call)
+// ai_client expect TEXT [S] wait until a reply holding TEXT has come (default 10 s)
+// ai_client close disconnect
+// values: ai_link_state (0 off, 1 listening, 2 waiting for approval, 3 connected, 4 asking), ai_client_lines,
+// undo_ai (1: the next undo step is labelled "AI: ...")
// (tools/guide/update_shortcuts.py puts it into docs/guide/shortcuts.md)
//
// Simulated graphics tablet: real SDL3 pen events, each followed by the mouse event SDL 3.2 synthesizes
@@ -281,11 +288,15 @@
#include "core/SelectionSets.h"
#include "core/ThreadPool.h"
#include "core/Timeline.h"
+#include "link/AiLink.h"
#include "link/HttpServer.h"
#include <imgui_internal.h>
#include <algorithm>
+#include <thread>
+#include <mutex>
+#include <atomic>
#include <cctype>
#include <chrono>
#include <cstdlib>
@@ -302,6 +313,31 @@ namespace sf {
namespace {
+// ai_client: the scripted AI tool's connection and what it has received (a reader thread fills `lines`).
+struct AiTestClient {
+ link::AiLinkConn conn;
+ std::mutex mutex;
+ std::vector<std::string> lines;
+ std::thread reader;
+ std::atomic<bool> stop{false};
+ ~AiTestClient() {
+ stop = true;
+ conn.shutdown();
+ if (reader.joinable()) reader.join();
+ }
+ size_t count() {
+ std::lock_guard lock(mutex);
+ return lines.size();
+ }
+ bool received(const std::string& text) {
+ std::lock_guard lock(mutex);
+ for (const std::string& l : lines)
+ if (l.find(text) != std::string::npos) return true;
+ return false;
+ }
+};
+std::unique_ptr<AiTestClient> g_aiClient;
+
// Splits a line into words; "double quoted" words may contain spaces.
std::vector<std::string> splitWords(const std::string& line) {
std::vector<std::string> out;
@@ -689,6 +725,9 @@ double Demo::query(const std::string& name, bool& known) const {
}
return conflicts;
}
+ if (name == "ai_link_state") return double(app_.aiLinkStateValue()); // live mode (PanelAiLink.cpp)
+ if (name == "ai_client_lines") return g_aiClient ? double(g_aiClient->count()) : 0.0;
+ if (name == "undo_ai") return app_.doc_.undo.canUndo() && app_.doc_.undo.undoLabel().rfind("AI: ", 0) == 0 ? 1.0 : 0.0;
if (name == "mask_shape") return double(int(app_.maskShape_)); // 0 MaskPen, 1 MaskLasso, 2 MaskRect
if (name == "hide_shape") return double(int(app_.hideShape_)); // 1 SelectLasso, 2 SelectRect
if (name.rfind("phone_", 0) == 0) {
@@ -1721,6 +1760,53 @@ bool Demo::parseStep(int line, const std::vector<std::string>& w, std::string& e
fs::copy(src, dst, fs::copy_options::recursive | fs::copy_options::overwrite_existing, ec);
if (ec) SDL_Log("copy %s: %s", src.string().c_str(), ec.message().c_str());
});
+ } else if (verb == "ai_client") {
+ if (!need(1)) return false;
+ const std::string what = w[1];
+ if (what == "connect") {
+ run([this, line] {
+ g_aiClient.reset();
+ auto c = std::make_unique<AiTestClient>();
+ std::string err, endpoint = link::aiLinkEndpoint(err);
+ if (endpoint.empty() || !link::aiLinkConnect(c->conn, endpoint, err)) {
+ fail(line, "can't connect: " + err);
+ return;
+ }
+ AiTestClient* raw = c.get();
+ c->reader = std::thread([raw] {
+ std::string l;
+ while (!raw->stop) {
+ const int got = raw->conn.readLine(l, 50, link::kAiLinkMaxReplyLine);
+ if (got < 0) break;
+ if (got > 0) {
+ std::lock_guard lock(raw->mutex);
+ raw->lines.push_back(l);
+ }
+ }
+ });
+ g_aiClient = std::move(c);
+ });
+ } else if (what == "send") {
+ const std::string message = restOf(lineText_, 2);
+ run([this, line, message] {
+ if (!g_aiClient || !g_aiClient->conn.writeLine(message)) fail(line, "ai_client isn't connected");
+ });
+ } else if (what == "expect") {
+ if (!need(2)) return false;
+ const std::string text = w[2];
+ const float timeout = num(3, 10.0f);
+ steps_.push_back([this, line, text, timeout](float t) {
+ if (g_aiClient && g_aiClient->received(text)) return true;
+ SDL_Delay(10);
+ if (t > timeout) fail(line, "no reply with \"" + text + "\" after " + number(timeout) + " s");
+ return t > timeout;
+ });
+ } else if (what == "close") {
+ run([] { g_aiClient.reset(); });
+ } else {
+ error = "ai_client connect | send JSON | expect TEXT [S] | close";
+ return false;
+ }
} else if (verb == "phone_upload" || verb == "phone_face" || verb == "phone_request") {
if (!need(verb == "phone_request" ? 3 : verb == "phone_upload" ? 2 : 1)) return false;
std::vector<std::string> args(w.begin() + 1, w.end());
diff --git a/src/app/main.cpp b/src/app/main.cpp
index 6e9b244e..1cd0c285 100644
--- a/src/app/main.cpp
+++ b/src/app/main.cpp
@@ -109,10 +109,12 @@ void isolateSettings() {
#if defined(_WIN32)
_putenv_s("APPDATA", d.c_str());
_wputenv_s(L"SF_USER_DATA_DIR", dir.c_str()); // (SDL_GetPrefPath ignores APPDATA: app/UserData.h; wide, any name)
+ _putenv_s("SF_AI_LIVE_DIR", d.c_str()); // live mode's pipe (link/AiLink.h): never the user's window's
#else
setenv("XDG_DATA_HOME", d.c_str(), 1);
setenv("XDG_CONFIG_HOME", d.c_str(), 1);
setenv("HOST_XDG_DATA_HOME", d.c_str(), 1); // in a Flatpak, the Blender bridge folder (io/BlenderBridge.h)
+ setenv("SF_AI_LIVE_DIR", d.c_str(), 1); // live mode's socket (link/AiLink.h): never the user's window's
#if defined(__APPLE__)
setenv("HOME", d.c_str(), 1);
#endif
diff --git a/src/cli/McpAttach.cpp b/src/cli/McpAttach.cpp
new file mode 100644
index 00000000..97cbaf45
--- /dev/null
+++ b/src/cli/McpAttach.cpp
@@ -0,0 +1,282 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "cli/McpAttach.h"
+
+#include "cli/McpTools.h"
+#include "core/Json.h"
+#include "link/AiLink.h"
+#include "link/AiLinkSession.h"
+
+#include <iostream>
+
+#ifndef SCULPTFORGE_VERSION
+#define SCULPTFORGE_VERSION "unknown"
+#endif
+
+namespace sf {
+
+namespace {
+
+using link::AiLinkSession;
+
+constexpr int kApprovalWaitMs = 60 * 1000; // live_connect waits this long for a click on Approve
+constexpr int kAnswerWaitMs = 30 * 60 * 1000; // a tool call (a big remesh, or the user deciding in a dialog)
+
+Json textContent(const std::string& text) {
+ Json t = Json::object();
+ t.set("type", "text");
+ t.set("text", text);
+ Json content = Json::array();
+ content.push(std::move(t));
+ return content;
+}
+
+Json tool(const std::string& name, const std::string& description, Json properties) {
+ Json schema = Json::object();
+ schema.set("type", "object");
+ schema.set("properties", std::move(properties));
+ schema.set("required", Json::array());
+ Json t = Json::object();
+ t.set("name", name);
+ t.set("description", description);
+ t.set("inputSchema", std::move(schema));
+ return t;
+}
+
+Json connectTool() {
+ Json code = Json::object();
+ code.set("type", "string");
+ code.set("description", "The 6-digit code SculptForge shows, read to you by the user (leave out to wait for a click on Approve).");
+ Json props = Json::object();
+ props.set("code", std::move(code));
+ return tool("live_connect",
+ "Connect to the SculptForge window the user has open, to sculpt in it live. SculptForge shows an Approve "
+ "dialog with a 6-digit code: the user clicks Approve, or reads you the code and you call this again with "
+ "code=. Live mode must be on there (Preferences > AI > Let AI tools control this window).",
+ std::move(props));
+}
+
+Json disconnectTool() {
+ return tool("live_disconnect", "Disconnect from the SculptForge window (the user can also press Disconnect there).",
+ Json::object());
+}
+
+class Attach {
+public:
+ Attach(std::ostream& out, std::string endpoint) : out_(out), endpoint_(std::move(endpoint)) {}
+
+ void message(const std::string& line) {
+ Json msg;
+ std::string err;
+ if (!Json::parse(line, msg, err) || !msg.isObject()) return send(AiLinkSession::errorReply(Json(), -32700, "Parse error: " + err));
+ if (!msg.has("id")) return; // notifications
+ const Json& id = msg["id"];
+ const std::string method = msg["method"].asString();
+ if (method == "initialize") return initialize(id, msg["params"]);
+ if (method == "ping") return send(result(id, Json::object()));
+ if (method == "prompts/list") return send(result(id, mcpPromptList()));
+ if (method == "prompts/get") {
+ Json r;
+ if (!mcpPromptGet(msg["params"]["name"].asString(), msg["params"]["arguments"], r, err))
+ return send(AiLinkSession::errorReply(id, -32602, err));
+ return send(result(id, std::move(r)));
+ }
+ if (method == "tools/list") return toolsList(id, msg);
+ if (method == "tools/call") return toolsCall(id, msg);
+ send(AiLinkSession::errorReply(id, -32601, "Method not found: " + method));
+ }
+
+private:
+ static std::string result(const Json& id, Json r) {
+ Json m = Json::object();
+ m.set("jsonrpc", "2.0");
+ m.set("id", id);
+ m.set("result", std::move(r));
+ return m.dump();
+ }
+
+ void send(const std::string& line) { out_ << line << "\n" << std::flush; }
+
+ void listChanged() { send(R"({"jsonrpc":"2.0","method":"notifications/tools/list_changed"})"); }
+
+ void dropConnection() {
+ const bool was = paired_;
+ conn_.close();
+ paired_ = false;
+ if (was) listChanged();
+ }
+
+ void initialize(const Json& id, const Json& params) {
+ client_ = params["clientInfo"]["name"].asString();
+ Json r = Json::object();
+ const std::string requested = params["protocolVersion"].asString();
+ r.set("protocolVersion", requested.empty() ? "2025-06-18" : requested);
+ Json caps = Json::object(), tools = Json::object(), prompts = Json::object();
+ tools.set("listChanged", true);
+ prompts.set("listChanged", false);
+ caps.set("tools", tools);
+ caps.set("prompts", prompts);
+ r.set("capabilities", caps);
+ Json info = Json::object();
+ info.set("name", "sculptforge-live");
+ info.set("version", SCULPTFORGE_VERSION);
+ r.set("serverInfo", info);
+ r.set("instructions",
+ "Live mode: you sculpt in the SculptForge window the user has open, and they watch. Call live_connect "
+ "first; the user approves in SculptForge. Then work in small steps and look after each one: "
+ "viewport_image shows what the user sees, view_turntable shows the model from all sides, view_set turns "
+ "the camera. Every step lands in the undo history (labelled AI), so the user can step back. Some actions "
+ "ask the user first (files outside the project folder, overwrites, scripts, network); if they decline, "
+ "don't retry, ask them.");
+ send(result(id, std::move(r)));
+ }
+
+ // Reads the app's next line; false when the connection closed.
+ bool readApp(Json& msg, int timeoutMs) {
+ std::string line;
+ const int got = conn_.readLine(line, timeoutMs, link::kAiLinkMaxReplyLine);
+ if (got < 0) {
+ dropConnection();
+ return false;
+ }
+ if (got == 0) return false;
+ std::string err;
+ if (!Json::parse(line, msg, err)) msg = Json::object();
+ return true;
+ }
+
+ // The app's answer to a pairing message: approved now, refused (closed), or still waiting.
+ std::string pairingOutcome(const Json& msg) {
+ if (msg["paired"].asBool()) {
+ paired_ = true;
+ listChanged();
+ return {};
+ }
+ if (msg.has("paired")) {
+ const std::string e = msg["error"].asString();
+ if (!conn_.valid() || msg["attempts_left"].asNumber(1) <= 0 || e.find("declined") != std::string::npos) dropConnection();
+ return e.empty() ? "not approved" : e;
+ }
+ return "waiting";
+ }
+
+ void toolsList(const Json& id, const Json& msg) {
+ if (!paired_) {
+ Json tools = Json::array();
+ tools.push(connectTool());
+ Json r = Json::object();
+ r.set("tools", tools);
+ return send(result(id, std::move(r)));
+ }
+ Json reply;
+ if (!forward(id, msg, reply)) return;
+ Json tools = Json::array();
+ for (const Json& t : reply["result"]["tools"].items()) tools.push(t);
+ tools.push(disconnectTool());
+ Json r = Json::object();
+ r.set("tools", tools);
+ send(result(id, std::move(r)));
+ }
+
+ void toolsCall(const Json& id, const Json& msg) {
+ const std::string name = msg["params"]["name"].asString();
+ if (name == "live_connect") return send(AiLinkSession::contentReply(id, textContent(connect(msg["params"]["arguments"]["code"].asString())), !paired_));
+ if (name == "live_disconnect") {
+ dropConnection();
+ return send(AiLinkSession::resultReply(id, true, "Disconnected from SculptForge"));
+ }
+ if (!paired_)
+ return send(AiLinkSession::resultReply(id, false, "Not connected to SculptForge: call live_connect first."));
+ Json reply;
+ if (forward(id, msg, reply)) send(reply.dump());
+ }
+
+ // Sends a request to the app and waits for its answer (the same id). False (answered here) if the app left.
+ bool forward(const Json& id, const Json& msg, Json& reply) {
+ Json request = Json::object();
+ request.set("jsonrpc", "2.0");
+ request.set("id", id);
+ request.set("method", msg["method"]);
+ request.set("params", msg["params"]);
+ if (conn_.writeLine(request.dump())) {
+ for (;;) {
+ Json m;
+ if (!readApp(m, kAnswerWaitMs)) break;
+ if (m["id"].dump() == id.dump()) {
+ reply = std::move(m);
+ return true;
+ }
+ }
+ }
+ dropConnection();
+ send(AiLinkSession::resultReply(id, false, "SculptForge closed the connection (the user disconnected, turned live mode "
+ "off or closed the window). Call live_connect to ask again."));
+ return false;
+ }
+
+ std::string connect(const std::string& code) {
+ if (paired_) return "Already connected to SculptForge.";
+ if (!conn_.valid()) {
+ std::string err, endpoint = endpoint_.empty() ? link::aiLinkEndpoint(err) : endpoint_;
+ if (endpoint.empty() || !link::aiLinkConnect(conn_, endpoint, err))
+ return "Can't reach SculptForge: " + err +
+ ". Ask the user to open it and turn on Preferences > AI > Let AI tools control this window.";
+ Json hello = Json::object();
+ hello.set("hello", "sculptforge-live");
+ hello.set("v", 1);
+ hello.set("client", client_.empty() ? "AI tool" : client_);
+ Json m;
+ if (!conn_.writeLine(hello.dump()) || !readApp(m, 10000) || m["pairing"].asString() != "waiting") {
+ dropConnection();
+ return "SculptForge didn't accept the connection (is another AI tool connected?).";
+ }
+ }
+ // An Approve click that came in since the last call.
+ for (Json m; conn_.valid() && readApp(m, 0);)
+ if (const std::string o = pairingOutcome(m); o != "waiting") return o.empty() ? connectedText() : "Not connected: " + o;
+ if (!conn_.valid()) return "Not connected: SculptForge closed the connection.";
+ if (!code.empty()) {
+ Json pair = Json::object();
+ pair.set("pair", code);
+ Json m;
+ if (!conn_.writeLine(pair.dump()) || !readApp(m, 10000)) {
+ dropConnection();
+ return "Not connected: SculptForge closed the connection.";
+ }
+ const std::string o = pairingOutcome(m);
+ if (o.empty()) return connectedText();
+ if (o == "waiting") return "Still waiting for approval.";
+ return "Not connected: " + o +
+ (conn_.valid() ? " (" + std::to_string(int(m["attempts_left"].asNumber())) + " tries left)" : "");
+ }
+ for (Json m; readApp(m, kApprovalWaitMs);)
+ if (const std::string o = pairingOutcome(m); o != "waiting") return o.empty() ? connectedText() : "Not connected: " + o;
+ if (!conn_.valid()) return "Not connected: SculptForge closed the connection.";
+ return "Waiting for approval: ask the user to click Approve in SculptForge, or to read you the 6-digit code it "
+ "shows, then call live_connect again with code=.";
+ }
+
+ static std::string connectedText() {
+ return "Connected to SculptForge. Its tools are now listed (call tools/list again if you don't see them): start "
+ "with scene_overview and viewport_image.";
+ }
+
+ std::ostream& out_;
+ std::string endpoint_, client_;
+ link::AiLinkConn conn_;
+ bool paired_ = false;
+};
+
+} // namespace
+
+int runMcpAttach(std::istream& in, std::ostream& out, const std::string& endpoint) {
+ Attach attach(out, endpoint);
+ std::string line;
+ while (std::getline(in, line)) {
+ if (line.find_first_not_of(" \t\r") == std::string::npos) continue;
+ attach.message(line);
+ }
+ return 0;
+}
+
+} // namespace sf
diff --git a/src/cli/McpAttach.h b/src/cli/McpAttach.h
new file mode 100644
index 00000000..0b3f0907
--- /dev/null
+++ b/src/cli/McpAttach.h
@@ -0,0 +1,19 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// `sculptforge-cli --mcp --attach`: an MCP server on stdio that drives the OPEN app (live mode, link/AiLink.h)
+// instead of a headless scene. Until the user approves the connection in the app it offers one tool,
+// live_connect; once approved, the app's own tools (every command, plus the viewport image, the camera and
+// screen-space strokes) and live_disconnect. The app decides everything: what's offered, what's asked first,
+// what's refused. This side only carries messages.
+#pragma once
+
+#include <iosfwd>
+#include <string>
+
+namespace sf {
+
+// Serves until `in` closes. `endpoint` "" = this user's (link::aiLinkEndpoint).
+int runMcpAttach(std::istream& in, std::ostream& out, const std::string& endpoint = {});
+
+} // namespace sf
diff --git a/src/cli/McpServer.cpp b/src/cli/McpServer.cpp
index 4c28b454..4b6d5d5c 100644
--- a/src/cli/McpServer.cpp
+++ b/src/cli/McpServer.cpp
@@ -126,6 +126,8 @@ std::string handleMcpMessage(const CommandRegistry& registry, Document& doc, con
return errorReply(id, -32601, "Method not found: " + method).dump();
}
+Json mcpToolList(const CommandRegistry& registry) { return toolList(registry)["tools"]; }
+
int runMcpServer(const CommandRegistry& registry, std::istream& in, std::ostream& out) {
Document doc;
// stdout is the protocol: library messages go to stderr.
diff --git a/src/cli/McpServer.h b/src/cli/McpServer.h
index c9823705..733c919a 100644
--- a/src/cli/McpServer.h
+++ b/src/cli/McpServer.h
@@ -8,6 +8,7 @@
#pragma once
#include "core/Commands.h"
+#include "core/Json.h"
#include <iosfwd>
#include <string>
@@ -17,6 +18,9 @@ namespace sf {
// Handles one JSON-RPC message; returns the response line, or "" for notifications.
std::string handleMcpMessage(const CommandRegistry& registry, Document& doc, const std::string& line);
+// Every command as an MCP tool definition (name, description, inputSchema), as tools/list sends them.
+Json mcpToolList(const CommandRegistry& registry);
+
// Serves until `in` closes. Returns the process exit code.
int runMcpServer(const CommandRegistry& registry, std::istream& in, std::ostream& out);
diff --git a/src/cli/main.cpp b/src/cli/main.cpp
index 6e6a72a1..74d32d57 100644
--- a/src/cli/main.cpp
+++ b/src/cli/main.cpp
@@ -6,6 +6,7 @@
#include "ai/AiCommands.h"
#include "ai/AiPolicy.h"
#include "ai/SplatTrainer.h"
+#include "cli/McpAttach.h"
#include "cli/McpServer.h"
#include "core/Benchmark.h"
#include "core/BrushLibrary.h"
@@ -35,6 +36,7 @@ void usage() {
" -l, --list List available commands\n"
" --schema Print commands as LLM tool definitions (JSON)\n"
" --mcp Run as an MCP server on stdio (Claude Code, Claude Desktop, any MCP client)\n"
+ " --mcp --attach ... that drives the open SculptForge window instead (live mode: Preferences > AI)\n"
" -q, --quiet Only print errors\n"
" --no-ai Leave the AI commands out (as SF_AI=off; Preferences > AI turns them off for good)\n"
" --no-packs Safe mode: leave every installed pack out (pack_install still works)\n"
@@ -128,6 +130,9 @@ int main(int argc, char** argv) {
}
return 0;
} else if (a == "--mcp") {
+ // --attach: drive the open app (live mode, cli/McpAttach.h) instead of a scene of our own.
+ for (int j = i + 1; j < argc; ++j)
+ if (std::string(argv[j]) == "--attach") return sf::runMcpAttach(std::cin, std::cout);
return sf::runMcpServer(registry, std::cin, std::cout);
} else if (a == "--schema") {
std::puts(registry.toolSchemaJson().c_str());
diff --git a/src/core/AgentTools.cpp b/src/core/AgentTools.cpp
new file mode 100644
index 00000000..1c26e710
--- /dev/null
+++ b/src/core/AgentTools.cpp
@@ -0,0 +1,178 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "core/AgentTools.h"
+
+#include "core/Commands.h"
+#include "core/Multires.h"
+
+#include <cmath>
+#include <cstdio>
+#include <sstream>
+
+namespace sf {
+
+namespace {
+
+std::string num(double v) {
+ char buf[32];
+ std::snprintf(buf, sizeof buf, "%.4g", v);
+ return buf;
+}
+
+std::string vecText(const glm::vec3& v) { return num(v.x) + "," + num(v.y) + "," + num(v.z); }
+
+bool parseVec(const std::string& s, glm::vec3& out) {
+ return std::sscanf(s.c_str(), " %f , %f , %f", &out.x, &out.y, &out.z) == 3;
+}
+
+// Part by name (exact) or index; "" = the active Part.
+int partArg(const Document& doc, const std::string& value) {
+ if (value.empty()) return doc.activePart;
+ if (const int i = doc.findPart(value); i >= 0) return i;
+ char* end = nullptr;
+ const long n = std::strtol(value.c_str(), &end, 10);
+ return end && *end == '\0' && n >= 0 && n < doc.partCount() ? int(n) : -1;
+}
+
+std::string partLine(const Document& doc, int i) {
+ const AABB b = doc.partMesh(i).bounds();
+ const glm::vec3 size = b.valid() ? b.max - b.min : glm::vec3(0.0f);
+ const glm::vec3 centre = b.valid() ? (b.max + b.min) * 0.5f : glm::vec3(0.0f);
+ return "size " + vecText(size) + " (w,h,d), centre " + vecText(centre);
+}
+
+} // namespace
+
+void registerAgentTools(CommandRegistry& reg) {
+ using T = ParamSpec::Type;
+ CommandRegistry* registry = &reg; // (the registry outlives its commands)
+
+ reg.add({"blockout",
+ "Block out a form in one call: a Forge Sphere armature (root, limbs, head...) skinned into a sculptable "
+ "Part. Each sphere is \"x,y,z,radius,parent\" (parent = the index of an earlier sphere in this list; the "
+ "first sphere is the root, its parent is ignored), separated by '|'. Y is up, the model faces +Z, "
+ "units are scene units (a new sphere has radius 1). Each step is its own undo step.",
+ {{"spheres", T::String, "\"x,y,z,r,parent | ...\", e.g. \"0,0,0,0.6,-1 | 0,0.9,0.1,0.4,0 | 0,1.5,0.2,0.3,1\".", true},
+ {"symmetry", T::String, "Mirror the limbs across these planes, e.g. \"x\" (default none).", false},
+ {"name", T::String, "Part name (default \"Blockout\").", false},
+ {"make_mesh", T::Bool, "Skin it into a sculptable Part (default true).", false},
+ {"resolution", T::Number, "Skin cells across the longest side (16-1024, default 160).", false}},
+ [registry](Document& doc, const Args& a) -> CommandResult {
+ struct S { glm::vec3 c; double r; int parent; };
+ std::vector<S> spheres;
+ std::stringstream in(argString(a, "spheres"));
+ std::string item;
+ while (std::getline(in, item, '|')) {
+ if (item.find_first_not_of(" \t") == std::string::npos) continue;
+ S s{};
+ float r = 0.0f;
+ int parent = -1;
+ const int got = std::sscanf(item.c_str(), " %f , %f , %f , %f , %d", &s.c.x, &s.c.y, &s.c.z, &r, &parent);
+ if (got < 4 || !(r > 0.0f) || !std::isfinite(r))
+ return {false, "sphere " + std::to_string(spheres.size()) + ": expected \"x,y,z,radius,parent\" with radius > 0"};
+ s.r = r;
+ s.parent = spheres.empty() ? -1 : parent;
+ if (!spheres.empty() && (parent < 0 || parent >= int(spheres.size())))
+ return {false, "sphere " + std::to_string(spheres.size()) + ": parent must be an earlier sphere (0 to " +
+ std::to_string(spheres.size() - 1) + ")"};
+ spheres.push_back(s);
+ if (spheres.size() > 256) return {false, "at most 256 spheres"};
+ }
+ if (spheres.empty()) return {false, "give at least one sphere"};
+
+ auto run = [&](const std::string& name, const Args& args) { return registry->execute(doc, name, args); };
+ CommandResult r = run("forgesphere_new", {{"name", argString(a, "name", "Blockout")}, {"radius", spheres[0].r}});
+ if (!r.ok) return r;
+ r = run("forgesphere_set", {{"index", 0.0}, {"position", vecText(spheres[0].c)}});
+ if (!r.ok) return r;
+ // forgesphere_add reports the new index; with symmetry the mirror copies take indices too.
+ std::vector<int> index{0};
+ const std::string symmetry = argString(a, "symmetry");
+ for (size_t i = 1; i < spheres.size(); ++i) {
+ const size_t before = doc.mesh.forgespheres.size();
+ Args add{{"parent", double(index[size_t(spheres[i].parent)])},
+ {"position", vecText(spheres[i].c)},
+ {"radius", spheres[i].r}};
+ if (!symmetry.empty()) add["symmetry"] = symmetry;
+ r = run("forgesphere_add", add);
+ if (!r.ok) return {false, "sphere " + std::to_string(i) + ": " + r.message};
+ index.push_back(int(before));
+ }
+ std::string out = "Blocked out " + std::to_string(doc.mesh.forgespheres.size()) + " spheres";
+ if (argBool(a, "make_mesh", true)) {
+ r = run("forgesphere_make_mesh", {{"resolution", argNumber(a, "resolution", 160)}});
+ if (!r.ok) return r;
+ out += "; " + r.message;
+ }
+ return {true, out};
+ }});
+
+ reg.add({"measure",
+ "Measure proportions: a Part's size (width, height, depth), centre and its share of the whole scene; "
+ "with compare=, the two Parts' size ratios and the offset between their centres; with from= and to=, "
+ "the distance between two points.",
+ {{"part", T::String, "Part name or index (default: the active Part).", false},
+ {"compare", T::String, "Another Part to compare it with.", false},
+ {"from", T::String, "A point \"x,y,z\" (with to=: their distance).", false},
+ {"to", T::String, "A point \"x,y,z\".", false}},
+ [](Document& doc, const Args& a) -> CommandResult {
+ if (a.contains("from") || a.contains("to")) {
+ glm::vec3 p, q;
+ if (!parseVec(argString(a, "from"), p) || !parseVec(argString(a, "to"), q))
+ return {false, "from and to must both be \"x,y,z\""};
+ return {true, "Distance " + num(glm::length(q - p)) + " (delta " + vecText(q - p) + ")"};
+ }
+ const int i = partArg(doc, argString(a, "part"));
+ if (i < 0) return {false, "No Part \"" + argString(a, "part") + "\" (see scene_overview)"};
+ const AABB b = doc.partMesh(i).bounds();
+ if (!b.valid()) return {false, doc.parts[size_t(i)].name + " is empty"};
+ const glm::vec3 size = b.max - b.min;
+ std::string out = doc.parts[size_t(i)].name + ": " + partLine(doc, i);
+ const float longest = std::max({size.x, size.y, size.z, 1e-9f});
+ out += "; proportions w:h:d = " + num(size.x / longest) + ":" + num(size.y / longest) + ":" + num(size.z / longest);
+ const AABB scene = doc.visibleBounds();
+ if (scene.valid() && scene.max.y > scene.min.y)
+ out += "; " + num(100.0 * size.y / (scene.max.y - scene.min.y)) + "% of the scene's height";
+ if (a.contains("compare")) {
+ const int j = partArg(doc, argString(a, "compare"));
+ if (j < 0) return {false, "No Part \"" + argString(a, "compare") + "\" (see scene_overview)"};
+ const AABB c = doc.partMesh(j).bounds();
+ if (!c.valid()) return {false, doc.parts[size_t(j)].name + " is empty"};
+ const glm::vec3 other = c.max - c.min;
+ auto ratio = [](float x, float y) { return y > 1e-9f ? num(x / y) : std::string("-"); };
+ out += "\n" + doc.parts[size_t(j)].name + ": " + partLine(doc, j) + "\nratio " +
+ doc.parts[size_t(i)].name + "/" + doc.parts[size_t(j)].name + ": width " + ratio(size.x, other.x) +
+ ", height " + ratio(size.y, other.y) + ", depth " + ratio(size.z, other.z) +
+ "; centre offset " + vecText((c.max + c.min) * 0.5f - (b.max + b.min) * 0.5f);
+ }
+ return {true, out};
+ }});
+
+ reg.add({"scene_overview",
+ "What's in the scene: every Part (index, name, triangles, subdivision levels, size, centre, active / "
+ "hidden), the active brush and the size of the whole scene. Use it before and after big steps.",
+ {},
+ [](Document& doc, const Args&) -> CommandResult {
+ std::string out = std::to_string(doc.partCount()) + " Part" + (doc.partCount() == 1 ? "" : "s") + ":";
+ for (int i = 0; i < doc.partCount(); ++i) {
+ const Part& p = doc.parts[size_t(i)];
+ const Mesh& m = doc.partMesh(i);
+ out += "\n" + std::to_string(i) + ". " + p.name + ": " + std::to_string(m.triangleCount()) + " triangles";
+ if (subdivLevelCount(m)) out += ", " + subdivLevelText(m);
+ if (!m.forgespheres.empty()) out += ", Forge Spheres (" + std::to_string(m.forgespheres.size()) + ")";
+ if (m.triangleCount()) out += ", " + partLine(doc, i);
+ if (i == doc.activePart) out += ", active";
+ if (!p.visible) out += ", hidden";
+ }
+ const AABB scene = doc.visibleBounds();
+ if (scene.valid()) out += "\nScene (visible): size " + vecText(scene.max - scene.min) + ", centre " +
+ vecText((scene.max + scene.min) * 0.5f);
+ out += "\nActive brush: " + (doc.activeBrush >= 0 && doc.activeBrush < int(doc.brushes.size())
+ ? doc.brushes[size_t(doc.activeBrush)].name
+ : std::string("built-in"));
+ out += "\nUndo steps on the active Part: " + std::to_string(doc.undo.undoCount());
+ return {true, out};
+ }});
+}
+
+} // namespace sf
diff --git a/src/core/AgentTools.h b/src/core/AgentTools.h
new file mode 100644
index 00000000..8e1aa5e6
--- /dev/null
+++ b/src/core/AgentTools.h
@@ -0,0 +1,17 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Higher-level commands for AI agents (and scripts), built on the plain ones so every step lands in the undo
+// history as it would from the UI:
+// blockout a whole Forge Sphere armature in one call ("x,y,z,r,parent | ..."), skinned into a sculptable Part
+// measure a Part's size, centre and proportions, or two Parts compared, or the distance between two points
+// scene_overview the Parts with their triangles, levels, sizes and visibility, the active brush, the scene's size
+#pragma once
+
+namespace sf {
+
+class CommandRegistry;
+
+void registerAgentTools(CommandRegistry& registry);
+
+} // namespace sf
diff --git a/src/core/Commands.cpp b/src/core/Commands.cpp
index 906122b4..878704fb 100644
--- a/src/core/Commands.cpp
+++ b/src/core/Commands.cpp
@@ -1,6 +1,8 @@
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
#include "core/Commands.h"
+
+#include "core/AgentTools.h"
#include "core/ViewCapture.h"
#include "core/Bake.h"
@@ -648,6 +650,7 @@ CommandRegistry::CommandRegistry() {
registerRetopoCommands(*this); // qremesh, project_all (RetopoCommands.cpp)
registerQRemeshGuideCommands(*this); // qremesh_guide, ... (QRemeshGuides.cpp)
registerForgeSphereCommands(*this); // Forge Sphere_new, ... (Forge Spheres.cpp)
+ registerAgentTools(*this); // blockout, measure, scene_overview (core/AgentTools.cpp)
registerDeformCommands(*this); // deform_polish, deform_relax, deform_smooth, deform_balloon (Deform.cpp)
add({"stroke",
diff --git a/src/link/AiLink.cpp b/src/link/AiLink.cpp
new file mode 100644
index 00000000..da2e600b
--- /dev/null
+++ b/src/link/AiLink.cpp
@@ -0,0 +1,519 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "link/AiLink.h"
+
+#include <algorithm>
+#include <cctype>
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <functional>
+
+#if defined(_WIN32)
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <aclapi.h>
+#include <sddl.h>
+#else
+#include <cerrno>
+#include <fcntl.h>
+#include <poll.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <sys/un.h>
+#include <unistd.h>
+#endif
+
+namespace sf::link {
+
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+int remainingMs(Clock::time_point deadline) {
+ const auto left = std::chrono::duration_cast<std::chrono::milliseconds>(deadline - Clock::now()).count();
+ return left > 0 ? int(left) : 0;
+}
+
+#if !defined(_WIN32)
+// The folder must be ours and closed to everyone else; made 0700 if missing.
+bool safeDir(const std::string& dir, std::string& error) {
+ if (::mkdir(dir.c_str(), 0700) != 0 && errno != EEXIST) {
+ error = "can't create " + dir + ": " + std::strerror(errno);
+ return false;
+ }
+ struct stat st{};
+ if (::lstat(dir.c_str(), &st) != 0 || !S_ISDIR(st.st_mode)) {
+ error = dir + " is not a folder";
+ return false;
+ }
+ if (st.st_uid != ::getuid()) {
+ error = dir + " belongs to another user: live mode stays off";
+ return false;
+ }
+ if ((st.st_mode & 077) != 0 && ::chmod(dir.c_str(), 0700) != 0) {
+ error = dir + " is open to other users and can't be closed";
+ return false;
+ }
+ return true;
+}
+
+bool peerIsMe(int fd) {
+#if defined(SO_PEERCRED)
+ struct ucred cred{};
+ socklen_t len = sizeof cred;
+ if (::getsockopt(fd, SOL_SOCKET, SO_PEERCRED, &cred, &len) != 0) return false;
+ return cred.uid == ::getuid();
+#else
+ uid_t uid = 0;
+ gid_t gid = 0;
+ if (::getpeereid(fd, &uid, &gid) != 0) return false;
+ return uid == ::getuid();
+#endif
+}
+
+bool fillAddress(const std::string& path, sockaddr_un& addr, std::string& error) {
+ std::memset(&addr, 0, sizeof addr);
+ addr.sun_family = AF_UNIX;
+ if (path.size() >= sizeof addr.sun_path) {
+ error = "socket path too long: " + path;
+ return false;
+ }
+ std::memcpy(addr.sun_path, path.c_str(), path.size() + 1);
+ return true;
+}
+#else
+std::wstring widen(const std::string& s) {
+ if (s.empty()) return {};
+ const int n = MultiByteToWideChar(CP_UTF8, 0, s.data(), int(s.size()), nullptr, 0);
+ std::wstring w(size_t(n), L'\0');
+ MultiByteToWideChar(CP_UTF8, 0, s.data(), int(s.size()), w.data(), n);
+ return w;
+}
+
+std::string userName() {
+ wchar_t name[256];
+ DWORD len = 256;
+ if (!GetUserNameW(name, &len)) return "user";
+ std::string out;
+ for (DWORD i = 0; i + 1 < len; ++i) {
+ const wchar_t c = name[i];
+ out += (c < 128 && (std::isalnum(int(c)) || c == '-' || c == '_')) ? char(c) : '_';
+ }
+ return out.empty() ? "user" : out;
+}
+
+// A DACL granting the current user (only) full access: the security descriptor is LocalFree'd by the caller.
+PSECURITY_DESCRIPTOR currentUserOnly() {
+ HANDLE token = nullptr;
+ if (!OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &token)) return nullptr;
+ DWORD size = 0;
+ GetTokenInformation(token, TokenUser, nullptr, 0, &size);
+ std::string buffer(size, '\0');
+ PSECURITY_DESCRIPTOR sd = nullptr;
+ if (GetTokenInformation(token, TokenUser, buffer.data(), size, &size)) {
+ LPWSTR sid = nullptr;
+ if (ConvertSidToStringSidW(reinterpret_cast<TOKEN_USER*>(buffer.data())->User.Sid, &sid)) {
+ // Protected DACL: this user, full access; nobody else (not even Administrators or Everyone).
+ const std::wstring sddl = L"D:P(A;;GA;;;" + std::wstring(sid) + L")";
+ ConvertStringSecurityDescriptorToSecurityDescriptorW(sddl.c_str(), SDDL_REVISION_1, &sd, nullptr);
+ LocalFree(sid);
+ }
+ }
+ CloseHandle(token);
+ return sd;
+}
+
+// The user SID of a process's token (empty if it can't be read).
+std::string processUserSid(HANDLE process) {
+ HANDLE token = nullptr;
+ if (!OpenProcessToken(process, TOKEN_QUERY, &token)) return {};
+ DWORD size = 0;
+ GetTokenInformation(token, TokenUser, nullptr, 0, &size);
+ std::string buffer(size, '\0'), out;
+ if (GetTokenInformation(token, TokenUser, buffer.data(), size, &size)) {
+ LPSTR sid = nullptr;
+ if (ConvertSidToStringSidA(reinterpret_cast<TOKEN_USER*>(buffer.data())->User.Sid, &sid)) {
+ out = sid;
+ LocalFree(sid);
+ }
+ }
+ CloseHandle(token);
+ return out;
+}
+
+// True when the pipe's server runs as this user: another account could create the name first (before any app
+// window), with a DACL open to us; the AI tool's requests must not go to it.
+bool serverIsMe(HANDLE pipe) {
+ ULONG pid = 0;
+ if (!GetNamedPipeServerProcessId(pipe, &pid)) return false;
+ const HANDLE process = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, FALSE, pid);
+ if (!process) return false;
+ const std::string server = processUserSid(process);
+ CloseHandle(process);
+ const std::string me = processUserSid(GetCurrentProcess());
+ return !me.empty() && server == me;
+}
+
+HANDLE asHandle(intptr_t h) { return reinterpret_cast<HANDLE>(h); }
+intptr_t fromHandle(HANDLE h) { return h == INVALID_HANDLE_VALUE || !h ? AiLinkConn::kInvalid : reinterpret_cast<intptr_t>(h); }
+
+HANDLE createInstance(const std::string& endpoint, bool first) {
+ PSECURITY_DESCRIPTOR sd = currentUserOnly();
+ if (!sd) return INVALID_HANDLE_VALUE;
+ SECURITY_ATTRIBUTES sa{sizeof sa, sd, FALSE};
+ const HANDLE h = CreateNamedPipeW(widen(endpoint).c_str(),
+ PIPE_ACCESS_DUPLEX | FILE_FLAG_OVERLAPPED | (first ? FILE_FLAG_FIRST_PIPE_INSTANCE : 0),
+ PIPE_TYPE_BYTE | PIPE_READMODE_BYTE | PIPE_WAIT | PIPE_REJECT_REMOTE_CLIENTS, 2, // (a second client is told "busy")
+ 1 << 16, 1 << 16, 0, &sa);
+ LocalFree(sd);
+ return h;
+}
+#endif
+
+} // namespace
+
+std::string aiLinkEndpoint(std::string& error) {
+#if defined(_WIN32)
+ (void)error;
+ std::string name = "\\\\.\\pipe\\sculptforge-ai-live-" + userName();
+ if (const char* own = std::getenv("SF_AI_LIVE_DIR"); own && *own) // tests and isolated runs (app/main.cpp)
+ name += "-" + std::to_string(std::hash<std::string>{}(own) % 1000000007u);
+ return name;
+#else
+ std::string dir;
+ if (const char* own = std::getenv("SF_AI_LIVE_DIR"); own && *own) { // tests and isolated runs (app/main.cpp)
+ dir = std::string(own) + "/sculptforge";
+ } else if (const char* run = std::getenv("XDG_RUNTIME_DIR"); run && *run) {
+ dir = std::string(run) + "/sculptforge";
+ } else {
+ const char* tmp = std::getenv("TMPDIR");
+ std::string base = tmp && *tmp ? tmp : "/tmp";
+ while (base.size() > 1 && base.back() == '/') base.pop_back();
+ dir = base + "/sculptforge-" + std::to_string(::getuid());
+ }
+ if (!safeDir(dir, error)) return {};
+ return dir + "/ai-live.sock";
+#endif
+}
+
+int aiLinkFileMode(const std::string& path) {
+#if defined(_WIN32)
+ (void)path;
+ return -1;
+#else
+ struct stat st{};
+ if (::lstat(path.c_str(), &st) != 0) return -1;
+ return int(st.st_mode & 0777);
+#endif
+}
+
+// ---------------------------------------------------------------------------
+// AiLinkConn
+// ---------------------------------------------------------------------------
+
+AiLinkConn::AiLinkConn(AiLinkConn&& o) noexcept : handle_(o.handle_), server_(o.server_), buffer_(std::move(o.buffer_)) {
+ o.handle_ = kInvalid;
+}
+
+AiLinkConn& AiLinkConn::operator=(AiLinkConn&& o) noexcept {
+ if (this != &o) {
+ close();
+ handle_ = o.handle_;
+ server_ = o.server_;
+ buffer_ = std::move(o.buffer_);
+ o.handle_ = kInvalid;
+ }
+ return *this;
+}
+
+void AiLinkConn::close() {
+ if (handle_ == kInvalid) return;
+#if defined(_WIN32)
+ if (server_) DisconnectNamedPipe(asHandle(handle_));
+ CloseHandle(asHandle(handle_));
+#else
+ ::close(int(handle_));
+#endif
+ handle_ = kInvalid;
+ buffer_.clear();
+}
+
+void AiLinkConn::shutdown() {
+ if (handle_ == kInvalid) return;
+#if defined(_WIN32)
+ CancelIoEx(asHandle(handle_), nullptr);
+ if (server_) DisconnectNamedPipe(asHandle(handle_));
+#else
+ ::shutdown(int(handle_), SHUT_RDWR);
+#endif
+}
+
+int AiLinkConn::readLine(std::string& line, int timeoutMs, size_t maxLine) {
+ const auto deadline = Clock::now() + std::chrono::milliseconds(timeoutMs);
+ for (;;) {
+ if (const size_t nl = buffer_.find('\n'); nl != std::string::npos) {
+ if (nl > maxLine) { // (it came whole: still too long)
+ close();
+ return -1;
+ }
+ line.assign(buffer_, 0, nl);
+ if (!line.empty() && line.back() == '\r') line.pop_back();
+ buffer_.erase(0, nl + 1);
+ return 1;
+ }
+ if (buffer_.size() > maxLine) {
+ close();
+ return -1;
+ }
+ if (handle_ == kInvalid) return -1;
+ char chunk[16384];
+ long long got = 0;
+#if defined(_WIN32)
+ DWORD avail = 0;
+ if (!PeekNamedPipe(asHandle(handle_), nullptr, 0, nullptr, &avail, nullptr)) {
+ close();
+ return -1;
+ }
+ if (avail == 0) {
+ if (remainingMs(deadline) == 0) return 0;
+ Sleep(5);
+ continue;
+ }
+ OVERLAPPED ov{};
+ ov.hEvent = CreateEventW(nullptr, TRUE, FALSE, nullptr);
+ DWORD n = 0;
+ BOOL ok = ReadFile(asHandle(handle_), chunk, DWORD(std::min<size_t>(sizeof chunk, avail)), &n, &ov);
+ if (!ok && GetLastError() == ERROR_IO_PENDING) ok = GetOverlappedResult(asHandle(handle_), &ov, &n, TRUE);
+ CloseHandle(ov.hEvent);
+ if (!ok || n == 0) {
+ close();
+ return -1;
+ }
+ got = n;
+#else
+ pollfd p{int(handle_), POLLIN, 0};
+ const int r = ::poll(&p, 1, remainingMs(deadline));
+ if (r == 0) return 0;
+ if (r < 0) {
+ if (errno == EINTR) continue;
+ close();
+ return -1;
+ }
+ got = ::recv(int(handle_), chunk, sizeof chunk, 0);
+ if (got <= 0) {
+ if (got < 0 && (errno == EINTR || errno == EAGAIN)) continue;
+ close();
+ return -1;
+ }
+#endif
+ buffer_.append(chunk, size_t(got));
+ }
+}
+
+bool AiLinkConn::writeLine(const std::string& line) {
+ if (handle_ == kInvalid || line.find('\n') != std::string::npos) return false;
+ const std::string data = line + "\n";
+ size_t sent = 0;
+ while (sent < data.size()) {
+#if defined(_WIN32)
+ OVERLAPPED ov{};
+ ov.hEvent = CreateEventW(nullptr, TRUE, FALSE, nullptr);
+ DWORD n = 0;
+ BOOL ok = WriteFile(asHandle(handle_), data.data() + sent, DWORD(std::min<size_t>(data.size() - sent, 1 << 20)), &n, &ov);
+ if (!ok && GetLastError() == ERROR_IO_PENDING) ok = GetOverlappedResult(asHandle(handle_), &ov, &n, TRUE);
+ CloseHandle(ov.hEvent);
+ if (!ok) return false;
+#else
+#if defined(MSG_NOSIGNAL)
+ const ssize_t n = ::send(int(handle_), data.data() + sent, data.size() - sent, MSG_NOSIGNAL);
+#else
+ const ssize_t n = ::send(int(handle_), data.data() + sent, data.size() - sent, 0);
+#endif
+ if (n < 0 && errno == EINTR) continue;
+ if (n <= 0) return false;
+#endif
+ sent += size_t(n);
+ }
+ return true;
+}
+
+// ---------------------------------------------------------------------------
+// AiLinkListener
+// ---------------------------------------------------------------------------
+
+bool AiLinkListener::open(const std::string& endpoint, std::string& error) {
+ close();
+ if (endpoint.empty()) {
+ error = "no endpoint";
+ return false;
+ }
+#if defined(_WIN32)
+ const HANDLE h = createInstance(endpoint, true);
+ if (h == INVALID_HANDLE_VALUE) {
+ error = GetLastError() == ERROR_ACCESS_DENIED ? "another SculptForge window already offers live mode"
+ : "can't create the pipe (error " + std::to_string(GetLastError()) + ")";
+ return false;
+ }
+ pending_ = fromHandle(h);
+ event_ = fromHandle(CreateEventW(nullptr, TRUE, FALSE, nullptr));
+ handle_ = pending_;
+#else
+ sockaddr_un addr;
+ if (!fillAddress(endpoint, addr, error)) return false;
+ // A socket file left by a crashed app: nobody answers it, so it's replaced. A live one is another window's.
+ if (aiLinkFileMode(endpoint) >= 0) {
+ const int probe = ::socket(AF_UNIX, SOCK_STREAM, 0);
+ const bool live = probe >= 0 && ::connect(probe, reinterpret_cast<sockaddr*>(&addr), sizeof addr) == 0;
+ if (probe >= 0) ::close(probe);
+ if (live) {
+ error = "another SculptForge window already offers live mode";
+ return false;
+ }
+ ::unlink(endpoint.c_str());
+ }
+ const int fd = ::socket(AF_UNIX, SOCK_STREAM, 0);
+ if (fd < 0) {
+ error = std::string("socket: ") + std::strerror(errno);
+ return false;
+ }
+ ::fcntl(fd, F_SETFD, FD_CLOEXEC);
+ const mode_t old = ::umask(0177); // the socket file is born 0600 (no window where it is wider)
+ const int bound = ::bind(fd, reinterpret_cast<sockaddr*>(&addr), sizeof addr);
+ ::umask(old);
+ if (bound != 0 || ::chmod(endpoint.c_str(), 0600) != 0 || ::listen(fd, 2) != 0) {
+ error = std::string("can't listen on ") + endpoint + ": " + std::strerror(errno);
+ ::close(fd);
+ return false;
+ }
+ handle_ = fd;
+#endif
+ endpoint_ = endpoint;
+ return true;
+}
+
+bool AiLinkListener::accept(AiLinkConn& client, int timeoutMs, bool* refused) {
+ if (refused) *refused = false;
+ if (handle_ == AiLinkConn::kInvalid) return false;
+#if defined(_WIN32)
+ HANDLE pipe = asHandle(pending_);
+ HANDLE ev = asHandle(event_);
+ OVERLAPPED ov{};
+ ov.hEvent = ev;
+ ResetEvent(ev);
+ bool connected = false;
+ if (ConnectNamedPipe(pipe, &ov)) connected = true;
+ else if (GetLastError() == ERROR_PIPE_CONNECTED) connected = true;
+ else if (GetLastError() == ERROR_IO_PENDING) {
+ if (WaitForSingleObject(ev, DWORD(timeoutMs)) == WAIT_OBJECT_0) {
+ DWORD n = 0;
+ connected = GetOverlappedResult(pipe, &ov, &n, FALSE) != 0;
+ } else {
+ CancelIoEx(pipe, &ov);
+ DWORD n = 0;
+ GetOverlappedResult(pipe, &ov, &n, TRUE);
+ return false;
+ }
+ }
+ if (!connected) {
+ DisconnectNamedPipe(pipe);
+ return false;
+ }
+ // The connected instance becomes the client's; a fresh one waits for the next client.
+ client.close();
+ client.handle_ = pending_;
+ client.server_ = true;
+ const HANDLE next = createInstance(endpoint_, false);
+ pending_ = fromHandle(next);
+ handle_ = pending_;
+ return true;
+#else
+ pollfd p{int(handle_), POLLIN, 0};
+ if (::poll(&p, 1, timeoutMs) <= 0) return false;
+ const int fd = ::accept(int(handle_), nullptr, nullptr);
+ if (fd < 0) return false;
+ ::fcntl(fd, F_SETFD, FD_CLOEXEC);
+ if (!peerIsMe(fd)) {
+ ::close(fd);
+ if (refused) *refused = true;
+ return false;
+ }
+ client.close();
+ client.handle_ = fd;
+ return true;
+#endif
+}
+
+void AiLinkListener::close() {
+#if defined(_WIN32)
+ if (pending_ != AiLinkConn::kInvalid) CloseHandle(asHandle(pending_));
+ if (event_ != AiLinkConn::kInvalid) CloseHandle(asHandle(event_));
+ pending_ = event_ = handle_ = AiLinkConn::kInvalid;
+#else
+ if (handle_ != AiLinkConn::kInvalid) {
+ ::close(int(handle_));
+ ::unlink(endpoint_.c_str());
+ }
+ handle_ = AiLinkConn::kInvalid;
+#endif
+ endpoint_.clear();
+}
+
+bool aiLinkConnect(AiLinkConn& conn, const std::string& endpoint, std::string& error) {
+ conn.close();
+#if defined(_WIN32)
+ const HANDLE h = CreateFileW(widen(endpoint).c_str(), GENERIC_READ | GENERIC_WRITE, 0, nullptr, OPEN_EXISTING,
+ FILE_FLAG_OVERLAPPED | SECURITY_SQOS_PRESENT | SECURITY_IDENTIFICATION, nullptr);
+ if (h == INVALID_HANDLE_VALUE) {
+ error = GetLastError() == ERROR_PIPE_BUSY ? "SculptForge is already connected to another AI tool"
+ : "SculptForge isn't running, or live mode is off";
+ return false;
+ }
+ if (!serverIsMe(h)) {
+ CloseHandle(h);
+ error = "the live-mode pipe belongs to another user";
+ return false;
+ }
+ conn.handle_ = fromHandle(h);
+ return true;
+#else
+ sockaddr_un addr;
+ if (!fillAddress(endpoint, addr, error)) return false;
+ const int fd = ::socket(AF_UNIX, SOCK_STREAM, 0);
+ if (fd < 0) {
+ error = std::string("socket: ") + std::strerror(errno);
+ return false;
+ }
+ ::fcntl(fd, F_SETFD, FD_CLOEXEC);
+ if (::connect(fd, reinterpret_cast<sockaddr*>(&addr), sizeof addr) != 0) {
+ ::close(fd);
+ error = "SculptForge isn't running, or live mode is off";
+ return false;
+ }
+ if (!peerIsMe(fd)) { // (the folder is ours: only a bug could put another user's socket there)
+ ::close(fd);
+ error = "the live-mode socket belongs to another user";
+ return false;
+ }
+ conn.handle_ = fd;
+ return true;
+#endif
+}
+
+std::string base64Encode(const uint8_t* data, size_t size) {
+ static const char* const kAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+ std::string out;
+ out.reserve((size + 2) / 3 * 4);
+ for (size_t i = 0; i < size; i += 3) {
+ const uint32_t n = uint32_t(data[i]) << 16 | (i + 1 < size ? uint32_t(data[i + 1]) << 8 : 0) |
+ (i + 2 < size ? uint32_t(data[i + 2]) : 0);
+ out += kAlphabet[(n >> 18) & 63];
+ out += kAlphabet[(n >> 12) & 63];
+ out += i + 1 < size ? kAlphabet[(n >> 6) & 63] : '=';
+ out += i + 2 < size ? kAlphabet[n & 63] : '=';
+ }
+ return out;
+}
+
+} // namespace sf::link
diff --git a/src/link/AiLink.h b/src/link/AiLink.h
new file mode 100644
index 00000000..739f7e25
--- /dev/null
+++ b/src/link/AiLink.h
@@ -0,0 +1,87 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Live mode's channel (Preferences > AI > Let AI tools control this window): `sculptforge-cli --mcp --attach`
+// talks to the open app through a local endpoint only this user can open. No TCP or UDP port, no network
+// listener of any kind:
+// Linux / macOS: a Unix domain socket "ai-live.sock" (0600) in a folder only this user can enter (0700):
+// $XDG_RUNTIME_DIR/sculptforge, else $TMPDIR/sculptforge-<uid> ($SF_AI_LIVE_DIR/sculptforge first: tests
+// and isolated runs). The folder is refused when another
+// user owns it or anyone else can enter it; every connection's peer must be this user (SO_PEERCRED /
+// getpeereid).
+// Windows: the named pipe \\.\pipe\sculptforge-ai-live-<user>, its DACL granting the current user only,
+// created as the first instance (nobody can squat the name first) with remote clients rejected.
+// Messages are newline-delimited JSON, at most kAiLinkMaxLine bytes a line (longer: the connection closes).
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace sf::link {
+
+inline constexpr size_t kAiLinkMaxLine = 1u << 20; // client -> app (requests are small)
+inline constexpr size_t kAiLinkMaxReplyLine = 64u << 20; // app -> client (viewport images)
+
+// The endpoint this user's app listens on ("" with `error` set when the folder can't be made safe).
+std::string aiLinkEndpoint(std::string& error);
+
+// One connection: a socket (POSIX) or pipe handle (Windows).
+class AiLinkConn {
+public:
+ AiLinkConn() = default;
+ ~AiLinkConn() { close(); }
+ AiLinkConn(const AiLinkConn&) = delete;
+ AiLinkConn& operator=(const AiLinkConn&) = delete;
+ AiLinkConn(AiLinkConn&& o) noexcept;
+ AiLinkConn& operator=(AiLinkConn&& o) noexcept;
+
+ // 1: a line in `line` (without its newline); 0: none within `timeoutMs`; -1: closed, error or a line longer
+ // than `maxLine` (the connection is then closed).
+ int readLine(std::string& line, int timeoutMs, size_t maxLine = kAiLinkMaxLine);
+ bool writeLine(const std::string& line);
+ bool valid() const { return handle_ != kInvalid; }
+ void close();
+ // Unblocks a readLine waiting on another thread (the connection is closed afterwards by its owner).
+ void shutdown();
+
+ static constexpr intptr_t kInvalid = -1;
+ intptr_t handle_ = kInvalid;
+ bool server_ = false; // Windows: the app's end of the pipe (disconnect before closing)
+
+private:
+ std::string buffer_;
+};
+
+class AiLinkListener {
+public:
+ AiLinkListener() = default;
+ ~AiLinkListener() { close(); }
+ AiLinkListener(const AiLinkListener&) = delete;
+ AiLinkListener& operator=(const AiLinkListener&) = delete;
+
+ // Starts listening on `endpoint` (aiLinkEndpoint). A stale socket file left by a crashed app is replaced; a
+ // live one (another SculptForge window of this user) is not: false.
+ bool open(const std::string& endpoint, std::string& error);
+ // Waits up to `timeoutMs` for a client. False on timeout or error. On POSIX a peer that isn't this user is
+ // refused here (closed, false, `refused` set).
+ bool accept(AiLinkConn& client, int timeoutMs, bool* refused = nullptr);
+ void close();
+ bool valid() const { return handle_ != AiLinkConn::kInvalid; }
+ const std::string& endpoint() const { return endpoint_; }
+
+private:
+ intptr_t handle_ = AiLinkConn::kInvalid;
+ intptr_t pending_ = AiLinkConn::kInvalid; // Windows: the pipe instance waiting for a client
+ intptr_t event_ = AiLinkConn::kInvalid; // Windows: its overlapped connect event
+ std::string endpoint_;
+};
+
+// The CLI's side: connects to the app's endpoint. False with `error` (the app isn't running, or live mode is off).
+bool aiLinkConnect(AiLinkConn& conn, const std::string& endpoint, std::string& error);
+
+// POSIX: the permission bits of `path` (tests check 0600 / 0700), -1 if it doesn't exist. Windows: -1.
+int aiLinkFileMode(const std::string& path);
+
+std::string base64Encode(const uint8_t* data, size_t size);
+
+} // namespace sf::link
diff --git a/src/link/AiLinkSession.cpp b/src/link/AiLinkSession.cpp
new file mode 100644
index 00000000..1797b21a
--- /dev/null
+++ b/src/link/AiLinkSession.cpp
@@ -0,0 +1,370 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "link/AiLinkSession.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+#include <filesystem>
+#include <random>
+
+namespace sf::link {
+
+namespace fs = std::filesystem;
+
+namespace {
+
+fs::path toPath(const std::string& s) { return fs::path(std::u8string(s.begin(), s.end())); }
+
+std::string fromPath(const fs::path& p) {
+ const std::u8string u = p.generic_u8string();
+ return std::string(u.begin(), u.end());
+}
+
+// Absolute, with "." / ".." and symlinks resolved as far as the path exists. Relative paths are relative to the
+// project folder; with no project they can't be placed (empty).
+fs::path resolved(const std::string& path, const std::string& projectDir) {
+ std::error_code ec;
+ fs::path p = toPath(path);
+ if (p.is_relative()) {
+ if (projectDir.empty()) return {};
+ p = toPath(projectDir) / p;
+ }
+ fs::path r = fs::weakly_canonical(p, ec);
+ return ec ? p.lexically_normal() : r;
+}
+
+bool inside(const fs::path& path, const fs::path& folder) {
+ if (folder.empty() || path.empty()) return false;
+ auto f = folder.begin(), p = path.begin();
+ for (; f != folder.end(); ++f, ++p) {
+ if (f->empty()) continue; // a trailing separator
+ if (p == path.end() || *p != *f) return false;
+ }
+ return true;
+}
+
+bool isPathParam(const std::string& name) {
+ return name == "path" || name == "file" || name == "folder" || name == "out" || name == "dir" ||
+ name == "directory" || name == "output";
+}
+
+// Commands whose path argument is written (not read).
+bool writes(const std::string& name) {
+ static const char* const kWords[] = {"export", "save", "_send", "bake", "capture_", "pack_create"};
+ for (const char* w : kWords)
+ if (name.find(w) != std::string::npos) return true;
+ return false;
+}
+
+// A file a later program might run: an AI tool may not write one without asking.
+bool runnable(const fs::path& p) {
+ std::string ext = fromPath(p.extension());
+ std::transform(ext.begin(), ext.end(), ext.begin(), [](unsigned char c) { return char(std::tolower(c)); });
+ static const char* const kExt[] = {".exe", ".bat", ".cmd", ".com", ".ps1", ".vbs", ".js", ".sh", ".py", ".pl",
+ ".rb", ".desktop", ".so", ".dll", ".dylib", ".lnk", ".app", ".command", ".scr", ".msi"};
+ for (const char* e : kExt)
+ if (ext == e) return true;
+ const std::string file = fromPath(p.filename());
+ return !file.empty() && file[0] == '.'; // dot-files: shell profiles, configs
+}
+
+} // namespace
+
+// ---------------------------------------------------------------------------
+// Policy
+// ---------------------------------------------------------------------------
+
+void AiLinkPolicy::addPicked(const std::string& path) {
+ if (path.empty()) return;
+ const std::string p = fromPath(resolved(path, {}));
+ if (!p.empty() && std::find(picked.begin(), picked.end(), p) == picked.end()) picked.push_back(p);
+}
+
+bool AiLinkPolicy::hidden(const std::string& name) {
+ return name == "pack_install" || name == "pack_remove" || name == "pack_enable" || name == "pack_disable" ||
+ name == "ai_features";
+}
+
+bool AiLinkPolicy::allowedPath(const std::string& path) const {
+ const fs::path p = resolved(path, projectDir);
+ if (p.empty()) return false;
+ if (!projectDir.empty() && inside(p, resolved(projectDir, {}))) return true;
+ for (const std::string& pick : picked)
+ if (p == toPath(pick) || inside(p, toPath(pick))) return true;
+ return false;
+}
+
+AiDecision AiLinkPolicy::classify(const Command* cmd, const std::string& name, const Args& args) const {
+ if (hidden(name)) return {AiVerdict::Deny, "Unknown tool: " + name};
+ if (!cmd) return {}; // a live-window tool: the viewport, the camera, screen strokes
+
+ static const char* const kNetwork[] = {"image_to_3d", "text_to_3d", "brush_ai", "comfyui_check",
+ "brush_gallery_search", "brush_gallery_install", "unreal_editors",
+ "unreal_send"};
+ for (const char* n : kNetwork)
+ if (name == n) return {AiVerdict::Confirm, "Connects to the network"};
+ if (args.contains("url")) return {AiVerdict::Confirm, "Connects to the network"};
+ if (name == "macro_run" || name.rfind("script", 0) == 0 || name.rfind("python", 0) == 0)
+ return {AiVerdict::Confirm, "Runs a macro or script"};
+ if (name == "splat_train") return {AiVerdict::Confirm, "Runs outside programs (splat training)"};
+ if (name == "brush_delete" || name == "vdm_delete") return {AiVerdict::Confirm, "Deletes a file from your library"};
+
+ const bool writer = writes(name);
+ for (const auto& [key, value] : args) {
+ if (!isPathParam(key)) continue;
+ const std::string* s = std::get_if<std::string>(&value);
+ if (!s || s->empty()) continue;
+ const fs::path p = resolved(*s, projectDir);
+ const std::string shown = p.empty() ? *s : fromPath(p);
+ if (writer && !p.empty() && runnable(p)) return {AiVerdict::Confirm, "Writes a program or settings file: " + shown};
+ std::error_code ec;
+ if (writer && !p.empty() && fs::exists(p, ec) && !fs::is_directory(p, ec))
+ return {AiVerdict::Confirm, "Overwrites " + shown};
+ if (!allowedPath(*s))
+ return {AiVerdict::Confirm, std::string(writer ? "Writes " : "Reads ") + shown +
+ " (outside the project folder and the files you picked)"};
+ }
+ if (name == "save_project") {
+ const auto it = args.find("path");
+ if (it == args.end() || std::get_if<std::string>(&it->second) == nullptr || std::get<std::string>(it->second).empty())
+ return {AiVerdict::Confirm, "Saves over the project"};
+ }
+ return {};
+}
+
+// ---------------------------------------------------------------------------
+// Session
+// ---------------------------------------------------------------------------
+
+bool RateLimiter::take(double now) {
+ if (last_ >= 0.0) tokens_ = std::min(burst_, tokens_ + (now - last_) * rate_);
+ last_ = now;
+ if (tokens_ < 1.0) return false;
+ tokens_ -= 1.0;
+ return true;
+}
+
+AiLinkSession::AiLinkSession(std::string code) : code_(std::move(code)) {}
+
+AiLinkSession::Step AiLinkSession::reject(Step s) {
+ if (++rejected_ >= kMaxRejected) {
+ s.kind = Step::Kind::Close;
+ state_ = State::Closed;
+ }
+ return s;
+}
+
+AiLinkSession::Step AiLinkSession::handle(const std::string& line, double now) {
+ Step s;
+ if (state_ == State::Closed) return s;
+ Json msg;
+ std::string err;
+ if (!Json::parse(line, msg, err) || !msg.isObject()) {
+ s.kind = Step::Kind::Reply;
+ s.reply = errorReply(Json(), -32700, "Parse error");
+ return reject(std::move(s));
+ }
+
+ if (state_ == State::Hello) {
+ if (msg["hello"].asString() != "sculptforge-live") {
+ s.kind = Step::Kind::Close;
+ s.reply = R"({"error":"say hello first"})";
+ state_ = State::Closed;
+ return s;
+ }
+ client_ = sanitizeClientName(msg["client"].asString());
+ state_ = State::Pairing;
+ s.kind = Step::Kind::ShowApproval;
+ s.reply = R"({"pairing":"waiting"})";
+ return s;
+ }
+
+ if (state_ == State::Pairing) {
+ if (msg.has("pair")) {
+ if (sameCode(msg["pair"].asString(), code_)) {
+ s.kind = Step::Kind::Reply;
+ s.reply = approve();
+ return s;
+ }
+ if (--attemptsLeft_ <= 0) {
+ state_ = State::Closed;
+ s.kind = Step::Kind::Close;
+ s.reply = R"({"paired":false,"error":"wrong code: the connection is closed","attempts_left":0})";
+ return s;
+ }
+ Json r = Json::object();
+ r.set("paired", false);
+ r.set("error", "wrong code");
+ r.set("attempts_left", attemptsLeft_);
+ s.kind = Step::Kind::Reply;
+ s.reply = r.dump();
+ return s;
+ }
+ s.kind = Step::Kind::Reply;
+ s.reply = msg.has("id") ? errorReply(msg["id"], -32001, "Not approved yet: click Approve in SculptForge, or "
+ "send the code it shows")
+ : R"({"pairing":"waiting"})";
+ return reject(std::move(s));
+ }
+
+ // Paired: MCP requests.
+ if (!msg.has("id")) return s; // a notification
+ const Json& id = msg["id"];
+ const std::string method = msg["method"].asString();
+ s.kind = Step::Kind::Reply;
+ if (method == "ping") {
+ Json r = Json::object();
+ r.set("jsonrpc", "2.0");
+ r.set("id", id);
+ r.set("result", Json::object());
+ s.reply = r.dump();
+ return s;
+ }
+ if (method != "tools/list" && method != "tools/call") {
+ s.reply = errorReply(id, -32601, "Method not found: " + method);
+ return reject(std::move(s));
+ }
+ if (!limiter_.take(now)) {
+ s.reply = errorReply(id, -32000, "Too many requests: slow down");
+ return reject(std::move(s));
+ }
+ if (method == "tools/list") {
+ s.kind = Step::Kind::ListTools;
+ s.call.id = id;
+ return s;
+ }
+ s.call.id = id;
+ s.call.name = msg["params"]["name"].asString();
+ if (s.call.name.empty() || !jsonToArgs(msg["params"]["arguments"], s.call.args)) {
+ s.reply = errorReply(id, -32602, "Bad tool call");
+ return reject(std::move(s));
+ }
+ s.kind = Step::Kind::Execute; // the app classifies it (it knows the registry): AiLinkPolicy::classify
+ return s;
+}
+
+std::string AiLinkSession::approve() {
+ if (state_ != State::Pairing) return {};
+ state_ = State::Paired;
+ attemptsLeft_ = 0;
+ return R"({"paired":true})";
+}
+
+std::string AiLinkSession::deny() {
+ state_ = State::Closed;
+ return R"({"paired":false,"error":"the user declined the connection"})";
+}
+
+std::string AiLinkSession::listReply(const Json& id, Json tools) {
+ Json result = Json::object();
+ result.set("tools", std::move(tools));
+ Json r = Json::object();
+ r.set("jsonrpc", "2.0");
+ r.set("id", id);
+ r.set("result", std::move(result));
+ return r.dump();
+}
+
+std::string AiLinkSession::resultReply(const Json& id, bool ok, const std::string& text) {
+ Json t = Json::object();
+ t.set("type", "text");
+ t.set("text", text);
+ Json content = Json::array();
+ content.push(std::move(t));
+ return contentReply(id, std::move(content), !ok);
+}
+
+std::string AiLinkSession::contentReply(const Json& id, Json content, bool isError) {
+ Json result = Json::object();
+ result.set("content", std::move(content));
+ result.set("isError", isError);
+ Json r = Json::object();
+ r.set("jsonrpc", "2.0");
+ r.set("id", id);
+ r.set("result", std::move(result));
+ return r.dump();
+}
+
+std::string AiLinkSession::errorReply(const Json& id, int code, const std::string& message) {
+ Json e = Json::object();
+ e.set("code", code);
+ e.set("message", message);
+ Json r = Json::object();
+ r.set("jsonrpc", "2.0");
+ r.set("id", id);
+ r.set("error", std::move(e));
+ return r.dump();
+}
+
+std::string AiLinkSession::declinedReply(const Json& id, const std::string& name) {
+ return resultReply(id, false, "The user declined " + name + " in SculptForge. Don't retry it; ask them what to do instead.");
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+std::string makePairingCode() {
+ std::random_device rd; // the OS's random source
+ std::uniform_int_distribution<int> digit(0, 9);
+ std::string code;
+ for (int i = 0; i < 6; ++i) code += char('0' + digit(rd));
+ return code;
+}
+
+bool sameCode(const std::string& a, const std::string& b) {
+ // Spaces are ignored ("482 913" as the dialog shows it).
+ auto digits = [](const std::string& s) {
+ std::string d;
+ for (char c : s)
+ if (c != ' ') d += c;
+ return d;
+ };
+ const std::string x = digits(a), y = digits(b);
+ unsigned diff = unsigned(x.size() ^ y.size());
+ for (size_t i = 0; i < y.size(); ++i) diff |= unsigned(i < x.size() ? x[i] ^ y[i] : 0xff);
+ return diff == 0 && !y.empty();
+}
+
+std::string sanitizeClientName(const std::string& name) {
+ std::string out;
+ for (unsigned char c : name) {
+ if (out.size() >= 40) break;
+ if (c >= 0x20 && c < 0x7f) out += char(c);
+ }
+ return out.empty() ? "An AI tool" : out;
+}
+
+bool jsonToArgs(const Json& arguments, Args& out) {
+ out.clear();
+ if (arguments.isNull()) return true;
+ if (!arguments.isObject() || arguments.members().size() > 64) return false;
+ for (const auto& [key, value] : arguments.members()) {
+ if (value.isBool()) out[key] = value.asBool();
+ else if (value.isNumber()) out[key] = value.asNumber();
+ else if (value.isString()) out[key] = value.asString();
+ else out[key] = value.dump();
+ }
+ return true;
+}
+
+std::string describeArgs(const Args& args, size_t maxValue) {
+ std::string out;
+ for (const auto& [key, value] : args) {
+ std::string v;
+ if (const bool* b = std::get_if<bool>(&value)) v = *b ? "true" : "false";
+ else if (const double* d = std::get_if<double>(&value)) {
+ char buf[32];
+ std::snprintf(buf, sizeof buf, "%g", *d);
+ v = buf;
+ } else v = std::get<std::string>(value);
+ if (v.size() > maxValue) v = v.substr(0, maxValue) + "...";
+ for (char& c : v)
+ if (static_cast<unsigned char>(c) < 0x20) c = ' ';
+ out += (out.empty() ? "" : ", ") + key + "=" + v;
+ }
+ return out;
+}
+
+} // namespace sf::link
diff --git a/src/link/AiLinkSession.h b/src/link/AiLinkSession.h
new file mode 100644
index 00000000..e3094dd6
--- /dev/null
+++ b/src/link/AiLinkSession.h
@@ -0,0 +1,121 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Live mode's rules, one connection at a time (link/AiLink.h is the channel). Pure logic, no window or socket, so
+// the tests drive every path:
+// 1. Pairing. The client says hello; the app shows an Approve dialog with a one-time 6-digit code. The user
+// clicks Approve, or reads the code to the AI tool, which sends it back (3 tries, then the connection closes).
+// Approval lasts for this connection only. Before it, every request is refused.
+// 2. Requests are JSON-RPC (MCP tools/list, tools/call). They are data: a tool name is looked up, its arguments
+// become typed values; nothing is evaluated. A token bucket limits the rate; a flood closes the connection.
+// 3. The policy (AiLinkPolicy) sorts every call: allowed, asked first in the app (files outside the project
+// folder and what the user picked, overwrites, saving over the project, deleting library files, scripts and
+// macros, anything that reaches the network), or refused (packs, the AI switch).
+#pragma once
+
+#include "core/Commands.h"
+#include "core/Json.h"
+
+#include <string>
+#include <vector>
+
+namespace sf::link {
+
+enum class AiVerdict { Allow, Confirm, Deny };
+
+struct AiDecision {
+ AiVerdict verdict = AiVerdict::Allow;
+ std::string reason; // Confirm: what the dialog says ("Overwrites C:/x.glb"); Deny: the error
+};
+
+struct AiLinkPolicy {
+ std::string projectDir; // the saved project's folder ("" when none)
+ std::vector<std::string> picked; // files and folders the user chose in a file dialog this session
+
+ void addPicked(const std::string& path);
+ // `cmd` null: a live-window tool (viewport_image, view_set...), always allowed.
+ AiDecision classify(const Command* cmd, const std::string& name, const Args& args) const;
+ // Never offered to an AI tool: installing / switching packs and the AI switch stay the user's.
+ static bool hidden(const std::string& name);
+ // True when `path` is inside the project folder, is a picked file, or is inside a picked folder.
+ bool allowedPath(const std::string& path) const;
+};
+
+class RateLimiter {
+public:
+ RateLimiter(double perSecond, double burst) : rate_(perSecond), burst_(burst), tokens_(burst) {}
+ bool take(double now);
+
+private:
+ double rate_, burst_, tokens_, last_ = -1.0;
+};
+
+struct AiLinkCall {
+ Json id;
+ std::string name;
+ Args args;
+};
+
+class AiLinkSession {
+public:
+ enum class State { Hello, Pairing, Paired, Closed };
+
+ struct Step {
+ enum class Kind {
+ None, // nothing to do
+ Reply, // send `reply`
+ Close, // send `reply` (if any), then close the connection
+ ShowApproval, // show the Approve dialog (code(), client())
+ ListTools, // answer tools/list for `call.id` (listReply)
+ Execute, // run `call`, then send resultReply / contentReply
+ Confirm, // ask the user (`reason`), then Execute or send declinedReply
+ } kind = Kind::None;
+ std::string reply;
+ AiLinkCall call;
+ std::string reason;
+ };
+
+ explicit AiLinkSession(std::string code);
+
+ Step handle(const std::string& line, double now);
+ std::string approve(); // the user clicked Approve: the line to send
+ std::string deny(); // the user clicked Deny (or the dialog timed out): the line to send, then close
+
+ State state() const { return state_; }
+ const std::string& code() const { return code_; }
+ const std::string& client() const { return client_; }
+ int attemptsLeft() const { return attemptsLeft_; }
+
+ AiLinkPolicy policy;
+
+ static std::string listReply(const Json& id, Json tools);
+ static std::string resultReply(const Json& id, bool ok, const std::string& text);
+ static std::string contentReply(const Json& id, Json content, bool isError);
+ static std::string errorReply(const Json& id, int code, const std::string& message);
+ static std::string declinedReply(const Json& id, const std::string& name);
+
+ static constexpr int kCodeTries = 3;
+ static constexpr int kMaxRejected = 50; // refused or malformed messages before the connection closes
+
+private:
+ Step reject(Step s);
+
+ State state_ = State::Hello;
+ std::string code_, client_;
+ int attemptsLeft_ = kCodeTries;
+ int rejected_ = 0;
+ RateLimiter limiter_{10.0, 30.0};
+};
+
+// A fresh 6-digit code from the system's random source.
+std::string makePairingCode();
+// Compares without stopping at the first difference.
+bool sameCode(const std::string& a, const std::string& b);
+// What the client calls itself, shown in the dialog as data: printable characters only, at most 40.
+std::string sanitizeClientName(const std::string& name);
+// JSON arguments as command arguments (objects and arrays as their JSON text). False: not an object, or too many.
+bool jsonToArgs(const Json& arguments, Args& out);
+// "brush=Clay, radius=0.1": a call's arguments for the confirm dialog, each value cut to `maxValue` characters.
+std::string describeArgs(const Args& args, size_t maxValue = 80);
+
+} // namespace sf::link
diff --git a/tests/test_ai_link.cpp b/tests/test_ai_link.cpp
new file mode 100644
index 00000000..15a6dfa0
--- /dev/null
+++ b/tests/test_ai_link.cpp
@@ -0,0 +1,320 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Live mode's security (link/AiLink.h, link/AiLinkSession.h): requests before approval are refused, a wrong code is
+// refused (and three close the connection), the socket and its folder are this user's only, a disconnect is seen
+// at once, the policy asks before files outside the project / overwrites / scripts / network and refuses packs,
+// and the message parser survives garbage. Plus the agent tools (core/AgentTools.h).
+#include "TestHarness.h"
+
+#include "cli/McpAttach.h"
+#include "core/Commands.h"
+#include "link/AiLink.h"
+#include "link/AiLinkSession.h"
+
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <random>
+#include <sstream>
+#include <thread>
+
+using namespace sf;
+using namespace sf::link;
+
+namespace {
+
+using Kind = AiLinkSession::Step::Kind;
+
+std::string call(int id, const std::string& name, const std::string& args = "{}") {
+ return R"({"jsonrpc":"2.0","id":)" + std::to_string(id) + R"(,"method":"tools/call","params":{"name":")" + name +
+ R"(","arguments":)" + args + "}}";
+}
+
+AiLinkSession paired() {
+ AiLinkSession s("123456");
+ s.handle(R"({"hello":"sculptforge-live","v":1,"client":"Test"})", 0.0);
+ s.handle(R"({"pair":"123456"})", 0.0);
+ return s;
+}
+
+std::string scratchDir(const char* name) {
+ const std::string d = tempPath(name);
+ std::error_code ec;
+ std::filesystem::remove_all(d, ec);
+ std::filesystem::create_directories(d, ec);
+ return d;
+}
+
+} // namespace
+
+TEST(ai_link_refuses_requests_before_approval) {
+ AiLinkSession s("482913");
+ // No hello: closed.
+ AiLinkSession rude("482913");
+ CHECK(rude.handle(call(1, "mesh_info"), 0.0).kind == Kind::Close);
+ CHECK(rude.state() == AiLinkSession::State::Closed);
+
+ const auto hello = s.handle(R"({"hello":"sculptforge-live","v":1,"client":"Claude Code\u0007\n"})", 0.0);
+ CHECK(hello.kind == Kind::ShowApproval);
+ CHECK(s.client() == "Claude Code"); // control characters dropped: the dialog shows data, not markup
+ // Waiting for approval: tool calls are refused, never run.
+ for (const char* tool : {"mesh_info", "save_project", "macro_run"}) {
+ const auto st = s.handle(call(2, tool), 0.0);
+ CHECK(st.kind == Kind::Reply);
+ CHECK(st.reply.find("-32001") != std::string::npos);
+ }
+ CHECK(s.state() == AiLinkSession::State::Pairing);
+}
+
+TEST(ai_link_wrong_code_refused) {
+ AiLinkSession s("482913");
+ s.handle(R"({"hello":"sculptforge-live","v":1})", 0.0);
+ auto st = s.handle(R"({"pair":"000000"})", 0.0);
+ CHECK(st.kind == Kind::Reply && st.reply.find("\"paired\":false") != std::string::npos);
+ CHECK(s.attemptsLeft() == 2);
+ CHECK(s.handle(call(1, "mesh_info"), 0.0).reply.find("-32001") != std::string::npos);
+ st = s.handle(R"({"pair":"48291"})", 0.0); // a prefix isn't the code
+ CHECK(s.attemptsLeft() == 1);
+ st = s.handle(R"({"pair":"999999"})", 0.0);
+ CHECK(st.kind == Kind::Close); // three wrong codes: the connection closes
+ CHECK(s.state() == AiLinkSession::State::Closed);
+ // The right code after that changes nothing.
+ CHECK(s.handle(R"({"pair":"482913"})", 0.0).kind == Kind::None);
+
+ AiLinkSession ok("482913");
+ ok.handle(R"({"hello":"sculptforge-live","v":1})", 0.0);
+ CHECK(ok.handle(R"({"pair":"482 913"})", 0.0).reply == R"({"paired":true})");
+ CHECK(ok.state() == AiLinkSession::State::Paired);
+
+ AiLinkSession denied("482913");
+ denied.handle(R"({"hello":"sculptforge-live","v":1})", 0.0);
+ CHECK(denied.deny().find("declined") != std::string::npos);
+ CHECK(denied.handle(call(1, "mesh_info"), 0.0).kind == Kind::None);
+
+ CHECK(sameCode("123456", "123456"));
+ CHECK(!sameCode("", "123456"));
+ CHECK(!sameCode("1234567", "123456"));
+ const std::string a = makePairingCode(), b = makePairingCode();
+ CHECK(a.size() == 6 && a.find_first_not_of("0123456789") == std::string::npos);
+ CHECK(a != b || makePairingCode() != a); // (one in a million twice in a row)
+}
+
+TEST(ai_link_paired_requests_and_rate_limit) {
+ AiLinkSession s = paired();
+ CHECK(s.state() == AiLinkSession::State::Paired);
+ auto st = s.handle(R"({"jsonrpc":"2.0","id":7,"method":"tools/list"})", 0.0);
+ CHECK(st.kind == Kind::ListTools);
+ st = s.handle(call(8, "stroke", R"({"points":"0,0,0","radius":0.1,"invert":true,"nested":{"a":[1,2]}})"), 0.0);
+ CHECK(st.kind == Kind::Execute);
+ CHECK(st.call.name == "stroke");
+ CHECK(std::get<double>(st.call.args.at("radius")) == 0.1);
+ CHECK(std::get<bool>(st.call.args.at("invert")));
+ CHECK(std::get<std::string>(st.call.args.at("nested")) == R"({"a":[1,2]})"); // data, as text
+ CHECK(s.handle(R"({"jsonrpc":"2.0","id":9,"method":"resources/list"})", 0.0).reply.find("-32601") != std::string::npos);
+ // A burst past the bucket: refused with "slow down"; time refills it.
+ int limited = 0;
+ for (int i = 0; i < 40; ++i)
+ if (s.handle(call(100 + i, "mesh_info"), 1.0).reply.find("slow down") != std::string::npos) ++limited;
+ CHECK(limited > 0);
+ CHECK(s.handle(call(200, "mesh_info"), 10.0).kind == Kind::Execute);
+}
+
+TEST(ai_link_policy) {
+ CommandRegistry reg;
+ const std::string project = scratchDir("sf_ai_link_policy");
+ const std::string elsewhere = scratchDir("sf_ai_link_elsewhere");
+ { std::ofstream(project + "/old.glb") << "x"; }
+ AiLinkPolicy p;
+ p.projectDir = project;
+ auto verdict = [&](const std::string& name, const Args& a) { return p.classify(reg.find(name), name, a).verdict; };
+
+ CHECK(AiLinkPolicy::hidden("pack_install") && AiLinkPolicy::hidden("ai_features"));
+ CHECK(verdict("pack_install", {{"path", project + "/p.sfpack"}}) == AiVerdict::Deny);
+ CHECK(verdict("mesh_info", {}) == AiVerdict::Allow);
+ CHECK(p.classify(nullptr, "viewport_image", {}).verdict == AiVerdict::Allow);
+ // Files: inside the project folder fine, a new file there fine, an existing one asks (overwrite).
+ CHECK(verdict("export_glb", {{"path", project + "/new.glb"}}) == AiVerdict::Allow);
+ CHECK(verdict("export_glb", {{"path", std::string("relative.glb")}}) == AiVerdict::Allow);
+ CHECK(verdict("export_glb", {{"path", project + "/old.glb"}}) == AiVerdict::Confirm);
+ // Outside it (or escaping it with ..): asks, reading or writing.
+ CHECK(verdict("export_glb", {{"path", elsewhere + "/x.glb"}}) == AiVerdict::Confirm);
+ CHECK(verdict("open", {{"path", elsewhere + "/x.obj"}}) == AiVerdict::Confirm);
+ CHECK(verdict("open", {{"path", project + "/../sf_ai_link_elsewhere/x.obj"}}) == AiVerdict::Confirm);
+ // A picked file (or folder) is the user's choice.
+ p.addPicked(elsewhere + "/x.obj");
+ CHECK(verdict("open", {{"path", elsewhere + "/x.obj"}}) == AiVerdict::Allow);
+ CHECK(verdict("open", {{"path", elsewhere + "/y.obj"}}) == AiVerdict::Confirm);
+ // Programs and dot-files: always asked, even inside the project.
+ CHECK(verdict("export_glb", {{"path", project + "/run.sh"}}) == AiVerdict::Confirm);
+ CHECK(verdict("export_glb", {{"path", project + "/.bashrc"}}) == AiVerdict::Confirm);
+ // Saving over the project, scripts, network, deleting library files.
+ CHECK(verdict("save_project", {}) == AiVerdict::Confirm);
+ CHECK(verdict("macro_run", {{"name", std::string("x")}}) == AiVerdict::Confirm);
+ CHECK(AiLinkPolicy{}.classify(reg.find("mesh_info"), "image_to_3d", {}).verdict == AiVerdict::Confirm);
+ CHECK(verdict("brush_delete", {{"name", std::string("x")}}) == AiVerdict::Confirm);
+ CHECK(AiLinkPolicy{}.classify(reg.find("mesh_info"), "anything", {{"url", std::string("http://x")}}).verdict == AiVerdict::Confirm);
+ // No project: a relative path can't be placed, so it asks.
+ AiLinkPolicy none;
+ CHECK(none.classify(reg.find("export_glb"), "export_glb", {{"path", std::string("a.glb")}}).verdict == AiVerdict::Confirm);
+}
+
+TEST(ai_link_message_parser_fuzz) {
+ std::mt19937 rng(1234);
+ const std::string seeds[] = {call(1, "mesh_info"), R"({"pair":"123456"})", R"({"hello":"sculptforge-live"})",
+ R"({"jsonrpc":"2.0","id":1,"method":"tools/list"})"};
+ const std::string alphabet = "{}[]\":,0123456789abcdefnulltruefalse\\u \t\n\x01\xff";
+ for (int round = 0; round < 3000; ++round) {
+ AiLinkSession s = round % 2 ? paired() : AiLinkSession("123456");
+ std::string m = seeds[size_t(round) % 4];
+ const int edits = 1 + int(rng() % 8);
+ for (int e = 0; e < edits; ++e) {
+ const size_t at = m.empty() ? 0 : rng() % m.size();
+ switch (rng() % 3) {
+ case 0: m.insert(at, 1, alphabet[rng() % alphabet.size()]); break;
+ case 1: if (!m.empty()) m.erase(at, 1); break;
+ default: if (!m.empty()) m[at] = alphabet[rng() % alphabet.size()]; break;
+ }
+ }
+ const auto st = s.handle(m, 0.0); // must not crash or hang
+ if (round % 2 == 0) CHECK(st.kind != Kind::Execute && st.kind != Kind::ListTools); // never before approval
+ }
+ // Deep nesting and huge numbers of arguments are refused, not followed.
+ AiLinkSession s = paired();
+ CHECK(s.handle(std::string(100000, '[') + std::string(100000, ']'), 0.0).kind == Kind::Reply);
+ std::string many = "{";
+ for (int i = 0; i < 100; ++i) many += (i ? "," : "") + std::string("\"k") + std::to_string(i) + "\":1";
+ many += "}";
+ CHECK(s.handle(call(1, "mesh_info", many), 0.0).reply.find("Bad tool call") != std::string::npos);
+ // A flood of garbage closes the connection.
+ AiLinkSession flood("123456");
+ Kind last = Kind::None;
+ for (int i = 0; i < AiLinkSession::kMaxRejected; ++i) last = flood.handle("garbage", 0.0).kind;
+ CHECK(last == Kind::Close);
+}
+
+#if !defined(_WIN32)
+TEST(ai_link_socket_permissions_and_disconnect) {
+ // A runtime folder of our own for the test (the user's real one may have the app listening).
+ const std::string run = scratchDir("sf_ai_link_run");
+ const char* old = std::getenv("XDG_RUNTIME_DIR");
+ const std::string saved = old ? old : "";
+ setenv("XDG_RUNTIME_DIR", run.c_str(), 1);
+ std::string err;
+ const std::string endpoint = aiLinkEndpoint(err);
+ CHECK(!endpoint.empty());
+ CHECK(aiLinkFileMode(run + "/sculptforge") == 0700);
+
+ AiLinkListener listener;
+ CHECK(listener.open(endpoint, err));
+ CHECK(aiLinkFileMode(endpoint) == 0600);
+ // A second listener on the same endpoint (another window) is refused while the first one lives.
+ AiLinkListener second;
+ CHECK(!second.open(endpoint, err));
+ { // (its probe connection, already closed, waits in the first one's queue)
+ AiLinkConn probe;
+ CHECK(listener.accept(probe, 2000));
+ std::string none;
+ CHECK(probe.readLine(none, 2000) == -1);
+ }
+
+ AiLinkConn client, server;
+ CHECK(aiLinkConnect(client, endpoint, err));
+ bool refused = true;
+ CHECK(listener.accept(server, 2000, &refused));
+ CHECK(!refused); // same user
+ CHECK(client.writeLine(R"({"hello":"sculptforge-live"})"));
+ std::string line;
+ CHECK(server.readLine(line, 2000) == 1 && line == R"({"hello":"sculptforge-live"})");
+ // A line longer than the limit closes the connection.
+ std::thread big([&] { client.writeLine(std::string(kAiLinkMaxLine + 10, 'x')); }); // (fails once the app closes)
+ CHECK(server.readLine(line, 2000) == -1);
+ big.join();
+ CHECK(!server.valid());
+ // Disconnect: the other side sees it at once.
+ AiLinkConn c2, s2;
+ CHECK(aiLinkConnect(c2, endpoint, err));
+ CHECK(listener.accept(s2, 2000));
+ s2.shutdown();
+ s2.close();
+ CHECK(c2.readLine(line, 2000) == -1);
+
+ // A folder opened to others is closed again; one that isn't a folder is refused.
+ std::filesystem::permissions(run + "/sculptforge", std::filesystem::perms::all);
+ listener.close();
+ CHECK(!aiLinkEndpoint(err).empty());
+ CHECK(aiLinkFileMode(run + "/sculptforge") == 0700);
+ std::filesystem::remove_all(run + "/sculptforge");
+ { std::ofstream(run + "/sculptforge") << "x"; }
+ CHECK(aiLinkEndpoint(err).empty());
+ std::filesystem::remove(run + "/sculptforge");
+ // The socket file is gone after close; nobody's listening: the CLI says so.
+ CHECK(aiLinkFileMode(endpoint) == -1);
+ AiLinkConn c3;
+ CHECK(!aiLinkConnect(c3, endpoint, err));
+ if (old) setenv("XDG_RUNTIME_DIR", saved.c_str(), 1);
+ else unsetenv("XDG_RUNTIME_DIR");
+}
+
+TEST(ai_link_attach_end_to_end) {
+ // sculptforge-cli --mcp --attach against a stand-in app: live_connect waits, the code pairs, tools are forwarded.
+ const std::string run = scratchDir("sf_ai_link_attach");
+ const std::string endpoint = run + "/live.sock";
+ AiLinkListener listener;
+ std::string err;
+ CHECK(listener.open(endpoint, err));
+ std::thread app([&] {
+ AiLinkConn conn;
+ if (!listener.accept(conn, 5000)) return;
+ AiLinkSession s("314159");
+ std::string line;
+ while (conn.readLine(line, 5000) == 1) {
+ const auto st = s.handle(line, 0.0);
+ if (st.kind == Kind::ListTools) conn.writeLine(AiLinkSession::listReply(st.call.id, Json::array()));
+ else if (st.kind == Kind::Execute) conn.writeLine(AiLinkSession::resultReply(st.call.id, true, "ran " + st.call.name));
+ else if (!st.reply.empty()) conn.writeLine(st.reply);
+ if (st.kind == Kind::Close) break;
+ }
+ });
+ std::stringstream in, out;
+ in << R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"Tester"}}})" << "\n"
+ << call(2, "mesh_info") << "\n" // not connected yet
+ << call(3, "live_connect", R"({"code":"000000"})") << "\n" // wrong code
+ << call(4, "live_connect", R"({"code":"314159"})") << "\n" // right code
+ << call(5, "mesh_info") << "\n"
+ << call(6, "live_disconnect") << "\n"
+ << call(7, "mesh_info") << "\n";
+ runMcpAttach(in, out, endpoint);
+ app.join();
+ const std::string o = out.str();
+ CHECK(o.find("Not connected to SculptForge: call live_connect first") != std::string::npos);
+ CHECK(o.find("wrong code") != std::string::npos);
+ CHECK(o.find("Connected to SculptForge") != std::string::npos);
+ CHECK(o.find("ran mesh_info") != std::string::npos);
+ CHECK(o.find("notifications/tools/list_changed") != std::string::npos);
+ CHECK(o.rfind("Not connected to SculptForge") > o.find("ran mesh_info")); // after Disconnect, refused again
+}
+#endif
+
+TEST(agent_tools_blockout_measure_overview) {
+ CommandRegistry reg;
+ Document doc;
+ CommandResult r = reg.execute(doc, "blockout",
+ {{"spheres", std::string("0,0,0,0.6,-1 | 0,0.9,0.1,0.4,0 | 0.5,0.2,0,0.25,0")},
+ {"name", std::string("Body")},
+ {"resolution", 64.0}});
+ CHECK(r.ok);
+ CHECK(doc.findPart("Body") >= 0);
+ CHECK(doc.mesh.triangleCount() > 0); // the skinned Part is active
+ r = reg.execute(doc, "measure", {});
+ CHECK(r.ok && r.message.find("proportions") != std::string::npos);
+ r = reg.execute(doc, "measure", {{"compare", std::string("Body")}});
+ CHECK(r.ok && r.message.find("ratio") != std::string::npos);
+ r = reg.execute(doc, "measure", {{"from", std::string("0,0,0")}, {"to", std::string("3,4,0")}});
+ CHECK(r.ok && r.message.find("Distance 5") == 0);
+ r = reg.execute(doc, "scene_overview", {});
+ CHECK(r.ok && r.message.find("Body") != std::string::npos && r.message.find("active") != std::string::npos);
+ CHECK(!reg.execute(doc, "blockout", {{"spheres", std::string("0,0,0,-1")}}).ok);
+ CHECK(!reg.execute(doc, "blockout", {{"spheres", std::string("0,0,0,1 | 1,0,0,1,5")}}).ok);
+ CHECK(!reg.execute(doc, "measure", {{"part", std::string("Nope")}}).ok);
+}
diff --git a/tests/ui/ai_live.sfui b/tests/ui/ai_live.sfui
new file mode 100644
index 00000000..a7c76429
--- /dev/null
+++ b/tests/ui/ai_live.sfui
@@ -0,0 +1,76 @@
+# Live mode (PanelAiLink.cpp): Preferences > AI > Let AI tools control this window. Off by default; a scripted AI
+# tool over the real local socket / pipe: refused before approval, a wrong code refused, the right code (or Approve)
+# connects, the badge shows, a step outside the project asks first, every step is in Undo labelled "AI:",
+# Disconnect cuts it, and turning AI features off stops it.
+run ui_look look=classic layout=classic
+run new_sphere subdivisions=3
+expect_value ai_link_state == 0
+click "Preferences##palette.preferences"
+click "AI##preferences.ai"
+expect_text "Let AI tools control this window"
+click "Let AI tools control this window##prefs.ai_live"
+expect_value ai_link_state == 1
+shot ai-live-prefs
+click "Preferences##palette.preferences"
+
+# Before approval nothing runs; a wrong code is refused.
+ai_client connect
+ai_client send {"hello":"sculptforge-live","v":1,"client":"Claude Code"}
+wait_value ai_link_state == 2 5
+ai_client expect waiting
+ai_client send {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"new_sphere","arguments":{}}}
+ai_client expect -32001
+ai_client send {"pair":"000000"}
+ai_client expect attempts_left
+expect_text "Let an AI tool control this window?"
+expect_text "Claude Code"
+shot ai-live-approve
+click "Approve##ailink"
+ai_client expect paired":true
+wait_value ai_link_state == 3 5
+
+# Connected: the badge; the tools include the live ones; a step lands in Undo as "AI: ...".
+ai_client send {"jsonrpc":"2.0","id":2,"method":"tools/list"}
+ai_client expect viewport_image
+ai_client send {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"view_set","arguments":{"preset":"three_quarter","frame":"all"}}}
+ai_client expect "Camera: yaw 35"
+ai_client send {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"stroke_screen","arguments":{"points":"0.4,0.45 0.5,0.4 0.6,0.45","brush":"Clay Buildup","radius":0.06,"strength":0.8}}}
+ai_client expect id":4,
+ai_client send {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"viewport_image","arguments":{"size":256}}}
+ai_client expect image/png
+expect_text "AI connected: Claude Code"
+expect_value undo_ai == 1
+shot ai-live-badge
+
+# Outside the project: asks first. Deny tells the tool not to retry.
+ai_client send {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"export_glb","arguments":{"path":"/tmp/elsewhere/out.glb"}}}
+wait_value ai_link_state == 4 5
+expect_text "Allow this AI step?"
+expect_text "outside the project folder"
+shot ai-live-confirm
+click "Deny##ailinkconfirm"
+ai_client expect "declined export_glb"
+wait_value ai_link_state == 3 5
+
+# Packs and the AI switch are never offered.
+ai_client send {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"ai_features","arguments":{"on":false}}}
+ai_client expect "Unknown tool: ai_features"
+expect_value ai_enabled == 1
+
+# The kill switch.
+click "Disconnect##ailink"
+wait_value ai_link_state == 1 5
+expect_status "AI tool disconnected"
+ai_client close
+
+# AI features off: live mode stops (and the switch is hidden).
+ai_client connect
+ai_client send {"hello":"sculptforge-live","v":1,"client":"Again"}
+wait_value ai_link_state == 2 5
+run ai_features on=false
+expect_value ai_link_state == 0
+click "Preferences##palette.preferences"
+expect_not "Let AI tools control this window##prefs.ai_live"
+ai_client close
+run ai_features on=true
+expect_value ai_link_state == 1 # (the switch stays on: back with AI)