multi-forge 0.2.0__py3-none-any.whl

forge/session/claude/invoke.py

@@ -0,0 +1,236 @@
+"""Claude binary invocation utilities.
+
+This module provides utilities for invoking the Claude Code CLI binary
+with proper argument handling and environment setup.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def invoke_claude(
+    *,
+    session_id: str | None = None,
+    resume_id: str | None = None,
+    fork_session: bool = False,
+    name: str | None = None,
+    model: str | None = None,
+    system_prompt_file: str | None = None,
+    env_vars: dict[str, str] | None = None,
+    unset_env_vars: list[str] | None = None,
+    cwd: str | None = None,
+    extra_args: list[str] | None = None,
+) -> int:
+    """Invoke the Claude Code CLI binary.
+
+    Builds the command line arguments, sets up environment variables,
+    and runs Claude as a subprocess.
+
+    Args:
+        session_id: UUID for new session (--session-id flag).
+        resume_id: UUID to resume (--resume flag).
+        fork_session: Whether to fork (--fork-session flag).
+        name: Display name for Claude's session (--name flag).
+        model: Model tier to use (--model flag).
+        system_prompt_file: Path to system prompt file (--append-system-prompt-file flag).
+        env_vars: Additional environment variables to set.
+        unset_env_vars: Environment variables to remove from the child process.
+        cwd: Working directory for Claude process.
+        extra_args: Additional CLI arguments to pass through to Claude.
+
+    Returns:
+        Claude's exit code.
+
+    Raises:
+        FileNotFoundError: If claude binary is not found.
+
+    Example:
+        >>> # Start new session
+        >>> exit_code = invoke_claude(
+        ...     session_id="abc-123",
+        ...     model="opus",
+        ...     env_vars={"FORGE_SESSION": "my-session"},
+        ... )
+
+        >>> # Resume session
+        >>> exit_code = invoke_claude(
+        ...     resume_id="abc-123",
+        ...     env_vars={"FORGE_SESSION": "my-session"},
+        ... )
+
+        >>> # Fork session
+        >>> exit_code = invoke_claude(
+        ...     resume_id="parent-uuid",
+        ...     fork_session=True,
+        ...     env_vars={
+        ...         "FORGE_SESSION": "fork-name",
+        ...         "FORGE_FORK_NAME": "fork-name",
+        ...         "FORGE_PARENT_SESSION": "parent-session",
+        ...     },
+        ... )
+    """
+    cmd = _build_command(
+        session_id=session_id,
+        resume_id=resume_id,
+        fork_session=fork_session,
+        name=name,
+        model=model,
+        system_prompt_file=system_prompt_file,
+        extra_args=extra_args,
+    )
+
+    env = _build_environment(env_vars, unset_env_vars)
+
+    return _run_claude(cmd, env=env, cwd=cwd)
+
+
+def build_claude_args(
+    *,
+    session_id: str | None = None,
+    resume_id: str | None = None,
+    fork_session: bool = False,
+    name: str | None = None,
+    model: str | None = None,
+    system_prompt_file: str | None = None,
+    extra_args: list[str] | None = None,
+) -> list[str]:
+    """Build Claude CLI arguments without the executable prefix."""
+    args: list[str] = []
+
+    if session_id:
+        args.extend(["--session-id", session_id])
+    elif resume_id:
+        args.extend(["--resume", resume_id])
+        if fork_session:
+            args.append("--fork-session")
+
+    # --name works with both --session-id and --resume
+    if name:
+        args.extend(["--name", name])
+
+    if model:
+        args.extend(["--model", model])
+
+    if system_prompt_file:
+        args.extend(["--append-system-prompt-file", system_prompt_file])
+
+    if extra_args:  # e.g. -- --debug
+        args.extend(extra_args)
+    return args
+
+
+def _build_command(
+    *,
+    session_id: str | None = None,
+    resume_id: str | None = None,
+    fork_session: bool = False,
+    name: str | None = None,
+    model: str | None = None,
+    system_prompt_file: str | None = None,
+    extra_args: list[str] | None = None,
+) -> list[str]:
+    """Build the command line arguments for Claude.
+
+    Args:
+        session_id: UUID for new session.
+        resume_id: UUID to resume.
+        fork_session: Whether to fork.
+        model: Model tier.
+        system_prompt_file: Path to system prompt file.
+        extra_args: Additional CLI arguments appended after all other flags.
+
+    Returns:
+        List of command line arguments.
+    """
+    # No --bare: interactive sessions need hooks, LSP, and plugin sync
+    return [
+        "claude",
+        *build_claude_args(
+            session_id=session_id,
+            resume_id=resume_id,
+            fork_session=fork_session,
+            name=name,
+            model=model,
+            system_prompt_file=system_prompt_file,
+            extra_args=extra_args,
+        ),
+    ]
+
+
+def _build_environment(
+    extra_vars: dict[str, str] | None = None,
+    unset_vars: list[str] | None = None,
+) -> dict[str, str]:
+    """Build the environment for Claude process.
+
+    Delegates to the shared ``build_claude_env`` utility.
+
+    Args:
+        extra_vars: Additional environment variables to set.
+        unset_vars: Environment variables to remove from the child process.
+
+    Returns:
+        Complete environment dictionary.
+    """
+    from forge.core.reactive.env import build_claude_env
+
+    env = build_claude_env(extra_vars=extra_vars)
+    for key in unset_vars or ():
+        env.pop(key, None)
+    return env
+
+
+def _run_claude(
+    cmd: list[str],
+    env: dict[str, str] | None = None,
+    cwd: str | None = None,
+) -> int:
+    """Run the Claude binary as a subprocess.
+
+    Args:
+        cmd: Command line arguments.
+        env: Environment variables.
+        cwd: Working directory.
+
+    Returns:
+        Claude's exit code.
+
+    Raises:
+        FileNotFoundError: If claude binary is not found.
+    """
+    if cwd:
+        cwd = str(Path(cwd).resolve())
+
+    result = subprocess.run(
+        cmd,
+        env=env,
+        cwd=cwd,
+        # Let Claude take over the terminal
+        stdin=None,
+        stdout=None,
+        stderr=None,
+    )
+
+    return result.returncode
+
+
+def find_claude_binary() -> str | None:
+    """Find the claude binary in PATH.
+
+    Returns:
+        Path to claude binary, or None if not found.
+    """
+    import shutil
+
+    return shutil.which("claude")
+
+
+def is_claude_available() -> bool:
+    """Check if claude binary is available.
+
+    Returns:
+        True if claude is in PATH, False otherwise.
+    """
+    return find_claude_binary() is not None

forge/session/claude/paths.py

@@ -0,0 +1,200 @@
+"""Path utilities for Claude Code integration.
+
+Claude stores session data at: ~/.claude/projects/<encoded-path>/
+- <session_id>.jsonl - Transcript
+- agent-<uuid>.jsonl - Agent logs
+
+This module provides utilities for:
+- Encoding project paths for Claude's directory structure
+- Resolving transcript and agent log paths
+- Finding project roots (handles git worktrees)
+- Computing Claude's effective project root for a session
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from forge.session.models import SessionState
+
+
+def get_claude_home() -> Path:
+    """Get the Claude home directory (~/.claude).
+
+    Respects CLAUDE_HOME environment variable if set (for testing isolation).
+    Note: We expand a leading "~" so values like "~/.claude" work correctly,
+    even though that's the default.
+
+    Returns:
+        Path to ~/.claude directory (or CLAUDE_HOME override).
+    """
+    claude_home = os.environ.get("CLAUDE_HOME")
+    if claude_home:
+        return Path(claude_home).expanduser()
+    return Path.home() / ".claude"
+
+
+def get_claude_projects_dir() -> Path:
+    """Get the Claude projects directory (~/.claude/projects).
+
+    Returns:
+        Path to ~/.claude/projects directory.
+    """
+    return get_claude_home() / "projects"
+
+
+def encode_project_path(project_root: str) -> str:
+    """Encode project path for Claude's directory structure.
+
+    Claude stores session data in directories named after the project path,
+    with path separators and dots replaced by hyphens.
+
+    Args:
+        project_root: Absolute path to project root.
+
+    Returns:
+        Encoded path string (e.g., '/home/user/project' -> '-home-user-project').
+
+    Example:
+        >>> encode_project_path("/home/user/my.project")
+        '-home-user-my-project'
+    """
+    normalized = str(Path(project_root).resolve())
+    encoded = normalized.replace("/", "-").replace(".", "-")
+
+    return encoded
+
+
+def get_transcript_path(project_root: str, session_id: str) -> Path:
+    """Get the path to a session transcript file.
+
+    Args:
+        project_root: Absolute path to project root.
+        session_id: Claude session UUID.
+
+    Returns:
+        Path to the transcript file (may not exist).
+
+    Example:
+        >>> get_transcript_path("/home/user/project", "abc-123")
+        PosixPath('/home/user/.claude/projects/-home-user-project/abc-123.jsonl')
+    """
+    encoded_path = encode_project_path(project_root)
+    return get_claude_projects_dir() / encoded_path / f"{session_id}.jsonl"
+
+
+def find_agent_logs(project_root: str, session_id: str) -> list[Path]:
+    """Find agent log files containing a specific session ID.
+
+    Agent logs don't use session UUID in filename, only in content.
+    This function searches log file contents to find matching logs.
+
+    Args:
+        project_root: Absolute path to project root.
+        session_id: Claude session UUID to search for.
+
+    Returns:
+        List of paths to agent log files containing the session ID.
+        Returns empty list if directory doesn't exist or no matches found.
+    """
+    encoded_path = encode_project_path(project_root)
+    project_dir = get_claude_projects_dir() / encoded_path
+
+    if not project_dir.exists():
+        return []
+
+    matching_logs: list[Path] = []
+
+    for log_file in project_dir.glob("agent-*.jsonl"):
+        try:
+            content = log_file.read_text(encoding="utf-8")
+            if session_id in content:
+                matching_logs.append(log_file)
+        except (OSError, UnicodeDecodeError):
+            continue
+
+    return matching_logs
+
+
+def resolve_claude_project_root(state: SessionState) -> str:
+    """Claude Code project root for a session.
+
+    Claude Code scopes .claude/ settings, conversations, and transcripts
+    to its launch CWD.  This computes the correct CWD for any session
+    topology so that hooks, transcripts, and --resume all resolve correctly.
+
+    Rules:
+    - Non-worktree sessions: use forge_root (always correct).
+    - Nested projects (forge_root inside checkout): use forge_root so
+      Claude finds .claude/ at the nested path.
+    - Root-level worktrees (forge_root anchored at parent repo): use
+      worktree.path because extensions are installed at the checkout root.
+    """
+    if not state.worktree:
+        return state.forge_root or str(Path.cwd())
+
+    worktree_root = Path(state.worktree.path)
+    if state.forge_root:
+        try:
+            Path(state.forge_root).relative_to(worktree_root)
+            return state.forge_root  # Nested: forge_root is inside checkout
+        except ValueError:
+            pass
+    return str(worktree_root)  # Root-level: forge_root is at parent repo
+
+
+def find_project_root(start_path: str | None = None) -> Path:
+    """Find the git repository root by walking up the directory tree.
+
+    Handles both regular git repositories (where .git is a directory)
+    and git worktrees (where .git is a file pointing to the main repo).
+
+    Args:
+        start_path: Starting directory to search from. Defaults to cwd.
+
+    Returns:
+        Path to the git repository root.
+
+    Raises:
+        FileNotFoundError: If no git repository found.
+
+    Example:
+        >>> find_project_root("/home/user/project/src/module")
+        PosixPath('/home/user/project')
+    """
+    if start_path is None:
+        current = Path.cwd().resolve()
+    else:
+        current = Path(start_path).resolve()
+
+    while current != current.parent:
+        git_path = current / ".git"
+
+        # In worktrees, .git is a FILE; in main checkout, it's a DIRECTORY
+        if git_path.exists():
+            return current
+
+        current = current.parent
+
+    if (current / ".git").exists():
+        return current
+
+    raise FileNotFoundError(f"No git repository found at or above '{start_path or os.getcwd()}'")
+
+
+def get_project_encoded_dir(project_root: str) -> Path:
+    """Get the Claude projects subdirectory for a project.
+
+    Args:
+        project_root: Absolute path to project root.
+
+    Returns:
+        Path to the project's Claude data directory.
+
+    Example:
+        >>> get_project_encoded_dir("/home/user/project")
+        PosixPath('/home/user/.claude/projects/-home-user-project')
+    """
+    encoded_path = encode_project_path(project_root)
+    return get_claude_projects_dir() / encoded_path

