grinta 1.0.0__py3-none-any.whl

backend/README.md

@@ -0,0 +1,83 @@
+# Backend
+
+This folder contains all backend-related code and resources for the Grinta project.
+
+## Structure
+
+```text
+backend/
+├── cli/             # Terminal UI, REPL, and CLI entry
+├── context/         # Context memory and compaction
+├── core/            # Shared config, schemas, logging, and bootstrap
+├── engine/          # LLM-facing agent engine and tools
+├── evaluation/      # Agent eval pack and related helpers
+├── execution/       # Local runtime execution and policy enforcement
+├── inference/       # Model/provider abstraction layer
+├── integrations/    # External adapters (e.g. MCP plumbing)
+├── knowledge/       # Knowledge base logic
+├── ledger/          # Record stream, event types, serialization
+├── orchestration/   # Session orchestration loop and services
+├── persistence/     # Local file-backed persistence
+├── playbooks/       # Built-in playbook content and engine
+├── scripts/         # Backend utility scripts
+├── security/        # Security analysis and policy checks
+├── telemetry/       # Lightweight instrumentation
+├── tools/           # Repo maintenance utilities (e.g. trajectory sanitization)
+├── utils/           # Shared utilities (LSP client, imports, etc.)
+├── validation/    # Validation and completion guards
+├── tests/         # Test suite
+└── conftest.py    # Pytest configuration
+```
+
+## Package Structure
+
+Most application code lives under `backend/`. The supported interactive surface is the terminal CLI in `backend/cli/`, launched through `launch.entry` or `python -m backend.cli.entry`.
+
+## Running Tests
+
+From the project root, `uv run pytest` (no path) discovers all of `backend/tests` per the repo [`pytest.ini`](../pytest.ini). To match the required PR gates (unit only):
+
+```bash
+uv run pytest backend/tests/unit
+```
+
+To run the full tree explicitly:
+
+```bash
+uv run pytest backend/tests
+```
+
+Or use the Makefile:
+
+```bash
+make test-unit
+```
+
+## Scripts
+
+`backend/scripts/` currently holds **verification** utilities used in CI and local gates (`verify/`). One-off automation, smoke installs, and eval helpers live under the repository root [`scripts/`](../scripts/) instead — see [`scripts/README.md`](../scripts/README.md) for the full index.
+
+From the project root:
+
+```bash
+python backend/scripts/verify/check_layer_imports.py
+python backend/scripts/verify/reliability_gate.py --phase full
+```
+
+See [`backend/scripts/README.md`](scripts/README.md) for the full list.
+
+## Development
+
+Backend code imports from `backend.*`. The supported entrypoints are the CLI under `backend/cli/` and the portable launcher in `launch/`.
+
+### CLI Mixin Typing Convention
+
+When extracting logic into CLI mixins (for example in `backend/cli/repl/` or
+`backend/cli/event_rendering/`), define host interfaces in
+`backend/cli/_typing.py` and import them into mixins instead of re-declaring
+`TYPE_CHECKING`-only host stubs per file.
+
+- Keep shared host contracts in `backend/cli/_typing.py` as `Protocol` classes.
+- In mixins, cast `self` to the relevant host protocol where needed.
+- Prefer this shared protocol approach over file-local structural stubs so
+  typing and lint behavior stays consistent across extracted modules.

backend/README_GRINTA.md

@@ -0,0 +1,9 @@
+# backend/ — see docs instead
+
+This file is **legacy**. For current architecture and module layout, read:
+
+- [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md)
+- [docs/CLI_MODULE_MAP.md](../docs/CLI_MODULE_MAP.md)
+- [docs/CONTRIBUTOR_MAP.md](../docs/CONTRIBUTOR_MAP.md)
+
+The runtime is organized into `cli/`, `orchestration/`, `execution/`, `inference/`, and `ledger/` packages — not the class-centric overview that used to live here.

backend/__init__.py

