multi-forge 0.2.0__py3-none-any.whl

forge/core/reactive/session_runner.py

@@ -0,0 +1,185 @@
+"""Claude subprocess management for headless (-p) mode.
+
+Provides a unified interface for running ``claude -p`` as a subprocess
+with structured result handling. Used by the semantic supervisor
+(``claude -p --resume``) and handoff agent (``claude -p``).
+
+For interactive sessions (stdin/stdout inherited), use
+``forge.session.claude.invoke.invoke_claude()`` instead.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from dataclasses import dataclass
+
+from forge.core.reactive.env import (
+    FORGE_SUBPROCESS_PROXY_VAR,
+    build_claude_env,
+    can_use_bare,
+)
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass
+class SessionResult:
+    """Result from a ``claude -p`` invocation.
+
+    The runner never raises — all errors are captured in the ``error`` field.
+    Callers inspect ``success`` and ``error`` to decide their own fail
+    behavior (fail-open warnings for supervisor, return False for handoff).
+    """
+
+    stdout: str
+    stderr: str
+    returncode: int
+    timed_out: bool = False
+    error: str | None = None
+
+    @property
+    def success(self) -> bool:
+        """True if the subprocess completed successfully."""
+        return self.returncode == 0 and not self.timed_out and self.error is None
+
+
+def run_claude_session(
+    prompt: str,
+    *,
+    resume_id: str | None = None,
+    fork_session: bool = False,
+    bare: bool | None = None,
+    base_url: str | None = None,
+    direct: bool = False,
+    timeout_seconds: int = 60,
+    cwd: str | None = None,
+    extra_env: dict[str, str] | None = None,
+) -> SessionResult:
+    """Run ``claude -p`` as a headless subprocess.
+
+    Builds the command, environment, and runs ``subprocess.run`` with
+    ``capture_output=True``. All exceptions are caught and reported
+    via ``SessionResult.error``.
+
+    Args:
+        prompt: Text sent to claude via stdin.
+        resume_id: If set, adds ``--resume <id>`` to continue a session.
+        fork_session: If True and resume_id is set, adds ``--fork-session``
+            to create an ephemeral fork instead of appending to the
+            original conversation.
+        bare: If True, adds ``--bare`` to skip hooks/LSP/plugins.
+            None (default) auto-detects: uses ``--bare`` only when
+            ANTHROPIC_API_KEY is present (``--bare`` disables OAuth).
+        base_url: Proxy URL (sets ANTHROPIC_BASE_URL in environment).
+        timeout_seconds: Maximum seconds to wait for completion.
+        cwd: Working directory for the subprocess.
+        extra_env: Additional environment variables.
+
+    Returns:
+        SessionResult with stdout/stderr/returncode or error details.
+    """
+    env = build_claude_env(base_url=base_url, extra_vars=extra_env, direct=direct)
+
+    use_bare = bare if bare is not None else can_use_bare(env)
+    cmd = ["claude", "-p"]
+    if use_bare:
+        cmd.append("--bare")
+    if resume_id:
+        cmd.extend(["--resume", resume_id])
+        if fork_session:
+            cmd.append("--fork-session")
+
+    # Guard: fail if subprocess proxy was configured but didn't resolve.
+    # Prevents silent fallback to direct mode (which would burn subscription quota).
+    subprocess_proxy = env.get(FORGE_SUBPROCESS_PROXY_VAR)
+    if subprocess_proxy and not base_url and not direct and not env.get("ANTHROPIC_BASE_URL"):
+        msg = (
+            f"Subprocess proxy '{subprocess_proxy}' not available. "
+            f"Start it with: forge proxy start {subprocess_proxy}"
+        )
+        _log.warning(msg)
+        return SessionResult(stdout="", stderr="", returncode=-1, error=msg)
+
+    # Guard: fail with actionable error if --bare was requested but no API key.
+    # Without this, the subprocess would fail with a cryptic Claude CLI error.
+    # Only fires when bare mode was explicitly requested (bare=True) — when
+    # bare=None and no key exists, can_use_bare() returns False and Claude
+    # falls through to OAuth (which may be intentional).
+    if bare and not env.get("ANTHROPIC_BASE_URL") and not env.get("ANTHROPIC_API_KEY"):
+        try:
+            from forge.core.auth.capabilities import (
+                CREDENTIALS,
+                format_missing_credential_error,
+            )
+            from forge.runtime_config import get_runtime_config
+
+            env_ignored = get_runtime_config().auth_ignore_env
+            cred = CREDENTIALS.get("anthropic-api")
+            if cred:
+                msg = format_missing_credential_error(
+                    cred,
+                    missing_vars=["ANTHROPIC_API_KEY"],
+                    context="Forge subprocess (claude -p)",
+                    extra_hint="Or use --subprocess-proxy to route through an existing proxy.",
+                    env_ignored=env_ignored,
+                )
+                _log.warning(msg)
+                return SessionResult(stdout="", stderr="", returncode=-1, error=msg)
+        except Exception as e:
+            _log.debug("Could not format missing Anthropic subprocess credential error: %s", e)
+
+    try:
+        _log.debug(
+            "Running claude session: cmd=%s, resume=%s, cwd=%s",
+            cmd,
+            resume_id and resume_id[:16],
+            cwd,
+        )
+
+        result = subprocess.run(
+            cmd,
+            input=prompt,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            cwd=cwd,
+            env=env,
+        )
+
+        if result.returncode != 0:
+            _log.warning("claude -p returned non-zero exit code: %d", result.returncode)
+
+        return SessionResult(
+            stdout=result.stdout,
+            stderr=result.stderr,
+            returncode=result.returncode,
+        )
+
+    except subprocess.TimeoutExpired:
+        _log.warning("claude -p timed out after %ds", timeout_seconds)
+        return SessionResult(
+            stdout="",
+            stderr="",
+            returncode=-1,
+            timed_out=True,
+            error=f"Timed out after {timeout_seconds}s",
+        )
+
+    except FileNotFoundError:
+        _log.error("claude CLI not found in PATH")
+        return SessionResult(
+            stdout="",
+            stderr="",
+            returncode=-1,
+            error="claude CLI not found in PATH",
+        )
+
+    except Exception as e:
+        _log.warning("claude -p failed: %s", e)
+        return SessionResult(
+            stdout="",
+            stderr="",
+            returncode=-1,
+            error=str(e),
+        )

forge/core/reactive/structured_output.py

@@ -0,0 +1,62 @@
+"""Structured output extraction from LLM responses.
+
+Extracts JSON objects from LLM text responses that may contain
+code fences, prose, or raw JSON. Used by verdict parsing,
+workflow policy checkers, and any component that needs structured
+LLM output.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+_log = logging.getLogger(__name__)
+
+# Patterns tried in order: ```json ... ```, then ``` ... ```
+_CODE_FENCE_PATTERNS = [
+    re.compile(r"```json\s*\n?(.*?)\n?```", re.DOTALL | re.IGNORECASE),
+    re.compile(r"```\s*\n?(.*?)\n?```", re.DOTALL | re.IGNORECASE),
+]
+
+
+def extract_json_from_response(response: str) -> dict[str, Any] | None:
+    """Extract a JSON object from an LLM response.
+
+    Tries code fences first (````` ```json ````` , then ````` ``` ````` ),
+    then falls back to parsing the entire response as raw JSON.
+    Returns the first successfully parsed JSON object.
+
+    Args:
+        response: Raw text response from the LLM.
+
+    Returns:
+        Parsed dict if extraction succeeds, None otherwise.
+        Callers decide their own fail behavior (fail-open, warn, etc.).
+    """
+    if not response:
+        return None
+
+    # Try code fences
+    for pattern in _CODE_FENCE_PATTERNS:
+        matches = pattern.findall(response)
+        for match in matches:
+            try:
+                data = json.loads(match.strip())
+                if isinstance(data, dict):
+                    return data
+            except json.JSONDecodeError:
+                continue
+
+    # Fallback: raw JSON
+    try:
+        data = json.loads(response.strip())
+        if isinstance(data, dict):
+            return data
+    except json.JSONDecodeError:
+        pass
+
+    _log.debug("Could not extract JSON from response (len=%d)", len(response))
+    return None

