cloudagent-daemon 0.2.1__py3-none-any.whl

cloudagent_daemon/workspace.py

@@ -0,0 +1,441 @@
+"""Workspace: manages ~/.cloudagent/agents/<agent_id>/ directory lifecycle.
+
+Spec §6.1 directory layout:
+
+    ~/.cloudagent/agents/<agent_id>/
+      ├── MEMORY.md        (template — §6.8, created once on first registration)
+      ├── notes/
+      ├── workspace/
+      ├── .meta/
+      │   ├── identity.json            (mode 0o600)
+      │   ├── claude-mcp-config.json   (regenerated each ensure())
+      │   ├── claude-token.txt          (per-spawn, written by daemon, deleted after)
+      │   └── last-spawn.json
+      └── claude/
+
+``Workspace`` owns the directory lifecycle (create / archive).
+``AgentWorkspace`` is the per-agent handle used by ClaudeRunner (implements
+the ``AgentWorkspaceLike`` protocol from claude_runner.py).
+
+Task #118 (2026-05-12) — agent claude subprocess cwd is now decoupled
+from the metadata directory. Metadata (identity.json / mcp-config /
+last-spawn / MEMORY.md) **always** lives at
+``~/.cloudagent/agents/<agent_id>/`` so a user-chosen cwd never gets
+polluted with platform files. The cwd itself is computed via
+:func:`compute_agent_cwd` with this fallback:
+
+    agent.workspace_root                                 -- per-agent override
+      > <host.workspace_root>/<agent_id>/workspace/      -- host-level default
+      > ~/.cloudagent/agents/<agent_id>/workspace/        -- compiled-in default
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+# Task #123 (2026-05-12) — name of the per-agent override file persisted
+# under ``<metadata_root>/<agent_id>/.meta/`` so subsequent
+# ``for_agent`` calls (and daemon restarts) can rebuild the cwd without
+# requiring the caller to re-pass ``agent_workspace_root``. Single line
+# of UTF-8 text holding the absolute path; absence of the file means
+# "no per-agent override, fall back to host / platform tier".
+_AGENT_WORKSPACE_ROOT_FILENAME = "agent_workspace_root"
+
+
+def _read_persisted_agent_workspace_root(meta_dir: Path) -> str | None:
+    """Read the persisted per-agent override.
+
+    Returns the path string when present + non-empty, else ``None`` so
+    ``compute_agent_cwd`` falls back to the host / platform tier.
+    Failures (file missing, OS hiccup) collapse to ``None`` — the file
+    is a hint, not a source of truth.
+    """
+    p = meta_dir / _AGENT_WORKSPACE_ROOT_FILENAME
+    try:
+        raw = p.read_text(encoding="utf-8").strip()
+    except (FileNotFoundError, OSError):
+        return None
+    return raw or None
+
+
+def _write_persisted_agent_workspace_root(
+    meta_dir: Path, value: str | None
+) -> None:
+    """Persist or clear the per-agent override.
+
+    ``value=None`` deletes the file (cleared override) so subsequent
+    reads fall back to the host / platform tier. ``value`` non-None
+    overwrites with the absolute path string. Caller guarantees
+    ``meta_dir`` exists.
+    """
+    p = meta_dir / _AGENT_WORKSPACE_ROOT_FILENAME
+    if value is None:
+        p.unlink(missing_ok=True)
+        return
+    p.write_text(value, encoding="utf-8")
+
+
+def compute_agent_cwd(
+    agent_id: str,
+    *,
+    agent_workspace_root: str | None,
+    host_workspace_root: str | Path | None,
+    metadata_root: Path,
+) -> Path:
+    """Resolve the cwd for an agent's claude subprocess.
+
+    Fallback order (Task #118 CEO directive):
+
+      1. ``agent_workspace_root`` (per-agent absolute path; **no**
+         ``/<agent_id>/workspace/`` suffix is appended — the user's
+         choice is used verbatim so they can target the same repo for
+         multiple sessions).
+      2. ``host_workspace_root / agent_id / workspace`` (the host-level
+         default per Task #113; preserves the pre-#118 "one dir per
+         agent under a shared root" shape).
+      3. ``metadata_root / agent_id / workspace`` (compiled-in
+         ``~/.cloudagent/agents/<id>/workspace/``).
+
+    Tilde paths are expanded; relative paths are NOT accepted (the API
+    rejects them at create / patch time so they never reach the daemon).
+    """
+    if agent_workspace_root:
+        return Path(os.path.expanduser(agent_workspace_root))
+    if host_workspace_root:
+        base = Path(os.path.expanduser(str(host_workspace_root)))
+        return base / agent_id / "workspace"
+    return metadata_root / agent_id / "workspace"
+
+
+class AgentWorkspace:
+    """Per-agent workspace handle; satisfies the AgentWorkspaceLike protocol.
+
+    Task #118 (2026-05-12) split:
+
+    * ``path`` — metadata root (always ``~/.cloudagent/agents/<id>/``).
+      Holds identity.json, mcp-config, last-spawn, MEMORY.md.
+    * ``cwd`` — claude subprocess cwd. Computed via
+      :func:`compute_agent_cwd` from the host / agent overrides.
+    """
+
+    def __init__(self, path: Path, *, cwd: Path | None = None) -> None:
+        self.path = path
+        # ``cwd`` defaults to ``<path>/workspace`` so legacy callers
+        # that don't supply a cwd still get the pre-#118 behaviour.
+        self._cwd = cwd if cwd is not None else path / "workspace"
+
+    @property
+    def cwd(self) -> Path:
+        """Return the resolved cwd for the agent's claude subprocess."""
+        return self._cwd
+
+    # ------------------------------------------------------------------
+    # AgentWorkspaceLike protocol implementation
+    # ------------------------------------------------------------------
+
+    def last_session_id(self) -> str | None:
+        """Return session_id from last-spawn.json, or None."""
+        p = self.path / ".meta" / "last-spawn.json"
+        try:
+            data = json.loads(p.read_text())
+            sid = data.get("session_id")
+            return sid if isinstance(sid, str) and sid else None
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            return None
+
+    def set_last_session_id(self, sid: str) -> None:
+        """Update session_id in last-spawn.json, preserving all other fields."""
+        p = self.path / ".meta" / "last-spawn.json"
+        try:
+            data: dict[str, Any] = json.loads(p.read_text())
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            data = {}
+        data["session_id"] = sid
+        p.write_text(json.dumps(data, indent=2))
+
+    def clear_last_session_id(self) -> None:
+        """Drop a stale session_id from last-spawn.json.
+
+        1k followup — when ``claude --resume <sid>`` fails because the
+        session was never persisted (``--print`` mode does not always
+        write the session to ``~/.claude/sessions/``), the daemon must
+        clear the stored id so the next wake starts fresh. Preserves
+        the rest of the file (exit_code / stderr_tail / ts) so the
+        operator can still see why the prior wake failed.
+        """
+        p = self.path / ".meta" / "last-spawn.json"
+        try:
+            data: dict[str, Any] = json.loads(p.read_text())
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            # Nothing to clear — file missing or corrupt; either way,
+            # last_session_id() will return None going forward.
+            return
+        if data.get("session_id") is None:
+            return
+        data["session_id"] = None
+        p.write_text(json.dumps(data, indent=2))
+
+    def mcp_config_path(self) -> Path:
+        """Return path to claude-mcp-config.json."""
+        return self.path / ".meta" / "claude-mcp-config.json"
+
+    def write_last_spawn(
+        self, exit_code: int, session_id: str | None, stderr_tail: str
+    ) -> None:
+        """Write all last-spawn fields atomically (simple overwrite)."""
+        p = self.path / ".meta" / "last-spawn.json"
+        data = {
+            "exit_code": exit_code,
+            "session_id": session_id,
+            "stderr_tail": stderr_tail,
+            "ts": datetime.now(tz=timezone.utc).isoformat(),
+        }
+        p.write_text(json.dumps(data, indent=2))
+
+    def delete_token_file(self) -> None:
+        """Best-effort delete of per-spawn token file."""
+        token_path = self.path / ".meta" / "claude-token.txt"
+        token_path.unlink(missing_ok=True)
+
+    # ------------------------------------------------------------------
+    # Per-spawn current-session marker (1k hotfix)
+    # ------------------------------------------------------------------
+    #
+    # The mcp_bridge subprocess is spawned as a child of the ``claude``
+    # subprocess and has no other channel to learn the cloudagent
+    # business ``session_id`` carried by the deliver frame that triggered
+    # the wake. ClaudeRunner writes that session_id to
+    # ``.meta/current-session.txt`` BEFORE spawn and deletes it AFTER —
+    # the bridge reads the file at startup and includes the session_id
+    # in every IPC ``tool_call`` payload. Lifecycle parallels the
+    # per-spawn ``claude-token.txt`` file (spec §6.6).
+
+    def current_session_path(self) -> Path:
+        """Return the path to the per-spawn current-session marker."""
+        return self.path / ".meta" / "current-session.txt"
+
+    def write_current_session(self, session_id: str | None) -> None:
+        """Persist the current deliver's session_id for the bridge to read.
+
+        ``None`` is treated as "delete" — equivalent to
+        :meth:`delete_current_session`. The file is written with mode
+        0o600 so only the daemon-owning user can read it.
+        """
+        p = self.current_session_path()
+        if session_id is None:
+            self.delete_current_session()
+            return
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(session_id)
+        try:
+            p.chmod(0o600)
+        except OSError:
+            # On platforms / filesystems that reject chmod we still want
+            # the write to succeed — the unix socket already enforces
+            # 0o600 ownership.
+            pass
+
+    def delete_current_session(self) -> None:
+        """Best-effort delete of the per-spawn current-session marker."""
+        try:
+            self.current_session_path().unlink()
+        except FileNotFoundError:
+            pass
+
+    # ------------------------------------------------------------------
+    # Internal write helpers (called by Workspace.ensure)
+    # ------------------------------------------------------------------
+
+    def _write_identity(self, identity: dict) -> None:
+        """Write identity.json with mode 0o600."""
+        p = self.path / ".meta" / "identity.json"
+        p.write_text(json.dumps(identity, indent=2))
+        os.chmod(p, 0o600)
+
+    def _write_memory_md_template(self, identity: dict) -> None:
+        """Write MEMORY.md from spec §6.8 template (only if it does not exist)."""
+        agent_id = identity.get("agent_id", "unknown")
+        agent_name = identity.get("agent_name", agent_id)
+        role = identity.get("role", "staff")
+        reports_to = identity.get("reports_to", "(unset)")
+        workspace_slug = identity.get("workspace_slug", "default")
+
+        content = f"""# Agent Memory — {agent_name}
+
+> Auto-generated by cloudagent-daemon on first assignment.
+
+## Identity
+- Agent ID: {agent_id}
+- Role: {role}
+- Reports to: {reports_to}
+- Workspace: {workspace_slug}
+
+## Active Context
+(none yet)
+
+## Notes Index
+(none yet)
+
+## Long-term Memory
+(none yet)
+"""
+        (self.path / "MEMORY.md").write_text(content)
+
+    def _write_mcp_config(self, identity: dict) -> None:
+        """Write claude-mcp-config.json pointing to the mcp-bridge subcommand."""
+        agent_id = identity.get("agent_id", "unknown")
+        token_file = str(self.path / ".meta" / "claude-token.txt")
+        config = {
+            "mcpServers": {
+                "cloudagent": {
+                    "command": "cloudagent-daemon",
+                    "args": [
+                        "mcp-bridge",
+                        "--agent-id",
+                        agent_id,
+                        "--token-file",
+                        token_file,
+                    ],
+                }
+            }
+        }
+        self.mcp_config_path().write_text(json.dumps(config, indent=2))
+
+
+class Workspace:
+    """Manages ~/.cloudagent/agents/ — owns agent dir lifecycles.
+
+    Task #118 (2026-05-12) — ``root`` is the **metadata** root (always
+    ``~/.cloudagent/agents/`` in production; tests override). Agent cwd
+    for claude is computed separately via :func:`compute_agent_cwd`
+    using ``host_workspace_root`` (set at daemon start) + the per-agent
+    ``workspace_root`` (passed to :meth:`ensure`). Splitting these means
+    a user-chosen project directory never gets polluted with
+    ``identity.json`` / ``MEMORY.md`` / mcp-config.
+    """
+
+    DEFAULT_ROOT = Path.home() / ".cloudagent" / "agents"
+
+    @classmethod
+    def default_root_for_profile(cls, profile: str | None = None) -> Path:
+        """Workspace root for *profile* — default keeps legacy
+        ``~/.cloudagent/agents``, named profiles get
+        ``~/.cloudagent/agents-<name>``."""
+        # Lazy import keeps this module import-light for tooling that
+        # only touches AgentWorkspace.
+        from .paths import profile_workspace_root
+
+        return profile_workspace_root(profile)
+
+    def __init__(
+        self,
+        root: Path | None = None,
+        *,
+        host_workspace_root: Path | None = None,
+        profile: str | None = None,
+    ) -> None:
+        if root is not None:
+            self.root = root
+        elif profile is not None:
+            self.root = self.default_root_for_profile(profile)
+        else:
+            self.root = self.DEFAULT_ROOT
+        # Task #118 — host-level default for agent cwd (Task #113's
+        # daemon ``--workspace-root`` setting). Used as the second-tier
+        # fallback in :func:`compute_agent_cwd`. ``None`` ⇒ third tier
+        # (``self.root / <id> / workspace``) is used.
+        self.host_workspace_root = host_workspace_root
+
+    def for_agent(
+        self, agent_id: str, *, agent_workspace_root: str | None = None
+    ) -> AgentWorkspace:
+        """Return AgentWorkspace handle for agent_id (does not create dirs).
+
+        Task #118 — ``agent_workspace_root`` (the per-agent override
+        from ``Agent.workspace_root``) participates in cwd resolution
+        but does NOT change where metadata lives.
+
+        Task #123 (2026-05-12) — when the caller doesn't pass
+        ``agent_workspace_root`` (typically: claude_runner's per-deliver
+        ``for_agent(agent_id)`` call), we fall back to reading the
+        persisted value from ``<path>/.meta/agent_workspace_root``.
+        That file is written by :meth:`ensure` and lets daemon restarts
+        + lazy lookups recover the user-chosen cwd without round-
+        tripping to backend. ``None`` from the file (missing / empty)
+        cleanly cascades into the host / platform tier in
+        :func:`compute_agent_cwd`.
+        """
+        path = self.root / agent_id
+        if agent_workspace_root is None:
+            agent_workspace_root = _read_persisted_agent_workspace_root(
+                path / ".meta"
+            )
+        cwd = compute_agent_cwd(
+            agent_id,
+            agent_workspace_root=agent_workspace_root,
+            host_workspace_root=self.host_workspace_root,
+            metadata_root=self.root,
+        )
+        return AgentWorkspace(path, cwd=cwd)
+
+    def ensure(
+        self,
+        agent_id: str,
+        identity: dict,
+        *,
+        agent_workspace_root: str | None = None,
+    ) -> AgentWorkspace:
+        """Idempotent: create metadata dir + identity + MEMORY.md + mcp
+        config under ``~/.cloudagent/agents/<id>/``. The claude cwd is
+        resolved via :func:`compute_agent_cwd` and its parent dirs are
+        created so the spawn can ``cwd=...`` into it.
+
+        Task #118 — ``agent_workspace_root`` (when set) chooses a cwd
+        OUTSIDE the metadata root; we deliberately do NOT write any
+        platform files there to keep the user's project directory
+        clean.
+        """
+        ws = self.for_agent(
+            agent_id, agent_workspace_root=agent_workspace_root
+        )
+        ws.path.mkdir(parents=True, exist_ok=True)
+        # Metadata-side subdirs always exist under ``ws.path``.
+        for sub in ("notes", ".meta", "claude"):
+            (ws.path / sub).mkdir(exist_ok=True)
+        # Task #123 (2026-05-12) — persist the agent_workspace_root
+        # override so subsequent ``for_agent(agent_id)`` calls (per-
+        # deliver lookups in claude_runner, daemon restarts) can
+        # recover the user-chosen cwd without the caller having to
+        # re-pass it. ``None`` deletes the file: explicit assign-frame
+        # "clear override" semantic per Task #122. The lazy claude_
+        # runner path also calls ``ensure(agent_id, identity)`` without
+        # the kwarg → None → file deletion, BUT that path only runs
+        # when ``ws.path`` did not previously exist (truly new agent on
+        # this daemon), so there's no override file to clobber.
+        _write_persisted_agent_workspace_root(
+            ws.path / ".meta", agent_workspace_root
+        )
+        # Ensure the chosen cwd exists too. When ``agent_workspace_root``
+        # is set this is a user-supplied path (e.g. ~/projects/foo) —
+        # mkdir(parents=True, exist_ok=True) makes the directory if it
+        # doesn't already exist. When the fallback chain picks
+        # ``ws.path / "workspace"`` we still need to create it.
+        ws.cwd.mkdir(parents=True, exist_ok=True)
+        ws._write_identity(identity)
+        if not (ws.path / "MEMORY.md").exists():
+            ws._write_memory_md_template(identity)
+        ws._write_mcp_config(identity)
+        return ws
+
+    def archive(self, agent_id: str) -> None:
+        """Mark agent as archived (touch .meta/archived.txt). 30-day cleanup is future."""
+        ws = self.for_agent(agent_id)
+        archived_marker = ws.path / ".meta" / "archived.txt"
+        # Ensure the dir exists before trying to write; if it never existed, still create marker.
+        ws.path.mkdir(parents=True, exist_ok=True)
+        (ws.path / ".meta").mkdir(exist_ok=True)
+        archived_marker.write_text(datetime.now(tz=timezone.utc).isoformat())