@@ -0,0 +1,103 @@
+"""Grinta package."""
+
+import warnings
+
+# Suppress only known, specific third-party DeprecationWarnings.
+# Do NOT use a blanket `category=DeprecationWarning` filter — that silences
+# warnings from Grinta's own code and newly added dependencies too.
+#
+# Pattern: warnings.filterwarnings('ignore', message=<regex>, category=DeprecationWarning, module=<regex>)
+# Add a new entry for each third-party library that produces noise, scoped as
+# narrowly as possible (prefer `module=` + `message=` over category-only).
+
+# asttokens / astroid: fires from frozen importlib frames; cannot be caught by
+# module-based filters alone because the source frame is internal to importlib.
+warnings.filterwarnings(
+    'ignore',
+    message=r'.*asttokens.*',
+    category=DeprecationWarning,
+)
+warnings.filterwarnings(
+    'ignore',
+    message=r'.*astroid.*',
+    category=DeprecationWarning,
+)
+
+# google-genai (Gemini SDK) subclasses aiohttp.ClientSession — noisy on import.
+warnings.filterwarnings(
+    'ignore',
+    message=r'Inheritance class AiohttpClientSession from ClientSession is discouraged',
+    category=DeprecationWarning,
+)
+
+# anthropic SDK: uses deprecated pkg_resources internals in some versions.
+warnings.filterwarnings(
+    'ignore',
+    message=r'.*pkg_resources.*',
+    category=DeprecationWarning,
+    module=r'anthropic.*',
+)
+
+# tree-sitter <0.25 exposes a deprecated Language constructor form.
+warnings.filterwarnings(
+    'ignore',
+    message=r'.*Language\(\) with a shared library.*',
+    category=DeprecationWarning,
+    module=r'tree_sitter.*',
+)
+
+from importlib.metadata import PackageNotFoundError, version  # noqa: E402
+from pathlib import Path  # noqa: E402
+
+_DEFAULT_VERSION = '1.0.0'
+__version__ = _DEFAULT_VERSION
+__package_name__ = 'grinta'
+
+
+def get_version() -> str:
+    """Get the package version, preferring the local source tree when present."""
+    from_pyproject = _version_from_pyproject()
+    if from_pyproject:
+        return from_pyproject
+    from_metadata = _version_from_metadata()
+    if from_metadata:
+        return from_metadata
+    return _DEFAULT_VERSION
+
+
+def _version_from_metadata() -> str | None:
+    """Try to get version from installed package metadata."""
+    try:
+        return version(__package_name__)
+    except PackageNotFoundError:
+        return None
+
+
+def _version_from_pyproject() -> str | None:
+    """Try to get version from pyproject.toml (local dev)."""
+    try:
+        root_dir = Path(__file__).resolve().parent.parent
+        pyproject_path = root_dir / 'pyproject.toml'
+        if not pyproject_path.exists():
+            return None
+        with pyproject_path.open('r', encoding='utf-8') as f:
+            for line in f:
+                if line.strip().startswith('version ='):
+                    return line.split('=', 1)[1].strip().strip('"').strip("'")
+    except Exception:
+        pass
+    return None
+
+
+try:
+    __version__ = get_version()
+except Exception as _exc:
+    warnings.warn(
+        f'Grinta: could not determine package version ({_exc!r}); reporting '
+        f'{_DEFAULT_VERSION!r}.',
+        stacklevel=1,
+    )
+    __version__ = _DEFAULT_VERSION
+
+
+__all__ = ['__version__', '__package_name__', 'get_version']

backend/_canonical.py

