mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-21 01:51:46 +01:00
Merge pull request #2550 from davidmann4/agents/default-folder
craft-control agents: default agent folder in Documents and the agent_folders tool
This commit is contained in:
6 files changed
+257
-8
No files matched your search
Generated
+1
@@ -1714,6 +1714,7 @@ dependencies = [
|
||||
"craft-ai-agents",
|
||||
"craft-atomic",
|
||||
"craft-flags",
|
||||
"dirs",
|
||||
"getrandom 0.3.4",
|
||||
"log",
|
||||
"proptest",
|
||||
|
||||
@@ -14,7 +14,7 @@ workspace = true
|
||||
default = []
|
||||
# AI agents in the open window (desktop): the ArtCraft Launcher's switch, the connection file and
|
||||
# the `<id>-cli mcp` side that finds the open window. The agent settings build without it.
|
||||
agents = ["dep:craft-ai-agents", "dep:craft-atomic", "dep:craft-flags", "dep:log"]
|
||||
agents = ["dep:craft-ai-agents", "dep:craft-atomic", "dep:craft-flags", "dep:dirs", "dep:log"]
|
||||
|
||||
[dependencies]
|
||||
serde = { workspace = true }
|
||||
@@ -28,6 +28,8 @@ getrandom = "0.3"
|
||||
craft-ai-agents = { workspace = true, optional = true }
|
||||
craft-atomic = { workspace = true, optional = true }
|
||||
craft-flags = { workspace = true, optional = true }
|
||||
# The system's Documents folder for the default agent folder, on every desktop system (MIT OR Apache-2.0).
|
||||
dirs = { version = "7", optional = true }
|
||||
log = { workspace = true, optional = true }
|
||||
|
||||
[dev-dependencies]
|
||||
|
||||
@@ -0,0 +1,196 @@
|
||||
//! The folder agents open and save files in when the person set none, and the tool that tells an
|
||||
//! agent which folders it may use.
|
||||
//!
|
||||
//! Each app has its own default folder, `Documents/ArtCraft/Agents/<App>`, in the system's
|
||||
//! Documents folder on every desktop system, so people find what an agent made. The person's own
|
||||
//! folder settings ([`AgentSettings::read_root`], [`AgentSettings::write_root`]) win; an empty one
|
||||
//! falls back to the default folder ([`AgentSettings::folders`]).
|
||||
//!
|
||||
//! An agent learns the folders from the app's own MCP tool [`FOLDERS_TOOL`], answered with
|
||||
//! [`folders_answer`]. The ArtCraft gateway passes app tools through, so the agent finds it by
|
||||
//! searching for "folder" or "files", and the app reports the folders it really uses.
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde_json::{Value, json};
|
||||
|
||||
use super::AgentSettings;
|
||||
|
||||
/// The folders under Documents that hold every app's default agent folder.
|
||||
pub const DEFAULT_FOLDER_PARENTS: [&str; 2] = ["ArtCraft", "Agents"];
|
||||
|
||||
/// Longest app name a default folder is made for; app names are short catalog names.
|
||||
const MAX_APP_NAME: usize = 64;
|
||||
|
||||
/// The MCP tool an app offers to tell agents its folders.
|
||||
pub const FOLDERS_TOOL: &str = "agent_folders";
|
||||
|
||||
/// [`FOLDERS_TOOL`]'s description, for the app's tool list.
|
||||
pub const FOLDERS_TOOL_DESCRIPTION: &str = "Where this app opens and saves files for agents. Put files the app should open in \
|
||||
read_folder (or a folder below it) and find what it saves in write_folder. Both are usually the app's agent folder in \
|
||||
Documents/ArtCraft/Agents; the person may have set others. null means the app has no such folder now.";
|
||||
|
||||
/// The folders an agent session may open from and save to, after the default is filled in.
|
||||
#[derive(Clone, Debug, Default, PartialEq, Eq)]
|
||||
#[non_exhaustive]
|
||||
pub struct AgentFolders {
|
||||
/// The folder files may be opened from.
|
||||
pub read: Option<PathBuf>,
|
||||
/// The folder files may be saved to.
|
||||
pub write: Option<PathBuf>,
|
||||
}
|
||||
|
||||
/// The app's default agent folder, `Documents/ArtCraft/Agents/<app_name>`. `None` when the
|
||||
/// system names no Documents folder and no home folder, or when `app_name` isn't a plain name
|
||||
/// (empty, too long, or with anything other than ASCII letters, digits, `-` and `_`), so a name
|
||||
/// can't lead outside the Agents folder. Doesn't touch the disk.
|
||||
pub fn default_folder(app_name: &str) -> Option<PathBuf> {
|
||||
default_folder_in(dirs::document_dir(), dirs::home_dir(), app_name)
|
||||
}
|
||||
|
||||
/// [`default_folder`] for these system folders: Documents, otherwise `<home>/Documents` (Linux
|
||||
/// without an XDG Documents folder). A relative folder is ignored.
|
||||
fn default_folder_in(documents: Option<PathBuf>, home: Option<PathBuf>, app_name: &str) -> Option<PathBuf> {
|
||||
if !plain_app_name(app_name) {
|
||||
return None;
|
||||
}
|
||||
let documents = documents.filter(|d| d.is_absolute()).or_else(|| home.filter(|h| h.is_absolute()).map(|h| h.join("Documents")))?;
|
||||
Some(DEFAULT_FOLDER_PARENTS.iter().fold(documents, |path, part| path.join(part)).join(app_name))
|
||||
}
|
||||
|
||||
/// A name that is one ordinary path component on every system.
|
||||
fn plain_app_name(name: &str) -> bool {
|
||||
!name.is_empty() && name.len() <= MAX_APP_NAME && name.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
|
||||
}
|
||||
|
||||
impl AgentSettings {
|
||||
/// The folders for agents of the app `app_name`: the person's own folder settings, and
|
||||
/// [`default_folder`] for an empty one ([`Self::folders_with`]).
|
||||
pub fn folders(&self, app_name: &str) -> AgentFolders {
|
||||
self.folders_with(default_folder(app_name).as_deref())
|
||||
}
|
||||
|
||||
/// The person's own folder settings, and `default` for an empty one. The default folder is
|
||||
/// created when it is used; if it can't be, that direction has no folder (and the reason is
|
||||
/// logged), so an agent is refused rather than pointed at a folder that isn't there.
|
||||
pub fn folders_with(&self, default: Option<&Path>) -> AgentFolders {
|
||||
let (read, write) = (self.read_folder(), self.write_folder());
|
||||
let default = if read.is_none() || write.is_none() { default.and_then(created) } else { None };
|
||||
AgentFolders { read: read.or_else(|| default.clone()), write: write.or(default) }
|
||||
}
|
||||
}
|
||||
|
||||
/// `dir`, created with its parents if missing; `None` when it can't be.
|
||||
fn created(dir: &Path) -> Option<PathBuf> {
|
||||
match std::fs::create_dir_all(dir) {
|
||||
Ok(()) => Some(dir.to_path_buf()),
|
||||
Err(e) => {
|
||||
log::warn!("couldn't create the agent folder {}: {e}", dir.display());
|
||||
None
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// [`FOLDERS_TOOL`]'s answer: `read_folder` and `write_folder`, each a path or `null`. A path
|
||||
/// that isn't Unicode is shown with replacement characters.
|
||||
pub fn folders_answer(folders: &AgentFolders) -> Value {
|
||||
let path = |p: &Option<PathBuf>| p.as_deref().map(|p| p.to_string_lossy().into_owned());
|
||||
json!({ "read_folder": path(&folders.read), "write_folder": path(&folders.write) })
|
||||
}
|
||||
|
||||
/// [`FOLDERS_TOOL`] as an MCP tool entry (`name`, `description`, an `inputSchema` with no
|
||||
/// parameters), for an app that lists its tools as JSON.
|
||||
pub fn folders_tool() -> Value {
|
||||
json!({
|
||||
"name": FOLDERS_TOOL,
|
||||
"description": FOLDERS_TOOL_DESCRIPTION,
|
||||
"inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
#![allow(clippy::unwrap_used)]
|
||||
use super::*;
|
||||
|
||||
fn abs(parts: &[&str]) -> PathBuf {
|
||||
let root = if cfg!(windows) { PathBuf::from(r"C:\") } else { PathBuf::from("/") };
|
||||
parts.iter().fold(root, |p, part| p.join(part))
|
||||
}
|
||||
|
||||
// The default folder is in Documents; without one, in <home>/Documents.
|
||||
#[test]
|
||||
fn default_folder_is_in_documents_then_home() {
|
||||
let docs = abs(&["Users", "a", "Docs"]);
|
||||
let home = abs(&["Users", "a"]);
|
||||
assert_eq!(
|
||||
default_folder_in(Some(docs.clone()), Some(home.clone()), "PhotoCraft"),
|
||||
Some(docs.join("ArtCraft").join("Agents").join("PhotoCraft"))
|
||||
);
|
||||
assert_eq!(
|
||||
default_folder_in(None, Some(home.clone()), "PhotoCraft"),
|
||||
Some(home.join("Documents").join("ArtCraft").join("Agents").join("PhotoCraft"))
|
||||
);
|
||||
// A relative Documents folder is no place to put files.
|
||||
assert_eq!(
|
||||
default_folder_in(Some(PathBuf::from("Docs")), Some(home.clone()), "PhotoCraft"),
|
||||
Some(home.join("Documents").join("ArtCraft").join("Agents").join("PhotoCraft"))
|
||||
);
|
||||
assert_eq!(default_folder_in(None, Some(PathBuf::from("rel")), "PhotoCraft"), None);
|
||||
assert_eq!(default_folder_in(None, None, "PhotoCraft"), None);
|
||||
}
|
||||
|
||||
// A name that could lead outside the Agents folder gets no default folder.
|
||||
#[test]
|
||||
fn odd_app_names_get_no_default_folder() {
|
||||
let docs = Some(abs(&["Docs"]));
|
||||
for name in ["", ".", "..", "../x", "a/b", r"a\b", "C:", "a b", "x".repeat(MAX_APP_NAME + 1).as_str(), "Fotó"] {
|
||||
assert_eq!(default_folder_in(docs.clone(), None, name), None, "{name:?}");
|
||||
}
|
||||
assert!(default_folder_in(docs, None, "grid-craft_2").is_some());
|
||||
}
|
||||
|
||||
// The person's own folders win; the default only fills an empty setting, and is created.
|
||||
#[test]
|
||||
fn own_folders_win_and_the_default_is_created() {
|
||||
let mine = AgentSettings { read_root: " /in ".into(), write_root: "/out".into(), ..AgentSettings::default() };
|
||||
assert_eq!(mine.folders("PhotoCraft"), AgentFolders { read: Some(PathBuf::from("/in")), write: Some(PathBuf::from("/out")) });
|
||||
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let default = default_folder_in(Some(dir.path().to_path_buf()), None, "PhotoCraft").unwrap();
|
||||
assert_eq!(created(&default), Some(default.clone()));
|
||||
assert!(default.is_dir());
|
||||
// A file where the folder should be: no folder, not a crash.
|
||||
let blocked = dir.path().join("file");
|
||||
std::fs::write(&blocked, b"x").unwrap();
|
||||
assert_eq!(created(&blocked.join("Agents")), None);
|
||||
}
|
||||
|
||||
// With no own folders, both directions get the one default folder, created; a default that
|
||||
// can't be created leaves them without one.
|
||||
#[test]
|
||||
fn empty_settings_use_one_default_folder() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let default = dir.path().join("ArtCraft").join("Agents").join("PhotoCraft");
|
||||
let folders = AgentSettings::default().folders_with(Some(&default));
|
||||
assert_eq!(folders, AgentFolders { read: Some(default.clone()), write: Some(default.clone()) });
|
||||
assert!(default.is_dir());
|
||||
let only_read = AgentSettings { read_root: "/in".into(), ..AgentSettings::default() };
|
||||
assert_eq!(only_read.folders_with(Some(&default)), AgentFolders { read: Some(PathBuf::from("/in")), write: Some(default) });
|
||||
|
||||
let file = dir.path().join("file");
|
||||
std::fs::write(&file, b"x").unwrap();
|
||||
assert_eq!(AgentSettings::default().folders_with(Some(&file.join("PhotoCraft"))), AgentFolders::default());
|
||||
assert_eq!(AgentSettings::default().folders("..").read, None);
|
||||
}
|
||||
|
||||
// The tool's answer names both folders, null where there is none.
|
||||
#[test]
|
||||
fn the_answer_names_both_folders() {
|
||||
let folders = AgentFolders { read: Some(PathBuf::from("/in")), write: None };
|
||||
assert_eq!(folders_answer(&folders), json!({"read_folder": "/in", "write_folder": null}));
|
||||
let tool = folders_tool();
|
||||
assert_eq!(tool["name"], FOLDERS_TOOL);
|
||||
assert_eq!(tool["inputSchema"]["properties"], json!({}));
|
||||
}
|
||||
}
|
||||
@@ -14,7 +14,7 @@
|
||||
//! folders are for agents the person let in.
|
||||
//! - No app accepts agents, but agents are allowed: the closed-app choice decides
|
||||
//! ([`LiveConfig::when_closed`], otherwise [`AgentSettings::when_app_closed`]): start the app and
|
||||
//! wait until it accepts agents, a headless session with the app's agent folders (the command's
|
||||
//! wait until it accepts agents, a headless session with the app's agent folders ([`AgentSettings::folders`], the default agent folder for an empty setting; the command's
|
||||
//! folders win), or an error that says what to do.
|
||||
//!
|
||||
//! Once headless, the session stays headless: documents don't move under the agent. Only a session
|
||||
@@ -138,6 +138,9 @@ pub struct LiveConfig<W, H> {
|
||||
/// The folder a headless session may save to (the CLI's write root); while agents are allowed
|
||||
/// it replaces the app's write folder.
|
||||
pub write_root: Option<PathBuf>,
|
||||
/// The app's default agent folder, used for an empty folder setting
|
||||
/// ([`AgentSettings::folders_with`]); [`super::default_folder`] of `app_name` unless changed.
|
||||
pub default_folder: Option<PathBuf>,
|
||||
/// Starts the app; `None` when this install can't ([`launcher`] found nothing to start).
|
||||
pub launch: Option<LaunchFn>,
|
||||
/// How long a started app gets to accept agents ([`LAUNCH_TIMEOUT`]; at most 10 minutes).
|
||||
@@ -159,8 +162,10 @@ impl<W, H> LiveConfig<W, H> {
|
||||
connect: impl Fn(&Window) -> Result<W, String> + Send + Sync + 'static,
|
||||
headless: impl Fn(&HeadlessFolders) -> Result<H, String> + Send + Sync + 'static,
|
||||
) -> Self {
|
||||
let app_name = app_name.into();
|
||||
Self {
|
||||
app_name: app_name.into(),
|
||||
default_folder: super::default_folder(&app_name),
|
||||
app_name,
|
||||
config_dir,
|
||||
when_closed: None,
|
||||
read_roots: Vec::new(),
|
||||
@@ -260,11 +265,17 @@ impl<W: Clone, H: Clone> Live<W, H> {
|
||||
match self.cfg.when_closed.unwrap_or(consent.settings.when_app_closed) {
|
||||
WhenAppClosed::Error => Err(format!("{app} isn't running: open it, then try again.")),
|
||||
WhenAppClosed::Headless => {
|
||||
let app_read = self.cfg.read_roots.is_empty() && consent.settings.read_folder().is_some();
|
||||
let app_write = self.cfg.write_root.is_none() && consent.settings.write_folder().is_some();
|
||||
let read =
|
||||
if self.cfg.read_roots.is_empty() { consent.settings.read_folder().into_iter().collect() } else { self.cfg.read_roots.clone() };
|
||||
let write = self.cfg.write_root.clone().or_else(|| consent.settings.write_folder());
|
||||
// The app's folders, its default agent folder for an empty setting; only looked up
|
||||
// (and the default created) when the command leaves a direction open.
|
||||
let own = if self.cfg.read_roots.is_empty() || self.cfg.write_root.is_none() {
|
||||
consent.settings.folders_with(self.cfg.default_folder.as_deref())
|
||||
} else {
|
||||
super::AgentFolders::default()
|
||||
};
|
||||
let app_read = self.cfg.read_roots.is_empty() && own.read.is_some();
|
||||
let app_write = self.cfg.write_root.is_none() && own.write.is_some();
|
||||
let read = if self.cfg.read_roots.is_empty() { own.read.into_iter().collect() } else { self.cfg.read_roots.clone() };
|
||||
let write = self.cfg.write_root.clone().or(own.write);
|
||||
let why = format!("{app} isn't running and its agent folders can't be used");
|
||||
self.headless(&HeadlessFolders { read, write }, app_read || app_write, &why)
|
||||
}
|
||||
|
||||
@@ -20,6 +20,7 @@
|
||||
//! |---|---|---|
|
||||
//! | Settings | [`AgentSettings`], [`WhenAppClosed`], [`agents_allowed`], [`folder`] | every target |
|
||||
//! | The launcher's switch | [`AgentSwitch`], [`mcp_flag`], [`launcher_allows`], [`POLL`] | desktop, feature `agents` |
|
||||
//! | The agent folders | [`AgentFolders`], [`AgentSettings::folders`], [`default_folder`], [`FOLDERS_TOOL`], [`folders_answer`], [`folders_tool`] | desktop, feature `agents` |
|
||||
//! | The connection file | [`Connection`], [`write_connection`], [`read_connection`], [`remove_connection`], [`remove_stale_connection`], [`probe`] | desktop, feature `agents` |
|
||||
//! | The CLI's side | [`Live`], [`LiveConfig`], [`Route`], [`Window`], [`Consent`], [`HeadlessFolders`], [`find_window`], [`launcher`] | desktop, feature `agents` |
|
||||
//!
|
||||
@@ -41,6 +42,10 @@
|
||||
//! the app's process id. No restart, no agents switch of its own. There is one connection file
|
||||
//! per settings folder: an app that runs more than one process on one folder lets only one of
|
||||
//! them accept agents.
|
||||
//! 3. The folders agents open from and save to are `settings.folders("GridCraft")`
|
||||
//! ([`AgentSettings::folders`]): the person's own, otherwise `Documents/ArtCraft/Agents/GridCraft`.
|
||||
//! Its MCP server offers [`FOLDERS_TOOL`] (described by [`FOLDERS_TOOL_DESCRIPTION`] or listed
|
||||
//! as [`folders_tool`]), answered with [`folders_answer`] for the folders it uses.
|
||||
//!
|
||||
//! Its `gridcraft-cli mcp`:
|
||||
//!
|
||||
@@ -62,6 +67,8 @@ pub use settings::{AgentSettings, WhenAppClosed, agents_allowed, folder};
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
mod connection;
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
mod folders;
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
mod live;
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
mod switch;
|
||||
@@ -70,6 +77,8 @@ pub use connection::{
|
||||
CONNECTION_FILE, Connection, PROBE_TIMEOUT, TOKEN_FILE, probe, read_connection, remove_connection, remove_stale_connection, write_connection,
|
||||
};
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
pub use folders::{AgentFolders, DEFAULT_FOLDER_PARENTS, FOLDERS_TOOL, FOLDERS_TOOL_DESCRIPTION, default_folder, folders_answer, folders_tool};
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
pub use live::{
|
||||
ConnectFn, Consent, ConsentFn, HeadlessFn, HeadlessFolders, LAUNCH_POLL, LAUNCH_TIMEOUT, LaunchFn, Live, LiveConfig, Route, Window, find_window,
|
||||
launcher,
|
||||
|
||||
@@ -201,6 +201,8 @@ fn config(dir: &Path, consent: Consent, made: &Arc<Made>) -> LiveConfig<Window,
|
||||
},
|
||||
);
|
||||
cfg.poll = Duration::from_millis(5);
|
||||
// No folder in the real Documents from a test; tests that want one set their own.
|
||||
cfg.default_folder = None;
|
||||
cfg
|
||||
}
|
||||
|
||||
@@ -297,6 +299,34 @@ fn allowed_and_closed_runs_headless_with_the_apps_folders_unless_the_command_giv
|
||||
assert_eq!((f.read, f.write), (paths(&["/app-in"]), Some(PathBuf::from("/cli-out"))));
|
||||
}
|
||||
|
||||
/// Agents allowed, app closed, "headless", no folders set: the app's default agent folder for
|
||||
/// both directions, created; the command's folders still win, and agents the person didn't let in
|
||||
/// never get the default.
|
||||
#[test]
|
||||
fn empty_folder_settings_fall_back_to_the_default_agent_folder() {
|
||||
let dir = temp_dir("default-folder");
|
||||
let default = dir.path().join("Agents").join("Test");
|
||||
let made = Arc::new(Made::default());
|
||||
let empty = |allowed| Consent::new(allowed, settings(WhenAppClosed::Headless, "", ""));
|
||||
|
||||
let mut cfg = config(dir.path(), empty(true), &made);
|
||||
cfg.default_folder = Some(default.clone());
|
||||
let f = headless_folders(TestLive::new(cfg).resolve());
|
||||
assert_eq!((f.read, f.write), (vec![default.clone()], Some(default.clone())));
|
||||
assert!(default.is_dir(), "the default folder is created");
|
||||
|
||||
let mut cfg = config(dir.path(), empty(true), &made);
|
||||
cfg.default_folder = Some(default.clone());
|
||||
cfg.write_root = Some(PathBuf::from("/cli-out"));
|
||||
let f = headless_folders(TestLive::new(cfg).resolve());
|
||||
assert_eq!((f.read, f.write), (vec![default.clone()], Some(PathBuf::from("/cli-out"))));
|
||||
|
||||
let mut cfg = config(dir.path(), empty(false), &made);
|
||||
cfg.default_folder = Some(default);
|
||||
let f = headless_folders(TestLive::new(cfg).resolve());
|
||||
assert_eq!((f.read, f.write), (Vec::<PathBuf>::new(), None));
|
||||
}
|
||||
|
||||
/// Agents allowed, app closed, "error": the call fails with words that name the app; the command's
|
||||
/// choice wins over the app's.
|
||||
#[test]
|
||||
|
||||
Reference in new issue
Block a user