igni-core 1.0.4__py3-none-any.whl

igni_core/__init__.py

@@ -0,0 +1,37 @@
+"""igni — Terminal-based AI coding assistant built on Agno."""
+
+# Must run before anything that pulls in ``transformers`` /
+# ``sentence-transformers``. See the shim's docstring for why.
+from igni_core import _torchvision_shim as _torchvision_shim  # noqa: F401
+from igni_core.core.agno_telemetry import AgnoTelemetry
+
+# ── No run leaves the machine unless somebody asks for it ──────────
+#
+# Agno posts a telemetry event to ``https://os-api.agno.com`` on every
+# agent run, and its default is on. Found by reading a ``--debug`` log
+# during a smoke test: ``POST https://os-api.agno.com/telemetry/runs
+# "HTTP/2 201 Created"``, once per run, on an ordinary session.
+#
+# What it sends is metadata, not content: agent/session/run ids, the
+# provider, model name and model id, the database class name, and a set
+# of capability booleans. **No prompt, no code, no paths.** That
+# distinction matters and is why this is not a breach of "your code
+# never leaves your network" — but it is still an unannounced outbound
+# call from a product sold as self-hosted, it names the customer's
+# model and storage choices, and it is a third party that appears in
+# none of the compliance documents that enumerate where data goes.
+#
+# Set here, before anything imports Agno, because
+# ``agno.agent._init.set_telemetry`` re-reads this variable on every
+# run and overrides whatever the constructor said, so one assignment
+# covers every process that imports igni. Every ``Agent`` / ``Team``
+# igni builds also passes ``telemetry=False``, for a process whose
+# environment lost the variable.
+#
+# An explicit ``AGNO_TELEMETRY=true`` is honoured, except under
+# air-gapped mode, where it is forced off with a warning — here for
+# ``IGNI_AIR_GAPPED=1``, and once settings are loaded for
+# ``air_gapped: true``. ``core/agno_telemetry.py`` has the whole rule.
+AgnoTelemetry.apply_process_default()
+
+__version__ = "1.0.4"

igni_core/__main__.py

@@ -0,0 +1,19 @@
+"""Entry point for `igni`, `ignite-ember` and `python -m igni_core`."""
+
+from igni_core.cli import cli
+from igni_core.core.dir_migration import migrate_home
+
+
+def main():
+    # Before anything reads the home directory. The rename is
+    # idempotent and costs two stat calls once it has happened, and
+    # ``paths.home_config_dir`` falls back to the legacy name anyway —
+    # so a path that somehow skips this still works. Doing it here means
+    # it happens once, early, rather than being something every reader
+    # has to remember.
+    migrate_home()
+    cli()
+
+
+if __name__ == "__main__":
+    main()

igni_core/_torchvision_shim.py

@@ -0,0 +1,67 @@
+"""Disarm a transitive-dep crash that breaks every ``transformers`` import.
+
+``torchvision`` registers fake implementations for ops like
+``torchvision::nms`` at module load time:
+
+    @torch.library.register_fake("torchvision::nms")
+
+On torch / torchvision wheel pairs whose native bindings don't match
+(seen on macOS arm64 + Python 3.12 with torch 2.11.0 + torchvision
+0.26.0 / 0.27.0), that registration raises
+``RuntimeError: operator torchvision::nms does not exist``.
+``transformers`` then catches the failure inside its lazy
+``__getattr__`` and re-raises it as a misleading
+``ModuleNotFoundError: Could not import module 'PreTrainedModel'``,
+which kills every ``transformers`` user along with it — Laya, the
+decision model igni runs, among them.
+
+We don't use torchvision — igni's models read text only. The fix is to
+make sure ``transformers`` never reaches torchvision's auto-discovery
+in the first place. Eagerly probe the import; if it explodes, mark
+the module unimportable in ``sys.modules`` so future ``import
+torchvision`` raises a clean ``ImportError``. ``transformers``'s
+``is_torchvision_available()`` treats that as "not installed" and
+takes the text-only path.
+
+This module is import-side-effect-only — import it once, at the top
+of ``igni_core/__init__.py``, before anything that pulls in
+``transformers`` / ``sentence-transformers``.
+"""
+
+import importlib.util
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def _disarm_torchvision_if_broken() -> None:
+    if "torchvision" in sys.modules:
+        # Already imported — either successfully (nothing to do) or by
+        # something that handled the failure itself.
+        return
+    try:
+        spec = importlib.util.find_spec("torchvision")
+    except Exception:
+        # ``find_spec`` itself can raise on partial installs. Treat as
+        # missing — transformers will skip torchvision regardless.
+        return
+    if spec is None:
+        return
+    try:
+        import torchvision  # noqa: F401 — eager probe; failure is the signal
+    except Exception as exc:
+        logger.info(
+            "torchvision import failed (%s); marking it unimportable so "
+            "transformers takes the text-only path",
+            exc,
+        )
+        # ``None`` in sys.modules makes future ``import torchvision``
+        # raise ``ImportError: import of torchvision halted; None in
+        # sys.modules`` — which ``importlib.util.find_spec`` and
+        # transformers' availability check both translate to "not
+        # available".
+        sys.modules["torchvision"] = None  # type: ignore[assignment]
+
+
+_disarm_torchvision_if_broken()