@@ -0,0 +1,67 @@
+"""Shared registry for canonical classes across reloads."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic._internal._model_construction import ModelMetaclass
+
+
+def _canonical_model_instancecheck(cls: type[Any], instance: Any) -> bool:
+    if type.__instancecheck__(cls, instance):
+        return True
+    # Check if the class names match. This allows isinstance(reloaded_obj, original_class) to be True.
+    return type(instance).__name__ == cls.__name__
+
+
+def _canonical_model_subclasscheck(cls: type[Any], subclass: type[Any]) -> bool:
+    if type.__subclasscheck__(cls, subclass):
+        return True
+    # Check if the class names match. This allows issubclass(reloaded_class, original_class) to be True.
+    return getattr(subclass, '__name__', None) == cls.__name__
+
+
+class CanonicalModelMetaclass(ModelMetaclass):
+    """Metaclass that ensures Pydantic models behave consistently across reloads.
+
+    Instead of trying to return the same class object (which causes issues with super()),
+    this metaclass overrides ``isinstance`` / ``issubclass`` behavior across reloads.
+    """
+
+    __instancecheck__ = _canonical_model_instancecheck  # type: ignore[assignment]
+    __subclasscheck__ = _canonical_model_subclasscheck  # type: ignore[assignment]
+
+
+class CanonicalMeta(type):
+    """Metaclass that ensures non-Pydantic classes behave consistently across reloads.
+
+    Supports isinstance() and issubclass() checks across reloaded versions of the
+    same class by comparing class names.
+    """
+
+    def __instancecheck__(cls, instance: object) -> bool:
+        if super().__instancecheck__(instance):
+            return True
+        # Check if the class names match.
+        inst_type = type(instance)
+        if getattr(inst_type, '__name__', None) != getattr(cls, '__name__', None):
+            # Special case for base classes to allow subclasses from other reloads
+            if cls.__name__ in ('Action', 'Observation', 'Event'):
+                return any(b.__name__ == cls.__name__ for b in inst_type.__mro__)
+            return False
+
+        # If it's an Action/Observation, we can also check the type attribute
+        cls_type = getattr(cls, 'action', getattr(cls, 'observation', None))
+        inst_type_attr = getattr(
+            instance, 'action', getattr(instance, 'observation', None)
+        )
+        if cls_type and inst_type_attr:
+            return cls_type == inst_type_attr
+
+        return True
+
+    def __subclasscheck__(cls, subclass: type) -> bool:
+        if super().__subclasscheck__(subclass):
+            return True
+        # Check if the class names match.
+        return getattr(subclass, '__name__', None) == cls.__name__

backend/app/__init__.py

@@ -0,0 +1,36 @@
+"""Bootstrap modules that wire together cross-layer components.
+
+These modules are intentionally allowed to import from higher layers
+(controller, engines, memory, runtime) because they serve as the
+application composition root. They are the only modules in ``core``
+that cross layer boundaries.
+
+Modules:
+    agent_control_loop - Polling loop that drives the agent until a terminal state
+    main               - CLI / headless entry point, run_controller orchestration
+    setup              - Factory functions: create_agent, create_controller, create_memory, create_runtime
+"""
+
+from backend.app.agent_control_loop import run_agent_until_done
+from backend.app.setup import (
+    create_agent,
+    create_controller,
+    create_memory,
+    create_runtime,
+    filter_plugins_by_config,
+    generate_sid,
+    get_provider_tokens,
+    initialize_repository_for_runtime,
+)
+
+__all__ = [
+    'create_agent',
+    'create_controller',
+    'create_memory',
+    'create_runtime',
+    'filter_plugins_by_config',
+    'generate_sid',
+    'get_provider_tokens',
+    'initialize_repository_for_runtime',
+    'run_agent_until_done',
+]

backend/app/agent_control_loop.py

@@ -0,0 +1,223 @@
+"""Agent control loop helpers for running runtimes and handling status callbacks."""
+
+import asyncio
+from collections.abc import Callable
+
+from backend.context.memory.agent_memory import Memory
+from backend.core.enums import RuntimeStatus
+from backend.core.logging.logger import app_logger as logger
+from backend.core.schemas import AgentState
+from backend.core.timeouts.suspend_aware_deadline import SuspendAwareDeadline
+from backend.execution.server.base import Runtime
+from backend.orchestration import SessionOrchestrator
+from backend.utils.async_helpers.async_utils import run_or_schedule
+
+
+def _handle_error_status(
+    controller: SessionOrchestrator, runtime_status: RuntimeStatus, msg: str
+) -> None:
+    """Handle error status in the status callback."""
+    if controller:
+        controller.state.set_last_error(msg, source='loop.status_callback')
+        try:
+            if runtime_status == RuntimeStatus.ERROR_MEMORY:
+                setattr(
+                    controller.state,
+                    '_memory_error_boundary',
+                    controller.state.iteration_flag.current_value,
+                )
+                logger.info(
+                    'LOOP.status_callback: memory error boundary recorded at iteration %s',
+                    controller.state.iteration_flag.current_value,
+                )
+        except Exception:
+            logger.debug('Failed to record memory error boundary', exc_info=True)
+        # Late runtime callbacks may fire after the user stopped/finished the
+        # agent; do not promote those diagnostics to ERROR.  The agent's
+        # state stays STOPPED/FINISHED — a transition to ERROR would raise
+        # InvalidStateTransitionError and blur the WAL semantics.
+        if controller.get_agent_state() in (
+            AgentState.STOPPED,
+            AgentState.FINISHED,
+        ):
+            logger.info(
+                'Runtime error callback: skipping agent ERROR transition while state is %s',
+                controller.get_agent_state().value,
+            )
+        else:
+            try:
+                run_or_schedule(controller.set_agent_state_to(AgentState.ERROR))
+            except Exception:
+                logger.warning(
+                    'Failed to schedule ERROR state transition via run_or_schedule',
+                    exc_info=True,
+                )
+                try:
+                    from backend.utils.async_helpers.async_utils import (
+                        create_tracked_task,
+                    )
+
+                    create_tracked_task(
+                        controller.set_agent_state_to(AgentState.ERROR),
+                        name='error-state-fallback',
+                    )
+                except Exception:
+                    logger.error(
+                        'All attempts to transition agent to ERROR state failed',
+                        exc_info=True,
+                    )
+
+
+def _create_status_callback(
+    controller: SessionOrchestrator,
+) -> Callable[[str, RuntimeStatus, str], None]:
+    """Create the status callback function."""
+
+    def status_callback(msg_type: str, runtime_status: RuntimeStatus, msg: str) -> None:
+        """Handle runtime status updates.
+
+        Args:
+            msg_type: Message type (error, info, etc.)
+            runtime_status: Runtime status object
+            msg: Status message
+
+        """
+        if msg_type == 'error':
+            logger.error(msg)
+            _handle_error_status(controller, runtime_status, msg)
+        else:
+            logger.info(msg)
+
+    return status_callback
+
+
+def _validate_status_callbacks(
+    runtime: Runtime, controller: SessionOrchestrator
+) -> None:
+    """Validate that status callbacks are not already set."""
+    if getattr(runtime, 'status_callback', None):
+        logger.debug('Runtime status_callback already set; overriding in run loop')
+    if getattr(controller, 'status_callback', None):
+        logger.debug('Controller status_callback already set; overriding in run loop')
+
+
+def _set_status_callbacks(
+    runtime: Runtime,
+    controller: SessionOrchestrator,
+    memory: Memory,
+    status_callback: Callable[[str, RuntimeStatus, str], None],
+) -> None:
+    """Set status callbacks on runtime, controller, and memory."""
+    runtime.status_callback = status_callback
+    controller.status_callback = status_callback
+    memory.status_callback = status_callback
+
+
+def _apply_freeze_credit(
+    started: float, slept: float, poll_interval: float, grace: float
+) -> tuple[float, float]:
+    """Credit a detected freeze back to the run deadline (test/helper shim)."""
+    overrun = slept - poll_interval
+    if overrun > grace:
+        return started + overrun, overrun
+    return started, 0.0
+
+
+async def run_agent_until_done(
+    controller: SessionOrchestrator,
+    runtime: Runtime,
+    memory: Memory,
+    end_states: list[AgentState],
+) -> None:
+    """run_agent_until_done takes a controller and a runtime, and will run.
+
+    the agent until it reaches a terminal state.
+
+    Note that runtime must be connected before being passed in here.
+    """
+    _validate_status_callbacks(runtime, controller)
+
+    # Set session ID for working memory scoping — isolates working memory
+    # across concurrent/sequential sessions on the same workspace.
+    try:
+        from backend.context.memory.session_context import bind_session_context
+
+        session_id = getattr(controller, 'id', None)
+        bind_session_context(session_id=session_id)
+    except Exception:
+        logger.debug('Failed to bind session context', exc_info=True)
+
+    status_callback = _create_status_callback(controller)
+    _set_status_callbacks(runtime, controller, memory, status_callback)
+
+    # Skip the initial step if the controller is already in an end state or not
+    # in a stepping-compatible state (e.g. restored from a crashed session).
+    if controller.state.agent_state not in end_states:
+        try:
+            controller.step()
+        except Exception:
+            logger.warning('Initial controller.step() failed', exc_info=True)
+
+    # Wait for the agent to reach an end state.  Steps are driven by the
+    # event-driven mechanism (observation_service.trigger_step, _on_event ->
+    # should_step, etc.) rather than by polling.  The initial step() above kicks
+    # things off; all subsequent steps are triggered by events.
+    #
+    # A timeout guard prevents orphaned polling when the event-driven state
+    # machine stalls (e.g. due to a provider outage or infinite loop).
+    import time as _time
+
+    from backend.core.constants import (
+        DEFAULT_AGENT_RUN_FREEZE_GRACE_SECONDS,
+        DEFAULT_AGENT_RUN_HARD_TIMEOUT_SECONDS,
+    )
+
+    _POLL_INTERVAL = 0.5
+    _max_poll_seconds = DEFAULT_AGENT_RUN_HARD_TIMEOUT_SECONDS
+    _freeze_grace = DEFAULT_AGENT_RUN_FREEZE_GRACE_SECONDS
+    deadline = SuspendAwareDeadline(
+        _max_poll_seconds,
+        poll_interval=_POLL_INTERVAL,
+        freeze_grace_seconds=_freeze_grace,
+    )
+    _ran_loop = False
+    try:
+        while controller.state.agent_state not in end_states:  # noqa: ASYNC110
+            _ran_loop = True
+            _before_sleep = _time.monotonic()
+            await asyncio.sleep(_POLL_INTERVAL)
+            _slept = _time.monotonic() - _before_sleep
+            _credited = deadline.credit_poll_sleep(_slept)
+            if _credited > 0:
+                logger.warning(
+                    'run_agent_until_done: detected ~%.0fs freeze (poll sleep '
+                    'overran by %.0fs) — likely OS suspend or a blocked loop. '
+                    'Frozen time credited back to the run budget; not counted '
+                    'as an agent hang.',
+                    _slept,
+                    _credited,
+                    extra={
+                        'msg_type': 'AGENT_RUN_FREEZE_CREDIT',
+                        'frozen_seconds': round(_credited, 1),
+                    },
+                )
+            if deadline.expired():
+                logger.error(
+                    'run_agent_until_done: HARD TIMEOUT after %.0fs in state=%s',
+                    _max_poll_seconds,
+                    controller.state.agent_state,
+                    extra={'msg_type': 'AGENT_HARD_TIMEOUT'},
+                )
+                try:
+                    await controller.set_agent_state_to(AgentState.ERROR)
+                except Exception:
+                    pass
+                break
+    finally:
+        deadline.close()
+        if _ran_loop:
+            # Drain is intentionally omitted here — the TUI gates new messages on
+            # _agent_task.done(), and this cleanup delays completion. Background
+            # tasks are independently scheduled and don't need this coroutine to
+            # wait for them.  The TUI's run_tui finally block handles final drain.
+            pass