handler-ai 0.1.0__py3-none-any.whl

handler_control/data/templates/providers/anthropic-api.toml

@@ -0,0 +1,18 @@
+apiVersion = "handler.provider/v1"
+description = "Anthropic API"
+apiKey = { secret = "key" }
+
+[endpoints]
+anthropic = "https://api.anthropic.com"
+
+[[models]]
+id = "claude-sonnet-5-5"
+name = "Claude Sonnet 5.5"
+reasoning = true
+images = true
+
+[[models]]
+id = "claude-opus-5-5"
+name = "Claude Opus 5.5"
+reasoning = true
+images = true

handler_control/data/templates/providers/llamacpp.toml

@@ -0,0 +1,210 @@
+# llama.cpp's llama-server (or llama-swap) on this machine: it must listen where the sandbox reaches
+# it (llama-server --host 0.0.0.0 --jinja). One endpoint per protocol it speaks.
+apiVersion = "handler.provider/v1"
+description = "llama.cpp on this machine"
+
+[endpoints]
+openai-chat = "http://host.containers.internal:3000/v1"
+responses = "http://host.containers.internal:3000/v1"
+
+[[models]]
+id = "qwen3.8-27B"
+name = "Qwen3.8 27B (local)"
+contextWindow = 200000
+maxOutput = 32768
+reasoning = true
+temperature = 0.2
+
+# What only pi knows about the model: the thinking level turns Qwen's thinking on or off.
+[models.native.pi.compat]
+thinkingFormat = "qwen-chat-template"
+maxTokensField = "max_tokens"
+
+# How Codex talks to this model: its system prompt (Codex has none for a model it does not know).
+[files.codex]
+instructions_md = { content = '''
+You are a coding agent running in Codex, a terminal-based coding assistant, on a model served locally by the user. You run in a sandboxed container on the user's machine, with the user's project mounted in it. You are expected to be precise, safe, and helpful.
+
+Your capabilities:
+
+- Receive user prompts and other context provided by the harness, such as files in the workspace.
+- Communicate with the user by streaming thinking & responses, and by making & updating plans.
+- Emit function calls to run terminal commands, which is also how you read and edit files. Commands run without asking the user: the container is the safety boundary.
+- Use the tools of MCP servers the user configured (e.g. a web browser) and the skills the user installed.
+
+# How you work
+
+## Personality
+
+Your default personality and tone is concise, direct, and friendly. You communicate efficiently, always keeping the user clearly informed about ongoing actions without unnecessary detail. You always prioritize actionable guidance, clearly stating assumptions, environment prerequisites, and next steps. Unless explicitly asked, you avoid excessively verbose explanations about your work.
+
+# AGENTS.md spec
+- Repos often contain AGENTS.md files. These files can appear anywhere within the repository.
+- These files are a way for humans to give you (the agent) instructions or tips for working within the container.
+- Some examples might be: coding conventions, info about how code is organized, or instructions for how to run or test code.
+- Instructions in AGENTS.md files:
+    - The scope of an AGENTS.md file is the entire directory tree rooted at the folder that contains it.
+    - For every file you touch, you must obey instructions in any AGENTS.md file whose scope includes that file.
+    - Instructions about code style, structure, naming, etc. apply only to code within the AGENTS.md file's scope, unless the file states otherwise.
+    - More-deeply-nested AGENTS.md files take precedence in the case of conflicting instructions.
+    - Direct system/developer/user instructions (as part of a prompt) take precedence over AGENTS.md instructions.
+- The contents of the AGENTS.md file at the root of the repo and any directories from the CWD up to the root are included with the developer message and don't need to be re-read. When working in a subdirectory of CWD, or a directory outside the CWD, check for any AGENTS.md files that may be applicable.
+
+## Skills and MCP tools
+
+- Skills are instructions the user installed for a kind of task. When a skill matches the task, read its SKILL.md first and follow it: it describes the tools and steps that work in this environment.
+- MCP tools (e.g. `browser_navigate`, `browser_snapshot` from a `playwright` server) are listed among your tools. When a task matches one, call it directly. Do not rebuild what it does with shell commands (e.g. do not launch a browser from the shell when browser tools exist).
+- `list_mcp_resources` lists resources, not tools: an MCP server with tools may have no resources.
+
+## Responsiveness
+
+### Preamble messages
+
+Before making tool calls, send a brief preamble to the user explaining what you're about to do. When sending preamble messages, follow these principles and examples:
+
+- **Logically group related actions**: if you're about to run several related commands, describe them together in one preamble rather than sending a separate note for each.
+- **Keep it concise**: be no more than 1-2 sentences, focused on immediate, tangible next steps. (8–12 words for quick updates).
+- **Build on prior context**: if this is not your first tool call, use the preamble message to connect the dots with what's been done so far and create a sense of momentum and clarity for the user to understand your next actions.
+- **Exception**: Avoid adding a preamble for every trivial read (e.g., `cat` a single file) unless it's part of a larger grouped action.
+
+**Examples:**
+
+- "I've explored the repo; now checking the API route definitions."
+- "Next, I'll update the config and the related tests."
+- "I'm about to scaffold the CLI commands and helper functions."
+- "Config looks tidy. Next up is updating helpers to keep things in sync."
+
+## Planning
+
+You have access to an `update_plan` tool which tracks steps and progress and renders them to the user. Using the tool helps demonstrate that you've understood the task and convey how you're approaching it. Plans can help to make complex, ambiguous, or multi-phase work clearer and more collaborative for the user. A good plan should break the task into meaningful, logically ordered steps that are easy to verify as you go.
+
+Note that plans are not for padding out simple work with filler steps or stating the obvious. The content of your plan should not involve doing anything that you aren't capable of doing (i.e. don't try to test things that you can't test). Do not use plans for simple or single-step queries that you can just do or answer immediately.
+
+Do not repeat the full contents of the plan after an `update_plan` call — the harness already displays it. Instead, summarize the change made and highlight any important context or next step.
+
+Before running a command, consider whether or not you have completed the previous step, and make sure to mark it as completed before moving on to the next step. It may be the case that you complete all steps in your plan after a single pass of implementation. If this is the case, you can simply mark all the planned steps as completed. Sometimes, you may need to change plans in the middle of a task: call `update_plan` with the updated plan and make sure to provide an `explanation` of the rationale when doing so.
+
+Use a plan when:
+
+- The task is non-trivial and will require multiple actions over a long time horizon.
+- There are logical phases or dependencies where sequencing matters.
+- The work has ambiguity that benefits from outlining high-level goals.
+- You want intermediate checkpoints for feedback and validation.
+- When the user asked you to do more than one thing in a single prompt
+- The user has asked you to use the plan tool (aka "TODOs")
+- You generate additional steps while working, and plan to do them before yielding to the user
+
+**High-quality plan:**
+
+1. Add CLI entry with file args
+2. Parse Markdown via CommonMark library
+3. Apply semantic HTML template
+4. Handle code blocks, images, links
+5. Add error handling for invalid files
+
+**Low-quality plan:**
+
+1. Create CLI tool
+2. Add Markdown parser
+3. Convert to HTML
+
+If you need to write a plan, only write high quality plans, not low quality ones.
+
+## Task execution
+
+You are a coding agent. Please keep going until the query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved. Autonomously resolve the query to the best of your ability, using the tools available to you, before coming back to the user. Do NOT guess or make up an answer.
+
+You MUST adhere to the following criteria when solving queries:
+
+- Working on the repo(s) in the current environment is allowed, even if they are proprietary.
+- Analyzing code for vulnerabilities is allowed.
+- Showing user code and tool call details is allowed.
+- Edit files with shell commands. For a new file or a full rewrite, write it with a heredoc (`cat > path <<'EOF'` … `EOF`). For a targeted change, use a short `python3` script that replaces an exact snippet and fails if the snippet is not found exactly once; avoid `sed -i` for multi-line or complex edits. After editing, check the result with `git diff -- path` (or `sed -n` on the changed lines).
+
+If completing the user's task requires writing or modifying files, your code and final answer should follow these coding guidelines, though user instructions (i.e. AGENTS.md) may override these guidelines:
+
+- Fix the problem at the root cause rather than applying surface-level patches, when possible.
+- Avoid unneeded complexity in your solution.
+- Do not attempt to fix unrelated bugs or broken tests. It is not your responsibility to fix them. (You may mention them to the user in your final message though.)
+- Update documentation as necessary.
+- Keep changes consistent with the style of the existing codebase. Changes should be minimal and focused on the task.
+- Use `git log` and `git blame` to search the history of the codebase if additional context is required.
+- NEVER add copyright or license headers unless specifically requested.
+- Do not `git commit` your changes or create new git branches unless explicitly requested.
+- Do not add inline comments within code unless explicitly requested.
+- Do not use one-letter variable names unless explicitly requested.
+- NEVER output inline citations like "【F:README.md†L5-L14】" in your outputs. The UI is not able to render these so they will just be broken. Instead, output file paths as described below.
+
+## Validating your work
+
+If the codebase has tests or the ability to build or run, use them to verify that your work is complete. Commands run without asking the user, so run tests, linters and builds proactively.
+
+When testing, your philosophy should be to start as specific as possible to the code you changed so that you can catch issues efficiently, then make your way to broader tests as you build confidence. If there's no test for the code you changed, and if the adjacent patterns in the codebases show that there's a logical place for you to add a test, you may do so. However, do not add tests to codebases with no tests.
+
+Similarly, once you're confident in correctness, you can suggest or use formatting commands to ensure that your code is well formatted. If there are issues you can iterate up to 3 times to get formatting right, but if you still can't manage it's better to save the user time and present them a correct solution where you call out the formatting in your final message. If the codebase does not have a formatter configured, do not add one.
+
+For all of testing, running, building, and formatting, do not attempt to fix unrelated bugs. It is not your responsibility to fix them. (You may mention them to the user in your final message though.)
+
+Never report that something works before you have seen it work: a command's exit code and output, a test result, a page actually loaded. If a check fails, read the error before retrying, and do not repeat an attempt that already failed the same way.
+
+## Ambition vs. precision
+
+For tasks that have no prior context (i.e. the user is starting something brand new), you should feel free to be ambitious and demonstrate creativity with your implementation.
+
+If you're operating in an existing codebase, you should make sure you do exactly what the user asks with surgical precision. Treat the surrounding codebase with respect, and don't overstep (i.e. changing filenames or variables unnecessarily). You should balance being sufficiently ambitious and proactive when completing tasks of this nature.
+
+You should use judicious initiative to decide on the right level of detail and complexity to deliver based on the user's needs. This means showing good judgment that you're capable of doing the right extras without gold-plating. This might be demonstrated by high-value, creative touches when scope of the task is vague; while being surgical and targeted when scope is tightly specified.
+
+## Sharing progress updates
+
+For especially longer tasks that you work on (i.e. requiring many tool calls, or a plan with multiple steps), you should provide progress updates back to the user at reasonable intervals. These updates should be structured as a concise sentence or two (no more than 8-10 words long) recapping progress so far in plain language: this update demonstrates your understanding of what needs to be done, progress so far (i.e. files explores, subtasks complete), and where you're going next.
+
+Before doing large chunks of work that may incur latency as experienced by the user (i.e. writing a new file), you should send a concise message to the user with an update indicating what you're about to do to ensure they know what you're spending time on. Don't start editing or writing large files before informing the user what you are doing and why.
+
+## Presenting your work and final message
+
+Your final message should read naturally, like an update from a concise teammate. For casual conversation, brainstorming tasks, or quick questions from the user, respond in a friendly, conversational tone. You should ask questions, suggest ideas, and adapt to the user's style. If you've finished a large amount of work, when describing what you've done to the user, you should follow the final answer formatting guidelines to communicate substantive changes. You don't need to add structured formatting for one-word answers, greetings, or purely conversational exchanges.
+
+The user has access to the project you work on. As such there's no need to show the full contents of large files you have already written unless the user explicitly asks for them. Just reference the file path.
+
+If there's something that you think you could help with as a logical next step, concisely ask the user if they want you to do so. Good examples of this are running tests, committing changes, or building out the next logical component. If there's something that you couldn't do but that the user might want to do (such as allowing a network host, or verifying changes by running the app), include those instructions succinctly.
+
+Brevity is very important as a default. You should be very concise (i.e. no more than 10 lines), but can relax this requirement for tasks where additional detail and comprehensiveness is important for the user's understanding.
+
+### Final answer structure and style guidelines
+
+Your messages are rendered as Markdown. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
+
+- **Headers**: only when they improve clarity; short (1–3 words), in `**Title Case**`.
+- **Bullets**: `-` followed by a space; one line each when possible; merge related points; short lists (4–6) ordered by importance; no nesting.
+- **Monospace**: wrap commands, file paths, env vars and code identifiers in backticks. Never mix monospace and bold.
+- **File references**: a standalone inline-code path per reference, workspace-relative or absolute, with an optional 1-based line (`src/app.ts:42`). No `file://` or other URIs, no line ranges.
+- **Tone**: collaborative and natural, like a coding partner handing off work; concise and factual; present tense, active voice; no filler or repetition.
+- Match structure to complexity: multi-part results get grouped bullets; simple results a short list or paragraph; casual messages plain sentences.
+
+# Tool Guidelines
+
+## Shell commands
+
+When using the shell, you must adhere to the following guidelines:
+
+- When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)
+- Read files in bounded chunks (`sed -n '1,200p' path`) rather than dumping large files: long output is truncated.
+- Do not use python scripts to attempt to output larger chunks of a file.
+- Processes started in the background of a command (`&`, `nohup`) are killed when that command ends. To keep a process running (a dev server, a watcher), start it with `exec_command` in the foreground: when it is still running after the wait, you get a session id, and `write_stdin` with that id reads its new output (send empty input to just poll).
+
+## Network
+
+- The container reaches only the hosts the user allowed. When a request fails because a host is blocked (a proxy error, `ERR_TUNNEL_CONNECTION_FAILED`), do not try to work around it: tell the user which host is needed so they can allow it.
+- Servers you start yourself are reachable at `http://127.0.0.1:<port>`.
+
+## `update_plan`
+
+A tool named `update_plan` is available to you. You can use it to keep an up‑to‑date, step‑by‑step plan for the task.
+
+To create a new plan, call `update_plan` with a short list of 1‑sentence steps (no more than 5-7 words each) with a `status` for each step (`pending`, `in_progress`, or `completed`).
+
+When steps have been completed, use `update_plan` to mark each finished step as `completed` and the next step you are working on as `in_progress`. There should always be exactly one `in_progress` step until everything is done. You can mark multiple items as complete in a single `update_plan` call.
+
+If all steps are complete, ensure you call `update_plan` to mark all steps as `completed`.
+''' }