forge/session/cleanup.py

@@ -0,0 +1,216 @@
+"""Session age-based cleanup.
+
+Mirrors the log management cleanup pattern (forge.cli.logs):
+- auto_clean_old_sessions(): called on CLI startup (best-effort)
+- clean_old_sessions(): core logic for both auto and manual cleanup
+
+Uses SessionManager.delete_session() for all actual deletion — it already
+handles manifests, index, transcripts, worktrees, co-resident sessions,
+and active-registry cleanup.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from forge.core.state import parse_iso
+from forge.runtime_config import get_runtime_config
+from forge.session import SessionManager
+from forge.session.active import ActiveSessionStore
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SessionCleanupResult:
+    """Result of a session cleanup operation.
+
+    All skip categories are surfaced so --dry-run and CLI output can
+    report every case. No silent drops.
+    """
+
+    deleted: list[str] = field(default_factory=list)
+    skipped_active: list[str] = field(default_factory=list)
+    skipped_unparseable: list[str] = field(default_factory=list)
+    failed: list[tuple[str, str]] = field(default_factory=list)
+    aborted_error: str | None = None
+
+    @property
+    def aborted(self) -> bool:
+        """Return True when cleanup stopped before evaluating sessions."""
+        return self.aborted_error is not None
+
+    @property
+    def is_empty(self) -> bool:
+        """Return True when cleanup found nothing actionable and did not abort."""
+        return (
+            not self.deleted
+            and not self.skipped_active
+            and not self.skipped_unparseable
+            and not self.failed
+            and self.aborted_error is None
+        )
+
+    @property
+    def has_failures(self) -> bool:
+        """Return True when cleanup aborted or any deletion failed."""
+        return self.aborted_error is not None or bool(self.failed)
+
+    @property
+    def failure_count(self) -> int:
+        """Return the number of surfaced cleanup failures."""
+        return len(self.failed) + (1 if self.aborted_error is not None else 0)
+
+    def failure_items(self) -> list[tuple[str, str]]:
+        """Return cleanup failures as display-ready (name, error) pairs."""
+        items = list(self.failed)
+        if self.aborted_error is not None:
+            items.insert(0, ("active session registry", self.aborted_error))
+        return items
+
+    @property
+    def should_exit_nonzero(self) -> bool:
+        """Return True when CLI cleanup should exit with an error."""
+        return self.has_failures
+
+    @property
+    def has_partial_success(self) -> bool:
+        """Return True when cleanup deleted sessions before later failures."""
+        return bool(self.deleted)
+
+    @property
+    def has_only_skips(self) -> bool:
+        """Return True when cleanup evaluated sessions but only skipped them."""
+        return (
+            not self.deleted
+            and not self.failed
+            and self.aborted_error is None
+            and bool(self.skipped_active or self.skipped_unparseable)
+        )
+
+    @property
+    def has_results(self) -> bool:
+        """Return True when cleanup produced any visible outcome."""
+        return not self.is_empty
+
+    @property
+    def summary_failed_count(self) -> int:
+        """Return the number of failures for user-facing summaries."""
+        return self.failure_count
+
+    @property
+    def summary_failed_label(self) -> str:
+        """Return singular/plural label for failure summaries."""
+        return "failure" if self.failure_count == 1 else "failures"
+
+
+def clean_old_sessions(
+    older_than_days: int,
+    *,
+    delete_transcripts: bool = True,
+    delete_worktree: bool = False,
+    delete_branch: bool = False,
+    force: bool = False,
+) -> SessionCleanupResult:
+    """Delete sessions whose last_accessed_at is older than the threshold.
+
+    Active sessions (per ActiveSessionStore) are always skipped. Sessions
+    with unparseable timestamps are skipped and reported.
+
+    Args:
+        older_than_days: Age threshold in days.
+        delete_transcripts: Delete Claude transcript files (~/.claude/projects/*.jsonl).
+            Forge artifact snapshots (.forge/artifacts/) are never removed.
+        delete_worktree: Delete git worktree directories (default False for safety).
+        delete_branch: Delete git branches (requires delete_worktree=True).
+        force: Bypass dirty-worktree protection (only relevant when delete_worktree=True).
+    """
+    result = SessionCleanupResult()
+    manager = SessionManager()
+
+    all_sessions = manager.list_sessions(include_incognito=True)
+
+    # One-pass active session lookup (single lock/read/probe cycle).
+    # Fail-closed: if we can't determine liveness, abort cleanup entirely.
+    # Sessions are high-value objects — deleting one whose Claude process is
+    # still running would destroy state.
+    active_store = ActiveSessionStore()
+    try:
+        active_entries = active_store.list_sessions()
+        # Use (name, forge_root) tuples to avoid cross-project false positives
+        active_identities = {(name, ae.forge_root or ae.worktree_path) for name, ae in active_entries}
+    except Exception as e:
+        logger.debug("Cannot read active session registry, aborting cleanup: %s", e)
+        result.aborted_error = str(e)
+        return result
+
+    for name, entry in all_sessions:
+        # Check age
+        try:
+            dt = parse_iso(entry.last_accessed_at)
+            age_days = (datetime.now(UTC) - dt).total_seconds() / 86400
+        except (ValueError, TypeError, AttributeError):
+            result.skipped_unparseable.append(name)
+            continue
+
+        if age_days <= older_than_days:
+            continue
+
+        # Check active status (scoped by forge_root to avoid cross-project false positives)
+        entry_identity = (name, entry.forge_root or entry.worktree_path)
+        if entry_identity in active_identities:
+            result.skipped_active.append(name)
+            continue
+
+        # Delete (scoped by forge_root to avoid cross-project collisions)
+        try:
+            manager.delete_session(
+                name,
+                delete_transcripts=delete_transcripts,
+                delete_worktree=delete_worktree,
+                delete_branch=delete_branch,
+                force=force,
+                forge_root=entry.forge_root or entry.worktree_path,
+            )
+            result.deleted.append(name)
+        except Exception as e:
+            result.failed.append((name, str(e)))
+            logger.debug("Failed to clean session '%s': %s", name, e, exc_info=True)
+
+    return result
+
+
+def auto_clean_old_sessions() -> None:
+    """Auto-prune old sessions based on session_retention_days config.
+
+    Called opportunistically on CLI startup. Best-effort: swallows all
+    exceptions to avoid breaking CLI commands.
+
+    Auto-cleanup uses safe defaults:
+    - delete_transcripts=True (transcripts are useless without sessions)
+    - delete_worktree=False (too destructive for automatic operation)
+    - delete_branch=False (branches are lightweight, keep them)
+    - force=True (safe because delete_worktree=False means dirty-check is never reached)
+    """
+    try:
+        rc = get_runtime_config()
+        if rc.session_retention_days <= 0:
+            return
+
+        cleanup_result = clean_old_sessions(
+            older_than_days=rc.session_retention_days,
+            delete_transcripts=True,
+            delete_worktree=False,
+            delete_branch=False,
+            force=True,
+        )
+        if cleanup_result.deleted:
+            logger.debug(
+                "Auto-cleaned %d session(s) older than %d days",
+                len(cleanup_result.deleted),
+                rc.session_retention_days,
+            )
+    except Exception as e:
+        logger.debug("Session auto-cleanup error (non-fatal): %s", e)

forge/session/config.py

@@ -0,0 +1,34 @@
+"""Default configuration values for forge session.
+
+These defaults can be overridden via environment variables:
+- FORGE_DEFAULT_PROXY_TEMPLATE
+- FORGE_DEFAULT_PROXY_BASE_URL
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Proxy defaults (configurable via env vars)
+DEFAULT_PROXY_TEMPLATE = os.environ.get("FORGE_DEFAULT_PROXY_TEMPLATE", "litellm-openai")
+DEFAULT_PROXY_BASE_URL = os.environ.get("FORGE_DEFAULT_PROXY_BASE_URL", "http://localhost:8085")
+
+# Launch mode constants
+LAUNCH_MODE_HOST = "host"
+LAUNCH_MODE_SIDECAR = "sidecar"
+
+# Sidecar sessions always talk to the proxy on the container-local loopback.
+SIDECAR_RUNTIME_BASE_URL = "http://localhost:8085"
+
+
+def _discover_templates() -> tuple[str, ...]:
+    """Derive valid proxy templates from the templates directory."""
+    templates_dir = Path(__file__).parent.parent / "config" / "defaults" / "templates"
+    if not templates_dir.is_dir():
+        return ()
+    return tuple(sorted(p.stem for p in templates_dir.glob("*.yaml")))
+
+
+# Valid proxy templates (derived from templates directory)
+VALID_PROXY_TEMPLATES: tuple[str, ...] = _discover_templates()