forge/core/reactive/tagger.py

@@ -0,0 +1,94 @@
+"""Cheap LLM classification via core.llm.SyncAdapter.
+
+Classifies actions into tags using a cheap model for routing
+decisions in WorkflowPolicy branches.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from forge.guard.types import ActionContext
+
+_log = logging.getLogger(__name__)
+
+
+def tag_action(
+    context: ActionContext,
+    *,
+    model: str,
+    prompt_template: str,
+) -> list[str]:
+    """Classify an action into tags via a cheap LLM call.
+
+    Uses ``core.llm.SyncAdapter`` to make a single LLM call. The prompt
+    template is formatted with action context fields. The response is
+    parsed as either a JSON array or pipe/comma-separated string.
+
+    Must NOT be called from inside an event loop (SyncAdapter constraint).
+
+    Args:
+        context: Action being classified.
+        model: Prefixed model ID (e.g., "gemini/gemini-2.0-flash").
+        prompt_template: Template with {tool_name}, {target_path}, {content}
+                         placeholders.
+
+    Returns:
+        List of tag strings. Empty list on any error (fail-open).
+    """
+    try:
+        from forge.core.llm import SyncAdapter, get_client
+
+        prompt = prompt_template.format(
+            tool_name=context.tool_name,
+            target_path=context.target_path or "N/A",
+            content=(context.raw_diff or context.new_content or "")[:2000],
+        )
+
+        client = get_client(model)
+        adapter = SyncAdapter(client)
+        response = adapter.ask(prompt)
+
+        return _parse_tags(response)
+
+    except Exception as e:
+        _log.warning("tag_action failed (model=%s): %s", model, e)
+        return []
+
+
+def _parse_tags(response: str) -> list[str]:
+    """Parse tags from an LLM response.
+
+    Tries JSON array first, then pipe-separated, then comma-separated.
+
+    Args:
+        response: Raw text from the LLM.
+
+    Returns:
+        List of stripped, non-empty tag strings.
+    """
+    if not response:
+        return []
+
+    text = response.strip()
+
+    # Try JSON array
+    try:
+        data = json.loads(text)
+        if isinstance(data, list):
+            return [str(t).strip() for t in data if t is not None and str(t).strip()]
+    except json.JSONDecodeError:
+        pass
+
+    # Try pipe-separated (e.g., "routine | trivial")
+    if "|" in text:
+        return [t.strip() for t in text.split("|") if t.strip()]
+
+    # Try comma-separated (e.g., "routine, trivial")
+    if "," in text:
+        return [t.strip() for t in text.split(",") if t.strip()]
+
+    # Single tag
+    tag = text.strip()
+    return [tag] if tag else []

forge/core/reactive/throttle.py

@@ -0,0 +1,132 @@
+"""Generic TTL-based throttle cache.
+
+Extracted from forge.guard.store supervisor cache functions.
+Provides a reusable cache for deduplicating expensive calls
+(LLM invocations, subprocess spawns) within a time window.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from forge.core.state import now_iso
+
+_log = logging.getLogger(__name__)
+
+
+def compute_cache_key(tool_name: str, file_path: str | None, content: str | None) -> str:
+    """Compute a cache key from action attributes.
+
+    Returns a truncated SHA256 hash of tool_name + file_path + content.
+
+    Args:
+        tool_name: The tool being invoked (e.g., "Write").
+        file_path: Target file path (may be None).
+        content: Content being written (may be None).
+
+    Returns:
+        16-character hex string cache key.
+    """
+    parts = [tool_name, file_path or "", content or ""]
+    key_string = "|".join(parts)
+    return hashlib.sha256(key_string.encode()).hexdigest()[:16]
+
+
+class ThrottleCache:
+    """TTL-based in-memory cache for deduplicating expensive calls.
+
+    Entries expire after ``ttl_seconds``. The cache is bounded to
+    ``max_entries`` (pruned in ``get_state()`` for persistence).
+
+    The cache does NOT decide *what* to cache — callers own that logic.
+    For example, the supervisor only caches clean allows (no warnings).
+
+    State round-trip via ``get_state()``/``set_state()`` supports
+    ``StatefulPolicy`` persistence across hook invocations.
+    """
+
+    def __init__(self, ttl_seconds: int = 30, max_entries: int = 50) -> None:
+        self._ttl_seconds = ttl_seconds
+        self._max_entries = max_entries
+        self._cache: dict[str, dict[str, Any]] = {}
+
+    def check(self, key: str) -> dict[str, Any] | None:
+        """Check if a cached entry is still valid.
+
+        Args:
+            key: Cache key to look up.
+
+        Returns:
+            Cached entry dict if valid (within TTL), None otherwise.
+        """
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+
+        checked_at = entry.get("checked_at")
+        if checked_at is None:
+            return None
+
+        try:
+            checked_time = datetime.fromisoformat(checked_at.replace("Z", "+00:00"))
+            now = datetime.now(timezone.utc)
+            age_seconds = (now - checked_time).total_seconds()
+
+            if age_seconds < self._ttl_seconds:
+                _log.debug("Cache hit for %s (age: %.1fs)", key, age_seconds)
+                return entry
+
+            _log.debug(
+                "Cache expired for %s (age: %.1fs > %ds)",
+                key,
+                age_seconds,
+                self._ttl_seconds,
+            )
+            return None
+
+        except (ValueError, TypeError) as e:
+            _log.warning("Invalid cache timestamp for %s: %s", key, e)
+            return None
+
+    def update(self, key: str, **values: Any) -> None:
+        """Add or update a cache entry.
+
+        Automatically sets ``checked_at`` to the current UTC timestamp.
+
+        Args:
+            key: Cache key.
+            **values: Arbitrary key-value pairs to store (e.g., verdict, confidence).
+        """
+        self._cache[key] = {
+            "checked_at": now_iso(),
+            **values,
+        }
+
+    def get_state(self) -> dict[str, Any]:
+        """Return cache state for persistence, pruned to max_entries most recent.
+
+        Returns a deep copy so mutations don't affect internal state.
+
+        Returns:
+            Flat dict of ``{key: {checked_at, ...}, ...}``.
+        """
+        cache = {k: dict(v) for k, v in self._cache.items()}
+        if len(cache) > self._max_entries:
+            sorted_keys = sorted(
+                cache.keys(),
+                key=lambda k: cache[k].get("checked_at", ""),
+                reverse=True,
+            )
+            cache = {k: cache[k] for k in sorted_keys[: self._max_entries]}
+        return cache
+
+    def set_state(self, state: dict[str, Any]) -> None:
+        """Restore cache state from persisted data.
+
+        Args:
+            state: Flat dict previously returned by ``get_state()``.
+        """
+        self._cache = dict(state) if state else {}