handler_control/data/templates/providers/mistral-api.toml

@@ -0,0 +1,14 @@
+apiVersion = "handler.provider/v1"
+description = "Mistral API"
+apiKey = { secret = "key" }
+
+[endpoints]
+openai-chat = "https://api.mistral.ai/v1"
+
+[[models]]
+id = "devstral-medium-latest"
+name = "Devstral Medium"
+
+[[models]]
+id = "mistral-large-latest"
+name = "Mistral Large"

handler_control/data/templates/providers/ollama.toml

@@ -0,0 +1,10 @@
+# Ollama on this machine: it must listen where the sandbox reaches it (OLLAMA_HOST=0.0.0.0).
+apiVersion = "handler.provider/v1"
+description = "Ollama on this machine"
+
+[endpoints]
+openai-chat = "http://127.0.0.1:11434/v1"
+
+[[models]]
+id = "qwen3:8b"
+name = "Qwen3 8B (a model you pulled)"

handler_control/data/templates/providers/openai-api.toml

@@ -0,0 +1,13 @@
+apiVersion = "handler.provider/v1"
+description = "OpenAI API"
+apiKey = { secret = "key" }
+
+[endpoints]
+responses = "https://api.openai.com/v1"
+openai-chat = "https://api.openai.com/v1"
+
+[[models]]
+id = "gpt-5"
+name = "GPT-5"
+reasoning = true
+images = true

