clearbox 0.2.1__tar.gz → 0.2.2__tar.gz

{clearbox-0.2.1 → clearbox-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clearbox
-Version: 0.2.1
+Version: 0.2.2
 Summary: Observable, reviewable agent work: DAG plans over MCP, executed node by node and watched live
 Project-URL: Homepage, https://github.com/KaiHabermann/Clearbox
 Project-URL: Repository, https://github.com/KaiHabermann/Clearbox
@@ -576,7 +576,7 @@ clearbox --db $HOME\.clearbox\vc.db --workdir $HOME\.clearbox\workspace
 ```
 
 The repo contains a `.mcp.json`, so Claude Code started in this folder offers the `clearbox`
-server automatically. Create plans with `working_directory` set to the repo path so built-in agents
+server automatically. Plans take `working_directory`, so point it at the repo path and built-in agents
 work on the code. To pick up the agents' changes, stop the service and run
 `uv tool install --force .` again.
 
@@ -595,8 +595,8 @@ and every later plan can use it. Two things worth knowing when a plan builds Cle
 | Flag | Env | Default |
 | --- | --- | --- |
 | `--host`, `--port` | `CLEARBOX_HOST`, `CLEARBOX_PORT` | `127.0.0.1`, `8765` |
-| `--db` | `CLEARBOX_DB` | `clearbox.db` |
-| `--workdir` | `CLEARBOX_WORKDIR` | `workspace` |
+| `--db` | `CLEARBOX_DB` | `<data dir>/clearbox.db` |
+| `--workdir` | `CLEARBOX_WORKDIR` | `<data dir>/workspace` |
 | `--max-concurrency` | `CLEARBOX_MAX_CONCURRENCY` | `3` |
 | `--permission-mode` | `CLEARBOX_PERMISSION_MODE` | `acceptEdits` |
 | `--model` | `CLEARBOX_MODEL` | SDK default |
@@ -653,6 +653,25 @@ tests/test_mixed_run.py     per-node agents and max_parallel in a real run
 tests/test_openai_harness.py  the agent loop against tests/fake_openai.py (no network, no DB)
 ```
 
+## Where Clearbox keeps its data
+
+The database and the fallback workspace live in the platform's data directory:
+
+| OS | path |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\clearbox\` |
+| macOS | `~/Library/Application Support/clearbox/` |
+| Linux | `$XDG_DATA_HOME/clearbox/`, else `~/.local/share/clearbox/` |
+
+`--db` / `CLEARBOX_DB` and `--workdir` / `CLEARBOX_WORKDIR` override both. Before 0.2.2 these
+defaulted to `clearbox.db` and `workspace/` relative to the current directory, so launching from
+two folders gave you two unrelated databases; a `clearbox.db` already sitting in the directory you
+start from is still used, and the banner says so.
+
+Every top-level plan must name its own `working_directory` -- the directory its agents work in,
+normally a repository. Subplans inherit it. Two plans with overlapping directories cannot run at
+the same time, since file-conflict locking only orders nodes within one plan tree.
+
 ## Releasing
 
 The git tag is the trigger and the single source of truth. Bump the version, tag it, push:

{clearbox-0.2.1 → clearbox-0.2.2}/README.md

@@ -545,7 +545,7 @@ clearbox --db $HOME\.clearbox\vc.db --workdir $HOME\.clearbox\workspace
 ```
 
 The repo contains a `.mcp.json`, so Claude Code started in this folder offers the `clearbox`
-server automatically. Create plans with `working_directory` set to the repo path so built-in agents
+server automatically. Plans take `working_directory`, so point it at the repo path and built-in agents
 work on the code. To pick up the agents' changes, stop the service and run
 `uv tool install --force .` again.
 
@@ -564,8 +564,8 @@ and every later plan can use it. Two things worth knowing when a plan builds Cle
 | Flag | Env | Default |
 | --- | --- | --- |
 | `--host`, `--port` | `CLEARBOX_HOST`, `CLEARBOX_PORT` | `127.0.0.1`, `8765` |
-| `--db` | `CLEARBOX_DB` | `clearbox.db` |
-| `--workdir` | `CLEARBOX_WORKDIR` | `workspace` |
+| `--db` | `CLEARBOX_DB` | `<data dir>/clearbox.db` |
+| `--workdir` | `CLEARBOX_WORKDIR` | `<data dir>/workspace` |
 | `--max-concurrency` | `CLEARBOX_MAX_CONCURRENCY` | `3` |
 | `--permission-mode` | `CLEARBOX_PERMISSION_MODE` | `acceptEdits` |
 | `--model` | `CLEARBOX_MODEL` | SDK default |
@@ -622,6 +622,25 @@ tests/test_mixed_run.py     per-node agents and max_parallel in a real run
 tests/test_openai_harness.py  the agent loop against tests/fake_openai.py (no network, no DB)
 ```
 
+## Where Clearbox keeps its data
+
+The database and the fallback workspace live in the platform's data directory:
+
+| OS | path |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\clearbox\` |
+| macOS | `~/Library/Application Support/clearbox/` |
+| Linux | `$XDG_DATA_HOME/clearbox/`, else `~/.local/share/clearbox/` |
+
+`--db` / `CLEARBOX_DB` and `--workdir` / `CLEARBOX_WORKDIR` override both. Before 0.2.2 these
+defaulted to `clearbox.db` and `workspace/` relative to the current directory, so launching from
+two folders gave you two unrelated databases; a `clearbox.db` already sitting in the directory you
+start from is still used, and the banner says so.
+
+Every top-level plan must name its own `working_directory` -- the directory its agents work in,
+normally a repository. Subplans inherit it. Two plans with overlapping directories cannot run at
+the same time, since file-conflict locking only orders nodes within one plan tree.
+
 ## Releasing
 
 The git tag is the trigger and the single source of truth. Bump the version, tag it, push:

{clearbox-0.2.1 → clearbox-0.2.2}/clearbox/__main__.py

@@ -13,14 +13,39 @@ from .app import Settings, create_app
 from .bootstrap import StartupError
 
 
+LEGACY_DB = "clearbox.db"   # the pre-0.2.2 default: relative to wherever you launched
+
+
+def default_data_dir() -> str:
+    """Where an installed clearbox keeps its database and workspaces.
+
+    The old defaults were relative (``clearbox.db``, ``workspace``), so running the
+    command from two directories silently gave you two unrelated databases and left
+    stray files in whatever folder you happened to be in.
+    """
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser(r"~\AppData\Local")
+    elif sys.platform == "darwin":
+        base = os.path.expanduser("~/Library/Application Support")
+    else:
+        base = os.environ.get("XDG_DATA_HOME") or os.path.expanduser("~/.local/share")
+    return os.path.join(base, "clearbox")
+
+
 def main() -> None:
     env = os.environ.get
+    data_dir = default_data_dir()
+    # A database left in the current directory by an older version still wins, so nobody's
+    # plans disappear on upgrade. The banner says where the new default lives.
+    legacy = os.path.abspath(LEGACY_DB) if os.path.isfile(LEGACY_DB) else None
     ap = argparse.ArgumentParser(prog="clearbox", description=__doc__)
     ap.add_argument("--host", default=env("CLEARBOX_HOST", "127.0.0.1"))
     ap.add_argument("--port", type=int, default=int(env("CLEARBOX_PORT", "8765")))
-    ap.add_argument("--db", default=env("CLEARBOX_DB", "clearbox.db"), help="SQLite file")
-    ap.add_argument("--workdir", default=env("CLEARBOX_WORKDIR", "workspace"),
-                    help="base directory; each plan's agents work in <workdir>/plan-<id>")
+    ap.add_argument("--db", default=env("CLEARBOX_DB", legacy or os.path.join(data_dir, "clearbox.db")),
+                    help=f"SQLite file (default: {os.path.join(data_dir, 'clearbox.db')})")
+    ap.add_argument("--workdir", default=env("CLEARBOX_WORKDIR", os.path.join(data_dir, "workspace")),
+                    help="fallback directory for plans created before a working directory was "
+                         "required; each such plan's agents work in <workdir>/plan-<id>")
     ap.add_argument("--mock", action="store_true", default=env("CLEARBOX_AGENT") == "mock",
                     help="use fake agents (no Claude sessions, no cost) to try out the UI")
     ap.add_argument("--mock-speed", type=float, default=1.0)
@@ -69,6 +94,10 @@ def main() -> None:
     print(f"Clearbox UI:  http://{settings.host}:{settings.port}/")
     print(f"MCP endpoint:     {settings.mcp_url}   (agents: {settings.agent})")
     print(f"Agents:           {app.state.agents_line}")
+    print(f"Database:         {os.path.abspath(settings.db)}")
+    if legacy and os.path.abspath(settings.db) == legacy:
+        print(f"                  (a clearbox.db in this folder; the default is now "
+              f"{os.path.join(data_dir, 'clearbox.db')} -- move it there, or keep passing --db)")
     # Ctrl+C must always get the port back. uvicorn waits for open connections *before* running
     # the lifespan shutdown, and /api/stream is endless, so the app has to notice the stop itself:
     # it watches server.should_exit, which is set the moment the signal arrives. The timeout is

{clearbox-0.2.1 → clearbox-0.2.2}/clearbox/mcp_tools.py

@@ -202,7 +202,9 @@ depends on it (from_node_id must finish before to_node_id starts). Execution wal
 from the roots to the leaves; independent nodes run in parallel.
 
 Building a plan:
-  1. create_plan(title, description) -> plan_id
+  1. create_plan(title, description, working_directory) -> plan_id
+     working_directory is required: the absolute path of the existing directory the plan's
+     agents work in (usually the repository). Subplans inherit it.
   2. add_node(plan_id, title, description) -> [plan_id, node_id]   (one call per piece of work)
   3. add_edge(plan_id, from_node_id, to_node_id)                   (dependencies)
   A node can itself be a small plan: create_plan(..., parent_plan_id, parent_node_id) attaches
@@ -367,9 +369,10 @@ def build_mcp(engine: Engine) -> MCPServer:
         Pass parent_plan_id and parent_node_id to make this plan the subplan of that node
         (the node then represents "do this whole small plan" instead of a single task).
 
-        working_directory (top-level plans only): absolute path of an existing directory the
-        plan's agents work in, e.g. a code repository. Defaults to <workdir>/plan-<id>.
-        Subplans always use the working directory of their top-level plan.
+        working_directory: REQUIRED for a top-level plan -- the absolute path of an existing
+        directory the plan's agents work in, e.g. a code repository. Say where the work happens
+        rather than letting agents edit files somewhere you did not choose. Subplans inherit it
+        from their top-level plan and must not pass it.
 
         max_parallel (top-level plans only): cap how many nodes of this plan's whole tree
         (including its subplans) run at once, regardless of the server's global concurrency
@@ -378,9 +381,14 @@ def build_mcp(engine: Engine) -> MCPServer:
         """
         if parent_plan_id is not None and max_parallel is not None:
             raise ToolError("max_parallel can only be set on top-level plans")
+        if parent_plan_id is None and working_directory is None:
+            raise ToolError(
+                "working_directory is required for a top-level plan: pass the absolute path of "
+                "the existing directory its agents should work in (e.g. the repository)")
         if working_directory is not None:
             if parent_plan_id is not None:
-                raise ToolError("working_directory can only be set on top-level plans")
+                raise ToolError("working_directory can only be set on top-level plans; a subplan "
+                                "uses its top-level plan's directory")
             try:
                 validate_working_directory(working_directory)
             except PlanError as e:

{clearbox-0.2.1 → clearbox-0.2.2}/examples/demo_plan.py

@@ -10,11 +10,12 @@ from __future__ import annotations
 import argparse
 import asyncio
 import json
+import tempfile
 
 from mcp.client.client import Client
 
 
-async def main(url: str, start: bool) -> None:
+async def main(url: str, start: bool, workdir: str | None = None) -> None:
     async with Client(url) as c:
         async def call(name: str, **args):
             res = await c.call_tool(name, args)
@@ -24,8 +25,11 @@ async def main(url: str, start: bool) -> None:
                 return res.structured_content.get("result", res.structured_content)
             return json.loads(res.content[0].text)
 
+        # a top-level plan must say where its agents work; a fresh temp dir by default,
+        # since this demo writes a whole little app
         plan = await call("create_plan", title="Tiny CLI todo app",
-                          description="Write a small Python command-line todo app with tests and docs.")
+                          description="Write a small Python command-line todo app with tests and docs.",
+                          working_directory=workdir or tempfile.mkdtemp(prefix="clearbox-demo-"))
         print("plan", plan)
 
         async def node(title: str, desc: str, plan_id: int = plan) -> int:
@@ -62,5 +66,6 @@ if __name__ == "__main__":
     ap = argparse.ArgumentParser()
     ap.add_argument("--url", default="http://127.0.0.1:8765/mcp")
     ap.add_argument("--start", action="store_true")
+    ap.add_argument("--dir", help="working directory for the plan (default: a fresh temp dir)")
     a = ap.parse_args()
-    asyncio.run(main(a.url, a.start))
+    asyncio.run(main(a.url, a.start, a.dir))

{clearbox-0.2.1 → clearbox-0.2.2}/examples/file_conflict_plan.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 import argparse
 import asyncio
 import json
+import tempfile
 import time
 
 from mcp.client.client import Client
@@ -37,6 +38,7 @@ async def main(a: argparse.Namespace) -> None:
         plan = await call(
             "create_plan", title="File conflict demo",
             description="Two nodes write shared.txt and must serialize; a third writes its own file freely.",
+            working_directory=getattr(a, "dir", None) or tempfile.mkdtemp(prefix="clearbox-conflict-"),
         )
         print("plan", plan)
 
@@ -86,4 +88,5 @@ if __name__ == "__main__":
     ap = argparse.ArgumentParser()
     ap.add_argument("--url", default="http://127.0.0.1:8765/mcp")
     ap.add_argument("--start", action="store_true")
+    ap.add_argument("--dir", help="working directory for the plan (default: a fresh temp dir)")
     asyncio.run(main(ap.parse_args()))

{clearbox-0.2.1 → clearbox-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clearbox"
-version = "0.2.1"
+version = "0.2.2"
 description = "Observable, reviewable agent work: DAG plans over MCP, executed node by node and watched live"
 readme = "README.md"
 requires-python = ">=3.10"

{clearbox-0.2.1 → clearbox-0.2.2}/tests/test_agents_api.py

@@ -7,11 +7,16 @@ and -- explicitly -- that no response body ever contains `api_key` or the secret
 Run:  uv run clearbox --mock      (one shell)
       uv run python tests/test_agents_api.py [http://127.0.0.1:8765]
 """
-import asyncio, json, sys, threading, time, uuid
+import asyncio, json, sys, tempfile, threading, time, uuid
 import urllib.error
 import urllib.request
 from mcp.client.client import Client
 
+# Each top-level plan needs its own working directory: it is required, and two plans
+# must not run in the same folder at once.
+def wd():
+    return tempfile.mkdtemp(prefix="cb-test-")
+
 URL = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:8765"
 SECRET = "sk-test-" + uuid.uuid4().hex
 bodies: list[str] = []  # every REST response body, scanned for leaks at the end
@@ -50,7 +55,7 @@ async def main():
             sc = r.structured_content
             return sc.get("result", sc) if sc is not None else json.loads(r.content[0].text)
 
-        p = await call("create_plan", title="Agents API")
+        p = await call("create_plan", title="Agents API", working_directory=wd())
         sp_node = (await call("add_node", plan_id=p, title="parent"))[1]
         n2 = (await call("add_node", plan_id=p, title="leaf"))[1]
         sp = await call("create_plan", title="sub", parent_plan_id=p, parent_node_id=sp_node)

{clearbox-0.2.1 → clearbox-0.2.2}/tests/test_file_conflicts.py

@@ -169,7 +169,9 @@ async def main():
 
         async def plan(title, specs, edges=(), parent=None, start=True):
             """specs: list of files lists (None = declare nothing); returns (plan_id, [node ids])."""
-            kw = {"parent_plan_id": parent[0], "parent_node_id": parent[1]} if parent else {}
+            # a top-level plan needs its own working directory; two plans must not share one
+            kw = ({"parent_plan_id": parent[0], "parent_node_id": parent[1]} if parent
+                  else {"working_directory": tempfile.mkdtemp(prefix="cb-test-")})
             pid = await call("create_plan", title=f"{title} {TAG}", **kw)
             if parent is None:
                 plans.append(pid)

{clearbox-0.2.1 → clearbox-0.2.2}/tests/test_flow.py

@@ -7,11 +7,16 @@ Scheduling with files is proven in test_file_conflicts.py.
 Run:  uv run clearbox --mock --mock-speed 20      (one shell)
       uv run python tests/test_flow.py [http://127.0.0.1:8765]
 """
-import asyncio, json, sys, time
+import asyncio, json, sys, tempfile, time
 import urllib.error
 import urllib.request
 from mcp.client.client import Client
 
+# Each top-level plan needs its own working directory: it is required, and two plans
+# must not run in the same folder at once.
+def wd():
+    return tempfile.mkdtemp(prefix="cb-test-")
+
 URL = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:8765"
 
 async def main():
@@ -24,7 +29,7 @@ async def main():
             return sc.get("result", sc) if sc is not None else json.loads(r.content[0].text)
 
         # --- cycle rejection
-        p = await call("create_plan", title="External flow")
+        p = await call("create_plan", title="External flow", working_directory=wd())
         a = (await call("add_node", plan_id=p, title="A"))[1]
         b = (await call("add_node", plan_id=p, title="B"))[1]
         cc = (await call("add_node", plan_id=p, title="C"))[1]
@@ -76,7 +81,8 @@ async def main():
         print("external flow OK")
 
         # --- builtin flow with a wide graph, wait for completion
-        q = await call("create_plan", title="Wide builtin graph", description="layout test")
+        q = await call("create_plan", title="Wide builtin graph", description="layout test",
+                       working_directory=wd())
         ids = [(await call("add_node", plan_id=q, title=f"Step {i}", description=f"do {i}"))[1] for i in range(8)]
         for x, y in [(0,1),(0,2),(0,3),(1,4),(2,4),(3,5),(4,6),(5,6),(0,6),(6,7),(1,7)]:
             await call("add_edge", plan_id=q, from_node_id=ids[x], to_node_id=ids[y])
@@ -101,7 +107,7 @@ async def main():
         fast, strong = f"flow-fast-{tag}", f"flow-strong-{tag}"
         await call("create_agent", name=fast, harness="mock", params={"speed": 20}, max_parallel=1)
         await call("create_agent", name=strong, harness="mock")
-        r = await call("create_plan", title="Agent resolution")
+        r = await call("create_plan", title="Agent resolution", working_directory=wd())
         r1 = (await call("add_node", plan_id=r, title="plain"))[1]
         r2 = (await call("add_node", plan_id=r, title="override"))[1]
         r3 = (await call("add_node", plan_id=r, title="expands"))[1]
@@ -152,7 +158,7 @@ async def main():
             except urllib.error.HTTPError as e:
                 return e.code, json.loads(e.read())
 
-        f = await call("create_plan", title="Files")
+        f = await call("create_plan", title="Files", working_directory=wd())
         f1 = (await call("add_node", plan_id=f, title="one", files=["Shared.txt", "docs/"]))[1]
         f2 = (await call("add_node", plan_id=f, title="two"))[1]
         f3 = (await call("add_node", plan_id=f, title="three", files=[".\\shared.txt"]))[1]

{clearbox-0.2.1 → clearbox-0.2.2}/tests/test_mixed_run.py

@@ -11,11 +11,16 @@ caps, not the global limit, are what holds the nodes back.
 Run:  uv run clearbox --mock      (one shell)
       uv run python tests/test_mixed_run.py [http://127.0.0.1:8765]
 """
-import asyncio, json, sys, time, uuid
+import asyncio, json, sys, tempfile, time, uuid
 import urllib.error
 import urllib.request
 from mcp.client.client import Client
 
+# Each top-level plan needs its own working directory: it is required, and two plans
+# must not run in the same folder at once.
+def wd():
+    return tempfile.mkdtemp(prefix="cb-test-")
+
 URL = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:8765"
 
 
@@ -52,7 +57,7 @@ async def build() -> tuple[int, list[int]]:
             r = await c.call_tool(name, a)
             sc = r.structured_content
             return sc.get("result", sc) if sc is not None else json.loads(r.content[0].text)
-        pid = await call("create_plan", title=f"Mixed run {tag}")
+        pid = await call("create_plan", title=f"Mixed run {tag}", working_directory=wd())
         return pid, [(await call("add_node", plan_id=pid, title=f"N{i}"))[1] for i in range(8)]
 
 

{clearbox-0.2.1 → clearbox-0.2.2}/tests/test_rework.py

@@ -13,10 +13,15 @@ edits something.
 Run:  uv run clearbox --mock      (one shell)
       uv run python tests/test_rework.py [http://127.0.0.1:8765]
 """
-import asyncio, json, sys, time, urllib.error, urllib.request
+import asyncio, json, sys, tempfile, time, urllib.error, urllib.request
 
 from mcp.client.client import Client
 
+# Each top-level plan needs its own working directory: it is required, and two plans
+# must not run in the same folder at once.
+def wd():
+    return tempfile.mkdtemp(prefix="cb-test-")
+
 URL = (sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:8765").rstrip("/")
 MARKER = "MARKER-rework-brief-must-reach-the-prompt"
 
@@ -51,7 +56,7 @@ async def main():
             sc = r.structured_content
             return sc.get("result", sc) if sc is not None else json.loads(r.content[0].text)
 
-        pid = await call("create_plan", title="Rework test")
+        pid = await call("create_plan", title="Rework test", working_directory=wd())
         a = (await call("add_node", plan_id=pid, title="A", description="first step"))[1]
         b = (await call("add_node", plan_id=pid, title="B", description="second step"))[1]
         await call("add_edge", plan_id=pid, from_node_id=a, to_node_id=b)