multi-forge 0.2.0__py3-none-any.whl

forge/session/direct_model.py

@@ -0,0 +1,107 @@
+"""Claude Code direct model pin helpers."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from dataclasses import dataclass
+
+from forge.core.models.catalog import (
+    ModelCatalogError,
+    get_model_spec,
+    resolve_model_id,
+)
+
+ONE_M_SUFFIX = "[1m]"
+
+
+@dataclass(frozen=True)
+class DirectModelPin:
+    """A Claude Code env-ready direct model pin."""
+
+    canonical_model: str
+    env_model: str
+    tier: str
+
+    @property
+    def env_var(self) -> str:
+        return f"ANTHROPIC_DEFAULT_{self.tier.upper()}_MODEL"
+
+    def env(self) -> dict[str, str]:
+        return {
+            "ANTHROPIC_MODEL": self.tier,
+            self.env_var: self.env_model,
+        }
+
+
+def resolve_direct_model_pin(value: str) -> DirectModelPin:
+    """Resolve a direct-session model value to Claude Code model env vars.
+
+    The catalog owns aliases and canonical model IDs. Claude Code owns the
+    ``[1m]`` model-pin suffix, so this helper strips it for catalog lookup and
+    restores it on the normalized env-ready model value.
+    """
+    raw_value = value.strip()
+    if not raw_value:
+        raise ValueError("--model cannot be empty")
+
+    requested_1m = raw_value.endswith(ONE_M_SUFFIX)
+    lookup_value = raw_value.removesuffix(ONE_M_SUFFIX) if requested_1m else raw_value
+
+    try:
+        canonical = resolve_model_id(lookup_value)
+    except ModelCatalogError as e:
+        raise ValueError(f"Unknown direct Claude model: {value!r}") from e
+
+    normalized_1m = requested_1m or canonical.endswith("-1m")
+    base_canonical = canonical.removesuffix("-1m") if canonical.endswith("-1m") else canonical
+
+    if not base_canonical.startswith("claude-"):
+        raise ValueError(f"--model only supports Claude models for direct sessions, got {value!r}")
+
+    tier = _claude_tier(base_canonical)
+    if tier is None:
+        raise ValueError(f"Unsupported Claude model tier for direct sessions: {value!r}")
+
+    if normalized_1m:
+        spec = get_model_spec(base_canonical)
+        if tier not in {"opus", "sonnet"} and not spec.supports_1m_context:
+            raise ValueError("[1m] direct model pins are only supported for Opus/Sonnet Claude models")
+
+    env_model = f"{base_canonical}{ONE_M_SUFFIX}" if normalized_1m else base_canonical
+    return DirectModelPin(canonical_model=base_canonical, env_model=env_model, tier=tier)
+
+
+def direct_model_env(value: str | None) -> dict[str, str]:
+    """Return Claude Code direct-model environment variables for ``value``."""
+    if not value:
+        return {}
+    return resolve_direct_model_pin(value).env()
+
+
+def apply_direct_model_env(env_vars: MutableMapping[str, str], value: str | None) -> str | None:
+    """Apply direct-model env vars in-place, returning an error message on failure."""
+    if not value:
+        return None
+    try:
+        env_vars.update(direct_model_env(value))
+    except ValueError as e:
+        return str(e)
+    return None
+
+
+def token_estimate_multiplier_for_direct_model(value: str | None) -> float:
+    """Return the catalog token-estimate multiplier for a direct model pin."""
+    if not value:
+        return 1.0
+    pin = resolve_direct_model_pin(value)
+    return get_model_spec(pin.canonical_model).token_estimate_multiplier
+
+
+def _claude_tier(canonical_model: str) -> str | None:
+    if canonical_model.startswith("claude-opus-"):
+        return "opus"
+    if canonical_model.startswith("claude-sonnet-"):
+        return "sonnet"
+    if canonical_model.startswith("claude-haiku-"):
+        return "haiku"
+    return None

forge/session/effective.py

@@ -0,0 +1,169 @@
+"""Effective configuration computation (intent + overrides).
+
+This module provides functions for computing the effective session configuration
+by merging the baseline intent with runtime overrides.
+
+Merge semantics:
+- Scalars: override replaces base value
+- Dicts: recursively merge (override keys win on conflict)
+- Lists: override replaces entire list (no concatenation)
+- None in override: clears the field (effective value becomes None)
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import asdict
+from typing import Any
+
+import dacite
+
+from .exceptions import InvalidOverrideKeyError, InvalidOverrideValueError
+from .models import SessionIntent, SessionState
+
+
+def apply_overrides(base: dict[str, Any], overrides: dict[str, Any]) -> dict[str, Any]:
+    """Apply user overrides to a base configuration dict.
+
+    This is a generic merge function with no schema awareness.
+    Schema validation happens in compute_effective_intent().
+
+    Merge semantics:
+    - Scalars: override replaces base
+    - Dicts: recursively merge (both must be dicts)
+    - Lists: override replaces entire list (no concatenation)
+    - None in override: sets field to None (clears it)
+    - New keys in override: added to result
+
+    Args:
+        base: The base dictionary (typically from intent).
+        overrides: The overrides dictionary (sparse, only changed fields).
+
+    Returns:
+        A new dict with overrides applied to base.
+    """
+    result = deepcopy(base)
+
+    for key, value in overrides.items():
+        if value is None:
+            result[key] = None
+        elif isinstance(value, dict) and key in result and isinstance(result[key], dict):
+            result[key] = apply_overrides(result[key], value)
+        else:
+            result[key] = deepcopy(value)
+
+    return result
+
+
+def compute_effective_intent(
+    state: SessionState,
+    strict: bool = True,
+    override_key: str | None = None,
+) -> SessionIntent:
+    """Compute effective config by merging intent with overrides.
+
+    Args:
+        state: The session state containing intent and overrides.
+        strict: If True, validate the merged result can become a valid SessionIntent.
+                Raises InvalidOverrideValueError on type mismatches.
+        override_key: If provided, used in error messages to identify which override
+                      caused the failure. Typically the key being set via CLI.
+
+    Returns:
+        A SessionIntent representing the effective configuration.
+
+    Raises:
+        InvalidOverrideValueError: If strict=True and the merged config has invalid types.
+    """
+    intent_dict = asdict(state.intent)
+
+    if state.overrides:
+        merged = apply_overrides(intent_dict, state.overrides)
+    else:
+        merged = intent_dict
+
+    if strict:
+        try:
+            return dacite.from_dict(
+                data_class=SessionIntent,
+                data=merged,
+                config=dacite.Config(strict=True),
+            )
+        except (dacite.DaciteError, TypeError, ValueError) as e:
+            key = override_key or "unknown"
+            actual = _infer_actual_type(e, merged)
+            expected = _infer_expected_type(e)
+            raise InvalidOverrideValueError(key, expected, actual) from e
+
+    # Non-strict mode: best-effort conversion.
+    # Note: With strict v3 manifests and strict override validation, this should
+    # generally not encounter unknown keys.
+    return dacite.from_dict(
+        data_class=SessionIntent,
+        data=merged,
+        config=dacite.Config(strict=True),
+    )
+
+
+def get_effective_value(state: SessionState, key: str) -> Any | None:
+    """Get effective value for a specific dot-notation key.
+
+    This function validates the key syntax but returns None for valid keys
+    that are not present in the effective config (rather than raising).
+
+    Args:
+        state: The session state.
+        key: Dot-notation path (e.g., "agent", "proxy.template").
+
+    Returns:
+        The effective value, or None if key is valid but not set.
+
+    Raises:
+        InvalidOverrideKeyError: If key syntax is invalid (empty, empty segments).
+    """
+    if not key:
+        raise InvalidOverrideKeyError(key, "key cannot be empty")
+
+    parts = key.split(".")
+    for part in parts:
+        if not part:
+            raise InvalidOverrideKeyError(key, "empty segment in path")
+
+    effective = compute_effective_intent(state, strict=True)
+    effective_dict = asdict(effective)
+
+    current: Any = effective_dict
+    for part in parts:
+        if not isinstance(current, dict):
+            return None
+        if part not in current:
+            return None
+        current = current[part]
+
+    return current
+
+
+def _infer_actual_type(error: Exception, merged: dict[str, Any]) -> str:
+    """Try to infer the actual type/value from a dacite error."""
+    error_str = str(error)
+
+    if "expected" in error_str.lower() and "got" in error_str.lower():
+        return error_str
+
+    return f"invalid value ({error_str})"
+
+
+def _infer_expected_type(error: Exception) -> str:
+    """Try to infer the expected type from a dacite error."""
+    error_str = str(error)
+
+    if "str" in error_str:
+        return "str"
+    if "list" in error_str:
+        return "list"
+    if "int" in error_str:
+        return "int"
+    if "bool" in error_str:
+        return "bool"
+
+    return "valid type"