igni_core/alembic.ini

@@ -0,0 +1,52 @@
+[alembic]
+; ``alembic.ini`` and ``migrations/`` live INSIDE the ``igni_core``
+; package so the wheel ships them — non-source-tree installs (Homebrew,
+; pipx, system pip) need to find them too. ``%(here)s`` expands to the
+; directory containing this file (``src/igni_core/`` in dev,
+; ``<site-packages>/igni_core/`` in a wheel install) — using it
+; avoids any dependency on CWD, since alembic resolves bare relative
+; paths against CWD rather than the ini location.
+script_location = %(here)s/migrations
+; Add the package's parent to sys.path so ``igni_core`` is importable
+; when ``alembic`` is invoked outside an editable install (autogenerate
+; from a non-installed checkout, etc.). In a wheel layout this is
+; ``site-packages/`` — already on sys.path, harmless.
+prepend_sys_path = %(here)s/..
+path_separator = os
+; URL is overridden programmatically per-call (Database.__init__) — this
+; placeholder only exists to satisfy ``alembic revision --autogenerate``.
+sqlalchemy.url = sqlite:///%(here)s/.alembic-autogenerate-tmp.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

igni_core/backend/__init__.py

@@ -0,0 +1,5 @@
+"""Backend server — owns Session and all AI logic.
+
+The TUI (or any future frontend) communicates with the backend
+exclusively through protocol messages. No Agno types cross this boundary.
+"""

igni_core/backend/__main__.py