forge/core/state/__init__.py

@@ -0,0 +1,59 @@
+"""Shared state utilities for Forge file-based state system.
+
+This module provides:
+- Atomic file write operations (tempfile + os.replace pattern)
+- Timestamp helpers (ISO8601, UTC-only)
+- Base exception hierarchy for state operations
+
+Usage:
+    from forge.core.state import atomic_write_json, now_iso
+    from forge.core.state import StateCorruptedError, SchemaVersionError
+
+For domain-specific state operations, use the domain modules:
+    from forge.session import SessionStore, IndexStore
+    from forge.proxy.proxies import ProxyRegistryStore
+"""
+
+# IO utilities
+from .io import atomic_write_json, atomic_write_text, open_secure_append, read_json
+
+# Locking utilities
+from .lock import (
+    FileLockTimeoutError,
+    file_lock,
+    file_lock_for_target,
+    get_lock_path_for_target,
+)
+
+# Timestamp utilities
+from .timestamps import iso_to_timestamp, now_iso, parse_iso
+
+# Exceptions
+from .exceptions import (
+    SchemaVersionError,
+    StateCorruptedError,
+    StateError,
+    StateNotFoundError,
+)
+
+__all__ = [
+    # IO
+    "atomic_write_text",
+    "atomic_write_json",
+    "open_secure_append",
+    "read_json",
+    # Locking
+    "get_lock_path_for_target",
+    "file_lock",
+    "file_lock_for_target",
+    "FileLockTimeoutError",
+    # Timestamps
+    "now_iso",
+    "parse_iso",
+    "iso_to_timestamp",
+    # Exceptions
+    "StateError",
+    "StateNotFoundError",
+    "StateCorruptedError",
+    "SchemaVersionError",
+]