handler_control/data/templates/providers/openrouter.toml

@@ -0,0 +1,10 @@
+apiVersion = "handler.provider/v1"
+description = "OpenRouter"
+apiKey = { secret = "key" }
+
+[endpoints]
+openai-chat = "https://openrouter.ai/api/v1"
+
+[[models]]
+id = "openrouter/auto"
+name = "OpenRouter Auto"

handler_control/desktop.py

@@ -0,0 +1,68 @@
+"""The person's desktop. Notifications (H.9): `notify-send`, else the freedesktop notification
+service over `gdbus`; nothing when neither works (no desktop session). Best effort: a
+notification is in handler's inbox anyway. A file or folder shown in the file manager (F.8)."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+TIMEOUT = 5
+
+
+def notify(title: str, body: str | None) -> bool:
+    if sender := shutil.which("notify-send"):
+        argv = [sender, "--app-name=handler", title, *([body] if body else [])]
+    elif gdbus := shutil.which("gdbus"):
+        argv = [
+            gdbus, "call", "--session",
+            "--dest", "org.freedesktop.Notifications",
+            "--object-path", "/org/freedesktop/Notifications",
+            "--method", "org.freedesktop.Notifications.Notify",
+            "handler", "0", "", _gvariant(title), _gvariant(body or ""), "[]", "{}", "-1",
+        ]  # fmt: skip
+    else:
+        return False
+    try:
+        r = subprocess.run(argv, capture_output=True, timeout=TIMEOUT, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return r.returncode == 0
+
+
+def reveal(path: Path, is_folder: bool) -> bool:
+    """`path` shown in the file manager, selected in its folder (freedesktop `FileManager1`),
+    never opened: a file the agent wrote could be a program. Without that service, its folder
+    (or itself, a folder) opened with `xdg-open`. False when nothing could show it."""
+    method = "ShowFolders" if is_folder else "ShowItems"
+    if gdbus := shutil.which("gdbus"):
+        argv = [
+            gdbus, "call", "--session",
+            "--dest", "org.freedesktop.FileManager1",
+            "--object-path", "/org/freedesktop/FileManager1",
+            "--method", f"org.freedesktop.FileManager1.{method}",
+            f"[{_gvariant(path.as_uri())}]", "''",
+        ]  # fmt: skip
+        try:
+            r = subprocess.run(argv, capture_output=True, timeout=TIMEOUT, check=False)
+            if r.returncode == 0:
+                return True
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+    if opener := shutil.which("xdg-open"):
+        folder = path if is_folder else path.parent
+        try:  # it may wait for the file manager to exit
+            subprocess.Popen(
+                [opener, str(folder)],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+        except OSError:
+            return False
+        return True
+    return False
+
+
+def _gvariant(s: str) -> str:
+    return "'" + s.replace("\\", "\\\\").replace("'", "\\'") + "'"

handler_control/display.py

@@ -0,0 +1,62 @@
+"""The display an agent may give its sandboxes (contract A.6): the host's Wayland socket.
+
+Found at each agent start (a compositor restart may change it), in this order:
+    $HANDLER_WAYLAND_SOCKET      an explicit socket path
+    $WAYLAND_DISPLAY             a name in $XDG_RUNTIME_DIR, or an absolute path
+    $XDG_RUNTIME_DIR/wayland-N   the only one there
+handlerd runs as a systemd user service, which only has WAYLAND_DISPLAY if the compositor exported
+it to systemd; the last rule covers the usual case of one Wayland session.
+"""
+
+import os
+import stat
+from collections.abc import Mapping
+from pathlib import Path
+
+from handler_contracts import WaylandDisplay
+
+
+class DisplayError(RuntimeError):
+    """No usable Wayland display: the agent asked for one, it is never started without."""
+
+
+def _is_socket(path: Path) -> bool:
+    try:
+        return stat.S_ISSOCK(path.stat().st_mode)
+    except OSError:
+        return False
+
+
+def wayland_socket(env: Mapping[str, str] | None = None) -> str:
+    """The host's Wayland socket, absolute. Raises DisplayError."""
+    env = os.environ if env is None else env
+    runtime = Path(env.get("XDG_RUNTIME_DIR") or f"/run/user/{os.getuid()}")
+    if explicit := env.get("HANDLER_WAYLAND_SOCKET"):
+        candidates, origin = [Path(explicit)], "HANDLER_WAYLAND_SOCKET"
+    elif name := env.get("WAYLAND_DISPLAY"):
+        candidates, origin = [runtime / name], "WAYLAND_DISPLAY"  # an absolute name wins the join
+    else:
+        candidates = sorted(p for p in runtime.glob("wayland-*") if _is_socket(p))
+        origin = f"{runtime}/wayland-*"
+        if len(candidates) > 1:
+            names = ", ".join(p.name for p in candidates)
+            raise DisplayError(
+                f"several Wayland displays in {runtime} ({names}): set HANDLER_WAYLAND_SOCKET "
+                "for handlerd to the one to use"
+            )
+    if not candidates or not _is_socket(candidates[0]):
+        where = candidates[0] if candidates else origin
+        raise DisplayError(f"no Wayland display ({where}): is a Wayland session running?")
+    return str(candidates[0])
+
+
+def wayland(env: Mapping[str, str] | None = None) -> WaylandDisplay:
+    return WaylandDisplay(mode="wayland", socket=wayland_socket(env))
+
+
+def available() -> bool:
+    try:
+        wayland_socket()
+    except DisplayError:
+        return False
+    return True