@@ -0,0 +1,134 @@
+"""Backend process entry point.
+
+Usage: python -m igni_core.backend --socket <path>
+
+Starts a :class:`BackendApp`, listens on the given Unix socket
+and/or WebSocket port, and processes FE messages until shutdown.
+The real work lives in :mod:`igni_core.backend.app` — this module
+is the CLI + the module-load side effects (logging config).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import click
+
+from igni_core.backend.app import BackendApp
+from igni_core.backend.logging_setup import configure_logging
+from igni_core.backend.schemas_lifecycle import BackendLaunch
+from igni_core.core.data_paths import canonical_project_dir
+from igni_core.core.layer import layers
+from igni_core.transport.ws_auth import take_window_token
+
+logger = logging.getLogger(__name__)
+
+#: The interpreter this ships on. Kept in step with ``requires-python``
+#: in pyproject.toml and ``PYTHON_VERSION`` in the Tauri runtime, which
+#: is what actually installs it for a user.
+SUPPORTED_PYTHON = (3, 12)
+
+
+def warn_if_unsupported_python(emit: Callable[..., None] = logger.warning) -> bool:
+    """Say so, loudly, when the backend is running off-version.
+
+    The reason this is worth a check rather than a note in a README: the
+    failure is silent. On 3.14 a Neo4j sidecar the backend used to run
+    exited without writing stderr, without a log, and without raising —
+    the feature behind it simply never came up, and the panel said
+    "disabled" as though someone had configured it that way. Two hours
+    went into that before the interpreter turned out to be the variable.
+
+    A warning rather than a refusal. Contributors run the test suite on
+    whatever they have, and most of the codebase is fine there; the part
+    that is not now announces itself.
+
+    Returns True when the version is the supported one.
+    """
+    actual = sys.version_info[:2]
+    if actual == SUPPORTED_PYTHON:
+        return True
+    emit(
+        "running on Python %d.%d; this backend is supported on %d.%d only. "
+        "Some subsystems fail silently off-version.",
+        *actual,
+        *SUPPORTED_PYTHON,
+    )
+    return False
+
+
+@click.command()
+@click.option("--socket", "socket_path", default=None, help="Unix socket path")
+@click.option(
+    "--ws-port",
+    "ws_port",
+    type=int,
+    default=None,
+    help="Listen on a loopback WebSocket port instead of a Unix socket "
+    "(0 = auto-assign; the bound port is printed in the ready line). "
+    "Used by GUI clients (the Tauri desktop app, the web client).",
+)
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--resume-session", "resume_session_id", default=None)
+@click.option("--additional-dirs", multiple=True, default=())
+@click.option("--debug", is_flag=True, default=False)
+def main(
+    socket_path: str | None,
+    ws_port: int | None,
+    project_dir: str,
+    resume_session_id: str | None,
+    additional_dirs: tuple[str, ...],
+    debug: bool,
+) -> None:
+    """Start the igni backend server."""
+    if socket_path is None and ws_port is None:
+        raise click.UsageError("at least one of --socket or --ws-port is required")
+    # Always. ``--debug`` is unreachable for the backend the desktop
+    # app spawns (the app builds the argv), and the env var that
+    # replaced it still had to be set by someone who already suspected
+    # a problem and knew its name — which is nobody, before the fact.
+    # ``--debug`` / ``IGNI_DEBUG_LOG`` now choose the level.
+    log_path = configure_logging(debug_flag=debug)
+    if log_path is not None:
+        logger.info("backend log: %s", log_path)
+
+    warn_if_unsupported_python()
+
+    # Taken out of the environment at once, before anything is spawned
+    # that would inherit it (shell tools, hooks, MCP servers).
+    # A backend started by hand has no launcher to give it one, so on a
+    # desktop it mints its own and says so once (the cloud's gateway
+    # authenticates every client; there the backend takes no token).
+    ws_token, minted = take_window_token(
+        mint=ws_port is not None and layers.current().name == "desktop"
+    )
+    if minted:
+        click.echo(
+            f"igni window token for this backend (shown once, never written to disk): {ws_token} "
+            "-- a program connects as the window with igni-client's Local(url=..., token=...).",
+            err=True,
+        )
+
+    extra_dirs = [Path(d) for d in additional_dirs] if additional_dirs else None
+    # One spelling of the project dir, shared with ``igni migrate`` and
+    # every store, so all of them open the same ``state.db``.
+    resolved_project = canonical_project_dir(project_dir)
+    app = BackendApp(
+        BackendLaunch(
+            socket_path=socket_path,
+            ws_port=ws_port,
+            project_dir=resolved_project,
+            resume_session_id=resume_session_id,
+            additional_dirs=extra_dirs,
+            ws_token=ws_token,
+        )
+    )
+    asyncio.run(app.run())
+
+
+if __name__ == "__main__":
+    main()

igni_core/backend/activity.py

@@ -0,0 +1,112 @@
+"""Whether a backend is doing anything — what decides if its VM may sleep.
+
+``docs/CLOUD.md``. A producer's VM is suspended when nothing runs in it.
+A run that waits only on a person — the main agent paused on an
+approval, or a ``spawn_agent`` call whose sub-agent is paused on one —
+does nothing until the person decides: it counts as **waiting**, not
+running, and the VM may be suspended. The snapshot keeps the waiting run
+frozen exactly where it is; the decision, delivered to the woken VM,
+simply continues it. (Should the VM be lost instead, the approval and
+what hangs from it are in the database: ``ColdSpawnResume``.)
+
+:class:`Activity` is that state for the whole backend, as the host
+object model's ``app.activity`` reports it to the node agent.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from igni_core.core.activity import ActivityRegistry, BusyLease
+
+
+class ActivityState(StrEnum):
+    #: Nothing running and nothing waiting.
+    IDLE = "idle"
+    #: Nothing running; one or more approvals wait on a person.
+    WAITING = "waiting"
+    #: A run is working: a model call, a tool, a sub-agent that is not paused.
+    RUNNING = "running"
+
+
+class SessionActivity(BaseModel):
+    session_id: str
+    state: ActivityState
+    waiting_approvals: int = 0
+
+    @classmethod
+    def of(
+        cls,
+        session_id: str,
+        *,
+        run_in_progress: bool,
+        waiting_approvals: int,
+        blocked_spawns: int,
+        active_subagent_runs: int,
+    ) -> SessionActivity:
+        """The session's state from what its backend can see.
+
+        A run in progress is only waiting when every sub-agent run it
+        has going is blocked on a person (and at least one is): the
+        main agent is then inside ``spawn_agent`` calls that do nothing
+        until a decision.
+        """
+        if run_in_progress:
+            only_waiting = blocked_spawns > 0 and blocked_spawns >= active_subagent_runs
+            state = ActivityState.WAITING if only_waiting else ActivityState.RUNNING
+        elif waiting_approvals:
+            state = ActivityState.WAITING
+        else:
+            state = ActivityState.IDLE
+        return cls(session_id=session_id, state=state, waiting_approvals=waiting_approvals)
+
+
+class Activity(BaseModel):
+    """The backend as a whole: running if any session runs or anything holds a busy lease."""
+
+    state: ActivityState
+    #: Whether the VM may be suspended now: nothing is running and nothing is busy.
+    suspendable: bool
+    waiting_approvals: int = 0
+    sessions: list[SessionActivity] = Field(default_factory=list)
+    #: What is working outside a run's own turn (``core/activity``): calls
+    #: out, scheduled tasks, processes, extensions that said they are busy.
+    busy: list[BusyLease] = Field(default_factory=list)
+    #: The earliest time something is due while nothing runs: when to wake.
+    wake_at: datetime | None = None
+
+    @classmethod
+    def of(
+        cls,
+        sessions: list[SessionActivity],
+        *,
+        busy: list[BusyLease] | None = None,
+        wake_at: datetime | None = None,
+    ) -> Activity:
+        busy = busy or []
+        states = {s.state for s in sessions}
+        if ActivityState.RUNNING in states or busy:
+            state = ActivityState.RUNNING
+        elif ActivityState.WAITING in states:
+            state = ActivityState.WAITING
+        else:
+            state = ActivityState.IDLE
+        return cls(
+            state=state,
+            suspendable=state is not ActivityState.RUNNING,
+            waiting_approvals=sum(s.waiting_approvals for s in sessions),
+            sessions=sessions,
+            busy=busy,
+            wake_at=wake_at,
+        )
+
+    @classmethod
+    def now(cls, sessions: list[SessionActivity], registry: ActivityRegistry) -> Activity:
+        """``sessions``, with what ``registry`` says is busy and due."""
+        return cls.of(sessions, busy=registry.busy(), wake_at=registry.wake_at())
+
+
+__all__ = ["Activity", "ActivityState", "SessionActivity"]