forge/core/state/exceptions.py

@@ -0,0 +1,59 @@
+"""Base exceptions for Forge state operations.
+
+Domain modules (session, proxies) define their own specific exceptions
+that inherit from these bases.
+"""
+
+from __future__ import annotations
+
+
+class StateError(Exception):
+    """Base exception for all state operations."""
+
+
+class StateNotFoundError(StateError):
+    """Raised when a state file does not exist.
+
+    Attributes:
+        path: Path to the missing file.
+    """
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"state file not found: '{path}'")
+
+
+class StateCorruptedError(StateError):
+    """Raised when a state file cannot be parsed or has an incompatible format.
+
+    Attributes:
+        path: Path to the problematic file.
+        reason: Description of what went wrong.
+    """
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(f"'{path}': {reason}")
+
+
+class SchemaVersionError(StateCorruptedError):
+    """Raised when schema version is unsupported.
+
+    Attributes:
+        path: Path to the file.
+        expected: Expected version(s).
+        actual: Version found in file.
+    """
+
+    def __init__(self, path: str, expected: int | set[int], actual: int) -> None:
+        self.expected = expected if isinstance(expected, set) else {expected}
+        self.actual = actual
+        self.path = path
+        self.reason = f"incompatible version {actual} (expected {sorted(self.expected)})"
+        Exception.__init__(
+            self,
+            f"'{path}' has incompatible version {actual} "
+            f"(this Forge expects {sorted(self.expected)}). "
+            f"Delete this file and retry.",
+        )