forge/session/exceptions.py

@@ -0,0 +1,255 @@
+"""Exceptions for Forge Session module."""
+
+from __future__ import annotations
+
+
+class ForgeSessionError(Exception):
+    """Base exception for session module."""
+
+
+class InvalidSessionNameError(ForgeSessionError):
+    """Raised when session name validation fails."""
+
+
+class SessionNotFoundError(ForgeSessionError):
+    """Raised when a session cannot be found."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"session '{name}' not found")
+
+
+class SessionExistsError(ForgeSessionError):
+    """Raised when trying to create a session that already exists."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"session '{name}' already exists")
+
+
+class SessionFileNotFoundError(ForgeSessionError):
+    """Raised when session state file doesn't exist in expected location."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"session file not found at '{path}'")
+
+
+class ManifestCorruptedError(ForgeSessionError):
+    """Raised when manifest file exists but cannot be parsed."""
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(f"manifest at '{path}': {reason}")
+
+
+class ManifestValidationError(ForgeSessionError):
+    """Raised when manifest is missing required fields."""
+
+    def __init__(self, path: str, missing_fields: list[str]) -> None:
+        self.path = path
+        self.missing_fields = missing_fields
+        fields_str = ", ".join(missing_fields)
+        super().__init__(f"manifest at '{path}' missing required fields: {fields_str}")
+
+
+class IndexCorruptedError(ForgeSessionError):
+    """Raised when index file exists but cannot be parsed."""
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(f"index at '{path}': {reason}")
+
+
+class CannotForkIncognitoError(ForgeSessionError):
+    """Raised when attempting to fork from an incognito session."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"cannot fork from incognito session '{name}'")
+
+
+class ClaudeInvocationError(ForgeSessionError):
+    """Raised when Claude binary invocation fails."""
+
+    def __init__(self, reason: str, exit_code: int | None = None) -> None:
+        self.reason = reason
+        self.exit_code = exit_code
+        msg = reason
+        if exit_code is not None:
+            msg = f"{reason} (exit code: {exit_code})"
+        super().__init__(msg)
+
+
+class ProjectRootNotFoundError(ForgeSessionError):
+    """Raised when no git repository can be found."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"no git repository found at or above '{path}'")
+
+
+class ForgeNotEnabledError(ForgeSessionError):
+    """Raised when session start is attempted without a Forge project.
+
+    Rule 1: sessions require ``forge extension enable`` (which creates ``.forge/``).
+    """
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"no Forge project at '{path}'. Run 'forge extension enable' first.")
+
+
+# --- Git Worktree Exceptions ---
+
+
+class GitNotFoundError(ForgeSessionError):
+    """Raised when git binary is not found in PATH."""
+
+    def __init__(self) -> None:
+        super().__init__("git binary not found in PATH")
+
+
+class GitWorktreeError(ForgeSessionError):
+    """Raised when a git worktree operation fails."""
+
+    def __init__(self, operation: str, reason: str, exit_code: int | None = None) -> None:
+        self.operation = operation
+        self.reason = reason
+        self.exit_code = exit_code
+        msg = f"git worktree {operation} failed: {reason}"
+        if exit_code is not None:
+            msg = f"{msg} (exit code: {exit_code})"
+        super().__init__(msg)
+
+
+class InvalidBranchNameError(ForgeSessionError):
+    """Raised when an explicit --branch name is invalid."""
+
+    def __init__(self, branch: str, reason: str) -> None:
+        self.branch = branch
+        self.reason = reason
+        super().__init__(f"invalid branch name '{branch}': {reason}")
+
+
+class BranchExistsError(ForgeSessionError):
+    """Raised when trying to create a branch that already exists."""
+
+    def __init__(self, branch: str, worktree: str | None = None) -> None:
+        self.branch = branch
+        self.worktree = worktree
+        if worktree:
+            msg = f"branch '{branch}' already exists (checked out in '{worktree}')"
+        else:
+            msg = f"branch '{branch}' already exists"
+        super().__init__(msg)
+
+
+class BranchInUseError(ForgeSessionError):
+    """Raised when a branch is checked out in another worktree."""
+
+    def __init__(self, branch: str, worktree: str) -> None:
+        self.branch = branch
+        self.worktree = worktree
+        super().__init__(f"branch '{branch}' is checked out in worktree '{worktree}'")
+
+
+class BranchNotMergedError(ForgeSessionError):
+    """Raised when trying to delete a branch that is not fully merged."""
+
+    def __init__(self, branch: str) -> None:
+        self.branch = branch
+        super().__init__(f"branch '{branch}' is not fully merged. Use --force to delete anyway")
+
+
+class WorktreePathExistsError(ForgeSessionError):
+    """Raised when the target worktree path already exists."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"worktree path '{path}' already exists")
+
+
+class DirtyWorktreeError(ForgeSessionError):
+    """Raised when a worktree has uncommitted changes during cleanup."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"worktree '{path}' has uncommitted changes. Use --force to remove anyway")
+
+
+# --- Override Exceptions ---
+
+
+class InvalidOverrideKeyError(ForgeSessionError):
+    """Raised when an override key is invalid.
+
+    Keys can be invalid due to:
+    - Empty key or empty segment in path (e.g., "foo..bar")
+    - Targeting confirmed.* fields
+    - Targeting top-level manifest fields (name, schema_version, etc.)
+    - Using intent.* prefix (keys should be relative to intent)
+    - Unknown field not in SessionIntent schema
+    """
+
+    def __init__(self, key: str, reason: str, hint: str | None = None) -> None:
+        self.key = key
+        self.reason = reason
+        self.hint = hint  # e.g., "valid keys: agent, proxy.*, policy.*, ..."
+        msg = f"invalid override key '{key}': {reason}"
+        if hint:
+            msg = f"{msg} ({hint})"
+        super().__init__(msg)
+
+
+class InvalidOverrideValueError(ForgeSessionError):
+    """Raised when an override value has an incompatible type.
+
+    This occurs when the effective config (intent + overrides) cannot be
+    converted to a valid SessionIntent due to type mismatches.
+    """
+
+    def __init__(self, key: str, expected: str, actual: str) -> None:
+        self.key = key
+        self.expected = expected  # e.g., "str", "list[str]", "enum"
+        self.actual = actual  # e.g., "bool", "True"
+        super().__init__(f"invalid value for '{key}': expected {expected}, got {actual}")
+
+
+# --- Resume Exceptions ---
+
+
+class AmbiguousSessionError(ForgeSessionError):
+    """Raised when a session name matches multiple projects.
+
+    User-facing commands use strict resolution which raises this when
+    forge_root is None and duplicate names exist across projects.
+    """
+
+    def __init__(self, name: str, forge_roots: list[str]) -> None:
+        self.name = name
+        self.forge_roots = forge_roots
+        roots_str = ", ".join(forge_roots)
+        super().__init__(
+            f"session '{name}' exists in multiple projects: {roots_str}. "
+            f"Run from within the target project directory to disambiguate."
+        )
+
+
+class ContextBudgetExceededError(ForgeSessionError):
+    """Raised when parent context exceeds proxy context limit.
+
+    This is a fail-fast check for the 'full' resume strategy. When the parent
+    transcript is too large to fit in the target proxy's context window, we
+    fail before launching Claude rather than wasting tokens.
+    """
+
+    def __init__(self, token_estimate: int, context_limit: int) -> None:
+        self.token_estimate = token_estimate
+        self.context_limit = context_limit
+        super().__init__(
+            f"Parent transcript ({token_estimate:,} tokens) exceeds context limit "
+            f"({context_limit:,}). Use --strategy structured or --strategy minimal."
+        )