igni_core/backend/activity_nudge.py

@@ -0,0 +1,43 @@
+"""The host model told to look at the activity again when the busy registry moves."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+
+from igni_core.extensions.host.model import HostModel
+
+
+class ActivityNudge:
+    """Tells the host model to look at the activity again when the registry moves.
+
+    A lease can be taken or let go on any thread; the model is the
+    loop's. Several moves before the loop gets round to it are one look.
+    """
+
+    def __init__(self, model: HostModel, loop: asyncio.AbstractEventLoop) -> None:
+        self._model = model
+        self._loop = loop
+        self._pending = False
+        self._lock = threading.Lock()
+
+    def __call__(self) -> None:
+        with self._lock:
+            if self._pending:
+                return
+            self._pending = True
+        try:
+            self._loop.call_soon_threadsafe(self._look)
+        except RuntimeError:
+            # The loop is closed: no look was scheduled, so none is
+            # pending — a later move must not be swallowed by this one.
+            with self._lock:
+                self._pending = False
+
+    def _look(self) -> None:
+        with self._lock:
+            self._pending = False
+        self._model.services.activity_watch.moved()
+
+
+__all__ = ["ActivityNudge"]

igni_core/backend/agent_framing.py

@@ -0,0 +1,82 @@
+"""What the agent is told around a message it did not get from the person's keyboard.
+
+Two framings, both ``<system-context>`` blocks the windows strip from
+display, so the chat bubble shows only the text itself:
+
+* :class:`ExtensionMessage` — a message an extension posted.
+* :class:`PlanResearchHint` — the one-shot nudge after ``/plan``.
+"""
+
+from __future__ import annotations
+
+import re
+from html import escape
+
+
+class ExtensionMessage:
+    """How a message an extension posts reads to the agent.
+
+    The agent must never take it for the person's: it says who sent it,
+    in a block the windows strip from display (``<system-context>``),
+    around the text wrapped in a tag the windows read back on reload to
+    label the bubble.
+    """
+
+    TAG = "extension-message"
+
+    #: The ``<`` that opens one of igni's own wrapper tags — the ones the
+    #: agent reads as igni speaking and the windows strip from display.
+    #: Inside an extension's text such a tag
+    #: is a forgery: it would close the message early, or hand the agent a
+    #: ``<system-context>`` the person never sees.
+    _WRAPPER_TAG = re.compile(
+        r"<(?=\s*/?\s*(?:system-context|attached-files|extension-message|loop-iteration)\b)",
+        re.IGNORECASE,
+    )
+
+    @classmethod
+    def wrap(cls, extension_id: str, text: str) -> str:
+        # A manifest id never holds a quote or a bracket, so for a real id
+        # this changes nothing; an id that does could otherwise close the
+        # attribute or the block and write the agent a context of its own.
+        sender = escape(extension_id, quote=True)
+        # Only a wrapper tag's opening ``<`` changes; every other byte of the
+        # text — markdown, code, a ``<div>`` — reaches the agent as posted,
+        # so the framing stays the one the model was trained on.
+        text = cls._WRAPPER_TAG.sub("&lt;", text)
+        return (
+            "<system-context>\n"
+            f"The message below was posted by the igni extension '{sender}', "
+            "not typed by the person. Answer it in the chat as you would answer them.\n"
+            "</system-context>\n"
+            f'<{cls.TAG} from="{sender}">\n{text}\n</{cls.TAG}>'
+        )
+
+
+class PlanResearchHint:
+    """One-shot ``/plan`` → ``enter_plan_mode`` nudge.
+
+    When the person just typed ``/plan`` (the slash command armed
+    :meth:`PlanCoordinator.arm_research`), the next request is
+    prefixed with an instruction to spawn the ``plan_researcher``
+    sub-agent on that exact request. The caller consumes the armed
+    flag, so later turns in the same plan-mode session do not get it.
+    """
+
+    TEXT = (
+        "<system-context>\n"
+        "Plan mode was just entered via the user's /plan slash "
+        "command. BEFORE doing any other work, call "
+        "`enter_plan_mode(task=...)` with the user's request "
+        "below as the ``task`` argument so the plan_researcher "
+        "sub-agent runs first and produces a structured "
+        "Findings + Proposed Plan + Open Questions report. "
+        "Do not skip this step — the researcher's report is "
+        "what makes the eventual ``exit_plan_mode`` call "
+        "grounded enough to pass the confidence validator.\n"
+        "</system-context>\n\n"
+    )
+
+    @classmethod
+    def wrap(cls, text: str) -> str:
+        return cls.TEXT + text

igni_core/backend/agent_refresh.py

@@ -0,0 +1,49 @@
+"""Rebuilding the agents when what extensions do to them changes.
+
+An extension becoming ready, one going down, a condition it reports
+moving ("my index covers this commit now") — each changes what the
+agent's prompt says or which agent definition stands under a name.
+:class:`~igni_core.core.prompts.contributions.PromptContributions`
+says so whenever it happens, sometimes several times in a row as one
+extension's claims land, and this turns that into one rebuild of every
+session's agents, on the next turn of the event loop.
+
+A run already under way finishes with the agent it started with; the
+next one gets the new prompt.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class AgentRefresh:
+    """Coalesces requests to rebuild the agents into one rebuild."""
+
+    def __init__(self, *, loop: asyncio.AbstractEventLoop, refresh: Callable[[], None]) -> None:
+        self._loop = loop
+        self._refresh = refresh
+        self._scheduled = False
+
+    def request(self) -> None:
+        """Rebuild soon. Safe from any thread, and cheap to call often."""
+        if self._scheduled or self._loop.is_closed():
+            return
+        self._scheduled = True
+        try:
+            self._loop.call_soon_threadsafe(self._run)
+        except RuntimeError:
+            # The loop closed between the check and the call: nothing was
+            # scheduled, so a later request must still be able to schedule.
+            self._scheduled = False
+
+    def _run(self) -> None:
+        self._scheduled = False
+        try:
+            self._refresh()
+        except Exception:  # noqa: BLE001 — a failed rebuild keeps the agents that work
+            logger.exception("rebuilding the agents after an extension change failed")