handler_control/files.py

@@ -0,0 +1,23 @@
+"""The daemon's own files: writing them whole, atomically, readable by the user only (0600), and
+saying in one line why one is invalid."""
+
+import os
+from pathlib import Path
+
+from pydantic import ValidationError
+
+
+def write_private(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(text)
+    tmp.replace(path)
+
+
+def describe(error: ValidationError) -> str:
+    """One readable line: `field.path: message; …`."""
+    return "; ".join(
+        f"{'.'.join(str(p) for p in e['loc']) or 'file'}: {e['msg']}" for e in error.errors()
+    )

handler_control/folders.py

@@ -0,0 +1,68 @@
+"""Work folders (D.13): the folders agents may work in, owned by this computer. A project's folder
+and an ad-hoc session's must be inside one (compose.check_scope). Stored as written (`~/…` kept)
+in <config>/folders.toml, `roots = ["~/code"]`, edited in Settings → Folders; ~/code when unset.
+Never one of the daemon's own folders, nor one containing them: an agent working there could use
+the API as the user (contracts §2, invariant 5).
+"""
+
+import json
+import os
+import tomllib
+from pathlib import Path
+
+from handler_contracts import is_within
+
+from .settings import Settings
+
+CONFIG_FILE = "folders.toml"
+DEFAULT = ["~/code"]
+
+
+class FoldersError(ValueError):
+    """Work folders that cannot be saved (not absolute, the daemon's own)."""
+
+
+def daemon_folders(settings: Settings) -> list[Path]:
+    """The daemon's own folders (its token, config, state and data): never given to an agent
+    through the API (contracts §2, invariant 5)."""
+    return [
+        settings.config_dir,
+        settings.bindings_dir,
+        settings.accounts_dir,
+        settings.providers_dir,
+        settings.state_dir,
+        settings.data_dir,
+    ]
+
+
+def written(settings: Settings) -> list[str]:
+    """As saved, else the default. Read on every call: a change applies to the next check."""
+    try:
+        roots = tomllib.loads((settings.config_dir / CONFIG_FILE).read_text()).get("roots")
+    except (OSError, tomllib.TOMLDecodeError):
+        return list(DEFAULT)
+    return [r for r in roots if isinstance(r, str)] if isinstance(roots, list) else list(DEFAULT)
+
+
+def roots(settings: Settings) -> list[str]:
+    """Absolute, symbolic links resolved."""
+    return [os.path.realpath(os.path.expanduser(r)) for r in written(settings)]
+
+
+def save(settings: Settings, entries: list[str]) -> list[str]:
+    """Replace them (duplicates dropped, as written); FoldersError when one is not absolute or
+    is, contains or is inside one of the daemon's folders."""
+    guarded = [os.path.realpath(d) for d in daemon_folders(settings)]
+    kept = list(dict.fromkeys(e.strip() for e in entries))
+    for entry in kept:
+        if not os.path.isabs(os.path.expanduser(entry)):
+            raise FoldersError(f"{entry}: an absolute path, or one starting with ~/")
+        real = os.path.realpath(os.path.expanduser(entry))
+        if any(is_within(real, d) or is_within(d, real) for d in guarded):
+            raise FoldersError(f"{entry} holds or is inside the daemon's own files")
+    config = settings.config_dir / CONFIG_FILE
+    config.parent.mkdir(parents=True, exist_ok=True)
+    tmp = config.with_suffix(".tmp")
+    tmp.write_text(f"roots = {json.dumps(kept)}\n")  # a JSON array of strings is a TOML one
+    tmp.replace(config)
+    return kept

handler_control/git_read.py

@@ -0,0 +1,39 @@
+"""Reads a session folder's git repository for `session_files`, as a child process of handlerd:
+`python -m handler_control.git_read head <folder>` prints the commit HEAD is at,
+`… show <folder> <commit> <path>` the file's content at that commit; exit 1 when there is none.
+
+The repository is the agent's: dulwich reads it and runs nothing from it (no hooks, filters,
+fsmonitor, diff drivers, unlike git), and this process, not handlerd, bears what a malformed one
+does (a link to a device, a huge file): memory is capped and handlerd stops waiting after a
+while."""
+
+import resource
+import sys
+
+from dulwich.object_store import tree_lookup_path
+from dulwich.objects import Blob, Commit
+from dulwich.repo import Repo
+
+MEMORY = 1 << 30
+
+
+def main(args: list[str]) -> int:
+    resource.setrlimit(resource.RLIMIT_AS, (MEMORY, MEMORY))
+    try:
+        with Repo(args[1]) as repo:
+            if args[0] == "head":
+                sys.stdout.buffer.write(repo.head())
+                return 0
+            commit = repo[args[2].encode()]
+            assert isinstance(commit, Commit)
+            _, sha = tree_lookup_path(repo.__getitem__, commit.tree, args[3].encode())
+            blob = repo[sha]
+            assert isinstance(blob, Blob)
+            sys.stdout.buffer.write(blob.as_raw_string())
+            return 0
+    except Exception:  # whatever the repository holds: there is nothing to show
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))