Merge pull request #13396 from davidmann4/integration-mcp

Integration batch MCP: agents in the open PhotoCraft window, one switch in the ArtCraft Launcher (#11363, #5525)
This commit is contained in:
David Mann authored and GitHub committed 2026-11-13 17:41:24 +01:00
commit de93ee2d38
55 files changed
+2992 -259

No files matched your search

+2
View File
@@ -161,6 +161,8 @@ cargo xtask test-corpus # if you touched psd, io, codecs, compose, gpu, text
While iterating, run less and keep the full commands above as the final gate: `cargo test -p <crate> --lib --tests` skips the examples and doctests plain `cargo test` builds every time (ui-egui has 11 examples), and `cargo test -p <crate> --test <file>` runs one integration-test file. `cargo nextest run` runs tests in parallel across binaries; see `docs/development.md` › Faster test loops.
**MCP in tests and agent sessions: `photocraft-cli mcp --headless`.** Plain `photocraft-cli mcp` works in the open PhotoCraft window while the ArtCraft Launcher's agents switch is on, and then may start PhotoCraft on the developer's machine when it is closed. Scripts, tests and agents that want a session without a window pass `--headless` (or use `photocraft-cli serve`); a test that runs the CLI also gives it its own settings, launcher and flags folders (`PHOTOCRAFT_CONFIG_DIR`, `CRAFT_MCP_DIR`, `CRAFT_FLAGS_FILE`, as `crate::command()` in `apps/photocraft-cli/tests/it/main.rs` does). To drive the running app on purpose, use `--control` (`docs/development.md`).
**Test corpora.** Real-file corpora live in `corpus/` (gitignored, never committed), fetched at pinned commits and sha256-verified by `cargo xtask corpus --all`: our Photoshop- and GIMP-authored oracles from https://github.com/storytold/photocraft-corpus plus psd-tools, ag-psd and PngSuite from their upstreams. Pins: `xtask/src/corpus_pins.rs`. The corpus tests are opt-in (cargo feature `corpus`): plain `cargo test` skips them, and with the feature on a missing corpus fails ("run `cargo xtask corpus --all`"). `cargo xtask test-corpus` fetches and runs them all. CI always runs them (the `corpus` job, cached by pin). Never commit corpus files; new oracles go to photocraft-corpus (its `AGENTS.md`), then a pin bump here. Details: `docs/development.md` › Test corpora.
Commands must **never panic** on bad input (Rule 9): every `run` closure and the code it calls returns `Err`, not a panic, for any params or document state. New commands come with a graceful-failure test (empty/out-of-range/wrong-type params → `Err`, not a crash).
Generated
+69
View File
@@ -1426,6 +1426,24 @@ dependencies = [
"libc",
]
[[package]]
name = "craft-ai-agents"
version = "0.1.0"
source = "git+https://github.com/storytold/craft-ai-integrations?rev=35e0352666a117407d62230a6c6c2366f3e21a3b#35e0352666a117407d62230a6c6c2366f3e21a3b"
dependencies = [
"dirs",
"serde",
"serde_json",
]
[[package]]
name = "craft-atomic"
version = "0.1.0"
source = "git+https://github.com/storytold/craft-libs?rev=86d6e8c5b05a4dadc35ff1c8e5d2f992c687ee97#86d6e8c5b05a4dadc35ff1c8e5d2f992c687ee97"
dependencies = [
"rustix 1.1.5",
]
[[package]]
name = "craft-docpath"
version = "0.1.0"
@@ -1447,6 +1465,16 @@ dependencies = [
"serde_json",
]
[[package]]
name = "craft-flags"
version = "0.1.0"
source = "git+https://github.com/storytold/craft-libs?rev=86d6e8c5b05a4dadc35ff1c8e5d2f992c687ee97#86d6e8c5b05a4dadc35ff1c8e5d2f992c687ee97"
dependencies = [
"craft-atomic",
"dirs",
"toml_edit",
]
[[package]]
name = "craft-fonts-build"
version = "0.1.0"
@@ -1841,6 +1869,27 @@ dependencies = [
"crypto-common 0.2.2",
]
[[package]]
name = "dirs"
version = "7.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8d57d423b3c82e89b9a24ca3091fee61f456a26edbd28d26c65906f4bc1dcd8f"
dependencies = [
"dirs-sys",
]
[[package]]
name = "dirs-sys"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
dependencies = [
"libc",
"option-ext",
"redox_users",
"windows-sys 0.59.0",
]
[[package]]
name = "dispatch"
version = "0.2.0"
@@ -5166,6 +5215,12 @@ version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7e036b411754132fd6b74e94b74e9a13c5cf606fa93d1885c35860d3060820b1"
[[package]]
name = "option-ext"
version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
[[package]]
name = "orbclient"
version = "0.3.55"
@@ -5440,6 +5495,7 @@ dependencies = [
"chrono",
"clap",
"core-graphics2",
"craft-flags",
"craft-update",
"dispatch2",
"eframe",
@@ -5516,6 +5572,8 @@ dependencies = [
"base64 0.23.1",
"cap-std",
"clap",
"craft-ai-agents",
"craft-flags",
"craft-psd",
"getrandom 0.3.4",
"hmac",
@@ -6641,6 +6699,16 @@ dependencies = [
"bitflags 2.13.2",
]
[[package]]
name = "redox_users"
version = "0.5.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "60dc65c0ff1a7ae1294b0c67b9f14baf70b644404010370171787bfac1038fc0"
dependencies = [
"libredox",
"thiserror 2.0.21",
]
[[package]]
name = "ref-cast"
version = "1.0.27"
@@ -8223,6 +8291,7 @@ dependencies = [
"indexmap",
"toml_datetime",
"toml_parser",
"toml_writer",
"winnow",
]
+6
View File
@@ -11,6 +11,12 @@ rust-version = "1.95"
[workspace.dependencies]
craft-ui = { git = "https://github.com/storytold/craft-libs", rev = "6e03f65bf45181db77ba6229716e6624db9eb25b", features = ["serde"] }
# Feature flags shared with the launcher and the other Craft apps (craft-libs#1118, #1119).
craft-flags = { git = "https://github.com/storytold/craft-libs", rev = "86d6e8c5b05a4dadc35ff1c8e5d2f992c687ee97" }
# The ArtCraft Launcher's agents switch and app list, shared with the launcher, the MCP gateway and
# every Craft app (storytold/craft-ai-integrations#195). Pinned to the head of
# storytold/craft-ai-integrations#197 until it merges.
craft-ai-agents = { git = "https://github.com/storytold/craft-ai-integrations", rev = "35e0352666a117407d62230a6c6c2366f3e21a3b" }
# internal
photocraft-geom = { path = "crates/geom" }
photocraft-color = { path = "crates/color" }
+5 -1
View File
@@ -242,10 +242,14 @@ photocraft-cli batch --actions grade.json --in ./raw --out ./graded
# Every subcommand explains itself
photocraft-cli batch --help
# Let an agent drive it over MCP (headless, or bridged to the running app)
# Let an agent drive it over MCP: the open window while agents are allowed, otherwise headless
photocraft-cli mcp
# Always without a window (scripts, tests)
photocraft-cli mcp --headless
```
To let Claude or another AI app drive the open PhotoCraft window without a terminal, turn on **ArtCraft Launcher › Settings › AI agents** and click **Add** next to the AI app (one entry for every Craft app). See [`docs/mcp.md`](docs/mcp.md). These settings are behind the Craft suite's `AI-MCP` feature flag: set `AI-MCP = true` in `ArtCraft/flags.toml`, or start PhotoCraft with `CRAFT_FLAGS=AI-MCP`.
The desktop app also offers an authenticated, loopback-only control channel (`photocraft --control`) for inspecting UI state, driving tools with pointer events, and taking offscreen screenshots. Every image in this README was rendered that way. See [`docs/control-protocol.md`](docs/control-protocol.md).
## Under the hood
+51 -5
View File
@@ -270,13 +270,24 @@ pub(crate) struct CommandsArgs {
pub(crate) filter: Option<String>,
}
/// Run the MCP server on stdio (headless engine, or bridge to a running `photocraft --control <port>`)
/// Run the MCP server on stdio: in the open PhotoCraft window when the person lets agents use it
/// (ArtCraft Launcher › Settings › AI agents), otherwise headless
///
/// Headless: each automation root grants that direction of file access; an omitted root denies it.
/// Prefer absolute root paths in MCP client configurations. Bridge: set the roots on the desktop
/// app; root flags are refused. The token flags require --bridge (or PHOTOCRAFT_CONTROL_PORT).
/// The open window is found again on every call, with no port or token to configure. Without
/// the person's consent, or with --headless, it runs headless: each automation root grants that
/// direction of file access; an omitted root denies it. Prefer absolute root paths in MCP client
/// configurations. Bridge (--bridge or PHOTOCRAFT_CONTROL_PORT): a running `photocraft --control
/// <port>`; set the roots on the desktop app, root flags are refused, and the token flags require
/// it.
#[derive(Args)]
pub(crate) struct McpArgs {
/// Always work headless, without the open window
#[arg(long, conflicts_with = "when_closed")]
pub(crate) headless: bool,
/// While agents may use PhotoCraft but it is closed: start it, serve a headless session, or
/// fail (default: the app's When PhotoCraft Is Closed setting)
#[arg(long, value_name = "launch|headless|error", value_parser = when_closed)]
pub(crate) when_closed: Option<photocraft_engine::prefs::WhenAppClosed>,
/// Bridge to the PhotoCraft app listening here instead of a headless engine; a bare port means
/// 127.0.0.1:<PORT>
#[arg(long, value_name = "127.0.0.1:PORT", env = "PHOTOCRAFT_CONTROL_PORT", value_parser = bridge)]
@@ -337,6 +348,8 @@ enum ValueError {
/// Why a `--bridge` value, or a PHOTOCRAFT_CONTROL_PORT value for `mcp`, is refused.
#[error("expected a port, 0-65535 (--bridge also takes 127.0.0.1:<PORT>)")]
Bridge,
#[error("expected launch, headless or error")]
WhenClosed,
}
/// Why `parse` refuses `mcp` or `serve` options clap accepted: clap prints it as a usage error
@@ -360,13 +373,19 @@ enum ServerOptionError {
/// A token flag without the bridge or port that reads it would be ignored (#8035).
#[error("{flag} requires {transport}")]
NeedsTransport { flag: &'static str, transport: &'static str },
/// `--headless` never reaches an app.
#[error("--headless works without the app; {0} is for --bridge")]
HeadlessBridge(&'static str),
/// `--when-closed` is about the open app, which a bridge names itself.
#[error("--when-closed is for the open window; --bridge names the app itself")]
BridgeWhenClosed,
}
impl ServerOptionError {
fn into_clap(self, cmd: &mut clap::Command) -> clap::Error {
let kind = match self {
Self::BridgeVar(_) | Self::GpuVar(_) => ErrorKind::ValueValidation,
Self::BridgeRoots | Self::BridgeGpu => ErrorKind::ArgumentConflict,
Self::BridgeRoots | Self::BridgeGpu | Self::HeadlessBridge(_) | Self::BridgeWhenClosed => ErrorKind::ArgumentConflict,
Self::NeedsTransport { .. } => ErrorKind::MissingRequiredArgument,
};
cmd.error(kind, self)
@@ -394,6 +413,10 @@ fn tiff_compression(s: &str) -> Result<TiffCompression, ValueError> {
}
}
fn when_closed(s: &str) -> Result<photocraft_engine::prefs::WhenAppClosed, ValueError> {
photocraft_engine::prefs::WhenAppClosed::parse(s).ok_or(ValueError::WhenClosed)
}
fn on_off(s: &str) -> Result<bool, ValueError> {
match s {
"on" => Ok(true),
@@ -474,6 +497,11 @@ fn steps(m: &ArgMatches) -> Vec<Step> {
/// stray.psd --help`): clap reports the mistake first.
pub(crate) fn parse(args: &[OsString]) -> Result<Cli, clap::Error> {
let mut cmd = Cli::command().mut_subcommands(|sub| sub.mut_args(blank_env_is_unset));
// `mcp --headless` reaches no app: a PHOTOCRAFT_CONTROL_PORT exported for another tool is not
// read, so a value it couldn't use anyway doesn't stop it.
if args.first().is_some_and(|a| a == "mcp") && args.iter().take_while(|a| *a != "--").any(|a| a == "--headless") {
cmd = cmd.mut_subcommand("mcp", |sub| sub.mut_arg("bridge", |arg| arg.env(None::<&str>)));
}
let argv = std::iter::once(OsString::from("photocraft-cli")).chain(args.iter().cloned());
let matches = match cmd.try_get_matches_from_mut(argv) {
Err(e) if args.iter().take_while(|a| *a != "--").any(|a| *a == "--help" || *a == "-h") => {
@@ -490,6 +518,21 @@ pub(crate) fn parse(args: &[OsString]) -> Result<Cli, clap::Error> {
check_gpu_env(&mut cmd, m)?;
}
(Command::Mcp(a), Some((name, m))) => {
if a.headless {
// `--headless` reaches no app. Given on the command line, the bridge's flags
// conflict; exported for another tool, they are left alone.
for (id, flag) in [("bridge", "--bridge"), ("control_token", "--control-token"), ("control_token_file", "--control-token-file")] {
if m.value_source(id) == Some(ValueSource::CommandLine) {
if let Some(sub) = cmd.find_subcommand_mut(name) {
return Err(ServerOptionError::HeadlessBridge(flag).into_clap(sub));
}
return Err(ServerOptionError::HeadlessBridge(flag).into_clap(&mut cmd));
}
}
a.bridge = None;
check_gpu_env(&mut cmd, m)?;
return Ok(cli);
}
a.bridge_from_env = from_env(m, "bridge");
if a.bridge_from_env
&& let Some(Bridge::Addr(v)) = &a.bridge
@@ -516,6 +559,9 @@ pub(crate) fn parse(args: &[OsString]) -> Result<Cli, clap::Error> {
return Err(ServerOptionError::BridgeGpu.into_clap(sub));
}
check_server(sub, m, a.bridge.is_some(), "--bridge")?;
if a.bridge.is_some() && a.when_closed.is_some() {
return Err(ServerOptionError::BridgeWhenClosed.into_clap(sub));
}
}
if a.bridge.is_none() {
check_gpu_env(&mut cmd, m)?;
+31
View File
@@ -68,8 +68,12 @@ pub(crate) fn serve(a: &ServeArgs, err: &mut dyn Write) -> Result {
}
}
/// `mcp`: with the suite's `AI-MCP` flag, the open window when agents may use it, otherwise
/// headless (`mcp_live`); without the flag headless, as before it; `--headless` always headless;
/// `--bridge` (or PHOTOCRAFT_CONTROL_PORT) a `photocraft --control` app.
pub(crate) fn mcp(a: &McpArgs, err: &mut dyn Write) -> Result {
let server = match &a.bridge {
None if !a.headless && photocraft_automation::agent_link::mcp_flag() => PhotocraftMcp::live(live_config(a)?),
Some(addr) => {
if a.bridge_from_env {
// Name the mode switch, as `serve` does: the way back to headless is to unset it.
@@ -94,3 +98,30 @@ pub(crate) fn mcp(a: &McpArgs, err: &mut dyn Write) -> Result {
let rt = tokio::runtime::Builder::new_multi_thread().enable_all().build()?;
Ok(rt.block_on(server.serve_stdio())?)
}
/// `mcp`: the app's settings folder, the closed-app override, the app launcher, and the headless
/// session's roots and rendering for when it works without the window.
fn live_config(a: &McpArgs) -> Result<photocraft_automation::live::LiveConfig> {
let other = |m: &str| crate::CliError::Other(m.to_string());
let dir = photocraft_automation::app_dirs::from_env()
.dir
.ok_or_else(|| other("can't find PhotoCraft's settings folder (no home folder; set PHOTOCRAFT_CONFIG_DIR)"))?;
let mut config = photocraft_automation::live::LiveConfig::new(dir);
config.when_closed = a.when_closed;
// As a headless `mcp` always did: folders that can't be opened stop the start, before the
// server answers anything, rather than at the first call that would fall back to them.
a.automation.workspace()?;
config.read_roots.clone_from(&a.automation.automation_read_root);
config.write_root = a.automation.automation_write_root.clone();
config.launch = std::env::current_exe().ok().and_then(|exe| photocraft_automation::live::launcher(&exe));
let policy = crate::gpu::GpuPolicy::from_args(&a.gpu).map_err(crate::CliError::Other)?;
config.prepare_headless = Some(Box::new(move |h| {
policy.apply_to_headless(h);
// stdout carries the protocol; the warnings a headless start has go to stderr.
let mut err = std::io::stderr();
for d in h.drain_diagnostics() {
let _ = writeln!(err, "warning: {d}");
}
}));
Ok(config)
}
+93 -1
View File
@@ -8,7 +8,7 @@ use serde_json::{Value, json};
/// The binary, without the variables `mcp` and `serve` fall back to: a test that wants one sets it.
fn bin() -> Command {
let mut cmd = Command::new(crate::binary());
let mut cmd = crate::command();
for var in ENV_VARS {
cmd.env_remove(var);
}
@@ -2029,3 +2029,95 @@ fn info_detail_adds_text_runs_and_antialiasing() {
assert!(text["runs"].as_array().is_some_and(|r| !r.is_empty()), "{text}");
let _ = std::fs::remove_dir_all(&dir);
}
/// Flags that don't go together are usage errors before anything starts. Adding PhotoCraft to an
/// MCP client is the ArtCraft Launcher's job, so there is no `mcp install`, and plain `mcp` does
/// what `--live` did, so there is no `--live` either.
#[test]
fn mcp_rejects_mismatched_flags() {
for (args, needle) in [
(&["mcp", "install"][..], "install"),
(&["mcp", "--live"], "--live"),
(&["mcp", "--client", "json"], "--client"),
(&["mcp", "--headless", "--bridge", "127.0.0.1:1"], "--bridge"),
(&["mcp", "--headless", "--control-token-file", "t"], "--control-token-file"),
(&["mcp", "--headless", "--when-closed", "launch"], "--when-closed"),
(&["mcp", "--when-closed", "sometimes"], "sometimes"),
(&["mcp", "--bridge", "127.0.0.1:1", "--when-closed", "error"], "--when-closed"),
] {
let o = bin().args(args).stdin(Stdio::null()).output().unwrap();
let err = String::from_utf8_lossy(&o.stderr);
assert_eq!(o.status.code(), Some(2), "{args:?}: {err}");
assert!(err.contains(needle), "{args:?}: {err}");
}
}
/// One MCP exchange with `photocraft-cli mcp <args>`: initialize, then each tool call; returns the
/// tool results.
fn mcp_session(args: &[&str], env: &[(&str, &std::ffi::OsStr)], calls: &[(&str, Value)]) -> Vec<Value> {
let mut cmd = bin();
cmd.args(args).stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::null());
for (k, v) in env {
cmd.env(k, v);
}
let mut child = cmd.spawn().unwrap();
let mut stdin = child.stdin.take().unwrap();
let mut stdout = BufReader::new(child.stdout.take().unwrap());
let mut send = |v: Value| {
writeln!(stdin, "{v}").unwrap();
stdin.flush().unwrap();
};
let mut recv = |id: u64| -> Value {
loop {
let mut line = String::new();
assert!(stdout.read_line(&mut line).unwrap() > 0, "server closed");
let v: Value = serde_json::from_str(&line).unwrap();
if v["id"] == id {
return v;
}
}
};
send(json!({"jsonrpc":"2.0","id":1,"method":"initialize","params":{
"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}));
recv(1);
send(json!({"jsonrpc":"2.0","method":"notifications/initialized"}));
let mut out = Vec::new();
for (i, (name, arguments)) in calls.iter().enumerate() {
let id = 2 + i as u64;
send(json!({"jsonrpc":"2.0","id":id,"method":"tools/call","params":{"name":name,"arguments":arguments}}));
out.push(recv(id)["result"].clone());
}
drop(stdin);
let _ = child.kill();
let _ = child.wait();
out
}
/// Plain `mcp` without the person's consent works headless, as it always did: commands run, UI
/// tools say they need the open app. `--headless` too, and it doesn't read a PHOTOCRAFT_CONTROL_PORT
/// exported for another tool (here not even a port).
#[test]
fn mcp_without_consent_works_headless() {
let dir = tmp("mcp-plain");
let empty = tmp("mcp-plain-launcher");
// `crate::command()` keeps the machine's launcher and flags out already; this test names its
// own settings and an empty launcher folder as well, to say what it relies on.
let env = [("PHOTOCRAFT_CONFIG_DIR", dir.as_os_str()), ("CRAFT_MCP_DIR", empty.as_os_str())];
let calls = [("command_list", json!({})), ("ui_inspect", json!({}))];
let r = mcp_session(&["mcp", "--when-closed", "error"], &env, &calls);
assert_ne!(r[0]["isError"], true, "headless commands run: {}", r[0]);
assert_eq!(r[1]["isError"], true, "{}", r[1]);
assert!(r[1]["content"][0]["text"].as_str().unwrap().contains("bridge"), "{}", r[1]);
let mut env = env.to_vec();
env.push(("PHOTOCRAFT_CONTROL_PORT", std::ffi::OsStr::new("not-a-port")));
let r = mcp_session(&["mcp", "--headless"], &env, &calls[..1]);
assert_ne!(r[0]["isError"], true, "{}", r[0]);
// Without the `AI-MCP` flag a Control Port saved before the agents switch (which the app
// reads as "agents may connect") still leaves plain `mcp` headless: it neither looks for
// the app nor applies When PhotoCraft Is Closed ("error" would fail this call).
std::fs::write(dir.join("preferences.json"), r#"{"integrations": {"controlPort": 7878}}"#).unwrap();
let r = mcp_session(&["mcp", "--when-closed", "error"], &env[..2], &calls[..1]);
assert_ne!(r[0]["isError"], true, "without the flag plain mcp stays headless: {}", r[0]);
let _ = std::fs::remove_dir_all(&dir);
let _ = std::fs::remove_dir_all(&empty);
}
+1 -1
View File
@@ -6,7 +6,7 @@ use std::process::Command;
use serde_json::Value;
fn bin() -> Command {
let mut cmd = Command::new(crate::binary());
let mut cmd = crate::command();
cmd.env_remove("PHOTOCRAFT_CONTROL_PORT");
cmd.env_remove("PHOTOCRAFT_CONTROL_TOKEN");
cmd.env_remove("PHOTOCRAFT_CONTROL_TOKEN_FILE");
+16
View File
@@ -13,3 +13,19 @@ mod psd_write_oracle;
fn binary() -> std::ffi::OsString {
std::env::var_os("NEXTEST_BIN_EXE_photocraft_cli").unwrap_or_else(|| env!("CARGO_BIN_EXE_photocraft-cli").into())
}
/// The CLI, kept away from this machine's own PhotoCraft settings, ArtCraft Launcher and feature
/// flags: plain `mcp` works in the open app when the launcher's switch lets agents use it, and
/// would otherwise find (or start) the developer's own PhotoCraft. A test that needs a settings
/// folder of its own sets `PHOTOCRAFT_CONFIG_DIR` again; the last value wins.
fn command() -> std::process::Command {
let base = std::env::temp_dir().join(format!("pc-cli-it-isolated-{}", std::process::id()));
let settings = base.join("settings");
let _ = std::fs::create_dir_all(&settings);
let mut cmd = std::process::Command::new(binary());
cmd.env("PHOTOCRAFT_CONFIG_DIR", &settings)
.env("CRAFT_MCP_DIR", base.join("launcher"))
.env("CRAFT_FLAGS_FILE", base.join("flags.toml"))
.env_remove("CRAFT_FLAGS");
cmd
}
@@ -2,13 +2,13 @@
//! and a value the user set.
use std::io::{BufRead, BufReader, Write};
use std::process::{Command, Stdio};
use std::process::Stdio;
use photocraft_engine::malloc_tuning::{TRIM_THRESHOLD, TRIM_THRESHOLD_VAR};
/// The environment of a running `serve` once it answered a request, as `NAME=value` entries.
fn serve_environ(set: Option<&str>) -> Vec<String> {
let mut cmd = Command::new(crate::binary());
let mut cmd = crate::command();
for var in [TRIM_THRESHOLD_VAR, "MALLOC_MMAP_THRESHOLD_", "MALLOC_TOP_PAD_", "MALLOC_MMAP_MAX_", "MALLOC_ARENA_MAX", "GLIBC_TUNABLES"] {
cmd.env_remove(var);
}
+1 -1
View File
@@ -10,7 +10,7 @@ use photocraft_codecs::{ChannelLayout, DecodeOptions, EncodeOptions, Format, Ima
use serde_json::Value;
fn bin() -> Command {
Command::new(crate::binary())
crate::command()
}
fn tmp(name: &str) -> PathBuf {
+1
View File
@@ -27,6 +27,7 @@ photocraft-io = { workspace = true }
photocraft-format = { workspace = true }
photocraft-automation = { workspace = true }
photocraft-ui-egui = { workspace = true }
craft-flags = { workspace = true }
# Pen tablet pressure/tilt on macOS and X11 (the workspace's one isolated unsafe helper crate).
photocraft-tablet = { workspace = true }
eframe = { workspace = true, features = ["wgpu", "accesskit", "wayland", "x11", "persistence", "clipboard"] }
+281
View File
@@ -0,0 +1,281 @@
//! Agents in the open desktop app: while the person lets them in (ArtCraft Launcher › Settings ›
//! AI agents; without the `AI-MCP` flag, a Control Port saved before), the app serves the control
//! protocol by itself (no `--control`) and publishes the connection file `photocraft-cli mcp`
//! finds it by ([`photocraft_automation::agent_link`]). Turning it on or off, or changing the
//! port or folders in Preferences › AI Integrations, applies at once. The token stays in the settings
//! folder across launches (`agent-control.token`, as `--control-token-file` would keep it; delete
//! it for a new one). Agent requests get the policy and the folders chosen there, exactly as with
//! `--control` and the automation roots.
//!
//! Launch flags win: started with `--control`, the app doesn't install this service and the
//! dialog says the launch options manage the connection.
use std::path::{Path, PathBuf};
use std::sync::mpsc::Receiver;
use photocraft_automation::agent_link::{self, Connection};
use photocraft_automation::security;
use photocraft_engine::prefs::Integrations;
use photocraft_ui_egui::{AgentLink, AgentLinkFn, ControlRequest};
use crate::control_server;
/// The connection while it runs; dropping it stops the server and removes the connection file.
struct Running {
server: control_server::Listening,
dir: PathBuf,
/// The `controlPort` preference it was started for (0 = any).
port_pref: u32,
}
impl Drop for Running {
fn drop(&mut self) {
agent_link::remove_connection(&self.dir, std::process::id());
log::info!("agent connection on 127.0.0.1:{} stopped", self.server.port);
}
}
/// Start serving agents on `port` (0 = any free port): the token from the settings folder
/// (created `0600` when missing), then the connection file. Returns the connection and the
/// channel its requests arrive on. A token file that can't be written leaves the connection off
/// (no server, so no token to leak) and says why.
fn start(dir: &Path, port: u16, ctx: &egui::Context, port_pref: u32) -> Result<(Running, Receiver<ControlRequest>), String> {
let token_file = dir.join(agent_link::TOKEN_FILE);
let token = security::server_token(None, Some(&token_file)).map_err(|e| format!("Agents can't connect: the token file could not be written: {e}"))?;
let (requests, server) = control_server::listen(port, token, ctx.clone()).map_err(|e| format!("Couldn't listen on 127.0.0.1:{port}: {e}"))?;
let running = Running { server, dir: dir.to_path_buf(), port_pref };
agent_link::write_connection(dir, &Connection::new(running.server.port, token_file)).map_err(|e| format!("Couldn't publish the agent connection: {e}"))?;
log::info!("agents can connect on 127.0.0.1:{}", running.server.port);
Ok((running, requests))
}
/// The agent connection service (`settings_dir`: where the connection file and token go).
pub fn service(settings_dir: Option<PathBuf>) -> AgentLinkFn {
let mut running: Option<Running> = None;
Box::new(move |integrations: &Integrations, ctx: &egui::Context| apply(&mut running, settings_dir.as_deref(), integrations, ctx))
}
/// Bring the connection in line with `integrations`: start, restart on another port, stop, or only
/// change the folders agents may use.
fn apply(running: &mut Option<Running>, dir: Option<&Path>, integrations: &Integrations, ctx: &egui::Context) -> AgentLink {
let mut out = AgentLink::default();
if !integrations.connect_agents {
out.stopped = running.take().is_some();
return out;
}
// Allow Agent Control off refuses every control server, this one as `--control`.
if !integrations.allow_agent_control {
out.stopped = running.take().is_some();
out.status.error = Some("Agents can't connect: Allow Agent Control is off in the preferences file.".into());
return out;
}
let Some(dir) = dir else {
out.stopped = running.take().is_some();
out.status.error = Some("Agents can't connect: PhotoCraft has no settings folder (no home folder).".into());
return out;
};
if running.as_ref().is_none_or(|r| r.port_pref != integrations.control_port) {
out.stopped = running.take().is_some();
// The preference's range is 0..=65535; anything else picks a free port.
let port = u16::try_from(integrations.control_port).unwrap_or(0);
match start(dir, port, ctx, integrations.control_port) {
Ok((r, requests)) => {
out.requests = Some(requests);
*running = Some(r);
}
Err(e) => {
log::warn!("{e}");
out.status.error = Some(e);
return out;
}
}
}
out.status.port = running.as_ref().map(|r| r.server.port);
// Agent requests always go through the automation policy; without folders they get no file
// access at all (as `--control` without automation roots). A folder that can't be opened, or
// isn't an absolute path, is left out (that direction fails closed) and named, as at launch.
let no_flags = photocraft_automation::args::AutomationArgs { automation_read_root: Vec::new(), automation_write_root: None };
let workspace = match crate::automation_workspace(&no_flags, integrations) {
Ok((workspace, warning)) => {
if let Some(w) = warning {
out.status.error = Some(format!("Agents can connect, but without file access there: {w}"));
}
workspace
}
Err(e) => {
out.status.error = Some(format!("Agents can connect, but without file access: {e}"));
photocraft_automation::AuthorizedWorkspace::default()
}
};
out.automation = crate::services::automation(Some(workspace));
out
}
/// How often [`launcher_watch`] looks at the ArtCraft Launcher's files.
const LAUNCHER_POLL: std::time::Duration = std::time::Duration::from_secs(2);
/// Whether the ArtCraft Launcher turned agents on for every Craft app
/// ([`agent_link::launcher_allows_agents`]), watched on its own thread so the UI can ask every
/// frame without touching the disk. A change wakes the UI, which then starts or stops the
/// connection. Without a thread (one couldn't be started) the answer stays what it was at launch.
pub fn launcher_watch(ctx: &egui::Context) -> Box<dyn Fn() -> bool> {
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
let on = Arc::new(AtomicBool::new(agent_link::launcher_allows_agents()));
let (seen, ctx) = (on.clone(), ctx.clone());
let started = std::thread::Builder::new().name("launcher-agents".into()).spawn(move || {
loop {
std::thread::sleep(LAUNCHER_POLL);
let now = agent_link::launcher_allows_agents();
if seen.swap(now, Ordering::Relaxed) != now {
log::info!("ArtCraft Launcher: agents {}", if now { "on" } else { "off" });
ctx.request_repaint();
}
}
});
if let Err(e) = started {
log::warn!("couldn't watch the ArtCraft Launcher's agents switch: {e}");
}
Box::new(move || on.load(Ordering::Relaxed))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicUsize, Ordering};
fn temp() -> PathBuf {
static N: AtomicUsize = AtomicUsize::new(0);
let d = std::env::temp_dir().join(format!("photocraft-agent-service-{}-{}", std::process::id(), N.fetch_add(1, Ordering::Relaxed)));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
d
}
fn on(port: u32) -> Integrations {
Integrations { connect_agents: true, control_port: port, ..Default::default() }
}
#[test]
fn turning_agents_on_publishes_a_reachable_connection_and_off_removes_it() {
let dir = temp();
let ctx = egui::Context::default();
let mut link = service(Some(dir.clone()));
// Off (the default): nothing listens, nothing is published.
let off = link(&Integrations::default(), &ctx);
assert!(off.requests.is_none() && !off.stopped && off.status.port.is_none());
assert!(off.automation.command.is_none(), "no agent policy without a connection");
assert_eq!(agent_link::read_connection(&dir).unwrap(), None);
let started = link(&on(0), &ctx);
let port = started.status.port.unwrap();
assert!(started.requests.is_some());
assert!(started.automation.command.is_some() && started.automation.authorize.is_some(), "agent requests go through the policy");
assert!(started.automation.read.is_some(), "the workspace answers (and refuses: no folder chosen)");
let c = agent_link::read_connection(&dir).unwrap().unwrap();
assert_eq!((c.port, c.pid), (port, std::process::id()));
assert!(agent_link::probe(port, agent_link::PROBE_TIMEOUT));
let token = security::client_token(None, Some(&c.token_file)).unwrap();
// Folder changes keep the server and its token.
let folders = Integrations { read_root: dir.to_string_lossy().into_owned(), ..on(0) };
let changed = link(&folders, &ctx);
assert!(changed.requests.is_none() && !changed.stopped);
assert_eq!(changed.status.port, Some(port));
assert!(changed.status.error.is_none(), "{:?}", changed.status.error);
assert_eq!(security::client_token(None, Some(&c.token_file)).unwrap(), token);
// A missing folder still connects, without file access, and says why.
let missing = Integrations { write_root: dir.join("nope").to_string_lossy().into_owned(), ..on(0) };
let partial = link(&missing, &ctx);
assert_eq!(partial.status.port, Some(port));
assert!(partial.status.error.as_deref().is_some_and(|e| e.contains("without file access")), "{:?}", partial.status.error);
assert!(partial.automation.command.is_some());
let stopped = link(&Integrations::default(), &ctx);
assert!(stopped.stopped && stopped.status.port.is_none());
assert_eq!(agent_link::read_connection(&dir).unwrap(), None, "the connection file goes with the server");
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
while agent_link::probe(port, agent_link::PROBE_TIMEOUT) {
assert!(std::time::Instant::now() < deadline, "port {port} still open");
std::thread::sleep(std::time::Duration::from_millis(20));
}
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_new_port_restarts_with_the_same_token_and_a_taken_port_is_reported() {
let dir = temp();
let ctx = egui::Context::default();
let mut link = service(Some(dir.clone()));
let first = link(&on(0), &ctx);
let first_port = first.status.port.unwrap();
let token_file = dir.join(agent_link::TOKEN_FILE);
let first_token = std::fs::read_to_string(&token_file).unwrap();
// A taken port: the error names it and nothing is published for it.
let taken = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let taken_port = taken.local_addr().unwrap().port();
let failed = link(&on(u32::from(taken_port)), &ctx);
assert!(failed.stopped && failed.requests.is_none() && failed.status.port.is_none());
assert!(failed.status.error.as_deref().is_some_and(|e| e.contains(&taken_port.to_string())), "{:?}", failed.status.error);
assert_eq!(agent_link::read_connection(&dir).unwrap(), None);
drop(taken);
// Back to any port: the token in the settings folder is kept, so a client holding it
// (a `--bridge` setup reading the token file) needn't be set up again.
let again = link(&on(0), &ctx);
assert!(again.requests.is_some());
assert!(again.status.port.is_some_and(|p| p != 0));
assert_eq!(std::fs::read_to_string(&token_file).unwrap(), first_token);
let _ = first_port;
drop(link);
assert_eq!(agent_link::read_connection(&dir).unwrap(), None, "quitting removes the connection file");
let _ = std::fs::remove_dir_all(&dir);
}
/// A token file that can't be written (here the "settings folder" is a file) leaves the
/// connection off with the reason shown, and its port free.
#[test]
fn a_token_file_that_cannot_be_written_leaves_agents_off() {
let dir = temp();
let settings = dir.join("not-a-folder");
std::fs::write(&settings, b"").unwrap();
let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
let mut link = service(Some(settings));
let r = link(&on(u32::from(port)), &egui::Context::default());
assert!(r.requests.is_none() && r.status.port.is_none());
assert!(r.status.error.as_deref().is_some_and(|e| e.contains("token file")), "{:?}", r.status.error);
std::net::TcpListener::bind(("127.0.0.1", port)).expect("the port was let go");
let _ = std::fs::remove_dir_all(&dir);
}
/// A relative folder would depend on the folder the app was started from: left out and named.
#[test]
fn a_relative_folder_is_left_out_with_a_reason() {
let dir = temp();
let mut link = service(Some(dir.clone()));
let r = link(&Integrations { read_root: ".".into(), ..on(0) }, &egui::Context::default());
assert!(r.status.port.is_some());
assert!(r.status.error.as_deref().is_some_and(|e| e.contains("not an absolute path")), "{:?}", r.status.error);
drop(link);
let _ = std::fs::remove_dir_all(&dir);
}
/// Allow Agent Control off (in the file; the dialog doesn't show it) refuses this server too.
#[test]
fn allow_agent_control_off_keeps_agents_out() {
let dir = temp();
let mut link = service(Some(dir.clone()));
let r = link(&Integrations { allow_agent_control: false, ..on(0) }, &egui::Context::default());
assert!(r.requests.is_none() && r.status.port.is_none() && r.automation.command.is_none());
assert!(r.status.error.as_deref().is_some_and(|e| e.contains("Allow Agent Control")), "{:?}", r.status.error);
assert_eq!(agent_link::read_connection(&dir).unwrap(), None);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn no_settings_folder_is_an_error_not_a_panic() {
let mut link = service(None);
let r = link(&on(0), &egui::Context::default());
assert!(r.requests.is_none() && r.status.error.is_some());
}
}
+8 -90
View File
@@ -10,6 +10,9 @@
//! 3. The platform convention: macOS `~/Library/Application Support/Photocraft`, Windows
//! `%APPDATA%\Photocraft`, Linux `$XDG_CONFIG_HOME/photocraft` or `~/.config/photocraft`.
//!
//! The rules live in [`photocraft_automation::app_dirs`], so `photocraft-cli` resolves the same
//! folder; this module resolves it once for the app and logs the outcome.
//!
//! One exception: the platform convention keeps crash-recovery autosaves out of what is synced
//! with the settings: the Windows roaming profile and the Linux config folder ([`recovery_dir`]).
@@ -17,31 +20,11 @@ use std::ffi::OsString;
use std::path::{Path, PathBuf};
use std::sync::OnceLock;
/// Files beside the executable that switch on portable mode (either one; contents are ignored).
pub const PORTABLE_MARKERS: [&str; 2] = ["portable.txt", "PhotoCraft.portable"];
/// The data folder created beside the executable in portable mode.
pub const PORTABLE_DATA_DIR: &str = "PhotoCraftData";
/// How [`DataDir::dir`] was chosen.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Mode {
/// `PHOTOCRAFT_CONFIG_DIR`.
Override,
/// `<exe dir>/PhotoCraftData`.
Portable,
/// The platform's per-user config directory.
Platform,
}
/// The resolved data directory.
#[derive(Clone, Debug)]
pub struct DataDir {
/// `None` only when no platform directory is known either (no `HOME`/`APPDATA`).
pub dir: Option<PathBuf>,
pub mode: Mode,
/// Set when a portable marker was found but its data folder isn't writable.
pub warning: Option<String>,
}
pub use photocraft_automation::app_dirs::{DataDir, Mode, resolve};
// The tests below exercise the shared resolver too; some of them run on Unix only.
#[cfg(test)]
#[allow(unused_imports)]
use photocraft_automation::app_dirs::{PORTABLE_DATA_DIR, PORTABLE_MARKERS, WRITE_PROBE_ATTEMPTS, ensure_writable, platform_dir, portable_marker};
/// The data directory for this process, resolved once (the portable check probes the disk).
pub fn current() -> &'static DataDir {
@@ -453,70 +436,5 @@ fn copy_file(from: &Path, to: &Path) -> std::io::Result<()> {
dst.sync_all()
}
/// Resolve the data directory from the environment (`env`) and the executable's folder.
pub fn resolve(env: impl Fn(&str) -> Option<OsString>, exe_dir: Option<&Path>) -> DataDir {
if let Some(d) = env("PHOTOCRAFT_CONFIG_DIR").filter(|d| !d.is_empty()) {
return DataDir { dir: Some(PathBuf::from(d)), mode: Mode::Override, warning: None };
}
let platform = platform_dir(&env);
let Some((exe_dir, marker)) = exe_dir.and_then(|d| portable_marker(d).map(|m| (d, m))) else {
return DataDir { dir: platform, mode: Mode::Platform, warning: None };
};
let data = exe_dir.join(PORTABLE_DATA_DIR);
match ensure_writable(&data) {
Ok(()) => DataDir { dir: Some(data), mode: Mode::Portable, warning: None },
Err(e) => {
let fallback = platform.as_ref().map_or_else(|| "nowhere (no user folder found)".to_string(), |p| p.display().to_string());
let warning =
format!("portable mode ({} found) but {} isn't writable ({e}); settings are kept in {fallback} instead", marker.display(), data.display());
DataDir { dir: platform, mode: Mode::Platform, warning: Some(warning) }
}
}
}
/// The platform convention, from `env` (so tests can fake `HOME`/`APPDATA`/`XDG_CONFIG_HOME`).
pub fn platform_dir(env: &impl Fn(&str) -> Option<OsString>) -> Option<PathBuf> {
let home = env("HOME").filter(|h| !h.is_empty()).map(PathBuf::from);
if cfg!(target_os = "macos") {
return home.map(|h| h.join("Library/Application Support/Photocraft"));
}
if cfg!(windows) {
return env("APPDATA").filter(|a| !a.is_empty()).map(|a| PathBuf::from(a).join("Photocraft"));
}
env("XDG_CONFIG_HOME").filter(|x| !x.is_empty()).map(PathBuf::from).or_else(|| home.map(|h| h.join(".config"))).map(|c| c.join("photocraft"))
}
/// The first portable marker file in `exe_dir`, if any.
pub fn portable_marker(exe_dir: &Path) -> Option<PathBuf> {
PORTABLE_MARKERS.iter().map(|m| exe_dir.join(m)).find(|p| p.is_file())
}
/// Probe names tried before giving up on a portable data folder.
const WRITE_PROBE_ATTEMPTS: u32 = 64;
/// Create `dir` and prove a file can be written in it (a folder can exist yet be read-only).
///
/// The probe is created exclusively (`create_new`), so an entry already at its name (a link
/// someone else placed there, say) is never opened, written through or removed: the next name
/// is tried instead. Only a probe this call created is removed.
fn ensure_writable(dir: &Path) -> std::io::Result<()> {
std::fs::create_dir_all(dir)?;
let pid = std::process::id();
for attempt in 0..WRITE_PROBE_ATTEMPTS {
let probe = dir.join(format!(".write-test-{pid}-{attempt}"));
match std::fs::OpenOptions::new().write(true).create_new(true).open(&probe) {
Ok(file) => {
drop(file);
// A leftover probe is harmless; don't fail portable mode over it.
let _ = std::fs::remove_file(&probe);
return Ok(());
}
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(e) => return Err(e),
}
}
Err(std::io::Error::new(std::io::ErrorKind::AlreadyExists, "every write-test name is already taken"))
}
#[cfg(test)]
mod tests;
+93 -19
View File
@@ -1,9 +1,13 @@
//! Localhost JSON-lines control server (one request per line, one reply per line).
//! Loopback only. This is the transport the MCP server will wrap.
//!
//! `--control` starts it for the whole run ([`start`]); Preferences › AI Integrations starts and
//! stops it while the app runs ([`listen`], see `agent_link`).
use std::io::{BufReader, Write};
use std::net::{TcpListener, TcpStream};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{Receiver, Sender, channel};
use std::time::{Duration, Instant};
@@ -16,32 +20,74 @@ use photocraft_ui_egui::ControlRequest;
use photocraft_ui_egui::control::REPLY_DEADLINE;
use serde_json::{Value, json};
/// Start serving a listener already bound during startup, before a window is opened.
/// Start serving a listener already bound during startup, before a window is opened. It serves
/// for the whole run.
pub fn start(listener: TcpListener, token: String, ctx: egui::Context) -> Receiver<ControlRequest> {
let (tx, rx) = channel::<ControlRequest>();
let port = listener.local_addr().map_or(0, |a| a.port());
eprintln!("photocraft: control server listening on {}", listening_addr(&listener, port));
std::thread::spawn(move || {
let limiter = ConnectionLimiter::new(MAX_CONNECTIONS);
let token = Arc::new(token);
for mut stream in listener.incoming().flatten() {
let Some(permit) = limiter.try_acquire() else {
let _ = configure_stream(&stream);
let _ = writeln!(stream, "{}", json!({"id": null, "ok": false, "error": "connection limit reached"}));
continue;
};
let tx = tx.clone();
let ctx = ctx.clone();
let token = Arc::clone(&token);
std::thread::spawn(move || {
let _permit = permit;
serve(stream, &token, tx, ctx);
});
}
});
std::thread::spawn(move || accept(listener, token, tx, ctx, None));
rx
}
/// A control server started by [`listen`]. Dropping it stops accepting connections; connections
/// already open end at their next request, once the app drops the request channel.
pub struct Listening {
/// The bound port (the one the system picked for port 0).
pub port: u16,
stop: Arc<AtomicBool>,
accept: Option<std::thread::JoinHandle<()>>,
}
impl Drop for Listening {
fn drop(&mut self) {
self.stop.store(true, Ordering::Release);
// Wake the accept loop so it sees the flag and closes the listener, and wait for that, so
// the port is free when this returns (a restart on the same port binds it again at once).
// Without a wake-up the loop would block in `accept`: then don't wait.
let woke = TcpStream::connect_timeout(&std::net::SocketAddr::from(([127, 0, 0, 1], self.port)), Duration::from_millis(500)).is_ok();
if woke && let Some(accept) = self.accept.take() {
let _ = accept.join();
}
}
}
/// Serve the control protocol on `127.0.0.1:port` (0 = any free port) until the returned
/// [`Listening`] is dropped.
pub fn listen(port: u16, token: String, ctx: egui::Context) -> std::io::Result<(Receiver<ControlRequest>, Listening)> {
let (tx, rx) = channel::<ControlRequest>();
let listener = TcpListener::bind(("127.0.0.1", port))?;
let port = listener.local_addr()?.port();
let stop = Arc::new(AtomicBool::new(false));
let stopped = stop.clone();
let accept = std::thread::Builder::new().name("control server".into()).spawn(move || accept(listener, token, tx, ctx, Some(stopped)))?;
Ok((rx, Listening { port, stop, accept: Some(accept) }))
}
/// Accept connections on `listener` and serve each on its own thread, until `stop` is set (never,
/// without one).
fn accept(listener: TcpListener, token: String, tx: Sender<ControlRequest>, ctx: egui::Context, stop: Option<Arc<AtomicBool>>) {
let limiter = ConnectionLimiter::new(MAX_CONNECTIONS);
let token = Arc::new(token);
for mut stream in listener.incoming().flatten() {
if stop.as_ref().is_some_and(|s| s.load(Ordering::Acquire)) {
break;
}
let Some(permit) = limiter.try_acquire() else {
let _ = configure_stream(&stream);
let _ = writeln!(stream, "{}", json!({"id": null, "ok": false, "error": "connection limit reached"}));
continue;
};
let tx = tx.clone();
let ctx = ctx.clone();
let token = Arc::clone(&token);
std::thread::spawn(move || {
let _permit = permit;
serve(stream, &token, tx, ctx);
});
}
}
/// The address `listener` is bound to: with `--control 0` the OS picks the port, and a client
/// needs that one, not the requested 0 (#6427). Falls back to the requested port if the OS
/// can't report it.
@@ -138,6 +184,34 @@ mod tests {
use std::io::BufRead;
/// #6427: with port 0 the log names the port the OS bound, which a client can connect to.
#[test]
fn a_listening_server_picks_a_port_and_stops_when_dropped() {
const TOKEN: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
let (rx, server) = listen(0, TOKEN.into(), egui::Context::default()).unwrap();
let port = server.port;
assert_ne!(port, 0);
let handler = std::thread::spawn(move || {
let req = rx.recv_timeout(Duration::from_secs(5)).unwrap();
assert_eq!(req.method, "test.ping");
req.reply.send(json!({"ok": true, "result": "pong"})).unwrap();
});
let mut stream = TcpStream::connect(("127.0.0.1", port)).unwrap();
stream.set_read_timeout(Some(Duration::from_secs(5))).unwrap();
let mut reader = BufReader::new(stream.try_clone().unwrap());
let mut line = String::new();
writeln!(stream, "{}", json!({"id": 1, "method": "auth", "params": {"token": TOKEN}})).unwrap();
reader.read_line(&mut line).unwrap();
assert_eq!(serde_json::from_str::<Value>(&line).unwrap()["ok"], true);
writeln!(stream, "{}", json!({"id": 2, "method": "test.ping"})).unwrap();
line.clear();
reader.read_line(&mut line).unwrap();
assert_eq!(serde_json::from_str::<Value>(&line).unwrap()["result"], "pong");
handler.join().unwrap();
drop(server);
// The listener is closed when the drop returns: the same port binds again at once.
TcpListener::bind(("127.0.0.1", port)).expect("the port is free after the drop");
}
#[test]
fn port_zero_logs_the_bound_port() {
let listener = TcpListener::bind(("127.0.0.1", 0)).unwrap();
+232 -53
View File
@@ -29,6 +29,7 @@
#![cfg_attr(all(windows, not(debug_assertions)), windows_subsystem = "windows")]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod agent_link;
mod app_dirs;
mod app_icon;
mod appearance;
@@ -94,51 +95,77 @@ fn custom_titlebar(prefs_file: Option<&std::path::Path>) -> bool {
CUSTOM_TITLEBAR && !prefs.interface.system_title_bar
}
/// Preferences › Integrations, read before the window opens the way [`custom_titlebar`] is:
/// whether agents may drive this launch at all, and the port to listen on when no `--control`
/// was given (0 = only with `--control`). A missing or unreadable file keeps the defaults.
/// Preferences › AI Integrations, read before the window opens the way [`custom_titlebar`] is:
/// whether agents may drive this launch at all, the port to listen on when no `--control`
/// was given (0 = only with `--control`) and the automation folders used when no
/// `--automation-read-root` / `--automation-write-root` was given. A missing or unreadable file
/// keeps the defaults.
///
/// The section is read on its own, and when it doesn't read as a whole each value on its own,
/// as the app's lenient load reads them (#6611): a wrong-typed value elsewhere in the file, or
/// in the other field, must not turn Allow Agent Control back on while the dialog shows it off.
fn integrations(prefs_file: Option<&std::path::Path>) -> photocraft_engine::prefs::Integrations {
use serde_json::Value;
let mut out = photocraft_engine::prefs::Preferences::default().integrations;
let file: Option<Value> = prefs_file.and_then(|p| std::fs::read_to_string(p).ok()).and_then(|t| serde_json::from_str(&t).ok());
let Some(section) = file.as_ref().and_then(|v| v.get("integrations")) else {
return out;
};
if let Ok(whole) = serde_json::from_value(section.clone()) {
return whole;
let file: Option<serde_json::Value> = prefs_file.and_then(|p| std::fs::read_to_string(p).ok()).and_then(|t| serde_json::from_str(&t).ok());
file.as_ref()
.and_then(|v| v.get("integrations"))
.cloned()
.map(photocraft_engine::prefs::read_integrations_section)
.unwrap_or_else(|| photocraft_engine::prefs::Preferences::default().integrations)
}
/// The automation roots: `--automation-read-root` / `--automation-write-root` (or their
/// variables) win; a direction without one takes Preferences › AI Integrations' folder. A flag's
/// root that can't be opened stops the launch (exit status 2) as before. A preference's root that
/// can't be opened, or isn't an absolute path (it would depend on the folder the app was started
/// from), is left out, so that direction fails closed, and the warning says why: a folder moved
/// since it was chosen must not stop the app from starting. Each folder is opened once, so one
/// that goes away during the launch can't turn into an error, and the same folder for reading
/// and writing shares one capability, as it does when given by flags.
fn automation_workspace(
flags: &photocraft_automation::args::AutomationArgs,
prefs: &photocraft_engine::prefs::Integrations,
) -> Result<(photocraft_automation::workspace::AuthorizedWorkspace, Option<String>), photocraft_automation::AutomationError> {
use photocraft_automation::agent_link::folder;
let mut workspace = flags.workspace()?;
let mut warnings = Vec::new();
for read in [true, false] {
let given = if read { !flags.automation_read_root.is_empty() } else { flags.automation_write_root.is_some() };
let Some(root) = folder(if read { &prefs.read_root } else { &prefs.write_root }).filter(|_| !given) else {
continue;
};
let opened = if !root.is_absolute() {
Err(format!("`{}` is not an absolute path", root.display()))
} else if read {
workspace.with_read_root(&root).map_err(|e| e.to_string())
} else {
workspace.with_write_root(&root).map_err(|e| e.to_string())
};
match opened {
Ok(w) => workspace = w,
Err(e) => {
let which = if read { "Automation Read Folder" } else { "Automation Write Folder" };
warnings.push(format!("Preferences › AI Integrations › {which} is not used: {e}"));
}
}
}
if let Some(allow) = section.get("allowAgentControl").and_then(Value::as_bool) {
out.allow_agent_control = allow;
}
if let Some(port) = section.get("controlPort").and_then(Value::as_u64).and_then(|p| u32::try_from(p).ok()) {
out.control_port = port;
}
out
Ok((workspace, (!warnings.is_empty()).then(|| warnings.join("\n"))))
}
/// The control port this launch listens on, and the warning to print when a request was refused.
/// `--control` (or `PHOTOCRAFT_CONTROL_PORT`) wins over the preference; Allow Agent Control off
/// refuses both, and says so rather than ignoring the flag silently. A preferred port outside
/// 1..=65535 is refused the same way.
/// Only `--control` (or `PHOTOCRAFT_CONTROL_PORT`) opens one at launch: Preferences › AI
/// Integrations' connection starts and stops while the app runs (`agent_link`). Allow Agent
/// Control off refuses the flag too, and says so rather than ignoring it silently.
fn control_port_for(cli: Option<u16>, prefs: &photocraft_engine::prefs::Integrations) -> (Option<u16>, Option<String>) {
if !prefs.allow_agent_control {
let warning = cli.map(|p| format!("photocraft: Preferences › Integrations › Allow Agent Control is off: not listening on port {p}\n"));
let warning = cli.map(|p| {
format!(
"photocraft: Preferences › AI Integrations › Allow Agent Control is off: not listening on port {p}
"
)
});
return (None, warning);
}
if let Some(port) = cli {
return (Some(port), None);
}
match prefs.control_port {
0 => (None, None),
p => match u16::try_from(p).ok().filter(|p| *p != 0) {
Some(port) => (Some(port), None),
None => (None, Some(format!("photocraft: Preferences › Integrations › Control Port {p} is not a usable port: not listening\n"))),
},
}
(cli, None)
}
/// The main window: 1440 × 900 (shrunk to fit the monitor, and maximized on the first frame
@@ -282,17 +309,54 @@ fn linux_display_session() -> linux_libs::DisplaySession {
session
}
/// The control server's port, token and workspace, when it is on (exits 2 on a bad configuration).
/// The control server: its listener, token and workspace.
type Control = (std::net::TcpListener, String, photocraft_automation::workspace::AuthorizedWorkspace);
/// What [`control_setup`] set up: the control server when it is on, and a notice for the window
/// (a preference's automation folder that wasn't used).
struct ControlSetup {
control: Option<Control>,
warning: Option<ControlNotice>,
}
/// A notice for the window about the control server: a Dock launch has no console.
struct ControlNotice {
title: &'static str,
lines: Vec<String>,
}
/// The `--control` server's port, token and workspace, when it is on (exits 2 on a bad
/// configuration). Preferences › AI Integrations' folders stand in for automation roots no flag
/// names. The server the agents switch starts is `agent_link`'s, not this.
fn control_setup(
cli_port: Option<u16>,
auth: photocraft_automation::args::ControlArgs,
automation: &photocraft_automation::args::AutomationArgs,
) -> Option<(std::net::TcpListener, String, photocraft_automation::workspace::AuthorizedWorkspace)> {
let (port, warning) = control_port_for(cli_port, &integrations(services::prefs_file().as_deref()));
) -> ControlSetup {
control_setup_in(services::config_dir(), &integrations(services::prefs_file().as_deref()), cli_port, auth, automation)
}
/// [`control_setup`] with the settings folder and Preferences › AI Integrations given.
fn control_setup_in(
settings: Option<std::path::PathBuf>,
prefs: &photocraft_engine::prefs::Integrations,
cli_port: Option<u16>,
auth: photocraft_automation::args::ControlArgs,
automation: &photocraft_automation::args::AutomationArgs,
) -> ControlSetup {
use photocraft_automation::agent_link;
let (port, warning) = control_port_for(cli_port, prefs);
if let Some(warning) = &warning {
eprint!("{warning}");
}
let port = port?;
// A file a crashed (or, on macOS, quit) launch left behind names a port nothing serves. Before
// binding, so this launch's own listener doesn't keep it.
if let Some(dir) = &settings {
agent_link::remove_stale_connection(dir);
}
let Some(port) = port else {
return ControlSetup { control: None, warning: None };
};
let listener = match std::net::TcpListener::bind(("127.0.0.1", port)) {
Ok(listener) => listener,
Err(error) => {
@@ -308,21 +372,26 @@ fn control_setup(
std::process::exit(2);
}
};
if let Some(path) = token_file {
if let Some(path) = &token_file {
eprintln!("photocraft: control token file: {}", path.display());
} else if supplied.is_none() {
eprintln!("photocraft: control token: {token}");
} else {
eprintln!("photocraft: using supplied control token");
}
let workspace = match automation.workspace() {
let (workspace, warning) = match automation_workspace(automation, prefs) {
Ok(workspace) => workspace,
Err(error) => {
eprintln!("photocraft: cannot configure automation workspace: {error}");
std::process::exit(2);
}
};
Some((listener, token, workspace))
if let Some(warning) = &warning {
eprintln!("photocraft: {warning}");
log::warn!("{warning}");
}
let warning = warning.map(|w| ControlNotice { title: "Automation folder not used", lines: w.lines().map(str::to_owned).collect() });
ControlSetup { control: Some((listener, token, workspace)), warning }
}
/// Record this start's backend in the GPU startup marker, if the marker is locked.
@@ -398,7 +467,7 @@ fn main() -> eframe::Result {
let _ = (new_instance, &launch_options);
// Bind and authenticate the authorized control listener before display/GPU initialization.
let control = control_setup(control_port, auth, &automation);
let ControlSetup { control, warning: control_warning } = control_setup(control_port, auth, &automation);
#[cfg(target_os = "linux")]
let native_session = linux_libs::session_from_env(|name| std::env::var(name).ok());
@@ -618,9 +687,24 @@ fn main() -> eframe::Result {
log::warn!("couldn't remember GPU backend {}: {e}", b.name());
}
});
// Agents in the open window, unless the launch flags (`--control`) manage the
// connection. Behind the suite's AI-MCP feature flag, the ArtCraft Launcher's switch
// (Settings › AI agents) is the one consent; without it, as before, a Control Port.
let flags = craft_flags::load();
for problem in &flags.problems {
log::warn!("feature flags: {problem}");
}
app.agent_link.mcp_flag = flags.enabled(&craft_flags::AI_MCP);
if app.agent_link.mcp_flag {
app.services.launcher_agents = Some(agent_link::launcher_watch(&cc.egui_ctx));
}
if let Some((listener, token, _)) = control {
app.agent_link.launch_flags = true;
app.agent_link.port = listener.local_addr().ok().map(|a| a.port());
let rx = control_server::start(listener, token, cc.egui_ctx.clone());
app = app.with_control(rx);
} else {
app.services.agent_link = Some(agent_link::service(services::config_dir()));
}
#[cfg(target_os = "macos")]
{
@@ -695,6 +779,11 @@ fn main() -> eframe::Result {
if let Some(w) = &app_dirs::current().warning {
photocraft_ui_egui::notices::post(&mut app, "Portable mode is off", vec![w.clone()], false, None);
}
// A preference's automation folder that couldn't be opened, or a token file it couldn't
// write: a Dock launch has no console.
if let Some(ControlNotice { title, lines }) = control_warning {
photocraft_ui_egui::notices::post(&mut app, title, lines, false, None);
}
Ok(Box::new(app))
}),
);
@@ -977,16 +1066,17 @@ mod tests {
#[test]
fn integrations_preferences_decide_the_control_port() {
use photocraft_engine::prefs::Integrations;
let off = Integrations { allow_agent_control: false, control_port: 0 };
let on = Integrations { allow_agent_control: true, control_port: 0 };
let preferred = Integrations { allow_agent_control: true, control_port: 7878 };
let off = Integrations { allow_agent_control: false, control_port: 0, ..Default::default() };
let on = Integrations { allow_agent_control: true, control_port: 0, ..Default::default() };
let preferred = Integrations { allow_agent_control: true, control_port: 7878, ..Default::default() };
// Nothing asked for, nothing listening.
assert_eq!(super::control_port_for(None, &on), (None, None));
// --control wins over the preference.
assert_eq!(super::control_port_for(Some(9000), &preferred), (Some(9000), None));
// The preference opens the port when --control is absent.
assert_eq!(super::control_port_for(None, &preferred), (Some(7878), None));
// The preference alone opens nothing at launch: the agent connection starts it while
// the app runs (`agent_link`).
assert_eq!(super::control_port_for(None, &preferred), (None, None));
// Allow Agent Control off refuses both, and says so when --control asked for one
// rather than ignoring the flag.
@@ -994,14 +1084,8 @@ mod tests {
let (port, warning) = super::control_port_for(Some(9000), &off);
assert_eq!(port, None);
assert!(warning.is_some_and(|w| w.contains("Allow Agent Control") && w.contains("9000")), "the refusal names the port");
let off_with_port = Integrations { allow_agent_control: false, control_port: 7878 };
let off_with_port = Integrations { allow_agent_control: false, control_port: 7878, ..Default::default() };
assert_eq!(super::control_port_for(None, &off_with_port), (None, None), "off beats a preferred port");
// A port a hand-edited file could hold, outside 1..=65535, is refused and named.
let huge = Integrations { allow_agent_control: true, control_port: 70_000 };
let (port, warning) = super::control_port_for(None, &huge);
assert_eq!(port, None);
assert!(warning.is_some_and(|w| w.contains("70000")), "the refusal names the value");
}
#[test]
@@ -1049,13 +1133,108 @@ mod tests {
assert_eq!(r.control_port, 0, "the bad port alone takes its default");
// A bad Allow Agent Control alone takes its default.
let r = read(r#"{"integrations":{"allowAgentControl":"no","controlPort":7878}}"#);
assert_eq!(r, photocraft_engine::prefs::Integrations { allow_agent_control: true, control_port: 7878 });
// (A saved port from before the agents switch turns it on, in both reads.)
assert_eq!(r, photocraft_engine::prefs::Integrations { allow_agent_control: true, control_port: 7878, connect_agents: true, ..Default::default() });
read(r#"{"integrations":{"allowAgentControl":false,"controlPort":-1}}"#);
read(r#"{"integrations":{"allowAgentControl":false,"controlPort":4294967296}}"#);
read(r#"{"integrations":"off"}"#);
// serde reads a struct from a list too; the app does.
assert!(!read(r#"{"integrations":[false]}"#).allow_agent_control, "a list");
assert_eq!(read(r#"{"integrations":[false,7878]}"#).control_port, 7878);
// The automation folders: a bad one takes its default alone, too.
let r = read(r#"{"integrations":{"allowAgentControl":false,"readRoot":5,"writeRoot":"/w"}}"#);
assert!(!r.allow_agent_control, "a bad folder");
assert_eq!((r.read_root.as_str(), r.write_root.as_str()), ("", "/w"));
let _ = std::fs::remove_dir_all(&dir);
}
fn temp_dir(name: &str) -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!("pc-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
dir
}
fn flags(read: Option<&std::path::Path>, write: Option<&std::path::Path>) -> photocraft_automation::args::AutomationArgs {
photocraft_automation::args::AutomationArgs {
automation_read_root: read.map(Into::into).into_iter().collect(),
automation_write_root: write.map(Into::into),
}
}
fn roots(read: &std::path::Path, write: &std::path::Path) -> photocraft_engine::prefs::Integrations {
photocraft_engine::prefs::Integrations {
read_root: read.to_string_lossy().into_owned(),
write_root: write.to_string_lossy().into_owned(),
..Default::default()
}
}
/// Preferences › AI Integrations' folders are the automation roots when no flag names one, and
/// a flag wins over its preference, direction by direction.
#[test]
fn automation_folders_come_from_the_preferences_unless_a_flag_names_one() {
let dir = temp_dir("automation-roots");
let (pref, flag) = (dir.join("pref"), dir.join("flag"));
std::fs::create_dir_all(&pref).unwrap();
std::fs::create_dir_all(&flag).unwrap();
// No flags: both directions from the preferences.
let (ws, warning) = super::automation_workspace(&flags(None, None), &roots(&pref, &pref)).unwrap();
assert_eq!(warning, None);
ws.write("a.txt", b"pref").unwrap();
assert_eq!(std::fs::read(pref.join("a.txt")).unwrap(), b"pref");
assert_eq!(ws.read("a.txt").unwrap(), b"pref");
// One folder for both shares one capability, as the flags do: an implicit save is allowed.
assert_eq!(ws.read_with_save_path("a.txt").unwrap().1.as_deref(), Some("a.txt"));
// A write flag wins over the write folder; reads still come from the preference.
let (ws, _) = super::automation_workspace(&flags(None, Some(&flag)), &roots(&pref, &pref)).unwrap();
ws.write("b.txt", b"flag").unwrap();
assert!(flag.join("b.txt").is_file() && !pref.join("b.txt").exists(), "the flag's folder takes the write");
assert_eq!(ws.read("a.txt").unwrap(), b"pref");
assert_eq!(ws.read_with_save_path("a.txt").unwrap().1, None, "read and write folders differ: no implicit save");
// A read folder spelled like the write flag shares the flag's capability.
let (ws, _) = super::automation_workspace(&flags(None, Some(&flag)), &roots(&flag, &pref)).unwrap();
assert_eq!(ws.read_with_save_path("b.txt").unwrap().1.as_deref(), Some("b.txt"));
// Empty preferences grant nothing, as no flags do.
let (ws, warning) = super::automation_workspace(&flags(None, None), &photocraft_engine::prefs::Integrations::default()).unwrap();
assert_eq!(warning, None);
assert!(ws.read("a.txt").is_err() && ws.write("c.txt", b"x").is_err());
let _ = std::fs::remove_dir_all(&dir);
}
/// A preference's folder that can't be opened is left out (that direction fails closed) and
/// named in the warning; the app still starts. A flag's still stops the launch.
#[test]
fn a_missing_preference_folder_is_left_out_and_a_missing_flag_root_is_an_error() {
let dir = temp_dir("automation-roots-missing");
let missing = dir.join("gone");
let (ws, warning) = super::automation_workspace(&flags(None, None), &roots(&dir, &missing)).unwrap();
let warning = warning.expect("the missing write folder is named");
assert!(warning.contains("Automation Write Folder") && !warning.contains("Read Folder"), "{warning}");
std::fs::write(dir.join("in.txt"), b"x").unwrap();
assert_eq!(ws.read("in.txt").unwrap(), b"x", "the read folder still applies");
assert!(ws.write("out.txt", b"x").is_err(), "no write access without its folder");
assert!(super::automation_workspace(&flags(Some(&missing), None), &roots(&dir, &dir)).is_err(), "a flag's root must open");
let _ = std::fs::remove_dir_all(&dir);
}
/// A relative folder preference would depend on the folder the app was started from: left
/// out with a warning, like a missing one.
#[test]
fn a_relative_preference_folder_is_left_out() {
let dir = temp_dir("automation-roots-relative");
let relative = photocraft_engine::prefs::Integrations { read_root: ".".into(), ..roots(&dir, &dir) };
let (ws, warning) = super::automation_workspace(&flags(None, None), &relative).unwrap();
let warning = warning.expect("the relative read folder is named");
assert!(warning.contains("Automation Read Folder") && warning.contains("not an absolute path"), "{warning}");
assert!(ws.read("anything").is_err(), "no read access from a relative folder");
ws.write("out.txt", b"x").unwrap();
assert!(dir.join("out.txt").is_file(), "the absolute write folder still applies");
let _ = std::fs::remove_dir_all(&dir);
}
+23 -16
View File
@@ -721,38 +721,45 @@ fn shell_word(s: &str) -> String {
if s.bytes().all(|b| b.is_ascii_alphanumeric() || b"/._-+:,@".contains(&b)) { s.to_string() } else { format!("'{}'", s.replace('\'', r"'\''")) }
}
pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) -> Services {
let clip: Rc<RefCell<Option<arboard::Clipboard>>> = Rc::default();
let clip_unreadable: Rc<Cell<bool>> = Rc::default();
let automation_read = automation.clone().map(|workspace| {
/// What control and MCP requests may read, write and run, through `workspace` (`None`: no
/// automation, as without `--control` or an agent connection).
pub fn automation(workspace: Option<photocraft_automation::AuthorizedWorkspace>) -> photocraft_ui_egui::AutomationServices {
let read = workspace.clone().map(|workspace| {
Box::new(move |path: &str| {
let (bytes, save_path) = workspace.read_with_save_path(path).map_err(|error| error.to_string())?;
let name = Path::new(path).file_name().and_then(|name| name.to_str()).unwrap_or(path).to_string();
Ok(photocraft_ui_egui::AutomationReadResult { name, bytes, save_path })
}) as photocraft_ui_egui::AutomationReadFn
});
let automation_write = automation.clone().map(|workspace| {
let write = workspace.clone().map(|workspace| {
Box::new(move |path: &str, bytes: &[u8]| workspace.write(path, bytes).map_err(|error| error.to_string())) as photocraft_ui_egui::AutomationWriteFn
});
let automation_open_pcraft = automation.clone().map(|workspace| {
let open_pcraft = workspace.clone().map(|workspace| {
Box::new(move |path: &str| {
let name = Path::new(path).file_name().and_then(|name| name.to_str()).unwrap_or(path).to_string();
let opened = crate::crash_guard::guard("Open", || workspace.open_pcraft(path).map_err(|e| e.to_string()))?;
Ok(opened.map(|doc| (name, doc)))
}) as photocraft_ui_egui::AutomationOpenPcraftFn
});
let automation_save = automation.clone().map(|workspace| {
let save = workspace.clone().map(|workspace| {
std::sync::Arc::new(move |doc: &Document, path: &str, settings: &photocraft_ui_egui::ExportSettings, ctl: &photocraft_ui_egui::jobs_ui::SaveCtl| {
save_through(doc, path, settings, ctl, |p, encoded, _| workspace.write_stream(p, &mut |w| encoded.write_to(w)).map_err(|e| e.to_string()))
}) as photocraft_ui_egui::SaveFileFn
});
let step: fn(&str, &serde_json::Value) -> photocraft_engine::Result<()> = photocraft_automation::workspace::authorize_desktop_engine_step;
let automation_authorize = automation.is_some().then_some(step);
let automation_command = automation.map(|_| {
let step: photocraft_ui_egui::AutomationAuthorizeFn = photocraft_automation::workspace::authorize_desktop_engine_step;
let authorize = workspace.is_some().then_some(step);
let command = workspace.map(|_| {
Box::new(|id: &str, params: &serde_json::Value| {
photocraft_automation::workspace::authorize_desktop_engine_command(id, params).map_err(|error| error.to_string())
}) as photocraft_ui_egui::AutomationCommandFn
});
photocraft_ui_egui::AutomationServices { read, write, open_pcraft, save, command, authorize }
}
pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) -> Services {
let clip: Rc<RefCell<Option<arboard::Clipboard>>> = Rc::default();
let clip_unreadable: Rc<Cell<bool>> = Rc::default();
let automation = self::automation(automation);
Services {
import: Some(Box::new(|name: &str, bytes: &[u8], opts: &photocraft_io::ImportOptions| {
crate::crash_guard::guard("Open", || {
@@ -772,12 +779,12 @@ pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) ->
Some(photocraft_ui_egui::FileStamp { len: meta.len(), modified: meta.modified().ok() })
})),
same_file: Some(Box::new(|a: &str, b: &str| same_entry(Path::new(a), Path::new(b), same_file))),
automation_read,
automation_write,
automation_open_pcraft,
automation_save,
automation_command,
automation_authorize,
automation_read: automation.read,
automation_write: automation.write,
automation_open_pcraft: automation.open_pcraft,
automation_save: automation.save,
automation_command: automation.command,
automation_authorize: automation.authorize,
encode_png: Some(Box::new(|w, h, rgba| {
let img = Image::from_u8(w, h, ChannelLayout::Rgba, rgba.to_vec()).map_err(|e| e.to_string())?;
photocraft_codecs::encode(&img, photocraft_codecs::Format::Png, &EncodeOptions::default()).map_err(|e| e.to_string())
+13 -3
View File
@@ -1,17 +1,21 @@
# MCP
`photocraft-automation` implements an MCP server over stdio with two backends:
`photocraft-automation` implements an MCP server over stdio with three backends:
- **Headless:** an in-process `Headless` session owns the engine and performs file I/O.
- **Bridge:** `BridgeClient` forwards tools to a desktop application started with `photocraft --control <port>`.
- **The open window:** plain `photocraft-cli mcp` finds the desktop application through the connection file it publishes while the person lets agents use it (ArtCraft Launcher › Settings › AI agents), before every tool call; while the app is closed it starts it, serves a headless session, or reports an error, as chosen in Preferences › AI Integrations. Without that consent, or with `--headless`, it is the headless session above.
The simplest setup needs no terminal: turn on ArtCraft Launcher › Settings › AI agents and click *Add* next to the AI app; that one entry reaches every Craft app. See [`docs/mcp.md`](../../../docs/mcp.md#connecting-the-desktop-app-no-terminal).
For a source checkout, first [install the CLI on PATH and register the server](../../../docs/mcp.md#install-and-register).
The installed binary survives `cargo clean`; a symlink into `target/release` does not.
Start the headless server with:
Start the headless server with (without `--headless`, `mcp` works in the open PhotoCraft window
while the ArtCraft Launcher's agents switch is on):
```sh
photocraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project
photocraft-cli mcp --headless --automation-read-root /work/project --automation-write-root /work/project
```
Bridge to a running desktop application with the same private token file used by the app:
@@ -56,6 +60,12 @@ explicitly granted at launch; omitting a root omits that authority. Bridge mode
loopback control connection with a bearer token before invoking any control method and uses the
roots configured on the desktop process.
The launcher's switch (off by default) opens the same loopback, token-authenticated control
listener as `--control`, with a token the app keeps in its settings folder (`agent-control.token`,
user-only on Unix; delete it for a new one). The folders chosen in Preferences › AI Integrations
are the desktop process's roots, and the roots of a `mcp` headless session only when agents may
use the app and *When PhotoCraft is closed* is set to work without a window.
The current server does not issue scoped sessions or distinguish trusted tools from high-impact tools. Authentication proves possession of the token; it does not restrict an authenticated client to document-only access. Do not expose either transport through an untrusted broker, shell, proxy, or remote service without adding an external policy boundary.
Filesystem capabilities are implemented. General tool and method capabilities remain
+8
View File
@@ -29,6 +29,14 @@ Automation is a privilege boundary because requests can cause filesystem access,
Screenshots are decoded under separate dimension, pixel, and allocation ceilings before
downscaling; the 5 MiB PNG limit applies to the returned image.
- MCP normally uses stdio and can optionally bridge to loopback control TCP.
- ArtCraft Launcher › Settings › AI agents (off by default; one switch for every Craft app) opens that loopback
listener without launch flags. Its token is kept in a user-only file in the settings folder
(`agent-control.token`) and stays the same across restarts and port changes: restarting does
not revoke it. To revoke an exposed token, delete that file; the next start creates a new one.
The published `agent-connection.json` holds the port and the token file's path, never the
token. `photocraft-cli mcp` authenticates with the challenge handshake, so the token
itself is never sent: the listener must first prove it holds the token, and a stale file whose
port another program took fails that check before the client reveals anything.
- The bridge and UI request paths use timeouts.
- Engine commands are expected to reject invalid parameters without panicking.
- Remote filesystem methods use separately granted read and write directory capabilities.
+3
View File
@@ -39,6 +39,9 @@ hmac = "0.12"
sha2 = "0.10"
cap-std = "4"
clap = { workspace = true }
# The suite's AI-MCP flag and the ArtCraft Launcher's agents switch (the one consent for agents).
craft-flags = { workspace = true }
craft-ai-agents = { workspace = true }
# Optional native GPU rendering backend
photocraft-gpu = { workspace = true, optional = true }
+387
View File
@@ -0,0 +1,387 @@
//! Connecting AI agents to the open desktop app: whether the person lets them (one switch, in
//! the ArtCraft Launcher, [`agents_allowed`]), and how a local client finds the app's control
//! server without being told. Adding PhotoCraft to MCP clients is the launcher's job (one entry
//! for every Craft app), so nothing here writes a client's configuration.
//!
//! While agents may connect (and no `--control` was given), the app serves its control protocol
//! on loopback and publishes where in its settings folder ([`CONNECTION_FILE`]): the port, its
//! process id and the bearer-token file ([`TOKEN_FILE`] unless a token file was given at launch;
//! created `0600` on Unix, see [`crate::security::server_token`]). A local client reads that
//! file, then the token from the file it names, so nothing has to pass a port or a token to an
//! app started from the Dock, the Start menu or a file manager.
//!
//! The file holds no secret. A crashed (or, on macOS, quit) app can leave it behind; nothing then
//! listens on its port ([`probe`]), and the app's next launch replaces it or removes it
//! ([`remove_stale_connection`]). Until then another program could take that port, so a client
//! checks that [`Connection::pid`] is still running before it sends the token. That narrows the
//! gap without closing it (a pid can be reused); `docs/control-protocol.md` says when a client
//! should not send the token on the strength of this file.
//!
//! The app starts and stops that server at once when the switch changes. `photocraft-cli mcp`
//! ([`crate::live`]) reads the connection file on every tool call, so MCP client configurations
//! never hold a port or a token, and keep working when the app restarts on another port.
use std::net::{SocketAddr, TcpStream};
use std::path::{Path, PathBuf};
use std::time::Duration;
use photocraft_engine::prefs::Integrations;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::AutomationError;
/// The connection file in the settings folder, present while the app accepts agents.
pub const CONNECTION_FILE: &str = "agent-connection.json";
/// The bearer-token file the app keeps in its settings folder for agent connections.
pub const TOKEN_FILE: &str = "agent-control.token";
/// The server name MCP clients list PhotoCraft under.
pub const SERVER_NAME: &str = "photocraft";
/// How long [`probe`] waits for the app to accept a connection.
pub const PROBE_TIMEOUT: Duration = Duration::from_millis(500);
/// Version of the [`Connection`] file format.
const CONNECTION_VERSION: u32 = 1;
/// Largest connection file read; anything bigger is not ours.
const MAX_CONNECTION_BYTES: u64 = 1 << 20;
/// What the app publishes in [`CONNECTION_FILE`]. Holds no secret: the token stays in its own
/// user-only file.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Connection {
pub version: u32,
/// The app's process id: only that process removes the file.
pub pid: u32,
/// Loopback port of the control server.
pub port: u16,
pub token_file: PathBuf,
/// The app's version, for diagnostics.
pub app: String,
}
impl Connection {
pub fn new(port: u16, token_file: PathBuf) -> Self {
Connection { version: CONNECTION_VERSION, pid: std::process::id(), port, token_file, app: photocraft_engine::build_info::long_version() }
}
/// `127.0.0.1:<port>`.
pub fn addr(&self) -> String {
format!("127.0.0.1:{}", self.port)
}
}
fn io_error(path: &Path, e: impl std::fmt::Display) -> AutomationError {
AutomationError::Io(format!("{}: {e}", path.display()))
}
/// Publish `c` in `dir` (written atomically, so a reader never sees half a file).
pub fn write_connection(dir: &Path, c: &Connection) -> Result<(), AutomationError> {
std::fs::create_dir_all(dir).map_err(|e| io_error(dir, e))?;
let path = dir.join(CONNECTION_FILE);
let text = serde_json::to_string_pretty(c).map_err(|e| AutomationError::Other(e.to_string()))?;
photocraft_format::atomic_write(&path, text.as_bytes()).map_err(|e| io_error(&path, e))
}
/// The connection published in `dir`, if any. A file from another version or one that doesn't
/// parse (invalid UTF-8 included) counts as none: the app rewrites it when it next starts
/// listening. Anything but a regular file (a FIFO would block the read) is an error, and left
/// alone.
pub fn read_connection(dir: &Path) -> Result<Option<Connection>, AutomationError> {
let path = dir.join(CONNECTION_FILE);
let meta = match std::fs::metadata(&path) {
Ok(m) => m,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(io_error(&path, e)),
};
if !meta.is_file() {
return Err(io_error(&path, "not a regular file"));
}
if meta.len() > MAX_CONNECTION_BYTES {
return Err(io_error(&path, format!("larger than {MAX_CONNECTION_BYTES} bytes")));
}
let bytes = match std::fs::read(&path) {
Ok(b) => b,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(io_error(&path, e)),
};
Ok(serde_json::from_slice::<Connection>(&bytes).ok().filter(|c| c.version == CONNECTION_VERSION && c.port != 0))
}
/// Remove the connection file in `dir` if process `pid` wrote it (another instance may have
/// published its own since). Errors are ignored: a stale file only fails [`probe`].
pub fn remove_connection(dir: &Path, pid: u32) {
if let Ok(Some(c)) = read_connection(dir)
&& c.pid == pid
{
let _ = std::fs::remove_file(dir.join(CONNECTION_FILE));
}
}
/// Remove the connection file in `dir` when nothing listens on its port any more (an app that
/// crashed or quit without removing it), or when it doesn't read as a connection. A live
/// instance's file is kept. Errors are ignored.
pub fn remove_stale_connection(dir: &Path) {
let path = dir.join(CONNECTION_FILE);
let stale = match read_connection(dir) {
Ok(Some(c)) => !probe(c.port, PROBE_TIMEOUT),
Ok(None) => path.is_file(),
Err(_) => false,
};
if stale {
let _ = std::fs::remove_file(path);
}
}
/// Does something accept connections on loopback `port`? (A crashed app leaves its connection
/// file behind; nothing listens on its port any more.)
pub fn probe(port: u16, timeout: Duration) -> bool {
port != 0 && TcpStream::connect_timeout(&SocketAddr::from(([127, 0, 0, 1], port)), timeout).is_ok()
}
/// A folder preference as a path (`None` when empty or blank).
pub fn folder(pref: &str) -> Option<PathBuf> {
let pref = pref.trim();
(!pref.is_empty()).then(|| PathBuf::from(pref))
}
/// Largest client configuration file read; anything bigger is not ours.
const MAX_CONFIG_BYTES: u64 = 16 << 20;
/// Read a small text file, refusing anything larger than [`MAX_CONFIG_BYTES`] or anything but a
/// regular file (a FIFO would block the read).
fn read_small(path: &Path) -> Result<Option<String>, AutomationError> {
let meta = match std::fs::metadata(path) {
Ok(m) => m,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(io_error(path, e)),
};
if !meta.is_file() {
return Err(io_error(path, "not a regular file"));
}
if meta.len() > MAX_CONFIG_BYTES {
return Err(io_error(path, format!("larger than {MAX_CONFIG_BYTES} bytes")));
}
match std::fs::read_to_string(path) {
Ok(s) => Ok(Some(s)),
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
Err(e) => Err(io_error(path, e)),
}
}
/// The MCP preferences saved in `dir/preferences.json` (defaults when the file or
/// the section is missing or unreadable: the CLI must not fail over the app's settings).
pub fn read_integrations(dir: &Path) -> Integrations {
read_small(&dir.join("preferences.json"))
.ok()
.flatten()
.and_then(|text| serde_json::from_str::<Value>(&text).ok())
.and_then(|v| v.get("integrations").cloned())
.map(photocraft_engine::prefs::read_integrations_section)
.unwrap_or_default()
}
// ---- The agents switch -------------------------------------------------------------------------
/// The id the ArtCraft Launcher's app list names PhotoCraft by.
pub const LAUNCHER_APP_ID: &str = "photocraft";
/// The suite's `AI-MCP` feature flag (`ArtCraft/flags.toml` or `CRAFT_FLAGS`).
pub fn mcp_flag() -> bool {
craft_flags::load().enabled(&craft_flags::AI_MCP)
}
/// The ArtCraft Launcher's switch (Settings › AI agents › *Let AI agents use Craft apps*) lets
/// agents use PhotoCraft: the `AI-MCP` flag is on and the launcher's app list names PhotoCraft,
/// read through `craft-ai-agents` like the launcher, the MCP gateway and every Craft app do. Reads
/// two small files; ask from a timer, not every frame.
pub fn launcher_allows_agents() -> bool {
mcp_flag() && craft_ai_agents::allowed(LAUNCHER_APP_ID)
}
/// Whether agents may use the open window. With the `AI-MCP` flag only the launcher's switch
/// decides: there is one switch for every Craft app, and none in PhotoCraft. Without the flag it
/// is as on `main`: a Control Port saved in the preferences (`connect_agents`, set from it when
/// the preferences load). Allow Agent Control off still refuses agents either way.
pub fn agents_allowed(integrations: &Integrations, mcp_flag: bool, launcher: bool) -> bool {
if mcp_flag { launcher } else { integrations.connect_agents }
}
/// [`agents_allowed`] for this run: the flag and the launcher's switch as they are now.
pub fn agents_allowed_now(integrations: &Integrations) -> bool {
let flag = mcp_flag();
agents_allowed(integrations, flag, flag && craft_ai_agents::allowed(LAUNCHER_APP_ID))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicUsize, Ordering};
fn temp(tag: &str) -> PathBuf {
static N: AtomicUsize = AtomicUsize::new(0);
let d = std::env::temp_dir().join(format!("photocraft-agent-link-{tag}-{}-{}", std::process::id(), N.fetch_add(1, Ordering::Relaxed)));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
d
}
#[test]
fn with_the_flag_only_the_launchers_switch_lets_agents_in() {
let legacy = Integrations { connect_agents: true, ..Default::default() };
let none = Integrations::default();
// Without the AI-MCP flag: as on main, a Control Port saved before.
assert!(agents_allowed(&legacy, false, false));
assert!(!agents_allowed(&none, false, true), "the launcher's list means nothing without the flag");
// With the flag: the launcher's switch, and nothing else.
assert!(agents_allowed(&none, true, true));
assert!(!agents_allowed(&legacy, true, false), "no second switch in PhotoCraft");
}
#[test]
fn connection_round_trips_and_only_its_writer_removes_it() {
let dir = temp("conn");
assert_eq!(read_connection(&dir).unwrap(), None);
let c = Connection::new(4242, dir.join(TOKEN_FILE));
write_connection(&dir, &c).unwrap();
assert_eq!(read_connection(&dir).unwrap(), Some(c.clone()));
assert_eq!(c.addr(), "127.0.0.1:4242");
remove_connection(&dir, c.pid.wrapping_add(1));
assert!(dir.join(CONNECTION_FILE).exists(), "another instance's file stays");
remove_connection(&dir, c.pid);
assert!(!dir.join(CONNECTION_FILE).exists());
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_damaged_or_foreign_connection_file_counts_as_none() {
let dir = temp("bad-conn");
for text in
["", "{", "[]", r#"{"version":99,"pid":1,"port":1,"tokenFile":"t","app":"x"}"#, r#"{"version":1,"pid":1,"port":0,"tokenFile":"t","app":"x"}"#]
{
std::fs::write(dir.join(CONNECTION_FILE), text).unwrap();
assert_eq!(read_connection(&dir).unwrap(), None, "{text}");
}
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn probe_sees_a_listener_and_not_a_closed_port() {
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = listener.local_addr().unwrap().port();
assert!(probe(port, PROBE_TIMEOUT));
drop(listener);
assert!(!probe(port, PROBE_TIMEOUT));
assert!(!probe(0, PROBE_TIMEOUT));
}
#[test]
fn integrations_come_from_the_saved_preferences_or_default() {
let dir = temp("prefs");
assert_eq!(read_integrations(&dir), Integrations::default());
std::fs::write(dir.join("preferences.json"), "not json").unwrap();
assert_eq!(read_integrations(&dir), Integrations::default());
// A section of the wrong type doesn't fail the CLI either.
std::fs::write(dir.join("preferences.json"), r#"{"integrations": {"connectAgents": "yes"}}"#).unwrap();
assert_eq!(read_integrations(&dir), Integrations::default());
std::fs::write(
dir.join("preferences.json"),
r#"{"general": {}, "integrations": {"connectAgents": true, "whenAppClosed": "headless", "readRoot": "/in"}}"#,
)
.unwrap();
let i = read_integrations(&dir);
assert!(i.connect_agents);
assert_eq!(i.when_app_closed, photocraft_engine::prefs::WhenAppClosed::Headless);
assert_eq!(folder(&i.read_root), Some(PathBuf::from("/in")));
assert_eq!(folder(&i.write_root), None);
assert_eq!(folder(" "), None);
// A Control Port saved before the agents switch reads as on, as the app reads it.
std::fs::write(dir.join("preferences.json"), r#"{"integrations": {"controlPort": 7878}}"#).unwrap();
assert!(read_integrations(&dir).connect_agents);
std::fs::write(dir.join("preferences.json"), r#"{"integrations": {"controlPort": 7878, "connectAgents": false}}"#).unwrap();
assert!(!read_integrations(&dir).connect_agents);
// One bad value resets only itself, as in the app: the saved closed-app choice stays.
std::fs::write(dir.join("preferences.json"), r#"{"integrations": {"whenAppClosed": "error", "readRoot": 5}}"#).unwrap();
assert_eq!(read_integrations(&dir).when_app_closed, photocraft_engine::prefs::WhenAppClosed::Error);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_published_connection_reads_back_in_the_documented_shape() {
let dir = temp("conn");
let c = Connection::new(7878, dir.join(TOKEN_FILE));
write_connection(&dir, &c).unwrap();
assert_eq!(read_connection(&dir).unwrap(), Some(c.clone()));
let v: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(dir.join(CONNECTION_FILE)).unwrap()).unwrap();
let mut keys: Vec<_> = v.as_object().unwrap().keys().cloned().collect();
keys.sort();
assert_eq!(keys, ["app", "pid", "port", "tokenFile", "version"]);
assert_eq!((v["version"].as_u64(), v["port"].as_u64()), (Some(1), Some(7878)));
assert_eq!(c.addr(), "127.0.0.1:7878");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn other_versions_garbage_and_port_zero_read_as_none() {
let dir = temp("conn");
assert_eq!(read_connection(&dir).unwrap(), None, "no file");
for text in [
&b"{not json"[..],
br#"{"version":2,"pid":1,"port":7878,"tokenFile":"t","app":"x"}"#,
br#"{"version":1,"pid":1,"port":0,"tokenFile":"t","app":"x"}"#,
b"\xff\xfe not utf-8",
] {
std::fs::write(dir.join(CONNECTION_FILE), text).unwrap();
assert_eq!(read_connection(&dir).unwrap(), None, "{}", String::from_utf8_lossy(text));
}
std::fs::remove_file(dir.join(CONNECTION_FILE)).unwrap();
// Not a regular file: an error (and `remove_stale_connection` leaves it), never a read
// that could block on a FIFO.
std::fs::create_dir(dir.join(CONNECTION_FILE)).unwrap();
assert!(read_connection(&dir).is_err());
remove_stale_connection(&dir);
assert!(dir.join(CONNECTION_FILE).is_dir());
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn only_the_publishing_process_removes_its_file() {
let dir = temp("conn");
let c = Connection { pid: 1, ..Connection::new(7878, dir.join(TOKEN_FILE)) };
write_connection(&dir, &c).unwrap();
remove_connection(&dir, 2);
assert!(dir.join(CONNECTION_FILE).is_file(), "another process's file stays");
remove_connection(&dir, 1);
assert!(!dir.join(CONNECTION_FILE).exists());
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_stale_file_is_removed_and_a_live_one_kept() {
let dir = temp("conn");
let live = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let live_port = live.local_addr().unwrap().port();
write_connection(&dir, &Connection { pid: 1, ..Connection::new(live_port, dir.join(TOKEN_FILE)) }).unwrap();
remove_stale_connection(&dir);
assert!(dir.join(CONNECTION_FILE).is_file(), "something listens on {live_port}");
drop(live);
// A port nothing listens on: bind one, then close it.
let closed = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
write_connection(&dir, &Connection { pid: 1, ..Connection::new(closed, dir.join(TOKEN_FILE)) }).unwrap();
remove_stale_connection(&dir);
assert!(!dir.join(CONNECTION_FILE).exists(), "nothing listens on {closed}");
for text in [&b"{not json"[..], b"\xff\xfe not utf-8"] {
std::fs::write(dir.join(CONNECTION_FILE), text).unwrap();
remove_stale_connection(&dir);
assert!(!dir.join(CONNECTION_FILE).exists(), "an unreadable file is not a connection");
}
remove_stale_connection(&dir);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn folder_preferences_are_trimmed_and_empty_means_none() {
assert_eq!(folder(""), None);
assert_eq!(folder(" "), None);
assert_eq!(folder(" /work/project "), Some(PathBuf::from("/work/project")));
}
}
+114
View File
@@ -0,0 +1,114 @@
//! Where PhotoCraft keeps its per-user data, resolved the same way by the desktop app and
//! `photocraft-cli` (which finds the app's agent connection file there, see [`crate::agent_link`]).
//!
//! In order:
//! 1. `PHOTOCRAFT_CONFIG_DIR`, when set (tests, agents, custom setups).
//! 2. **Portable mode** (#228): a marker file ([`PORTABLE_MARKERS`]) beside the executable puts
//! everything in `<exe dir>/PhotoCraftData`, so a portable copy on a USB stick leaves nothing in
//! `%APPDATA%`. The Windows portable zip ships with `portable.txt`; the MSI doesn't. If that
//! folder can't be written (read-only medium, Program Files), the platform folder is used and
//! [`DataDir::warning`] says why.
//! 3. The platform convention: macOS `~/Library/Application Support/Photocraft`, Windows
//! `%APPDATA%\Photocraft`, Linux `$XDG_CONFIG_HOME/photocraft` or `~/.config/photocraft`.
//!
//! The desktop app's `app_dirs` resolves it once per process and adds the crash-recovery folder.
use std::ffi::OsString;
use std::path::{Path, PathBuf};
/// Files beside the executable that switch on portable mode (either one; contents are ignored).
pub const PORTABLE_MARKERS: [&str; 2] = ["portable.txt", "PhotoCraft.portable"];
/// The data folder created beside the executable in portable mode.
pub const PORTABLE_DATA_DIR: &str = "PhotoCraftData";
/// How [`DataDir::dir`] was chosen.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Mode {
/// `PHOTOCRAFT_CONFIG_DIR`.
Override,
/// `<exe dir>/PhotoCraftData`.
Portable,
/// The platform's per-user config directory.
Platform,
}
/// The resolved data directory.
#[derive(Clone, Debug)]
pub struct DataDir {
/// `None` only when no platform directory is known either (no `HOME`/`APPDATA`).
pub dir: Option<PathBuf>,
pub mode: Mode,
/// Set when a portable marker was found but its data folder isn't writable.
pub warning: Option<String>,
}
/// Resolve the data directory from the environment (`env`) and the executable's folder.
pub fn resolve(env: impl Fn(&str) -> Option<OsString>, exe_dir: Option<&Path>) -> DataDir {
if let Some(d) = env("PHOTOCRAFT_CONFIG_DIR").filter(|d| !d.is_empty()) {
return DataDir { dir: Some(PathBuf::from(d)), mode: Mode::Override, warning: None };
}
let platform = platform_dir(&env);
let Some((exe_dir, marker)) = exe_dir.and_then(|d| portable_marker(d).map(|m| (d, m))) else {
return DataDir { dir: platform, mode: Mode::Platform, warning: None };
};
let data = exe_dir.join(PORTABLE_DATA_DIR);
match ensure_writable(&data) {
Ok(()) => DataDir { dir: Some(data), mode: Mode::Portable, warning: None },
Err(e) => {
let fallback = platform.as_ref().map_or_else(|| "nowhere (no user folder found)".to_string(), |p| p.display().to_string());
let warning =
format!("portable mode ({} found) but {} isn't writable ({e}); settings are kept in {fallback} instead", marker.display(), data.display());
DataDir { dir: platform, mode: Mode::Platform, warning: Some(warning) }
}
}
}
/// The platform convention, from `env` (so tests can fake `HOME`/`APPDATA`/`XDG_CONFIG_HOME`).
pub fn platform_dir(env: &impl Fn(&str) -> Option<OsString>) -> Option<PathBuf> {
let home = env("HOME").filter(|h| !h.is_empty()).map(PathBuf::from);
if cfg!(target_os = "macos") {
return home.map(|h| h.join("Library/Application Support/Photocraft"));
}
if cfg!(windows) {
return env("APPDATA").filter(|a| !a.is_empty()).map(|a| PathBuf::from(a).join("Photocraft"));
}
env("XDG_CONFIG_HOME").filter(|x| !x.is_empty()).map(PathBuf::from).or_else(|| home.map(|h| h.join(".config"))).map(|c| c.join("photocraft"))
}
/// The first portable marker file in `exe_dir`, if any.
pub fn portable_marker(exe_dir: &Path) -> Option<PathBuf> {
PORTABLE_MARKERS.iter().map(|m| exe_dir.join(m)).find(|p| p.is_file())
}
/// Probe names tried before giving up on a portable data folder.
pub const WRITE_PROBE_ATTEMPTS: u32 = 64;
/// Create `dir` and prove a file can be written in it (a folder can exist yet be read-only).
///
/// The probe is created exclusively (`create_new`), so an entry already at its name (a link
/// someone else placed there, say) is never opened, written through or removed: the next name
/// is tried instead. Only a probe this call created is removed.
pub fn ensure_writable(dir: &Path) -> std::io::Result<()> {
std::fs::create_dir_all(dir)?;
let pid = std::process::id();
for attempt in 0..WRITE_PROBE_ATTEMPTS {
let probe = dir.join(format!(".write-test-{pid}-{attempt}"));
match std::fs::OpenOptions::new().write(true).create_new(true).open(&probe) {
Ok(file) => {
drop(file);
// A leftover probe is harmless; don't fail portable mode over it.
let _ = std::fs::remove_file(&probe);
return Ok(());
}
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(e) => return Err(e),
}
}
Err(std::io::Error::new(std::io::ErrorKind::AlreadyExists, "every write-test name is already taken"))
}
/// The data directory for this process's environment and executable (not cached).
pub fn from_env() -> DataDir {
let exe = std::env::current_exe().ok();
resolve(|k| std::env::var_os(k), exe.as_deref().and_then(Path::parent))
}
+5
View File
@@ -11,16 +11,21 @@
//! * [`rpc`]: a headless JSON-lines server (stdio or loopback TCP) with the
//! control protocol's envelope, used by `photocraft-cli serve`.
//! * [`files`]: open/save any supported format, `.pcraft` natively.
//! * [`agent_link`] and [`live`]: connecting agents to the desktop app without a terminal
//! (the ArtCraft Launcher's agents switch and plain `photocraft-cli mcp`).
//!
//! L6, no UI-toolkit dependencies.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
pub mod agent_link;
pub mod app_dirs;
pub mod args;
pub mod bridge;
pub mod budgets;
pub mod files;
pub mod headless;
pub mod live;
pub mod rpc;
pub mod security;
pub mod server;
+295
View File
@@ -0,0 +1,295 @@
//! `photocraft-cli mcp`: tools go to the open desktop app when the person lets agents use it,
//! found through its connection file ([`crate::agent_link`]), and otherwise to a session without
//! a window, as `mcp` always did (`--headless` forces that). The file is looked up again on every
//! tool call, so the app may start, quit or move to another port while the MCP client stays
//! connected, and the MCP client's own start never opens a window.
//!
//! While agents may use the app but it is closed, When PhotoCraft Is Closed (or `--when-closed`)
//! decides: start the app and wait for it, serve a headless session with the folders chosen in
//! the app, or report an error that says what to do. A session that went headless stays headless
//! for the rest of the MCP session, so documents don't move under the agent.
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, PoisonError};
use std::time::{Duration, Instant};
use photocraft_engine::prefs::WhenAppClosed;
use crate::agent_link::{self, Connection, PROBE_TIMEOUT};
use crate::bridge::BridgeClient;
use crate::headless::Headless;
use crate::{AuthorizedWorkspace, security};
/// Starts the desktop app (see [`launcher`]).
pub type LaunchFn = Box<dyn Fn() -> Result<(), String> + Send + Sync>;
/// Prepares a headless session before its first call (see [`LiveConfig::prepare_headless`]).
pub type PrepareFn = Box<dyn Fn(&mut Headless) + Send + Sync>;
/// How long a started app gets to accept agents. A first start can take a while (GPU driver
/// shader caches, font scan), but MCP clients give a tool call about a minute.
pub const LAUNCH_TIMEOUT: Duration = Duration::from_secs(45);
const POLL: Duration = Duration::from_millis(250);
pub struct LiveConfig {
/// The app's settings folder: connection file, token and preferences.
pub config_dir: PathBuf,
/// Overrides the app's preference (`--when-closed`).
pub when_closed: Option<WhenAppClosed>,
/// The folders a headless session may use (`--automation-read-root`, repeatable, and
/// `--automation-write-root`); while agents may use the app, they override its folders.
pub read_roots: Vec<PathBuf>,
pub write_root: Option<PathBuf>,
/// Starts the app; `None` when this install can't (Flatpak sandbox, no app beside the CLI).
pub launch: Option<LaunchFn>,
pub launch_timeout: Duration,
/// Whether the person lets agents use the open app, given its saved preferences
/// ([`agent_link::agents_allowed_now`]: the ArtCraft Launcher's switch); tests replace it.
pub allowed: fn(&photocraft_engine::prefs::Integrations) -> bool,
/// Prepares a headless session before its first call (the CLI's `--gpu` / `--no-gpu`).
pub prepare_headless: Option<PrepareFn>,
}
impl LiveConfig {
pub fn new(config_dir: PathBuf) -> Self {
LiveConfig {
config_dir,
when_closed: None,
read_roots: Vec::new(),
write_root: None,
launch: None,
launch_timeout: LAUNCH_TIMEOUT,
allowed: agent_link::agents_allowed_now,
prepare_headless: None,
}
}
}
/// Where a tool call goes once [`Live::resolve`] has run.
#[derive(Clone)]
pub(crate) enum Target {
Bridge(Arc<BridgeClient>),
Headless(Arc<Mutex<Headless>>),
}
/// The port and token a bridge client was made for: when the app restarts, either changes.
type BridgeKey = (u16, String, u32);
pub struct Live {
cfg: LiveConfig,
/// Serialises lookups, so concurrent calls start the app once.
lookup: tokio::sync::Mutex<()>,
/// The current target, and for the bridge the port and token it was made for.
current: Mutex<Option<(Target, Option<BridgeKey>)>>,
}
impl Live {
pub fn new(cfg: LiveConfig) -> Self {
Live { cfg, lookup: tokio::sync::Mutex::new(()), current: Mutex::new(None) }
}
pub(crate) fn current(&self) -> Option<Target> {
self.current.lock().unwrap_or_else(PoisonError::into_inner).as_ref().map(|(t, _)| t.clone())
}
fn set(&self, target: Target, key: Option<BridgeKey>) {
*self.current.lock().unwrap_or_else(PoisonError::into_inner) = Some((target, key));
}
/// Find the app (or apply the closed-app choice) before a tool call. The error is the tool's
/// result: it tells the agent, and through it the user, what to do.
pub(crate) async fn resolve(&self) -> Result<(), String> {
let _one_at_a_time = self.lookup.lock().await;
if matches!(self.current(), Some(Target::Headless(_))) {
return Ok(());
}
let dir = self.cfg.config_dir.clone();
let consent = self.cfg.allowed;
let (found, integrations, allowed) = blocking(move || {
let integrations = agent_link::read_integrations(&dir);
let allowed = consent(&integrations);
(find_app(&dir), integrations, allowed)
})
.await?;
if let Some((c, token)) = found? {
self.use_app(&c, token)?;
return Ok(());
}
if !allowed {
// As `mcp` always worked: a session without a window, with only the folders given to
// this command. The app's own folders are for agents the person let in.
return self.headless(&self.cfg.read_roots, self.cfg.write_root.clone(), "the automation roots can't be used");
}
match self.cfg.when_closed.unwrap_or(integrations.when_app_closed) {
WhenAppClosed::Error => Err("PhotoCraft isn't running: open it, then try again.".into()),
WhenAppClosed::Headless => {
let reads = if self.cfg.read_roots.is_empty() {
agent_link::folder(&integrations.read_root).into_iter().collect()
} else {
self.cfg.read_roots.clone()
};
let write = self.cfg.write_root.clone().or_else(|| agent_link::folder(&integrations.write_root));
self.headless(&reads, write, "PhotoCraft isn't running and its agent folders can't be used")
}
WhenAppClosed::Launch => self.launch_and_wait().await,
}
}
/// Serve a headless session with these folders from now on.
fn headless(&self, reads: &[PathBuf], write: Option<PathBuf>, why: &str) -> Result<(), String> {
let workspace = AuthorizedWorkspace::with_read_roots(reads.iter().map(PathBuf::as_path), write.as_deref()).map_err(|e| format!("{why}: {e}"))?;
let mut session = Headless::with_workspace(workspace);
if let Some(prepare) = &self.cfg.prepare_headless {
prepare(&mut session);
}
self.set(Target::Headless(Arc::new(Mutex::new(session))), None);
Ok(())
}
/// Start the app (agents may use it) and wait until it accepts them.
async fn launch_and_wait(&self) -> Result<(), String> {
let Some(launch) = &self.cfg.launch else {
return Err("PhotoCraft isn't running, and this install can't start it from here: open PhotoCraft, then try again.".into());
};
launch().map_err(|e| format!("couldn't start PhotoCraft: {e}"))?;
let deadline = Instant::now() + self.cfg.launch_timeout;
loop {
tokio::time::sleep(POLL).await;
let dir = self.cfg.config_dir.clone();
if let Some((c, token)) = blocking(move || find_app(&dir)).await?? {
return self.use_app(&c, token);
}
if Instant::now() >= deadline {
return Err(format!(
"PhotoCraft didn't accept agents within {} s of starting. If it's still opening, try again in a moment; otherwise check that AI agents are on in ArtCraft Launcher › Settings › AI agents.",
self.cfg.launch_timeout.as_secs()
));
}
}
}
fn use_app(&self, c: &Connection, token: String) -> Result<(), String> {
// The pid too: a restarted app keeps its port and token, but the old socket is dead.
let key: BridgeKey = (c.port, token, c.pid);
let same = self.current.lock().unwrap_or_else(PoisonError::into_inner).as_ref().is_some_and(|(_, k)| k.as_ref() == Some(&key));
if !same {
let client = BridgeClient::new(c.addr(), key.1.clone()).map_err(|e| e.to_string())?;
self.set(Target::Bridge(Arc::new(client)), Some(key));
}
Ok(())
}
}
/// Run blocking file and socket work off the async runtime.
async fn blocking<T: Send + 'static>(f: impl FnOnce() -> T + Send + 'static) -> Result<T, String> {
tokio::task::spawn_blocking(f).await.map_err(|e| format!("task failed: {e}"))
}
/// The running app's connection and token: `None` when no app accepts agents (no connection
/// file, or one left by an app that crashed).
fn find_app(dir: &Path) -> Result<Option<(Connection, String)>, String> {
let Some(c) = agent_link::read_connection(dir).map_err(|e| e.to_string())? else { return Ok(None) };
if !agent_link::probe(c.port, PROBE_TIMEOUT) {
return Ok(None);
}
let token = security::client_token(None, Some(&c.token_file)).map_err(|e| format!("PhotoCraft's agent token: {e}"))?;
Ok(Some((c, token)))
}
/// How to start the desktop app that ships with the CLI at `cli` (detached, with no standard
/// streams: the CLI's carry the MCP protocol, and the app must outlive the MCP client).
pub fn launcher(cli: &Path) -> Option<LaunchFn> {
use std::process::{Command, Stdio};
if std::env::var_os("FLATPAK_ID").is_some() {
return None;
}
let command: Command = if let Some(image) = std::env::var_os("APPIMAGE").filter(|v| !v.is_empty()) {
// The AppImage's mount point goes away with the CLI; the image itself stays.
Command::new(image)
} else {
let dir = cli.parent()?;
let bundle = dir.parent().filter(|_| dir.ends_with("Contents/MacOS")).and_then(Path::parent);
match bundle {
// A macOS app bundle: LaunchServices starts (or brings forward) the app.
Some(app) if cfg!(target_os = "macos") => {
let mut c = Command::new("/usr/bin/open");
c.arg("-a").arg(app);
c
}
_ => {
let app = dir.join(if cfg!(windows) { "photocraft.exe" } else { "photocraft" });
if !app.is_file() {
return None;
}
if cfg!(windows) {
let (program, args) = windows_launch(&app, std::env::var_os("SystemRoot").as_deref());
let mut c = Command::new(program);
c.args(args);
c
} else {
Command::new(app)
}
}
}
};
let command = Mutex::new(command);
Some(Box::new(move || {
let mut c = command.lock().unwrap_or_else(PoisonError::into_inner);
c.stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::null());
detach(&mut c);
c.spawn().map(|_| ()).map_err(|e| e.to_string())
}))
}
/// How Windows starts the app at `app`: through Explorer, as a double-click would. The app is then
/// no child of the CLI, so it outlives the MCP client ending the CLI's process tree (Claude Code
/// does on Windows), and it runs outside the container of a Microsoft Store client (Claude
/// Desktop): there, new files under `%APPDATA%` land in the client's package, where the app
/// started from the Start menu would never see the settings saved meanwhile. Explorer reads a
/// comma as a separator, so such a path is started directly. (`%WINDIR%` can be empty under a
/// Store client, hence `%SystemRoot%`.)
fn windows_launch(app: &Path, system_root: Option<&std::ffi::OsStr>) -> (PathBuf, Vec<std::ffi::OsString>) {
if app.to_string_lossy().contains(',') {
return (app.to_path_buf(), Vec::new());
}
let root = system_root.filter(|r| !r.is_empty()).map_or_else(|| PathBuf::from(r"C:\Windows"), PathBuf::from);
(root.join("explorer.exe"), vec![app.as_os_str().to_os_string()])
}
/// Keep the app running when the MCP client stops the CLI (and its process group).
fn detach(c: &mut std::process::Command) {
#[cfg(unix)]
{
use std::os::unix::process::CommandExt;
c.process_group(0);
}
#[cfg(windows)]
{
use std::os::windows::process::CommandExt;
const DETACHED_PROCESS: u32 = 0x0000_0008;
const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
c.creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP);
}
#[cfg(not(any(unix, windows)))]
let _ = c;
}
#[cfg(test)]
mod tests {
use super::*;
use std::ffi::OsStr;
#[test]
fn windows_starts_the_app_through_explorer() {
let app = Path::new(r"C:\Program Files\PhotoCraft\photocraft.exe");
let (program, args) = windows_launch(app, Some(OsStr::new(r"D:\Win")));
assert_eq!(program, Path::new(r"D:\Win").join("explorer.exe"));
assert_eq!(args, [app.as_os_str()]);
// No usable %SystemRoot%: the default Windows folder.
let default = Path::new(r"C:\Windows").join("explorer.exe");
assert_eq!(windows_launch(app, Some(OsStr::new(""))).0, default);
assert_eq!(windows_launch(app, None).0, default);
// Explorer would split this path at the comma.
let comma = Path::new(r"C:\Apps, tools\photocraft.exe");
assert_eq!(windows_launch(comma, None), (comma.to_path_buf(), Vec::new()));
}
}
+32
View File
@@ -282,6 +282,20 @@ fn create_token_file(path: &Path, token: &str) -> Result<(), AutomationError> {
writeln!(file, "{token}").map_err(|e| AutomationError::Io(format!("{}: {e}", path.display())))
}
/// Write a fresh token to `path`, replacing any earlier one (user-only on Unix), and return it.
/// The desktop app rotates the agent-connection token this way each time it starts listening, so
/// a token sent to a port another program took over after a crash stops working.
pub fn replace_token_file(path: &Path) -> Result<String, AutomationError> {
let token = generate_token()?;
match std::fs::remove_file(path) {
Ok(()) => {}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
Err(e) => return Err(AutomationError::Io(format!("{}: {e}", path.display()))),
}
create_token_file(path, &token)?;
Ok(token)
}
/// Resolve a server token. With no supplied token or file, a fresh token is returned.
/// A missing token file is created atomically; an existing one is read and validated.
pub fn server_token(supplied: Option<&str>, token_file: Option<&Path>) -> Result<String, AutomationError> {
@@ -486,6 +500,24 @@ mod tests {
}
}
#[test]
fn replaced_token_files_hold_a_new_valid_token() {
let dir = std::env::temp_dir().join(format!("photocraft-replace-token-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
let path = dir.join("agent.token");
let first = replace_token_file(&path).unwrap();
assert_eq!(client_token(None, Some(&path)).unwrap(), first);
let second = replace_token_file(&path).unwrap();
assert_ne!(first, second);
assert_eq!(client_token(None, Some(&path)).unwrap(), second);
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
assert_eq!(std::fs::metadata(&path).unwrap().permissions().mode() & 0o777, 0o600);
}
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn generated_tokens_are_valid_and_distinct() {
let a = generate_token().unwrap();
+74 -13
View File
@@ -18,6 +18,7 @@ use serde_json::{Value, json};
use crate::bridge::BridgeClient;
use crate::budgets::{BatchReplyBudget, MAX_PREVIEW_SIDE, check_png, json_bytes};
use crate::headless::Headless;
use crate::live::{Live, LiveConfig, Target};
use crate::security::MAX_BATCH_STEPS;
use crate::{AuthorizedWorkspace, AutomationError, files};
@@ -27,6 +28,9 @@ pub enum Backend {
Headless(Arc<Mutex<Headless>>),
/// A running desktop app reached over the control protocol.
Bridge(Arc<BridgeClient>),
/// The desktop app found through its connection file before each call, or the closed-app
/// choice (plain `photocraft-cli mcp`, see [`crate::live`]).
Live(Arc<Live>),
}
#[derive(Clone)]
@@ -619,6 +623,12 @@ impl PhotocraftMcp {
Ok(Self::with_backend(Backend::Bridge(Arc::new(BridgeClient::new(addr, token)?))))
}
/// Serve the desktop app found through its connection file, or headless without consent
/// (plain `photocraft-cli mcp`).
pub fn live(config: LiveConfig) -> Self {
Self::with_backend(Backend::Live(Arc::new(Live::new(config))))
}
pub fn with_backend(backend: Backend) -> Self {
let mut tool_router = Self::tool_router();
for route in tool_router.map.values_mut() {
@@ -639,10 +649,7 @@ impl PhotocraftMcp {
&self,
f: impl FnOnce(&mut Headless) -> Result<T, AutomationError> + Send + 'static,
) -> Option<Result<T, AutomationError>> {
let Backend::Headless(h) = &*self.backend else {
return None;
};
let h = h.clone();
let h = self.headless_session()?;
Some(
tokio::task::spawn_blocking(move || {
// A panicking command poisons the lock, but edits run on a copy
@@ -657,13 +664,47 @@ impl PhotocraftMcp {
)
}
fn bridge_client(&self) -> Option<&BridgeClient> {
/// The headless session tools run on, if this backend (or the live choice) is one.
fn headless_session(&self) -> Option<Arc<Mutex<Headless>>> {
match &*self.backend {
Backend::Bridge(b) => Some(b),
Backend::Headless(h) => Some(h.clone()),
Backend::Live(live) => match live.current()? {
Target::Headless(h) => Some(h),
Target::Bridge(_) => None,
},
Backend::Bridge(_) => None,
}
}
fn bridge_client(&self) -> Option<Arc<BridgeClient>> {
match &*self.backend {
Backend::Bridge(b) => Some(b.clone()),
Backend::Live(live) => match live.current()? {
Target::Bridge(b) => Some(b),
Target::Headless(_) => None,
},
Backend::Headless(_) => None,
}
}
/// Where calls go now: the backend's session or app, or the live mode's last resolve.
fn target(&self) -> Option<Target> {
match &*self.backend {
Backend::Headless(h) => Some(Target::Headless(h.clone())),
Backend::Bridge(b) => Some(Target::Bridge(b.clone())),
Backend::Live(live) => live.current(),
}
}
/// Live mode: find the app (or apply the closed-app choice) before a call; the error is the
/// call's result. Other backends are always ready.
async fn ready(&self) -> Result<(), String> {
match &*self.backend {
Backend::Live(live) => live.resolve().await,
Backend::Headless(_) | Backend::Bridge(_) => Ok(()),
}
}
async fn screenshot(&self, b: &BridgeClient, max_side: Option<u32>) -> Result<CallToolResult, McpError> {
if max_side.is_some_and(|side| side > MAX_PREVIEW_SIDE) {
return Ok(fail(format!("automation preview side exceeds {MAX_PREVIEW_SIDE} pixels")));
@@ -960,7 +1001,7 @@ impl PhotocraftMcp {
if p.index.is_some() {
return Ok(fail("`index` is only supported in headless mode; bridge previews capture the app window"));
}
self.screenshot(b, Some(max)).await
self.screenshot(&b, Some(max)).await
}
#[tool(description = "Render a bounded flattened PNG preview (bridge mode: app window screenshot).")]
@@ -1056,7 +1097,7 @@ impl PhotocraftMcp {
#[tool(description = "Bridge mode: screenshot of the live app window as PNG.")]
async fn ui_screenshot(&self, Parameters(p): Parameters<ScreenshotParams>) -> Result<CallToolResult, McpError> {
match self.bridge_client() {
Some(b) => self.screenshot(b, p.max_side).await,
Some(b) => self.screenshot(&b, p.max_side).await,
None => bridge_only("ui_screenshot"),
}
}
@@ -1107,6 +1148,16 @@ impl PhotocraftMcp {
}
}
/// Whether two targets are the same session or the same app connection.
fn same_target(a: Option<&Target>, b: Option<&Target>) -> bool {
match (a, b) {
(Some(Target::Headless(a)), Some(Target::Headless(b))) => Arc::ptr_eq(a, b),
(Some(Target::Bridge(a)), Some(Target::Bridge(b))) => Arc::ptr_eq(a, b),
(None, None) => true,
_ => false,
}
}
fn bridge_only_headless(name: &str) -> Result<CallToolResult, McpError> {
Ok(fail(format!("`{name}` is only available in headless mode (in the GUI use the window/tab UI or control_call)")))
}
@@ -1119,11 +1170,13 @@ impl PhotocraftMcp {
/// Run one command in either backend; `at` is its place in a batch, for progress.
async fn step(&self, id: String, params: Value, wait: bool, waiter: &mut Waiter, at: (usize, usize)) -> Result<Value, AutomationError> {
let none = || Err(AutomationError::Other("internal error: no headless session or app bridge".into()));
match &*self.backend {
Backend::Headless(_) if wait => self.headless_wait(id, params, waiter, at).await.unwrap_or_else(none),
Backend::Headless(_) => self.headless_op(move |h| h.command_start(&id, params, false)).await.unwrap_or_else(none),
Backend::Bridge(b) if wait => self.bridge_wait(b, id, params, waiter, at).await,
Backend::Bridge(b) => b.call("engine.execute", json!({"command": id, "params": params, "wait": false})).await,
// Live mode goes wherever its last resolve pointed: the app, or a headless session.
match (self.headless_session(), self.bridge_client()) {
(Some(_), _) if wait => self.headless_wait(id, params, waiter, at).await.unwrap_or_else(none),
(Some(_), _) => self.headless_op(move |h| h.command_start(&id, params, false)).await.unwrap_or_else(none),
(None, Some(b)) if wait => self.bridge_wait(&b, id, params, waiter, at).await,
(None, Some(b)) => b.call("engine.execute", json!({"command": id, "params": params, "wait": false})).await,
(None, None) => none(),
}
}
@@ -1137,11 +1190,19 @@ impl PhotocraftMcp {
let mut failed = 0;
// The reply travels as escaped JSON text, so steps are charged their escaped size.
let mut reply_budget = BatchReplyBudget::escaped();
// Live mode may find a restarted app (or go headless) while a batch runs: its steps must
// not end up split across two documents in two places.
let pinned = self.target();
for (i, s) in p.steps.into_iter().enumerate() {
// A cancelled request runs no further steps; the client no longer reads the reply.
if waiter.is_cancelled() {
break;
}
if !same_target(pinned.as_ref(), self.target().as_ref()) {
failed += 1;
results.push(json!({"ok": false, "error": "PhotoCraft restarted (or the session changed) during the batch; this step and the ones after it did not run"}));
break;
}
let response = self.step(s.id, s.params.unwrap_or_else(|| json!({})), s.wait.unwrap_or(true), &mut waiter, (i, total)).await;
let was_error = response.is_err();
let result = match response {
+8 -2
View File
@@ -1,5 +1,5 @@
//! Catalog metadata, strict tool envelopes and live resources.
use super::{Arc, Backend, BatchParams, DocIndex, ListParams, McpError, Parameters, PhotocraftMcp, RunParams, ServerHandler, Value, json};
use super::{Arc, BatchParams, DocIndex, ListParams, McpError, Parameters, PhotocraftMcp, RunParams, ServerHandler, Value, fail, json};
use rmcp::RoleServer;
use rmcp::model::{
CallToolRequestParams, CallToolResponse, Implementation, ListResourcesResult, ListToolsResult, PaginatedRequestParams, ReadResourceRequestParams,
@@ -55,7 +55,10 @@ impl ServerHandler for PhotocraftMcp {
let args = Value::Object(request.arguments.clone().unwrap_or_default());
let _: BatchParams = serde_json::from_value(args).map_err(|e| McpError::invalid_params(e.to_string(), None))?;
}
if request.name == "command_run" && matches!(&*self.backend, Backend::Headless(_)) {
if let Err(error) = self.ready().await {
return Ok(fail(error).into());
}
if request.name == "command_run" && self.headless_session().is_some() {
let args = Value::Object(request.arguments.clone().unwrap_or_default());
let params: RunParams = serde_json::from_value(args).map_err(|e| McpError::invalid_params(e.to_string(), None))?;
if params.id == "file.export.renderVideo" {
@@ -74,6 +77,9 @@ impl ServerHandler for PhotocraftMcp {
}
async fn read_resource(&self, request: ReadResourceRequestParams, _: RequestContext<RoleServer>) -> Result<ReadResourceResponse, McpError> {
if let Err(error) = self.ready().await {
return Err(McpError::internal_error(error, None));
}
let result = match request.uri.as_str() {
DOCUMENT => self.doc_inspect(Parameters(DocIndex::default())).await?,
COMMANDS => self.command_list(Parameters(ListParams::default())).await?,
+12 -12
View File
@@ -1,8 +1,9 @@
//! Progress and cancellation for calls that wait. Render Video runs on the existing blocking
//! worker; other long commands run as engine jobs that the server polls ([`Waiter`]): the headless
//! session's own, or the app's over the bridge.
use super::{Arc, AutomationError, Backend, BridgeClient, CallToolResult, PhotocraftMcp, PoisonError, Value, fail, json, no_backend, ok_json};
use super::{Arc, AutomationError, BridgeClient, CallToolResult, PhotocraftMcp, PoisonError, Value, fail, json, no_backend, ok_json};
use crate::headless::JobPoll;
use crate::live::Target;
use photocraft_engine::jobs::{JobId, Started};
use rmcp::RoleServer;
use rmcp::model::ProgressNotificationParam;
@@ -92,7 +93,9 @@ impl Waiter {
/// Cancels a waited job when its waiter goes away without collecting it: rmcp may drop the
/// request future on cancellation, and nothing else would stop the job.
struct Abandon {
backend: Arc<Backend>,
/// The session or app that started the job: in live mode the current target can change
/// before the guard drops, and the job id means nothing elsewhere.
target: Target,
job: Option<JobId>,
}
@@ -100,8 +103,8 @@ impl Drop for Abandon {
fn drop(&mut self) {
let Some(job) = self.job.take() else { return };
let runtime = tokio::runtime::Handle::try_current();
match &*self.backend {
Backend::Headless(session) => {
match &self.target {
Target::Headless(session) => {
let session = session.clone();
let abandon = move || drop(session.lock().unwrap_or_else(PoisonError::into_inner).job_abandon(job));
match runtime {
@@ -111,7 +114,7 @@ impl Drop for Abandon {
}
}
// Without a runtime there is no way to reach the app; the job then runs to the end.
Backend::Bridge(client) => {
Target::Bridge(client) => {
if let Ok(runtime) = runtime {
let client = client.clone();
drop(runtime.spawn(async move { client.call("jobs.cancel", json!({"job": job.0})).await }));
@@ -127,10 +130,7 @@ impl PhotocraftMcp {
/// `waiter` as `step.0 + fraction` of `step.1`, and cancelling the request cancels the job,
/// leaving the document unchanged. `None` in bridge mode.
pub(super) async fn headless_wait(&self, id: String, params: Value, waiter: &mut Waiter, step: (usize, usize)) -> Option<Result<Value, AutomationError>> {
if !matches!(&*self.backend, Backend::Headless(_)) {
return None;
}
let backend = self.backend.clone();
let target = Target::Headless(self.headless_session()?);
let cancel = waiter.context.as_ref().map(|context| context.ct.clone());
// The guard is armed under the lock that starts the job: when the request is dropped while
// the start still waits for the lock, the closure's output is dropped unread and cancels it.
@@ -143,7 +143,7 @@ impl PhotocraftMcp {
Started::Job(job) if cancel.as_ref().is_some_and(|token| token.is_cancelled()) => {
return h.job_abandon(job).map(Err);
}
Started::Job(job) => Ok(Abandon { backend, job: Some(job) }),
Started::Job(job) => Ok(Abandon { target, job: Some(job) }),
Started::Done(value) => Err(value),
})
})
@@ -187,7 +187,7 @@ impl PhotocraftMcp {
/// (#1007); a failed poll reports the job instead of guessing its outcome.
pub(super) async fn bridge_wait(
&self,
client: &BridgeClient,
client: &Arc<BridgeClient>,
id: String,
params: Value,
waiter: &mut Waiter,
@@ -202,7 +202,7 @@ impl PhotocraftMcp {
let Some(job) = started.get("job").and_then(Value::as_u64).filter(|_| pending) else {
return Ok(started);
};
let mut guard = Abandon { backend: self.backend.clone(), job: Some(JobId(job)) };
let mut guard = Abandon { target: Target::Bridge(client.clone()), job: Some(JobId(job)) };
let mut delay = Duration::from_millis(10);
loop {
// Race the poll against a cancel: an app slow to answer must not hold it until the call times out.
+19 -1
View File
@@ -56,6 +56,20 @@ impl AuthorizedWorkspace {
Ok(Self { read, write })
}
/// This workspace with `path` as its only read root (the write authority stays). A path
/// spelled like the write root shares its capability, as [`Self::with_read_roots`] does, so
/// an implicit save can still write where a file was read.
pub fn with_read_root(&self, path: &Path) -> Result<Self, AutomationError> {
let opened: Vec<RootCapability> = self.write.iter().cloned().collect();
Ok(Self { read: vec![open_root(path, "read", &opened)?], write: self.write.clone() })
}
/// This workspace with `path` as its write root (the read authority stays), sharing the
/// capability of a read root spelled the same.
pub fn with_write_root(&self, path: &Path) -> Result<Self, AutomationError> {
Ok(Self { read: self.read.clone(), write: Some(open_root(path, "write", &self.read)?) })
}
/// Read the first matching regular file, trying roots in their configured order.
/// Only an open that reports NotFound tries the next root. Once opened, errors
/// (including a non-regular file or a failed bounded read) never select another file.
@@ -738,8 +752,12 @@ fn preference_uses_ambient_filesystem(path: &str) -> bool {
let mut segments = path.split('.').filter(|segment| !segment.is_empty());
let Some(section) = segments.next() else { return true };
// File Handling's LUT folder (#6558) is listed from disk; the rest of that section is not.
// Integrations' automation roots are what this policy grants (applied at once): an agent must
// not widen its own file access.
let key = segments.next();
matches!(section, "colorSettings" | "scriptEvents" | "historyLog" | "plugIns" | "scratchDisks")
|| (section == "fileHandling" && segments.next().is_none_or(|key| key == "lutFolder"))
|| (section == "fileHandling" && key.is_none_or(|key| key == "lutFolder"))
|| (section == "integrations" && key.is_none_or(|key| matches!(key, "readRoot" | "writeRoot")))
}
fn command_uses_ambient_path(id: &str, params: &Value) -> bool {
+10
View File
@@ -802,6 +802,10 @@ fn automation_rejects_ambient_path_commands_and_preferences() {
"fileHandling.lutFolder",
"fileHandling",
"scratchDisks.disks",
"integrations",
"integrations.readRoot",
"integrations.writeRoot",
".integrations.writeRoot",
".",
"..historyLog.filePath",
] {
@@ -812,6 +816,12 @@ fn automation_rejects_ambient_path_commands_and_preferences() {
);
assert!(authorize_engine_command("prefs.set", &serde_json::json!({"path": "interface.language", "value": "fr"})).is_ok());
assert!(authorize_engine_command("prefs.set", &serde_json::json!({"path": "fileHandling.autosave", "value": false})).is_ok());
assert!(
authorize_engine_command("prefs.set", &serde_json::json!({"values": {"integrations.controlPort": 7878, "integrations.writeRoot": "/outside"}}))
.is_err(),
"a batch may not grant automation roots either"
);
assert!(authorize_engine_command("prefs.set", &serde_json::json!({"path": "integrations.controlPort", "value": 7878})).is_ok());
}
#[test]
+378
View File
@@ -0,0 +1,378 @@
//! Plain `photocraft-cli mcp` with agents allowed (the ArtCraft Launcher's switch): the MCP server finds the desktop
//! app through its connection file before every call, follows it to a new port and token, and
//! applies the closed-app choice (start it, headless, or an error) when no app answers.
use std::io::{BufRead, BufReader, Write};
use std::net::TcpListener;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::time::Duration;
use photocraft_automation::PhotocraftMcp;
use photocraft_automation::agent_link::{self, Connection};
use photocraft_automation::live::LiveConfig;
use photocraft_engine::prefs::WhenAppClosed;
use rmcp::model::{CallToolRequestParams, CallToolResult, ClientConfig};
use rmcp::service::RunningService;
use rmcp::{ClientHandler, RoleClient, ServiceExt};
use serde_json::{Value, json};
#[derive(Clone, Default)]
struct Client;
impl ClientHandler for Client {
fn get_info(&self) -> ClientConfig {
ClientConfig::default()
}
}
async fn connect(server: PhotocraftMcp) -> RunningService<RoleClient, Client> {
let (s, c) = tokio::io::duplex(1 << 20);
tokio::spawn(async move {
if let Ok(running) = server.serve(s).await {
let _ = running.waiting().await;
}
});
Client.serve(c).await.expect("client init")
}
async fn call(client: &RunningService<RoleClient, Client>, name: &str, args: Value) -> CallToolResult {
let mut p = CallToolRequestParams::new(name.to_owned());
if let Value::Object(m) = args {
p = p.with_arguments(m);
}
client.call_tool(p).await.expect("call_tool transport")
}
fn text(r: &CallToolResult) -> String {
r.content.iter().filter_map(|c| c.as_text()).map(|t| t.text.clone()).collect::<Vec<_>>().join("\n")
}
fn settings_dir(tag: &str) -> PathBuf {
static N: AtomicUsize = AtomicUsize::new(0);
let d = std::env::temp_dir().join(format!("pc-mcp-live-{tag}-{}-{}", std::process::id(), N.fetch_add(1, Ordering::Relaxed)));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
d
}
fn prefs(dir: &Path, integrations: Value) {
std::fs::write(dir.join("preferences.json"), json!({"integrations": integrations}).to_string()).unwrap();
}
/// A desktop app as `mcp` sees it: a control server on a free port with a fresh token, its
/// connection file published in `dir`. `ui.inspect` answers with `name`. [`quit`] stops it.
struct FakeApp {
port: u16,
stop: Arc<std::sync::atomic::AtomicBool>,
}
fn fake_app(dir: &Path, name: &'static str) -> FakeApp {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let port = listener.local_addr().unwrap().port();
let token_file = dir.join(agent_link::TOKEN_FILE);
let token = photocraft_automation::security::replace_token_file(&token_file).unwrap();
agent_link::write_connection(dir, &Connection::new(port, token_file)).unwrap();
let stop = Arc::new(std::sync::atomic::AtomicBool::new(false));
let stopped = stop.clone();
std::thread::spawn(move || {
for stream in listener.incoming().flatten() {
if stopped.load(Ordering::SeqCst) {
break;
}
let token = token.clone();
std::thread::spawn(move || {
let mut out = stream.try_clone().unwrap();
// The app's own handshake (challenge or token), as `control_server` runs it.
let mut handshake = photocraft_automation::security::ServerHandshake::new();
let mut authenticated = false;
for line in BufReader::new(stream).lines() {
let Ok(line) = line else { break };
if !authenticated {
let (reply, step) = handshake.reply(&line, &token);
authenticated = step == photocraft_automation::security::AuthStep::Authenticated;
if writeln!(out, "{reply}").is_err() || step == photocraft_automation::security::AuthStep::Rejected {
break;
}
continue;
}
let req: Value = serde_json::from_str(&line).unwrap();
let id = req["id"].clone();
let reply = match req["method"].as_str().unwrap_or("") {
"ui.inspect" => json!({"id": id, "ok": true, "result": {"app": name}}),
m => json!({"id": id, "ok": false, "error": format!("unexpected {m}")}),
};
if writeln!(out, "{reply}").is_err() {
break;
}
}
});
}
});
FakeApp { port, stop }
}
/// The fake app quits: its port stops accepting (connections already open end with the test).
fn quit(app: FakeApp) {
app.stop.store(true, Ordering::SeqCst);
let _ = std::net::TcpStream::connect(("127.0.0.1", app.port));
while agent_link::probe(app.port, Duration::from_millis(200)) {
std::thread::sleep(Duration::from_millis(10));
}
}
fn live(dir: &Path, when_closed: Option<WhenAppClosed>) -> LiveConfig {
let mut c = LiveConfig::new(dir.to_path_buf());
c.when_closed = when_closed;
c.launch_timeout = Duration::from_secs(10);
// The machine's own ArtCraft Launcher and feature flags stay out of the tests: agents are
// allowed exactly when the test's preferences say so (as without the AI-MCP flag).
c.allowed = |i| i.connect_agents;
c
}
#[tokio::test(flavor = "multi_thread")]
async fn a_closed_app_is_a_tool_error_that_says_what_to_do() {
let dir = settings_dir("closed");
prefs(&dir, json!({"connectAgents": true}));
let client = connect(PhotocraftMcp::live(live(&dir, Some(WhenAppClosed::Error)))).await;
// The tool list doesn't need the app.
assert!(client.list_all_tools().await.unwrap().iter().any(|t| t.name == "ui_inspect"));
let r = call(&client, "command_list", json!({})).await;
assert_eq!(r.is_error, Some(true));
assert!(text(&r).contains("isn't running"), "{}", text(&r));
// A connection file left by a crashed app (nothing listens) counts as closed.
let gone = TcpListener::bind("127.0.0.1:0").unwrap();
let port = gone.local_addr().unwrap().port();
drop(gone);
agent_link::write_connection(&dir, &Connection::new(port, dir.join(agent_link::TOKEN_FILE))).unwrap();
let r = call(&client, "ui_inspect", json!({})).await;
assert!(text(&r).contains("isn't running"), "{}", text(&r));
client.cancel().await.unwrap();
let _ = std::fs::remove_dir_all(&dir);
}
#[tokio::test(flavor = "multi_thread")]
async fn follows_the_app_across_restarts_on_new_ports_and_tokens() {
let dir = settings_dir("follow");
prefs(&dir, json!({"connectAgents": true, "whenAppClosed": "error"}));
let client = connect(PhotocraftMcp::live(live(&dir, None))).await;
let first = fake_app(&dir, "first");
let r = call(&client, "ui_inspect", json!({})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert!(text(&r).contains("first"));
// Restart: another port, a new token.
quit(first);
let second = fake_app(&dir, "second");
let r = call(&client, "ui_inspect", json!({})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert!(text(&r).contains("second"), "{}", text(&r));
quit(second);
std::fs::remove_file(dir.join(agent_link::CONNECTION_FILE)).unwrap();
let r = call(&client, "ui_inspect", json!({})).await;
assert_eq!(r.is_error, Some(true));
client.cancel().await.unwrap();
let _ = std::fs::remove_dir_all(&dir);
}
#[tokio::test(flavor = "multi_thread")]
async fn launch_starts_the_app_once_and_only_when_agents_may_connect() {
let dir = settings_dir("launch");
let launches = Arc::new(AtomicUsize::new(0));
let apps = Arc::new(std::sync::Mutex::new(Vec::new()));
let config = |dir: &Path| {
let mut c = live(dir, Some(WhenAppClosed::Launch));
let (launches, apps, dir) = (launches.clone(), apps.clone(), dir.to_path_buf());
c.launch = Some(Box::new(move || {
launches.fetch_add(1, Ordering::SeqCst);
let (apps, dir) = (apps.clone(), dir.clone());
// The app takes a moment to start listening.
std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(300));
apps.lock().unwrap().push(fake_app(&dir, "launched"));
});
Ok(())
}));
c
};
// Agents not allowed: the app would never listen, so it isn't started; the session works
// without a window, as `mcp` always did.
let client = connect(PhotocraftMcp::live(config(&dir))).await;
let r = call(&client, "ui_inspect", json!({})).await;
assert!(text(&r).contains("bridge"), "UI tools need the open app: {}", text(&r));
let r = call(&client, "command_list", json!({})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert_eq!(launches.load(Ordering::SeqCst), 0);
client.cancel().await.unwrap();
// The ArtCraft Launcher's switch is the consent: the app is started on it alone.
let mut c = config(&dir);
c.allowed = |_| true;
let client = connect(PhotocraftMcp::live(c)).await;
let r = call(&client, "ui_inspect", json!({})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert_eq!(launches.load(Ordering::SeqCst), 1);
client.cancel().await.unwrap();
for app in apps.lock().unwrap().drain(..) {
quit(app);
}
launches.store(0, Ordering::SeqCst);
prefs(&dir, json!({"connectAgents": true}));
let client = connect(PhotocraftMcp::live(config(&dir))).await;
// Two calls at once start one app.
let (a, b) = tokio::join!(call(&client, "ui_inspect", json!({})), call(&client, "ui_inspect", json!({})));
for r in [a, b] {
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert!(text(&r).contains("launched"));
}
assert_eq!(launches.load(Ordering::SeqCst), 1);
client.cancel().await.unwrap();
for app in apps.lock().unwrap().drain(..) {
quit(app);
}
let _ = std::fs::remove_dir_all(&dir);
}
#[tokio::test(flavor = "multi_thread")]
async fn a_launch_that_never_listens_times_out_with_advice() {
let dir = settings_dir("timeout");
prefs(&dir, json!({"connectAgents": true}));
let mut c = live(&dir, Some(WhenAppClosed::Launch));
c.launch_timeout = Duration::from_millis(600);
c.launch = Some(Box::new(|| Ok(())));
let client = connect(PhotocraftMcp::live(c)).await;
let r = call(&client, "ui_inspect", json!({})).await;
assert_eq!(r.is_error, Some(true));
assert!(text(&r).contains("didn't accept agents"), "{}", text(&r));
// A launcher that fails says so.
let mut c = live(&dir, Some(WhenAppClosed::Launch));
c.launch = Some(Box::new(|| Err("no such file".into())));
let client2 = connect(PhotocraftMcp::live(c)).await;
let r = call(&client2, "ui_inspect", json!({})).await;
assert!(text(&r).contains("couldn't start PhotoCraft: no such file"), "{}", text(&r));
// No launcher (Flatpak, the app not installed beside the CLI): ask the user.
let client3 = connect(PhotocraftMcp::live(live(&dir, Some(WhenAppClosed::Launch)))).await;
let r = call(&client3, "ui_inspect", json!({})).await;
assert!(text(&r).contains("open PhotoCraft"), "{}", text(&r));
for c in [client, client2, client3] {
c.cancel().await.unwrap();
}
let _ = std::fs::remove_dir_all(&dir);
}
#[tokio::test(flavor = "multi_thread")]
async fn headless_uses_the_app_folders_and_stays_headless() {
let dir = settings_dir("headless");
let work = dir.join("work");
std::fs::create_dir_all(&work).unwrap();
prefs(&dir, json!({"connectAgents": true, "whenAppClosed": "headless", "writeRoot": work.to_string_lossy()}));
let client = connect(PhotocraftMcp::live(live(&dir, None))).await;
let r = call(&client, "doc_new", json!({"width": 8, "height": 8})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
let r = call(&client, "doc_save", json!({"path": "out.pcraft"})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert!(work.join("out.pcraft").exists(), "saved into the app's write folder");
// No read folder was chosen: reads are refused.
let r = call(&client, "doc_open", json!({"path": "out.pcraft"})).await;
assert_eq!(r.is_error, Some(true));
// The app starting later doesn't move the documents away from the agent.
let app = fake_app(&dir, "late");
let r = call(&client, "ui_inspect", json!({})).await;
assert!(text(&r).contains("bridge"), "UI tools stay unavailable in the headless session: {}", text(&r));
let r = call(&client, "session_list", json!({})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
client.cancel().await.unwrap();
quit(app);
// A folder that doesn't exist is a clear error, not a crash.
prefs(&dir, json!({"connectAgents": true, "whenAppClosed": "headless", "readRoot": dir.join("missing").to_string_lossy()}));
std::fs::remove_file(dir.join(agent_link::CONNECTION_FILE)).unwrap();
let client = connect(PhotocraftMcp::live(live(&dir, None))).await;
let r = call(&client, "command_list", json!({})).await;
assert_eq!(r.is_error, Some(true));
assert!(text(&r).contains("agent folders"), "{}", text(&r));
client.cancel().await.unwrap();
let _ = std::fs::remove_dir_all(&dir);
}
/// Agents allowed, app closed, headless: a root flag given to `mcp` replaces the app's folder for
/// its own direction only; the other direction still falls back to the app's folder.
#[tokio::test(flavor = "multi_thread")]
async fn headless_root_flags_override_each_direction_on_their_own() {
let dir = settings_dir("headless-override");
let (app_read, app_write, given) = (dir.join("app-read"), dir.join("app-write"), dir.join("given"));
for d in [&app_read, &app_write, &given] {
std::fs::create_dir_all(d).unwrap();
}
prefs(&dir, json!({"connectAgents": true, "whenAppClosed": "headless", "readRoot": app_read.to_string_lossy(), "writeRoot": app_write.to_string_lossy()}));
// Only the write root is given: saves go there, reads still come from the app's read folder.
let mut c = live(&dir, None);
c.write_root = Some(given.clone());
let client = connect(PhotocraftMcp::live(c)).await;
let r = call(&client, "doc_new", json!({"width": 8, "height": 8})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
let r = call(&client, "doc_save", json!({"path": "out.pcraft"})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert!(given.join("out.pcraft").exists(), "saved into the given write root");
assert!(!app_write.join("out.pcraft").exists(), "not into the app's write folder");
std::fs::copy(given.join("out.pcraft"), app_read.join("in.pcraft")).unwrap();
let r = call(&client, "doc_open", json!({"path": app_read.join("in.pcraft").to_string_lossy()})).await;
assert_eq!(r.is_error, Some(false), "the app's read folder still applies: {}", text(&r));
client.cancel().await.unwrap();
// Only a read root is given: it replaces the app's read folder; saves still go to the app's write folder.
let mut c = live(&dir, None);
c.read_roots = vec![given.clone()];
let client = connect(PhotocraftMcp::live(c)).await;
let r = call(&client, "doc_open", json!({"path": app_read.join("in.pcraft").to_string_lossy()})).await;
assert_eq!(r.is_error, Some(true), "the app's read folder is replaced by the given one");
let r = call(&client, "doc_open", json!({"path": given.join("out.pcraft").to_string_lossy()})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
let r = call(&client, "doc_save", json!({"path": "again.pcraft"})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert!(app_write.join("again.pcraft").exists(), "saved into the app's write folder");
client.cancel().await.unwrap();
let _ = std::fs::remove_dir_all(&dir);
}
/// Agents not allowed: `mcp` serves a session without a window as it always did, with only the
/// folders given to the command (the app's own folders are for agents the person let in), never
/// starts the app, and prepares the session as the command asked (`--gpu`).
#[tokio::test(flavor = "multi_thread")]
async fn without_consent_mcp_is_headless_with_its_own_folders() {
static PREPARED: AtomicUsize = AtomicUsize::new(0);
let dir = settings_dir("no-consent");
let (app_folder, given) = (dir.join("app-folder"), dir.join("given"));
std::fs::create_dir_all(&app_folder).unwrap();
std::fs::create_dir_all(&given).unwrap();
prefs(&dir, json!({"whenAppClosed": "launch", "writeRoot": app_folder.to_string_lossy()}));
let launches = Arc::new(AtomicUsize::new(0));
let config = |write_root: Option<PathBuf>| {
let mut c = live(&dir, None);
c.write_root = write_root;
let launches = launches.clone();
c.launch = Some(Box::new(move || {
launches.fetch_add(1, Ordering::SeqCst);
Ok(())
}));
c.prepare_headless = Some(Box::new(|_| {
PREPARED.fetch_add(1, Ordering::SeqCst);
}));
c
};
let client = connect(PhotocraftMcp::live(config(None))).await;
let r = call(&client, "doc_new", json!({"width": 8, "height": 8})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
let r = call(&client, "doc_save", json!({"path": "out.pcraft"})).await;
assert_eq!(r.is_error, Some(true), "the app's folder isn't granted without consent");
assert!(!app_folder.join("out.pcraft").exists());
client.cancel().await.unwrap();
let client = connect(PhotocraftMcp::live(config(Some(given.clone())))).await;
call(&client, "doc_new", json!({"width": 8, "height": 8})).await;
let r = call(&client, "doc_save", json!({"path": "out.pcraft"})).await;
assert_eq!(r.is_error, Some(false), "{}", text(&r));
assert!(given.join("out.pcraft").exists(), "the command's own root is used");
client.cancel().await.unwrap();
assert_eq!(launches.load(Ordering::SeqCst), 0, "never started without consent");
assert_eq!(PREPARED.load(Ordering::SeqCst), 2, "each headless session is prepared once");
let _ = std::fs::remove_dir_all(&dir);
}
+54 -2
View File
@@ -120,6 +120,11 @@ choice!(
/// fastest and softest. Photoshop's Camera Raw has no such choice.
RawDemosaic { Ahd = "ahd", Mhc = "mhc", Bilinear = "bilinear" } default Ahd
);
choice!(
/// MCP › When PhotoCraft Is Closed: what `photocraft-cli mcp` does when an
/// agent calls a tool and the app isn't running.
WhenAppClosed { Launch = "launch", Headless = "headless", Error = "error" } default Launch
);
impl Unit {
/// Document pixels → this unit. `dpi` is the document resolution, `extent` the 100% length
@@ -1169,18 +1174,62 @@ impl Default for RawDefaults {
}
}
/// Before the agents switch, a Control Port other than 0 started the control server by itself.
/// A saved `integrations` section like that keeps its connection: the port now means "on, at this
/// port". Every reader of the saved section applies this (the app, its launch read, and
/// `photocraft-cli mcp`), so they agree.
pub fn migrate_integrations(section: &mut Value) {
if let Some(integrations) = section.as_object_mut()
&& !integrations.contains_key("connectAgents")
&& integrations.get("controlPort").and_then(Value::as_u64).is_some_and(|p| (1..=65535).contains(&p))
{
integrations.insert("connectAgents".into(), json!(true));
}
}
/// A saved `integrations` section read as the app's preference load reads it: migrated, and
/// leniently (a value of the wrong type keeps its default, the rest still loads). The desktop
/// app's launch read and `photocraft-cli mcp` use it, so a bad value can't reset, say, When
/// PhotoCraft Is Closed for them alone.
pub fn read_integrations_section(mut section: Value) -> Integrations {
migrate_integrations(&mut section);
read_section(section)
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct Integrations {
/// Allow agents to drive the app over the loopback control channel / MCP bridge.
pub allow_agent_control: bool,
/// Default control port (0 = only when `--control` is given).
/// Port agents connect to (0 = any free port, published in the connection file).
pub control_port: u32,
/// The folder automation may read from when no `--automation-read-root` is given (empty =
/// none). Applied at once while agents are connected.
pub read_root: String,
/// The folder automation may write to when no `--automation-write-root` is given (empty =
/// none). Applied at once while agents are connected.
pub write_root: String,
/// Without the suite's `AI-MCP` flag, agents may connect: the desktop app serves the control
/// protocol on loopback for `photocraft-cli mcp` without `--control`, and starts or stops it at
/// once when this changes (off by default; launch flags still win). Set from a saved Control
/// Port ([`migrate_integrations`]); not in the dialog. With the flag the ArtCraft Launcher's
/// switch decides instead. After the older fields, so a
/// section saved as a list still reads them where they were.
pub connect_agents: bool,
/// What `photocraft-cli mcp` does while agents may use the app but it is closed.
pub when_app_closed: WhenAppClosed,
}
impl Default for Integrations {
fn default() -> Self {
Self { allow_agent_control: true, control_port: 0 }
Self {
allow_agent_control: true,
control_port: 0,
read_root: String::new(),
write_root: String::new(),
connect_agents: false,
when_app_closed: WhenAppClosed::Launch,
}
}
}
@@ -1653,6 +1702,9 @@ impl Session {
{
*language = json!("sr-latn");
}
if let Some(integrations) = v.get_mut("integrations") {
migrate_integrations(integrations);
}
let color = v.as_object_mut().and_then(|m| m.remove("colorSettings"));
let presets = v.as_object_mut().and_then(|m| m.remove("presets"));
let mut invalid = Vec::new();
+18
View File
@@ -1217,3 +1217,21 @@ fn an_effect_cache_above_the_cap_loads_clamped_and_does_not_block_apply() {
assert_eq!(s.execute("prefs.get", json!({"path": "fileHandling.recentFileCount"})).unwrap(), json!(7), "{saved} MB");
}
}
/// A file from before the agents switch whose Control Port started the control server keeps
/// it on; one without a port, or that already says, is left as it is.
#[test]
fn a_saved_control_port_turns_the_agent_connection_on() {
let load = |text: &str| {
let mut session = Session::new();
session.load_prefs_json(text).unwrap();
session.prefs().integrations.clone()
};
let legacy = load(r#"{"integrations":{"allowAgentControl":true,"controlPort":7878}}"#);
assert!(legacy.connect_agents);
assert_eq!(legacy.control_port, 7878);
assert!(!load(r#"{"integrations":{"controlPort":0}}"#).connect_agents);
assert!(!load(r#"{"integrations":{"controlPort":70000}}"#).connect_agents, "not a usable port");
assert!(!load(r#"{"integrations":{"controlPort":7878,"connectAgents":false}}"#).connect_agents, "an explicit choice wins");
assert!(!load("{}").connect_agents, "off by default");
}
+2 -1
View File
@@ -3,7 +3,7 @@ use super::{
AppearanceMode, Ask, CanvasBorder, CanvasColor, CheckerColors, CheckerSize, ColorPicker, DarkTheme, ExportLocation, ExportMetadata, FontPreview,
GpuBackend, Interpolation, LightTheme, LineStyle, LinuxDisplayServer, LogDestination, LogDetail, OtherCursor, PaintingCursor, PlaybackPerformance,
PointSize, PressureCurve, QuickExportFormat, RawColorSpace, RawDemosaic, RawDepth, RawSharpen, RenderingMode, RightClickPaint, TabletInput, TextEngine,
Theme, TypeUnit, UiFontSize, UiScale, Unit, Value,
Theme, TypeUnit, UiFontSize, UiScale, Unit, Value, WhenAppClosed,
};
/// Preferences dialog sections in Photoshop's order: (id, title).
@@ -102,6 +102,7 @@ pub fn choices(path: &str) -> Option<&'static [&'static str]> {
"performance.gpuBackend" => GpuBackend::NAMES,
"performance.linuxDisplayServer" => LinuxDisplayServer::NAMES,
"performance.renderingMode" => RenderingMode::NAMES,
"integrations.whenAppClosed" => WhenAppClosed::NAMES,
"actions.performance" => PlaybackPerformance::NAMES,
_ => return None,
})
+1
View File
@@ -90,6 +90,7 @@ impl PhotocraftApp {
caps_lock: false,
opacity_keys: None,
control_rx: None,
agent_link: crate::AgentLinkStatus::default(),
captures: crate::screenshot::Captures::default(),
type_ime: type_tool::ImeState::default(),
input_waiters: Vec::new(),
+1
View File
@@ -135,6 +135,7 @@ pub fn inspect(app: &PhotocraftApp, ctx: &egui::Context) -> Value {
"brush": {"size": app.session.tools.brush.size, "hardness": app.session.tools.brush.hardness, "opacity": app.session.tools.brush.opacity},
"distort": app.distort.describe(),
"jobs": crate::jobs_ui::inspect(app),
"agentLink": app.agent_link,
"histogram": crate::histogram_panel::inspect(app),
"cameraRaw": app.camera_raw.as_ref().map(|d| d.describe(&app.ui.camera_raw_scope, &app.ui.camera_raw_preview)),
})
+1 -1
View File
@@ -355,7 +355,7 @@ fn command_body_more(app: &mut PhotocraftApp, ui: &mut egui::Ui, d: &Dialog, fie
}
}
_ if crate::color_range_ui::owns(fields) => crate::color_range_ui::body(app, ui, fields),
_ if crate::prefs_ui::owns(fields) => crate::prefs_ui::body(app, ui, fields),
_ if crate::prefs_ui::owns(fields) => crate::prefs_ui::body(app, ui, fields, d.id),
_ if fields.contains_key("__export") => crate::export_dialog::body(app, ui, fields),
// Image Size and Canvas Size open on Width, selected (#2329).
_ if fields.contains_key("__sizing") => first_field_focused(ui, id, |ui| crate::sizing::body(ui, fields)),
+8 -5
View File
@@ -261,11 +261,12 @@ pub(crate) use services::SAVE_OPTIONS_OPEN;
#[cfg(test)]
pub(crate) use services::saved_revision_after_write;
pub use services::{
AdoptAutosaveFn, AppendTextFn, AutomationCommandFn, AutomationOpenPcraftFn, AutomationReadFn, AutomationWriteFn, AutosaveFn, AutosaveResultsFn, CapsLockFn,
CaptionStyleFn, ClipboardGetFn, ClipboardGetSvgFn, ClipboardSetFn, ClipboardUnreadableFn, CursorPosFn, DiscardAutosaveFn, EncodePngFn, ExportFn,
ExportSettings, ExternalSvgEditor, ExternalSvgSession, ExternalVectorSave, ExternalVectorSource, FileStamp, FileStampFn, FormatChoices, ImportFn, Inbox,
LastUpdateFn, LoadTextFn, OpenExternalSvgFn, OpenUrlFn, OsEventsFn, PenEndFn, PenScreenFn, PhotoshopShortcutsFn, PlaceInbox, QuitFn, RecoverFn,
Recoverable, RightButtonDownFn, SameFileFn, SaveFileFn, SaveTextFn, Services, SystemThemeFn, TabletPollFn, WindowFrameFn, WriteFn,
AdoptAutosaveFn, AgentLink, AgentLinkFn, AgentLinkStatus, AppendTextFn, AutomationAuthorizeFn, AutomationCommandFn, AutomationOpenPcraftFn,
AutomationReadFn, AutomationServices, AutomationWriteFn, AutosaveFn, AutosaveResultsFn, CapsLockFn, CaptionStyleFn, ClipboardGetFn, ClipboardGetSvgFn,
ClipboardSetFn, ClipboardUnreadableFn, CursorPosFn, DiscardAutosaveFn, EncodePngFn, ExportFn, ExportSettings, ExternalSvgEditor, ExternalSvgSession,
ExternalVectorSave, ExternalVectorSource, FileStamp, FileStampFn, FormatChoices, ImportFn, Inbox, LastUpdateFn, LoadTextFn, OpenExternalSvgFn, OpenUrlFn,
OsEventsFn, PenEndFn, PenScreenFn, PhotoshopShortcutsFn, PlaceInbox, QuitFn, RecoverFn, Recoverable, RightButtonDownFn, SameFileFn, SaveFileFn, SaveTextFn,
Services, SystemThemeFn, TabletPollFn, WindowFrameFn, WriteFn,
};
pub(crate) use services::{opaque_layer, saves_flat_in_place};
pub use text::bidi_text;
@@ -459,6 +460,8 @@ pub struct PhotocraftApp {
/// The first digit of a two-digit opacity typed on the number keys (`opacity_keys`, #352).
pub(crate) opacity_keys: opacity_keys::Pending,
control_rx: Option<Receiver<ControlRequest>>,
/// Preferences › AI Integrations: the agent connection's state (see [`Services::agent_link`]).
pub agent_link: AgentLinkStatus,
/// `ui.screenshot` requests: bounded admission, a weak-slot callback per issuance, monotonic
/// deadlines and a capture-time geometry epoch (see `screenshot.rs`).
captures: screenshot::Captures,
+8
View File
@@ -52,6 +52,11 @@ pub struct Runtime {
show_rulers: Option<bool>,
/// Tool options as last remembered in the preferences (see `tool_memory`).
pub(crate) tool_options: Option<crate::state::ToolOptions>,
/// MCP settings the agent connection was last set up for (`agents::sync_agent_link`).
agent_link: Option<prefs::Integrations>,
/// When to try again after the agent connection failed to start (a taken port), in seconds of
/// `gpu_canvas::now_ms`; `None` while it runs or is off.
agent_link_retry: Option<f64>,
pub(crate) selected_tool: Option<crate::state::Tool>,
pub(crate) tool_colors: Option<[[[f32; 4]; 2]; 2]>,
pub(crate) tool_cmyk_picks: crate::tool_memory::CmykPicks,
@@ -64,6 +69,7 @@ pub struct Runtime {
pub use crate::shortcuts::{default_shortcut, effective_shortcut};
mod agents;
mod appearance;
mod dialogs;
mod fields;
@@ -103,6 +109,8 @@ pub(crate) use startup::{on_recovery_event, remember_rulers};
// Test modules stay after the production code: the prefs_usage test reads each file up to
// its first `#[cfg(test)] mod`.
#[cfg(test)]
mod agents_tests;
#[cfg(test)]
mod recovery_tests;
#[cfg(test)]
+141
View File
@@ -0,0 +1,141 @@
//! Preferences › AI Integrations: whether agents can use the open app (one switch for every Craft
//! app, in the ArtCraft Launcher), the port, the folders agents may use, and what
//! `photocraft-cli mcp` does while the app is closed. Changes apply at once, without a restart.
//! Adding PhotoCraft to an MCP client is the launcher's job too, so there is nothing for it here.
use super::dialogs::is_preferences;
use super::fields::{choice_label, humanize};
use super::{Map, PhotocraftApp, RichText, Tokens, Value, json, prefs};
/// Seconds between tries while the agent connection is on but couldn't start (its port taken).
pub(super) const AGENT_LINK_RETRY_S: f64 = 5.0;
/// Start, move or stop the agent connection when its settings change
/// ([`crate::Services::agent_link`]); the first frame applies the saved settings. A connection
/// that is on but failed to start is tried again every [`AGENT_LINK_RETRY_S`], so freeing its
/// port is enough, without touching a setting. With the suite's `AI-MCP` flag, the ArtCraft
/// Launcher's switch ([`crate::Services::launcher_agents`]) alone decides whether agents may connect:
/// one switch for every Craft app. Without the flag, as before, a Control Port saved in the
/// preferences (`connectAgents`, set from it when they load).
pub(super) fn sync_agent_link(app: &mut PhotocraftApp, ctx: &egui::Context) {
let launcher = app.services.launcher_agents.as_ref().is_some_and(|on| on());
let mcp_flag = app.agent_link.mcp_flag;
let Some(link) = app.services.agent_link.as_mut() else { return };
let mut effective = app.session.prefs().integrations.clone();
if mcp_flag {
effective.connect_agents = launcher;
}
let current = &effective;
let now = crate::gpu_canvas::now_ms() / 1000.0;
let retry_due = app.prefs_rt.agent_link_retry.is_some_and(|at| now >= at);
if app.prefs_rt.agent_link.as_ref() == Some(current) && !retry_due {
return;
}
let update = link(current, ctx);
let failed_start = current.connect_agents && current.allow_agent_control && update.status.port.is_none();
app.prefs_rt.agent_link = Some(current.clone());
app.prefs_rt.agent_link_retry = failed_start.then_some(now + AGENT_LINK_RETRY_S);
if failed_start {
ctx.request_repaint_after(std::time::Duration::from_secs_f64(AGENT_LINK_RETRY_S));
}
if update.stopped {
app.control_rx = None;
}
if let Some(rx) = update.requests {
app.control_rx = Some(rx);
}
app.services.set_automation(update.automation);
// Actions automation records keep the policy as their gate when the user plays them, as they
// do with `--control` (`PhotocraftApp::new`); the gate stays once agents have connected.
app.session.automation_gate = app.session.automation_gate.or(app.services.automation_authorize);
// The service reports the connection; the feature flag is the app's, set once at launch.
app.agent_link = update.status;
app.agent_link.mcp_flag = mcp_flag;
app.agent_link.launcher = launcher;
}
/// The rows of the section. A button click is left in `f["__agentAction"]` for [`agent_action`].
pub(super) fn integration_rows(ui: &mut egui::Ui, obj: &mut Map<String, Value>, f: &mut Map<String, Value>) {
let t = Tokens::get(ui.ctx());
let status = f.get("__agentLink").cloned().unwrap_or(Value::Null);
let launch_flags = status.get("launchFlags").and_then(Value::as_bool) == Some(true);
// One switch for every Craft app: ArtCraft Launcher › Settings › AI agents. There is none here.
ui.label(
RichText::new(tl!(
"AI apps such as Claude can open, edit and save documents in this window while ArtCraft Launcher › Settings › AI agents › Let AI agents use Craft apps is on. Only programs on this computer can connect."
))
.color(t.text_dim),
);
ui.add_space(4.0);
let port = status.get("port").and_then(Value::as_u64);
let error = status.get("error").and_then(Value::as_str);
let (line, color) = match (launch_flags, port, error) {
(true, _, _) => (tl!("Managed by the launch options (--control).").to_string(), t.text_dim),
(false, _, Some(e)) => (e.to_string(), t.danger),
(false, Some(p), None) => (crate::i18n::fmt(tl!("Agents can connect on 127.0.0.1:{port}."), &[("port", &p.to_string())]), t.accent_text),
(false, None, None) => (tl!("Off: turn on AI agents in ArtCraft Launcher › Settings › AI agents.").to_string(), t.text_faint),
};
ui.label(RichText::new(line).color(color));
ui.add_space(8.0);
egui::Grid::new("prefs-integrations").num_columns(2).spacing([14.0, 7.0]).show(ui, |ui| {
let port_label = ui.label(RichText::new(tl!(&humanize("controlPort"))).color(t.text_dim));
ui.horizontal(|ui| {
let mut p = obj.get("controlPort").and_then(Value::as_i64).unwrap_or(0);
ui.add(egui::DragValue::new(&mut p).range(0..=65535).custom_parser(crate::widgets::parse_num)).labelled_by(port_label.id);
obj.insert("controlPort".into(), json!(p));
ui.label(RichText::new(tl!("0 picks a free port; AI apps find it by themselves")).color(t.text_faint));
});
ui.end_row();
for (key, pick) in [("readRoot", "chooseRead"), ("writeRoot", "chooseWrite")] {
let label = humanize(key);
ui.label(RichText::new(tl!(&label)).color(t.text_dim));
ui.horizontal(|ui| {
let mut path = obj.get(key).and_then(Value::as_str).unwrap_or("").to_string();
crate::widgets::text_field(ui, ui.scope_id().with(key), &mut path, tl!("None"), 260.0, false);
obj.insert(key.into(), json!(path));
if crate::widgets::secondary_button(ui, tl!("Browse…"), 70.0).clicked() {
f.insert("__agentAction".into(), json!(pick));
}
});
ui.end_row();
}
let label = humanize("whenAppClosed");
ui.label(RichText::new(tl!(&label)).color(t.text_dim));
let mut cur = obj.get("whenAppClosed").and_then(Value::as_str).unwrap_or("launch").to_string();
let options = prefs::choices("integrations.whenAppClosed").unwrap_or(&[]);
let labels: Vec<String> = options.iter().map(|o| choice_label(o)).collect();
let pairs: Vec<(String, &str)> = options.iter().map(|o| o.to_string()).zip(labels.iter().map(String::as_str)).collect();
crate::widgets::dropdown(ui, "pref-integrations.whenAppClosed", &label, &mut cur, &pairs, 220.0);
obj.insert("whenAppClosed".into(), json!(cur));
ui.end_row();
});
if let Some(result) = f.get("__agentResult").and_then(Value::as_object) {
let ok = result.get("ok").and_then(Value::as_bool) == Some(true);
let text = result.get("message").and_then(Value::as_str).unwrap_or("");
ui.label(RichText::new(text).color(if ok { t.text_dim } else { t.danger }));
}
}
/// A button of [`integration_rows`]: choose a folder (into the dialog's working copy).
pub(super) fn agent_action(app: &mut PhotocraftApp, f: &mut Map<String, Value>, action: &str, dialog: u64) {
let key = match action {
"chooseRead" => Some("readRoot"),
"chooseWrite" => Some("writeRoot"),
_ => None,
};
if let Some(key) = key {
// Into the Preferences dialog that asked: closed meanwhile (or reopened as a new one), the
// answer is dropped rather than landing in another working copy.
let picked = app.ask_folder(move |app, path| {
if let Some(d) = app.ui.dialogs.iter_mut().find(|d| d.id == dialog && is_preferences(&d.fields))
&& let Some(obj) = d.fields.get_mut("values").and_then(|v| v.get_mut("integrations")).and_then(Value::as_object_mut)
{
obj.insert(key.into(), json!(path));
}
Ok(Value::Null)
});
if let Err(e) = picked {
f.insert("__agentResult".into(), json!({"ok": false, "message": e}));
}
}
}
@@ -0,0 +1,216 @@
//! Preferences › AI Integrations (`agents.rs`): the live agent connection and its buttons.
use super::tests::app_with_store;
use super::*;
use std::sync::{Arc, Mutex};
#[test]
fn ai_integrations_start_and_stop_the_agent_connection_through_the_service() {
use std::sync::mpsc::channel;
let (mut app, _) = app_with_store();
let ctx = egui::Context::default();
let calls: Arc<Mutex<Vec<prefs::Integrations>>> = Arc::default();
let seen = calls.clone();
let (tx, rx) = channel::<crate::ControlRequest>();
let mut rx = Some(rx);
app.services.agent_link = Some(Box::new(move |p: &prefs::Integrations, _: &egui::Context| {
seen.lock().unwrap().push(p.clone());
let mut out = crate::AgentLink { stopped: !p.connect_agents, ..Default::default() };
if p.connect_agents {
out.requests = rx.take();
out.status.port = Some(4321);
out.automation.command = Some(Box::new(|_, _| Err("policy".into())));
}
out
}));
// The first frame applies the saved settings (off), once.
tick(&mut app, &ctx);
tick(&mut app, &ctx);
assert_eq!(calls.lock().unwrap().len(), 1);
assert!(app.control_rx.is_none() && app.agent_link.port.is_none());
// On: the request channel and the automation policy are installed, without a restart.
app.run("prefs.set", json!({"values": {"integrations.connectAgents": true, "integrations.readRoot": "/work"}})).unwrap();
tick(&mut app, &ctx);
assert_eq!(calls.lock().unwrap().last().map(|p| (p.connect_agents, p.read_root.clone())), Some((true, "/work".into())));
assert!(app.control_rx.is_some());
assert!(app.services.automation_command.is_some());
assert_eq!(app.agent_link.port, Some(4321));
assert!(tx.send(crate::ControlRequest::new("ui.inspect", json!({})).0).is_ok(), "the app holds the receiver");
// An unrelated preference doesn't touch the connection.
app.run("prefs.set", json!({"values": {"performance.historyStates": 12}})).unwrap();
tick(&mut app, &ctx);
assert_eq!(calls.lock().unwrap().len(), 2);
// Off: the channel and the policy go.
app.run("prefs.set", json!({"values": {"integrations.connectAgents": false}})).unwrap();
tick(&mut app, &ctx);
assert_eq!(calls.lock().unwrap().len(), 3);
assert!(app.control_rx.is_none() && app.services.automation_command.is_none());
assert_eq!(app.agent_link.port, None);
// ui.inspect reports it.
assert!(crate::control::inspect(&app, &ctx).get("agentLink").is_some());
}
/// With the AI-MCP flag the ArtCraft Launcher's switch is the one consent: it starts the
/// connection, turning it off there stops it again, and a Control Port saved before (the old,
/// flag-less way) doesn't keep it on.
#[test]
fn with_the_flag_the_launcher_switch_alone_turns_the_agent_connection_on_and_off() {
use std::sync::atomic::{AtomicBool, Ordering};
let (mut app, _) = app_with_store();
app.agent_link.mcp_flag = true;
app.run("prefs.set", json!({"values": {"integrations.connectAgents": true}})).unwrap();
let ctx = egui::Context::default();
let calls: Arc<Mutex<Vec<bool>>> = Arc::default();
let seen = calls.clone();
app.services.agent_link = Some(Box::new(move |p: &prefs::Integrations, _: &egui::Context| {
seen.lock().unwrap().push(p.connect_agents);
crate::AgentLink {
stopped: !p.connect_agents,
status: crate::AgentLinkStatus { port: p.connect_agents.then_some(4321), ..Default::default() },
..Default::default()
}
}));
let launcher = Arc::new(AtomicBool::new(false));
let on = launcher.clone();
app.services.launcher_agents = Some(Box::new(move || on.load(Ordering::Relaxed)));
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), [false]);
launcher.store(true, Ordering::Relaxed);
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), [false, true], "the launcher's switch alone starts it");
assert!(app.agent_link.launcher && app.agent_link.port == Some(4321));
tick(&mut app, &ctx);
assert_eq!(calls.lock().unwrap().len(), 2, "no change, no restart");
launcher.store(false, Ordering::Relaxed);
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), [false, true, false], "off in the launcher stops it");
assert!(!app.agent_link.launcher && app.agent_link.port.is_none());
}
/// Without the AI-MCP flag nothing changes from before: the launcher's switch means nothing, and a
/// Control Port saved in the preferences keeps its connection.
#[test]
fn without_the_flag_the_launcher_switch_means_nothing() {
let (mut app, _) = app_with_store();
let ctx = egui::Context::default();
let calls: Arc<Mutex<Vec<bool>>> = Arc::default();
let seen = calls.clone();
app.services.agent_link = Some(Box::new(move |p: &prefs::Integrations, _: &egui::Context| {
seen.lock().unwrap().push(p.connect_agents);
crate::AgentLink { stopped: !p.connect_agents, ..Default::default() }
}));
app.services.launcher_agents = Some(Box::new(|| true));
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), [false], "the launcher's switch needs the flag");
app.run("prefs.set", json!({"values": {"integrations.connectAgents": true}})).unwrap();
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), [false, true], "a saved Control Port still counts");
}
/// The connection's updates keep the AI-MCP flag the app was started with: losing it would put the
/// page back to the settings it had before the flag after the first frame.
#[test]
fn connection_updates_keep_the_mcp_flag() {
let (mut app, _) = app_with_store();
let ctx = egui::Context::default();
app.services.agent_link = Some(Box::new(|_: &prefs::Integrations, _: &egui::Context| crate::AgentLink::default()));
app.agent_link.mcp_flag = true;
tick(&mut app, &ctx);
assert!(app.agent_link.mcp_flag, "first frame");
app.run("prefs.set", json!({"values": {"integrations.connectAgents": true}})).unwrap();
tick(&mut app, &ctx);
assert!(app.agent_link.mcp_flag, "after a change");
}
/// With the flag the page has no switch of its own and nothing that sets up an MCP client: it says
/// where agents are turned on (the ArtCraft Launcher), and keeps the port, folders and closed-app
/// choice.
#[test]
fn ai_integrations_point_to_the_launcher_and_have_no_switch_or_client_buttons() {
use egui_kittest::{Harness, kittest::Queryable};
let (mut app, _) = app_with_store();
app.agent_link.mcp_flag = true;
open_preferences(&mut app, "integrations");
let mut h = Harness::builder().with_size(vec2(1280.0, 800.0)).build_eframe(move |cc| {
PhotocraftApp::setup_context(&cc.egui_ctx, Default::default());
app
});
h.run_steps(4);
for label in ["Let AI agents connect (MCP)", "Copy Configuration", "Add to Claude Desktop", "Copy Prompt for an Agent"] {
assert!(h.query_by_label(label).is_none(), "{label}");
}
h.get_by_label_contains("ArtCraft Launcher › Settings › AI agents › Let AI agents use Craft apps");
h.get_by_label("Off: turn on AI agents in ArtCraft Launcher › Settings › AI agents.");
assert!(h.query_by_label("Folder agents can open from").is_some(), "the folders stay");
}
/// Without the suite's AI-MCP feature flag the page shows only the settings it had before.
#[test]
fn ai_integrations_without_the_mcp_flag_show_only_the_earlier_settings() {
use egui_kittest::{Harness, kittest::Queryable};
let (mut app, _) = app_with_store();
app.agent_link.mcp_flag = false;
open_preferences(&mut app, "integrations");
let mut h = Harness::builder().with_size(vec2(1280.0, 800.0)).build_eframe(move |cc| {
PhotocraftApp::setup_context(&cc.egui_ctx, Default::default());
app
});
h.run_steps(4);
assert!(h.query_by_label("Let AI agents connect (MCP)").is_none(), "the new connection switch waits for the flag");
assert!(h.query_by_label("Folder agents can open from").is_none());
assert!(h.query_by_label("Allow agent control").is_some(), "the earlier setting stays");
}
#[test]
fn ai_integrations_choices_and_paths_validate_through_prefs_set() {
let (mut app, _) = app_with_store();
for v in ["launch", "headless", "error"] {
app.run("prefs.set", json!({"values": {"integrations.whenAppClosed": v}})).unwrap();
assert_eq!(app.session.prefs().integrations.when_app_closed.name(), v);
}
assert!(app.run("prefs.set", json!({"values": {"integrations.whenAppClosed": "sometimes"}})).is_err());
assert!(app.run("prefs.set", json!({"values": {"integrations.controlPort": 70000}})).is_err());
app.run("prefs.set", json!({"values": {"integrations.writeRoot": "/tmp/out"}})).unwrap();
assert_eq!(app.session.prefs().integrations.write_root, "/tmp/out");
}
/// A connection that is on but failed to start (its port taken) is tried again by itself, with the
/// same settings, and the automation gate follows the live policy.
#[test]
fn a_failed_start_is_retried_without_a_setting_change() {
let (mut app, _) = app_with_store();
let ctx = egui::Context::default();
let calls: Arc<Mutex<u32>> = Arc::default();
let seen = calls.clone();
app.services.agent_link = Some(Box::new(move |p: &prefs::Integrations, _: &egui::Context| {
let mut n = seen.lock().unwrap();
*n += 1;
let mut out = crate::AgentLink::default();
if p.connect_agents && *n >= 3 {
out.status.port = Some(4321);
out.automation.authorize = Some(|_, _| Ok(()));
} else if p.connect_agents {
out.status.error = Some("Couldn't listen on 127.0.0.1:4321: in use".into());
}
out
}));
app.run("prefs.set", json!({"values": {"integrations.connectAgents": true}})).unwrap();
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), 1);
assert!(app.agent_link.port.is_none() && app.prefs_rt.agent_link_retry.is_some(), "a retry is scheduled");
// Not yet due: nothing happens.
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), 1);
// Due: tried again with the same settings, still failing, then started.
app.prefs_rt.agent_link_retry = Some(0.0);
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), 2);
app.prefs_rt.agent_link_retry = Some(0.0);
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), 3);
assert_eq!(app.agent_link.port, Some(4321));
assert!(app.prefs_rt.agent_link_retry.is_none(), "running: no more retries");
assert!(app.session.automation_gate.is_some(), "actions agents record keep the policy");
tick(&mut app, &ctx);
assert_eq!(*calls.lock().unwrap(), 3);
}
+41 -2
View File
@@ -6,16 +6,20 @@ use super::{Color32, Map, PhotocraftApp, RichText, SECTIONS, Sense, Tokens, Valu
// ------------------------------------------------------------------ bodies
/// Render one of our dialogs' bodies.
pub fn body(app: &mut PhotocraftApp, ui: &mut egui::Ui, f: &mut Map<String, Value>) {
/// Render one of our dialogs' bodies (`id`: the dialog's, for answers that arrive later).
pub fn body(app: &mut PhotocraftApp, ui: &mut egui::Ui, f: &mut Map<String, Value>, id: u64) {
match f.get("__prefsui").and_then(Value::as_str).unwrap_or("") {
"prefs" => {
let mut info = app.perf.gpu_info.lines();
info.extend(gpu_memory_lines(app));
f.insert("__gpuInfo".into(), json!(info));
f.insert("__gpuAdapters".into(), json!(app.perf.gpu_info.adapters));
f.insert("__agentLink".into(), serde_json::to_value(&app.agent_link).unwrap_or(Value::Null));
let system = system_theme(app, ui.ctx());
prefs_body(ui, f, system);
if let Some(action) = f.remove("__agentAction").and_then(|a| a.as_str().map(str::to_string)) {
super::agents::agent_action(app, f, &action, id);
}
}
"shortcuts" => shortcuts_body(app, ui, f),
"presets" => presets_body(app, ui, f),
@@ -49,6 +53,14 @@ pub(super) fn humanize(key: &str) -> String {
if key == "notificationAutoHide" {
return "Auto Hide Notifications".into();
}
// MCP: the labels its own rows show (`agents::integration_rows`), also for search.
match key {
"connectAgents" => return "Let AI agents connect (MCP)".into(),
"readRoot" => return "Folder agents can open from".into(),
"writeRoot" => return "Folder agents can save to".into(),
"whenAppClosed" => return "When PhotoCraft is closed".into(),
_ => {}
}
if key == "notificationDurationSeconds" {
return "Notification Duration (seconds)".into();
}
@@ -123,6 +135,10 @@ pub(super) fn choice_label(v: &str) -> String {
"ahd" => "AHD (adaptive homogeneity)".into(),
"mhc" => "Malvar–He–Cutler".into(),
"cpu" => "CPU (no GPU acceleration)".into(),
// MCP › When PhotoCraft is closed.
"launch" => "Open PhotoCraft".into(),
"headless" => "Work without a window".into(),
"error" => "Ask to open PhotoCraft".into(),
v => humanize(v),
}
}
@@ -250,6 +266,20 @@ fn prefs_body(ui: &mut egui::Ui, f: &mut Map<String, Value>, system: Option<egui
if !has_visible_fields(&values, &section) {
ui.add_space(4.0);
ui.label(RichText::new(tl!("These settings aren't available in PhotoCraft yet.")).color(t.text_faint));
} else if section == "integrations"
&& f.get("__agentLink").and_then(|s| s.get("mcpFlag")).and_then(Value::as_bool) == Some(true)
&& let Some(obj) = values.get_mut(&section).and_then(Value::as_object_mut)
{
super::agents::integration_rows(ui, obj, f);
ui.add_space(8.0);
} else if section == "integrations"
&& let Some(obj) = values.get_mut(&section).and_then(Value::as_object_mut)
{
// Without the AI-MCP feature flag: the settings PhotoCraft had before.
let mut shown: Map<String, Value> =
obj.iter().filter(|(k, _)| LEGACY_INTEGRATIONS.contains(&k.as_str())).map(|(k, v)| (k.clone(), v.clone())).collect();
section_fields(ui, &section, &mut shown, &order, lang, system, filter);
obj.extend(shown);
} else if let Some(obj) = values.get_mut(&section).and_then(Value::as_object_mut) {
section_fields(ui, &section, obj, &order, lang, system, filter);
if section == "fileHandling" {
@@ -370,6 +400,10 @@ fn interface_groups(ui: &mut egui::Ui, obj: &mut Map<String, Value>, keys: &[Str
/// Where a clicked colour swatch leaves its preference path and label for the dialog body, which
/// holds the fields the Color Picker request goes in.
/// Preferences › AI Integrations without the AI-MCP feature flag: the settings PhotoCraft had
/// before the agent connection page.
const LEGACY_INTEGRATIONS: [&str; 2] = ["allowAgentControl", "controlPort"];
const PICK_ID: &str = "prefs-pick-color";
/// The colour swatch clicked this frame, if any: (preference path, label).
@@ -522,6 +556,11 @@ fn field_rows(ui: &mut egui::Ui, section: &str, obj: &mut Map<String, Value>, ke
let mut s = s.clone();
ui.add(egui::TextEdit::singleline(&mut s).desired_width(260.0)).accessible_name(tl!(&label));
obj.insert(k, json!(s));
if read_at_launch(&path) {
ui.end_row();
ui.label("");
ui.label(RichText::new(tl!("Applies at next launch.")).color(t.text_dim));
}
}
Value::Number(n) => {
let value_label = ui.label(RichText::new(tl!(&label)).color(t.text_dim));
@@ -134,8 +134,6 @@ pub(super) fn read_at_launch(path: &str) -> bool {
match path {
// Only Windows and Linux draw their own title bar.
"interface.systemTitleBar" => cfg!(all(not(target_arch = "wasm32"), not(target_os = "macos"))),
// The desktop app decides on the control server before its window opens.
"integrations.allowAgentControl" | "integrations.controlPort" => cfg!(not(target_arch = "wasm32")),
// The WinTab context is opened once, when the window starts.
"tools.tabletInput" => cfg!(target_os = "windows"),
_ => false,
@@ -15,6 +15,7 @@ pub fn tick(app: &mut PhotocraftApp, ctx: &egui::Context) {
presets_store(app);
sync_tooltips(app, ctx);
app.sync_recent();
super::agents::sync_agent_link(app, ctx);
// Monotonic, not `ctx.input(|i| i.time)`: logic also runs on hidden ticks, where egui's input
// time is that of the last UI pass.
if let Some(wait) = persist(app, crate::gpu_canvas::now_ms() / 1000.0) {
+11 -13
View File
@@ -598,7 +598,7 @@ fn preferences_interface_search_hides_rows_and_skips_empty_groups() {
}
}
fn app_with_store() -> (PhotocraftApp, Arc<Mutex<Option<String>>>) {
pub(super) fn app_with_store() -> (PhotocraftApp, Arc<Mutex<Option<String>>>) {
app_with_saved(None)
}
@@ -1582,10 +1582,13 @@ fn unimplemented_preferences_are_hidden_from_the_dialog() {
assert!(has_visible_fields(&values, "fileHandling"));
assert!(has_visible_fields(&values, "scratchDisks"));
assert!(!prefs::is_hidden("scratchDisks.disks"));
// Allow Agent Control and Control Port are read at launch (apps/photocraft main.rs).
// MCP: the agent connection and its folders apply at once (`agents.rs`).
assert!(has_visible_fields(&values, "integrations"));
assert!(!prefs::is_hidden("integrations.allowAgentControl"));
assert!(!prefs::is_hidden("integrations.controlPort"));
assert!(!prefs::is_hidden("integrations.readRoot"));
assert!(!prefs::is_hidden("integrations.writeRoot"));
assert!(!prefs::is_hidden("integrations.connectAgents"));
// "Fill new type layers with placeholder text" and "Use Escape to Commit" are live; other Type rows stay hidden.
assert!(has_visible_fields(&values, "type"));
assert!(!prefs::is_hidden("type.fillNewTypeLayersWithPlaceholder"));
@@ -1830,18 +1833,13 @@ fn rendering_mode_explains_next_launch() {
assert!(h.query_by_label("Applies at next launch.").is_none());
}
/// #4097: Allow Agent Control and Control Port are read when the app starts, and say so.
/// Integrations' rows apply at once, so none of them says "Applies at next launch." (it did
/// before the agent connection followed the preferences live).
#[test]
fn integrations_explain_next_launch() {
use egui_kittest::{Harness, kittest::Queryable};
let obj = json!({"allowAgentControl": true, "controlPort": 0}).as_object().unwrap().clone();
let mut h = Harness::new_ui_state(
|ui, obj: &mut Map<String, Value>| section_fields(ui, "integrations", obj, &[], crate::i18n::Lang::from_pref("en"), None, ""),
obj,
);
h.run_steps(4);
h.get_by_label("Allow agent control");
assert_eq!(h.query_all_by_label("Applies at next launch.").count(), 2, "one notice under each row");
fn integrations_apply_without_a_restart() {
for key in ["allowAgentControl", "connectAgents", "controlPort", "readRoot", "writeRoot", "whenAppClosed"] {
assert!(!graphics::read_at_launch(&format!("integrations.{key}")), "{key}");
}
}
#[test]
+68 -1
View File
@@ -340,6 +340,54 @@ pub type AutomationOpenPcraftFn = Box<dyn FnMut(&str) -> Result<Option<(String,
/// Reject engine commands which still perform ambient filesystem I/O.
pub type AutomationCommandFn = Box<dyn Fn(&str, &Value) -> Result<(), String>>;
/// Same policy as [`AutomationCommandFn`] for each step a command runs (`actions.play`).
pub type AutomationAuthorizeFn = fn(&str, &Value) -> photocraft_engine::Result<()>;
/// The automation half of [`Services`]: what control and MCP requests may read, write and run.
/// Replaced as a whole when Preferences › AI Integrations starts the agent connection or
/// changes its folders ([`Services::set_automation`]).
#[derive(Default)]
pub struct AutomationServices {
pub read: Option<AutomationReadFn>,
pub write: Option<AutomationWriteFn>,
pub open_pcraft: Option<AutomationOpenPcraftFn>,
pub save: Option<SaveFileFn>,
pub command: Option<AutomationCommandFn>,
pub authorize: Option<AutomationAuthorizeFn>,
}
/// Preferences › AI Integrations: the agent connection as the dialog and `ui.inspect` show it.
#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AgentLinkStatus {
/// Loopback port agents reach the app on, while it accepts them.
pub port: Option<u16>,
/// Started with `--control`: the launch flags manage the connection, not Preferences.
pub launch_flags: bool,
/// Why the connection, or one of its folders, couldn't be set up.
pub error: Option<String>,
/// The suite's `AI-MCP` feature flag (`craft-flags`): without it the page shows only the
/// connection settings PhotoCraft had before (Allow Agent Control, Control Port).
pub mcp_flag: bool,
/// The ArtCraft Launcher's switch (Settings › AI agents) lets agents use the Craft apps: with
/// the `AI-MCP` flag, the one consent for agents in this window.
pub launcher: bool,
}
/// What [`Services::agent_link`] did after the MCP settings changed.
#[derive(Default)]
pub struct AgentLink {
/// Requests from agents on a connection that just started (or moved to another port).
pub requests: Option<std::sync::mpsc::Receiver<crate::ControlRequest>>,
/// The connection stopped: drop the request channel.
pub stopped: bool,
/// What agent requests may read, write and run now.
pub automation: AutomationServices,
pub status: AgentLinkStatus,
}
/// Starts, moves or stops the agent connection to match Preferences › AI Integrations.
pub type AgentLinkFn = Box<dyn FnMut(&photocraft_engine::prefs::Integrations, &egui::Context) -> AgentLink>;
/// Open a URL in the system browser (native) — reliable cross-platform, unlike `ctx.open_url`.
pub type OpenUrlFn = Box<dyn Fn(&str) -> Result<(), String>>;
@@ -534,7 +582,14 @@ pub struct Services {
/// Same policy as [`Self::automation_command`], as a function pointer the engine calls for
/// each step of `actions.play`. Installed on the session only while a control request or
/// an automation-driven [`PhotocraftApp::run`] runs, so a local play of a recorded `file.*` step still works.
pub automation_authorize: Option<fn(&str, &serde_json::Value) -> photocraft_engine::Result<()>>,
pub automation_authorize: Option<AutomationAuthorizeFn>,
/// Preferences › AI Integrations (desktop): starts, moves or stops the agent connection when
/// its settings change. `None` on the web, and when `--control` manages the connection.
pub agent_link: Option<AgentLinkFn>,
/// Whether the ArtCraft Launcher turned agents on for every Craft app, cheap enough to ask every
/// frame (the desktop app watches the launcher's files on its own thread). `None` without the
/// suite's `AI-MCP` flag, on the web, and in tests that don't set it.
pub launcher_agents: Option<Box<dyn Fn() -> bool>>,
/// Encode an RGBA8 image as PNG (used for screenshots and `ui.render`).
pub encode_png: Option<EncodePngFn>,
/// Open a URL in the system browser (native). Falls back to `ctx.open_url` (web) when unset.
@@ -639,3 +694,15 @@ pub struct Services {
/// Without one, eframe closes the window and the app ends with it.
pub quit: Option<QuitFn>,
}
impl Services {
/// Install the automation services (see [`AutomationServices`]).
pub fn set_automation(&mut self, a: AutomationServices) {
self.automation_read = a.read;
self.automation_write = a.write;
self.automation_open_pcraft = a.open_pcraft;
self.automation_save = a.save;
self.automation_command = a.command;
self.automation_authorize = a.authorize;
}
}
+49 -3
View File
@@ -17,6 +17,39 @@ photocraft --control 7878 --control-token-file /private/path/photocraft-control.
If the file does not exist, PhotoCraft creates it with a fresh 256-bit token. On Unix the new file is mode `0600`; on Windows, protect it with an appropriate user-only ACL. An existing file is reused. If neither a token nor token file is configured, PhotoCraft generates a token for that launch and writes it to standard error. `PHOTOCRAFT_CONTROL_TOKEN` and `PHOTOCRAFT_CONTROL_TOKEN_FILE` are the environment-variable equivalents. A flag wins over its variable and an empty variable counts as unset; with `--control` (or `PHOTOCRAFT_CONTROL_PORT`), a token together with a token file, from flags or variables, is a usage error (exit status 2). Without it no token is read, so the pair is ignored.
### Without `--control`: the agents switch and Preferences › AI Integrations
An app started from the Dock, the Start menu or a file manager has no command line. It starts and stops the control server while it runs. With the suite's `AI-MCP` flag, ArtCraft Launcher › Settings › AI agents › *Let AI agents use Craft apps* is the one switch (for every Craft app; PhotoCraft looks at it every 2 s); without the flag, as before, a saved Control Port. Turning it on or off, or changing the port or folders in Edit › Preferences › AI Integrations, applies at once, with no restart.
| Preference | What it does |
|---|---|
| `integrations.connectAgents` (default off, not in the dialog) | Without the `AI-MCP` flag: serve agents on loopback without `--control`, and publish the connection (below). Set from a saved Control Port; with the flag only the launcher's switch counts |
| `integrations.controlPort` (default 0) | The port for that; 0 = any free port (clients read it from the connection file) |
| `integrations.readRoot` (default empty) | The agents' read folder; with `--control`, stands in for `--automation-read-root` |
| `integrations.writeRoot` (default empty) | The agents' write folder; with `--control`, stands in for `--automation-write-root` |
| `integrations.whenAppClosed` (default `launch`) | What `photocraft-cli mcp` does while agents may use the app but it is closed: `launch`, `headless` or `error` |
| `integrations.allowAgentControl` (default on, not in the dialog) | Off refuses `--control` too |
A file whose `controlPort` (1 to 65535) started the server at launch, as on `main` before the agents switch, loads with `connectAgents` on, so that keeps working without the flag. Started with `--control`, the app leaves the connection to the launch flags and the dialog says so; only `--control` (or `PHOTOCRAFT_CONTROL_PORT`) opens a port at launch.
With `--control`, each launch option, or its environment variable, wins over its preference; the two folders are decided separately (any `--automation-read-root` replaces the read folder). The same folder for both reading and writing shares one capability, as it does when given by flags, so an implicit save works there too. A folder named by a flag that can't be opened stops the launch (exit status 2), as before. A folder named only in the preferences that can't be opened, or isn't an absolute path, is left out, so that direction of file access fails closed; the app still starts, prints the reason on standard error and shows it in a notice. Automation can't change the two folders (`prefs.set` refuses `integrations.readRoot`, `integrations.writeRoot` and the whole `integrations` section): an agent must not widen its own file access.
While agents may connect, the app keeps its token in its settings folder, in `agent-control.token`, exactly as `--control-token-file <settings folder>/agent-control.token` would (created mode `0600` with a fresh token when missing, reused otherwise, also when the port changes; delete it to get a new token). If that file can't be written or read (a read-only or full settings folder), agents can't connect and the dialog shows why. Otherwise the app publishes the connection beside it, in `agent-connection.json`, and removes it when the connection stops:
```json
{
"version": 1,
"pid": 41234,
"port": 7878,
"tokenFile": "/Users/me/Library/Application Support/Photocraft/agent-control.token",
"app": "0.20.1 (8e9277e20, 2026-11-04)"
}
```
A local client reads that file, then the token from `tokenFile`, connects to `127.0.0.1:<port>` and authenticates as below. The file holds no secret. A `--control` launch publishes nothing: whoever started it chose the port and token.
On Windows and Linux the app removes the file when it quits. On macOS (quitting ends the process inside AppKit) and after a crash the file stays behind, naming a `port` nothing listens on: a client should treat a refused connection as "not running", and the next launch replaces or removes the file. Until then, another local program could be listening on that port. A program running as the same user can read the token file anyway, so this matters only against one that can listen on a loopback port but can't read that `0600` file (another user's, or a sandboxed app). A client must check that the process `pid` names is still running before it sends the token, and treat the file as stale otherwise. That check narrows the gap but doesn't close it: the pid can be reused, and the app can quit between the check and the connection. A client that must rule this out should not send the token on the strength of this file at all; it should use challenge authentication (below), which never sends the token to the listener, with no fallback to sending the token. `version` changes only with an incompatible format. The settings folder is the one that holds `preferences.json` (see [Preferences](#preferences); `PHOTOCRAFT_CONFIG_DIR` moves it).
The first request on every TCP connection must authenticate. No other method is dispatched before this succeeds. There are two ways; a refused frame gets `{"ok": false, "error": "authentication required"}` and the connection is closed.
**Challenge authentication** (what `photocraft-cli mcp --bridge` uses) never sends the token, and the server proves it holds the token before the client reveals anything derived from it, so a process that took the port (the app is not running yet, or has exited) learns nothing:
@@ -288,6 +321,8 @@ the same commands work in the app, the CLI and headless MCP. Paths are dotted ca
`unitsAndRulers`, `guidesGridAndSlices`, `plugIns`, `type`, `enhancedControls`, `rawDefaults`,
`integrations`, plus `shortcuts.<command id>`, `menus` (`hidden`, `colors.<id>`), `toolbar`
(`hidden`, `order`) and `colorSettings` (Edit › Color Settings).
`integrations` drives the agent connection while the desktop app runs (`allowAgentControl` also
when it starts); see [Without `--control`](#without---control-preferences--integrations).
| Command | Params |
|---|---|
@@ -385,8 +420,12 @@ magenta alignment lines. `ui.pointer` drives the same code, so agents get identi
`photocraft-automation` provides an MCP server built on the official Rust SDK (`rmcp`). It runs in one of two modes:
- **Headless** (`photocraft-cli mcp`): an in-process `photocraft_engine::Session`. There is no window. CPU composition is the default; `--gpu` or `PHOTOCRAFT_GPU=1` enables optional GPU rendering with automatic CPU fallback.
- **Bridge** (`photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file <path>`): every tool is forwarded to a running `photocraft --control 7878 --control-token-file <path>` over this protocol, so agents see and drive the live app. Explicit `--gpu` / `--no-gpu` flags are rejected with a usage error because the desktop controls rendering; `PHOTOCRAFT_GPU` is ignored in bridge mode. `--bridge 7878` is short for `--bridge 127.0.0.1:7878`. With no `--bridge`, `PHOTOCRAFT_CONTROL_PORT` selects the bridge port (`127.0.0.1:<port>`), and the CLI says so on standard error; with neither (or the variable empty), the MCP runs headless. A value that is not a port is a usage error naming the variable. `--automation-read-root` or `--automation-write-root` with the variable set is a usage error, since the bridge would drop the roots.
- **Headless** (`photocraft-cli mcp --headless`, always an isolated session; or plain `mcp` without the suite's `AI-MCP` flag or while agents may not use the app): an in-process `photocraft_engine::Session`. There is no window. CPU composition is the default; `--gpu` or `PHOTOCRAFT_GPU=1` enables optional GPU rendering with automatic CPU fallback.
- **Bridge** (`photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file <path>`): every tool is forwarded to a running `photocraft --control 7878 --control-token-file <path>` over this protocol, so agents see and drive the live app. Explicit `--gpu` / `--no-gpu` flags are rejected with a usage error because the desktop controls rendering; `PHOTOCRAFT_GPU` is ignored in bridge mode. `--bridge 7878` is short for `--bridge 127.0.0.1:7878`. With no `--bridge`, `PHOTOCRAFT_CONTROL_PORT` selects the bridge port (`127.0.0.1:<port>`), and the CLI says so on standard error; with neither (or the variable empty), plain `mcp` uses the open window (below) or runs headless. A value that is not a port is a usage error naming the variable. `--automation-read-root` or `--automation-write-root` with the variable set is a usage error, since the bridge would drop the roots.
- **The open window** (plain `photocraft-cli mcp`): the bridge, with the address and token read before every tool call from `agent-connection.json` in the app's settings folder, with the suite's `AI-MCP` flag and while the person lets agents use the app. With agents allowed and the app closed, `integrations.whenAppClosed` decides (`launch`, the default: start it and wait up to 45 s; `headless`: headless, with `--automation-read-root` / `--automation-write-root` where given and the app's agent folder for each direction without one; `error`: fail with "PhotoCraft isn't running"), and `--when-closed` overrides it. Otherwise headless, as above (`--headless` forces that). The app publishes that file while agents may connect (the ArtCraft Launcher's switch; without the `AI-MCP` flag a saved Control Port), not with `--control`, and removes it when the connection stops; a file left by a crash fails the connection probe and counts as no app. See [MCP conventions](mcp.md#connecting-the-desktop-app-no-terminal).
`ui.inspect` reports the connection as `agentLink`: `port` while agents can connect, `launchFlags` when `--control` manages it, `error`, `mcpFlag` and `launcher` (the ArtCraft Launcher's switch is on).
The bridge keeps one authenticated TCP connection open, and drops and reconnects before a call once the connection has been idle long enough that the app (which closes idle connections after 30s) may have dropped it. A transport failure while sending a request or waiting for its reply, including a reply timeout, drops the connection and reports that the operation may have completed (a call abandoned before its reply, such as a cancelled MCP wait, also drops it, so the next call never queues behind it); inspect the document before retrying an edit. Edits are never automatically resent (#1007); a connection that could not be established is reported as "the request was not sent" instead. The MCP server opts its pure-read tools (`ui_inspect`, `doc_inspect`, `command_list`, `jobs_list`, `session_list`, `ui_screenshot`) into one automatic retry on a fresh connection, since a read applies nothing; clients driving `BridgeClient` directly opt in per call with `call_read`. The next separate call reconnects and authenticates, and reply lines whose `id` does not match the request are skipped. The client's call timeout is 55s, strictly below the server's 60s reply deadline, so the bridge's error is the one callers see. A waited MCP `command_run` (or `command_batch` step) of an engine command is not bound by it (#8130): the bridge sends `engine.execute` once with `"wait": false` and, when the app starts a background job, polls `jobs.list` until the job ends and returns its result, forwarding progress and cancelling the job (`jobs.cancel`) when the request is cancelled, at once, even while a poll still waits on the app. Limits: a command that does not run as a job, a UI command (not an engine command; the app waits on it) and a lost reply to the start itself still fail at the timeout, the last with "operation may have completed" (look for the job in `jobs_list` before retrying); a failed poll of an uncancelled wait reports the job id and leaves the job running; and an unresponsive app still times out. Clients driving `BridgeClient` directly pass `"wait": false` and poll `jobs.list` themselves. It only accepts the literal loopback addresses `127.0.0.1:<port>` and `[::1]:<port>`, because the app only listens on loopback; `localhost:<port>` means `127.0.0.1:<port>` and is never looked up, since a lookup may return `[::1]` first and reach another process listening there. Every connection authenticates by challenge (see above), so the token is never sent, and a listener that cannot prove it holds the token is reported as such ("the control token was not sent"); an app too old for challenge authentication is refused the same way, so update the app with the CLI. Supply its bearer token with `--control-token-file`, `--control-token`, `PHOTOCRAFT_CONTROL_TOKEN_FILE`, or `PHOTOCRAFT_CONTROL_TOKEN`:
@@ -431,7 +470,10 @@ lines are visible. The protocol is unencrypted and must remain on loopback; do n
it to an untrusted host.
Filesystem access fails closed unless launch-time read and/or write roots are granted with
`--automation-read-root` and `--automation-write-root`. Repeat the read flag to grant an ordered
`--automation-read-root` and `--automation-write-root` (or, for the desktop app, Preferences ›
Integrations' `readRoot` / `writeRoot`, see [Without `--control`](#without---control-preferences--integrations);
each names one folder and is used only when no flag or variable names a root in that direction).
Repeat the read flag to grant an ordered
list of directories; both `--flag <dir>` and `--flag=<dir>` syntax are supported by desktop,
headless MCP and `serve`, and duplicate read roots are allowed. Headless reads try those roots
in launch order and select the first existing regular file. Only a missing file (`NotFound`)
@@ -451,6 +493,10 @@ One explicit write-root flag overrides `PHOTOCRAFT_AUTOMATION_WRITE_ROOT`. These
variables are not supported by headless `photocraft-cli mcp` or `serve`; supply flags explicitly.
In MCP bridge mode, configure roots on the desktop process. Supplying root flags to
`photocraft-cli mcp --bridge` is a usage error; a bridge client cannot grant filesystem access.
While agents may use the app, the folders chosen in Preferences › AI Integrations (`readRoot` /
`writeRoot`) are the agents' roots; `mcp` uses them for a headless session only when the app's
*When PhotoCraft is closed* choice (or `--when-closed headless`) asks for one. Without the
person's consent, `mcp` works headless with only the roots given to it, as before.
Request paths must be non-empty, forward-slash relative paths beneath the applicable root, or
absolute paths beneath a corresponding granted root. An absolute path is compared with the
+4 -3
View File
@@ -322,8 +322,9 @@ At startup the desktop lists recovery metadata, then decodes one document at a t
`photocraft-cli mcp` serves MCP on stdio using `crates/automation`, which is built on `rmcp`:
- **Headless:** `photocraft-cli mcp --automation-read-root <project> --automation-read-root <library> --automation-write-root <project>`. It drives an in-process engine session with ordered read directories and one write directory.
- **Headless:** `photocraft-cli mcp --headless --automation-read-root <project> --automation-read-root <library> --automation-write-root <project>`. Use `--headless` in scripts, tests and agent sessions: without it `mcp` works in the open window while the ArtCraft Launcher's agents switch is on, and may start PhotoCraft (When PhotoCraft Is Closed defaults to starting it). It drives an in-process engine session with ordered read directories and one write directory.
- **Live app:** start `photocraft --control 7878 --control-token-file <private-path> --automation-read-root <project> --automation-read-root <library> --automation-write-root <project>`, then run `photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file <private-path>`. The desktop process owns the roots; root flags on the bridging CLI are a usage error. See `docs/control-protocol.md#mcp-bridge`.
- **Live app, no flags:** with the `AI-MCP` flag, turn on ArtCraft Launcher › Settings › AI agents and add the MCP client there; plain `photocraft-cli mcp` then works in the open window. The app publishes its port and token file in `agent-connection.json` in the settings folder; `mcp` reads it on every call. Without a launcher, a scratch `CRAFT_MCP_DIR` with an `apps.json` naming `photocraft` (the format in storytold/craft-ai-integrations, crate `craft-ai-agents`) turns the switch on for a test. See [MCP conventions](mcp.md#connecting-the-desktop-app-no-terminal). Test it against a scratch settings folder with `PHOTOCRAFT_CONFIG_DIR`, which both the app and the CLI honour.
For headless MCP clients, pass absolute paths to deliberately chosen trusted workspace directories in the launch arguments. Desktop `PHOTOCRAFT_AUTOMATION_READ_ROOT` and `PHOTOCRAFT_AUTOMATION_WRITE_ROOT` environment variables do **not** grant headless CLI access. Omitting a root flag deliberately denies that direction of access.
@@ -367,7 +368,7 @@ Claude Code (`.mcp.json` in the repo root, or `claude mcp add`):
"mcpServers": {
"photocraft": {
"command": "/path/to/photocraft/target/release/photocraft-cli",
"args": ["mcp", "--automation-read-root", "/absolute/path/to/trusted/workspace", "--automation-read-root", "/absolute/path/to/reference/library", "--automation-write-root", "/absolute/path/to/trusted/workspace"]
"args": ["mcp", "--headless", "--automation-read-root", "/absolute/path/to/trusted/workspace", "--automation-read-root", "/absolute/path/to/reference/library", "--automation-write-root", "/absolute/path/to/trusted/workspace"]
},
"photocraft-live": {
"command": "/path/to/photocraft/target/release/photocraft-cli",
@@ -380,7 +381,7 @@ Claude Code (`.mcp.json` in the repo root, or `claude mcp add`):
```sh
cargo build --release -p photocraft-cli
mkdir -p "$PWD/photocraft-work"
claude mcp add photocraft -- "$PWD/target/release/photocraft-cli" mcp \
claude mcp add photocraft -- "$PWD/target/release/photocraft-cli" mcp --headless \
--automation-read-root "$PWD/photocraft-work" \
--automation-write-root "$PWD/photocraft-work"
```
+65 -2
View File
@@ -1,5 +1,66 @@
# MCP conventions
## Connecting the desktop app (no terminal)
**One switch, in the ArtCraft Launcher.** Settings › AI agents › **Let AI agents use Craft apps**
is the person's consent for every Craft app, PhotoCraft included; PhotoCraft has no switch of its
own. **Add** next to an MCP client (Claude Desktop, Claude Code, Cursor, LM Studio) puts one entry
in it, `ArtCraft`, for every installed Craft app (the `craft-ai-mcp` gateway, which starts
`photocraft-cli mcp`); **Copy** gives the configuration for any other client. Then restart the
client. Adding to MCP clients is the launcher's job alone: PhotoCraft writes no client
configuration. The design is in storytold/craft-ai-integrations#195.
This is behind the Craft suite's `AI-MCP` feature flag (`craft-flags`). Flags are set only in the
per-user `ArtCraft/flags.toml` (`AI-MCP = true` under `[flags]`; on Windows in
`%LOCALAPPDATA%\ArtCraft`), which every Craft app and the launcher read, or for one run with
`CRAFT_FLAGS=AI-MCP`; no app or launcher setting switches them. Without the flag, everything is as
it was: Preferences › AI Integrations shows Allow Agent Control and Control Port, a Control Port
already set keeps its connection, and the launcher's switch means nothing to PhotoCraft.
While the launcher's switch is on, its app list `ArtCraft/mcp/apps.json` (in the per-user local
configuration folder; `CRAFT_MCP_DIR` moves it) names `photocraft`, read through
`craft-ai-agents`, the same crate the launcher writes it with and the gateway reads it with.
PhotoCraft then serves agents on loopback (any free port by default, or the Control Port) with a
token it keeps in its settings folder, and publishes both in `agent-connection.json` there. The
app looks at the launcher's files every 2 s, so switching there applies without a restart. Allow
Agent Control off still refuses agents. Started with `--control`, the app ignores all this and the
launch flags manage the connection, as before.
**Edit › Preferences › AI Integrations** says whether agents can connect (and on which port), and
keeps what is PhotoCraft's own: the port, the folders agents can open from and save to, and what
happens when an agent needs PhotoCraft while it is closed (open it, work without a window, or ask
the user to open it).
### `photocraft-cli mcp`
Plain `photocraft-cli mcp` works in the open PhotoCraft window when the person lets agents use it,
and otherwise without a window, as it always did. It reads `agent-connection.json` before every
tool call, so the client configuration holds no port or token and keeps working when PhotoCraft
restarts or moves to another port.
- **Agents allowed, PhotoCraft open:** tools work in the window.
- **Agents allowed, PhotoCraft closed:** When PhotoCraft Is Closed decides (`--when-closed
<launch|headless|error>` overrides it): start the app and wait for it, serve a headless
session, or say to open it. The headless session takes `--automation-read-root` and
`--automation-write-root` when given to `mcp`, each on its own: a given read root replaces the
app's read folder, a given write root its write folder, and the app's folder is used for any
direction without a flag. The app is started only on a tool
call, never when the MCP client starts.
- **Agents not allowed:** a headless session with only the roots given to `mcp`, exactly as
before; the app is never started and its folders aren't used.
- **`--headless`:** always headless, whatever the switch says.
- **`--bridge` (or `PHOTOCRAFT_CONTROL_PORT`):** a `photocraft --control` app, as before.
A session that went headless stays headless until the MCP client restarts it, so documents don't
move under the agent. In the Flatpak the connection needs
`flatpak override --user --share=network ai.storyteller.photocraft`.
When `mcp` starts the app, macOS goes through LaunchServices (`open -a`) and Windows through
Explorer, as a double-click would: the app is no child of the CLI, so it keeps running when the
MCP client ends the CLI's process tree (Claude Code does on Windows), and it stays out of a
Microsoft Store client's container, where new files under `%APPDATA%` would land in the client's
package instead of PhotoCraft's settings folder. Linux starts it in its own process group.
## Install and register
From the repository root, with the [source-build prerequisites](development.md#prerequisites)
@@ -47,10 +108,12 @@ not put the CLI on `PATH`.
## Start a session
PhotoCraft follows the same conventions as FilmCraft #28. Start a headless session:
PhotoCraft follows the same conventions as FilmCraft #28. Start a headless session (`--headless`:
without it, `mcp` works in the open PhotoCraft window while the ArtCraft Launcher's agents switch is
on, and may start the app; scripts, tests and agents pass it):
```sh
photocraft-cli mcp \
photocraft-cli mcp --headless \
--automation-read-root /work/project \
--automation-read-root /library/reference \
--automation-write-root /work/project
+2 -1
View File
@@ -1,6 +1,6 @@
# Roadmap
> **Last reviewed:** 2026-10-11 · **Last updated:** 2026-10-11 · **Change:** minor (adaptive Unsharp Mask performance evidence linked; Photomerge status correction retained; alpha gate, focus and estimates unchanged) · **Target:** Adobe Photoshop 2026
> **Last reviewed:** 2026-10-11 · **Last updated:** 2026-11-12 · **Change:** minor (M11: the desktop app connects to MCP clients from Edit › Preferences › AI Integrations, no terminal, no restart; alpha gate, focus and estimates unchanged) · **Target:** Adobe Photoshop 2026
- UI.5: Panels can detach, join other tab groups, split, resize and redock through shared docking transactions. Custom layouts persist with workspaces, respect workspace locking, and retain collapse flags for intact native groups.
@@ -116,6 +116,7 @@ Each milestone has a **definition of done (DoD)** and must leave `main` green on
| Date | Change | Summary |
|---|---|---|
| 2026-11-12 | minor | M11: Edit › Preferences › AI Integrations connects MCP clients to the running app without a terminal or restart; milestones, alpha gate and estimates unchanged |
| 2026-10-11 | minor | Linked adaptive Unsharp Mask performance and quality evidence; milestones, alpha gate and estimates unchanged |
| 2026-10-10 | minor | Photomerge is implemented; real-world quality validation remains open |
| 2026-10-10 | minor | Alpha gate table (core-workflow gate): passes, stage stays alpha |
+4 -3
View File
@@ -9,9 +9,9 @@ Generated by `cargo xtask scorecard` from `perf/budgets.toml`, `perf/baseline.js
| [Performance](#performance) | 3 | 22 | 56 | 90 scenarios: 3 within budget, 22 over budget or failing, 9 tracked only, 52 not run, 4 not measurable yet (baseline 2026-10-05) |
| [File compatibility](#file-compatibility) | 11 | 14 | 2 | io corpus: oracle ≥ 148/170, round trip ≥ 169/170; psd-tools corpus: oracle ≥ 249/309, round trip ≥ 308/309; photoshop oracles: oracle ≥ 190/258, round trip ≥ 258/258 |
| [Tools](#tools) | 36 | 9 | 0 | |
| [Workspace and UI](#workspace-and-ui) | 15 | 6 | 2 | settings that do nothing: 8 of 199 (target 0) |
| [Workspace and UI](#workspace-and-ui) | 15 | 6 | 2 | settings that do nothing: 8 of 203 (target 0) |
| [Type](#type) | 5 | 5 | 0 | |
| [Automation](#automation) | 5 | 4 | 2 | 664 of 664 menu items live (100.0%) |
| [Automation](#automation) | 6 | 4 | 2 | 664 of 664 menu items live (100.0%) |
| [Reliability](#reliability) | 5 | 2 | 0 | never-crash lints on 28 of 28 crates; panic_hunt present |
| [Distribution](#distribution) | 5 | 5 | 1 | |
| [Open bugs](#open-bugs) | 31 | 1 | 0 | |
@@ -214,7 +214,7 @@ Corpus floors (`crates/io/tests/it/corpus.rs`): the enforced minimums; the corpu
## Workspace and UI
**Settings that do nothing: 8 of 199** (target 0, #204). Counted by the prefs audit (`xtask/src/scorecard.rs`): a `Preferences` field counts as read when code outside the prefs model (`prefs.rs` except its `impl Session` blocks; tests excluded; the schema-driven dialog never names a field) accesses `section.field`, or `.section` and `.field` in the same file, or calls a section method that reads `self.field`. It is a heuristic lower bound: a generic name can look read when it isn't.
**Settings that do nothing: 8 of 203** (target 0, #204). Counted by the prefs audit (`xtask/src/scorecard.rs`): a `Preferences` field counts as read when code outside the prefs model (`prefs.rs` except its `impl Session` blocks; tests excluded; the schema-driven dialog never names a field) accesses `section.field`, or `.section` and `.field` in the same file, or calls a section method that reads `self.field`. It is a heuristic lower bound: a generic name can look read when it isn't.
Unread: `general.color_picker`, `workspace.auto_show_hidden_panels`, `workspace.enable_floating_document_window_docking`, `performance.legacy_compositing`, `plug_ins.show_extension_panels`, `plug_ins.allow_scripts_to_connect`, `type_.text_engine`, `enhanced_controls.scrubby_slider_acceleration`.
@@ -276,6 +276,7 @@ Menu wiring (`docs/parity-checklist.md`): 664 of 664 menu items live (100.0%). T
| AUTO-219-8 | xtask check that every panel button routes through a command id | partial | [#219](https://github.com/storytold/photocraft/issues/219) | cargo xtask panel-commands (run by xtask ci and CI) fails on a shell click handler that changes the document or session directly; 1 allowlisted function left (panels/color.rs color_field assigns the foreground/background colour instead of tools.setColors) |
| AUTO-219-9 | Headless commands for in-canvas type editing, Liquify/Puppet strokes, transform handles | done | [#219](https://github.com/storytold/photocraft/issues/219) | type.hitTest, type.caret, type.navigate; filter.liquify strokes, edit.puppetWarp pins, type.edit, edit.transform |
| AUTO-219-10 | Agent acceptance suite grown to 30-50 workflows | partial | [#219](https://github.com/storytold/photocraft/issues/219) | automation/tests/it/agent_tasks.rs runs 10 workflows over MCP |
| AUTO-MCP-LIVE | Connect an MCP client to the running app without a terminal (no flags, ports or tokens to copy) | done | | 2026-11-12 (#5525, #11363, craft-ai-integrations#195): the ArtCraft Launcher's agents switch (the one consent; read through craft-ai-agents) starts and stops the loopback control server while the app runs (no restart) and publishes agent-connection.json; plain photocraft-cli mcp works in the open app on every call while agents are allowed (launch / headless / error while it is closed) and headless otherwise (--headless forces it); the launcher's Add buttons register every Craft app, PhotoCraft writes no client configuration. automation/tests/mcp_live.rs, apps/photocraft/src/agent_link.rs tests |
## Reliability
+8
View File
@@ -112,5 +112,13 @@ integrate() {
done
}
# `PhotoCraft.AppImage --cli <args>` runs the bundled photocraft-cli: MCP clients start
# `--cli mcp` this way (the ArtCraft Launcher's app list), since the mount point that holds
# the CLI changes with every run.
if [ "${1:-}" = "--cli" ]; then
shift
exec "$APPDIR/usr/bin/photocraft-cli" "$@"
fi
integrate
exec "$APPDIR/usr/bin/photocraft" "$@"
+8
View File
@@ -22,6 +22,8 @@ mkdir -p "$APPDIR/usr/share/icons"
cp -R "$ROOT/assets/app-icon/hicolor" "$APPDIR/usr/share/icons/"
printf '#!/bin/sh\necho "stub: $*"\n' >"$APPDIR/usr/bin/photocraft"
chmod +x "$APPDIR/usr/bin/photocraft"
printf '#!/bin/sh\necho "cli stub: $*"\n' >"$APPDIR/usr/bin/photocraft-cli"
chmod +x "$APPDIR/usr/bin/photocraft-cli"
APPIMAGE="$TMP/photocraft test.AppImage" # spaces on purpose: Exec must stay quoted
: >"$APPIMAGE"
@@ -152,4 +154,10 @@ rm -f "$am_desktop"
"$APPDIR/AppRun" >/dev/null || fail "launch after AM removal exited non-zero"
[[ -f "$DESKTOP" ]] || fail "no desktop entry after the AM launcher was removed"
# 12. `--cli` runs the bundled CLI (MCP clients start `--cli mcp`), without integrating.
rm -rf "$XDG_DATA_HOME"
out="$("$APPDIR/AppRun" --cli mcp --headless)" || fail "--cli exited non-zero"
[ "$out" = "cli stub: mcp --headless" ] || fail "--cli output: $out"
[ ! -e "$XDG_DATA_HOME" ] || fail "--cli integrated the desktop entry"
echo "AppRun desktop integration ok"
+2
View File
@@ -120,6 +120,8 @@ echo "==> assembling $APP"
mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
# Executable and icon carry the display name (CFBundleExecutable / CFBundleIconFile).
cp "$WORK/bin/photocraft" "$APP/Contents/MacOS/PhotoCraft"
# The CLI too, beside the app: Preferences › AI Integrations points MCP clients at it
# (`photocraft-cli mcp`), and it starts the app when an agent needs it.
cp "$WORK/bin/photocraft-cli" "$APP/Contents/MacOS/photocraft-cli"
cp "$ROOT/assets/app-icon/photocraft.icns" "$APP/Contents/Resources/PhotoCraft.icns"
# Notices for the bundled font fallback, included before the bundle is signed.
+6
View File
@@ -80,3 +80,9 @@ target = "Agent acceptance suite grown to 30-50 workflows"
status = "partial"
issue = 219
note = "automation/tests/it/agent_tasks.rs runs 10 workflows over MCP"
[[item]]
id = "AUTO-MCP-LIVE"
target = "Connect an MCP client to the running app without a terminal (no flags, ports or tokens to copy)"
status = "done"
note = "2026-11-12 (#5525, #11363, craft-ai-integrations#195): the ArtCraft Launcher's agents switch (the one consent; read through craft-ai-agents) starts and stops the loopback control server while the app runs (no restart) and publishes agent-connection.json; plain photocraft-cli mcp works in the open app on every call while agents are allowed (launch / headless / error while it is closed) and headless otherwise (--headless forces it); the launcher's Add buttons register every Craft app, PhotoCraft writes no client configuration. automation/tests/mcp_live.rs, apps/photocraft/src/agent_link.rs tests"