igni_core/backend/agno_decision_applier.py

@@ -0,0 +1,69 @@
+"""Apply a person's HITL decision to an Agno requirement.
+
+:class:`AgnoDecisionApplier` owns the ``req.confirm()`` /
+``req.reject()`` dispatch behind :class:`HitlAction` (Pattern 7 — the
+wire keeps the string literal; the domain uses the enum). It never
+builds ``msg.*`` frames: it returns an :class:`ApplyDecisionResult`
+and the caller (:meth:`HitlController.resolve_batch`) turns a failure
+into the wire ``msg.Error``.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from igni_core.backend.schemas_hitl import (
+    ApplyDecisionResult,
+    HitlAction,
+    RequirementTool,
+    RunRequirement,
+)
+from igni_core.core.approvals.declined import declined_note
+from igni_core.protocol import messages as msg
+
+logger = logging.getLogger(__name__)
+
+
+class AgnoDecisionApplier:
+    """Applies an :class:`msg.HITLDecision` to an Agno
+    :class:`RunRequirement` via ``confirm()`` / ``reject()``.
+
+    Stateless; one module-level instance in :mod:`hitl_controller`
+    is shared by every controller.
+    """
+
+    def apply(self, decision: msg.HITLDecision, req: RunRequirement) -> ApplyDecisionResult:
+        """Call ``req.confirm()`` or ``req.reject(...)``.
+
+        Returns :class:`ApplyDecisionResult` — ``ok=False`` when the
+        action is unknown or the Agno call raised.
+        """
+        try:
+            action = HitlAction(decision.action)
+        except ValueError:
+            reason = (
+                f"Unknown HITL action '{decision.action}' for requirement {decision.requirement_id}"
+            )
+            logger.warning("resolve_hitl_batch: %s", reason)
+            return ApplyDecisionResult(ok=False, reason=reason)
+
+        try:
+            if action is HitlAction.CONFIRM:
+                req.confirm()
+            else:
+                req.reject(note=declined_note(RequirementTool.of(req).name))
+        except Exception as exc:
+            logger.warning(
+                "resolve_hitl_batch: requirement %s %s() raised %s; skipping",
+                decision.requirement_id,
+                action.value,
+                exc,
+            )
+            return ApplyDecisionResult(
+                ok=False,
+                reason=f"Failed to {action.value} requirement {decision.requirement_id}: {exc}",
+            )
+        return ApplyDecisionResult(ok=True)
+
+
+__all__ = ["AgnoDecisionApplier"]